@angular-helpers/worker-http 0.5.0 → 0.7.0

package/README.md

@@ -67,9 +67,40 @@ transport.terminate();
 **Features:**
 
 - Round-robin pool (`maxInstances`) for parallel request handling
-- Request cancellation via `AbortController` in the worker
-- Automatic `Transferable` detection for zero-copy `ArrayBuffer` transfer
 - Lazy worker instantiation — no worker created until first request
+- **Cancellation that actually aborts `fetch()`** — unsubscribing posts a
+  cancel message; the worker-side message loop threads an `AbortSignal` all
+  the way into `fetch()` so the in-flight HTTP request is truly aborted
+- **Per-request timeout** (default `30_000` ms) via `requestTimeout`; errors
+  with `WorkerHttpTimeoutError` and sends a cancel message to the worker.
+  Set to `0` to disable.
+- **Opt-in transferable detection** via `transferDetection: 'auto'` — passes
+  detected `ArrayBuffer` / `MessagePort` / `ImageBitmap` /
+  `OffscreenCanvas` / streams as the transfer list of `postMessage`, enabling
+  zero-copy transfer of large buffers. Default is `'none'` to preserve the
+  caller's access to the original data after post.
+
+```typescript
+import {
+  createWorkerTransport,
+  WorkerHttpTimeoutError,
+} from '@angular-helpers/worker-http/transport';
+
+const transport = createWorkerTransport({
+  workerUrl: new URL('./workers/api.worker', import.meta.url),
+  maxInstances: 2,
+  requestTimeout: 10_000, // override default 30 s
+  transferDetection: 'auto', // zero-copy ArrayBuffer at postMessage
+});
+
+transport.execute(request).subscribe({
+  error: (err) => {
+    if (err instanceof WorkerHttpTimeoutError) {
+      // dedicated timeout handling
+    }
+  },
+});
+```
 
 ---
 
@@ -406,6 +437,79 @@ manual control.
 
 ---
 
+## Telemetry
+
+Main-thread extension point for APM / metrics. `withTelemetry(...)` registers
+a subscriber that fires synchronously at three lifecycle points of every
+request handled by `WorkerHttpBackend`:
+
+- **`onRequest`** — after worker resolution, before dispatch
+- **`onResponse`** — when a successful response is emitted
+- **`onError`** — when the request fails (transport or non-2xx)
+
+Events share a `requestId` so you can correlate the three emissions for one
+request. `transport` is `'worker'` or `'fallback-fetch'` (SSR /
+no-route). Errors in your subscriber are caught and logged — they **never**
+affect the actual HTTP request.
+
+Call `withTelemetry(...)` multiple times to attach independent subscribers
+(e.g. one for Sentry, one for custom metrics). All subscribers receive every
+event in registration order.
+
+```ts
+provideWorkerHttpClient(
+  withWorkerConfigs([{ id: 'api', workerUrl: new URL('./workers/api.worker', import.meta.url) }]),
+  withWorkerRoutes([{ pattern: /\/api\//, worker: 'api' }]),
+
+  // Latency histogram
+  withTelemetry({
+    onResponse: (e) =>
+      histogram.record(e.durationMs, {
+        workerId: e.workerId,
+        status: e.status,
+        transport: e.transport,
+      }),
+    onError: (e) =>
+      histogram.record(e.durationMs, {
+        workerId: e.workerId,
+        status: 'error',
+      }),
+  }),
+
+  // Sentry breadcrumbs
+  withTelemetry({
+    onRequest: (e) =>
+      Sentry.addBreadcrumb({
+        category: 'worker-http',
+        message: `${e.method} ${e.url}`,
+        data: { requestId: e.requestId, workerId: e.workerId },
+      }),
+    onError: (e) =>
+      Sentry.captureException(e.error, {
+        tags: { workerId: e.workerId ?? 'fallback' },
+      }),
+  }),
+);
+```
+
+Event interface:
+
+```ts
+interface WorkerHttpTelemetryEventBase {
+  readonly requestId: string; // unique per request, correlates events
+  readonly method: string;
+  readonly url: string;
+  readonly urlWithParams: string;
+  readonly workerId: string | null; // null = fallback fetch
+  readonly transport: 'worker' | 'fallback-fetch';
+  readonly timestamp: number; // performance.now() at emission
+}
+// onResponse adds: kind: 'response', status, durationMs
+// onError    adds: kind: 'error',    error,  durationMs
+```
+
+---
+
 ## SSR + hydration
 
 Worker HTTP integrates transparently with Angular SSR. The two problems SSR

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

@@ -2,7 +2,7 @@ import * as i0 from '@angular/core';
 import { InjectionToken, inject, Injectable, makeEnvironmentProviders } from '@angular/core';
 import { HttpContextToken, HttpHeaders, HttpResponse, HttpBackend, FetchBackend, HttpErrorResponse, HttpClient, HttpContext, provideHttpClient, withFetch } from '@angular/common/http';
 import { throwError } from 'rxjs';
-import { map, catchError } from 'rxjs/operators';
+import { map, tap, catchError } from 'rxjs/operators';
 import { createWorkerTransport } from '@angular-helpers/worker-http/transport';
 
 /**
@@ -53,6 +53,15 @@ const WORKER_HTTP_SERIALIZER_TOKEN = new InjectionToken('WorkerHttpSerializer',
  * Defaults to an empty map (no interceptors).
  */
 const WORKER_HTTP_INTERCEPTORS_TOKEN = new InjectionToken('WorkerHttpInterceptors', { factory: () => ({}) });
+/**
+ * Telemetry subscribers registered via `withTelemetry()`.
+ *
+ * Multi-provider token — each `withTelemetry(...)` call appends one
+ * subscriber. All subscribers are invoked on every emission; a throwing
+ * subscriber is isolated (the backend swallows the error so it never
+ * affects the HTTP request).
+ */
+const WORKER_HTTP_TELEMETRY_TOKEN = new InjectionToken('WorkerHttpTelemetry', { factory: () => [] });
 
 /**
  * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
@@ -117,6 +126,16 @@ function matchWorkerRoute(url, routes) {
     return null;
 }
 
+let telemetryRequestCounter = 0;
+function nextTelemetryRequestId() {
+    telemetryRequestCounter = (telemetryRequestCounter + 1) >>> 0;
+    return `whttp-${telemetryRequestCounter.toString(36)}`;
+}
+function now() {
+    return typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+}
 /**
  * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
  *
@@ -136,14 +155,15 @@ class WorkerHttpBackend extends HttpBackend {
     serializer = inject(WORKER_HTTP_SERIALIZER_TOKEN);
     interceptorSpecs = inject(WORKER_HTTP_INTERCEPTORS_TOKEN);
     fetchBackend = inject(FetchBackend, { optional: true });
+    telemetry = inject(WORKER_HTTP_TELEMETRY_TOKEN);
     transports = new Map();
     handle(req) {
         if (typeof Worker === 'undefined') {
-            return this.handleFallback(req, 'Web Workers are not available in this environment (SSR)');
+            return this.handleFallback(req, null, 'Web Workers are not available in this environment (SSR)');
         }
         const workerId = req.context.get(WORKER_TARGET) ?? matchWorkerRoute(req.url, this.routes);
         if (!workerId) {
-            return this.handleFallback(req, `No worker route matched for URL: ${req.url}`);
+            return this.handleFallback(req, null, `No worker route matched for URL: ${req.url}`);
         }
         const config = this.configs.find((c) => c.id === workerId);
         if (!config) {
@@ -156,12 +176,22 @@ class WorkerHttpBackend extends HttpBackend {
             ? this.serializer.serialize(serializable.body).data
             : serializable.body;
         const payload = body !== serializable.body ? { ...serializable, body } : serializable;
-        return transport.execute(payload).pipe(map((res) => toHttpResponse(res, req)), catchError((err) => throwError(() => new HttpErrorResponse({
-            error: err,
-            status: 0,
-            statusText: 'Worker Error',
-            url: req.urlWithParams,
-        }))));
+        const base = this.buildEventBase(req, workerId, 'worker');
+        this.emitRequest(base);
+        return transport.execute(payload).pipe(map((res) => toHttpResponse(res, req)), tap((event) => {
+            if (event instanceof HttpResponse) {
+                this.emitResponse(base, event.status);
+            }
+        }), catchError((err) => {
+            const httpError = new HttpErrorResponse({
+                error: err,
+                status: 0,
+                statusText: 'Worker Error',
+                url: req.urlWithParams,
+            });
+            this.emitError(base, httpError);
+            return throwError(() => httpError);
+        }));
     }
     ngOnDestroy() {
         for (const transport of this.transports.values()) {
@@ -191,11 +221,74 @@ class WorkerHttpBackend extends HttpBackend {
             return wildcard;
         return [...wildcard, ...specific];
     }
-    handleFallback(req, reason) {
+    handleFallback(req, workerId, reason) {
         if (this.fallback === 'error' || !this.fetchBackend) {
             return throwError(() => new Error(`[WorkerHttpBackend] ${reason}`));
         }
-        return this.fetchBackend.handle(req);
+        const base = this.buildEventBase(req, workerId, 'fallback-fetch');
+        this.emitRequest(base);
+        return this.fetchBackend.handle(req).pipe(tap((event) => {
+            if (event instanceof HttpResponse) {
+                this.emitResponse(base, event.status);
+            }
+        }), catchError((err) => {
+            this.emitError(base, err);
+            return throwError(() => err);
+        }));
+    }
+    // --- Telemetry ---------------------------------------------------------
+    buildEventBase(req, workerId, transport) {
+        return {
+            requestId: nextTelemetryRequestId(),
+            method: req.method,
+            url: req.url,
+            urlWithParams: req.urlWithParams,
+            workerId,
+            transport,
+            timestamp: now(),
+        };
+    }
+    emitRequest(base) {
+        if (this.telemetry.length === 0)
+            return;
+        const event = { ...base, kind: 'request' };
+        this.dispatch((sub) => sub.onRequest?.(event));
+    }
+    emitResponse(base, status) {
+        if (this.telemetry.length === 0)
+            return;
+        const event = {
+            ...base,
+            kind: 'response',
+            status,
+            durationMs: now() - base.timestamp,
+            timestamp: now(),
+        };
+        this.dispatch((sub) => sub.onResponse?.(event));
+    }
+    emitError(base, error) {
+        if (this.telemetry.length === 0)
+            return;
+        const event = {
+            ...base,
+            kind: 'error',
+            error,
+            durationMs: now() - base.timestamp,
+            timestamp: now(),
+        };
+        this.dispatch((sub) => sub.onError?.(event));
+    }
+    dispatch(invoke) {
+        for (const subscriber of this.telemetry) {
+            try {
+                invoke(subscriber);
+            }
+            catch (telemetryError) {
+                // A throwing telemetry subscriber must never affect the HTTP request.
+                // oxlint-disable-next-line no-console -- defensive log when user-provided telemetry throws
+                console.error('[WorkerHttpBackend] telemetry subscriber threw:', telemetryError);
+            }
+        }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpBackend, deps: null, target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpBackend });
@@ -423,9 +516,51 @@ function withWorkerInterceptors(specs) {
         providers: [{ provide: WORKER_HTTP_INTERCEPTORS_TOKEN, useValue: map }],
     };
 }
+/**
+ * Registers a telemetry subscriber for `WorkerHttpBackend`.
+ *
+ * Telemetry hooks are a main-thread extension point for APM integrations
+ * (Sentry, Datadog, OpenTelemetry, ad-hoc logging). They fire synchronously
+ * at three lifecycle points of every HTTP request handled by the backend:
+ *
+ * - `onRequest` — after worker resolution, before dispatch
+ * - `onResponse` — when a successful response is emitted
+ * - `onError` — when the request fails
+ *
+ * The feature is repeatable — call `withTelemetry(...)` multiple times to
+ * attach independent subscribers. All of them receive every event, in
+ * registration order. A throwing subscriber is isolated: the backend
+ * catches and logs the error so telemetry bugs never break the request.
+ *
+ * @example Basic counter
+ * ```typescript
+ * const counters = { requests: 0, errors: 0 };
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withTelemetry({
+ *     onRequest: () => counters.requests++,
+ *     onError: () => counters.errors++,
+ *   }),
+ * );
+ * ```
+ *
+ * @example Latency histogram
+ * ```typescript
+ * withTelemetry({
+ *   onResponse: (e) => histogram.record(e.durationMs, { workerId: e.workerId }),
+ *   onError: (e) => histogram.record(e.durationMs, { workerId: e.workerId, error: true }),
+ * });
+ * ```
+ */
+function withTelemetry(telemetry) {
+    return {
+        kind: 'Telemetry',
+        providers: [{ provide: WORKER_HTTP_TELEMETRY_TOKEN, useValue: telemetry, multi: true }],
+    };
+}
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };

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

@@ -80,9 +80,13 @@ async function createAesEncryptor(config) {
         ? new Uint8Array(config.keyMaterial.buffer.slice(0))
         : new Uint8Array(config.keyMaterial);
     const cryptoKey = await crypto.subtle.importKey('raw', keyMaterial, { name: algorithm, length: keyLength }, false, ['encrypt', 'decrypt']);
+    // AES-GCM uses a 96-bit (12-byte) IV per NIST SP 800-38D recommendation.
+    // AES-CBC and AES-CTR require exactly one block (16 bytes) for their IV /
+    // counter respectively; passing 12 bytes causes `OperationError`.
+    const ivLength = algorithm === 'AES-GCM' ? 12 : 16;
     return {
         async encrypt(data) {
-            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const iv = crypto.getRandomValues(new Uint8Array(ivLength));
             const params = algorithm === 'AES-GCM'
                 ? { name: algorithm, iv }
                 : algorithm === 'AES-CBC'

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

@@ -1,9 +1,14 @@
 /**
  * Composes interceptor functions around a final handler, producing a single
- * `(req) => Promise<resp>` chain. Pure — no side effects.
+ * `(req, signal?) => Promise<resp>` chain. Pure — no side effects.
+ *
+ * The optional `signal` is threaded through interceptor boundaries automatically
+ * via a wrapper around `next`, so legacy `WorkerInterceptorFn` implementations
+ * (which take only `req, next`) keep working and still propagate cancellation
+ * when they invoke `next(req)`.
  */
 function buildChain(fns, finalHandler) {
-    return fns.reduceRight((next, interceptor) => (req) => interceptor(req, next), finalHandler);
+    return fns.reduceRight((next, interceptor) => (req, signal) => interceptor(req, (r) => next(r, signal)), finalHandler);
 }
 /**
  * Performs the actual `fetch()` call inside the worker, translating the
@@ -98,7 +103,7 @@ function attachRequestLoop(chain) {
         const controller = new AbortController();
         controllers.set(requestId, controller);
         try {
-            const response = await chain(payload);
+            const response = await chain(payload, controller.signal);
             self.postMessage({ type: 'response', requestId, result: response });
         }
         catch (error) {
@@ -145,7 +150,7 @@ function attachRequestLoop(chain) {
  * ```
  */
 function createWorkerPipeline(interceptors) {
-    const chain = buildChain(interceptors, (req) => executeFetch(req));
+    const chain = buildChain(interceptors, (req, signal) => executeFetch(req, signal));
     attachRequestLoop(chain);
 }
 
@@ -325,7 +330,9 @@ function hmacSigningInterceptor(config) {
  * ```
  */
 function loggingInterceptor(config) {
-    const logger = config?.logger ?? ((msg, data) => console.log(msg, data));
+    const logger = config?.logger ??
+        // oxlint-disable-next-line no-console -- default logger of a logging interceptor; consumers inject their own via config.logger
+        ((msg, data) => console.log(msg, data));
     const includeHeaders = config?.includeHeaders ?? false;
     function safeLog(message, data) {
         try {
@@ -538,7 +545,7 @@ function createConfigurableWorkerPipeline() {
         if (data.type === INIT_MESSAGE_TYPE) {
             const specs = data.specs ?? [];
             const fns = specs.map((spec) => resolveSpec(spec));
-            const chain = buildChain(fns, (req) => executeFetch(req));
+            const chain = buildChain(fns, (req, signal) => executeFetch(req, signal));
             // Swap to the regular request loop and replay any buffered messages.
             attachRequestLoop(chain);
             const handler = self.onmessage;

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

@@ -1,14 +1,118 @@
 import { Observable } from 'rxjs';
 
+/**
+ * Scans a payload one level deep and collects every `Transferable` instance
+ * (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, ReadableStream,
+ * WritableStream, TransformStream) found in its own enumerable properties.
+ *
+ * Used by `createWorkerTransport` when `transferDetection === 'auto'` to build
+ * the second argument of `worker.postMessage(data, transfer)` so large buffers
+ * move zero-copy instead of being structured-cloned.
+ *
+ * Design notes:
+ * - Only one level deep by design: deep traversal has quadratic cost on heavy
+ *   graphs and makes the transfer list surprising. Real payloads that care
+ *   about zero-copy put the buffer at the top level.
+ * - Duplicates are filtered — the same buffer referenced twice is transferred
+ *   only once (required by the structured-clone algorithm).
+ * - Returns an empty array for primitives, plain serializable values, or when
+ *   no transferable is found; `postMessage` accepts `[]` safely.
+ */
+function detectTransferables(payload) {
+    if (payload === null || payload === undefined)
+        return [];
+    if (typeof payload !== 'object')
+        return [];
+    const found = [];
+    const seen = new Set();
+    const collect = (value) => {
+        if (value === null || value === undefined)
+            return;
+        if (isTransferable(value)) {
+            if (!seen.has(value)) {
+                seen.add(value);
+                found.push(value);
+            }
+        }
+    };
+    if (isTransferable(payload)) {
+        collect(payload);
+        return found;
+    }
+    if (Array.isArray(payload)) {
+        for (const item of payload)
+            collect(item);
+        return found;
+    }
+    for (const key of Object.keys(payload)) {
+        collect(payload[key]);
+    }
+    return found;
+}
+function isTransferable(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== 'object')
+        return false;
+    // ArrayBuffer is the common case; check first.
+    if (typeof ArrayBuffer !== 'undefined' && value instanceof ArrayBuffer)
+        return true;
+    // Typed-array views carry an underlying buffer but are NOT Transferable —
+    // only the buffer is. Caller must pass `.buffer` explicitly if they want it.
+    if (typeof MessagePort !== 'undefined' && value instanceof MessagePort)
+        return true;
+    if (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap)
+        return true;
+    if (typeof OffscreenCanvas !== 'undefined' && value instanceof OffscreenCanvas)
+        return true;
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream)
+        return true;
+    if (typeof WritableStream !== 'undefined' && value instanceof WritableStream)
+        return true;
+    if (typeof TransformStream !== 'undefined' && value instanceof TransformStream)
+        return true;
+    return false;
+}
+
+/**
+ * Thrown by `createWorkerTransport` when a request exceeds its configured
+ * `requestTimeout`. Consumers can `instanceof`-check this error to distinguish
+ * timeout rejections from transport/worker errors.
+ *
+ * @example
+ * ```typescript
+ * transport.execute(req).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpTimeoutError) {
+ *       // dedicated timeout handling
+ *     }
+ *   },
+ * });
+ * ```
+ */
+class WorkerHttpTimeoutError extends Error {
+    name = 'WorkerHttpTimeoutError';
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Worker request timed out after ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+        // Maintain a proper prototype chain across TS transpile targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 /**
  * Creates a typed, Observable-based transport for communicating with a web worker.
  *
  * Features:
  * - Request/response correlation via `requestId`
- * - Automatic cancellation on Observable unsubscribe
+ * - Cancellation on Observable unsubscribe (also aborts `fetch()` in the worker)
+ * - Per-request timeout (default 30 s) rejecting with `WorkerHttpTimeoutError`
  * - Optional worker pool with round-robin dispatch
  * - Lazy worker creation (default)
- * - Transferable auto-detection for ArrayBuffer payloads
+ * - Opt-in transferable detection (`transferDetection: 'auto'`) for zero-copy
+ *   `ArrayBuffer` / stream payloads
  *
  * @example
  * ```typescript
@@ -28,6 +132,8 @@ function createWorkerTransport(config) {
     let roundRobinIndex = 0;
     let terminated = false;
     const maxInstances = Math.min(config.maxInstances ?? 1, typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 4) : 1);
+    const requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const transferDetection = config.transferDetection ?? 'none';
     function createWorker() {
         if (config.workerFactory) {
             return config.workerFactory();
@@ -62,12 +168,24 @@ function createWorkerTransport(config) {
         const requestId = crypto.randomUUID();
         return new Observable((subscriber) => {
             const worker = getOrCreateWorker();
+            let settled = false;
+            let timeoutHandle;
+            const cleanup = () => {
+                worker.removeEventListener('message', messageHandler);
+                worker.removeEventListener('error', errorHandler);
+                if (timeoutHandle !== undefined) {
+                    clearTimeout(timeoutHandle);
+                    timeoutHandle = undefined;
+                }
+            };
             const messageHandler = (event) => {
                 const data = event.data;
                 if (data.requestId !== requestId)
                     return;
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 if (data.type === 'error') {
                     const err = data.error;
                     subscriber.error(new Error(err.message));
@@ -78,17 +196,39 @@ function createWorkerTransport(config) {
                 }
             };
             const errorHandler = (event) => {
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 subscriber.error(new Error(event.message ?? 'Worker error'));
             };
             worker.addEventListener('message', messageHandler);
             worker.addEventListener('error', errorHandler);
-            worker.postMessage({ type: 'request', requestId, payload: request });
+            if (transferDetection === 'auto') {
+                const transferables = detectTransferables(request);
+                worker.postMessage({ type: 'request', requestId, payload: request }, transferables);
+            }
+            else {
+                worker.postMessage({ type: 'request', requestId, payload: request });
+            }
+            if (requestTimeout > 0 && Number.isFinite(requestTimeout)) {
+                timeoutHandle = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    // Ask the worker to abort any in-flight work for this id. The
+                    // cancellation fix wires this through to `fetch()`.
+                    worker.postMessage({ type: 'cancel', requestId });
+                    subscriber.error(new WorkerHttpTimeoutError(requestTimeout));
+                }, requestTimeout);
+            }
             // Teardown: send cancel message on unsubscribe
             return () => {
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 worker.postMessage({ type: 'cancel', requestId });
             };
         });
@@ -116,4 +256,4 @@ function createWorkerTransport(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { createWorkerTransport };
+export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };

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

@@ -1,20 +1,3 @@
-/**
- * @angular-helpers/worker-http
- *
- * Angular HTTP over Web Workers — off-main-thread HTTP pipelines
- * with configurable interceptors, WebCrypto security, and pluggable serialization.
- *
- * Sub-entry points:
- *   - @angular-helpers/worker-http/transport     (P1: typed RPC bridge)
- *   - @angular-helpers/worker-http/serializer    (P2: TOON, seroval, auto-detect)
- *   - @angular-helpers/worker-http/backend       (P3: Angular HttpBackend replacement)
- *   - @angular-helpers/worker-http/interceptors  (P4: pure-fn interceptors for workers)
- *   - @angular-helpers/worker-http/crypto        (P5: WebCrypto primitives)
- */
-const WORKER_HTTP_VERSION = '0.0.1';
-
 /**
  * Generated bundle index. Do not edit.
  */
-
-export { WORKER_HTTP_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/worker-http",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -9,7 +9,7 @@ import { Observable } from 'rxjs';
  * Discriminated union for worker HTTP feature kinds.
  * Mirrors Angular's HttpFeatureKind pattern.
  */
-type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization' | 'WorkerInterceptors';
+type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization' | 'WorkerInterceptors' | 'Telemetry';
 /**
  * Feature object — mirrors Angular's HttpFeature<K> shape.
  */
@@ -68,6 +68,82 @@ interface SerializableResponse {
     url: string;
 }
 
+/**
+ * Telemetry hooks for `WorkerHttpBackend`.
+ *
+ * Extension point for APM integrations (Sentry, Datadog, OpenTelemetry,
+ * ad-hoc metrics). Fires on the main thread, synchronously, at three
+ * lifecycle points of every HTTP request that reaches
+ * `WorkerHttpBackend`:
+ *
+ * - `onRequest` — after worker resolution / fallback decision, BEFORE
+ *   dispatch.
+ * - `onResponse` — when a successful response is returned from the worker
+ *   (or the fallback `FetchBackend`).
+ * - `onError` — when the request fails in transport or surfaces as a
+ *   non-2xx `HttpErrorResponse`.
+ *
+ * Subscribers are invoked inside a try/catch — a throwing or misbehaving
+ * subscriber is isolated from the HTTP request and from every other
+ * subscriber. Telemetry errors are logged via `console.error` and
+ * swallowed.
+ *
+ * Multiple subscribers are supported via a multi-provider DI token.
+ * Register with `withTelemetry(...)`; every call appends one subscriber.
+ */
+/**
+ * How a request was dispatched.
+ *
+ * - `'worker'` — dispatched to a worker from the pool.
+ * - `'fallback-fetch'` — dispatched to the main-thread `FetchBackend`
+ *   (SSR context, no matching route, unknown worker with `'main-thread'`
+ *   fallback strategy).
+ */
+type WorkerHttpTransportKind = 'worker' | 'fallback-fetch';
+/**
+ * Base shape shared by every telemetry event.
+ */
+interface WorkerHttpTelemetryEventBase {
+    /** Stable id unique to this request within the process. Correlates all three events. */
+    readonly requestId: string;
+    /** HTTP method (`'GET'`, `'POST'`, ...). */
+    readonly method: string;
+    /** URL without query params, as Angular sees it. */
+    readonly url: string;
+    /** URL with query params baked in. */
+    readonly urlWithParams: string;
+    /** Worker id that served the request. `null` when routed to fallback fetch. */
+    readonly workerId: string | null;
+    /** How the request was actually dispatched. */
+    readonly transport: WorkerHttpTransportKind;
+    /** `performance.now()` value at emission time. */
+    readonly timestamp: number;
+}
+/** Fires before the request is dispatched. */
+interface WorkerHttpRequestEvent extends WorkerHttpTelemetryEventBase {
+    readonly kind: 'request';
+}
+/** Fires when a successful response is returned. */
+interface WorkerHttpResponseEvent extends WorkerHttpTelemetryEventBase {
+    readonly kind: 'response';
+    readonly status: number;
+    readonly durationMs: number;
+}
+/** Fires when the request fails. */
+interface WorkerHttpErrorEvent extends WorkerHttpTelemetryEventBase {
+    readonly kind: 'error';
+    readonly error: unknown;
+    readonly durationMs: number;
+}
+/**
+ * Telemetry subscriber — all callbacks are optional.
+ */
+interface WorkerHttpTelemetry {
+    onRequest?(event: WorkerHttpRequestEvent): void;
+    onResponse?(event: WorkerHttpResponseEvent): void;
+    onError?(event: WorkerHttpErrorEvent): void;
+}
+
 /**
  * Per-worker interceptor specs map. Key is the worker id from
  * `WorkerConfig.id`, plus the special `'*'` wildcard that applies to every
@@ -232,6 +308,43 @@ declare function withWorkerSerialization(serializer: WorkerSerializer): WorkerHt
  * ```
  */
 declare function withWorkerInterceptors(specs: readonly WorkerInterceptorSpec[] | WorkerInterceptorSpecsMap): WorkerHttpFeature<'WorkerInterceptors'>;
+/**
+ * Registers a telemetry subscriber for `WorkerHttpBackend`.
+ *
+ * Telemetry hooks are a main-thread extension point for APM integrations
+ * (Sentry, Datadog, OpenTelemetry, ad-hoc logging). They fire synchronously
+ * at three lifecycle points of every HTTP request handled by the backend:
+ *
+ * - `onRequest` — after worker resolution, before dispatch
+ * - `onResponse` — when a successful response is emitted
+ * - `onError` — when the request fails
+ *
+ * The feature is repeatable — call `withTelemetry(...)` multiple times to
+ * attach independent subscribers. All of them receive every event, in
+ * registration order. A throwing subscriber is isolated: the backend
+ * catches and logs the error so telemetry bugs never break the request.
+ *
+ * @example Basic counter
+ * ```typescript
+ * const counters = { requests: 0, errors: 0 };
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withTelemetry({
+ *     onRequest: () => counters.requests++,
+ *     onError: () => counters.errors++,
+ *   }),
+ * );
+ * ```
+ *
+ * @example Latency histogram
+ * ```typescript
+ * withTelemetry({
+ *   onResponse: (e) => histogram.record(e.durationMs, { workerId: e.workerId }),
+ *   onError: (e) => histogram.record(e.durationMs, { workerId: e.workerId, error: true }),
+ * });
+ * ```
+ */
+declare function withTelemetry(telemetry: WorkerHttpTelemetry): WorkerHttpFeature<'Telemetry'>;
 
 /**
  * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
@@ -252,12 +365,18 @@ declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
     private readonly serializer;
     private readonly interceptorSpecs;
     private readonly fetchBackend;
+    private readonly telemetry;
     private readonly transports;
     handle(req: HttpRequest<unknown>): Observable<HttpEvent<unknown>>;
     ngOnDestroy(): void;
     private getOrCreateTransport;
     private resolveSpecsFor;
     private handleFallback;
+    private buildEventBase;
+    private emitRequest;
+    private emitResponse;
+    private emitError;
+    private dispatch;
     static ɵfac: i0.ɵɵFactoryDeclaration<WorkerHttpBackend, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<WorkerHttpBackend>;
 }
@@ -341,5 +460,5 @@ declare function matchWorkerRoute(url: string, routes: Array<{
     priority?: number;
 }>): string | null;
 
-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 };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };
+export type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpErrorEvent, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerHttpRequestEvent, WorkerHttpResponseEvent, WorkerHttpTelemetry, WorkerHttpTelemetryEventBase, WorkerHttpTransportKind, WorkerInterceptorSpecsMap, WorkerRequestOptions, WorkerRoute };

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

@@ -34,9 +34,27 @@ interface WorkerTransportConfig {
     workerUrl?: string | URL;
     /** Maximum number of worker instances in the pool (default: 1) */
     maxInstances?: number;
-    /** Transfer strategy for large payloads */
+    /**
+     * Transfer strategy for `postMessage` payloads.
+     *
+     * - `'none'` (default) — payloads are always structured-cloned, preserving
+     *   the caller's access to the original data after post.
+     * - `'auto'` — shallowly walks the payload and passes every detected
+     *   `Transferable` (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas,
+     *   ReadableStream, WritableStream, TransformStream) in the transfer list
+     *   of `postMessage`. Large buffers move zero-copy; their `byteLength`
+     *   becomes `0` in the main thread after post.
+     *
+     * The `'manual'` value is reserved for a future API where callers supply
+     * their own transfer list per request. It currently behaves like `'none'`.
+     */
     transferDetection?: 'auto' | 'manual' | 'none';
-    /** Timeout in ms for a single request (default: 30000) */
+    /**
+     * Per-request timeout in milliseconds. If the worker does not respond
+     * within this window, `execute()` errors with `WorkerHttpTimeoutError`
+     * and a cancel message is posted to the worker. Set to `0` or
+     * non-finite to disable the timeout entirely. Default: `30000` (30 s).
+     */
     requestTimeout?: number;
     /**
      * Optional handshake message posted to every worker as soon as it is
@@ -103,10 +121,12 @@ interface WorkerTransport<TRequest = unknown, TResponse = unknown> {
  *
  * Features:
  * - Request/response correlation via `requestId`
- * - Automatic cancellation on Observable unsubscribe
+ * - Cancellation on Observable unsubscribe (also aborts `fetch()` in the worker)
+ * - Per-request timeout (default 30 s) rejecting with `WorkerHttpTimeoutError`
  * - Optional worker pool with round-robin dispatch
  * - Lazy worker creation (default)
- * - Transferable auto-detection for ArrayBuffer payloads
+ * - Opt-in transferable detection (`transferDetection: 'auto'`) for zero-copy
+ *   `ArrayBuffer` / stream payloads
  *
  * @example
  * ```typescript
@@ -123,5 +143,47 @@ interface WorkerTransport<TRequest = unknown, TResponse = unknown> {
  */
 declare function createWorkerTransport<TRequest = unknown, TResponse = unknown>(config: WorkerTransportConfig): WorkerTransport<TRequest, TResponse>;
 
-export { createWorkerTransport };
+/**
+ * Thrown by `createWorkerTransport` when a request exceeds its configured
+ * `requestTimeout`. Consumers can `instanceof`-check this error to distinguish
+ * timeout rejections from transport/worker errors.
+ *
+ * @example
+ * ```typescript
+ * transport.execute(req).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpTimeoutError) {
+ *       // dedicated timeout handling
+ *     }
+ *   },
+ * });
+ * ```
+ */
+declare class WorkerHttpTimeoutError extends Error {
+    readonly name = "WorkerHttpTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+/**
+ * Scans a payload one level deep and collects every `Transferable` instance
+ * (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, ReadableStream,
+ * WritableStream, TransformStream) found in its own enumerable properties.
+ *
+ * Used by `createWorkerTransport` when `transferDetection === 'auto'` to build
+ * the second argument of `worker.postMessage(data, transfer)` so large buffers
+ * move zero-copy instead of being structured-cloned.
+ *
+ * Design notes:
+ * - Only one level deep by design: deep traversal has quadratic cost on heavy
+ *   graphs and makes the transfer list surprising. Real payloads that care
+ *   about zero-copy put the buffer at the top level.
+ * - Duplicates are filtered — the same buffer referenced twice is transferred
+ *   only once (required by the structured-clone algorithm).
+ * - Returns an empty array for primitives, plain serializable values, or when
+ *   no transferable is found; `postMessage` accepts `[]` safely.
+ */
+declare function detectTransferables(payload: unknown): Transferable[];
+
+export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };
 export type { WorkerErrorResponse, WorkerMessage, WorkerResponse, WorkerTransport, WorkerTransportConfig };

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

@@ -1,16 +1,2 @@
-/**
- * @angular-helpers/worker-http
- *
- * Angular HTTP over Web Workers — off-main-thread HTTP pipelines
- * with configurable interceptors, WebCrypto security, and pluggable serialization.
- *
- * Sub-entry points:
- *   - @angular-helpers/worker-http/transport     (P1: typed RPC bridge)
- *   - @angular-helpers/worker-http/serializer    (P2: TOON, seroval, auto-detect)
- *   - @angular-helpers/worker-http/backend       (P3: Angular HttpBackend replacement)
- *   - @angular-helpers/worker-http/interceptors  (P4: pure-fn interceptors for workers)
- *   - @angular-helpers/worker-http/crypto        (P5: WebCrypto primitives)
- */
-declare const WORKER_HTTP_VERSION = "0.0.1";
 
-export { WORKER_HTTP_VERSION };
+export { };