@angular-helpers/worker-http 0.2.0

package/fesm2022/angular-helpers-worker-http-interceptors.mjs

@@ -0,0 +1,453 @@
+/**
+ * Creates and registers a worker-side HTTP pipeline.
+ *
+ * Call this inside a worker file to set up the interceptor chain.
+ * The pipeline listens for incoming requests via `postMessage`,
+ * runs them through the interceptor chain, executes `fetch()`,
+ * and sends the response back.
+ *
+ * @example
+ * ```typescript
+ * // workers/secure.worker.ts
+ * import { createWorkerPipeline } from '@angular-helpers/worker-http/interceptors';
+ * import { hmacSigningInterceptor } from './my-interceptors';
+ *
+ * createWorkerPipeline([hmacSigningInterceptor]);
+ * ```
+ */
+function createWorkerPipeline(interceptors) {
+    const controllers = new Map();
+    async function executeFetch(req) {
+        const controller = controllers.get(req.url) ?? new AbortController();
+        const headers = new Headers();
+        for (const [key, values] of Object.entries(req.headers)) {
+            for (const value of values) {
+                headers.append(key, value);
+            }
+        }
+        let url = req.url;
+        const paramEntries = Object.entries(req.params);
+        if (paramEntries.length > 0) {
+            const searchParams = new URLSearchParams();
+            for (const [key, values] of paramEntries) {
+                for (const value of values) {
+                    searchParams.append(key, value);
+                }
+            }
+            url += (url.includes('?') ? '&' : '?') + searchParams.toString();
+        }
+        const fetchInit = {
+            method: req.method,
+            headers,
+            credentials: req.withCredentials ? 'include' : 'same-origin',
+            signal: controller.signal,
+        };
+        if (req.body !== null &&
+            req.body !== undefined &&
+            req.method !== 'GET' &&
+            req.method !== 'HEAD') {
+            fetchInit.body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+        }
+        const response = await fetch(url, fetchInit);
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = responseHeaders[key] ?? [];
+            responseHeaders[key].push(value);
+        });
+        let body;
+        switch (req.responseType) {
+            case 'text':
+                body = await response.text();
+                break;
+            case 'arraybuffer':
+                body = await response.arrayBuffer();
+                break;
+            case 'blob':
+                body = await response.blob();
+                break;
+            default:
+                body = await response.json();
+        }
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+            body,
+            url: response.url,
+        };
+    }
+    function buildChain(fns, finalHandler) {
+        return fns.reduceRight((next, interceptor) => (req) => interceptor(req, next), finalHandler);
+    }
+    const chain = buildChain(interceptors, executeFetch);
+    self.onmessage = async (event) => {
+        const { type, requestId, payload } = event.data;
+        if (type === 'cancel') {
+            controllers.get(requestId)?.abort();
+            controllers.delete(requestId);
+            return;
+        }
+        if (type === 'request') {
+            const controller = new AbortController();
+            controllers.set(requestId, controller);
+            try {
+                const response = await chain(payload);
+                self.postMessage({ type: 'response', requestId, result: response });
+            }
+            catch (error) {
+                self.postMessage({
+                    type: 'error',
+                    requestId,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                        name: error instanceof Error ? error.name : 'UnknownError',
+                        stack: error instanceof Error ? error.stack : undefined,
+                    },
+                });
+            }
+            finally {
+                controllers.delete(requestId);
+            }
+        }
+    };
+}
+
+function parseRetryAfterMs(headerValue) {
+    const seconds = parseFloat(headerValue);
+    if (!isNaN(seconds)) {
+        return Math.max(0, seconds * 1000);
+    }
+    const date = new Date(headerValue).getTime();
+    if (!isNaN(date)) {
+        return Math.max(0, date - Date.now());
+    }
+    return 0;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Creates a retry interceptor with exponential backoff.
+ *
+ * Retries requests that fail with specific HTTP status codes.
+ * Respects the `Retry-After` response header when present.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   retryInterceptor({ maxRetries: 3, initialDelay: 500 }),
+ * ]);
+ * ```
+ */
+function retryInterceptor(config) {
+    const maxRetries = config?.maxRetries ?? 3;
+    const initialDelay = config?.initialDelay ?? 1000;
+    const backoffMultiplier = config?.backoffMultiplier ?? 2;
+    const retryStatusCodes = config?.retryStatusCodes ?? [408, 429, 500, 502, 503, 504];
+    const retryOnNetworkError = config?.retryOnNetworkError ?? true;
+    return async (req, next) => {
+        let attempt = 0;
+        while (true) {
+            try {
+                const response = await next(req);
+                if (maxRetries > 0 && retryStatusCodes.includes(response.status)) {
+                    if (attempt < maxRetries) {
+                        const retryAfterHeader = response.headers['retry-after']?.[0] ?? response.headers['Retry-After']?.[0];
+                        const waitMs = retryAfterHeader
+                            ? parseRetryAfterMs(retryAfterHeader)
+                            : initialDelay * Math.pow(backoffMultiplier, attempt);
+                        await delay(waitMs);
+                        attempt++;
+                        continue;
+                    }
+                    throw Object.assign(new Error(`Max retries exceeded after ${maxRetries} attempt(s) (status: ${response.status})`), { status: response.status });
+                }
+                return response;
+            }
+            catch (error) {
+                if (retryOnNetworkError && attempt < maxRetries) {
+                    const waitMs = initialDelay * Math.pow(backoffMultiplier, attempt);
+                    await delay(waitMs);
+                    attempt++;
+                    continue;
+                }
+                throw error;
+            }
+        }
+    };
+}
+
+/**
+ * Creates a cache interceptor that stores responses in worker memory.
+ *
+ * Caches GET responses by default (configurable). Evicts oldest entry
+ * when `maxEntries` is reached (insertion-order eviction).
+ * Each factory call creates an independent cache instance.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   cacheInterceptor({ ttl: 30000, maxEntries: 50 }),
+ * ]);
+ * ```
+ */
+function cacheInterceptor(config) {
+    const ttl = config?.ttl ?? 60_000;
+    const maxEntries = config?.maxEntries ?? 100;
+    const methods = config?.methods ?? ['GET'];
+    const cache = new Map();
+    return async (req, next) => {
+        if (!methods.includes(req.method.toUpperCase())) {
+            return next(req);
+        }
+        if (ttl === 0) {
+            return next(req);
+        }
+        const cacheKey = `${req.method.toUpperCase()}:${req.url}`;
+        const now = Date.now();
+        const cached = cache.get(cacheKey);
+        if (cached && cached.expiresAt > now) {
+            return cached.response;
+        }
+        if (cached) {
+            cache.delete(cacheKey);
+        }
+        const response = await next(req);
+        if (cache.size >= maxEntries) {
+            const firstKey = cache.keys().next().value;
+            if (firstKey !== undefined) {
+                cache.delete(firstKey);
+            }
+        }
+        cache.set(cacheKey, { response, expiresAt: now + ttl });
+        return response;
+    };
+}
+
+function arrayBufferToHex$1(buffer) {
+    return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+function defaultPayloadBuilder(req) {
+    const body = req.body != null ? JSON.stringify(req.body) : '';
+    return `${req.method}:${req.url}:${body}`;
+}
+/**
+ * Creates an HMAC signing interceptor that adds a signature header to outgoing requests.
+ *
+ * Uses WebCrypto `SubtleCrypto` (native in web workers). The `CryptoKey` is
+ * imported lazily on the first request and reused for all subsequent requests
+ * in the same factory instance.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   hmacSigningInterceptor({
+ *     keyMaterial: new TextEncoder().encode('my-secret-key'),
+ *     algorithm: 'SHA-256',
+ *     headerName: 'X-HMAC-Signature',
+ *   }),
+ * ]);
+ * ```
+ */
+function hmacSigningInterceptor(config) {
+    const algorithm = config.algorithm ?? 'SHA-256';
+    const headerName = config.headerName ?? 'X-HMAC-Signature';
+    const payloadBuilder = config.payloadBuilder ?? defaultPayloadBuilder;
+    let cryptoKeyPromise = null;
+    function getCryptoKey() {
+        if (!cryptoKeyPromise) {
+            const keyMaterial = config.keyMaterial instanceof Uint8Array
+                ? config.keyMaterial
+                : new Uint8Array(config.keyMaterial);
+            cryptoKeyPromise = crypto.subtle.importKey('raw', keyMaterial, { name: 'HMAC', hash: algorithm }, false, ['sign']);
+        }
+        return cryptoKeyPromise;
+    }
+    return async (req, next) => {
+        const key = await getCryptoKey();
+        const payload = payloadBuilder(req);
+        const signatureBuffer = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload));
+        const signatureHex = arrayBufferToHex$1(signatureBuffer);
+        const signedReq = {
+            ...req,
+            headers: {
+                ...req.headers,
+                [headerName]: [signatureHex],
+            },
+        };
+        return next(signedReq);
+    };
+}
+
+/**
+ * Creates a logging interceptor that logs request and response details.
+ *
+ * Uses `console.log` by default. A custom logger can be provided via config.
+ * Logger exceptions are swallowed — a logging failure never interrupts the pipeline.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   loggingInterceptor({ includeHeaders: true }),
+ * ]);
+ * ```
+ */
+function loggingInterceptor(config) {
+    const logger = config?.logger ?? ((msg, data) => console.log(msg, data));
+    const includeHeaders = config?.includeHeaders ?? false;
+    function safeLog(message, data) {
+        try {
+            logger(message, data);
+        }
+        catch {
+            // swallow — logger must never break the pipeline
+        }
+    }
+    return async (req, next) => {
+        const startMs = Date.now();
+        safeLog(`[worker] → ${req.method} ${req.url}`, includeHeaders ? { headers: req.headers } : undefined);
+        try {
+            const response = await next(req);
+            const elapsedMs = Date.now() - startMs;
+            safeLog(`[worker] ← ${response.status} ${req.url} (${elapsedMs}ms)`, includeHeaders ? { headers: response.headers } : undefined);
+            return response;
+        }
+        catch (error) {
+            const elapsedMs = Date.now() - startMs;
+            const status = error.status;
+            const label = status != null ? String(status) : 'NETWORK_ERROR';
+            safeLog(`[worker] ✕ ${label} ${req.url} (${elapsedMs}ms)`, error);
+            throw error;
+        }
+    };
+}
+
+/**
+ * Creates a client-side rate limiting interceptor using a sliding window algorithm.
+ *
+ * Tracks request timestamps within the configured window. When the limit is
+ * exceeded, throws an error with status 429. State is per-factory-instance
+ * (resets when the worker is terminated).
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   rateLimitInterceptor({ maxRequests: 10, windowMs: 5000 }),
+ * ]);
+ * ```
+ */
+function rateLimitInterceptor(config) {
+    const maxRequests = config?.maxRequests ?? 100;
+    const windowMs = config?.windowMs ?? 60_000;
+    const timestamps = [];
+    return async (req, next) => {
+        const now = Date.now();
+        const windowStart = now - windowMs;
+        let i = 0;
+        while (i < timestamps.length && timestamps[i] < windowStart) {
+            i++;
+        }
+        timestamps.splice(0, i);
+        if (timestamps.length >= maxRequests) {
+            throw Object.assign(new Error('Rate limit exceeded'), { status: 429 });
+        }
+        timestamps.push(now);
+        return next(req);
+    };
+}
+
+function arrayBufferToHex(buffer) {
+    return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+async function hashBody(body, algorithm) {
+    let data;
+    if (body instanceof ArrayBuffer) {
+        data = body;
+    }
+    else if (body instanceof Blob) {
+        data = await body.arrayBuffer();
+    }
+    else {
+        const str = typeof body === 'string' ? body : (JSON.stringify(body) ?? '');
+        data = new TextEncoder().encode(str).buffer;
+    }
+    const hash = await crypto.subtle.digest(algorithm, data);
+    return arrayBufferToHex(hash);
+}
+function getHeaderValue(response, headerName) {
+    const lower = headerName.toLowerCase();
+    return response.headers[lower]?.[0] ?? response.headers[headerName]?.[0];
+}
+/**
+ * Creates a content integrity interceptor that verifies response body integrity
+ * against a hash provided in a response header.
+ *
+ * Uses WebCrypto `SubtleCrypto` (native in web workers).
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   contentIntegrityInterceptor({
+ *     algorithm: 'SHA-256',
+ *     headerName: 'X-Content-Hash',
+ *     requireHash: true,
+ *   }),
+ * ]);
+ * ```
+ */
+function contentIntegrityInterceptor(config) {
+    const algorithm = config?.algorithm ?? 'SHA-256';
+    const headerName = config?.headerName ?? 'X-Content-Hash';
+    const requireHash = config?.requireHash ?? false;
+    return async (req, next) => {
+        const response = await next(req);
+        const expectedHash = getHeaderValue(response, headerName);
+        if (!expectedHash) {
+            if (requireHash) {
+                throw Object.assign(new Error(`Content integrity header '${headerName}' is required but missing`), { status: 0 });
+            }
+            return response;
+        }
+        const actualHash = await hashBody(response.body, algorithm);
+        if (actualHash !== expectedHash.toLowerCase()) {
+            throw Object.assign(new Error('Content integrity check failed'), { status: 0 });
+        }
+        return response;
+    };
+}
+
+/**
+ * Composes multiple worker interceptors into a single `WorkerInterceptorFn`.
+ *
+ * Interceptors are executed left-to-right, matching Angular's interceptor chain convention.
+ * Each interceptor calls `next()` to pass control to the next one.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = composeInterceptors(
+ *   loggingInterceptor(),
+ *   retryInterceptor({ maxRetries: 2 }),
+ *   hmacSigningInterceptor({ keyMaterial: key }),
+ * );
+ *
+ * createWorkerPipeline([pipeline]);
+ * ```
+ */
+function composeInterceptors(...fns) {
+    if (fns.length === 0) {
+        return (_req, next) => next(_req);
+    }
+    if (fns.length === 1) {
+        return fns[0];
+    }
+    return (req, finalNext) => {
+        const chain = fns.reduceRight((next, interceptor) => (r) => interceptor(r, next), (r) => finalNext(r));
+        return chain(req);
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { cacheInterceptor, composeInterceptors, contentIntegrityInterceptor, createWorkerPipeline, hmacSigningInterceptor, loggingInterceptor, rateLimitInterceptor, retryInterceptor };

package/fesm2022/angular-helpers-worker-http-serializer.mjs

@@ -0,0 +1,180 @@
+/**
+ * Default serializer that relies on the browser's native structured clone algorithm.
+ * Zero overhead — data is passed directly to postMessage without transformation.
+ *
+ * Best for: small payloads (< 100 KiB), simple types.
+ * Limitations: cannot handle functions, DOM nodes, or class instances with prototype chains.
+ */
+const structuredCloneSerializer = {
+    serialize(data) {
+        return {
+            data,
+            transferables: [],
+            format: 'structured-clone',
+        };
+    },
+    deserialize(payload) {
+        return payload.data;
+    },
+};
+
+let cachedSeroval = null;
+async function loadSeroval() {
+    if (!cachedSeroval) {
+        try {
+            // Dynamic import via variable — keeps seroval as optional peer dep (no static reference)
+            const id = 'seroval';
+            cachedSeroval = (await import(/* @vite-ignore */ id));
+        }
+        catch {
+            throw new Error('seroval is required as a peer dependency. Install it with: npm install seroval');
+        }
+    }
+    return cachedSeroval;
+}
+/**
+ * Creates a `WorkerSerializer` backed by `seroval` for full type fidelity.
+ *
+ * Supports `Date`, `Map`, `Set`, `BigInt`, `RegExp`, circular references, and more.
+ * The factory is async because it dynamically imports the optional `seroval` peer.
+ *
+ * `seroval` must be installed separately:
+ * ```
+ * npm install seroval
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const serializer = await createSerovalSerializer();
+ * const payload = serializer.serialize({ date: new Date(), map: new Map() });
+ * const original = serializer.deserialize(payload);
+ * ```
+ *
+ * @see https://github.com/lxsmnsyc/seroval
+ */
+async function createSerovalSerializer() {
+    const { serialize, deserialize } = await loadSeroval();
+    return {
+        serialize(data) {
+            return {
+                data: serialize(data),
+                transferables: [],
+                format: 'seroval',
+            };
+        },
+        deserialize(payload) {
+            if (payload.format !== 'seroval') {
+                throw new Error(`Expected format 'seroval', got '${payload.format}'`);
+            }
+            return deserialize(payload.data);
+        },
+    };
+}
+
+/**
+ * Shallow check for complex types at depth-1 that structured-clone cannot preserve.
+ * Depth-1 is intentional: fast and predictable. For deeply nested complex types,
+ * use `withWorkerSerialization(await createSerovalSerializer())` explicitly.
+ */
+function hasComplexType(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    if (value instanceof Date ||
+        value instanceof Map ||
+        value instanceof Set ||
+        value instanceof RegExp) {
+        return true;
+    }
+    const items = Array.isArray(value) ? value : Object.values(value);
+    for (const item of items) {
+        if (item instanceof Date ||
+            item instanceof Map ||
+            item instanceof Set ||
+            item instanceof RegExp) {
+            return true;
+        }
+    }
+    return false;
+}
+function encodeToTransferable(str) {
+    const buffer = new TextEncoder().encode(str).buffer;
+    return { data: buffer, transferables: [buffer] };
+}
+/**
+ * Creates an auto-detecting `WorkerSerializer` that picks the best strategy per payload.
+ *
+ * The factory is async because it pre-loads `seroval` during initialization
+ * so the returned serializer methods are fully synchronous (no await in hot path).
+ *
+ * Strategy selection per `serialize()` call:
+ * - Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
+ * - Otherwise → structured clone (native, zero overhead)
+ *
+ * Large payloads (> `transferThreshold`, default 100 KiB) are encoded to
+ * `ArrayBuffer` and added to `transferables` for zero-copy `postMessage` transfer.
+ *
+ * @example
+ * ```typescript
+ * const auto = await createAutoSerializer();
+ * const payload = auto.serialize({ users, fetchedAt: new Date() });
+ * worker.postMessage({ payload }, payload.transferables);
+ * ```
+ */
+async function createAutoSerializer(config) {
+    const transferThreshold = config?.transferThreshold ?? 102_400;
+    let sv = null;
+    try {
+        sv = await createSerovalSerializer();
+    }
+    catch {
+        // seroval not installed — complex types will throw at serialize time with a clear message
+    }
+    return {
+        serialize(data) {
+            let payload;
+            if (hasComplexType(data)) {
+                if (!sv) {
+                    throw new Error('seroval is required to serialize complex types (Date, Map, Set, RegExp). ' +
+                        'Install it with: npm install seroval');
+                }
+                payload = sv.serialize(data);
+            }
+            else {
+                payload = structuredCloneSerializer.serialize(data);
+            }
+            if (payload.transferables.length === 0 && typeof payload.data === 'string') {
+                const approxBytes = payload.data.length * 2;
+                if (approxBytes > transferThreshold) {
+                    const { data: buffer, transferables } = encodeToTransferable(payload.data);
+                    return { data: buffer, transferables, format: payload.format };
+                }
+            }
+            return payload;
+        },
+        deserialize(payload) {
+            let resolved = payload;
+            if (payload.data instanceof ArrayBuffer) {
+                const str = new TextDecoder().decode(payload.data);
+                resolved = { ...payload, data: str };
+            }
+            if (resolved.format === 'structured-clone') {
+                return structuredCloneSerializer.deserialize(resolved);
+            }
+            if (resolved.format === 'seroval') {
+                if (!sv) {
+                    throw new Error('seroval is required to deserialize this payload. ' +
+                        'Install it with: npm install seroval');
+                }
+                return sv.deserialize(resolved);
+            }
+            throw new Error(`Unknown serialization format: '${resolved.format}'`);
+        },
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { createAutoSerializer, createSerovalSerializer, structuredCloneSerializer };