@gravito/echo 3.0.1 → 3.1.0

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

@@ -0,0 +1,240 @@
+/**
+ * @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 = () => {
+    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 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;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @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';

package/dist/core/src/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/core/src/events/types.d.ts

@@ -0,0 +1,75 @@
+import type { ActionCallback } from '../HookManager';
+import type { EventOptions } from './EventOptions';
+/**
+ * Event task for priority queue processing.
+ * @internal
+ */
+export interface EventTask {
+    /**
+     * Unique identifier for this event task.
+     */
+    id: string;
+    /**
+     * Event hook name.
+     */
+    hook: string;
+    /**
+     * Event payload/arguments.
+     */
+    args: unknown;
+    /**
+     * Event options.
+     */
+    options: EventOptions;
+    /**
+     * Callbacks to execute for this event.
+     */
+    callbacks: ActionCallback[];
+    /**
+     * Timestamp when the event was created.
+     */
+    createdAt: number;
+    /**
+     * Partition key for ordering (if applicable).
+     */
+    partitionKey?: string;
+    /**
+     * Number of retry attempts made.
+     * @internal
+     */
+    retryCount?: number;
+    /**
+     * Timestamp when the event first failed.
+     * @internal
+     */
+    firstFailedAt?: number;
+    /**
+     * Last error encountered.
+     * @internal
+     */
+    lastError?: Error;
+}
+/**
+ * Strategy for handling backpressure when the queue is full.
+ */
+export type BackpressureStrategy = 'reject' | 'drop-oldest' | 'drop-newest' | 'ignore';
+/**
+ * Configuration for the event priority queue.
+ */
+export interface EventQueueConfig {
+    /**
+     * Maximum number of pending events in the queue.
+     * If exceeded, the backpressure strategy is applied.
+     * @default undefined (unbounded)
+     */
+    maxSize?: number;
+    /**
+     * Strategy to use when the queue is full.
+     * - 'reject': Throw an error (default)
+     * - 'drop-oldest': Drop the oldest lowest-priority event
+     * - 'drop-newest': Drop the incoming event
+     * - 'ignore': Silently drop the incoming event
+     * @default 'reject'
+     */
+    strategy?: BackpressureStrategy;
+}

package/dist/core/src/exceptions/CircularDependencyException.d.ts

@@ -0,0 +1,9 @@
+import type { ServiceKey } from '../Container';
+/**
+ * CircularDependencyException - Thrown when the container detects an infinite loop.
+ *
+ * @module @gravito/core
+ */
+export declare class CircularDependencyException extends Error {
+    constructor(key: ServiceKey, stack: ServiceKey[]);
+}

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

@@ -1,5 +1,6 @@
 export * from './AuthenticationException';
 export * from './AuthorizationException';
+export * from './CircularDependencyException';
 export * from './GravitoException';
 export * from './HttpException';
 export * from './ModelNotFoundException';

package/dist/core/src/http/cookie.d.ts

@@ -0,0 +1,29 @@
+import { type CookieOptions } from './CookieJar';
+import type { GravitoContext } from './types';
+/**
+ * Get a cookie value from the request
+ * @param c - Context object
+ * @param name - Cookie name
+ * @returns Cookie value or undefined
+ * @public
+ */
+export declare function getCookie(c: GravitoContext, name: string): string | undefined;
+/**
+ * Set a cookie in the response
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @public
+ */
+export declare function setCookie(c: GravitoContext, name: string, value: string, options?: CookieOptions & {
+    maxAge?: number;
+}): void;
+/**
+ * Delete a cookie (expire it)
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param options - Cookie options (path, domain, etc.)
+ * @public
+ */
+export declare function deleteCookie(c: GravitoContext, name: string, options?: CookieOptions): void;

package/dist/core/src/http/types.d.ts

@@ -57,6 +57,13 @@ export interface GravitoVariables {
      * Cookie jar for managing response cookies
      */
     cookieJar?: unknown;
+    /**
+     * Middleware scope tracking for Orbit isolation
+     * Tracks which Orbit/scope this request belongs to
+     * Used to prevent cross-Orbit middleware contamination
+     * @since 2.3.0
+     */
+    middlewareScope?: string;
     /** @deprecated Use ctx.route() instead */
     route?: unknown;
     [key: string]: unknown;
@@ -85,6 +92,20 @@ export interface GravitoRequest {
     readonly method: string;
     /** Request path without query string */
     readonly path: string;
+    /**
+     * Route pattern (e.g., /users/:id) for the matched route
+     *
+     * This provides the parameterized route pattern instead of the concrete path,
+     * which is critical for preventing high cardinality issues in metrics systems.
+     *
+     * @example
+     * ```typescript
+     * // For request: GET /users/123
+     * ctx.req.path          // => "/users/123"
+     * ctx.req.routePattern  // => "/users/:id"
+     * ```
+     */
+    readonly routePattern?: string;
     /**
      * Get a route parameter value
      * @param name - Parameter name (e.g., 'id' for route '/users/:id')

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

@@ -17,29 +17,39 @@ export type { AdapterConfig, AdapterFactory, HttpAdapter, RouteDefinition } from
 export { isHttpAdapter } from './adapters/types';
 export type { ContentfulStatusCode, GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNext, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, StatusCode, ValidationTarget, } from './http/types';
 export { Application, type ApplicationConfig } from './Application';
+export { type CommandHandler, CommandKernel } from './CommandKernel';
 export { ConfigManager } from './ConfigManager';
-export { Container, type Factory } from './Container';
+export { Container, type Factory, type ServiceKey, type ServiceMap } from './Container';
 export { codeFromStatus, ErrorHandler, type ErrorHandlerDeps, messageFromStatus, } from './ErrorHandler';
 export { EventManager } from './EventManager';
+export type { CircuitBreakerOptions, DLQEntry, DLQFilter, EventBackend, EventOptions, EventTask, } from './events';
+export { CircuitBreaker, CircuitBreakerState, DEFAULT_EVENT_OPTIONS, DeadLetterQueue, EventPriorityQueue, } from './events';
+export type { EventTracingConfig, ObservabilityConfig, QueueDepthCallback, } from './events/observability';
+export { EventMetrics, EventTracer, EventTracing, getEventTracing, ObservableHookManager, OTelEventMetrics, } from './events/observability';
 export * from './exceptions';
 export { type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, type RegisterGlobalErrorHandlersOptions, registerGlobalErrorHandlers, } from './GlobalErrorHandlers';
 export { type GravitoManifest, GravitoServer } from './GravitoServer';
-export type { ActionCallback, FilterCallback } from './HookManager';
-export { HookManager } from './HookManager';
+export type { ActionCallback, FilterCallback, ListenerInfo, ListenerOptions } from './HookManager';
+export { HookManager, type HookManagerConfig } from './HookManager';
 export * from './helpers';
 export { CookieJar, type CookieOptions } from './http/CookieJar';
+export { deleteCookie, getCookie, setCookie } from './http/cookie';
 export { type BodySizeLimitOptions, bodySizeLimit } from './http/middleware/BodySizeLimit';
 export { type CorsOptions, type CorsOrigin, cors } from './http/middleware/Cors';
 export { type CsrfOptions, csrfProtection, getCsrfToken } from './http/middleware/Csrf';
 export { createHeaderGate, type HeaderTokenGateOptions, type RequireHeaderTokenOptions, requireHeaderToken, } from './http/middleware/HeaderTokenGate';
 export { type HstsOptions, type SecurityHeadersOptions, securityHeaders, } from './http/middleware/SecurityHeaders';
 export { ThrottleRequests } from './http/middleware/ThrottleRequests';
+export * as instrumentation from './instrumentation';
+export { DEFAULT_CONFIG as OTEL_DEFAULT_CONFIG, getMeter, getOpenTelemetrySDK, getTracer as getOtelTracer, isOpenTelemetryInitialized, type MetricsConfig as OtelMetricsConfig, type MetricsExporter, type OpenTelemetryConfig, type OpenTelemetrySDK, OTEL_ENV_VARS, resetOpenTelemetry, setupOpenTelemetry, shutdownOpenTelemetry, type TracingConfig as OtelTracingConfig, type TracingExporter, } from './instrumentation';
 export type { Listener, ShouldQueue } from './Listener';
 export type { Logger } from './Logger';
 export { ConsoleLogger } from './Logger';
 export { type CacheService, type ErrorHandlerContext, type GravitoConfig, type GravitoOrbit, PlanetCore, type ViewService, } from './PlanetCore';
 export { Route } from './Route';
 export { type ControllerClass, FORM_REQUEST_SYMBOL, type FormRequestClass, type FormRequestLike, RouteGroup, type RouteHandler, type RouteOptions, Router, } from './Router';
+export type { DLQManagerFilter, DLQRecord, DLQStats, RetryPolicy } from './reliability';
+export { DeadLetterQueueManager, getDefaultRetryPolicy, getPresetRetryPolicy, RetryEngine, } from './reliability';
 export { ServiceProvider } from './ServiceProvider';
 export { Encrypter, type EncrypterOptions } from './security/Encrypter';
 export type { Channel, ShouldBroadcast } from './types/events';

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

@@ -0,0 +1,35 @@
+/**
+ * @gravito/core - Instrumentation Module
+ *
+ * 提供 OpenTelemetry SDK 集成功能，包括分佈式追蹤與指標收集。
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   setupOpenTelemetry,
+ *   getOpenTelemetrySDK,
+ *   getTracer,
+ *   getMeter
+ * } from '@gravito/core'
+ *
+ * // 初始化 SDK
+ * await setupOpenTelemetry({
+ *   serviceName: 'my-service',
+ *   tracing: { enabled: true, exporter: 'jaeger' },
+ *   metrics: { enabled: true, exporter: 'prometheus' }
+ * })
+ *
+ * // 獲取 Tracer
+ * const tracer = await getTracer('my-module')
+ * const span = tracer.startSpan('my-operation')
+ *
+ * // 獲取 Meter
+ * const meter = await getMeter('my-module')
+ * const counter = meter.createCounter('request_count')
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { getMeter, getOpenTelemetrySDK, getTracer, isOpenTelemetryInitialized, resetOpenTelemetry, setupOpenTelemetry, shutdownOpenTelemetry, } from './opentelemetry';
+export type { MetricsConfig, MetricsExporter, OpenTelemetryConfig, OpenTelemetrySDK, TracingConfig, TracingExporter, } from './types';
+export { DEFAULT_CONFIG, OTEL_ENV_VARS } from './types';