@angular-helpers/worker-http 0.2.0

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

@@ -0,0 +1,116 @@
+import { Observable } from 'rxjs';
+
+/**
+ * Creates a typed, Observable-based transport for communicating with a web worker.
+ *
+ * Features:
+ * - Request/response correlation via `requestId`
+ * - Automatic cancellation on Observable unsubscribe
+ * - Optional worker pool with round-robin dispatch
+ * - Lazy worker creation (default)
+ * - Transferable auto-detection for ArrayBuffer payloads
+ *
+ * @example
+ * ```typescript
+ * const transport = createWorkerTransport<MyRequest, MyResponse>({
+ *   workerFactory: () => new Worker(new URL('./my.worker.ts', import.meta.url), { type: 'module' }),
+ *   maxInstances: 2,
+ * });
+ *
+ * transport.execute(request).subscribe({
+ *   next: (response) => console.log(response),
+ *   error: (err) => console.error(err),
+ * });
+ * ```
+ */
+function createWorkerTransport(config) {
+    const workers = [];
+    let roundRobinIndex = 0;
+    let terminated = false;
+    const maxInstances = Math.min(config.maxInstances ?? 1, typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 4) : 1);
+    function createWorker() {
+        if (config.workerFactory) {
+            return config.workerFactory();
+        }
+        if (config.workerUrl) {
+            const url = typeof config.workerUrl === 'string'
+                ? new URL(config.workerUrl, document.baseURI)
+                : config.workerUrl;
+            return new Worker(url, { type: 'module' });
+        }
+        throw new Error('Either workerFactory or workerUrl must be provided');
+    }
+    function getOrCreateWorker() {
+        if (workers.length < maxInstances) {
+            const worker = createWorker();
+            workers.push(worker);
+            return worker;
+        }
+        const worker = workers[roundRobinIndex % workers.length];
+        roundRobinIndex++;
+        return worker;
+    }
+    function execute(request) {
+        if (terminated) {
+            return new Observable((subscriber) => {
+                subscriber.error(new Error('WorkerTransport has been terminated'));
+            });
+        }
+        const requestId = crypto.randomUUID();
+        return new Observable((subscriber) => {
+            const worker = getOrCreateWorker();
+            const messageHandler = (event) => {
+                const data = event.data;
+                if (data.requestId !== requestId)
+                    return;
+                worker.removeEventListener('message', messageHandler);
+                worker.removeEventListener('error', errorHandler);
+                if (data.type === 'error') {
+                    const err = data.error;
+                    subscriber.error(new Error(err.message));
+                }
+                else {
+                    subscriber.next(data.result);
+                    subscriber.complete();
+                }
+            };
+            const errorHandler = (event) => {
+                worker.removeEventListener('message', messageHandler);
+                worker.removeEventListener('error', errorHandler);
+                subscriber.error(new Error(event.message ?? 'Worker error'));
+            };
+            worker.addEventListener('message', messageHandler);
+            worker.addEventListener('error', errorHandler);
+            worker.postMessage({ type: 'request', requestId, payload: request });
+            // Teardown: send cancel message on unsubscribe
+            return () => {
+                worker.removeEventListener('message', messageHandler);
+                worker.removeEventListener('error', errorHandler);
+                worker.postMessage({ type: 'cancel', requestId });
+            };
+        });
+    }
+    function terminate() {
+        terminated = true;
+        for (const worker of workers) {
+            worker.terminate();
+        }
+        workers.length = 0;
+    }
+    return {
+        execute,
+        terminate,
+        get isActive() {
+            return !terminated && workers.length > 0;
+        },
+        get activeInstances() {
+            return workers.length;
+        },
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { createWorkerTransport };

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

@@ -0,0 +1,20 @@
+/**
+ * @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

@@ -0,0 +1,81 @@
+{
+  "name": "@angular-helpers/worker-http",
+  "version": "0.2.0",
+  "description": "Angular HTTP over Web Workers — off-main-thread HTTP pipelines with configurable interceptors, WebCrypto security, and pluggable serialization",
+  "keywords": [
+    "angular",
+    "web-worker",
+    "http",
+    "off-main-thread",
+    "interceptors",
+    "webcrypto",
+    "hmac",
+    "serialization",
+    "toon",
+    "performance"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Gaspar1992/angular-helpers"
+  },
+  "bugs": {
+    "url": "https://github.com/Gaspar1992/angular-helpers/issues"
+  },
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "rxjs": "^7.0.0",
+    "seroval": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/common": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "seroval": {
+      "optional": true
+    }
+  },
+  "module": "fesm2022/angular-helpers-worker-http.mjs",
+  "typings": "types/angular-helpers-worker-http.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/angular-helpers-worker-http.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http.mjs"
+    },
+    "./backend": {
+      "types": "./types/angular-helpers-worker-http-backend.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http-backend.mjs"
+    },
+    "./crypto": {
+      "types": "./types/angular-helpers-worker-http-crypto.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http-crypto.mjs"
+    },
+    "./interceptors": {
+      "types": "./types/angular-helpers-worker-http-interceptors.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http-interceptors.mjs"
+    },
+    "./serializer": {
+      "types": "./types/angular-helpers-worker-http-serializer.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http-serializer.mjs"
+    },
+    "./transport": {
+      "types": "./types/angular-helpers-worker-http-transport.d.ts",
+      "default": "./fesm2022/angular-helpers-worker-http-transport.mjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

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

@@ -0,0 +1,42 @@
+import { Provider } from '@angular/core';
+
+/**
+ * Discriminated union for worker HTTP feature kinds.
+ * Mirrors Angular's HttpFeatureKind pattern.
+ */
+type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization';
+/**
+ * Feature object — mirrors Angular's HttpFeature<K> shape.
+ */
+interface WorkerHttpFeature<K extends WorkerHttpFeatureKind> {
+    readonly kind: K;
+    readonly providers: Provider[];
+}
+/**
+ * Single worker definition.
+ */
+interface WorkerConfig {
+    /** Unique identifier used for routing / explicit selection */
+    id: string;
+    /** URL of the worker script (passed to `new Worker(url)`) */
+    workerUrl: URL;
+    /** Maximum worker instances in the pool (default: 1) */
+    maxInstances?: number;
+}
+/**
+ * URL-pattern to worker auto-routing rule.
+ */
+interface WorkerRoute {
+    /** URL pattern to match (RegExp or string prefix) */
+    pattern: RegExp | string;
+    /** Must match a WorkerConfig.id */
+    worker: string;
+    /** Higher priority = evaluated first (default: 0) */
+    priority?: number;
+}
+/**
+ * Fallback strategy when workers are unavailable (SSR, old browsers).
+ */
+type WorkerFallbackStrategy = 'main-thread' | 'error';
+
+export type { WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerRoute };

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

@@ -0,0 +1,127 @@
+/**
+ * Supported HMAC hash algorithms.
+ */
+type HmacAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+/**
+ * Supported AES algorithms.
+ */
+type AesAlgorithm = 'AES-GCM' | 'AES-CBC' | 'AES-CTR';
+/**
+ * Supported hash algorithms for content integrity.
+ */
+type HashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+/**
+ * Configuration for HMAC signing operations.
+ */
+interface HmacSignerConfig {
+    /** The raw key material (e.g., a secret string encoded as ArrayBuffer) */
+    keyMaterial: ArrayBuffer | Uint8Array;
+    /** Hash algorithm to use (default: 'SHA-256') */
+    algorithm?: HmacAlgorithm;
+}
+/**
+ * Configuration for AES encryption operations.
+ */
+interface AesEncryptorConfig {
+    /** The raw key material */
+    keyMaterial: ArrayBuffer | Uint8Array;
+    /** AES algorithm to use (default: 'AES-GCM') */
+    algorithm?: AesAlgorithm;
+    /** Key length in bits (default: 256) */
+    keyLength?: 128 | 192 | 256;
+}
+/**
+ * Result of an AES encryption operation.
+ */
+interface EncryptedPayload {
+    /** The encrypted data */
+    ciphertext: ArrayBuffer;
+    /** The initialization vector used */
+    iv: Uint8Array;
+    /** The algorithm used */
+    algorithm: AesAlgorithm;
+}
+/**
+ * Interface for HMAC signing and verification.
+ */
+interface HmacSigner {
+    /** Sign data and return the signature as ArrayBuffer */
+    sign(data: string | ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+    /** Sign data and return the signature as hex string */
+    signHex(data: string | ArrayBuffer | Uint8Array): Promise<string>;
+    /** Verify a signature against data */
+    verify(data: string | ArrayBuffer | Uint8Array, signature: ArrayBuffer): Promise<boolean>;
+}
+/**
+ * Interface for AES encryption and decryption.
+ */
+interface AesEncryptor {
+    /** Encrypt data */
+    encrypt(data: string | ArrayBuffer | Uint8Array): Promise<EncryptedPayload>;
+    /** Decrypt data */
+    decrypt(payload: EncryptedPayload): Promise<ArrayBuffer>;
+}
+/**
+ * Interface for content hashing.
+ */
+interface ContentHasher {
+    /** Hash data and return as ArrayBuffer */
+    hash(data: string | ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+    /** Hash data and return as hex string */
+    hashHex(data: string | ArrayBuffer | Uint8Array): Promise<string>;
+}
+
+/**
+ * Creates an HMAC signer using the Web Crypto API.
+ *
+ * Works in both main thread and web workers.
+ * Requires a secure context (HTTPS).
+ *
+ * @example
+ * ```typescript
+ * const signer = await createHmacSigner({
+ *   keyMaterial: new TextEncoder().encode('my-secret-key'),
+ *   algorithm: 'SHA-256',
+ * });
+ *
+ * const signature = await signer.signHex('request-payload');
+ * const isValid = await signer.verify('request-payload', signatureBuffer);
+ * ```
+ */
+declare function createHmacSigner(config: HmacSignerConfig): Promise<HmacSigner>;
+
+/**
+ * Creates an AES encryptor using the Web Crypto API.
+ *
+ * Works in both main thread and web workers.
+ * Requires a secure context (HTTPS).
+ *
+ * @example
+ * ```typescript
+ * const encryptor = await createAesEncryptor({
+ *   keyMaterial: new TextEncoder().encode('32-byte-secret-key-for-aes-256!'),
+ *   algorithm: 'AES-GCM',
+ * });
+ *
+ * const encrypted = await encryptor.encrypt('sensitive data');
+ * const decrypted = await encryptor.decrypt(encrypted);
+ * ```
+ */
+declare function createAesEncryptor(config: AesEncryptorConfig): Promise<AesEncryptor>;
+
+/**
+ * Creates a content hasher using the Web Crypto API.
+ *
+ * Works in both main thread and web workers.
+ * Useful for content integrity verification (e.g., response body hashing).
+ *
+ * @example
+ * ```typescript
+ * const hasher = createContentHasher('SHA-256');
+ * const hex = await hasher.hashHex('response-body-content');
+ * ```
+ */
+declare function createContentHasher(algorithm?: HashAlgorithm): ContentHasher;
+
+export { createAesEncryptor, createContentHasher, createHmacSigner };
+export type { AesAlgorithm, AesEncryptor, AesEncryptorConfig, ContentHasher, EncryptedPayload, HashAlgorithm, HmacAlgorithm, HmacSigner, HmacSignerConfig };

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

@@ -0,0 +1,244 @@
+/**
+ * Serializable HTTP request — POJO version of Angular's HttpRequest.
+ * Structured-clone safe: no classes, no functions, no prototype chains.
+ */
+interface SerializableRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string[]>;
+    params: Record<string, string[]>;
+    body: unknown;
+    responseType: 'json' | 'text' | 'blob' | 'arraybuffer';
+    withCredentials: boolean;
+    context: Record<string, unknown>;
+}
+/**
+ * Serializable HTTP response — POJO version of Angular's HttpResponse.
+ */
+interface SerializableResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string[]>;
+    body: unknown;
+    url: string;
+}
+/**
+ * Pure-function interceptor that runs inside a web worker.
+ *
+ * Constraints:
+ * - No `inject()` — Angular DI does not exist in the worker
+ * - No DOM access — workers have no `document` or `window`
+ * - No closures over external mutable state
+ * - Must be serialization-safe (bundled at build time, not transferred at runtime)
+ */
+type WorkerInterceptorFn = (req: SerializableRequest, next: (req: SerializableRequest) => Promise<SerializableResponse>) => Promise<SerializableResponse>;
+/**
+ * Configuration for the retry interceptor.
+ */
+interface RetryConfig {
+    /** Maximum number of retries (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in ms (default: 1000) */
+    initialDelay?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryStatusCodes?: number[];
+    /** Whether to retry on network errors (fetch throws) (default: true) */
+    retryOnNetworkError?: boolean;
+}
+/**
+ * Configuration for the cache interceptor.
+ */
+interface CacheConfig {
+    /** TTL in ms (default: 60000 = 1 min) */
+    ttl?: number;
+    /** Maximum number of cached entries (default: 100) */
+    maxEntries?: number;
+    /** HTTP methods to cache (default: ['GET']) */
+    methods?: string[];
+}
+/**
+ * Configuration for the HMAC signing interceptor.
+ */
+interface HmacInterceptorConfig {
+    /** Raw key material for HMAC signing */
+    keyMaterial: ArrayBuffer | Uint8Array;
+    /** Hash algorithm (default: 'SHA-256') */
+    algorithm?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /** Header name for the signature (default: 'X-HMAC-Signature') */
+    headerName?: string;
+    /** Function to build the signing payload from the request (default: `${method}:${url}:${body}`) */
+    payloadBuilder?: (req: SerializableRequest) => string;
+}
+/**
+ * Configuration for the rate limit interceptor.
+ */
+interface RateLimitConfig {
+    /** Maximum requests per window (default: 100) */
+    maxRequests?: number;
+    /** Window size in ms (default: 60000 = 1 min) */
+    windowMs?: number;
+}
+/**
+ * Configuration for the logging interceptor.
+ */
+interface LoggingConfig {
+    /** Custom logger function (default: console.log) */
+    logger?: (message: string, data?: unknown) => void;
+    /** Whether to include request/response headers in logs (default: false) */
+    includeHeaders?: boolean;
+}
+/**
+ * Configuration for the content integrity interceptor.
+ */
+interface ContentIntegrityConfig {
+    /** Hash algorithm to use (default: 'SHA-256') */
+    algorithm?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /** Response header containing the expected hash (default: 'X-Content-Hash') */
+    headerName?: string;
+    /** Throw if the integrity header is absent (default: false) */
+    requireHash?: boolean;
+}
+
+/**
+ * Creates and registers a worker-side HTTP pipeline.
+ *
+ * Call this inside a worker file to set up the interceptor chain.
+ * The pipeline listens for incoming requests via `postMessage`,
+ * runs them through the interceptor chain, executes `fetch()`,
+ * and sends the response back.
+ *
+ * @example
+ * ```typescript
+ * // workers/secure.worker.ts
+ * import { createWorkerPipeline } from '@angular-helpers/worker-http/interceptors';
+ * import { hmacSigningInterceptor } from './my-interceptors';
+ *
+ * createWorkerPipeline([hmacSigningInterceptor]);
+ * ```
+ */
+declare function createWorkerPipeline(interceptors: WorkerInterceptorFn[]): void;
+
+/**
+ * Creates a retry interceptor with exponential backoff.
+ *
+ * Retries requests that fail with specific HTTP status codes.
+ * Respects the `Retry-After` response header when present.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   retryInterceptor({ maxRetries: 3, initialDelay: 500 }),
+ * ]);
+ * ```
+ */
+declare function retryInterceptor(config?: RetryConfig): WorkerInterceptorFn;
+
+/**
+ * Creates a cache interceptor that stores responses in worker memory.
+ *
+ * Caches GET responses by default (configurable). Evicts oldest entry
+ * when `maxEntries` is reached (insertion-order eviction).
+ * Each factory call creates an independent cache instance.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   cacheInterceptor({ ttl: 30000, maxEntries: 50 }),
+ * ]);
+ * ```
+ */
+declare function cacheInterceptor(config?: CacheConfig): WorkerInterceptorFn;
+
+/**
+ * Creates an HMAC signing interceptor that adds a signature header to outgoing requests.
+ *
+ * Uses WebCrypto `SubtleCrypto` (native in web workers). The `CryptoKey` is
+ * imported lazily on the first request and reused for all subsequent requests
+ * in the same factory instance.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   hmacSigningInterceptor({
+ *     keyMaterial: new TextEncoder().encode('my-secret-key'),
+ *     algorithm: 'SHA-256',
+ *     headerName: 'X-HMAC-Signature',
+ *   }),
+ * ]);
+ * ```
+ */
+declare function hmacSigningInterceptor(config: HmacInterceptorConfig): WorkerInterceptorFn;
+
+/**
+ * Creates a logging interceptor that logs request and response details.
+ *
+ * Uses `console.log` by default. A custom logger can be provided via config.
+ * Logger exceptions are swallowed — a logging failure never interrupts the pipeline.
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   loggingInterceptor({ includeHeaders: true }),
+ * ]);
+ * ```
+ */
+declare function loggingInterceptor(config?: LoggingConfig): WorkerInterceptorFn;
+
+/**
+ * Creates a client-side rate limiting interceptor using a sliding window algorithm.
+ *
+ * Tracks request timestamps within the configured window. When the limit is
+ * exceeded, throws an error with status 429. State is per-factory-instance
+ * (resets when the worker is terminated).
+ *
+ * @example
+ * ```typescript
+ * createWorkerPipeline([
+ *   rateLimitInterceptor({ maxRequests: 10, windowMs: 5000 }),
+ * ]);
+ * ```
+ */
+declare function rateLimitInterceptor(config?: RateLimitConfig): WorkerInterceptorFn;
+
+/**
+ * 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,
+ *   }),
+ * ]);
+ * ```
+ */
+declare function contentIntegrityInterceptor(config?: ContentIntegrityConfig): WorkerInterceptorFn;
+
+/**
+ * Composes multiple worker interceptors into a single `WorkerInterceptorFn`.
+ *
+ * Interceptors are executed left-to-right, matching Angular's interceptor chain convention.
+ * Each interceptor calls `next()` to pass control to the next one.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = composeInterceptors(
+ *   loggingInterceptor(),
+ *   retryInterceptor({ maxRetries: 2 }),
+ *   hmacSigningInterceptor({ keyMaterial: key }),
+ * );
+ *
+ * createWorkerPipeline([pipeline]);
+ * ```
+ */
+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 };