Aller au contenu
Français

BrokerActor base class

Ce contenu n’est pas encore disponible dans votre langue.

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:

HookWhen called
connectImplementationOpen the protocol-specific connection.
disconnectImplementationClose 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.

connect

ok

fail — reconnect cycle

stop

disconnected

connecting

connected

disconnecting

Four states:

  • disconnected — initial; not currently connected.
  • connecting — connectImplementation is running.
  • connected — connection up; messages flow.
  • disconnecting — disconnectImplementation is 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).

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’s match(...).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.

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 payload in an OutboundEnvelope and calls dispatchOutgoing(envelope) immediately.
  • If disconnected (or connecting) — buffers up to outboundBuffer envelopes (default 1000). 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.

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.

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:

HookPurpose
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 subscribe that 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 unsubscribe is 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: {
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 }

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-failures consecutive 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 BrokerReconnectAttempt and does not count against maxAttempts; the actor comes back when the window ends, by the breaker’s clock, spread forwards by randomFactor as 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-factor grows, up to max-reset-timeout.
  • ignored-error-names lists Error.name values 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, SseActor and TcpSocketActor abort that attempt through abortConnectAttempt, 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.

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 ordinary handleConnectionLost path, 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 one connectImplementation. 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 in connecting indefinitely. 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.

Published on system.eventStream:

EventWhen
BrokerConnectedA connectImplementation succeeded.
BrokerDisconnectedA live connection was lost. Not published by a graceful stop.
BrokerReconnectAttemptA reconnect attempt is starting.
BrokerReconnectFailedmaxAttempts exhausted.
BrokerBufferOverflowThe outbound buffer dropped an envelope.
BrokerNotConnectedSent without a connection.
BrokerCircuitBreakerStateChangedThe 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.

1. builtInDefaultOptions() ← lowest priority (always applied)
2. readOptionsFromConfig() ← HOCON overrides
3. 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.

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(...).