lunibee 0.3.0 → 0.3.2

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,134 @@
+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 3,000. */
+    helloTimeout?: number;
+    /**
+     * Most connections that may be waiting to authenticate at once. When full,
+     * the one that has waited longest is closed to make room: a host answers
+     * the challenge within a round trip, a connection that holds a slot idle
+     * does not. Default 16.
+     */
+    maxUnauthenticated?: number;
+    /** The same limit for one client address (see `clientAddress`). Default 4. */
+    maxUnauthenticatedPerAddress?: number;
+    /** New connections one client address may open per second; more are refused. Default 10. */
+    connectionsPerSecond?: number;
+    /**
+     * The client address the per-address limits count by. Default: the peer
+     * address of the TCP connection. Behind a TLS proxy every peer is the
+     * proxy, so return the client address the proxy forwards (only from a
+     * header your proxy sets and overwrites).
+     */
+    clientAddress?: (request: Request, peer: string | undefined) => string;
+    /** 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/supervisor.d.ts

@@ -4,7 +4,7 @@ export interface SupervisorOptions {
     restartDelay?: number;
     /** Each further crash in the window multiplies the delay by this (default 1: a fixed delay). */
     backoff?: number;
-    /** The longest delay (default 5 minutes). */
+    /** The longest delay, jitter included (default 5 minutes). */
     maxDelay?: number;
     /** Random spread added to each delay, as a fraction of it (0-1, default 0). */
     jitter?: number;

package/dist/sharding/transport.d.ts

@@ -28,14 +28,15 @@ export interface IpcEndpoint {
     on(event: "message", listener: (message: unknown) => void): unknown;
     off(event: "message", listener: (message: unknown) => void): unknown;
 }
-/**
- * Forked clusters: a worker `send()`s to its parent, and the parent
- * ({@link ClusterManager}) relays to every other worker. Selected
- * automatically in a worker forked by `ClusterManager`.
- */
 export declare class IpcTransport implements ShardBusTransport {
     #private;
     constructor(endpoint?: IpcEndpoint);
+    /**
+     * Sends to the parent, which relays to other clusters, and delivers to the
+     * other buses in this process: the parent never sends a message back to the
+     * cluster it came from, so without this a shard could not reach a shard in
+     * its own worker. Each bus drops what is not addressed to it.
+     */
     post(message: ShardMessage): void;
     onMessage(listener: (message: ShardMessage) => void): void;
     onPeerDown(listener: (shardIds: readonly number[]) => void): void;

package/dist/sharding/worker.d.ts

@@ -0,0 +1,55 @@
+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, options?: {
+        /**
+         * Exit when the parent's IPC channel closes. Without a parent
+         * nothing coordinates IDENTIFY or fences this process, and its
+         * Gateway sessions would keep running beside a replacement.
+         * Default: true for the real process, false for an injected endpoint.
+         */
+        exitOnParentLoss?: boolean;
+        /** Replaces `process.exit`; for tests. */
+        exit?: (code: number) => void;
+    });
+    /** 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/base.d.ts

@@ -11,6 +11,7 @@ export declare class BaseStructure {
     /** Returns the timestamp this snowflake was created at. */
     get createdAt(): Date;
 }
+/** What a structure uses to act on Discord (send, edit, fetch, compute permissions). `Client` supplies it; tests can supply their own. */
 export interface ResourceContext {
     sendMessage(channelId: string, options: MessageCreateOptions): Promise<import("./index.js").Message>;
     editMessage(channelId: string, messageId: string, options: MessageEditOptions): Promise<import("./index.js").Message>;
@@ -29,7 +30,9 @@ export interface ResourceContext {
      * (with overwrites) when a channel ID is given. Null when the guild (or
      * channel) is not cached.
      */
-    memberPermissions?(guildId: string, memberId: string, roleIds: readonly string[], channelId?: string, timedOutUntil?: Date | null): import("@lunibee/core").PermissionSet | null;
+    /** The cached channel, when the client has a complete one (not a partial placeholder). */
+    cachedChannel?(channelId: string): Channel | undefined;
+    memberPermissions?(guildId: string, memberId: string, roleIds: readonly string[], channelId?: string, timedOutUntil?: Date | null): import("./permissions.js").PermissionSet | null;
     kickMember?(guildId: string, userId: string, reason?: string): Promise<void>;
     banMember?(guildId: string, userId: string, options?: {
         reason?: string;
@@ -49,7 +52,7 @@ export interface ResourceContext {
  * Permissions to change on one overwrite: `true` allows, `false` denies,
  * `null` goes back to inheriting. Permissions not named keep their state.
  */
-export type PermissionOverwriteChanges = Partial<Record<import("@lunibee/core").PermissionName, boolean | null>>;
+export type PermissionOverwriteChanges = Partial<Record<import("./permissions.js").PermissionName, boolean | null>>;
 export declare const CDN_BASE = "https://cdn.discordapp.com";
 /** Options for CDN image URLs. */
 export interface ImageURLOptions {
@@ -94,8 +97,16 @@ export declare class Channel extends BaseStructure {
     position?: number;
     /** Role and member permission overwrites (empty for DMs and when not provided). */
     permissionOverwrites: import("@lunibee/types").APIOverwrite[];
-    /** Creates a channel structure from Discord channel data. */
-    constructor(data: import("@lunibee/types").APIChannel, context?: ResourceContext);
+    /**
+     * A placeholder built from a message's `channel_id`, not from channel
+     * data: its `type`, `name`, `parentId` and `permissionOverwrites` are not
+     * the real channel's, so nothing may decide access from them.
+     */
+    partial: boolean;
+    /** Creates a channel structure from Discord channel data. `options.partial` marks a placeholder. */
+    constructor(data: import("@lunibee/types").APIChannel, context?: ResourceContext, options?: {
+        partial?: boolean;
+    });
     /** Sends a message to this channel. @param options Message payload. @returns The created message. @throws {Error} If the channel is not attached to a client. */
     send(options: MessageCreateOptions): Promise<import("./index.js").Message>;
     /** Edits this channel. @param options Channel fields to change. @returns The updated channel. @throws {Error} If the channel is not attached to a client. */
@@ -125,7 +136,7 @@ export declare class Channel extends BaseStructure {
     get kind(): ChannelKind | UnknownChannelKind;
     /**
      * Whether this channel is one of `kinds`, narrowing its type to match.
-     * @example if (channel.is("text", "announcement")) await channel.send("hi");
+     * @example if (channel.is("text", "announcement")) await channel.send({ content: "hi" });
      */
     is<K extends ChannelKind | UnknownChannelKind>(...kinds: K[]): this is ChannelOfKind<K>;
     /**

package/dist/structures/index.d.ts

@@ -116,4 +116,4 @@ export * from "./interactions.js";
 export { Embed } from "./embed.js";
 export { AuditLog, AuditLogEntry, type AuditLogAutoModInfo, type AuditLogInfo, type AuditLogInfoByType, type AuditLogOverwriteInfo, type AuditLogQuery, } from "./audit-log.js";
 export { Sticker, stickerURL } from "./sticker.js";
-export { PermissionsBitField } from "@lunibee/core";
+export { Permission, Permissions, PermissionFlagsBits, PermissionSet, PermissionsBitField, PermissionOverwriteEnum, computePermissions, type PermissionContext, type PermissionOverwrite, type PermissionRole, type PermissionName, type PermissionResolvable, } from "./permissions.js";