@dunx/http 3.2.0 → 3.3.0

package/dist/inspect.d.ts

@@ -1,4 +1,13 @@
 import { type Dependency, type ModuleRef } from '@dunx/core';
+/**
+ * Routes and gateways read off the module graph, constructing nothing. The
+ * traversal is `@dunx/core`'s; here is the half needing this package's metadata -
+ * route markers, guards, `@Roles`/`@Public`, the gateway marker.
+ *
+ * `discoverRoutes` walks a prototype chain, and
+ * `Object.create(Controller.prototype)` is that chain with nothing behind it, so
+ * no constructor or dependency of one has to exist.
+ */
 export interface RouteInputs {
     readonly body?: string;
     readonly query?: string;

package/dist/internal.d.ts

@@ -3,34 +3,17 @@
  *
  * The barrel was a semver promise 173 symbols wide, which is more than this
  * package meant to make. What stays public there is the surface an app writes
- * against:
- * decorators, options, contracts, errors, modules and the metadata helpers a
- * user's own guard reads. What is here is route-table construction, the
- * middleware fold, the relay codec and the discovery readers - things
- * `@dunx/dashboard`, `@dunx/mcp` and `@dunx/openapi` need and an app does not.
+ * against. What is here is the discovery readers and route metadata that
+ * `@dunx/dashboard`, `@dunx/mcp`, `@dunx/openapi` and `@dunx/testing` import.
+ *
+ * It held 62 symbols and 50 had no importer, all of them reachable from inside
+ * this package by relative import. Add one back when a sibling needs it.
  *
  * No stability promise attaches to this subpath.
  */
 export { discoverRoutes, joinPath, type DiscoveredRoute, } from './route/discover.js';
-export { defaultStatusFor, type DefaultStatus, type RouteMeta, } from './route/marker.js';
-export { guardsOf } from './route/metadata.js';
+export { defaultStatusFor } from './route/marker.js';
 export { gatewaysOf, routesOf, type GatewayHandler, type GatewayNode, type RouteInputs, type RouteNode, } from './inspect.js';
 export { buildContext } from './server/context.js';
-export { preflight, withCors } from './server/cors.js';
-export { isErrorFilter, toErrorMapper } from './server/errors.js';
-export { compose } from './server/middleware.js';
-export { assertNoCollisions, assertNoGatewayCollisions, buildRoutes, withUpgradeRoutes, type BunRoutes, type GuardResolver, type RouteMethod, type ServeRoutes, } from './server/routes.js';
-export { normalizePrefix } from './static/options.js';
-export { negotiate } from './compression/negotiate.js';
-export { isCompressibleType } from './compression/options.js';
-export { buildWebSocket, type UpgradeHandler, type WebSocketRuntime, } from './ws/adapter.js';
-export { discoverGateway, discoverGateways, normalizePath, type DiscoveredGateway, type DiscoveredHandler, type Invoke, } from './ws/discover.js';
-export { decode, encode } from './ws/envelope.js';
-export { composeSocket, observe } from './ws/middleware.js';
-export { HandlerKind, isGateway, type HandlerMeta } from './ws/marker.js';
-export { defaultRelayUrl } from './ws/redis-relay.js';
-export { decodeRelay, encodeRelay, type RelayFrame, type RelayPhase, } from './ws/relay.js';
-export { buildGateways, buildRuntime, type GatewayRuntime, } from './ws/runtime.js';
-export { HiddenHealthController } from './health/controller.js';
-export { backoffDelay, executeWithRetry, isRetryableStatus, retryAfterMs, } from './client/retry.js';
-export { isJsonBody, isPlainObject, safeStringify } from './client/json.js';
+export { embedJson } from './server/html.js';
+export { isGateway } from './ws/marker.js';

package/dist/internal.js

@@ -1,56 +1,22 @@
 // @bun
+import"./chunk-bg0dr54z.js";
 import {
-  HIDDEN,
-  HandlerKind,
-  HiddenHealthController,
-  PUBLIC,
-  ROLES,
-  assertNoCollisions,
-  assertNoGatewayCollisions,
-  buildContext,
-  buildGateways,
-  buildRoutes,
-  buildRuntime,
-  buildWebSocket,
-  compose,
-  composeSocket,
-  decode,
-  decodeRelay,
-  defaultRelayUrl,
-  defaultStatusFor,
+  defaultStatusFor2,
+  ROLES2,
+  PUBLIC2,
+  HIDDEN2,
+  joinPath2,
+  discoverRoutes2,
+  isGateway2,
   discoverGateway,
-  discoverGateways,
-  discoverRoutes,
-  encode,
-  encodeRelay,
-  guardsOf,
-  isCompressibleType,
-  isErrorFilter,
-  isGateway,
-  joinPath,
-  negotiate,
-  normalizePath,
-  normalizePrefix,
-  observe,
-  preflight,
-  toErrorMapper,
-  withCors,
-  withUpgradeRoutes
-} from "./chunk-y85wcdhw.js";
-import {
-  backoffDelay,
-  executeWithRetry,
-  isJsonBody,
-  isPlainObject,
-  isRetryableStatus,
-  retryAfterMs,
-  safeStringify
-} from "./chunk-e8a9c6j2.js";
-import"./chunk-9x3evk19.js";
+  buildContext2
+} from "./chunk-8939brh2.js";
 // src/inspect.ts
 import {
+  classOf,
   collectModules,
   dependenciesOf,
+  inertInstance,
   readControllers
 } from "@dunx/core";
 var vendorOf = (schema) => schema?.["~standard"]?.vendor;
@@ -65,7 +31,7 @@ var validatesIn = (options) => {
   };
 };
 var rolesIn = (route) => {
-  const roles = route.meta?.get(ROLES.id);
+  const roles = route.meta?.get(ROLES2.id);
   if (roles === undefined || roles === null)
     return null;
   return (Array.isArray(roles) ? roles : [roles]).map(String);
@@ -76,20 +42,19 @@ var nodeFor = (route, module) => ({
   controller: route.controller,
   handler: route.handlerName,
   module,
-  public: route.meta?.get(PUBLIC.id) === true,
+  public: route.meta?.get(PUBLIC2.id) === true,
   roles: rolesIn(route),
   guards: (route.guards ?? []).map((guard) => guard.name),
-  hidden: route.meta?.get(HIDDEN.id) === true,
+  hidden: route.meta?.get(HIDDEN2.id) === true,
   validates: validatesIn(route.options),
   status: route.options?.status ?? null,
   responses: Object.keys(route.options?.response ?? {}).map(Number)
 });
 var routesOf = (root) => collectModules(root).flatMap((module) => readControllers(module).flatMap((controller) => {
-  const { prototype } = controller;
-  return discoverRoutes(Object.create(prototype)).map((route) => nodeFor(route, module.name));
+  return discoverRoutes2(inertInstance(controller)).map((route) => nodeFor(route, module.name));
 }));
 var gatewayFor = (ctor, module) => {
-  const { name, path, handlers } = discoverGateway(Object.create(ctor.prototype));
+  const { name, path, handlers } = discoverGateway(inertInstance(ctor));
   return {
     name,
     path,
@@ -102,53 +67,16 @@ var gatewayFor = (ctor, module) => {
     }))
   };
 };
-var classOf = (entry) => {
-  if (typeof entry === "function")
-    return entry;
-  return entry.provider.kind === "class" ? entry.provider.ctor : undefined;
-};
-var gatewaysOf = (root) => collectModules(root).flatMap((module) => (module.options.providers ?? []).map(classOf).filter((ctor) => ctor !== undefined).filter(isGateway).map((ctor) => gatewayFor(ctor, module.name)));
+var gatewaysOf = (root) => collectModules(root).flatMap((module) => (module.options.providers ?? []).map((entry) => classOf(entry)?.ctor).filter((ctor) => ctor !== undefined).filter(isGateway2).map((ctor) => gatewayFor(ctor, module.name)));
+// src/server/html.ts
+var embedJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
 export {
-  HandlerKind,
-  HiddenHealthController,
-  assertNoCollisions,
-  assertNoGatewayCollisions,
-  backoffDelay,
-  buildContext,
-  buildGateways,
-  buildRoutes,
-  buildRuntime,
-  buildWebSocket,
-  compose,
-  composeSocket,
-  decode,
-  decodeRelay,
-  defaultRelayUrl,
-  defaultStatusFor,
-  discoverGateway,
-  discoverGateways,
-  discoverRoutes,
-  encode,
-  encodeRelay,
-  executeWithRetry,
+  buildContext2 as buildContext,
+  defaultStatusFor2 as defaultStatusFor,
+  discoverRoutes2 as discoverRoutes,
+  embedJson,
   gatewaysOf,
-  guardsOf,
-  isCompressibleType,
-  isErrorFilter,
-  isGateway,
-  isJsonBody,
-  isPlainObject,
-  isRetryableStatus,
-  joinPath,
-  negotiate,
-  normalizePath,
-  normalizePrefix,
-  observe,
-  preflight,
-  retryAfterMs,
-  routesOf,
-  safeStringify,
-  toErrorMapper,
-  withCors,
-  withUpgradeRoutes
+  isGateway2 as isGateway,
+  joinPath2 as joinPath,
+  routesOf
 };

package/dist/server/application.d.ts

@@ -1,106 +1,11 @@
 import type { BunRequest } from 'bun';
-import { type App, type AppOptions, type Ctor, type InjectionToken, type ModuleRef, type ShutdownHookOptions, type ShutdownSignal } from '@dunx/core';
+import { ShutdownAware, type App, type Ctor, type InjectionToken, type ModuleRef } from '@dunx/core';
 import { type DiscoveredRoute } from '../route/discover.js';
 import type { WebSocketRuntime } from '../ws/adapter.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';
 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>[];
-    /**
-     * Replaces the default mapper. Prefer an `ErrorFilter` class over a bare
-     * `ErrorMapper`: a class is resolved from the container and can inject.
-     */
-    readonly onError?: ErrorHandler;
-    /**
-     * One structured entry per request, on by default and outermost, so a request
-     * a guard rejected is still logged with the status it got.
-     * See {@link RequestLoggingMiddleware}.
-     */
-    readonly requestLogging?: boolean | RequestLoggingOptions;
-    /**
-     * Count requests and time them per route, readable through
-     * {@link RequestMetrics}. Off by default; `+35.2 ns` per request when
-     * `requestLogging` is on, because the entry it already builds shares the
-     * timing. With `requestLogging: false` a `MetricsMiddleware` pays for its own
-     * `.then` instead, at +175.9 ns.
-     */
-    readonly metrics?: boolean;
-    /**
-     * One entry at `listen()` naming every route and gateway served. On by default,
-     * and switched separately from `requestLogging`: one is per process, the other
-     * per request. `@dunx/testing` defaults it off.
-     */
-    readonly bootLogging?: boolean;
-    /** Bun's `websocket` options, plus where a throwing handler goes. Server-wide;
-     * gateways themselves are declared in `@Module({ providers })`. */
-    readonly websocket?: SocketOptions;
-    /**
-     * The socket half of `middleware`. Each entry wraps every dispatched gateway
-     * handler; `socketLogging`'s runs outermost, ahead of anything here.
-     */
-    readonly socketMiddleware?: readonly Ctor<SocketMiddleware>[];
-    /**
-     * One structured entry per socket frame, on by default at `debug` - a gateway
-     * can take a frame per connection per tick, so it writes nothing until an app
-     * lowers its level. See {@link SocketLoggingMiddleware}.
-     */
-    readonly socketLogging?: boolean | SocketLoggingOptions;
-    /**
-     * Multi-node websocket fan-out. Absent means `PubSub` publishes to this process
-     * only. Anything with `publish` and `subscribe` fits; one that has to come out
-     * of the container goes through `app.get(PubSub).relayThrough(...)` instead.
-     */
-    readonly relay?: PubSubRelay;
-    /** The broker channel the relay carries frames on. @default 'dunx:ws' */
-    readonly relayChannel?: string;
-    /**
-     * How hard to retry a failed subscribe. Bounded, doubling, on an unref'd timer,
-     * so a broker that never returns cannot hold the process open.
-     */
-    readonly relayResubscribe?: RelayOptions['resubscribe'];
-    /**
-     * 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.
-     * Either way `UNMATCHED` is set, which no real route sets.
-     *
-     * @default 'guarded'
-     */
-    readonly notFound?: 'guarded' | 'public';
-}
+import type { HttpOptions } from './options.js';
 /**
  * Everything below `listen()` configures the route table, built once when the
  * server binds. Calling any of them afterwards throws.
@@ -118,9 +23,11 @@ export interface HttpApp extends App {
     clientIp(req: BunRequest): string | undefined;
     /** Every gateway path this app upgrades on, exactly as mounted. */
     readonly gatewayPaths: readonly string[];
+    /** The gateway port's own url, `undefined` unless `gatewayPort` split them. */
+    readonly gatewayUrl: string | undefined;
     listen(port?: number): Promise<string>;
 }
-export declare class HttpApplication implements HttpApp {
+export declare class HttpApplication extends ShutdownAware implements HttpApp {
     #private;
     /** Forwarded from the container so an app can log scope warnings at boot. */
     readonly warnings: readonly string[];
@@ -137,6 +44,8 @@ export declare class HttpApplication implements HttpApp {
     /** The one `Bun.serve` call. A gateway's upgrade is a native `GET` route in the
      * same table, so Bun's router matches it and no `fetch` handler is needed. */
     listen(port?: number): Promise<string>;
+    /** The gateway port's own url, when `gatewayPort` split them. */
+    get gatewayUrl(): string | undefined;
     /** Public so an operator can start draining without committing to a shutdown,
      * which is what a readiness probe wants during a rolling deploy. */
     drain(): Promise<void>;
@@ -146,5 +55,4 @@ export declare class HttpApplication implements HttpApp {
      * `closed` unresolved; failures are collected and thrown at the end.
      */
     shutdown(): Promise<void>;
-    enableShutdownHooks(signals?: readonly ShutdownSignal[], options?: ShutdownHookOptions): this;
 }

package/dist/server/binding.d.ts

@@ -0,0 +1,67 @@
+import type { Server } from 'bun';
+import type { SocketData } from '../ws/socket.js';
+import type { WebSocketRuntime } from '../ws/adapter.js';
+import type { RouteHandler } from './middleware.js';
+import { type BunRoutes } from './routes.js';
+/** What `listen()` computes and hands the binding, once the table is final. */
+export interface BindingPlan {
+    readonly port: number;
+    readonly routes: BunRoutes;
+    readonly fetch: RouteHandler;
+    readonly websocket: WebSocketRuntime | undefined;
+}
+/** The protocol settings, fixed at construction. `undefined` leaves Bun's own
+ * default in place rather than restating it. */
+export interface BindingProtocols {
+    readonly http2?: boolean | undefined;
+    readonly http1?: boolean | undefined;
+    /**
+     * A port of its own for the gateways. When set, the upgrade routes are not
+     * merged into the main table and a second `Bun.serve` takes them.
+     */
+    readonly gatewayPort?: number | undefined;
+}
+/**
+ * The two per-server counters a metrics reader wants, summed across however
+ * many servers are bound. `Server` satisfies it on its own, which is what an
+ * unsplit app hands over.
+ */
+export interface ServerGauges {
+    readonly pendingRequests: number;
+    readonly pendingWebSockets: number;
+}
+export interface Bound {
+    readonly main: Server<SocketData>;
+    /** The server that owns the sockets, which is what `PubSub` publishes on. */
+    readonly sockets: Server<SocketData>;
+    readonly gauges: ServerGauges;
+}
+/**
+ * The one or two `Bun.serve` instances an app binds.
+ *
+ * One is the normal shape: a gateway's upgrade is a native `GET` route in the
+ * same table, so Bun's router matches it and nothing else is needed.
+ *
+ * Two exist for `gatewayPort`. A websocket upgrade is an HTTP/1.1 request, so a
+ * server with `http1: false` can serve HTTP/2 routes or gateways and never both;
+ * splitting the ports is what lets one app do both. The gateway server takes no
+ * protocol overrides, because refusing HTTP/1.x there is the thing being avoided.
+ *
+ * Both servers come from one container, which is the reason this is a second
+ * `Bun.serve` rather than a second `HttpFactory.create`: a second app would build
+ * a second container, and the gateways would inject different singletons than the
+ * controllers.
+ */
+export declare class ServerBinding {
+    #private;
+    constructor(protocols: BindingProtocols);
+    bind(plan: BindingPlan): Bound;
+    get gatewayUrl(): string | undefined;
+    /**
+     * `force` is for the server that owns the sockets: a graceful stop waits for
+     * open connections, and a WebSocket never closes itself, so those clients see
+     * a 1006. Under a split the routes server holds none and stops gracefully, so
+     * an in-flight request there finishes rather than being cut off.
+     */
+    stop(force: boolean): Promise<void>;
+}

package/dist/server/factory.d.ts

@@ -1,6 +1,8 @@
 import { type ModuleRef } from '@dunx/core';
-import { type HttpApp, type HttpOptions } from './application.js';
-export type { HttpApp, HttpOptions } from './application.js';
+import { type HttpApp } from './application.js';
+import type { HttpOptions } from './options.js';
+export type { HttpApp } from './application.js';
+export type { HttpOptions } from './options.js';
 export declare class HttpFactory {
     #private;
     /**

package/dist/server/html.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Serialise a value for a `<script type="application/json">` block.
+ *
+ * `<` is the only character that can end the data block early, and escaping it as
+ * `\u003c` keeps the text valid JSON - the parser sees the same document either
+ * way. `@dunx/dashboard` and `@dunx/openapi` both inline a model into a page they
+ * serve, and both had a copy of this; if the escaping ever proves insufficient,
+ * one fix should cover both pages.
+ */
+export declare const embedJson: (value: unknown) => string;

package/dist/server/metrics.d.ts

@@ -1,5 +1,6 @@
 import { type HistogramSnapshot } from '@dunx/core';
-import type { BunRequest, Server } from 'bun';
+import type { BunRequest } from 'bun';
+import type { ServerGauges } from './binding.js';
 import type { RouteContext } from './context.js';
 import type { Middleware, Next } from './middleware.js';
 /** Every path Bun matched nothing for, collapsed into one series. */
@@ -53,8 +54,12 @@ export declare class RequestMetrics {
      * reflecting a deploy three days ago; who calls this is the app's decision.
      */
     reset(): void;
-    /** Internal: `listen()` hands the bound server to the resolved singleton. */
-    attach(server: Server<unknown>): void;
+    /**
+     * Internal: `listen()` hands the bound server's counters to the resolved
+     * singleton. Structural, so an app serving from two ports can hand over the
+     * sum rather than one server's half of it.
+     */
+    attach(server: ServerGauges): void;
 }
 /**
  * Whether `MetricsMiddleware` is the thing doing the observing.

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

@@ -1,5 +1,5 @@
 import type { Ctor } from '@dunx/core';
-import type { HttpOptions } from './application.js';
+import type { HttpOptions } from './options.js';
 import type { SocketLoggingOptions } from '../ws/logging.js';
 import type { SocketMiddleware } from '../ws/middleware.js';
 import type { PubSubRelay, RelayOptions } from '../ws/relay.js';
@@ -86,6 +86,19 @@ export declare abstract class HttpOptionsProvider {
     /** Multi-node websocket fan-out. Absent publishes to this process only. */
     get relay(): PubSubRelay | undefined;
     get relayResubscribe(): RelayOptions['resubscribe'];
+    /**
+     * Serve HTTP/2 alongside HTTP/1.1 on the same port. `undefined` rather than
+     * `false` so an absent answer leaves Bun's own default in place instead of
+     * restating it. See {@link HttpOptions.http2}.
+     */
+    get http2(): boolean | undefined;
+    /** See {@link HttpOptions.http1}. `false` disables every gateway. */
+    get http1(): boolean | undefined;
+    /**
+     * A port of its own for the gateways, which is what makes `http1: false`
+     * usable with one. See {@link HttpOptions.gatewayPort}.
+     */
+    get gatewayPort(): number | undefined;
 }
 /**
  * The base itself, bound when no module bound a subclass. Concrete because the

package/dist/server/options.d.ts

@@ -0,0 +1,141 @@
+import type { AppOptions, Ctor, ShutdownHookOptions, ShutdownSignal } from '@dunx/core';
+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';
+/**
+ * Every setting `HttpFactory.create` takes. Here rather than in
+ * `application.ts` so that file is the class it is named for.
+ *
+ * Each field has a twin on {@link HttpOptionsProvider}, which is the same
+ * settings answered from the container instead. The argument wins field by
+ * field; see `resolveHttpOptions`.
+ */
+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>[];
+    /**
+     * Replaces the default mapper. Prefer an `ErrorFilter` class over a bare
+     * `ErrorMapper`: a class is resolved from the container and can inject.
+     */
+    readonly onError?: ErrorHandler;
+    /**
+     * One structured entry per request, on by default and outermost, so a request
+     * a guard rejected is still logged with the status it got.
+     * See {@link RequestLoggingMiddleware}.
+     */
+    readonly requestLogging?: boolean | RequestLoggingOptions;
+    /**
+     * Count requests and time them per route, readable through
+     * {@link RequestMetrics}. Off by default; `+35.2 ns` per request when
+     * `requestLogging` is on, because the entry it already builds shares the
+     * timing. With `requestLogging: false` a `MetricsMiddleware` pays for its own
+     * `.then` instead, at +175.9 ns.
+     */
+    readonly metrics?: boolean;
+    /**
+     * One entry at `listen()` naming every route and gateway served. On by default,
+     * and switched separately from `requestLogging`: one is per process, the other
+     * per request. `@dunx/testing` defaults it off.
+     */
+    readonly bootLogging?: boolean;
+    /** Bun's `websocket` options, plus where a throwing handler goes. Server-wide;
+     * gateways themselves are declared in `@Module({ providers })`. */
+    readonly websocket?: SocketOptions;
+    /**
+     * The socket half of `middleware`. Each entry wraps every dispatched gateway
+     * handler; `socketLogging`'s runs outermost, ahead of anything here.
+     */
+    readonly socketMiddleware?: readonly Ctor<SocketMiddleware>[];
+    /**
+     * One structured entry per socket frame, on by default at `debug` - a gateway
+     * can take a frame per connection per tick, so it writes nothing until an app
+     * lowers its level. See {@link SocketLoggingMiddleware}.
+     */
+    readonly socketLogging?: boolean | SocketLoggingOptions;
+    /**
+     * Multi-node websocket fan-out. Absent means `PubSub` publishes to this process
+     * only. Anything with `publish` and `subscribe` fits; one that has to come out
+     * of the container goes through `app.get(PubSub).relayThrough(...)` instead.
+     */
+    readonly relay?: PubSubRelay;
+    /** The broker channel the relay carries frames on. @default 'dunx:ws' */
+    readonly relayChannel?: string;
+    /**
+     * How hard to retry a failed subscribe. Bounded, doubling, on an unref'd timer,
+     * so a broker that never returns cannot hold the process open.
+     */
+    readonly relayResubscribe?: RelayOptions['resubscribe'];
+    /**
+     * 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.
+     * Either way `UNMATCHED` is set, which no real route sets.
+     *
+     * @default 'public'
+     */
+    readonly notFound?: 'guarded' | 'public';
+    /**
+     * Serve HTTP/2 on the same port, through the same routes and the same
+     * `fetch` fallback. Without TLS that is h2c: a client opening with the HTTP/2
+     * preface gets HTTP/2 and everyone else gets HTTP/1.1, which is what a proxy
+     * in front of the app speaks. Bun marks the option experimental.
+     *
+     * Gateways are unaffected and keep working, because a websocket upgrade is an
+     * HTTP/1.1 request and Bun serves both protocols on the one socket. There is
+     * no websocket over HTTP/2.
+     *
+     * @default false
+     */
+    readonly http2?: boolean;
+    /**
+     * Serve HTTP/1.1. `false` alongside `http2` refuses HTTP/1.x with a 505, which
+     * **disables every gateway**: a websocket upgrade is an HTTP/1.1 request, so
+     * nothing can connect to one. Only for a port that is HTTP/2 or nothing.
+     *
+     * @default true
+     */
+    readonly http1?: boolean;
+    /**
+     * A port of its own for the gateways. The routes keep {@link port} and the
+     * upgrades move here, on a second `Bun.serve` that takes no protocol
+     * overrides, so it speaks HTTP/1.1 whatever the main port is set to.
+     *
+     * This is what makes `http2` with `http1: false` usable: a websocket upgrade
+     * is an HTTP/1.1 request, so one port serves HTTP/2-only routes or gateways
+     * and never both. The pair without a `gatewayPort` is a boot error.
+     *
+     * `0` takes any free port and is the one value that does not warn when no
+     * gateway is declared. See docs/guide/19-deployment.md.
+     */
+    readonly gatewayPort?: number;
+}

package/dist/ws/decorators.d.ts

@@ -1,5 +1,5 @@
+import type { HandlerMethod } from '@dunx/core';
 type GatewayTarget = abstract new (...args: never[]) => object;
-type HandlerMethod = (...args: never[]) => unknown;
 export declare const Gateway: (path?: string) => <T extends GatewayTarget>(target: T) => T;
 /** Runs before the socket exists. Return a `Response` to refuse the upgrade. */
 export declare const OnUpgrade: () => <T extends HandlerMethod>(value: T) => T;

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

@@ -1,6 +1,4 @@
 import { WsRelay } from './relay.js';
-/** The same fallback chain `Bun.SQL` uses when given no URL. */
-export declare const defaultPostgresRelayUrl: () => string;
 export interface PostgresRelayOptions {
     /** @default `$POSTGRES_URL`, `$DATABASE_URL`, then `postgres://localhost:5432` */
     readonly url?: string;