@gravito/core 1.6.1 → 2.0.1

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

@@ -0,0 +1,332 @@
+/**
+ * @gravito/core - OpenTelemetry Event Metrics
+ *
+ * Provides event system metrics using OpenTelemetry API directly.
+ * This enables Prometheus export without requiring @gravito/monitor dependency.
+ *
+ * Metrics:
+ * - gravito_event_dispatch_duration_seconds (Histogram)
+ * - gravito_event_listener_duration_seconds (Histogram)
+ * - gravito_event_queue_depth (Observable Gauge)
+ *
+ * @packageDocumentation
+ */
+import type { Meter } from '@opentelemetry/api';
+import type { CircuitBreakerMetricsRecorder } from '../CircuitBreaker';
+/**
+ * Queue depth callback type.
+ * Returns the current queue depths for each priority level.
+ */
+export type QueueDepthCallback = () => {
+    critical: number;
+    high: number;
+    normal: number;
+    low: number;
+};
+/**
+ * Circuit breaker state callback type.
+ * Returns the current state of a circuit breaker.
+ */
+export type CircuitBreakerStateCallback = () => {
+    eventName: string;
+    listenerIndex: number;
+    state: 0 | 1 | 2;
+};
+/**
+ * OpenTelemetry-based Event Metrics collector.
+ *
+ * Uses OpenTelemetry API directly for metrics collection, enabling
+ * Prometheus export through the OpenTelemetry SDK.
+ *
+ * @example
+ * ```typescript
+ * import { metrics } from '@opentelemetry/api'
+ * import { OTelEventMetrics } from '@gravito/core'
+ *
+ * const meter = metrics.getMeter('@gravito/core', '1.0.0')
+ * const eventMetrics = new OTelEventMetrics(meter)
+ *
+ * // Record dispatch duration
+ * eventMetrics.recordDispatchDuration('order:created', 'high', 0.123)
+ *
+ * // Record listener duration
+ * eventMetrics.recordListenerDuration('order:created', 0, 0.456)
+ *
+ * // Set queue depth callback
+ * eventMetrics.setQueueDepthCallback(() => ({
+ *   high: 10,
+ *   normal: 50,
+ *   low: 100
+ * }))
+ * ```
+ *
+ * @public
+ */
+export declare class OTelEventMetrics implements CircuitBreakerMetricsRecorder {
+    private readonly meter;
+    private readonly prefix;
+    private readonly dispatchDurationHistogram;
+    private readonly listenerDurationHistogram;
+    private readonly queueDepthGauge;
+    private readonly cbStateGauge;
+    private readonly cbFailuresCounter;
+    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;
+    /**
+     * Bucket boundaries for dispatch duration histogram.
+     */
+    private readonly dispatchDurationBuckets;
+    /**
+     * Bucket boundaries for listener duration histogram.
+     */
+    private readonly listenerDurationBuckets;
+    /**
+     * Bucket boundaries for circuit breaker open duration histogram.
+     */
+    private readonly cbOpenDurationBuckets;
+    /**
+     * Create a new OTelEventMetrics instance.
+     *
+     * @param meter - OpenTelemetry Meter instance
+     * @param prefix - Metric name prefix (default: 'gravito_event_')
+     */
+    constructor(meter: Meter, prefix?: string);
+    /**
+     * Record event dispatch duration.
+     *
+     * @param eventName - Name of the event
+     * @param priority - Priority level (high, normal, low)
+     * @param durationSeconds - Duration in seconds
+     */
+    recordDispatchDuration(eventName: string, priority: string, durationSeconds: number): void;
+    /**
+     * Record listener execution duration.
+     *
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener in the callback list
+     * @param durationSeconds - Duration in seconds
+     */
+    recordListenerDuration(eventName: string, listenerIndex: number, durationSeconds: number): void;
+    /**
+     * Set the callback for queue depth observable gauge.
+     *
+     * The callback will be invoked when metrics are collected,
+     * allowing real-time reporting of queue depths.
+     *
+     * @param callback - Function returning current queue depths
+     */
+    setQueueDepthCallback(callback: QueueDepthCallback): void;
+    /**
+     * Register a circuit breaker state callback for monitoring.
+     *
+     * @param key - Unique identifier for the circuit breaker (e.g., "order:created-0")
+     * @param callback - Function returning current circuit breaker state
+     */
+    registerCircuitBreakerStateCallback(key: string, callback: CircuitBreakerStateCallback): void;
+    /**
+     * Unregister a circuit breaker state callback.
+     *
+     * @param key - Unique identifier for the circuit breaker
+     */
+    unregisterCircuitBreakerStateCallback(key: string): void;
+    /**
+     * Record circuit breaker state change.
+     *
+     * @param name - Name of the circuit breaker (usually event name)
+     * @param state - State as number (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
+     */
+    recordState(name: string, state: number): void;
+    /**
+     * Record circuit breaker state transition.
+     *
+     * @param name - Name of the circuit breaker
+     * @param fromState - Previous state
+     * @param toState - New state
+     */
+    recordTransition(name: string, fromState: string, toState: string): void;
+    /**
+     * Record circuit breaker failure.
+     *
+     * @param name - Name of the circuit breaker
+     */
+    recordFailure(name: string): void;
+    /**
+     * Record circuit breaker success.
+     *
+     * @param name - Name of the circuit breaker
+     */
+    recordSuccess(name: string): void;
+    /**
+     * Record circuit breaker open duration.
+     *
+     * @param name - Name of the circuit breaker
+     * @param seconds - Duration in seconds
+     */
+    recordOpenDuration(name: string, seconds: number): void;
+    /**
+     * Record circuit breaker failure.
+     *
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener
+     */
+    recordCircuitBreakerFailure(eventName: string, listenerIndex: number): void;
+    /**
+     * Record circuit breaker success.
+     *
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener
+     */
+    recordCircuitBreakerSuccess(eventName: string, listenerIndex: number): void;
+    /**
+     * Record circuit breaker state transition.
+     *
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener
+     * @param fromState - Previous state (CLOSED, HALF_OPEN, OPEN)
+     * @param toState - New state (CLOSED, HALF_OPEN, OPEN)
+     */
+    recordCircuitBreakerTransition(eventName: string, listenerIndex: number, fromState: string, toState: string): void;
+    /**
+     * Record circuit breaker open duration.
+     *
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener
+     * @param durationSeconds - Duration in seconds
+     */
+    recordCircuitBreakerOpenDuration(eventName: string, listenerIndex: number, durationSeconds: number): void;
+    /**
+     * Get the bucket boundaries for dispatch duration histogram.
+     *
+     * @returns Array of bucket boundaries in seconds
+     */
+    getDispatchDurationBuckets(): number[];
+    /**
+     * Get the bucket boundaries for listener duration histogram.
+     *
+     * @returns Array of bucket boundaries in seconds
+     */
+    getListenerDurationBuckets(): number[];
+    /**
+     * Get the OpenTelemetry Meter instance.
+     *
+     * @returns Meter instance
+     */
+    getMeter(): Meter;
+    /**
+     * Get the metric name prefix.
+     *
+     * @returns Metric name prefix
+     */
+    getPrefix(): string;
+    /**
+     * Get the bucket boundaries for circuit breaker open duration histogram.
+     *
+     * @returns Array of bucket boundaries in seconds
+     */
+    getCircuitBreakerOpenDurationBuckets(): number[];
+    /**
+     * Get all registered circuit breaker state callback keys.
+     *
+     * @returns Array of registered keys
+     */
+    getRegisteredCircuitBreakers(): string[];
+    /**
+     * 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/events/observability/ObservableHookManager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @gravito/core - Observable Hook Manager
+ *
+ * Wraps HookManager with observability support (metrics and tracing).
+ */
+import { HookManager, type HookManagerConfig } from '../../HookManager';
+import type { EventOptions } from '../EventOptions';
+import { EventMetrics } from './EventMetrics';
+import { EventTracer } from './EventTracer';
+import { EventTracing } from './EventTracing';
+/**
+ * Configuration for observability features.
+ * @public
+ */
+export interface ObservabilityConfig {
+    /**
+     * Enable observability features.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * MetricsRegistry instance from @gravito/monitor.
+     * Required if metrics collection is enabled.
+     */
+    metrics?: any;
+    /**
+     * Enable OpenTelemetry distributed tracing.
+     * @default false
+     */
+    tracing?: boolean;
+    /**
+     * Prefix for metric names.
+     * @default 'gravito_event_'
+     */
+    metricsPrefix?: string;
+}
+/**
+ * Observable Hook Manager - extends HookManager with observability.
+ *
+ * Provides metrics and distributed tracing for event dispatch and listener execution.
+ * Maintains 100% backward compatibility with HookManager.
+ *
+ * @public
+ */
+export declare class ObservableHookManager extends HookManager {
+    private eventMetrics?;
+    private eventTracer?;
+    private eventTracing?;
+    private obsConfig;
+    /**
+     * Create a new ObservableHookManager instance.
+     *
+     * @param config - HookManager configuration
+     * @param obsConfig - Observability configuration
+     */
+    constructor(config?: HookManagerConfig, obsConfig?: ObservabilityConfig);
+    /**
+     * Run all registered actions asynchronously via priority queue with observability.
+     *
+     * This override adds metrics and tracing to the base implementation.
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     * @param options - Event options for async dispatch.
+     */
+    doActionAsync<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
+    /**
+     * Run all registered actions synchronously with observability.
+     *
+     * This override adds metrics and tracing to the base implementation.
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     */
+    doActionSync<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+    /**
+     * Get the EventMetrics instance.
+     *
+     * @returns EventMetrics instance if observability is enabled, undefined otherwise
+     */
+    getMetrics(): EventMetrics | undefined;
+    /**
+     * Get the EventTracer instance.
+     *
+     * @returns EventTracer instance if tracing is enabled, undefined otherwise
+     */
+    getTracer(): EventTracer | undefined;
+    /**
+     * Update observability configuration at runtime.
+     *
+     * @param config - New observability configuration
+     */
+    setObservabilityConfig(config: Partial<ObservabilityConfig>): void;
+    /**
+     * Get the EventTracing instance.
+     *
+     * @returns EventTracing instance if tracing is enabled, undefined otherwise
+     */
+    getEventTracing(): EventTracing | undefined;
+    /**
+     * Get current observability configuration.
+     *
+     * @returns Current observability configuration
+     */
+    getObservabilityConfig(): ObservabilityConfig;
+}

package/dist/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/events/observability/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @public
+ */
+export { EventMetrics } from './EventMetrics';
+/**
+ * @public
+ */
+export { EventTracer } from './EventTracer';
+/**
+ * @public
+ */
+export { EventTracing, type EventTracingConfig, getEventTracing } from './EventTracing';
+/**
+ * @public
+ */
+export { type ObservabilityConfig, ObservableHookManager } from './ObservableHookManager';
+/**
+ * @public
+ */
+export { OTelEventMetrics, type QueueDepthCallback } from './OTelEventMetrics';
+/**
+ * @public
+ */
+export { StreamWorkerMetrics, WorkerJobStatus, type WorkerMetricsRecorder, } from './StreamWorkerMetrics';

package/dist/events/observability/metrics-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal metric types for event observability.
+ * Avoids importing @gravito/monitor from core to prevent circular dependency.
+ * Runtime implementations are provided by @gravito/monitor MetricsRegistry.
+ *
+ * @internal
+ */
+export interface EventMetricCounter {
+    inc(labels: Record<string, string>): void;
+}
+export interface EventMetricGauge {
+    set(value: number, labels: Record<string, string>): void;
+}
+export interface EventMetricHistogram {
+    observe(value: number, labels: Record<string, string>): void;
+}

package/dist/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/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;
+    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;
+}