@helyx/bot 1.5.2 → 1.5.4

package/dist/cloud-command-policy-sync.js

@@ -0,0 +1,198 @@
+import { restoreCommandPolicyPublication, normalizeCommandPolicyManifest, } from "@helyx/database-contracts";
+import { commandPolicyReplySchema, } from "@helyx/control-protocol/command-policy";
+import { randomUUID } from "node:crypto";
+/** One authenticated socket, one bounded transfer, no customer policy authority. */
+export class CloudCommandPolicySynchronizer {
+    input;
+    #abort = new AbortController();
+    #pending;
+    #timer;
+    #active;
+    #known;
+    constructor(input) {
+        this.input = input;
+    }
+    async start() {
+        await this.#assertCurrent();
+        await this.input.delivery.openSession({
+            owner: this.input.owner,
+            session: this.input.session,
+            signal: this.#abort.signal,
+        });
+        await this.#assertCurrent();
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => {
+            void this.runOnce();
+        }, this.input.intervalMs ?? 30_000);
+        this.#timer.unref();
+        void this.runOnce();
+    }
+    runOnce() {
+        if (this.#active)
+            return this.#active;
+        if (this.#abort.signal.aborted)
+            return Promise.resolve();
+        this.#active = this.#refresh()
+            .catch(() => {
+            if (!this.#abort.signal.aborted)
+                this.input.onHeld();
+        })
+            .finally(() => {
+            this.#active = undefined;
+        });
+        return this.#active;
+    }
+    /** Caller must first pass the current accepted envelope's sequence/epoch guard. */
+    accept(correlationId, payload, expiresAt) {
+        const pending = this.#pending;
+        if (!pending ||
+            correlationId !== pending.correlationId ||
+            this.#abort.signal.aborted)
+            return;
+        const reply = commandPolicyReplySchema.parse(payload);
+        if (!Number.isFinite(Date.parse(expiresAt)) ||
+            Date.parse(expiresAt) <= Date.now())
+            throw new Error("command_policy_confirmation_expired");
+        clearTimeout(pending.timer);
+        this.#pending = undefined;
+        pending.resolve({ reply, expiresAt });
+    }
+    /** Stop local activity before an atomic receipt-first identity transition. */
+    cancel() {
+        this.#abort.abort();
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+        if (this.#pending) {
+            clearTimeout(this.#pending.timer);
+            this.#pending.reject(new Error("command_policy_session_closed"));
+            this.#pending = undefined;
+        }
+    }
+    async stop() {
+        this.cancel();
+        await this.#active;
+        await this.input.delivery.invalidate({
+            owner: this.input.owner,
+            expectedSession: this.input.session,
+        });
+    }
+    async #assertCurrent() {
+        this.#abort.signal.throwIfAborted();
+        if (this.input.isOwnerCurrent && !(await this.input.isOwnerCurrent()))
+            throw new Error("command_policy_owner_changed");
+        this.#abort.signal.throwIfAborted();
+    }
+    async #request(pull) {
+        await this.#assertCurrent();
+        const correlationId = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending = undefined;
+                reject(new Error("command_policy_request_timed_out"));
+            }, this.input.timeoutMs ?? 10_000);
+            timer.unref();
+            this.#pending = { correlationId, resolve, reject, timer };
+            try {
+                this.input.send(correlationId, pull);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.#pending = undefined;
+                reject(error instanceof Error
+                    ? error
+                    : new Error("command_policy_send_failed"));
+            }
+        });
+    }
+    async #refresh() {
+        let entries = [];
+        let manifest;
+        let pull = {
+            kind: "check",
+            ...(this.#known
+                ? {
+                    known: {
+                        revision: this.#known.revision,
+                        fingerprint: this.#known.fingerprint,
+                    },
+                }
+                : {}),
+        };
+        // At most 10,000 one-entry pages plus two source-change retries. Normal
+        // pages contain up to 500 entries; no unbounded snapshot churn is accepted.
+        let restarts = 0;
+        for (let pages = 0; pages < 10_003; pages += 1) {
+            const { reply, expiresAt } = await this.#request(pull);
+            await this.#assertCurrent();
+            if (reply.state === "unavailable" || reply.state === "unconfigured") {
+                this.#known = undefined;
+                await this.input.delivery.invalidate({
+                    owner: this.input.owner,
+                    expectedSession: this.input.session,
+                });
+                throw new Error("command_policy_source_unavailable");
+            }
+            if (reply.targetApplicationId !== this.input.applicationId)
+                throw new Error("command_policy_application_mismatch");
+            const currentManifest = normalizeCommandPolicyManifest(reply.publication);
+            if (reply.state === "unchanged") {
+                if (!this.#known ||
+                    JSON.stringify(this.#known) !== JSON.stringify(currentManifest))
+                    throw new Error("command_policy_unexpected_unchanged");
+                if (!(await this.input.delivery.renew({
+                    owner: this.input.owner,
+                    session: this.input.session,
+                    publication: currentManifest,
+                    confirmationExpiresAt: expiresAt,
+                    signal: this.#abort.signal,
+                })))
+                    throw new Error("command_policy_renewal_refused");
+                return;
+            }
+            if (reply.state === "snapshot_changed") {
+                if (++restarts > 2)
+                    throw new Error("command_policy_source_churn");
+                entries = [];
+                manifest = currentManifest;
+                pull = {
+                    kind: "page",
+                    revision: manifest.revision,
+                    fingerprint: manifest.fingerprint,
+                    offset: 0,
+                };
+                continue;
+            }
+            if (reply.page.offset !== entries.length ||
+                (manifest &&
+                    JSON.stringify(manifest) !== JSON.stringify(currentManifest)))
+                throw new Error("command_policy_noncontiguous_page");
+            manifest = currentManifest;
+            entries.push(...reply.page.entries);
+            if (entries.length > 10_000)
+                throw new Error("command_policy_entry_limit");
+            if (reply.page.nextOffset !== null) {
+                pull = {
+                    kind: "page",
+                    revision: manifest.revision,
+                    fingerprint: manifest.fingerprint,
+                    offset: reply.page.nextOffset,
+                };
+                continue;
+            }
+            const publication = restoreCommandPolicyPublication(manifest, entries);
+            await this.#assertCurrent();
+            await this.input.delivery.adopt({
+                owner: this.input.owner,
+                session: this.input.session,
+                publication,
+                confirmationExpiresAt: expiresAt,
+                signal: this.#abort.signal,
+            });
+            this.#known = manifest;
+            return;
+        }
+        throw new Error("command_policy_page_limit");
+    }
+}
+//# sourceMappingURL=cloud-command-policy-sync.js.map

package/dist/cloud-connector.d.ts

@@ -1,12 +1,14 @@
 import type { BotEnvironment } from "@helyx/config";
-import { type SupportBugCreatePayload, type SupportBugCreateResponsePayload } from "@helyx/control-protocol";
+import { cloudControlResponsePayloadSchema, type CloudControlRequestPayload, type SupportBugCreatePayload, type SupportBugCreateResponsePayload } from "@helyx/control-protocol";
 import { type CloudConnectorConsentRecord, type DatabasePool } from "@helyx/database";
 import type { Client } from "discord.js";
 import type { Logger } from "pino";
+import { z } from "zod";
 import type { ConfiguredModulePackage } from "./modules.js";
 import type { GuildCommandReadHandler } from "./guild-command-read-service.js";
 import { type CloudConnectorStore } from "./cloud-control-dispatcher.js";
 import { type BotControlHandler } from "./control-server.js";
+import type { CommandPolicyRuntime } from "./command-policy-runtime.js";
 type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "recovery_required" | "revoked" | "stopped";
 export interface CloudConnectorStatus {
     state: ConnectorState;
@@ -68,6 +70,8 @@ export declare class CloudConnectorController implements CloudConnector {
         database?: never;
     }));
     setControlHandler(handler: BotControlHandler, commands?: GuildCommandReadHandler): void;
+    /** Called only after the runtime has claimed its immutable SQL owner scope. */
+    setCommandPolicyDelivery(runtime: CommandPolicyRuntime): Promise<void>;
     start(): Promise<void>;
     status(): CloudConnectorStatus;
     getSupportConsent(): Promise<CloudConnectorConsentRecord>;
@@ -88,6 +92,7 @@ export declare class CloudConnectorUserError extends Error {
     constructor(message: string);
 }
 export declare function mapControlError(error: unknown): "not_found" | "conflict" | "bad_request" | "forbidden" | "temporarily_unavailable" | "internal_error";
+export declare function cloudControlFailureResponse(operation: CloudControlRequestPayload["operation"], error: unknown): z.infer<typeof cloudControlResponsePayloadSchema>;
 export declare function safeControlMessage(error: unknown): string;
 export {};
 //# sourceMappingURL=cloud-connector.d.ts.map