@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/observability/correlation.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Observability & Monitoring - Request Correlation IDs across Services
+ *
+ * Enterprise-grade request correlation for distributed systems tracing
+ */
+import type { EnhancedRequest } from '../types';
+export interface CorrelationConfig {
+    headerName?: string;
+    generateId?: () => string;
+    propagateHeaders?: string[];
+    enableLogging?: boolean;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    maxIdLength?: number;
+    validateId?: (id: string) => boolean;
+}
+export interface CorrelationContext {
+    correlationId: string;
+    parentId?: string;
+    spanId?: string;
+    traceId?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    metadata: Record<string, any>;
+    startTime: number;
+    headers: Record<string, string>;
+}
+export interface ServiceCall {
+    serviceName: string;
+    method: string;
+    url: string;
+    correlationId: string;
+    parentId?: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status?: number;
+    error?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Correlation ID manager
+ */
+export declare class CorrelationManager {
+    private config;
+    private contexts;
+    private serviceCalls;
+    private activeRequests;
+    constructor(config?: CorrelationConfig);
+    /**
+     * Generate UUID v4
+     */
+    private generateUUID;
+    /**
+     * Validate correlation ID format
+     */
+    private isValidId;
+    /**
+     * Extract correlation context from request
+     */
+    extractContext(req: EnhancedRequest): CorrelationContext;
+    /**
+     * Get correlation context by ID
+     */
+    getContext(correlationId: string): CorrelationContext | undefined;
+    /**
+     * Update correlation context
+     */
+    updateContext(correlationId: string, updates: Partial<CorrelationContext>): void;
+    /**
+     * Add metadata to correlation context
+     */
+    addMetadata(correlationId: string, metadata: Record<string, any>): void;
+    /**
+     * Create child correlation context
+     */
+    createChildContext(parentId: string, serviceName: string): CorrelationContext;
+    /**
+     * Record service call
+     */
+    recordServiceCall(call: Omit<ServiceCall, 'startTime'>): void;
+    /**
+     * Complete service call
+     */
+    completeServiceCall(correlationId: string, serviceName: string, status: number, error?: string, metadata?: Record<string, any>): void;
+    /**
+     * Get service calls for correlation ID
+     */
+    getServiceCalls(correlationId: string): ServiceCall[];
+    /**
+     * Finish correlation context
+     */
+    finishContext(correlationId: string, status?: number, error?: string): void;
+    /**
+     * Create HTTP client with correlation propagation
+     */
+    createHttpClient(correlationId: string): {
+        fetch: (url: string, options?: RequestInit) => Promise<Response>;
+        get: (url: string, options?: RequestInit) => Promise<Response>;
+        post: (url: string, options?: RequestInit) => Promise<Response>;
+        put: (url: string, options?: RequestInit) => Promise<Response>;
+        delete: (url: string, options?: RequestInit) => Promise<Response>;
+    };
+    /**
+     * Get correlation trace
+     */
+    getTrace(correlationId: string): {
+        context: CorrelationContext;
+        serviceCalls: ServiceCall[];
+        children: string[];
+    } | null;
+    /**
+     * Get full trace tree
+     */
+    getFullTrace(rootCorrelationId: string): any;
+    /**
+     * Cleanup old contexts
+     */
+    cleanup(maxAge?: number): void;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        activeContexts: number;
+        totalContexts: number;
+        totalServiceCalls: number;
+        averageCallsPerContext: number;
+    };
+    /**
+     * Log with correlation context
+     */
+    private log;
+}
+/**
+ * Initialize global correlation manager
+ */
+export declare function initializeCorrelation(config?: CorrelationConfig): CorrelationManager;
+/**
+ * Get global correlation manager
+ */
+export declare function getCorrelationManager(): CorrelationManager | null;
+/**
+ * Correlation middleware factory
+ */
+export declare function createCorrelationMiddleware(config?: Partial<CorrelationConfig>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Correlation helper functions
+ */
+export declare const CorrelationHelpers: {
+    /**
+     * Get correlation ID from request
+     */
+    getId: (req: EnhancedRequest) => string | null;
+    /**
+     * Get correlation context from request
+     */
+    getContext: (req: EnhancedRequest) => CorrelationContext | null;
+    /**
+     * Get HTTP client from request
+     */
+    getHttpClient: (req: EnhancedRequest) => any;
+    /**
+     * Add metadata to current correlation
+     */
+    addMetadata: (req: EnhancedRequest, metadata: Record<string, any>) => void;
+    /**
+     * Create child context for service call
+     */
+    createChild: (req: EnhancedRequest, serviceName: string) => CorrelationContext | null;
+    /**
+     * Get trace for current request
+     */
+    getTrace: (req: EnhancedRequest) => any;
+};
+/**
+ * Correlation endpoint handlers
+ */
+export declare const CorrelationEndpoints: {
+    /**
+     * Get correlation trace endpoint
+     */
+    trace: (req: EnhancedRequest) => Promise<Response>;
+    /**
+     * Get correlation statistics endpoint
+     */
+    stats: (_req: EnhancedRequest) => Promise<Response>;
+};

package/dist/observability/health-checks.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Observability & Monitoring - Health Check Endpoints with Dependency Checks
+ *
+ * Enterprise-grade health monitoring with dependency validation and detailed reporting
+ */
+import type { EnhancedRequest } from '../types';
+export interface HealthCheckConfig {
+    timeout?: number;
+    retries?: number;
+    interval?: number;
+    gracePeriod?: number;
+    dependencies?: DependencyConfig[];
+    customChecks?: CustomHealthCheck[];
+}
+export interface DependencyConfig {
+    name: string;
+    type: 'http' | 'database' | 'redis' | 'queue' | 'file' | 'custom';
+    url?: string;
+    timeout?: number;
+    retries?: number;
+    critical?: boolean;
+    metadata?: Record<string, any>;
+    check?: () => Promise<HealthCheckResult>;
+}
+export interface CustomHealthCheck {
+    name: string;
+    check: () => Promise<HealthCheckResult>;
+    critical?: boolean;
+    timeout?: number;
+}
+export interface HealthCheckResult {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    message?: string;
+    duration?: number;
+    metadata?: Record<string, any>;
+    error?: string;
+    timestamp: number;
+}
+export interface HealthStatus {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    timestamp: number;
+    uptime: number;
+    version?: string;
+    environment?: string;
+    checks: Record<string, HealthCheckResult>;
+    dependencies: Record<string, HealthCheckResult>;
+    summary: {
+        total: number;
+        healthy: number;
+        unhealthy: number;
+        degraded: number;
+    };
+}
+/**
+ * Health check manager
+ */
+export declare class HealthCheckManager {
+    private config;
+    private dependencies;
+    private customChecks;
+    private lastResults;
+    private startTime;
+    constructor(config?: HealthCheckConfig);
+    /**
+     * Add a dependency check
+     */
+    addDependency(config: DependencyConfig): void;
+    /**
+     * Add a custom health check
+     */
+    addCustomCheck(check: CustomHealthCheck): void;
+    /**
+     * Remove a dependency check
+     */
+    removeDependency(name: string): boolean;
+    /**
+     * Remove a custom check
+     */
+    removeCustomCheck(name: string): boolean;
+    /**
+     * Perform all health checks
+     */
+    checkHealth(): Promise<HealthStatus>;
+    /**
+     * Check a specific dependency
+     */
+    private checkDependency;
+    /**
+     * Check HTTP dependency
+     */
+    private checkHttpDependency;
+    /**
+     * Check database dependency
+     */
+    private checkDatabaseDependency;
+    /**
+     * Check Redis dependency
+     */
+    private checkRedisDependency;
+    /**
+     * Check queue dependency
+     */
+    private checkQueueDependency;
+    /**
+     * Check file system dependency
+     */
+    private checkFileDependency;
+    /**
+     * Run custom health check
+     */
+    private runCustomCheck;
+    /**
+     * Execute a promise with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Check if a result is from a critical check
+     */
+    private isCriticalCheck;
+    /**
+     * Get the last health check results
+     */
+    getLastResults(): Map<string, HealthCheckResult>;
+    /**
+     * Get uptime in seconds
+     */
+    getUptime(): number;
+    /**
+     * Reset start time (for testing)
+     */
+    resetStartTime(): void;
+}
+/**
+ * Initialize global health check manager
+ */
+export declare function initializeHealthChecks(config?: HealthCheckConfig): HealthCheckManager;
+/**
+ * Get global health check manager
+ */
+export declare function getHealthManager(): HealthCheckManager | null;
+/**
+ * Health check endpoint handlers
+ */
+export declare const HealthEndpoints: {
+    /**
+     * Basic health check endpoint
+     */
+    health: (_req: EnhancedRequest) => Promise<Response>;
+    /**
+     * Readiness probe endpoint
+     */
+    ready: (_req: EnhancedRequest) => Promise<Response>;
+    /**
+     * Liveness probe endpoint
+     */
+    live: (_req: EnhancedRequest) => Promise<Response>;
+    /**
+     * Startup probe endpoint
+     */
+    startup: (_req: EnhancedRequest) => Promise<Response>;
+};
+/**
+ * Built-in dependency check factories
+ */
+export declare const DependencyChecks: {
+    /**
+     * HTTP service dependency
+     */
+    httpService: (name: string, url: string, options?: Partial<DependencyConfig>) => DependencyConfig;
+    /**
+     * Database dependency
+     */
+    database: (name: string, options?: Partial<DependencyConfig>) => DependencyConfig;
+    /**
+     * Redis dependency
+     */
+    redis: (name: string, options?: Partial<DependencyConfig>) => DependencyConfig;
+    /**
+     * File system dependency
+     */
+    fileSystem: (name: string, path: string, options?: Partial<DependencyConfig>) => DependencyConfig;
+    /**
+     * Custom dependency with function
+     */
+    custom: (name: string, checkFn: () => Promise<HealthCheckResult>, options?: Partial<DependencyConfig>) => DependencyConfig;
+};

package/dist/observability/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Observability & Monitoring - Main Exports
+ *
+ * Enterprise-grade observability features for distributed systems
+ */
+import type { EnhancedRequest } from '../types';
+import type { ObservabilityConfig, ObservabilityManager } from './integration';
+export { type CorrelationConfig, type CorrelationContext, CorrelationEndpoints, CorrelationHelpers, CorrelationManager, createCorrelationMiddleware, getCorrelationManager, initializeCorrelation, type ServiceCall, } from './correlation';
+export { type CustomHealthCheck, DependencyChecks, type DependencyConfig, getHealthManager, type HealthCheckConfig, HealthCheckManager, type HealthCheckResult, HealthEndpoints, type HealthStatus, initializeHealthChecks, } from './health-checks';
+export { getObservabilityManager, initializeObservability, type ObservabilityConfig, ObservabilityIntegration, ObservabilityManager, ObservabilityPresets, ObservabilityUtils, } from './integration';
+export { Counter, createMetricsHandler, createMetricsMiddleware, Gauge, getMetricsRegistry, Histogram, type HistogramBucket, initializeMetrics, type MetricConfig, type MetricLabels, MetricsRegistry, Summary, type SummaryQuantile, } from './metrics';
+export { createTracingMiddleware, DistributedTracer, getTracer, initializeTracer, type Span, type SpanContext, type TraceConfig, type TraceData, TraceHelpers, } from './tracing';
+/**
+ * Quick setup functions for common use cases
+ */
+/**
+ * Initialize observability with development preset
+ */
+export declare function setupDevelopmentObservability(): Promise<ObservabilityManager>;
+/**
+ * Initialize observability with production preset
+ */
+export declare function setupProductionObservability(): Promise<ObservabilityManager>;
+/**
+ * Initialize observability with Kubernetes preset
+ */
+export declare function setupKubernetesObservability(): Promise<ObservabilityManager>;
+/**
+ * Initialize observability with microservices preset
+ */
+export declare function setupMicroservicesObservability(): Promise<ObservabilityManager>;
+/**
+ * Initialize observability from environment variables
+ */
+export declare function setupObservabilityFromEnv(): Promise<ObservabilityManager>;
+/**
+ * Create a complete observability middleware stack
+ */
+export declare function createObservabilityStack(config?: ObservabilityConfig): Promise<{
+    middleware: (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    endpoints: Record<string, (req: EnhancedRequest) => Promise<Response>>;
+    manager: ObservabilityManager;
+}>;
+/**
+ * Default export for convenience
+ */
+declare const observabilityDefault: {
+    setupDevelopmentObservability: typeof setupDevelopmentObservability;
+    setupProductionObservability: typeof setupProductionObservability;
+    setupKubernetesObservability: typeof setupKubernetesObservability;
+    setupMicroservicesObservability: typeof setupMicroservicesObservability;
+    setupObservabilityFromEnv: typeof setupObservabilityFromEnv;
+    createObservabilityStack: typeof createObservabilityStack;
+    initializeObservability: Promise<any>;
+    getObservabilityManager: Promise<any>;
+    ObservabilityPresets: Promise<any>;
+    ObservabilityIntegration: Promise<any>;
+    ObservabilityUtils: Promise<any>;
+};
+export default observabilityDefault;

package/dist/observability/integration.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Observability & Monitoring - Integration Layer
+ *
+ * Unified integration for tracing, metrics, health checks, and correlation
+ */
+import type { EnhancedRequest } from '../types';
+import type { CorrelationConfig } from './correlation';
+import type { HealthCheckConfig } from './health-checks';
+import type { MetricConfig } from './metrics';
+import type { TraceConfig } from './tracing';
+export interface ObservabilityConfig {
+    tracing?: TraceConfig;
+    metrics?: MetricConfig;
+    healthChecks?: HealthCheckConfig;
+    correlation?: CorrelationConfig;
+    enableTracing?: boolean;
+    enableMetrics?: boolean;
+    enableHealthChecks?: boolean;
+    enableCorrelation?: boolean;
+    endpoints?: {
+        metrics?: string;
+        health?: string;
+        ready?: string;
+        live?: string;
+        startup?: string;
+        trace?: string;
+        correlationStats?: string;
+    };
+}
+/**
+ * Observability manager - coordinates all observability features
+ */
+export declare class ObservabilityManager {
+    private config;
+    private initialized;
+    constructor(config?: ObservabilityConfig);
+    /**
+     * Initialize all observability components
+     */
+    initialize(): void;
+    /**
+     * Create observability middleware stack
+     */
+    createMiddleware(): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create observability route handlers
+     */
+    createRouteHandlers(): Record<string, (req: EnhancedRequest) => Promise<Response>>;
+    /**
+     * Get observability status
+     */
+    getStatus(): {
+        initialized: boolean;
+        components: {
+            tracing: boolean;
+            metrics: boolean;
+            healthChecks: boolean;
+            correlation: boolean;
+        };
+        endpoints: string[];
+    };
+}
+/**
+ * Initialize global observability
+ */
+export declare function initializeObservability(config?: ObservabilityConfig): ObservabilityManager;
+/**
+ * Get global observability manager
+ */
+export declare function getObservabilityManager(): ObservabilityManager | null;
+/**
+ * Observability presets for common configurations
+ */
+export declare const ObservabilityPresets: {
+    /**
+     * Development preset - console logging, basic metrics
+     */
+    development: () => ObservabilityConfig;
+    /**
+     * Production preset - optimized for performance
+     */
+    production: () => ObservabilityConfig;
+    /**
+     * Kubernetes preset - optimized for k8s deployment
+     */
+    kubernetes: () => ObservabilityConfig;
+    /**
+     * Microservices preset - enhanced correlation and tracing
+     */
+    microservices: () => ObservabilityConfig;
+    /**
+     * Minimal preset - basic observability
+     */
+    minimal: () => ObservabilityConfig;
+};
+/**
+ * Router integration helpers
+ */
+export declare const ObservabilityIntegration: {
+    /**
+     * Add observability to router
+     */
+    enhance: (router: any, config?: ObservabilityConfig) => {
+        manager: ObservabilityManager;
+        middleware: (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+        handlers: Record<string, (req: EnhancedRequest) => Promise<Response>>;
+        status: ReturnType<ObservabilityManager["getStatus"]>;
+    };
+    /**
+     * Create observability-enabled route builder
+     */
+    createRouteBuilder: (config?: ObservabilityConfig) => {
+        /**
+         * Create route with observability
+         */
+        route: (method: string, path: string, handler: (req: EnhancedRequest) => Promise<Response>) => {
+            method: string;
+            path: string;
+            handler: (req: EnhancedRequest) => Promise<Response>;
+        };
+        /**
+         * Get observability endpoints
+         */
+        getEndpoints: () => Record<string, (req: EnhancedRequest) => Promise<Response>>;
+        /**
+         * Get manager instance
+         */
+        getManager: () => ObservabilityManager;
+    };
+};
+/**
+ * Utility functions for observability
+ */
+export declare const ObservabilityUtils: {
+    /**
+     * Create observability configuration from environment
+     */
+    fromEnvironment: () => ObservabilityConfig;
+    /**
+     * Validate observability configuration
+     */
+    validateConfig: (config: ObservabilityConfig) => string[];
+    /**
+     * Get observability summary
+     */
+    getSummary: () => any;
+};