@agent-relay/storage 0.1.0

package/dist/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

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

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