@dunx/http 2.1.1 → 2.2.1

package/dist/server/application.d.ts

@@ -2,6 +2,8 @@ import type { BunRequest } from 'bun';
 import { type App, type AppOptions, type Ctor, type InjectionToken, type ModuleRef, type ShutdownHookOptions, type ShutdownSignal } 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';
@@ -50,6 +52,29 @@ export interface HttpOptions extends AppOptions {
      * themselves are declared in `@Module({ providers })`.
      */
     readonly websocket?: SocketOptions;
+    /**
+     * The socket half of `middleware`, resolved from the container the same way.
+     *
+     * Each entry wraps every dispatched gateway handler - open, each named message,
+     * the catch-all, close, drain, ping and pong - the way an HTTP middleware wraps a
+     * route. `socketLogging`'s middleware runs outermost, ahead of anything here.
+     */
+    readonly socketMiddleware?: readonly Ctor<SocketMiddleware>[];
+    /**
+     * One structured entry per socket frame, on by default at **`debug`**. `false`
+     * removes it; an options object tunes the level per event. See
+     * {@link SocketLoggingMiddleware}.
+     *
+     * `debug` rather than request logging's `info`, because a gateway can take a
+     * frame per connection per tick. The default `ConsoleLogger` threshold is
+     * `info`, so this writes nothing until an app lowers its level or names a louder
+     * one here.
+     *
+     * Installing it also takes `SocketOptions.onError`'s `console.error` default out
+     * of the way: a middleware wraps the handler, so the failure is already reported
+     * through the `Logger` with the gateway and the event on it.
+     */
+    readonly socketLogging?: boolean | SocketLoggingOptions;
     /**
      * Multi-node websocket fan-out. Absent - the default - means `PubSub` publishes
      * to this process only, which is exactly Bun's native pub/sub and costs nothing.
@@ -138,6 +163,12 @@ export declare class HttpApplication implements HttpApp {
      * shutdown, which is what a readiness probe wants during a rolling deploy.
      */
     drain(): Promise<void>;
+    /**
+     * The four phases, in order, and **none of them is skipped because an earlier
+     * one failed**. A drain hook that threw used to abort this before `server.stop()`
+     * had run, so the port stayed open and `closed` never resolved; each failure is
+     * collected now and thrown once the whole teardown is over.
+     */
     shutdown(): Promise<void>;
     enableShutdownHooks(signals?: readonly ShutdownSignal[], options?: ShutdownHookOptions): this;
 }

package/dist/server/errors.d.ts

@@ -1,8 +1,22 @@
 import { AppError, type Ctor, type Logger } from '@dunx/core';
+export interface HttpErrorOptions extends ErrorOptions {
+    /**
+     * Headers the error response carries. `Retry-After` on a 429,
+     * `WWW-Authenticate` on a 401, `Allow` on a 405 - each of them part of the
+     * status rather than an extra, and none of them expressible by a throw before
+     * this existed.
+     *
+     * {@link errorMapper} copies them onto the response. An app that replaces the
+     * mapper has to read them itself, which is the same contract `status` and
+     * `message` already have.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
 export declare class HttpError extends AppError {
     readonly status: number;
     name: string;
-    constructor(status: number, message: string, options?: ErrorOptions);
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    constructor(status: number, message: string, options?: HttpErrorOptions);
 }
 /** Which declared schema rejected the request. */
 export type InputSource = 'body' | 'query' | 'params';

package/dist/server/factory.d.ts

@@ -2,6 +2,7 @@ import { type ModuleRef } from '@dunx/core';
 import { type HttpApp, type HttpOptions } from './application.js';
 export type { HttpApp, HttpOptions } from './application.js';
 export declare class HttpFactory {
+    #private;
     /**
      * Boots the container, discovers every controller's routes and every gateway's
      * handlers, and rejects a collision in either. The `Bun.serve` route table itself

package/dist/server/request-id.d.ts

@@ -0,0 +1,27 @@
+export declare const REQUEST_ID_HEADER = "x-request-id";
+/**
+ * The request id, and the only thing that decides a request has one.
+ *
+ * `RequestLoggingMiddleware` sets the header on a response it returns, and a
+ * failure is never one: `buildRoutes` and `buildFallback` catch outside the chain
+ * and build a fresh `Response` from the error mapper. So a guard's 401, a
+ * validation 400, a mapped 500 and every unmatched 404 went out with no id on
+ * them, which are the responses a caller most needs in order to find the log line
+ * the middleware just wrote.
+ *
+ * Recorded against the request rather than threaded through the mapper, because
+ * `ErrorMapper` is `(error, req) => Response` and an app writes its own.
+ * {@link stamp} then reads back whatever {@link assign} recorded, so an app that
+ * turned request logging off, or a path it told the middleware to ignore, is still
+ * answered without a header: nothing minted an id, so there is none to stamp.
+ */
+export declare class RequestIds {
+    /**
+     * Called by `RequestLoggingMiddleware` and by nothing else. Splitting minting
+     * from recording would let a second caller invent an id the log line does not
+     * carry.
+     */
+    static assign(req: Request): string;
+    /** The response, with this request's id on it if it was ever given one. */
+    static stamp(response: Response, req: Request): Response;
+}

package/dist/server/request-logging.d.ts

@@ -2,7 +2,6 @@ import { Logger, RequestContext } from '@dunx/core';
 import type { BunRequest } from 'bun';
 import type { RouteContext } from './context.js';
 import type { Middleware, Next } from './middleware.js';
-export declare const REQUEST_ID_HEADER = "x-request-id";
 export interface RequestLoggingOptions {
     /** Bodies past this many characters are logged as a size. Default 2048. `0` omits them. */
     readonly maxBodyLength?: number;

package/dist/server/routes.d.ts

@@ -47,6 +47,26 @@ export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMa
  * matched. It puts the global middleware in front of a 404 in the framework's
  * own error shape.
  *
+ * **The miss is a `throw`, not a returned `Response`.** `miss` raises
+ * `HttpError(404)` and `compose` propagates it, so a middleware written as
+ * `const response = await next(); if (response.status === 404) ...` never reaches
+ * its own second line on an unmatched path - the rewrite it was written for is the
+ * one case it cannot see. A middleware that means to act on a miss has to catch:
+ *
+ * ```ts
+ * try {
+ *   return await next();
+ * } catch (error) {
+ *   if (!(error instanceof HttpError) || error.status !== 404) throw error;
+ *   return rewritten();
+ * }
+ * ```
+ *
+ * `ctx.get(UNMATCHED)` is the other half, and the cheaper one: it is set here and
+ * by no real route, so a middleware can tell "nothing matched this path" from "a
+ * handler answered 404 for a record that does not exist" **before** calling
+ * `next()` at all. Only the second of those is a `Response` to inspect.
+ *
  * Composed per request rather than at boot, because the context names the path
  * that missed. That allocation is on the 404 path only.
  */

package/dist/static/module.d.ts

@@ -14,9 +14,43 @@ import { type StaticOptionsInit } from './options.js';
  * default can know which. Anything outside the mount falls through untouched, so
  * the app's own routes and its 404 behave exactly as before.
  *
- * There is no `index.html` fallback and no SPA rewrite. Both are one route in the
- * app - `@Get('/*')` returning `Bun.file(...)` - and building them in would mean
+ * There is no `index.html` fallback and no SPA rewrite: building them in would mean
  * this middleware deciding what a 404 means for paths it does not own.
+ *
+ * An app that wants one writes a middleware **outside** this one, and the shape
+ * matters. An unmatched path is a **thrown** `HttpError(404)`, not a returned
+ * `Response` - see `buildFallback` - so reading `(await next()).status` never sees a
+ * miss, and `ctx.get(UNMATCHED)` is what does:
+ *
+ * ```ts
+ * export class SpaFallback implements Middleware {
+ *   async handle(req: BunRequest, ctx: RouteContext, next: Next) {
+ *     const missed = ctx.get(UNMATCHED) === true;
+ *     if (
+ *       !missed ||
+ *       req.method !== 'GET' ||
+ *       new URL(req.url).pathname.startsWith('/api') ||
+ *       !(req.headers.get('accept') ?? '').includes('text/html')
+ *     ) {
+ *       return next();
+ *     }
+ *     const index = Bun.file(`${root}/index.html`);
+ *     if (!(await index.exists())) return next();
+ *     // The document carries the hashed asset names, so a stale one points at
+ *     // bundles that no longer exist.
+ *     return new Response(index, {
+ *       headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' },
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * Two more things that shape where it goes in the chain. `notFound: 'guarded'` -
+ * the default - reports a miss with no route metadata, so a global session guard
+ * refuses it and the status is a 401 rather than a 404; an app serving a SPA wants
+ * `notFound: 'public'`. And the fallback answers **before** any middleware listed
+ * after the guard, so the rewrite has to sit ahead of the guard to see the miss at
+ * all.
  */
 export declare class StaticModule {
     static forRoot(init: StaticOptionsInit): DynamicModule;

package/dist/throttle/decorators.d.ts

@@ -0,0 +1,22 @@
+import { type MetaKey } from '../route/metadata.js';
+export interface ThrottleLimit {
+    /** Requests allowed per window, per subject. */
+    readonly limit: number;
+    readonly windowSeconds: number;
+}
+/**
+ * Read off a `RouteContext` the way `ROLES` and `PUBLIC` are, so an app can build
+ * its own guard on the same metadata rather than a parallel one.
+ */
+export declare const THROTTLE: MetaKey<ThrottleLimit>;
+export declare const SKIP_THROTTLE: MetaKey<boolean>;
+/**
+ * A per-route limit, replacing the module's default for this handler.
+ *
+ * Valid on a method or on a class. A class-level limit covers every handler in the
+ * controller and a handler's own wins over it, because the route's metadata is
+ * `mergeMeta(klass, handler)` - the same precedence `@Roles` has.
+ */
+export declare const Throttle: (limit: ThrottleLimit) => <F extends object>(target: F) => F;
+/** Exempts a handler, or a whole controller, from the limit entirely. */
+export declare const SkipThrottle: () => <F extends object>(target: F) => F;

package/dist/throttle/guard.d.ts

@@ -0,0 +1,31 @@
+import { Logger } from '@dunx/core';
+import type { BunRequest } from 'bun';
+import { ClientAddress } from '../server/client-address.js';
+import type { RouteContext } from '../server/context.js';
+import type { Middleware, Next } from '../server/middleware.js';
+import { ThrottleOptions } from './options.js';
+import { ThrottleStore } from './store.js';
+/**
+ * A fixed-window rate limit, one key per subject and handler.
+ *
+ * **Fails open.** A store that cannot be reached allows the request and warns
+ * **once per process** - a line per request would be its own outage, and refusing
+ * every request because the counter is down turns a degraded dependency into a
+ * dead service.
+ *
+ * **List it after any session guard.** An authenticated caller should be limited by
+ * user id and an anonymous one by address, and only the guard ahead of this one
+ * knows which - which is what `ThrottleOptions.subject` reads.
+ *
+ * The 429 is thrown, never returned, so it goes through the app's own `onError` and
+ * comes out in the app's error shape like every other status.
+ */
+export declare class ThrottleGuard implements Middleware {
+    #private;
+    private readonly options;
+    private readonly store;
+    private readonly address;
+    private readonly logger;
+    constructor(options: ThrottleOptions, store: ThrottleStore, address: ClientAddress, logger: Logger);
+    handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
+}

package/dist/throttle/module.d.ts

@@ -0,0 +1,35 @@
+import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
+import { type ThrottleOptionsInit } from './options.js';
+/**
+ * A first-class rate limit: the decorator, the guard, the counter and its options.
+ *
+ * `global: true`, because the guard is listed in `HttpOptions.middleware` - which
+ * is the app's own list, resolved from wherever the class is declared - and a
+ * non-global module would make every consumer import this one to reach a guard it
+ * never names.
+ *
+ * ```ts
+ * ThrottleModule.forRootAsync({
+ *   useFactory: (config: AppConfig, redis: RedisConnection) => ({
+ *     ...config.throttle,
+ *     prefix: config.app.name,
+ *     store: new RedisThrottleStore(redis),
+ *     subject: (req) => caller.optional()?.id ?? address.of(req),
+ *   }),
+ *   inject: [AppConfig, RedisConnection] as const,
+ * });
+ *
+ * HttpFactory.create(AppModule, { middleware: [SessionGuard, ThrottleGuard] });
+ * ```
+ *
+ * Position in the chain is the app's, the same decision `StaticFiles` leaves open,
+ * and for a sharper reason: ahead of a session guard the limit counts every caller
+ * as an address.
+ */
+export declare class ThrottleModule {
+    static forRoot(init: ThrottleOptionsInit): DynamicModule;
+    /** `forRoot` with the limit read off the container - a config value, usually. */
+    static forRootAsync<const D extends Deps>(config: FactoryProvider<ThrottleOptionsInit, D> & {
+        readonly imports?: DynamicModule['imports'];
+    }): DynamicModule;
+}

package/dist/throttle/options.d.ts

@@ -0,0 +1,52 @@
+import type { BunRequest } from 'bun';
+import type { RouteContext } from '../server/context.js';
+import type { ThrottleLimit } from './decorators.js';
+import type { ThrottleStore } from './store.js';
+export interface ThrottleOptionsInit extends ThrottleLimit {
+    /**
+     * Namespaces every key this app writes. **Required, and an empty one throws.**
+     *
+     * There is no default on purpose. A scaffolded app that inherits the template's
+     * prefix and ships with it puts two applications in one Redis on one throttle
+     * namespace, each spending the other's budget - which is exactly what happened,
+     * and a friendly fallback is what let it.
+     */
+    readonly prefix: string;
+    /**
+     * Who is being limited. Defaults to the client address, or `'anonymous'` when
+     * even that is unknown.
+     *
+     * This is an option rather than an injected caller because the identity a limit
+     * counts by belongs to the app: an authenticated request is limited by user id
+     * and an anonymous one by address, and only the guard ahead of this one knows
+     * which. It is also what keeps `@dunx/http` from depending on `@dunx/auth`.
+     *
+     * ```ts
+     * subject: (req) => currentUser.optional()?.id ?? address.of(req)
+     * ```
+     */
+    readonly subject?: (req: BunRequest, ctx: RouteContext) => string | undefined;
+    /**
+     * Send `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, plus
+     * `Retry-After` on a 429. @default true
+     */
+    readonly headers?: boolean;
+    /**
+     * The counter. Defaults to {@link MemoryThrottleStore}, which is per process -
+     * so two replicas each allow the full budget until this names a shared one.
+     */
+    readonly store?: ThrottleStore;
+}
+/**
+ * A class, not an interface, so it is a runtime value and can be a constructor
+ * parameter type the transform records - the same reason `StaticOptions` is one.
+ */
+export declare class ThrottleOptions {
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly prefix: string;
+    readonly headers: boolean;
+    readonly subject: ((req: BunRequest, ctx: RouteContext) => string | undefined) | undefined;
+    readonly store: ThrottleStore | undefined;
+    constructor(init: ThrottleOptionsInit);
+}

package/dist/throttle/store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The counter behind the guard.
+ *
+ * An `abstract class` rather than an interface: `@dunx/transform` records
+ * constructor parameter *types*, so an interface at an injection site is a boot
+ * error. Same reason `RedisConnection` and `Logger` are classes.
+ *
+ * **A fixed window, not a sliding one.** `hit` increments and returns the count for
+ * the window the key is already in; the window starts at the first hit and ends
+ * when the key expires. A sliding window needs a sorted set per subject and a
+ * range trim per request, which is a different cost for an accuracy a rate limit
+ * does not need.
+ */
+export declare abstract class ThrottleStore {
+    constructor();
+    /**
+     * The count for this key in the current window.
+     *
+     * **`undefined` means the store could not be reached**, and the guard reads that
+     * as "allow". A rate limiter that turns an unreachable Redis into a 503 has
+     * turned a degraded route into an outage.
+     */
+    abstract hit(key: string, windowSeconds: number): Promise<number | undefined>;
+    /** Seconds left in this key's window, for `Retry-After`. */
+    abstract ttl(key: string): Promise<number | undefined>;
+}
+/**
+ * The commands the Redis store needs, restated structurally so this package keeps
+ * its zero dependencies - the same trick `PubSubRelay` uses.
+ *
+ * `@dunx/infra`'s `RedisConnection` satisfies it, and so does a bare
+ * `Bun.RedisClient`, without either being named here.
+ */
+export interface ThrottleRedis {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+    ttl(key: string): Promise<number>;
+}
+/**
+ * The multi-process counter: one key per subject and handler.
+ *
+ * `INCR` then `EXPIRE`, and the `EXPIRE` **only on the call that returned 1**. That
+ * is what makes the window start at the first hit rather than being pushed forward
+ * by every subsequent one, and it is two round trips rather than a Lua script
+ * because `Bun.RedisClient` pipelines on its own.
+ */
+export declare class RedisThrottleStore extends ThrottleStore {
+    private readonly redis;
+    constructor(redis: ThrottleRedis);
+    hit(key: string, windowSeconds: number): Promise<number | undefined>;
+    ttl(key: string): Promise<number | undefined>;
+}
+/**
+ * The single-process counter, and the default - so an app with no Redis still
+ * limits something rather than nothing.
+ *
+ * It is per process, which is the whole caveat: two replicas each allow the full
+ * budget. `RedisThrottleStore` is the answer for more than one.
+ *
+ * The map is bounded. An expired entry is dropped when its key is next touched,
+ * and once the map passes `maxKeys` every expired entry is swept - so a burst
+ * across many subjects cannot grow it without limit. Reaching the cap with nothing
+ * expired clears it, which resets a window early rather than holding memory a
+ * server does not have.
+ */
+export declare class MemoryThrottleStore extends ThrottleStore {
+    #private;
+    constructor(maxKeys?: number);
+    hit(key: string, windowSeconds: number): Promise<number | undefined>;
+    ttl(key: string): Promise<number | undefined>;
+}

package/dist/ws/adapter.d.ts

@@ -1,5 +1,6 @@
 import type { BunRequest, Server, WebSocketHandler } from 'bun';
 import type { DiscoveredGateway } from './discover.js';
+import { type SocketMiddleware } from './middleware.js';
 import type { SocketData, SocketOptions } from './socket.js';
 /**
  * A gateway's entry in the server's route table. Returning `undefined` is how Bun
@@ -24,6 +25,11 @@ export interface WebSocketRuntime {
      * "Consuming N job(s)" entry already set.
      */
     readonly gateways: readonly GatewaySummary[];
+    /**
+     * What `HttpFactory.create` logs at boot, the way the container logs its own
+     * scope warnings. Empty for a server that reports socket errors, or says it does.
+     */
+    readonly warnings: readonly string[];
 }
 export interface GatewaySummary {
     readonly name: string;
@@ -31,4 +37,4 @@ export interface GatewaySummary {
     /** `@OnMessage('name')` events. A raw catch-all has no name to report. */
     readonly events: readonly string[];
 }
-export declare const buildWebSocket: (discovered: readonly DiscoveredGateway[], options?: SocketOptions) => WebSocketRuntime;
+export declare const buildWebSocket: (discovered: readonly DiscoveredGateway[], options?: SocketOptions, middleware?: readonly SocketMiddleware[]) => WebSocketRuntime;

package/dist/ws/logging.d.ts

@@ -0,0 +1,69 @@
+import { Logger, LogLevel, RequestContext } from '@dunx/core';
+import { type SocketContext, type SocketFrame, type SocketMiddleware, type SocketNext } from './middleware.js';
+export interface SocketLoggingOptions {
+    /**
+     * The level every message frame is logged at. Default **`'debug'`**.
+     *
+     * `'debug'`, not `'info'`, because a socket is not a request: a gateway can take
+     * a frame per player per tick, and one `info` line each would bury everything
+     * else the process writes. The default `ConsoleLogger` threshold is `'info'`, so
+     * this is off until an app lowers its level or names a louder one here.
+     */
+    readonly level?: LogLevel;
+    /** What a throwing or rejecting handler is logged at. @default 'error' */
+    readonly errorLevel?: LogLevel;
+    /**
+     * Per-event level, keyed by the `@OnMessage(event)` name. `false` skips the
+     * event entirely, and skipping is complete: no entry, no timing, no scope.
+     *
+     * ```ts
+     * socketLogging: { events: { placeBet: 'info', cursorMove: false } }
+     * ```
+     */
+    readonly events?: Readonly<Record<string, LogLevel | false>>;
+    /**
+     * Open, close, drain, ping and pong. Defaults to `level`; `false` drops them.
+     *
+     * Separate from `level` because the two answer different questions - how much
+     * traffic a socket carries, against how many sockets there are - and an app that
+     * silences the first usually still wants the second.
+     */
+    readonly lifecycle?: LogLevel | false;
+    /**
+     * Log the frame's payload. Default **`false`**.
+     *
+     * A payload is caller-supplied and arrives without validation, so it is both the
+     * field most likely to carry a credential and the one most likely to be large.
+     */
+    readonly payload?: boolean;
+    /** Payloads past this many characters are logged as a size. @default 512 */
+    readonly maxPayloadLength?: number;
+    /**
+     * Wrap each dispatch in an `AsyncRequestContext` scope. Default **`true`**.
+     *
+     * The scope is what makes a line a service logs four frames down carry
+     * `connectionId` and `event` without being handed the socket.
+     */
+    readonly correlate?: boolean;
+}
+/**
+ * One structured entry per dispatched frame, carrying the frame and its outcome.
+ *
+ * The socket counterpart of `RequestLoggingMiddleware`, and the same single-entry
+ * shape: the middleware wraps the handler, so the frame and what it answered are
+ * one line rather than an inbound line to correlate with an outbound one.
+ *
+ * It also replaces what a gateway would otherwise hand-write. A throwing handler
+ * reaches the `Logger` here with the gateway, the path and the event on it -
+ * `SocketOptions.onError`'s default is a bare `console.error` off the logging
+ * pipeline entirely, and installing this takes that fallback out of the way.
+ */
+export declare class SocketLoggingMiddleware implements SocketMiddleware {
+    #private;
+    private readonly logger;
+    private readonly context;
+    /** A throwing handler reaches the `Logger` here, at `errorLevel`. */
+    readonly reportsErrors = true;
+    constructor(logger: Logger, context: RequestContext, options?: SocketLoggingOptions);
+    handle(frame: SocketFrame, ctx: SocketContext, next: SocketNext): unknown;
+}

package/dist/ws/middleware.d.ts

@@ -0,0 +1,95 @@
+import type { HandlerKind } from './marker.js';
+import type { Socket } from './socket.js';
+/**
+ * Which handler a frame is on its way to, resolved at boot.
+ *
+ * The websocket half of {@link RouteContext}: it names the gateway rather than the
+ * controller, and the envelope event rather than the method and path. One object
+ * per slot, built once, so a middleware costs no allocation per frame beyond the
+ * frame itself.
+ */
+export interface SocketContext {
+    /** The gateway class's name. */
+    readonly gateway: string;
+    /** The path it upgraded on, exactly as mounted. */
+    readonly path: string;
+    readonly kind: HandlerKind;
+    /**
+     * The `@OnMessage(event)` name. `undefined` for a lifecycle hook and for the raw
+     * `@OnMessage()` catch-all, which claims every frame no named handler took.
+     */
+    readonly event: string | undefined;
+}
+/**
+ * The frame itself: the socket it arrived on, and the argument the handler is
+ * about to be given.
+ *
+ * `data` is the envelope's `data` for a named message, the whole frame for the raw
+ * catch-all, `{ code, reason }` for a close, the buffer for a ping or a pong, and
+ * `undefined` for an open or a drain.
+ */
+export interface SocketFrame {
+    readonly socket: Socket;
+    readonly data: unknown;
+}
+/**
+ * Runs the rest of the chain and finally the gateway handler, returning whatever
+ * it returned - which for a named message is the value dunx sends back.
+ *
+ * It is **not** `Promise<unknown>`, unlike the HTTP `Next`. A gateway handler may
+ * be synchronous and the dispatcher does not allocate a promise to hide that, so a
+ * middleware that needs the outcome handles both channels. {@link observe} is that
+ * dance, written once.
+ */
+export type SocketNext = () => unknown;
+/**
+ * The single extension point on the socket side, shaped like {@link Middleware} on
+ * the HTTP side: one method, wrapping `next()`.
+ *
+ * It sees every dispatched handler - open, each named message, the catch-all,
+ * close, drain, ping and pong - and open and close arrive even for a gateway that
+ * declares no `@OnOpen`/`@OnClose`, so a connection is never invisible to it.
+ *
+ * A throwing or rejecting handler passes through here, which is where a guard
+ * refuses and where an observer records the failure. Rethrow to leave the outcome
+ * to `SocketOptions.onError`; return a value instead to answer the frame.
+ *
+ * Three things it cannot see, because they never reach the dispatcher: a
+ * `socket.send` a handler makes itself, a `PubSub` broadcast, and the upgrade -
+ * which is an HTTP request answered by the gateway's own route.
+ */
+export interface SocketMiddleware {
+    /**
+     * That a failure passing through here is reported somewhere. Default
+     * **`false`**.
+     *
+     * `SocketOptions.onError`'s `console.error` fallback is not installed while any
+     * socket middleware exists, because a middleware wraps the handler and would
+     * report the same failure a second time. Whether it does is something only the
+     * middleware knows: one that ignores a throw turns error reporting off for the
+     * whole server, and nothing about the wiring says so.
+     *
+     * Setting it is how a middleware says it does report. Leaving it unset with no
+     * `websocket.onError` beside it is what `HttpFactory.create` warns about at
+     * boot.
+     */
+    readonly reportsErrors?: boolean;
+    handle(frame: SocketFrame, ctx: SocketContext, next: SocketNext): unknown;
+}
+/** One slot's folded chain. The handler's own arguments ride in `run`. */
+export type SocketDispatch = (frame: SocketFrame, run: SocketNext) => unknown;
+/**
+ * Folded into one closure per slot at boot, the same shape `compose` gives an HTTP
+ * route - so dispatch stays a property read and a call, with no array iteration
+ * per frame.
+ */
+export declare const composeSocket: (middleware: readonly SocketMiddleware[], ctx: SocketContext) => SocketDispatch;
+/**
+ * Calls `next()` and reports how it went, on whichever channel it went out on,
+ * leaving the result untouched.
+ *
+ * `error` is `undefined` on success. A synchronous throw and a rejection both
+ * reach `done` and are then rethrown, so a middleware that only observes cannot
+ * accidentally swallow a failure.
+ */
+export declare const observe: (next: SocketNext, done: (error: unknown, value: unknown) => void) => unknown;

package/dist/ws/socket.d.ts

@@ -7,6 +7,12 @@ import type { ServerWebSocket, WebSocketHandler } from 'bun';
 export interface SocketData<T = unknown> {
     readonly path: string;
     readonly context: T;
+    /**
+     * This connection, for as long as it lasts. Minted at the upgrade, because Bun's
+     * socket carries no identity of its own and a log line for a frame is only
+     * joinable to the connect and the disconnect around it if something does.
+     */
+    readonly id: string;
 }
 /**
  * Bun's native socket, unwrapped. `send`, `subscribe`, `unsubscribe`,
@@ -23,6 +29,17 @@ export type SocketErrorHandler = (error: unknown, socket: Socket) => void;
  * anything above 960 at `Bun.serve` time.
  */
 export type SocketOptions = Readonly<Pick<WebSocketHandler<SocketData>, 'backpressureLimit' | 'closeOnBackpressureLimit' | 'idleTimeout' | 'maxPayloadLength' | 'perMessageDeflate' | 'publishToSelf' | 'sendPings'>> & {
-    /** Where a throwing or rejecting handler goes. @default console.error */
+    /**
+     * Where a throwing or rejecting handler goes. @default console.error
+     *
+     * The default is **not** installed when `socketMiddleware` is non-empty: a
+     * middleware wraps the handler, so it already saw the failure and a second
+     * report on the console would be a duplicate.
+     *
+     * Seeing a failure and reporting it are not the same thing, so a middleware that
+     * reports says so with `SocketMiddleware.reportsErrors`. Middleware that sets it
+     * nowhere, and no `onError` here, is a boot warning: the fallback is gone and
+     * nothing replaced it.
+     */
     readonly onError?: SocketErrorHandler;
 };

package/package.json

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