DistributedPubSub
此内容尚不支持你的语言。
DistributedPubSub is the cluster-wide version of the local
event stream — pub/sub by topic name, working across nodes.
Each node hosts a mediator at a well-known path
(/system/cluster/pubsub/mediator). Subscribers register with their local
mediator; mediators gossip the topic→node map. Publishing sends
the message to the local mediator, which fans out to every node
that has subscribers for that topic.
A minimal example
Section titled “A minimal example”import { ActorSystem, Actor } from 'actor-ts';import { Cluster, ClusterOptions } from 'actor-ts/cluster';import { DistributedPubSubId, type DistributedPubSubMediator, Publish, Subscribe } from 'actor-ts/cluster';
class ChatMessage { constructor(public readonly user: string, public readonly text: string) {}}
class ChatRoom extends Actor<ChatMessage> { override onReceive(message: ChatMessage): void { this.log.info(`[chat] ${message.user}: ${message.text}`); }}
const system = ActorSystem.create('my-app');const clusterOptions = ClusterOptions.create() .withHost(host) .withPort(port) .withSeeds(seeds);const cluster = await Cluster.join(system, clusterOptions);const ps = system.extension(DistributedPubSubId);ps.start(cluster);
// Subscribe (typically in an actor's preStart):const room = system.spawnAnonymous(ChatRoom);ps.mediator.tell(new Subscribe('chat.room.general', room));
// Publish (anywhere — from any node, in or out of an actor):ps.mediator.tell(new Publish('chat.room.general', new ChatMessage('alice', 'hi')));The publish reaches every subscriber, on every node — the alice
message arrives at room regardless of which node hosted the
publisher.
The four operations
Section titled “The four operations”| Message | What |
|---|---|
Subscribe(topic, ref, replyTo?) | Register ref as a subscriber to topic. Answers replyTo (or the sender) with SubscribeAcknowledgment — or SubscribeRejected when a cap is full. |
Unsubscribe(topic, ref) | Remove ref from topic’s subscribers. |
UnsubscribeAll(ref) | Remove ref from every topic. |
Publish(topic, message, delivery?) | Send message to every subscriber of topic — or, with delivery = 'one-subscriber', to exactly one. |
Send these to ps.mediator (an ActorRef). Use ask if you
need the ack:
await ps.mediator.ask(new Subscribe('chat.room.general', room));Subscribe takes an optional third argument, replyTo, naming
where the acknowledgment or the refusal goes. Without it the
answer follows context.sender — which is empty for the
mediator.tell(…) shape above, called from outside an actor. Name
a replyTo whenever you want to see the answer:
ps.mediator.tell(new Subscribe('chat.room.general', room, room));Topics
Section titled “Topics”Topic names are arbitrary strings. The framework doesn’t
impose structure — chat.room.general, user-42.events,
metrics-tier-1 all work.
For organization, a dot-segmented convention works well
(<domain>.<scope>.<resource>), but the framework doesn’t
interpret the segments — it’s just string matching.
How fan-out works
Section titled “How fan-out works”On Publish(topic, message):
- The local mediator looks up the topic in its
Map<topic, { local, remoteNodes }>. - Local subscribers receive directly —
local.values(), each gets atell. - Remote nodes with subscribers get one envelope per node (not per subscriber) — the mediator on the destination node fans out to its locals.
This gives at-most-one-remote-hop delivery: a publish never chains through multiple nodes to reach a subscriber.
Knowing which node published
Section titled “Knowing which node published”A topic fan-out carries no sender: tell is one-way, the publisher is
usually not the interesting party, and every subscriber’s onReceive
is written against the bare body. A subscriber that has to authorise
on the publisher needs more than that, and asks for it at subscribe
time:
mediator.tell(new Subscribe('ledger', auditor, null, /* deliverWithOrigin= */ true));Every message for that subscriber then arrives as a PubSubEnvelope
instead of the bare body:
override onReceive(message: PubSubEnvelope<LedgerEntry>): void { const { topic, message: entry, origin } = message; if (origin === null) return; // no authenticated sender if (!this.mayWrite(entry.author, origin)) return; this.apply(entry);}origin is never a value out of the payload. For a message that
crossed the wire it is the connection’s peer — the identity the cluster
handshake established — and for one published on this node it is
cluster.selfAddress. null means the mediator had no authenticated
identity to attach, and a subscriber that authorises on origin must
read that as unauthenticated, not as local.
The comparison is only meaningful because of the at-most-one-hop rule above: the node a subscriber sees is the node that published, not a relay that forwarded on someone else’s behalf.
The flag belongs to the subscriber, not to the subscription — one
actor has one onReceive, so a mixture of shapes across its topics
would be a discrimination problem it could not solve. A later
Subscribe from the same actor restates the shape for all of its
topics. ReplicatedEventSourcedActor is the in-tree user: an event
envelope names its own author, and without the publishing node there is
nothing to hold that name against.
Anycast — one subscriber instead of all
Section titled “Anycast — one subscriber instead of all”A third argument switches Publish from broadcast to anycast:
exactly one subscriber, cluster-wide, receives the message.
// Every worker joins the same topic…ps.mediator.tell(new Subscribe('jobs', worker));
// …and each task is handled once, by one of them.ps.mediator.tell(new Publish('jobs', new RenderThumbnail(id), 'one-subscriber'));That is the work-queue shape: N workers spread over the cluster,
every task handled exactly once, and no worker needs to know how
many others exist. The default stays 'all-subscribers', so a
Publish written without the third argument is unchanged.
How the one is chosen. The mediator builds a candidate list — each local subscriber counts once, each remote node claiming the topic counts once — and walks it in rotation, one step per publish. Two consequences worth knowing:
- It is a rotation, not a draw. Ten tasks over three workers land 4/3/3, not “probably roughly even”. Restarting the publisher restarts the rotation; it is per-topic state on the mediator, not a cluster-wide sequence.
- The candidate order is stable. Local subscribers come first, in registration order, then the remote claimants sorted by address. Gossip arriving mid-rotation does not reshuffle the walk, and every mediator orders the remote half identically.
- Remote nodes count as one candidate each, not one per subscriber. A node with ten subscribers gets the same share as a node with one, because the gossip frame carries topic names and not subscriber counts (that is what keeps it small). Within the chosen node, its own rotation picks the subscriber. Keep worker counts roughly even across nodes if the balance matters.
- A node that both publishes and hosts workers rotates on two cursors. The anycasts it originates walk the full candidate list; the ones that reach it over the wire walk its local subscribers only. The two lists differ in length, so they are counted separately — one shared cursor would pin the originating walk below the local subscriber count and starve every remote candidate.
An anycast that finds no candidate — no local subscriber and no remote claimant — goes to dead letters like any other unrouted publish. So does one that crossed a hop and found the far node’s subscribers already gone: it is not re-routed, because a second hop would trade the at-most-one-hop guarantee for a race against the gossip round that is about to correct the sender anyway.
A frame the mediator has no handler for at all — an older node reached by a newer node’s wire kind, say — also lands in dead letters, with a warning. Rolling upgrades are the case that needs it: a silently dropped frame looks exactly like a cluster with nothing to do.
Topic→node gossip
Section titled “Topic→node gossip”The mediator keeps its Map<topic, SubscriberSet> local and gossips
only topic names: every topic this node holds at least one local
subscriber for, the full set in every frame, never a delta. The
receiver replaces that sender’s contribution wholesale. A topic
the frame no longer names is dropped for that node, so an unsubscribe
travels as an absence from the next frame. There are no tombstones,
and a node that leaves loses its claims on every peer when the cluster
announces MemberRemoved.
The periodic push runs on the mediator’s own timer and goes to
one random up peer per tick. Its interval is
actor-ts.cluster.pub-sub.gossip-interval, 1 second by default, and
it does not follow the cluster’s gossip-interval: changing one
leaves the other alone. Override it per mediator:
const distributedPubSubOptions = DistributedPubSubOptions.create().withGossipIntervalMs(500);system.extension(DistributedPubSubId).start(cluster, distributedPubSubOptions);Lower intervals → faster anti-entropy, more chatter. Subscribing,
unsubscribing and a member reaching up each broadcast right away to
every up peer and do not wait for the interval; what the interval
repairs is a frame that was dropped. Because each tick reaches one
random peer, a given peer hears a given node’s periodic push about once
every N−1 ticks in an N-node cluster, so that repair slows as the
cluster grows. 500 ms is reasonable for chat-style use cases.
When subscribers stop
Section titled “When subscribers stop”The mediator watches every local subscriber. A subscriber that
stops without sending Unsubscribe — a crash, a forgotten cleanup,
an actor spawned per request — is removed as soon as the
Terminated lands, and the topic is dropped with its last
subscriber.
Unsubscribing explicitly is still the faster path, and it is the only way to leave a topic without stopping:
class Subscriber extends Actor<...> { override preStart(): void { this.system.extension(...).mediator.tell(new Subscribe('topic', this.self)); } override postStop(): void { this.system.extension(...).mediator.tell(new UnsubscribeAll(this.self)); }}Bounded registries
Section titled “Bounded registries”The mediator holds three things that a subscriber — or a peer’s gossip — could otherwise grow without end, and publish fan-out walks all three. Each has a cap:
| Option | HOCON leaf | Default | Bounds |
|---|---|---|---|
maxSubscribersPerTopic | cluster.pub-sub.max-subscribers-per-topic | 10000 | Local subscribers on one topic |
maxTopics | cluster.pub-sub.max-topics | 10000 | Distinct topics on this mediator |
maxRemoteNodesPerTopic | cluster.pub-sub.max-remote-nodes-per-topic | 1000 | Peers claiming subscribers for one topic |
const distributedPubSubOptions = DistributedPubSubOptions.create() .withMaxSubscribersPerTopic(500) .withMaxTopics(1_000);system.extension(DistributedPubSubId).start(cluster, distributedPubSubOptions);A Subscribe over maxSubscribersPerTopic or maxTopics is
refused, not dropped — the reply is a SubscribeRejected
carrying the cap that refused it:
import { SubscribeRejected } from 'actor-ts/cluster';
// message.reason: 'maxSubscribersPerTopic' | 'maxTopics'// message.limit: the value that cap is set tomaxTopics and maxRemoteNodesPerTopic apply to gossip as
well, and that is the half worth knowing about: a peer announcing
100 000 topics it claims to have subscribers for used to allocate
100 000 entries on every receiving node, with no local Subscribe
involved anywhere. Claims over a cap are dropped and logged; the
connection stays up, because one noisy peer should not cost a
healthy link.
Publishes that reach nobody
Section titled “Publishes that reach nobody”A Publish to a topic with no local subscribers and no remote
claimants goes to system.deadLetters — as does one that crossed
a hop and found no subscriber at the far end.
system.eventStream.subscribe(monitor, DeadLetter);This is on by default. A mistyped topic name and a topic whose subscribers have not gossiped in yet look identical from the publisher’s side, and this is what tells them apart. Turn it off for a deployment where unrouted publishes are expected and the volume would be noise:
actor-ts.cluster.pub-sub.send-to-dead-letters-when-no-subscribers = offWhen to use DistributedPubSub
Section titled “When to use DistributedPubSub”Four good fits:
- Chat / notifications — multiple subscribers (often on different nodes) interested in the same topic.
- System-wide announcements — a “schema-updated” event that every node should react to.
- De-coupled fan-out across nodes — when the publisher shouldn’t know how many subscribers exist or where they live.
- Work queues over a dynamic worker set — with
'one-subscriber'delivery, workers join and leave a topic at runtime and every task is handled once.
When NOT
Section titled “When NOT”DistributedPubSub vs the event streams
Section titled “DistributedPubSub vs the event streams”Three pub/sub buses; pick by scope first, then by how a channel is named:
| Bus | Scope | Channel key |
|---|---|---|
| Event stream | One ActorSystem | Class (instanceof) or kind |
| Cluster event stream | Cluster-wide | Class (instanceof) or kind |
DistributedPubSub | Cluster-wide | String topic |
Use the event stream for in-system dispatch, and the cluster event stream when the same channels should reach every node — it is built on the mediator described above, so it is this page’s machinery with a typed façade.
Reach for DistributedPubSub directly when a topic is a string
chosen at runtime (a room id, a tenant, a device id — anything a
class or kind cannot enumerate ahead of time), or when you want
anycast: exactly one subscriber cluster-wide rather than all of
them. The event streams offer neither.
All three can coexist — many apps use more than one for different concerns.
Where to next
Section titled “Where to next”- Cluster overview — the membership underneath.
- Event stream — the single-system pub/sub for comparison.
- Refs across nodes — how the mediator’s cross-node deliveries serialize.
The DistributedPubSubMediator
API reference covers the full protocol.
