@einaraglen/quorum 1.0.0 → 1.0.3

package/README.md

@@ -18,13 +18,13 @@ When a pod starts up it runs an election: it contacts every peer with a higher n
 
 All coordination travels over a single internal HTTP port (default `4001`). Each pod runs a small Express server on that port with five endpoints:
 
-| Route | Purpose |
-|---|---|
-| `GET /health` | Heartbeat probe |
-| `POST /bully/election` | Incoming election challenge from a lower peer |
-| `POST /bully/coordinator` | Incoming leader announcement |
-| `POST /bully/message` | Incoming application-level event |
-| `GET /channel/stream/:event` | SSE stream for live subscriptions |
+| Route                        | Purpose                                       |
+| ---------------------------- | --------------------------------------------- |
+| `GET /health`                | Heartbeat probe                               |
+| `POST /bully/election`       | Incoming election challenge from a lower peer |
+| `POST /bully/coordinator`    | Incoming leader announcement                  |
+| `POST /bully/message`        | Incoming application-level event              |
+| `GET /channel/stream/:event` | SSE stream for live subscriptions             |
 
 The Transport class owns both sides of this: the server that listens on those routes, and the HTTP client (`postToPeer`, `pingPeer`) that sends to them.
 
@@ -32,12 +32,12 @@ The Transport class owns both sides of this: the server that listens on those ro
 
 Four messaging patterns are available, each with a different routing model:
 
-| Method | Who can call | Who receives |
-|---|---|---|
-| `broadcast(event, payload)` | Leader only | All followers + self |
-| `send(event, payload)` | Any follower | Current leader |
-| `tell(peer, event, payload)` | Leader only | One specific named peer |
-| `messagePeer(peer, event, payload)` | Anyone | One specific named peer |
+| Method                              | Who can call | Who receives            |
+| ----------------------------------- | ------------ | ----------------------- |
+| `broadcast(event, payload)`         | Leader only  | All followers + self    |
+| `send(event, payload)`              | Any follower | Current leader          |
+| `tell(peer, event, payload)`        | Leader only  | One specific named peer |
+| `messagePeer(peer, event, payload)` | Anyone       | One specific named peer |
 
 All four deliver to the pod's local `channel` EventEmitter when the target happens to be self, with no network round-trip.
 
@@ -45,7 +45,7 @@ All four deliver to the pod's local `channel` EventEmitter when the target happe
 
 `subscribeToPeer(peer, event, onData)` opens a live SSE connection to a named peer and delivers every event it emits under that name. Returns an unsubscribe function. Targets itself locally — no loopback HTTP connection.
 
-### ShardManager — work distribution
+### Sharding — work distribution
 
 The leader periodically reconciles who owns what. Reconciliation works in four steps:
 
@@ -60,20 +60,20 @@ Ownership changes drive subscriptions: `subscribe(id, onEvent)` listens to the c
 
 ### Quorum — the wrapper
 
-`Quorum` creates and wires all three layers (Transport, Bully, Forum, ShardManager) from a single options object. It is the primary entry point for production use. The individual classes are exported for testing and advanced composition.
+`Quorum` creates and wires all four layers (Transport, Bully, Forum, Sharding) from a single options object. It is the primary entry point for production use. The individual classes are exported for testing and advanced composition.
 
 ---
 
 ## Quick start
 
 ```typescript
-import { Quorum } from "quorum";
-import { getCluster } from "./my-discovery.js"; // returns { self, cluster }
+import { Quorum } from "@einaraglen/quorum";
+import { discovery } from "./my-discovery.js"; // returns { self, cluster }
 
 const q = new Quorum({
-  getCluster,
+  discovery,
   ids: ["uuid-1", "uuid-2", "uuid-3"], // the full set of work items to distribute
-  expectedClusterSize: 4,              // enables quorum protection
+  expectedClusterSize: 4, // enables quorum protection
 });
 
 q.start(); // starts the HTTP server, runs the first election, begins reconciling
@@ -89,6 +89,10 @@ q.publish("uuid-1", { reading: 42 });
 // Look up who owns an id without a network call:
 console.log(q.getOwner("uuid-1")); // "pod-name-c"
 
+// React the instant this pod gains or loses ids — no polling getHeldIds():
+q.onAssigned((ids) => console.log("now holding:", ids));
+q.onReleased((ids) => console.log("no longer holding:", ids));
+
 // Clean shutdown (or use `using q = new Quorum(...)` for automatic teardown):
 q.stop();
 ```
@@ -97,7 +101,7 @@ q.stop();
 
 ```typescript
 async function main() {
-  using q = new Quorum({ getCluster, ids });
+  using q = new Quorum({ discovery, ids });
   q.start();
 
   await new Promise<void>((resolve) => {
@@ -114,22 +118,22 @@ async function main() {
 
 ### `new Quorum(opts)`
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `getCluster` | `() => Promise<{ self, cluster }>` | required | Peer discovery. Return this pod as `self` and the full peer list (including self) as `cluster`. |
-| `ids` | `TId[]` | required | The complete set of work IDs to distribute. |
-| `fetchFn` | `typeof fetch` | `globalThis.fetch` | Swap in a custom fetch for testing. |
-| `internalPort` | `number` | `4001` or `$INTERNAL_PORT` | Port for the internal coordination server. |
-| `internalHost` | `string` | all interfaces | Bind address for the internal server. Useful in tests running multiple real instances on one machine. |
-| `requestTimeoutMs` | `number` | `2000` | Timeout for outgoing HTTP requests to peers. |
-| `coordinatorWaitMs` | `number` | `4000` | How long a pod waits for a coordinator announcement before restarting the election. |
-| `heartbeatIntervalMs` | `number` | `5000` | How often followers ping the leader to check it is still alive. |
-| `reportTimeoutMs` | `number` | `2000` | How long the leader waits for holdings reports before reconciling with whoever responded. |
-| `rebalanceIntervalMs` | `number` | `10000` | How often the leader runs a full reconcile. |
-| `expectedClusterSize` | `number` | none | Target pod count for quorum checks. |
-| `quorumFailureThreshold` | `number` | `3` | Consecutive quorum failures before `onSustainedQuorumLoss` fires. |
-| `onSustainedQuorumLoss` | `() => void` | `process.exit(1)` | Called once when the failure threshold is reached. |
-| `logger` | `Logger` | `console` | Log sink, must implement `info`/`warn`/`error`/`debug`. `console` satisfies this as-is. |
+| Option                   | Type                               | Default                    | Description                                                                                           |
+| ------------------------ | ---------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `discovery`              | `() => Promise<{ self, cluster }>` | required                   | Peer discovery. Return this pod as `self` and the full peer list (including self) as `cluster`.       |
+| `ids`                    | `TId[]`                            | required                   | The complete set of work IDs to distribute.                                                           |
+| `fetchFn`                | `typeof fetch`                     | `globalThis.fetch`         | Swap in a custom fetch for testing.                                                                   |
+| `internalPort`           | `number`                           | `4001` or `$INTERNAL_PORT` | Port for the internal coordination server.                                                            |
+| `internalHost`           | `string`                           | all interfaces             | Bind address for the internal server. Useful in tests running multiple real instances on one machine. |
+| `requestTimeoutMs`       | `number`                           | `2000`                     | Timeout for outgoing HTTP requests to peers.                                                          |
+| `coordinatorWaitMs`      | `number`                           | `4000`                     | How long a pod waits for a coordinator announcement before restarting the election.                   |
+| `heartbeatIntervalMs`    | `number`                           | `5000`                     | How often followers ping the leader to check it is still alive.                                       |
+| `reportTimeoutMs`        | `number`                           | `2000`                     | How long the leader waits for holdings reports before reconciling with whoever responded.             |
+| `rebalanceIntervalMs`    | `number`                           | `10000`                    | How often the leader runs a full reconcile.                                                           |
+| `expectedClusterSize`    | `number`                           | none                       | Target pod count for quorum checks.                                                                   |
+| `quorumFailureThreshold` | `number`                           | `3`                        | Consecutive quorum failures before `onSustainedQuorumLoss` fires.                                     |
+| `onSustainedQuorumLoss`  | `() => void`                       | `process.exit(1)`          | Called once when the failure threshold is reached.                                                    |
+| `logger`                 | `Logger`                           | `console`                  | Log sink, must implement `info`/`warn`/`error`/`debug`. `console` satisfies this as-is.               |
 
 **Methods:**
 
@@ -146,6 +150,9 @@ q.getOwner(id): string | undefined     // local lookup — no network call
 q.getOwnership(): Map<TId, string>     // full id→peer map as of last reconcile
 q.getHeldIds(): TId[]                  // ids currently assigned to this pod
 q.updateIds(ids): Promise<void>        // leader-only: replace the full id set and reconcile
+
+q.onAssigned(onEvent): () => void      // fires with the ids just gained when held ids grow
+q.onReleased(onEvent): () => void      // fires with the ids just lost when held ids shrink
 ```
 
 ---
@@ -155,12 +162,12 @@ q.updateIds(ids): Promise<void>        // leader-only: replace the full id set a
 For testing or custom wiring you can create the layers individually:
 
 ```typescript
-import { Transport, Bully, Forum, ShardManager } from "quorum";
+import { Transport, Bully, Forum, Sharding } from "@einaraglen/quorum";
 
 const transport = new Transport({ fetchFn: mockFetch, internalPort: 9000 });
-const bully = new Bully({ getCluster, transport });
-const forum = new Forum({ bully, transport, getCluster });
-const shard = new ShardManager({ bully, forum, ids: [] });
+const bully = new Bully({ discovery, transport });
+const forum = new Forum({ bully, transport, discovery });
+const shard = new Sharding({ bully, forum, ids: [] });
 
 // Wire the transport callbacks manually:
 transport.start({
@@ -183,12 +190,15 @@ await bully.startElection();
 bully.channel.emit("assign-connections", [7, 12, 44]);
 
 // Simulate the leader publishing an updated ownership map:
-bully.channel.emit("ownership-map", [[7, "pod-c"], [12, "pod-a"]]);
+bully.channel.emit("ownership-map", [
+  [7, "pod-c"],
+  [12, "pod-a"],
+]);
 ```
 
 ### Lifecycle events
 
-`bully.lifecycle` emits `"elected"` when this pod becomes leader (after peers have been notified), and `"demoted"` when it steps down. ShardManager uses these internally; you can also listen directly:
+`bully.lifecycle` emits `"elected"` when this pod becomes leader (after peers have been notified), and `"demoted"` when it steps down. Sharding uses these internally; you can also listen directly:
 
 ```typescript
 bully.lifecycle.on("elected", () => {
@@ -199,11 +209,22 @@ bully.lifecycle.on("demoted", () => {
 });
 ```
 
+`shard.lifecycle` similarly emits `"assigned"` and `"released"`, each with the delta of ids that just changed (not the full held set) — this is what `Quorum.onAssigned`/`onReleased` wrap:
+
+```typescript
+shard.lifecycle.on("assigned", (ids) => {
+  console.log("now holding:", ids);
+});
+shard.lifecycle.on("released", (ids) => {
+  console.log("no longer holding:", ids);
+});
+```
+
 ---
 
 ## Peer discovery
 
-`getCluster` is the only application-specific piece. It must return:
+`discovery` is the only application-specific piece. It must return:
 
 ```typescript
 {
@@ -216,7 +237,7 @@ bully.lifecycle.on("demoted", () => {
 
 ```typescript
 // In your application layer (not in quorum itself):
-const getCluster = async () => {
+const discovery = async () => {
   const pods = await k8s.listNamespacedPod({
     namespace: "default",
     labelSelector: "app=my-service",
@@ -255,5 +276,5 @@ src/
 Every class (and `Quorum` itself) accepts an optional `logger` implementing `info`/`warn`/`error`/`debug` — `console` satisfies this shape as-is and is the default. Pass your own (winston, pino, a wrapper around your APM, etc.) to route quorum's election/reconcile/messaging logs wherever the rest of your app's logs go:
 
 ```typescript
-const q = new Quorum({ getCluster, ids, logger: myWinstonLogger });
+const q = new Quorum({ discovery, ids, logger: myWinstonLogger });
 ```

package/dist/core/bully.d.ts

@@ -0,0 +1,56 @@
+import { EventEmitter } from "events";
+import type { Logger } from "./logger";
+import type { Transport } from "./transport";
+export type BullyPeer = {
+    name?: string;
+    host?: string;
+};
+export type BullyCluster = {
+    self: BullyPeer;
+    cluster: BullyPeer[];
+};
+export type Discovery = () => Promise<BullyCluster>;
+export type BullyOptions = {
+    discovery: Discovery;
+    transport: Transport;
+    coordinatorWaitMs?: number;
+    heartbeatIntervalMs?: number;
+    logger?: Logger;
+};
+export declare class Bully implements Disposable {
+    readonly lifecycle: EventEmitter<[never]>;
+    readonly channel: EventEmitter<[never]>;
+    private readonly discovery;
+    private readonly transport;
+    private readonly coordinatorWaitMs;
+    private readonly heartbeatIntervalMs;
+    private readonly logger;
+    private selfId?;
+    private leaderId?;
+    private electionInFlight;
+    private coordinatorWaitTimeout?;
+    private heartbeatInterval?;
+    constructor(opts: BullyOptions);
+    isLeader(): boolean;
+    getStatus(): {
+        self: string | undefined;
+        leader: string | undefined;
+        isLeader: boolean;
+    };
+    getPodRoles(): Promise<{
+        name: string | undefined;
+        host: string | undefined;
+        role: string;
+    }[]>;
+    /** Returns all cluster peers except self. Side-effect: populates selfId. */
+    getPeers(): Promise<BullyPeer[]>;
+    private becomeLeader;
+    startElection(): Promise<void>;
+    onElectionMessage(fromId: string): void;
+    onCoordinatorMessage(id: string): void;
+    onMessage(event: string, payload: unknown): void;
+    start(): void;
+    stop(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=bully.d.ts.map

package/dist/core/bully.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bully.d.ts","sourceRoot":"","sources":["../../src/core/bully.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAM,YAAW,UAAU;IACtC,SAAgB,SAAS,wBAAsB;IAC/C,SAAgB,OAAO,wBAAsB;IAE7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,sBAAsB,CAAC,CAAiB;IAChD,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAE3C,YAAY,IAAI,EAAE,YAAY,EAM7B;IAEM,QAAQ,IAAI,OAAO,CAEzB;IAEM,SAAS;QACL,IAAI;QAAe,MAAM;QAAiB,QAAQ;MAC5D;IAEY,WAAW;;;;SAOvB;IAED,4EAA4E;IAC/D,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAI5C;YAEa,YAAY;IAeb,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAkC1C;IAEM,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG7C;IAEM,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAa5C;IAEM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;IAEM,KAAK,IAAI,IAAI,CAuBnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}

package/dist/core/bully.js

@@ -0,0 +1,140 @@
+import { EventEmitter } from "events";
+export class Bully {
+    lifecycle = new EventEmitter();
+    channel = new EventEmitter();
+    discovery;
+    transport;
+    coordinatorWaitMs;
+    heartbeatIntervalMs;
+    logger;
+    selfId;
+    leaderId;
+    electionInFlight = false;
+    coordinatorWaitTimeout;
+    heartbeatInterval;
+    constructor(opts) {
+        this.discovery = opts.discovery;
+        this.transport = opts.transport;
+        this.coordinatorWaitMs = opts.coordinatorWaitMs ?? 4000;
+        this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 5000;
+        this.logger = opts.logger ?? console;
+    }
+    isLeader() {
+        return !!this.selfId && this.selfId === this.leaderId;
+    }
+    getStatus() {
+        return { self: this.selfId, leader: this.leaderId, isLeader: this.isLeader() };
+    }
+    async getPodRoles() {
+        const { cluster } = await this.discovery();
+        return cluster.map((pod) => ({
+            name: pod.name,
+            host: pod.host,
+            role: pod.name === this.leaderId ? "leader" : "follower",
+        }));
+    }
+    /** Returns all cluster peers except self. Side-effect: populates selfId. */
+    async getPeers() {
+        const { self, cluster } = await this.discovery();
+        this.selfId = self.name;
+        return cluster.filter((pod) => pod.name !== self.name && pod.host);
+    }
+    async becomeLeader(peers) {
+        const wasLeader = this.leaderId === this.selfId;
+        this.leaderId = this.selfId;
+        if (!wasLeader)
+            this.logger.info(`Became leader (id=${this.selfId})`);
+        await Promise.all(peers.map((peer) => this.transport.postToPeer(peer.host, "/bully/coordinator", { id: this.selfId })));
+        // Emitted only after peers have been told, so an "elected" listener that immediately talks
+        // to peers (e.g. Sharding.reconcile()) doesn't race ahead of them learning who's leader.
+        if (!wasLeader)
+            this.lifecycle.emit("elected");
+    }
+    async startElection() {
+        if (this.electionInFlight)
+            return;
+        this.electionInFlight = true;
+        if (this.coordinatorWaitTimeout)
+            clearTimeout(this.coordinatorWaitTimeout);
+        this.logger.info("Starting election");
+        try {
+            const peers = await this.getPeers();
+            const higherPeers = peers.filter((peer) => peer.name > this.selfId);
+            if (higherPeers.length === 0) {
+                await this.becomeLeader(peers);
+                return;
+            }
+            const acked = await Promise.all(higherPeers.map((peer) => this.transport.postToPeer(peer.host, "/bully/election", { id: this.selfId })));
+            if (acked.some(Boolean)) {
+                this.logger.debug("Higher peer(s) acknowledged, waiting for coordinator announcement");
+                this.coordinatorWaitTimeout = setTimeout(() => {
+                    this.logger.debug("Timed out waiting for coordinator, restarting election");
+                    this.startElection();
+                }, this.coordinatorWaitMs);
+            }
+            else {
+                await this.becomeLeader(peers);
+            }
+        }
+        catch (err) {
+            this.logger.error(`Election error: ${err.message}`);
+        }
+        finally {
+            this.electionInFlight = false;
+        }
+    }
+    onElectionMessage(fromId) {
+        this.logger.debug(`Received election message from ${fromId}, asserting alive and starting own election`);
+        this.startElection();
+    }
+    onCoordinatorMessage(id) {
+        if (this.coordinatorWaitTimeout)
+            clearTimeout(this.coordinatorWaitTimeout);
+        const wasLeader = this.isLeader();
+        const changed = this.leaderId !== id;
+        this.leaderId = id;
+        if (changed)
+            this.logger.debug(`New leader announced: ${id}`);
+        if (wasLeader && id !== this.selfId) {
+            this.logger.info("Demoted to follower");
+            this.lifecycle.emit("demoted");
+        }
+    }
+    onMessage(event, payload) {
+        this.channel.emit(event, payload);
+    }
+    start() {
+        this.heartbeatInterval = setInterval(async () => {
+            try {
+                if (this.electionInFlight)
+                    return;
+                if (this.leaderId && this.leaderId === this.selfId)
+                    return;
+                if (!this.leaderId) {
+                    this.startElection();
+                    return;
+                }
+                const peers = await this.getPeers();
+                const leader = peers.find((peer) => peer.name === this.leaderId);
+                if (!leader?.host || !(await this.transport.pingPeer(leader.host))) {
+                    this.logger.info(`Leader ${this.leaderId} unreachable, starting election`);
+                    this.leaderId = undefined;
+                    this.startElection();
+                }
+            }
+            catch (err) {
+                this.logger.error(`Heartbeat error: ${err.message}`);
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    stop() {
+        this.logger.info("Stopping Bully Coordinator...");
+        if (this.heartbeatInterval)
+            clearInterval(this.heartbeatInterval);
+        if (this.coordinatorWaitTimeout)
+            clearTimeout(this.coordinatorWaitTimeout);
+    }
+    [Symbol.dispose]() {
+        this.stop();
+    }
+}

package/dist/core/forum.d.ts

@@ -0,0 +1,41 @@
+import type { Logger } from "./logger";
+import type { Bully, BullyPeer, Discovery } from "./bully";
+import type { Transport } from "./transport";
+export type ForumOptions = {
+    bully: Bully;
+    transport: Transport;
+    discovery: Discovery;
+    fetchFn?: typeof fetch;
+    logger?: Logger;
+};
+export declare class Forum {
+    private readonly bully;
+    private readonly transport;
+    private readonly discovery;
+    private readonly fetchFn;
+    private readonly logger;
+    constructor(opts: ForumOptions);
+    /** Leader-only: fan a custom event out to every follower, and fire it locally too. */
+    broadcast(event: string, payload?: unknown): Promise<void>;
+    /** Follower-only: send a custom event to whichever pod is currently leader. */
+    send(event: string, payload?: unknown): Promise<void>;
+    /** Leader-only: send a custom event to exactly one named peer (self included). */
+    tell(peerName: string, event: string, payload?: unknown): Promise<void>;
+    /**
+     * Peer-to-peer: message one specific named peer directly (self included), regardless of
+     * leadership. Unlike broadcast/send/tell, this isn't leader-mediated.
+     */
+    messagePeer(peerName: string, event: string, payload?: unknown): Promise<void>;
+    /**
+     * Leader-only: partition work across the whole cluster (self included). `resolvePayload` is
+     * called once per participant, in a stable order, and gets back that pod's own share to send.
+     */
+    distribute<T>(event: string, resolvePayload: (peer: BullyPeer, index: number, allPeers: BullyPeer[]) => T): Promise<void>;
+    /**
+     * Peer-to-peer: open a live subscription to everything a specific peer emits under one
+     * channel event name (self included, via a local listener — no loopback HTTP call needed).
+     * Returns an unsubscribe function.
+     */
+    subscribeToPeer(peerName: string, event: string, onData: (payload: unknown) => void): () => void;
+}
+//# sourceMappingURL=forum.d.ts.map

package/dist/core/forum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forum.d.ts","sourceRoot":"","sources":["../../src/core/forum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,IAAI,EAAE,YAAY,EAM7B;IAED,sFAAsF;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtE;IAED,+EAA+E;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE;IAED,kFAAkF;IACrE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;IAED;;;OAGG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1F;IAED;;;OAGG;IACU,UAAU,CAAC,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,GAC3E,OAAO,CAAC,IAAI,CAAC,CAoBf;IAED;;;;OAIG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA+DtG;CACF"}

package/dist/core/forum.js

@@ -0,0 +1,152 @@
+export class Forum {
+    bully;
+    transport;
+    discovery;
+    fetchFn;
+    logger;
+    constructor(opts) {
+        this.bully = opts.bully;
+        this.transport = opts.transport;
+        this.discovery = opts.discovery;
+        this.fetchFn = opts.fetchFn ?? this.transport.fetchFn;
+        this.logger = opts.logger ?? console;
+    }
+    /** Leader-only: fan a custom event out to every follower, and fire it locally too. */
+    async broadcast(event, payload) {
+        if (!this.bully.isLeader()) {
+            this.logger.warn(`broadcast('${event}') called while not leader, ignoring`);
+            return;
+        }
+        this.bully.channel.emit(event, payload);
+        const peers = await this.bully.getPeers();
+        await Promise.all(peers.map((peer) => this.transport.postToPeer(peer.host, "/bully/message", { event, payload })));
+    }
+    /** Follower-only: send a custom event to whichever pod is currently leader. */
+    async send(event, payload) {
+        if (this.bully.isLeader()) {
+            this.bully.channel.emit(event, payload);
+            return;
+        }
+        const { leader } = this.bully.getStatus();
+        if (!leader) {
+            this.logger.warn(`send('${event}') called with no known leader, dropping`);
+            return;
+        }
+        const peers = await this.bully.getPeers();
+        const leaderPeer = peers.find((peer) => peer.name === leader);
+        if (!leaderPeer?.host) {
+            this.logger.warn(`send('${event}') could not resolve leader host, dropping`);
+            return;
+        }
+        await this.transport.postToPeer(leaderPeer.host, "/bully/message", { event, payload });
+    }
+    /** Leader-only: send a custom event to exactly one named peer (self included). */
+    async tell(peerName, event, payload) {
+        if (!this.bully.isLeader()) {
+            this.logger.warn(`tell('${event}') called while not leader, ignoring`);
+            return;
+        }
+        await this.messagePeer(peerName, event, payload);
+    }
+    /**
+     * Peer-to-peer: message one specific named peer directly (self included), regardless of
+     * leadership. Unlike broadcast/send/tell, this isn't leader-mediated.
+     */
+    async messagePeer(peerName, event, payload) {
+        const { self } = this.bully.getStatus();
+        if (peerName === self) {
+            this.bully.channel.emit(event, payload);
+            return;
+        }
+        const peers = await this.bully.getPeers();
+        const target = peers.find((peer) => peer.name === peerName);
+        if (!target?.host) {
+            this.logger.warn(`messagePeer('${event}') could not resolve peer '${peerName}', dropping`);
+            return;
+        }
+        await this.transport.postToPeer(target.host, "/bully/message", { event, payload });
+    }
+    /**
+     * Leader-only: partition work across the whole cluster (self included). `resolvePayload` is
+     * called once per participant, in a stable order, and gets back that pod's own share to send.
+     */
+    async distribute(event, resolvePayload) {
+        if (!this.bully.isLeader()) {
+            this.logger.warn(`distribute('${event}') called while not leader, ignoring`);
+            return;
+        }
+        const { self, cluster } = await this.discovery();
+        const allPeers = [self, ...cluster.filter((pod) => pod.name !== self.name && pod.host)].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+        await Promise.all(allPeers.map((peer, index) => {
+            const payload = resolvePayload(peer, index, allPeers);
+            if (peer.name === self.name) {
+                this.bully.channel.emit(event, payload);
+                return;
+            }
+            return this.transport.postToPeer(peer.host, "/bully/message", { event, payload });
+        }));
+    }
+    /**
+     * Peer-to-peer: open a live subscription to everything a specific peer emits under one
+     * channel event name (self included, via a local listener — no loopback HTTP call needed).
+     * Returns an unsubscribe function.
+     */
+    subscribeToPeer(peerName, event, onData) {
+        const { self } = this.bully.getStatus();
+        if (peerName === self) {
+            this.bully.channel.on(event, onData);
+            return () => this.bully.channel.off(event, onData);
+        }
+        const controller = new AbortController();
+        let stopped = false;
+        (async () => {
+            const peers = await this.bully.getPeers();
+            const target = peers.find((peer) => peer.name === peerName);
+            if (!target?.host) {
+                this.logger.warn(`subscribeToPeer('${event}') could not resolve peer '${peerName}'`);
+                return;
+            }
+            try {
+                const res = await this.fetchFn(`http://${target.host}:${this.transport.port}/channel/stream/${event}`, {
+                    signal: controller.signal,
+                });
+                if (!res.ok || !res.body) {
+                    this.logger.warn(`subscribeToPeer('${event}') to '${peerName}' failed to connect`);
+                    return;
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                while (!stopped) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    let boundary;
+                    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+                        const frame = buffer.slice(0, boundary);
+                        buffer = buffer.slice(boundary + 2);
+                        const dataLine = frame.split("\n").find((line) => line.startsWith("data: "));
+                        if (!dataLine)
+                            continue;
+                        try {
+                            onData(JSON.parse(dataLine.slice(6)));
+                        }
+                        catch {
+                            this.logger.warn(`subscribeToPeer('${event}') received a malformed frame from '${peerName}'`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (err.name !== "AbortError") {
+                    this.logger.error(`subscribeToPeer('${event}') stream to '${peerName}' failed: ${err.message}`);
+                }
+            }
+        })();
+        return () => {
+            stopped = true;
+            controller.abort();
+        };
+    }
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,3 @@
+/** Minimal logging shape every class accepts as `opts.logger`. `console` satisfies this as-is. */
+export type Logger = Pick<Console, "info" | "warn" | "error" | "debug">;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC"}