@angular-helpers/worker-http 0.3.0 → 0.4.0

package/README.md

@@ -325,8 +325,10 @@ import {
   withWorkerRoutes,
   withWorkerFallback,
   withWorkerSerialization,
+  withWorkerInterceptors,
 } from '@angular-helpers/worker-http/backend';
 import { createSerovalSerializer } from '@angular-helpers/worker-http/serializer';
+import { workerLogging, workerRetry, workerCache } from '@angular-helpers/worker-http/interceptors';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -348,6 +350,11 @@ export const appConfig: ApplicationConfig = {
       ]),
       withWorkerFallback('main-thread'), // SSR-safe
       withWorkerSerialization(createSerovalSerializer()), // optional: complex bodies
+      withWorkerInterceptors([
+        workerLogging(),
+        workerRetry({ maxRetries: 3 }),
+        workerCache({ ttl: 60000 }),
+      ]),
     ),
   ],
 };
@@ -367,20 +374,23 @@ export class DataService {
 }
 
 // workers/api.worker.ts — runs on a separate OS thread
-import {
-  createWorkerPipeline,
-  loggingInterceptor,
-  retryInterceptor,
-  cacheInterceptor,
-} from '@angular-helpers/worker-http/interceptors';
-
-createWorkerPipeline([
-  loggingInterceptor(),
-  retryInterceptor({ maxRetries: 3 }),
-  cacheInterceptor({ ttl: 60000 }),
-]);
+import { createConfigurableWorkerPipeline } from '@angular-helpers/worker-http/interceptors';
+
+// The pipeline is built at runtime from the specs configured via
+// `withWorkerInterceptors([...])` in `app.config.ts`. Custom interceptors
+// not covered by the built-in catalogue can be wired in here:
+//
+//   import { registerInterceptor } from '@angular-helpers/worker-http/interceptors';
+//   registerInterceptor('auth-token', (config) => async (req, next) => { ... });
+//
+// then referenced from the main thread with `workerCustom('auth-token', config)`.
+createConfigurableWorkerPipeline();
 ```
 
+If you prefer to keep the pipeline composition inside the worker file, use
+`createWorkerPipeline([interceptors])` instead — it stays available for full
+manual control.
+
 **Features:**
 
 - `provideWorkerHttpClient(...features)` — replaces `provideHttpClient()`; do not use both
@@ -388,6 +398,7 @@ createWorkerPipeline([
 - `withWorkerRoutes(routes)` — URL-pattern routing with priority ordering
 - `withWorkerFallback(strategy)` — `'main-thread'` (SSR-safe) or `'error'`
 - `withWorkerSerialization(serializer)` — plug in `createSerovalSerializer()` for complex request bodies (`Date`, `Map`, `Set`)
+- `withWorkerInterceptors(specs | specsByWorker)` — configure the worker-side pipeline from Angular DI; pairs with `createConfigurableWorkerPipeline()` in the worker file
 - `WORKER_TARGET` — `HttpContextToken<string | null>` for per-request worker routing via `HttpContext`
 - `WorkerHttpClient` — `HttpClient` wrapper with optional `{ worker: string }` routing field
 - `WorkerHttpBackend` — the `HttpBackend` implementation (injectable for advanced use)
@@ -429,6 +440,48 @@ Server-Side Rendering (SSR) is supported via automatic fallback to the main thre
 
 ---
 
+## Benchmarks
+
+A reproducible benchmark suite ships with the demo app at
+[`/demo/worker-http-benchmark`](../../src/app/demo/worker-http-benchmark) and compares three
+transport modes across four workloads:
+
+| Mode            | What it measures                                           |
+| --------------- | ---------------------------------------------------------- |
+| `main-thread`   | Baseline — the same simulated work runs on the main thread |
+| `worker-pool-1` | Single worker — measures pure transport overhead           |
+| `worker-pool-4` | Four workers — measures the benefit of parallel dispatch   |
+
+Each scenario simulates identical "server" work (synchronous CPU burn + async delay + payload
+generation), so the only variable being compared is **where** the work runs.
+
+**Workloads**:
+
+- 100 small sequential requests — pure transport overhead
+- 1 large response (10MB) — serialization / structured clone cost
+- 50 parallel requests — pool benefit
+- 20 parallel requests + 500ms main-thread CPU burn — real-world jank case
+
+**Metrics collected**:
+
+- **Long Tasks** (`PerformanceObserver` / `longtask`) — count and total duration (Chromium-only)
+- **Dropped frames** (`requestAnimationFrame` deltas > 25 ms) — visible jank proxy, works in every browser
+- **Wall-clock total** for the scenario
+- **Success / failure** counts
+
+To run locally:
+
+```bash
+npm run build:workers
+npm start
+# open https://localhost:4200/demo/worker-http-benchmark
+```
+
+Numbers vary by hardware, browser, and current system load — always run a scenario several times
+and watch the trend, not a single value.
+
+---
+
 ## Related documentation
 
 - [Architecture & Feasibility Study](../../docs/sdd-angular-http-web-workers.md)

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

@@ -48,6 +48,11 @@ const WORKER_HTTP_FALLBACK_TOKEN = new InjectionToken('WorkerHttpFallback', { fa
  * serialized form — add a worker interceptor to deserialize it if needed.
  */
 const WORKER_HTTP_SERIALIZER_TOKEN = new InjectionToken('WorkerHttpSerializer', { factory: () => null });
+/**
+ * Per-worker interceptor specs provided via `withWorkerInterceptors()`.
+ * Defaults to an empty map (no interceptors).
+ */
+const WORKER_HTTP_INTERCEPTORS_TOKEN = new InjectionToken('WorkerHttpInterceptors', { factory: () => ({}) });
 
 /**
  * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
@@ -129,6 +134,7 @@ class WorkerHttpBackend extends HttpBackend {
     routes = inject(WORKER_HTTP_ROUTES_TOKEN);
     fallback = inject(WORKER_HTTP_FALLBACK_TOKEN);
     serializer = inject(WORKER_HTTP_SERIALIZER_TOKEN);
+    interceptorSpecs = inject(WORKER_HTTP_INTERCEPTORS_TOKEN);
     fetchBackend = inject(FetchBackend, { optional: true });
     transports = new Map();
     handle(req) {
@@ -167,13 +173,24 @@ class WorkerHttpBackend extends HttpBackend {
         const existing = this.transports.get(config.id);
         if (existing)
             return existing;
+        const specs = this.resolveSpecsFor(config.id);
         const transport = createWorkerTransport({
             workerFactory: () => new Worker(config.workerUrl, { type: 'module' }),
             maxInstances: config.maxInstances ?? 1,
+            initMessage: specs.length > 0 ? { type: 'init-interceptors', specs } : undefined,
         });
         this.transports.set(config.id, transport);
         return transport;
     }
+    resolveSpecsFor(workerId) {
+        const wildcard = this.interceptorSpecs['*'] ?? [];
+        const specific = this.interceptorSpecs[workerId] ?? [];
+        if (wildcard.length === 0)
+            return specific;
+        if (specific.length === 0)
+            return wildcard;
+        return [...wildcard, ...specific];
+    }
     handleFallback(req, reason) {
         if (this.fallback === 'error' || !this.fetchBackend) {
             return throwError(() => new Error(`[WorkerHttpBackend] ${reason}`));
@@ -364,9 +381,51 @@ function withWorkerSerialization(serializer) {
         providers: [{ provide: WORKER_HTTP_SERIALIZER_TOKEN, useValue: serializer }],
     };
 }
+/**
+ * Configures the worker-side interceptor pipeline from Angular DI.
+ *
+ * Specs are forwarded to each worker via an `init-interceptors` handshake
+ * message posted before any HTTP request. Workers must call
+ * `createConfigurableWorkerPipeline()` to receive and act on the handshake.
+ *
+ * Two shapes are accepted:
+ *  - `WorkerInterceptorSpec[]` — applied to every registered worker
+ *  - `Record<workerId, WorkerInterceptorSpec[]>` — per-worker, with the
+ *    special `'*'` key applied to all workers in addition to the
+ *    worker-specific specs
+ *
+ * @example
+ * ```typescript
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([{ id: 'api', workerUrl: ... }]),
+ *   withWorkerInterceptors([
+ *     workerLogging(),
+ *     workerRetry({ maxRetries: 3 }),
+ *     workerCache({ ttl: 30_000 }),
+ *   ]),
+ * );
+ * ```
+ *
+ * @example Per-worker specs
+ * ```typescript
+ * withWorkerInterceptors({
+ *   '*': [workerLogging()],
+ *   'secure': [workerHmacSigning({ keyMaterial })],
+ * });
+ * ```
+ */
+function withWorkerInterceptors(specs) {
+    const map = Array.isArray(specs)
+        ? { '*': [...specs] }
+        : specs;
+    return {
+        kind: 'WorkerInterceptors',
+        providers: [{ provide: WORKER_HTTP_INTERCEPTORS_TOKEN, useValue: map }],
+    };
+}
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerRoutes, withWorkerSerialization };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };

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,6 +199,66 @@ 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 && 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: {
@@ -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.3.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",

package/types/angular-helpers-worker-http-backend.d.ts

@@ -2,13 +2,14 @@ import * as i0 from '@angular/core';
 import { Provider, InjectionToken, EnvironmentProviders, OnDestroy } from '@angular/core';
 import { HttpContextToken, HttpBackend, HttpRequest, HttpEvent, HttpContext, HttpResponse } from '@angular/common/http';
 import { WorkerSerializer } from '@angular-helpers/worker-http/serializer';
+import { WorkerInterceptorSpec } from '@angular-helpers/worker-http/interceptors';
 import { Observable } from 'rxjs';
 
 /**
  * Discriminated union for worker HTTP feature kinds.
  * Mirrors Angular's HttpFeatureKind pattern.
  */
-type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization';
+type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization' | 'WorkerInterceptors';
 /**
  * Feature object — mirrors Angular's HttpFeature<K> shape.
  */
@@ -67,6 +68,13 @@ interface SerializableResponse {
     url: string;
 }
 
+/**
+ * Per-worker interceptor specs map. Key is the worker id from
+ * `WorkerConfig.id`, plus the special `'*'` wildcard that applies to every
+ * worker. Specs from `'*'` are prepended to the worker-specific specs at
+ * resolve time.
+ */
+type WorkerInterceptorSpecsMap = Readonly<Record<string, readonly WorkerInterceptorSpec[]>>;
 /**
  * Per-request HttpContextToken that carries the target worker ID.
  *
@@ -93,6 +101,11 @@ declare const WORKER_TARGET: HttpContextToken<string>;
  * serialized form — add a worker interceptor to deserialize it if needed.
  */
 declare const WORKER_HTTP_SERIALIZER_TOKEN: InjectionToken<WorkerSerializer>;
+/**
+ * Per-worker interceptor specs provided via `withWorkerInterceptors()`.
+ * Defaults to an empty map (no interceptors).
+ */
+declare const WORKER_HTTP_INTERCEPTORS_TOKEN: InjectionToken<Readonly<Record<string, readonly WorkerInterceptorSpec[]>>>;
 
 /**
  * Sets up the worker HTTP infrastructure and replaces Angular's `HttpBackend`
@@ -185,6 +198,40 @@ declare function withWorkerFallback(strategy: WorkerFallbackStrategy): WorkerHtt
  * ```
  */
 declare function withWorkerSerialization(serializer: WorkerSerializer): WorkerHttpFeature<'WorkerSerialization'>;
+/**
+ * Configures the worker-side interceptor pipeline from Angular DI.
+ *
+ * Specs are forwarded to each worker via an `init-interceptors` handshake
+ * message posted before any HTTP request. Workers must call
+ * `createConfigurableWorkerPipeline()` to receive and act on the handshake.
+ *
+ * Two shapes are accepted:
+ *  - `WorkerInterceptorSpec[]` — applied to every registered worker
+ *  - `Record<workerId, WorkerInterceptorSpec[]>` — per-worker, with the
+ *    special `'*'` key applied to all workers in addition to the
+ *    worker-specific specs
+ *
+ * @example
+ * ```typescript
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([{ id: 'api', workerUrl: ... }]),
+ *   withWorkerInterceptors([
+ *     workerLogging(),
+ *     workerRetry({ maxRetries: 3 }),
+ *     workerCache({ ttl: 30_000 }),
+ *   ]),
+ * );
+ * ```
+ *
+ * @example Per-worker specs
+ * ```typescript
+ * withWorkerInterceptors({
+ *   '*': [workerLogging()],
+ *   'secure': [workerHmacSigning({ keyMaterial })],
+ * });
+ * ```
+ */
+declare function withWorkerInterceptors(specs: readonly WorkerInterceptorSpec[] | WorkerInterceptorSpecsMap): WorkerHttpFeature<'WorkerInterceptors'>;
 
 /**
  * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
@@ -203,11 +250,13 @@ declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
     private readonly routes;
     private readonly fallback;
     private readonly serializer;
+    private readonly interceptorSpecs;
     private readonly fetchBackend;
     private readonly transports;
     handle(req: HttpRequest<unknown>): Observable<HttpEvent<unknown>>;
     ngOnDestroy(): void;
     private getOrCreateTransport;
+    private resolveSpecsFor;
     private handleFallback;
     static ɵfac: i0.ɵɵFactoryDeclaration<WorkerHttpBackend, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<WorkerHttpBackend>;
@@ -292,5 +341,5 @@ declare function matchWorkerRoute(url: string, routes: Array<{
     priority?: number;
 }>): string | null;
 
-export { WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerRoutes, withWorkerSerialization };
-export type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerRequestOptions, WorkerRoute };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };
+export type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerInterceptorSpecsMap, WorkerRequestOptions, WorkerRoute };

package/types/angular-helpers-worker-http-interceptors.d.ts

@@ -109,17 +109,120 @@ interface ContentIntegrityConfig {
  * 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
  * // workers/secure.worker.ts
- * import { createWorkerPipeline } from '@angular-helpers/worker-http/interceptors';
- * import { hmacSigningInterceptor } from './my-interceptors';
+ * import { createWorkerPipeline, hmacSigningInterceptor } from '@angular-helpers/worker-http/interceptors';
  *
- * createWorkerPipeline([hmacSigningInterceptor]);
+ * createWorkerPipeline([hmacSigningInterceptor({ keyMaterial })]);
  * ```
  */
 declare function createWorkerPipeline(interceptors: WorkerInterceptorFn[]): void;
 
+/**
+ * Serializable subset of LoggingConfig — `logger` is a function and cannot
+ * cross the worker boundary, so it is dropped here. The configurable pipeline
+ * uses `console.log` inside the worker for built-in logging.
+ */
+type SerializableLoggingConfig = Omit<LoggingConfig, 'logger'>;
+/**
+ * Serializable subset of HmacInterceptorConfig — `payloadBuilder` is a function
+ * and cannot cross the worker boundary. The default payload builder is used.
+ *
+ * `keyMaterial` is `ArrayBuffer | Uint8Array`, both of which ARE supported by
+ * the structured clone algorithm.
+ */
+type SerializableHmacConfig = Omit<HmacInterceptorConfig, 'payloadBuilder'>;
+/**
+ * Discriminated union of interceptor specifications that can be configured
+ * from Angular DI via `withWorkerInterceptors([...])` and forwarded to the
+ * worker over `postMessage`.
+ *
+ * For interceptors with custom function fields (loggers, payload builders),
+ * register the interceptor in the worker file via `registerInterceptor()` and
+ * reference it here with `kind: 'custom'`.
+ */
+type WorkerInterceptorSpec = {
+    readonly kind: 'logging';
+    readonly config?: SerializableLoggingConfig;
+} | {
+    readonly kind: 'retry';
+    readonly config?: RetryConfig;
+} | {
+    readonly kind: 'cache';
+    readonly config?: CacheConfig;
+} | {
+    readonly kind: 'hmac-signing';
+    readonly config: SerializableHmacConfig;
+} | {
+    readonly kind: 'rate-limit';
+    readonly config?: RateLimitConfig;
+} | {
+    readonly kind: 'content-integrity';
+    readonly config?: ContentIntegrityConfig;
+} | {
+    readonly kind: 'custom';
+    readonly name: string;
+    readonly config?: unknown;
+};
+/**
+ * Wire format for the init handshake message sent from the main thread to the
+ * worker. Posted exactly once per worker, before any HTTP request.
+ */
+interface WorkerInterceptorInitMessage {
+    readonly type: 'init-interceptors';
+    readonly specs: readonly WorkerInterceptorSpec[];
+}
+
+type CustomFactory = (config?: unknown) => WorkerInterceptorFn;
+/**
+ * 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();
+ * ```
+ */
+declare function registerInterceptor(name: string, factory: CustomFactory): void;
+/**
+ * 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.
+ */
+declare function resolveSpec(spec: WorkerInterceptorSpec): WorkerInterceptorFn;
+/**
+ * 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.
+ */
+declare function createConfigurableWorkerPipeline(): void;
+
 /**
  * Creates a retry interceptor with exponential backoff.
  *
@@ -240,5 +343,24 @@ declare function contentIntegrityInterceptor(config?: ContentIntegrityConfig): W
  */
 declare function composeInterceptors(...fns: WorkerInterceptorFn[]): WorkerInterceptorFn;
 
-export { cacheInterceptor, composeInterceptors, contentIntegrityInterceptor, createWorkerPipeline, hmacSigningInterceptor, loggingInterceptor, rateLimitInterceptor, retryInterceptor };
-export type { CacheConfig, ContentIntegrityConfig, HmacInterceptorConfig, LoggingConfig, RateLimitConfig, RetryConfig, SerializableRequest, SerializableResponse, WorkerInterceptorFn };
+/**
+ * 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).
+ */
+declare function workerLogging(config?: SerializableLoggingConfig): WorkerInterceptorSpec;
+declare function workerRetry(config?: RetryConfig): WorkerInterceptorSpec;
+declare function workerCache(config?: CacheConfig): WorkerInterceptorSpec;
+declare function workerHmacSigning(config: SerializableHmacConfig): WorkerInterceptorSpec;
+declare function workerRateLimit(config?: RateLimitConfig): WorkerInterceptorSpec;
+declare function workerContentIntegrity(config?: ContentIntegrityConfig): WorkerInterceptorSpec;
+/**
+ * Reference a custom interceptor that has been registered on the worker side
+ * via `registerInterceptor(name, factory)`.
+ */
+declare function workerCustom(name: string, config?: unknown): WorkerInterceptorSpec;
+
+export { cacheInterceptor, composeInterceptors, contentIntegrityInterceptor, createConfigurableWorkerPipeline, createWorkerPipeline, hmacSigningInterceptor, loggingInterceptor, rateLimitInterceptor, registerInterceptor, resolveSpec, retryInterceptor, workerCache, workerContentIntegrity, workerCustom, workerHmacSigning, workerLogging, workerRateLimit, workerRetry };
+export type { CacheConfig, ContentIntegrityConfig, HmacInterceptorConfig, LoggingConfig, RateLimitConfig, RetryConfig, SerializableHmacConfig, SerializableLoggingConfig, SerializableRequest, SerializableResponse, WorkerInterceptorFn, WorkerInterceptorInitMessage, WorkerInterceptorSpec };

package/types/angular-helpers-worker-http-transport.d.ts

@@ -38,6 +38,18 @@ interface WorkerTransportConfig {
     transferDetection?: 'auto' | 'manual' | 'none';
     /** Timeout in ms for a single request (default: 30000) */
     requestTimeout?: number;
+    /**
+     * Optional handshake message posted to every worker as soon as it is
+     * created, BEFORE any request. Useful to ship runtime configuration
+     * (e.g. interceptor specs) that the worker uses to build its pipeline.
+     *
+     * The shape is opaque to the transport — the worker is responsible for
+     * recognising and acting on it.
+     */
+    initMessage?: {
+        type: string;
+        [key: string]: unknown;
+    };
 }
 /**
  * Message sent from main thread to worker.