BrokerActor base class
Every protocol actor in actor-ts/io/broker — KafkaActor,
MqttActor, NatsActor, etc. — extends BrokerActor. The base
class owns the shared lifecycle: connection state machine,
reconnect-with-backoff, outbound buffer, subscriber fan-out,
lifecycle event publishing.
BrokerActor (the abstract base) owns:
- Lifecycle state machine —
disconnected ↔ connecting ↔ connected ↔ disconnecting. - Outbound buffer — messages sent before the connection is up.
- Reconnect loop — exponential backoff on connection loss.
- Subscriber tracking — fan-out for incoming events.
- Desired subscriptions — protocol subscriptions that outlive any one connection and are re-established on every reconnect.
Subclasses implement three protocol hooks:
| Hook | When called |
|---|---|
connectImplementation | Open the protocol-specific connection. |
disconnectImplementation | Close it — on stop and before every re-connect attempt. |
dispatchOutgoing(envelope) | Send a single buffered message on the wire. |
Subclasses implement the three protocol hooks; the base handles the rest. This page documents what’s shared. For per-protocol specifics, see the per-protocol pages.
The state machine
Section titled “The state machine”Four states:
disconnected— initial; not currently connected.connecting—connectImplementationis running.connected— connection up; messages flow.disconnecting—disconnectImplementationis running.
A disconnected → connecting → failure triggers a reconnect
loop: backoff + retry until success or maxAttempts
exhausted.
Every re-connect attempt starts from a clean slate: the base calls
disconnectImplementation first whenever a previous attempt opened
anything, so a subclass never builds a new connection on top of the dead
one’s handles. That makes disconnectImplementation an idempotent
contract — it may be called on an already-dead connection, and it must
drop only the live handles, never the desired subscriptions below.
Stopping the actor while a reconnect attempt is in flight abandons that
connection rather than adopting it. Reconnect runs on the system scheduler,
detached from the mailbox, so an attempt already inside
connectImplementation cannot be cancelled — it resumes after postStop
has returned. The base class therefore re-checks liveness on the way out of
the handshake and, if the actor is gone, calls disconnectImplementation
once more and stays disconnected: no BrokerConnected, no buffer drain,
no further retry. Without that check a handshake that completed installed
live handles on a terminated actor, and one that failed re-armed the
backoff timer and reconnected forever, since maxAttempts defaults to
Infinity (#708).
Subclass contract
Section titled “Subclass contract”import type { RetiredLeaves } from 'actor-ts/io';
abstract class BrokerActor<S, Command, P, Subscription = never> extends Actor<Command> { // Subclasses implement: protected abstract configKey(): string; protected abstract builtInDefaultOptions(): Partial<S>; protected abstract readOptionsFromConfig(config: Config): Partial<S>; protected abstract requiredOptions(): ReadonlyArray<keyof S>; protected abstract endpointLabel(): string;
protected abstract connectImplementation(): Promise<void>; protected abstract disconnectImplementation(): Promise<void>; protected abstract dispatchOutgoing(envelope: OutboundEnvelope<P>): Promise<void>;
protected abstract onCommand(command: Command): void | Promise<void>;
// Optional — only for refs the subclass watches itself: protected onTerminated(signal: Terminated): void | Promise<void> {}
// Optional — the spellings this broker's own leaves had before a rename: protected retiredLeaves(): RetiredLeaves { return {}; }}Four categories:
- Settings glue (
configKey,builtInDefaultOptions,readOptionsFromConfig,requiredOptions,endpointLabel) — describes how to assemble settings from the three layers (constructor + HOCON + defaults) and how to validate. - Protocol hooks (
connectImplementation,disconnectImplementation,dispatchOutgoing) — the protocol-specific work. - Message handling (
onCommand) — one command from the mailbox. This is where a subclass’smatch(...).exhaustive()dispatch table lives. - Death watch (
onTerminated) — optional; see Subscriber tracking.
readOptionsFromConfig is handed the system config, not the broker’s
block, and reads its leaves at their full dotted paths under configKey() —
`${this.configKey()}.url`, or a ConfigKeys constant holding the path —
the way every other reader in the framework addresses its keys. It is called
only when the block exists. The config it is handed refuses any path outside
configKey() with a ConfigError naming it, so an override written for the
old contract, which was handed the block and read relative names such as
'url', fails at start instead of quietly reading nothing.
retiredLeaves() is the other half of renaming a leaf: return the old
spellings mapped to the new ones — a RetiredLeaves table, imported from
actor-ts/io beside BrokerActor — as paths relative to configKey() (dotted
for a leaf in a group), and a configuration that still spells one the old way
fails preStart with a ConfigError naming both paths — the same refusal the
shared leaves below get. The default retires nothing.
endpointLabel is the human-readable connection identity
(“amqp://localhost:5672”, “kafka-cluster-1”) used in log lines
and lifecycle events.
Return the connection string as configured — do not redact it
yourself. The base class runs every use through
redactedEndpointLabel(), which drops the userinfo and the query
string, so amqp://svc:pw@rabbit:5671/orders reaches
BrokerConnected as amqp://rabbit:5671/orders. That matters
more than it looks: the four lifecycle events go to the
system-wide EventStream, which has no authorization concept, so
any actor in the system can read them — and a reconnect loop
republishes on every backoff tick for the length of an outage.
A joined server list keeps its shape and loses each credential
(nats://***@a:4222,nats://***@b:4222). A label that never carried
one comes back unchanged only when it holds no ?, # or @:
nothing behind the first ? or # is shown, and an @ anywhere
past a host cannot be told from a password that holds a /, so
amqp://rabbit:5671/orders@eu stops at amqp://***. A URL with a
web scheme (http, https, ws, wss) is also printed the way its
parse normalises it — ws://Broker.Example:80/feed as
ws://broker.example/feed. Call redactedEndpointLabel() in your
own log lines too.
onReceive is sealed — the base class owns it, so that it can intercept
Terminated before your dispatch table sees it. Implement onCommand
instead; it receives everything except the death-watch signal.
What the base does for you
Section titled “What the base does for you”Outbound buffering
Section titled “Outbound buffering”this.enqueueOutbound(payload);Subclasses call this.enqueueOutbound(payload) to send; it
returns true if the message was sent or buffered, false if it
was dropped. The base class:
- If connected — wraps
payloadin anOutboundEnvelopeand callsdispatchOutgoing(envelope)immediately. - If disconnected (or
connecting) — buffers up tooutboundBufferenvelopes (default1000). On reconnect, drains the buffer in order.
On overflow the base always evicts the oldest buffered
envelope (FIFO) and publishes a BrokerBufferOverflow event on
the event stream — it is never thrown. With outboundBuffer: 0
buffering is disabled: the message is dropped and a
BrokerNotConnected event is published.
Subscriber tracking
Section titled “Subscriber tracking”import { match } from 'ts-pattern';
protected override onCommand(command: MyCommand): void { match(command) .with({ kind: 'subscribe' }, (c) => this.onSubscribe(c)) .with({ kind: 'unsubscribe' }, (c) => this.onUnsubscribe(c)) .exhaustive();}
private onSubscribe(command: SubscribeCommand): void { this.subscribeRef(command.topic, command.subscriber);}
private onUnsubscribe(command: UnsubscribeCommand): void { this.unsubscribeRef(command.topic, command.subscriber);}subscribeRef(topic, ref) registers ref as interested in
topic’s inbound messages, and death-watches it — for a local ref;
see the caveat below.
unsubscribeRef matches on the ref’s path rather than the ref object, so
holding a different ref for the same actor still unsubscribes.
When the protocol pushes an inbound message, the subclass calls:
this.fanOutToTopic(topic, inboundMessage);The base delivers to every subscriber for that topic.
Desired subscriptions
Section titled “Desired subscriptions”Subscriber tracking above is inside the actor system — which local refs want which topic. A desired subscription is the other half: the subscription the actor holds on the broker, which has to be re-established every time the connection is rebuilt.
The base keeps that set separate from the live handles, so it outlives any one connection:
// Record it (and establish it now, if connected).await this.rememberSubscription('orders.new', target);// Drop it, from the broker and from the desired set.await this.forgetSubscription('orders.new');Subclasses provide three hooks:
| Hook | Purpose |
|---|---|
initialSubscriptions() | Subscriptions declared in the options. Folded into the desired set once, before the first connect. |
applySubscription(key, subscription) | Establish one subscription on the live connection. Must tolerate a key that is already live. |
revokeSubscription(key) | Tear one down. Optional — several protocols can only drop a subscription by dropping the whole consumer. |
and replay the whole set from inside connectImplementation:
protected async connectImplementation(): Promise<void> { this.connection = await MyClient.connect(this.options.url); await this.applyDesiredSubscriptions(); // configured + runtime}The replay is driven by the subclass rather than by the base class
because the right point in the handshake is protocol-specific —
kafkajs, for one, wants every subscribe in before consumer.run.
What this buys you:
- A subscription added at runtime survives a reconnect — it is not just a call on a connection that is about to die.
- A
subscribethat arrives while the actor is disconnected is remembered and applied on the next connect, instead of being dropped. - Seeding from the options is once-only, so a runtime
unsubscribeis not resurrected by the next reconnect. - Re-remembering a live key revokes it first, so a changed payload (a different target actor, say) actually takes effect.
- A subscription that cannot be established is logged as a warning and the rest of the set still goes through. One bad subject does not take the connection down — and it does not silently leave you connected-but-deaf either.
MqttActor predates this mechanism and keeps its own richer registry
(per-topic QoS, several targets per pattern, deathwatch on each), with
the same reconnect guarantees.
Reconnect-with-backoff
Section titled “Reconnect-with-backoff”reconnect: { initialDelayMs: 200, maxDelayMs: 30_000, factor: 2, maxAttempts: Infinity, // the default — retry forever randomFactor: 0.2, // the default — ±20 % jitter}Configurable per actor (or reconnect: false to disable
auto-reconnect entirely). Each attempt waits
min(initialDelayMs * factor^(attempt - 1), maxDelayMs), multiplied
by a random 1 ± randomFactor.
The same settings come from HOCON too, under the broker’s own root. Every
broker block shares these leaves with the circuit breaker’s id and the
outbound buffer, and a subclass you write reads them under its configKey()
without doing anything for it:
actor-ts.io.broker.kafka { reconnect { initial-delay = 200ms max-delay = 30s factor = 2 random-factor = 0.2 # ±20 % jitter; 0 for a deterministic schedule # max-attempts omitted = unlimited (the default); 1 = one reconnect, two connects in all } circuit-breaker = "kafka" # a breaker id; none when unset or "" outbound-buffer = 1000 # messages held while disconnected; 0 = fail-fast}
# The breaker's numbers live with every other breaker's, over actor-ts.circuit-breaker.default.actor-ts.circuit-breaker.kafka { max-failures = 5 reset-timeout = 30s}Each leaf is the kebab-case of its field with the unit suffix dropped, so a
duration takes 30s as readily as a bare millisecond count. There is no
HOCON spelling of reconnect: false: switching auto-reconnect off entirely
takes the constructor, and max-attempts = 1 is the nearest a config file
gets. It still retries once: the count is of reconnects, the first connect is
not one, and 0 is refused. The camelCase spellings these leaves used to
have — initialDelayMs, outboundBuffer and the rest — and every block the
breaker had before it
became an id — circuitBreaker { … } and
circuit-breaker { failure-threshold, reset } — are refused with a
ConfigError that names the new key, rather than ignored. The refusal comes
when the actor starts, in its preStart, which is where its block is first
read — not at ActorSystem.create, so a retired key under a broker that is
never spawned is never reported.
The jitter is what keeps a fleet from retrying in lockstep. Without
it the delay is a pure function of the attempt counter and these options,
so every broker actor that lost the same broker in the same instant wakes
in the same millisecond, wave after wave — and the herd can hold the
recovering broker down. Set randomFactor: 0 for a fully deterministic
schedule.
The same spread applies to the wake-up after a circuit breaker refused an
attempt: the actor comes back somewhere in
[remaining, remaining × (1 + randomFactor)] of the window the breaker
reported, rather than exactly at its end. That jitter is one-sided — a
breaker is never re-tried early. See Circuit breaker
below.
Each attempt fires BrokerReconnectAttempt on the event stream (its
delayMs is the jittered value actually scheduled); after maxAttempts
exhausted (if finite), BrokerReconnectFailed fires and the actor stays
disconnected.
For a deterministic test, inject the randomness source — random: () => 0.5 pins every delay to its un-jittered value:
reconnect: { initialDelayMs: 100, random: () => 0.5 }Circuit breaker
Section titled “Circuit breaker”Off by default. Name a breaker by id and every connect attempt is called through it:
import { KafkaOptions } from 'actor-ts/io';
const kafkaOptions = KafkaOptions.create() .withBrokers(['kafka-1:9092']) .withCircuitBreaker('kafka');— or circuit-breaker = "kafka" under the broker’s root, as in the block
above. It is the pattern breaker, resolved
through CircuitBreakerExtension: its numbers live under
actor-ts.circuit-breaker.kafka, leaf by leaf over
actor-ts.circuit-breaker.default, the block every breaker in the system is
configured from. "" names none.
What it does to the connect cycle:
- It opens after
max-failuresconsecutive failed connects. Only connect attempts count: a connection that drops after it was established is a reconnect, not a failure, and a connect that succeeds resets the count. - While open, it refuses. A refused attempt makes no connect, publishes
no
BrokerReconnectAttemptand does not count againstmaxAttempts; the actor comes back when the window ends, by the breaker’s clock, spread forwards byrandomFactoras above. - Once the window has passed, it lets one probe through. The breaker is
half-open, and the probe decides: a success closes it, a failure opens it
again at once — for a window
backoff-factorgrows, up tomax-reset-timeout. ignored-error-nameslistsError.namevalues that never count — a driver’s transient resolver error, say.call-timeout, when set, is a deadline on each connect, and an attempt that outlasts it counts as a failure. The WebSocket client,SseActorandTcpSocketActorabort that attempt throughabortConnectAttempt, as the connect deadline below aborts one. No other built-in broker can abort a connect in flight: there the timeout still counts and can open the breaker, but the connect runs until it settles on its own, the next attempt waits for it, and a warning says so.
Actors that name the same id share one breaker, and so one verdict: once
it opens, an actor that never tried is refused too, and each actor makes at
most one connect per window. For a fleet of actors on one broker cluster that
is the point — one attempt each per window instead of a reconnect burst from
each. Whether a single probe answers for all of them depends on how long a
failing connect takes. Each actor’s wake-up is spread forwards by its
randomFactor, and the half-open breaker admits every attempt that arrives
before the probe settles. A connect that fails fast reopens the breaker
before the next actor wakes, so the rest are refused and one probe decided for
the fleet; a connect that hangs — a broker that black-holes its traffic — is
still in flight when the others wake, and each of them probes too. A
call-timeout bounds how long a hanging probe holds the breaker half-open.
It is also why two
unrelated brokers get two ids: a breaker shared by both opens on either’s
failures and holds both off.
Every transition is published as BrokerCircuitBreakerStateChanged — actor
path, endpoint, breaker id and state — by each actor that names the breaker.
open is the one to alert on, since a refused attempt publishes nothing else.
A connect that fails because the actor was being stopped is not counted.
What a breaker does not do is slow a peer that accepts every connect and
then drops it. A connect that succeeds counts as a success and resets the
reconnect backoff, so the actor reconnects to such a peer every
initialDelayMs or so.
Liveness deadlines
Section titled “Liveness deadlines”Everything above is triggered by handleConnectionLost, and that is
only ever called when the transport says something ended — a
close event, an error, a stream that reported done. A peer that
vanishes without sending FIN or RST says none of them. A dropped NAT
entry, a container killed with SIGKILL, a route that starts
black-holing: the socket stays open, the actor stays connected, and
the reconnect machinery never runs.
Two clocks close that gap. Both are opt-in per protocol, because only the application knows how quiet its peer is allowed to be:
idleTimeoutMs— a read deadline. If nothing arrives from the peer for that long, the connection is reported lost through the ordinaryhandleConnectionLostpath, so everything on this page applies unchanged:BrokerDisconnected, backoff, buffer, breaker. It is reset by inbound bytes and not by outbound ones, deliberately: a client writing into a black hole is exactly the case that has to trip it.connectTimeoutMs— a deadline on oneconnectImplementation. Every protocol settles its connect on an event (connect,open, response headers) and none of them has a clock, so a peer that finishes the handshake and then stalls holds the actor inconnectingindefinitely. On expiry the attempt is aborted, and the failure travels the path a refused connect already takes.
TcpSocketActor, SseActor and WebsocketClientActor expose both.
Set idleTimeoutMs above whatever heartbeat the peer already
sends; below it, the deadline severs healthy connections in a loop.
0 (the default) disables either one.
Protocols with their own protocol-level liveness do not need these:
MqttActor has MQTT keepAlive, and KafkaActor runs a consumer
heartbeat.
Lifecycle events
Section titled “Lifecycle events”Published on system.eventStream:
| Event | When |
|---|---|
BrokerConnected | A connectImplementation succeeded. |
BrokerDisconnected | A live connection was lost. Not published by a graceful stop. |
BrokerReconnectAttempt | A reconnect attempt is starting. |
BrokerReconnectFailed | maxAttempts exhausted. |
BrokerBufferOverflow | The outbound buffer dropped an envelope. |
BrokerNotConnected | Sent without a connection. |
BrokerCircuitBreakerStateChanged | The circuit breaker the actor names went open, half-open or closed. |
Subscribe to monitor every broker actor uniformly:
system.eventStream.subscribe(monitorRef, BrokerConnected);system.eventStream.subscribe(monitorRef, BrokerDisconnected);The events include actorPath — distinguish events from
different broker actors in the system.
Settings resolution
Section titled “Settings resolution”1. builtInDefaultOptions() ← lowest priority (always applied)2. readOptionsFromConfig() ← HOCON overrides3. Constructor argument ← highest priority (per-instance)preStart first refuses a retired spelling under configKey() — one of the
shared leaves, or one retiredLeaves() lists. It then reads the shared
reconnect, circuit-breaker and buffer leaves itself and the protocol’s own
through readOptionsFromConfig, both off the system config at full paths
under configKey(), merges the three layers, validates against
requiredOptions(), resolves the circuit breaker circuitBreaker names, and
stashes the result for the rest of the actor’s life via this.options.
Missing required settings cause an early-error throw on
preStart — the actor goes through the supervisor’s failure
path before it ever attempts to connect.
Writing a custom protocol actor
Section titled “Writing a custom protocol actor”import { match } from 'ts-pattern';import type { Config } from 'actor-ts';import { BrokerActor, type OutboundEnvelope, type BrokerCommonOptionsType } from 'actor-ts/io';
interface MyProtocolOptionsType extends BrokerCommonOptionsType { readonly url: string;}
class MyProtocolActor extends BrokerActor<MyProtocolOptionsType, Command, MyPayload> { private connection: MyClient | null = null;
protected configKey() { return 'actor-ts.io.broker.my-protocol'; } protected builtInDefaultOptions() { return { /* ... */ }; } // The system config, read at full paths under configKey(). protected readOptionsFromConfig(config: Config): Partial<MyProtocolOptionsType> { const url = `${this.configKey()}.url`; return config.hasPath(url) ? { url: config.getString(url) } : {}; } protected requiredOptions() { return ['url'] as const; } protected endpointLabel() { return this.options.url; }
protected async connectImplementation(): Promise<void> { this.connection = await MyClient.connect(this.options.url); this.connection.onMessage((m) => this.fanOutToTopic(m.topic, m)); }
// Called on stop AND before every re-connect attempt — idempotent, // and safe on a connection that is already dead. protected async disconnectImplementation(): Promise<void> { await this.connection?.close(); this.connection = null; }
protected async dispatchOutgoing(env: OutboundEnvelope<MyPayload>): Promise<void> { await this.connection!.send(env.payload); }
// `onReceive` is sealed by the base — implement `onCommand` instead. protected override onCommand(command: Command): void { match(command) .with({ kind: 'subscribe' }, (c) => this.onSubscribe(c)) .exhaustive(); }
private onSubscribe(command: SubscribeCommand): void { this.subscribeRef(command.topic, command.subscriber); }}The base handles the rest. Most third-party clients (kafkajs,
nats.js, etc.) have an event-based message-receive API that
maps cleanly to this.fanOutToTopic(...).
Where to next
Section titled “Where to next”- I/O overview — the bigger picture: which protocols ship.
- Kafka / MQTT / NATS / etc. — per-protocol pages.
- Event stream — where lifecycle events are published.
- Backoff policy — a standalone backoff primitive (the reconnect loop rolls its own).
