Zum Inhalt springen
Deutsch

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:

TransportVerwendung
TcpTransportProduktion. Echte TCP-Sockets, optional TLS.
InMemoryTransportTests. 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.

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.

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:port auf eingehende Verbindungen — das ist das Paar, an das gebunden wird, ein Wildcard-Host gehört also hierher.
  • Kündigt advertisedHost:advertisedPort in 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 Host host, sofern der routebar ist, und der Port ist port. 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.

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.

TcpTransport redet nicht direkt mit dem OS — er läuft über ein TcpBackend-Interface mit jeweils einer Implementierung pro Runtime:

RuntimeBackendZugrundeliegende API
BunbunTcpBackendBun.listen / Bun.connect, und Buns node:net / node:tls für einen Dial, der abgebrochen werden kann
NodenodeTcpBackendnode:net / node:tls
DenodenoTcpBackendDeno.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.

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.

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.

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);
SchrankeDeckt abLöst aus mit
handshakeTimeoutMsEine 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.
connectTimeoutMsEin 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.
outboundQueueSizeFrames, die für einen Peer gehalten werden, der sie gerade nicht annehmen kann.Die ältesten fallen weg, plus ein WARN je Verbindung.
maxInboundConnectionsDass sich die Kosten pro Verbindung durch Sockets im Loop vervielfachen.Der neueste Socket wird abgelehnt, ein WARN je Sättigungsepisode.
incompleteFrameIdleMsEine 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.

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.

  • Netzwerkausfälle. Per Default liefert die Registry zuverlässig. Für Fault Injection würdest du einen eigenen Transport mit 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 TcpTransport ist der einzige Transport, der überhaupt serialisiert: MessageChannelTransport reicht das Envelope an postMessage, 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 du TcpTransport über Loopback. Der CBOR-Codec ist von keinem Cluster-Transport aus erreichbar; teste ihn direkt oder über HTTP-Marshalling.

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.

const peers = transport.peers(); // aktuell verbundene Adressen

peers() 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-Zeilen

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.