@gravito/echo 3.1.0 → 3.1.1

package/dist/monitor/src/health/HealthRegistry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @gravito/monitor - Health Check Registry
+ *
+ * Manages health check registrations and executions
+ */
+import type { HealthCheckFn, HealthCheckResult, HealthConfig } from '../config';
+/**
+ * Aggregated health check report.
+ * @public
+ */
+export interface HealthReport {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    timestamp: string;
+    uptime: number;
+    checks: Record<string, HealthCheckResult & {
+        name: string;
+    }>;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+/**
+ * HealthRegistry manages all health checks
+ */
+export declare class HealthRegistry {
+    private checks;
+    private startTime;
+    private cachedReport;
+    private cacheExpiry;
+    private timeout;
+    private cacheTtl;
+    private cacheHits;
+    private cacheMisses;
+    constructor(config?: HealthConfig);
+    /**
+     * Register a health check
+     */
+    register(name: string, check: HealthCheckFn): this;
+    /**
+     * Unregister a health check
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get all registered check names
+     */
+    getCheckNames(): string[];
+    /**
+     * Execute a single health check with timeout
+     */
+    private executeCheck;
+    /**
+     * Execute all health checks and generate report
+     */
+    check(): Promise<HealthReport>;
+    /**
+     * Simple liveness check (is the process running?)
+     */
+    liveness(): Promise<{
+        status: 'healthy' | 'unhealthy';
+    }>;
+    /**
+     * Readiness check (is the app ready to serve traffic?)
+     * By default, requires all checks to be healthy
+     */
+    readiness(): Promise<{
+        status: 'healthy' | 'unhealthy';
+        reason?: string;
+    }>;
+    /**
+     * Get cache statistics
+     *
+     * Useful for monitoring cache effectiveness and tuning cacheTtl
+     */
+    getCacheStats(): CacheStats;
+}

package/dist/monitor/src/health/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @gravito/monitor - Built-in Health Checks
+ */
+import type { HealthCheckFn } from '../config';
+export type { CacheStats, HealthReport } from './HealthRegistry';
+/**
+ * Create a database health check
+ */
+export declare function createDatabaseCheck(connectionFn: () => Promise<boolean> | boolean): HealthCheckFn;
+/**
+ * Create a Redis health check
+ */
+export declare function createRedisCheck(pingFn: () => Promise<string> | string): HealthCheckFn;
+/**
+ * Create a memory usage health check
+ */
+export declare function createMemoryCheck(options?: {
+    maxHeapUsedPercent?: number;
+}): HealthCheckFn;
+/**
+ * Create a custom HTTP endpoint health check
+ */
+export declare function createHttpCheck(url: string, options?: {
+    timeout?: number;
+    expectedStatus?: number;
+    method?: string;
+}): HealthCheckFn;
+/**
+ * Create a disk space health check
+ */
+export declare function createDiskCheck(options?: {
+    path?: string;
+    minFreePercent?: number;
+}): HealthCheckFn;
+export { HealthController } from './HealthController';
+export { HealthRegistry } from './HealthRegistry';

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

@@ -0,0 +1,13 @@
+/**
+ * @gravito/monitor
+ *
+ * Observability module for Gravito
+ * - Health Checks (Kubernetes probes)
+ * - Metrics (Prometheus format)
+ * - Tracing (OpenTelemetry OTLP)
+ */
+export { defineMonitorConfig, type HealthCheckFn, type HealthCheckResult, type HealthConfig, type MetricOptions, type MetricsConfig, type MonitorConfig, type TracingConfig, } from './config';
+export { createDatabaseCheck, createDiskCheck, createHttpCheck, createMemoryCheck, createRedisCheck, HealthController, HealthRegistry, type HealthReport, } from './health';
+export { MonitorOrbit, type MonitorService } from './MonitorOrbit';
+export { Counter, createHttpMetricsMiddleware, Gauge, Histogram, MetricsController, MetricsRegistry, } from './metrics';
+export { createTracingMiddleware, type Span, type SpanContext, type SpanEvent, TracingManager, } from './tracing';

package/dist/monitor/src/metrics/MetricsController.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @gravito/monitor - Metrics Controller
+ */
+import type { GravitoContext } from '@gravito/core';
+import type { MetricsRegistry } from './MetricsRegistry';
+/**
+ * MetricsController handles the /metrics endpoint
+ */
+export declare class MetricsController {
+    private registry;
+    constructor(registry: MetricsRegistry);
+    /**
+     * GET /metrics - Prometheus metrics endpoint
+     */
+    metrics(_c: GravitoContext): Promise<Response>;
+    /**
+     * 更新 health cache metrics
+     *
+     * 從 HealthRegistry 讀取最新的 cache 統計並更新 gauges
+     */
+    private updateHealthCacheMetrics;
+}

package/dist/monitor/src/metrics/MetricsRegistry.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @gravito/monitor - Metrics Registry
+ *
+ * Manages metric collection and Prometheus exposition
+ */
+import type { MetricOptions, MetricsConfig } from '../config';
+/**
+ * Represents a single metric data point with labels.
+ * @public
+ */
+export interface MetricValue {
+    value: number;
+    labels: Record<string, string>;
+    timestamp?: number;
+}
+/**
+ * Counter metric - monotonically increasing value
+ */
+export declare class Counter {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    /**
+     * Increment the counter
+     */
+    inc(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Get current values
+     */
+    getValues(): MetricValue[];
+    /**
+     * Reset all values
+     */
+    reset(): void;
+    private labelsToKey;
+    private keyToLabels;
+}
+/**
+ * Gauge metric - value that can go up or down
+ */
+export declare class Gauge {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    /**
+     * Set the gauge value
+     */
+    set(value: number, labels?: Record<string, string>): void;
+    /**
+     * Increment the gauge
+     */
+    inc(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Decrement the gauge
+     */
+    dec(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Get current values
+     */
+    getValues(): MetricValue[];
+    private labelsToKey;
+    private keyToLabels;
+}
+/**
+ * Histogram metric - tracks distribution of values
+ */
+export declare class Histogram {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private bucketCounts;
+    private sums;
+    private counts;
+    readonly buckets: number[];
+    constructor(name: string, help: string, labelNames?: string[], buckets?: number[]);
+    /**
+     * Observe a value
+     */
+    observe(value: number, labels?: Record<string, string>): void;
+    /**
+     * Start a timer and return a function to stop it
+     */
+    startTimer(labels?: Record<string, string>): () => void;
+    /**
+     * Get values for Prometheus format
+     */
+    getValues(): {
+        buckets: Map<string, Map<number, number>>;
+        sums: Map<string, number>;
+        counts: Map<string, number>;
+    };
+    private labelsToKey;
+}
+/**
+ * MetricsRegistry manages all metrics
+ */
+export declare class MetricsRegistry {
+    private counters;
+    private gauges;
+    private histograms;
+    private startTime;
+    private prefix;
+    private defaultLabels;
+    private collectDefaultMetrics;
+    constructor(config?: MetricsConfig);
+    /**
+     * Create or get a counter
+     */
+    counter(options: MetricOptions): Counter;
+    /**
+     * Create or get a gauge
+     */
+    gauge(options: MetricOptions): Gauge;
+    /**
+     * Create or get a histogram
+     */
+    histogram(options: MetricOptions): Histogram;
+    /**
+     * Initialize default runtime metrics
+     */
+    private initDefaultMetrics;
+    /**
+     * Update default metrics with current values
+     */
+    private updateDefaultMetrics;
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheus(): string;
+    private formatLabels;
+    private keyToLabels;
+}

package/dist/monitor/src/metrics/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @gravito/monitor - HTTP Metrics Middleware
+ */
+import type { GravitoContext } from '@gravito/core';
+import type { MetricsRegistry } from './MetricsRegistry';
+/**
+ * Create middleware that collects HTTP metrics
+ */
+export declare function createHttpMetricsMiddleware(registry: MetricsRegistry): (c: GravitoContext, next: () => Promise<void>) => Promise<Response | undefined>;
+export { MetricsController } from './MetricsController';
+export { Counter, Gauge, Histogram, MetricsRegistry } from './MetricsRegistry';

package/dist/monitor/src/tracing/TracingManager.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @gravito/monitor - Tracing Manager
+ *
+ * OpenTelemetry OTLP tracing integration
+ */
+import type { TracingConfig } from '../config';
+/**
+ * Span interface for tracing
+ */
+export interface Span {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    startTime: number;
+    endTime?: number;
+    attributes: Record<string, string | number | boolean>;
+    status: 'ok' | 'error' | 'unset';
+    events: SpanEvent[];
+}
+/**
+ * Event recorded within a span.
+ * @public
+ */
+export interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Span context for propagation
+ */
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/**
+ * TracingManager handles distributed tracing
+ */
+export declare class TracingManager {
+    private otelSdk;
+    private spans;
+    private isInitialized;
+    private serviceName;
+    private serviceVersion;
+    private endpoint;
+    private resourceAttributes;
+    constructor(config?: TracingConfig);
+    /**
+     * Initialize OpenTelemetry SDK if available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown tracing
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Start a new span
+     */
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+        parentSpan?: Span;
+    }): Span;
+    /**
+     * End a span
+     */
+    endSpan(span: Span, status?: 'ok' | 'error'): void;
+    /**
+     * Add an event to a span
+     */
+    addEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Set span attribute
+     */
+    setAttribute(span: Span, key: string, value: string | number | boolean): void;
+    /**
+     * Get the currently active span
+     */
+    getActiveSpan(): Span | null;
+    /**
+     * Extract trace context from headers
+     */
+    extractContext(headers: Headers): SpanContext | null;
+    /**
+     * Inject trace context into headers
+     */
+    injectContext(headers: Headers, span: Span): void;
+    /**
+     * Get all collected spans (for debugging)
+     */
+    getSpans(): Span[];
+    /**
+     * Clear collected spans
+     */
+    clearSpans(): void;
+}

package/dist/monitor/src/tracing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @gravito/monitor - Tracing Middleware
+ */
+import type { GravitoContext } from '@gravito/core';
+import type { TracingManager } from './TracingManager';
+/**
+ * Create middleware that traces HTTP requests
+ */
+export declare function createTracingMiddleware(tracer: TracingManager): (c: GravitoContext, next: () => Promise<void>) => Promise<Response | undefined>;
+export { type Span, type SpanContext, type SpanEvent, TracingManager } from './TracingManager';

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

@@ -77,6 +77,11 @@ export * from './middleware/htmx';
  * @public
  */
 export * from './middleware/ratelimit';
+/**
+ * Redis-based rate limiting storage.
+ * @public
+ */
+export * from './middleware/ratelimit-redis';
 /**
  * OpenAPI utilities
  * @public

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

@@ -0,0 +1,50 @@
+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>;
+}

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

@@ -88,11 +88,15 @@ export interface RateLimitState {
 export declare class MemoryStore implements RateLimitStore {
     private config;
     private store;
+    private head?;
+    private tail?;
     private cleanupInterval;
     constructor(config: {
         maxRequests: number;
         windowMs: number;
     }, cleanupIntervalMs?: number);
+    private addNode;
+    private removeNode;
     increment(key: string): Promise<RateLimitState>;
     reset(key: string): Promise<void>;
     get(key: string): Promise<RateLimitState | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/echo",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Enterprise-grade webhook handling for Gravito. Secure receiving and reliable sending.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -43,7 +43,7 @@
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",
   "peerDependencies": {
-    "@gravito/core": "workspace:*"
+    "@gravito/core": "^1.6.1"
   },
   "devDependencies": {
     "bun-types": "latest",