Ir al contenido
Español

Transports

Esta página aún no está disponible en tu idioma.

The cluster transport is the wire between cluster nodes — it delivers gossip messages, heartbeats, and application envelopes (your tells to remote actors). Two implementations ship with the framework:

TransportUse
TcpTransportProduction. Real TCP sockets, optional TLS.
InMemoryTransportTests. Loops frames through in-process JS structures — no networking.

Both implement the same Transport interface, so cluster behavior is identical regardless of which is plugged in.

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;
}

Small surface — bootstrap, send, receive, disconnect. The cluster plugs in a handler and gets a stream of inbound wire messages with their sender address.

holdsConnectionTo is optional. It answers whether send(peer, …) would go out over a connection the transport already holds — acked or still in its handshake — rather than dial a new one, and the cluster asks it before an application frame leaves for a node that is not a member (see Cluster security). A custom transport without it still works: the cluster falls back to peers(), which lists acked connections only, so a frame to a non-member in that handshake window is refused instead of queued.

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 defaults to TcpTransport — no need to pass explicitly
);

What it does:

  • Listens on host:port for incoming connections — that is the pair to bind, so a wildcard host belongs here.
  • Announces advertisedHost:advertisedPort in its handshake, and keys peers on it. That is the node’s identity, so it is resolved separately and is never a wildcard; unset, the host follows host when host is routable and the port is port. See Cluster overview.
  • Connects to peers as needed (on first send, or to seeds at join time).
  • Per-frame size cap (default 16 MiB) — frames larger than this are rejected to prevent a DoS via fake length-prefix.
  • Auto-reconnect — if a connection drops mid-cluster-life, reconnects on the next send.

Measured on this transport over loopback, with the far node on a worker thread (Bun 1.4.2, Windows 11, 2026-09-18): a cross-node tell costs about 22 µs per message and a cross-node ask about 245 µs per round trip, against ~260 ns and ~6 µs for the same actor in-process. That is the whole wire — envelope, tagged-JSON frame, socket, FrameDecoder and its guards, dispatch — and it is within noise of the MessageChannelTransport hop the worker mesh pays, so the socket itself is not the expensive part. benchmarks/cluster/tcp-message-cost.ts is the source, and the only benchmark that exercises this transport: the framing round-trip needs TcpTransport over loopback, as the in-memory transport’s limits below say, and the far node lives on its own thread because two nodes on one event loop lose the tail of a burst to the loopback buffers (#931) — the benchmark verifies every batch, so that is a throw, not a number.

TcpTransport doesn’t talk directly to the OS — it goes through a TcpBackend interface, with one implementation per runtime:

RuntimeBackendUnderlying API
BunbunTcpBackendBun.listen / Bun.connect, and Bun’s node:net / node:tls for a dial that can be aborted
NodenodeTcpBackendnode:net / node:tls
DenodenoTcpBackendDeno.listen / Deno.connect

Auto-detected via getTcpBackend(). You usually don’t think about this — same TcpTransport works on every runtime. On Bun, though, the transport’s dials do not use Bun.connect: every dial carries its connect deadline as an abort signal (see Association lifecycle), and native Bun.connect cannot be cancelled, so they go through Bun’s own node:net / node:tls, which can. The listener stays on Bun.listen.

So on Bun the two ends of one connection do not buffer alike — the dialling side’s half of #931. The side that dialled writes through node:net, which keeps in memory whatever the peer cannot take yet, without bound; a socket that Bun.listen accepted writes natively, and native Bun drops what the kernel will not take, so the receiver’s decoder reads the rest of the stream from the middle of a frame. On Node and Deno both ends buffer. Neither runtime pushes back on the sender — TcpSocketLike.write reports nothing — so a peer that stops reading grows the heap at one end and breaks the stream at the other, and the bound that would stop both is #931’s to add.

import { Cluster, ClusterOptions, NodeAddress, TcpTransport, TcpTransportOptions } from 'actor-ts/cluster';
const transportOptions = TcpTransportOptions.create().withTls({
cert: '...', // PEM
key: '...', // PEM
ca: '...', // optional 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-wrapped TCP, all-or-nothing per cluster. The transport’s address is the node’s own: my-app is the name the actor system was created with, and withHost / withPort name the same host and port.

A peer addressed by an IP literal, as here, is verified against an IP SAN in its certificate, so give each node’s certificate its address as a subject alternative name (IP:10.0.0.5) and leave serverName unset — SNI carries host names only, so a dial to an IP announces none. A dial to a host name announces it through SNI and verifies the peer against a DNS SAN; set serverName only when the name to verify differs from the host dialled. On Deno it also becomes the host dialled, because Deno.connectTls has one field for both. See Cluster security for the production recipe.

const transportOptions = TcpTransportOptions.create().withMaxFrameBytes(64 * 1024 * 1024);
const transport = new TcpTransport(self, log, transportOptions);

Override the per-frame size cap. Default 16 MiB is enough for typical cluster traffic (gossip, heartbeats, small envelopes). Larger values don’t improve general throughput — they only matter for individual large messages.

Four bounds decide what a party that can open a TCP connection to this port is able to make the node hold. They apply to every TcpTransport, and they are the same four an operator sets under actor-ts.remote for the transport the cluster builds for itself — beside a fifth, connectTimeoutMs, which bounds this node’s own dials rather than what a stranger can make it hold:

const transportOptions = TcpTransportOptions.create()
.withHandshakeTimeoutMs(5_000)
.withOutboundQueueSize(1_000)
.withMaxInboundConnections(1_024)
.withIncompleteFrameIdleMs(30_000);
const transport = new TcpTransport(self, log, transportOptions);
BoundCoversTrips with
handshakeTimeoutMsA connection that never speaks its half of the handshake — a dial that opened and never gets its hello-ack, an accepted socket with no hello.A WARN naming the deadline and the frames dropped with it.
connectTimeoutMsA dial that never opens — no TCP connect, or a TLS handshake that never completes. Unset, it is handshakeTimeoutMs.A WARN saying the dial could not connect, and the dial aborted.
outboundQueueSizeFrames held for a peer that cannot take them right now.Oldest dropped, and one WARN per connection.
maxInboundConnectionsThe per-connection cost being multiplied by opening sockets in a loop.The newest socket refused, one WARN per saturation episode.
incompleteFrameIdleMsA connection that spoke and then went silent mid-frame.A WARN naming the buffered byte count, then the connection dropped.

handshakeTimeoutMs is one value for both directions on purpose. The dialling side starts its clock before the TCP connect and the TLS handshake and the accepting side after the accept, so with one number the peer that is still trying has always given up first. incompleteFrameIdleMs has to stay above it — a socket that sends nothing at all never reaches the stall deadline, so the handshake timer is the only thing that reclaims it — and construction throws if it does not. The pair it checks is the pair the transport will run with, so one of the two set alone is checked against the other’s built-in default: .withIncompleteFrameIdleMs(1_000) on its own is refused, because the handshake deadline it would run against is the 5 s default. None of the five has an “off” spelling: 0 is refused for each.

A dial runs two deadlines, armed together the moment it starts. connectTimeoutMs gives up a dial that has not opened — the TCP connect and, on a TLS dial, the TLS handshake — and its WARN reads could not connect to … within N ms. Once the dial has opened, handshakeTimeoutMs gives it up if no hello-ack comes, with connected to …, but no hello-ack came within N ms. Unset, the connect deadline is the handshake deadline, the one deadline a dial had before it; set it lower to learn sooner that a peer is not there while a slow one still gets the whole handshake deadline to answer. It may not exceed handshakeTimeoutMs, which bounds the same dial from the same moment — construction throws, and a lone .withConnectTimeoutMs(10_000) is refused against the 5 s default.

Missing either deadline gives the dial up rather than forgetting it: the transport aborts the connect, and the socket under it is destroyed instead of connecting on for as long as the OS keeps trying. A dial that fails before its connect deadline — refused, unresolvable, a certificate the CA does not sign — logs the could not connect line too, with the runtime’s error attached rather than quoted, because a runtime’s error code can misname the cause: Bun on Windows reports an unanswered connect as ECONNREFUSED. That holds on every runtime because every backend reports a TLS dial open only once its handshake is done, Deno included: Deno.connectTls resolves at the TCP connect, so the Deno backend runs the handshake itself before it hands the connection over. A certificate the CA does not sign is therefore a dial that could not connect there too, and a peer that accepts the connect and stalls the handshake is the connect deadline’s to give up.

One part of one combination cannot be aborted. Deno has no way to cancel the TCP connect of a TLS dial (Deno.connectTls takes no signal), so a dial given up while connecting is dropped and its connection closed the moment it appears, while the connect itself runs on until it completes or the OS gives up. A dial given up during its handshake is dropped at once, but Deno does not end the TCP connection under it: on Deno 2.6.8 the far side keeps that socket until it closes it itself.

A transport you build yourself carries its own values. The cluster only passes the config block’s to a transport it constructed, never to one handed in via withTransport(…).

import { InMemoryTransport, NodeAddress, Cluster, ClusterOptions } from 'actor-ts/cluster';
import { TestKit } from 'actor-ts/testkit';
// No bus to wire up — in-memory transports discover each other through a
// process-global registry, keyed by each transport's own NodeAddress.
const tk1 = TestKit.create('node-1');
const tk2 = TestKit.create('node-2');
// Each transport's self address must match its node's system@host:port.
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,
);

The inMemoryTransport(system, host, port) factory is a shorthand for the same construction — it derives the NodeAddress from system.name.

How it works:

  • A process-global registry routes messages between in-process transports.
  • Each transport registers itself in the registry by address on start.
  • send(to, message) looks up the recipient in the registry and invokes its handler directly — no sockets, no serialization to bytes.

Used by MultiNodeSpec — the multi-node test harness — to spin up multi-node clusters in one process.

  • Network failures. By default, the registry delivers reliably. For fault injection, you’d implement a custom Transport with drop / delay / reorder logic.
  • Latency. Delivery is synchronous within an event-loop turn.
  • Serialization. Messages are passed by reference, not bytes — and TcpTransport is the only transport that serializes at all: MessageChannelTransport hands the envelope to postMessage, and this one hands the object straight to the recipient’s handler. So to exercise the real framing round-trip (encodeFrame / FrameDecoder, which frames a tagged JSON tree, not bare JSON) you need TcpTransport over loopback. The CBOR codec is not reachable from any cluster transport; test it directly, or through HTTP marshalling.

Implementing Transport against a different wire is rare but possible. Examples:

  • WebSocket transport — for browser-side cluster participants (theoretical; not implemented).
  • MessageChannel transport — for worker-thread clusters in a single OS process. Used by the “worker mesh” pattern.

The interface is small enough that a competent implementation is ~200 lines of code; the difficulty is in matching the framing + heartbeat semantics the cluster expects.

const peers = transport.peers(); // currently-connected addresses

peers() is also what the framework’s cluster-transport readiness check reads: a node with members it still expects and no connection to any of them is cut off, and /ready answers 503 so a load balancer stops routing to it. See Health checks. Note that InMemoryTransport.peers() reports every transport registered in the process regardless of connection state — a test written against it cannot observe that check failing.

The transport doesn’t expose per-connection metrics directly — use the cluster’s metrics extension to get connection counts and bytes sent/received per peer.

For lower-level inspection (specific frame contents), enable debug logging on the system:

const actorSystemOptions = ActorSystemOptions.create().withLogLevel(LogLevel.Debug);
const system = ActorSystem.create('my-app', actorSystemOptions);
// Look for [tcp-transport] log lines

A single TCP connection between two nodes carries:

  • Gossip messages — cluster membership exchanges.
  • Heartbeat messages — failure-detection.
  • Envelope messages — your tells, encoded with routing information.
  • Subsystem messages — sharding protocol, pubsub gossip, DistributedData replication.

All multiplexed onto the same TCP stream. There’s no priority-routing — heartbeats and your bulk traffic share the pipe. For most workloads this is fine; for explicit isolation (reserve bandwidth for cluster control), you’d need a custom transport with per-channel framing.