Ir al contenido
Español

Cluster event stream

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

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 only
cluster.eventStream.publish(event); // every node

one hop

publish on node A

node-A mediator

node-A receiver

subscribers on A

node-B mediator

node-B receiver

subscribers on B

It 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.

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

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.

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 switch

A 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:

EventWhy it stays node-local
ActorStarted / ActorStopped / ActorRestartedpublish 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.
DeadLetterUndeliverable 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 eventsTheir cause can still carry a credential-bearing driver error, and this bus has no authorization concept.
DispatcherError, SchedulerErrorNode 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.

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.

Three things on this page look alike and are not:

APIScopeCarriesReplays
system.eventStreamOne nodeAny class or kindNo
cluster.eventStreamCluster-wideAny class or kindNo
cluster.subscribeOne node, from cluster-wide stateMembership events only, to a callbackYes
DistributedPubSubCluster-wideString topics, with anycastNo

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.

  • 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.subscribe and the events it delivers.