@helyx/bot 1.5.2 → 1.5.4

package/dist/emergency-deletion-dispatcher.js

@@ -0,0 +1,502 @@
+/** Dormant private queue. No SDK service, provider adapter or runtime registration. */
+export class EmergencyDeletionDispatcher {
+    #entries = new Map();
+    #routes = new Map();
+    #guilds = new Map();
+    #options;
+    #now;
+    #timer;
+    #lastTime = 0;
+    #globalBlockedUntil = 0;
+    #inFlight = 0;
+    #dropped = 0;
+    #stopped = false;
+    #pumping = false;
+    constructor(options) {
+        for (const [value, minimum, maximum] of [
+            [options.capacity, 1, 100_000],
+            [options.perChannelCapacity, 1, options.capacity],
+            [options.perGuildCapacity, 1, Math.max(1, options.capacity - 1)],
+            [options.concurrency, 1, options.capacity],
+            [options.maximumAgeMs, 1, 600_000],
+            [options.maximumAttempts, 1, 16],
+            [options.transientBackoffMs, 1, 600_000],
+            [options.maximumBackoffMs, options.transientBackoffMs, 600_000],
+            [options.maximumRetryAfterMs, 1, 86_400_000],
+        ])
+            if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+                throw new TypeError("Invalid emergency deletion queue limits");
+        if (typeof options.isCurrent !== "function" ||
+            typeof options.transport?.deleteExact !== "function" ||
+            (options.now !== undefined && typeof options.now !== "function"))
+            throw new TypeError("Invalid emergency deletion queue ports");
+        this.#options = Object.freeze({ ...options });
+        this.#now = options.now ?? (() => performance.now());
+    }
+    enqueue(input, authority) {
+        return this.#enqueue(input, authority).result;
+    }
+    /** Synchronous Core ownership result; duplicate entries share their SDK promise. */
+    enqueueCaptured(input, authority) {
+        const accepted = this.#enqueue(input, authority);
+        return Object.freeze({
+            result: accepted.sdkResult,
+            retainedProvidedAuthority: accepted.retainedProvidedAuthority,
+        });
+    }
+    #enqueue(input, authority) {
+        if (this.#stopped)
+            return resolved("stopped");
+        let stable;
+        try {
+            stable = Object.freeze({
+                guildId: input.guildId,
+                moduleId: input.moduleId,
+                channelId: input.channelId,
+                messageId: input.messageId,
+                admissionToken: input.admissionToken,
+            });
+            if (![stable.guildId, stable.channelId, stable.messageId].every((id) => typeof id === "string" && /^\d{17,20}$/u.test(id)) ||
+                typeof stable.moduleId !== "string" ||
+                !/^helyx\.[a-z0-9][a-z0-9-]{0,79}$/u.test(stable.moduleId) ||
+                typeof stable.admissionToken !== "string" ||
+                !/^[A-Za-z0-9._:-]{1,256}$/u.test(stable.admissionToken))
+                return resolved("invalid-request");
+        }
+        catch {
+            return resolved("invalid-request");
+        }
+        const capturedAuthority = authority === undefined ? undefined : captureAuthority(stable, authority);
+        if (capturedAuthority === null)
+            return resolved("invalid-request");
+        if (this.#stopped)
+            return resolved("stopped");
+        const now = this.#time();
+        if (now === null)
+            return resolved("stopped");
+        this.#pump();
+        if (this.#stopped)
+            return resolved("stopped");
+        const current = this.#current(stable, capturedAuthority);
+        if (this.#stopped)
+            return resolved("stopped");
+        if (!current)
+            return resolved("revoked");
+        const routeKey = `${stable.guildId}/${stable.channelId}`;
+        const key = `${routeKey}/${stable.messageId}/${stable.moduleId}/${stable.admissionToken}`;
+        const duplicate = this.#entries.get(key);
+        if (duplicate)
+            return submitted(duplicate, authority);
+        let route = this.#routes.get(routeKey);
+        const guildRoutes = this.#guilds.get(stable.guildId);
+        const guildEntries = [...(guildRoutes?.values() ?? [])].reduce((total, item) => total + item.entries.length, 0);
+        if (this.#entries.size >= this.#options.capacity ||
+            guildEntries >= this.#options.perGuildCapacity ||
+            (route?.entries.length ?? 0) >= this.#options.perChannelCapacity ||
+            (!route &&
+                (this.#routes.size >= this.#options.capacity ||
+                    (guildRoutes?.size ?? 0) >= this.#options.perGuildCapacity))) {
+            this.#dropped = Math.min(Number.MAX_SAFE_INTEGER, this.#dropped + 1);
+            return resolved("capacity");
+        }
+        if (!route) {
+            route = {
+                key: routeKey,
+                guildId: stable.guildId,
+                entries: [],
+                blockedUntil: 0,
+                active: false,
+            };
+            this.#routes.set(routeKey, route);
+            let routes = this.#guilds.get(stable.guildId);
+            if (!routes) {
+                routes = new Map();
+                this.#guilds.set(stable.guildId, routes);
+            }
+            routes.set(routeKey, route);
+        }
+        let settle;
+        let settleSdk;
+        const result = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const sdkResult = new Promise((resolve) => {
+            settleSdk = resolve;
+        });
+        const entry = {
+            key,
+            input: stable,
+            acceptedAt: now,
+            readyAt: now,
+            attempts: 0,
+            active: false,
+            authority: capturedAuthority,
+            providedAuthority: authority,
+            result,
+            sdkResult,
+            settle,
+            settleSdk,
+        };
+        this.#entries.set(key, entry);
+        route.entries.push(entry);
+        this.#pump();
+        return submitted(entry, authority);
+    }
+    /** Lifecycle callers can synchronously discard waiting work after revocation. */
+    revalidate() {
+        this.#pump();
+    }
+    stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#clearTimer();
+        for (const route of this.#routes.values()) {
+            for (const entry of [...route.entries]) {
+                this.#revoke(entry);
+                if (!entry.active)
+                    this.#finish(route, entry, "stopped");
+            }
+            if (!route.active)
+                this.#removeRoute(route);
+        }
+        // Already-issued requests retain their actual outcome; they cannot be recalled.
+    }
+    stats() {
+        return Object.freeze({
+            pending: this.#entries.size - this.#inFlight,
+            inFlight: this.#inFlight,
+            retainedRoutes: this.#routes.size,
+            dropped: this.#dropped,
+            stopped: this.#stopped,
+        });
+    }
+    #current(input, authority) {
+        try {
+            return (this.#options.isCurrent(input) === true &&
+                !this.#stopped &&
+                (authority === undefined || authority.isCurrent() === true) &&
+                !this.#stopped);
+        }
+        catch {
+            return false;
+        }
+    }
+    #time() {
+        try {
+            const value = this.#now();
+            if (this.#stopped)
+                return null;
+            if (!Number.isFinite(value) ||
+                value < this.#lastTime ||
+                value > Number.MAX_SAFE_INTEGER - 600_000)
+                throw new Error("Invalid monotonic clock");
+            this.#lastTime = value;
+            return value;
+        }
+        catch {
+            this.stop();
+            return null;
+        }
+    }
+    #pump() {
+        if (this.#stopped || this.#pumping)
+            return;
+        this.#pumping = true;
+        try {
+            let now = this.#time();
+            if (now === null)
+                return;
+            for (const route of this.#routes.values()) {
+                for (const entry of [...route.entries]) {
+                    if (entry.active)
+                        continue;
+                    if (now >= entry.acceptedAt + this.#options.maximumAgeMs)
+                        this.#finish(route, entry, "expired");
+                    else if (!this.#current(entry.input, entry.authority))
+                        this.#finish(route, entry, "revoked");
+                }
+                if (!route.entries.length && route.blockedUntil <= now)
+                    this.#removeRoute(route);
+            }
+            while (!this.#stopped &&
+                this.#inFlight < this.#options.concurrency &&
+                now >= this.#globalBlockedUntil) {
+                const route = this.#nextRoute(now);
+                if (!route)
+                    break;
+                const entry = route.entries[0];
+                if (entry.attempts >= this.#options.maximumAttempts) {
+                    this.#finish(route, entry, "attempts-exhausted");
+                    continue;
+                }
+                // Revalidate immediately before handing anything to the transport.
+                if (!this.#current(entry.input, entry.authority)) {
+                    this.#finish(route, entry, "revoked");
+                    continue;
+                }
+                if (this.#stopped)
+                    break;
+                now = this.#time();
+                if (now === null)
+                    break;
+                if (now >= entry.acceptedAt + this.#options.maximumAgeMs) {
+                    this.#finish(route, entry, "expired");
+                    continue;
+                }
+                entry.active = true;
+                route.active = true;
+                entry.attempts++;
+                this.#inFlight++;
+                void this.#execute(route, entry);
+            }
+        }
+        finally {
+            this.#pumping = false;
+            this.#schedule();
+        }
+    }
+    #nextRoute(now) {
+        for (const [guildId, routes] of this.#guilds) {
+            for (const [key, route] of routes) {
+                const first = route.entries[0];
+                if (!route.active &&
+                    first &&
+                    now >= first.readyAt &&
+                    now >= route.blockedUntil) {
+                    // Move both selections to the tail; many channels do not buy extra turns.
+                    routes.delete(key);
+                    routes.set(key, route);
+                    this.#guilds.delete(guildId);
+                    this.#guilds.set(guildId, routes);
+                    return route;
+                }
+            }
+        }
+        return undefined;
+    }
+    async #execute(route, entry) {
+        let outcome;
+        const attemptNumber = entry.attempts;
+        let refused = false;
+        let attemptSettled = false;
+        const live = () => !this.#stopped &&
+            !attemptSettled &&
+            entry.active &&
+            entry.attempts === attemptNumber &&
+            this.#entries.get(entry.key) === entry;
+        const attempt = Object.freeze({
+            isCurrent: () => {
+                if (refused)
+                    return false;
+                const now = live() ? this.#time() : null;
+                if (now === null ||
+                    now >= entry.acceptedAt + this.#options.maximumAgeMs ||
+                    !live() ||
+                    !this.#current(entry.input, entry.authority) ||
+                    !live()) {
+                    refused = true;
+                    return false;
+                }
+                const checkedAt = this.#time();
+                if (checkedAt === null ||
+                    checkedAt >= entry.acceptedAt + this.#options.maximumAgeMs ||
+                    !live()) {
+                    refused = true;
+                    return false;
+                }
+                return true;
+            },
+        });
+        try {
+            const response = await this.#options.transport.deleteExact(entry.input, attempt, entry.authority);
+            attemptSettled = true;
+            outcome = normalizeTransportResult(response);
+        }
+        catch {
+            attemptSettled = true;
+            outcome = { kind: "transient" };
+        }
+        entry.active = false;
+        route.active = false;
+        this.#inFlight--;
+        try {
+            if (isTerminal(outcome?.kind)) {
+                this.#finish(route, entry, outcome.kind);
+                return;
+            }
+            if (this.#stopped) {
+                this.#finish(route, entry, "stopped");
+                return;
+            }
+            const now = this.#time();
+            if (now === null) {
+                this.#finish(route, entry, "stopped");
+                return;
+            }
+            if (outcome?.kind === "retry") {
+                if (!Number.isFinite(outcome.afterMs) ||
+                    outcome.afterMs <= 0 ||
+                    outcome.afterMs > this.#options.maximumRetryAfterMs ||
+                    outcome.afterMs > Number.MAX_SAFE_INTEGER - now ||
+                    (outcome.scope !== "route" && outcome.scope !== "global")) {
+                    this.#finish(route, entry, "failed");
+                    return;
+                }
+                route.blockedUntil = Math.max(route.blockedUntil, now + outcome.afterMs);
+                if (outcome.scope === "global")
+                    this.#globalBlockedUntil = Math.max(this.#globalBlockedUntil, route.blockedUntil);
+                entry.readyAt = route.blockedUntil;
+            }
+            else if (outcome?.kind === "transient") {
+                entry.readyAt =
+                    now +
+                        Math.min(this.#options.maximumBackoffMs, this.#options.transientBackoffMs * 2 ** (entry.attempts - 1));
+            }
+            else {
+                this.#finish(route, entry, "failed");
+                return;
+            }
+            if (entry.attempts >= this.#options.maximumAttempts)
+                this.#finish(route, entry, "attempts-exhausted");
+        }
+        finally {
+            this.#pump();
+        }
+    }
+    #finish(route, entry, kind) {
+        if (!this.#entries.delete(entry.key))
+            return;
+        const index = route.entries.indexOf(entry);
+        if (index >= 0)
+            route.entries.splice(index, 1);
+        entry.settle(Object.freeze({
+            kind,
+            issued: entry.attempts > 0,
+            attempts: entry.attempts,
+        }));
+        entry.settleSdk(Object.freeze({
+            outcome: kind,
+            issued: entry.attempts > 0,
+            attempts: entry.attempts,
+        }));
+        if (!route.entries.length && route.blockedUntil <= this.#lastTime)
+            this.#removeRoute(route);
+        this.#revoke(entry);
+    }
+    #revoke(entry) {
+        const authority = entry.authority;
+        entry.authority = undefined;
+        entry.providedAuthority = undefined;
+        try {
+            authority?.stop();
+        }
+        catch {
+            /* A cleanup port cannot replace the actual result. */
+        }
+    }
+    #removeRoute(route) {
+        if (this.#routes.get(route.key) !== route)
+            return;
+        this.#routes.delete(route.key);
+        const routes = this.#guilds.get(route.guildId);
+        routes?.delete(route.key);
+        if (!routes?.size)
+            this.#guilds.delete(route.guildId);
+    }
+    #clearTimer() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    #schedule() {
+        this.#clearTimer();
+        if (this.#stopped)
+            return;
+        const now = this.#time();
+        if (now === null)
+            return;
+        let next = Infinity;
+        for (const route of this.#routes.values()) {
+            if (!route.entries.length && route.blockedUntil > now)
+                next = Math.min(next, route.blockedUntil);
+            for (const entry of route.entries)
+                if (!entry.active)
+                    next = Math.min(next, entry.acceptedAt + this.#options.maximumAgeMs);
+            const first = route.entries[0];
+            if (!route.active &&
+                first &&
+                this.#inFlight < this.#options.concurrency) {
+                const ready = Math.max(first.readyAt, route.blockedUntil, this.#globalBlockedUntil);
+                if (ready > now)
+                    next = Math.min(next, ready);
+            }
+        }
+        if (Number.isFinite(next)) {
+            this.#timer = setTimeout(() => {
+                this.#timer = undefined;
+                this.#pump();
+            }, Math.min(2_147_483_647, Math.max(1, Math.ceil(next - now))));
+            this.#timer.unref?.();
+        }
+    }
+}
+function isTerminal(value) {
+    return (value === "deleted" ||
+        value === "already-absent" ||
+        value === "missing-permission" ||
+        value === "invalid-request" ||
+        value === "failed");
+}
+function normalizeTransportResult(value) {
+    try {
+        const kind = value?.kind;
+        if (isTerminal(kind) || kind === "transient")
+            return { kind };
+        if (kind === "retry")
+            return { kind, afterMs: value.afterMs, scope: value.scope };
+    }
+    catch {
+        // Never retain raw provider objects, accessors, diagnostics or content.
+    }
+    return { kind: "failed" };
+}
+function resolved(kind) {
+    return Object.freeze({
+        result: Promise.resolve(Object.freeze({ kind, issued: false, attempts: 0 })),
+        sdkResult: Promise.resolve(Object.freeze({ outcome: kind, issued: false, attempts: 0 })),
+        retainedProvidedAuthority: false,
+    });
+}
+function submitted(entry, authority) {
+    return Object.freeze({
+        result: entry.result,
+        sdkResult: entry.sdkResult,
+        retainedProvidedAuthority: authority !== undefined &&
+            entry.authority !== undefined &&
+            entry.providedAuthority === authority,
+    });
+}
+function captureAuthority(input, authority) {
+    try {
+        const original = authority.scope;
+        const scope = Object.freeze({
+            guildId: original.guildId,
+            moduleId: original.moduleId,
+            channelId: original.channelId,
+            messageId: original.messageId,
+            admissionToken: original.admissionToken,
+        });
+        const current = authority.isCurrent;
+        const stop = authority.stop;
+        if (typeof current !== "function" ||
+            typeof stop !== "function" ||
+            !Object.keys(input).every((key) => Reflect.get(scope, key) === Reflect.get(input, key)))
+            return null;
+        return Object.freeze({ scope, isCurrent: current, stop });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=emergency-deletion-dispatcher.js.map

package/dist/emergency-deletion-rest-transport.d.ts

@@ -0,0 +1,24 @@
+import type { Client } from "discord.js";
+import { Agent } from "undici";
+import type { CachedMessageDeletionAuthority } from "./cached-message-deletion-authority.js";
+import type { EmergencyDeletionAttemptContext, EmergencyDeletionTransport, EmergencyDeletionTransportResult, EmergencyMessageDeletion } from "./emergency-deletion-dispatcher.js";
+interface Options {
+    client: Client;
+    agent: Agent;
+    expectedApplicationId: string;
+    maximumAgeMs: number;
+    maximumDispatches: number;
+    now?: () => number;
+}
+/**
+ * Dormant transport. Core owns grants/lifecycle and the standard shared REST manager.
+ * Its method/strategy/handler surfaces must remain stable: a custom replacement that
+ * ignores dispatcher during REST's internal waits is outside this wire-fence contract.
+ */
+export declare class EmergencyMessageDeletionRestTransport implements EmergencyDeletionTransport {
+    #private;
+    constructor(options: Options);
+    deleteExact(input: EmergencyMessageDeletion, attempt: EmergencyDeletionAttemptContext, grant?: CachedMessageDeletionAuthority): Promise<EmergencyDeletionTransportResult>;
+}
+export {};
+//# sourceMappingURL=emergency-deletion-rest-transport.d.ts.map