@einaraglen/quorum 1.0.0 → 1.0.3

package/dist/core/quorum.d.ts

@@ -0,0 +1,51 @@
+import { type Discovery } from "./bully";
+import type { Logger } from "./logger";
+export type QuorumOptions<TId = string> = {
+    discovery: Discovery;
+    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>;
+    /** Fires with the ids just gained whenever this pod's held ids grow. Returns an unsubscribe function. */
+    onAssigned(onEvent: (ids: TId[]) => void): () => void;
+    /** Fires with the ids just lost whenever this pod's held ids shrink. Returns an unsubscribe function. */
+    onReleased(onEvent: (ids: TId[]) => void): () => 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,SAAS,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,aAAa,CAAC,GAAG,GAAG,MAAM,IAAI;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB,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,CAAgB;IAEtC,YAAY,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EAiCnC;IAEM,QAAQ,IAAI,OAAO,CAEzB;IACM,SAAS;;;;MAEf;IACY,WAAW;;;;SAEvB;IAEM,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,CAE9C;IACM,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAE3C;IACM,YAAY,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAEtC;IACM,UAAU,IAAI,GAAG,EAAE,CAEzB;IACY,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD;IAED,yGAAyG;IAClG,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAG3D;IACD,yGAAyG;IAClG,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAG3D;IAEM,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,100 @@
+import { Transport } from "./transport";
+import { Bully } from "./bully";
+import { Forum } from "./forum";
+import { Sharding } 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({
+            discovery: opts.discovery,
+            transport: this.transport,
+            coordinatorWaitMs: opts.coordinatorWaitMs,
+            heartbeatIntervalMs: opts.heartbeatIntervalMs,
+            logger: opts.logger,
+        });
+        this.forum = new Forum({
+            bully: this.bully,
+            transport: this.transport,
+            discovery: opts.discovery,
+            fetchFn: opts.fetchFn,
+            logger: opts.logger,
+        });
+        this.shard = new Sharding({
+            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);
+    }
+    /** Fires with the ids just gained whenever this pod's held ids grow. Returns an unsubscribe function. */
+    onAssigned(onEvent) {
+        this.shard.lifecycle.on("assigned", onEvent);
+        return () => this.shard.lifecycle.off("assigned", onEvent);
+    }
+    /** Fires with the ids just lost whenever this pod's held ids shrink. Returns an unsubscribe function. */
+    onReleased(onEvent) {
+        this.shard.lifecycle.on("released", onEvent);
+        return () => this.shard.lifecycle.off("released", onEvent);
+    }
+    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,100 @@
+import { EventEmitter } from "events";
+import type { Bully } from "./bully";
+import type { Forum } from "./forum";
+import type { Logger } from "./logger";
+export type ShardingOptions<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 Sharding<TId = string> implements Disposable {
+    /** Emits `"assigned"` / `"released"` (each with the delta of ids, not the full held set) whenever this pod's held ids change. */
+    readonly lifecycle: EventEmitter<[never]>;
+    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;
+    /** Guards against a periodic rebalance tick overlapping an explicit reconcile() already in flight. */
+    private reconcileInFlight;
+    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: ShardingOptions<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>;
+    private doReconcile;
+}
+//# 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":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,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,eAAe,CAAC,GAAG,IAAI;IACjC,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,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAE,YAAW,UAAU;IACvD,iIAAiI;IACjI,SAAgB,SAAS,wBAAsB;IAE/C,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,sGAAsG;IACtG,OAAO,CAAC,iBAAiB,CAAS;IAClC,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,eAAe,CAAC,GAAG,CAAC,EAUrC;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,CAId;IAEF,OAAO,CAAC,SAAS,CAIf;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,kBASrB;YAEa,WAAW;CA2F1B"}

package/dist/core/sharding.js

@@ -0,0 +1,264 @@
+import { EventEmitter } from "events";
+export class Sharding {
+    /** Emits `"assigned"` / `"released"` (each with the delta of ids, not the full held set) whenever this pod's held ids change. */
+    lifecycle = new EventEmitter();
+    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;
+    /** Guards against a periodic rebalance tick overlapping an explicit reconcile() already in flight. */
+    reconcileInFlight = 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)`);
+        this.lifecycle.emit("assigned", ids);
+    };
+    onRelease = (ids) => {
+        for (const id of ids)
+            this.heldIds.delete(id);
+        this.logger.debug(`Released ${ids.length} id(s), now holding ${this.heldIds.size}`);
+        this.lifecycle.emit("released", ids);
+    };
+    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() {
+        if (this.reconcileInFlight)
+            return;
+        this.reconcileInFlight = true;
+        try {
+            await this.doReconcile();
+        }
+        finally {
+            this.reconcileInFlight = false;
+        }
+    }
+    async doReconcile() {
+        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, Discovery, 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 { Sharding } from "./core/sharding";
+export type { ShardingOptions } 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,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErF,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,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,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 { Sharding } from "./core/sharding";