@gravito/echo 3.0.1 → 3.1.0

package/README.md

@@ -8,6 +8,9 @@
 - **Built-in Providers** - Stripe, GitHub, and generic provider support
 - **Reliable Sending** - Exponential backoff retry with configurable strategy
 - **Gravito Integration** - First-class OrbitEcho module for PlanetCore
+- **Request Buffering (v1.1)** - Prevents signature verification failures from framework auto-parsing
+- **Circuit Breaker (v1.1)** - Protects downstream services with automatic failure detection
+- **Key Rotation (v1.2)** - Zero-downtime key updates with multi-version support
 
 ## Installation
 
@@ -90,8 +93,174 @@ if (result.success) {
 } else {
   console.error('Delivery failed:', result.error)
 }
+
+// Batch sending
+const batchResult = await dispatcher.dispatchBatch([
+  { url: 'https://a.com', event: 'e1', data: { id: 1 } },
+  { url: 'https://b.com', event: 'e1', data: { id: 2 } }
+], { concurrency: 5 })
+```
+
+### Persistence & Reliability
+
+Echo supports persistence for audit logs and Dead Letter Queues (DLQ) for failed deliveries.
+
+```typescript
+import { 
+  OrbitEcho, 
+  MemoryWebhookStore, 
+  MemoryDeadLetterQueue 
+} from '@gravito/echo'
+
+const echo = new OrbitEcho({
+  providers: { /* ... */ },
+  dispatcher: { /* ... */ },
+  // Configure persistence
+  store: new MemoryWebhookStore(), // Or your DB implementation
+  deadLetterQueue: new MemoryDeadLetterQueue()
+})
+
+// Replay failed events
+const replayService = new WebhookReplayService(echo.getConfig().store!, echo.getDispatcher()!)
+await replayService.replay({ 
+  timeRange: { from: new Date(Date.now() - 86400000), to: new Date() },
+  dryRun: true 
+})
+
+// Observability
+const echoWithObservability = new OrbitEcho({
+  providers: { /* ... */ },
+  observability: {
+    logger: new ConsoleEchoLogger(),
+    metrics: new PrometheusMetricsProvider(),
+    // tracer: opentelemetryTracer
+  }
+})
+```
+
+## Advanced Features (v1.1+)
+
+### Request Buffer Middleware
+
+防止框架自動解析 JSON 導致簽章驗證失敗。預設啟用，會在驗證前緩存原始 request body。
+
+```typescript
+const echo = new OrbitEcho({
+  providers: { /* ... */ },
+  requestBuffer: {
+    enabled: true,              // 預設 true
+    maxBodySize: 10485760,      // 預設 10MB
+    skipContentTypes: [         // 跳過特定 content types
+      'multipart/form-data',
+      'application/octet-stream'
+    ]
+  }
+})
 ```
 
+Request Buffer 會自動整合到接收流程，無需額外配置。若需停用：
+
+```typescript
+const echo = new OrbitEcho({
+  providers: { /* ... */ },
+  requestBuffer: { enabled: false }
+})
+```
+
+### Circuit Breaker
+
+保護下游服務免於雪崩效應，當失敗率超過閾值時自動斷路。
+
+```typescript
+import { WebhookDispatcher } from '@gravito/echo'
+
+const dispatcher = new WebhookDispatcher({
+  secret: process.env.OUTGOING_WEBHOOK_SECRET!,
+  circuitBreaker: {
+    enabled: true,              // 預設 true
+    failureThreshold: 5,        // 預設 5 次失敗後開路
+    successThreshold: 2,        // 預設 2 次成功後關路
+    windowSize: 60000,          // 預設 1 分鐘窗口
+    openTimeout: 30000,         // 預設 30 秒後嘗試半開
+    // 可選的狀態變更回調
+    onOpen: (target) => console.log(`Circuit opened for ${target}`),
+    onHalfOpen: (target) => console.log(`Circuit half-open for ${target}`),
+    onClose: (target) => console.log(`Circuit closed for ${target}`)
+  }
+})
+
+// 檢查熔斷器狀態
+const metrics = dispatcher.getCircuitBreakerMetrics('example.com')
+console.log(metrics.state) // 'CLOSED' | 'OPEN' | 'HALF_OPEN'
+
+// 手動重置熔斷器
+dispatcher.resetCircuitBreaker('example.com')
+```
+
+**熔斷器運作邏輯**：
+- **CLOSED（關路）**：正常運作，所有請求通過
+- **OPEN（開路）**：失敗次數超過閾值，立即拒絕所有請求
+- **HALF_OPEN（半開）**：嘗試恢復，允許有限請求測試服務狀態
+
+每個目標 host 使用獨立的熔斷器，避免單點故障影響全域。
+
+### Key Rotation
+
+支援 Provider 密鑰的動態輪換，無需重啟應用。
+
+```typescript
+import { OrbitEcho } from '@gravito/echo'
+
+const echo = new OrbitEcho({
+  // 啟用密鑰輪換功能
+  keyRotation: {
+    enabled: true,
+    autoCleanup: true,          // 自動清理過期密鑰
+    gracePeriod: 86400000,      // 24 小時寬限期
+    onRotate: (provider, newKey) => {
+      console.log(`Key rotated for ${provider}: ${newKey.version}`)
+    }
+  },
+  // 使用多密鑰配置 Provider
+  providers: {
+    stripe: {
+      name: 'stripe',
+      secret: '', // 主密鑰會從 keys 中自動設定
+      keys: [
+        {
+          key: 'whsec_new_key',
+          version: 'v2',
+          isPrimary: true,
+          activeFrom: new Date('2026-01-15')
+        },
+        {
+          key: 'whsec_old_key',
+          version: 'v1',
+          isPrimary: false,
+          activeFrom: new Date('2025-01-01'),
+          expiresAt: new Date('2026-02-15') // 寬限期結束時間
+        }
+      ]
+    }
+  }
+})
+
+// 執行密鑰輪換
+await echo.rotateProviderKey('stripe', {
+  key: 'whsec_newest_key',
+  version: 'v3',
+  activeFrom: new Date()
+})
+```
+
+**密鑰輪換運作邏輯**：
+1. 在輪換期間，系統同時接受新舊密鑰驗證
+2. 舊主密鑰自動降級為輔助密鑰，並設定過期時間（當前時間 + gracePeriod）
+3. 新密鑰成為主密鑰，用於所有新的簽章驗證
+4. 過期密鑰會自動清理（若啟用 autoCleanup）
+
+這確保了正在傳輸中的 Webhook 不會因密鑰輪換而失敗。
+
 ## Providers
 
 ### Built-in Providers
@@ -101,6 +270,11 @@ if (result.success) {
 | `stripe` | HMAC-SHA256 + Timestamp | `Stripe-Signature` |
 | `github` | HMAC-SHA256 | `X-Hub-Signature-256` |
 | `generic` | HMAC-SHA256 | `X-Webhook-Signature` |
+| `shopify` | HMAC-SHA256 (base64) | `X-Shopify-Hmac-Sha256` |
+| `twilio` | HMAC-SHA1 (base64) | `X-Twilio-Signature` |
+| `slack` | HMAC-SHA256 + Timestamp | `X-Slack-Signature` |
+| `paddle` | HMAC-SHA256 + Timestamp | `Paddle-Signature` |
+| `linear` | HMAC-SHA256 | `Linear-Signature` |
 
 ### Custom Provider
 
@@ -122,6 +296,8 @@ receiver.registerProvider('custom', 'secret', { type: 'my-provider' })
 
 ## Configuration
 
+For detailed API information, please refer to the [API Documentation](./docs/api/README.md).
+
 ### WebhookDispatcher
 
 ```typescript
@@ -143,6 +319,18 @@ interface WebhookDispatcherConfig {
 
   /** Custom User-Agent */
   userAgent?: string
+
+  /** Circuit breaker configuration (v1.1+) */
+  circuitBreaker?: {
+    enabled?: boolean           // default: true
+    failureThreshold?: number   // default: 5
+    successThreshold?: number   // default: 2
+    windowSize?: number         // default: 60000 (1 minute)
+    openTimeout?: number        // default: 30000 (30 seconds)
+    onOpen?: (target: string) => void
+    onHalfOpen?: (target: string) => void
+    onClose?: (target: string) => void
+  }
 }
 ```
 
@@ -155,6 +343,14 @@ interface EchoConfig {
     name: string
     secret: string
     tolerance?: number  // timestamp tolerance in seconds
+    // Key rotation support (v1.2+)
+    keys?: Array<{
+      key: string
+      version: string
+      isPrimary: boolean
+      activeFrom: Date
+      expiresAt?: Date
+    }>
   }>
 
   /** Dispatcher configuration */
@@ -162,6 +358,21 @@ interface EchoConfig {
 
   /** Base path for webhook endpoints */
   basePath?: string  // default: '/webhooks'
+
+  /** Request buffer configuration (v1.1+) */
+  requestBuffer?: {
+    enabled?: boolean           // default: true
+    maxBodySize?: number        // default: 10485760 (10MB)
+    skipContentTypes?: string[] // default: ['multipart/form-data', 'application/octet-stream']
+  }
+
+  /** Key rotation configuration (v1.2+) */
+  keyRotation?: {
+    enabled?: boolean           // default: false
+    autoCleanup?: boolean       // default: true
+    gracePeriod?: number        // default: 86400000 (24 hours)
+    onRotate?: (providerName: string, newKey: ProviderKeyEntry) => void
+  }
 }
 ```
 

package/dist/atlas/src/DB.d.ts

@@ -0,0 +1,301 @@
+import { type AtlasMetrics, type AtlasTracer } from './observability';
+import type { AtlasConfig, CacheInterface, ConnectionConfig, ConnectionContract, QueryBuilderContract, QueryResult } from './types';
+/**
+ * DB Facade - Static entry point for database operations.
+ *
+ * Provides a Laravel-style static interface for managing connections,
+ * building queries, and executing transactions. Acts as the primary
+ * gateway for application-level database interaction.
+ *
+ * @example
+ * ```typescript
+ * // Setup
+ * DB.configure({
+ *   default: 'main',
+ *   connections: { main: { driver: 'sqlite', database: ':memory:' } }
+ * });
+ *
+ * // Fluent Querying
+ * const users = await DB.table('users').where('id', 1).get();
+ *
+ * // Raw Execution
+ * const stats = await DB.raw('SELECT count(*) FROM users');
+ * ```
+ */
+export declare class DB {
+    private static manager;
+    private static initialized;
+    private static cache;
+    private static _debug;
+    private static _queryLog;
+    private static readonly MAX_LOG_SIZE;
+    private static queryListener?;
+    /**
+     * Sets the global cache provider for query results.
+     *
+     * @param cache - Implementation of CacheInterface (e.g., Redis, In-Memory).
+     */
+    static setCache(cache: CacheInterface): void;
+    /**
+     * Retrieves the active global cache provider.
+     *
+     * @returns The cache interface or undefined if none is configured.
+     */
+    static getCache(): CacheInterface | undefined;
+    /**
+     * Toggles debug mode for query logging.
+     *
+     * When enabled, executed queries are stored in an internal log with
+     * performance metrics.
+     *
+     * @param enabled - Whether to enable logging.
+     */
+    static debug(enabled?: boolean): void;
+    /**
+     * Indicates if debug mode is currently active.
+     */
+    static isDebug(): boolean;
+    /**
+     * Retrieves the last executed SQL statement with interpolated values.
+     *
+     * Useful for debugging and integration testing.
+     *
+     * @returns The full SQL string or null if no queries were run.
+     */
+    static getLastQuery(): string | null;
+    /**
+     * Retrieves the complete query log for the current session.
+     *
+     * @returns A copy of the query log array.
+     */
+    static getQueryLog(): typeof this._queryLog;
+    /**
+     * Flushes the internal query log.
+     */
+    static clearQueryLog(): void;
+    /**
+     * Records a query execution event.
+     *
+     * @param sql - The SQL statement.
+     * @param bindings - The parameter values.
+     * @param duration - Time taken in ms.
+     * @internal
+     */
+    static logQuery(sql: string, bindings: unknown[], duration: number): void;
+    /**
+     * Interpolates bindings into a SQL string for display purposes.
+     *
+     * Warning: This is only for logging/debugging and NOT for execution
+     * to avoid SQL injection risks.
+     *
+     * @param sql - The SQL template with placeholders.
+     * @param bindings - The values to inject.
+     * @returns The readable SQL string.
+     */
+    private static interpolateBindings;
+    /**
+     * Executes a callback in "pretend" mode where queries are captured but not run.
+     *
+     * Ideal for verifying generated SQL without side effects.
+     *
+     * @param callback - Logic to simulate.
+     * @returns Captured SQL strings and the callback result.
+     *
+     * @example
+     * ```typescript
+     * const { queries } = await DB.pretend(() => User.create({ name: 'Test' }));
+     * ```
+     */
+    static pretend<T>(callback: () => Promise<T>): Promise<{
+        queries: string[];
+        result?: T;
+    }>;
+    private constructor();
+    /**
+     * Retrieves performance metrics from the SQL compiler cache.
+     *
+     * @returns Stats including hit rate and cache utilization.
+     */
+    static getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+    };
+    /**
+     * Initializes the database subsystem with the provided configuration.
+     *
+     * Configures the connection manager and observability (Tracing/Metrics).
+     * This method must be called before any database operations.
+     *
+     * @param config - The Atlas configuration object.
+     * @throws {Error} If configuration is invalid.
+     */
+    static configure(config: AtlasConfig): void;
+    /**
+     * Retrieves the global tracer for manual span creation.
+     */
+    static getTracer(): AtlasTracer | undefined;
+    /**
+     * Retrieves the global metrics reporter.
+     */
+    static getMetrics(): AtlasMetrics | undefined;
+    /**
+     * Configures the database using environment variables.
+     *
+     * Looks for standard DB_* variables or DATABASE_URL.
+     *
+     * @param connectionName - The name to assign to the primary connection.
+     */
+    static configureFromEnv(connectionName?: string): void;
+    /**
+     * Loads configuration from a file.
+     *
+     * Automatically detects common patterns like config/database.ts.
+     *
+     * @param configPath - Explicit path to the config file.
+     */
+    static configureFromFile(configPath?: string): Promise<void>;
+    /**
+     * Best-effort configuration using file detection then environment variables.
+     *
+     * @param configPath - Optional path to try first.
+     */
+    static autoConfigure(configPath?: string): Promise<void>;
+    /**
+     * Manually adds a connection to the manager.
+     *
+     * @param name - Unique connection name.
+     * @param config - Connection settings.
+     */
+    static addConnection(name: string, config: ConnectionConfig): void;
+    /**
+     * Adds a connection configured via prefixed environment variables.
+     *
+     * @param name - Connection name.
+     * @param prefix - Env variable prefix (e.g. "READ_ONLY").
+     */
+    static addConnectionFromEnv(name: string, prefix?: string): void;
+    /**
+     * Sets the global default connection.
+     *
+     * @param name - The connection identifier.
+     */
+    static setDefaultConnection(name: string): void;
+    /**
+     * Returns the name of the current default connection.
+     */
+    static getDefaultConnection(): string;
+    /**
+     * Retrieves a connection instance.
+     *
+     * @param name - Name of the connection (defaults to the global default).
+     * @returns The active connection instance.
+     * @throws {Error} If DB is not configured or connection name is unknown.
+     */
+    static connection(name?: string): ConnectionContract;
+    /**
+     * Checks if a specific connection has been configured.
+     */
+    static hasConnection(name: string): boolean;
+    /**
+     * Lists all configured connection identifiers.
+     */
+    static getConnectionNames(): string[];
+    /**
+     * Retrieves the raw configuration for a connection.
+     */
+    static getConnectionConfig(name?: string): ConnectionConfig | undefined;
+    /**
+     * Initializes a fluent query builder for a specific table.
+     *
+     * @template T - The row type.
+     * @param tableName - The database table name.
+     * @returns A QueryBuilder instance.
+     */
+    static table<T = Record<string, unknown>>(tableName: string): QueryBuilderContract<T>;
+    /**
+     * Executes a raw SQL statement with telemetry tracking.
+     *
+     * @template T - The expected row type.
+     * @param sql - The SQL string with placeholders.
+     * @param bindings - Array of values.
+     * @returns The raw query result.
+     *
+     * @example
+     * ```typescript
+     * const users = await DB.raw('SELECT * FROM users WHERE active = ?', [true]);
+     * ```
+     */
+    static raw<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Alias for {@link raw}.
+     */
+    static rawQuery<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Executes logic within a managed database transaction.
+     *
+     * Automatically commits on success and rolls back on error.
+     * Receives a connection instance scoped to the transaction.
+     *
+     * @template T - Logic result type.
+     * @param callback - The transactional logic.
+     * @param connectionName - Optional specific connection.
+     * @returns The callback's return value.
+     */
+    static transaction<T>(callback: (connection: ConnectionContract) => Promise<T>, connectionName?: string): Promise<T>;
+    /**
+     * Manually starts a database transaction.
+     *
+     * Caller is responsible for calling commit() or rollback().
+     *
+     * @param connectionName - Connection to use.
+     * @returns A transaction-scoped connection.
+     * @throws {Error} If the driver does not support transactions.
+     */
+    static beginTransaction(connectionName?: string): Promise<ConnectionContract>;
+    /**
+     * Closes the specified connection.
+     */
+    static disconnect(name?: string): Promise<void>;
+    /**
+     * Closes all managed connections.
+     */
+    static disconnectAll(): Promise<void>;
+    /**
+     * Safely shuts down the database subsystem.
+     */
+    static shutdown(): Promise<void>;
+    /**
+     * Closes and re-opens a connection.
+     */
+    static reconnect(name?: string): Promise<ConnectionContract>;
+    /**
+     * Removes a connection from the internal cache without closing it.
+     */
+    static purge(name?: string): void;
+    /**
+     * Shortcut for starting a query with specific columns.
+     */
+    static select<T = Record<string, unknown>>(tableName: string, columns?: string[]): QueryBuilderContract<T>;
+    /**
+     * Shortcut for inserting records.
+     */
+    static insert<T = Record<string, unknown>>(tableName: string, data: Partial<T> | Partial<T>[]): Promise<T[]>;
+    /**
+     * Shortcut for updating records based on key-value filters.
+     */
+    static update<T = Record<string, unknown>>(tableName: string, where: Record<string, unknown>, data: Partial<T>): Promise<number>;
+    /**
+     * Shortcut for deleting records based on key-value filters.
+     */
+    static delete(tableName: string, where: Record<string, unknown>): Promise<number>;
+    /**
+     * Ensures the DB facade is ready for use.
+     */
+    private static ensureConfigured;
+    /**
+     * Internal reset for testing.
+     * @internal
+     */
+    static _reset(): Promise<void>;
+}

package/dist/atlas/src/OrbitAtlas.d.ts

@@ -0,0 +1,9 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+/**
+ * Atlas Orbit - Database & ORM Integration
+ * Integrates the Atlas ORM engine into the Gravito Core ecosystem.
+ * @public
+ */
+export declare class OrbitAtlas implements GravitoOrbit {
+    install(core: PlanetCore): Promise<void>;
+}

package/dist/atlas/src/config/defineConfig.d.ts

@@ -0,0 +1,14 @@
+import type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig } from '../types';
+export type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig };
+/**
+ * Define configuration with type checking
+ */
+export declare function defineConfig(config: AtlasConfig): AtlasConfig;
+/**
+ * Load configuration from environment variables with optional prefix
+ * Supports both DATABASE_URL and individual DB_* variables
+ *
+ * @param connectionName - Name for the connection
+ * @param prefix - Optional prefix for environment variables (e.g., 'READ' for DB_READ_*)
+ */
+export declare function fromEnv(connectionName?: string, prefix?: string): AtlasConfig;

package/dist/atlas/src/config/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Configuration Module
+ * @description Database configuration utilities
+ */
+export type { AtlasConfig, ConnectionConfig } from '../types';
+export { defineConfig, fromEnv } from './defineConfig';
+export { autoConfigure, loadConfig, loadConfigFile } from './loadConfig';

package/dist/atlas/src/config/loadConfig.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Configuration Loader
+ * @description Load database configuration from various sources
+ */
+import type { AtlasConfig } from '../types';
+/**
+ * Load configuration from a TypeScript/JavaScript config file
+ *
+ * @param configPath - Path to the config file (default: 'config/database.ts' or 'config/database.js')
+ * @returns Atlas configuration
+ *
+ * @example
+ * ```typescript
+ * // config/database.ts
+ * import { defineConfig } from '@gravito/atlas'
+ *
+ * export default defineConfig({
+ *   default: 'default',
+ *   connections: {
+ *     default: {
+ *       driver: 'postgres',
+ *       host: 'localhost',
+ *       database: 'myapp'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function loadConfigFile(configPath?: string): Promise<AtlasConfig>;
+/**
+ * Load configuration from multiple sources with priority
+ * Priority: 1. Config file, 2. Environment variables, 3. Default
+ *
+ * @param options - Loading options
+ * @returns Atlas configuration
+ */
+export declare function loadConfig(options?: {
+    configPath?: string;
+    useEnv?: boolean;
+    envPrefix?: string;
+}): Promise<AtlasConfig>;
+/**
+ * Auto-configure database from config file or environment
+ * This is a convenience function that tries config file first, then environment
+ *
+ * @param configPath - Optional path to config file
+ */
+export declare function autoConfigure(configPath?: string): Promise<void>;