@gravito/ripple 4.0.1 → 5.0.0

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

@@ -1,182 +0,0 @@
-/**
- * @gravito/core - OpenTelemetry 類型定義
- *
- * 定義 OpenTelemetry SDK 集成所需的類型與介面。
- */
-/**
- * Tracing（追蹤）導出器類型
- */
-export type TracingExporter = 'jaeger' | 'otlp' | 'console' | 'none';
-/**
- * Metrics（指標）導出器類型
- */
-export type MetricsExporter = 'prometheus' | 'otlp' | 'console' | 'none';
-/**
- * Tracing 配置選項
- */
-export interface TracingConfig {
-    /** 是否啟用追蹤（預設：true） */
-    enabled?: boolean;
-    /** 導出器類型（預設：otlp） */
-    exporter?: TracingExporter;
-    /** Jaeger HTTP 端點（使用 jaeger 導出器時） */
-    jaegerEndpoint?: string;
-    /** OTLP 端點（使用 otlp 導出器時） */
-    otlpEndpoint?: string;
-    /** 採樣率（0-1，預設：1.0 = 100%） */
-    samplingRate?: number;
-    /** 是否啟用自動儀器化（預設：false） */
-    autoInstrumentation?: boolean;
-    /** Batch Span Processor 配置 */
-    batchConfig?: {
-        /** 最大批次大小（預設：512） */
-        maxExportBatchSize?: number;
-        /** 導出間隔（毫秒，預設：5000） */
-        scheduledDelayMillis?: number;
-        /** 導出超時（毫秒，預設：30000） */
-        exportTimeoutMillis?: number;
-        /** 最大隊列大小（預設：2048） */
-        maxQueueSize?: number;
-    };
-}
-/**
- * Metrics 配置選項
- */
-export interface MetricsConfig {
-    /** 是否啟用指標（預設：true） */
-    enabled?: boolean;
-    /** 導出器類型（預設：otlp） */
-    exporter?: MetricsExporter;
-    /** Prometheus 端口（使用 prometheus 導出器時，預設：9090） */
-    prometheusPort?: number;
-    /** Prometheus 端點路徑（預設：/metrics） */
-    prometheusEndpoint?: string;
-    /** OTLP 端點（使用 otlp 導出器時） */
-    otlpEndpoint?: string;
-    /** 導出間隔（毫秒，預設：60000） */
-    exportIntervalMillis?: number;
-}
-/**
- * OpenTelemetry SDK 完整配置
- */
-export interface OpenTelemetryConfig {
-    /** 是否啟用 OpenTelemetry（預設：true） */
-    enabled?: boolean;
-    /** 服務名稱（預設：gravito-app） */
-    serviceName?: string;
-    /** 服務版本（預設：1.0.0） */
-    serviceVersion?: string;
-    /** 環境名稱（預設：development） */
-    environment?: 'development' | 'staging' | 'production' | string;
-    /** 自定義 Resource Attributes */
-    resourceAttributes?: Record<string, string | number | boolean>;
-    /** Tracing 配置 */
-    tracing?: TracingConfig;
-    /** Metrics 配置 */
-    metrics?: MetricsConfig;
-    /** 是否在控制台輸出初始化日誌（預設：true） */
-    logInitialization?: boolean;
-}
-/**
- * OpenTelemetry SDK 實例包裝
- *
- * 封裝初始化後的 SDK 實例與相關資源。
- */
-export interface OpenTelemetrySDK {
-    /** SDK 是否已啟動 */
-    isStarted: boolean;
-    /** SDK 是否已關閉 */
-    isShutdown: boolean;
-    /** 服務名稱 */
-    serviceName: string;
-    /** 服務版本 */
-    serviceVersion: string;
-    /** Tracer Provider（如果啟用追蹤） */
-    tracerProvider: unknown | null;
-    /** Meter Provider（如果啟用指標） */
-    meterProvider: unknown | null;
-    /** 原始配置 */
-    config: OpenTelemetryConfig;
-    /** 關閉 SDK */
-    shutdown: () => Promise<void>;
-}
-/**
- * 支援的 OpenTelemetry 環境變數
- *
- * 參考：https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
- */
-export declare const OTEL_ENV_VARS: {
-    /** 服務名稱 */
-    readonly SERVICE_NAME: "OTEL_SERVICE_NAME";
-    /** 服務版本 */
-    readonly SERVICE_VERSION: "OTEL_SERVICE_VERSION";
-    /** 環境名稱 */
-    readonly DEPLOYMENT_ENVIRONMENT: "OTEL_DEPLOYMENT_ENVIRONMENT";
-    /** Resource Attributes */
-    readonly RESOURCE_ATTRIBUTES: "OTEL_RESOURCE_ATTRIBUTES";
-    /** OTLP 端點（通用） */
-    readonly OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
-    /** OTLP Traces 端點 */
-    readonly OTLP_TRACES_ENDPOINT: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
-    /** OTLP Metrics 端點 */
-    readonly OTLP_METRICS_ENDPOINT: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
-    /** 採樣器類型 */
-    readonly TRACES_SAMPLER: "OTEL_TRACES_SAMPLER";
-    /** 採樣率參數 */
-    readonly TRACES_SAMPLER_ARG: "OTEL_TRACES_SAMPLER_ARG";
-    /** 是否啟用 OpenTelemetry */
-    readonly GRAVITO_ENABLED: "GRAVITO_OTEL_ENABLED";
-    /** Jaeger 端點 */
-    readonly JAEGER_ENDPOINT: "JAEGER_ENDPOINT";
-    /** Prometheus 端口 */
-    readonly PROMETHEUS_PORT: "PROMETHEUS_PORT";
-};
-/**
- * 完整的 BatchConfig 類型（所有屬性必填）
- */
-export interface BatchConfigRequired {
-    maxExportBatchSize: number;
-    scheduledDelayMillis: number;
-    exportTimeoutMillis: number;
-    maxQueueSize: number;
-}
-/**
- * 完整的 TracingConfig 類型（所有屬性必填）
- */
-export interface TracingConfigRequired {
-    enabled: boolean;
-    exporter: TracingExporter;
-    jaegerEndpoint: string;
-    otlpEndpoint: string;
-    samplingRate: number;
-    autoInstrumentation: boolean;
-    batchConfig: BatchConfigRequired;
-}
-/**
- * 完整的 MetricsConfig 類型（所有屬性必填）
- */
-export interface MetricsConfigRequired {
-    enabled: boolean;
-    exporter: MetricsExporter;
-    prometheusPort: number;
-    prometheusEndpoint: string;
-    otlpEndpoint: string;
-    exportIntervalMillis: number;
-}
-/**
- * 完整的 OpenTelemetryConfig 類型（所有屬性必填）
- */
-export interface OpenTelemetryConfigRequired {
-    enabled: boolean;
-    serviceName: string;
-    serviceVersion: string;
-    environment: 'development' | 'staging' | 'production';
-    resourceAttributes: Record<string, string | number | boolean>;
-    tracing: TracingConfigRequired;
-    metrics: MetricsConfigRequired;
-    logInitialization: boolean;
-}
-/**
- * 預設配置值
- */
-export declare const DEFAULT_CONFIG: OpenTelemetryConfigRequired;

package/dist/core/src/observability/Metrics.d.ts

@@ -1,244 +0,0 @@
-/**
- * @gravito/core - Prometheus Metrics Setup
- *
- * 設置和導出 Prometheus 指標，用於性能監控。
- */
-/**
- * Prometheus 指標配置
- */
-export interface PrometheusMetricsConfig {
-    /** Prometheus 抓取端口 */
-    port?: number;
-    /** 指標前綴 */
-    prefix?: string;
-    /** 上報間隔（毫秒） */
-    interval?: number;
-    /** 是否啟用默認指標（如內存、CPU） */
-    defaultMetrics?: boolean;
-}
-/**
- * Prometheus 指標導出器
- *
- * 將 Gravito 事件系統的指標導出到 Prometheus
- *
- * @example
- * ```typescript
- * import { setupPrometheusMetrics } from '@gravito/core/observability'
- *
- * const exporter = await setupPrometheusMetrics({
- *   port: 9090,
- *   prefix: 'gravito_event_'
- * })
- * ```
- *
- * @public
- */
-export declare function setupPrometheusMetrics(config?: PrometheusMetricsConfig): Promise<{
-    port: number;
-    endpoint: string;
-} | null>;
-/**
- * 事件系統指標定義
- *
- * 這些指標用於監控事件派發系統的性能和可靠性。
- *
- * @public
- */
-export interface EventMetricsDefinition {
-    /** 事件派發延遲（直方圖） */
-    dispatchLatency: {
-        name: string;
-        help: string;
-        labels: string[];
-        buckets: number[];
-    };
-    /** 監聽器執行時間（直方圖） */
-    listenerExecutionTime: {
-        name: string;
-        help: string;
-        labels: string[];
-        buckets: number[];
-    };
-    /** 隊列深度（量表） */
-    queueDepth: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 失敗計數（計數器） */
-    failureRate: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 超時計數（計數器） */
-    timeoutCount: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 吞吐量（計數器） */
-    throughput: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 熔斷器狀態（量表） */
-    circuitBreakerState: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 熔斷器狀態轉換（計數器） */
-    circuitBreakerTransitions: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 熔斷器失敗計數（計數器） */
-    circuitBreakerFailures: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 熔斷器成功計數（計數器） */
-    circuitBreakerSuccesses: {
-        name: string;
-        help: string;
-        labels: string[];
-    };
-    /** 熔斷器 OPEN 持續時間（直方圖） */
-    circuitBreakerOpenDuration: {
-        name: string;
-        help: string;
-        labels: string[];
-        buckets: number[];
-    };
-}
-/**
- * 獲取事件系統的標準指標定義
- *
- * @param prefix - 指標名稱前綴（默認：gravito_event_）
- * @returns 指標定義對象
- *
- * @example
- * ```typescript
- * import { getEventMetricsDefinition } from '@gravito/core/observability'
- *
- * const metrics = getEventMetricsDefinition('gravito_event_')
- * console.log(metrics.dispatchLatency.name)  // gravito_event_dispatch_latency_seconds
- * ```
- *
- * @public
- */
-export declare function getEventMetricsDefinition(prefix?: string): EventMetricsDefinition;
-/**
- * Prometheus 查詢範例
- *
- * 提供常用的 Prometheus 查詢語句，用於監控事件系統
- *
- * @public
- */
-export declare const PROMETHEUS_QUERIES: {
-    /** 事件派發延遲 P95 */
-    dispatchLatencyP95: string;
-    /** 事件派發延遲 P99 */
-    dispatchLatencyP99: string;
-    /** 隊列深度（按優先級） */
-    queueDepthByPriority: string;
-    /** 吞吐量（事件/秒） */
-    throughput: string;
-    /** 失敗率 */
-    failureRate: string;
-    /** 監聽器執行時間 P99 */
-    listenerLatencyP99: string;
-    /** 超時次數 */
-    timeoutCount: string;
-    /** 吞吐量異常檢測 */
-    throughputAnomaly: string;
-    /** 熔斷器狀態（0=CLOSED, 1=HALF_OPEN, 2=OPEN） */
-    circuitBreakerState: string;
-    /** 熔斷器開啟率 */
-    circuitBreakerOpenRate: string;
-    /** 熔斷器恢復率 */
-    circuitBreakerRecoveryRate: string;
-    /** 熔斷器失敗率 */
-    circuitBreakerFailureRate: string;
-    /** 熔斷器 OPEN 持續時間 P95 */
-    circuitBreakerOpenDurationP95: string;
-    /** 熔斷器 OPEN 持續時間 P99 */
-    circuitBreakerOpenDurationP99: string;
-};
-/**
- * Prometheus 告警規則
- *
- * 提供預定義的告警規則，用於監控事件系統的健康狀況
- *
- * @public
- */
-export declare const PROMETHEUS_ALERT_RULES: {
-    /** P99 延遲過高 */
-    HighDispatchLatency: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 隊列深度過高 */
-    HighQueueDepth: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 失敗率過高 */
-    HighFailureRate: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 監聽器執行時間過長 */
-    SlowListener: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 吞吐量異常下降 */
-    ThroughputDrop: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 熔斷器持續開啟 */
-    CircuitBreakerOpen: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 熔斷器頻繁切換 */
-    CircuitBreakerFlapping: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-    /** 熔斷器故障率過高 */
-    CircuitBreakerHighFailureRate: {
-        expr: string;
-        for: string;
-        severity: string;
-        summary: string;
-        description: string;
-    };
-};

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

@@ -1,89 +0,0 @@
-/**
- * @gravito/photon - High-performance web engine for the Gravito Galaxy Architecture.
- *
- * Photon serves as the foundational HTTP layer for Gravito, providing an ultra-fast,
- * type-safe routing system based on Hono. It is designed to be the "light" that
- * connects Satellites (domain plugins) and Orbits (infrastructure) within the ecosystem.
- *
- * Key features:
- * - Zero-overhead routing and middleware.
- * - Full TypeScript inference for request parameters and body.
- * - Built-in support for HTMX and binary (CBOR) protocols.
- *
- * @example
- * ```typescript
- * import { Photon } from '@gravito/photon'
- *
- * const app = new Photon()
- *
- * app.get('/welcome', (c) => c.text('Welcome to the Galaxy!'))
- *
- * export default app
- * ```
- * @packageDocumentation
- */
-export * from 'hono';
-/**
- * The primary application class for Photon.
- *
- * An alias for `Hono`, providing the core routing and middleware capabilities.
- * Use this to define your API structure and mount domain-specific Satellites.
- *
- * @remarks
- * Photon extends Hono's capabilities with Gravito-specific optimizations.
- * It serves as the entry point for defining routes, applying middleware,
- * and handling the request-response lifecycle.
- *
- * @example
- * ```typescript
- * const app = new Photon()
- *
- * // Basic routing
- * app.get('/api/health', (c) => c.json({ status: 'ok' }))
- *
- * // Middleware integration
- * app.use('/api/*', myMiddleware)
- *
- * // Mounting sub-routers
- * app.route('/v1', v1Router)
- * ```
- * @public
- */
-export { Hono as Photon } from 'hono';
-/**
- * Binary-related middleware for Photon.
- *
- * Provides utilities for handling binary data formats like CBOR,
- * optimizing payload size and serialization speed for high-performance APIs.
- *
- * @public
- */
-export * from './middleware/binary';
-/**
- * HTMX-related middleware for Photon.
- *
- * Enhances Photon with first-class support for HTMX, including
- * automatic request detection and simplified header access for hypermedia-driven UIs.
- *
- * @public
- */
-export * from './middleware/htmx';
-/**
- * Rate limiting middleware for Photon.
- *
- * Provides built-in rate limiting with token bucket and sliding window strategies.
- * Supports both memory-based and custom storage backends.
- *
- * @public
- */
-export * from './middleware/ratelimit';
-/**
- * Redis-based rate limiting storage.
- * @public
- */
-export * from './middleware/ratelimit-redis';
-/**
- * OpenAPI utilities
- * @public
- */
-export * from './openapi';

package/dist/photon/src/middleware/binary.d.ts

@@ -1,31 +0,0 @@
-import type { MiddlewareHandler } from 'hono';
-/**
- * Binary Middleware for Photon.
- *
- * Automatically detects 'Accept: application/cbor' and encodes
- * JSON responses using the CBOR binary format for high-performance communication.
- *
- * @remarks
- * This middleware is essential for high-frequency API calls where payload size
- * and serialization speed are critical. It leverages the `cborg` library for
- * efficient binary encoding.
- *
- * @returns A Hono middleware handler that intercepts JSON responses.
- *
- * @example
- * ```typescript
- * import { Photon } from '@gravito/photon'
- * import { binaryMiddleware } from '@gravito/photon/middleware/binary'
- *
- * const app = new Photon()
- * app.use(binaryMiddleware())
- *
- * app.get('/api/data', (c) => c.json({ items: [1, 2, 3] }))
- * ```
- *
- * @performance
- * - CBOR encoding is ~2-3x faster than JSON.stringify for large objects.
- * - Binary format reduces payload size by 20-40% on average.
- * - Optimized to read body directly without clone(), saving ~30% overhead.
- */
-export declare const binaryMiddleware: () => MiddlewareHandler;

package/dist/photon/src/middleware/htmx.d.ts

@@ -1,39 +0,0 @@
-import type { MiddlewareHandler } from 'hono';
-/**
- * HTMX Middleware for Photon.
- *
- * Automatically detects HTMX requests and populates the context with
- * HTMX-specific headers and state.
- *
- * @remarks
- * This middleware enables hypermedia-driven UIs by providing first-class
- * support for HTMX. It allows handlers to easily distinguish between
- * full-page loads and partial updates.
- *
- * @returns A Hono middleware handler that populates HTMX context variables.
- *
- * @example
- * ```typescript
- * import { Photon } from '@gravito/photon'
- * import { htmxMiddleware } from '@gravito/photon/middleware/htmx'
- *
- * const app = new Photon()
- * app.use(htmxMiddleware())
- *
- * app.get('/search', async (c) => {
- *   // Check if request is from HTMX
- *   if (c.get('htmx')) {
- *     return c.html('<div>Search results...</div>')
- *   }
- *
- *   return c.html('<html>...</html>')
- * })
- * ```
- *
- * @context_variables
- * - `htmx`: Boolean indicating if the request is an HTMX request.
- * - `htmx.boosted`: Boolean indicating if the request was boosted.
- * - `htmx.target`: The ID of the target element.
- * - `htmx.trigger`: The ID of the trigger element.
- */
-export declare const htmxMiddleware: () => MiddlewareHandler;

package/dist/photon/src/middleware/ratelimit-redis.d.ts

@@ -1,50 +0,0 @@
-import type { RateLimitState, RateLimitStore } from './ratelimit';
-/**
- * Redis-based storage for Rate Limiting.
- *
- * Implements atomic rate limiting using Lua scripts to prevent race conditions
- * in distributed environments.
- *
- * @remarks
- * This store is recommended for production environments with multiple application
- * instances. It requires a Redis client (like ioredis or node-redis).
- *
- * @example
- * ```typescript
- * import Redis from 'ioredis'
- * import { rateLimit } from '@gravito/photon/middleware'
- * import { RedisStore } from '@gravito/photon/middleware/ratelimit-redis'
- *
- * const redis = new Redis()
- * const app = new Photon()
- *
- * app.use(rateLimit({
- *   maxRequests: 100,
- *   windowMs: 60000,
- *   store: new RedisStore(redis, { maxRequests: 100, windowMs: 60000 })
- * }))
- * ```
- * @public
- */
-export declare class RedisStore implements RateLimitStore {
-    private client;
-    private config;
-    /**
-     * Create a new RedisStore.
-     *
-     * @param client - Redis client instance (must support .eval())
-     * @param config - Rate limit configuration
-     */
-    constructor(client: any, config: {
-        maxRequests: number;
-        windowMs: number;
-        prefix?: string;
-    });
-    private get prefix();
-    /**
-     * Atomic increment and TTL management using Lua.
-     */
-    increment(key: string): Promise<RateLimitState>;
-    reset(key: string): Promise<void>;
-    get(key: string): Promise<RateLimitState | null>;
-}