@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/middleware/performance_monitor.d.ts

@@ -0,0 +1,209 @@
+import type { EnhancedRequest as BaseEnhancedRequest, Middleware, NextFunction } from '../types';
+export interface EnhancedRequest extends BaseEnhancedRequest {
+    profiling?: {
+        samples: any[];
+        systemSamples: any[];
+        requestId: string;
+    };
+}
+export interface PerformanceMetrics {
+    requestId: string;
+    method: string;
+    path: string;
+    statusCode: number;
+    responseTime: number;
+    memoryUsage: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        rss: number;
+        arrayBuffers?: number;
+    };
+    cpuUsage: {
+        user: number;
+        system: number;
+    };
+    timestamp: number;
+    userAgent?: string;
+    ip?: string;
+    contentLength?: number;
+    queryParams?: number | Record<string, string>;
+    headers?: Record<string, string>;
+    error?: string;
+    traceId?: string;
+    spanId?: string;
+}
+export interface PerformanceThresholds {
+    responseTime: {
+        warning: number;
+        critical: number;
+    };
+    memoryUsage: {
+        warning: number;
+        critical: number;
+    };
+    errorRate: {
+        warning: number;
+        critical: number;
+    };
+}
+export interface PerformanceMonitorOptions {
+    enabled?: boolean;
+    sampleRate?: number;
+    maxRequestsPerSecond?: number;
+    sampling?: {
+        enabled?: boolean;
+        interval?: number;
+        maxSamples?: number;
+        rate?: number;
+        maxRequestsPerSecond?: number;
+    };
+    collectMetrics?: {
+        responseTime?: boolean;
+        memoryUsage?: boolean;
+        cpuUsage?: boolean;
+        requestDetails?: boolean;
+        headers?: boolean;
+        queryParams?: boolean;
+        userAgent?: boolean;
+        ip?: boolean;
+        contentLength?: boolean;
+    };
+    includeHeaders?: boolean;
+    includeQueryParams?: boolean;
+    includeUserAgent?: boolean;
+    includeIp?: boolean;
+    includeContentLength?: boolean;
+    thresholds?: {
+        responseTime?: {
+            warning?: number;
+            critical?: number;
+        };
+        memoryUsage?: {
+            warning?: number;
+            critical?: number;
+        };
+        errorRate?: {
+            warning?: number;
+            critical?: number;
+        };
+    };
+    customHandler?: (metrics: PerformanceMetrics) => Promise<void>;
+    storage?: {
+        type: 'memory' | 'file' | 'database' | 'custom';
+        maxEntries?: number;
+        retentionPeriod?: number;
+        filePath?: string;
+        customHandler?: (metrics: PerformanceMetrics) => Promise<void>;
+    };
+    alerts?: {
+        enabled?: boolean;
+        cooldown?: number;
+        thresholds?: {
+            responseTime: number;
+            memoryUsage: number;
+            errorRate: number;
+        };
+        handler?: (alert: {
+            type: string;
+            message: string;
+            value: number;
+            threshold: number;
+            path: string;
+            method: string;
+            statusCode: number;
+            timestamp: number;
+            severity: 'info' | 'warning' | 'critical';
+        }) => Promise<void>;
+        customHandler?: (alert: {
+            type: string;
+            message: string;
+            value: number;
+            threshold: number;
+            path: string;
+            method: string;
+            statusCode: number;
+            timestamp: number;
+            severity: 'info' | 'warning' | 'critical';
+        }) => Promise<void>;
+        webhookUrl?: string;
+        emailConfig?: {
+            smtp: string;
+            from: string;
+            to: string[];
+        };
+        slackConfig?: {
+            webhookUrl: string;
+            channel: string;
+        };
+    };
+    profiling?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        includeStackTrace?: boolean;
+        maxStackDepth?: number;
+        sampleInterval?: number;
+        maxSamples?: number;
+    };
+    tracing?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        exporters?: ('console' | 'jaeger' | 'zipkin' | 'otlp')[];
+    };
+}
+export default class PerformanceMonitor implements Middleware {
+    private options;
+    private metrics;
+    private lastAlertTime;
+    private requestsThisSecond;
+    private lastSecondTimestamp;
+    private requestContexts;
+    private samplingCounter;
+    private alertCooldowns;
+    private cleanupInterval?;
+    constructor(options?: PerformanceMonitorOptions);
+    private startCleanupInterval;
+    private cleanupOldMetrics;
+    private shouldSample;
+    private generateTraceId;
+    private generateSpanId;
+    private getClientIP;
+    private collectSystemMetrics;
+    private takeSample;
+    private calculateCpuPercent;
+    private storeMetrics;
+    private checkThresholds;
+    private sendAlert;
+    private sendAlerts;
+    private collectMetrics;
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response | null>;
+    addMetrics(metrics: PerformanceMetrics): void;
+    checkThresholdsPublic(metrics: PerformanceMetrics): Promise<void>;
+    getMetrics(options?: {
+        startTime?: number;
+        endTime?: number;
+        path?: string;
+        method?: string;
+        statusCode?: number;
+        limit?: number;
+    }): PerformanceMetrics[];
+    getAggregatedMetrics(timeWindow?: number): {
+        totalRequests: number;
+        averageResponseTime: number;
+        medianResponseTime: number;
+        p95ResponseTime: number;
+        p99ResponseTime: number;
+        errorRate: number;
+        averageMemoryUsage: number;
+        requestsPerSecond: number;
+        statusCodeDistribution: Record<number, number>;
+        pathDistribution: Record<string, number>;
+    };
+    getProfiles(): Array<{
+        timestamp: number;
+        memoryUsage: NodeJS.MemoryUsage;
+        cpuUsage: NodeJS.CpuUsage;
+    }>;
+    destroy(): void;
+}
+export declare function performanceMonitor(options?: PerformanceMonitorOptions): (req: EnhancedRequest, next: NextFunction) => Promise<Response | null>;

package/dist/middleware/pipeline.d.ts

@@ -0,0 +1,131 @@
+import type { EnhancedRequest, MiddlewareHandler } from '../types';
+/**
+ * Middleware pipeline with composition caching, conditional execution,
+ * dependency injection, and short-circuiting capabilities
+ */
+export interface MiddlewareContext {
+    request: EnhancedRequest;
+    route?: any;
+    skipConditions?: MiddlewareSkipCondition[];
+    dependencies?: Map<string, any>;
+    metadata?: Record<string, any>;
+}
+export interface MiddlewareSkipCondition {
+    name: string;
+    condition: (context: MiddlewareContext) => boolean | Promise<boolean>;
+}
+export interface MiddlewareDependency {
+    name: string;
+    factory: (context: MiddlewareContext) => any | Promise<any>;
+    singleton?: boolean;
+    dependencies?: string[];
+}
+export interface CompiledMiddleware {
+    handler: MiddlewareHandler;
+    name: string;
+    skipConditions: MiddlewareSkipCondition[];
+    dependencies: string[];
+    canShortCircuit: boolean;
+    priority: number;
+}
+export interface MiddlewarePipelineStats {
+    totalExecutions: number;
+    cacheHits: number;
+    cacheMisses: number;
+    shortCircuits: number;
+    skippedMiddleware: number;
+    averageExecutionTime: number;
+    dependencyResolutions: number;
+}
+/**
+ * Middleware pipeline with advanced optimization features
+ */
+export declare class MiddlewarePipeline {
+    private compiledPipelines;
+    private dependencyRegistry;
+    private singletonInstances;
+    private stats;
+    /**
+     * Register a dependency for injection into middleware
+     */
+    registerDependency(dependency: MiddlewareDependency): void;
+    /**
+     * Compile middleware chain for a specific route
+     */
+    compileMiddleware(routeKey: string, middleware: MiddlewareHandler[], skipConditions?: MiddlewareSkipCondition[]): void;
+    /**
+     * Execute compiled middleware pipeline
+     */
+    execute(routeKey: string, request: EnhancedRequest, finalHandler: () => Promise<Response>): Promise<Response>;
+    /**
+     * Check if middleware should be skipped
+     */
+    private shouldSkip;
+    /**
+     * Resolve dependencies for middleware
+     */
+    private resolveDependencies;
+    /**
+     * Extract dependency names from middleware function
+     */
+    private extractDependencies;
+    /**
+     * Check if middleware can short-circuit the pipeline
+     */
+    private canShortCircuit;
+    /**
+     * Update average execution time
+     */
+    private updateAverageExecutionTime;
+    /**
+     * Get pipeline statistics
+     */
+    getStats(): MiddlewarePipelineStats;
+    /**
+     * Clear compiled pipelines and reset stats
+     */
+    clear(): void;
+}
+/**
+ * Skip condition factory functions
+ */
+export declare const SkipConditions: {
+    skipForMethods: (methods: string[]) => MiddlewareSkipCondition;
+    skipForPaths: (paths: string[]) => MiddlewareSkipCondition;
+    skipForHeaders: (headers: Record<string, string>) => MiddlewareSkipCondition;
+    skipForRoles: (roles: string[]) => MiddlewareSkipCondition;
+    skipForEnvironment: (environments: string[]) => MiddlewareSkipCondition;
+};
+/**
+ * Dependency factory functions
+ */
+export declare const Dependencies: {
+    database: (connectionString?: string) => MiddlewareDependency;
+    logger: (level?: string) => MiddlewareDependency;
+    cache: (maxSize?: number) => MiddlewareDependency;
+    httpClient: (baseURL?: string) => MiddlewareDependency;
+};
+/**
+ * Middleware factory functions
+ */
+export declare const MiddlewareFactory: {
+    auth: (options?: {
+        secret?: string;
+        skipPaths?: string[];
+    }) => MiddlewareHandler;
+    rateLimit: (options: {
+        maxRequests: number;
+        windowMs: number;
+    }) => MiddlewareHandler;
+    cors: (options?: {
+        origin?: string;
+        methods?: string[];
+    }) => MiddlewareHandler;
+    logging: (_options?: {
+        level?: string;
+    }) => MiddlewareHandler;
+};
+/**
+ * Global middleware pipeline instance
+ */
+export declare const globalMiddlewarePipeline: MiddlewarePipeline;

package/dist/middleware/rate_limit.d.ts

@@ -0,0 +1,36 @@
+import type { EnhancedRequest, Middleware, MiddlewareHandler, NextFunction } from '../types';
+export interface RateLimitOptions {
+    windowMs?: number;
+    maxRequests?: number;
+    standardHeaders?: boolean;
+    legacyHeaders?: boolean;
+    skipFailedRequests?: boolean;
+    keyGenerator?: (request: Request) => string | Promise<string>;
+    handler?: (request: Request, limit: {
+        remaining: number;
+        limit: number;
+        resetTime: number;
+    }) => Response | Promise<Response>;
+    skip?: (request: Request) => boolean | Promise<boolean>;
+    storage?: any;
+    algorithm?: 'fixed-window' | 'sliding-window' | 'token-bucket';
+    draftMode?: boolean;
+    redis?: {
+        url?: string;
+        prefix?: string;
+    };
+    tokenBucket?: {
+        tokensPerInterval?: number;
+        interval?: number;
+        burst?: number;
+    };
+}
+export default class RateLimit implements Middleware {
+    private limiter;
+    private options;
+    constructor(options?: RateLimitOptions);
+    private initLimiter;
+    private defaultHandler;
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+}
+export declare function rateLimit(options?: RateLimitOptions): MiddlewareHandler;

package/dist/middleware/request_id.d.ts

@@ -0,0 +1,4 @@
+import type { EnhancedRequest, NextFunction } from '../types';
+export default class RequestId {
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+}

package/dist/middleware/request_signing.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Request Signing Middleware
+ *
+ * Provides HMAC-based request signature verification for secure API authentication.
+ * Supports multiple algorithms, timestamp validation, and replay attack prevention.
+ */
+import type { EnhancedRequest, Middleware, NextFunction } from '../types';
+export type SignatureAlgorithm = 'sha256' | 'sha384' | 'sha512';
+export interface RequestSigningOptions {
+    /**
+     * Secret key(s) for HMAC verification.
+     * Can be a single key or a function that returns the key based on key ID.
+     */
+    secret: string | ((_keyId: string) => string | Promise<string | null> | null);
+    /**
+     * HMAC algorithm to use
+     * @default 'sha256'
+     */
+    algorithm?: SignatureAlgorithm;
+    /**
+     * Header name containing the signature
+     * @default 'X-Signature'
+     */
+    signatureHeader?: string;
+    /**
+     * Header name containing the timestamp
+     * @default 'X-Timestamp'
+     */
+    timestampHeader?: string;
+    /**
+     * Header name containing the key ID (for multi-key setups)
+     * @default 'X-Key-Id'
+     */
+    keyIdHeader?: string;
+    /**
+     * Header name containing the nonce (for replay protection)
+     * @default 'X-Nonce'
+     */
+    nonceHeader?: string;
+    /**
+     * Maximum age of request in seconds (timestamp validation)
+     * @default 300 (5 minutes)
+     */
+    maxAge?: number;
+    /**
+     * Whether to require timestamp validation
+     * @default true
+     */
+    requireTimestamp?: boolean;
+    /**
+     * Whether to require nonce for replay protection
+     * @default false
+     */
+    requireNonce?: boolean;
+    /**
+     * Custom function to check if nonce has been used (for replay protection)
+     */
+    nonceStore?: NonceStore;
+    /**
+     * Parts of the request to include in signature
+     * @default ['method', 'path', 'timestamp', 'body']
+     */
+    signedParts?: SignedPart[];
+    /**
+     * Custom function to build the string to sign
+     */
+    stringToSign?: (req: EnhancedRequest, timestamp: string, nonce?: string) => Promise<string> | string;
+    /**
+     * Custom error handler
+     */
+    onError?: (error: SignatureError, req: EnhancedRequest) => Response | Promise<Response>;
+    /**
+     * Skip signature verification for certain paths
+     */
+    exclude?: string[] | ((_req: EnhancedRequest) => boolean);
+    /**
+     * Additional headers to include in signature
+     */
+    signedHeaders?: string[];
+    /**
+     * Signature encoding format
+     * @default 'hex'
+     */
+    encoding?: 'hex' | 'base64';
+}
+export type SignedPart = 'method' | 'path' | 'query' | 'timestamp' | 'body' | 'nonce' | 'headers';
+export interface NonceStore {
+    /**
+     * Check if nonce exists (has been used)
+     */
+    has: (nonce: string) => Promise<boolean> | boolean;
+    /**
+     * Store a nonce
+     */
+    set: (nonce: string, expiry?: number) => Promise<void> | void;
+}
+export type SignatureErrorCode = 'MISSING_SIGNATURE' | 'MISSING_TIMESTAMP' | 'MISSING_NONCE' | 'MISSING_KEY_ID' | 'INVALID_KEY' | 'INVALID_SIGNATURE' | 'EXPIRED_TIMESTAMP' | 'FUTURE_TIMESTAMP' | 'NONCE_REUSED' | 'SIGNATURE_MISMATCH';
+export declare class SignatureError extends Error {
+    readonly code: SignatureErrorCode;
+    readonly statusCode: number;
+    constructor(code: SignatureErrorCode, message: string);
+}
+/**
+ * In-memory nonce store with automatic expiry
+ */
+export declare class InMemoryNonceStore implements NonceStore {
+    private nonces;
+    private cleanupInterval;
+    constructor(cleanupIntervalMs?: number);
+    has(nonce: string): boolean;
+    set(nonce: string, expirySeconds?: number): void;
+    private cleanup;
+    destroy(): void;
+}
+/**
+ * Request Signing Middleware
+ */
+export default class RequestSigning implements Middleware {
+    private options;
+    constructor(options: RequestSigningOptions);
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response | null>;
+    private shouldSkip;
+    private verifySignature;
+    private getSecret;
+    private validateTimestamp;
+    private validateNonce;
+    private buildStringToSign;
+    private calculateSignature;
+    private timingSafeEqual;
+    private defaultErrorResponse;
+}
+/**
+ * Factory function to create request signing middleware
+ */
+export declare function requestSigning(options: RequestSigningOptions): RequestSigning;
+/**
+ * Helper to sign a request (for clients)
+ */
+export declare function signRequest(request: Request, secret: string, options?: {
+    algorithm?: SignatureAlgorithm;
+    signedParts?: SignedPart[];
+    signedHeaders?: string[];
+    signatureHeader?: string;
+    timestampHeader?: string;
+    nonceHeader?: string;
+    keyId?: string;
+    keyIdHeader?: string;
+    encoding?: 'hex' | 'base64';
+}): Promise<Request>;
+/**
+ * Verify a signature (utility function)
+ */
+export declare function verifySignature(stringToSign: string, signature: string, secret: string, algorithm?: SignatureAlgorithm, encoding?: 'hex' | 'base64'): Promise<boolean>;

package/dist/middleware/request_tracer.d.ts

@@ -0,0 +1,72 @@
+import type { EnhancedRequest, NextFunction } from '../types';
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    tags: Record<string, any>;
+    logs: Array<{
+        timestamp: number;
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        fields?: Record<string, any>;
+    }>;
+    status: 'ok' | 'error' | 'timeout';
+    error?: string;
+    stackTrace?: string[];
+}
+export interface TracingOptions {
+    enabled?: boolean;
+    sampleRate?: number;
+    maxSpans?: number;
+    includeHeaders?: boolean;
+    includeQueryParams?: boolean;
+    includeRequestBody?: boolean;
+    includeResponseBody?: boolean;
+    maxBodySize?: number;
+    exporters?: Array<{
+        type: 'console' | 'jaeger' | 'zipkin' | 'otlp' | 'custom';
+        endpoint?: string;
+        headers?: Record<string, string>;
+        customExporter?: (spans: TraceSpan[]) => Promise<void>;
+    }>;
+    propagation?: {
+        enabled?: boolean;
+        headers?: string[];
+    };
+}
+export default class RequestTracer {
+    private options;
+    private spans;
+    private activeSpans;
+    private exportQueue;
+    private exportInterval?;
+    constructor(options?: TracingOptions);
+    private startExportInterval;
+    private shouldSample;
+    private generateId;
+    private extractPropagationHeaders;
+    private captureRequestBody;
+    private captureResponseBody;
+    private createSpan;
+    private addSpanTag;
+    private addSpanLog;
+    private finishSpan;
+    private exportSpans;
+    private exportToConsole;
+    private exportToJaeger;
+    private exportToZipkin;
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+    getActiveSpans(): TraceSpan[];
+    getSpanById(spanId: string): TraceSpan | undefined;
+    createChildSpan(parentSpanId: string, operationName: string): string | null;
+    addTag(spanId: string, key: string, value: any): void;
+    addLog(spanId: string, level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, any>): void;
+    finish(spanId: string, status?: 'ok' | 'error' | 'timeout', error?: string): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+export declare function requestTracer(options?: TracingOptions): (req: EnhancedRequest, next: NextFunction) => Promise<Response>;

package/dist/middleware/response_cache.d.ts

@@ -0,0 +1,97 @@
+import type { EnhancedRequest, Middleware, NextFunction } from '../types';
+export interface CacheEntry {
+    key: string;
+    response: {
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: number[];
+        contentType: string;
+    };
+    createdAt: number;
+    expiresAt: number;
+    etag?: string;
+    lastModified?: string;
+    size: number;
+}
+export interface ResponseCacheOptions {
+    enabled?: boolean;
+    storage?: {
+        type: 'memory' | 'file' | 'hybrid';
+        directory?: string;
+        maxSize?: number;
+        maxEntries?: number;
+    };
+    ttl?: {
+        default: number;
+        routes?: Record<string, number>;
+        methods?: Record<string, number>;
+    };
+    keyGenerator?: (req: EnhancedRequest) => string;
+    shouldCache?: (req: EnhancedRequest, res: Response) => boolean;
+    varyHeaders?: string[];
+    compression?: {
+        enabled: boolean;
+        threshold: number;
+        algorithms: ('gzip' | 'deflate' | 'br')[];
+    };
+    invalidation?: {
+        patterns?: string[];
+        methods?: string[];
+        headers?: string[];
+    };
+    etag?: {
+        enabled: boolean;
+        weak: boolean;
+    };
+    staleWhileRevalidate?: {
+        enabled: boolean;
+        maxAge: number;
+    };
+}
+export declare class ResponseCache implements Middleware {
+    private options;
+    private memoryCache;
+    private cacheStats;
+    private cleanupInterval?;
+    constructor(options?: ResponseCacheOptions);
+    private initializeStorage;
+    private startCleanupInterval;
+    cleanup(): Promise<void>;
+    private cleanupFileCache;
+    private defaultKeyGenerator;
+    private defaultShouldCache;
+    private getTTL;
+    private generateETag;
+    private getFromMemoryCache;
+    private getFromFileCache;
+    private setMemoryCache;
+    private setFileCache;
+    private evictLRU;
+    private updateCacheStats;
+    private generateCacheKey;
+    private getCachedResponse;
+    private setCachedResponse;
+    private handleConditionalRequest;
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+    private deleteCachedResponse;
+    private createCacheEntry;
+    private createResponseFromEntry;
+    private backgroundRevalidate;
+    invalidateCache(req?: EnhancedRequest): Promise<void>;
+    clearCache(): Promise<void>;
+    getStats(): {
+        hits: number;
+        misses: number;
+        sets: number;
+        deletes: number;
+        size: number;
+        memoryUsage: number;
+        hitRate: number;
+    };
+    destroy(): void;
+}
+export declare function responseCache(options?: ResponseCacheOptions): ResponseCache;
+export declare function memoryCache(options?: Omit<ResponseCacheOptions, 'storage'>): ResponseCache;
+export declare function fileCache(directory?: string, options?: Omit<ResponseCacheOptions, 'storage'>): ResponseCache;
+export declare function hybridCache(options?: ResponseCacheOptions): ResponseCache;