@angular-helpers/worker-http 0.2.0 → 0.4.0

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

@@ -1,180 +1,152 @@
 /**
- * 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';
+ * Composes interceptor functions around a final handler, producing a single
+ * `(req) => Promise<resp>` chain. Pure — no side effects.
+ */
+function buildChain(fns, finalHandler) {
+    return fns.reduceRight((next, interceptor) => (req) => interceptor(req, next), finalHandler);
+}
+/**
+ * Performs the actual `fetch()` call inside the worker, translating the
+ * structured-clone-safe `SerializableRequest` into a `Request` and the
+ * `Response` back into a `SerializableResponse`.
  *
- * createWorkerPipeline([hmacSigningInterceptor]);
- * ```
+ * The optional `signal` allows the caller to wire up cancellation via an
+ * `AbortController` owned outside of this function.
  */
-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);
-            }
+async function executeFetch(req, signal) {
+    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);
-                }
+    }
+    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,
-        };
+        url += (url.includes('?') ? '&' : '?') + searchParams.toString();
+    }
+    const fetchInit = {
+        method: req.method,
+        headers,
+        credentials: req.withCredentials ? 'include' : 'same-origin',
+        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);
     }
-    function buildChain(fns, finalHandler) {
-        return fns.reduceRight((next, interceptor) => (req) => interceptor(req, next), finalHandler);
+    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();
     }
-    const chain = buildChain(interceptors, executeFetch);
+    return {
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+        body,
+        url: response.url,
+    };
+}
+
+/**
+ * Wires up the worker's `self.onmessage` handler around a built request chain.
+ *
+ * Owns the per-request `AbortController` map for cancellation support. Posts
+ * `response` / `error` messages back to the main thread.
+ *
+ * Returns a disposer that restores `self.onmessage` to whatever it was before
+ * (mainly useful for the configurable pipeline, which swaps the handler when
+ * receiving the init message).
+ */
+function attachRequestLoop(chain) {
+    const controllers = new Map();
+    const previous = self.onmessage;
     self.onmessage = async (event) => {
-        const { type, requestId, payload } = event.data;
+        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);
-            }
+        if (type !== 'request') {
+            return;
+        }
+        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);
         }
     };
+    return () => {
+        self.onmessage = previous;
+        for (const controller of controllers.values()) {
+            controller.abort();
+        }
+        controllers.clear();
+    };
 }
 
-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.
+ * Creates and registers a worker-side HTTP pipeline.
  *
- * Retries requests that fail with specific HTTP status codes.
- * Respects the `Retry-After` response header when present.
+ * 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.
+ *
+ * For a runtime-configurable variant whose chain is built from specs sent
+ * from the main thread, use `createConfigurableWorkerPipeline()` instead.
  *
  * @example
  * ```typescript
- * createWorkerPipeline([
- *   retryInterceptor({ maxRetries: 3, initialDelay: 500 }),
- * ]);
+ * // workers/secure.worker.ts
+ * import { createWorkerPipeline, hmacSigningInterceptor } from '@angular-helpers/worker-http/interceptors';
+ *
+ * createWorkerPipeline([hmacSigningInterceptor({ keyMaterial })]);
  * ```
  */
-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;
-            }
-        }
-    };
+function createWorkerPipeline(interceptors) {
+    const chain = buildChain(interceptors, (req) => executeFetch(req));
+    attachRequestLoop(chain);
 }
 
 /**
@@ -227,8 +199,68 @@ function cacheInterceptor(config) {
 function arrayBufferToHex$1(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$1(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;
+    };
+}
+
+function arrayBufferToHex(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) : '';
+    const body = req.body !== null && req.body !== undefined ? JSON.stringify(req.body) : '';
     return `${req.method}:${req.url}:${body}`;
 }
 /**
@@ -267,7 +299,7 @@ function hmacSigningInterceptor(config) {
         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 signatureHex = arrayBufferToHex(signatureBuffer);
         const signedReq = {
             ...req,
             headers: {
@@ -315,7 +347,7 @@ function loggingInterceptor(config) {
         catch (error) {
             const elapsedMs = Date.now() - startMs;
             const status = error.status;
-            const label = status != null ? String(status) : 'NETWORK_ERROR';
+            const label = status !== null && status !== undefined ? String(status) : 'NETWORK_ERROR';
             safeLog(`[worker] ✕ ${label} ${req.url} (${elapsedMs}ms)`, error);
             throw error;
         }
@@ -356,64 +388,180 @@ function rateLimitInterceptor(config) {
     };
 }
 
-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();
+function parseRetryAfterMs(headerValue) {
+    const seconds = parseFloat(headerValue);
+    if (!isNaN(seconds)) {
+        return Math.max(0, seconds * 1000);
     }
-    else {
-        const str = typeof body === 'string' ? body : (JSON.stringify(body) ?? '');
-        data = new TextEncoder().encode(str).buffer;
+    const date = new Date(headerValue).getTime();
+    if (!isNaN(date)) {
+        return Math.max(0, date - Date.now());
     }
-    const hash = await crypto.subtle.digest(algorithm, data);
-    return arrayBufferToHex(hash);
+    return 0;
 }
-function getHeaderValue(response, headerName) {
-    const lower = headerName.toLowerCase();
-    return response.headers[lower]?.[0] ?? response.headers[headerName]?.[0];
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Creates a content integrity interceptor that verifies response body integrity
- * against a hash provided in a response header.
+ * Creates a retry interceptor with exponential backoff.
  *
- * Uses WebCrypto `SubtleCrypto` (native in web workers).
+ * Retries requests that fail with specific HTTP status codes.
+ * Respects the `Retry-After` response header when present.
  *
  * @example
  * ```typescript
  * createWorkerPipeline([
- *   contentIntegrityInterceptor({
- *     algorithm: 'SHA-256',
- *     headerName: 'X-Content-Hash',
- *     requireHash: true,
- *   }),
+ *   retryInterceptor({ maxRetries: 3, initialDelay: 500 }),
  * ]);
  * ```
  */
-function contentIntegrityInterceptor(config) {
-    const algorithm = config?.algorithm ?? 'SHA-256';
-    const headerName = config?.headerName ?? 'X-Content-Hash';
-    const requireHash = config?.requireHash ?? false;
+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) => {
-        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 });
+        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;
             }
-            return response;
         }
-        const actualHash = await hashBody(response.body, algorithm);
-        if (actualHash !== expectedHash.toLowerCase()) {
-            throw Object.assign(new Error('Content integrity check failed'), { status: 0 });
+    };
+}
+
+const INIT_MESSAGE_TYPE = 'init-interceptors';
+const customRegistry = new Map();
+/**
+ * Registers a custom interceptor factory that can be referenced from
+ * `withWorkerInterceptors([workerCustom('my-name', config)])`.
+ *
+ * Must be called inside the worker file BEFORE `createConfigurableWorkerPipeline()`.
+ *
+ * @example
+ * ```typescript
+ * // app.worker.ts
+ * import { createConfigurableWorkerPipeline, registerInterceptor } from '@angular-helpers/worker-http/interceptors';
+ *
+ * registerInterceptor('auth-token', (config: { token: string }) => async (req, next) => {
+ *   const headers = { ...req.headers, authorization: [`Bearer ${config.token}`] };
+ *   return next({ ...req, headers });
+ * });
+ *
+ * createConfigurableWorkerPipeline();
+ * ```
+ */
+function registerInterceptor(name, factory) {
+    customRegistry.set(name, factory);
+}
+/** Test-only: clears the custom registry. */
+function __clearCustomRegistry() {
+    customRegistry.clear();
+}
+/**
+ * Resolves a single spec to its concrete `WorkerInterceptorFn`.
+ *
+ * Exported for test use. Throws on unknown `kind` or unregistered custom name
+ * so misconfiguration fails loudly at init time, not on the first request.
+ */
+function resolveSpec(spec) {
+    switch (spec.kind) {
+        case 'logging':
+            return loggingInterceptor(spec.config);
+        case 'retry':
+            return retryInterceptor(spec.config);
+        case 'cache':
+            return cacheInterceptor(spec.config);
+        case 'hmac-signing':
+            return hmacSigningInterceptor(spec.config);
+        case 'rate-limit':
+            return rateLimitInterceptor(spec.config);
+        case 'content-integrity':
+            return contentIntegrityInterceptor(spec.config);
+        case 'custom': {
+            const factory = customRegistry.get(spec.name);
+            if (!factory) {
+                throw new Error(`[worker-http] Custom interceptor "${spec.name}" was not registered. ` +
+                    `Call registerInterceptor("${spec.name}", factory) in your worker file before createConfigurableWorkerPipeline().`);
+            }
+            return factory(spec.config);
+        }
+        default: {
+            const exhaustive = spec;
+            throw new Error(`[worker-http] Unknown interceptor spec kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Creates a worker-side pipeline whose interceptor chain is supplied at
+ * runtime via the init handshake message sent by `WorkerHttpBackend`.
+ *
+ * Behavior:
+ *  - Listens for the first `init-interceptors` message and builds the chain
+ *    from the received specs.
+ *  - Until init arrives, incoming `request` messages are buffered (they will
+ *    be flushed once the chain is ready).
+ *  - If no init arrives (e.g. worker used standalone without
+ *    `withWorkerInterceptors`), the pipeline runs with an empty chain so
+ *    every request goes straight to `fetch()`.
+ *
+ * Custom interceptor factories must be registered with
+ * `registerInterceptor(name, factory)` before this call.
+ */
+function createConfigurableWorkerPipeline() {
+    const pending = [];
+    const initialHandler = (event) => {
+        const data = event.data ?? {};
+        if (data.type === INIT_MESSAGE_TYPE) {
+            const specs = data.specs ?? [];
+            const fns = specs.map((spec) => resolveSpec(spec));
+            const chain = buildChain(fns, (req) => executeFetch(req));
+            // Swap to the regular request loop and replay any buffered messages.
+            attachRequestLoop(chain);
+            const handler = self.onmessage;
+            if (handler) {
+                for (const buffered of pending) {
+                    handler.call(self, buffered);
+                }
+            }
+            pending.length = 0;
+            return;
+        }
+        if (data.type === 'request' || data.type === 'cancel') {
+            pending.push(event);
         }
-        return response;
     };
+    self.onmessage = initialHandler;
+    // Safety net: if the main thread never sends init within a microtask,
+    // the worker still works as a no-interceptor pipeline. We DO NOT trigger
+    // this immediately — the init arrives via postMessage which is queued, so
+    // we let the buffered messages accumulate until init or the first non-init
+    // message after a tick. The transport guarantees init is posted first, so
+    // in practice the empty-chain path is only hit when the worker is used
+    // without withWorkerInterceptors.
 }
 
 /**
@@ -446,8 +594,41 @@ function composeInterceptors(...fns) {
     };
 }
 
+/**
+ * Spec builders — pure factories that return POJO `WorkerInterceptorSpec`
+ * objects suitable for `withWorkerInterceptors([...])`.
+ *
+ * Each builder mirrors the corresponding worker-side interceptor factory but
+ * accepts only serializable config (no function fields).
+ */
+function workerLogging(config) {
+    return { kind: 'logging', config };
+}
+function workerRetry(config) {
+    return { kind: 'retry', config };
+}
+function workerCache(config) {
+    return { kind: 'cache', config };
+}
+function workerHmacSigning(config) {
+    return { kind: 'hmac-signing', config };
+}
+function workerRateLimit(config) {
+    return { kind: 'rate-limit', config };
+}
+function workerContentIntegrity(config) {
+    return { kind: 'content-integrity', config };
+}
+/**
+ * Reference a custom interceptor that has been registered on the worker side
+ * via `registerInterceptor(name, factory)`.
+ */
+function workerCustom(name, config) {
+    return { kind: 'custom', name, config };
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { cacheInterceptor, composeInterceptors, contentIntegrityInterceptor, createWorkerPipeline, hmacSigningInterceptor, loggingInterceptor, rateLimitInterceptor, retryInterceptor };
+export { cacheInterceptor, composeInterceptors, contentIntegrityInterceptor, createConfigurableWorkerPipeline, createWorkerPipeline, hmacSigningInterceptor, loggingInterceptor, rateLimitInterceptor, registerInterceptor, resolveSpec, retryInterceptor, workerCache, workerContentIntegrity, workerCustom, workerHmacSigning, workerLogging, workerRateLimit, workerRetry };

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

@@ -43,6 +43,9 @@ function createWorkerTransport(config) {
     function getOrCreateWorker() {
         if (workers.length < maxInstances) {
             const worker = createWorker();
+            if (config.initMessage) {
+                worker.postMessage(config.initMessage);
+            }
             workers.push(worker);
             return worker;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/worker-http",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Angular HTTP over Web Workers — off-main-thread HTTP pipelines with configurable interceptors, WebCrypto security, and pluggable serialization",
   "keywords": [
     "angular",