ts-server-lib 0.0.17

package/db/TSRQW.d.ts

@@ -0,0 +1,271 @@
+/**
+ * TSRQW — Redis Queue Worker (standalone / sentinel / cluster).
+ *
+ * R = Redis · Q = Queue · W = Worker
+ *
+ * Single class unifying queue storage (Redis Streams) + worker lifecycle
+ * (events, retry, dead-letter, cron schedule, thread pool).
+ *
+ * Backend: Redis Streams (XADD / XREADGROUP / XAUTOCLAIM / XACK).
+ *   - All keys hash-tagged → zero CROSSSLOT on any topology.
+ *   - No Lua scripts, no EVALSHA, no SCRIPT LOAD broadcast.
+ *   - Consumer-group model: crashed consumers recovered automatically via XAUTOCLAIM.
+ *   - Built-in dead-letter stream (`{ns:name}:dlq`).
+ *
+ * Performance:
+ *   - send:    1 roundtrip (XADD MAXLEN ~)
+ *   - receive: 1 roundtrip (XREADGROUP); XAUTOCLAIM throttled to reclaimIntervalMs
+ *   - node-redis v5 auto-pipelines concurrent callers → linear throughput scaling
+ *
+ * Events: new · ready · completed · retry · exceeded · failed · deleted · error
+ */
+import { EventEmitter } from 'events';
+import { AsyncResource } from 'async_hooks';
+import { CronJob } from 'cron';
+import { Worker } from 'worker_threads';
+import type { TSRedisClient } from './TSRedis';
+export declare enum TSRQWEvents {
+    new = "new",
+    ready = "ready",
+    deleted = "deleted",
+    completed = "completed",
+    retry = "retry",
+    exceeded = "exceeded",
+    failed = "failed",
+    error = "error"
+}
+export type TSRQWStatus = 'idle' | 'completed' | 'retry' | 'failed';
+export type TSRQWHandler = (message: string, meta: {
+    id: string;
+    rc: number;
+    fr: number;
+}) => Promise<boolean | void> | boolean | void;
+export type TSRQWCallback = (data?: unknown) => Promise<(data?: unknown) => Promise<unknown>>;
+export interface TSRQWReceiveResult {
+    status: TSRQWStatus;
+    message?: string;
+    meta?: {
+        id: string;
+        rc: number;
+        fr: number;
+    };
+}
+export interface TSRQWAttributes {
+    msgs: number;
+    hiddenmsgs: number;
+    totalsent: number;
+    totalrecv: number;
+}
+/** Raw message shape returned by receiveRaw() and the adaptive consumer API. */
+export interface TSRQWMessage {
+    id: string;
+    message: string;
+    rc: number;
+    fr: number;
+    sent: number;
+}
+/** Queue health state — derived from snapshot fields, no extra Redis calls. */
+export type TSRQWHealth = 'empty' | 'healthy' | 'lagging' | 'stuck';
+/**
+ * Rich Streams-native snapshot — call from dashboards / platform stats.
+ * Extends TSRQWAttributes with fields only Redis Streams can provide.
+ * NOT for the hot path — use attributes() there (2 roundtrips).
+ */
+export interface TSRQWSnapshot extends TSRQWAttributes {
+    /** Messages in stream not yet delivered to this group — real queue backlog. */
+    lag: number;
+    /** Active consumers in this group (0 = no worker connected). */
+    consumers: number;
+    /** Dead-letter queue depth — poison messages accumulating. */
+    dlqDepth: number;
+    /** Exact total-sent counter, unaffected by MAXLEN trim (entries-added, Redis 7.2+). */
+    totalsentExact: number;
+    /** Unix ms of last message delivered to this group (0 = never). */
+    lastDeliveredMs: number;
+    /** Unix ms of oldest in-flight (PEL) message (0 = nothing pending). */
+    oldestPendingMs: number;
+    /** Unix ms of last XADD — 0 if stream has no entries. Idle indicator. */
+    lastAddedMs: number;
+    /** lag + hiddenmsgs — total messages in the system not yet completed. */
+    backpressure: number;
+    /** (totalrecv / totalsentExact) * 100 — % of sent messages consumed. 100 = fully drained. */
+    consumptionRate: number;
+    /** (dlqDepth / totalsentExact) * 100 — % of messages dead-lettered. */
+    dlqRate: number;
+    /**
+     * empty   — no messages ever sent.
+     * healthy — no lag, nothing stuck.
+     * lagging — lag > 0 (messages waiting to be delivered to this group).
+     * stuck   — oldest pending entry has been in-flight > 2 min.
+     */
+    health: TSRQWHealth;
+}
+export interface TSRQWOptions {
+    /** Logical queue name (default: 'queue'). */
+    name?: string;
+    /** Redis key namespace prefix (default: 'tsq'). */
+    ns?: string;
+    /** Max delivery attempts before dead-lettering (default: 3). */
+    attempts?: number;
+    /** Consumer group name (default: ns). One group per service. */
+    group?: string;
+    /** Consumer name (default: auto-generated per process). */
+    consumer?: string;
+    /** Approximate stream MAXLEN (default: 100_000). */
+    maxLen?: number;
+    /** How often to run XAUTOCLAIM for stale-consumer recovery (ms, default: 2_000). */
+    reclaimIntervalMs?: number;
+}
+declare const kTaskInfo: unique symbol;
+interface WorkerWithTaskInfo extends Worker {
+    [kTaskInfo]?: TSRQWPoolTask | null;
+}
+declare class TSRQWPoolTask extends AsyncResource {
+    callback: (err: Error | null, result: unknown) => void;
+    constructor(callback: (err: Error | null, result: unknown) => void);
+    done(err: Error | null, result: unknown): void;
+}
+export declare class TSRQWPool extends EventEmitter {
+    factor: number;
+    callback: TSRQWCallback;
+    wd?: unknown | undefined;
+    workers: WorkerWithTaskInfo[];
+    freeWorkers: WorkerWithTaskInfo[];
+    tasks: Array<{
+        task: unknown;
+        callback: (err: Error | null, result: unknown) => void;
+    }>;
+    constructor(factor: number | undefined, callback: TSRQWCallback, wd?: unknown | undefined);
+    work: (data: unknown) => Promise<unknown>;
+    update(data: Record<string, unknown> & {
+        _wd_updated?: number;
+    }): void;
+    close(): void;
+    private _runTask;
+    private _addWorker;
+}
+export declare class TSRQW extends EventEmitter {
+    protected readonly redis: TSRedisClient;
+    protected readonly qname: string;
+    protected readonly rawNs: string;
+    protected readonly ns: string;
+    protected readonly group: string;
+    protected readonly consumer: string;
+    protected readonly maxLen: number;
+    protected readonly attempts: number;
+    protected readonly reclaimIntervalMs: number;
+    connected: boolean;
+    private offlineBuffer;
+    private ensured;
+    private ensurePromise;
+    private lastReclaimAt;
+    /** Resolves when the consumer group is ready and the first offline drain completes. */
+    readonly initialized: Promise<void>;
+    constructor(redis: TSRedisClient, options?: TSRQWOptions);
+    private _streamKey;
+    private _dlqKey;
+    private _init;
+    private _ensureGroup;
+    private _createGroup;
+    /** Reset the ensured flag so the next receive call recreates stream+group.
+     *  Call this when XREADGROUP returns NOGROUP (stream/group wiped, e.g. after Redis flush). */
+    resetEnsured(): void;
+    /**
+     * Append a message. Returns the stream entry ID for immediate sends;
+     * undefined for buffered (pre-connect) or delayed sends.
+     */
+    send(message: string, delay?: number): Promise<string | undefined>;
+    private _xadd;
+    receiveWithStatus({ handle, visibility: vt, }: {
+        handle: TSRQWHandler;
+        visibility?: number;
+    }): Promise<TSRQWReceiveResult>;
+    receive(opts: {
+        handle: TSRQWHandler;
+        visibility?: number;
+    }): Promise<void>;
+    /**
+     * Blocking receive — XREADGROUP with BLOCK so the connection sleeps until a message
+     * arrives, then wakes immediately. Zero polling overhead vs CronJob polling.
+     *
+     * Preferred consumer pattern for durable/recovery consumers (e.g. integration event
+     * streams). Each call blocks for up to `blockMs` ms. On timeout: returns null (no
+     * message). On message: calls `handler`, ACKs on success, leaves in PEL on failure.
+     *
+     * Run in a `while (running) { await q.receiveBlocking(handler) }` loop per channel.
+     * The loop is woken by Redis as soon as a message is written — no polling overhead.
+     *
+     * @param handler   - Return true to ACK, false to leave in PEL (retry after vt).
+     * @param vt        - Visibility timeout seconds.
+     * @param blockMs   - Max ms to wait for a message (Redis BLOCK option). Default 2 000.
+     *                   Keep short (≤5s) when using a shared cluster client — BLOCK holds
+     *                   the master socket and prevents other commands from executing on it.
+     */
+    receiveBlocking(handler: (message: string, meta: {
+        id: string;
+        rc: number;
+        fr: number;
+    }) => Promise<boolean>, vt?: number, blockMs?: number): Promise<void>;
+    /** Pull one raw message without calling a handler or auto-acking. */
+    receiveRaw(vt?: number): Promise<TSRQWMessage | null>;
+    /** XACK a message by ID. Returns true when the PEL entry was removed. */
+    ack(id: string): Promise<boolean>;
+    /**
+     * XACK multiple messages in one roundtrip.
+     * All IDs must belong to this stream — guaranteed by the caller holding them from receiveRaw/receiveRawBatch.
+     * Returns the number of entries removed from the PEL.
+     */
+    ackBatch(ids: string[]): Promise<number>;
+    /**
+     * Pull up to `count` messages in one roundtrip (XREADGROUP COUNT N).
+     * Reclaim path uses a single XPENDING RANGE for all stale entries — no per-message round-trips.
+     * Returns an empty array when the queue is idle. Caller owns ack/deadLetter for each message.
+     */
+    receiveRawBatch(vt?: number, count?: number): Promise<TSRQWMessage[]>;
+    private _receiveRawBatchImpl;
+    /** Move a message to the `:dlq` stream and XACK the source. */
+    deadLetter(id: string, message: string, rc: number): Promise<void>;
+    private _readOne;
+    private _reclaimOne;
+    private _deliveryCount;
+    private _ack;
+    private _moveToDeadLetter;
+    private _msFromId;
+    attributes(): Promise<TSRQWAttributes | null>;
+    /**
+     * Rich Streams-native snapshot — for dashboards, platform stats, admin UI.
+     * 4–5 parallel roundtrips (XLEN×2 + XINFO STREAM + XINFO GROUPS + optional XPENDING).
+     * Do NOT call on the hot message path — use attributes() there.
+     */
+    snapshot(): Promise<TSRQWSnapshot | null>;
+    private _drainOffline;
+    /** List all queue names registered in a namespace (reads from `{ns:QUEUES}` index set). */
+    static listQueues(redis: TSRedisClient, ns: string): Promise<string[]>;
+    /**
+     * Read-only aggregate snapshot across ALL consumer groups on a stream — no XGROUP CREATE.
+     * Use from dashboards instead of `new TSRQW(...).snapshot()` to avoid creating phantom groups.
+     *
+     * Aggregation rules (correct for fan-out / multi-group topologies):
+     *  - lag        : max across groups (worst consumer defines backpressure)
+     *  - consumers  : sum across groups (total workers active)
+     *  - totalrecv  : max entries-read across groups (how far the fastest consumer has reached)
+     *  - lastDeliveredMs: max last-delivered-id ms (most-recently-delivered across groups)
+     *  - dlqRate    : dlqDepth / totalsentExact capped at entries-read by the most-advanced group
+     *                 (avoids 100% false-positive when DLQ accumulated across stream recreations)
+     *
+     * Returns null when the stream does not exist.
+     */
+    static snapshotFromGroups(redis: TSRedisClient, ns: string, name: string): Promise<TSRQWSnapshot | null>;
+    private static _msFromIdStatic;
+    static schedule({ onTick, onComplete, runOnInit, cronTime, context, start, timeZone, }: {
+        onTick?: () => void;
+        onComplete?: (() => void) | null;
+        runOnInit?: boolean;
+        cronTime?: string;
+        context?: unknown;
+        start?: boolean;
+        timeZone?: string;
+    }): CronJob;
+    static worker(cb: TSRQWCallback, factor?: number, wd?: unknown): TSRQWPool;
+}
+export {};