@helyx/bot 0.3.1 → 0.4.2

package/dist/shard-contracts.js

@@ -0,0 +1,445 @@
+import { z } from "zod";
+export const SHARD_CONTRACT_VERSION = 1;
+export const SHARD_CONTROL_MAX_BYTES = 64 * 1_024;
+export const SHARD_CONTROL_TIMEOUT_MS = 10_000;
+export const SHARD_HEALTH_STALE_MS = 30_000;
+export const SHARD_LEASE_HEARTBEAT_TIMEOUT_MS = 20_000;
+const snowflake = z.string().regex(/^\d{17,20}$/u);
+const safeIdentifier = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u);
+const dateTime = z.iso.datetime({ offset: true });
+const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+const mutationContext = z
+    .object({
+    actorUserId: snowflake,
+    correlationId: z.string().min(1).max(200),
+})
+    .strict();
+const permissionPolicy = z
+    .object({
+    preset: z.enum(["everyone", "moderators", "administrators", "custom"]),
+    allowedRoleIds: z.array(snowflake).max(100),
+    deniedRoleIds: z.array(snowflake).max(100),
+})
+    .strict();
+const permissionState = z
+    .object({
+    version: z.number().int().min(0),
+    module: permissionPolicy,
+    commands: z
+        .array(z
+        .object({
+        commandId: z.string().min(1).max(100),
+        version: z.number().int().min(0),
+        enabled: z.boolean(),
+        policy: permissionPolicy,
+    })
+        .strict())
+        .max(100),
+})
+    .strict();
+const configurationValue = z.record(z.string().min(1).max(100), z.union([
+    z.string().max(4_000),
+    z.boolean(),
+    z.number().finite(),
+    z.array(z.string().max(4_000)).max(100),
+]));
+export const shardIdentitySchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    mode: z.enum(["auto", "fixed"]),
+    scope: z.enum(["local", "coordinated"]),
+    generation: safeIdentifier,
+    deploymentOrder: z.number().int().positive().optional(),
+    supervisorId: z.uuid(),
+    shardId: z.number().int().min(0).max(4_095),
+    shardCount: z.number().int().min(1).max(4_096),
+    fencingToken: z.number().int().positive(),
+})
+    .strict()
+    .superRefine((identity, context) => {
+    if (identity.shardId >= identity.shardCount)
+        context.addIssue({
+            code: "custom",
+            path: ["shardId"],
+            message: "must be lower than shardCount",
+        });
+});
+export const gatewayBotInformationSchema = z
+    .object({
+    url: z.url(),
+    shards: z.number().int().min(1).max(4_096),
+    session_start_limit: z
+        .object({
+        total: z.number().int().min(1),
+        remaining: z.number().int().min(0),
+        reset_after: z.number().int().min(0),
+        max_concurrency: z.number().int().min(1),
+    })
+        .strict(),
+})
+    .strict();
+export const shardProcessHealthSchema = z
+    .object({
+    shardId: z.number().int().min(0).max(4_095),
+    status: z.enum([
+        "starting",
+        "ready",
+        "disconnected",
+        "reconnecting",
+        "stopped",
+        "failed",
+    ]),
+    guildCount: z.number().int().min(0),
+    gatewayPingMs: z.number().finite().min(-1).max(300_000),
+    uptimeSeconds: z.number().finite().min(0),
+    restartCount: z.number().int().min(0),
+    eventLoopDelayMs: z.number().finite().min(0).max(300_000),
+    memoryRssBytes: z.number().int().min(0),
+    queueDepth: z.number().int().min(0).max(10_000),
+    observedAt: dateTime,
+})
+    .strict();
+const sessionStartBudgetSchema = z
+    .object({
+    total: z.number().int().min(1),
+    remaining: z.number().int().min(0),
+    resetAt: dateTime,
+    maxConcurrency: z.number().int().min(1),
+    observedAt: dateTime,
+})
+    .strict();
+export const shardHealthSnapshotSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    mode: z.enum(["off", "auto", "fixed"]),
+    scope: z.enum(["local", "coordinated"]),
+    status: z.enum(["healthy", "degraded", "starting", "unavailable", "stale"]),
+    observedAt: dateTime,
+    generation: safeIdentifier,
+    supervisorId: z.uuid(),
+    configuredShardCount: z.number().int().min(1).max(4_096),
+    readyShardCount: z.number().int().min(0).max(4_096),
+    coordination: z
+        .object({
+        redis: z.enum(["not_required", "healthy", "degraded", "unavailable"]),
+        database: z.enum(["healthy", "degraded", "unavailable"]),
+    })
+        .strict(),
+    sessionStarts: sessionStartBudgetSchema.optional(),
+    shards: z.array(shardProcessHealthSchema).max(4_096),
+})
+    .strict()
+    .superRefine((health, context) => {
+    if (health.readyShardCount > health.configuredShardCount)
+        context.addIssue({
+            code: "custom",
+            path: ["readyShardCount"],
+            message: "cannot exceed configuredShardCount",
+        });
+    if (health.shards.some((shard) => shard.shardId >= health.configuredShardCount))
+        context.addIssue({
+            code: "custom",
+            path: ["shards"],
+            message: "contains a shard outside configuredShardCount",
+        });
+});
+export const shardControlOperationSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("guild.state.get"), guildId: snowflake }).strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.status.set"),
+        guildId: snowflake,
+        moduleId,
+        enabled: z.boolean(),
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.configuration.update"),
+        guildId: snowflake,
+        moduleId,
+        value: configurationValue,
+        expectedVersion: z.number().int().positive().nullable(),
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.permissions.update"),
+        guildId: snowflake,
+        moduleId,
+        state: permissionState,
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.logging.update"),
+        guildId: snowflake,
+        moduleId,
+        eventId: z.string().regex(/^[a-z][a-z0-9_-]*$/u),
+        enabled: z.boolean(),
+        expectedVersion: z.number().int().min(0),
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.action.execute"),
+        guildId: snowflake,
+        moduleId,
+        actionId: z.string().regex(/^[a-z][a-z0-9_-]*$/u),
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z.object({ kind: z.literal("privacy.providers.list") }).strict(),
+    z
+        .object({
+        kind: z.literal("privacy.capture"),
+        providerId: moduleId,
+        providerVersion: z.number().int().positive(),
+        requestId: z.uuid(),
+        subjectUserId: snowflake,
+        cutoffAt: dateTime,
+        cursor: z.string().min(1).max(2_048).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("privacy.erase"),
+        providerId: moduleId,
+        providerVersion: z.number().int().positive(),
+        requestId: z.uuid(),
+        subjectUserId: snowflake,
+        executeThrough: dateTime,
+        cursor: z.string().min(1).max(2_048).optional(),
+    })
+        .strict(),
+]);
+export const shardControlRequestSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.control.request"),
+    requestId: z.uuid(),
+    generation: safeIdentifier,
+    fencingToken: z.number().int().positive(),
+    deadlineAt: dateTime,
+    operation: shardControlOperationSchema,
+})
+    .strict();
+export const shardControlResponseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.control.response"),
+        requestId: z.uuid(),
+        ok: z.literal(true),
+        result: z.unknown(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.control.response"),
+        requestId: z.uuid(),
+        ok: z.literal(false),
+        status: z.number().int().min(400).max(599),
+        message: z.string().min(1).max(300),
+    })
+        .strict(),
+]);
+const shardCloudOperationSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("cloud.status") }).strict(),
+    z.object({ kind: z.literal("cloud.consent.get") }).strict(),
+    z
+        .object({
+        kind: z.literal("cloud.consent.update"),
+        supportInspectionEnabled: z.boolean(),
+        supportDataClasses: z.array(z.string().min(1).max(100)).max(5),
+        diagnosticsEnabled: z.boolean(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("cloud.enrol"),
+        token: z.string().min(1).max(200),
+        source: z.enum(["discord", "file", "startup"]),
+    })
+        .strict(),
+    z.object({ kind: z.literal("cloud.disconnect") }).strict(),
+    z.object({ kind: z.literal("cloud.rotate") }).strict(),
+]);
+export const shardCloudRequestSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.cloud.request"),
+    requestId: z.uuid(),
+    deadlineAt: dateTime,
+    operation: shardCloudOperationSchema,
+})
+    .strict();
+export const shardCloudResponseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.cloud.response"),
+        requestId: z.uuid(),
+        ok: z.literal(true),
+        result: z.unknown(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.cloud.response"),
+        requestId: z.uuid(),
+        ok: z.literal(false),
+        message: z.string().min(1).max(300),
+    })
+        .strict(),
+]);
+export const shardOperationsHealthRequestSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.operations.health.request"),
+    requestId: z.uuid(),
+    deadlineAt: dateTime,
+})
+    .strict();
+export const shardOperationsHealthResponseSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.operations.health.response"),
+    requestId: z.uuid(),
+    health: shardHealthSnapshotSchema,
+})
+    .strict();
+export const supervisorMessageSchema = z.discriminatedUnion("type", [
+    shardControlRequestSchema,
+    shardCloudResponseSchema,
+    shardOperationsHealthResponseSchema,
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.lease.heartbeat"),
+        identity: shardIdentitySchema,
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.health.request"),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.shutdown"),
+        reason: z.string().min(1).max(100),
+    })
+        .strict(),
+]);
+export const workerMessageSchema = z.discriminatedUnion("type", [
+    shardControlResponseSchema,
+    shardCloudRequestSchema,
+    shardOperationsHealthRequestSchema,
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.health.update"),
+        identity: shardIdentitySchema,
+        health: shardProcessHealthSchema,
+    })
+        .strict(),
+]);
+export function guildIdToShardId(guildId, shardCount) {
+    const parsedGuildId = snowflake.parse(guildId);
+    if (!Number.isSafeInteger(shardCount) || shardCount < 1 || shardCount > 4_096)
+        throw new Error("Shard count must be an integer between 1 and 4096");
+    return Number((BigInt(parsedGuildId) >> 22n) % BigInt(shardCount));
+}
+export function controlOperationGuildId(operation) {
+    return "guildId" in operation ? operation.guildId : undefined;
+}
+export function assertShardMessageSize(value) {
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > SHARD_CONTROL_MAX_BYTES)
+        throw new Error("Shard control message exceeds the byte limit");
+}
+export async function executeShardControlOperation(handler, operation) {
+    switch (operation.kind) {
+        case "guild.state.get":
+            return handler.getGuildState(operation.guildId);
+        case "guild.module.status.set": {
+            return handler.setModuleStatus({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                enabled: operation.enabled,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
+        case "guild.module.configuration.update": {
+            return handler.updateConfiguration({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                value: operation.value,
+                expectedVersion: operation.expectedVersion,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
+        case "guild.module.permissions.update": {
+            return handler.updatePermissions({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                state: operation.state,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
+        case "guild.module.logging.update": {
+            return handler.updateLoggingPolicy({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                eventId: operation.eventId,
+                enabled: operation.enabled,
+                expectedVersion: operation.expectedVersion,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
+        case "guild.module.action.execute": {
+            return handler.executeDashboardAction({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                actionId: operation.actionId,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
+        case "privacy.providers.list":
+            return handler.listPrivacyProviders();
+        case "privacy.capture": {
+            return handler.capturePrivacy({
+                providerId: operation.providerId,
+                providerVersion: operation.providerVersion,
+                requestId: operation.requestId,
+                subjectUserId: operation.subjectUserId,
+                cutoffAt: new Date(operation.cutoffAt),
+                ...(operation.cursor === undefined ? {} : { cursor: operation.cursor }),
+            });
+        }
+        case "privacy.erase": {
+            return handler.erasePrivacy({
+                providerId: operation.providerId,
+                providerVersion: operation.providerVersion,
+                requestId: operation.requestId,
+                subjectUserId: operation.subjectUserId,
+                executeThrough: new Date(operation.executeThrough),
+                ...(operation.cursor === undefined ? {} : { cursor: operation.cursor }),
+            });
+        }
+    }
+}
+//# sourceMappingURL=shard-contracts.js.map

package/dist/shard-coordinator.d.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { type ShardControlRequest, type ShardControlResponse, type ShardCloudRequest, type ShardCloudResponse, type ShardIdentity, type ShardProcessHealth } from "./shard-contracts.js";
+declare const generationDescriptorSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    applicationId: z.ZodString;
+    environment: z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>;
+    generation: z.ZodString;
+    shardCount: z.ZodNumber;
+    catalogueHash: z.ZodString;
+}, z.core.$strict>;
+export type ShardGenerationDescriptor = z.infer<typeof generationDescriptorSchema>;
+declare const leaseSchema: z.ZodObject<{
+    generation: z.ZodString;
+    deploymentOrder: z.ZodNumber;
+    supervisorId: z.ZodUUID;
+    shardId: z.ZodNumber;
+    fencingToken: z.ZodNumber;
+}, z.core.$strict>;
+export type ShardLease = z.infer<typeof leaseSchema>;
+declare const leaderLeaseSchema: z.ZodObject<{
+    generation: z.ZodString;
+    supervisorId: z.ZodUUID;
+    fencingToken: z.ZodNumber;
+}, z.core.$strict>;
+export type ShardLeaderLease = z.infer<typeof leaderLeaseSchema>;
+export interface ShardCoordinator {
+    readonly supervisorId: ReturnType<typeof randomUUID>;
+    start(handler: (targetShardId: number, request: ShardControlRequest) => Promise<ShardControlResponse>, leaderHandler?: (request: ShardControlRequest) => Promise<ShardControlResponse>, cloudHandler?: (request: ShardCloudRequest) => Promise<ShardCloudResponse>): Promise<void>;
+    checkReady(): Promise<void>;
+    assertGeneration(descriptor: ShardGenerationDescriptor, proposedDeploymentOrder: number): Promise<number>;
+    refreshGeneration(descriptor: ShardGenerationDescriptor, deploymentOrder: number): Promise<boolean>;
+    claimShard(descriptor: ShardGenerationDescriptor, shardId: number, deploymentOrder: number): Promise<ShardLease | undefined>;
+    renewShard(lease: ShardLease): Promise<boolean>;
+    releaseShard(lease: ShardLease): Promise<boolean>;
+    getShardLease(shardId: number): Promise<ShardLease | undefined>;
+    getShardLeases(shardCount: number): Promise<ShardLease[]>;
+    acquireLeader(descriptor: ShardGenerationDescriptor, deploymentOrder: number): Promise<ShardLeaderLease | undefined>;
+    renewLeader(lease: ShardLeaderLease): Promise<boolean>;
+    releaseLeader(lease: ShardLeaderLease): Promise<boolean>;
+    getLeaderLease(): Promise<ShardLeaderLease | undefined>;
+    routeRemote(lease: ShardLease, request: ShardControlRequest): Promise<ShardControlResponse>;
+    routeLeader(lease: ShardLeaderLease, request: ShardControlRequest): Promise<ShardControlResponse>;
+    routeLeaderCloud(lease: ShardLeaderLease, request: ShardCloudRequest): Promise<ShardCloudResponse>;
+    reserveSessionStarts(count: number, available: number, resetAfterMs: number): Promise<boolean>;
+    acquireIdentifyPermit(shardId: number, maxConcurrency: number, timeoutMs: number): Promise<boolean>;
+    setHealth(identity: ShardIdentity, health: ShardProcessHealth): Promise<void>;
+    getHealth(shardCount: number): Promise<Array<{
+        identity: ShardIdentity;
+        health: ShardProcessHealth;
+    }>>;
+    stop(): Promise<void>;
+}
+export declare class RedisShardCoordinator implements ShardCoordinator {
+    #private;
+    readonly supervisorId: `${string}-${string}-${string}-${string}-${string}`;
+    constructor(redisUrl: string, namespace: string, options?: {
+        onError?: (error: Error) => void;
+    });
+    start(handler: (targetShardId: number, request: ShardControlRequest) => Promise<ShardControlResponse>, leaderHandler?: (request: ShardControlRequest) => Promise<ShardControlResponse>, cloudHandler?: (request: ShardCloudRequest) => Promise<ShardCloudResponse>): Promise<void>;
+    checkReady(): Promise<void>;
+    assertGeneration(descriptor: ShardGenerationDescriptor, proposedDeploymentOrder: number): Promise<number>;
+    refreshGeneration(descriptor: ShardGenerationDescriptor, deploymentOrder: number): Promise<boolean>;
+    claimShard(descriptor: ShardGenerationDescriptor, shardId: number, deploymentOrder: number): Promise<ShardLease | undefined>;
+    renewShard(lease: ShardLease): Promise<boolean>;
+    releaseShard(lease: ShardLease): Promise<boolean>;
+    getShardLease(shardId: number): Promise<ShardLease | undefined>;
+    getShardLeases(shardCount: number): Promise<ShardLease[]>;
+    acquireLeader(descriptor: ShardGenerationDescriptor, deploymentOrder: number): Promise<ShardLeaderLease | undefined>;
+    renewLeader(lease: ShardLeaderLease): Promise<boolean>;
+    releaseLeader(lease: ShardLeaderLease): Promise<boolean>;
+    getLeaderLease(): Promise<ShardLeaderLease | undefined>;
+    routeRemote(lease: ShardLease, request: ShardControlRequest): Promise<ShardControlResponse>;
+    routeLeader(lease: ShardLeaderLease, request: ShardControlRequest): Promise<ShardControlResponse>;
+    routeLeaderCloud(lease: ShardLeaderLease, request: ShardCloudRequest): Promise<ShardCloudResponse>;
+    reserveSessionStarts(count: number, available: number, resetAfterMs: number): Promise<boolean>;
+    acquireIdentifyPermit(shardId: number, maxConcurrency: number, timeoutMs: number): Promise<boolean>;
+    setHealth(identity: ShardIdentity, health: ShardProcessHealth): Promise<void>;
+    getHealth(shardCount: number): Promise<Array<{
+        identity: ShardIdentity;
+        health: ShardProcessHealth;
+    }>>;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=shard-coordinator.d.ts.map