raffel 0.1.2

package/dist/metrics/registry.js

@@ -0,0 +1,178 @@
+/**
+ * Metric Registry
+ *
+ * Central registry for all metrics with counter, gauge, and histogram support.
+ */
+import { DEFAULT_HISTOGRAM_BUCKETS } from './types.js';
+import { exportPrometheus, exportJson } from './exporters.js';
+/**
+ * Create a string key from labels for Map storage
+ */
+function labelsToKey(labels) {
+    const sortedKeys = Object.keys(labels).sort();
+    if (sortedKeys.length === 0)
+        return '';
+    return sortedKeys.map((k) => `${k}="${labels[k]}"`).join(',');
+}
+/**
+ * Merge default labels with provided labels
+ */
+function mergeLabels(defaults, provided = {}) {
+    return { ...defaults, ...provided };
+}
+/**
+ * Validate that provided labels match the registered label keys.
+ * Default labels are exempt from validation.
+ */
+function validateLabels(metricName, labelKeys, provided, defaultLabels) {
+    const providedKeys = Object.keys(provided);
+    const defaultKeys = Object.keys(defaultLabels);
+    // Check for extra labels not in definition (excluding default labels)
+    for (const key of providedKeys) {
+        // Default labels are always allowed
+        if (defaultKeys.includes(key))
+            continue;
+        if (!labelKeys.includes(key)) {
+            throw new Error(`Metric '${metricName}' does not have label '${key}'. ` +
+                `Registered labels: [${labelKeys.join(', ')}]`);
+        }
+    }
+}
+/**
+ * Create an empty histogram value
+ */
+function createHistogramValue(buckets, labels) {
+    return {
+        labels,
+        buckets: buckets.map((le) => ({ le, count: 0 })),
+        sum: 0,
+        count: 0,
+    };
+}
+/**
+ * Create a new MetricRegistry instance
+ */
+export function createMetricRegistry() {
+    const metrics = new Map();
+    let defaultLabels = {};
+    function registerMetric(name, type, opts = {}) {
+        if (metrics.has(name)) {
+            throw new Error(`Metric '${name}' is already registered`);
+        }
+        const definition = {
+            name,
+            type,
+            description: opts.description ?? '',
+            labelKeys: opts.labels ?? [],
+            values: new Map(),
+        };
+        if (type === 'histogram') {
+            definition.buckets = opts.buckets ?? [...DEFAULT_HISTOGRAM_BUCKETS];
+            definition.histogramValues = new Map();
+        }
+        metrics.set(name, definition);
+    }
+    function getMetricOrThrow(name, expectedType) {
+        const metric = metrics.get(name);
+        if (!metric) {
+            throw new Error(`Metric '${name}' is not registered`);
+        }
+        if (expectedType && metric.type !== expectedType) {
+            throw new Error(`Metric '${name}' is a ${metric.type}, not a ${expectedType}`);
+        }
+        return metric;
+    }
+    const registry = {
+        counter(name, opts) {
+            registerMetric(name, 'counter', opts);
+        },
+        gauge(name, opts) {
+            registerMetric(name, 'gauge', opts);
+        },
+        histogram(name, opts) {
+            registerMetric(name, 'histogram', opts);
+        },
+        increment(name, labels = {}, delta = 1) {
+            const metric = getMetricOrThrow(name, 'counter');
+            const mergedLabels = mergeLabels(defaultLabels, labels);
+            validateLabels(name, metric.labelKeys, mergedLabels, defaultLabels);
+            const key = labelsToKey(mergedLabels);
+            const existing = metric.values.get(key);
+            if (existing) {
+                existing.value += delta;
+            }
+            else {
+                metric.values.set(key, {
+                    value: delta,
+                    labels: mergedLabels,
+                });
+            }
+        },
+        set(name, value, labels = {}) {
+            const metric = getMetricOrThrow(name, 'gauge');
+            const mergedLabels = mergeLabels(defaultLabels, labels);
+            validateLabels(name, metric.labelKeys, mergedLabels, defaultLabels);
+            const key = labelsToKey(mergedLabels);
+            metric.values.set(key, {
+                value,
+                labels: mergedLabels,
+            });
+        },
+        observe(name, value, labels = {}) {
+            const metric = getMetricOrThrow(name, 'histogram');
+            const mergedLabels = mergeLabels(defaultLabels, labels);
+            validateLabels(name, metric.labelKeys, mergedLabels, defaultLabels);
+            const key = labelsToKey(mergedLabels);
+            let histValue = metric.histogramValues.get(key);
+            if (!histValue) {
+                histValue = createHistogramValue(metric.buckets, mergedLabels);
+                metric.histogramValues.set(key, histValue);
+            }
+            // Update sum and count
+            histValue.sum += value;
+            histValue.count += 1;
+            // Update buckets (cumulative)
+            for (const bucket of histValue.buckets) {
+                if (value <= bucket.le) {
+                    bucket.count += 1;
+                }
+            }
+        },
+        timer(name, labels = {}) {
+            const start = performance.now();
+            return () => {
+                const duration = (performance.now() - start) / 1000; // Convert to seconds
+                registry.observe(name, duration, labels);
+                return duration;
+            };
+        },
+        export(format) {
+            if (format === 'prometheus') {
+                return exportPrometheus(metrics, defaultLabels);
+            }
+            return exportJson(metrics, defaultLabels);
+        },
+        getMetric(name) {
+            return metrics.get(name);
+        },
+        getMetricNames() {
+            return Array.from(metrics.keys());
+        },
+        reset() {
+            for (const metric of metrics.values()) {
+                metric.values.clear();
+                if (metric.histogramValues) {
+                    metric.histogramValues.clear();
+                }
+            }
+        },
+        getDefaultLabels() {
+            return { ...defaultLabels };
+        },
+        setDefaultLabels(labels) {
+            defaultLabels = { ...labels };
+        },
+    };
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/metrics/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/metrics/registry.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Metrics System Types
+ *
+ * Prometheus-style metrics with counters, gauges, and histograms.
+ */
+/** Metric types supported */
+export type MetricType = 'counter' | 'gauge' | 'histogram';
+/** Label key-value pairs */
+export type Labels = Record<string, string>;
+/** Options for registering a metric */
+export interface MetricOptions {
+    /** Human-readable description (used in HELP line) */
+    description?: string;
+    /** Label keys this metric supports */
+    labels?: string[];
+    /** Bucket boundaries for histograms (default: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]) */
+    buckets?: number[];
+}
+/** Configuration for enabling metrics on server */
+export interface MetricsConfig {
+    /** Enable/disable metrics (default: true when enableMetrics is called) */
+    enabled?: boolean;
+    /** HTTP endpoint path for Prometheus scraping (default: '/metrics') */
+    endpoint?: string;
+    /** Default labels added to all metrics */
+    defaultLabels?: Labels;
+    /** Auto-collect request metrics (default: true) */
+    collectRequestMetrics?: boolean;
+    /** Auto-collect process metrics - CPU, memory, event loop (default: false) */
+    collectProcessMetrics?: boolean;
+}
+/** Internal metric value storage */
+export interface MetricValue {
+    value: number;
+    labels: Labels;
+    timestamp?: number;
+}
+/** Histogram bucket with cumulative count */
+export interface HistogramBucket {
+    le: number;
+    count: number;
+}
+/** Histogram value with buckets, sum, and count */
+export interface HistogramValue {
+    labels: Labels;
+    buckets: HistogramBucket[];
+    sum: number;
+    count: number;
+}
+/** Registered metric definition */
+export interface MetricDefinition {
+    name: string;
+    type: MetricType;
+    description: string;
+    labelKeys: string[];
+    /** For histogram: bucket boundaries */
+    buckets?: number[];
+    /** Counter/gauge values by label key string */
+    values: Map<string, MetricValue>;
+    /** Histogram values by label key string */
+    histogramValues?: Map<string, HistogramValue>;
+}
+/** Metric Registry API */
+export interface MetricRegistry {
+    /** Register a counter metric */
+    counter(name: string, opts?: MetricOptions): void;
+    /** Register a gauge metric */
+    gauge(name: string, opts?: MetricOptions): void;
+    /** Register a histogram metric */
+    histogram(name: string, opts?: MetricOptions): void;
+    /** Increment a counter (default delta: 1) */
+    increment(name: string, labels?: Labels, delta?: number): void;
+    /** Set a gauge value */
+    set(name: string, value: number, labels?: Labels): void;
+    /** Record an observation in a histogram */
+    observe(name: string, value: number, labels?: Labels): void;
+    /** Start a timer, returns function to stop and record duration */
+    timer(name: string, labels?: Labels): () => number;
+    /** Export all metrics in the specified format */
+    export(format: 'prometheus' | 'json'): string;
+    /** Get a metric definition by name */
+    getMetric(name: string): MetricDefinition | undefined;
+    /** List all registered metric names */
+    getMetricNames(): string[];
+    /** Reset all metric values (for testing) */
+    reset(): void;
+    /** Get default labels */
+    getDefaultLabels(): Labels;
+    /** Set default labels */
+    setDefaultLabels(labels: Labels): void;
+}
+/** Export format options */
+export type ExportFormat = 'prometheus' | 'json';
+/** Default histogram buckets (Prometheus defaults for seconds) */
+export declare const DEFAULT_HISTOGRAM_BUCKETS: number[];
+/** Auto-collected metric names */
+export declare const AUTO_METRICS: {
+    readonly REQUESTS_TOTAL: "raffel_requests_total";
+    readonly REQUEST_DURATION: "raffel_request_duration_seconds";
+    readonly REQUEST_ERRORS: "raffel_request_errors_total";
+    readonly WS_CONNECTIONS: "raffel_ws_connections_active";
+    readonly WS_MESSAGES: "raffel_ws_messages_total";
+    readonly PROCESS_CPU: "process_cpu_seconds_total";
+    readonly PROCESS_MEMORY: "process_resident_memory_bytes";
+    readonly EVENTLOOP_LAG: "nodejs_eventloop_lag_seconds";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.js

@@ -0,0 +1,21 @@
+/**
+ * Metrics System Types
+ *
+ * Prometheus-style metrics with counters, gauges, and histograms.
+ */
+/** Default histogram buckets (Prometheus defaults for seconds) */
+export const DEFAULT_HISTOGRAM_BUCKETS = [
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+];
+/** Auto-collected metric names */
+export const AUTO_METRICS = {
+    REQUESTS_TOTAL: 'raffel_requests_total',
+    REQUEST_DURATION: 'raffel_request_duration_seconds',
+    REQUEST_ERRORS: 'raffel_request_errors_total',
+    WS_CONNECTIONS: 'raffel_ws_connections_active',
+    WS_MESSAGES: 'raffel_ws_messages_total',
+    PROCESS_CPU: 'process_cpu_seconds_total',
+    PROCESS_MEMORY: 'process_resident_memory_bytes',
+    EVENTLOOP_LAG: 'nodejs_eventloop_lag_seconds',
+};
+//# sourceMappingURL=types.js.map

package/dist/metrics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2GH,kEAAkE;AAClE,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;CACxD,CAAA;AAED,kCAAkC;AAClC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc,EAAE,uBAAuB;IACvC,gBAAgB,EAAE,iCAAiC;IACnD,cAAc,EAAE,6BAA6B;IAC7C,cAAc,EAAE,8BAA8B;IAC9C,WAAW,EAAE,0BAA0B;IACvC,WAAW,EAAE,2BAA2B;IACxC,cAAc,EAAE,+BAA+B;IAC/C,aAAa,EAAE,8BAA8B;CACrC,CAAA"}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Authentication Middleware
+ *
+ * Flexible authentication middleware supporting multiple strategies:
+ * - Bearer token (JWT, OAuth tokens)
+ * - API Key
+ * - Custom strategies
+ */
+import type { Interceptor, Envelope, Context, AuthContext } from '../types/index.js';
+/**
+ * Authentication result
+ */
+export interface AuthResult {
+    /** Whether authentication was successful */
+    authenticated: boolean;
+    /** User/service identifier (maps to AuthContext.principal) */
+    principal?: string;
+    /** User roles/permissions (stored in claims.roles) */
+    roles?: string[];
+    /** Authentication claims (JWT payload, etc.) */
+    claims?: Record<string, unknown>;
+}
+/**
+ * Authentication strategy interface
+ */
+export interface AuthStrategy {
+    /** Strategy name for identification */
+    name: string;
+    /**
+     * Authenticate the request
+     * @param envelope - The incoming envelope with metadata
+     * @param ctx - Request context
+     * @returns AuthResult or null if strategy doesn't apply
+     */
+    authenticate(envelope: Envelope, ctx: Context): Promise<AuthResult | null>;
+}
+/**
+ * Authentication middleware options
+ */
+export interface AuthMiddlewareOptions {
+    /** Authentication strategies to apply (in order) */
+    strategies: AuthStrategy[];
+    /** Procedures that don't require authentication */
+    publicProcedures?: string[];
+    /** Custom error handler */
+    onError?: (error: Error, envelope: Envelope) => void;
+}
+/**
+ * Bearer token authentication strategy
+ */
+export interface BearerTokenOptions {
+    /** Function to verify and decode the token */
+    verify: (token: string) => Promise<AuthResult | null>;
+    /** Header name (default: 'authorization') */
+    headerName?: string;
+    /** Token prefix (default: 'Bearer ') */
+    tokenPrefix?: string;
+}
+/**
+ * Create a bearer token authentication strategy
+ */
+export declare function createBearerStrategy(options: BearerTokenOptions): AuthStrategy;
+/**
+ * API Key authentication strategy options
+ */
+export interface ApiKeyOptions {
+    /** Function to verify the API key */
+    verify: (apiKey: string) => Promise<AuthResult | null>;
+    /** Header name for API key (default: 'x-api-key') */
+    headerName?: string;
+}
+/**
+ * Create an API key authentication strategy
+ */
+export declare function createApiKeyStrategy(options: ApiKeyOptions): AuthStrategy;
+/**
+ * Simple static API key strategy for development/internal use
+ */
+export declare function createStaticApiKeyStrategy(validKeys: Map<string, AuthResult>): AuthStrategy;
+/**
+ * Cookie session authentication strategy options
+ */
+export interface CookieSessionOptions {
+    /** Cookie name (default: 'session') */
+    cookieName?: string;
+    /** Secret for signed cookies (optional) */
+    secret?: string;
+    /** Function to validate and decode the session */
+    validate: (sessionId: string) => Promise<AuthResult | null>;
+    /** Whether to use chunked cookies for large sessions */
+    chunked?: boolean;
+}
+/**
+ * Create a cookie session authentication strategy
+ *
+ * Works with:
+ * - Simple session cookies
+ * - Signed cookies (HMAC-SHA256)
+ * - Chunked cookies (for large JWT sessions)
+ *
+ * @example
+ * ```ts
+ * const cookieAuth = createCookieSessionStrategy({
+ *   cookieName: 'session',
+ *   secret: process.env.COOKIE_SECRET,
+ *   validate: async (sessionId) => {
+ *     const session = await redis.get(`session:${sessionId}`)
+ *     if (!session) return null
+ *     return { authenticated: true, principal: session.userId, claims: session }
+ *   }
+ * })
+ * ```
+ */
+export declare function createCookieSessionStrategy(options: CookieSessionOptions): AuthStrategy;
+/**
+ * Enhanced bearer token options with query param support
+ */
+export interface EnhancedBearerTokenOptions {
+    /** Function to verify and decode the token */
+    verify: (token: string) => Promise<AuthResult | null>;
+    /** Header name (default: 'authorization') */
+    headerName?: string;
+    /** Token prefix (default: 'Bearer ') */
+    tokenPrefix?: string;
+    /** Query param name for token (e.g., 'token' for EventSource) */
+    queryParam?: string;
+    /** Extract from sources (default: ['header']) */
+    extractFrom?: Array<'header' | 'query'>;
+}
+/**
+ * Create an enhanced bearer token strategy with query param support
+ *
+ * This is useful for EventSource/SSE connections where you can't set
+ * custom headers. The token can be passed via query param instead.
+ *
+ * @example
+ * ```ts
+ * const bearerAuth = createEnhancedBearerStrategy({
+ *   extractFrom: ['header', 'query'],
+ *   queryParam: 'token',
+ *   verify: async (token) => {
+ *     const decoded = jwt.verify(token, secret)
+ *     return { authenticated: true, principal: decoded.sub, claims: decoded }
+ *   }
+ * })
+ *
+ * // Works with:
+ * // Authorization: Bearer <token>
+ * // GET /stream?token=<token>
+ * ```
+ */
+export declare function createEnhancedBearerStrategy(options: EnhancedBearerTokenOptions): AuthStrategy;
+/**
+ * Enhanced API key options with query param support
+ */
+export interface EnhancedApiKeyOptions {
+    /** Function to verify the API key */
+    verify: (apiKey: string) => Promise<AuthResult | null>;
+    /** Header name for API key (default: 'x-api-key') */
+    headerName?: string;
+    /** Query param name for API key (e.g., 'apiKey' for EventSource) */
+    queryParam?: string;
+    /** Extract from sources (default: ['header']) */
+    extractFrom?: Array<'header' | 'query'>;
+}
+/**
+ * Create an enhanced API key strategy with query param support
+ *
+ * @example
+ * ```ts
+ * const apiKeyAuth = createEnhancedApiKeyStrategy({
+ *   extractFrom: ['header', 'query'],
+ *   queryParam: 'apiKey',
+ *   verify: async (key) => {
+ *     const apiKey = await db.apiKeys.findByKey(key)
+ *     if (!apiKey) return null
+ *     return { authenticated: true, principal: apiKey.ownerId, claims: { scopes: apiKey.scopes } }
+ *   }
+ * })
+ *
+ * // Works with:
+ * // X-API-Key: <key>
+ * // GET /stream?apiKey=<key>
+ * ```
+ */
+export declare function createEnhancedApiKeyStrategy(options: EnhancedApiKeyOptions): AuthStrategy;
+/**
+ * Create the authentication interceptor
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): Interceptor;
+/**
+ * Authorization middleware options
+ */
+export interface AuthzMiddlewareOptions {
+    /** Role-based access control rules */
+    rules: AuthzRule[];
+    /** Default policy when no rule matches */
+    defaultAllow?: boolean;
+}
+/**
+ * Authorization rule
+ */
+export interface AuthzRule {
+    /** Procedure name pattern (supports * wildcard) */
+    procedure: string;
+    /** Required roles (any of these) */
+    roles?: string[];
+    /** Custom check function */
+    check?: (ctx: Context) => Promise<boolean> | boolean;
+}
+/**
+ * Create authorization middleware (role-based access control)
+ */
+export declare function createAuthzMiddleware(options: AuthzMiddlewareOptions): Interceptor;
+/**
+ * Helper to require authentication on context
+ */
+export declare function requireAuth(ctx: Context): AuthContext;
+/**
+ * Helper to check if user has a specific role
+ */
+export declare function hasRole(ctx: Context, role: string): boolean;
+/**
+ * Helper to check if user has any of the specified roles
+ */
+export declare function hasAnyRole(ctx: Context, roles: string[]): boolean;
+/**
+ * Helper to check if user has all of the specified roles
+ */
+export declare function hasAllRoles(ctx: Context, roles: string[]): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"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"}

package/dist/middleware/auth.int.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Authentication Middleware Tests
+ */
+export {};
+//# sourceMappingURL=auth.int.test.d.ts.map

package/dist/middleware/auth.int.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.int.test.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.int.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}