@angular-helpers/worker-http 0.2.0 → 0.4.0

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

@@ -1,10 +1,15 @@
-import { Provider } from '@angular/core';
+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.
  */
@@ -38,5 +43,303 @@ interface WorkerRoute {
  * Fallback strategy when workers are unavailable (SSR, old browsers).
  */
 type WorkerFallbackStrategy = 'main-thread' | 'error';
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ *
+ * `null` → use URL-pattern auto-routing (or main-thread fallback if no route matches).
+ *
+ * @example
+ * ```typescript
+ * // With WorkerHttpClient (recommended)
+ * this.http.get('/api/data', { worker: 'secure' });
+ *
+ * // With standard HttpClient (power user)
+ * this.http.get('/api/data', {
+ *   context: new HttpContext().set(WORKER_TARGET, 'secure'),
+ * });
+ * ```
+ */
+declare const WORKER_TARGET: HttpContextToken<string>;
+/**
+ * Optional serializer for crossing the worker boundary.
+ * Provided via `withWorkerSerialization()`. Defaults to `null` (structured clone).
+ *
+ * When set, `WorkerHttpBackend` serializes the request body before `postMessage`
+ * using this serializer. The worker-side `createWorkerPipeline()` receives the
+ * 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`
+ * with `WorkerHttpBackend`.
+ *
+ * Drop-in companion to `provideHttpClient()`. Can be used INSTEAD of it —
+ * `HttpClient` and the full interceptor chain are included automatically.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideWorkerHttpClient(
+ *       withWorkerConfigs([
+ *         { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *       ]),
+ *       withWorkerRoutes([
+ *         { pattern: /\/api\//, worker: 'public', priority: 1 },
+ *       ]),
+ *       withWorkerFallback('main-thread'),
+ *     ),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideWorkerHttpClient(...features: WorkerHttpFeature<WorkerHttpFeatureKind>[]): EnvironmentProviders;
+/**
+ * Registers worker definitions (id + workerUrl + optional pool size).
+ *
+ * At least one config is required for any request to reach a worker.
+ *
+ * @example
+ * ```typescript
+ * withWorkerConfigs([
+ *   { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *   { id: 'secure', workerUrl: new URL('./workers/secure.worker', import.meta.url), maxInstances: 2 },
+ * ])
+ * ```
+ */
+declare function withWorkerConfigs(configs: WorkerConfig[]): WorkerHttpFeature<'WorkerConfigs'>;
+/**
+ * Declares URL-pattern → worker routing rules evaluated in priority order.
+ *
+ * When a request URL matches a pattern, the associated worker handles it.
+ * Explicit `WORKER_TARGET` context always takes precedence over routes.
+ *
+ * @example
+ * ```typescript
+ * withWorkerRoutes([
+ *   { pattern: /\/api\/secure\//, worker: 'secure', priority: 10 },
+ *   { pattern: /\/api\//, worker: 'public', priority: 1 },
+ * ])
+ * ```
+ */
+declare function withWorkerRoutes(routes: WorkerRoute[]): WorkerHttpFeature<'WorkerRoutes'>;
+/**
+ * Sets the fallback strategy when workers are unavailable (SSR, old browsers,
+ * or when no route matches).
+ *
+ * - `'main-thread'` (default) — silently delegates to `FetchBackend`
+ * - `'error'` — throws, forcing explicit handling in the application
+ *
+ * @example
+ * ```typescript
+ * withWorkerFallback('main-thread') // SSR-safe
+ * ```
+ */
+declare function withWorkerFallback(strategy: WorkerFallbackStrategy): WorkerHttpFeature<'WorkerFallback'>;
+/**
+ * Configures a custom serializer for crossing the worker boundary.
+ *
+ * By default `WorkerHttpBackend` relies on the browser's structured clone algorithm
+ * (safe for plain objects, arrays, primitives, `Date`, `ArrayBuffer`).
+ * Use `withWorkerSerialization` when your request bodies contain types that
+ * structured clone cannot handle (e.g. class instances, circular references, `Map`, `Set`).
+ *
+ * **Worker-side note:** The serialized form is what the worker receives as `req.body`.
+ * If you use `createSerovalSerializer` or similar, add a worker-side interceptor
+ * to deserialize the body before calling `fetch()`.
+ *
+ * @example
+ * ```typescript
+ * import { createSerovalSerializer } from '@angular-helpers/worker-http/serializer';
+ *
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withWorkerSerialization(createSerovalSerializer()),
+ * )
+ * ```
+ */
+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.
+ *
+ * Registered via `provideWorkerHttpClient()`. Not meant to be used directly.
+ *
+ * Flow per request:
+ * 1. Check SSR: if `Worker` is undefined → fallback strategy
+ * 2. Resolve target worker ID from `WORKER_TARGET` context or URL-pattern routing
+ * 3. Serialize `HttpRequest` → `SerializableRequest` (structured-clone safe)
+ * 4. Dispatch to the worker's `WorkerTransport`
+ * 5. Deserialize `SerializableResponse` → `HttpResponse`
+ */
+declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
+    private readonly configs;
+    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>;
+}
+
+/**
+ * Options accepted by `WorkerHttpClient` methods.
+ * Identical to `HttpClient` options with an optional `worker` field added.
+ */
+interface WorkerRequestOptions {
+    /** Target worker ID. Overrides URL-pattern routing for this specific request. */
+    worker?: string | null;
+    context?: HttpContext;
+    headers?: Record<string, string | string[]>;
+    params?: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
+    responseType?: 'json';
+    withCredentials?: boolean;
+    observe?: 'body';
+    reportProgress?: boolean;
+    transferCache?: {
+        includeHeaders?: string[];
+    } | boolean;
+}
+/**
+ * Convenience wrapper over `HttpClient` that adds an optional `{ worker }` field
+ * to every method. Under the hood it sets `WORKER_TARGET` on the `HttpContext` —
+ * the caller never has to touch the context manually.
+ *
+ * Usage is identical to `HttpClient` — just inject `WorkerHttpClient` instead.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class DataService {
+ *   private readonly http = inject(WorkerHttpClient);
+ *
+ *   getUsers(): Observable<User[]> {
+ *     return this.http.get<User[]>('/api/users'); // auto-routed by URL pattern
+ *   }
+ *
+ *   getSensitiveReport(): Observable<Report> {
+ *     return this.http.get<Report>('/api/secure/reports', { worker: 'secure' });
+ *   }
+ * }
+ * ```
+ */
+declare class WorkerHttpClient {
+    private readonly http;
+    get<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    post<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    put<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    patch<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    delete<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    head<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    private withWorker;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WorkerHttpClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WorkerHttpClient>;
+}
+
+/**
+ * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
+ * that can be sent to a web worker via `postMessage`.
+ *
+ * Notes:
+ * - `urlWithParams` is used so query params embedded via `HttpParams` are included.
+ * - The `context` field is intentionally left empty: `HttpContext` uses class references
+ *   as keys which cannot cross the worker boundary.
+ */
+declare function toSerializableRequest(req: HttpRequest<unknown>): SerializableRequest;
+/**
+ * Converts a worker `SerializableResponse` back into an Angular `HttpResponse`.
+ */
+declare function toHttpResponse(res: SerializableResponse, req: HttpRequest<unknown>): HttpResponse<unknown>;
+/**
+ * Matches a URL against a sorted list of `WorkerRoute` rules.
+ * Rules with higher `priority` are evaluated first.
+ * Returns the matched worker ID or `null` if no rule matches.
+ */
+declare function matchWorkerRoute(url: string, routes: Array<{
+    pattern: RegExp | string;
+    worker: string;
+    priority?: number;
+}>): string | null;
 
-export type { WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, 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.