@schmock/core 2.5.0 → 2.6.0

package/dist/adapter.d.ts

@@ -9,11 +9,13 @@
  *   request's abort signal.
  * - `createFetchInterceptor` is the fetch interception `mock.intercept()` is
  *   built on.
+ * - `acquireFetchRelay` / `routeRelayedRequest` let a relay transport (a
+ *   service worker) deliver intercepted requests itself.
  *
  * @packageDocumentation
  */
 export { abortReason, awaitWithAbort } from "./abort.js";
 export { acquireRequestAdmission } from "./admission.js";
 export type { CallableMockInstance, InterceptHandle, InterceptOptions, } from "./index.js";
-export { createFetchInterceptor } from "./interceptor.js";
-export type { MockRequestHandler, RequestAdmission } from "./types.js";
+export { acquireFetchRelay, createFetchInterceptor, routeRelayedRequest, } from "./interceptor.js";
+export type { FetchRelay, MockRequestHandler, RequestAdmission, } from "./types.js";

package/dist/adapter.js

@@ -9,9 +9,11 @@
  *   request's abort signal.
  * - `createFetchInterceptor` is the fetch interception `mock.intercept()` is
  *   built on.
+ * - `acquireFetchRelay` / `routeRelayedRequest` let a relay transport (a
+ *   service worker) deliver intercepted requests itself.
  *
  * @packageDocumentation
  */
 export { abortReason, awaitWithAbort } from "./abort.js";
 export { acquireRequestAdmission } from "./admission.js";
-export { createFetchInterceptor } from "./interceptor.js";
+export { acquireFetchRelay, createFetchInterceptor, routeRelayedRequest, } from "./interceptor.js";

package/dist/builder.js

@@ -7,9 +7,9 @@ import { MockEvents } from "./events.js";
 import { RequestGenerations } from "./generations.js";
 import { redactHeaders } from "./headers.js";
 import { RequestHistory } from "./history.js";
-import { createFetchInterceptor, NORMALIZED_ADMISSION_KEY, } from "./interceptor.js";
+import { createFetchLease, NORMALIZED_ADMISSION_KEY, } from "./interceptor.js";
 import { NodeServerController } from "./node-server.js";
-import { assertValidPlugin, runInstallHook, runUninstallHooks, } from "./plugin-hooks.js";
+import { assertValidPlugin, hasExchangeObserver, runExchangeHooks, runInstallHook, runUninstallHooks, } from "./plugin-hooks.js";
 import { recoverGeneratorError, runPluginBeforeRequest, runPluginPipeline, } from "./plugin-pipeline.js";
 import { buildJsonErrorResponse, normalizeResponse, } from "./response-normalizer.js";
 import { parseResponse } from "./response-parser.js";
@@ -224,7 +224,13 @@ export class CallableMockInstance {
         // slot with their own options, released independently. The owner symbol
         // keeps them one mock for dispatch, so a single request reaches handle()
         // once no matter how many leases this instance holds.
-        const lease = createFetchInterceptor((method, path, opts) => this.handle(method, path, opts), options, () => this.createRequestAdmission(), this.interceptOwner);
+        const lease = createFetchLease({
+            handle: (method, path, opts) => this.handle(method, path, opts),
+            options,
+            admitRequest: () => this.createRequestAdmission(),
+            owner: this.interceptOwner,
+            observe: () => this.#openExchangeObservation(),
+        });
         const handle = {
             restore: () => {
                 lease.restore();
@@ -243,6 +249,27 @@ export class CallableMockInstance {
         this.logger.log("lifecycle", `Interception lease acquired (${this.interceptHandles.size} held)`);
         return handle;
     }
+    /**
+     * Called by the lease right before it consults this mock about one request.
+     * It captures the plugins and the generation the request is admitted under,
+     * so observers piped later, or retired by reset(), never see it.
+     */
+    #openExchangeObservation() {
+        const plugins = this.plugins; // replaced, never mutated
+        if (!hasExchangeObserver(plugins))
+            return undefined; // no exchange is built
+        const generation = this.generations.current;
+        // Same gate as events and history, checked before each observer: one
+        // observer may reset() the mock and uninstall the ones after it.
+        return (exchange) => {
+            runExchangeHooks({
+                plugins,
+                exchange,
+                logger: this.logger,
+                isLive: () => this.generations.isCurrent(generation),
+            });
+        };
+    }
     // ===== Request Handling =====
     async handle(method, path, options, admission) {
         const requestAdmission = admission ?? this.#captureRequestAdmission();

package/dist/generations.d.ts

@@ -18,6 +18,11 @@ export declare class RequestGenerations {
      * emit lifecycle events and record history.
      */
     isCurrent(generation: RequestGeneration): boolean;
+    /**
+     * The live generation, for a caller to compare later with `isCurrent()`.
+     * Reading it admits nothing and never runs an uninstall.
+     */
+    get current(): RequestGeneration;
     /** Count one more in-flight request in the current generation. */
     admit(): RequestGeneration;
     /**

package/dist/generations.js

@@ -18,6 +18,13 @@ export class RequestGenerations {
     isCurrent(generation) {
         return generation === this.#current;
     }
+    /**
+     * The live generation, for a caller to compare later with `isCurrent()`.
+     * Reading it admits nothing and never runs an uninstall.
+     */
+    get current() {
+        return this.#current;
+    }
     /** Count one more in-flight request in the current generation. */
     admit() {
         const generation = this.#current;

package/dist/history.js

@@ -1,62 +1,6 @@
 import { canonicalizePath, normalizePath } from "./constants.js";
 import { SchmockError } from "./errors.js";
-function unavailableHistoryValue(value) {
-    let type = typeof value;
-    if (typeof value === "object" && value !== null) {
-        try {
-            type = Object.prototype.toString.call(value);
-        }
-        catch {
-            type = "object";
-        }
-    }
-    return {
-        kind: "unavailable",
-        reason: "not-structured-cloneable",
-        type,
-    };
-}
-function removeSharedMemory(value, seen = new WeakMap()) {
-    if (typeof value !== "object" || value === null)
-        return value;
-    const existing = seen.get(value);
-    if (existing !== undefined)
-        return existing;
-    if (typeof SharedArrayBuffer !== "undefined" &&
-        value instanceof SharedArrayBuffer) {
-        const copy = Uint8Array.from(new Uint8Array(value)).buffer;
-        seen.set(value, copy);
-        return copy;
-    }
-    if (ArrayBuffer.isView(value) &&
-        typeof SharedArrayBuffer !== "undefined" &&
-        value.buffer instanceof SharedArrayBuffer) {
-        const copy = Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
-        seen.set(value, copy);
-        return copy;
-    }
-    seen.set(value, value);
-    if (value instanceof Map) {
-        const entries = [...value.entries()];
-        value.clear();
-        for (const [key, entryValue] of entries) {
-            value.set(removeSharedMemory(key, seen), removeSharedMemory(entryValue, seen));
-        }
-        return value;
-    }
-    if (value instanceof Set) {
-        const entries = [...value.values()];
-        value.clear();
-        for (const entryValue of entries) {
-            value.add(removeSharedMemory(entryValue, seen));
-        }
-        return value;
-    }
-    for (const key of Reflect.ownKeys(value)) {
-        Reflect.set(value, key, removeSharedMemory(Reflect.get(value, key), seen));
-    }
-    return value;
-}
+import { snapshotNormalizedBody, snapshotValue } from "./snapshot.js";
 /**
  * Reject a history limit that cannot bound anything.
  *
@@ -72,29 +16,6 @@ function assertValidHistoryLimit(limit) {
         throw new SchmockError(`Invalid maxHistorySize: ${String(limit)}. Expected a non-negative integer (0 disables history).`, "INVALID_CONFIG", { maxHistorySize: limit });
     }
 }
-function snapshotHistoryValue(value) {
-    try {
-        return removeSharedMemory(structuredClone(value));
-    }
-    catch {
-        return unavailableHistoryValue(value);
-    }
-}
-/**
- * Snapshot a body that already went through `normalizeResponse`.
- *
- * A normalized body is a string, a `JSON.parse` tree or a fresh byte copy, so
- * it can never hold shared memory: the `removeSharedMemory` walk that caller
- * supplied values need would only re-visit every node for nothing.
- */
-function snapshotNormalizedBody(value) {
-    try {
-        return structuredClone(value);
-    }
-    catch {
-        return unavailableHistoryValue(value);
-    }
-}
 function cloneRecord(r) {
     return {
         method: r.method,
@@ -102,7 +23,7 @@ function cloneRecord(r) {
         params: { ...r.params },
         query: { ...r.query },
         headers: { ...r.headers },
-        body: snapshotHistoryValue(r.body),
+        body: snapshotValue(r.body),
         timestamp: r.timestamp,
         response: {
             status: r.response.status,
@@ -158,7 +79,7 @@ export class RequestHistory {
         return {
             query: { ...request.query },
             headers: { ...request.headers },
-            body: snapshotHistoryValue(request.body),
+            body: snapshotValue(request.body),
         };
     }
     /** Record a matched request, unless its history generation has ended. */

package/dist/index.d.ts

@@ -192,6 +192,22 @@ namespace Schmock {
       error: Error,
       context: PluginContext,
     ): Error | ResponseResult | void | Promise<Error | ResponseResult | void>;
+
+    /**
+     * Observe what a client finally received. Called once for each request this
+     * mock settled through fetch interception (`mock.intercept()`, and the
+     * service-worker relay built on its leases): answered, failed, or aborted
+     * while the mock was answering it. It runs after every adapter hook, so it
+     * sees `beforeResponse` and `errorFormatter` output, the 404 for an
+     * unrouted request and the 400 for a malformed JSON body when passthrough
+     * is off. Not called for requests passed on to the network, for
+     * `mock.handle()`, or for requests that arrived before the last `reset()`
+     * or before this plugin was piped. Observation only: each observer gets its
+     * own frozen snapshot (bodies are copies), the return value is ignored, and
+     * a throw or rejection is logged under the `plugin` debug category without
+     * reaching the client.
+     */
+    onExchange?(exchange: Exchange): void | Promise<void>;
   }
 
   /**
@@ -765,6 +781,20 @@ namespace Schmock {
     hasRoute?(method: HttpMethod, path: string): boolean;
   }
 
+  /**
+   * A relay transport's hold on in-page fetch interception, from
+   * `acquireFetchRelay()` in `@schmock/core/adapter`. While any hold is
+   * active, a fetch the page makes is forwarded to the network unanswered,
+   * with exactly the input and init it was called with, for the relay (a
+   * service worker) to bring back through `routeRelayedRequest()`.
+   */
+  interface FetchRelay {
+    /** Hand fetch back to in-page interception once no hold remains. Idempotent. */
+    release(): void;
+    /** False once released. */
+    readonly active: boolean;
+  }
+
   /** Input to `buildFormattedErrorResponse()`. */
   interface FormattedErrorOptions {
     /** The `errorFormatter` hook, called exactly once. */
@@ -824,6 +854,58 @@ namespace Schmock {
 
   type SchmockEvent = keyof SchmockEventMap;
 
+  // ===== Exchange Observation =====
+
+  /** The request half of an {@link Exchange}: the request as its client sent it, before any adapter `beforeRequest` hook. */
+  interface ExchangeRequest {
+    /** The method as the client sent it. */
+    readonly method: string;
+    /** The absolute request URL without its fragment, as `Response.url` reports it (a relative fetch is resolved against the document base). */
+    readonly url: string;
+    /** Request headers, names lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The body as the mock read it (JSON value, text, form fields, FormData, ArrayBuffer); absent when the request had none or it was never read. The observer's own copy. */
+    readonly body?: unknown;
+  }
+
+  /** The response half of an {@link AnsweredExchange}: what the client received. */
+  interface ExchangeResponse {
+    readonly status: number;
+    /** Headers of the Response the client received, names lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The body before serialization; absent for none (HEAD, 204). The observer's own copy. */
+    readonly body?: unknown;
+  }
+
+  interface ExchangeBase {
+    readonly request: ExchangeRequest;
+    /** `performance.now()` when the transport received the request. */
+    readonly startTime: number;
+    /** `performance.now()` when the client's outcome was settled. */
+    readonly endTime: number;
+  }
+
+  /** The mock answered: `response` is what the client got after `beforeResponse` and `errorFormatter`, including the 404 for an unrouted request and the 400 for a malformed JSON body when passthrough is off. */
+  interface AnsweredExchange extends ExchangeBase {
+    readonly outcome: "answered";
+    readonly response: ExchangeResponse;
+  }
+
+  /** The client's request rejected with `error` (a hook or handler threw and no errorFormatter replaced it, or the formatter threw). */
+  interface FailedExchange extends ExchangeBase {
+    readonly outcome: "failed";
+    /** Exactly the value the client's request rejected with. */
+    readonly error: unknown;
+  }
+
+  /** The client aborted the request while this mock was answering it. */
+  interface AbortedExchange extends ExchangeBase {
+    readonly outcome: "aborted";
+  }
+
+  /** One request a transport delivered to a mock, as its client saw it end. Passed to `Plugin.onExchange`. */
+  type Exchange = AnsweredExchange | FailedExchange | AbortedExchange;
+
   // ===== Introspection Types =====
 
   interface RouteInfo {
@@ -1225,14 +1307,14 @@ export type { HttpErrorReply, HttpIngressErrorCode, NodeRequestLike, NodeRespons
 export { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, serveNodeRequest, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
 export { buildFormattedErrorResponse, normalizeResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
 export { getResponseParts, replaceResponseBody, } from "./response-parser.js";
-export type { AdapterRequest, AdapterRequestOverride, AdapterResponse, 
+export type { AbortedExchange, AdapterRequest, AdapterRequestOverride, AdapterResponse, 
 /**
  * @deprecated Import `AngularAdapterOptions` from `@schmock/angular`; this
  * copy will be removed in the next major version.
  */
-AngularAdapterOptions, CallableMockInstance, CrudOperationMeta, 
+AngularAdapterOptions, AnsweredExchange, CallableMockInstance, CrudOperationMeta, Exchange, ExchangeRequest, ExchangeResponse, 
 /**
  * @deprecated Import `ExpressAdapterOptions` from `@schmock/express`; this
  * copy will be removed in the next major version.
  */
-ExpressAdapterOptions, FakerPluginOptions, FormattedErrorOptions, Generator, GeneratorFunction, GlobalConfig, HttpMethod, InterceptHandle, InterceptOptions, OnSchemaCallback, OnSchemaContext, OpenApiCallbackOptions, OpenApiCallbackRequest, OpenApiOptions, OpenApiRefPolicy, PaginatedResponse, PaginateOptions, PathPrefix, Plugin, PluginContext, PluginHookResult, PluginResult, RequestContext, RequestEndEvent, RequestMatchEvent, RequestNotFoundEvent, RequestOptions, RequestRecord, RequestStartEvent, ResourceOverride, Response, ResponseBody, ResponseHeaderDef, ResponseParts, ResponseResult, RouteConfig, RouteInfo, RouteKey, Schema, SchemaDefinition, SchemaGenerationContext, SchmockEvent, SchmockEventMap, SeedConfig, SeedSource, ServerInfo, StaticData, } from "./types.js";
+ExpressAdapterOptions, FailedExchange, FakerPluginOptions, FormattedErrorOptions, Generator, GeneratorFunction, GlobalConfig, HttpMethod, InterceptHandle, InterceptOptions, OnSchemaCallback, OnSchemaContext, OpenApiCallbackOptions, OpenApiCallbackRequest, OpenApiOptions, OpenApiRefPolicy, PaginatedResponse, PaginateOptions, PathPrefix, Plugin, PluginContext, PluginHookResult, PluginResult, RequestContext, RequestEndEvent, RequestMatchEvent, RequestNotFoundEvent, RequestOptions, RequestRecord, RequestStartEvent, ResourceOverride, Response, ResponseBody, ResponseHeaderDef, ResponseParts, ResponseResult, RouteConfig, RouteInfo, RouteKey, Schema, SchemaDefinition, SchemaGenerationContext, SchmockEvent, SchmockEventMap, SeedConfig, SeedSource, ServerInfo, StaticData, } from "./types.js";

package/dist/interceptor.d.ts

@@ -8,6 +8,23 @@
  * normalized again.
  */
 export declare const NORMALIZED_ADMISSION_KEY: unique symbol;
+export type ExchangeObserver = (exchange: Schmock.Exchange) => void;
+/** Called synchronously right before one consultation of a lease; undefined when nothing observes the lease's mock. */
+type ExchangeObservationOpener = () => ExchangeObserver | undefined;
+/**
+ * Makes every intercepted fetch skip routing and go straight to the baseline
+ * until released. Holds stack: fetches resume once every hold is released.
+ * It never touches `globalThis.fetch`.
+ */
+export declare function acquireFetchRelay(): Schmock.FetchRelay;
+/**
+ * Routes a request that a service worker relayed to the page through the
+ * newest session's leases. Resolves `undefined` when nothing answers it (no
+ * lease, or a route miss with passthrough) and never calls the baseline fetch,
+ * so the caller decides how the request reaches the network. Rejects with the
+ * request's abort reason when it is aborted mid-route.
+ */
+export declare function routeRelayedRequest(request: Request): Promise<Response | undefined>;
 /**
  * Create a fetch interceptor that routes requests through mock.handle().
  *
@@ -17,3 +34,12 @@ export declare const NORMALIZED_ADMISSION_KEY: unique symbol;
  * handler — and emits its lifecycle events — once per request it is asked.
  */
 export declare function createFetchInterceptor(handle: Schmock.MockRequestHandler, options?: Schmock.InterceptOptions, admitRequest?: () => Schmock.RequestAdmission, owner?: symbol): Schmock.InterceptHandle;
+interface FetchLeaseSpec {
+    handle: Schmock.MockRequestHandler;
+    options?: Schmock.InterceptOptions;
+    admitRequest?: () => Schmock.RequestAdmission;
+    owner?: symbol;
+    observe?: ExchangeObservationOpener;
+}
+export declare function createFetchLease(spec: FetchLeaseSpec): Schmock.InterceptHandle;
+export {};

package/dist/interceptor.js

@@ -2,6 +2,7 @@
 import { awaitWithAbort, throwIfAborted } from "./abort.js";
 import { canonicalizePath, getResponseException, isHttpMethod, isRouteNotFound, matchPathPrefix, parsePathPrefix, } from "./constants.js";
 import { buildFormattedErrorResponse, buildJsonErrorResponse, normalizeResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
+import { snapshotRequestBody } from "./snapshot.js";
 const PASSTHROUGH = Symbol("schmock.fetch.passthrough");
 // A lease whose baseUrl filter rejected the request never reached its handler:
 // it was not interested in the request at all, and claimed nothing.
@@ -25,6 +26,11 @@ function isNormalizedAdmission(admission) {
         Reflect.get(admission, NORMALIZED_ADMISSION_KEY) === true);
 }
 let activeSession;
+/**
+ * Holds taken through acquireFetchRelay(). Module-wide rather than per
+ * session, so a dispatcher that a third-party wrapper captured obeys them too.
+ */
+const fetchRelayHolds = new Set();
 function getRelativeRequestBase() {
     const candidates = [
         typeof document === "undefined" ? undefined : document.baseURI,
@@ -111,58 +117,101 @@ function normalizeFetchRequest(input, init) {
         origin,
     };
 }
+/**
+ * Whether `error` is the signal's own abort. An abort that lands after the
+ * lease already rejected with another error leaves that error the outcome.
+ */
+function isAbortOf(signal, error) {
+    if (!signal.aborted)
+        return false;
+    if ("reason" in signal && signal.reason !== undefined) {
+        return error === signal.reason;
+    }
+    return error instanceof Error && error.name === "AbortError";
+}
+async function routeThroughLeases(leases, normalizedRequest, startTime) {
+    const { signal } = normalizedRequest.request;
+    throwIfAborted(signal);
+    // A mock is asked each distinct effective request at most once, however
+    // many leases it holds: without this, nested providers on one mock would
+    // run handle() — and emit request:start/notfound/end — once per lease.
+    // The key is the request each lease would issue after its own baseUrl
+    // filter and beforeRequest, so an older lease whose hook rewrites the
+    // request (an outer provider stripping "/api") still gets its turn.
+    const consultedRequests = new Map();
+    const claimFor = (owner) => (requestKey) => {
+        if (owner === undefined)
+            return true;
+        let keys = consultedRequests.get(owner);
+        if (keys === undefined) {
+            keys = new Set();
+            consultedRequests.set(owner, keys);
+        }
+        if (keys.has(requestKey))
+            return false;
+        keys.add(requestKey);
+        return true;
+    };
+    for (let index = leases.length - 1; index >= 0; index -= 1) {
+        const registered = leases[index];
+        // Synchronously before the call: the handler admits before its first await,
+        // so the generation the opener captures is the one the request runs in.
+        const observe = registered.observe?.();
+        const draft = { observed: observe !== undefined };
+        let result;
+        try {
+            result = await awaitWithAbort(registered.intercept({
+                request: normalizedRequest,
+                claim: claimFor(registered.owner),
+                draft,
+            }), signal);
+            throwIfAborted(signal);
+        }
+        catch (error) {
+            if (observe !== undefined) {
+                if (!isAbortOf(signal, error)) {
+                    notify(observe, () => failedExchange(normalizedRequest, draft, error, startTime));
+                }
+                else if (draft.response !== undefined || draft.answers?.() === true) {
+                    notify(observe, () => abortedExchange(normalizedRequest, draft, startTime));
+                }
+            }
+            throw error;
+        }
+        // FILTERED: this lease was not interested, so a sibling lease may be.
+        // ALREADY_CONSULTED: the mock already answered this exact request.
+        // PASSTHROUGH: the mock has no route for it. All three move on.
+        if (result === FILTERED ||
+            result === ALREADY_CONSULTED ||
+            result === PASSTHROUGH) {
+            continue;
+        }
+        const response = result;
+        if (observe !== undefined) {
+            notify(observe, () => answeredExchange(normalizedRequest, draft, response, startTime));
+        }
+        return response;
+    }
+    return PASSTHROUGH;
+}
 function createInterceptorSession() {
     const baselineFetch = globalThis.fetch;
     const interceptors = [];
     const dispatchFetch = async (input, init) => {
         const snapshot = interceptors.slice();
-        if (snapshot.length === 0) {
+        if (snapshot.length === 0 || fetchRelayHolds.size > 0) {
             return baselineFetch(input, init);
         }
+        const startTime = performance.now();
         const normalizedRequest = normalizeFetchRequest(input, init);
-        throwIfAborted(normalizedRequest.request.signal);
-        // A mock is asked each distinct effective request at most once, however
-        // many leases it holds: without this, nested providers on one mock would
-        // run handle() — and emit request:start/notfound/end — once per lease.
-        // The key is the request each lease would issue after its own baseUrl
-        // filter and beforeRequest, so an older lease whose hook rewrites the
-        // request (an outer provider stripping "/api") still gets its turn.
-        const consultedRequests = new Map();
-        const claimFor = (owner) => (requestKey) => {
-            if (owner === undefined)
-                return true;
-            let keys = consultedRequests.get(owner);
-            if (keys === undefined) {
-                keys = new Set();
-                consultedRequests.set(owner, keys);
-            }
-            if (keys.has(requestKey))
-                return false;
-            keys.add(requestKey);
-            return true;
-        };
-        for (let index = snapshot.length - 1; index >= 0; index -= 1) {
-            const registered = snapshot[index];
-            const result = await awaitWithAbort(registered.intercept({
-                request: normalizedRequest,
-                claim: claimFor(registered.owner),
-            }), normalizedRequest.request.signal);
-            throwIfAborted(normalizedRequest.request.signal);
-            // FILTERED: this lease was not interested, so a sibling lease may be.
-            // ALREADY_CONSULTED: the mock already answered this exact request.
-            // PASSTHROUGH: the mock has no route for it. All three move on.
-            if (result === FILTERED ||
-                result === ALREADY_CONSULTED ||
-                result === PASSTHROUGH) {
-                continue;
-            }
-            return result;
-        }
+        const answer = await routeThroughLeases(snapshot, normalizedRequest, startTime);
+        if (answer !== PASSTHROUGH)
+            return answer;
         return awaitWithAbort(baselineFetch(normalizedRequest.request), normalizedRequest.request.signal);
     };
     return { baselineFetch, dispatchFetch, interceptors };
 }
-function registerInterceptor(intercept, applyOptions, owner) {
+function registerInterceptor(intercept, applyOptions, owner, observe) {
     let session = activeSession;
     if (!session || globalThis.fetch !== session.dispatchFetch) {
         session = createInterceptorSession();
@@ -170,7 +219,7 @@ function registerInterceptor(intercept, applyOptions, owner) {
         globalThis.fetch = session.dispatchFetch;
     }
     const token = Symbol("schmock.fetch.interceptor");
-    session.interceptors.push({ token, owner, intercept });
+    session.interceptors.push({ token, owner, intercept, observe });
     let active = true;
     return {
         restore() {
@@ -204,15 +253,100 @@ function registerInterceptor(intercept, applyOptions, owner) {
         },
     };
 }
+/**
+ * Makes every intercepted fetch skip routing and go straight to the baseline
+ * until released. Holds stack: fetches resume once every hold is released.
+ * It never touches `globalThis.fetch`.
+ */
+export function acquireFetchRelay() {
+    const token = Symbol("schmock.fetch.relay");
+    fetchRelayHolds.add(token);
+    return {
+        release() {
+            fetchRelayHolds.delete(token);
+        },
+        get active() {
+            return fetchRelayHolds.has(token);
+        },
+    };
+}
+/**
+ * Routes a request that a service worker relayed to the page through the
+ * newest session's leases. Resolves `undefined` when nothing answers it (no
+ * lease, or a route miss with passthrough) and never calls the baseline fetch,
+ * so the caller decides how the request reaches the network. Rejects with the
+ * request's abort reason when it is aborted mid-route.
+ */
+export async function routeRelayedRequest(request) {
+    const startTime = performance.now();
+    const leases = activeSession?.interceptors.slice() ?? [];
+    if (leases.length === 0)
+        return undefined;
+    const normalizedRequest = normalizeFetchRequest(request);
+    const answer = await routeThroughLeases(leases, normalizedRequest, startTime);
+    return answer === PASSTHROUGH ? undefined : answer;
+}
 function extractQuery(url) {
     return Object.fromEntries(url.searchParams);
 }
-function extractHeaders(request) {
-    const headers = {};
-    request.headers.forEach((value, key) => {
-        headers[key.toLowerCase()] = value;
+function headerRecordOf(headers) {
+    const record = {};
+    headers.forEach((value, key) => {
+        record[key.toLowerCase()] = value;
     });
-    return headers;
+    return record;
+}
+function extractHeaders(request) {
+    return headerRecordOf(request.headers);
+}
+/** Hand an exchange to its observer. */
+function notify(observe, build) {
+    try {
+        observe(build());
+    }
+    catch {
+        // observation never changes the fetch outcome
+    }
+}
+function exchangeRequestOf({ request, url }, draft) {
+    return {
+        method: request.method,
+        url: responseUrlOf(url),
+        headers: extractHeaders(request),
+        ...(draft.requestBody !== undefined ? { body: draft.requestBody } : {}),
+    };
+}
+function answeredExchange(normalizedRequest, draft, response, startTime) {
+    return {
+        outcome: "answered",
+        request: exchangeRequestOf(normalizedRequest, draft),
+        response: {
+            status: response.status,
+            headers: headerRecordOf(response.headers),
+            ...(draft.response?.body !== undefined
+                ? { body: draft.response.body }
+                : {}),
+        },
+        startTime,
+        endTime: performance.now(),
+    };
+}
+function failedExchange(normalizedRequest, draft, error, startTime) {
+    return {
+        outcome: "failed",
+        request: exchangeRequestOf(normalizedRequest, draft),
+        error,
+        startTime,
+        endTime: performance.now(),
+    };
+}
+function abortedExchange(normalizedRequest, draft, startTime) {
+    return {
+        outcome: "aborted",
+        request: exchangeRequestOf(normalizedRequest, draft),
+        startTime,
+        endTime: performance.now(),
+    };
 }
 function normalizeMediaType(contentType) {
     return contentType?.split(";", 1)[0].trim().toLowerCase() ?? "";
@@ -253,7 +387,13 @@ async function extractNonJsonBody(request) {
 function routeProbeOf(admission) {
     if (admission === undefined)
         return undefined;
-    const probe = Reflect.get(admission, "hasRoute");
+    let probe;
+    try {
+        probe = Reflect.get(admission, "hasRoute");
+    }
+    catch {
+        return undefined;
+    }
     if (typeof probe !== "function")
         return undefined;
     // Anything but a definite `false` counts as a route, so an unexpected
@@ -284,6 +424,7 @@ function createFetchResponse(normalized, context) {
     // A constructed Response has an empty url. Real fetch reports the request
     // URL, and code resolving links with `new URL(next, res.url)` needs it.
     Object.defineProperty(response, "url", { value: context.url });
+    context.draft.response = normalized;
     return response;
 }
 function toFetchResponse(response, context) {
@@ -344,12 +485,16 @@ function effectiveRequestKey(method, path) {
  * handler — and emits its lifecycle events — once per request it is asked.
  */
 export function createFetchInterceptor(handle, options = {}, admitRequest, owner) {
+    return createFetchLease({ handle, options, admitRequest, owner });
+}
+export function createFetchLease(spec) {
+    const { handle, admitRequest, owner, observe } = spec;
     // The options live in a mutable cell that each request reads once at its
     // start. Reconfiguring a lease in place is what lets an adapter apply new
     // hooks without re-registering — re-registration would move the lease to the
     // front of the dispatch order and steal precedence from other mocks.
-    let currentOptions = options;
-    return registerInterceptor(async ({ request: { request, url, origin }, claim, }) => {
+    let currentOptions = spec.options ?? {};
+    return registerInterceptor(async ({ request: { request, url, origin }, claim, draft, }) => {
         const { baseUrl, passthrough = true, beforeRequest, beforeResponse, errorFormatter, } = currentOptions;
         const path = canonicalizePath(url.pathname);
         // BaseUrl filter — non-matching requests go straight to real fetch.
@@ -371,6 +516,7 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
         const context = {
             method: request.method,
             url: responseUrlOf(url),
+            draft,
         };
         const initialMethod = request.method.toUpperCase();
         // Without a beforeRequest hook (which may change the method or path)
@@ -399,7 +545,13 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
         // it. On a definite miss the body is never read: the request reaches
         // the network untouched, and handle() still runs, without a body, so
         // request:start/notfound/end are emitted exactly as before.
-        const routeProbe = passthrough && !beforeRequest ? routeProbeOf(admission) : undefined;
+        const routeExists = routeProbeOf(admission);
+        const answersFor = (method, routedPath) => () => !passthrough ||
+            routeExists === undefined ||
+            routeExists(method, routedPath);
+        if (beforeRequest === undefined)
+            draft.answers = answersFor(initialMethod, path);
+        const routeProbe = passthrough && !beforeRequest ? routeExists : undefined;
         // The request handed to errorFormatter: the latest one this lease built,
         // so it reflects beforeRequest once that hook has returned.
         let formatterRequest;
@@ -407,6 +559,8 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
             const body = routeProbe !== undefined && !routeProbe(initialMethod, path)
                 ? { value: undefined, malformedJson: false }
                 : await awaitWithAbort(extractBody(request), request.signal);
+            if (draft.observed)
+                draft.requestBody = snapshotRequestBody(body.value);
             throwIfAborted(request.signal);
             // With passthrough off the lease owns every request that reaches it,
             // as the Node server does, so a JSON body that does not parse gets
@@ -449,6 +603,9 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
                 !claim(effectiveRequestKey(effectiveMethod, adapterRequest.path))) {
                 return ALREADY_CONSULTED;
             }
+            if (beforeRequest !== undefined) {
+                draft.answers = answersFor(effectiveMethod, adapterRequest.path);
+            }
             const requestOptions = {
                 headers: adapterRequest.headers,
                 body: adapterRequest.body,
@@ -531,5 +688,5 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
         }
     }, (nextOptions) => {
         currentOptions = nextOptions ?? {};
-    }, owner);
+    }, owner, observe);
 }

package/dist/plugin-hooks.d.ts

@@ -2,10 +2,27 @@ import type { DebugLogger } from "./debug-logger.js";
 export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
 /**
  * Reject, when it is piped, a plugin that could never work: one without a
- * `process` function answered every matched request with a 500 instead.
- * Only shapes that already failed are rejected, so no working setup breaks.
+ * `process` function (it answered every matched request with a 500), or one
+ * whose `install`, `beforeRequest` or `onExchange` is a truthy non-function.
+ * The `install` and `beforeRequest` shapes already failed before this check;
+ * `onExchange` is new, so no working setup breaks.
  */
 export declare function assertValidPlugin(plugin: unknown): asserts plugin is Schmock.Plugin;
+/** Whether any plugin observes exchanges (a function `onExchange`). */
+export declare function hasExchangeObserver(plugins: readonly Schmock.Plugin[]): boolean;
+/**
+ * Report one settled exchange to each plugin's `onExchange`, in pipe order.
+ * Every observer gets its own frozen snapshot, built right before its call, so
+ * none sees or alters another's copy. A throwing or rejecting observer is
+ * logged and never stops the others. Reporting stops as soon as `isLive`
+ * returns false.
+ */
+export declare function runExchangeHooks(input: {
+    plugins: readonly Schmock.Plugin[];
+    exchange: Schmock.Exchange;
+    logger: Pick<DebugLogger, "log">;
+    isLive?: () => boolean;
+}): void;
 /** The live reads a hook's instance forwards to the mock. */
 export interface HookReadAccess {
     history(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord[];

package/dist/plugin-hooks.js

@@ -1,4 +1,5 @@
 import { errorMessage, SchmockError } from "./errors.js";
+import { snapshotNormalizedBody, snapshotRequestBody } from "./snapshot.js";
 const PLUGIN_HOOK_ERROR_CODES = {
     install: {
         expired: "PLUGIN_INSTALL_SCOPE_EXPIRED",
@@ -10,13 +11,16 @@ const PLUGIN_HOOK_ERROR_CODES = {
     },
 };
 /**
- * Optional hooks that break the plugin when set to a truthy non-function:
- * `install` threw a TypeError from pipe() and `beforeRequest` failed every
- * matched request. Falsy values (`onError: null`, `install: false`) are how
- * callers switch a hook off and keep working; `onError`/`uninstall` failures
- * only ever surfaced on paths that already fail or log, so they are left alone.
+ * Optional hooks rejected when set to a truthy non-function. `install` threw a
+ * TypeError from pipe() and `beforeRequest` failed every matched request, so
+ * rejecting them breaks no working setup. `onExchange` is new: no working
+ * setup relies on another shape, and a non-function would otherwise silently
+ * observe nothing. Falsy values (`onError: null`, `install: false`,
+ * `onExchange: undefined`) still switch a hook off. `onError`/`uninstall`
+ * failures only ever surfaced on paths that already fail or log, so they are
+ * left alone.
  */
-const EAGER_PLUGIN_HOOKS = ["install", "beforeRequest"];
+const EAGER_PLUGIN_HOOKS = ["install", "beforeRequest", "onExchange"];
 export function isThenable(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -41,8 +45,10 @@ function describeInvalidPlugin(plugin) {
 }
 /**
  * Reject, when it is piped, a plugin that could never work: one without a
- * `process` function answered every matched request with a 500 instead.
- * Only shapes that already failed are rejected, so no working setup breaks.
+ * `process` function (it answered every matched request with a 500), or one
+ * whose `install`, `beforeRequest` or `onExchange` is a truthy non-function.
+ * The `install` and `beforeRequest` shapes already failed before this check;
+ * `onExchange` is new, so no working setup breaks.
  */
 export function assertValidPlugin(plugin) {
     const reason = describeInvalidPlugin(plugin);
@@ -57,6 +63,84 @@ export function assertValidPlugin(plugin) {
         reason,
     });
 }
+/** Whether any plugin observes exchanges (a function `onExchange`). */
+export function hasExchangeObserver(plugins) {
+    return plugins.some((plugin) => typeof plugin.onExchange === "function");
+}
+/** A fresh, frozen copy of an exchange, built for one observer. */
+function snapshotExchange(exchange) {
+    const { request } = exchange;
+    const requestCopy = Object.freeze({
+        method: request.method,
+        url: request.url,
+        headers: Object.freeze({ ...request.headers }),
+        ...(request.body !== undefined
+            ? { body: snapshotRequestBody(request.body) }
+            : {}),
+    });
+    const { startTime, endTime } = exchange;
+    if (exchange.outcome === "answered") {
+        const { response } = exchange;
+        return Object.freeze({
+            outcome: exchange.outcome,
+            request: requestCopy,
+            response: Object.freeze({
+                status: response.status,
+                headers: Object.freeze({ ...response.headers }),
+                ...(response.body !== undefined
+                    ? { body: snapshotNormalizedBody(response.body) }
+                    : {}),
+            }),
+            startTime,
+            endTime,
+        });
+    }
+    if (exchange.outcome === "failed") {
+        return Object.freeze({
+            outcome: exchange.outcome,
+            request: requestCopy,
+            error: exchange.error,
+            startTime,
+            endTime,
+        });
+    }
+    return Object.freeze({
+        outcome: exchange.outcome,
+        request: requestCopy,
+        startTime,
+        endTime,
+    });
+}
+/**
+ * Report one settled exchange to each plugin's `onExchange`, in pipe order.
+ * Every observer gets its own frozen snapshot, built right before its call, so
+ * none sees or alters another's copy. A throwing or rejecting observer is
+ * logged and never stops the others. Reporting stops as soon as `isLive`
+ * returns false.
+ */
+export function runExchangeHooks(input) {
+    const { plugins, exchange, logger, isLive } = input;
+    for (const plugin of plugins) {
+        if (isLive !== undefined && !isLive())
+            return;
+        try {
+            const observe = plugin.onExchange;
+            if (typeof observe !== "function")
+                continue;
+            const result = Reflect.apply(observe, plugin, [
+                snapshotExchange(exchange),
+            ]);
+            if (isThenable(result)) {
+                void Promise.resolve(result).catch((error) => {
+                    logger.log("plugin", `Plugin ${plugin.name} onExchange rejected: ${errorMessage(error)}`);
+                });
+            }
+        }
+        catch (error) {
+            logger.log("plugin", `Plugin ${plugin.name} onExchange failed: ${errorMessage(error)}`);
+        }
+    }
+}
 /**
  * The instance a plugin hook receives. Reads are live; route registration is
  * allowed only when the hook passes `registerRoute` (install does, uninstall

package/dist/snapshot.d.ts

@@ -0,0 +1,14 @@
+export declare function snapshotValue(value: unknown): unknown;
+/**
+ * Snapshot a body that already went through `normalizeResponse`.
+ *
+ * A normalized body is a string, a `JSON.parse` tree or a fresh byte copy, so
+ * it can never hold shared memory: the `removeSharedMemory` walk that caller
+ * supplied values need would only re-visit every node for nothing.
+ */
+export declare function snapshotNormalizedBody(value: unknown): unknown;
+/**
+ * Snapshot a request body as a transport read it. A `FormData` is copied entry
+ * by entry, since `structuredClone` cannot copy one.
+ */
+export declare function snapshotRequestBody(body: unknown): unknown;

package/dist/snapshot.js

@@ -0,0 +1,98 @@
+function unavailableValue(value) {
+    let type = typeof value;
+    if (typeof value === "object" && value !== null) {
+        try {
+            type = Object.prototype.toString.call(value);
+        }
+        catch {
+            type = "object";
+        }
+    }
+    return {
+        kind: "unavailable",
+        reason: "not-structured-cloneable",
+        type,
+    };
+}
+function removeSharedMemory(value, seen = new WeakMap()) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (typeof SharedArrayBuffer !== "undefined" &&
+        value instanceof SharedArrayBuffer) {
+        const copy = Uint8Array.from(new Uint8Array(value)).buffer;
+        seen.set(value, copy);
+        return copy;
+    }
+    if (ArrayBuffer.isView(value) &&
+        typeof SharedArrayBuffer !== "undefined" &&
+        value.buffer instanceof SharedArrayBuffer) {
+        const copy = Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+        seen.set(value, copy);
+        return copy;
+    }
+    seen.set(value, value);
+    if (value instanceof Map) {
+        const entries = [...value.entries()];
+        value.clear();
+        for (const [key, entryValue] of entries) {
+            value.set(removeSharedMemory(key, seen), removeSharedMemory(entryValue, seen));
+        }
+        return value;
+    }
+    if (value instanceof Set) {
+        const entries = [...value.values()];
+        value.clear();
+        for (const entryValue of entries) {
+            value.add(removeSharedMemory(entryValue, seen));
+        }
+        return value;
+    }
+    for (const key of Reflect.ownKeys(value)) {
+        Reflect.set(value, key, removeSharedMemory(Reflect.get(value, key), seen));
+    }
+    return value;
+}
+export function snapshotValue(value) {
+    try {
+        return removeSharedMemory(structuredClone(value));
+    }
+    catch {
+        return unavailableValue(value);
+    }
+}
+/**
+ * Snapshot a body that already went through `normalizeResponse`.
+ *
+ * A normalized body is a string, a `JSON.parse` tree or a fresh byte copy, so
+ * it can never hold shared memory: the `removeSharedMemory` walk that caller
+ * supplied values need would only re-visit every node for nothing.
+ */
+export function snapshotNormalizedBody(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        return unavailableValue(value);
+    }
+}
+/**
+ * Snapshot a request body as a transport read it. A `FormData` is copied entry
+ * by entry, since `structuredClone` cannot copy one.
+ */
+export function snapshotRequestBody(body) {
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        try {
+            const copy = new FormData();
+            for (const [key, value] of body.entries())
+                copy.append(key, value);
+            return copy;
+        }
+        catch {
+            return unavailableValue(body);
+        }
+    }
+    return snapshotValue(body);
+}

package/dist/types.d.ts

@@ -63,3 +63,10 @@ export type PathPrefix = Schmock.PathPrefix;
 export type FormattedErrorOptions = Schmock.FormattedErrorOptions;
 export type MockRequestHandler = Schmock.MockRequestHandler;
 export type RequestAdmission = Schmock.RequestAdmission;
+export type FetchRelay = Schmock.FetchRelay;
+export type Exchange = Schmock.Exchange;
+export type ExchangeRequest = Schmock.ExchangeRequest;
+export type ExchangeResponse = Schmock.ExchangeResponse;
+export type AnsweredExchange = Schmock.AnsweredExchange;
+export type FailedExchange = Schmock.FailedExchange;
+export type AbortedExchange = Schmock.AbortedExchange;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/core",
   "description": "Core functionality for Schmock",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "type": "module",
   "repository": {
     "type": "git",