Cluster event stream
system.eventStream is scoped to one ActorSystem, which is one node:
publishing there walks an in-process list and never touches the network.
cluster.eventStream is the other half — the same channels, reaching
subscribers on every node.
The owner carries the scope, so the two are told apart at the call site rather than by a convention you have to remember:
system.eventStream.publish(event); // this node onlycluster.eventStream.publish(event); // every nodeIt rides on the same mediator DistributedPubSub uses — one channel becomes one topic — so it inherits that machinery’s bounded gossip, its at-most-one-hop delivery and its caps, and it adds no new frame to the wire protocol.
A minimal example
Section titled “A minimal example”import { ActorSystem, Actor } from 'actor-ts';import { Cluster, ClusterOptions } from 'actor-ts/cluster';
type OrderPlacedEvent = { readonly kind: 'order-placed'; readonly sku: string };
class Auditor extends Actor<OrderPlacedEvent> { override onReceive(message: OrderPlacedEvent): void { this.log.info(`[audit] ${message.sku}`); }}
const system = ActorSystem.create('shop');const clusterOptions = ClusterOptions.create() .withHost(host) .withPort(port) .withSeeds(seeds);const cluster = await Cluster.join(system, clusterOptions);
const auditor = system.spawn(Auditor, 'auditor');cluster.eventStream.subscribe(auditor, 'order-placed');
// On any node in the cluster — every auditor sees it.cluster.eventStream.publish({ kind: 'order-placed', sku: 'XYZ-1' });Two channel forms, and only one is free
Section titled “Two channel forms, and only one is free”A kind-discriminated event needs nothing. It is already valid JSON and
its discriminant survives the wire untouched, so subscribing by kind string
or by an EventKey works across nodes out of the box — which is also the
shape the project’s own message conventions ask
for.
A class channel cannot travel on its own. The wire format tags the
built-in types it restores — a Date, a Map — and no user class, so an
instance crosses as its fields alone and arrives on the far side as a plain
object that matches no instanceof. Name it first:
class ShipmentEvent { constructor(public readonly trackingId: string) {} static fromJSON(body: Record<string, unknown>): ShipmentEvent { return new ShipmentEvent(String(body.trackingId)); }}
cluster.eventStream.register('ShipmentEvent', ShipmentEvent);cluster.eventStream.subscribe(auditor, ShipmentEvent);cluster.eventStream.publish(new ShipmentEvent('TRK-1'));register takes an optional third argument if the class has no static
fromJSON, and one of the two must exist. That is deliberate rather than a
missing convenience: rebuilding an arbitrary class generically means writing
peer-supplied keys onto a fresh prototype, which is a prototype-pollution
hazard this project has already had to remove once. Making the class say how
it is rebuilt keeps that door shut.
Bridging a node-local channel
Section titled “Bridging a node-local channel”bridge mirrors a channel of the node-local bus onto the cluster bus. It is
where “cluster-wide instead of local” gets decided, and the decision is
yours rather than the framework’s:
cluster.eventStream.bridge('cache-flushed');const stop = cluster.eventStream.bridge(ShipmentEvent); // returns an off switchA bridge mirrors; it does not divert. Everything already subscribed on
system.eventStream keeps its delivery, which is what lets an existing
deployment turn one on without auditing what already listens.
Why the framework’s own events stay local
Section titled “Why the framework’s own events stay local”Nothing the framework publishes is on the cluster bus by default, and each has its own reason:
| Event | Why it stays node-local |
|---|---|
ActorStarted / ActorStopped / ActorRestarted | publish runs on every actor start, stop and restart — the hottest path in the system, and one whose empty case is optimised down to a single length check. |
DeadLetter | Undeliverable messages arrive in floods, and there is no storm suppression yet. Cluster-wide, a local storm becomes a cluster-wide one. |
MemberUp, MemberRemoved, … | Every node derives these from its own gossip merge, so publishing them cluster-wide would show each subscriber N copies of one membership change. |
| Broker lifecycle events | Their cause can still carry a credential-bearing driver error, and this bus has no authorization concept. |
DispatcherError, SchedulerError | Node diagnostics, and they carry a cause with the same exposure. |
If you want one of them cluster-wide anyway, bridge it deliberately —
subject to the single-origin rule above, which rules the membership events
out.
Not synchronous
Section titled “Not synchronous”system.eventStream.publish delivers inside the call.
cluster.eventStream.publish does not: it goes through the mediator’s
mailbox even for a subscriber on the publishing node. Nothing about crossing a node boundary
could have been synchronous, and putting both origins on one path is what
keeps local and remote delivery in one order rather than racing each other.
A test therefore waits for the delivery instead of asserting straight after the publish.
Which bus, and which subscribe
Section titled “Which bus, and which subscribe”Three things on this page look alike and are not:
| API | Scope | Carries | Replays |
|---|---|---|---|
system.eventStream | One node | Any class or kind | No |
cluster.eventStream | Cluster-wide | Any class or kind | No |
cluster.subscribe | One node, from cluster-wide state | Membership events only, to a callback | Yes |
DistributedPubSub | Cluster-wide | String topics, with anycast | No |
cluster.subscribe is the one most easily mistaken for cluster.eventStream
because they sit on the same object. It takes a callback rather than a ref,
carries only membership events, and replays the current membership when you
subscribe — that replay is why it exists as its own thing.
Reach for DistributedPubSub instead when you want string topics chosen at
runtime, or anycast — one subscriber cluster-wide rather than all of them.
Where to next
Section titled “Where to next”- Event stream — the node-local bus, its channel forms and the events the framework publishes on it.
- DistributedPubSub — topic-based pub/sub, and the mediator this bus is built on.
- Cluster overview — membership,
cluster.subscribeand the events it delivers.
