@angular-helpers/worker-http 0.4.0 → 0.6.0

package/README.md

@@ -406,6 +406,134 @@ 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
+creates for worker-based HTTP are handled out of the box:
+
+**1. Workers do not exist on the server.**
+During SSR, `typeof Worker === 'undefined'`. `WorkerHttpBackend` detects this
+and falls back to `FetchBackend` automatically (controlled by
+`withWorkerFallback()`). The request is fulfilled on the server thread
+exactly like a plain `HttpClient.get()` would do.
+
+**2. Avoiding a re-fetch after hydration.**
+Add `provideClientHydration()` from `@angular/platform-browser` at the app
+root (standard Angular SSR setup). That enables Angular's HTTP transfer
+cache by default. The transfer cache interceptor sits in the `HttpClient`
+pipeline — **before** `WorkerHttpBackend`:
+
+- On the server: `WorkerHttpBackend` falls back to fetch → returns a
+  response → the interceptor captures it into `TransferState`.
+- On the browser: a matching request hits the interceptor first → it replays
+  the cached response synchronously, **without ever reaching
+  `WorkerHttpBackend`**. No worker is booted for hydrated requests.
+
+```ts
+// app.config.server.ts (or your SSR bootstrap)
+export const serverConfig: ApplicationConfig = {
+  providers: [
+    provideServerRendering(),
+    provideWorkerHttpClient(
+      withWorkerConfigs([
+        { id: 'api', workerUrl: new URL('./workers/api.worker', import.meta.url) },
+      ]),
+    ),
+  ],
+};
+
+// app.config.ts (browser bootstrap)
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideClientHydration(), // ← enables HTTP transfer cache automatically
+    provideWorkerHttpClient(
+      withWorkerConfigs([
+        { id: 'api', workerUrl: new URL('./workers/api.worker', import.meta.url) },
+      ]),
+    ),
+  ],
+};
+```
+
+To customise which headers are captured or to cache `POST` requests, pass
+`withHttpTransferCacheOptions(...)` to `provideClientHydration()` — both are
+re-exported from `@angular/platform-browser`.
+
+---
+
 ## Design principles
 
 - **Zero main-thread cost** — `fetch()` runs entirely in the worker; the main thread only handles the `postMessage` handoff

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,73 @@ 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.
+                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 +515,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/package.json

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