Zum Inhalt springen
Deutsch

HTTP-Endpunkte

Der Management-Server stellt einen kleinen Satz operativer Endpunkte bereit. Die meisten sind read-only; die Admin-Endpunkte (/cluster/down, /cluster/leave) sind Opt-in und standardmäßig aus.

Sicherheit (security audit #8): die read-only-Endpunkte legen dennoch interne Topologie offen — Member-Adressen (host:port), Rollen, die Anwendungsversion, die jedes Mitglied nennt, den Leader und die Shard-Map. Behandle den Management-Server als sensibel: binde ihn an ein internes Interface und schütze ihn mit den Optionen ipAllowlist (und/oder auth) von managementRoutes(...), statt ihn öffentlich zu exponieren.

Liveness — ist dieser Prozess fundamental gesund?

GET /health
→ 200 OK
{
"status": "UP",
"checks": [
{ "name": "actor-system", "status": true }
]
}

503 mit { "status": "DOWN", ... }, wenn ein Liveness-Check fehlschlägt. Siehe Health Checks.

Readiness — sollte dieser Pod Traffic bekommen?

GET /ready
→ 200 OK
{
"status": "UP",
"clusterReady": true,
"checks": [
{ "name": "cluster-membership", "status": true },
{ "name": "cluster-transport", "status": true },
{ "name": "database", "status": true }
]
}

Das checks-Array enthält jeden Readiness-Check auf der Registry des Systems — die eingebauten Checks des Frameworks (cluster-membership und cluster-transport, dazu startup und je benanntem Typ ein shard-region:<type>, wo konfiguriert) und alles, was du registriert hast. clusterReady ist das Ergebnis von cluster-membership selbst, aus diesem Array zurückgelesen statt separat berechnet: es ist also false, bis der lokale Node Up erreicht, und true, wenn es gar keinen Cluster gibt. 503, wenn ein Check fehlschlägt.

/health und /ready sind Defaults, keine festen Routen. Beide sind ein einzelnes Pfadsegment und im Code wie aus einer Config-Datei setzbar:

actor-ts.management {
liveness-path = "alive"
readiness-path = "serving"
}

Ein Wert mit / wird beim Bauen der Routen mit einem OptionsError abgelehnt, denn path() entfernt nur umschließende Slashes — aus "k8s/ready" würde ein Segment mit einem Slash darin, das auf keine URL passt und den Endpunkt lautlos verschwinden lässt. Wie die Segmente auch heißen: halte die Probe-Pfade in K8s im Gleichschritt damit, ein Manifest wird von nichts gegengeprüft.

Verfügbar, wenn ein cluster an managementRoutes übergeben wurde.

GET /cluster/members
→ 200 OK
{
"members": [
{
"address": "my-app@10.0.0.5:2552",
"status": "up",
"version": 1710000000001,
"roles": ["compute"],
"appVersion": "2.4.0"
},
...
],
"self": "my-app@10.0.0.5:2552"
}

Voller Membership-Snapshot. Adressen haben die Form system@host:port, die auch POST /cluster/down erwartet. version ist die logische Uhr des Mitglieds: Sie beginnt bei der Wanduhrzeit seines Joins in Millisekunden — so überholt ein unter derselben Adresse neu gestarteter Node den Tombstone, den sein vorheriger Lauf hinterlassen hat — und steigt mit jedem Statuswechsel um eins. Nützlich für:

  • Manuelle Cluster-Zustand-Checks während Incidents.
  • Externe Dashboards, die den Cluster visualisieren.
  • Tests, die das Cluster-Joining verifizieren.

appVersion ist die Anwendungsversion, die das Mitglied nennt — actor-ts.cluster.app-version oder withAppVersion(...) im Code —, und daran lässt sich ein Rolling Update ablesen: welcher Node welches Release fährt. Das Feld steht nur bei einem Mitglied, das eine Version nennt, und fehlt sonst, statt null zu sein — ein Mitglied, das ohne Version neu startet, steht ohne da, nicht mit der seines vorigen Laufs —; es ist ein Label und nicht mehr — nichts platziert, routet oder downt danach. Wie der Rest dieses Endpunkts wird es jedem ausgeliefert, der den Port erreicht, solange managementRoutes(...) kein auth bekommt (#971) — es fügt also dem, was ein nicht authentifizierter Aufrufer erfährt, das Release jedes Nodes hinzu.

GET /cluster/leader
→ 200 OK
{ "leader": "my-app@10.0.0.5:2552", "isSelf": true }

Die Adresse des Leaders plus isSelf (ist der lokale Node der Leader). leader ist null, bevor ein Leader gewählt wurde. Nützlich zum Monitoring von Leader-Wechseln.

GET /cluster/shards?type=cart
→ 200 OK
{
"typeName": "cart",
"leader": "my-app@10.0.0.5:2552",
"version": 7,
"takenAt": 1710000000000,
"regions": [
{
"key": "my-app@10.0.0.5:2552|/system/cluster/sharding/region-cart",
"address": "my-app@10.0.0.5:2552",
"path": "/system/cluster/sharding/region-cart",
"proxy": false,
"shards": [0, 1, 2, ..., 33]
},
...
],
"shardHome": [
{ "shard": 0, "regionKey": "my-app@10.0.0.5:2552|/system/cluster/sharding/region-cart" },
...
]
}

Zeigt die Shard-zu-Region-Allokation für einen sharded Typ. Nutze für:

  • Verifizieren gleichmäßiger Verteilung nach einem Rebalance.
  • Diagnostizieren heißer Regionen (eine Region mit zu vielen Shards).
  • Manuelle Rebalance-Trigger in der Entwicklung.

Woher die Antwort kommt. Der Node antwortet aus ClusterSharding.shardMap(typeName) — der letzten Karte, die der Coordinator an die Region dieses Nodes gesendet hat. Dafür ist keine Konfiguration nötig: keine DistributedData-Extension, kein coordinatorStateStore, kein Round-Trip zum Leader. Die einzige Voraussetzung ist, dass der antwortende Node an dem Typ teilnimmt — also sharding.start(...) oder sharding.startProxy(...) dafür aufgerufen hat —, denn der Coordinator sendet nur an Regionen, die sich registriert haben. Ein Node, der cart nie erwähnt hat, hat nichts zu berichten und antwortet mit 404.

Früher las dieser Endpunkt den DistributedData-Snapshot des Coordinators, wodurch eine 200 in einer Standardkonfiguration unerreichbar war: nichts im Framework startet diese Extension, und der Snapshot wird nur geschrieben, wenn man sich per coordinatorStateStore dafür entscheidet. Der Store existiert weiterhin und bleibt optional — er verkürzt den Leader-Failover —, aber dieser Endpunkt hängt nicht mehr davon ab.

Den Body lesen:

  • version zählt Broadcasts des Coordinators, keine Shard-Zuweisungen — eine Erhöhung pro Publish, und ein Publish fasst einen Schwung Verschiebungen zusammen. Vergleiche den Wert über zwei Abfragen, um „die Karte hat sich bewegt“ von „die Karte ist unverändert“ zu unterscheiden.
  • takenAt und leader stempelt der antwortende Node beim Eintreffen der Karte, zwei Nodes können also dieselbe version mit leicht verschiedenen Zeitstempeln melden.
  • regions[].key ist <Adresse>|<Region-Pfad>, derselbe Key, den shardHome[].regionKey verwendet. Eine Region, die nichts hostet, steht trotzdem in der Liste, mit leerem shards — „registriert und ohne Shards“ ist die interessante Hälfte einer Rebalance-Frage.
  • Eine 200 mit leerem shardHome ist normal und kein Fehler: regions füllt sich, sobald sich Regionen registrieren, während ein Shard erst dann ein Zuhause bekommt, wenn eine Entity darin adressiert wird.

Opt-in via enableMetricsEndpoint: true.

GET /metrics
→ 200 OK
Content-Type: text/plain; version=0.0.4; charset=utf-8
# HELP actor_messages_processed_total ...
# TYPE actor_messages_processed_total counter
actor_messages_processed_total{class="Worker",path="..."} 12345
...

Prometheus-Textformat. Siehe Prometheus-Exporter.

Antwortet stattdessen mit 503, wenn die installierte MetricsRegistry sich nicht über collect() zurücklesen lässt — die prom-client-Bridge ist die eine im Framework, die das nicht kann, weil sie ihre Schreibvorgänge an prom-client weiterleitet und keinen Snapshot behält:

GET /metrics
→ 503 Service Unavailable
metrics endpoint unavailable: the installed MetricsRegistry does not
support collect() — ...

Ein 200 mit leerem Body wäre schlimmer als der Fehler: eine leere Exposition ist ein gültiger Scrape, also verbucht Prometheus das Target als erreichbar, und jede Serie des Frameworks hört still auf zu existieren. Die Prüfung läuft pro Request, weil die Registry zu jedem Zeitpunkt im Leben des Systems ausgetauscht werden kann.

Opt-in via enableLeaveEndpoint: true.

POST /cluster/leave
→ 202 Accepted
leaving

Der 202-Body ist das Klartext-Wort leaving (kein JSON) — der Leave ist Fire-and-forget.

Löst einen Graceful Cluster-Leave aus. Der Node wechselt auf leaving und meldet das den Peers, die er erreicht; sie führen ihn als removed, und seine Shards werden umverteilt. Das Actor-System selbst läuft weiter: Der Endpunkt ruft cluster.leave() auf und sonst nichts.

Nutze für:

  • Pod-Außerbetriebnahme vor einem Rolling Update.
  • Manuellen Node-Out während Incidents.

Hinter Authentifizierung gaten — jeder mit Portzugriff kann deinen Node drainen.

Opt-in via enableDownEndpoint: true oder actor-ts.management.enable-down-endpoint = on in HOCON.

POST /cluster/down
{ "address": "my-app@10.0.0.5:2552" }
→ 202 Accepted
{ "downed": "my-app@10.0.0.5:2552" }

Gibt 202 mit { downed } zurück, wenn das Mitglied gedownt wurde, oder 404, wenn die Adresse unbekannt oder bereits terminal ist.

Force-downt ein Mitglied per Adresse, in der Sicht des Nodes, den du aufrufst: Es wird dort als down und removed angekündigt und als Tombstone behalten, und Gossip trägt das Entfernen zu den Mitgliedern, die dieser Node noch erreicht. Das verteilt die Shards des Mitglieds neu und gibt seinen entfernten Watchern ihr Terminated. Das Target selbst wird nicht benachrichtigt (#940): Es läuft weiter, samt seinen Actors — stoppe es also zuerst oder stell sicher, dass es weg ist, bevor du es downst.

Das ist der Weg aus dem Opt-out. Unter dem Default — keine Downing-Strategie, actor-ts.cluster.failure-detector.auto-down = on — löscht der Failure Detector ein stilles Mitglied selbst, sobald er es für down erklärt, und der Endpunkt antwortet danach meist mit 404 dafür. Mit zwei oder mehr Überlebenden kann der Gossip eines anderen Überlebenden das gelöschte Mitglied allerdings als unreachable zurückbringen, bis der Detector es erneut entfernt, und ein Aufruf in diesem Fenster findet es und antwortet mit 202. Unter auto-down = off parkt der Failure Detector ein stilles Mitglied auf unreachable, und der Node loggt eine Warnung, die das Mitglied und diesen Endpunkt nennt; nur ein Operator, eine Strategie oder der eigene Neustart des Nodes auf derselben Adresse entfernt es.

Nutze für:

  • Entfernen eines abgestürzten Mitglieds, das der Failure Detector unter auto-down = off geparkt hat, ohne konfigurierte Downing-Strategie. Wurde der Node seitdem auf derselben Adresse neu gestartet, hat der Cluster den geparkten Lauf schon beendet, und der Eintrag unter dieser Adresse ist der neue Prozess: GET /cluster/members zeigt ihn wieder auf up mit neuerer version. Ihn dann zu downen entfernt den gesunden Lauf, der nicht benachrichtigt wird und außerhalb des Clusters weiterläuft.
  • Eine Partition von Hand auflösen unter auto-down = off ohne Strategie: Downe die Mitglieder der anderen Seite von der Seite aus, die du behältst, und stoppe die Prozesse auf der Seite, die du aufgibst, denn sie werden nicht benachrichtigt. Unter dem Default gibt es bis dahin nichts mehr aufzulösen — jede Seite hat die andere bei down-after entfernt und läuft als eigener Cluster weiter; konfiguriere lease-majority oder eine andere Downing-Strategie, damit stattdessen eine Seite gewinnt.
  • Entfernen eines Mitglieds, das eine konfigurierte Strategie geparkt gelassen hat, weil sie zu keinem Urteil gekommen ist.

Hochrisiko-Endpunkt — hinter Auth + Audit-Logs gaten.

import { path, get, concat, completeJson } from 'actor-ts/http';
import { managementRoutes } from 'actor-ts/management';
const baseRoutes = managementRoutes(system, cluster);
const customRoutes = concat(
baseRoutes,
path('admin',
get(async () => completeJson(200, { appVersion: '1.2.3' })),
),
);
await system.http(port, { host }).bind(customRoutes);

managementRoutes(system, cluster, options) gibt die Basis-Routen zurück; kombiniere mit eigenen via concat. Nützlich, um app-spezifische Admin-Endpunkte neben dem Standard-Satz hinzuzufügen.

Die Read-Endpunkte (/health, /ready, /cluster/members, /cluster/leader, /cluster/shards) und /cluster/down geben JSON zurück. /metrics liefert Prometheus-text/plain, und /cluster/leave gibt den Klartext-Body leaving zurück.

Fehler sind Klartext-Bodies (das complete(status, message) des Frameworks), kein strukturiertes Objekt — z. B. ergibt ein fehlender type-Query-Param ein 400, dessen Body missing query param \type“ ist.

Status-Codes folgen HTTP-Konventionen: 200 für Reads, 202 Accepted für die Admin-Aktionen (/cluster/leave, /cluster/down), 4xx für Client-Fehler (404, wenn eine /cluster/down-Adresse unbekannt ist) und 503, wenn Cluster oder ein Health-Check nicht verfügbar ist.

Die privilegierten Endpunkte (/cluster/down, /cluster/leave, /cluster/members, /cluster/shards, /metrics) akzeptieren standardmäßig anonyme Requests. Das ist nur sicher, wenn der Management-Port auf einem netzwerkisolierten Bind sitzt (separater Service, anderer Port, 127.0.0.1-only) oder hinter einem Reverse-Proxy, der die Auth für dich übernimmt.

Für Produktions-Deployments, die Management-Endpunkte einem breiteren Netz exponieren, hänge die mitgelieferten Middlewares über managementRoutes(system, cluster, { auth, ipAllowlist }) an:

import {
BearerTokenAuth,
IpAllowlist,
} from 'actor-ts/http';
import {
managementRoutes,
} from 'actor-ts/management';
const routes = managementRoutes(system, cluster, {
enableLeaveEndpoint: true,
enableDownEndpoint: true,
enableMetricsEndpoint: true,
// Shared-Secret-Bearer-Token (Rotation über mehrere Einträge).
auth: BearerTokenAuth({
tokens: [process.env.MGMT_TOKEN!],
realm: 'my-app-mgmt',
}),
// Netzwerk-Level-Fence — nur Requests aus diesen CIDRs
// erreichen die Anwendung überhaupt.
ipAllowlist: IpAllowlist({
allow: ['10.0.0.0/8', '127.0.0.1/32'],
// Hinter einem Reverse-Proxy: benenne die Proxys — die
// Client-Adresse wird dann vom Socket-Ende der
// Forwarded-Kette nach innen aufgelöst. Ohne das liest der
// Default den Socket-Peer, und der ist hinter einem Proxy
// der Proxy.
// trustedProxies: ['10.9.9.0/24'],
}),
});

Policy-Trennung:

  • auth wrappt die privilegierte Teilmenge (/cluster/*, /metrics). /health und /ready bleiben anonym — Kubernetes- Liveness-/Readiness-Probes können nicht so leicht einen Authorization-Header mitschicken. Setze authProtectHealth: true, wenn dein Deployment garantiert, dass die Probes Credentials präsentieren können.
  • ipAllowlist wrappt JEDEN Endpunkt inklusive /health und /ready. Netzwerk-Level-Isolation ist unabhängig davon, wer authentifiziert ist.

Fehlermodi:

  • Fehlender / falscher Authorization-Header → 401 Unauthorized mit WWW-Authenticate: Bearer realm="...".
  • Client-IP außerhalb der Allowlist (oder unauflösbar) → 403 Forbidden.

Die Middlewares sind general-purpose — du kannst sie auch außerhalb des Management-Subtrees über den withMiddleware(mw, route)-Builder einsetzen.