@dunx/http 2.3.0 → 2.4.0

package/dist/route/schema.d.ts

@@ -33,6 +33,14 @@ export interface StandardSchemaIssue {
 }
 /** The validated output of a schema - `InferOutput<typeof CreateNote>` is `Note`. */
 export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer Out> ? Out : never;
+/**
+ * A JSON Schema, as JSON. OpenAPI 3.1 embeds draft 2020-12 verbatim.
+ *
+ * Declared here rather than in `@dunx/openapi` because {@link RouteSchemas} names
+ * it and that package depends on this one, so this is the lowest common owner.
+ * `@dunx/openapi` re-exports it.
+ */
+export type JsonSchema = Readonly<Record<string, unknown>>;
 /**
  * The second argument to `@Get`/`@Post`/... Declaring a schema is what makes the
  * matching `input` field appear, get parsed, and get validated; omitting one
@@ -62,8 +70,20 @@ export interface RouteSchemas {
      * cost paid for a documentation feature, which is the wrong trade - the
      * handler's own return type is what checks the answer, at compile time and for
      * free. Nothing in the request path reads this key.
+     *
+     * A plain {@link JsonSchema} is accepted here too, and only here: a JSON Schema
+     * needs no conversion, so documenting a response costs no validator. `$id` names
+     * it, hoisting it into `components/schemas` the way `.meta({ id })` does for a
+     * zod schema. `body`, `query` and `params` still take a Standard Schema, because
+     * those are parsed.
+     *
+     * ```ts
+     * response: {
+     *   200: Object.freeze({ $id: 'Pong', type: 'object' }),
+     * }
+     * ```
      */
-    readonly response?: Readonly<Record<number, StandardSchemaV1>>;
+    readonly response?: Readonly<Record<number, StandardSchemaV1 | JsonSchema>>;
 }
 /**
  * The handler's parameter type, derived from its own options object. It has to be

package/dist/server/context.d.ts

@@ -11,6 +11,16 @@ export interface RouteContext {
     readonly handler: string;
     readonly method: HttpMethod;
     readonly path: string;
+    /**
+     * Whether this route declares a `body` schema, and therefore whether the input
+     * reader will parse the body and record it for anything else that wants it.
+     *
+     * Resolved here because it is a property of the route, known when the table is
+     * built. `RequestLoggingMiddleware` reads it to decide once - not per request -
+     * whether logging the body needs a `Request.clone()`, which is the single most
+     * expensive thing it can do. See `raw-body.ts`.
+     */
+    readonly parsesBody: boolean;
     get<T>(key: MetaKey<T>): T | undefined;
 }
 /**

package/dist/server/raw-body.d.ts

@@ -0,0 +1,21 @@
+import type { BunRequest } from 'bun';
+export declare class RawBody {
+    /**
+     * Called by `RequestLoggingMiddleware` before the chain runs, when it intends to
+     * log this body and the route is going to parse it anyway.
+     */
+    static want(req: BunRequest): void;
+    /** Whether the body reader should buffer the text on the way past. */
+    static wanted(req: BunRequest): boolean;
+    /**
+     * Called by the body reader with the text it buffered, **before** validating it.
+     *
+     * Before, on purpose, and for two reasons. Validation applies defaults, coerces
+     * and strips unknown keys, so the validated object is not what the caller sent.
+     * And a body that fails to parse at all still has text - which is the case the
+     * clone used to cover and the reason this holds text rather than a value.
+     */
+    static record(req: BunRequest, text: string): void;
+    /** The buffered text, or `undefined` when nothing read one. */
+    static read(req: BunRequest): string | undefined;
+}

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

@@ -8,15 +8,35 @@ export interface RequestLoggingOptions {
     /**
      * Log the request body. Default **`false`**.
      *
-     * Reading it means `req.clone().text()` - a second copy of every payload,
-     * buffered and parsed, on the hot path. Measured on the `validate` scenario in
-     * `internal/bench`, turning both body options on costs roughly two thirds of the
-     * throughput. It is also the field most likely to contain a password.
+     * **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`:
      *
-     * Turn it on in development, where seeing the payload is the point.
+     * | 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.
      */
     readonly requestBody?: boolean;
-    /** Log the response body. Default **`false`** - same clone-and-buffer cost. */
+    /**
+     * 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.
+     */
     readonly responseBody?: boolean;
     /**
      * Paths to skip entirely - a health check polled every second, say.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/http",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "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.3.0",
+    "@dunx/core": "^2.4.0",
     "@types/bun": ">=1.3.0"
   },
   "peerDependenciesMeta": {