@gravito/echo 3.0.0 → 3.1.0

package/dist/echo/src/rotation/KeyRotationManager.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Key Rotation Manager
+ *
+ * Manages the lifecycle of webhook provider secrets, including multi-version
+ * support, automatic cleanup, and grace periods for smooth transitions.
+ *
+ * @module @gravito/echo/rotation
+ * @since v1.2
+ */
+import type { KeyRotationConfig, ProviderKeyEntry } from '../types';
+/**
+ * KeyRotationManager orchestrates the lifecycle of webhook provider secrets.
+ *
+ * It provides a central hub for managing multiple concurrent versions of signing
+ * secrets, enabling zero-downtime rotation. By maintaining a set of "active"
+ * keys (including those in a grace period), it ensures that webhooks signed
+ * with either an old or new secret are successfully verified during transition.
+ *
+ * Key features:
+ * - Multi-version secret management.
+ * - Automatic background cleanup of expired keys.
+ * - Grace period support for smooth cut-overs.
+ * - Promotion of new primary keys.
+ *
+ * @example Managing zero-downtime rotation
+ * ```typescript
+ * const manager = new KeyRotationManager({
+ *   gracePeriod: 86400000, // 24 hours
+ *   autoCleanup: true,
+ * });
+ *
+ * // Register initial keys
+ * manager.registerKeys('stripe', [
+ *   {
+ *     key: 'whsec_primary',
+ *     version: 'v2',
+ *     isPrimary: true,
+ *     activeFrom: new Date(),
+ *   }
+ * ]);
+ *
+ * // Rotate to a new secret
+ * await manager.rotatePrimaryKey('stripe', {
+ *   key: 'whsec_new_secret',
+ *   version: 'v3',
+ *   activeFrom: new Date(),
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class KeyRotationManager {
+    private providerKeys;
+    private cleanupTimer?;
+    private config;
+    /**
+     * Constructs a new KeyRotationManager with the specified policy.
+     *
+     * @param config - Configuration for auto-cleanup, grace periods, and rotation hooks.
+     */
+    constructor(config?: KeyRotationConfig);
+    /**
+     * Registers a collection of keys for a specific provider.
+     *
+     * Validation ensures that exactly one primary key is specified for the provider.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @param keys - Array of valid key entries with metadata.
+     * @throws {Error} If no primary key is provided or if multiple primary keys are detected.
+     */
+    registerKeys(providerName: string, keys: ProviderKeyEntry[]): void;
+    /**
+     * Retrieves all currently valid keys for a provider to attempt verification.
+     *
+     * A key is considered active if the current time is after its `activeFrom` date
+     * and before its `expiresAt` date (if defined).
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns An array of currently active key entries.
+     */
+    getActiveKeys(providerName: string): ProviderKeyEntry[];
+    /**
+     * Retrieves the current primary key used for signature generation.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns The primary key entry, or null if no active primary key exists.
+     */
+    getPrimaryKey(providerName: string): ProviderKeyEntry | null;
+    /**
+     * Promotes a new primary key for the provider and retires the old one.
+     *
+     * The previous primary key is automatically assigned an expiration date based on
+     * the configured `gracePeriod`, allowing it to remain valid for incoming requests
+     * that were signed before the rotation propagated.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @param newKey - Metadata and secret for the new primary key.
+     */
+    rotatePrimaryKey(providerName: string, newKey: Omit<ProviderKeyEntry, 'isPrimary'>): Promise<void>;
+    /**
+     * Manually triggers a purge of all expired keys across all providers.
+     *
+     * @returns The total number of keys removed during this cycle.
+     */
+    cleanupExpiredKeys(): number;
+    /**
+     * Initializes the background timer for periodic key purging.
+     */
+    private startAutoCleanup;
+    /**
+     * Stops the auto-cleanup background process.
+     */
+    destroy(): void;
+    /**
+     * Provides a read-only snapshot of all keys across all providers.
+     *
+     * @returns A map of provider names to their complete key history.
+     */
+    getAllProviderKeys(): Map<string, ProviderKeyEntry[]>;
+    /**
+     * Checks if a specific provider has any keys registered in the manager.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns True if the provider is tracked.
+     */
+    hasProvider(providerName: string): boolean;
+}

package/dist/echo/src/rotation/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Echo Key Rotation
+ *
+ * 提供密鑰輪換功能
+ *
+ * @module @gravito/echo/rotation
+ * @since v1.2
+ */
+export type { KeyRotationConfig, ProviderKeyEntry } from '../types';
+export { KeyRotationManager } from './KeyRotationManager';

package/dist/echo/src/send/WebhookDispatcher.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Webhook Dispatcher
+ *
+ * Reliably sends webhooks to external services with retry support.
+ *
+ * @module @gravito/echo/send
+ */
+import type { DeadLetterQueue } from '../dlq/DeadLetterQueue';
+import type { EchoLogger } from '../observability/logging';
+import { type MetricsProvider } from '../observability/metrics';
+import { type Tracer } from '../observability/tracing';
+import type { BatchDispatchOptions, BatchDispatchResult, CircuitBreakerMetrics, WebhookDeliveryResult, WebhookDispatcherConfig, WebhookPayload } from '../types';
+/**
+ * WebhookDispatcher manages the secure and reliable delivery of events to external targets.
+ *
+ * It provides a robust engine for sending signed webhook payloads to third-party
+ * consumers, incorporating enterprise-grade reliability features such as:
+ * - Exponential backoff retries for transient network/server errors.
+ * - Per-host Circuit Breaking to prevent cascading failures.
+ * - Dead Letter Queue (DLQ) integration for capturing permanently failed events.
+ * - HMAC-SHA256 payload signing for authenticity.
+ *
+ * @example Dispatching a signed event
+ * ```typescript
+ * const dispatcher = new WebhookDispatcher({
+ *   secret: 'app-outbound-secret',
+ *   retry: { maxAttempts: 5 }
+ * });
+ *
+ * const result = await dispatcher.dispatch({
+ *   url: 'https://consumer.com/webhooks',
+ *   event: 'order.shipped',
+ *   data: { orderId: 'ORD-123' }
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Webhook delivered successfully');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class WebhookDispatcher {
+    private secret;
+    private retryConfig;
+    private timeout;
+    private userAgent;
+    private dlq?;
+    private metrics;
+    private tracer;
+    private logger?;
+    private circuitBreakers;
+    private circuitBreakerConfig?;
+    /**
+     * Initializes the dispatcher with security and reliability policies.
+     *
+     * @param config - The configuration for payload signing, retry logic, and timeouts.
+     */
+    constructor(config: WebhookDispatcherConfig);
+    /**
+     * Attaches a Dead Letter Queue for capturing events that fail all delivery attempts.
+     *
+     * @param dlq - Implementation of the DeadLetterQueue interface.
+     * @returns The current instance for method chaining.
+     */
+    setDeadLetterQueue(dlq: DeadLetterQueue): this;
+    /**
+     * Configures the metrics provider for delivery and failure tracking.
+     *
+     * @param metrics - Implementation of the MetricsProvider interface.
+     * @returns The current instance for method chaining.
+     */
+    setMetrics(metrics: MetricsProvider): this;
+    /**
+     * Configures the distributed tracer for end-to-end request visibility.
+     *
+     * @param tracer - Implementation of the Tracer interface.
+     * @returns The current instance for method chaining.
+     */
+    setTracer(tracer: Tracer): this;
+    /**
+     * Configures the logger for diagnostic and delivery audit logging.
+     *
+     * @param logger - Implementation of the EchoLogger interface.
+     * @returns The current instance for method chaining.
+     */
+    setLogger(logger: EchoLogger): this;
+    /**
+     * Resolves or creates a dedicated circuit breaker instance for a specific host.
+     *
+     * Using per-host isolation ensures that an outage at one consumer does not
+     * block or slow down deliveries to other healthy consumers.
+     *
+     * @param url - Destination URL used to derive the target host.
+     * @returns The active circuit breaker instance, or undefined if disabled.
+     */
+    private getCircuitBreaker;
+    /**
+     * Retrieves the current health metrics for a specific target's circuit breaker.
+     *
+     * @param url - The target URL whose host metrics are requested.
+     * @returns Current metrics or null if circuit breaking is not active for the host.
+     */
+    getCircuitBreakerMetrics(url: string): CircuitBreakerMetrics | null;
+    /**
+     * Manually resets a tripped circuit breaker to its CLOSED state for a specific target.
+     *
+     * @param url - The target URL whose host circuit should be reset.
+     */
+    resetCircuitBreaker(url: string): void;
+    /**
+     * Executes the end-to-end delivery of a signed webhook event.
+     *
+     * This method performs the following:
+     * 1. Wraps the payload with an authenticity signature (HMAC-SHA256).
+     * 2. Checks the state of the target's circuit breaker.
+     * 3. Executes the HTTP POST request.
+     * 4. Manages the retry lifecycle if errors occur.
+     * 5. Enqueues failed events to the DLQ if configured.
+     *
+     * @param payload - Data and destination parameters for the dispatch.
+     * @returns Final delivery outcome including success status and attempt count.
+     * @throws {Error} If critical internal operations (like signing) fail.
+     */
+    dispatch<T = unknown>(payload: WebhookPayload<T>): Promise<WebhookDeliveryResult>;
+    /**
+     * Internal orchestration for the delivery retry loop.
+     *
+     * @param payload - The webhook payload.
+     * @returns Final delivery result after all retry attempts.
+     */
+    private dispatchInternal;
+    /**
+     * Dispatches a batch of webhooks concurrently using an optimized worker pool.
+     *
+     * This method balances high throughput with source/target resource constraints
+     * by allowing you to tune concurrency and error propagation policies.
+     *
+     * @param payloads - Collection of payloads to deliver.
+     * @param options - Tuning parameters for concurrency and failure handling.
+     * @returns A summary result of all dispatch attempts in the batch.
+     *
+     * @example Batch dispatch with concurrency control
+     * ```typescript
+     * const results = await dispatcher.dispatchBatch(payloads, {
+     *   concurrency: 10,
+     *   stopOnFirstFailure: false
+     * });
+     * console.log(`Batch complete. Succeeded: ${results.succeeded}, Failed: ${results.failed}`);
+     * ```
+     */
+    dispatchBatch<T = unknown>(payloads: WebhookPayload<T>[], options?: BatchDispatchOptions): Promise<BatchDispatchResult>;
+    /**
+     * Re-attempts the delivery of a previously failed event from the Dead Letter Queue.
+     *
+     * If the delivery succeeds, the event is automatically removed from the DLQ.
+     *
+     * @param id - The unique identifier of the event in the DLQ.
+     * @returns Result of the retry attempt, or null if the event ID is invalid.
+     */
+    retryFromDlq(id: string): Promise<WebhookDeliveryResult | null>;
+    /**
+     * Executes a single delivery attempt including signing and circuit breaker check.
+     *
+     * @param payload - The webhook payload.
+     * @param attempt - The current attempt number.
+     * @returns Detailed result of the single attempt.
+     */
+    private attemptDelivery;
+    /**
+     * Internal logic to decide if an attempt should be retried.
+     *
+     * @param result - The delivery result to evaluate.
+     * @returns True if retry is eligible.
+     */
+    private shouldRetry;
+    /**
+     * Calculates the exponential backoff delay for the next attempt.
+     *
+     * @param attempt - The current attempt number.
+     * @returns Delay in milliseconds.
+     */
+    private calculateDelay;
+    /**
+     * Standardized categorization of delivery errors for metrics.
+     *
+     * @param result - The delivery result to categorize.
+     * @returns Category string.
+     */
+    private categorizeError;
+    /**
+     * Utility for asynchronous sleep.
+     *
+     * @param ms - Duration to sleep in ms.
+     * @returns Promise that resolves after delay.
+     */
+    private sleep;
+}

package/dist/echo/src/send/index.d.ts

@@ -0,0 +1 @@
+export * from './WebhookDispatcher';

package/dist/echo/src/storage/MemoryWebhookStore.d.ts

@@ -0,0 +1,14 @@
+import type { DeliveryAttempt, EventQueryFilter, IncomingWebhookRecord, OutgoingWebhookRecord, WebhookRecord, WebhookStore } from './WebhookStore';
+/**
+ * 記憶體儲存實作（開發/測試用）
+ */
+export declare class MemoryWebhookStore implements WebhookStore {
+    private events;
+    saveIncomingEvent(event: IncomingWebhookRecord): Promise<string>;
+    saveOutgoingEvent(event: OutgoingWebhookRecord): Promise<string>;
+    updateDeliveryAttempt(id: string, attempt: DeliveryAttempt): Promise<void>;
+    getEvent(id: string): Promise<WebhookRecord | null>;
+    queryEvents(filter: EventQueryFilter): Promise<WebhookRecord[]>;
+    markProcessed(id: string): Promise<void>;
+    markFailed(id: string, error: string): Promise<void>;
+}

package/dist/echo/src/storage/WebhookStore.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Interface for the Webhook Event Storage layer.
+ *
+ * Implementations of this interface are responsible for providing durable
+ * persistence for both incoming and outgoing webhook events. This layer is
+ * critical for:
+ * - Security Auditing: Maintaining a verifiable trail of all received events.
+ * - Reliability: Enabling re-dispatch of failed outgoing webhooks.
+ * - Idempotency: Checking for duplicate events to prevent double-processing.
+ * - Observability: Providing data for historical analysis and reporting.
+ *
+ * @example Implementing a custom database store
+ * ```typescript
+ * class MyStore implements WebhookStore {
+ *   async saveIncomingEvent(event: IncomingWebhookRecord) {
+ *     const id = await db.insert('webhooks').values(event).returning('id');
+ *     return id;
+ *   }
+ *   // ... implement other methods
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface WebhookStore {
+    /**
+     * Persists a record of a successfully verified incoming webhook.
+     *
+     * @param event - Metadata and payload of the verified incoming event.
+     * @returns A promise resolving to a unique identifier for the stored event.
+     */
+    saveIncomingEvent(event: IncomingWebhookRecord): Promise<string>;
+    /**
+     * Persists a record of a webhook that is being dispatched to a consumer.
+     *
+     * @param event - Metadata and payload of the outgoing event intent.
+     * @returns A promise resolving to a unique identifier for the stored record.
+     */
+    saveOutgoingEvent(event: OutgoingWebhookRecord): Promise<string>;
+    /**
+     * Updates or appends a delivery attempt result for an outgoing webhook.
+     *
+     * @param id - The unique ID of the original outgoing event record.
+     * @param attempt - Detailed outcome of the specific delivery attempt.
+     */
+    updateDeliveryAttempt(id: string, attempt: DeliveryAttempt): Promise<void>;
+    /**
+     * Retrieves a specific webhook event record by its unique identifier.
+     *
+     * @param id - The unique ID assigned by the storage layer.
+     * @returns The event record if found, otherwise null.
+     */
+    getEvent(id: string): Promise<WebhookRecord | null>;
+    /**
+     * Performs a filtered search across persisted webhook events.
+     *
+     * @param filter - Criteria for filtering events (e.g., provider, date range).
+     * @returns A collection of matching webhook records.
+     */
+    queryEvents(filter: EventQueryFilter): Promise<WebhookRecord[]>;
+    /**
+     * Transitions an incoming event status to 'processed' after successful handling.
+     *
+     * @param id - The unique ID of the incoming event.
+     */
+    markProcessed(id: string): Promise<void>;
+    /**
+     * Records a processing failure for an incoming event with diagnostic details.
+     *
+     * @param id - The unique ID of the incoming event.
+     * @param error - A descriptive message detailing why processing failed.
+     */
+    markFailed(id: string, error: string): Promise<void>;
+}
+/**
+ * Persisted representation of an authenticated incoming webhook event.
+ *
+ * @public
+ */
+export interface IncomingWebhookRecord {
+    /**
+     * Unique identifier assigned by the storage layer.
+     */
+    id?: string;
+    /**
+     * The name of the provider instance that verified the event.
+     */
+    provider: string;
+    /**
+     * The semantic type of the event (e.g., 'invoice.paid').
+     */
+    eventType: string;
+    /**
+     * The parsed JSON data extracted from the verified webhook body.
+     */
+    payload: unknown;
+    /**
+     * Filtered set of HTTP headers received with the original request.
+     */
+    headers: Record<string, string | undefined>;
+    /**
+     * The exact unparsed request body, preserved for audit or re-verification.
+     */
+    rawBody: string;
+    /**
+     * The timestamp when the event was first recorded by the system.
+     */
+    receivedAt: Date;
+    /**
+     * The current stage in the event's processing lifecycle.
+     */
+    status: 'pending' | 'processed' | 'failed';
+    /**
+     * Diagnostic details provided if the status is 'failed'.
+     */
+    processingError?: string;
+    /**
+     * Discriminator field used for heterogeneous storage collections.
+     */
+    direction?: 'incoming';
+}
+/**
+ * Persisted representation of an outgoing webhook dispatch and its delivery status.
+ *
+ * @public
+ */
+export interface OutgoingWebhookRecord {
+    /**
+     * Unique identifier assigned by the storage layer.
+     */
+    id?: string;
+    /**
+     * The destination URL where the webhook is being delivered.
+     */
+    url: string;
+    /**
+     * The semantic name of the event being dispatched.
+     */
+    event: string;
+    /**
+     * The JSON payload sent to the destination server.
+     */
+    payload: unknown;
+    /**
+     * The timestamp when the dispatch operation was first initiated.
+     */
+    createdAt: Date;
+    /**
+     * The overall delivery status based on attempt history.
+     */
+    status: 'pending' | 'delivered' | 'failed';
+    /**
+     * Chronological history of all delivery attempts for this dispatch.
+     */
+    attempts: DeliveryAttempt[];
+    /**
+     * Discriminator field used for heterogeneous storage collections.
+     */
+    direction?: 'outgoing';
+}
+/**
+ * Union type representing any type of persisted webhook transaction.
+ *
+ * @public
+ */
+export type WebhookRecord = IncomingWebhookRecord | OutgoingWebhookRecord;
+/**
+ * Detailed telemetry for a single HTTP delivery attempt to an external consumer.
+ *
+ * @public
+ */
+export interface DeliveryAttempt {
+    /**
+     * The sequence number of this attempt (starts at 1).
+     */
+    attemptNumber: number;
+    /**
+     * The exact timestamp when the network request was initiated.
+     */
+    timestamp: Date;
+    /**
+     * The HTTP status code returned by the destination server (if reached).
+     */
+    statusCode?: number;
+    /**
+     * The raw response body returned by the target server for diagnostics.
+     */
+    responseBody?: string;
+    /**
+     * The error message if the attempt failed at the network or protocol level.
+     */
+    error?: string;
+    /**
+     * The total duration of the HTTP request in milliseconds.
+     */
+    duration: number;
+}
+/**
+ * Parameters for querying and filtering the webhook event audit log.
+ *
+ * @public
+ */
+export interface EventQueryFilter {
+    /**
+     * Limit search to either 'incoming' or 'outgoing' events.
+     */
+    direction?: 'incoming' | 'outgoing';
+    /**
+     * Filter by the name of the provider instance.
+     */
+    provider?: string;
+    /**
+     * Filter by the semantic event type.
+     */
+    eventType?: string;
+    /**
+     * Filter by current processing or delivery status.
+     */
+    status?: string;
+    /**
+     * Start boundary for the search time range.
+     */
+    from?: Date;
+    /**
+     * End boundary for the search time range.
+     */
+    to?: Date;
+    /**
+     * Maximum number of records to return for this query.
+     */
+    limit?: number;
+    /**
+     * Number of records to skip for paginated results.
+     */
+    offset?: number;
+}

package/dist/echo/src/storage/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MemoryWebhookStore';
+export * from './WebhookStore';