@helyx/bot 0.4.1 → 0.4.4

package/dist/shard-router.js

@@ -28,6 +28,63 @@ export class ShardControlRouter {
     executeDashboardAction(input) {
         return this.#route({ kind: "guild.module.action.execute", ...input });
     }
+    listManagedResources(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.resource.list",
+            ...input,
+        }));
+    }
+    readManagedResource(input) {
+        return this.#route({
+            kind: "guild.module.resource.read",
+            ...input,
+        });
+    }
+    listManagedResourceRelation(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.resource.relation.list",
+            ...input,
+        }));
+    }
+    previewManagedResource(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.resource.preview",
+            ...input,
+        }));
+    }
+    createManagedResource(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.resource.create",
+            ...input,
+        }));
+    }
+    updateManagedResource(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.resource.update",
+            ...input,
+        }));
+    }
+    deleteManagedResource(input) {
+        return this.#route({
+            kind: "guild.module.resource.delete",
+            ...input,
+        });
+    }
+    executeManagedResourceAction(input) {
+        return this.#route({
+            kind: "guild.module.resource.action.execute",
+            ...input,
+        });
+    }
+    sendSupportNotification(input) {
+        if (!this.input.notificationGuildId)
+            throw new BotControlTransportError(404, "The support notification channel is not configured");
+        return this.#route({
+            kind: "support.notification.send",
+            guildId: this.input.notificationGuildId,
+            ...input,
+        });
+    }
     listPrivacyProviders() {
         return this.#routeLeader({ kind: "privacy.providers.list" });
     }
@@ -171,6 +228,7 @@ function unwrapResponse(response) {
     const accepted = shardControlResponseSchema.parse(response);
     if (!accepted.ok)
         throw new BotControlTransportError(accepted.status === 400 ||
+            accepted.status === 403 ||
             accepted.status === 404 ||
             accepted.status === 409 ||
             accepted.status === 504

package/dist/shard-supervisor.d.ts

@@ -1,10 +1,11 @@
 import type { BotEnvironment } from "@helyx/config";
 import { type DatabasePool } from "@helyx/database";
-import type { ModuleDefinition } from "@helyx/sdk";
+import type { ModuleDefinition, ScheduledTaskExecutionResult } 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 deferScheduledRoutingFailures(route: () => Promise<ScheduledTaskExecutionResult>): Promise<ScheduledTaskExecutionResult>;
 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;

package/dist/shard-supervisor.js

@@ -13,13 +13,15 @@ import { BotControlService, createBotControlServer, mapBotControlError, } from "
 import { createManagementModule } from "./management-module.js";
 import { buildApplicationCommandDefinitions } from "./interactions.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
-import { loadConfiguredModulePackages } from "./modules.js";
+import { deriveSecureRandomSelectionKey, loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
 import { createPermissionsModule } from "./permissions-module.js";
-import { SHARD_CONTROL_MAX_BYTES, SHARD_HEALTH_STALE_MS, assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, gatewayBotInformationSchema, shardCloudRequestSchema, shardHealthSnapshotSchema, workerMessageSchema, } from "./shard-contracts.js";
+import { SHARD_CONTROL_MAX_BYTES, SHARD_HEALTH_STALE_MS, assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, gatewayBotInformationSchema, guildIdToShardId, shardCloudRequestSchema, shardHealthSnapshotSchema, workerMessageSchema, } from "./shard-contracts.js";
 import { RedisShardCoordinator, } from "./shard-coordinator.js";
 import { ShardControlRouter } from "./shard-router.js";
 import { createDeveloperOperationsModule } from "./developer-operations-module.js";
 import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js";
+import { createSupportModule } from "./support-module.js";
+import { createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
 const LEASE_RENEW_INTERVAL_MS = 10_000;
 const STARTUP_LEASE_RENEW_INTERVAL_MS = 5_000;
 const LEASE_VALIDATION_TIMEOUT_MS = 1_000;
@@ -29,6 +31,18 @@ const WORKER_SHUTDOWN_MS = 5_000;
 const MAX_RESTARTS_PER_WINDOW = 5;
 const RESTART_WINDOW_MS = 10 * 60 * 1_000;
 export const STEADY_STATE_LEASE_LOSS_BOUND_MS = LEASE_RENEW_INTERVAL_MS + LEASE_VALIDATION_TIMEOUT_MS + WORKER_SHUTDOWN_MS;
+export async function deferScheduledRoutingFailures(route) {
+    try {
+        return await route();
+    }
+    catch {
+        return {
+            outcome: "deferred",
+            delayMs: 1_000,
+            safeCode: "routing_unavailable",
+        };
+    }
+}
 export async function startShardSupervisor(environment, processEnvironment, workerEntry) {
     if (environment.HELYX_SHARD_MODE === "off")
         throw new Error("Shard supervisor requires sharding to be enabled");
@@ -65,6 +79,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     const localLeases = new Map();
     const healthByShard = new Map();
     const pendingControl = new Map();
+    const pendingScheduled = new Map();
     const restartHistory = new Map();
     const restartCounts = new Map();
     const workers = new Map();
@@ -75,6 +90,9 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let shardCount = 1;
     let privacyService;
     let manager;
+    let scheduledTasks;
+    let scheduledModules = [];
+    let workersRoutable = false;
     let promoteToLeader = () => Promise.resolve(false);
     try {
         await checkDatabaseConnection(database);
@@ -112,6 +130,9 @@ export async function startShardSupervisor(environment, processEnvironment, work
             getGuildResources: () => Promise.reject(new Error("Guild resources are worker-owned")),
             sendToChannel: () => Promise.reject(new Error("Guild resources are worker-owned")),
             deleteChannelMessage: () => Promise.reject(new Error("Guild resources are worker-owned")),
+            editChannelMessage: () => Promise.reject(new Error("Guild resources are worker-owned")),
+            addChannelMessageReaction: () => Promise.reject(new Error("Guild resources are worker-owned")),
+            resolveActor: () => Promise.reject(new Error("Guild resources are worker-owned")),
         };
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, unavailableResources);
@@ -123,12 +144,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 configuredOwnerUserIds: environment.HELYX_OWNER_USER_IDS,
             })
             : undefined;
+        const supportModule = createSupportModule(cloudConnector);
         const publicModules = [
             managementModule,
             permissionsModule,
+            supportModule,
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
         ];
+        scheduledModules = publicModules;
         const operationsModule = environment.DISCORD_INTERNAL_GUILD_ID
             ? createDeveloperOperationsModule({
                 internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
@@ -142,6 +166,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 coreFunctions: [
                     managementModule,
                     permissionsModule,
+                    supportModule,
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
                 modules: featureModules.map(({ manifest }) => manifest),
@@ -160,7 +185,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             assertStartupLeaseHealthy();
             privacyDatabase = await createPrivacyDatabase(environment, database);
             assertStartupLeaseHealthy();
-            const services = new Map(createPlatformServices(database, publicModules));
+            const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
             privacyService = new BotControlService(database, publicModules, unavailableResources, new ServiceRegistry(services), privacyDatabase
                 ? new PostgresPrivacyProviderExecutor({
                     readPool: database,
@@ -176,6 +201,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 privacy: privacyService,
                 localLeaderLease: leaderLease,
                 ...(coordinator ? { coordinator } : {}),
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? {
+                        notificationGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
+                    }
+                    : {}),
             }));
             await startLeaderSingletons();
             assertStartupLeaseHealthy();
@@ -194,7 +224,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 onError: (error) => logger.error({ event: "shard.redis_error", error: safeError(error) }, "Shard coordination failed"),
             });
             supervisorId = coordinator.supervisorId;
-            await coordinator.start((targetShardId, request) => dispatchLocal(targetShardId, request), (request) => executeLeaderControl(request), (request) => executeLeaderCloud(request));
+            await coordinator.start((targetShardId, request) => dispatchLocal(targetShardId, request), (request) => executeLeaderControl(request), (request) => executeLeaderCloud(request), (targetShardId, request) => dispatchLocalScheduled(targetShardId, request));
             deploymentOrder = await coordinator.assertGeneration(generationDescriptor, deploymentOrder);
             leaderLease = await coordinator.acquireLeader(generationDescriptor, deploymentOrder);
             startStartupLeaseMaintenance();
@@ -249,6 +279,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
             ...(privacyService ? { privacy: privacyService } : {}),
             ...(leaderLease ? { localLeaderLease: leaderLease } : {}),
             ...(coordinator ? { coordinator } : {}),
+            ...(environment.DISCORD_INTERNAL_GUILD_ID
+                ? {
+                    notificationGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
+                }
+                : {}),
         });
         if (!leaderLease)
             cloudConnector.setControlHandler(router);
@@ -263,6 +298,9 @@ export async function startShardSupervisor(environment, processEnvironment, work
         });
         await reserveInitialSessionStarts(claimedIds.length, gateway);
         await spawnInIdentifyBuckets(claimedIds, gateway.session_start_limit.max_concurrency);
+        workersRoutable = true;
+        if (leaderLease)
+            startScheduledTasks();
         assertStartupLeaseHealthy();
         if (environment.HELYX_BOT_CONTROL_SECRET) {
             controlServer = await createBotControlServer({
@@ -442,6 +480,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
             pending.resolve(message.data);
             return;
         }
+        if (message.data.type === "helyx.scheduled.response") {
+            const pending = pendingScheduled.get(message.data.requestId);
+            if (!pending || pending.shardId !== shardId)
+                return;
+            pendingScheduled.delete(message.data.requestId);
+            clearTimeout(pending.timer);
+            pending.resolve(message.data);
+            return;
+        }
         if (message.data.type === "helyx.cloud.request") {
             const response = leaderLease
                 ? await executeLeaderCloud(message.data)
@@ -478,6 +525,24 @@ export async function startShardSupervisor(environment, processEnvironment, work
             });
         });
     }
+    function dispatchLocalScheduled(shardId, request) {
+        const shard = workers.get(shardId);
+        if (!shard?.process)
+            return Promise.resolve(unavailableScheduled(request.requestId));
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                pendingScheduled.delete(request.requestId);
+                resolve(unavailableScheduled(request.requestId, "shard_timeout"));
+            }, Math.max(1, new Date(request.deadlineAt).getTime() - Date.now()));
+            timer.unref();
+            pendingScheduled.set(request.requestId, { shardId, resolve, timer });
+            void shard.send(request).catch(() => {
+                clearTimeout(timer);
+                pendingScheduled.delete(request.requestId);
+                resolve(unavailableScheduled(request.requestId));
+            });
+        });
+    }
     async function executeLeaderControl(request) {
         if (!leaderLease || !privacyService)
             return unavailableControl(request.requestId);
@@ -549,6 +614,23 @@ export async function startShardSupervisor(environment, processEnvironment, work
                         return failedCloud(parsed.requestId, "Cloud request expired");
                     result = await cloudConnector.rotate();
                     break;
+                case "support.bug.create":
+                    if (cloudRequestExpired(parsed))
+                        return failedCloud(parsed.requestId, "Support request expired");
+                    result = await cloudConnector.submitBug({
+                        operation: "support.bug.create.v1",
+                        reporterDiscordUserId: parsed.operation.reporterDiscordUserId,
+                        guildId: parsed.operation.guildId,
+                        moduleOrArea: parsed.operation.moduleOrArea,
+                        summary: parsed.operation.summary,
+                        whatHappened: parsed.operation.whatHappened,
+                        ...(parsed.operation.extraDetail
+                            ? { extraDetail: parsed.operation.extraDetail }
+                            : {}),
+                        interactionId: parsed.operation.interactionId,
+                        correlationId: parsed.operation.correlationId,
+                    });
+                    break;
             }
             const response = {
                 version: 1,
@@ -700,6 +782,72 @@ export async function startShardSupervisor(environment, processEnvironment, work
         retentionTimer.unref();
         await cloudConnector?.start();
         cloudStarted = true;
+        if (workersRoutable)
+            startScheduledTasks();
+    }
+    function startScheduledTasks() {
+        if (scheduledTasks || !leaderLease || !workersRoutable)
+            return;
+        scheduledTasks = createScheduledTaskRunner({
+            database,
+            modules: scheduledModules,
+            route: routeScheduledTask,
+            logger,
+            workerId: `shard-leader:${leaderLease.generation}:${String(leaderLease.fencingToken)}`,
+        });
+        scheduledTasks.start();
+    }
+    async function routeScheduledTask(task, signal) {
+        if (!task.guildId)
+            return {
+                outcome: "requires_review",
+                safeCode: "guild_route_required",
+            };
+        if (!leaderLease || signal.aborted)
+            return {
+                outcome: "deferred",
+                delayMs: 1_000,
+                safeCode: "leader_unavailable",
+            };
+        return deferScheduledRoutingFailures(async () => {
+            const shardId = guildIdToShardId(task.guildId, shardCount);
+            const lease = localLeases.get(shardId) ??
+                (coordinator ? await coordinator.getShardLease(shardId) : undefined);
+            if (!lease || lease.generation !== generationDescriptor.generation)
+                return {
+                    outcome: "deferred",
+                    delayMs: 1_000,
+                    safeCode: "shard_unavailable",
+                };
+            const request = {
+                version: 1,
+                type: "helyx.scheduled.request",
+                requestId: randomUUID(),
+                deadlineAt: new Date(Date.now() + 10_000).toISOString(),
+                identity: {
+                    version: 1,
+                    mode: shardMode,
+                    scope: environment.HELYX_SHARD_SCOPE,
+                    generation: lease.generation,
+                    deploymentOrder: lease.deploymentOrder,
+                    supervisorId: lease.supervisorId,
+                    shardId,
+                    shardCount,
+                    fencingToken: lease.fencingToken,
+                },
+                task: {
+                    ...task,
+                    guildId: task.guildId,
+                },
+            };
+            assertShardMessageSize(request);
+            const response = lease.supervisorId === supervisorId
+                ? await dispatchLocalScheduled(shardId, request)
+                : coordinator
+                    ? await coordinator.routeRemoteScheduled(lease, request)
+                    : unavailableScheduled(request.requestId);
+            return response.result;
+        });
     }
     function startStartupLeaseMaintenance() {
         if (!coordinator || startupLeaseTimer)
@@ -749,6 +897,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
     }
     async function buildHealth() {
         const now = Date.now();
+        const scheduler = scheduledTasks
+            ? await withTimeout(scheduledTasks.getHealth(), LEASE_VALIDATION_TIMEOUT_MS)
+                .then(schedulerOperationalHealth)
+                .catch(() => ({ status: "unavailable" }))
+            : { status: "unavailable" };
         let redisReady = true;
         if (coordinator)
             await withTimeout(coordinator.checkReady(), LEASE_VALIDATION_TIMEOUT_MS).catch(() => {
@@ -802,7 +955,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 ? "stale"
                 : readyShardCount === shardCount &&
                     coordinationRedis !== "unavailable" &&
-                    databaseHealthy
+                    databaseHealthy &&
+                    scheduler.status === "available"
                     ? "healthy"
                     : readyShardCount === 0
                         ? "unavailable"
@@ -818,6 +972,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 redis: coordinationRedis,
                 database: databaseHealthy ? "healthy" : "unavailable",
             },
+            scheduler,
             ...(sessionBudget ? { sessionStarts: sessionBudget } : {}),
             shards,
         });
@@ -832,6 +987,14 @@ export async function startShardSupervisor(environment, processEnvironment, work
             clearInterval(startupLeaseTimer);
         if (retentionTimer)
             clearInterval(retentionTimer);
+        workersRoutable = false;
+        await scheduledTasks?.stop().catch(() => undefined);
+        scheduledTasks = undefined;
+        for (const [requestId, pending] of pendingScheduled) {
+            clearTimeout(pending.timer);
+            pending.resolve(unavailableScheduled(requestId, "supervisor_stopping"));
+        }
+        pendingScheduled.clear();
         await controlServer?.close().catch(() => undefined);
         await Promise.allSettled([...workers.values()].map(async (shard) => {
             if (!shard.process)
@@ -965,6 +1128,7 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         "DISCORD_TOKEN",
         "DISCORD_CLIENT_ID",
         "DISCORD_INTERNAL_GUILD_ID",
+        "HELYX_SUPPORT_STAFF_CHANNEL_ID",
         "HELYX_MODULE_PACKAGES",
         "HELYX_MODULE_CATALOGUE_PATH",
         "HELYX_CLOUD_CONNECT_ENABLED",
@@ -988,8 +1152,14 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         "TMP",
     ]);
     const environment = Object.fromEntries(Object.entries(source).filter(([key, value]) => allowed.has(key) && value !== undefined));
+    const selectionKey = source.HELYX_DATA_ENCRYPTION_KEY
+        ? Buffer.from(deriveSecureRandomSelectionKey(source.HELYX_DATA_ENCRYPTION_KEY)).toString("base64")
+        : undefined;
     return {
         ...environment,
+        ...(selectionKey
+            ? { [secureRandomSelectionWorkerKeyName]: selectionKey }
+            : {}),
         SHARDING_MANAGER: "true",
         SHARDING_MANAGER_MODE: "process",
         SHARDS: String(identity.shardId),
@@ -1042,6 +1212,18 @@ function unavailableControl(requestId, status = 503) {
             : "The owning shard is temporarily unavailable",
     };
 }
+function unavailableScheduled(requestId, safeCode = "shard_unavailable") {
+    return {
+        version: 1,
+        type: "helyx.scheduled.response",
+        requestId,
+        result: {
+            outcome: "deferred",
+            delayMs: 1_000,
+            safeCode,
+        },
+    };
+}
 function failedCloud(requestId, message) {
     return {
         version: 1,

package/dist/shard-worker.d.ts

@@ -1,6 +1,7 @@
 import { type CommandRegistration } from "./interactions.js";
-import { type ShardIdentity } from "./shard-contracts.js";
+import { type ShardIdentity, type ShardScheduledTaskRequest, type ShardScheduledTaskResponse } from "./shard-contracts.js";
 import { type BotHandle } from "./index.js";
+import { type ScheduledTaskRoute } from "./scheduled-task-runner.js";
 export declare const WORKER_ORPHAN_TERMINATION_BOUND_MS: number;
 export declare function createLeaseHeartbeatWatchdog(onExpired: () => void, timeoutMs?: number): {
     heartbeat(): void;
@@ -17,8 +18,11 @@ export declare function startShardWorker(processEnvironment?: NodeJS.ProcessEnv,
     fencingToken: number;
     deploymentOrder?: number | undefined;
 }): Promise<BotHandle>;
+export declare function executeShardScheduledTaskRequest(identity: ShardIdentity, request: ShardScheduledTaskRequest, route: ScheduledTaskRoute, now?: number): Promise<ShardScheduledTaskResponse>;
 export declare function parseShardWorkerLaunchContract(value: string | undefined): ShardIdentity;
 export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.ProcessEnv, identity: ShardIdentity): {
+    HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY?: string;
+    HELYX_DATA_ENCRYPTION_KEY: undefined;
     HELYX_SHARD_WORKERS_PER_REPLICA: number;
     HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX: number | undefined;
     HELYX_SHARD_WORKER_DATABASE_POOL_MAX: number | undefined;
@@ -30,6 +34,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     APPROVED_ROLES: string[];
     HELYX_MODULE_PACKAGES: string[];
     HELYX_MODULE_CATALOGUE_PATH: string | undefined;
+    HELYX_SUPPORT_STAFF_CHANNEL_ID: string | undefined;
     HELYX_BOT_CONTROL_PORT: number;
     HELYX_PRIVACY_ENABLED: boolean;
     HELYX_CLOUD_CONNECT_ENABLED: boolean;
@@ -45,9 +50,9 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     LOG_LEVEL: "error" | "fatal" | "warn" | "info" | "debug" | "trace" | "silent";
     NODE_ENV: "development" | "test" | "production";
     HELYX_BOT_CONTROL_SECRET?: string | undefined;
+    HELYX_SUPPORT_SERVICE_SECRET?: string | undefined;
     HELYX_PRIVACY_EXECUTOR_DATABASE_URL?: string | undefined;
     HELYX_PRIVACY_EXECUTOR_DATABASE_SSL?: "disable" | "require" | "verify-full" | undefined;
-    HELYX_DATA_ENCRYPTION_KEY?: string | undefined;
     HELYX_SHARD_COUNT?: number | undefined;
     HELYX_SHARD_REDIS_URL?: string | undefined;
     HELYX_SHARD_REDIS_NAMESPACE?: string | undefined;
@@ -58,5 +63,6 @@ export declare function shardWorkerCommandRegistration(input: {
     internalGuildId?: string;
     prepare: NonNullable<CommandRegistration["prepare"]>;
     operationsModuleId?: string;
+    supportModuleId: string;
 }): CommandRegistration;
 //# sourceMappingURL=shard-worker.d.ts.map