@angular-helpers/worker-http 0.6.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
+    }
+  },
+});
+```
 
 ---
 

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

@@ -285,6 +285,7 @@ class WorkerHttpBackend extends HttpBackend {
             }
             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);
             }
         }

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.6.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-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 { };