@gravito/ripple 4.0.0 → 4.0.1

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,6 +2,8 @@
  * Event system exports for async event dispatch.
  * @packageDocumentation
  */
+export type { BackpressureConfig, BackpressureDecision, BackpressureMetricsSnapshot, } from './BackpressureManager';
+export { BackpressureManager, BackpressureState } from './BackpressureManager';
 export type { CircuitBreakerOptions } from './CircuitBreaker';
 export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
 export type { DLQEntry, DLQFilter } from './DeadLetterQueue';
@@ -10,5 +12,14 @@ export * from './EventBackend';
 export type { EventOptions } from './EventOptions';
 export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
 export { EventPriorityQueue } from './EventPriorityQueue';
+export type { FlowControlContext, FlowControlStrategy } from './FlowControlStrategy';
+export { CompositeStrategy, createDefaultStrategies, PriorityRebalanceStrategy, QueueDepthStrategy, RateLimitStrategy, StarvationProtectionStrategy, } from './FlowControlStrategy';
+export type { EventStatus, MessageQueueBridgeConfig } from './MessageQueueBridge';
+export { MessageQueueBridge } from './MessageQueueBridge';
 export * from './observability';
+export type { QueueStats, RetrySchedulerConfig } from './RetryScheduler';
+export { RetryScheduler } from './RetryScheduler';
 export type { BackpressureStrategy, EventQueueConfig, EventTask } 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/types.d.ts

@@ -1,4 +1,5 @@
 import type { ActionCallback } from '../HookManager';
+import type { BackpressureConfig } from './BackpressureManager';
 import type { EventOptions } from './EventOptions';
 /**
  * Event task for priority queue processing.
@@ -29,6 +30,12 @@ export interface EventTask {
      * Timestamp when the event was created.
      */
     createdAt: number;
+    /**
+     * Timestamp when the event was enqueued (added to the queue).
+     * Used for priority escalation calculations.
+     * @internal
+     */
+    enqueuedAt: number;
     /**
      * Partition key for ordering (if applicable).
      */
@@ -72,4 +79,56 @@ export interface EventQueueConfig {
      * @default 'reject'
      */
     strategy?: BackpressureStrategy;
+    /**
+     * Advanced backpressure management configuration.
+     * When enabled, provides state-based flow control with multi-strategy support.
+     * If not provided, falls back to simple strategy-based backpressure.
+     * @default undefined (disabled, uses simple strategy)
+     */
+    backpressure?: BackpressureConfig;
+}
+/**
+ * Multi-priority queue depth snapshot (FS-103)
+ * Represents the current queue depth for each priority level.
+ * @internal
+ */
+export interface MultiPriorityQueueDepth {
+    /** Queue depth for CRITICAL priority events */
+    critical: number;
+    /** Queue depth for HIGH priority events */
+    high: number;
+    /** Queue depth for NORMAL priority events */
+    normal: number;
+    /** Queue depth for LOW priority events */
+    low: number;
+    /** Total queue depth across all priorities */
+    total: number;
+}
+/**
+ * Window adjustment record for backpressure feedback (FS-103)
+ * Records when and why the aggregation window was adjusted.
+ * @internal
+ */
+export interface WindowAdjustment {
+    /** Timestamp of the adjustment */
+    timestamp: number;
+    /** Previous window size in milliseconds */
+    from: number;
+    /** New window size in milliseconds */
+    to: number;
+    /** Backpressure state that triggered the adjustment */
+    reason: string;
+}
+/**
+ * Dead letter queue routing decision (FS-103)
+ * Determines whether an event should be routed to the DLQ.
+ * @internal
+ */
+export interface DeadLetterDecision {
+    /** Whether the event should be routed to DLQ */
+    shouldRoute: boolean;
+    /** Reason for the decision (if applicable) */
+    reason?: string;
+    /** Suggested retry strategy */
+    retryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
 }

package/dist/core/src/health/HealthProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview HealthProvider - Cloud-native health checks
+ *
+ * Provides liveness and readiness probes for Kubernetes and cloud deployments
+ *
+ * @module @gravito/core/health
+ * @since 2.2.0
+ */
+import type { Container } from '../Container';
+import type { PlanetCore } from '../PlanetCore';
+import { ServiceProvider } from '../ServiceProvider';
+/**
+ * Health check result
+ * @public
+ */
+export interface HealthCheckResult {
+    /** Health status */
+    status: 'healthy' | 'unhealthy';
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Health check function interface
+ * @public
+ */
+export interface HealthCheck {
+    /** Unique name for this check */
+    name: string;
+    /** Check function that returns health status */
+    check(): Promise<HealthCheckResult>;
+}
+/**
+ * HealthProvider - Provides /health/liveness and /health/readiness endpoints
+ *
+ * - Liveness: Always returns 200 OK (just checks if server is running)
+ * - Readiness: Returns 200 if all checks are healthy, 503 otherwise
+ *
+ * @public
+ */
+export declare class HealthProvider extends ServiceProvider {
+    private checks;
+    register(container: Container): void;
+    /**
+     * Register a health check
+     *
+     * @param check - The health check to register
+     *
+     * @example
+     * ```typescript
+     * const health = core.container.make<HealthProvider>('health')
+     * health.registerCheck({
+     *   name: 'database',
+     *   check: async () => {
+     *     try {
+     *       await db.ping()
+     *       return { status: 'healthy' }
+     *     } catch {
+     *       return { status: 'unhealthy', message: 'DB unreachable' }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    registerCheck(check: HealthCheck): void;
+    boot(core: PlanetCore): void;
+}
+export default HealthProvider;