actor-ts 0.9.0

package/dist/cluster/pubsub/DistributedPubSubMediator.js

@@ -0,0 +1,240 @@
+import { match, P } from 'ts-pattern';
+import { Actor } from '../../Actor.js';
+import { DEFAULT_GOSSIP_INTERVAL_MS } from '../../util/Constants.js';
+import { MemberRemoved, MemberUp } from '../ClusterEvents.js';
+import { NodeAddress } from '../NodeAddress.js';
+import { CurrentTopics, GetTopics, Publish, Subscribe, SubscribeAck, Unsubscribe, UnsubscribeAck, UnsubscribeAll, } from './Messages.js';
+/**
+ * Well-known path at which every node hosts its DistributedPubSubMediator.
+ * Remote publishes target this path so the receiving mediator can fan out
+ * to its local subscribers.
+ */
+export function mediatorPath(systemName) {
+    return `actor-ts://${systemName}/user/pubsub-mediator`;
+}
+/**
+ * Cluster-wide publish/subscribe bus.  Every node hosts one mediator
+ * which keeps a local Map<topic, subscribers> and gossip-replicates
+ * the topic→node set so Publish can reach every subscriber with at
+ * most one remote hop.
+ *
+ * Simple delta model: each mediator periodically gossips its local
+ * topic set to one random peer.  Peers merge into their view.
+ */
+export class DistributedPubSubMediator extends Actor {
+    settings;
+    topics = new Map();
+    gossipTimer = null;
+    unsubscribeWire = null;
+    unsubscribeCluster = null;
+    version = 0;
+    constructor(settings) {
+        super();
+        this.settings = settings;
+    }
+    preStart() {
+        const cluster = this.settings.cluster;
+        this.unsubscribeWire = cluster._onWire('pubsub-gossip', (msg) => this.handleGossip(msg));
+        // Remote publishes arrive via the envelope handler, not the wire hook.
+        this.unsubscribeCluster = cluster.subscribe((evt) => match(evt)
+            .with(P.instanceOf(MemberRemoved), (e) => this.forgetNode(e.member.address))
+            .with(P.instanceOf(MemberUp), () => { this.version++; })
+            .otherwise(() => { }));
+        const interval = this.settings.gossipIntervalMs ?? DEFAULT_GOSSIP_INTERVAL_MS;
+        this.gossipTimer = this.system.scheduler.scheduleAtFixedRateFn(interval, interval, () => this.gossipTick());
+    }
+    postStop() {
+        this.unsubscribeWire?.();
+        this.unsubscribeCluster?.();
+        this.gossipTimer?.cancel();
+    }
+    onReceive(msg) {
+        match(msg)
+            .with(P.instanceOf(Subscribe), (m) => this.handleSubscribe(m))
+            .with(P.instanceOf(Unsubscribe), (m) => this.handleUnsubscribe(m))
+            .with(P.instanceOf(UnsubscribeAll), (m) => this.handleUnsubscribeAll(m))
+            .with(P.instanceOf(Publish), (m) => this.handlePublish(m))
+            .with(P.instanceOf(GetTopics), (m) => this.handleGetTopics(m))
+            // Remote Publish forwarded from another mediator (plain envelope, not a class instance).
+            .with({ t: 'pubsub-publish' }, (m) => this.deliverLocal(m.topic, m.body))
+            .otherwise(() => { });
+    }
+    /* ----------------------------- Command handlers ----------------------------- */
+    handleSubscribe(msg) {
+        const set = this.getOrCreateSet(msg.topic);
+        const key = msg.ref.path.toString();
+        let changed = false;
+        if (!set.local.has(key)) {
+            set.local.set(key, msg.ref);
+            this.version++;
+            changed = true;
+        }
+        this.log.debug(`[pubsub] subscribe '${msg.topic}' by ${key} (local subs now: ${set.local.size}; ${changed ? 'new' : 'duplicate'})`);
+        this.sender.forEach((s) => s.tell(new SubscribeAck(msg)));
+        // Eager broadcast: peers learn about the new subscription within
+        // one hop, deterministically.  Without this the random-peer-per-
+        // tick gossip leaves a probabilistic gap (~1/2^N for N ticks)
+        // where a publish-immediately-after-subscribe misses the new
+        // subscriber.  Periodic gossip continues to handle anti-entropy.
+        if (changed)
+            this.eagerGossip();
+    }
+    handleUnsubscribe(msg) {
+        const set = this.topics.get(msg.topic);
+        const key = msg.ref.path.toString();
+        let changed = false;
+        if (set?.local.delete(key)) {
+            this.version++;
+            changed = true;
+            if (set.local.size === 0 && set.remoteNodes.size === 0)
+                this.topics.delete(msg.topic);
+        }
+        this.log.debug(`[pubsub] unsubscribe '${msg.topic}' by ${key} (${changed ? 'removed' : 'not subscribed'})`);
+        this.sender.forEach((s) => s.tell(new UnsubscribeAck(msg)));
+        if (changed)
+            this.eagerGossip();
+    }
+    handleUnsubscribeAll(msg) {
+        const key = msg.ref.path.toString();
+        let changed = false;
+        for (const [topic, set] of this.topics) {
+            if (set.local.delete(key)) {
+                this.version++;
+                changed = true;
+            }
+            if (set.local.size === 0 && set.remoteNodes.size === 0)
+                this.topics.delete(topic);
+        }
+        if (changed)
+            this.eagerGossip();
+    }
+    handleGetTopics(msg) {
+        msg.replyTo.tell(new CurrentTopics(Array.from(this.topics.keys()).sort()));
+    }
+    handlePublish(msg) {
+        const set = this.topics.get(msg.topic);
+        const localCount = set?.local.size ?? 0;
+        const remoteCount = set?.remoteNodes.size ?? 0;
+        this.log.debug(`[pubsub] publish '${msg.topic}' → ${localCount} local + ${remoteCount} remote node(s)`);
+        this.deliverLocal(msg.topic, msg.message);
+        if (!set)
+            return;
+        const payload = { t: 'pubsub-publish', topic: msg.topic, body: msg.message };
+        for (const nodeStr of set.remoteNodes) {
+            const node = NodeAddress.parse(nodeStr);
+            if (node.equals(this.settings.cluster.selfAddress))
+                continue;
+            this.sendWire(node, payload);
+        }
+    }
+    deliverLocal(topic, body) {
+        const set = this.topics.get(topic);
+        if (!set)
+            return;
+        for (const ref of set.local.values()) {
+            try {
+                ref.tell(body);
+            }
+            catch (e) {
+                this.log.warn(`pubsub: subscriber ${ref} threw on delivery`, e);
+            }
+        }
+    }
+    /* --------------------------------- Gossip ---------------------------------- */
+    gossipTick() {
+        const peers = this.settings.cluster.upMembers()
+            .filter(m => !m.address.equals(this.settings.cluster.selfAddress));
+        if (peers.length === 0)
+            return;
+        const gossip = this.buildGossip();
+        // Push to one random peer — epidemic dissemination.
+        const target = peers[Math.floor(Math.random() * peers.length)];
+        this.sendWire(target.address, gossip);
+    }
+    /**
+     * Send the current subscription state to **every** peer
+     * immediately.  Used after local subscribe / unsubscribe so a
+     * follow-up publish doesn't have to wait several gossip ticks
+     * for the random-peer-per-tick scheme to reach every node.
+     * Periodic `gossipTick` continues to run as steady-state
+     * anti-entropy.
+     */
+    eagerGossip() {
+        const peers = this.settings.cluster.upMembers()
+            .filter(m => !m.address.equals(this.settings.cluster.selfAddress));
+        if (peers.length === 0)
+            return;
+        const gossip = this.buildGossip();
+        for (const peer of peers) {
+            this.sendWire(peer.address, gossip);
+        }
+    }
+    buildGossip() {
+        // Only topic names — the receiver doesn't use the per-topic
+        // subscriber lists (it only tracks "node N has at least one
+        // subscriber for topic T"), so omitting them keeps the wire
+        // payload proportional to the topic count, not the subscriber
+        // count.  See `handleGossip` for the consuming side.
+        const entries = [];
+        for (const [topic, set] of this.topics) {
+            if (set.local.size === 0)
+                continue;
+            entries.push(topic);
+        }
+        return {
+            t: 'pubsub-gossip',
+            from: this.settings.cluster.selfAddress.toJSON(),
+            entries,
+            version: this.version,
+        };
+    }
+    handleGossip(msg) {
+        const senderAddr = NodeAddress.fromJSON(msg.from).toString();
+        // First, clear any remote-node claims this sender used to have — we
+        // always replace its contribution wholesale to stay in sync.
+        for (const [topic, set] of this.topics) {
+            set.remoteNodes.delete(senderAddr);
+            if (set.local.size === 0 && set.remoteNodes.size === 0)
+                this.topics.delete(topic);
+        }
+        for (const topic of msg.entries) {
+            const set = this.getOrCreateSet(topic);
+            set.remoteNodes.add(senderAddr);
+        }
+    }
+    forgetNode(addr) {
+        const key = addr.toString();
+        for (const [topic, set] of this.topics) {
+            set.remoteNodes.delete(key);
+            if (set.local.size === 0 && set.remoteNodes.size === 0)
+                this.topics.delete(topic);
+        }
+    }
+    /* ---------------------------------- Helpers --------------------------------- */
+    getOrCreateSet(topic) {
+        let s = this.topics.get(topic);
+        if (!s) {
+            s = { local: new Map(), remoteNodes: new Set() };
+            this.topics.set(topic, s);
+        }
+        return s;
+    }
+    sendWire(to, msg) {
+        if (msg.t === 'pubsub-publish') {
+            // Wrap in envelope so the receiver's Cluster routes it into the
+            // mediator actor.  Publishes are "user" messages from the wire POV.
+            this.settings.cluster._sendEnvelope(to, {
+                t: 'envelope',
+                to: mediatorPath(this.settings.cluster.system.name),
+                from: null,
+                body: msg,
+                tag: 'PubSubPublish',
+            });
+        }
+        else {
+            // Gossip frames ride on the raw transport — they're system traffic.
+            this.settings.cluster.transport.send(to, msg);
+        }
+    }
+}
+//# sourceMappingURL=DistributedPubSubMediator.js.map

package/dist/cluster/pubsub/DistributedPubSubMediator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistributedPubSubMediator.js","sourceRoot":"","sources":["../../../src/cluster/pubsub/DistributedPubSubMediator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EACL,aAAa,EACb,SAAS,EACT,OAAO,EACP,SAAS,EACT,YAAY,EAIZ,WAAW,EACX,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,OAAO,cAAc,UAAU,uBAAuB,CAAC;AACzD,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAE9C;IAO6B;IANX,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IACnD,WAAW,GAAuB,IAAI,CAAC;IACvC,eAAe,GAAwB,IAAI,CAAC;IAC5C,kBAAkB,GAAwB,IAAI,CAAC;IAC/C,OAAO,GAAG,CAAC,CAAC;IAEpB,YAA4B,QAAmC;QAAI,KAAK,EAAE,CAAC;QAA/C,aAAQ,GAAR,QAAQ,CAA2B;IAAa,CAAC;IAEpE,QAAQ;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QACtC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,EAAE,CAC9D,IAAI,CAAC,YAAY,CAAC,GAAiC,CAAC,CACrD,CAAC;QACF,uEAAuE;QACvE,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAClD,KAAK,CAAC,GAAG,CAAC;aACP,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;aAC3E,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;aACvD,SAAS,CAAC,GAAG,EAAE,GAA8B,CAAC,CAAC,CACnD,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;QAC9E,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,qBAAqB,CAC5D,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAC5C,CAAC;IACJ,CAAC;IAEQ,QAAQ;QACf,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;QACzB,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;QAC5B,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IAEQ,SAAS,CAAC,GAAsF;QACvG,KAAK,CAAC,GAAG,CAAC;aACP,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;aACjE,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;aACvE,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;aACzD,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAC9D,yFAAyF;aACxF,IAAI,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;aACxE,SAAS,CAAC,GAAG,EAAE,GAAyB,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,kFAAkF;IAE1E,eAAe,CAAC,GAAc;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CACZ,uBAAuB,GAAG,CAAC,KAAK,QAAQ,GAAG,qBAAqB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,GAAG,CACpH,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1D,iEAAiE;QACjE,iEAAiE;QACjE,8DAA8D;QAC9D,6DAA6D;QAC7D,iEAAiE;QACjE,IAAI,OAAO;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC;IAEO,iBAAiB,CAAC,GAAgB;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CACZ,yBAAyB,GAAG,CAAC,KAAK,QAAQ,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,GAAG,CAC5F,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,OAAO;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC;IAEO,oBAAoB,CAAC,GAAmB;QAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBAAC,OAAO,GAAG,IAAI,CAAC;YAAC,CAAC;YAC9D,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,OAAO;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC;IAEO,eAAe,CAAC,GAAc;QACpC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IAEO,aAAa,CAAI,GAAe;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,UAAU,GAAG,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;QACxC,MAAM,WAAW,GAAG,GAAG,EAAE,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,KAAK,CACZ,qBAAqB,GAAG,CAAC,KAAK,OAAO,UAAU,YAAY,WAAW,iBAAiB,CACxF,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,MAAM,OAAO,GAAqB,EAAE,CAAC,EAAE,gBAAgB,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAC/F,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC;gBAAE,SAAS;YAC7D,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,YAAY,CAAI,KAAa,EAAE,IAAO;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,IAAI,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,IAAa,CAAC,CAAC;YAAC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,sBAAsB,GAAG,oBAAoB,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;IACH,CAAC;IAED,iFAAiF;IAEzE,UAAU;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE;aAC5C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,oDAAoD;QACpD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAE,CAAC;QAChE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;OAOG;IACK,WAAW;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE;aAC5C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,4DAA4D;QAC5D,4DAA4D;QAC5D,4DAA4D;QAC5D,8DAA8D;QAC9D,qDAAqD;QACrD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;gBAAE,SAAS;YACnC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO;YACL,CAAC,EAAE,eAAe;YAClB,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE;YAChD,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;IAEO,YAAY,CAAC,GAAoB;QACvC,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC7D,oEAAoE;QACpE,6DAA6D;QAC7D,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACnC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACvC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,IAAiB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED,kFAAkF;IAE1E,cAAc,CAAC,KAAa;QAClC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,WAAW,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAEO,QAAQ,CAAC,EAAe,EAAE,GAAsB;QACtD,IAAI,GAAG,CAAC,CAAC,KAAK,gBAAgB,EAAE,CAAC;YAC/B,gEAAgE;YAChE,oEAAoE;YACpE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE;gBACtC,CAAC,EAAE,UAAU;gBACb,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;gBACnD,IAAI,EAAE,IAAI;gBACV,IAAI,EAAE,GAAG;gBACT,GAAG,EAAE,eAAe;aACrB,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,oEAAoE;YACpE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,GAA6B,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;CACF"}

package/dist/cluster/pubsub/Messages.d.ts

@@ -0,0 +1,75 @@
+import type { ActorRef } from '../../ActorRef.js';
+import type { NodeAddressData } from '../NodeAddress.js';
+/** Subscribe a local actor to a topic. */
+export declare class Subscribe {
+    readonly topic: string;
+    readonly ref: ActorRef;
+    constructor(topic: string, ref: ActorRef);
+}
+/** Unsubscribe a local actor from a topic. */
+export declare class Unsubscribe {
+    readonly topic: string;
+    readonly ref: ActorRef;
+    constructor(topic: string, ref: ActorRef);
+}
+/** Remove every subscription the actor holds on this mediator. */
+export declare class UnsubscribeAll {
+    readonly ref: ActorRef;
+    constructor(ref: ActorRef);
+}
+/** Publish `message` to every subscriber of `topic` — cluster-wide. */
+export declare class Publish<T = unknown> {
+    readonly topic: string;
+    readonly message: T;
+    /** Deliver to senders/publishers themselves?  Default false. */
+    readonly sendOneMessageToEachGroup: boolean;
+    constructor(topic: string, message: T, 
+    /** Deliver to senders/publishers themselves?  Default false. */
+    sendOneMessageToEachGroup?: boolean);
+}
+/** Sent back from Subscribe/Unsubscribe when the registry has been updated. */
+export declare class SubscribeAck {
+    readonly subscribe: Subscribe;
+    constructor(subscribe: Subscribe);
+}
+export declare class UnsubscribeAck {
+    readonly unsubscribe: Unsubscribe;
+    constructor(unsubscribe: Unsubscribe);
+}
+/** Query the current per-topic subscriber counts (local + remote). */
+export declare class GetTopics {
+    readonly replyTo: ActorRef;
+    constructor(replyTo: ActorRef);
+}
+export declare class CurrentTopics {
+    readonly topics: ReadonlyArray<string>;
+    constructor(topics: ReadonlyArray<string>);
+}
+/**
+ * Incremental gossip: one node announces the set of topics it currently
+ * hosts subscribers for.  Merged into the cluster-wide registry.
+ *
+ * `entries` is a flat list of topic names — the receiver only ever
+ * needs to know **which** topics the sender has subscribers for, so
+ * the per-topic subscriber paths from earlier wire shapes were
+ * removed (#80) to keep gossip bytes proportional to the topic count
+ * rather than to total subscriber count.
+ */
+export interface PubSubGossipMsg {
+    readonly t: 'pubsub-gossip';
+    readonly from: NodeAddressData;
+    /** Topic names hosted locally on the sender. */
+    readonly entries: ReadonlyArray<string>;
+    readonly version: number;
+}
+/**
+ * Payload envelope used to forward a Publish to a remote mediator.
+ * Remote mediator decodes and fans out to its local subscribers.
+ */
+export interface PubSubPublishMsg {
+    readonly t: 'pubsub-publish';
+    readonly topic: string;
+    readonly body: unknown;
+}
+export type PubSubWireMessage = PubSubGossipMsg | PubSubPublishMsg;
+//# sourceMappingURL=Messages.d.ts.map

package/dist/cluster/pubsub/Messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Messages.d.ts","sourceRoot":"","sources":["../../../src/cluster/pubsub/Messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,0CAA0C;AAC1C,qBAAa,SAAS;aACQ,KAAK,EAAE,MAAM;aAAkB,GAAG,EAAE,QAAQ;gBAA5C,KAAK,EAAE,MAAM,EAAkB,GAAG,EAAE,QAAQ;CACzE;AAED,8CAA8C;AAC9C,qBAAa,WAAW;aACM,KAAK,EAAE,MAAM;aAAkB,GAAG,EAAE,QAAQ;gBAA5C,KAAK,EAAE,MAAM,EAAkB,GAAG,EAAE,QAAQ;CACzE;AAED,kEAAkE;AAClE,qBAAa,cAAc;aACG,GAAG,EAAE,QAAQ;gBAAb,GAAG,EAAE,QAAQ;CAC1C;AAED,uEAAuE;AACvE,qBAAa,OAAO,CAAC,CAAC,GAAG,OAAO;aAEZ,KAAK,EAAE,MAAM;aACb,OAAO,EAAE,CAAC;IAC1B,gEAAgE;aAChD,yBAAyB;gBAHzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC;IAC1B,gEAAgE;IAChD,yBAAyB,UAAQ;CAEpD;AAED,+EAA+E;AAC/E,qBAAa,YAAY;aAA+B,SAAS,EAAE,SAAS;gBAApB,SAAS,EAAE,SAAS;CAAM;AAClF,qBAAa,cAAc;aAA+B,WAAW,EAAE,WAAW;gBAAxB,WAAW,EAAE,WAAW;CAAM;AAExF,sEAAsE;AACtE,qBAAa,SAAS;aAA+B,OAAO,EAAE,QAAQ;gBAAjB,OAAO,EAAE,QAAQ;CAAM;AAC5E,qBAAa,aAAa;aAA+B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC;gBAA7B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC;CAAM;AAI5F;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,eAAe,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,gBAAgB,CAAC"}

package/dist/cluster/pubsub/Messages.js

@@ -0,0 +1,66 @@
+/* ============================ User-facing API ============================= */
+/** Subscribe a local actor to a topic. */
+export class Subscribe {
+    topic;
+    ref;
+    constructor(topic, ref) {
+        this.topic = topic;
+        this.ref = ref;
+    }
+}
+/** Unsubscribe a local actor from a topic. */
+export class Unsubscribe {
+    topic;
+    ref;
+    constructor(topic, ref) {
+        this.topic = topic;
+        this.ref = ref;
+    }
+}
+/** Remove every subscription the actor holds on this mediator. */
+export class UnsubscribeAll {
+    ref;
+    constructor(ref) {
+        this.ref = ref;
+    }
+}
+/** Publish `message` to every subscriber of `topic` — cluster-wide. */
+export class Publish {
+    topic;
+    message;
+    sendOneMessageToEachGroup;
+    constructor(topic, message, 
+    /** Deliver to senders/publishers themselves?  Default false. */
+    sendOneMessageToEachGroup = false) {
+        this.topic = topic;
+        this.message = message;
+        this.sendOneMessageToEachGroup = sendOneMessageToEachGroup;
+    }
+}
+/** Sent back from Subscribe/Unsubscribe when the registry has been updated. */
+export class SubscribeAck {
+    subscribe;
+    constructor(subscribe) {
+        this.subscribe = subscribe;
+    }
+}
+export class UnsubscribeAck {
+    unsubscribe;
+    constructor(unsubscribe) {
+        this.unsubscribe = unsubscribe;
+    }
+}
+/** Query the current per-topic subscriber counts (local + remote). */
+export class GetTopics {
+    replyTo;
+    constructor(replyTo) {
+        this.replyTo = replyTo;
+    }
+}
+export class CurrentTopics {
+    topics;
+    constructor(topics) {
+        this.topics = topics;
+    }
+}
+//# sourceMappingURL=Messages.js.map

package/dist/cluster/pubsub/Messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Messages.js","sourceRoot":"","sources":["../../../src/cluster/pubsub/Messages.ts"],"names":[],"mappings":"AAGA,gFAAgF;AAEhF,0CAA0C;AAC1C,MAAM,OAAO,SAAS;IACQ;IAA+B;IAA3D,YAA4B,KAAa,EAAkB,GAAa;QAA5C,UAAK,GAAL,KAAK,CAAQ;QAAkB,QAAG,GAAH,GAAG,CAAU;IAAG,CAAC;CAC7E;AAED,8CAA8C;AAC9C,MAAM,OAAO,WAAW;IACM;IAA+B;IAA3D,YAA4B,KAAa,EAAkB,GAAa;QAA5C,UAAK,GAAL,KAAK,CAAQ;QAAkB,QAAG,GAAH,GAAG,CAAU;IAAG,CAAC;CAC7E;AAED,kEAAkE;AAClE,MAAM,OAAO,cAAc;IACG;IAA5B,YAA4B,GAAa;QAAb,QAAG,GAAH,GAAG,CAAU;IAAG,CAAC;CAC9C;AAED,uEAAuE;AACvE,MAAM,OAAO,OAAO;IAEA;IACA;IAEA;IAJlB,YACkB,KAAa,EACb,OAAU;IAC1B,gEAAgE;IAChD,4BAA4B,KAAK;QAHjC,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAG;QAEV,8BAAyB,GAAzB,yBAAyB,CAAQ;IAChD,CAAC;CACL;AAED,+EAA+E;AAC/E,MAAM,OAAO,YAAY;IAA+B;IAA5B,YAA4B,SAAoB;QAApB,cAAS,GAAT,SAAS,CAAW;IAAG,CAAC;CAAE;AAClF,MAAM,OAAO,cAAc;IAA+B;IAA5B,YAA4B,WAAwB;QAAxB,gBAAW,GAAX,WAAW,CAAa;IAAG,CAAC;CAAE;AAExF,sEAAsE;AACtE,MAAM,OAAO,SAAS;IAA+B;IAA5B,YAA4B,OAAiB;QAAjB,YAAO,GAAP,OAAO,CAAU;IAAG,CAAC;CAAE;AAC5E,MAAM,OAAO,aAAa;IAA+B;IAA5B,YAA4B,MAA6B;QAA7B,WAAM,GAAN,MAAM,CAAuB;IAAG,CAAC;CAAE"}

package/dist/cluster/pubsub/index.d.ts

@@ -0,0 +1,5 @@
+export { DistributedPubSub, DistributedPubSubId, } from './DistributedPubSubExtension.js';
+export { DistributedPubSubMediator, mediatorPath, } from './DistributedPubSubMediator.js';
+export type { DistributedPubSubSettings } from './DistributedPubSubMediator.js';
+export { CurrentTopics, GetTopics, Publish, Subscribe, SubscribeAck, Unsubscribe, UnsubscribeAck, UnsubscribeAll, } from './Messages.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cluster/pubsub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cluster/pubsub/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,yBAAyB,EACzB,YAAY,GACb,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EACL,aAAa,EACb,SAAS,EACT,OAAO,EACP,SAAS,EACT,YAAY,EACZ,WAAW,EACX,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/cluster/pubsub/index.js

@@ -0,0 +1,4 @@
+export { DistributedPubSub, DistributedPubSubId, } from './DistributedPubSubExtension.js';
+export { DistributedPubSubMediator, mediatorPath, } from './DistributedPubSubMediator.js';
+export { CurrentTopics, GetTopics, Publish, Subscribe, SubscribeAck, Unsubscribe, UnsubscribeAck, UnsubscribeAll, } from './Messages.js';
+//# sourceMappingURL=index.js.map

package/dist/cluster/pubsub/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cluster/pubsub/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,yBAAyB,EACzB,YAAY,GACb,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,aAAa,EACb,SAAS,EACT,OAAO,EACP,SAAS,EACT,YAAY,EACZ,WAAW,EACX,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/cluster/router/ClusterRouter.d.ts

@@ -0,0 +1,87 @@
+import { Props } from '../../Props.js';
+import { Broadcast } from '../../Router.js';
+import type { Cluster } from '../Cluster.js';
+/**
+ * Cluster-aware router — routees are derived dynamically from the
+ * cluster's up-members (optionally filtered by role) and rebuilt
+ * automatically when members come and go.  The standard local
+ * `Router` strategies (round-robin / random / broadcast) get a
+ * `consistent-hashing` sibling that pins messages with the same
+ * extracted key to the same node.
+ *
+ *   const router = system.spawn(
+ *     ClusterRouter.props({
+ *       cluster,
+ *       role: 'compute',                              // optional role filter
+ *       routerType: 'consistent-hashing',
+ *       routeePath: '/user/worker',
+ *       extractKey: (msg) => (msg as { id: string }).id,
+ *     }),
+ *     'compute-router',
+ *   );
+ *   router.tell({ id: 'order-42', op: 'price' });
+ *
+ * **Routees.**  Every up-member matching `role` (or every up-member
+ * if no role is given) is materialised as a `RemoteActorRef` pointing
+ * at `routeePath`.  Self-routing goes through the same `RemoteActorRef`
+ * — the cluster transport handles loopback, so behaviour is identical
+ * to a remote routee.  Order is deterministic (`upMembers()` sorts by
+ * address), so round-robin counters stay sane across rebuilds.
+ *
+ * **Empty set.**  If no member matches the role (or the cluster is
+ * empty), messages are dropped with a warn-level log.  The router
+ * deliberately doesn't queue while waiting for routees, since that
+ * would silently grow unbounded.
+ *
+ * **Rebuild trigger.**  Subscribes to `cluster.subscribe(...)` and
+ * rebuilds on `MemberUp` / `MemberRemoved`.  Other events
+ * (`MemberJoined`, `MemberWeaklyUp`, `MemberUnreachable`) are ignored
+ * because the router only sends to fully-up members.
+ *
+ * **Out of scope (v1).**
+ *   - `smallest-mailbox` cluster variant — would require pull-based
+ *     mailbox-size queries per routee per message.  File a separate
+ *     issue if the need arises.
+ *   - Routee groups across multiple paths (`/user/a`, `/user/b` mixed)
+ *     — current API supports a single `routeePath`.
+ */
+/** What a `ClusterRouter` does with each incoming message. */
+export type ClusterRouterType = 
+/** One routee per message, cycling through the pool. */
+'round-robin'
+/** One routee per message, picked uniformly at random. */
+ | 'random'
+/** One routee per message; same `extractKey` always lands on same routee. */
+ | 'consistent-hashing'
+/** Every routee gets every message (equivalent to wrapping in `Broadcast`). */
+ | 'broadcast';
+export interface ClusterRouterOptions<TMsg> {
+    /** The cluster the router lives in.  Used for membership + transport. */
+    readonly cluster: Cluster;
+    /** Restrict routees to up-members carrying this role.  Omit for "any node". */
+    readonly role?: string;
+    /** Strategy.  See {@link ClusterRouterType}. */
+    readonly routerType: ClusterRouterType;
+    /**
+     * The path the routee actor lives under on each routee node — usually
+     * `/user/<actorName>`.  The same path must exist on every targeted
+     * node; the router doesn't probe for liveness beyond the cluster
+     * membership state.
+     */
+    readonly routeePath: string;
+    /**
+     * Required for `routerType: 'consistent-hashing'`, ignored otherwise.
+     * Returns the string key used to pin a message to a routee.  Two
+     * messages with the same key always land on the same node (subject
+     * to the cluster topology not changing).
+     */
+    readonly extractKey?: (message: TMsg) => string;
+}
+/**
+ * `Props` factory for the cluster router.  See {@link ClusterRouterOptions}
+ * for the configuration shape.
+ */
+export declare const ClusterRouter: {
+    props<TMsg>(opts: ClusterRouterOptions<TMsg>): Props<TMsg | Broadcast<TMsg>>;
+};
+//# sourceMappingURL=ClusterRouter.d.ts.map

package/dist/cluster/router/ClusterRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterRouter.d.ts","sourceRoot":"","sources":["../../../src/cluster/router/ClusterRouter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB;AAC3B,wDAAwD;AACtD,aAAa;AACf,0DAA0D;GACxD,QAAQ;AACV,6EAA6E;GAC3E,oBAAoB;AACtB,+EAA+E;GAC7E,WAAW,CAAC;AAEhB,MAAM,WAAW,oBAAoB,CAAC,IAAI;IACxC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,MAAM,CAAC;CACjD;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa;UAClB,IAAI,QAAQ,oBAAoB,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;CAU7E,CAAC"}

package/dist/cluster/router/ClusterRouter.js

@@ -0,0 +1,116 @@
+import { Actor } from '../../Actor.js';
+import { Props } from '../../Props.js';
+import { Broadcast } from '../../Router.js';
+import { MemberRemoved, MemberUp } from '../ClusterEvents.js';
+import { RemoteActorRef } from '../RemoteActorRef.js';
+import { pickRendezvous } from './ConsistentHashing.js';
+/**
+ * `Props` factory for the cluster router.  See {@link ClusterRouterOptions}
+ * for the configuration shape.
+ */
+export const ClusterRouter = {
+    props(opts) {
+        if (opts.routerType === 'consistent-hashing' && !opts.extractKey) {
+            throw new Error('ClusterRouter: routerType=\'consistent-hashing\' requires extractKey');
+        }
+        return Props.create(() => new ClusterRouterActor(opts));
+    },
+};
+/**
+ * Materialise the full wire-path for a routee.  `routeePath` is given
+ * as the user-friendly relative form (`'/user/worker'`); the cluster
+ * envelope dispatcher (`Cluster.handleEnvelope`) parses paths via
+ * `parsePathSegments`, which requires the full `actor-ts://system/...`
+ * shape.  We build it per-member because the system name lives on the
+ * target node — although in practice every node in a cluster shares
+ * the same `systemName`, doing it this way removes the assumption.
+ */
+function fullPath(systemName, routeePath) {
+    const trimmed = routeePath.replace(/^\/+/, '');
+    return `actor-ts://${systemName}/${trimmed}`;
+}
+class ClusterRouterActor extends Actor {
+    opts;
+    routees = [];
+    counter = 0;
+    unsubscribe = null;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    preStart() {
+        this.rebuildRoutees();
+        this.unsubscribe = this.opts.cluster.subscribe((evt) => {
+            // Only `up` and `removed` change the routee set.  `joined`,
+            // `weakly-up`, `unreachable` are intermediate states we don't
+            // route to.  Replay-on-subscribe (Cluster fires every current
+            // member as a series of MemberJoined/MemberUp on subscribe) is
+            // already handled by the initial rebuild — but firing here too
+            // is harmless (rebuild is idempotent).
+            if (evt instanceof MemberUp || evt instanceof MemberRemoved) {
+                this.rebuildRoutees();
+            }
+        });
+    }
+    postStop() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.routees = [];
+    }
+    onReceive(message) {
+        const sender = this.sender.toNullable();
+        if (message instanceof Broadcast) {
+            for (const r of this.routees)
+                r.tell(message.message, sender);
+            return;
+        }
+        if (this.routees.length === 0) {
+            this.log.warn('ClusterRouter: no routees match — dropping message', {
+                role: this.opts.role,
+                routeePath: this.opts.routeePath,
+            });
+            return;
+        }
+        if (this.opts.routerType === 'broadcast') {
+            for (const r of this.routees)
+                r.tell(message, sender);
+            return;
+        }
+        const target = this.pickRoutee(message);
+        target.tell(message, sender);
+    }
+    /** Visible to subclasses / tests for inspecting the live routee list. */
+    get currentRoutees() {
+        return this.routees;
+    }
+    /* ----------------------------- internals ------------------------------ */
+    rebuildRoutees() {
+        const members = this.opts.role
+            ? this.opts.cluster.upMembersWithRole(this.opts.role)
+            : this.opts.cluster.upMembers();
+        // upMembers() already sorts by address, but spell it out for clarity
+        // — round-robin across rebuilds depends on a stable order.
+        const sorted = [...members].sort((a, b) => a.address.compareTo(b.address));
+        this.routees = sorted.map((m) => new RemoteActorRef(m.address, fullPath(m.address.systemName, this.opts.routeePath), this.opts.cluster));
+    }
+    pickRoutee(message) {
+        switch (this.opts.routerType) {
+            case 'round-robin': {
+                const idx = this.counter++ % this.routees.length;
+                return this.routees[idx];
+            }
+            case 'random': {
+                return this.routees[Math.floor(Math.random() * this.routees.length)];
+            }
+            case 'consistent-hashing': {
+                const key = this.opts.extractKey(message);
+                return pickRendezvous(key, this.routees, (r) => r.targetNode.toString());
+            }
+            case 'broadcast': {
+                // Unreachable here — `onReceive` short-circuits broadcast.
+                return this.routees[0];
+            }
+        }
+    }
+}
+//# sourceMappingURL=ClusterRouter.js.map

package/dist/cluster/router/ClusterRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterRouter.js","sourceRoot":"","sources":["../../../src/cluster/router/ClusterRouter.ts"],"names":[],"mappings":"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"}