forge-jsxy 1.0.66

package/dist/discordRateLimit.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Shared Discord HTTP 429 handling (bot REST + webhooks).
+ *
+ * Strategies implemented
+ * ──────────────────────
+ * 1. Retry-After header / retry_after JSON body — both read and respected on 429.
+ * 2. Exponential back-off with random jitter — avoids thundering herd when many
+ *    agents retry at the same instant.
+ * 3. Proactive per-route bucket tracking (DiscordBucketTracker) — reads
+ *    X-RateLimit-Remaining + X-RateLimit-Reset-After on *every* response.
+ *    When remaining==0 the bucket is marked as exhausted and the next caller
+ *    pre-waits before the request, preventing the 429 entirely.
+ * 4. Global rate-limit detection — X-RateLimit-Global / X-RateLimit-Scope headers
+ *    on 429 pause ALL routes for that tracker's token.
+ * 5. X-RateLimit-Scope: shared — 429s with scope=shared do NOT count toward the
+ *    Cloudflare 10 000/10 min invalid-request ban; they are still respected but
+ *    not treated as fatal.
+ * 6. configurable max attempts — RELAY_DISCORD_429_MAX_ATTEMPTS /
+ *    FORGE_JS_DISCORD_429_MAX_ATTEMPTS (1–12, default 12).
+ *
+ * @see https://discord.com/developers/docs/topics/rate-limits
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayDiscordBucketTracker = exports.DiscordBucketTracker = void 0;
+exports.sleepMs = sleepMs;
+exports.discord429DelayMs = discord429DelayMs;
+exports.discord429MaxAttempts = discord429MaxAttempts;
+exports.fetchUntilNot429 = fetchUntilNot429;
+exports.discordBackoffMsFromErrorText = discordBackoffMsFromErrorText;
+async function sleepMs(ms) {
+    await new Promise((r) => setTimeout(r, ms));
+}
+function clampRetryMs(ms) {
+    return Math.min(120_000, Math.max(250, ms));
+}
+/**
+ * Parse Discord `retry_after` (JSON body, seconds) or `Retry-After` (header, seconds).
+ * Adds small random jitter (+0–400 ms) so many agents don't all retry simultaneously.
+ */
+async function discord429DelayMs(res) {
+    const h = res.headers.get("retry-after");
+    if (h) {
+        const sec = Number.parseFloat(h.trim());
+        if (Number.isFinite(sec)) {
+            return clampRetryMs(Math.ceil(sec * 1000) + Math.floor(Math.random() * 400));
+        }
+    }
+    try {
+        const t = await res.clone().text();
+        const j = JSON.parse(t);
+        if (typeof j.retry_after === "number" && Number.isFinite(j.retry_after)) {
+            return clampRetryMs(Math.ceil(j.retry_after * 1000) + Math.floor(Math.random() * 400));
+        }
+    }
+    catch {
+        /* non-JSON 429 body */
+    }
+    return clampRetryMs(1000 + Math.floor(Math.random() * 400));
+}
+/** Max attempts per logical Discord call (first try + retries after 429). Default 12. */
+function discord429MaxAttempts() {
+    const raw = (process.env.RELAY_DISCORD_429_MAX_ATTEMPTS ||
+        process.env.FORGE_JS_DISCORD_429_MAX_ATTEMPTS ||
+        "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 1 && n <= 12)
+            return n;
+    }
+    return 12;
+}
+// ── Proactive bucket tracker ──────────────────────────────────────────────────
+/**
+ * Tracks Discord per-route and global rate-limit bucket state for ONE bot token.
+ *
+ * Call `update()` after every Discord response so remaining-request state is
+ * always fresh.  Call `preWaitMs()` before a request to get the number of ms
+ * to sleep before sending (0 if the bucket is not exhausted).
+ *
+ * This is PROACTIVE: by pre-waiting when `remaining==0` we avoid triggering
+ * a 429 in the first place, reducing both latency and Cloudflare invalid-request
+ * counts (since prevented 429s never hit Discord).
+ */
+class DiscordBucketTracker {
+    /** bucket-hash (or route key) → epoch ms at which the bucket resets */
+    _pauseUntil = new Map();
+    /** All routes for this token pause until this epoch ms (global 429). */
+    _globalPauseUntil = 0;
+    /**
+     * Update internal state from a Discord REST response.
+     * Should be called for EVERY response — 200s, 204s, and 429s alike.
+     */
+    update(headers, routeKey) {
+        const now = Date.now();
+        const bucket = headers.get("X-RateLimit-Bucket");
+        const remaining = headers.get("X-RateLimit-Remaining");
+        const resetAfter = headers.get("X-RateLimit-Reset-After");
+        if (remaining !== null && resetAfter !== null) {
+            const rem = parseInt(remaining, 10);
+            const resetMs = parseFloat(resetAfter) * 1000;
+            if (rem === 0 && Number.isFinite(resetMs) && resetMs >= 0) {
+                // Mark bucket exhausted — add a 75 ms safety buffer
+                const key = bucket ?? routeKey;
+                this._pauseUntil.set(key, now + resetMs + 75);
+            }
+        }
+        // Opportunistic clean-up of stale entries
+        if (Math.random() < 0.05) {
+            for (const [k, v] of this._pauseUntil) {
+                if (v <= now)
+                    this._pauseUntil.delete(k);
+            }
+        }
+    }
+    /**
+     * Set a global pause (all routes). Called when X-RateLimit-Global == "true"
+     * or X-RateLimit-Scope == "global" is found on a 429 response.
+     */
+    setGlobalPause(retryAfterMs) {
+        this._globalPauseUntil = Date.now() + retryAfterMs + 100;
+    }
+    /**
+     * Set a per-route pause.  Called on a per-route 429 to block that specific
+     * bucket until the reset window elapses.
+     */
+    setRoutePause(routeKey, bucket, retryAfterMs) {
+        const key = bucket ?? routeKey;
+        this._pauseUntil.set(key, Date.now() + retryAfterMs + 100);
+    }
+    /**
+     * Returns ms to pre-wait before sending a request to `routeKey`.
+     * Returns 0 when the route is not rate-limited.
+     * Adds a tiny random jitter (0–30 ms) so many concurrent calls stagger.
+     */
+    preWaitMs(routeKey, bucket) {
+        const now = Date.now();
+        let wait = Math.max(0, this._globalPauseUntil - now);
+        const key = bucket ?? routeKey;
+        const pause = this._pauseUntil.get(key) ?? 0;
+        wait = Math.max(wait, Math.max(0, pause - now));
+        if (wait > 0) {
+            wait += Math.floor(Math.random() * 30); // jitter
+        }
+        return wait;
+    }
+    /** For testing / diagnostics. */
+    isGloballyPaused() {
+        return this._globalPauseUntil > Date.now();
+    }
+}
+exports.DiscordBucketTracker = DiscordBucketTracker;
+/** Shared tracker for all relay-side Discord REST calls. One per module load. */
+exports.relayDiscordBucketTracker = new DiscordBucketTracker();
+// ── fetchUntilNot429 ─────────────────────────────────────────────────────────
+/**
+ * Re-invokes `doFetch` until the response is not 429 or max attempts are exhausted.
+ * Respects `Retry-After` / `retry_after` with jitter on every back-off.
+ *
+ * Optional `routeKey` + `tracker` enable proactive bucket tracking:
+ * - Pre-waits before the first attempt if the tracker says the bucket is exhausted.
+ * - Updates the tracker after every response.
+ * - Distinguishes global 429 (pauses all routes) from per-route 429.
+ *
+ * Backward compatible — `routeKey` and `tracker` default to undefined.
+ */
+async function fetchUntilNot429(doFetch, routeKey, tracker) {
+    const max = discord429MaxAttempts();
+    // Proactive pre-wait if we already know this bucket is exhausted
+    if (tracker && routeKey) {
+        const pre = tracker.preWaitMs(routeKey);
+        if (pre > 0) {
+            await sleepMs(pre);
+        }
+    }
+    let res = await doFetch();
+    // Update tracker from first response headers
+    if (tracker && routeKey) {
+        tracker.update(res.headers, routeKey);
+    }
+    for (let i = 0; i < max - 1 && res.status === 429; i++) {
+        const delay = await discord429DelayMs(res);
+        if (tracker && routeKey) {
+            const isGlobal = res.headers.get("X-RateLimit-Global") === "true" ||
+                res.headers.get("X-RateLimit-Scope") === "global";
+            const bucket = res.headers.get("X-RateLimit-Bucket");
+            if (isGlobal) {
+                tracker.setGlobalPause(delay);
+            }
+            else {
+                tracker.setRoutePause(routeKey, bucket, delay);
+            }
+        }
+        await sleepMs(delay);
+        res = await doFetch();
+        if (tracker && routeKey) {
+            tracker.update(res.headers, routeKey);
+        }
+    }
+    return res;
+}
+// ── Error-text backoff (ticket/webhook flow) ──────────────────────────────────
+function looksLikeDiscordRateLimitMessage(text) {
+    return /429|rate limit|rate_limited|being rate limited/i.test(String(text));
+}
+/**
+ * Milliseconds to wait after a failed Discord ticket/webhook step when the error
+ * text embeds JSON `"retry_after"` or clearly indicates rate limiting.
+ * Returns **0** when the error is not a rate-limit signal.
+ * @param minWaitMs — floor when `retry_after` is tiny (default **5000** ms).
+ */
+function discordBackoffMsFromErrorText(errText, minWaitMs = 5000) {
+    const t = String(errText);
+    const m = t.match(/"retry_after"\s*:\s*([0-9.]+)/);
+    if (m) {
+        const sec = parseFloat(m[1]);
+        if (Number.isFinite(sec)) {
+            let ms = Math.ceil(sec * 1000) + 250;
+            ms = Math.max(minWaitMs, ms);
+            return Math.min(120_000, ms);
+        }
+    }
+    if (looksLikeDiscordRateLimitMessage(t)) {
+        return clampRetryMs(minWaitMs + Math.floor(Math.random() * 400));
+    }
+    return 0;
+}

package/dist/discordRelayUpload.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Human-readable Discord REST errors for relay logs and agent-facing ticket/upload failures.
+ * @see https://discord.com/developers/docs/topics/opcodes-and-status-codes#json
+ */
+export declare function formatDiscordApiFailure(status: number, body: string): string;
+export declare function discordRelayScreenshotEnabled(): boolean;
+/** Discord text channel names: lowercase, alphanumeric, hyphens; max 100 chars. */
+export declare function sanitizeDiscordClientChannelName(clientId: string): string;
+type DiscordChannelRow = {
+    id: string;
+    name: string;
+    type: number;
+    parent_id?: string | null;
+};
+/** Exported for tests / diagnostics. */
+export declare function clearDiscordChannelCache(): void;
+export declare function listGuildTextChannels(botToken: string, guildId: string): Promise<DiscordChannelRow[]>;
+export declare function createGuildTextChannel(botToken: string, guildId: string, name: string, parentId?: string): Promise<string>;
+/**
+ * Resolve (or create) the Discord text channel for this client.
+ *
+ * **Caching**: the resolved channel ID is stored in `_channelIdCache` so that
+ * subsequent calls skip the `GET /guilds/{id}/channels` list entirely — the most
+ * expensive REST call in the relay hot path.  Cache is invalidated automatically
+ * when a 404 is detected on message POST.
+ */
+export declare function resolveScreenshotChannelId(botToken: string, guildId: string, clientId: string, parentCategoryId?: string): Promise<string>;
+export declare function postPngToDiscordChannel(botToken: string, channelId: string, png: Buffer, caption: string): Promise<{
+    ok: true;
+    message_id: string;
+} | {
+    ok: false;
+    error: string;
+    channelNotFound?: boolean;
+}>;
+export type DiscordScreenshotUploadMsg = {
+    request_id?: unknown;
+    client_id?: unknown;
+    b64?: unknown;
+    caption?: unknown;
+};
+export declare function handleDiscordScreenshotUploadFromAgent(msg: DiscordScreenshotUploadMsg): Promise<Record<string, unknown>>;
+/**
+ * HF-style ticket: relay mints a **channel incoming webhook** (bot token stays on relay).
+ * Agent POSTs PNG directly to `webhook_url`, then sends `relay_discord_upload_ack` so the relay
+ * deletes the webhook (revokes the URL).
+ */
+export declare function handleDiscordUploadTicketRequest(msg: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function handleDiscordUploadAck(msg: Record<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * Call once when the relay starts listening — if Discord screenshots are enabled but the bot cannot
+ * access `RELAY_DISCORD_GUILD_ID`, operators see an immediate warning in logs.
+ */
+export declare function warnDiscordRelayGuildIfMisconfigured(): Promise<void>;
+export {};