@equinor/fusion-framework-module-http 8.0.5 → 8.1.0-next.0

package/dist/types/configurator.d.ts

@@ -1,6 +1,6 @@
 import { HttpRequestHandler } from './lib/operators';
 import type { FetchRequest, IHttpClient } from './lib/client';
-import type { IHttpRequestHandler, IHttpResponseHandler } from './lib/operators';
+import type { HttpMiddleware, IHttpMiddlewareHandler, IHttpRequestHandler, IHttpResponseHandler } from './lib/operators';
 /**
  * Represents the options for constructing an `IHttpClient` instance.
  *
@@ -45,6 +45,12 @@ export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
     requestHandler?: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
     /** The response handler to be used by the `IHttpClient` instance. */
     responseHandler?: IHttpResponseHandler<HttpClientResponseType<TClient>>;
+    /**
+     * Middleware wrapping the network call, overriding {@link HttpClientConfigurator.addMiddleware}
+     * for this client only. Rarely needed — most middleware belongs on the configurator so it
+     * applies to every client, and still runs the same way against a mocked client in tests.
+     */
+    middlewareHandler?: IHttpMiddlewareHandler;
 }
 /**
  * Utility type that extracts the request init type from an `IHttpClient` implementation.
@@ -73,6 +79,23 @@ export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClie
     readonly clients: Record<string, HttpClientOptions<TClient>>;
     readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
     readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
+    readonly defaultHttpMiddlewareHandler: IHttpMiddlewareHandler;
+    /**
+     * Registers middleware wrapping the network call for every client this configurator builds —
+     * retries, caching, telemetry, circuit breaking. Register it wherever the app configures its
+     * real HTTP clients; because it wraps `_performFetch` rather than replacing it, the same
+     * registration still runs, unaltered, against a mocked client in tests.
+     * @param middleware - The middleware to register.
+     * @returns The configurator so registrations can be chained.
+     * @example
+     * ```ts
+     * configurator.http.addMiddleware(async (uri, init, next) => {
+     *   const response = await next(uri, init);
+     *   return response.ok ? response : next(uri, init);
+     * });
+     * ```
+     */
+    addMiddleware(middleware: HttpMiddleware): IHttpClientConfigurator<TClient>;
     /**
      * Registers or updates a named client configuration.
      * @param name - The client key used later with `createClient(name)`.
@@ -128,6 +151,8 @@ export declare class HttpClientConfigurator<TClient extends IHttpClient> impleme
     readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
     /** Default request handler pipeline cloned into each created client instance. */
     readonly defaultHttpRequestHandler: HttpRequestHandler<HttpClientRequestInitType<TClient>>;
+    /** Default middleware chain cloned into each created client instance. */
+    readonly defaultHttpMiddlewareHandler: IHttpMiddlewareHandler;
     /**
      * Creates a configurator with the default client constructor.
      * @param client - The default client constructor used when `ctor` is not configured per client.
@@ -136,6 +161,8 @@ export declare class HttpClientConfigurator<TClient extends IHttpClient> impleme
     /** @inheritdoc */
     hasClient(name: string): boolean;
     /** @inheritdoc */
+    addMiddleware(middleware: HttpMiddleware): HttpClientConfigurator<TClient>;
+    /** @inheritdoc */
     configureClient<T extends TClient>(name: string, args: string | HttpClientOptions<T> | HttpClientOptions<T>['onCreate']): HttpClientConfigurator<TClient>;
 }
 export default HttpClientConfigurator;

package/dist/types/lib/client/client.d.ts

@@ -1,6 +1,6 @@
 import { Subject } from 'rxjs';
 import type { Observable, ObservableInput } from 'rxjs';
-import type { IHttpRequestHandler, IHttpResponseHandler } from '../operators';
+import type { IHttpMiddlewareHandler, IHttpRequestHandler, IHttpResponseHandler } from '../operators';
 import type { BlobResult, FetchRequest, FetchRequestInit, FetchResponse, IHttpClient, JsonRequest, StreamResponse } from './types';
 import { type ServerSentEvent, type SseSelectorOptions } from '../selectors/create-sse-selector';
 /**
@@ -14,6 +14,7 @@ import { type ServerSentEvent, type SseSelectorOptions } from '../selectors/crea
 export type HttpClientCreateOptions<TRequest extends FetchRequest = FetchRequest, TResponse = Response> = {
     requestHandler: IHttpRequestHandler<TRequest>;
     responseHandler: IHttpResponseHandler<TResponse>;
+    middlewareHandler: IHttpMiddlewareHandler;
 };
 /** Base http client for executing requests */
 export declare class HttpClient<TRequest extends FetchRequest = FetchRequest, TResponse extends FetchResponse = FetchResponse> implements IHttpClient<TRequest, TResponse> {
@@ -28,6 +29,12 @@ export declare class HttpClient<TRequest extends FetchRequest = FetchRequest, TR
      * This property is part of the `HttpClientCreateOptions` configuration object used to create an `HttpClient` instance.
      */
     readonly responseHandler: IHttpResponseHandler<TResponse>;
+    /**
+     * Middleware wrapping the network call, for cross-cutting concerns such as retries,
+     * caching, or telemetry. This property is part of the `HttpClientCreateOptions`
+     * configuration object used to create an `HttpClient` instance.
+     */
+    readonly middlewareHandler: IHttpMiddlewareHandler;
     /**
      * A stream of requests that are about to be executed.
      * This property is used internally by the `HttpClient` class to manage the lifecycle of requests.
@@ -179,7 +186,9 @@ export declare class HttpClient<TRequest extends FetchRequest = FetchRequest, TR
     /**
      * Aborts any ongoing HTTP requests made by this `IHttpClient` instance.
      * This will trigger the `takeUntil` operator in the `_fetch$` method,
-     * causing any in-flight requests to be cancelled.
+     * causing any in-flight requests to be cancelled, and abort the
+     * per-request `AbortSignal` passed through to `_performFetch`, so the
+     * underlying network call is cancelled even behind registered middleware.
      */
     abort(): void;
     /**
@@ -201,6 +210,21 @@ export declare class HttpClient<TRequest extends FetchRequest = FetchRequest, TR
      * 6. Cancels the request if the `_abort$` observable emits.
      */
     protected _fetch$<T = TResponse>(path: string, args?: FetchRequestInit<T, TRequest, TResponse>): Observable<T>;
+    /**
+     * Performs the actual network call for a prepared request.
+     *
+     * @remarks
+     * Isolated from {@link _fetch$} so a test double can replace only this step —
+     * matching a request against registered route handlers instead of reaching
+     * the network — while everything around it (request preparation, the
+     * response pipeline, abort handling) runs unchanged. See
+     * `@equinor/fusion-framework-module-http/mock`.
+     *
+     * @param uri - The fully resolved URL for the request.
+     * @param init - The prepared `fetch` request options.
+     * @returns An observable of the raw `Response`, ahead of {@link _prepareResponse}.
+     */
+    protected _performFetch(uri: string, init: RequestInit): ObservableInput<Response>;
     /**
      * Prepares the request by passing it through the `requestHandler.process()` method.
      * This method is an implementation detail of the `_fetch$()` method, and is not part of the public API.

package/dist/types/lib/operators/HttpMiddlewareHandler.d.ts

@@ -0,0 +1,24 @@
+import type { Observable } from 'rxjs';
+import type { HttpMiddleware, HttpMiddlewareNext, IHttpMiddlewareHandler } from './types';
+/**
+ * Composes registered {@link HttpMiddleware} into a single execution pipeline wrapping the
+ * network call, so retries, caching, telemetry, or circuit-breaking can wrap `_performFetch`
+ * without touching request or response payload transforms.
+ *
+ * @see {@link HttpClient}
+ */
+export declare class HttpMiddlewareHandler implements IHttpMiddlewareHandler {
+    #private;
+    /**
+     * Constructs a handler, optionally cloning another handler's registered middleware.
+     * @param source - An existing handler to clone the registered middleware from.
+     */
+    constructor(source?: IHttpMiddlewareHandler);
+    /** @inheritdoc */
+    get middleware(): readonly HttpMiddleware[];
+    /** @inheritdoc */
+    use(middleware: HttpMiddleware): HttpMiddlewareHandler;
+    /** @inheritdoc */
+    process(uri: string, init: RequestInit, terminal: HttpMiddlewareNext): Observable<Response>;
+}
+export default HttpMiddlewareHandler;

package/dist/types/lib/operators/index.d.ts

@@ -1,5 +1,6 @@
 export { HttpRequestHandler } from './HttpRequestHandler';
 export { HttpResponseHandler } from './HttpResponseHandler';
+export { HttpMiddlewareHandler } from './HttpMiddlewareHandler';
 export { ProcessOperators } from './ProcessOperators';
 export { capitalizeRequestMethodOperator } from './capitalize-request-method-operator';
 export { requestValidationOperator } from './request-validation-operator';

package/dist/types/lib/operators/types.d.ts

@@ -1,4 +1,4 @@
-import type { Observable } from 'rxjs';
+import type { Observable, ObservableInput } from 'rxjs';
 import type { FetchRequest } from '../client';
 /**
  * A process operator that takes a request of type `T` and returns a transformed request of type `R`, or `void`, or a Promise that resolves to `R` or `void`.
@@ -76,3 +76,76 @@ export interface IHttpRequestHandler<T extends FetchRequest = FetchRequest> exte
  */
 export interface IHttpResponseHandler<T = Response> extends IProcessOperators<T> {
 }
+/**
+ * Continues an HTTP request by resolving the given (already-processed) request into a response.
+ *
+ * @remarks
+ * The terminal `next` passed to the outermost {@link HttpMiddleware} ultimately resolves to
+ * `HttpClient._performFetch` — the same overridable seam the mock system replaces — so
+ * middleware wraps around either the real network call or a mocked one transparently.
+ *
+ * @param uri - The fully resolved URL for the request.
+ * @param init - The prepared `fetch` request options.
+ * @returns The resulting `Response`, or an observable input of it.
+ */
+export type HttpMiddlewareNext = (uri: string, init: RequestInit) => Response | ObservableInput<Response>;
+/**
+ * Continues to the next registered {@link HttpMiddleware}, or the network call itself,
+ * always resolving to a `Response` regardless of how that next step actually produced it —
+ * a short-circuited `Response`, a `Promise`, or an `Observable`.
+ *
+ * @param uri - The fully resolved URL for the request.
+ * @param init - The prepared `fetch` request options.
+ * @returns A promise of the resulting `Response`.
+ */
+export type HttpMiddlewareContinuation = (uri: string, init: RequestInit) => Promise<Response>;
+/**
+ * Wraps request execution to add cross-cutting behavior — retries, caching, telemetry,
+ * circuit breaking — around the network call itself, rather than transforming the
+ * request or response payload.
+ *
+ * @remarks
+ * Unlike {@link ProcessOperator}, which transforms a value in a linear pipeline, a middleware
+ * controls whether and how many times `next` runs: it can short-circuit by never calling
+ * `next`, retry by calling it more than once, or recover from a rejection it throws.
+ * Registered middleware compose in an "onion" — the first one registered is outermost, so it
+ * sees the request first and the response last.
+ *
+ * @param uri - The fully resolved URL for the request.
+ * @param init - The prepared `fetch` request options.
+ * @param next - Continues to the next registered middleware, or the network call itself.
+ * @returns The resulting `Response`, or an observable input of it.
+ *
+ * @example Retry once on a failed response
+ * ```typescript
+ * const retryOnce: HttpMiddleware = async (uri, init, next) => {
+ *   const response = await next(uri, init);
+ *   return response.ok ? response : next(uri, init);
+ * };
+ * ```
+ */
+export type HttpMiddleware = (uri: string, init: RequestInit, next: HttpMiddlewareContinuation) => Response | ObservableInput<Response>;
+/**
+ * Registers and composes {@link HttpMiddleware} into a single execution pipeline wrapping
+ * the network call.
+ */
+export interface IHttpMiddlewareHandler {
+    /**
+     * Gets the registered middleware, in registration order.
+     */
+    get middleware(): readonly HttpMiddleware[];
+    /**
+     * Registers a middleware, wrapping every middleware registered before it.
+     * @param middleware - The middleware to register.
+     * @returns The updated handler, for chaining.
+     */
+    use(middleware: HttpMiddleware): IHttpMiddlewareHandler;
+    /**
+     * Runs the registered middleware chain around a request, ending with `terminal`.
+     * @param uri - The fully resolved URL for the request.
+     * @param init - The prepared `fetch` request options.
+     * @param terminal - The innermost step the chain wraps, called when every middleware defers to `next`.
+     * @returns An observable of the resulting `Response`.
+     */
+    process(uri: string, init: RequestInit, terminal: HttpMiddlewareNext): Observable<Response>;
+}

package/dist/types/mock/create-open-api-mock-middleware.d.ts

@@ -0,0 +1,28 @@
+import type { HttpMiddleware } from '../lib/operators/types';
+import { type OpenApiMockLike } from './resolve-open-api-mock-response';
+/**
+ * Adapts an `OpenApiMock` into an {@link HttpMiddleware}, so
+ * `configurator.http.addMiddleware(...)` fakes every matching request
+ * straight from an OpenAPI document — no separate mock configurator needed.
+ *
+ * @remarks
+ * A request that matches no operation in the document falls through to
+ * `next`, so this composes with whatever else is registered — including the
+ * real network call, or another middleware further down the chain. Because
+ * `addMiddleware` wraps `_performFetch` rather than replacing it, the exact
+ * same registration also fakes requests through any client this configurator
+ * builds, so app config never has to branch on whether it's under test.
+ *
+ * @param openApiMock - Typically `createOpenApiMock(document)` from `@equinor/fusion-openapi-mock`.
+ * @returns A middleware for {@link IHttpClientConfigurator.addMiddleware}.
+ *
+ * @example Fake every operation in a spec, straight from the document
+ * ```typescript
+ * import { createOpenApiMock } from '@equinor/fusion-openapi-mock';
+ * import openapi from './openapi.json' with { type: 'json' };
+ *
+ * configurator.http.addMiddleware(createOpenApiMockMiddleware(createOpenApiMock(openapi)));
+ * ```
+ */
+export declare function createOpenApiMockMiddleware(openApiMock: OpenApiMockLike): HttpMiddleware;
+export default createOpenApiMockMiddleware;

package/dist/types/mock/create-router-middleware.d.ts

@@ -0,0 +1,73 @@
+import type { HttpMiddleware } from '../lib/operators/types';
+/**
+ * A route match handed to a {@link MockRouteHandler} once its pattern has matched a request.
+ */
+export interface MockRouteMatch {
+    /** Path parameters extracted from named segments in the route pattern, e.g. `:id` -> `params.id`. */
+    params: Record<string, string>;
+    /** The fully resolved request URL, for reading query parameters via `url.searchParams`. */
+    url: URL;
+    /** The request as a Fetch-standard `Request`, for reading headers or a JSON/text body. */
+    request: Request;
+}
+/** Builds the `Response` for one matched route. */
+export type MockRouteHandler = (match: MockRouteMatch) => Response | Promise<Response>;
+/**
+ * Registers route handlers for {@link createRouterMiddleware}, in the style of a minimal
+ * Express-like router — path templates (`:id`) and per-method registration, without pulling
+ * in a real routing library.
+ */
+export interface IMockRouterBuilder {
+    /** Registers `handler` for `GET` requests matching `path`. @see {@link IMockRouterBuilder.on} */
+    get(path: string, handler: MockRouteHandler): IMockRouterBuilder;
+    /** Registers `handler` for `POST` requests matching `path`. @see {@link IMockRouterBuilder.on} */
+    post(path: string, handler: MockRouteHandler): IMockRouterBuilder;
+    /** Registers `handler` for `PUT` requests matching `path`. @see {@link IMockRouterBuilder.on} */
+    put(path: string, handler: MockRouteHandler): IMockRouterBuilder;
+    /** Registers `handler` for `PATCH` requests matching `path`. @see {@link IMockRouterBuilder.on} */
+    patch(path: string, handler: MockRouteHandler): IMockRouterBuilder;
+    /** Registers `handler` for `DELETE` requests matching `path`. @see {@link IMockRouterBuilder.on} */
+    delete(path: string, handler: MockRouteHandler): IMockRouterBuilder;
+    /**
+     * Registers `handler` for a method and path template.
+     * @param method - The HTTP method to match, case-insensitively, or `undefined` to match any method.
+     * @param path - A path template relative to the router's base URI. A segment starting with
+     *   `:` (e.g. `/contexts/:id`) captures that segment into `params`; every other segment must
+     *   match literally. A trailing slash is always optional.
+     * @param handler - Builds the `Response` for a matching request.
+     */
+    on(method: string | undefined, path: string, handler: MockRouteHandler): IMockRouterBuilder;
+}
+/**
+ * Builds an {@link HttpMiddleware} that answers requests to one base URI with hand-registered
+ * route handlers, matched by method and a path template (`:id`-style segments) — a lightweight
+ * router for tests with more than a couple of routes to fake, without hand-rolling `RegExp`
+ * matching against `uri` in every middleware.
+ *
+ * @remarks
+ * A request outside `baseUri`, or matching no registered route, falls through to `next`, so
+ * this composes with other middleware — including the real network call, or another router
+ * for a different base URI — registered around it. Routes are tried in registration order;
+ * the first match wins.
+ *
+ * Deliberately not an MSW-compatible API — this stays inside `addMiddleware`'s own request
+ * pipeline rather than intercepting the network boundary, so it has none of MSW's response
+ * transformers, `onUnhandledRequest` diagnostics, or wildcard patterns.
+ *
+ * @param baseUri - The base URI this router answers for, e.g. `https://api.example.com`.
+ * @param build - Registers routes on the given {@link IMockRouterBuilder}.
+ * @returns A middleware for {@link IHttpClientConfigurator.addMiddleware}.
+ *
+ * @example Fake a handful of routes under one base URI
+ * ```typescript
+ * configurator.http.addMiddleware(
+ *   createRouterMiddleware('https://context.example.com', (router) => {
+ *     router.get('/contexts/:id/relations', () => Response.json([{ id: 'ctx-3' }]));
+ *     router.get('/contexts', () => Response.json([{ id: 'ctx-2' }]));
+ *     router.get('/contexts/:id', ({ params }) => Response.json({ id: params.id }));
+ *   }),
+ * );
+ * ```
+ */
+export declare function createRouterMiddleware(baseUri: string, build: (router: IMockRouterBuilder) => void): HttpMiddleware;
+export default createRouterMiddleware;

package/dist/types/mock/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Testing utilities for the HTTP module.
+ *
+ * @remarks
+ * Imported from `@equinor/fusion-framework-module-http/mock`, so testing
+ * utilities ship and version with the implementation they stand in for.
+ *
+ * There is no separate mock client or configurator here — register a
+ * short-circuiting `HttpMiddleware` through `configurator.http.addMiddleware(...)`
+ * on the real `HttpClientConfigurator` instead, so app config never has to
+ * branch on whether it's under test. See {@link createOpenApiMockMiddleware}
+ * for faking a whole OpenAPI document's operations that way.
+ *
+ * This entry point has no dependency on any test runner.
+ *
+ * @packageDocumentation
+ */
+export { createOpenApiMockMiddleware } from './create-open-api-mock-middleware';
+export type { OpenApiMockLike } from './resolve-open-api-mock-response';
+export { createRouterMiddleware, type MockRouteHandler, type MockRouteMatch, type IMockRouterBuilder, } from './create-router-middleware';

package/dist/types/mock/resolve-open-api-mock-response.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The subset of `OpenApiMock` (from `@equinor/fusion-openapi-mock`'s
+ * `createOpenApiMock`) the adapters in this file need — duck-typed so this
+ * package has no dependency on that one; anything shaped like this works.
+ */
+export interface OpenApiMockLike {
+    resolve(request: {
+        method: string;
+        path: string;
+        query?: Record<string, string>;
+    }): Promise<{
+        status: number;
+        mock: unknown;
+    } | undefined>;
+}
+/**
+ * Resolves a method and URL against an `OpenApiMock`, building a `Response`
+ * from whatever it matches — shared by every adapter targeting a different
+ * middleware shape, so the method/path/query mapping and status/body wiring
+ * lives in one place.
+ *
+ * @param openApiMock - The mock to resolve against.
+ * @param method - The request's HTTP method.
+ * @param url - The request's fully resolved URL.
+ * @returns The faked `Response`, or `undefined` when no operation matches.
+ */
+export declare function resolveOpenApiMockResponse(openApiMock: OpenApiMockLike, method: string, url: URL): Promise<Response | undefined>;

package/dist/types/provider.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from './lib/client';
 import type { HttpClientOptions, HttpClientRequestInitType, IHttpClientConfigurator } from './configurator';
-import type { IHttpRequestHandler } from './lib/operators';
+import type { IHttpMiddlewareHandler, IHttpRequestHandler } from './lib/operators';
 import type { IHttpClient } from './lib/client';
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 /**
@@ -15,6 +15,11 @@ export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient>
      * This handler is responsible for executing HTTP requests using the configured HttpClient.
      */
     readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
+    /**
+     * The default middleware chain used by the HttpClientProvider, wrapping the network call
+     * for every client it creates unless a client overrides it with its own `middlewareHandler`.
+     */
+    readonly defaultHttpMiddlewareHandler: IHttpMiddlewareHandler;
     /**
      * Checks if a client is configured with the given key.
      * @param key - The key of the client to check.
@@ -54,6 +59,11 @@ export declare class HttpClientProvider<TClient extends IHttpClient = IHttpClien
      * @returns The default HTTP request handler.
      */
     get defaultHttpRequestHandler(): IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
+    /**
+     * Gets the default middleware chain for the HTTP client provider.
+     * @returns The default middleware chain.
+     */
+    get defaultHttpMiddlewareHandler(): IHttpMiddlewareHandler;
     /**
      * Creates a new `HttpClientProvider`.
      * @param config - The configurator providing client definitions and defaults.

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "8.0.5";
+export declare const version = "8.1.0-next.0";

package/docs/testing.md

@@ -0,0 +1,78 @@
+# Testing
+
+There is no separate mock client or configurator — register a short-circuiting middleware
+through `configurator.http.addMiddleware(...)` on the real configurator instead. The real
+configurator API — `configureClient`, `baseUri`, `defaultScopes`, `requestHandler`, `onCreate`
+— all still applies; a middleware only wraps the network call itself.
+
+## Quick Start
+
+```typescript
+configurator.configureHttpClient('catalog', { baseUri: 'https://api.example.com' });
+configurator.http.addMiddleware(async (uri, init, next) =>
+  uri === 'https://api.example.com/items' ? Response.json([{ id: 1 }]) : next(uri, init),
+);
+
+const items = await fusion.modules.http.createClient('catalog').json('/items');
+```
+
+## The Middleware Contract
+
+```typescript
+type HttpMiddleware = (
+  uri: string,
+  init: RequestInit,
+  next: (uri: string, init: RequestInit) => Promise<Response>,
+) => Response | Promise<Response> | Observable<Response>;
+```
+
+- **A middleware decides for itself whether to answer or fall through** — return a `Response` to
+  handle the request, or call and return `next(uri, init)` to continue to whichever middleware
+  (or the real network call) is registered next. There is no separate "declined" return value —
+  unlike a router, this is an onion-style chain, so a middleware can also inspect what `next(...)`
+  resolves to and decide based on that (a retry, for example).
+- **Registration order is outermost-first.** The first middleware registered via `addMiddleware`
+  wraps every other one, including the real network call — so it sees the request first and the
+  response last.
+- **A test middleware composes with real app config unchanged** — `addMiddleware` wraps
+  `_performFetch` rather than replacing it, so the exact same client and configuration a real
+  app registers is what a test exercises; only the boundary that would reach the network is
+  short-circuited.
+
+## Faking An Entire OpenAPI Document
+
+`createOpenApiMockMiddleware` (`@equinor/fusion-framework-module-http/mock`) adapts an
+[`@equinor/fusion-openapi-mock`](../../utils/openapi-mock) instance into an `HttpMiddleware`,
+so a real `openapi.json`/`openapi.yaml` fakes every response until a specific operation needs
+overriding:
+
+```typescript
+import { createOpenApiMock } from '@equinor/fusion-openapi-mock';
+import { createOpenApiMockMiddleware } from '@equinor/fusion-framework-module-http/mock';
+
+const openApiMock = createOpenApiMock(openApiDocument, { seed: 42 });
+
+configurator.configureHttpClient('catalog', { baseUri: 'https://api.example.com' });
+configurator.http.addMiddleware(createOpenApiMockMiddleware(openApiMock));
+```
+
+A request that matches no operation in the document falls through to `next`, so this composes
+with other middleware, or the real network call, registered around it.
+
+## Asserting Calls With `vi.fn`
+
+A middleware is a plain function, so a `vi.fn` spy works as one directly:
+
+```typescript
+const middleware = vi.fn(async () => Response.json({ ok: true }));
+configurator.http.addMiddleware(middleware);
+
+await client.json('/items');
+
+expect(middleware).toHaveBeenCalledOnce();
+const [uri, init] = middleware.mock.calls[0];
+expect(init.method ?? 'GET').toBe('GET');
+```
+
+See [`@equinor/fusion-framework/mock`](../../../framework/docs/testing-extending.md) to mock every
+framework boundary at once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-http",
-  "version": "8.0.5",
+  "version": "8.1.0-next.0",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -13,6 +13,10 @@
       "import": "./dist/esm/lib/client/index.js",
       "types": "./dist/types/lib/client/index.d.ts"
     },
+    "./mock": {
+      "import": "./dist/esm/mock/index.js",
+      "types": "./dist/types/mock/index.d.ts"
+    },
     "./operators": {
       "import": "./dist/esm/lib/operators/index.js",
       "types": "./dist/types/lib/operators/index.d.ts"
@@ -34,6 +38,9 @@
       "client": [
         "dist/types/lib/client/index.d.ts"
       ],
+      "mock": [
+        "dist/types/mock/index.d.ts"
+      ],
       "operators": [
         "dist/types/lib/operators/index.d.ts"
       ],
@@ -59,12 +66,12 @@
   "dependencies": {
     "rxjs": "^7.8.1",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "^6.1.1",
-    "@equinor/fusion-framework-module-msal": "^10.0.2"
+    "@equinor/fusion-framework-module": "^6.1.3-next.0",
+    "@equinor/fusion-framework-module-msal": "^11.0.0-next.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsc -b",

package/src/configurator.ts

@@ -1,11 +1,17 @@
 import {
   capitalizeRequestMethodOperator,
   requestValidationOperator,
+  HttpMiddlewareHandler,
   HttpRequestHandler,
 } from './lib/operators';
 
 import type { FetchRequest, IHttpClient } from './lib/client';
-import type { IHttpRequestHandler, IHttpResponseHandler } from './lib/operators';
+import type {
+  HttpMiddleware,
+  IHttpMiddlewareHandler,
+  IHttpRequestHandler,
+  IHttpResponseHandler,
+} from './lib/operators';
 
 /**
  * Represents the options for constructing an `IHttpClient` instance.
@@ -64,6 +70,13 @@ export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
 
   /** The response handler to be used by the `IHttpClient` instance. */
   responseHandler?: IHttpResponseHandler<HttpClientResponseType<TClient>>;
+
+  /**
+   * Middleware wrapping the network call, overriding {@link HttpClientConfigurator.addMiddleware}
+   * for this client only. Rarely needed — most middleware belongs on the configurator so it
+   * applies to every client, and still runs the same way against a mocked client in tests.
+   */
+  middlewareHandler?: IHttpMiddlewareHandler;
 }
 
 /**
@@ -97,6 +110,24 @@ export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClie
   readonly clients: Record<string, HttpClientOptions<TClient>>;
   readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
   readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
+  readonly defaultHttpMiddlewareHandler: IHttpMiddlewareHandler;
+
+  /**
+   * Registers middleware wrapping the network call for every client this configurator builds —
+   * retries, caching, telemetry, circuit breaking. Register it wherever the app configures its
+   * real HTTP clients; because it wraps `_performFetch` rather than replacing it, the same
+   * registration still runs, unaltered, against a mocked client in tests.
+   * @param middleware - The middleware to register.
+   * @returns The configurator so registrations can be chained.
+   * @example
+   * ```ts
+   * configurator.http.addMiddleware(async (uri, init, next) => {
+   *   const response = await next(uri, init);
+   *   return response.ok ? response : next(uri, init);
+   * });
+   * ```
+   */
+  addMiddleware(middleware: HttpMiddleware): IHttpClientConfigurator<TClient>;
 
   /**
    * Registers or updates a named client configuration.
@@ -176,6 +207,9 @@ export class HttpClientConfigurator<TClient extends IHttpClient>
     'request-validation': requestValidationOperator(),
   });
 
+  /** Default middleware chain cloned into each created client instance. */
+  readonly defaultHttpMiddlewareHandler: IHttpMiddlewareHandler = new HttpMiddlewareHandler();
+
   /**
    * Creates a configurator with the default client constructor.
    * @param client - The default client constructor used when `ctor` is not configured per client.
@@ -189,6 +223,12 @@ export class HttpClientConfigurator<TClient extends IHttpClient>
     return Object.keys(this._clients).includes(name);
   }
 
+  /** @inheritdoc */
+  addMiddleware(middleware: HttpMiddleware): HttpClientConfigurator<TClient> {
+    this.defaultHttpMiddlewareHandler.use(middleware);
+    return this;
+  }
+
   /** @inheritdoc */
   configureClient<T extends TClient>(
     name: string,