recker 1.0.73 → 1.0.75-next.2e5a94f

package/dist/browser/core/errors.js

@@ -3,20 +3,30 @@ export class ReckerError extends Error {
     response;
     suggestions;
     retriable;
-    constructor(message, request, response, suggestions = [], retriable = false) {
+    classification;
+    constructor(message, request, response, suggestions = [], retriable = false, classification) {
         super(message);
         this.name = 'ReckerError';
         this.request = request;
         this.response = response;
         this.suggestions = suggestions;
         this.retriable = retriable;
+        this.classification = classification;
     }
 }
 export class HttpError extends ReckerError {
     status;
     statusText;
     constructor(response, request) {
-        super(`Request failed with status code ${response.status} ${response.statusText}`, request, response, ['Check the upstream service response body for error details.', 'Inspect request headers/body to ensure they match the API contract.', 'Retry if this is a transient 5xx/429 error.'], isRetryableStatus(response.status));
+        const retriable = isRetryableStatus(response.status);
+        super(`Request failed with status code ${response.status} ${response.statusText}`, request, response, ['Check the upstream service response body for error details.', 'Inspect request headers/body to ensure they match the API contract.', 'Retry if this is a transient 5xx/429 error.'], retriable, {
+            category: 'http',
+            source: 'server',
+            severity: response.status >= 500 ? 'high' : 'medium',
+            canRetry: retriable,
+            reason: `HTTP ${response.status}`,
+            statusCode: response.status
+        });
         this.name = 'HttpError';
         this.status = response.status;
         this.statusText = response.statusText;
@@ -53,7 +63,13 @@ export class TimeoutError extends ReckerError {
             'Increase the specific timeout phase or optimize the upstream response time.',
             'Reduce concurrent requests if the connection pool is exhausted.'
         ];
-        super(message, request, undefined, suggestions, true);
+        super(message, request, undefined, suggestions, true, {
+            category: 'timeout',
+            source: 'transport',
+            severity: 'medium',
+            canRetry: true,
+            reason: `Timeout while ${phase}`
+        });
         this.name = 'TimeoutError';
         this.phase = phase;
         this.timeout = timeout ?? 0;
@@ -69,7 +85,13 @@ export class NetworkError extends ReckerError {
             'Check proxy/VPN/firewall settings that might block the request.',
             'Retry the request or switch transport if this is transient.'
         ];
-        super(message, request, undefined, suggestions, true);
+        super(message, request, undefined, suggestions, true, {
+            category: 'network',
+            source: 'transport',
+            severity: code ? 'medium' : 'low',
+            canRetry: true,
+            reason: code ? `Network error (${code})` : message
+        });
         this.name = 'NetworkError';
         this.code = code;
     }
@@ -83,7 +105,14 @@ export class Http2Error extends ReckerError {
         const retriable = isRetriableHttp2Error(errorCode);
         const suggestFallback = shouldFallbackToHttp1(errorCode);
         const suggestions = getHttp2ErrorSuggestions(errorCode, suggestFallback);
-        super(message, options.request, undefined, suggestions, retriable);
+        super(message, options.request, undefined, suggestions, retriable, {
+            category: 'protocol',
+            source: 'transport',
+            severity: retriable ? 'medium' : 'high',
+            canRetry: retriable,
+            reason: `HTTP/2 ${errorCode}`,
+            statusCode: errorCode ? Number.parseInt(String(errorCode), 10) || undefined : undefined
+        });
         this.name = 'Http2Error';
         this.errorCode = errorCode;
         this.level = options.level ?? 'stream';
@@ -171,6 +200,84 @@ export function parseHttp2Error(error) {
     }
     return null;
 }
+export function classifyTransportError(error) {
+    if (error instanceof ReckerError && error.classification) {
+        return error.classification;
+    }
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const anyError = error;
+    const name = anyError.name || '';
+    const message = anyError.message || '';
+    const code = anyError.code?.toUpperCase();
+    if (name === 'AbortError' || code === 'ABORT_ERR' || code === 'UND_ERR_ABORTED' || message.includes('aborted') || message.includes('AbortError')) {
+        return {
+            category: 'queue',
+            source: 'client',
+            severity: 'low',
+            canRetry: true,
+            reason: 'Request was aborted'
+        };
+    }
+    if (name === 'TimeoutError' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'UND_ERR_HEADERS_TIMEOUT' || code === 'UND_ERR_BODY_TIMEOUT' || message.includes('timeout')) {
+        return {
+            category: 'timeout',
+            source: 'transport',
+            severity: 'medium',
+            canRetry: true,
+            reason: message || 'Request timed out'
+        };
+    }
+    const networkCodes = new Set([
+        'ECONNRESET',
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'EPIPE',
+        'ETIMEDOUT',
+        'EHOSTUNREACH',
+        'ENETUNREACH',
+        'ENETDOWN',
+        'EAI_AGAIN'
+    ]);
+    if (code && networkCodes.has(code)) {
+        return {
+            category: 'network',
+            source: 'transport',
+            severity: 'medium',
+            canRetry: true,
+            reason: message || `Network error (${code})`
+        };
+    }
+    if (name === 'Http2Error' || message.includes('HTTP/2') || message.includes('RST_STREAM') || message.includes('GOAWAY')) {
+        return {
+            category: 'protocol',
+            source: 'transport',
+            severity: 'medium',
+            canRetry: true,
+            reason: message || 'HTTP/2 protocol error'
+        };
+    }
+    if (name === 'MaxSizeExceededError' || name === 'ParseError') {
+        return {
+            category: 'resource',
+            source: 'server',
+            severity: 'low',
+            canRetry: false,
+            reason: message || 'Resource limitation'
+        };
+    }
+    if (name === 'ConfigurationError' || name === 'ValidationError' || name === 'StateError') {
+        return {
+            category: 'state',
+            source: 'client',
+            severity: 'high',
+            canRetry: false,
+            reason: message || 'Request cannot be retried'
+        };
+    }
+    return undefined;
+}
 export class MaxSizeExceededError extends ReckerError {
     maxSize;
     actualSize;
@@ -182,7 +289,13 @@ export class MaxSizeExceededError extends ReckerError {
             'Increase maxResponseSize if the larger payload is expected.',
             'Add pagination/streaming to reduce payload size.',
             'Ensure the upstream is not returning unexpected large responses.'
-        ], false);
+        ], false, {
+            category: 'resource',
+            source: 'server',
+            severity: 'medium',
+            canRetry: false,
+            reason: 'Response size exceeded configured max'
+        });
         this.name = 'MaxSizeExceededError';
         this.maxSize = maxSize;
         this.actualSize = actualSize;
@@ -198,7 +311,13 @@ export class AbortError extends ReckerError {
             'Check if the abort was intentional (user-triggered or timeout).',
             'Increase timeout if the request needs more time to complete.',
             'Ensure AbortController is not being triggered prematurely.'
-        ], true);
+        ], true, {
+            category: 'timeout',
+            source: 'client',
+            severity: 'low',
+            canRetry: true,
+            reason: reason ? `Request was aborted: ${reason}` : 'Request was aborted'
+        });
         this.name = 'AbortError';
         this.reason = reason;
     }
@@ -212,7 +331,13 @@ export class ConnectionError extends ReckerError {
             'Verify the host and port are correct and the service is running.',
             'Check network connectivity and firewall rules.',
             'Ensure the service is accepting connections on the specified port.'
-        ], options?.retriable ?? true);
+        ], options?.retriable ?? true, {
+            category: 'network',
+            source: 'transport',
+            severity: options?.retriable === false ? 'high' : 'medium',
+            canRetry: options?.retriable ?? true,
+            reason: options?.code ? `Connection error (${options.code})` : 'Connection error'
+        });
         this.name = 'ConnectionError';
         this.host = options?.host;
         this.port = options?.port;
@@ -370,7 +495,13 @@ export class QueueCancelledError extends ReckerError {
             'This is typically expected during shutdown.',
             'Check if the queue was manually cleared.',
             'Retry the operation if the queue is still active.'
-        ], true);
+        ], true, {
+            category: 'queue',
+            source: 'client',
+            severity: 'low',
+            canRetry: true,
+            reason: message || 'Queue was cancelled'
+        });
         this.name = 'QueueCancelledError';
         this.queueName = options?.queueName;
     }

package/dist/browser/core/request.d.ts

@@ -15,6 +15,11 @@ export declare class HttpRequest implements ReckerRequest {
     readonly followRedirects?: boolean;
     readonly http2?: boolean;
     readonly useCurl?: boolean;
+    readonly correlationId?: string;
+    readonly tenant?: string;
+    readonly policyTags: string[];
+    readonly policySource?: string;
+    readonly traceId?: string;
     constructor(url: string, options?: RequestOptions);
     withHeader(name: string, value: string): ReckerRequest;
     withBody(body: BodyInit): ReckerRequest;

package/dist/browser/core/request.js

@@ -1,3 +1,4 @@
+import { attachRequestContext, getRequestContext } from '../core-runtime/request-context.js';
 function normalizeTimeout(timeout) {
     if (timeout === undefined)
         return undefined;
@@ -22,6 +23,11 @@ export class HttpRequest {
     followRedirects;
     http2;
     useCurl;
+    correlationId;
+    tenant;
+    policyTags;
+    policySource;
+    traceId;
     constructor(url, options = {}) {
         this.url = url;
         this.method = options.method || 'GET';
@@ -40,11 +46,17 @@ export class HttpRequest {
         this.followRedirects = options.followRedirects;
         this.http2 = options.http2;
         this.useCurl = options.useCurl;
+        this.correlationId = options.correlationId;
+        this.tenant = options.tenant;
+        this.policyTags = options.policyTags ?? [];
+        this.policySource = options.policySource;
+        this.traceId = options.traceId;
     }
     withHeader(name, value) {
+        const context = getRequestContext(this);
         const newHeaders = new Headers(this.headers);
         newHeaders.set(name, value);
-        return new HttpRequest(this.url, {
+        const request = new HttpRequest(this.url, {
             method: this.method,
             headers: newHeaders,
             body: this.body,
@@ -59,10 +71,20 @@ export class HttpRequest {
             followRedirects: this.followRedirects,
             http2: this.http2,
             useCurl: this.useCurl,
+            correlationId: this.correlationId,
+            tenant: this.tenant,
+            policyTags: this.policyTags,
+            policySource: this.policySource,
+            traceId: this.traceId
         });
+        if (context) {
+            return attachRequestContext(request, context);
+        }
+        return request;
     }
     withBody(body) {
-        return new HttpRequest(this.url, {
+        const context = getRequestContext(this);
+        const request = new HttpRequest(this.url, {
             method: this.method,
             headers: this.headers,
             body: body,
@@ -77,6 +99,15 @@ export class HttpRequest {
             followRedirects: this.followRedirects,
             http2: this.http2,
             useCurl: this.useCurl,
+            correlationId: this.correlationId,
+            tenant: this.tenant,
+            policyTags: this.policyTags,
+            policySource: this.policySource,
+            traceId: this.traceId
         });
+        if (context) {
+            return attachRequestContext(request, context);
+        }
+        return request;
     }
 }

package/dist/browser/core-runtime/plugin-manifest.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from '../types/index.js';
+export type PluginScope = 'request' | 'protocol' | 'transport' | 'runtime';
+export interface PluginManifest {
+    name: string;
+    version: string;
+    scope: PluginScope;
+    priority: number;
+    dependsOn: string[];
+    setup?: string;
+    teardown?: string;
+}
+export interface PluginRegistration {
+    plugin: Plugin;
+    manifest: PluginManifest;
+    registrationIndex: number;
+}
+export declare function attachPluginManifest(plugin: Plugin, manifest: Partial<PluginManifest>): Plugin;
+export declare function normalizePluginManifest(plugin: Plugin, options?: Partial<PluginManifest>): PluginManifest;
+export declare function getPluginManifest(plugin: Plugin): PluginManifest | undefined;
+export declare function toSortedPlugins(plugins: Plugin[]): PluginRegistration[];
+export declare function normalizePlugins(registrations: PluginRegistration[]): {
+    ordered: PluginRegistration[];
+    debugOrder: string[];
+};

package/dist/browser/core-runtime/plugin-manifest.js

@@ -0,0 +1,159 @@
+const MANIFEST_KEY = '__reckerManifest';
+const DEFAULT_SCOPE = 'request';
+const DEFAULT_PRIORITY = 0;
+export function attachPluginManifest(plugin, manifest) {
+    plugin.__reckerManifest = normalizeManifest(plugin, manifest);
+    return plugin;
+}
+export function normalizePluginManifest(plugin, options = {}) {
+    return normalizeManifest(plugin, options);
+}
+export function getPluginManifest(plugin) {
+    return plugin.__reckerManifest;
+}
+function normalizeManifest(plugin, manifest) {
+    const pluginId = manifest?.name || inferPluginName(plugin);
+    return {
+        name: pluginId,
+        version: manifest?.version || '1',
+        scope: manifest?.scope || DEFAULT_SCOPE,
+        priority: manifest?.priority ?? DEFAULT_PRIORITY,
+        dependsOn: manifest?.dependsOn || [],
+        setup: manifest?.setup,
+        teardown: manifest?.teardown,
+    };
+}
+function inferPluginName(plugin) {
+    return plugin.name && plugin.name !== 'anonymous'
+        ? plugin.name
+        : `plugin-${Math.random().toString(16).slice(2, 10)}`;
+}
+function assertUniqueName(name, existing, source) {
+    if (existing.has(name)) {
+        throw new Error(`Invalid plugin manifest: duplicate plugin name '${name}'. ${source}`);
+    }
+    existing.add(name);
+}
+function buildDependencyError(path, target) {
+    return `${target} -> ${path.join(' -> ')} -> ${target}`;
+}
+function formatSortState(names) {
+    return names.join(' -> ');
+}
+export function toSortedPlugins(plugins) {
+    return plugins.map((plugin, registrationIndex) => ({
+        plugin,
+        manifest: normalizePluginManifest(plugin, getPluginManifest(plugin)),
+        registrationIndex
+    }));
+}
+export function normalizePlugins(registrations) {
+    const byName = new Map();
+    const seenNames = new Set();
+    registrations.forEach((entry) => {
+        const manifest = entry.manifest;
+        const name = manifest.name;
+        assertUniqueName(name, seenNames, 'Use explicit `manifest.name` to avoid collisions for anonymous plugin factories.');
+        byName.set(name, entry);
+    });
+    const edges = new Map();
+    const indegree = new Map();
+    registrations.forEach((entry) => {
+        const { name, dependsOn } = entry.manifest;
+        indegree.set(name, 0);
+        edges.set(name, new Set());
+        for (const dependency of dependsOn) {
+            if (!byName.has(dependency)) {
+                throw new Error(`Invalid plugin dependency for '${name}': missing plugin '${dependency}'. ` +
+                    'Available plugins: ' +
+                    Array.from(byName.keys()).sort().join(', '));
+            }
+            edges.get(dependency).add(name);
+            indegree.set(name, (indegree.get(name) || 0) + 1);
+        }
+    });
+    const queue = [];
+    byName.forEach((_entry, name) => {
+        if ((indegree.get(name) || 0) === 0) {
+            queue.push(name);
+        }
+    });
+    const ordered = [];
+    const nextReady = (names) => names.sort((a, b) => {
+        const aMeta = byName.get(a);
+        const bMeta = byName.get(b);
+        const priorityDiff = bMeta.manifest.priority - aMeta.manifest.priority;
+        if (priorityDiff !== 0) {
+            return priorityDiff;
+        }
+        return aMeta.registrationIndex - bMeta.registrationIndex;
+    });
+    while (queue.length > 0) {
+        const current = nextReady(queue).splice(0, 1)[0];
+        const index = queue.indexOf(current);
+        if (index >= 0) {
+            queue.splice(index, 1);
+        }
+        const currentEntry = byName.get(current);
+        if (!currentEntry) {
+            continue;
+        }
+        ordered.push(currentEntry);
+        const dependents = edges.get(current);
+        if (!dependents) {
+            continue;
+        }
+        for (const dependentName of dependents) {
+            const currentDegree = (indegree.get(dependentName) || 0) - 1;
+            indegree.set(dependentName, currentDegree);
+            if (currentDegree === 0) {
+                queue.push(dependentName);
+            }
+        }
+    }
+    if (ordered.length !== registrations.length) {
+        const unresolved = Array.from(indegree.entries())
+            .filter(([, degree]) => degree > 0)
+            .map(([name]) => name);
+        const cycle = detectCycle(unresolved, edges);
+        throw new Error('Invalid plugin manifest: circular dependency detected. ' +
+            `Unresolved nodes: ${formatSortState(unresolved)}. ` +
+            (cycle ? `Detected cycle: ${cycle}.` : 'Refactor dependency graph to a DAG.'));
+    }
+    const debugOrder = ordered.map((entry) => `${entry.manifest.name}:${entry.manifest.scope}:${entry.manifest.priority}`);
+    return { ordered, debugOrder };
+}
+function detectCycle(nodes, edges) {
+    const visited = new Set();
+    const inStack = new Set();
+    const dfs = (node, stack) => {
+        if (inStack.has(node)) {
+            const cycleStart = stack.indexOf(node);
+            if (cycleStart >= 0) {
+                return buildDependencyError(stack.slice(cycleStart), node);
+            }
+            return null;
+        }
+        if (visited.has(node)) {
+            return null;
+        }
+        visited.add(node);
+        inStack.add(node);
+        const nextNodes = edges.get(node) || new Set();
+        for (const next of nextNodes) {
+            const hit = dfs(next, [...stack, next]);
+            if (hit) {
+                return hit;
+            }
+        }
+        inStack.delete(node);
+        return null;
+    };
+    for (const node of nodes) {
+        const cycle = dfs(node, [node]);
+        if (cycle) {
+            return cycle;
+        }
+    }
+    return null;
+}

package/dist/browser/core-runtime/request-context.d.ts

@@ -0,0 +1,13 @@
+import type { ReckerRequest } from '../types/index.js';
+export interface RuntimeContext {
+    requestId: string;
+    correlationId: string;
+    tenant?: string;
+    policyTags: string[];
+    policySource?: string;
+    createdAt: number;
+    traceId?: string;
+}
+export declare function createRequestContext(seed?: Partial<RuntimeContext>): RuntimeContext;
+export declare function attachRequestContext<T extends ReckerRequest>(request: T, context: RuntimeContext): T;
+export declare function getRequestContext(request: ReckerRequest): RuntimeContext | undefined;

package/dist/browser/core-runtime/request-context.js

@@ -0,0 +1,24 @@
+let requestSeq = 0;
+export function createRequestContext(seed = {}) {
+    requestSeq += 1;
+    const requestId = `${Date.now().toString(36)}-${requestSeq.toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
+    return {
+        requestId,
+        correlationId: seed.correlationId || requestId,
+        tenant: seed.tenant,
+        policyTags: seed.policyTags ?? [],
+        policySource: seed.policySource,
+        createdAt: Date.now(),
+        traceId: seed.traceId
+    };
+}
+export function attachRequestContext(request, context) {
+    if (!request) {
+        return request;
+    }
+    request._runtime = context;
+    return request;
+}
+export function getRequestContext(request) {
+    return request._runtime;
+}

package/dist/browser/core-runtime/typed-events.d.ts

@@ -0,0 +1,89 @@
+import type { ReckerRequest, ReckerResponse } from '../types/index.js';
+import type { RuntimeContext } from './request-context.js';
+export type RuntimeEventName = 'request:start' | 'request:success' | 'request:failed' | 'request:retry' | 'request:policy' | 'policy:block' | 'circuit:trip' | 'cache:hit' | 'cache:miss' | 'cache:store' | 'security:block' | 'transport:start' | 'transport:finish' | 'transport:error';
+export interface RuntimeEventPayloads {
+    'request:start': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+    };
+    'request:success': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        res: ReckerResponse;
+        durationMs: number;
+    };
+    'request:failed': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        error: Error;
+        durationMs: number;
+    };
+    'request:retry': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    };
+    'request:policy': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        policy: string;
+        policySource?: string;
+        reason?: string;
+    };
+    'policy:block': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        policy: string;
+        reason: string;
+    };
+    'circuit:trip': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        key: string;
+        reason: string;
+    };
+    'cache:hit': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        cacheStatus: 'hit' | 'stale' | 'revalidated' | 'stale-error';
+    };
+    'cache:miss': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+    };
+    'cache:store': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        status: number;
+    };
+    'security:block': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        rule: string;
+        reason: string;
+    };
+    'transport:start': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+    };
+    'transport:finish': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        durationMs: number;
+    };
+    'transport:error': {
+        context: RuntimeContext;
+        req: ReckerRequest;
+        error: Error;
+    };
+}
+export interface TypedEventBus {
+    on<K extends RuntimeEventName>(name: K, handler: (event: RuntimeEventPayloads[K]) => void): () => void;
+    emit<K extends RuntimeEventName>(name: K, event: RuntimeEventPayloads[K]): void;
+}
+export declare function createNoopEventBus(): TypedEventBus;
+export declare function createRuntimeEventBus(options?: {
+    debugLogger?: (...args: any[]) => void;
+}): TypedEventBus;

package/dist/browser/core-runtime/typed-events.js

@@ -0,0 +1,34 @@
+export function createNoopEventBus() {
+    return {
+        on: () => () => undefined,
+        emit: () => undefined
+    };
+}
+export function createRuntimeEventBus(options = {}) {
+    const handlers = {};
+    const logger = options.debugLogger;
+    return {
+        on: (name, handler) => {
+            const bucket = (handlers[name] ||= new Set());
+            bucket.add(handler);
+            return () => {
+                bucket.delete(handler);
+                if (bucket.size === 0) {
+                    delete handlers[name];
+                }
+            };
+        },
+        emit: (name, event) => {
+            if (logger) {
+                logger(name, event);
+            }
+            const bucket = handlers[name];
+            if (!bucket || bucket.size === 0) {
+                return;
+            }
+            for (const handler of bucket) {
+                handler(event);
+            }
+        }
+    };
+}