@helyx/bot 0.4.1 → 0.4.4

package/dist/scheduled-task-runner.d.ts

@@ -0,0 +1,130 @@
+import { type CoalescedTaskRecord, type ScheduledTaskRecord, type ScheduledTaskDefinition, type SchedulerHealth } from "@helyx/database";
+import { type Logger, type ModuleDefinition, type ModuleScheduledTaskExecution, type ScheduledTaskExecutionResult, type ServiceAccess } from "@helyx/sdk";
+import type { Pool } from "pg";
+export interface ScheduledTaskRoute {
+    (task: ModuleScheduledTaskExecution, signal: AbortSignal): Promise<ScheduledTaskExecutionResult>;
+}
+interface ScheduledTaskRepositoryContract {
+    claimDue(input: {
+        workerId: string;
+        leaseMs: number;
+        limit?: number;
+        eligible?: readonly ScheduledTaskDefinition[];
+    }): Promise<ScheduledTaskRecord[]>;
+    claimCoalesced(input: {
+        workerId: string;
+        leaseMs: number;
+        limit?: number;
+        eligible?: readonly ScheduledTaskDefinition[];
+    }): Promise<CoalescedTaskRecord[]>;
+    heartbeat(input: {
+        taskId: string;
+        workerId: string;
+        leaseGeneration: number;
+        leaseMs: number;
+    }): Promise<boolean>;
+    heartbeatCoalesced(input: {
+        laneId: string;
+        workerId: string;
+        leaseGeneration: number;
+        claimedGeneration: number;
+        leaseMs: number;
+    }): Promise<boolean>;
+    complete(input: {
+        taskId: string;
+        workerId: string;
+        leaseGeneration: number;
+    }): Promise<boolean>;
+    completeCoalesced(input: {
+        laneId: string;
+        workerId: string;
+        leaseGeneration: number;
+        claimedGeneration: number;
+    }): Promise<boolean>;
+    defer(input: {
+        taskId: string;
+        workerId: string;
+        leaseGeneration: number;
+        delayMs: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    deferCoalesced(input: {
+        laneId: string;
+        workerId: string;
+        leaseGeneration: number;
+        claimedGeneration: number;
+        delayMs: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    retry(input: {
+        taskId: string;
+        workerId: string;
+        leaseGeneration: number;
+        delayMs: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    retryCoalesced(input: {
+        laneId: string;
+        workerId: string;
+        leaseGeneration: number;
+        claimedGeneration: number;
+        delayMs: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    markRequiresReview(input: {
+        taskId: string;
+        workerId: string;
+        leaseGeneration: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    markCoalescedRequiresReview(input: {
+        laneId: string;
+        workerId: string;
+        leaseGeneration: number;
+        claimedGeneration: number;
+        safeCode: string;
+    }): Promise<boolean>;
+    getHealth(sampleLimit?: number): Promise<SchedulerHealth>;
+}
+export declare class ScheduledTaskRunner {
+    #private;
+    constructor(input: {
+        repository: ScheduledTaskRepositoryContract;
+        route: ScheduledTaskRoute;
+        logger: Logger;
+        workerId?: string;
+        pollIntervalMs?: number;
+        leaseMs?: number;
+        claimLimit?: number;
+        stopTimeoutMs?: number;
+        eligibleTasks?: readonly (ScheduledTaskDefinition & {
+            delivery: "one-shot" | "coalesced";
+        })[];
+    });
+    start(): void;
+    stop(): Promise<void>;
+    runOnce(): Promise<void>;
+    getHealth(): Promise<SchedulerHealth>;
+}
+export declare function createScheduledTaskRunner(input: {
+    database: Pool;
+    modules: readonly ModuleDefinition[];
+    route: ScheduledTaskRoute;
+    logger: Logger;
+    workerId?: string;
+}): ScheduledTaskRunner;
+export declare function schedulerOperationalHealth(health: SchedulerHealth): {
+    status: "available";
+    oneShot: ReturnType<typeof mapSchedulerWorkHealth>;
+    coalesced: ReturnType<typeof mapSchedulerWorkHealth>;
+};
+export declare function createLocalScheduledTaskRoute(input: {
+    modules: readonly ModuleDefinition[];
+    services: ServiceAccess;
+    logger: Logger;
+}): ScheduledTaskRoute;
+declare function mapSchedulerWorkHealth(health: SchedulerHealth["oneShot"]): Omit<SchedulerHealth["oneShot"], "oldestReadyAt"> & {
+    oldestReadyAt: string | null;
+};
+export {};
+//# sourceMappingURL=scheduled-task-runner.d.ts.map

package/dist/scheduled-task-runner.js

@@ -0,0 +1,417 @@
+import { CORE_RECORD_RETENTION_TASK, ScheduledTaskRepository, } from "@helyx/database";
+import { getModuleScheduledTaskContribution, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_LEASE_MS = 45_000;
+const DEFAULT_CLAIM_LIMIT = 8;
+const DEFAULT_STOP_TIMEOUT_MS = 5_000;
+const MAX_RESULT_DELAY_MS = 24 * 60 * 60 * 1_000;
+const SAFE_CODE = /^[a-z0-9][a-z0-9._-]{0,99}$/u;
+export class ScheduledTaskRunner {
+    #repository;
+    #route;
+    #logger;
+    #workerId;
+    #pollIntervalMs;
+    #leaseMs;
+    #claimLimit;
+    #stopTimeoutMs;
+    #oneShotEligible;
+    #coalescedEligible;
+    #catalogueFiltered;
+    #timer;
+    #active;
+    #controller = new AbortController();
+    #stopping = false;
+    constructor(input) {
+        this.#repository = input.repository;
+        this.#route = input.route;
+        this.#logger = input.logger;
+        this.#workerId = input.workerId ?? `scheduled-runner:${randomUUID()}`;
+        this.#pollIntervalMs = boundedInteger(input.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, 100, 60_000, "scheduler poll interval");
+        this.#leaseMs = boundedInteger(input.leaseMs ?? DEFAULT_LEASE_MS, 5_000, 5 * 60_000, "scheduler lease");
+        this.#claimLimit = boundedInteger(input.claimLimit ?? DEFAULT_CLAIM_LIMIT, 1, 25, "scheduler claim limit");
+        this.#stopTimeoutMs = boundedInteger(input.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS, 100, 30_000, "scheduler stop timeout");
+        this.#catalogueFiltered = input.eligibleTasks !== undefined;
+        this.#oneShotEligible = input.eligibleTasks
+            ?.filter(({ delivery }) => delivery === "one-shot")
+            .map(withoutDelivery);
+        this.#coalescedEligible = input.eligibleTasks
+            ?.filter(({ delivery }) => delivery === "coalesced")
+            .map(withoutDelivery);
+    }
+    start() {
+        if (this.#timer || this.#stopping)
+            throw new Error("Scheduled task runner is already started or stopped");
+        this.#runSoon();
+        this.#timer = setInterval(() => this.#runSoon(), this.#pollIntervalMs);
+        this.#timer.unref();
+    }
+    async stop() {
+        if (!this.#stopping) {
+            this.#stopping = true;
+            if (this.#timer)
+                clearInterval(this.#timer);
+            this.#timer = undefined;
+            this.#controller.abort();
+        }
+        const active = this.#active;
+        if (!active)
+            return;
+        await Promise.race([active, wait(this.#stopTimeoutMs)]);
+    }
+    async runOnce() {
+        if (this.#stopping)
+            return;
+        if (this.#catalogueFiltered &&
+            this.#oneShotEligible?.length === 0 &&
+            this.#coalescedEligible?.length === 0)
+            return;
+        const [oneShot, coalesced] = await Promise.all([
+            this.#catalogueFiltered && this.#oneShotEligible?.length === 0
+                ? Promise.resolve([])
+                : this.#repository.claimDue({
+                    workerId: this.#workerId,
+                    leaseMs: this.#leaseMs,
+                    limit: this.#claimLimit,
+                    ...(this.#oneShotEligible === undefined
+                        ? {}
+                        : { eligible: this.#oneShotEligible }),
+                }),
+            this.#catalogueFiltered && this.#coalescedEligible?.length === 0
+                ? Promise.resolve([])
+                : this.#repository.claimCoalesced({
+                    workerId: this.#workerId,
+                    leaseMs: this.#leaseMs,
+                    limit: this.#claimLimit,
+                    ...(this.#coalescedEligible === undefined
+                        ? {}
+                        : { eligible: this.#coalescedEligible }),
+                }),
+        ]);
+        const tasks = [
+            ...oneShot.map((record) => ({
+                delivery: "one-shot",
+                record,
+            })),
+            ...coalesced.map((record) => ({
+                delivery: "coalesced",
+                record,
+            })),
+        ];
+        await Promise.all(tasks.map((task) => this.#execute(task).catch((error) => {
+            this.#logger.error({
+                event: "scheduler.settlement_failed",
+                delivery: task.delivery,
+                taskId: task.record.id,
+                moduleId: task.record.moduleId,
+                errorName: error instanceof Error ? error.name : "Error",
+            }, "Scheduled task could not be settled");
+        })));
+    }
+    getHealth() {
+        return this.#repository.getHealth();
+    }
+    #runSoon() {
+        if (this.#active || this.#stopping)
+            return;
+        this.#active = this.runOnce()
+            .catch((error) => {
+            this.#logger.error({
+                event: "scheduler.claim_failed",
+                errorName: error instanceof Error ? error.name : "Error",
+            }, "Scheduled task claim failed");
+        })
+            .finally(() => {
+            this.#active = undefined;
+        });
+    }
+    async #execute(task) {
+        const runnerSignal = this.#controller.signal;
+        if (runnerSignal.aborted)
+            return;
+        const controller = new AbortController();
+        let heartbeat;
+        let heartbeatRunning = false;
+        const abort = () => {
+            if (heartbeat)
+                clearInterval(heartbeat);
+            heartbeat = undefined;
+            controller.abort();
+        };
+        runnerSignal.addEventListener("abort", abort, { once: true });
+        const renewLease = () => {
+            if (heartbeatRunning || controller.signal.aborted)
+                return;
+            heartbeatRunning = true;
+            void this.#heartbeat(task)
+                .then((alive) => {
+                if (!alive)
+                    abort();
+            })
+                .catch((error) => {
+                this.#logger.error({
+                    event: "scheduler.heartbeat_failed",
+                    delivery: task.delivery,
+                    taskId: task.record.id,
+                    moduleId: task.record.moduleId,
+                    errorName: error instanceof Error ? error.name : "Error",
+                }, "Scheduled task lease heartbeat failed");
+                abort();
+            })
+                .finally(() => {
+                heartbeatRunning = false;
+            });
+        };
+        heartbeat = setInterval(renewLease, Math.max(1_000, Math.floor(this.#leaseMs / 3)));
+        heartbeat.unref();
+        let result;
+        try {
+            result = validateExecutionResult(await this.#route(toExecution(task), controller.signal));
+        }
+        catch {
+            result = controller.signal.aborted
+                ? deferred("runner_stopped", 1_000)
+                : {
+                    outcome: "retry",
+                    delayMs: retryDelay(task.record.attemptCount),
+                    safeCode: "handler_failed",
+                };
+        }
+        finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
+            runnerSignal.removeEventListener("abort", abort);
+        }
+        if (runnerSignal.aborted || controller.signal.aborted)
+            return;
+        await this.#settle(task, result);
+    }
+    #heartbeat(task) {
+        if (task.delivery === "one-shot") {
+            return this.#repository.heartbeat({
+                taskId: task.record.id,
+                workerId: this.#workerId,
+                leaseGeneration: task.record.leaseGeneration,
+                leaseMs: this.#leaseMs,
+            });
+        }
+        return this.#repository.heartbeatCoalesced({
+            laneId: task.record.id,
+            workerId: this.#workerId,
+            leaseGeneration: task.record.leaseGeneration,
+            claimedGeneration: task.record.claimedGeneration,
+            leaseMs: this.#leaseMs,
+        });
+    }
+    #settle(task, result) {
+        const common = {
+            workerId: this.#workerId,
+            leaseGeneration: task.record.leaseGeneration,
+        };
+        if (task.delivery === "one-shot") {
+            const target = { ...common, taskId: task.record.id };
+            switch (result.outcome) {
+                case "completed":
+                    return this.#repository.complete(target);
+                case "deferred":
+                    return this.#repository.defer({
+                        ...target,
+                        delayMs: result.delayMs,
+                        safeCode: result.safeCode,
+                    });
+                case "retry":
+                    return this.#repository.retry({
+                        ...target,
+                        delayMs: result.delayMs,
+                        safeCode: result.safeCode,
+                    });
+                case "requires_review":
+                    return this.#repository.markRequiresReview({
+                        ...target,
+                        safeCode: result.safeCode,
+                    });
+            }
+        }
+        const target = {
+            ...common,
+            laneId: task.record.id,
+            claimedGeneration: task.record.claimedGeneration,
+        };
+        switch (result.outcome) {
+            case "completed":
+                return this.#repository.completeCoalesced(target);
+            case "deferred":
+                return this.#repository.deferCoalesced({
+                    ...target,
+                    delayMs: result.delayMs,
+                    safeCode: result.safeCode,
+                });
+            case "retry":
+                return this.#repository.retryCoalesced({
+                    ...target,
+                    delayMs: result.delayMs,
+                    safeCode: result.safeCode,
+                });
+            case "requires_review":
+                return this.#repository.markCoalescedRequiresReview({
+                    ...target,
+                    safeCode: result.safeCode,
+                });
+        }
+    }
+}
+export function createScheduledTaskRunner(input) {
+    return new ScheduledTaskRunner({
+        repository: new ScheduledTaskRepository(input.database),
+        route: input.route,
+        logger: input.logger,
+        eligibleTasks: [
+            {
+                ...CORE_RECORD_RETENTION_TASK,
+                delivery: "one-shot",
+                runWhenDisabled: true,
+            },
+            ...input.modules.flatMap((module) => (module.scheduledTasks ?? []).map((contribution) => ({
+                moduleId: module.manifest.id,
+                taskKind: contribution.kind,
+                taskVersion: contribution.version,
+                delivery: contribution.delivery,
+            }))),
+        ],
+        ...(input.workerId === undefined ? {} : { workerId: input.workerId }),
+    });
+}
+export function schedulerOperationalHealth(health) {
+    return {
+        status: "available",
+        oneShot: mapSchedulerWorkHealth(health.oneShot),
+        coalesced: mapSchedulerWorkHealth(health.coalesced),
+    };
+}
+export function createLocalScheduledTaskRoute(input) {
+    const modules = new Map(input.modules.map((module) => [module.manifest.id, module]));
+    return async (task, signal) => {
+        if (task.moduleId === CORE_RECORD_RETENTION_TASK.moduleId &&
+            task.taskKind === CORE_RECORD_RETENTION_TASK.taskKind &&
+            task.taskVersion === CORE_RECORD_RETENTION_TASK.taskVersion &&
+            task.delivery === "one-shot") {
+            const retentionTaskId = task.payload.retentionTaskId;
+            if (Object.keys(task.payload).length !== 1 ||
+                typeof retentionTaskId !== "string" ||
+                !/^[0-9a-f]{8}-[0-9a-f-]{27}$/iu.test(retentionTaskId))
+                return { outcome: "requires_review", safeCode: "payload_invalid" };
+            const result = await input.services
+                .get(HELYX_SERVICE_NAMES.recordRetention)
+                .execute(retentionTaskId);
+            return result.completed
+                ? { outcome: "completed" }
+                : {
+                    outcome: "deferred",
+                    delayMs: 100,
+                    safeCode: "retention_batch_remaining",
+                };
+        }
+        const module = modules.get(task.moduleId);
+        if (!module)
+            return deferred("module_unavailable", DEFAULT_POLL_INTERVAL_MS * 30);
+        if (task.guildId) {
+            const enabled = await input.services
+                .get(HELYX_SERVICE_NAMES.installations)
+                .isModuleEnabled(task.guildId, task.moduleId);
+            if (!enabled)
+                return deferred("module_disabled", DEFAULT_POLL_INTERVAL_MS * 30);
+        }
+        const contribution = getModuleScheduledTaskContribution(module, task.taskKind);
+        if (!contribution ||
+            contribution.delivery !== task.delivery ||
+            contribution.version !== task.taskVersion) {
+            return { outcome: "requires_review", safeCode: "handler_mismatch" };
+        }
+        let payload;
+        try {
+            payload = contribution.validatePayload(task.payload);
+        }
+        catch {
+            return { outcome: "requires_review", safeCode: "payload_invalid" };
+        }
+        if (!samePayload(payload, task.payload))
+            return { outcome: "requires_review", safeCode: "payload_mismatch" };
+        return contribution.execute({
+            logger: input.logger.child({
+                moduleId: task.moduleId,
+                taskKind: task.taskKind,
+                taskId: task.taskId,
+            }),
+            services: input.services,
+            signal,
+        }, task);
+    };
+}
+function toExecution(task) {
+    const common = {
+        taskId: task.record.id,
+        moduleId: task.record.moduleId,
+        taskKind: task.record.taskKind,
+        taskVersion: task.record.taskVersion,
+        guildId: task.record.guildId,
+        payload: task.record.payload,
+    };
+    return task.delivery === "one-shot"
+        ? { delivery: "one-shot", ...common }
+        : {
+            delivery: "coalesced",
+            ...common,
+            claimedGeneration: task.record.claimedGeneration,
+        };
+}
+function validateExecutionResult(result) {
+    if (result.outcome === "completed")
+        return result;
+    if (!SAFE_CODE.test(result.safeCode))
+        throw new Error("Scheduled task returned an invalid safe code");
+    if (result.outcome === "requires_review")
+        return result;
+    boundedInteger(result.delayMs, 100, MAX_RESULT_DELAY_MS, "task delay");
+    return result;
+}
+function deferred(safeCode, delayMs) {
+    return { outcome: "deferred", delayMs, safeCode };
+}
+function retryDelay(attemptCount) {
+    return Math.min(5 * 60_000, 1_000 * 2 ** Math.min(attemptCount, 8));
+}
+function withoutDelivery(input) {
+    return {
+        moduleId: input.moduleId,
+        taskKind: input.taskKind,
+        taskVersion: input.taskVersion,
+        ...(input.runWhenDisabled === undefined
+            ? {}
+            : { runWhenDisabled: input.runWhenDisabled }),
+    };
+}
+function boundedInteger(value, minimum, maximum, label) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new Error(`${label} must be between ${minimum} and ${maximum}`);
+    return value;
+}
+function samePayload(left, right) {
+    const leftEntries = Object.entries(left);
+    const rightKeys = Object.keys(right);
+    return (leftEntries.length === rightKeys.length &&
+        leftEntries.every(([key, value]) => right[key] === value));
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, milliseconds);
+        timer.unref();
+    });
+}
+function mapSchedulerWorkHealth(health) {
+    return {
+        ...health,
+        oldestReadyAt: health.oldestReadyAt?.toISOString() ?? null,
+    };
+}
+//# sourceMappingURL=scheduled-task-runner.js.map

package/dist/shard-cloud-proxy.d.ts

@@ -1,4 +1,5 @@
 import type { CloudConnectorConsentRecord } from "@helyx/database";
+import type { SupportBugCreatePayload, SupportBugCreateResponsePayload } from "@helyx/control-protocol";
 import type { CloudConnector, CloudConnectorStatus } from "./cloud-connector.js";
 import { type ShardCloudResponse } from "./shard-contracts.js";
 export declare class WorkerCloudConnectorProxy implements CloudConnector {
@@ -15,6 +16,9 @@ export declare class WorkerCloudConnectorProxy implements CloudConnector {
     enrol(token: string, source: "startup" | "discord" | "file"): Promise<CloudConnectorStatus>;
     disconnect(): Promise<void>;
     rotate(): Promise<CloudConnectorStatus>;
+    submitBug(input: SupportBugCreatePayload): Promise<Extract<SupportBugCreateResponsePayload, {
+        ok: true;
+    }>["result"]>;
     stop(): Promise<void>;
     accept(response: ShardCloudResponse): void;
 }

package/dist/shard-cloud-proxy.js

@@ -28,6 +28,19 @@ export class WorkerCloudConnectorProxy {
         this.#status = parseStatus(await this.#request({ kind: "cloud.rotate" }));
         return this.#status;
     }
+    async submitBug(input) {
+        return parseSupportResult(await this.#request({
+            kind: "support.bug.create",
+            reporterDiscordUserId: input.reporterDiscordUserId,
+            guildId: input.guildId,
+            moduleOrArea: input.moduleOrArea,
+            summary: input.summary,
+            whatHappened: input.whatHappened,
+            ...(input.extraDetail ? { extraDetail: input.extraDetail } : {}),
+            interactionId: input.interactionId,
+            correlationId: input.correlationId,
+        }));
+    }
     stop() {
         for (const pending of this.#pending.values()) {
             clearTimeout(pending.timer);
@@ -91,4 +104,25 @@ function parseConsent(value) {
     const consent = value;
     return { ...consent, updatedAt: new Date(consent.updatedAt) };
 }
+function parseSupportResult(value) {
+    const claimUrl = typeof value === "object" && value !== null && "claimUrl" in value
+        ? value.claimUrl
+        : undefined;
+    if (typeof value !== "object" ||
+        value === null ||
+        !("reference" in value) ||
+        typeof value.reference !== "string" ||
+        !("created" in value) ||
+        typeof value.created !== "boolean" ||
+        (claimUrl !== undefined &&
+            (typeof claimUrl !== "string" ||
+                claimUrl.length > 2_048 ||
+                !claimUrl.startsWith("https://"))))
+        throw new Error("Cloud supervisor returned an invalid support result");
+    return {
+        reference: value.reference,
+        created: value.created,
+        ...(typeof claimUrl === "string" ? { claimUrl } : {}),
+    };
+}
 //# sourceMappingURL=shard-cloud-proxy.js.map