lunibee 0.3.0 → 0.3.1

package/dist/sharding/protocol.d.ts

@@ -0,0 +1,47 @@
+import type { WorkerReport } from "./health.js";
+/** Marks a cluster control frame on the IPC channel, next to the shard-bus frames. */
+export declare const CLUSTER_FRAME = "__lunibeeCluster";
+/** The `source` and reply `target` of the parent process on the shard bus. */
+export declare const PARENT_ID = -1;
+/** Built-in cluster request: the worker answers with a {@link WorkerReport}. */
+export declare const REQUEST_HEALTH = "__lunibee:health";
+/** Built-in cluster request: the worker starts the given shards (recovery). */
+export declare const REQUEST_ASSIGN = "__lunibee:assign";
+/** Frames a worker sends to the parent. */
+export type ChildFrame = {
+    kind: "ready";
+    shardIds: number[];
+} | {
+    kind: "identify";
+    id: number;
+    shardId: number;
+} | {
+    kind: "identify-done";
+    shardId: number;
+} | {
+    kind: "reply";
+    id: string;
+    result?: unknown;
+    error?: string;
+} | {
+    kind: "health";
+    report: WorkerReport;
+};
+/** Frames the parent sends to a worker. */
+export type ParentFrame = {
+    kind: "identify-grant";
+    id: number;
+} | {
+    kind: "identify-deny";
+    id: number;
+    error: string;
+} | {
+    kind: "request";
+    id: string;
+    type: string;
+    data: unknown;
+};
+/** Validates the body of a control frame from a worker; `null` when it is malformed. */
+export declare function parseChildFrame(value: unknown): ChildFrame | null;
+/** Validates the body of a control frame from the parent; `null` when it is malformed. */
+export declare function parseParentFrame(value: unknown): ParentFrame | null;

package/dist/sharding/remote-protocol.d.ts

@@ -0,0 +1,100 @@
+/** Version of the coordinator ↔ host wire protocol. Both sides must agree. */
+export declare const REMOTE_PROTOCOL_VERSION = 1;
+/** Largest text frame either side accepts, in UTF-8 bytes. */
+export declare const MAX_REMOTE_FRAME_BYTES: number;
+/** WebSocket close codes used between a coordinator and a host. */
+export declare const RemoteClose: {
+    readonly BadRequest: 4400;
+    readonly AuthFailed: 4401;
+    readonly HelloTimeout: 4408;
+    readonly DuplicateHost: 4409;
+    readonly TooManyConnections: 4429;
+    readonly UnknownHost: 4410;
+    readonly VersionMismatch: 4426;
+    readonly HostLost: 4504;
+    readonly Shutdown: 4500;
+};
+/**
+ * The only environment variables a coordinator may set in a remote worker.
+ * Everything else comes from the host's own environment, so a coordinator
+ * cannot inject `NODE_OPTIONS`, `LD_PRELOAD` or a token.
+ */
+export declare const SPAWN_ENV_KEYS: ReadonlySet<string>;
+/** Signals a coordinator may send to a remote worker. */
+export declare const KILL_SIGNALS: ReadonlySet<string>;
+/** Whether a host name is this machine, where an unencrypted link is acceptable. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** A host ID: letters, digits, `.`, `_` and `-`, up to 64 characters. */
+export declare const HOST_ID: RegExp;
+/** Frames the coordinator sends to a host. */
+export type ToHost = {
+    t: "challenge";
+    nonce: string;
+    version: number;
+} | {
+    t: "welcome";
+    leaseMs: number;
+    pingMs: number;
+} | {
+    t: "ping";
+    n: number;
+} | {
+    t: "spawn";
+    cluster: number;
+    epoch: number;
+    env: Record<string, string>;
+} | {
+    t: "frame";
+    cluster: number;
+    epoch: number;
+    frame: unknown;
+} | {
+    t: "kill";
+    cluster: number;
+    epoch: number;
+    signal: string;
+} | {
+    t: "bye";
+    reason: string;
+};
+/** Frames a host sends to the coordinator. */
+export type ToCoordinator = {
+    t: "hello";
+    id: string;
+    mac: string;
+    version: number;
+} | {
+    t: "pong";
+    n: number;
+} | {
+    t: "spawned";
+    cluster: number;
+    epoch: number;
+    pid?: number;
+} | {
+    t: "frame";
+    cluster: number;
+    epoch: number;
+    frame: unknown;
+} | {
+    t: "exit";
+    cluster: number;
+    epoch: number;
+    code: number | null;
+    signal: string | null;
+} | {
+    t: "error";
+    cluster: number;
+    epoch: number;
+    message: string;
+};
+/** The size of a string on the wire, in UTF-8 bytes. */
+export declare function utf8Bytes(text: string): number;
+/** The proof a host sends: an HMAC of the coordinator's nonce and the host ID, keyed by the shared secret. The secret itself never travels. */
+export declare function signChallenge(secret: string, nonce: string, hostId: string): string;
+/** Checks a host's proof in constant time. */
+export declare function verifyChallenge(secret: string, nonce: string, hostId: string, mac: unknown): boolean;
+/** Validates a text frame from the coordinator; `null` when malformed. */
+export declare function parseToHost(text: unknown, maxBytes?: number): ToHost | null;
+/** Validates a text frame from a host; `null` when malformed. */
+export declare function parseToCoordinator(text: unknown, maxBytes?: number): ToCoordinator | null;

package/dist/sharding/remote.d.ts

@@ -0,0 +1,118 @@
+import { EventEmitter } from "node:events";
+import type { ChildProcess } from "node:child_process";
+/** Where, and how, a coordinator listens for hosts. */
+export interface RemoteOptions {
+    /** TCP port. `0` picks a free one (read it from `ClusterManager#remotePort`). */
+    port: number;
+    /**
+     * Interface to bind. Default `127.0.0.1`, which only this machine can
+     * reach. Any other address needs `tls` or `allowInsecure`.
+     */
+    hostname?: string;
+    /** Shared secret, at least 16 characters. Hosts prove they know it; it never crosses the wire. */
+    secret: string;
+    /** TLS for `wss://`. Required to listen on a non-loopback address unless `allowInsecure` is set. */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /**
+     * Listen on a non-loopback address without TLS: frames (shard messages
+     * and worker output) travel unencrypted and unsigned. Only for a network
+     * you fully trust, or when a TLS proxy in front terminates the connection.
+     * Default false.
+     */
+    allowInsecure?: boolean;
+    /**
+     * The host IDs that make up the deployment. Clusters are placed on them in
+     * this order, and an unlisted host is refused. Without it, the hosts that
+     * have joined when `spawn()` starts are used, sorted by ID.
+     */
+    hosts?: string[];
+    /** How many hosts must join before clusters are placed when `hosts` is not set. Default 1. */
+    minHosts?: number;
+    /** Milliseconds to wait for the hosts to join before `spawn()` fails. Default 60,000. */
+    joinTimeout?: number;
+    /**
+     * Fencing lease in milliseconds. A host that hears nothing from the
+     * coordinator for this long kills its workers; the coordinator waits twice
+     * as long before it treats the host as lost and restarts its clusters, so
+     * a shard never runs in two places. Default 15,000.
+     */
+    lease?: number;
+    /** Milliseconds a new connection has to authenticate before it is closed. Default 10,000. */
+    helloTimeout?: number;
+    /** Most connections that may be waiting to authenticate at once; more are closed. Default 16. */
+    maxUnauthenticated?: number;
+    /** Also run clusters on the coordinator's own machine. Default false: clusters run on the hosts only. */
+    local?: boolean;
+}
+/** A host as the coordinator sees it. */
+export interface HostStatus {
+    id: string;
+    /** Whether its socket is open and answering. */
+    connected: boolean;
+    /** When it last sent anything (epoch ms). */
+    lastSeen: number;
+    /** Clusters currently running on it. */
+    clusters: number[];
+}
+type Kill = (signal: string) => boolean;
+/** What the coordinator wants to hear about its hosts. */
+export interface RemoteHooks {
+    join(id: string): void;
+    leave(id: string, reason: string): void;
+    error(error: Error): void;
+}
+/**
+ * A worker process on another host, shaped like the `ChildProcess` that
+ * `ClusterManager` supervises. `send()` and `kill()` travel to the host's
+ * agent; its messages and exit travel back, so the manager's restart,
+ * IDENTIFY, routing and health logic needs no special case for it.
+ */
+export declare class RemoteChild extends EventEmitter {
+    #private;
+    readonly host: string;
+    readonly cluster: number;
+    readonly epoch: number;
+    pid: number | undefined;
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+    connected: boolean;
+    constructor(host: string, cluster: number, epoch: number, send: (frame: unknown) => boolean, kill: Kill);
+    /** Sends an IPC frame to the worker. */
+    send(frame: unknown): boolean;
+    /** Asks the host to signal the worker; the exit arrives as an event. */
+    kill(signal?: string): boolean;
+    /** The agent says the worker started. */
+    spawned(pid: number | undefined): void;
+    /** The worker sent a message. */
+    deliver(frame: unknown): void;
+    /** The worker exited, or its host was lost. Emits `exit` once. */
+    finish(code: number | null, signal: string | null): void;
+}
+/** The coordinator's listener and the hosts that joined it. */
+export declare class RemoteHosts {
+    #private;
+    constructor(options: RemoteOptions, hooks: RemoteHooks);
+    /** The port in use, once started. */
+    get port(): number | undefined;
+    /** Host IDs that are connected now, sorted. */
+    connected(): string[];
+    /** Opens the listener. Safe to call twice. */
+    start(): void;
+    /** Closes the listener and every host connection. */
+    stop(): void;
+    /** Resolves when the given hosts (or `count` hosts) are connected. @throws {Error} On timeout. */
+    waitFor(hosts: readonly string[] | undefined, count: number, timeoutMs: number): Promise<void>;
+    /** Fails everything waiting for hosts to join (a shutdown). */
+    abortWaits(): void;
+    /** Hosts and the clusters running on them. */
+    status(declared?: readonly string[]): HostStatus[];
+    /**
+     * Starts a worker on `hostId`. If the host is not connected the returned
+     * child exits at once, which `ClusterManager` handles like a crash.
+     */
+    createChild(hostId: string, cluster: number, env: Record<string, string>): ChildProcess;
+}
+export {};

package/dist/sharding/requests.d.ts

@@ -0,0 +1,54 @@
+/** One answer collected for a request. */
+export interface Settled<R = unknown> {
+    key: string;
+    result?: R;
+    error?: string;
+}
+/** What a finished request collected. */
+export interface Collected<R = unknown> {
+    /** Answers by key, in arrival order. */
+    replies: Settled<R>[];
+    /** Keys that never answered (timeout, abort or shutdown). */
+    missing: string[];
+}
+/**
+ * Pending requests of the parent process. Each request waits for answers from
+ * a set of keys (a shard, a cluster, or every shard of the live clusters) and
+ * settles when all arrived, the timeout passed, or the caller aborted.
+ *
+ * Answers are accepted only from the owner of the key, once per key; late,
+ * duplicate and unknown answers are ignored. The number of waiting requests is
+ * bounded, and a timer per request guarantees the entry is removed.
+ */
+export declare class RequestTracker {
+    #private;
+    constructor(prefix?: string, maxPending?: number);
+    /** Requests waiting for answers. */
+    get size(): number;
+    /**
+     * Starts waiting for answers.
+     * @param keys Each key that should answer, with the cluster that owns it.
+     * @throws {Error} If `maxPending` requests are already waiting.
+     */
+    begin<R>(options: {
+        keys: ReadonlyMap<string, number>;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): {
+        id: string;
+        done: Promise<Collected<R>>;
+    };
+    /**
+     * Records one answer.
+     * @param from The cluster the answer came from; it must own `key`.
+     * @returns Whether the answer was accepted.
+     */
+    answer(id: string, key: string, from: number, value: {
+        result?: unknown;
+        error?: string;
+    }): boolean;
+    /** A cluster went away: every key it owns that has not answered settles with `error`. */
+    failOwner(owner: number, error: string): void;
+    /** Settles every waiting request with what it has (shutdown). */
+    close(): void;
+}

package/dist/sharding/worker.d.ts

@@ -0,0 +1,45 @@
+import { type ClusterContext } from "./context.js";
+import type { WorkerReport } from "./health.js";
+/** Asks for the right to IDENTIFY, and gives it back. */
+export interface IdentifyGate {
+    /** Resolves when `shardId` may IDENTIFY now. Rejects if the parent refuses or goes away. */
+    acquire(shardId: number): Promise<void>;
+    /** `shardId` has sent its IDENTIFY. */
+    release(shardId: number): void;
+}
+/** The part of `process` a worker uses. */
+export interface WorkerEndpoint {
+    send?(message: unknown): unknown;
+    on(event: string, listener: (...args: never[]) => void): unknown;
+    off(event: string, listener: (...args: never[]) => void): unknown;
+}
+type RequestHandler = (data: unknown) => unknown;
+/**
+ * The worker side of a cluster. It tells the parent when the process is
+ * ready, answers the parent's requests, and asks the parent for IDENTIFY
+ * slots. `ShardManager` uses it automatically inside a cluster; use it
+ * directly when you run your own Gateways.
+ */
+export declare class ClusterWorker {
+    #private;
+    /** The worker of this process, or `undefined` when it was not forked by a `ClusterManager`. */
+    static current(): ClusterWorker | undefined;
+    /** Forgets the process-wide worker (tests). */
+    static reset(): void;
+    readonly context: ClusterContext;
+    constructor(context: ClusterContext, endpoint?: WorkerEndpoint);
+    /** The gate to use when the parent coordinates IDENTIFY, otherwise `undefined`. */
+    get identifyGate(): IdentifyGate | undefined;
+    /** Tells the parent every shard of this process finished its handshake. */
+    ready(shardIds?: readonly number[]): void;
+    /** Pushes a health report to the parent without being asked. */
+    reportHealth(report: WorkerReport): void;
+    /**
+     * Answers requests of `type` sent with `ClusterManager.requestCluster()`.
+     * The return value (or thrown error) goes back to the caller.
+     */
+    onRequest(type: string, handler: RequestHandler): this;
+    /** Stops listening and rejects pending IDENTIFY requests. */
+    close(): void;
+}
+export {};

package/dist/structures/index.js

@@ -779,7 +779,7 @@ var mapHas = Map.prototype.has;
 // packages/rest/package.json
 var package_default = {
   name: "@lunibee/rest",
-  version: "0.3.0",
+  version: "0.3.1",
   type: "module",
   module: "./src/index.ts",
   types: "./src/index.ts",
@@ -2417,4 +2417,4 @@ export {
   stickerURL
 };
 
-//# debugId=CCB1FE6D82188C4D64756E2164756E21
+//# debugId=1F2A9DC9E180B64C64756E2164756E21