agent-relay 1.3.0 → 1.3.2

package/dist/storage/dlq-adapter.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Dead Letter Queue Storage Adapter
+ *
+ * Abstract interface for DLQ storage with implementations for:
+ * - SQLite (local daemon)
+ * - PostgreSQL (cloud deployment)
+ * - In-memory (testing)
+ *
+ * Follows the adapter pattern used by the main storage layer.
+ */
+export type DLQFailureReason = 'max_retries_exceeded' | 'ttl_expired' | 'connection_lost' | 'target_not_found' | 'signature_invalid' | 'payload_too_large' | 'rate_limited' | 'unknown';
+export interface DeadLetter {
+    id: string;
+    messageId: string;
+    from: string;
+    to: string;
+    topic?: string;
+    kind: string;
+    body: string;
+    data?: Record<string, unknown>;
+    thread?: string;
+    originalTs: number;
+    dlqTs: number;
+    reason: DLQFailureReason;
+    errorMessage?: string;
+    attemptCount: number;
+    lastAttemptTs?: number;
+    dlqRetryCount: number;
+    acknowledged: boolean;
+    acknowledgedTs?: number;
+    acknowledgedBy?: string;
+}
+export interface DLQQuery {
+    to?: string;
+    from?: string;
+    reason?: DLQFailureReason;
+    acknowledged?: boolean;
+    afterTs?: number;
+    beforeTs?: number;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'dlqTs' | 'originalTs' | 'attemptCount';
+    orderDir?: 'ASC' | 'DESC';
+}
+export interface DLQStats {
+    totalEntries: number;
+    unacknowledged: number;
+    byReason: Record<DLQFailureReason, number>;
+    byTarget: Record<string, number>;
+    oldestEntryTs: number | null;
+    newestEntryTs: number | null;
+    avgRetryCount: number;
+}
+export interface DLQConfig {
+    enabled: boolean;
+    retentionHours: number;
+    maxEntries: number;
+    autoCleanup: boolean;
+    cleanupIntervalMinutes: number;
+    alertThreshold: number;
+}
+export interface MessageEnvelope {
+    from: string;
+    to: string;
+    topic?: string;
+    kind: string;
+    body: string;
+    data?: Record<string, unknown>;
+    thread?: string;
+    ts: number;
+}
+/**
+ * Abstract interface for DLQ storage backends.
+ */
+export interface DLQStorageAdapter {
+    /**
+     * Initialize the adapter (create tables, etc.)
+     */
+    init(): Promise<void>;
+    /**
+     * Add a dead letter to the queue.
+     */
+    add(messageId: string, envelope: MessageEnvelope, reason: DLQFailureReason, attemptCount: number, errorMessage?: string): Promise<DeadLetter>;
+    /**
+     * Get a dead letter by ID.
+     */
+    get(id: string): Promise<DeadLetter | null>;
+    /**
+     * Query dead letters with filters.
+     */
+    query(query?: DLQQuery): Promise<DeadLetter[]>;
+    /**
+     * Acknowledge a dead letter.
+     */
+    acknowledge(id: string, acknowledgedBy?: string): Promise<boolean>;
+    /**
+     * Acknowledge multiple dead letters.
+     */
+    acknowledgeMany(ids: string[], acknowledgedBy?: string): Promise<number>;
+    /**
+     * Increment retry count for a dead letter.
+     */
+    incrementRetry(id: string): Promise<boolean>;
+    /**
+     * Remove a dead letter.
+     */
+    remove(id: string): Promise<boolean>;
+    /**
+     * Get DLQ statistics.
+     */
+    getStats(): Promise<DLQStats>;
+    /**
+     * Cleanup old entries.
+     */
+    cleanup(retentionHours: number, maxEntries: number): Promise<{
+        removed: number;
+    }>;
+    /**
+     * Get messages ready for retry.
+     */
+    getRetryable(maxRetries?: number, limit?: number): Promise<DeadLetter[]>;
+    /**
+     * Close the adapter (cleanup resources).
+     */
+    close(): Promise<void>;
+}
+export declare const DEFAULT_DLQ_CONFIG: DLQConfig;
+import type { Database as BetterSqlite3Database } from 'better-sqlite3';
+export declare class SQLiteDLQAdapter implements DLQStorageAdapter {
+    private db;
+    constructor(db: BetterSqlite3Database);
+    init(): Promise<void>;
+    add(messageId: string, envelope: MessageEnvelope, reason: DLQFailureReason, attemptCount: number, errorMessage?: string): Promise<DeadLetter>;
+    get(id: string): Promise<DeadLetter | null>;
+    query(query?: DLQQuery): Promise<DeadLetter[]>;
+    acknowledge(id: string, acknowledgedBy?: string): Promise<boolean>;
+    acknowledgeMany(ids: string[], acknowledgedBy?: string): Promise<number>;
+    incrementRetry(id: string): Promise<boolean>;
+    remove(id: string): Promise<boolean>;
+    getStats(): Promise<DLQStats>;
+    cleanup(retentionHours: number, maxEntries: number): Promise<{
+        removed: number;
+    }>;
+    getRetryable(maxRetries?: number, limit?: number): Promise<DeadLetter[]>;
+    close(): Promise<void>;
+    private rowToDeadLetter;
+}
+import type { Pool as PgPool } from 'pg';
+export declare class PostgresDLQAdapter implements DLQStorageAdapter {
+    private pool;
+    constructor(pool: PgPool);
+    init(): Promise<void>;
+    add(messageId: string, envelope: MessageEnvelope, reason: DLQFailureReason, attemptCount: number, errorMessage?: string): Promise<DeadLetter>;
+    get(id: string): Promise<DeadLetter | null>;
+    query(query?: DLQQuery): Promise<DeadLetter[]>;
+    acknowledge(id: string, acknowledgedBy?: string): Promise<boolean>;
+    acknowledgeMany(ids: string[], acknowledgedBy?: string): Promise<number>;
+    incrementRetry(id: string): Promise<boolean>;
+    remove(id: string): Promise<boolean>;
+    getStats(): Promise<DLQStats>;
+    cleanup(retentionHours: number, maxEntries: number): Promise<{
+        removed: number;
+    }>;
+    getRetryable(maxRetries?: number, limit?: number): Promise<DeadLetter[]>;
+    close(): Promise<void>;
+    private rowToDeadLetter;
+}
+export declare class InMemoryDLQAdapter implements DLQStorageAdapter {
+    private letters;
+    init(): Promise<void>;
+    add(messageId: string, envelope: MessageEnvelope, reason: DLQFailureReason, attemptCount: number, errorMessage?: string): Promise<DeadLetter>;
+    get(id: string): Promise<DeadLetter | null>;
+    query(query?: DLQQuery): Promise<DeadLetter[]>;
+    acknowledge(id: string, acknowledgedBy?: string): Promise<boolean>;
+    acknowledgeMany(ids: string[], acknowledgedBy?: string): Promise<number>;
+    incrementRetry(id: string): Promise<boolean>;
+    remove(id: string): Promise<boolean>;
+    getStats(): Promise<DLQStats>;
+    cleanup(retentionHours: number, maxEntries: number): Promise<{
+        removed: number;
+    }>;
+    getRetryable(maxRetries?: number, limit?: number): Promise<DeadLetter[]>;
+    close(): Promise<void>;
+}
+export type DLQAdapterType = 'sqlite' | 'postgres' | 'memory';
+export interface DLQAdapterOptions {
+    type: DLQAdapterType;
+    sqlite?: BetterSqlite3Database;
+    postgres?: PgPool;
+}
+/**
+ * Create a DLQ adapter based on configuration.
+ */
+export declare function createDLQAdapter(options: DLQAdapterOptions): DLQStorageAdapter;
+//# sourceMappingURL=dlq-adapter.d.ts.map