@gravito/core 1.6.0 → 2.0.0

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;
+}

package/dist/events/types.d.ts

@@ -0,0 +1,134 @@
+import type { ActionCallback } from '../HookManager';
+import type { BackpressureConfig } from './BackpressureManager';
+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;
+    /**
+     * Timestamp when the event was enqueued (added to the queue).
+     * Used for priority escalation calculations.
+     * @internal
+     */
+    enqueuedAt: 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;
+    /**
+     * 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/exceptions/AuthenticationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when authentication fails.
+ * @public
+ */
+export declare class AuthenticationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/exceptions/AuthorizationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when user is not authorized to perform an action.
+ * @public
+ */
+export declare class AuthorizationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/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/exceptions/GravitoException.d.ts

@@ -0,0 +1,23 @@
+import type { ContentfulStatusCode } from '../http/types';
+/**
+ * Options for creating a GravitoException
+ * @public
+ */
+export interface ExceptionOptions {
+    message?: string;
+    cause?: unknown;
+    i18nKey?: string;
+    i18nParams?: Record<string, string | number>;
+}
+/**
+ * Base exception class for consistent error handling.
+ * @public
+ */
+export declare abstract class GravitoException extends Error {
+    readonly status: ContentfulStatusCode;
+    readonly code: string;
+    readonly i18nKey?: string;
+    readonly i18nParams?: Record<string, string | number>;
+    constructor(status: number, code: string, options?: ExceptionOptions);
+    getLocalizedMessage(t: (key: string, params?: Record<string, string | number>) => string): string;
+}

package/dist/exceptions/HttpException.d.ts

@@ -0,0 +1,9 @@
+import type { ContentfulStatusCode } from '../http/types';
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Generic HTTP Exception
+ * @public
+ */
+export declare class HttpException extends GravitoException {
+    constructor(status: ContentfulStatusCode, options?: ExceptionOptions);
+}

package/dist/exceptions/ModelNotFoundException.d.ts

@@ -0,0 +1,10 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when a database model is not found.
+ * @public
+ */
+export declare class ModelNotFoundException extends GravitoException {
+    readonly model: string;
+    readonly id?: string | number;
+    constructor(model: string, id?: string | number);
+}

package/dist/exceptions/ValidationException.d.ts

@@ -0,0 +1,22 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Structure of a validation error
+ * @public
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Exception thrown when data validation fails.
+ * @public
+ */
+export declare class ValidationException extends GravitoException {
+    readonly errors: ValidationError[];
+    redirectTo?: string;
+    input?: unknown;
+    constructor(errors: ValidationError[], message?: string);
+    withRedirect(url: string): this;
+    withInput(input: unknown): this;
+}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,7 @@
+export * from './AuthenticationException';
+export * from './AuthorizationException';
+export * from './CircularDependencyException';
+export * from './GravitoException';
+export * from './HttpException';
+export * from './ModelNotFoundException';
+export * from './ValidationException';

package/dist/ffi/NativeAccelerator.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 原生加速器統一入口
+ * 遵循 Galaxy Architecture 的運行時自適應模式
+ * 與 RuntimeAdapter 模式保持一致
+ */
+import type { CborAccelerator, NativeAcceleratorStatus } from './types';
+/**
+ * 原生加速器類別
+ * 提供運行時自適應的 CBOR 編碼/解碼加速
+ * - 在 Bun 環境下優先使用 C 編譯器實現（bun:ffi）
+ * - 在非 Bun 環境或 FFI 不可用時自動降級到 JavaScript 實現
+ */
+export declare class NativeAccelerator {
+    private static readonly DEBUG_ENV;
+    private static readonly DISABLE_ENV;
+    /**
+     * FFI 可用性緩存
+     * null: 未檢測, true: 可用, false: 不可用
+     */
+    private static available;
+    /**
+     * 當前加速器實例緩存
+     */
+    private static cborAccelerator;
+    /**
+     * 當前狀態
+     */
+    private static status;
+    /**
+     * 檢測原生 FFI 是否可用
+     * 偵測邏輯：
+     * 1. 檢查 GRAVITO_FFI_DISABLE 環境變數
+     * 2. 檢查 Bun 運行時可用性
+     * 3. 檢查 bun:ffi 的 cc() 是否可用
+     */
+    static isAvailable(): boolean;
+    /**
+     * 取得 CBOR 加速器實例
+     * 優先使用 Native，失敗則降級到 Fallback
+     */
+    static getCborAccelerator(): CborAccelerator;
+    /**
+     * 取得加速器狀態
+     */
+    static getStatus(): NativeAcceleratorStatus;
+    /**
+     * 重置加速器狀態（用於測試）
+     */
+    static reset(): void;
+    /**
+     * 解析 C 原始碼路徑
+     * 支援從原始碼目錄或 npm 套件的 src/ffi/native 目錄載入
+     */
+    private static resolveCSourcePath;
+    /**
+     * 載入原生 C 實現
+     * 使用 bun:ffi 的 cc() 動態編譯 C 代碼
+     * 優先從檔案載入完整實現，避免內聯限制
+     */
+    private static loadNativeImplementation;
+    /**
+     * 檢查是否啟用調試模式
+     */
+    private static isDebugEnabled;
+    /**
+     * 更新狀態
+     */
+    private static updateStatus;
+}