@dunx/http 3.0.5 → 3.1.0

package/dist/client/module.d.ts

@@ -1,4 +1,4 @@
-import { type Deps, type DynamicModule, type AsyncModuleConfig, type Token } from '@dunx/core';
+import { type Deps, type DynamicModule, type AsyncModuleConfig, type Ctor, type Token } from '@dunx/core';
 import { type HttpClientOptionsInit } from './options.js';
 import { HttpService } from './service.js';
 /**
@@ -8,16 +8,28 @@ import { HttpService } from './service.js';
  * module and the consumer would hold different tokens for `'stripe'` and the lookup
  * would miss. Same name in, same token out.
  *
- * A `Token` is not a constructor type, so a named client cannot be a constructor
- * parameter. Reach it with `inject()` in a field initialiser:
+ * A `Token` is not a constructor type, so a client registered under one cannot be a
+ * constructor parameter. Reach it with `inject()` in a field initialiser:
  *
  * ```ts
  * class Payments {
  *   readonly stripe = inject(httpClient('stripe'));
  * }
  * ```
+ *
+ * Passing `as` a subclass instead gives an ordinary constructor parameter, and is
+ * the shape to prefer for new code.
  */
 export declare const httpClient: (name: string) => Token<HttpService>;
+/**
+ * How a client is addressed: a name, which binds a `Token`, or a subclass of
+ * `HttpService`, which binds the class itself.
+ *
+ * A subclass is both a token and a parameter type, so `constructor(private readonly
+ * email: EmailClient)` resolves - which a `Token` can never do. `as` is the spelling
+ * `ConfigModule.forRoot({ validate, as })` already established.
+ */
+export type ClientTarget = string | Ctor<HttpService>;
 /**
  * The outbound half of `@dunx/http`.
  *
@@ -35,11 +47,22 @@ export declare const httpClient: (name: string) => Token<HttpService>;
  */
 export declare class HttpModule {
     /**
-     * Binds `HttpService` and `HttpClientOptions`, or `httpClient(init.name)` alone
-     * when `name` is set - a named registration deliberately does not also claim
-     * `HttpService`, so several upstreams can coexist alongside one default.
+     * Binds `HttpService` and `HttpClientOptions`.
+     *
+     * Pass `as` a subclass, or set `init.name`, to register an additional client
+     * instead. Either way it does not also claim `HttpService`, so several upstreams
+     * coexist alongside one default.
+     *
+     * ```ts
+     * export class EmailClient extends HttpService {}
+     * HttpModule.forRoot({ baseUrl: 'https://email.internal' }, EmailClient);
+     *
+     * class Notifier {
+     *   constructor(private readonly email: EmailClient) {}
+     * }
+     * ```
      */
-    static forRoot(init?: HttpClientOptionsInit): DynamicModule;
+    static forRoot(init?: HttpClientOptionsInit, as?: Ctor<HttpService>): DynamicModule;
     /**
      * `forRoot` with the options behind a factory, so the base url or the timeout
      * can come off `ConfigService`.
@@ -53,9 +76,10 @@ export declare class HttpModule {
      * });
      * ```
      *
-     * `name` is a parameter rather than a field of the awaited init, because the
-     * token has to exist before the factory runs.
+     * The second parameter is positional rather than a field of the awaited init,
+     * because the token has to exist before the factory runs. A subclass there gives
+     * a constructor parameter; a string gives an `httpClient(name)` token.
      */
-    static forRootAsync(load: () => HttpClientOptionsInit | Promise<HttpClientOptionsInit>, name?: string): DynamicModule;
-    static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<HttpClientOptionsInit, D>, name?: string): DynamicModule;
+    static forRootAsync(load: () => HttpClientOptionsInit | Promise<HttpClientOptionsInit>, as?: ClientTarget): DynamicModule;
+    static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<HttpClientOptionsInit, D>, as?: ClientTarget): DynamicModule;
 }

package/dist/client/options.d.ts

@@ -43,13 +43,29 @@ export interface HttpClientOptionsInit {
      * ported one cannot: talk through a proxy, pin a certificate, or reach a unix
      * socket, with no dependency.
      */
-    readonly proxy?: string;
+    /**
+     * The object form carries `Proxy-Authorization` to the proxy rather than to the
+     * target, which the string form cannot express.
+     */
+    readonly proxy?: BunFetchRequestInit['proxy'];
     readonly tls?: Bun.TLSOptions;
     readonly unix?: string;
     /** @default true - Bun decompresses by default. */
     readonly decompress?: boolean;
     /** Bun's own request/response tracing on stderr. Never on in production. */
     readonly verbose?: boolean;
+    /**
+     * Compress the request body. A string names the encoding; the object form sets
+     * the level too.
+     */
+    readonly compress?: BunFetchRequestInit['compress'];
+    /**
+     * `'http2'` lets concurrent requests to one origin share a connection, which is
+     * what a service calling a single upstream in a loop wants.
+     */
+    readonly protocol?: BunFetchRequestInit['protocol'];
+    /** How many redirects to follow before rejecting. */
+    readonly maxRedirects?: number;
 }
 export declare const DEFAULT_REQUEST_ID_HEADER = "x-request-id";
 /**

package/dist/client.d.ts

@@ -8,5 +8,5 @@
 export { FetchError, FetchTransportError } from './client/errors.js';
 export { DEFAULT_REQUEST_ID_HEADER, HttpClientOptions, type HttpClientOptionsInit, } from './client/options.js';
 export type { BackoffOptions, RetryOptions } from './client/retry.js';
-export { httpClient, HttpModule } from './client/module.js';
+export { httpClient, HttpModule, type ClientTarget } from './client/module.js';
 export { HttpService, type HeaderFactory, type RequestConfig, type RequestMethod, } from './client/service.js';

package/dist/client.js

@@ -37,7 +37,10 @@ class HttpClientOptions {
       ["tls", init.tls],
       ["unix", init.unix],
       ["decompress", init.decompress],
-      ["verbose", init.verbose]
+      ["verbose", init.verbose],
+      ["compress", init.compress],
+      ["protocol", init.protocol],
+      ["maxRedirects", init.maxRedirects]
     ].filter(([, value]) => value !== undefined));
   }
 }
@@ -288,26 +291,30 @@ var httpClient = (name) => {
   tokens.set(name, created);
   return created;
 };
-var serviceFrom = (target, optionsToken) => provide(target, {
-  useFactory: (options, logger, context) => new HttpService(options, logger, context),
+var serviceFrom = (target, optionsToken, ctor = HttpService) => provide(target, {
+  useFactory: (options, logger, context) => new ctor(options, logger, context),
   inject: [optionsToken, Logger2, RequestContext2]
 });
-var namedModule = (name, options, imports = []) => {
-  const optionsToken = token(`HttpClientOptions(${name})`);
+var namedModule = (target, options, imports = []) => {
+  const label = typeof target === "string" ? target : target.name;
+  const service = typeof target === "string" ? httpClient(target) : target;
+  const ctor = typeof target === "string" ? HttpService : target;
+  const optionsToken = token(`HttpClientOptions(${label})`);
   const optionsProvider = options instanceof HttpClientOptions ? provide(optionsToken, { useValue: options }) : provide(optionsToken, options);
   return {
     module: HttpModule,
     imports,
-    exports: [optionsToken, httpClient(name)],
-    providers: [optionsProvider, serviceFrom(httpClient(name), optionsToken)]
+    exports: [optionsToken, service],
+    providers: [optionsProvider, serviceFrom(service, optionsToken, ctor)]
   };
 };
 
 class HttpModule {
-  static forRoot(init = {}) {
+  static forRoot(init = {}, as) {
     const options = new HttpClientOptions(init);
-    if (options.name !== undefined)
-      return namedModule(options.name, options);
+    const target = as ?? options.name;
+    if (target !== undefined)
+      return namedModule(target, options);
     return {
       module: HttpModule,
       exports: [HttpClientOptions, HttpService],
@@ -317,13 +324,13 @@ class HttpModule {
       ]
     };
   }
-  static forRootAsync(source, name) {
+  static forRootAsync(source, as) {
     const load = typeof source === "function" ? source : source.useFactory;
     const inject = typeof source === "function" ? [] : source.inject ?? [];
     const imports = typeof source === "function" ? [] : source.imports ?? [];
     const useFactory = async (...deps) => new HttpClientOptions(await load(...deps));
-    if (name !== undefined) {
-      return namedModule(name, { useFactory, inject }, imports);
+    if (as !== undefined) {
+      return namedModule(as, { useFactory, inject }, imports);
     }
     return {
       module: HttpModule,

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { RouteContext } from './server/context.js';
 export type { CorsOptions, CorsOrigin } from './server/cors.js';
 export { defaultErrorMapper, ErrorFilter, errorMapper, HttpError, ValidationError, type ErrorHandler, type ErrorMapper, type HttpErrorOptions, type InputSource, type ValidationIssue, } from './server/errors.js';
 export { HttpFactory, type HttpApp, type HttpOptions, } from './server/factory.js';
+export { DefaultHttpOptions, HttpOptionsProvider, } from './server/options-provider.js';
 export { REQUEST_ID_HEADER } from './server/request-id.js';
 export { TRACEPARENT_HEADER, TRACESTATE_HEADER, TraceContext, type Trace, } from './server/trace-context.js';
 export { RequestLoggingMiddleware, type RequestLoggingOptions, } from './server/request-logging.js';
@@ -30,6 +31,7 @@ export type { SocketContext, SocketDispatch, SocketFrame, SocketMiddleware, Sock
 export { SocketLoggingMiddleware, type SocketLoggingOptions, } from './ws/logging.js';
 export { PubSub } from './ws/pubsub.js';
 export { RedisRelay, type RedisRelayOptions } from './ws/redis-relay.js';
+export { RelayConnectionOptions, WsRelayModule } from './ws/relay-module.js';
 export { DEFAULT_RELAY_CHANNEL, type PubSubRelay, type RelayOptions, } from './ws/relay.js';
 export type { Socket, SocketData, SocketErrorHandler, SocketOptions, } from './ws/socket.js';
 export { HealthIndicator, PingProbe, QueryProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';

package/dist/index.js

@@ -591,12 +591,29 @@ class HttpApplication {
     this.#relay = options.relay;
     this.#relayChannel = options.relayChannel;
     this.#relayResubscribe = options.relayResubscribe;
-    this.#notFound = options.notFound ?? "guarded";
+    this.#notFound = options.notFound ?? "public";
     this.#bootLogging = options.bootLogging ?? true;
     this.gatewayPaths = websocket?.paths ?? [];
     this.closed = new Promise((resolve) => {
       this.#resolveClosed = resolve;
     });
+    if (options.prefix !== undefined && options.prefix !== "") {
+      this.setGlobalPrefix(options.prefix);
+    }
+    if (options.cors !== undefined) {
+      this.enableCors(options.cors);
+    }
+    if (options.trustProxy !== undefined) {
+      this.set("trust proxy", options.trustProxy);
+    }
+    const hooks = options.shutdownHooks;
+    if (hooks !== undefined && hooks !== false) {
+      if (hooks === true) {
+        this.enableShutdownHooks();
+      } else {
+        this.enableShutdownHooks(hooks.signals, hooks.options);
+      }
+    }
   }
   get(token) {
     return this.#app.get(token);
@@ -734,26 +751,91 @@ class HttpApplication {
 }
 Object.defineProperty(HttpApplication, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "app: App", typeOnly: "App" }, { unresolved: "discovered: readonly DiscoveredRoute[]" }, { unresolved: "options: HttpOptions" }, { unresolved: "root: ModuleRef", typeOnly: "ModuleRef" }, { unresolved: "websocket?: WebSocketRuntime", typeOnly: "WebSocketRuntime" }] });
 
+// src/server/options-provider.ts
+class HttpOptionsProvider {
+  middleware = [];
+  socketMiddleware = [];
+  notFound = "public";
+  bootLogging = true;
+  trustProxy = false;
+  shutdownHooks = false;
+  relayChannel = "dunx:ws";
+  get prefix() {
+    return "";
+  }
+  get port() {
+    return;
+  }
+  get cors() {
+    return;
+  }
+  get requestLogging() {
+    return true;
+  }
+  get socketLogging() {
+    return true;
+  }
+  get onError() {
+    return;
+  }
+  get websocket() {
+    return;
+  }
+  get relay() {
+    return;
+  }
+  get relayResubscribe() {
+    return;
+  }
+}
+
+class DefaultHttpOptions extends HttpOptionsProvider {
+}
+function resolveHttpOptions(settings, given) {
+  const merged = {
+    middleware: settings.middleware,
+    socketMiddleware: settings.socketMiddleware,
+    notFound: settings.notFound,
+    bootLogging: settings.bootLogging,
+    trustProxy: settings.trustProxy,
+    shutdownHooks: settings.shutdownHooks,
+    relayChannel: settings.relayChannel,
+    prefix: settings.prefix,
+    port: settings.port,
+    cors: settings.cors,
+    requestLogging: settings.requestLogging,
+    socketLogging: settings.socketLogging,
+    onError: settings.onError,
+    websocket: settings.websocket,
+    relay: settings.relay,
+    relayResubscribe: settings.relayResubscribe
+  };
+  for (const key of Object.keys(given)) {
+    merged[key] = given[key];
+  }
+  return merged;
+}
+
 // src/server/factory.ts
 class HttpModule {
 }
+var pick = (given, fallback) => {
+  const chosen = given ?? fallback;
+  return typeof chosen === "object" ? chosen : {};
+};
 
 class HttpFactory {
   static async create(root, options = {}) {
     const logging = provide(RequestLoggingMiddleware, {
-      useFactory: (logger, context) => new RequestLoggingMiddleware(logger, context, typeof options.requestLogging === "object" ? options.requestLogging : {}),
-      inject: [Logger4, RequestContext3]
+      useFactory: (logger, context, settings) => new RequestLoggingMiddleware(logger, context, pick(options.requestLogging, settings.requestLogging)),
+      inject: [Logger4, RequestContext3, HttpOptionsProvider]
     });
     const socketLogging = provide(SocketLoggingMiddleware, {
-      useFactory: (logger, context) => new SocketLoggingMiddleware(logger, context, typeof options.socketLogging === "object" ? options.socketLogging : {}),
-      inject: [Logger4, RequestContext3]
+      useFactory: (logger, context, settings) => new SocketLoggingMiddleware(logger, context, pick(options.socketLogging, settings.socketLogging)),
+      inject: [Logger4, RequestContext3, HttpOptionsProvider]
     });
     const services = [PubSub, ClientAddress];
-    const providers = [
-      ...services,
-      ...options.requestLogging === false ? [] : [logging],
-      ...options.socketLogging === false ? [] : [socketLogging]
-    ];
+    const providers = [...services, logging, socketLogging];
     const scope = {
       module: HttpModule,
       global: true,
@@ -761,7 +843,11 @@ class HttpFactory {
       providers,
       exports: providers.map((entry) => typeof entry === "function" ? entry : entry.token)
     };
-    const app = await AppFactory.create(scope, options.overrides ? { overrides: options.overrides } : {});
+    const app = await AppFactory.create(scope, {
+      ...options.overrides ? { overrides: options.overrides } : {},
+      promote: [provide(HttpOptionsProvider, { useClass: DefaultHttpOptions })]
+    });
+    const resolved = resolveHttpOptions(app.get(HttpOptionsProvider, root), options);
     const modules = collectModules(scope);
     const discovered = [];
     for (const module of modules) {
@@ -782,11 +868,11 @@ class HttpFactory {
     }
     assertNoCollisions(discovered);
     const gateways = discoverGateways(modules, (token) => app.get(token));
-    const websocket = gateways.length > 0 ? buildWebSocket(gateways, options.websocket, HttpFactory.#socketMiddleware(app, root, options)) : undefined;
+    const websocket = gateways.length > 0 ? buildWebSocket(gateways, resolved.websocket, HttpFactory.#socketMiddleware(app, root, resolved)) : undefined;
     for (const warning of websocket?.warnings ?? []) {
       app.get(Logger4).warn(warning);
     }
-    return new HttpApplication(app, discovered, options, root, websocket);
+    return new HttpApplication(app, discovered, resolved, root, websocket);
   }
   static #socketMiddleware(app, root, options) {
     const declared = options.socketMiddleware ?? [];
@@ -1310,6 +1396,80 @@ var OnMessage = (event) => (value) => {
   markHandler(value, { kind: HandlerKind.MESSAGE, event });
   return value;
 };
+// src/ws/relay-module.ts
+import {
+  provide as provide5
+} from "@dunx/core";
+class RelayConnectionOptions {
+  url;
+  maxRetries;
+  connectionTimeout;
+  tls;
+  constructor(init = {}) {
+    this.url = init.url;
+    this.maxRetries = init.maxRetries;
+    this.connectionTimeout = init.connectionTimeout;
+    this.tls = init.tls;
+  }
+  toInit() {
+    return {
+      ...this.url !== undefined && { url: this.url },
+      ...this.maxRetries !== undefined && { maxRetries: this.maxRetries },
+      ...this.connectionTimeout !== undefined && {
+        connectionTimeout: this.connectionTimeout
+      },
+      ...this.tls !== undefined && { tls: this.tls }
+    };
+  }
+}
+Object.defineProperty(RelayConnectionOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: RedisRelayOptions = {}", optional: true, typeOnly: "RedisRelayOptions" }] });
+
+class RelayLifecycle {
+  relay;
+  constructor(relay) {
+    this.relay = relay;
+  }
+  async onShutdown() {
+    await this.relay.close();
+  }
+}
+Object.defineProperty(RelayLifecycle, Symbol.for("dunx.deps"), { value: () => [RedisRelay] });
+var bindings = (options) => [
+  provide5(RelayConnectionOptions, options),
+  provide5(RedisRelay, {
+    useFactory: (settings) => new RedisRelay(settings.toInit()),
+    inject: [RelayConnectionOptions]
+  }),
+  provide5(RelayLifecycle, {
+    useFactory: (relay) => new RelayLifecycle(relay),
+    inject: [RedisRelay]
+  })
+];
+
+class WsRelayModule {
+  static forRoot(init = {}) {
+    return {
+      module: WsRelayModule,
+      exports: [RedisRelay, RelayConnectionOptions],
+      providers: bindings({
+        useFactory: () => new RelayConnectionOptions(init),
+        inject: []
+      })
+    };
+  }
+  static forRootAsync(config) {
+    const useFactory = async (...deps) => new RelayConnectionOptions(await config.useFactory(...deps));
+    return {
+      module: WsRelayModule,
+      ...config.imports === undefined ? {} : { imports: config.imports },
+      exports: [RedisRelay, RelayConnectionOptions],
+      providers: bindings({
+        useFactory,
+        inject: config.inject ?? []
+      })
+    };
+  }
+}
 // src/health/contracts.ts
 class HealthIndicator {
   critical = true;
@@ -1413,7 +1573,7 @@ Object.defineProperty(DiskIndicator, Symbol.for("dunx.deps"), { value: () => [Di
 // src/health/module.ts
 import {
   Module as Module4,
-  provide as provide5
+  provide as provide6
 } from "@dunx/core";
 
 // src/health/readiness.ts
@@ -1456,15 +1616,15 @@ Object.defineProperty(Readiness, Symbol.for("dunx.deps"), { value: () => [Readin
 // src/health/module.ts
 var wiring = (options) => [
   ...options,
-  provide5(ReadinessOptions, {
+  provide6(ReadinessOptions, {
     useFactory: (opts) => new ReadinessOptions({ drainDelayMs: opts.drainDelayMs }),
     inject: [HealthOptions]
   }),
-  provide5(Readiness, {
+  provide6(Readiness, {
     useFactory: (opts) => new Readiness(opts),
     inject: [ReadinessOptions]
   }),
-  provide5(HealthRegistry, {
+  provide6(HealthRegistry, {
     useFactory: (opts, readiness) => new HealthRegistry(opts, readiness),
     inject: [HealthOptions, Readiness]
   })
@@ -1483,7 +1643,7 @@ class HealthModule {
       module: HealthModule,
       ...options.routes ? { controllers: [controllerFor(options.documented)] } : {},
       exports: surface,
-      providers: wiring([provide5(HealthOptions, { useValue: options })])
+      providers: wiring([provide6(HealthOptions, { useValue: options })])
     };
   }
   static forRootAsync(config) {
@@ -1493,7 +1653,7 @@ class HealthModule {
       ...config.routes ?? true ? { controllers: [controllerFor(config.documented ?? true)] } : {},
       exports: surface,
       providers: wiring([
-        provide5(HealthOptions, {
+        provide6(HealthOptions, {
           useFactory: async (...deps) => new HealthOptions(await config.useFactory(...deps)),
           inject: config.inject ?? []
         })
@@ -1515,6 +1675,7 @@ export {
   Controller,
   DEFAULT_RELAY_CHANNEL,
   DatabaseIndicator,
+  DefaultHttpOptions,
   Delete,
   DiskIndicator,
   DiskOptions,
@@ -1530,6 +1691,7 @@ export {
   HealthRegistry,
   HttpError,
   HttpFactory,
+  HttpOptionsProvider,
   HttpStatusCode,
   MemoryIndicator,
   MemoryOptions,
@@ -1556,6 +1718,7 @@ export {
   RedisIndicator,
   RedisRelay,
   RedisThrottleStore,
+  RelayConnectionOptions,
   RequestLoggingMiddleware,
   Roles,
   SKIP_THROTTLE,
@@ -1576,6 +1739,7 @@ export {
   UNMATCHED,
   UseGuards,
   ValidationError,
+  WsRelayModule,
   defaultErrorMapper,
   errorMapper,
   mergeMeta,

package/dist/server/application.d.ts

@@ -13,6 +13,30 @@ import { type RequestLoggingOptions } from './request-logging.js';
 import { type AppSettings } from './settings.js';
 export interface HttpOptions extends AppOptions {
     readonly port?: number;
+    /**
+     * Prefixes every discovered route, the same thing {@link HttpApp.setGlobalPrefix}
+     * does. Both exist: the method is what NestJS offers and what a script reaches
+     * for, the field is what an `HttpOptionsProvider` can answer from validated
+     * config. A later `setGlobalPrefix` call still wins, because it happens after.
+     *
+     * Explicitly `| undefined`, unlike the rest: a suite running one fixture both
+     * prefixed and unprefixed passes a variable here, and under
+     * `exactOptionalPropertyTypes` that would otherwise need a conditional spread.
+     * "No prefix" and "absent" mean the same thing. `@dunx/testing` relies on it.
+     */
+    readonly prefix?: string | undefined;
+    /** Mounts an `OPTIONS` preflight per path, as {@link HttpApp.enableCors} does. */
+    readonly cors?: CorsOptions;
+    /** `app.set('trust proxy', ...)` as a field. */
+    readonly trustProxy?: boolean;
+    /**
+     * Calls `enableShutdownHooks` at construction. `true` takes the default signals;
+     * an object names them and tunes the force-exit.
+     */
+    readonly shutdownHooks?: boolean | {
+        readonly signals?: readonly ShutdownSignal[];
+        readonly options?: ShutdownHookOptions;
+    };
     /** Resolved from the container, so middleware can inject(). */
     readonly middleware?: readonly Ctor<Middleware>[];
     /**

package/dist/server/options-provider.d.ts

@@ -0,0 +1,108 @@
+import type { Ctor } from '@dunx/core';
+import type { HttpOptions } from './application.js';
+import type { SocketLoggingOptions } from '../ws/logging.js';
+import type { SocketMiddleware } from '../ws/middleware.js';
+import type { PubSubRelay, RelayOptions } from '../ws/relay.js';
+import type { SocketOptions } from '../ws/socket.js';
+import type { CorsOptions } from './cors.js';
+import type { ErrorHandler } from './errors.js';
+import type { Middleware } from './middleware.js';
+import type { RequestLoggingOptions } from './request-logging.js';
+/**
+ * How an app configures its HTTP server. A subclass is resolved from the
+ * container, so it can inject `ConfigService`.
+ *
+ * ```ts
+ * export class AppHttpOptions extends HttpOptionsProvider {
+ *   constructor(private readonly config: AppConfigService) {
+ *     super();
+ *   }
+ *
+ *   override trustProxy = true;
+ *
+ *   override get prefix(): string {
+ *     return this.config.get('app').prefix;
+ *   }
+ * }
+ *
+ * @Module({ providers: [provide(HttpOptionsProvider, { useClass: AppHttpOptions })] })
+ * export class HttpConfigModule {}
+ * ```
+ *
+ * Every member has a default, and anything passed to `create()` wins field by
+ * field. Override a field with a field and a getter with a getter (`TS2611`,
+ * `TS2610`). See docs/architecture/http.md, "HTTP options as a provider".
+ */
+export declare abstract class HttpOptionsProvider {
+    /**
+     * Global middleware, in order, outermost first. Module-scoped middleware is
+     * declared by that module instead and does not belong here.
+     */
+    readonly middleware: readonly Ctor<Middleware>[];
+    /** The socket half of {@link middleware}. */
+    readonly socketMiddleware: readonly Ctor<SocketMiddleware>[];
+    /**
+     * What an unmatched path looks like to global middleware. `'guarded'` gives the
+     * miss no route metadata, so a global guard refuses it and a prober cannot tell a
+     * 404 from a 401; `'public'` reports it as `@Public()` for a conventional 404.
+     */
+    readonly notFound: 'guarded' | 'public';
+    /** One entry at `listen()` naming every route and gateway served. */
+    readonly bootLogging: boolean;
+    /**
+     * Whether `x-forwarded-for` is believed. Off by default: believing it behind
+     * nothing lets any caller choose its own address.
+     */
+    readonly trustProxy: boolean;
+    /**
+     * Install `SIGTERM`/`SIGINT` handlers that shut the app down. Off by default,
+     * because installing a signal handler changes how the process terminates and
+     * that is the app's decision to make.
+     *
+     * The object form names the signals and tunes the force-exit watchdog, which is
+     * what `forceExitAfter()` in a hand-written `main.ts` was doing:
+     * `{ signals: ['SIGTERM'], options: { exitAfterMs: 8000 } }`.
+     */
+    readonly shutdownHooks: NonNullable<HttpOptions['shutdownHooks']>;
+    /** The broker channel a relay carries frames on. */
+    readonly relayChannel: string;
+    /** Prefixes every discovered route. Empty means none. */
+    get prefix(): string;
+    /** `undefined` lets `listen(port)` decide, which is what a test harness needs. */
+    get port(): number | undefined;
+    /** `undefined` mounts no preflight at all. */
+    get cors(): CorsOptions | undefined;
+    /** `false` removes the middleware from the chain; an object tunes it. */
+    get requestLogging(): boolean | RequestLoggingOptions;
+    get socketLogging(): boolean | SocketLoggingOptions;
+    /**
+     * Replaces the default mapper. Prefer an `ErrorFilter` class over a bare
+     * function: a class is resolved from the container and can inject.
+     */
+    get onError(): ErrorHandler | undefined;
+    get websocket(): SocketOptions | undefined;
+    /** Multi-node websocket fan-out. Absent publishes to this process only. */
+    get relay(): PubSubRelay | undefined;
+    get relayResubscribe(): RelayOptions['resubscribe'];
+}
+/**
+ * The base itself, bound when no module bound a subclass. Concrete because the
+ * container has to construct something, and every member already has a default.
+ */
+export declare class DefaultHttpOptions extends HttpOptionsProvider {
+}
+/**
+ * One options object out of the two places they can come from.
+ *
+ * **The argument wins, field by field, and the provider fills the rest.** That
+ * ordering is not a preference: `HttpFactory.create(root, options)` already means
+ * something, and if the provider won, adding one to an existing app would silently
+ * change what its argument does. A field the argument does not mention is the
+ * provider's to answer, which is how an app moves configuration into the container
+ * one field at a time rather than all at once.
+ *
+ * Each getter is read exactly once, here, which is when the argument was read
+ * before. A getter that depends on something settling later should be read at the
+ * point it is used instead.
+ */
+export declare function resolveHttpOptions(settings: HttpOptionsProvider, given: HttpOptions): HttpOptions;

package/dist/ws/relay-module.d.ts

@@ -0,0 +1,49 @@
+import { type AsyncModuleConfig, type Deps, type DynamicModule } from '@dunx/core';
+import { type RedisRelayOptions } from './redis-relay.js';
+/**
+ * The relay's connection settings, as a class so a factory can bind them.
+ *
+ * `RedisRelayOptions` stays the interface a caller writes; this is what the
+ * container holds, which is the same split `HttpClientOptions` and
+ * `HttpClientOptionsInit` use.
+ */
+export declare class RelayConnectionOptions {
+    readonly url: string | undefined;
+    readonly maxRetries: number | undefined;
+    readonly connectionTimeout: number | undefined;
+    readonly tls: boolean | Bun.TLSOptions | undefined;
+    constructor(init?: RedisRelayOptions);
+    /** Only the keys actually set, so each `RedisRelay` default still applies. */
+    toInit(): RedisRelayOptions;
+}
+/**
+ * Binds the websocket relay, so `relay` is a provider rather than an instance
+ * `main.ts` constructs and threads into `HttpFactory.create`.
+ *
+ * `RedisRelay` is a class, so an options provider takes it as a parameter:
+ *
+ * ```ts
+ * export class AppHttpOptions extends HttpOptionsProvider {
+ *   constructor(private readonly bus: RedisRelay) {
+ *     super();
+ *   }
+ *
+ *   override get relay(): PubSubRelay {
+ *     return this.bus;
+ *   }
+ * }
+ * ```
+ *
+ * A relay of your own needs no module: bind the class and return it from that
+ * same getter. This one exists because `RedisRelay` is the one dunx ships and its
+ * url comes from config like everything else.
+ */
+export declare class WsRelayModule {
+    static forRoot(init?: RedisRelayOptions): DynamicModule;
+    /**
+     * The same bindings with the settings behind a factory, so the url can come off
+     * `ConfigService`. `imports` reaches that factory; importing the module
+     * alongside does not, since a dynamic module is its own scope.
+     */
+    static forRootAsync<const D extends Deps>(config: AsyncModuleConfig<RedisRelayOptions, D>): DynamicModule;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "3.0.5",
+  "version": "3.1.0",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -62,7 +62,7 @@
     "@dunx/core": "workspace:*"
   },
   "peerDependencies": {
-    "@dunx/core": "^3.0.5",
+    "@dunx/core": "^3.1.0",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {