lunibee 0.3.2 → 0.3.3

package/dist/sharding/cluster.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess } from "node:child_process";
 import { type ShardReply } from "./bus.js";
 import type { ClusterManagerHealth, ClusterState, WorkerReport } from "./health.js";
+import type { LeaderLock } from "./leader.js";
 import { type HostStatus, type RemoteOptions } from "./remote.js";
 import { type SupervisorOptions } from "./supervisor.js";
 /** Configuration for managing multiple shard clusters. */
@@ -82,6 +83,22 @@ export interface ClusterManagerOptions {
      * workers like local ones. See {@link RemoteOptions}.
      */
     remote?: RemoteOptions;
+    /**
+     * Run several coordinators of one deployment, one active at a time, so a
+     * standby takes over when the active one dies (`RedisLeaderLock`, or your
+     * own {@link LeaderLock}). `spawn()` waits until this coordinator holds
+     * the lock. The leader renews it every quarter of `ttl`; if it cannot for
+     * half of `ttl` (or another holds it) it kills every cluster at once,
+     * closes the host listener, and waits to lead again. A new leader waits
+     * two `remote.lease`s before it starts clusters, so the previous leader's
+     * hosts have fenced themselves. Point hosts at every coordinator
+     * (`ClusterHost` `url` as a list).
+     */
+    leader?: {
+        lock: LeaderLock;
+        /** Lock lifetime in ms. Default 10,000; at least 100. */
+        ttl?: number;
+    };
     /** Starts a worker process. Defaults to `child_process.fork()`; replace it for tests or custom launchers. */
     fork?: (script: string, env: Record<string, string | undefined>) => ChildProcess;
     /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. */
@@ -179,6 +196,15 @@ export interface ClusterManagerEvents {
     hostJoin: [hostId: string];
     /** A host left or was lost. Its clusters are treated as crashed. */
     hostLeave: [hostId: string, reason: string];
+    /** A lost host's cluster is restarting on another host (`remote.moveClusters`). */
+    clusterMoved: [cluster: ClusterInfo, info: {
+        from: string;
+        to: string;
+    }];
+    /** This coordinator took the `leader` lock and will start the clusters. */
+    leaderAcquired: [];
+    /** This coordinator lost the `leader` lock and killed its clusters; it waits to lead again. */
+    leaderLost: [reason: string];
     /** An IDENTIFY is waiting for the session-start budget to reset. */
     identifyWait: [info: {
         shardId: number;
@@ -238,6 +264,8 @@ export declare class ClusterManager {
      * @throws {Error} If called from a cluster worker (a worker must not start the fleet again).
      */
     spawn(): Promise<void>;
+    /** Whether this coordinator holds the `leader` lock; always true without `leader`. */
+    get isLeader(): boolean;
     /** The port hosts connect to, once the listener is open (useful with `remote.port: 0`). */
     get remotePort(): number | undefined;
     /** The hosts of this deployment: connected or not, and the clusters on each. Empty without `remote`. */

package/dist/sharding/host.d.ts

@@ -1,8 +1,13 @@
 import type { ChildProcess } from "node:child_process";
 /** Options for a {@link ClusterHost}. */
 export interface ClusterHostOptions {
-    /** The coordinator's address: `wss://host:port`. `ws://` is accepted for this machine, or anywhere with `allowInsecure`. */
-    url: string;
+    /**
+     * The coordinator's address: `wss://host:port`. `ws://` is accepted for
+     * this machine, or anywhere with `allowInsecure`. A list names every
+     * coordinator of a deployment with a `leader` lock: the host tries them in
+     * turn, and moves to the next whenever one cannot be reached or drops it.
+     */
+    url: string | string[];
     /** Connect with `ws://` to a coordinator on another machine, over a network you fully trust. Default false. */
     allowInsecure?: boolean;
     /** The coordinator's shared secret. */

package/dist/sharding/index.d.ts

@@ -12,8 +12,10 @@ export { ClusterManager } from "./cluster.js";
 export type { ClusterManagerOptions, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, } from "./cluster.js";
 export { allocateShards, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
 export { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { threadEndpoint, threadFork, type ThreadEndpoint, type ThreadForkOptions, } from "./thread.js";
 export { ClusterHost, type ClusterHostEvents, type ClusterHostOptions, } from "./host.js";
 export type { HostStatus, RemoteOptions } from "./remote.js";
+export { RedisLeaderLock, type LeaderLock, type LeaderRedisClient, type RedisLeaderLockOptions, } from "./leader.js";
 export { RemoteClose, REMOTE_PROTOCOL_VERSION } from "./remote-protocol.js";
 export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, } from "./identify.js";
 export { RequestTracker } from "./requests.js";