@od-oneapp/ai-platform 0.1.0

package/src/tools/approval/queue-factory.ts

@@ -0,0 +1,162 @@
+/**
+ * Backend implementations and queue factory functions for the approval system.
+ * Provides in-memory and Redis-backed approval queues.
+ */
+
+import { createQueueFromBackend } from './with-approval';
+
+import type { ApprovalBackend, ApprovalQueue, ApprovalRequest, RedisClient } from './types';
+
+/**
+ * Create an approval queue with in-memory backend
+ *
+ * @param options - Queue options
+ * @returns ApprovalQueue instance
+ *
+ * @example
+ * ```typescript
+ * const queue = createApprovalQueue();
+ *
+ * // Add request
+ * await queue.enqueue(request);
+ *
+ * // Process requests
+ * const pending = await queue.listPending();
+ * ```
+ */
+export function createApprovalQueue(options?: { enableLogging?: boolean }): ApprovalQueue {
+  const backend = createInMemoryBackend();
+  return createQueueFromBackend(backend, options);
+}
+
+/**
+ * Create approval queue with Redis backend
+ *
+ * @param redisClient - Redis client instance
+ * @param options - Queue options
+ * @returns ApprovalQueue instance
+ *
+ * @example
+ * ```typescript
+ * const redis = new Redis();
+ * const queue = createApprovalQueueWithRedis(redis);
+ * ```
+ */
+export async function createApprovalQueueWithRedis(
+  redisClient: RedisClient,
+  options?: {
+    keyPrefix?: string;
+    enableLogging?: boolean;
+  },
+): Promise<ApprovalQueue> {
+  const backend = createRedisBackend(redisClient, options?.keyPrefix || 'approval:');
+  return createQueueFromBackend(backend, options);
+}
+
+// ============================================================================
+// INTERNAL HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Create in-memory backend for approval queue
+ */
+function createInMemoryBackend(): ApprovalBackend {
+  const requests = new Map<string, ApprovalRequest>();
+  const results = new Map<string, unknown>();
+
+  return {
+    async store(request: ApprovalRequest): Promise<void> {
+      requests.set(request.id, { ...request });
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      return requests.get(requestId) || null;
+    },
+
+    async listPending(): Promise<ApprovalRequest[]> {
+      return Array.from(requests.values()).filter(r => r.status === 'pending');
+    },
+
+    async updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void> {
+      const request = requests.get(requestId);
+      if (request) {
+        request.status = status;
+      }
+    },
+
+    async delete(requestId: string): Promise<void> {
+      requests.delete(requestId);
+      results.delete(requestId);
+    },
+
+    async clearExpired(): Promise<number> {
+      const now = new Date();
+      let count = 0;
+
+      for (const [id, request] of requests.entries()) {
+        if (request.expiresAt && request.expiresAt < now) {
+          requests.delete(id);
+          count += 1;
+        }
+      }
+
+      return count;
+    },
+  };
+}
+
+/**
+ * Create Redis backend for approval queue
+ */
+function createRedisBackend(redisClient: RedisClient, keyPrefix: string): ApprovalBackend {
+  return {
+    async store(request: ApprovalRequest): Promise<void> {
+      const key = `${keyPrefix}${request.id}`;
+      await redisClient.set(key, JSON.stringify(request), 'EX', 86400); // 24h TTL
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      return data ? JSON.parse(data) : null;
+    },
+
+    async listPending(): Promise<ApprovalRequest[]> {
+      const pattern = `${keyPrefix}*`;
+      const keys = await redisClient.keys(pattern);
+      const requests: ApprovalRequest[] = [];
+
+      for (const key of keys) {
+        const data = await redisClient.get(key);
+        if (data) {
+          const request = JSON.parse(data);
+          if (request.status === 'pending') {
+            requests.push(request);
+          }
+        }
+      }
+
+      return requests;
+    },
+
+    async updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      if (data) {
+        const request = JSON.parse(data);
+        request.status = status;
+        await redisClient.set(key, JSON.stringify(request), 'EX', 86400);
+      }
+    },
+
+    async delete(requestId: string): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      await redisClient.del(key);
+    },
+
+    async clearExpired(): Promise<number> {
+      // Redis TTL handles expiration, return 0
+      return 0;
+    },
+  };
+}

package/src/tools/approval/redis-queue.ts

@@ -0,0 +1,327 @@
+/**
+ * Redis-based Approval Queue Implementation
+ * Priority-based queue with Redis persistence, batch processing, metrics, and dead letter queue
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+import type { AdvancedQueueConfig, QueueMetrics } from './in-memory-queue';
+import type {
+  ApprovalRequest,
+  ApprovalResult,
+  ApprovalQueue,
+  ApprovalBackend,
+  QueueStats,
+ RedisClient } from './types';
+
+
+
+/**
+ * Redis-based Approval Queue with advanced features
+ */
+export class RedisApprovalQueue implements ApprovalQueue {
+  private backend: ApprovalBackend;
+  private redisClient: RedisClient;
+  private keyPrefix: string;
+  private dlqKey: string;
+  private metricsKey: string;
+  private metrics: QueueMetrics;
+  private config: AdvancedQueueConfig;
+  private logger: (msg: string) => void;
+  private cleanupInterval?: NodeJS.Timeout;
+
+  constructor(
+    redisClient: RedisClient,
+    backend: ApprovalBackend,
+    keyPrefix = 'approval:',
+    config: AdvancedQueueConfig = {},
+  ) {
+    this.redisClient = redisClient;
+    this.backend = backend;
+    this.keyPrefix = keyPrefix;
+    this.dlqKey = `${keyPrefix}dlq`;
+    this.metricsKey = `${keyPrefix}metrics`;
+    this.config = config;
+    this.logger = config.enableLogging ? logInfo : () => {};
+
+    this.metrics = {
+      totalReceived: 0,
+      totalApproved: 0,
+      totalRejected: 0,
+      totalExpired: 0,
+      avgApprovalTimeMs: 0,
+      currentSize: 0,
+      peakSize: 0,
+      dlqSize: 0,
+    };
+
+    // Start cleanup interval
+    if (config.cleanupIntervalMs) {
+      this.startCleanupInterval(config.cleanupIntervalMs);
+    }
+  }
+
+  async enqueue(request: ApprovalRequest): Promise<void> {
+    // Check max queue size
+    const pending = await this.backend.listPending();
+    if (this.config.maxQueueSize && pending.length >= this.config.maxQueueSize) {
+      throw new Error(`Queue size limit (${this.config.maxQueueSize}) reached`);
+    }
+
+    await this.backend.store(request);
+
+    // Update metrics
+    await this.redisClient.hincrby(this.metricsKey, 'totalReceived', 1);
+    this.logger(`[Queue] Enqueued request ${request.id}`);
+  }
+
+  async dequeue(): Promise<ApprovalRequest | null> {
+    const pending = await this.backend.listPending();
+    if (pending.length === 0) return null;
+
+    const sorted = this.sortByPriority(pending);
+    return sorted[0] ?? null;
+  }
+
+  async get(requestId: string): Promise<ApprovalRequest | null> {
+    return this.backend.get(requestId);
+  }
+
+  async listPending(limit = 100, offset = 0): Promise<ApprovalRequest[]> {
+    const pending = await this.backend.listPending();
+    const sorted = this.sortByPriority(pending);
+    return sorted.slice(offset, offset + limit);
+  }
+
+  async updateStatus(
+    requestId: string,
+    status: ApprovalRequest['status'],
+    result?: ApprovalResult,
+  ): Promise<void> {
+    void result;
+    const request = await this.backend.get(requestId);
+    if (!request) {
+      throw new Error(`Request ${requestId} not found`);
+    }
+
+    await this.backend.updateStatus(requestId, status);
+
+    // Update metrics
+    if (status === 'approved') {
+      await this.redisClient.hincrby(this.metricsKey, 'totalApproved', 1);
+    } else if (status === 'rejected') {
+      await this.redisClient.hincrby(this.metricsKey, 'totalRejected', 1);
+
+      // Add to DLQ if enabled
+      if (this.config.enableDLQ) {
+        await this.redisClient.lpush(this.dlqKey, JSON.stringify(request));
+        this.metrics.dlqSize += 1;
+      }
+    } else if (status === 'expired') {
+      await this.redisClient.hincrby(this.metricsKey, 'totalExpired', 1);
+    }
+
+    this.logger(`[Queue] Updated request ${requestId} status: ${status}`);
+  }
+
+  async remove(requestId: string): Promise<void> {
+    await this.backend.delete(requestId);
+    this.logger(`[Queue] Removed request ${requestId}`);
+  }
+
+  async getStats(): Promise<QueueStats> {
+    const pending = await this.backend.listPending();
+    const byPriority: Record<string, number> = {
+      critical: 0,
+      high: 0,
+      normal: 0,
+      low: 0,
+    };
+
+    let oldestTime = Date.now();
+    for (const req of pending) {
+      const priority = req.priority || 'normal';
+      byPriority[priority] = (byPriority[priority] || 0) + 1;
+      oldestTime = Math.min(oldestTime, req.requestedAt.getTime());
+    }
+
+    const oldestRequestAgeMs = pending.length > 0 ? Date.now() - oldestTime : undefined;
+
+    const totalApprovedStr = await this.redisClient.hget(this.metricsKey, 'totalApproved');
+    const totalRejectedStr = await this.redisClient.hget(this.metricsKey, 'totalRejected');
+    const totalApproved = parseInt(totalApprovedStr || '0');
+    const totalRejected = parseInt(totalRejectedStr || '0');
+    const totalProcessed = totalApproved + totalRejected;
+    const approvalRate = totalProcessed > 0 ? totalApproved / totalProcessed : 0;
+
+    return {
+      totalPending: pending.length,
+      byPriority,
+      oldestRequestAgeMs,
+      totalProcessed,
+      approvalRate,
+    };
+  }
+
+  async clearExpired(): Promise<number> {
+    return this.backend.clearExpired();
+  }
+
+  /**
+   * Get dead letter queue items
+   */
+  async getDeadLetterQueue(): Promise<ApprovalRequest[]> {
+    const items = await this.redisClient.lrange(this.dlqKey, 0, -1);
+    return items.map((item: string) => JSON.parse(item));
+  }
+
+  /**
+   * Clear dead letter queue
+   */
+  async clearDeadLetterQueue(): Promise<void> {
+    await this.redisClient.del(this.dlqKey);
+    this.metrics.dlqSize = 0;
+    this.logger('[Queue] Cleared dead letter queue');
+  }
+
+  /**
+   * Process batch of requests
+   */
+  async processBatch(
+    handler: (request: ApprovalRequest) => Promise<ApprovalResult>,
+  ): Promise<number> {
+    const pending = await this.backend.listPending();
+    const batchSize = this.config.batchSize || 10;
+    const batch = pending.slice(0, batchSize);
+    let processed = 0;
+
+    for (const request of batch) {
+      try {
+        const result = await handler(request);
+        await this.updateStatus(request.id, result.approved ? 'approved' : 'rejected', result);
+        processed += 1;
+      } catch (error) {
+        this.logger(`[Queue] Error processing ${request.id}: ${error}`);
+      }
+    }
+
+    return processed;
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.logger('[Queue] Destroyed');
+  }
+
+  // =========================================================================
+  // PRIVATE METHODS
+  // =========================================================================
+
+  private sortByPriority(requests: ApprovalRequest[]): ApprovalRequest[] {
+    const priorityOrder: Record<string, number> = {
+      critical: 0,
+      high: 1,
+      normal: 2,
+      low: 3,
+    };
+
+    return requests.sort((a, b) => {
+      const defaultPriority = priorityOrder.normal ?? 2;
+      const aPriority = priorityOrder[a.priority ?? 'normal'];
+      const bPriority = priorityOrder[b.priority ?? 'normal'];
+      const aValue = typeof aPriority === 'number' ? aPriority : defaultPriority;
+      const bValue = typeof bPriority === 'number' ? bPriority : defaultPriority;
+
+      if (aValue !== bValue) return aValue - bValue;
+      return a.requestedAt.getTime() - b.requestedAt.getTime();
+    });
+  }
+
+  private startCleanupInterval(intervalMs: number): void {
+    this.cleanupInterval = setInterval(() => {
+      void (async () => {
+        try {
+          const cleared = await this.clearExpired();
+          if (cleared > 0) {
+            this.logger(`[Queue] Cleared ${cleared} expired requests`);
+          }
+        } catch (error) {
+          this.logger(`[Queue] Cleanup error: ${error}`);
+        }
+      })();
+    }, intervalMs);
+  }
+}
+
+/**
+ * Factory function to create Redis queue
+ */
+export function createRedisQueue(
+  redisClient: RedisClient,
+  config?: AdvancedQueueConfig & { keyPrefix?: string },
+): RedisApprovalQueue {
+  const keyPrefix = config?.keyPrefix || 'approval:';
+  const backend = createRedisBackend(redisClient, keyPrefix);
+  return new RedisApprovalQueue(redisClient, backend, keyPrefix, config);
+}
+
+/**
+ * Create Redis backend
+ */
+function createRedisBackend(redisClient: RedisClient, keyPrefix: string): ApprovalBackend {
+  return {
+    async store(request: ApprovalRequest): Promise<void> {
+      const key = `${keyPrefix}${request.id}`;
+      await redisClient.set(key, JSON.stringify(request), 'EX', 86400); // 24h TTL
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      return data ? JSON.parse(data) : null;
+    },
+
+    async listPending(): Promise<ApprovalRequest[]> {
+      const pattern = `${keyPrefix}apr_*`;
+      const keys = await redisClient.keys(pattern);
+      const requests: ApprovalRequest[] = [];
+
+      for (const key of keys) {
+        const data = await redisClient.get(key);
+        if (data) {
+          const request = JSON.parse(data);
+          if (request.status === 'pending') {
+            requests.push(request);
+          }
+        }
+      }
+
+      return requests;
+    },
+
+    async updateStatus(requestId: string, status: ApprovalRequest['status']): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      const data = await redisClient.get(key);
+      if (data) {
+        const request = JSON.parse(data);
+        request.status = status;
+        await redisClient.set(key, JSON.stringify(request), 'EX', 86400);
+      }
+    },
+
+    async delete(requestId: string): Promise<void> {
+      const key = `${keyPrefix}${requestId}`;
+      await redisClient.del(key);
+    },
+
+    async clearExpired(): Promise<number> {
+      // Redis TTL handles expiration
+      return 0;
+    },
+  };
+}