@dunx/http 3.1.3 → 3.2.1

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 {
   HIDDEN,
-  HandlerKind,
-  HiddenHealthController,
   PUBLIC,
   ROLES,
-  assertNoCollisions,
-  assertNoGatewayCollisions,
   buildContext,
-  buildGateways,
-  buildRoutes,
-  buildRuntime,
-  buildWebSocket,
-  compose,
-  composeSocket,
-  decode,
-  decodeRelay,
-  defaultRelayUrl,
   defaultStatusFor,
   discoverGateway,
-  discoverGateways,
   discoverRoutes,
-  encode,
-  encodeRelay,
-  guardsOf,
-  isCompressibleType,
-  isErrorFilter,
   isGateway,
-  joinPath,
-  negotiate,
-  normalizePath,
-  normalizePrefix,
-  observe,
-  preflight,
-  toErrorMapper,
-  withCors,
-  withUpgradeRoutes
-} from "./chunk-53cs6qek.js";
-import {
-  backoffDelay,
-  executeWithRetry,
-  isJsonBody,
-  isPlainObject,
-  isRetryableStatus,
-  retryAfterMs,
-  safeStringify
-} from "./chunk-7xrtwbx3.js";
+  joinPath
+} from "./chunk-3nbj06q8.js";
 import"./chunk-sz4pvqxy.js";
 // src/inspect.ts
 import {
+  classOf,
   collectModules,
   dependenciesOf,
+  inertInstance,
   readControllers
 } from "@dunx/core";
 var vendorOf = (schema) => schema?.["~standard"]?.vendor;
@@ -85,11 +51,10 @@ var nodeFor = (route, module) => ({
   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 discoverRoutes(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(isGateway).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,
+  embedJson,
   gatewaysOf,
-  guardsOf,
-  isCompressibleType,
-  isErrorFilter,
   isGateway,
-  isJsonBody,
-  isPlainObject,
-  isRetryableStatus,
   joinPath,
-  negotiate,
-  normalizePath,
-  normalizePrefix,
-  observe,
-  preflight,
-  retryAfterMs,
-  routesOf,
-  safeStringify,
-  toErrorMapper,
-  withCors,
-  withUpgradeRoutes
+  routesOf
 };

package/dist/server/application.d.ts

@@ -1,5 +1,5 @@
 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 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';
@@ -50,6 +50,14 @@ export interface HttpOptions extends AppOptions {
      * 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
@@ -112,7 +120,7 @@ export interface HttpApp extends App {
     readonly gatewayPaths: readonly string[];
     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[];
@@ -138,5 +146,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/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

@@ -0,0 +1,80 @@
+import { type HistogramSnapshot } from '@dunx/core';
+import type { BunRequest, Server } from 'bun';
+import type { RouteContext } from './context.js';
+import type { Middleware, Next } from './middleware.js';
+/** Every path Bun matched nothing for, collapsed into one series. */
+export declare const UNMATCHED_ROUTE = "(unmatched)";
+export interface RouteStats {
+    /** The route pattern, so `/users/1` and `/users/2` share one series. */
+    readonly route: string;
+    readonly method: string;
+    readonly count: number;
+    /** Keyed by status code as a string, because that is what JSON gives back. */
+    readonly byStatus: Readonly<Record<string, number>>;
+    /** Nanoseconds. */
+    readonly duration: HistogramSnapshot;
+    /**
+     * The trace of the slowest request on this route so far, which is the only
+     * question a p99 provokes: which request was it, and where are its logs.
+     */
+    readonly slowestTraceId?: string;
+}
+export interface HttpStatsReport {
+    readonly routes: readonly RouteStats[];
+    /** Read off `Bun.serve` at 14.7 ns rather than counted, so dunx counts nothing. */
+    readonly inFlight: number;
+    readonly pendingWebSockets: number;
+    /** When the counters were last reset, or boot. */
+    readonly since: string;
+}
+/**
+ * One series per route, keyed on the frozen `RouteContext` that `buildContext`
+ * makes once at boot. That object identity is the label set: a `Map` lookup on it
+ * is 8.8 ns, where building `${method} ${path}` and hashing it is 206.6 ns.
+ *
+ * Series count is bounded by the handler count, because `ctx.path` is the route
+ * pattern rather than the request's path.
+ *
+ * Bound by `HttpFactory`'s global wrapper, like `PubSub` and `ClientAddress`: an
+ * unbound class self-binds into whichever scope asks first, so a second consumer
+ * would be a boot error.
+ *
+ * `observe` takes everything as parameters and reads no ambient store, which is
+ * what keeps it at 35.2 ns folded into the `.then` request logging already
+ * allocates.
+ */
+export declare class RequestMetrics {
+    #private;
+    observe(ctx: RouteContext, status: number, durationNs: number, traceId?: string): void;
+    snapshot(): HttpStatsReport;
+    /**
+     * Drops every series rather than zeroing them, so a route that stopped being
+     * called stops being reported. A cumulative histogram over a week has a p99
+     * 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;
+}
+/**
+ * Whether `MetricsMiddleware` is the thing doing the observing.
+ *
+ * With request logging on - the default - `RequestLoggingMiddleware` observes
+ * from the `.then` it already allocates and this middleware would double-count.
+ * Exported because `HttpFactory` binds it and `HttpApplication` installs it, and
+ * the two disagreeing would mean either no metrics or twice as many.
+ */
+export declare const usesMetricsMiddleware: (options: {
+    readonly metrics?: boolean;
+    readonly requestLogging?: unknown;
+}) => boolean;
+/**
+ * Installed by `HttpFactory` only when `requestLogging: false`. With logging on -
+ * the default - `RequestLoggingMiddleware` calls `observe` from the `.then` it
+ * already allocates, at 35.2 ns against this middleware's 175.9 ns standalone.
+ */
+export declare class MetricsMiddleware implements Middleware {
+    private readonly metrics;
+    constructor(metrics: RequestMetrics);
+    handle(_req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
+}

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

@@ -75,6 +75,8 @@ export declare abstract class HttpOptionsProvider {
     /** `false` removes the middleware from the chain; an object tunes it. */
     get requestLogging(): boolean | RequestLoggingOptions;
     get socketLogging(): boolean | SocketLoggingOptions;
+    /** Per-route counts and timings. Off by default; see {@link RequestMetrics}. */
+    get metrics(): boolean;
     /**
      * Replaces the default mapper. Prefer an `ErrorFilter` class over a bare
      * function: a class is resolved from the container and can inject.

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

@@ -2,6 +2,7 @@ import { Logger, RequestContext } from '@dunx/core';
 import type { BunRequest } from 'bun';
 import type { RouteContext } from './context.js';
 import type { Middleware, Next } from './middleware.js';
+import type { RequestMetrics } from './metrics.js';
 export interface RequestLoggingOptions {
     /** Bodies past this many characters are logged as a size. Default 2048. `0` omits them. */
     readonly maxBodyLength?: number;
@@ -17,7 +18,7 @@ export interface RequestLoggingOptions {
      * materialised string by the time this clones it. */
     readonly responseBody?: boolean;
     /**
-     * Paths to skip entirely: no entry, no `x-request-id`, and no
+     * Paths to skip entirely: no entry, no trace, no `traceresponse`, and no
      * `AsyncLocalStorage` scope, so anything the handler logs is uncorrelated.
      * `correlateIgnored` buys the correlation back.
      */
@@ -33,24 +34,37 @@ export interface RequestLoggingOptions {
      */
     readonly ignorePrefix?: readonly string[];
     /**
-     * Keep the request id and the async scope on an `ignore`d path. Default
-     * `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.
+     * Keep the trace and the async scope on an `ignore`d path. Default `false`.
+     * The path still writes no entry; it gets a `traceresponse` and everything the
+     * handler logs carries the trace. 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`, +0.91 us.
-     * It is what lets a service four frames down log `requestId` without being
+     * It is what lets a service four frames down log `traceId` 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.
+     * unchanged, but every other line the request writes loses its trace.
      */
     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.
+     * Put `traceresponse` on the response. Default `true`, and ~500 ns of the 4.7 us
+     * the path costs, which is the largest thing here that can go without losing a
+     * field from a line.
+     *
+     * `false` keeps the trace on this middleware's own lines, in the async scope and
+     * on the metrics exemplar, and withholds the header from every response
+     * including a failure's: the error mapper stamps from what `TraceContext.adopt`
+     * marked, and this stops it marking.
+     */
+    readonly traceResponse?: boolean;
+    /**
+     * Adopt W3C Trace Context, putting `traceId`, `spanId`, `parentSpanId` and
+     * `traceFlags` on every line the request writes and `traceresponse` on its
+     * response. Default `true`, at 49.2 ns to mint both ids plus one header read.
+     * `@dunx/http/client` sends the adopted trace upstream.
+     *
+     * `false` removes it, and a request then carries no correlation id at all.
      */
     readonly trace?: boolean;
 }
@@ -70,6 +84,6 @@ export declare class RequestLoggingMiddleware implements Middleware {
     #private;
     private readonly logger;
     private readonly context;
-    constructor(logger: Logger, context: RequestContext, options?: RequestLoggingOptions);
+    constructor(logger: Logger, context: RequestContext, options?: RequestLoggingOptions, metrics?: RequestMetrics);
     handle(req: BunRequest, ctx: RouteContext, next: Next): Promise<Response>;
 }

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

@@ -1,5 +1,17 @@
 export declare const TRACEPARENT_HEADER = "traceparent";
 export declare const TRACESTATE_HEADER = "tracestate";
+/**
+ * The span that answered, sent back so a caller can record which of the callee's
+ * spans its own span points at. Same four fields as `traceparent`, and the
+ * the one correlation id a response carries.
+ *
+ * A W3C Distributed Tracing Working Group proposal rather than a ratified
+ * standard: `traceparent` and `tracestate` are the Recommendation, and the
+ * published Trace Context Level 2 Candidate Recommendation Draft covers those two
+ * request headers and not this response one. The format is specified and stable,
+ * and adoption is thin, so treat a caller reading it as a bonus.
+ */
+export declare const TRACERESPONSE_HEADER = "traceresponse";
 export interface Trace {
     /** 32 hex digits, shared by every span in the trace. */
     readonly traceId: string;
@@ -15,14 +27,18 @@ export interface Trace {
 /**
  * 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.
+ * The whole of it is one header parsed and two written. There is no exporter, no
+ * sampler and no dependency: every log line a request writes carries the same
+ * `traceId` the service upstream logged, so the two join without either of them
+ * running a collector.
+ *
+ * `traceId`, `spanId` and `parentSpanId` are the OpenTelemetry log data model's
+ * own fields, so a collector that ingests these lines correlates them with spans
+ * emitted by anything else speaking the standard. Bun 1.4.0 runs OpenTelemetry's
+ * Node instrumentation, and a trace adopted here is the trace those spans join.
  *
- * `@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.
+ * On by default. `requestLogging: { trace: false }` removes it, at which point a
+ * request carries no correlation id at all.
  */
 export declare class TraceContext {
     #private;
@@ -32,10 +48,15 @@ export declare class TraceContext {
      * 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.
+     * A trace that arrived is continued with a span of this server's own, and the
+     * caller's sampling decision is kept rather than overridden.
+     *
+     * `expose: false` adopts the trace without marking it for {@link stamp}, so no
+     * `traceresponse` is written - by this middleware or by the error mapper, which
+     * builds its own `Response` from what was recorded here. Everything inward is
+     * unchanged: the scope, the log lines, the metrics exemplar.
      */
-    static adopt(req: Request, requestId: string): Trace;
+    static adopt(req: Request, expose?: boolean): Trace;
     /** The trace adopted for this request, if one was. */
     static of(req: Request): Trace | undefined;
     /**
@@ -43,5 +64,15 @@ export declare class TraceContext {
      * parent, so the two link without inventing a span nothing logged.
      */
     static header(trace: Pick<Trace, 'traceId' | 'spanId' | 'flags'>): string;
+    /**
+     * The response, carrying `traceresponse` if this request adopted a trace.
+     *
+     * 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 would go out
+     * bare. Read back from the request rather than threaded through the mapper,
+     * which an app writes its own of.
+     */
+    static stamp(response: Response, req: Request): Response;
     static sampled(trace: Pick<Trace, 'flags'>): boolean;
 }

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;

package/dist/ws/relay.d.ts

@@ -27,6 +27,14 @@ export interface PubSubRelay {
      */
     close?(): unknown;
 }
+/**
+ * Both relays take a URL, and a wrong scheme has to fail here rather than at
+ * connect time: an absence-tolerant relay swallows the connection error, so a
+ * typo would degrade silently to single-node fan-out.
+ */
+export declare const assertRelayUrl: (url: string, protocols: readonly string[], example: string) => string;
+/** The URL with any password removed, for logs and error messages. */
+export declare const redactUrl: (url: string) => string;
 /** Which relay call failed, so one message can say what degraded. */
 export type RelayPhase = 'publish' | 'subscribe' | 'close';
 export interface RelayOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "3.1.3",
+  "version": "3.2.1",
   "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
   "keywords": [
     "bun",
@@ -56,13 +56,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@arkv/shared": "^0.8.0"
+    "@arkv/shared": "0.8.0"
   },
   "devDependencies": {
-    "@dunx/core": "workspace:*"
+    "@dunx/core": "workspace:*",
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/core": "2.11.0",
+    "@opentelemetry/sdk-trace-node": "2.11.0"
   },
   "peerDependencies": {
-    "@dunx/core": "^3.1.3",
+    "@dunx/core": "^3.2.1",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {