@dunx/http 2.3.1 → 2.5.0

package/dist/{chunk-sz4pvqxy.js → chunk-jh7jk0bn.js}

@@ -105,7 +105,60 @@ var HttpStatusCode = Object.freeze({
   GATEWAY_TIMEOUT: 504
 });
 
-export { __privateGet, __privateAdd, __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, HttpStatusCode };
+// src/server/trace-context.ts
+var TRACEPARENT_HEADER = "traceparent";
+var TRACESTATE_HEADER = "tracestate";
+var HEX_32 = /^[0-9a-f]{32}$/;
+var HEX_16 = /^[0-9a-f]{16}$/;
+var HEX_2 = /^[0-9a-f]{2}$/;
+var ZERO_TRACE = "0".repeat(32);
+var ZERO_SPAN = "0".repeat(16);
+var SAMPLED = 1;
+var TRACE = Symbol.for("dunx.http.trace");
+var mintSpanId = () => Buffer.from(crypto.getRandomValues(new Uint8Array(8))).toString("hex");
 
-//# debugId=463DAE47FB741BC964756E2164756E21
-//# sourceMappingURL=chunk-sz4pvqxy.js.map
+class TraceContext {
+  static adopt(req, requestId) {
+    const inbound = TraceContext.#parse(req.headers.get(TRACEPARENT_HEADER));
+    const state = req.headers.get(TRACESTATE_HEADER);
+    const trace = {
+      traceId: inbound?.traceId ?? requestId.replaceAll("-", ""),
+      spanId: mintSpanId(),
+      ...inbound === undefined ? {} : { parentSpanId: inbound.spanId },
+      flags: inbound?.flags ?? "01",
+      ...inbound !== undefined && state !== null ? { state } : {}
+    };
+    req[TRACE] = trace;
+    return trace;
+  }
+  static of(req) {
+    return req[TRACE];
+  }
+  static header(trace) {
+    return `00-${trace.traceId}-${trace.spanId}-${trace.flags}`;
+  }
+  static sampled(trace) {
+    return (Number.parseInt(trace.flags, 16) & SAMPLED) === SAMPLED;
+  }
+  static #parse(header) {
+    if (header === null)
+      return;
+    const parts = header.split("-");
+    if (parts.length < 4)
+      return;
+    const [version, traceId, spanId, flags] = parts;
+    if (!HEX_2.test(version) || version === "ff")
+      return;
+    if (version === "00" && parts.length !== 4)
+      return;
+    if (!HEX_32.test(traceId) || traceId === ZERO_TRACE)
+      return;
+    if (!HEX_16.test(spanId) || spanId === ZERO_SPAN)
+      return;
+    if (!HEX_2.test(flags))
+      return;
+    return { traceId, spanId, flags };
+  }
+}
+
+export { __privateGet, __privateAdd, __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, HttpStatusCode, TRACEPARENT_HEADER, TRACESTATE_HEADER, TraceContext };

package/dist/client/options.d.ts

@@ -24,6 +24,17 @@ export interface HttpClientOptionsInit {
      * @default true
      */
     readonly propagateRequestId?: boolean | string;
+    /**
+     * Forward W3C Trace Context upstream as `traceparent`, so the callee's spans
+     * join this request's trace.
+     *
+     * Read from `RequestContext`, so it only carries when a trace is in scope -
+     * which means `requestLogging: { trace: true }` on the inbound side. With that
+     * off there is nothing to send and this costs one property read.
+     *
+     * @default true
+     */
+    readonly propagateTrace?: boolean;
     /** Bound as its own token, so a second client can be injected by name. */
     readonly name?: string;
     /**
@@ -51,6 +62,7 @@ export declare class HttpClientOptions {
     readonly headers: Readonly<Record<string, string>>;
     readonly retry: RetryOptions<unknown>;
     readonly requestIdHeader: string | undefined;
+    readonly propagateTrace: boolean;
     readonly name: string | undefined;
     readonly fetchOptions: Readonly<Record<string, unknown>>;
     constructor(init?: HttpClientOptionsInit);

package/dist/client.js

@@ -1,7 +1,9 @@
 // @bun
 import {
-  HttpStatusCode
-} from "./chunk-sz4pvqxy.js";
+  HttpStatusCode,
+  TRACEPARENT_HEADER,
+  TraceContext
+} from "./chunk-jh7jk0bn.js";
 
 // src/client/errors.ts
 import { AppError } from "@dunx/core";
@@ -75,6 +77,7 @@ class HttpClientOptions {
   headers;
   retry;
   requestIdHeader;
+  propagateTrace;
   name;
   fetchOptions;
   constructor(init = {}) {
@@ -83,6 +86,7 @@ class HttpClientOptions {
     this.headers = init.headers ?? {};
     this.retry = init.retry ?? {};
     this.name = init.name;
+    this.propagateTrace = init.propagateTrace ?? true;
     const propagate = init.propagateRequestId ?? true;
     this.requestIdHeader = propagate === false ? undefined : propagate === true ? DEFAULT_REQUEST_ID_HEADER : propagate;
     this.fetchOptions = Object.fromEntries([
@@ -328,11 +332,19 @@ class HttpService extends UrlHelper {
   }
   async send(config, url, body, serialised, accept = "application/json") {
     const requestId = this.options.requestIdHeader === undefined ? undefined : this.requestContext.getContext().requestId;
+    const trace = this.options.propagateTrace ? this.requestContext.getContext() : undefined;
     const headers = {
       accept,
       ...serialised === "" ? {} : { "content-type": "application/json" },
       ...this.options.headers,
       ...requestId === undefined || this.options.requestIdHeader === undefined ? {} : { [this.options.requestIdHeader]: requestId },
+      ...typeof trace?.traceId === "string" && typeof trace.spanId === "string" ? {
+        [TRACEPARENT_HEADER]: TraceContext.header({
+          traceId: trace.traceId,
+          spanId: trace.spanId,
+          flags: "01"
+        })
+      } : {},
       ...config.headerFactory?.({
         timestamp: Math.floor(Date.now() / 1000),
         method: config.method,
@@ -460,6 +472,3 @@ export {
   retryAfterMs,
   safeStringify
 };
-
-//# debugId=9448CCC7AF6FC82264756E2164756E21
-//# sourceMappingURL=client.js.map

package/dist/compression/compression.d.ts

@@ -0,0 +1,30 @@
+import type { BunRequest } from 'bun';
+import type { RouteContext } from '../server/context.js';
+import type { Middleware, Next } from '../server/middleware.js';
+import { CompressionOptions } from './options.js';
+/**
+ * Response compression, on Bun's own compressors.
+ *
+ * **Not installed by default, and registered by the app rather than by a module:**
+ *
+ * ```ts
+ * const app = await HttpFactory.create(AppModule, { imports: [CompressionModule.forRoot()] });
+ * app.use(Compression);
+ * ```
+ *
+ * An app that never registers it pays nothing - there is no branch in the request
+ * path to skip. Position is the app's decision for the same reason `StaticFiles`
+ * leaves it open: compression belongs inside request logging, so the logged status
+ * is the real one, and outside anything that wants to read the body it produced.
+ *
+ * Two encoders rather than one. A body whose `content-length` is known and under
+ * `BUFFER_LIMIT` goes through `Bun.zstdCompressSync`/`gzipSync`, which is faster
+ * than the stream and leaves an accurate `content-length` on the response; a
+ * streamed or oversized body goes through `CompressionStream` and loses the header,
+ * as it must.
+ */
+export declare class Compression implements Middleware {
+    #private;
+    constructor(options: CompressionOptions);
+    handle(req: BunRequest, _ctx: RouteContext, next: Next): Promise<Response>;
+}

package/dist/compression/module.d.ts

@@ -0,0 +1,20 @@
+import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
+import { type CompressionOptionsInit } from './options.js';
+/**
+ * Binds `Compression` and its options. Like `StaticModule`, importing it does not
+ * install anything - the app decides where in the chain it goes:
+ *
+ * ```ts
+ * const app = await HttpFactory.create(AppModule, {
+ *   imports: [CompressionModule.forRoot({ threshold: 2048 })],
+ * });
+ * app.use(Compression);
+ * ```
+ */
+export declare class CompressionModule {
+    static forRoot(init?: CompressionOptionsInit): DynamicModule;
+    /** `forRoot` with the options read off the container - a config value, usually. */
+    static forRootAsync<const D extends Deps>(config: FactoryProvider<CompressionOptionsInit, D> & {
+        readonly imports?: DynamicModule['imports'];
+    }): DynamicModule;
+}

package/dist/compression/negotiate.d.ts

@@ -0,0 +1,12 @@
+import type { CompressionEncoding } from './options.js';
+/**
+ * The coding to encode with, or `undefined` for none.
+ *
+ * `offered` is the server's preference order and breaks a tie, which is what
+ * makes `['zstd', 'gzip']` meaningful against a browser that sends both at the
+ * same q. An explicit `q=0` refuses a coding, `*` supplies a default for the ones
+ * not named, and an absent header means the client said nothing - answered with
+ * no encoding, because a client that cannot decode is worse than one that reads
+ * a few more bytes.
+ */
+export declare const negotiate: (header: string | null, offered: readonly CompressionEncoding[]) => CompressionEncoding | undefined;

package/dist/compression/options.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The content codings this package produces.
+ *
+ * **Brotli is absent, and that is a measurement rather than an oversight.** Bun
+ * implements it - `new CompressionStream('brotli')` works - but at 6,344 us to
+ * encode a 6.4 KB JSON body against gzip's 23 us and zstd's 24 us, roughly 275x.
+ * The `level` argument that would fix it is accepted and ignored: `{ level: 4 }`
+ * encodes in 6,345 us and produces the same 339 bytes as the default. Brotli
+ * belongs on a build artefact compressed once, not on a response encoded per
+ * request. Note also that the `CompressionStream` format is spelled `brotli`
+ * while the HTTP token is `br`, so the two never lined up anyway.
+ *
+ * **`deflate` is absent for a second and worse reason: Bun's two encoders disagree
+ * about what it means.** `Bun.deflateSync` emits raw DEFLATE (first bytes
+ * `cb 48`), while `CompressionStream('deflate')` emits zlib (`78 9c`), which is
+ * what `Content-Encoding: deflate` is defined as. No option reconciles them -
+ * `library`, `windowBits` and `level` all leave `deflateSync` raw - so offering
+ * the coding would flip wire format at the buffering threshold and serve bytes a
+ * strict client rejects. `gzip` is taken by everything that would have accepted
+ * `deflate`. Measured on Bun 1.4.0; see docs/bun-apis.md.
+ */
+export declare const CompressionEncoding: Readonly<{
+    readonly ZSTD: 'zstd';
+    readonly GZIP: 'gzip';
+}>;
+export type CompressionEncoding = (typeof CompressionEncoding)[keyof typeof CompressionEncoding];
+/**
+ * Whether a `content-type` is worth encoding.
+ *
+ * An already-compressed payload - a JPEG, an MP4, a zip - comes out of a second
+ * pass slightly larger, having spent the CPU to get there. The default answers
+ * no to anything it does not recognise, so a new binary type is skipped rather
+ * than wasted on.
+ */
+export declare const isCompressibleType: (contentType: string | null) => boolean;
+export interface CompressionOptionsInit {
+    /**
+     * The codings offered, most preferred first. A tie in the client's q-values is
+     * broken by this order, so it is a real preference and not just a filter.
+     *
+     * The default puts `zstd` first for speed. On a 6.4 KB JSON body zstd encodes to
+     * 372 bytes in 7.7 us where gzip takes 16.1 us to reach 576; on a 116 KB OpenAPI
+     * document the two land within 0.2% of each other (9,603 against 9,587), so the
+     * size advantage narrows with the body while the time one does not. A client
+     * that does not send `zstd` in `accept-encoding` gets gzip, so the order costs
+     * nothing to state.
+     *
+     * @default ['zstd', 'gzip']
+     */
+    readonly encodings?: readonly CompressionEncoding[];
+    /**
+     * Bodies below this many bytes are sent as they are.
+     *
+     * Only applied when the response declares a `content-length`. A short JSON body
+     * grows under gzip - the header and trailer alone are 18 bytes - and the round
+     * trip through a compressor is time spent to send more.
+     *
+     * @default 1024
+     */
+    readonly threshold?: number;
+    /** Which `content-type`s to encode. @default isCompressibleType */
+    readonly filter?: (contentType: string | null) => boolean;
+}
+/**
+ * A class, not an interface, so it is a runtime value `@dunx/transform` can record
+ * at an injection site - the same reason `StaticOptions` and `ThrottleOptions` are.
+ */
+export declare class CompressionOptions {
+    readonly encodings: readonly CompressionEncoding[];
+    readonly threshold: number;
+    readonly filter: (contentType: string | null) => boolean;
+    constructor(init?: CompressionOptionsInit);
+}

package/dist/health/controller.d.ts

@@ -3,9 +3,9 @@
  * finishes every `onInit` before `listen()` binds, so a connection refused *is* "not
  * started yet" and a third endpoint would restate it.
  *
- * `@Public()` because a probe has no credentials, and `@ApiHidden()` because these
- * are for the orchestrator rather than for an API consumer. Both are the existing
- * route metadata; there is nothing health-specific about either.
+ * `@Public()` because a probe has no credentials. Both routes are documented, under
+ * the `Health` tag; `HealthModule.forRoot({ documented: false })` mounts
+ * {@link HiddenHealthController} instead.
  */
 export declare class HealthController {
     #private;
@@ -19,3 +19,15 @@ export declare class HealthController {
     /** Should the process receive traffic. Fails from the moment the drain starts. */
     ready(): Promise<Response>;
 }
+/**
+ * The same two routes, kept out of the OpenAPI document.
+ *
+ * A subclass rather than a flag read when the module is registered, because
+ * `@ApiHidden()` writes to the class and a class is shared by every app in the
+ * process: `examples/full` boots a second container to demonstrate the websocket
+ * relay, so setting the flag at `forRoot` time would leak into the other one. The
+ * prefix and both handlers resolve through the prototype chain, so this is the
+ * whole implementation.
+ */
+export declare class HiddenHealthController extends HealthController {
+}

package/dist/health/module.d.ts

@@ -28,13 +28,14 @@ export declare class HealthModule {
      * });
      * ```
      *
-     * `routes` is read from the init here too, but the controller is mounted from the
-     * static shape rather than from the awaited options: a route table is folded into
-     * one closure per route when the server binds, so it cannot wait on a factory.
-     * Pass `routes: false` and mount your own if that matters.
+     * `routes` and `documented` are read from the init here too, but the controller is
+     * mounted from the static shape rather than from the awaited options: a route
+     * table is folded into one closure per route when the server binds, so it cannot
+     * wait on a factory. Pass `routes: false` and mount your own if that matters.
      */
     static forRootAsync<const D extends Deps>(config: FactoryProvider<HealthOptionsInit, D> & {
         readonly imports?: DynamicModule['imports'];
         readonly routes?: boolean;
+        readonly documented?: boolean;
     }): DynamicModule;
 }

package/dist/health/registry.d.ts

@@ -28,6 +28,8 @@ export declare class HealthOptions {
     readonly timeoutMs: number;
     /** Mount `/health/live` and `/health/ready`. Default `true`. */
     readonly routes: boolean;
+    /** Include the two routes in the OpenAPI document. Default `true`. */
+    readonly documented: boolean;
     /** How long to fail readiness before the server stops accepting. Default `0`. */
     readonly drainDelayMs: number;
     constructor(init?: HealthOptionsInit);
@@ -40,6 +42,12 @@ export interface HealthOptionsInit {
     /** Per-indicator budget. Default `2000`. */
     readonly timeoutMs?: number;
     readonly routes?: boolean;
+    /**
+     * `false` mounts `HiddenHealthController`, so the probes are served and left out
+     * of the document. They are documented by default: the paths and the report are
+     * worth finding in the reference, and an orchestrator reads neither.
+     */
+    readonly documented?: boolean;
     /** Passed through to {@link ReadinessOptions}. */
     readonly drainDelayMs?: number;
 }

package/dist/health/report-schema.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from '../route/schema.js';
+/**
+ * `HealthReport`, as a JSON Schema literal.
+ *
+ * A hand-written schema rather than a zod one, because `RouteSchemas.response`
+ * accepts either and this package has no validator dependency to spend on
+ * documenting two routes. `$id` hoists it into `components/schemas` once, so both
+ * probes and both statuses reference the same definition.
+ *
+ * It restates the `HealthReport` and `HealthCheckReport` interfaces, which is the
+ * one duplicate here: a type is erased and a document needs the shape at runtime.
+ * `health.test.ts` asserts the two agree.
+ */
+export declare const HEALTH_REPORT_SCHEMA: JsonSchema;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { Controller, Delete, Get, Patch, Post, Put, } from './route/decorators.js';
 export { discoverRoutes, joinPath, type DiscoveredRoute, } from './route/discover.js';
-export type { HttpMethod, RouteMeta, RoutePath } from './route/marker.js';
+export { defaultStatusFor, type DefaultStatus, type HttpMethod, type RouteMeta, type RoutePath, } from './route/marker.js';
 export { ApiHidden, guardsOf, HIDDEN, meta, metaKey, metaOf, mergeMeta, Public, PUBLIC, Roles, ROLES, UNMATCHED, UseGuards, type MetaKey, type MetaRecord, } from './route/metadata.js';
-export type { InferOutput, Input, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
+export type { InferOutput, Input, JsonSchema, ResponseMap, Returns, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
 export { gatewaysOf, routesOf, type GatewayHandler, type GatewayNode, type RouteInputs, type RouteNode, } from './inspect.js';
 export { ClientAddress } from './server/client-address.js';
 export { buildContext, type RouteContext } from './server/context.js';
@@ -10,6 +10,7 @@ export { preflight, withCors, type CorsOptions, type CorsOrigin, } from './serve
 export { defaultErrorMapper, ErrorFilter, errorMapper, HttpError, isErrorFilter, toErrorMapper, ValidationError, type ErrorHandler, type ErrorMapper, type HttpErrorOptions, type InputSource, type ValidationIssue, } from './server/errors.js';
 export { HttpFactory, type HttpApp, type HttpOptions, } from './server/factory.js';
 export { REQUEST_ID_HEADER } from './server/request-id.js';
+export { TRACEPARENT_HEADER, TRACESTATE_HEADER, TraceContext, type Trace, } from './server/trace-context.js';
 export { RequestLoggingMiddleware, type RequestLoggingOptions, } from './server/request-logging.js';
 export { compose, type Middleware, type Next, type RouteHandler, } from './server/middleware.js';
 export { assertNoCollisions, assertNoGatewayCollisions, buildRoutes, withUpgradeRoutes, type BunRoutes, type GuardResolver, type RouteMethod, type ServeRoutes, } from './server/routes.js';
@@ -17,6 +18,10 @@ export type { AppSettings } from './server/settings.js';
 export { StaticFiles } from './static/files.js';
 export { StaticModule } from './static/module.js';
 export { normalizePrefix, StaticOptions, type StaticOptionsInit, } from './static/options.js';
+export { Compression } from './compression/compression.js';
+export { CompressionModule } from './compression/module.js';
+export { negotiate } from './compression/negotiate.js';
+export { CompressionEncoding, CompressionOptions, isCompressibleType, type CompressionOptionsInit, } from './compression/options.js';
 export { SKIP_THROTTLE, SkipThrottle, THROTTLE, Throttle, type ThrottleLimit, } from './throttle/decorators.js';
 export { ThrottleGuard } from './throttle/guard.js';
 export { ThrottleModule } from './throttle/module.js';
@@ -36,8 +41,9 @@ export { decodeRelay, DEFAULT_RELAY_CHANNEL, encodeRelay, type PubSubRelay, type
 export { buildGateways, buildRuntime, type GatewayRuntime, } from './ws/runtime.js';
 export type { Socket, SocketData, SocketErrorHandler, SocketOptions, } from './ws/socket.js';
 export { HealthIndicator, PingProbe, QueryProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
-export { HealthController } from './health/controller.js';
+export { HealthController, HiddenHealthController, } from './health/controller.js';
 export { DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, type DiskOptionsInit, type MemoryOptionsInit, } from './health/indicators.js';
 export { HealthModule } from './health/module.js';
+export { HEALTH_REPORT_SCHEMA } from './health/report-schema.js';
 export { Readiness, ReadinessOptions } from './health/readiness.js';
 export { HealthOptions, HealthRegistry, type HealthCheckReport, type HealthOptionsInit, type HealthReport, } from './health/registry.js';