@equinor/fusion-framework-module-http 8.1.0 → 8.1.1

package/src/mock/create-router-middleware.ts

@@ -1,158 +0,0 @@
-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;
-}
-
-interface RegisteredRoute {
-  method: string | undefined;
-  regexp: RegExp;
-  keys: string[];
-  handler: MockRouteHandler;
-}
-
-/**
- * Compiles a path template into a matching `RegExp` plus the ordered list of named parameters
- * it captures.
- *
- * @param path - A path template such as `/contexts/:id`.
- * @returns The compiled pattern and the parameter names it captures, in segment order.
- */
-function compilePath(path: string): { regexp: RegExp; keys: string[] } {
-  const keys: string[] = [];
-  const pattern = path
-    .split('/')
-    // each segment either captures a path parameter or must match literally
-    .map((segment) => {
-      // only `:name` segments become capture groups; everything else must match literally
-      if (!segment.startsWith(':')) {
-        return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      }
-      keys.push(segment.slice(1));
-      return '([^/]+)';
-    })
-    .join('/');
-  return { regexp: new RegExp(`^${pattern}/?$`), keys };
-}
-
-/**
- * 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 function createRouterMiddleware(
-  baseUri: string,
-  build: (router: IMockRouterBuilder) => void,
-): HttpMiddleware {
-  const routes: RegisteredRoute[] = [];
-  const register = (
-    method: string | undefined,
-    path: string,
-    handler: MockRouteHandler,
-  ): IMockRouterBuilder => {
-    const { regexp, keys } = compilePath(path);
-    routes.push({ method: method?.toUpperCase(), regexp, keys, handler });
-    return router;
-  };
-  const router: IMockRouterBuilder = {
-    get: (path, handler) => register('GET', path, handler),
-    post: (path, handler) => register('POST', path, handler),
-    put: (path, handler) => register('PUT', path, handler),
-    patch: (path, handler) => register('PATCH', path, handler),
-    delete: (path, handler) => register('DELETE', path, handler),
-    on: register,
-  };
-  build(router);
-
-  const base = new URL(baseUri);
-  const basePath = base.pathname.replace(/\/$/, '');
-
-  return async (uri, init, next) => {
-    const url = new URL(uri);
-    // requests to a different origin, or outside this router's base path, are none of its concern
-    if (url.origin !== base.origin || !url.pathname.startsWith(basePath)) return next(uri, init);
-
-    const pathname = url.pathname.slice(basePath.length) || '/';
-    const method = (init.method ?? 'GET').toUpperCase();
-
-    // first registered route whose method and pattern both match wins
-    for (const route of routes) {
-      // a route registered for a specific method never answers a request for another method
-      if (route.method && route.method !== method) continue;
-      const match = route.regexp.exec(pathname);
-      // pattern didn't match this pathname at all — try the next registered route
-      if (!match) continue;
-      // capture groups are positional, in the same order `compilePath` recorded their names
-      const params = Object.fromEntries(route.keys.map((key, i) => [key, match[i + 1]]));
-      return route.handler({ params, url, request: new Request(uri, init) });
-    }
-
-    return next(uri, init);
-  };
-}
-
-export default createRouterMiddleware;

package/src/mock/index.ts

@@ -1,26 +0,0 @@
-/**
- * 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/src/mock/resolve-open-api-mock-response.ts

@@ -1,36 +0,0 @@
-/**
- * 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 async function resolveOpenApiMockResponse(
-  openApiMock: OpenApiMockLike,
-  method: string,
-  url: URL,
-): Promise<Response | undefined> {
-  const result = await openApiMock.resolve({
-    method,
-    path: url.pathname,
-    query: Object.fromEntries(url.searchParams),
-  });
-  return result && Response.json(result.mock, { status: result.status });
-}

package/src/module.ts

@@ -1,149 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { HttpClientMsal } from './lib/client';
-import {
-  type IHttpClientConfigurator,
-  HttpClientConfigurator,
-  type HttpClientOptions,
-} from './configurator';
-import { type IHttpClientProvider, HttpClientProvider } from './provider';
-
-import type {
-  Module,
-  ModuleConfigType,
-  IModuleConfigurator,
-} from '@equinor/fusion-framework-module';
-
-import type { MsalModule } from '@equinor/fusion-framework-module-msal';
-
-/**
- * Defines the type for the HTTP module, which includes:
- * - The module name: 'http'
- * - The type of the HTTP client provider, which is `IHttpClientProvider`
- * - The type of the HTTP client configurator, which is `IHttpClientConfigurator`
- */
-export type HttpModule = Module<'http', IHttpClientProvider, IHttpClientConfigurator>;
-
-/**
- * Defines the type for the HTTP module with MSAL authentication.
- *
- * This type represents the module configuration for the HTTP module, which includes:
- * - The module name: 'http'
- * - The type of the HTTP client provider, which is `IHttpClientProvider<HttpClientMsal>`
- * - The type of the HTTP client configurator, which is `IHttpClientConfigurator<HttpClientMsal>`
- * - The list of required modules, which includes the `MsalModule`
- */
-export type HttpMsalModule = Module<
-  'http',
-  IHttpClientProvider<HttpClientMsal>,
-  IHttpClientConfigurator<HttpClientMsal>,
-  [MsalModule]
->;
-
-/**
- * Default HTTP module definition for Fusion Framework applications.
- *
- * The module uses `HttpClientMsal` as the default client implementation and,
- * when the auth module is available, installs a request handler that can acquire
- * bearer tokens for scoped requests.
- */
-export const module: HttpMsalModule = {
-  name: 'http',
-  /**
-   * Configures the HTTP module with MSAL authentication.
-   *
-   * This function creates a new `HttpClientConfigurator` instance using the `HttpClientMsal` class.
-   * The `HttpClientConfigurator` is responsible for configuring the HTTP client with the necessary options,
-   * such as the base URL, request headers, and other settings.
-   *
-   * @returns A new `HttpClientConfigurator` instance configured for MSAL authentication.
-   */
-  configure: () => new HttpClientConfigurator(HttpClientMsal),
-
-  /**
-   * Initializes the HTTP client provider with MSAL authentication.
-   *
-   * This function is responsible for setting up the default HTTP request handler
-   * to acquire an access token from MSAL and attach it to the request headers
-   * when the request includes scopes.
-   *
-   * @param config - The module configuration.
-   * @param hasModule - A function to check if a module is available.
-   * @param requireInstance - A function to get an instance of a module.
-   * @returns A promise that resolves to the HTTP client provider.
-   */
-  initialize: async ({
-    config,
-    hasModule,
-    requireInstance,
-  }): Promise<HttpClientProvider<HttpClientMsal>> => {
-    const httpProvider = new HttpClientProvider(config);
-    // wire up an MSAL bearer-token handler only when the auth module is registered
-    if (hasModule('auth')) {
-      const authProvider = await requireInstance('auth');
-      httpProvider.defaultHttpRequestHandler.set('MSAL', async (request) => {
-        const { scopes = [] } = request;
-        // only attempt to acquire a token when the request actually declares scopes
-        if (scopes.length) {
-          /** TODO(#5143): should be try catch, check caller for handling */
-          const accessToken = await authProvider.acquireAccessToken({
-            request: { scopes },
-          });
-          // without a token there's nothing to attach, fall through to the default request
-          if (accessToken) {
-            const headers = new Headers(request.headers);
-            headers.set('Authorization', `Bearer ${accessToken}`);
-            return { ...request, headers };
-          }
-        }
-      });
-    }
-    return httpProvider;
-  },
-};
-
-/**
- * Creates a module configurator for the HTTP module.
- *
- * Use this when you need lower-level access to the module configuration callback,
- * for example when registering several named clients in one setup step.
- *
- * @param configure - The callback that receives the HTTP module configuration.
- * @returns A module configurator for the HTTP module.
- */
-export const configureHttp = <TRef = unknown>(
-  configure: (config: ModuleConfigType<HttpMsalModule>, ref?: TRef) => void,
-): IModuleConfigurator<HttpMsalModule, TRef> => ({
-  module,
-  configure,
-});
-
-/**
- * Creates a module configurator that registers one named HTTP client.
- *
- * This is the convenience API for the common case where a setup step only needs to
- * register one client with `baseUri`, `defaultScopes`, handlers, or a custom constructor.
- *
- * @param name - The client key used later with `createClient(name)`.
- * @param args - The named client configuration.
- * @returns A module configurator that registers the named client.
- */
-export const configureHttpClient = <TRef = unknown>(
-  name: string,
-  args: HttpClientOptions<HttpClientMsal>,
-): IModuleConfigurator<HttpMsalModule, TRef> => ({
-  module,
-  configure: (config: ModuleConfigType<HttpMsalModule>) => {
-    config.configureClient(name, args);
-  },
-});
-
-/**
- * Declares a module named '@equinor/fusion-framework-module' that contains an interface named 'Modules' with a property 'http' of type 'HttpMsalModule'.
- */
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    http: HttpMsalModule;
-  }
-}
-
-export default module;

package/src/provider.ts

@@ -1,225 +0,0 @@
-import type { HttpClient } from './lib/client';
-import type {
-  HttpClientOptions,
-  HttpClientRequestInitType,
-  IHttpClientConfigurator,
-} from './configurator';
-
-import type { IHttpMiddlewareHandler, IHttpRequestHandler } from './lib/operators';
-import type { IHttpClient } from './lib/client';
-import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
-import { version } from './version';
-import { ClientNotFoundException } from './errors/index.js';
-
-/**
- * Creates fresh HTTP client instances from named or ad-hoc configuration.
- *
- * A provider can create clients from registered names, inline `HttpClientOptions`,
- * or absolute URLs treated as ad-hoc `baseUri` values.
- */
-export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient> {
-  /**
-   * The default HTTP request handler used by the HttpClientProvider.
-   * 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.
-   * @returns `true` if a client is configured with the given key, `false` otherwise.
-   */
-  hasClient(key: string): boolean;
-
-  /**
-   * Creates a new HTTP client instance with the specified key.
-   * @param key - The key of the HTTP client to create.
-   * @returns The created HTTP client instance.
-   */
-  createClient(key: string): TClient;
-  createClient(key: HttpClientOptions<TClient>): TClient;
-
-  /**
-   * Creates a client instance and casts it to a custom HTTP client type.
-   *
-   * This is most useful when the named client configuration uses a custom `ctor`
-   * that extends `HttpClient` with domain-specific methods.
-   * @example
-   * ```ts
-   * config.http.configureClient('foobar', {
-   *   ctor: MyClient,
-   *   baseUri: 'https://foobar.com',
-   * });
-   * ```
-   */
-  createCustomClient<T extends HttpClient>(key: string): T;
-}
-
-/** URL protocols accepted as valid ad-hoc base URIs. */
-const SUPPORTED_PROTOCOLS = ['http:', 'https:', 'ws:', 'wss:'] as const;
-
-/**
- * Checks if a given string is a valid absolute URL with a supported protocol.
- * @param url - The string to check.
- * @returns `true` when the string uses one of {@link SUPPORTED_PROTOCOLS}.
- */
-const isURL = (url: string): boolean => {
-  try {
-    const parsed = new URL(url);
-    return (SUPPORTED_PROTOCOLS as readonly string[]).includes(parsed.protocol);
-  } catch {
-    return false;
-  }
-};
-
-/**
- * Heuristic check for strings that look like a bare hostname or URL without a
- * protocol prefix (e.g. `api.example.com` or `api.example.com/v1`).
- *
- * Used to emit a deprecation warning when callers rely on the old (pre-patch)
- * behaviour that accepted protocol-less URLs.
- */
-const looksLikeURL = (value: string): boolean =>
-  !value.includes(' ') && /^[a-z\d]([a-z\d-]*\.)+[a-z]{2,}/i.test(value);
-
-/**
- * The `HttpClientProvider` class is responsible for managing HTTP client instances and their configuration.
- * It provides methods to check if a client is configured, create new client instances, and create custom client instances.
- */
-export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
-  extends BaseModuleProvider<IHttpClientConfigurator<TClient>>
-  implements IHttpClientProvider<TClient>
-{
-  /**
-   * Gets the default HTTP request handler for the HTTP client provider.
-   * @returns The default HTTP request handler.
-   */
-  get defaultHttpRequestHandler(): IHttpRequestHandler<HttpClientRequestInitType<TClient>> {
-    return this.config.defaultHttpRequestHandler;
-  }
-
-  /**
-   * Gets the default middleware chain for the HTTP client provider.
-   * @returns The default middleware chain.
-   */
-  get defaultHttpMiddlewareHandler(): IHttpMiddlewareHandler {
-    return this.config.defaultHttpMiddlewareHandler;
-  }
-
-  /**
-   * Creates a new `HttpClientProvider`.
-   * @param config - The configurator providing client definitions and defaults.
-   */
-  constructor(protected config: IHttpClientConfigurator<TClient>) {
-    super({
-      version,
-      config,
-    });
-  }
-
-  /**
-   * Checks if a client with the given key is configured in the `HttpClientProvider`.
-   * @param key - The key of the HTTP client to check.
-   * @returns `true` if a client with the given key is configured, `false` otherwise.
-   */
-  public hasClient(key: string): boolean {
-    return Object.keys(this.config.clients).includes(key);
-  }
-
-  /**
-   * Creates a fresh HTTP client instance from a named or ad-hoc configuration.
-   *
-   * @param keyOrConfig - The key or configuration object for the HTTP client.
-   * @returns The created HTTP client instance.
-   *
-   * @remarks
-   * This method resolves the configuration for the HTTP client based on the provided `keyOrConfig` parameter.
-   * If a string is provided, it is treated as the key for a pre-configured client in the `HttpClientProvider`.
-   * If an `HttpClientOptions` object is provided, it is used as the configuration for the new client instance.
-   *
-   * The method applies `baseUri`, `defaultScopes`, `requestHandler`, `responseHandler`,
-   * a custom `ctor` when configured, and finally runs `onCreate` for the newly created instance.
-   *
-   * The created HTTP client instance is returned.
-   */
-  public createClient(keyOrConfig: string | HttpClientOptions<TClient>): TClient {
-    const config = this._resolveConfig(keyOrConfig);
-    const {
-      baseUri,
-      defaultScopes = [],
-      onCreate,
-      ctor = this.config.defaultHttpClientCtor,
-      requestHandler = this.defaultHttpRequestHandler,
-      responseHandler,
-      middlewareHandler = this.defaultHttpMiddlewareHandler,
-    } = config as HttpClientOptions<TClient>;
-    const options = { requestHandler, responseHandler, middlewareHandler };
-    const instance = new ctor(baseUri || '', options) as TClient;
-    // attach the resolved default scopes onto the instance without overwriting other own properties
-    Object.assign(instance, { defaultScopes });
-    onCreate?.(instance as TClient);
-    return instance as TClient;
-  }
-
-  /**
-   * Creates a client instance and returns it as the requested custom client type.
-   *
-   * @template T - The custom `HttpClient` implementation type to cast the created instance to.
-   * @param key - The key of the pre-configured HTTP client to create.
-   * @returns The created HTTP client instance, cast to the specified type `T`.
-   *
-   * @remarks
-   * This method delegates to the `createClient` method, but casts the returned
-   * instance to the specified type `T`. This can be useful when you need to
-   * work with a specific HTTP client implementation, but the `HttpClientProvider`
-   * is configured to use a different implementation.
-   */
-  public createCustomClient<T extends HttpClient>(key: string): T {
-    // `createClient` always returns the provider's configured `HttpClient` implementation —
-    // cast through `unknown` to hand back the caller-requested implementation type `T`.
-    return this.createClient(key) as unknown as T;
-  }
-
-  /**
-   * Resolves the configuration for an HTTP client based on the provided `keyOrConfig` parameter.
-   *
-   * If a string is provided, it is treated as either a pre-configured client key or,
-   * when it is an absolute `http:` or `https:` URL, as an ad-hoc `baseUri`.
-   * If an `HttpClientOptions` object is provided, it is used directly as the configuration for the new client instance.
-   *
-   * @param keyOrConfig - The key or configuration object for the HTTP client.
-   * @returns The resolved HTTP client configuration.
-   * @throws {ClientNotFoundException} When `keyOrConfig` is a string that is neither a registered
-   * client key nor a URL-like value.
-   */
-  protected _resolveConfig(
-    keyOrConfig: string | HttpClientOptions<TClient>,
-  ): HttpClientOptions<TClient> {
-    // a string may reference a registered client key or an ad-hoc URL; anything else is used as-is
-    if (typeof keyOrConfig === 'string') {
-      const config = this.config.clients[keyOrConfig];
-      // an absolute http(s) URL can be used directly as an ad-hoc baseUri
-      if (!config && isURL(keyOrConfig)) {
-        return { baseUri: keyOrConfig };
-      } else if (!config && looksLikeURL(keyOrConfig)) {
-        // recover from a missing protocol instead of failing outright, but warn so it can be fixed
-        console.warn(
-          `[HttpClientProvider] "${keyOrConfig}" looks like a URL but is missing the http:// or https:// protocol. ` +
-            `Treating it as "https://${keyOrConfig}". ` +
-            `Pass a fully-qualified URL to silence this warning.`,
-        );
-        return { baseUri: `https://${keyOrConfig}` };
-      } else if (!config) {
-        throw new ClientNotFoundException(`No registered http client for key [${keyOrConfig}]`);
-      }
-      return config;
-    }
-    return keyOrConfig as HttpClientOptions<TClient>;
-  }
-}

package/src/version.ts

@@ -1,2 +0,0 @@
-// Generated by genversion.
-export const version = '8.1.0';