@helyx/bot 0.3.0 → 0.4.1

package/dist/shard-router.js

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import { BotControlTransportError, } from "./control-server.js";
+import { SHARD_CONTROL_TIMEOUT_MS, controlOperationGuildId, guildIdToShardId, shardControlOperationSchema, shardControlResponseSchema, } from "./shard-contracts.js";
+const LEASE_VALIDATION_TIMEOUT_MS = 1_000;
+export class ShardControlRouter {
+    input;
+    constructor(input) {
+        this.input = input;
+    }
+    getGuildState(guildId) {
+        return this.#route({ kind: "guild.state.get", guildId });
+    }
+    setModuleStatus(input) {
+        return this.#route({ kind: "guild.module.status.set", ...input });
+    }
+    updateConfiguration(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.configuration.update",
+            ...input,
+        }));
+    }
+    updatePermissions(input) {
+        return this.#route({ kind: "guild.module.permissions.update", ...input });
+    }
+    updateLoggingPolicy(input) {
+        return this.#route({ kind: "guild.module.logging.update", ...input });
+    }
+    executeDashboardAction(input) {
+        return this.#route({ kind: "guild.module.action.execute", ...input });
+    }
+    listPrivacyProviders() {
+        return this.#routeLeader({ kind: "privacy.providers.list" });
+    }
+    capturePrivacy(input) {
+        const { cutoffAt, ...rest } = input;
+        return this.#routeLeader({
+            kind: "privacy.capture",
+            ...rest,
+            cutoffAt: cutoffAt.toISOString(),
+        });
+    }
+    erasePrivacy(input) {
+        const { executeThrough, ...rest } = input;
+        return this.#routeLeader({
+            kind: "privacy.erase",
+            ...rest,
+            executeThrough: executeThrough.toISOString(),
+        });
+    }
+    async #route(operation) {
+        const guildId = controlOperationGuildId(operation);
+        if (!guildId)
+            throw new BotControlTransportError(502, "The control operation has no shard route");
+        const shardId = guildIdToShardId(guildId, this.input.shardCount);
+        const localLease = this.input.localLeases.get(shardId);
+        let lease = localLease;
+        if (localLease && this.input.coordinator) {
+            const current = await this.#currentShardLease(shardId);
+            if (!current || !sameShardLease(localLease, current))
+                throw new BotControlTransportError(503, "The owning shard is temporarily unavailable");
+            lease = current;
+        }
+        else if (!lease && this.input.coordinator) {
+            lease = await this.#currentShardLease(shardId);
+        }
+        if (!lease || lease.generation !== this.input.generation)
+            throw new BotControlTransportError(503, "The owning shard is temporarily unavailable");
+        const request = {
+            version: 1,
+            type: "helyx.control.request",
+            requestId: randomUUID(),
+            generation: this.input.generation,
+            fencingToken: lease.fencingToken,
+            deadlineAt: new Date(Date.now() + SHARD_CONTROL_TIMEOUT_MS).toISOString(),
+            operation,
+        };
+        let response;
+        try {
+            response = localLease
+                ? await withDeadline(this.input.dispatchLocal(shardId, request), SHARD_CONTROL_TIMEOUT_MS)
+                : await this.input.coordinator.routeRemote(lease, request);
+        }
+        catch (error) {
+            const timedOut = error instanceof Error &&
+                error.message.toLowerCase().includes("timed out");
+            throw new BotControlTransportError(timedOut ? 504 : 503, timedOut
+                ? "The owning shard did not respond in time"
+                : "The owning shard is temporarily unavailable");
+        }
+        return unwrapResponse(response);
+    }
+    async #routeLeader(operation) {
+        if (this.input.localLeaderLease && this.input.privacy) {
+            if (this.input.coordinator) {
+                const current = await this.#currentLeaderLease();
+                if (!current || !sameLeaderLease(this.input.localLeaderLease, current))
+                    throw new BotControlTransportError(503, "The shard leader is temporarily unavailable");
+            }
+            return executePrivacy(this.input.privacy, operation);
+        }
+        const coordinator = this.input.coordinator;
+        const lease = await this.#currentLeaderLease();
+        if (!coordinator || !lease || lease.generation !== this.input.generation)
+            throw new BotControlTransportError(503, "The shard leader is temporarily unavailable");
+        const request = {
+            version: 1,
+            type: "helyx.control.request",
+            requestId: randomUUID(),
+            generation: this.input.generation,
+            fencingToken: lease.fencingToken,
+            deadlineAt: new Date(Date.now() + SHARD_CONTROL_TIMEOUT_MS).toISOString(),
+            operation,
+        };
+        try {
+            return unwrapResponse(await coordinator.routeLeader(lease, request));
+        }
+        catch (error) {
+            if (error instanceof BotControlTransportError)
+                throw error;
+            throw new BotControlTransportError(error instanceof Error &&
+                error.message.toLowerCase().includes("timed out")
+                ? 504
+                : 503, "The shard leader is temporarily unavailable");
+        }
+    }
+    async #currentShardLease(shardId) {
+        try {
+            return await withDeadline(this.input.coordinator.getShardLease(shardId), LEASE_VALIDATION_TIMEOUT_MS);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #currentLeaderLease() {
+        if (!this.input.coordinator)
+            return undefined;
+        try {
+            return await withDeadline(this.input.coordinator.getLeaderLease(), LEASE_VALIDATION_TIMEOUT_MS);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+async function executePrivacy(privacy, operation) {
+    if (operation.kind === "privacy.providers.list")
+        return (await privacy.listPrivacyProviders());
+    if (operation.kind === "privacy.capture") {
+        return (await privacy.capturePrivacy({
+            providerId: operation.providerId,
+            providerVersion: operation.providerVersion,
+            requestId: operation.requestId,
+            subjectUserId: operation.subjectUserId,
+            cutoffAt: new Date(operation.cutoffAt),
+            ...(operation.cursor === undefined ? {} : { cursor: operation.cursor }),
+        }));
+    }
+    if (operation.kind === "privacy.erase") {
+        return (await privacy.erasePrivacy({
+            providerId: operation.providerId,
+            providerVersion: operation.providerVersion,
+            requestId: operation.requestId,
+            subjectUserId: operation.subjectUserId,
+            executeThrough: new Date(operation.executeThrough),
+            ...(operation.cursor === undefined ? {} : { cursor: operation.cursor }),
+        }));
+    }
+    throw new BotControlTransportError(502, "The leader operation is invalid");
+}
+function unwrapResponse(response) {
+    const accepted = shardControlResponseSchema.parse(response);
+    if (!accepted.ok)
+        throw new BotControlTransportError(accepted.status === 400 ||
+            accepted.status === 404 ||
+            accepted.status === 409 ||
+            accepted.status === 504
+            ? accepted.status
+            : accepted.status >= 500
+                ? 503
+                : 502, accepted.message);
+    return accepted.result;
+}
+function sameShardLease(left, right) {
+    return (left.generation === right.generation &&
+        left.deploymentOrder === right.deploymentOrder &&
+        left.supervisorId === right.supervisorId &&
+        left.shardId === right.shardId &&
+        left.fencingToken === right.fencingToken);
+}
+function sameLeaderLease(left, right) {
+    return (left.generation === right.generation &&
+        left.supervisorId === right.supervisorId &&
+        left.fencingToken === right.fencingToken);
+}
+async function withDeadline(operation, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error("Shard control request timed out")), timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=shard-router.js.map

package/dist/shard-supervisor.d.ts

@@ -0,0 +1,36 @@
+import type { BotEnvironment } from "@helyx/config";
+import { type DatabasePool } from "@helyx/database";
+import type { ModuleDefinition } from "@helyx/sdk";
+import { type ShardCloudRequest, type ShardIdentity, type ShardProcessHealth } from "./shard-contracts.js";
+import { type ShardCoordinator, type ShardGenerationDescriptor, type ShardLeaderLease, type ShardLease } from "./shard-coordinator.js";
+import type { BotHandle } from "./index.js";
+export declare const STEADY_STATE_LEASE_LOSS_BOUND_MS: number;
+export declare function startShardSupervisor(environment: BotEnvironment, processEnvironment: NodeJS.ProcessEnv, workerEntry: string): Promise<BotHandle>;
+export declare function buildShardWorkerEnvironment(source: NodeJS.ProcessEnv, identity: ShardIdentity, restartCount: number): NodeJS.ProcessEnv;
+export declare function shardRuntimeCompositionHash(modules: readonly ModuleDefinition[], internalGuildId?: string): string;
+export declare function boundedRespawnDelay(attempt: number): number;
+export interface SteadyStateOwnershipRenewal {
+    generationRenewed: boolean;
+    lostShardIds: number[];
+    leaderRenewed: boolean;
+    leaderAvailable: boolean;
+}
+export declare function selectFencedShardHealth(input: {
+    generation: string;
+    shardCount: number;
+    coordinatedHealth: ReadonlyArray<{
+        identity: ShardIdentity;
+        health: ShardProcessHealth;
+    }>;
+    liveLeases: readonly ShardLease[];
+    localHealth: ReadonlyMap<number, ShardProcessHealth>;
+    localLeases: ReadonlyMap<number, ShardLease>;
+    coordinated: boolean;
+}): Map<number, ShardProcessHealth>;
+export declare function renewSteadyStateOwnership(coordinator: Pick<ShardCoordinator, "refreshGeneration" | "renewShard" | "renewLeader" | "getLeaderLease">, descriptor: ShardGenerationDescriptor, deploymentOrder: number, shardLeases: ReadonlyMap<number, ShardLease>, leaderLease?: ShardLeaderLease, timeoutMs?: number): Promise<SteadyStateOwnershipRenewal>;
+export declare function acquireFencedLeader(coordinator: Pick<ShardCoordinator, "acquireLeader">, descriptor: ShardGenerationDescriptor, deploymentOrder: number, timeoutMs?: number): Promise<ShardLeaderLease | undefined>;
+export declare function cloudRequestExpired(request: ShardCloudRequest): boolean;
+export declare function spawnWithShutdownGuard(isShuttingDown: () => boolean, spawn: () => Promise<unknown>, kill: () => void): Promise<boolean>;
+export declare function nextShardDeploymentOrder(database: DatabasePool): Promise<number>;
+export declare function renewStartupOwnership(coordinator: Pick<ShardCoordinator, "refreshGeneration" | "renewLeader">, descriptor: ShardGenerationDescriptor, deploymentOrder: number, leaderLease?: ShardLeaderLease): Promise<void>;
+//# sourceMappingURL=shard-supervisor.d.ts.map