Transports
Der Cluster-Transport ist die Leitung zwischen Cluster-Nodes —
er liefert Gossip-Nachrichten, Heartbeats und Anwendungs-Envelopes
(deine tells an Remote-Actors). Zwei Implementierungen liegen
dem Framework bei:
| Transport | Verwendung |
|---|---|
TcpTransport | Produktion. Echte TCP-Sockets, optional TLS. |
InMemoryTransport | Tests. Schleift Frames durch In-Process-JS-Strukturen — kein Networking. |
Beide implementieren dieselbe Transport-Schnittstelle, sodass das
Cluster-Verhalten unabhängig vom eingesteckten Transport identisch
ist.
Die Schnittstelle
Abschnitt betitelt „Die Schnittstelle“interface Transport { readonly self: NodeAddress; start(): Promise<void>; shutdown(): Promise<void>; setHandler(handler: (from: NodeAddress, message: WireMessage) => void): void; send(to: NodeAddress, message: WireMessage): void; disconnect(peer: NodeAddress): void; peers(): NodeAddress[]; holdsConnectionTo?(peer: NodeAddress): boolean;}Kleine Oberfläche — Bootstrap, Senden, Empfangen, Trennen. Der Cluster steckt einen Handler ein und bekommt einen Strom eingehender Wire-Nachrichten samt Absenderadresse.
holdsConnectionTo ist optional. Die Methode beantwortet, ob
send(peer, …) über eine Verbindung hinausginge, die der Transport
bereits hält — bestätigt oder noch im Handshake —, statt eine neue
aufzubauen, und der Cluster fragt sie, bevor ein Anwendungs-Frame an
einen Node geht, der kein Member ist (siehe
Cluster-Sicherheit).
Ein eigener Transport ohne sie funktioniert weiterhin: Der Cluster
fällt auf peers() zurück, das nur bestätigte Verbindungen auflistet,
sodass ein Frame an einen Nicht-Member in diesem Handshake-Fenster
abgelehnt statt eingereiht wird.
TcpTransport (Standard)
Abschnitt betitelt „TcpTransport (Standard)“import { Cluster, ClusterOptions, TcpTransport, TcpTransportOptions } from 'actor-ts/cluster';
const clusterOptions = ClusterOptions.create() .withHost('0.0.0.0') .withPort(2552) .withSeeds(['...']);const cluster = await Cluster.join( system, clusterOptions, // transport defaultet auf TcpTransport — kein expliziter Pass nötig);Was er tut:
- Lauscht auf
host:portauf eingehende Verbindungen — das ist das Paar, an das gebunden wird, ein Wildcard-Host gehört also hierher. - Kündigt
advertisedHost:advertisedPortin seinem Handshake an und schlüsselt Peers danach. Das ist die Identität des Nodes, wird deshalb getrennt aufgelöst und ist nie eine Wildcard; ungesetzt folgt der Hosthost, sofern der routebar ist, und der Port istport. Siehe Cluster — Überblick. - Verbindet sich nach Bedarf mit Peers (beim ersten Send oder zu Seeds bei Join-Zeit).
- Frame-Größen-Cap (Standard 16 MiB) — Frames, die größer sind, werden abgelehnt, um DoS via gefälschtem Längenpräfix zu verhindern.
- Auto-Reconnect — fällt eine Verbindung mitten im Cluster-Leben aus, wird beim nächsten Send neu verbunden.
Was ein Hop kostet
Abschnitt betitelt „Was ein Hop kostet“Gemessen auf diesem Transport über Loopback, mit dem fernen Node auf einem
Worker-Thread (Bun 1.4.2, Windows 11, 18.09.2026): ein Cross-Node-tell
kostet rund 22 µs pro Nachricht, ein Cross-Node-ask rund 245 µs
pro Roundtrip — gegenüber ~260 ns und ~6 µs für denselben Actor im Prozess.
Das ist der ganze Draht — Envelope, getaggter JSON-Frame, Socket,
FrameDecoder samt Guards, Zustellung — und liegt im Rauschen des
MessageChannelTransport-Hops, den das
Worker-Mesh bezahlt; der Socket selbst ist also
nicht der teure Teil. Quelle ist benchmarks/cluster/tcp-message-cost.ts,
der einzige Benchmark, der diesen Transport überhaupt übt: der
Framing-Round-Trip braucht TcpTransport über Loopback, wie die Grenzen des
In-Memory-Transports weiter unten sagen, und der ferne Node läuft auf einem
eigenen Thread, weil zwei Nodes auf einer Event-Loop das Ende eines Bursts an
die Loopback-Puffer verlieren (#931) — der Benchmark prüft jeden Batch, das
wird also ein Throw und keine Zahl.
Runtime-Backends
Abschnitt betitelt „Runtime-Backends“TcpTransport redet nicht direkt mit dem OS — er läuft über ein
TcpBackend-Interface mit jeweils einer Implementierung pro
Runtime:
| Runtime | Backend | Zugrundeliegende API |
|---|---|---|
| Bun | bunTcpBackend | Bun.listen / Bun.connect, und Buns node:net / node:tls für einen Dial, der abgebrochen werden kann |
| Node | nodeTcpBackend | node:net / node:tls |
| Deno | denoTcpBackend | Deno.listen / Deno.connect |
Automatisch erkannt über getTcpBackend(). Normalerweise denkst du
nicht darüber nach — derselbe TcpTransport läuft auf jeder
Runtime. Auf Bun nutzen die Dials des Transports allerdings nicht
Bun.connect: Jeder Dial trägt seine Connect-Frist als Abort-Signal (siehe
Assoziations-Lebenszyklus), und ein natives
Bun.connect lässt sich nicht abbrechen — sie laufen deshalb über Buns eigenes
node:net / node:tls, das es kann. Der Listener bleibt bei Bun.listen.
Auf Bun puffern die beiden Enden einer Verbindung deshalb nicht gleich — die
Hälfte von #931, die auf die wählende Seite fällt. Die Seite, die gewählt hat,
schreibt über node:net, das alles im Speicher hält, was der Peer gerade nicht
abnehmen kann, ohne Grenze; ein Socket, den Bun.listen angenommen hat,
schreibt nativ, und natives Bun verwirft, was der Kernel nicht annimmt — der
Decoder des Empfängers liest den Rest des Streams dann ab der Mitte eines
Frames. Auf Node und Deno puffern beide Enden. Keine Runtime bremst den
Sender — TcpSocketLike.write meldet nichts —, ein Peer, der nicht mehr liest,
lässt also an einem Ende den Heap wachsen und bricht am anderen den Stream,
und die Grenze, die beides stoppt, ist Sache von #931.
Optionales TLS
Abschnitt betitelt „Optionales TLS“import { Cluster, ClusterOptions, NodeAddress, TcpTransport, TcpTransportOptions } from 'actor-ts/cluster';
const transportOptions = TcpTransportOptions.create().withTls({ cert: '...', // PEM key: '...', // PEM ca: '...', // optionales CA-Bundle rejectUnauthorized: true,});const transport = new TcpTransport( NodeAddress.parse('my-app@10.0.0.5:2552'), system.log, transportOptions,);
const clusterOptions = ClusterOptions.create() .withHost('10.0.0.5') .withPort(2552) .withSeeds(seeds) .withTransport(transport);await Cluster.join( system, clusterOptions,);TLS-gewrapptes TCP, alles-oder-nichts pro Cluster. Die Adresse des
Transports ist die eigene des Knotens: my-app ist der Name, mit dem
das Actor-System erzeugt wurde, und withHost / withPort nennen
denselben Host und Port.
Ein Peer, der wie hier über ein IP-Literal adressiert wird, wird gegen
ein IP-SAN in seinem Zertifikat geprüft. Gib dem Zertifikat jedes
Knotens deshalb seine Adresse als Subject Alternative Name mit
(IP:10.0.0.5) und lass serverName ungesetzt — SNI transportiert nur
Hostnamen, ein Dial zu einer IP kündigt also keinen an. Ein Dial zu
einem Hostnamen kündigt ihn per SNI an und prüft den Peer gegen ein
DNS-SAN; setze serverName nur, wenn der zu prüfende Name vom
gewählten Host abweicht. Auf Deno wird er zugleich zum gewählten Host,
weil Deno.connectTls für beides nur ein Feld hat. Siehe
Cluster-Sicherheit
für das Produktionsrezept.
Frame-Größe
Abschnitt betitelt „Frame-Größe“const transportOptions = TcpTransportOptions.create().withMaxFrameBytes(64 * 1024 * 1024);const transport = new TcpTransport(self, log, transportOptions);Überschreibe den Frame-Größen-Cap pro Frame. Standard 16 MiB reicht für typischen Cluster-Traffic (Gossip, Heartbeats, kleine Envelopes). Größere Werte verbessern nicht den allgemeinen Durchsatz — sie sind nur für einzelne große Nachrichten relevant.
Assoziations-Lebenszyklus
Abschnitt betitelt „Assoziations-Lebenszyklus“Vier Schranken entscheiden, was eine Gegenstelle, die eine TCP-Verbindung zu
diesem Port aufbauen kann, den Knoten halten lassen darf. Sie gelten für jeden
TcpTransport und sind dieselben vier, die ein Betreiber unter
actor-ts.remote für den
Transport setzt, den der Cluster sich selbst baut — neben einer fünften,
connectTimeoutMs, die die eigenen Dials dieses Knotens begrenzt statt dessen,
was ein Fremder ihn halten lassen kann:
const transportOptions = TcpTransportOptions.create() .withHandshakeTimeoutMs(5_000) .withOutboundQueueSize(1_000) .withMaxInboundConnections(1_024) .withIncompleteFrameIdleMs(30_000);const transport = new TcpTransport(self, log, transportOptions);| Schranke | Deckt ab | Löst aus mit |
|---|---|---|
handshakeTimeoutMs | Eine Verbindung, die ihre Hälfte des Handshakes nie spricht — ein Dial, der aufging und nie sein hello-ack bekommt, ein angenommener Socket ohne hello. | Ein WARN, das die Frist und die mit ihr verworfenen Frames nennt. |
connectTimeoutMs | Ein Dial, der nie aufgeht — kein TCP-Connect, oder ein TLS-Handshake, der nie fertig wird. Ungesetzt ist sie handshakeTimeoutMs. | Ein WARN, dass der Dial nicht verbinden konnte, und der Dial wird abgebrochen. |
outboundQueueSize | Frames, die für einen Peer gehalten werden, der sie gerade nicht annehmen kann. | Die ältesten fallen weg, plus ein WARN je Verbindung. |
maxInboundConnections | Dass sich die Kosten pro Verbindung durch Sockets im Loop vervielfachen. | Der neueste Socket wird abgelehnt, ein WARN je Sättigungsepisode. |
incompleteFrameIdleMs | Eine Verbindung, die gesprochen hat und dann mitten im Frame verstummt ist. | Ein WARN mit der Zahl gepufferter Bytes, dann wird die Verbindung verworfen. |
handshakeTimeoutMs ist bewusst ein Wert für beide Richtungen. Die
wählende Seite startet ihre Uhr vor dem TCP-Connect und dem TLS-Handshake, die
annehmende erst nach dem Accept — mit einer Zahl hat der Peer, der es noch
versucht, also immer zuerst aufgegeben. incompleteFrameIdleMs muss darüber
bleiben — ein Socket, der überhaupt nichts sendet, erreicht die Stall-Frist nie,
der Handshake-Timer ist also das Einzige, was ihn zurückholt — und die
Konstruktion wirft, wenn das nicht gilt. Geprüft wird das Paar, mit dem der
Transport läuft: Setzt man nur einen der beiden Werte, wird er gegen den
eingebauten Default des anderen geprüft. .withIncompleteFrameIdleMs(1_000)
allein wird also abgelehnt, weil die Handshake-Frist, gegen die er liefe, der
Default von 5 s ist. Keine der fünf hat eine „Aus”-Schreibweise: 0 wird für
jede abgelehnt.
Ein Dial läuft gegen zwei Fristen, die zusammen gestellt werden, sobald er
beginnt. connectTimeoutMs gibt einen Dial auf, der nicht aufgegangen ist — der
TCP-Connect und bei einem TLS-Dial der TLS-Handshake —, und sein WARN lautet
could not connect to … within N ms. Ist der Dial aufgegangen, gibt
handshakeTimeoutMs ihn auf, wenn kein hello-ack kommt, mit
connected to …, but no hello-ack came within N ms. Ungesetzt ist die
Connect-Frist die Handshake-Frist, die eine Frist, die ein Dial vorher hatte;
setze sie niedriger, um früher zu erfahren, dass ein Peer nicht da ist, während
ein langsamer weiterhin die ganze Handshake-Frist zum Antworten bekommt. Sie darf
handshakeTimeoutMs nicht überschreiten, das denselben Dial vom selben Moment an
begrenzt — die Konstruktion wirft, und ein alleiniges
.withConnectTimeoutMs(10_000) wird gegen den Default von 5 s abgelehnt.
Wer eine der beiden Fristen verpasst, wird aufgegeben statt nur vergessen: Der
Transport bricht den Connect ab, und der Socket darunter wird zerstört, statt so
lange weiterzuverbinden, wie das OS es versucht. Ein Dial, der vor seiner
Connect-Frist scheitert — abgelehnt, nicht auflösbar, ein Zertifikat, das die CA
nicht signiert —, meldet ebenfalls die could not connect-Zeile, mit dem Fehler
der Runtime als Anhang statt zitiert, weil der Fehlercode einer Runtime die
Ursache falsch benennen kann: Bun meldet unter Windows einen unbeantworteten
Connect als ECONNREFUSED. Das gilt auf jeder Runtime, weil jedes Backend einen
TLS-Dial erst dann als aufgegangen meldet, wenn sein Handshake abgeschlossen
ist, Deno eingeschlossen: Deno.connectTls löst schon beim TCP-Connect auf,
also führt das Deno-Backend den Handshake selbst aus, bevor es die Verbindung
herausgibt. Ein Zertifikat, das die CA nicht signiert, ist deshalb auch dort ein
Dial, der nicht verbinden konnte, und ein Peer, der den Connect annimmt und den
Handshake verschleppt, fällt der Connect-Frist zu.
Ein Teil einer Kombination lässt sich nicht abbrechen. Deno hat keinen Weg, den
TCP-Connect eines TLS-Dials abzubrechen (Deno.connectTls nimmt kein Signal);
ein Dial, der noch beim Verbinden aufgegeben wird, wird deshalb verworfen und
seine Verbindung geschlossen, sobald sie auftaucht, während der Connect selbst
weiterläuft, bis er gelingt oder das OS aufgibt. Ein Dial, der während seines
Handshakes aufgegeben wird, wird sofort verworfen, doch Deno beendet die
TCP-Verbindung darunter nicht: Unter Deno 2.6.8 behält die Gegenseite diesen
Socket, bis sie ihn selbst schließt.
Ein selbst gebauter Transport trägt seine eigenen Werte. Der Cluster reicht die
des Config-Blocks nur an einen Transport weiter, den er konstruiert hat, nie
an einen per withTransport(…) übergebenen.
InMemoryTransport (Tests)
Abschnitt betitelt „InMemoryTransport (Tests)“import { InMemoryTransport, NodeAddress, Cluster, ClusterOptions } from 'actor-ts/cluster';import { TestKit } from 'actor-ts/testkit';
// Kein Bus zu verdrahten — In-Memory-Transports finden einander über eine// prozessglobale Registry, indiziert nach der eigenen NodeAddress jedes Transports.const tk1 = TestKit.create('node-1');const tk2 = TestKit.create('node-2');
// Die self-Adresse jedes Transports muss dem system@host:port seines Knotens entsprechen.const clusterOptions = ClusterOptions.create() .withHost('1') .withPort(0) .withSeeds(['1:0']) .withTransport(new InMemoryTransport(new NodeAddress('node-1', '1', 0)));await Cluster.join( tk1.system, clusterOptions,);
const cluster2Options = ClusterOptions.create() .withHost('2') .withPort(0) .withSeeds(['1:0']) .withTransport(new InMemoryTransport(new NodeAddress('node-2', '2', 0)));await Cluster.join( tk2.system, cluster2Options,);Die Factory inMemoryTransport(system, host, port) ist eine Kurzform für
dieselbe Konstruktion — sie leitet die NodeAddress aus system.name ab.
Wie es funktioniert:
- Eine prozessglobale Registry routet Nachrichten zwischen In-Process-Transports.
- Jeder Transport registriert sich beim Start per Adresse in der Registry.
send(to, message)schlägt den Empfänger in der Registry nach und ruft dessen Handler direkt auf — keine Sockets, keine Serialisierung zu Bytes.
Wird von MultiNodeSpec — dem Multi-Node-Test-Harness — verwendet, um Multi-Node-Cluster in einem Prozess hochzufahren.
Was er nicht simuliert
Abschnitt betitelt „Was er nicht simuliert“- Netzwerkausfälle. Per Default liefert die Registry zuverlässig.
Für Fault Injection würdest du einen eigenen
Transportmit Drop-/Delay-/Reorder-Logik implementieren. - Latenz. Die Zustellung ist synchron innerhalb einer Event-Loop-Drehung.
- Serialisierung. Nachrichten werden per Referenz, nicht in
Bytes übergeben — und
TcpTransportist der einzige Transport, der überhaupt serialisiert:MessageChannelTransportreicht das Envelope anpostMessage, dieser hier gibt das Objekt direkt an den Handler des Empfängers. Um also den echten Framing-Round-Trip (encodeFrame/FrameDecoder, der einen getaggten JSON-Tree rahmt, nicht rohes JSON) zu üben, brauchst duTcpTransportüber Loopback. Der CBOR-Codec ist von keinem Cluster-Transport aus erreichbar; teste ihn direkt oder über HTTP-Marshalling.
Eigener Transport
Abschnitt betitelt „Eigener Transport“Transport gegen eine andere Drahtverbindung zu implementieren ist
selten, aber möglich. Beispiele:
- WebSocket-Transport — für Cluster-Teilnehmer im Browser (theoretisch; nicht implementiert).
- MessageChannel-Transport — für Cluster mit Worker-Threads in einem einzelnen OS-Prozess. Wird vom “Worker-Mesh”-Muster genutzt.
Die Schnittstelle ist klein genug, dass eine kompetente Implementierung ~200 Zeilen Code ist; die Schwierigkeit liegt darin, die Framing- und Heartbeat-Semantik zu treffen, die der Cluster erwartet.
Diagnostik
Abschnitt betitelt „Diagnostik“const peers = transport.peers(); // aktuell verbundene Adressenpeers() ist auch das, was der Readiness-Check
cluster-transport des Frameworks liest: ein Knoten, der noch
Member erwartet und zu keinem davon eine Verbindung hat, ist
abgeschnitten — /ready antwortet dann mit 503, damit ein Load
Balancer nicht mehr dorthin routet. Siehe
Health Checks.
Beachte: InMemoryTransport.peers() meldet jeden im Prozess
registrierten Transport unabhängig vom Verbindungszustand — ein
dagegen geschriebener Test kann dieses Fehlschlagen nicht
beobachten.
Der Transport legt keine Metriken pro Verbindung direkt offen — nutze die Metrik-Extension des Clusters, um Verbindungszahlen und gesendete/empfangene Bytes pro Peer zu bekommen.
Für tiefergehende Inspektion (spezifische Frame-Inhalte) aktiviere Debug-Logging am System:
const actorSystemOptions = ActorSystemOptions.create().withLogLevel(LogLevel.Debug);const system = ActorSystem.create('my-app', actorSystemOptions);// Suche nach [tcp-transport] Log-ZeilenMultiplexing
Abschnitt betitelt „Multiplexing“Eine einzige TCP-Verbindung zwischen zwei Nodes trägt:
- Gossip-Nachrichten — Cluster-Mitgliedschaftsaustausche.
- Heartbeat-Nachrichten — Failure Detection.
- Envelope-Nachrichten — deine
tells, mit Routing-Info kodiert. - Subsystem-Nachrichten — Sharding-Protokoll, PubSub-Gossip, DistributedData-Replikation.
Alles auf denselben TCP-Stream gemultiplext. Es gibt kein Prioritäts-Routing — Heartbeats und dein Bulk-Traffic teilen sich die Leitung. Für die meisten Workloads ist das in Ordnung; für explizite Isolation (Bandbreite für Cluster-Steuerung reservieren) bräuchte man einen eigenen Transport mit Per-Channel-Framing.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Cluster-Überblick — was auf dem Transport reitet.
- Refs über Nodes hinweg — wie Envelopes Actor-Refs für die Cross-Node-Zustellung kodieren.
- Cluster-Sicherheit — TLS + Auth.
- Worker-Mesh — MessageChannel-basierter Transport für In-Process-Worker.
- MultiNodeSpec —
nutzt
InMemoryTransportfür Multi-Node-Tests.
