@od-oneapp/ai-platform 0.1.0

package/src/sdk/middleware/deduplication.ts

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Request deduplication middleware for AI operations
+ *
+ * Prevents duplicate requests from being processed simultaneously,
+ * reducing costs and improving response times for identical queries.
+ *
+ * @module @od-oneapp/ai-platform/sdk/middleware/deduplication
+ */
+
+import crypto from 'node:crypto';
+
+import { logDebug, logWarn } from '@repo/shared/logs';
+
+import type { JSONValue } from '../../shared';
+
+/**
+ * Deduplication storage backend interface.
+ */
+export interface DeduplicationStorage {
+  get(key: string): Promise<DeduplicationEntry | null>;
+  set(key: string, value: DeduplicationEntry, ttlMs: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Optional cleanup for storage backends */
+  destroy?(): void | Promise<void>;
+}
+
+/**
+ * Deduplication entry stored in cache.
+ */
+export interface DeduplicationEntry {
+  /** Hash of the request */
+  requestHash: string;
+  /** Promise that resolves with the result */
+  promise?: Promise<unknown>;
+  /** Cached result if completed */
+  result?: unknown;
+  /** Error if failed */
+  error?: Error;
+  /** Status of the request */
+  status: 'pending' | 'completed' | 'failed';
+  /** Timestamp when entry was created */
+  createdAt: number;
+  /** Number of deduped requests */
+  dedupedCount: number;
+}
+
+/**
+ * Deduplication configuration.
+ */
+export interface DeduplicationConfig {
+  /** Time-to-live for cached results in milliseconds (default: 60000) */
+  ttl?: number;
+  /** Custom hash function (default: SHA-256 of JSON stringified config) */
+  hashFunction?: (config: unknown) => string;
+  /** Storage backend (default: in-memory Map) */
+  storage?: DeduplicationStorage;
+  /** Maximum number of in-flight requests to track (default: 1000) */
+  maxInFlight?: number;
+  /** Enable deduplication (default: true) */
+  enabled?: boolean;
+  /** Cleanup interval for expired entries in milliseconds (default: 30000) */
+  cleanupInterval?: number;
+  /** Callback when request is deduped */
+  onDedup?: (hash: string, count: number) => void;
+}
+
+/**
+ * Default in-memory storage implementation.
+ */
+class InMemoryDeduplicationStorage implements DeduplicationStorage {
+  private cache = new Map<string, { entry: DeduplicationEntry; expiresAt: number }>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(cleanupIntervalMs = 30000) {
+    // Run cleanup based on configured interval
+    this.cleanupInterval = setInterval(() => this.cleanup(), cleanupIntervalMs);
+  }
+
+  async get(key: string): Promise<DeduplicationEntry | null> {
+    const item = this.cache.get(key);
+    if (!item) return null;
+
+    if (Date.now() > item.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return item.entry;
+  }
+
+  async set(key: string, value: DeduplicationEntry, ttlMs: number): Promise<void> {
+    this.cache.set(key, {
+      entry: value,
+      expiresAt: Date.now() + ttlMs,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, item] of this.cache.entries()) {
+      if (now > item.expiresAt) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Creates a hash of the request configuration.
+ * Uses SHA-256 for collision resistance.
+ */
+function defaultHashFunction(config: unknown): string {
+  const normalized = JSON.stringify(config, (_, value) => {
+    // Handle functions by converting to placeholder
+    if (typeof value === 'function') {
+      return '[Function]';
+    }
+    // Sort object keys for consistent hashing
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return Object.keys(value)
+        .sort()
+        .reduce(
+          (sorted, key) => {
+            sorted[key] = value[key];
+            return sorted;
+          },
+          {} as Record<string, JSONValue>,
+        );
+    }
+    return value;
+  });
+
+  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 32);
+}
+
+/**
+ * Request deduplication middleware.
+ * Prevents duplicate AI operations from being processed simultaneously.
+ */
+export class RequestDeduplicator {
+  private readonly config: Required<DeduplicationConfig>;
+  private readonly storage: DeduplicationStorage;
+  private readonly inFlightPromises = new Map<string, Promise<unknown>>();
+
+  constructor(config: DeduplicationConfig = {}) {
+    this.config = {
+      ttl: config.ttl ?? 60000,
+      hashFunction: config.hashFunction ?? defaultHashFunction,
+      storage: config.storage ?? new InMemoryDeduplicationStorage(config.cleanupInterval),
+      maxInFlight: config.maxInFlight ?? 1000,
+      enabled: config.enabled ?? true,
+      cleanupInterval: config.cleanupInterval ?? 30000,
+      onDedup: config.onDedup ?? (() => {}),
+    };
+    this.storage = this.config.storage;
+  }
+
+  /**
+   * Executes an operation with deduplication.
+   *
+   * @param config - Request configuration to hash
+   * @param operation - Async operation to execute
+   * @returns Promise with operation result
+   */
+  async execute<T>(config: unknown, operation: () => Promise<T>): Promise<T> {
+    if (!this.config.enabled) {
+      return operation();
+    }
+
+    const hash = this.config.hashFunction(config);
+
+    // Check for existing in-flight request
+    const existingPromise = this.inFlightPromises.get(hash);
+    if (existingPromise) {
+      logDebug(`[Dedup] Request deduped (in-flight)`, { hash });
+      this.config.onDedup(hash, this.inFlightPromises.size);
+      return existingPromise as Promise<T>;
+    }
+
+    // Check for cached result
+    const cached = await this.storage.get(hash);
+    if (cached) {
+      if (cached.status === 'completed' && cached.result !== undefined) {
+        logDebug(`[Dedup] Request deduped (cached)`, { hash });
+        cached.dedupedCount++;
+        await this.storage.set(hash, cached, this.config.ttl);
+        this.config.onDedup(hash, cached.dedupedCount);
+        return cached.result as T;
+      }
+      if (cached.status === 'failed' && cached.error) {
+        throw cached.error;
+      }
+    }
+
+    // Enforce max in-flight limit
+    if (this.inFlightPromises.size >= this.config.maxInFlight) {
+      logWarn(`[Dedup] Max in-flight limit reached, executing without dedup`, {
+        limit: this.config.maxInFlight,
+      });
+      return operation();
+    }
+
+    // Execute new request
+    const entry: DeduplicationEntry = {
+      requestHash: hash,
+      status: 'pending',
+      createdAt: Date.now(),
+      dedupedCount: 0,
+    };
+
+    await this.storage.set(hash, entry, this.config.ttl);
+
+    const promise = (async () => {
+      try {
+        const result = await operation();
+        entry.status = 'completed';
+        entry.result = result;
+        await this.storage.set(hash, entry, this.config.ttl);
+        this.inFlightPromises.delete(hash);
+        return result;
+      } catch (error) {
+        entry.status = 'failed';
+        entry.error = error instanceof Error ? error : new Error(String(error));
+        await this.storage.set(hash, entry, this.config.ttl);
+        this.inFlightPromises.delete(hash);
+        throw error;
+      }
+    })();
+
+    this.inFlightPromises.set(hash, promise);
+    return promise;
+  }
+
+  /**
+   * Invalidates a cached result by config.
+   */
+  async invalidate(config: unknown): Promise<void> {
+    const hash = this.config.hashFunction(config);
+    await this.storage.delete(hash);
+    this.inFlightPromises.delete(hash);
+  }
+
+  /**
+   * Clears all cached entries.
+   */
+  async clear(): Promise<void> {
+    if (typeof this.storage.destroy === 'function') {
+      await this.storage.destroy();
+    }
+    this.inFlightPromises.clear();
+  }
+
+  /**
+   * Gets current stats.
+   */
+  getStats(): { inFlight: number; enabled: boolean; ttl: number } {
+    return {
+      inFlight: this.inFlightPromises.size,
+      enabled: this.config.enabled,
+      ttl: this.config.ttl,
+    };
+  }
+}
+
+/**
+ * Default deduplicator instance.
+ */
+export const requestDeduplicator = new RequestDeduplicator();
+
+/**
+ * Creates a deduplication wrapper for an async function.
+ *
+ * @param config - Deduplication configuration
+ * @returns Function wrapper that dedupes requests
+ *
+ * @example
+ * ```typescript
+ * const dedupedGenerate = withDeduplication({ ttl: 30000 });
+ *
+ * const result = await dedupedGenerate(
+ *   { model: 'gpt-4', prompt: 'Hello' },
+ *   async () => generateText({ model: 'gpt-4', prompt: 'Hello' })
+ * );
+ * ```
+ */
+export function withDeduplication<T>(
+  config?: DeduplicationConfig,
+): (requestConfig: unknown, fn: () => Promise<T>) => Promise<T> {
+  const deduplicator = config ? new RequestDeduplicator(config) : requestDeduplicator;
+  return (requestConfig: unknown, fn: () => Promise<T>) => deduplicator.execute(requestConfig, fn);
+}