@einaraglen/quorum 1.0.0 → 1.0.2

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 GetCluster = () => Promise<BullyCluster>;
+export type BullyOptions = {
+    getCluster: GetCluster;
+    transport: Transport;
+    coordinatorWaitMs?: number;
+    heartbeatIntervalMs?: number;
+    logger?: Logger;
+};
+export declare class Bully implements Disposable {
+    readonly lifecycle: EventEmitter<[never]>;
+    readonly channel: EventEmitter<[never]>;
+    private readonly getClusterFn;
+    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,UAAU,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,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,YAAY,CAAa;IAC1C,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();
+    getClusterFn;
+    transport;
+    coordinatorWaitMs;
+    heartbeatIntervalMs;
+    logger;
+    selfId;
+    leaderId;
+    electionInFlight = false;
+    coordinatorWaitTimeout;
+    heartbeatInterval;
+    constructor(opts) {
+        this.getClusterFn = opts.getCluster;
+        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.getClusterFn();
+        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.getClusterFn();
+        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. ShardManager.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, GetCluster } from "./bully";
+import type { Transport } from "./transport";
+export type ForumOptions = {
+    bully: Bully;
+    transport: Transport;
+    getCluster: GetCluster;
+    fetchFn?: typeof fetch;
+    logger?: Logger;
+};
+export declare class Forum {
+    private readonly bully;
+    private readonly transport;
+    private readonly getClusterFn;
+    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,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,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,YAAY,CAAa;IAC1C,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,CAUtE;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,CAqBf;IAED;;;;OAIG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAgEtG;CACF"}

package/dist/core/forum.js

@@ -0,0 +1,153 @@
+export class Forum {
+    bully;
+    transport;
+    getClusterFn;
+    fetchFn;
+    logger;
+    constructor(opts) {
+        this.bully = opts.bully;
+        this.transport = opts.transport;
+        this.getClusterFn = opts.getCluster;
+        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.getClusterFn();
+        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"}

package/dist/core/quorum.d.ts

@@ -0,0 +1,47 @@
+import { type GetCluster } from "./bully";
+import type { Logger } from "./logger";
+export type QuorumOptions<TId = string> = {
+    getCluster: GetCluster;
+    ids: TId[];
+    fetchFn?: typeof fetch;
+    internalPort?: number;
+    internalHost?: string;
+    requestTimeoutMs?: number;
+    coordinatorWaitMs?: number;
+    heartbeatIntervalMs?: number;
+    reportTimeoutMs?: number;
+    rebalanceIntervalMs?: number;
+    expectedClusterSize?: number;
+    quorumFailureThreshold?: number;
+    onSustainedQuorumLoss?: () => void;
+    /** Injectable log sink; must implement `info`/`warn`/`error`/`debug`. Defaults to `console`. */
+    logger?: Logger;
+};
+export declare class Quorum<TId = string> implements Disposable {
+    private readonly transport;
+    private readonly bully;
+    private readonly forum;
+    private readonly shard;
+    constructor(opts: QuorumOptions<TId>);
+    isLeader(): boolean;
+    getStatus(): {
+        self: string | undefined;
+        leader: string | undefined;
+        isLeader: boolean;
+    };
+    getPodRoles(): Promise<{
+        name: string | undefined;
+        host: string | undefined;
+        role: string;
+    }[]>;
+    subscribe(id: TId, onEvent: (payload: unknown) => void): () => void;
+    publish(id: TId, payload: unknown): void;
+    getOwner(id: TId): string | undefined;
+    getOwnership(): Map<TId, string>;
+    getHeldIds(): TId[];
+    updateIds(ids: TId[]): Promise<void>;
+    start(): void;
+    stop(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=quorum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quorum.d.ts","sourceRoot":"","sources":["../../src/core/quorum.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,aAAa,CAAC,GAAG,GAAG,MAAM,IAAI;IACxC,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,MAAM,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAE1C,YAAY,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EAiCnC;IAEM,QAAQ,IAAI,OAAO,CAAkC;IACrD,SAAS;;;;MAAqC;IACxC,WAAW;;;;SAAuC;IAExD,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAEzE;IACM,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAqC;IAC7E,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAAoC;IACzE,YAAY,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAsC;IACtE,UAAU,IAAI,GAAG,EAAE,CAAoC;IACjD,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAsC;IAEhF,KAAK,IAAI,IAAI,CAUnB;IAEM,IAAI,IAAI,IAAI,CAIlB;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAE9B;CACF"}

package/dist/core/quorum.js

@@ -0,0 +1,74 @@
+import { Transport } from "./transport";
+import { Bully } from "./bully";
+import { Forum } from "./forum";
+import { ShardManager } from "./sharding";
+export class Quorum {
+    transport;
+    bully;
+    forum;
+    shard;
+    constructor(opts) {
+        this.transport = new Transport({
+            fetchFn: opts.fetchFn,
+            internalPort: opts.internalPort,
+            internalHost: opts.internalHost,
+            requestTimeoutMs: opts.requestTimeoutMs,
+            logger: opts.logger,
+        });
+        this.bully = new Bully({
+            getCluster: opts.getCluster,
+            transport: this.transport,
+            coordinatorWaitMs: opts.coordinatorWaitMs,
+            heartbeatIntervalMs: opts.heartbeatIntervalMs,
+            logger: opts.logger,
+        });
+        this.forum = new Forum({
+            bully: this.bully,
+            transport: this.transport,
+            getCluster: opts.getCluster,
+            fetchFn: opts.fetchFn,
+            logger: opts.logger,
+        });
+        this.shard = new ShardManager({
+            bully: this.bully,
+            forum: this.forum,
+            ids: opts.ids,
+            reportTimeoutMs: opts.reportTimeoutMs,
+            rebalanceIntervalMs: opts.rebalanceIntervalMs,
+            expectedClusterSize: opts.expectedClusterSize,
+            quorumFailureThreshold: opts.quorumFailureThreshold,
+            onSustainedQuorumLoss: opts.onSustainedQuorumLoss,
+            logger: opts.logger,
+        });
+    }
+    isLeader() { return this.bully.isLeader(); }
+    getStatus() { return this.bully.getStatus(); }
+    async getPodRoles() { return this.bully.getPodRoles(); }
+    subscribe(id, onEvent) {
+        return this.shard.subscribe(id, onEvent);
+    }
+    publish(id, payload) { this.shard.publish(id, payload); }
+    getOwner(id) { return this.shard.getOwner(id); }
+    getOwnership() { return this.shard.getOwnership(); }
+    getHeldIds() { return this.shard.getHeldIds(); }
+    async updateIds(ids) { return this.shard.updateIds(ids); }
+    start() {
+        this.transport.start({
+            onElectionMessage: (id) => this.bully.onElectionMessage(id),
+            onCoordinatorMessage: (id) => this.bully.onCoordinatorMessage(id),
+            onMessage: (event, payload) => this.bully.onMessage(event, payload),
+            channel: this.bully.channel,
+        });
+        this.shard.start();
+        this.bully.start();
+        this.bully.startElection();
+    }
+    stop() {
+        this.shard.stop();
+        this.bully.stop();
+        this.transport.stop();
+    }
+    [Symbol.dispose]() {
+        this.stop();
+    }
+}

package/dist/core/sharding.d.ts

@@ -0,0 +1,94 @@
+import type { Bully } from "./bully";
+import type { Forum } from "./forum";
+import type { Logger } from "./logger";
+export type ShardManagerOptions<TId> = {
+    bully: Bully;
+    forum: Forum;
+    ids: TId[];
+    reportTimeoutMs?: number;
+    rebalanceIntervalMs?: number;
+    /**
+     * The cluster's intended total pod count (e.g. the Deployment's `replicas`), used as a
+     * quorum guard: reconcile() refuses to act unless more than half of this count actually
+     * reported in. Left unset, quorum checking is disabled entirely — safe default for tests
+     * and small ad-hoc clusters that don't care about split-brain protection.
+     */
+    expectedClusterSize?: number;
+    /**
+     * How many *consecutive* quorum failures to tolerate before treating this pod as sustainably
+     * isolated (as opposed to one slow reconcile pass on an otherwise-healthy network) and
+     * invoking onSustainedQuorumLoss. Only relevant when expectedClusterSize is set.
+     */
+    quorumFailureThreshold?: number;
+    /**
+     * Called once quorumFailureThreshold consecutive quorum failures are hit. Defaults to
+     * `process.exit(1)` — fail loudly and let Kubernetes restart the pod, rather than keep
+     * serving increasingly stale data while believing it's still leader. Injectable so tests
+     * (and anyone who wants different behavior) don't have to actually kill the process.
+     */
+    onSustainedQuorumLoss?: () => void;
+    logger?: Logger;
+};
+export declare class ShardManager<TId = string> implements Disposable {
+    private bully;
+    private forum;
+    private allIds;
+    private reportTimeoutMs;
+    private rebalanceIntervalMs;
+    private expectedClusterSize?;
+    private quorumFailureThreshold;
+    private sustainedQuorumLossCallback;
+    private logger;
+    private consecutiveQuorumFailures;
+    /** Ensures sustainedQuorumLossCallback fires once per episode, not on every failure past threshold. */
+    private hasTriggeredSustainedLoss;
+    private heldIds;
+    private ownership;
+    private rebalanceInterval?;
+    /** Local-only: fires `<id>` whenever getOwner(id) changes, to drive subscribe() reconnects. */
+    private ownershipEvents;
+    /** Safety net: any subscribe() the caller never explicitly closed gets torn down in stop(). */
+    private activeSubscriptions;
+    constructor(opts: ShardManagerOptions<TId>);
+    getHeldIds(): TId[];
+    /** Local, instant lookup — no network round-trip — of which peer currently owns an id. */
+    getOwner(id: TId): string | undefined;
+    /** Local, cluster-wide view of every id's current owner — every peer as of the last reconcile. */
+    getOwnership(): Map<TId, string>;
+    /**
+     * Live-subscribe to events published for `id`, wherever it currently lives. Returns an
+     * unsubscribe function. Reconnects automatically if ownership of this specific id changes
+     * while the subscription is active, driven by the same ownership map reconcile() already
+     * keeps fresh — no message from the old owner required, no subscriber bookkeeping on the
+     * owner's side at all. Under the hood this is just an SSE connection (via
+     * bully.subscribeToPeer); closing it is the entire unsubscribe.
+     */
+    subscribe(id: TId, onEvent: (payload: unknown) => void): () => void;
+    /** Called by the app whenever it has a new event for one of the ids this pod owns. */
+    publish(id: TId, payload: unknown): void;
+    private onAssign;
+    private onRelease;
+    private onReportRequest;
+    private onUpdateIds;
+    private onOwnershipMap;
+    private onElected;
+    private onDemoted;
+    start(): void;
+    stop(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Leader-only: change the full set of ids that should be distributed across the cluster —
+     * e.g. after re-querying the database this bundle came from and finding it grew or shrank.
+     * Broadcasts the new set to every peer (so whichever pod is leader next already has it) and
+     * immediately reconciles, rather than waiting for the next periodic tick.
+     */
+    updateIds(ids: TId[]): Promise<void>;
+    /**
+     * Gathers what every reachable peer currently holds, computes the fair target split of all
+     * ids across those peers, broadcasts the full id→peer map so any pod can look up an owner
+     * locally via getOwner() without asking around, and sends each peer exactly the
+     * assign/release messages needed to converge on that target.
+     */
+    reconcile(): Promise<void>;
+}
+//# sourceMappingURL=sharding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../../src/core/sharding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,mBAAmB,CAAC,GAAG,IAAI;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAKF,qBAAa,YAAY,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IAC3D,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,2BAA2B,CAAa;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,yBAAyB,CAAK;IACtC,uGAAuG;IACvG,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAC3C,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAsB;IAC7C,+FAA+F;IAC/F,OAAO,CAAC,mBAAmB,CAAyB;IAEpD,YAAY,IAAI,EAAE,mBAAmB,CAAC,GAAG,CAAC,EAUzC;IAEM,UAAU,UAEhB;IAED,0FAA0F;IACnF,QAAQ,CAAC,EAAE,EAAE,GAAG,sBAEtB;IAED,kGAAkG;IAC3F,YAAY,qBAElB;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA+BzE;IAED,sFAAsF;IAC/E,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,QAMvC;IAED,OAAO,CAAC,QAAQ,CAGd;IAEF,OAAO,CAAC,SAAS,CAGf;IAEF,OAAO,CAAC,eAAe,CAIrB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,cAAc,CAUpB;IAEF,OAAO,CAAC,SAAS,CAGf;IAEF,OAAO,CAAC,SAAS,CAKf;IAEK,KAAK,SAQX;IAEM,IAAI,SAWV;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC,SAEtB;IAED;;;;;OAKG;IACU,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,iBAQhC;IAED;;;;;OAKG;IACU,SAAS,kBA0FrB;CACF"}

package/dist/core/sharding.js

@@ -0,0 +1,247 @@
+import { EventEmitter } from "events";
+export class ShardManager {
+    bully;
+    forum;
+    allIds;
+    reportTimeoutMs;
+    rebalanceIntervalMs;
+    expectedClusterSize;
+    quorumFailureThreshold;
+    sustainedQuorumLossCallback;
+    logger;
+    consecutiveQuorumFailures = 0;
+    /** Ensures sustainedQuorumLossCallback fires once per episode, not on every failure past threshold. */
+    hasTriggeredSustainedLoss = false;
+    heldIds = new Set();
+    ownership = new Map();
+    rebalanceInterval;
+    /** Local-only: fires `<id>` whenever getOwner(id) changes, to drive subscribe() reconnects. */
+    ownershipEvents = new EventEmitter();
+    /** Safety net: any subscribe() the caller never explicitly closed gets torn down in stop(). */
+    activeSubscriptions = new Set();
+    constructor(opts) {
+        this.bully = opts.bully;
+        this.forum = opts.forum;
+        this.allIds = opts.ids;
+        this.reportTimeoutMs = opts.reportTimeoutMs ?? 2000;
+        this.rebalanceIntervalMs = opts.rebalanceIntervalMs ?? 10000;
+        this.expectedClusterSize = opts.expectedClusterSize;
+        this.quorumFailureThreshold = opts.quorumFailureThreshold ?? 3;
+        this.sustainedQuorumLossCallback = opts.onSustainedQuorumLoss ?? (() => process.exit(1));
+        this.logger = opts.logger ?? console;
+    }
+    getHeldIds() {
+        return [...this.heldIds];
+    }
+    /** Local, instant lookup — no network round-trip — of which peer currently owns an id. */
+    getOwner(id) {
+        return this.ownership.get(id);
+    }
+    /** Local, cluster-wide view of every id's current owner — every peer as of the last reconcile. */
+    getOwnership() {
+        return new Map(this.ownership);
+    }
+    /**
+     * Live-subscribe to events published for `id`, wherever it currently lives. Returns an
+     * unsubscribe function. Reconnects automatically if ownership of this specific id changes
+     * while the subscription is active, driven by the same ownership map reconcile() already
+     * keeps fresh — no message from the old owner required, no subscriber bookkeeping on the
+     * owner's side at all. Under the hood this is just an SSE connection (via
+     * bully.subscribeToPeer); closing it is the entire unsubscribe.
+     */
+    subscribe(id, onEvent) {
+        let close;
+        const connect = () => {
+            const owner = this.getOwner(id);
+            if (!owner) {
+                this.logger.warn(`subscribe(${id}) could not resolve an owner`);
+                return;
+            }
+            close = this.forum.subscribeToPeer(owner, "connection-event", (event) => {
+                const { id: eventId, payload } = event;
+                if (eventId === id)
+                    onEvent(payload);
+            });
+        };
+        const onOwnerChanged = () => {
+            close?.();
+            connect();
+        };
+        connect();
+        this.ownershipEvents.on(String(id), onOwnerChanged);
+        const unsubscribe = () => {
+            this.ownershipEvents.off(String(id), onOwnerChanged);
+            close?.();
+            this.activeSubscriptions.delete(unsubscribe);
+        };
+        this.activeSubscriptions.add(unsubscribe);
+        return unsubscribe;
+    }
+    /** Called by the app whenever it has a new event for one of the ids this pod owns. */
+    publish(id, payload) {
+        if (!this.heldIds.has(id)) {
+            this.logger.warn(`publish(${id}) called but this pod doesn't own that id, dropping`);
+            return;
+        }
+        this.bully.channel.emit("connection-event", { id, payload });
+    }
+    onAssign = (ids) => {
+        for (const id of ids)
+            this.heldIds.add(id);
+        this.logger.debug(`Now holding ${this.heldIds.size} id(s)`);
+    };
+    onRelease = (ids) => {
+        for (const id of ids)
+            this.heldIds.delete(id);
+        this.logger.debug(`Released ${ids.length} id(s), now holding ${this.heldIds.size}`);
+    };
+    onReportRequest = () => {
+        const { self } = this.bully.getStatus();
+        if (!self)
+            return;
+        this.forum.send("holdings-report", { peer: self, ids: this.getHeldIds() });
+    };
+    onUpdateIds = (ids) => {
+        this.allIds = ids;
+    };
+    onOwnershipMap = (entries) => {
+        const next = new Map(entries);
+        const previous = this.ownership;
+        // Swapped in before emitting: subscribe()'s reconnect handler calls getOwner() synchronously
+        // in reaction to this event, so it must already see the new value, not the one it's replacing.
+        this.ownership = next;
+        for (const [id, peer] of next) {
+            if (previous.get(id) !== peer)
+                this.ownershipEvents.emit(String(id), peer);
+        }
+    };
+    onElected = () => {
+        this.reconcile();
+        this.rebalanceInterval = setInterval(() => this.reconcile(), this.rebalanceIntervalMs);
+    };
+    onDemoted = () => {
+        if (this.rebalanceInterval)
+            clearInterval(this.rebalanceInterval);
+        this.rebalanceInterval = undefined;
+        this.consecutiveQuorumFailures = 0;
+        this.hasTriggeredSustainedLoss = false;
+    };
+    start() {
+        this.bully.channel.on("assign-connections", this.onAssign);
+        this.bully.channel.on("release-connections", this.onRelease);
+        this.bully.channel.on("report-holdings-request", this.onReportRequest);
+        this.bully.channel.on("update-ids", this.onUpdateIds);
+        this.bully.channel.on("ownership-map", this.onOwnershipMap);
+        this.bully.lifecycle.on("elected", this.onElected);
+        this.bully.lifecycle.on("demoted", this.onDemoted);
+    }
+    stop() {
+        this.bully.channel.off("assign-connections", this.onAssign);
+        this.bully.channel.off("release-connections", this.onRelease);
+        this.bully.channel.off("report-holdings-request", this.onReportRequest);
+        this.bully.channel.off("update-ids", this.onUpdateIds);
+        this.bully.channel.off("ownership-map", this.onOwnershipMap);
+        this.bully.lifecycle.off("elected", this.onElected);
+        this.bully.lifecycle.off("demoted", this.onDemoted);
+        this.onDemoted();
+        for (const unsubscribe of [...this.activeSubscriptions])
+            unsubscribe();
+    }
+    [Symbol.dispose]() {
+        this.stop();
+    }
+    /**
+     * Leader-only: change the full set of ids that should be distributed across the cluster —
+     * e.g. after re-querying the database this bundle came from and finding it grew or shrank.
+     * Broadcasts the new set to every peer (so whichever pod is leader next already has it) and
+     * immediately reconciles, rather than waiting for the next periodic tick.
+     */
+    async updateIds(ids) {
+        if (!this.bully.isLeader()) {
+            this.logger.warn("updateIds() called while not leader, ignoring");
+            return;
+        }
+        await this.forum.broadcast("update-ids", ids);
+        await this.reconcile();
+    }
+    /**
+     * Gathers what every reachable peer currently holds, computes the fair target split of all
+     * ids across those peers, broadcasts the full id→peer map so any pod can look up an owner
+     * locally via getOwner() without asking around, and sends each peer exactly the
+     * assign/release messages needed to converge on that target.
+     */
+    async reconcile() {
+        const reports = new Map();
+        const { self } = this.bully.getStatus();
+        if (self)
+            reports.set(self, this.getHeldIds());
+        const collector = (payload) => {
+            reports.set(payload.peer, payload.ids);
+        };
+        this.bully.channel.on("holdings-report", collector);
+        await this.forum.broadcast("report-holdings-request");
+        await new Promise((resolve) => setTimeout(resolve, this.reportTimeoutMs));
+        this.bully.channel.off("holdings-report", collector);
+        const reporters = [...reports.keys()].sort();
+        if (reporters.length === 0) {
+            this.logger.warn("Reconciled: no peer reported in, nothing we can do");
+            return;
+        }
+        if (this.expectedClusterSize) {
+            const majority = Math.floor(this.expectedClusterSize / 2) + 1;
+            if (reporters.length < majority) {
+                this.consecutiveQuorumFailures++;
+                this.logger.warn(`Reconciled: only ${reporters.length}/${this.expectedClusterSize} peer(s) reachable ` +
+                    `(need ${majority} for quorum), refusing to reconcile ` +
+                    `[${this.consecutiveQuorumFailures}/${this.quorumFailureThreshold} consecutive failures]`);
+                if (this.consecutiveQuorumFailures >= this.quorumFailureThreshold && !this.hasTriggeredSustainedLoss) {
+                    this.hasTriggeredSustainedLoss = true;
+                    this.logger.error(`Sustained quorum loss after ${this.consecutiveQuorumFailures} consecutive attempts, ` +
+                        `invoking onSustainedQuorumLoss`);
+                    this.sustainedQuorumLossCallback();
+                }
+                return;
+            }
+        }
+        this.consecutiveQuorumFailures = 0;
+        this.hasTriggeredSustainedLoss = false;
+        const fairShare = Math.floor(this.allIds.length / reporters.length);
+        const remainder = this.allIds.length % reporters.length;
+        let cursor = 0;
+        const targets = new Map();
+        reporters.forEach((peer, index) => {
+            const count = fairShare + (index < remainder ? 1 : 0);
+            targets.set(peer, new Set(this.allIds.slice(cursor, cursor + count)));
+            cursor += count;
+        });
+        // Broadcast unconditionally, even on a pass where nothing moves — a peer's cached map is
+        // otherwise only as fresh as the last pass that happened to change something.
+        const ownershipEntries = [];
+        for (const [peer, ids] of targets)
+            for (const id of ids)
+                ownershipEntries.push([id, peer]);
+        await this.forum.broadcast("ownership-map", ownershipEntries);
+        const assignments = new Map();
+        const releases = new Map();
+        for (const peer of reporters) {
+            const current = new Set(reports.get(peer));
+            const target = targets.get(peer);
+            const toAdd = [...target].filter((id) => !current.has(id));
+            const toRemove = [...current].filter((id) => !target.has(id));
+            if (toAdd.length > 0)
+                assignments.set(peer, toAdd);
+            if (toRemove.length > 0)
+                releases.set(peer, toRemove);
+        }
+        if (assignments.size === 0 && releases.size === 0) {
+            this.logger.debug("Reconciled: already balanced, nothing to do");
+            return;
+        }
+        this.logger.info(`Reconciled: converging ${reporters.length} peer(s) on a fair split ` +
+            `(${assignments.size} gaining ids, ${releases.size} releasing ids)`);
+        await Promise.all([
+            ...[...assignments.entries()].map(([peer, ids]) => this.forum.tell(peer, "assign-connections", ids)),
+            ...[...releases.entries()].map(([peer, ids]) => this.forum.tell(peer, "release-connections", ids)),
+        ]);
+    }
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from "events";
+import type { Logger } from "./logger";
+export type TransportOptions = {
+    fetchFn?: typeof fetch;
+    internalPort?: number;
+    internalHost?: string;
+    requestTimeoutMs?: number;
+    logger?: Logger;
+};
+export type TransportCallbacks = {
+    onElectionMessage: (fromId: string) => void;
+    onCoordinatorMessage: (id: string) => void;
+    onMessage: (event: string, payload: unknown) => void;
+    channel: EventEmitter;
+};
+export declare class Transport {
+    readonly fetchFn: typeof fetch;
+    readonly port: number;
+    private readonly internalHost?;
+    private readonly requestTimeoutMs;
+    private readonly logger;
+    private server?;
+    constructor(opts?: TransportOptions);
+    postToPeer(host: string, path: string, body: unknown): Promise<boolean>;
+    pingPeer(host: string): Promise<boolean>;
+    start(cb: TransportCallbacks): void;
+    stop(): void;
+}
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/core/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,oBAAoB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,OAAO,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,qBAAa,SAAS;IACpB,SAAgB,OAAO,EAAE,OAAO,KAAK,CAAC;IACtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,MAAM,CAAC,CAAS;IAExB,YAAY,IAAI,GAAE,gBAAqB,EAMtC;IAEY,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnF;IAEY,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASpD;IAEM,KAAK,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI,CA4CzC;IAEM,IAAI,IAAI,IAAI,CAElB;CACF"}

package/dist/core/transport.js

@@ -0,0 +1,83 @@
+import express from "express";
+export class Transport {
+    fetchFn;
+    port;
+    internalHost;
+    requestTimeoutMs;
+    logger;
+    server;
+    constructor(opts = {}) {
+        this.fetchFn = opts.fetchFn ?? fetch;
+        this.port = opts.internalPort ?? Number(process.env.INTERNAL_PORT || 4001);
+        this.internalHost = opts.internalHost;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 2000;
+        this.logger = opts.logger ?? console;
+    }
+    async postToPeer(host, path, body) {
+        try {
+            const res = await this.fetchFn(`http://${host}:${this.port}${path}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async pingPeer(host) {
+        try {
+            const res = await this.fetchFn(`http://${host}:${this.port}/health`, {
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    start(cb) {
+        const app = express();
+        app.use(express.json());
+        app.get("/health", (_, res) => {
+            res.json({ status: "OK", timestamp: new Date().toISOString() });
+        });
+        app.post("/bully/election", (req, res) => {
+            cb.onElectionMessage(req.body?.id);
+            res.sendStatus(200);
+        });
+        app.post("/bully/coordinator", (req, res) => {
+            cb.onCoordinatorMessage(req.body?.id);
+            res.sendStatus(200);
+        });
+        app.post("/bully/message", (req, res) => {
+            cb.onMessage(req.body?.event, req.body?.payload);
+            res.sendStatus(200);
+        });
+        app.get("/channel/stream/:event", (req, res) => {
+            const eventName = req.params.event;
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            const forward = (payload) => res.write(`data: ${JSON.stringify(payload)}\n\n`);
+            cb.channel.on(eventName, forward);
+            req.on("close", () => cb.channel.off(eventName, forward));
+        });
+        app.use((err, _req, res, _next) => {
+            this.logger.error(err);
+            res.status(500).json({ status: "ERROR", error: err?.message ?? String(err) });
+        });
+        const onListening = () => this.logger.info(`Internal coordination server listening on port ${this.port}`);
+        this.server = this.internalHost
+            ? app.listen(this.port, this.internalHost, onListening)
+            : app.listen(this.port, onListening);
+    }
+    stop() {
+        if (this.server)
+            this.server.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Quorum } from "./core/quorum";
+export type { QuorumOptions } from "./core/quorum";
+export { Bully } from "./core/bully";
+export type { BullyPeer, BullyCluster, GetCluster, BullyOptions } from "./core/bully";
+export { Forum } from "./core/forum";
+export type { ForumOptions } from "./core/forum";
+export { Transport } from "./core/transport";
+export type { TransportOptions, TransportCallbacks } from "./core/transport";
+export { ShardManager } from "./core/sharding";
+export type { ShardManagerOptions } from "./core/sharding";
+export type { Logger } from "./core/logger";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEtF,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Quorum } from "./core/quorum";
+export { Bully } from "./core/bully";
+export { Forum } from "./core/forum";
+export { Transport } from "./core/transport";
+export { ShardManager } from "./core/sharding";

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@einaraglen/quorum",
-  "version": "1.0.0",
-  "description": "Distributed pod coordination: Bully leader election and work sharding",
-  "keywords": [
-    "leader-election",
-    "sharding",
-    "distributed-systems"
-  ],
-  "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/einaraglen/quorum.git"
-  },
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist"
-  ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "test": "tsx --test --test-reporter=spec --test-reporter-destination=stdout src/**/*.test.ts",
-    "build": "tsc"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/node": "^24.9.2",
-    "tsx": "^4.23.12",
-    "typescript": "^7.0.2"
-  },
-  "dependencies": {
-    "express": "^5.2.1"
-  }
-}
+{
+  "name": "@einaraglen/quorum",
+  "version": "1.0.2",
+  "description": "Distributed pod coordination: Bully leader election and work sharding",
+  "keywords": [
+    "leader-election",
+    "sharding",
+    "distributed-systems"
+  ],
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/einaraglen/quorum.git"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "tsx --test --test-reporter=spec --test-reporter-destination=stdout src/**/*.test.ts",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.9.2",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "express": "^5.2.1"
+  }
+}