@gravito/echo 3.0.1 → 3.1.0

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

@@ -5,50 +5,194 @@
  *
  * @module @gravito/echo/send
  */
-import type { WebhookDeliveryResult, WebhookDispatcherConfig, WebhookPayload } from '../types';
+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';
 /**
- * Webhook Dispatcher
+ * WebhookDispatcher manages the secure and reliable delivery of events to external targets.
  *
- * Sends webhooks with signature and retry support.
+ * 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
+ * @example Dispatching a signed event
  * ```typescript
  * const dispatcher = new WebhookDispatcher({
- *   secret: 'my-webhook-secret',
+ *   secret: 'app-outbound-secret',
  *   retry: { maxAttempts: 5 }
- * })
+ * });
  *
  * const result = await dispatcher.dispatch({
- *   url: 'https://example.com/webhook',
- *   event: 'order.created',
- *   data: { orderId: 123 }
- * })
+ *   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);
     /**
-     * Dispatch a webhook with retries
+     * 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>;
     /**
-     * Attempt a single delivery
+     * 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;
     /**
-     * Check if we should retry based on result
+     * 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;
     /**
-     * Calculate delay for exponential backoff
+     * Calculates the exponential backoff delay for the next attempt.
+     *
+     * @param attempt - The current attempt number.
+     * @returns Delay in milliseconds.
      */
     private calculateDelay;
     /**
-     * Sleep helper
+     * 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/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';