agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/notifications/retry-queue.js

@@ -0,0 +1,449 @@
+/**
+ * A2A Webhook Retry Queue
+ *
+ * Implements exponential backoff retry logic for failed webhook deliveries.
+ * Supports configurable retry strategies and queue persistence.
+ *
+ * @module adapters/a2a/notifications/retry-queue
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+import { EventEmitter } from 'events';
+// ============================================================================
+// Default Configuration
+// ============================================================================
+export const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 5,
+    baseDelayMs: 1000,
+    maxDelayMs: 60000,
+    backoffMultiplier: 2,
+    jitterEnabled: true,
+    jitterRatio: 0.2,
+};
+export const DEFAULT_QUEUE_CONFIG = {
+    maxQueueSize: 10000,
+    processingIntervalMs: 1000,
+    maxConcurrent: 10,
+    defaultRetryConfig: DEFAULT_RETRY_CONFIG,
+    enableAutoProcessing: true,
+};
+// ============================================================================
+// Retry Queue Implementation
+// ============================================================================
+/**
+ * Retry queue for failed webhook deliveries
+ *
+ * Implements exponential backoff with jitter for reliable delivery.
+ */
+export class RetryQueue extends EventEmitter {
+    config;
+    queue = new Map();
+    scheduledIndex = new Map();
+    processingTimer;
+    isProcessing = false;
+    currentlyProcessing = new Set();
+    // Statistics
+    stats = {
+        totalProcessed: 0,
+        totalSuccess: 0,
+        totalFailed: 0,
+    };
+    // Delivery function to be provided externally
+    deliveryFn;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            ...DEFAULT_QUEUE_CONFIG,
+            ...config,
+            defaultRetryConfig: {
+                ...DEFAULT_RETRY_CONFIG,
+                ...config.defaultRetryConfig,
+            },
+        };
+        if (this.config.enableAutoProcessing) {
+            this.startProcessing();
+        }
+    }
+    // ============================================================================
+    // Queue Operations
+    // ============================================================================
+    /**
+     * Add a delivery to the retry queue
+     */
+    enqueue(delivery) {
+        if (this.queue.size >= this.config.maxQueueSize) {
+            // Evict oldest item
+            this.evictOldest();
+        }
+        // Ensure proper retry config
+        delivery.retryConfig = {
+            ...this.config.defaultRetryConfig,
+            ...delivery.retryConfig,
+        };
+        this.queue.set(delivery.id, delivery);
+        this.addToScheduleIndex(delivery);
+        this.emit('enqueued', { delivery });
+    }
+    /**
+     * Create and enqueue a new delivery
+     */
+    enqueueNew(params) {
+        const now = new Date();
+        const id = `retry-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        const delivery = {
+            id,
+            subscriptionId: params.subscriptionId,
+            taskId: params.taskId,
+            url: params.url,
+            secret: params.secret,
+            payload: params.payload,
+            originalTimestamp: now,
+            attempt: 1,
+            scheduledAt: now,
+            retryConfig: {
+                ...this.config.defaultRetryConfig,
+                ...params.retryConfig,
+            },
+            metadata: params.metadata,
+        };
+        this.enqueue(delivery);
+        return delivery;
+    }
+    /**
+     * Get a delivery by ID
+     */
+    get(id) {
+        return this.queue.get(id);
+    }
+    /**
+     * Check if a delivery is in the queue
+     */
+    has(id) {
+        return this.queue.has(id);
+    }
+    /**
+     * Remove a delivery from the queue
+     */
+    remove(id) {
+        const delivery = this.queue.get(id);
+        if (!delivery) {
+            return false;
+        }
+        this.removeFromScheduleIndex(delivery);
+        this.queue.delete(id);
+        this.emit('removed', { id });
+        return true;
+    }
+    /**
+     * Remove all deliveries for a subscription
+     */
+    removeBySubscription(subscriptionId) {
+        const toRemove = [];
+        for (const [id, delivery] of this.queue) {
+            if (delivery.subscriptionId === subscriptionId) {
+                toRemove.push(id);
+            }
+        }
+        for (const id of toRemove) {
+            this.remove(id);
+        }
+        return toRemove.length;
+    }
+    /**
+     * Remove all deliveries for a task
+     */
+    removeByTask(taskId) {
+        const toRemove = [];
+        for (const [id, delivery] of this.queue) {
+            if (delivery.taskId === taskId) {
+                toRemove.push(id);
+            }
+        }
+        for (const id of toRemove) {
+            this.remove(id);
+        }
+        return toRemove.length;
+    }
+    // ============================================================================
+    // Processing
+    // ============================================================================
+    /**
+     * Set the delivery function for processing
+     */
+    setDeliveryFunction(fn) {
+        this.deliveryFn = fn;
+    }
+    /**
+     * Process the queue (call pending deliveries)
+     */
+    async processQueue() {
+        if (this.isProcessing) {
+            return;
+        }
+        if (!this.deliveryFn) {
+            return;
+        }
+        this.isProcessing = true;
+        try {
+            const now = Date.now();
+            const ready = this.getReadyDeliveries(now);
+            // Limit concurrent processing
+            const toProcess = ready.filter((d) => !this.currentlyProcessing.has(d.id)).slice(0, this.config.maxConcurrent - this.currentlyProcessing.size);
+            if (toProcess.length === 0) {
+                return;
+            }
+            // Process in parallel
+            const promises = toProcess.map((delivery) => this.processDelivery(delivery));
+            await Promise.allSettled(promises);
+        }
+        finally {
+            this.isProcessing = false;
+        }
+    }
+    /**
+     * Process a single delivery
+     */
+    async processDelivery(delivery) {
+        this.currentlyProcessing.add(delivery.id);
+        try {
+            this.emit('processing', { delivery });
+            const result = await this.deliveryFn(delivery);
+            this.stats.totalProcessed++;
+            if (result.success) {
+                // Success - remove from queue
+                this.stats.totalSuccess++;
+                this.remove(delivery.id);
+                this.emit('success', { delivery, result });
+            }
+            else if (result.shouldRetry && delivery.attempt < delivery.retryConfig.maxAttempts) {
+                // Retry - update and reschedule
+                this.rescheduleDelivery(delivery, result);
+                this.emit('retrying', { delivery, result });
+            }
+            else {
+                // Give up - remove from queue
+                this.stats.totalFailed++;
+                this.remove(delivery.id);
+                this.emit('failed', { delivery, result });
+            }
+        }
+        catch (error) {
+            // Unexpected error - attempt retry
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (delivery.attempt < delivery.retryConfig.maxAttempts) {
+                this.rescheduleDelivery(delivery, {
+                    success: false,
+                    shouldRetry: true,
+                    error: errorMessage,
+                });
+                this.emit('retrying', {
+                    delivery,
+                    result: { success: false, shouldRetry: true, error: errorMessage },
+                });
+            }
+            else {
+                this.stats.totalFailed++;
+                this.remove(delivery.id);
+                this.emit('failed', {
+                    delivery,
+                    result: { success: false, shouldRetry: false, error: errorMessage },
+                });
+            }
+        }
+        finally {
+            this.currentlyProcessing.delete(delivery.id);
+        }
+    }
+    /**
+     * Reschedule a delivery for retry
+     */
+    rescheduleDelivery(delivery, result) {
+        this.removeFromScheduleIndex(delivery);
+        delivery.attempt++;
+        delivery.lastError = result.error;
+        delivery.lastStatusCode = result.statusCode;
+        delivery.scheduledAt = this.calculateNextRetryTime(delivery);
+        this.addToScheduleIndex(delivery);
+    }
+    /**
+     * Calculate the next retry time using exponential backoff
+     */
+    calculateNextRetryTime(delivery) {
+        const { baseDelayMs, maxDelayMs, backoffMultiplier, jitterEnabled, jitterRatio } = delivery.retryConfig;
+        // Exponential backoff: delay = base * multiplier^(attempt-1)
+        let delay = baseDelayMs * Math.pow(backoffMultiplier, delivery.attempt - 1);
+        // Cap at max delay
+        delay = Math.min(delay, maxDelayMs);
+        // Add jitter
+        if (jitterEnabled && jitterRatio && jitterRatio > 0) {
+            const jitter = delay * jitterRatio * (Math.random() * 2 - 1);
+            delay = Math.max(baseDelayMs, delay + jitter);
+        }
+        return new Date(Date.now() + delay);
+    }
+    /**
+     * Get deliveries ready to process
+     */
+    getReadyDeliveries(now) {
+        const ready = [];
+        for (const delivery of this.queue.values()) {
+            if (delivery.scheduledAt.getTime() <= now) {
+                ready.push(delivery);
+            }
+        }
+        // Sort by scheduled time (oldest first)
+        ready.sort((a, b) => a.scheduledAt.getTime() - b.scheduledAt.getTime());
+        return ready;
+    }
+    // ============================================================================
+    // Timer Management
+    // ============================================================================
+    /**
+     * Start automatic processing
+     */
+    startProcessing() {
+        if (this.processingTimer) {
+            return;
+        }
+        this.processingTimer = setInterval(() => {
+            this.processQueue().catch((error) => {
+                this.emit('error', { error });
+            });
+        }, this.config.processingIntervalMs);
+        if (typeof this.processingTimer.unref === 'function') {
+            this.processingTimer.unref();
+        }
+    }
+    /**
+     * Stop automatic processing
+     */
+    stopProcessing() {
+        if (this.processingTimer) {
+            clearInterval(this.processingTimer);
+            this.processingTimer = undefined;
+        }
+    }
+    // ============================================================================
+    // Statistics
+    // ============================================================================
+    /**
+     * Get queue statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const byAttempt = {};
+        let oldestItemAgeMs = 0;
+        let readyToProcess = 0;
+        let scheduledForLater = 0;
+        for (const delivery of this.queue.values()) {
+            // Count by attempt
+            byAttempt[delivery.attempt] = (byAttempt[delivery.attempt] ?? 0) + 1;
+            // Track oldest
+            const age = now - delivery.originalTimestamp.getTime();
+            if (age > oldestItemAgeMs) {
+                oldestItemAgeMs = age;
+            }
+            // Count ready vs scheduled
+            if (delivery.scheduledAt.getTime() <= now) {
+                readyToProcess++;
+            }
+            else {
+                scheduledForLater++;
+            }
+        }
+        return {
+            totalItems: this.queue.size,
+            byAttempt,
+            oldestItemAgeMs,
+            readyToProcess,
+            scheduledForLater,
+            totalProcessed: this.stats.totalProcessed,
+            totalSuccess: this.stats.totalSuccess,
+            totalFailed: this.stats.totalFailed,
+        };
+    }
+    /**
+     * Get queue size
+     */
+    get size() {
+        return this.queue.size;
+    }
+    // ============================================================================
+    // Cleanup
+    // ============================================================================
+    /**
+     * Clear all failed retries (items that have reached max attempts)
+     */
+    clearFailed() {
+        const toRemove = [];
+        for (const [id, delivery] of this.queue) {
+            if (delivery.attempt >= delivery.retryConfig.maxAttempts) {
+                toRemove.push(id);
+            }
+        }
+        for (const id of toRemove) {
+            this.remove(id);
+        }
+        return toRemove.length;
+    }
+    /**
+     * Clear all items in the queue
+     */
+    clear() {
+        this.queue.clear();
+        this.scheduledIndex.clear();
+        this.emit('cleared', {});
+    }
+    /**
+     * Destroy the queue
+     */
+    destroy() {
+        this.stopProcessing();
+        this.clear();
+        this.removeAllListeners();
+    }
+    // ============================================================================
+    // Index Management
+    // ============================================================================
+    addToScheduleIndex(delivery) {
+        // Use minute-level buckets for scheduling index
+        const bucket = Math.floor(delivery.scheduledAt.getTime() / 60000);
+        let items = this.scheduledIndex.get(bucket);
+        if (!items) {
+            items = new Set();
+            this.scheduledIndex.set(bucket, items);
+        }
+        items.add(delivery.id);
+    }
+    removeFromScheduleIndex(delivery) {
+        const bucket = Math.floor(delivery.scheduledAt.getTime() / 60000);
+        const items = this.scheduledIndex.get(bucket);
+        if (items) {
+            items.delete(delivery.id);
+            if (items.size === 0) {
+                this.scheduledIndex.delete(bucket);
+            }
+        }
+    }
+    evictOldest() {
+        let oldest;
+        for (const delivery of this.queue.values()) {
+            if (!oldest || delivery.originalTimestamp < oldest.originalTimestamp) {
+                oldest = delivery;
+            }
+        }
+        if (oldest) {
+            this.remove(oldest.id);
+            this.emit('evicted', { delivery: oldest });
+        }
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new retry queue
+ */
+export function createRetryQueue(config = {}) {
+    return new RetryQueue(config);
+}
+//# sourceMappingURL=retry-queue.js.map

package/v3/dist/adapters/a2a/notifications/retry-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-queue.js","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/retry-queue.ts"],"names":[],"mappings":"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"}

package/v3/dist/adapters/a2a/notifications/signature.d.ts

@@ -0,0 +1,133 @@
+/**
+ * A2A Webhook Signature Utilities
+ *
+ * Provides HMAC-SHA256 signature generation and verification for webhook payloads.
+ * Follows the pattern: X-A2A-Signature: t={timestamp},v1={hmac}
+ *
+ * @module adapters/a2a/notifications/signature
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+/**
+ * Header name for A2A webhook signatures
+ */
+export declare const SIGNATURE_HEADER = "X-A2A-Signature";
+/**
+ * Current signature version
+ */
+export declare const SIGNATURE_VERSION = "v1";
+/**
+ * Default maximum age for signature validation (5 minutes)
+ */
+export declare const DEFAULT_MAX_AGE_MS: number;
+/**
+ * Minimum timestamp value to prevent integer overflow attacks
+ */
+export declare const MIN_TIMESTAMP = 1704067200000;
+/**
+ * Parsed signature components
+ */
+export interface ParsedSignature {
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Version 1 signature hash */
+    v1: string;
+}
+/**
+ * Signature verification result
+ */
+export interface VerificationResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Timestamp from the signature */
+    timestamp?: number;
+    /** Age of the signature in milliseconds */
+    ageMs?: number;
+}
+/**
+ * Generate an HMAC-SHA256 signature for a webhook payload
+ *
+ * @param payload - The JSON string payload to sign
+ * @param secret - The shared secret key
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns The hex-encoded HMAC-SHA256 signature
+ *
+ * @example
+ * ```typescript
+ * const signature = generateSignature(
+ *   JSON.stringify({ event: 'task.completed', taskId: '123' }),
+ *   'webhook-secret-key',
+ *   Date.now()
+ * );
+ * // Returns: 'a1b2c3d4e5f6...' (64 character hex string)
+ * ```
+ */
+export declare function generateSignature(payload: string, secret: string, timestamp: number): string;
+/**
+ * Generate the complete signature header value
+ *
+ * @param payload - The JSON string payload to sign
+ * @param secret - The shared secret key
+ * @param timestamp - Optional timestamp (defaults to current time)
+ * @returns The complete header value in format: t={timestamp},v1={signature}
+ *
+ * @example
+ * ```typescript
+ * const headerValue = generateSignatureHeader(
+ *   JSON.stringify({ event: 'task.completed' }),
+ *   'webhook-secret-key'
+ * );
+ * // Returns: 't=1704067200000,v1=a1b2c3d4e5f6...'
+ * ```
+ */
+export declare function generateSignatureHeader(payload: string, secret: string, timestamp?: number): string;
+/**
+ * Parse a signature header value into its components
+ *
+ * @param header - The signature header value
+ * @returns Parsed signature components or null if invalid format
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseSignatureHeader('t=1704067200000,v1=abc123...');
+ * // Returns: { timestamp: 1704067200000, v1: 'abc123...' }
+ * ```
+ */
+export declare function parseSignatureHeader(header: string): ParsedSignature | null;
+/**
+ * Verify a webhook signature using timing-safe comparison
+ *
+ * @param payload - The raw JSON string payload
+ * @param signature - The signature header value to verify
+ * @param secret - The shared secret key
+ * @param maxAge - Maximum age of signature in milliseconds (default: 5 minutes)
+ * @returns Verification result with validity status and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = verifySignature(
+ *   '{"event":"task.completed"}',
+ *   't=1704067200000,v1=abc123...',
+ *   'webhook-secret-key'
+ * );
+ *
+ * if (result.valid) {
+ *   console.log('Signature verified');
+ * } else {
+ *   console.error('Verification failed:', result.error);
+ * }
+ * ```
+ */
+export declare function verifySignature(payload: string, signature: string, secret: string, maxAge?: number): VerificationResult;
+/**
+ * Simple boolean check for signature validity (convenience wrapper)
+ *
+ * @param payload - The raw JSON string payload
+ * @param signature - The signature header value to verify
+ * @param secret - The shared secret key
+ * @param maxAge - Maximum age of signature in milliseconds
+ * @returns true if signature is valid, false otherwise
+ */
+export declare function isValidSignature(payload: string, signature: string, secret: string, maxAge?: number): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/v3/dist/adapters/a2a/notifications/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;GAEG;AACH,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAM3C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAmBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAKR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA4B3E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAA2B,GAClC,kBAAkB,CAuFpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAET"}