@dunx/http 2.4.0 → 3.0.0

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

@@ -2,18 +2,13 @@ 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.
+ * The logging middleware sets the header on a response it returns, and a failure
+ * is never one - the error mapper builds a fresh `Response` outside the chain. So
+ * a guard's 401, a validation 400 and every unmatched 404 went out with no id.
  *
- * 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.
+ * Recorded against the request rather than threaded through the mapper, which an
+ * app writes its own of. {@link stamp} reads back what {@link assign} recorded, so
+ * a path nothing minted an id for is still answered without a header.
  */
 export declare class RequestIds {
     /**

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

@@ -6,57 +6,26 @@ export interface RequestLoggingOptions {
     /** Bodies past this many characters are logged as a size. Default 2048. `0` omits them. */
     readonly maxBodyLength?: number;
     /**
-     * Log the request body. Default **`false`**.
+     * Log the request body. Default `false`, and the cost depends on whether the
+     * route declares a `body` schema: +1.9 us when it does, +28.8 us when it does
+     * not, because the logger has to `req.clone()` an unread network stream.
      *
-     * **What it costs depends on whether the route declares a `body` schema**, and by
-     * a factor of fifteen. `bun run logging:bodies` in `internal/bench`, round-robin
-     * over 3 runs against `POST /validate`:
-     *
-     * | setting                                  | us/req | vs the default |
-     * | ---------------------------------------- | -----: | -------------: |
-     * | `requestLogging: false`                  |  12.80 |      -4.45 us |
-     * | the shipped default, both bodies off     |  17.25 |              - |
-     * | **`requestBody: true`, schema route**    | **19.12** |  **+1.87 us** |
-     * | `responseBody: true`                     |  19.80 |      +2.55 us |
-     * | both bodies, schema route                |  20.03 |      +2.78 us |
-     * | **`requestBody: true`, no schema**       | **46.06** | **+28.81 us** |
-     *
-     * A route with a schema has already had its body buffered by the input reader, so
-     * the logger reads that text and nothing is cloned. A route without one leaves the
-     * logger to `req.clone()`, and cloning a request whose body is an unread network
-     * stream is the entire cost - not the second `JSON.parse`, which is 0.32 us.
-     * `raw-body.ts` has that decomposition.
-     *
-     * It is the field most likely to contain a password. Turn it on in development,
-     * where seeing the payload is the point.
+     * It is the field most likely to contain a password.
      */
     readonly requestBody?: boolean;
-    /**
-     * Log the response body. Default **`false`**, +2.55 us - see the table above.
-     *
-     * No equivalent trick here and none needed: a response is already a materialised
-     * string by the time this clones it, which is why it was never the expensive half.
-     */
+    /** Log the response body. Default `false`, +2.6 us. A response is already a
+     * materialised string by the time this clones it. */
     readonly responseBody?: boolean;
     /**
-     * Paths to skip entirely - a health check polled every second, say.
-     *
-     * **Entirely** is literal: no entry, no `x-request-id` on the response, and no
-     * `AsyncLocalStorage` scope, so anything the handler logs is uncorrelated. That
-     * is what makes it free. `correlateIgnored` buys the correlation back.
+     * Paths to skip entirely: no entry, no `x-request-id`, and no
+     * `AsyncLocalStorage` scope, so anything the handler logs is uncorrelated.
+     * `correlateIgnored` buys the correlation back.
      */
     readonly ignore?: readonly string[];
     /**
-     * Path **prefixes** to skip, for a whole mount rather than one path.
-     *
-     * `ignore` is an exact-match `Set` because that is one lookup on the hot path
-     * and a health check is one path. A mount is not: `@dunx/dashboard` at
-     * `/_dunx` polls four endpoints every five seconds and bull-board pulls a
-     * dozen assets, and listing them is both tedious and wrong the moment either
-     * grows an endpoint.
-     *
-     * Scanned only when non-empty, so an app that sets none pays nothing - the
-     * same guard `ignore` has. Keep the list short; it is a loop.
+     * Path prefixes to skip, for a whole mount rather than one path. `ignore` is an
+     * exact-match `Set`; this is a loop, so keep the list short. Scanned only when
+     * non-empty.
      *
      * ```ts
      * requestLogging: { ignorePrefix: ['/_dunx'] }
@@ -65,64 +34,37 @@ export interface RequestLoggingOptions {
     readonly ignorePrefix?: readonly string[];
     /**
      * Keep the request id and the async scope on an `ignore`d path. Default
-     * **`false`**.
-     *
-     * "Do not log the health check, but do keep its request id" is this. The path
-     * still writes no entry of its own; it gets an id - inbound or minted - on the
-     * response, and everything the handler logs carries it.
-     *
-     * It is not the default because it is not free: the ignored path pays for
-     * reading the header, `crypto.randomUUID()`, the `runWithContext` scope and the
-     * response header. On the `bun run logging` decomposition those four rows are
-     * ~2.2 µs, against ~5.4 µs for the whole default path - so it costs the half
-     * that buys correlation and not the half that builds and serialises the entry.
+     * `false`. The path still writes no entry; it gets an id on the response and
+     * everything the handler logs carries it. Costs ~2.2 us of the ~5.4 us the
+     * default path spends.
      */
     readonly correlateIgnored?: boolean;
     /**
-     * Wrap every request in an `AsyncLocalStorage` scope. Default **`true`**.
-     *
-     * The scope is what lets a service logging four frames down come out carrying
-     * `requestId` without being handed a request object. It is measured: the
-     * `runWithContext` row of `bun run logging` is **+0.91 µs**, 17% of the 5.38 µs
-     * request logging costs over `requestLogging: false`.
-     *
-     * `correlate: false` skips it. **The request entry is unchanged** - the same
-     * `requestId`, `method`, `event`, `flow` and `context` fields are written onto
-     * it directly instead of being read back out of the store. What is lost is
-     * everything *else* the request logs: those lines carry no `requestId`, and
-     * `updateContext` from a handler has nothing to update.
-     *
-     * Worth it for an app whose handlers never log, or one that passes correlation
-     * explicitly. Leave it on otherwise; correlation is most of what a request id
-     * is for.
+     * Wrap every request in an `AsyncLocalStorage` scope. Default `true`, +0.91 us.
+     * It is what lets a service four frames down log `requestId` without being
+     * handed a request. `correlate: false` skips it; this middleware's own entry is
+     * unchanged, but every other line the request writes loses its id.
      */
     readonly correlate?: boolean;
+    /**
+     * Adopt W3C Trace Context, so `traceId`, `spanId` and `parentSpanId` join
+     * `requestId`. Default `false`: it costs a header read and 8 random bytes, and
+     * `requestId` already spans two dunx services. `@dunx/http/client` sends the
+     * adopted trace upstream.
+     */
+    readonly trace?: boolean;
 }
 /**
  * One structured entry per request, carrying the request and its response.
+ * Installed by `HttpFactory.create` unless `requestLogging: false`, and injecting
+ * only core contracts, so it works with no logging module imported.
  *
- * Installed by `HttpFactory.create` unless `requestLogging: false`. It injects
- * `Logger` and `RequestContext` - both `@dunx/core` contracts, both bound by
- * default - so it works with no logging module imported, and picks up
- * `@arkv/logger` automatically once `@dunx/infra/logger` is.
- *
- * **One entry, not two.** A framework whose middleware cannot see the response
- * needs a middleware for the inbound half and an
- * interceptor for the outbound one, because they are different classes and the
- * interceptor cannot see what the middleware saw. Here they are the same
- * closure, so there is no pair to correlate by `requestId` to find out how a
- * call ended. A 4xx is the same line at `warn`, a 5xx at `error`.
- *
- * Everything the handler logs in between carries `requestId`, `method`, `event`
- * and `context` without being passed anything, because the whole call runs
- * inside `runWithContext` - unless `correlate: false`, which drops the scope and
- * with it that guarantee, but not the fields on this middleware's own entry.
+ * One entry rather than a middleware and an interceptor to correlate: middleware
+ * wraps `next()`, so both halves are the same closure. A 4xx logs at `warn`, a
+ * 5xx at `error`.
  *
- * **Nothing here is `async`.** Reading the request or the response body are the
- * only steps that can ever wait, both are off by default, and both are adopted
- * with `.then` rather than awaited - the same rule `input.ts` follows, for the
- * same measured reason. An `async` scope callback alone cost 0.44 µs/request
- * against a synchronous one on raw `Bun.serve`.
+ * Nothing here is `async`. The two steps that can wait are off by default and
+ * adopted with `.then`; an `async` scope callback alone cost 0.44 us/request.
  */
 export declare class RequestLoggingMiddleware implements Middleware {
     #private;

package/dist/server/routes.d.ts

@@ -1,6 +1,6 @@
 import { type Ctor, type ModuleRef } from '@dunx/core';
 import type { DiscoveredRoute } from '../route/discover.js';
-import type { HttpMethod } from '../route/marker.js';
+import { type HttpMethod } from '../route/marker.js';
 import type { UpgradeHandler } from '../ws/adapter.js';
 import { type CorsOptions } from './cors.js';
 import { type ErrorMapper } from './errors.js';
@@ -39,19 +39,12 @@ export declare const assertNoGatewayCollisions: (discovered: readonly Discovered
  */
 export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMap<string, UpgradeHandler>) => ServeRoutes;
 /**
- * Bun answers an unmatched path itself, so nothing in the middleware chain ever
- * sees it - which makes a 404 invisible to request logging, metrics and tracing.
+ * Bun answers an unmatched path itself, so nothing in the middleware chain sees
+ * it and a 404 is invisible to request logging. This is the only `fetch` handler
+ * dunx installs and it is not a router: it runs once Bun has matched nothing.
  *
- * This is the only `fetch` handler dunx installs, and it is not a router: Bun
- * still does all the matching, and this runs only once Bun has decided nothing
- * 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:
+ * The miss is a throw, not a returned `Response`, so a middleware reading
+ * `(await next()).status` never sees one and has to catch:
  *
  * ```ts
  * try {
@@ -62,13 +55,8 @@ export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMa
  * }
  * ```
  *
- * `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.
+ * `ctx.get(UNMATCHED)` is the cheaper half: set here and by no real route, so a
+ * middleware can tell a miss from a handler's own 404 before calling `next()`.
  */
 export declare const buildFallback: (middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, notFound?: 'guarded' | 'public') => RouteHandler;
 export declare const buildRoutes: (discovered: readonly DiscoveredRoute[], middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, resolve?: GuardResolver) => BunRoutes;

package/dist/server/trace-context.d.ts

@@ -0,0 +1,47 @@
+export declare const TRACEPARENT_HEADER = "traceparent";
+export declare const TRACESTATE_HEADER = "tracestate";
+export interface Trace {
+    /** 32 hex digits, shared by every span in the trace. */
+    readonly traceId: string;
+    /** 16 hex digits identifying this server's work on this request. */
+    readonly spanId: string;
+    /** The caller's span, when one arrived in `traceparent`. */
+    readonly parentSpanId?: string;
+    /** Two hex digits. Bit 0 is `sampled`. */
+    readonly flags: string;
+    /** `tracestate` verbatim, when one arrived. Vendor data this server does not read. */
+    readonly state?: string;
+}
+/**
+ * W3C Trace Context, propagated across services.
+ *
+ * The whole of it is one header parsed and one header written. There is no
+ * exporter, no sampler and no dependency: what this buys is that every log line a
+ * request writes carries the same `traceId` the service upstream logged, so the
+ * two can be joined without either of them running a collector.
+ *
+ * `@dunx/http` does not turn this on by itself - `requestLogging: { trace: true }`
+ * does. Adopting a trace costs a header read and 8 random bytes on every request,
+ * which is not worth spending in a service that has nothing to correlate with.
+ */
+export declare class TraceContext {
+    #private;
+    /**
+     * The inbound `traceparent`, or a fresh trace. A malformed header is discarded
+     * rather than repaired, as the standard requires. Version `ff` is invalid; a
+     * higher version keeps its first four fields, so a future format still
+     * propagates.
+     *
+     * With nothing inbound, `traceId` is the request id minus its hyphens - a UUID
+     * is 16 bytes, exactly a trace id, so there is no second `crypto` call.
+     */
+    static adopt(req: Request, requestId: string): Trace;
+    /** The trace adopted for this request, if one was. */
+    static of(req: Request): Trace | undefined;
+    /**
+     * The `traceparent` to send upstream. This server's span becomes the callee's
+     * parent, so the two link without inventing a span nothing logged.
+     */
+    static header(trace: Pick<Trace, 'traceId' | 'spanId' | 'flags'>): string;
+    static sampled(trace: Pick<Trace, 'flags'>): boolean;
+}

package/dist/static/files.d.ts

@@ -3,20 +3,12 @@ import type { Middleware, Next } from '../server/middleware.js';
 import type { RouteContext } from '../server/context.js';
 import { StaticOptions } from './options.js';
 /**
- * Static files, on `Bun.file`.
+ * Static files, on `Bun.file`. A `Bun.file` handed to a `Response` already
+ * streams, sets `content-type`, answers a `Range` request and uses `sendfile(2)`,
+ * so this file is a path check and a cache policy.
  *
- * Nest has `ServeStaticModule` over `serve-static`, which is Express middleware
- * doing its own `stat`, its own range parsing, its own ETag and its own MIME table.
- * None of that is needed here: `Bun.file(path)` handed to a `Response` already
- * streams, already sets `content-type` from the extension, already answers a
- * `Range` request, and does the whole thing with `sendfile(2)` rather than reading
- * into JavaScript. So this file is a **path check and a cache policy**, and that is
- * the entire justification for it existing.
- *
- * A middleware rather than routes, for the same reason the dashboard is one: the
- * file set is whatever is on disk at request time, and turning it into a
- * `Bun.serve` route table would mean walking a directory at boot and being wrong
- * the moment anything changed.
+ * A middleware rather than routes: the file set is whatever is on disk at request
+ * time, and a route table would be walked at boot and wrong thereafter.
  */
 export declare class StaticFiles implements Middleware {
     #private;

package/dist/static/module.d.ts

@@ -1,26 +1,21 @@
 import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
 import { type StaticOptionsInit } from './options.js';
 /**
- * Serves a directory, the way Nest's `ServeStaticModule` does - and like the
- * dashboard, **it does not register itself**. The app does:
+ * Serves a directory. Like the dashboard, it does not register itself:
  *
  * ```ts
  * const app = await HttpFactory.create(AppModule);
  * app.use(StaticFiles);
  * ```
  *
- * Position in the chain is the decision being left to the app. Static assets
- * usually want to be *outside* an auth guard and *inside* request logging, and no
- * default can know which. Anything outside the mount falls through untouched, so
- * the app's own routes and its 404 behave exactly as before.
+ * Position in the chain is left to the app - assets usually want to be outside an
+ * auth guard and inside request logging. Anything outside the mount falls through
+ * untouched.
  *
- * 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:
+ * There is no `index.html` fallback and no SPA rewrite, which 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, reading `ctx.get(UNMATCHED)`
+ * rather than a returned status, since a miss is thrown:
  *
  * ```ts
  * export class SpaFallback implements Middleware {
@@ -45,12 +40,8 @@ import { type StaticOptionsInit } from './options.js';
  * }
  * ```
  *
- * 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.
+ * `notFound: 'guarded'`, the default, reports a miss with no route metadata, so a
+ * session guard refuses it with a 401; a SPA wants `notFound: 'public'`.
  */
 export declare class StaticModule {
     static forRoot(init: StaticOptionsInit): DynamicModule;

package/dist/throttle/guard.d.ts

@@ -8,17 +8,14 @@ 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.
+ * Fails open: an unreachable store allows the request and warns once per process,
+ * since refusing everything 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.
+ * List it after any session guard - only the guard ahead knows whether to limit by
+ * user id or by address, 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.
+ * The 429 is thrown, so it comes out in the app's own error shape.
  */
 export declare class ThrottleGuard implements Middleware {
     #private;

package/dist/throttle/module.d.ts

@@ -1,12 +1,11 @@
 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.
+ * 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.
+ * `global: true`: the guard is listed in `HttpOptions.middleware`, the app's own
+ * list, so a non-global module would make every consumer import this one to reach
+ * a guard it never names.
  *
  * ```ts
  * ThrottleModule.forRootAsync({
@@ -22,9 +21,8 @@ import { type ThrottleOptionsInit } from './options.js';
  * 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.
+ * Position in the chain is the app's: ahead of a session guard, the limit counts
+ * every caller as an address.
  */
 export declare class ThrottleModule {
     static forRoot(init: ThrottleOptionsInit): DynamicModule;

package/dist/throttle/store.d.ts

@@ -1,15 +1,10 @@
 /**
- * The counter behind the guard.
+ * The counter behind the guard. An `abstract class` rather than an interface,
+ * since an interface at an injection site is a boot error.
  *
- * 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.
+ * A fixed window: `hit` returns the count for the window the key is already in,
+ * which starts at the first hit and ends when the key expires. A sliding window
+ * needs a sorted set per subject and a trim per request.
  */
 export declare abstract class ThrottleStore {
     constructor();
@@ -51,17 +46,13 @@ export declare class RedisThrottleStore extends ThrottleStore {
     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 single-process counter and the default, so an app with no Redis still limits
+ * something. Per process is the caveat: two replicas each allow the full budget,
+ * and `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.
+ * The map is bounded. Expired entries are dropped on touch and swept past
+ * `maxKeys`; reaching the cap with nothing expired clears it, resetting a window
+ * early rather than holding memory.
  */
 export declare class MemoryThrottleStore extends ThrottleStore {
     #private;

package/dist/ws/middleware.d.ts

@@ -43,35 +43,26 @@ export interface SocketFrame {
  */
 export type SocketNext = () => unknown;
 /**
- * The single extension point on the socket side, shaped like {@link Middleware} on
- * the HTTP side: one method, wrapping `next()`.
+ * The socket side's single extension point, shaped like {@link Middleware}: one
+ * method wrapping `next()`. It sees every dispatched handler, and open and close
+ * arrive even for a gateway declaring neither.
  *
- * 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 handler passes through here. Rethrow to leave the outcome to
+ * `SocketOptions.onError`, or return a value to answer the frame.
  *
- * 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.
+ * It cannot see a `socket.send` a handler makes itself, a `PubSub` broadcast, or
+ * the upgrade, which is an HTTP request.
  */
 export interface SocketMiddleware {
     /**
-     * That a failure passing through here is reported somewhere. Default
-     * **`false`**.
+     * 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.
+     * socket middleware exists, since a middleware would report the same failure
+     * twice. Only the middleware knows whether it does, and one that ignores a throw
+     * would silently turn error reporting off for the whole server.
      *
-     * 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.
+     * Unset with no `websocket.onError` beside it is what `create` warns about.
      */
     readonly reportsErrors?: boolean;
     handle(frame: SocketFrame, ctx: SocketContext, next: SocketNext): unknown;

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

@@ -5,15 +5,10 @@ export interface RedisRelayOptions {
     /** @default `$VALKEY_URL`, `$REDIS_URL`, then `redis://localhost:6379` */
     readonly url?: string;
     /**
-     * Bun's reconnection budget.
-     *
-     * `0` by default, and that default is not a preference: a `Bun.RedisClient` that
-     * never connects keeps an internal retry timer alive past `close()`, and the
-     * process then never exits. A relay is exactly the connection most likely to be
-     * absent - a single-node deployment with `REDIS_URL` left over from staging -
-     * so the default has to be the one that lets the app boot, degrade, and still
-     * exit. Raise it when Redis is a hard requirement and you want Bun to reconnect
-     * for you.
+     * Bun's reconnection budget. `0` by default: a `Bun.RedisClient` that never
+     * connects keeps a retry timer alive past `close()`, so the process never exits,
+     * and a relay is the connection most likely to be absent. Raise it where Redis
+     * is a hard requirement.
      *
      * @default 0
      */
@@ -23,17 +18,12 @@ export interface RedisRelayOptions {
     readonly tls?: boolean | Bun.TLSOptions;
 }
 /**
- * A {@link PubSubRelay} on `Bun.RedisClient` - a Bun global, so this costs
- * `@dunx/http` no dependency at all.
- *
- * **Two connections, not one.** A client in subscriber mode rejects every data
- * command, and throws synchronously doing it, so the subscription cannot share the
- * socket that publishes. This is the same split the socket.io Redis adapter makes
- * with its `pubClient` / `subClient`.
+ * A {@link PubSubRelay} on `Bun.RedisClient`, a Bun global, so it costs
+ * `@dunx/http` no dependency.
  *
- * Both are opened lazily, on the first call that needs them, and a failed one is
- * discarded so the next call builds a fresh connection rather than reusing a dead
- * one.
+ * Two connections: a client in subscriber mode rejects every data command, so the
+ * subscription cannot share the publishing socket. Both open lazily, and a failed
+ * one is discarded rather than reused.
  */
 export declare class RedisRelay implements PubSubRelay {
     #private;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -40,6 +40,10 @@
     "./client": {
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "publishConfig": {
@@ -58,7 +62,7 @@
     "@dunx/core": "workspace:*"
   },
   "peerDependencies": {
-    "@dunx/core": "^2.4.0",
+    "@dunx/core": "^3.0.0",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {
@@ -67,6 +71,6 @@
     }
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   }
 }