charness 0.0.0-stage → 3.1.0

package/dist/rateLimiter.d.ts

@@ -0,0 +1,246 @@
+import type { SessionKey } from './sessionKey';
+import { formatRateSummaryLine } from './utils/rateLimitLog';
+/**
+ * @description Telegram-side rate limiting for the multi-thread bot.
+ *
+ * Three layers, with different responsibilities:
+ *
+ *   1. **Per-thread FIFO queue** (`enqueueSend`). Keyed by **SessionKey**
+ *      (`chatId+threadId`). Its only job is to preserve ordering between
+ *      *dependent* operations on the same Telegram thread — e.g. an
+ *      `editMessageText` that depends on a preceding `sendMessage`. Two
+ *      forum topics interleave freely; only within one thread is ordering
+ *      guaranteed.
+ *
+ *   2. **Global send pacer** ({@link GlobalSendPacer}). ONE process-wide
+ *      frequency gate: it releases at most one send every
+ *      {@link globalSendIntervalMs} across ALL chats (supergroup + owner DM),
+ *      FCFS among waiters. It is CLOCK-BASED and NON-BLOCKING: a permit is
+ *      granted on a timer, decoupled from whether the previous send's `fn`
+ *      finished, so a slow/stuck send never head-of-line-blocks the others.
+ *      This replaced the old per-chat priority token bucket: at ~1 send / 2 s
+ *      Telegram never 429s under normal multi-topic use, and pure temporal
+ *      FCFS (no priority classes) keeps cross-topic output in the order it
+ *      was produced.
+ *
+ *   3. **`withRateLimitRetry`.** Keyed by **chatId**. Reactive: if Telegram
+ *      still returns 429, sleep `retry_after + jitter` and retry once. A
+ *      second 429 marks the chat blocked for the cooldown and surfaces a
+ *      typed {@link RateLimitedError}. 429-state is per-chat because that's
+ *      how Telegram returns it.
+ *
+ * The layers compose: `enqueueSend(key, fn)` chains behind the previous send
+ * for the *same thread*, then waits the global pacer, then runs `fn` through
+ * `withRateLimitRetry`. `withRateLimitRetry` stays exported for callers that
+ * need the retry without the proactive pacer (e.g. boot admin / health-check
+ * operations).
+ */
+/**
+ * @description The global frequency gate: at most one send is released every
+ * {@link globalSendIntervalMs} across ALL chats. Steady state ≈ 1 send / 2 s,
+ * so Telegram's per-chat budget is never overrun under multi-topic streaming.
+ */
+export declare const globalSendIntervalMs = 2000;
+/**
+ * @description Default bound (ms) for {@link drainPendingSends}: how long the
+ * graceful-shutdown flush waits for the per-thread send FIFOs to empty before
+ * giving up. Sized well under the 10s shutdown watchdog so the later steps
+ * (transient-frame sweep, update drain, `state.flush()`) keep their budgets.
+ */
+export declare const shutdownDrainMaxMs = 6000;
+/**
+ * @description Injectable clock + timer so timing tests can drive the pacer
+ * deterministically with a fake clock instead of real-time sleeps.
+ */
+export interface PacerClock {
+    now: () => number;
+    setTimeout: (fn: () => void, ms: number) => void;
+}
+/**
+ * @description Process-wide FCFS frequency gate. `acquire()` resolves when a
+ * send permit is granted; permits are released one per {@link intervalMs},
+ * granted to waiters in strict arrival order (FCFS).
+ *
+ * CLOCK-BASED + NON-BLOCKING by design: the "next permit" time advances on a
+ * timer, never on the completion of a previous caller's send. A caller whose
+ * `fn` hangs after `acquire()` therefore cannot delay any other waiter — there
+ * is no head-of-line blocking through this gate.
+ */
+export declare class GlobalSendPacer {
+    private intervalMs;
+    private clock;
+    /** Waiters parked for a permit, resolved in FIFO (arrival) order. */
+    private waiters;
+    /** Earliest clock time the next permit may be granted. */
+    private nextAllowedAt;
+    /** A drain timer is already armed for the current waiter set. */
+    private timerArmed;
+    /** Generation token that makes overdue, logically replaced timers inert. */
+    private timerGeneration;
+    /** Shutdown-drain mode: permits are granted immediately, no spacing. */
+    private isShutdownDraining;
+    constructor(intervalMs: number, clock?: PacerClock);
+    /** How many sends are currently parked waiting for a permit. */
+    getPendingCount(): number;
+    /**
+     * Flip the pacer into shutdown-drain mode: every parked waiter is released
+     * NOW (in FIFO order) and every subsequent `acquire()` resolves immediately.
+     * ONLY for the graceful-shutdown flush — during live operation the spacing is
+     * what keeps Telegram from 429ing; `withRateLimitRetry` stays on every send
+     * either way, so the small shutdown burst remains 429-safe. One-way: the
+     * process is exiting, so there is no leave-drain path.
+     */
+    enterShutdownDrain(): void;
+    /**
+     * Resolve when a send permit is granted. Fast path: when nobody is waiting
+     * and the window is already open, grant immediately (so a send after a ≥
+     * interval-long idle never eats a needless delay). Otherwise queue FIFO and
+     * let the clock-driven drain grant it in turn.
+     */
+    acquire(signal?: AbortSignal): Promise<void>;
+    /** Arm a single timer to grant the head waiter when the window next opens. */
+    private armDrain;
+    /** Logically cancel an armed timer when the pacing window is replaced. */
+    private invalidateDrainTimer;
+    /** Grant exactly one permit (the head waiter), advance the clock, re-arm. */
+    private drainOne;
+}
+/**
+ * @description Test-only seam: replace the process pacer with one on a
+ * deterministic clock so `enqueueSend` integration tests run instantly instead
+ * of waiting real 2 s windows. Never called in production.
+ */
+export declare function __setGlobalPacerForTest(pacer: GlobalSendPacer): void;
+export declare const rateLimiterConstants: {
+    readonly globalSendIntervalMs: 2000;
+};
+/**
+ * @description Snapshot of one chat's recent outbound rate, for the periodic
+ * summary in `bot.ts`. Returned together with the chat id by
+ * {@link getActiveChatRateSummaries}.
+ */
+export interface ChatRateSummary {
+    chatId: number;
+    sentPerMin: number;
+    peak10s: number;
+}
+/**
+ * @description Per-chat outbound-rate snapshots for every chat with activity in
+ * the rolling minute (silent chats omitted). The `bot.ts` periodic janitor logs
+ * these as `[RateLimit] rate …` lines — see {@link formatRateSummaryLine}.
+ */
+export declare function getActiveChatRateSummaries(nowMs?: number): ChatRateSummary[];
+/** Re-export the pure summary formatter so `bot.ts` has one import surface. */
+export { formatRateSummaryLine };
+/**
+ * @description Flip the process pacer into shutdown-drain mode (immediate
+ * release, no 2s spacing). ONLY called from the graceful-shutdown output flush
+ * — never during live operation, where the spacing is the 429 protection.
+ * Sends drained in this mode still run through {@link withRateLimitRetry}.
+ */
+export declare function enterShutdownDrain(): void;
+/** Verdict of {@link drainPendingSends}: did the FIFOs empty within the bound? */
+export type ShutdownDrainVerdict = 'drained' | 'timeout';
+/**
+ * @description Resolve once every per-thread send FIFO is empty, or after
+ * `maxWaitMs` — whichever comes first — reporting which. Pure bookkeeping over
+ * the existing {@link queues} map: it awaits the current queue tails (which
+ * never reject — `enqueueSend` tracks them settled-only) and loops, because a
+ * send finishing may have chained a successor onto the same thread's queue.
+ * Used by the graceful-shutdown flush after {@link enterShutdownDrain} so
+ * already-enqueued output lands before the process exits.
+ */
+export declare function drainPendingSends(maxWaitMs?: number): Promise<ShutdownDrainVerdict>;
+/**
+ * @description Check if a chat is currently rate-limited by Telegram.
+ * Used by the output debounce to lengthen delays during cooldown.
+ */
+export declare function checkIsRateLimited(chatId: number): boolean;
+/** Get remaining cooldown time in ms, 0 if not limited. */
+export declare function getRateLimitRemainingMs(chatId: number): number;
+interface TelegramErrorLike {
+    response?: {
+        error_code?: number;
+        parameters?: {
+            retry_after?: number;
+        };
+    };
+}
+/**
+ * @name RateLimitedError
+ * @description Thrown by {@link withRateLimitRetry} when a send still gets a
+ * 429 *after* the single retry. Carries the chat id and the remaining cooldown
+ * as a typed signal. The global pacer makes a sustained 429 essentially
+ * impossible, so this no longer drives any redelivery re-arm — it stays a typed
+ * error so a caller can recognise the 429 class if it ever surfaces.
+ *
+ * The original Telegram error payload is preserved on `response` so the
+ * existing classifier helpers (`checkIsApiError`, `getErrorCode`,
+ * `getErrorDescription`) keep working unchanged on this error.
+ */
+export declare class RateLimitedError extends Error {
+    readonly chatId: number;
+    readonly retryAfterMs: number;
+    readonly response?: TelegramErrorLike['response'];
+    constructor(chatId: number, retryAfterMs: number, original?: TelegramErrorLike);
+}
+export declare function checkIsRateLimitedError(err: unknown): err is RateLimitedError;
+/**
+ * @description Wraps a Telegram API call with 429 retry-after handling.
+ * On 429: waits the specified retry_after + jitter, retries once.
+ * If second attempt also fails with 429: marks chat as rate-limited, throws.
+ *
+ * Most call sites should prefer {@link enqueueSend}, which runs `fn` through
+ * the global pacer *and* `withRateLimitRetry`. Use this function directly only
+ * when you must bypass the proactive pacer (e.g. admin / health-check
+ * operations during boot).
+ */
+export declare function withRateLimitRetry<T>(chatId: number, operation: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+/**
+ * @description A send for a conversation of another platform (Jira connector
+ * plan J2b, R2): its operation never runs. Like a failed Telegram call it
+ * rejects, so an awaiting caller takes its error path.
+ */
+export declare class ForeignKeySendRefusedError extends Error {
+    constructor(key: SessionKey);
+}
+/**
+ * @description Send a Telegram operation OUTSIDE the global message pacer and
+ * the per-thread FIFO — still 429-safe ({@link withRateLimitRetry}) and still
+ * counted by {@link sendRateTracker}, but WITHOUT taking a
+ * {@link globalSendIntervalMs} permit and WITHOUT chaining behind the thread's
+ * other sends. Runs immediately.
+ *
+ * Reserved for the rare, non-output sends that must not consume the paced
+ * message budget nor queue behind streaming agent output:
+ *  - the typing indicator (`sendChatAction` — not a Telegram message, not
+ *    subject to the flood limit, so pacing it just wastes ~60% of the budget);
+ *  - the voice-transcript echo (the user's own input being acknowledged, which
+ *    should surface ahead of queued agent output).
+ *
+ * Do NOT route ordinary agent-output `sendMessage`s through this — that would
+ * break the FCFS ordering the pacer guarantees.
+ */
+export declare function sendUnpaced<T>(key: SessionKey, fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+/**
+ * @description Send a Telegram operation through the per-thread FIFO queue, the
+ * global send pacer, and per-chat 429 retry.
+ *
+ * - **Serialised per thread**: the next send for the same `SessionKey` only runs
+ *   after this one settles (success or failure). Sends for *different* threads
+ *   run concurrently, gated only by the global pacer.
+ * - **Paced globally**: {@link GlobalSendPacer} releases ≤1 send /
+ *   {@link globalSendIntervalMs} across all chats, FCFS. Permits are granted on
+ *   a clock, so a slow send never blocks another thread's permit.
+ * - **Retry on 429**: reactive backoff via {@link withRateLimitRetry}.
+ *
+ * Errors from the operation are returned to the caller (we don't swallow
+ * them — only the queue tail is swallowed so a single failure doesn't poison
+ * every subsequent send on that thread).
+ *
+ * @example
+ *   await enqueueSend(key, () =>
+ *     bot.telegram.sendMessage(key.chatId, text, { message_thread_id: key.threadId }));
+ */
+export declare function enqueueSend<T>(key: SessionKey, fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../src/rateLimiter.ts"],"names":[],"mappings":"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"}