@gravito/ripple 4.0.0 → 4.0.3

package/dist/core/src/events/aggregation/EventAggregationManager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Event aggregation manager (FS-102)
+ *
+ * Coordinates deduplication and batching for optimal event processing:
+ * - Event deduplication (pattern-based or idempotency-key based)
+ * - Micro-batching (time and size dual-trigger)
+ * - Backpressure-aware window adjustment
+ * - Complete statistics tracking
+ *
+ * Ported from: examples/flash-sale-fullstack/src/cache/events/EventAggregator.ts
+ */
+import type { BackpressureManager } from '../BackpressureManager';
+import type { EventTask } from '../types';
+import { AggregationWindow } from './AggregationWindow';
+import { DeduplicationManager } from './DeduplicationManager';
+import { EventBatcher } from './EventBatcher';
+import type { AggregationConfig, AggregationStats } from './types';
+/**
+ * Event aggregation manager.
+ */
+export declare class EventAggregationManager {
+    private deduplicator;
+    private batcher;
+    private window;
+    private config;
+    private backpressureManager?;
+    private submitToQueueFn?;
+    private disabled;
+    /**
+     * Create an event aggregation manager.
+     */
+    constructor(config?: Partial<AggregationConfig>);
+    /**
+     * Set backpressure manager for window adjustment.
+     * FS-103：Also sets BackpressureManager on AggregationWindow for feedback loop.
+     */
+    setBackpressureManager(backpressure: BackpressureManager): void;
+    /**
+     * Set the actual queue submission function.
+     */
+    setSubmitToQueueFn(fn: (tasks: EventTask[]) => Promise<void>): void;
+    /**
+     * Submit an event for aggregation.
+     *
+     * Returns true if accepted, false if rejected due to backpressure.
+     */
+    submit(task: EventTask): Promise<boolean>;
+    /**
+     * Submit multiple events.
+     */
+    submitBatch(tasks: EventTask[]): Promise<number>;
+    /**
+     * Flush current batch to queue.
+     */
+    flush(): Promise<EventTask[]>;
+    /**
+     * Get aggregation statistics.
+     */
+    getStats(): AggregationStats;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Clear aggregation state.
+     */
+    clear(): void;
+    /**
+     * Check if there are pending events.
+     */
+    hasPending(): boolean;
+    /**
+     * Get pending event count.
+     */
+    getPendingCount(): number;
+    /**
+     * Disable the aggregation manager.
+     */
+    disable(): void;
+    /**
+     * Enable the aggregation manager.
+     */
+    enable(): void;
+    /**
+     * Check if aggregation manager is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Shutdown the aggregation manager.
+     */
+    shutdown(): Promise<EventTask[]>;
+    /**
+     * Submit deduplicated events to queue.
+     */
+    private submitToQueue;
+    /**
+     * Get deduplication manager (for testing).
+     */
+    __getDeduplicator(): DeduplicationManager;
+    /**
+     * Get event batcher (for testing).
+     */
+    __getBatcher(): EventBatcher;
+    /**
+     * Get aggregation window (for testing).
+     */
+    __getWindow(): AggregationWindow;
+}

package/dist/core/src/events/aggregation/EventBatcher.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Event batcher for microbatching optimization (FS-102)
+ *
+ * Implements dual-trigger batching:
+ * - Time window trigger (default 50ms)
+ * - Batch size trigger (default 50 events)
+ *
+ * Expected improvements: 10-15% throughput increase
+ *
+ * Ported from: examples/flash-sale-fullstack/src/cache/events/BatchSubmitter.ts
+ */
+import type { EventTask } from '../types';
+import type { BatchStats } from './types';
+/**
+ * Event batcher for optimizing submission throughput.
+ */
+export declare class EventBatcher {
+    private queue;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private flushTimer;
+    private stats;
+    private submitFn;
+    /**
+     * Create an event batcher.
+     *
+     * @param batchSize - Batch size threshold (default 50)
+     * @param flushIntervalMs - Time window (ms, default 50)
+     * @param submitFn - Function to submit batches
+     */
+    constructor(batchSize: number | undefined, flushIntervalMs: number | undefined, submitFn: (tasks: EventTask[]) => Promise<void>);
+    /**
+     * Enqueue an event.
+     *
+     * Automatically triggers flush if:
+     * 1. Batch size is reached
+     * 2. Time window expires
+     */
+    enqueue(task: EventTask): Promise<void>;
+    /**
+     * Enqueue multiple events.
+     */
+    enqueueBatch(tasks: EventTask[]): Promise<void>;
+    /**
+     * Flush queued events.
+     *
+     * @param auto - Whether this is an auto-triggered flush
+     * @returns Array of flushed events
+     */
+    flush(auto?: boolean): Promise<EventTask[]>;
+    /**
+     * Get statistics.
+     */
+    getStats(): BatchStats;
+    /**
+     * Get pending event count.
+     */
+    getPendingCount(): number;
+    /**
+     * Check if there are pending events.
+     */
+    hasPending(): boolean;
+    /**
+     * Clear the queue.
+     */
+    clear(): void;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Stop the batcher and flush remaining events.
+     */
+    stop(): Promise<EventTask[]>;
+    /**
+     * Start time-window timer.
+     */
+    private startTimer;
+    /**
+     * Clear timer.
+     */
+    private clearTimer;
+    /**
+     * Adjust batch size.
+     */
+    setBatchSize(newSize: number): void;
+    /**
+     * Adjust flush interval.
+     */
+    setFlushInterval(_newIntervalMs: number): void;
+    /**
+     * Get batch size.
+     */
+    getBatchSize(): number;
+    /**
+     * Get flush interval.
+     */
+    getFlushInterval(): number;
+}

package/dist/core/src/events/aggregation/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Event aggregation and deduplication types (FS-102)
+ * @internal
+ */
+import { BackpressureState } from '../BackpressureManager';
+/**
+ * Deduplication statistics.
+ */
+export interface DeduplicationStats {
+    /** Total events submitted */
+    totalEvents: number;
+    /** Events after deduplication */
+    deduplicatedEvents: number;
+    /** Events removed by deduplication */
+    removedCount: number;
+    /** Number of patterns aggregated */
+    patternsAggregated: number;
+    /** Deduplication rate (%) */
+    deduplicationRate: number;
+}
+/**
+ * Batch submission statistics.
+ */
+export interface BatchStats {
+    /** Total batches submitted */
+    totalBatches: number;
+    /** Total events submitted */
+    totalEvents: number;
+    /** Average batch size */
+    averageBatchSize: number;
+    /** Average batch latency (ms) */
+    averageBatchLatency: number;
+    /** Last flush timestamp */
+    lastFlushTime: number;
+    /** Pending events in queue */
+    pendingEvents: number;
+    /** Auto-triggered flushes */
+    autoFlushCount: number;
+    /** Manual flushes */
+    manualFlushCount: number;
+}
+/**
+ * Aggregation window statistics.
+ */
+export interface WindowStats {
+    /** Current window size (ms) */
+    currentWindowMs: number;
+    /** Minimum window size (ms) */
+    minWindowMs: number;
+    /** Maximum window size (ms) */
+    maxWindowMs: number;
+    /** Last window adjustment reason */
+    lastAdjustmentReason?: string;
+    /** Window adjustment count */
+    adjustmentCount: number;
+}
+/**
+ * Complete aggregation statistics.
+ */
+export interface AggregationStats {
+    deduplication: DeduplicationStats;
+    batching: BatchStats;
+    window: WindowStats;
+    timestamp: number;
+}
+/**
+ * Aggregation configuration options.
+ */
+export interface AggregationConfig {
+    /** Enable aggregation (default: false) */
+    enabled: boolean;
+    /** Window size in milliseconds (default: 200) */
+    windowMs?: number;
+    /** Batch size threshold (default: 50) */
+    batchSize?: number;
+    /** Deduplication strategy */
+    deduplication?: 'pattern' | 'idempotencyKey' | 'off';
+    /** Deduplication pattern (string or function) */
+    pattern?: string | ((args: unknown) => string);
+    /** Merge priority when deduplicating */
+    mergePriority?: 'highest' | 'earliest' | 'latest';
+    /** Enable background cleanup (default: true) */
+    enableCleanup?: boolean;
+    /** Cleanup interval (ms, default: 5 minutes) */
+    cleanupIntervalMs?: number;
+    /** TTL for deduplication entries (ms, default: 10 minutes) */
+    ttlMs?: number;
+}
+/**
+ * Default aggregation configuration.
+ */
+export declare const DEFAULT_AGGREGATION_CONFIG: Required<AggregationConfig>;
+/**
+ * Priority order for merge decisions.
+ */
+export declare const PRIORITY_ORDER: Record<string, number>;
+/**
+ * Backpressure-aware window configuration.
+ */
+export interface WindowAdjustmentConfig {
+    /** Window for NORMAL backpressure state */
+    normalMs: number;
+    /** Window for WARNING backpressure state */
+    warningMs: number;
+    /** Window for CRITICAL backpressure state */
+    criticalMs: number;
+    /** Window for OVERFLOW backpressure state */
+    overflowMs: number;
+}
+/**
+ * Default window adjustment configuration based on backpressure.
+ */
+export declare const DEFAULT_WINDOW_ADJUSTMENT: WindowAdjustmentConfig;
+/**
+ * Get suggested window size based on backpressure state.
+ */
+export declare function getSuggestedWindow(state: BackpressureState, config?: WindowAdjustmentConfig): number;

package/dist/core/src/events/index.d.ts

@@ -2,13 +2,25 @@
  * Event system exports for async event dispatch.
  * @packageDocumentation
  */
-export type { CircuitBreakerOptions } from './CircuitBreaker';
-export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
-export type { DLQEntry, DLQFilter } from './DeadLetterQueue';
-export { DeadLetterQueue } from './DeadLetterQueue';
 export * from './EventBackend';
 export type { EventOptions } from './EventOptions';
 export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
-export { EventPriorityQueue } from './EventPriorityQueue';
-export * from './observability';
 export type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';
+export type { BackpressureConfig, BackpressureDecision, BackpressureMetricsSnapshot, } from './BackpressureManager';
+export { BackpressureManager, BackpressureState } from './BackpressureManager';
+export type { CircuitBreakerMetrics, CircuitBreakerMetricsRecorder, CircuitBreakerOptions, } from './CircuitBreaker';
+export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
+export type { DLQEntry, DLQEntryCallback, DLQEntrySource, DLQFilter } from './DeadLetterQueue';
+export { DeadLetterQueue } from './DeadLetterQueue';
+export { EventPriorityQueue } from './EventPriorityQueue';
+export * from './FlowControlStrategy';
+export { IdempotencyCache } from './IdempotencyCache';
+export { MessageQueueBridge } from './MessageQueueBridge';
+export type { PriorityStatistics } from './PriorityEscalationManager';
+export { PriorityEscalationManager } from './PriorityEscalationManager';
+export type { RetrySchedulerConfig } from './RetryScheduler';
+export { RetryScheduler } from './RetryScheduler';
+export type { DeadLetterDecision, MultiPriorityQueueDepth, WindowAdjustment } from './types';
+export { WorkerPool } from './WorkerPool';
+export type { WorkerPoolConfig, WorkerPoolStats, WorkerStats } from './WorkerPoolConfig';
+export { WorkerPoolMetrics } from './WorkerPoolMetrics';

package/dist/core/src/events/observability/OTelEventMetrics.d.ts

@@ -18,6 +18,7 @@ import type { CircuitBreakerMetricsRecorder } from '../CircuitBreaker';
  * Returns the current queue depths for each priority level.
  */
 export type QueueDepthCallback = () => {
+    critical: number;
     high: number;
     normal: number;
     low: number;
@@ -72,6 +73,16 @@ export declare class OTelEventMetrics implements CircuitBreakerMetricsRecorder {
     private readonly cbSuccessesCounter;
     private readonly cbTransitionsCounter;
     private readonly cbOpenDurationHistogram;
+    private readonly backpressureRejectionsCounter;
+    private readonly backpressureStateGauge;
+    private readonly backpressureDegradationsCounter;
+    private backpressureStateValue;
+    private readonly dlqEntriesCounter;
+    private readonly dlqDepthGauge;
+    private readonly dlqRequeueCounter;
+    private readonly retryAttemptsCounter;
+    private dlqDepthCallback?;
+    private readonly priorityEscalationCounter;
     private queueDepthCallback?;
     private circuitBreakerStateCallbacks;
     private recordedCircuitBreakerStates;
@@ -237,4 +248,85 @@ export declare class OTelEventMetrics implements CircuitBreakerMetricsRecorder {
      * Clear all circuit breaker state callbacks.
      */
     clearCircuitBreakerCallbacks(): void;
+    /**
+     * Record a backpressure rejection event.
+     *
+     * @param eventName - Event name
+     * @param priority - Event priority
+     * @param reason - Rejection reason
+     */
+    recordBackpressureRejection(eventName: string, priority: string, reason: string): void;
+    /**
+     * Record a backpressure state change event.
+     *
+     * @param state - New backpressure state (NORMAL, WARNING, CRITICAL, OVERFLOW)
+     */
+    recordBackpressureState(state: string): void;
+    /**
+     * Record a backpressure degradation event.
+     *
+     * @param eventName - Event name
+     * @param fromPriority - Original priority
+     * @param toPriority - Degraded priority
+     */
+    recordBackpressureDegradation(eventName: string, fromPriority: string, toPriority: string): void;
+    /**
+     * Record an event added to Dead Letter Queue.
+     *
+     * @param eventName - Event name
+     * @param source - Source of DLQ entry (retry_exhausted, circuit_breaker, backpressure_overflow)
+     */
+    recordDLQEntry(eventName: string, source: string): void;
+    /**
+     * Set the callback for DLQ depth observable gauge.
+     *
+     * @param callback - Function returning current DLQ depth
+     */
+    setDLQDepthCallback(callback: () => number): void;
+    /**
+     * Record a DLQ requeue attempt.
+     *
+     * @param eventName - Event name
+     * @param result - Result of requeue (success or failure)
+     */
+    recordDLQRequeue(eventName: string, result: 'success' | 'failure'): void;
+    /**
+     * Record an event retry attempt.
+     *
+     * @param eventName - Event name
+     * @param attemptNumber - Attempt number
+     */
+    recordRetryAttempt(eventName: string, attemptNumber: number): void;
+    /**
+     * Record a priority escalation event.
+     *
+     * @param eventName - Event name
+     * @param fromPriority - Original priority
+     * @param toPriority - Escalated priority
+     */
+    recordPriorityEscalation(eventName: string, fromPriority: string, toPriority: string): void;
+    /**
+     * Record event deduplication (FS-102).
+     *
+     * @param eventName - Event name
+     * @param deduplicatedCount - Number of events after deduplication
+     * @param totalCount - Total number of events before deduplication
+     */
+    recordDeduplication(eventName: string, deduplicatedCount: number, totalCount: number): void;
+    /**
+     * Record batch submission (FS-102).
+     *
+     * @param eventName - Event name
+     * @param batchSize - Size of submitted batch
+     * @param windowMs - Aggregation window size
+     */
+    recordBatch(eventName: string, batchSize: number, windowMs: number): void;
+    /**
+     * Record window adjustment (FS-102).
+     *
+     * @param oldWindowMs - Previous window size
+     * @param newWindowMs - New window size
+     * @param reason - Adjustment reason
+     */
+    recordWindowAdjustment(oldWindowMs: number, newWindowMs: number, reason: string): void;
 }

package/dist/core/src/events/observability/StreamWorkerMetrics.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Worker Pool Metrics Recorder for OpenTelemetry integration.
+ *
+ * Tracks Worker Pool statistics and emits OpenTelemetry metrics.
+ *
+ * @internal
+ */
+import type { Meter } from '@opentelemetry/api';
+/**
+ * Worker job status for metrics.
+ */
+export declare enum WorkerJobStatus {
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+/**
+ * Stream Worker Metrics Recorder.
+ *
+ * Collects and records metrics related to Worker Pool execution:
+ * - Pool size and utilization
+ * - Job execution duration
+ * - Job success/failure counts
+ * - Queue depth
+ */
+export declare class StreamWorkerMetrics {
+    private meter;
+    private jobDurationHistogram?;
+    private jobCounterCompleted?;
+    constructor(meter: Meter);
+    /**
+     * Initialize OpenTelemetry metrics.
+     */
+    private initializeMetrics;
+    /**
+     * Record job execution duration.
+     *
+     * @param durationSeconds - Duration in seconds
+     * @param status - Job status (completed or failed)
+     * @param queue - Queue name
+     */
+    recordJobDuration(durationSeconds: number, status: WorkerJobStatus, queue?: string): void;
+    /**
+     * Record pool size change.
+     *
+     * @param poolSize - Current pool size
+     * @param callback - Optional callback to fetch pool size dynamically
+     */
+    setPoolSizeProvider(callback: () => number): void;
+    private poolSizeCallback?;
+    /**
+     * Get current pool size.
+     */
+    getPoolSize(): number;
+    /**
+     * Record queue depth change.
+     *
+     * @param depth - Current queue depth
+     * @param callback - Optional callback to fetch queue depth dynamically
+     */
+    setQueueDepthProvider(callback: () => number): void;
+    private queueDepthCallback?;
+    /**
+     * Get current queue depth.
+     */
+    getQueueDepth(): number;
+}
+/**
+ * Worker Metrics Recorder interface for dependency injection.
+ */
+export interface WorkerMetricsRecorder {
+    recordJobDuration(durationSeconds: number, status: WorkerJobStatus, queue?: string): void;
+    setPoolSizeProvider(callback: () => number): void;
+    setQueueDepthProvider(callback: () => number): void;
+    getPoolSize(): number;
+    getQueueDepth(): number;
+}

package/dist/core/src/events/observability/index.d.ts

@@ -18,3 +18,7 @@ export { type ObservabilityConfig, ObservableHookManager } from './ObservableHoo
  * @public
  */
 export { OTelEventMetrics, type QueueDepthCallback } from './OTelEventMetrics';
+/**
+ * @public
+ */
+export { StreamWorkerMetrics, WorkerJobStatus, type WorkerMetricsRecorder, } from './StreamWorkerMetrics';

package/dist/core/src/events/queue-core.d.ts

@@ -0,0 +1,77 @@
+import { BackpressureManager } from './BackpressureManager';
+import type { DeadLetterQueue } from './DeadLetterQueue';
+import type { OTelEventMetrics } from './observability/OTelEventMetrics';
+import { type PriorityStatistics } from './PriorityEscalationManager';
+import type { BackpressureStrategy, EventQueueConfig, EventTask, MultiPriorityQueueDepth } from './types';
+/**
+ * Result of an enqueue operation.
+ *
+ * - `{ status: 'queued', id }` - Task successfully queued
+ * - `{ status: 'dropped' }` - Task dropped due to backpressure
+ * - `{ status: 'delayed', id, delayMs }` - Task should be re-enqueued after delayMs
+ *
+ * @internal
+ */
+export type EnqueueResult = {
+    status: 'queued';
+    id: string;
+} | {
+    status: 'dropped';
+} | {
+    status: 'delayed';
+    id: string;
+    delayMs: number;
+};
+/**
+ * Priority queue core: manages event task queues and backpressure.
+ *
+ * Handles enqueueing, dequeuing, backpressure logic, and priority escalation.
+ * This class is used internally by EventPriorityQueue as a composition target.
+ *
+ * @internal
+ */
+export declare class QueueCore {
+    criticalPriority: EventTask[];
+    highPriority: EventTask[];
+    normalPriority: EventTask[];
+    lowPriority: EventTask[];
+    processingPartitions: Set<string>;
+    private taskIdCounter;
+    private dlq?;
+    private otelEventMetrics?;
+    private backpressureManager?;
+    private priorityStats?;
+    private config;
+    constructor(config?: EventQueueConfig);
+    setDeadLetterQueue(dlq: DeadLetterQueue): void;
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    setPriorityStatistics(stats: PriorityStatistics): void;
+    getPriorityStatistics(): PriorityStatistics | undefined;
+    getBackpressureManager(): BackpressureManager | undefined;
+    getConfig(): EventQueueConfig;
+    getDLQ(): DeadLetterQueue | undefined;
+    createTaskId(): string;
+    /**
+     * Enqueue a task into the appropriate priority queue.
+     * Applies priority escalation and backpressure logic.
+     */
+    enqueue(task: EventTask): EnqueueResult;
+    /**
+     * Dequeue the next task based on priority and partition ordering.
+     * Priority order: CRITICAL > HIGH > NORMAL > LOW
+     */
+    dequeue(): EventTask | undefined;
+    /**
+     * Re-enqueue a task for retry.
+     */
+    enqueueRetry(task: EventTask): void;
+    getDepth(): number;
+    getDepthByPriority(priority: 'critical' | 'high' | 'normal' | 'low'): number;
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    clear(): void;
+    syncBackpressure(): void;
+    private handleBackpressure;
+    private dropOldest;
+    private dequeueFromPriority;
+}
+export type { BackpressureStrategy, EventQueueConfig, EventTask };

package/dist/core/src/events/task-executor.d.ts

@@ -0,0 +1,51 @@
+import type { Span } from '@opentelemetry/api';
+import { CircuitBreaker } from './CircuitBreaker';
+import type { DeadLetterQueue } from './DeadLetterQueue';
+import type { EventOptions } from './EventOptions';
+import type { EventMetrics } from './observability/EventMetrics';
+import type { EventTracing } from './observability/EventTracing';
+import type { OTelEventMetrics } from './observability/OTelEventMetrics';
+import type { RetryScheduler } from './RetryScheduler';
+import type { EventTask } from './types';
+/**
+ * Executes event tasks with circuit breaker protection, retry logic,
+ * exponential backoff, DLQ integration, and distributed tracing.
+ *
+ * @internal
+ */
+export declare class TaskExecutor {
+    private eventCircuitBreakers;
+    private eventMetrics?;
+    private otelEventMetrics?;
+    private eventTracing?;
+    private currentDispatchSpan?;
+    private retryScheduler?;
+    private dlq?;
+    private persistentDLQHandler?;
+    private enqueueRetryFn?;
+    setDeadLetterQueue(dlq: DeadLetterQueue): void;
+    setPersistentDLQHandler(handler: (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number) => Promise<void>): void;
+    setEventMetrics(metrics: EventMetrics): void;
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    setEventTracing(tracing: EventTracing): void;
+    setCurrentDispatchSpan(span: Span | undefined): void;
+    getCurrentDispatchSpan(): Span | undefined;
+    setRetryScheduler(scheduler: RetryScheduler): void;
+    getRetryScheduler(): RetryScheduler | undefined;
+    /**
+     * Set the callback to use when re-enqueueing a task after a retry delay.
+     */
+    setEnqueueRetryFn(fn: (task: EventTask) => void): void;
+    getCircuitBreaker(hook: string): CircuitBreaker | undefined;
+    getCircuitBreakers(): Map<string, CircuitBreaker>;
+    resetCircuitBreaker(hook: string): boolean;
+    /**
+     * Execute an event task by running all its callbacks.
+     * Implements circuit breaker protection, retry logic, and DLQ integration.
+     */
+    executeTask(task: EventTask, processingPartitions: Set<string>): Promise<void>;
+    private sendToDLQ;
+    private getOrCreateEventCircuitBreaker;
+    private calculateRetryDelay;
+    private executeWithTimeout;
+}