@daloyjs/core 0.38.3 → 0.39.0

package/README.md

@@ -249,7 +249,7 @@ const r = await client.getBookById({ params: { id: "1" } });
 
 ---
 
-## Built-in docs UI (Scalar / Swagger UI)
+## Built-in docs UI (Scalar / Swagger UI / Redoc)
 
 FastAPI-style. One line on the `App` constructor mounts `GET /docs`, `GET /openapi.json`, and `GET /openapi.yaml` for you,
 with a strict CSP and CDN-hosted assets:
@@ -269,7 +269,7 @@ Use `docs: "auto"` to mount only when `production: false`, or the object form fo
 new App({
   openapi: { info: { title: "My API", version: "1.0.0" } },
   docs: {
-    ui: "scalar",
+    ui: "scalar", // "scalar" (default) | "swagger" | "redoc"
     path: "/reference",
     openapiPath: "/spec.json",
     openapiYamlPath: "/spec.yaml", // or `false` to disable the YAML route
@@ -283,15 +283,30 @@ new App({
 });
 ```
 
+Switch UIs with one word. `ui: "redoc"` renders Redoc instead, and its
+options are forwarded to `Redoc.init` via `docs.redoc`:
+
+```ts
+new App({
+  openapi: { info: { title: "My API", version: "1.0.0" } },
+  docs: {
+    ui: "redoc",
+    redoc: { hideDownloadButtons: true, sortPropsAlphabetically: true },
+  },
+});
+```
+
 The `scalar` option is forwarded to Scalar's HTML API as JSON configuration,
 with Daloy keeping the live `openapiPath` as the source. Use it for themes,
 custom CSS, layout, auth defaults, and client visibility without copying the
-HTML helper.
+HTML helper. Redoc spins up a `blob:` Web Worker for search, so the
+auto-mounted `/docs` page widens its CSP with `worker-src 'self' blob:` for
+`ui: "redoc"` only — Scalar and Swagger UI keep the tighter default.
 
 Prefer to mount manually? Import the helpers directly:
 
 ```ts
-import { swaggerUiHtml, scalarHtml, htmlResponse } from "@daloyjs/core/docs";
+import { swaggerUiHtml, scalarHtml, redocHtml, htmlResponse } from "@daloyjs/core/docs";
 import { generateOpenAPI } from "@daloyjs/core/openapi";
 ```
 
@@ -488,7 +503,7 @@ DaloyJS is in **public preview** (`0.x`). The public API may still change betwee
 ### Routing, validation, and docs
 
 - Contract-first routing with Standard Schema validation (Zod 4, Valibot, ArkType, TypeBox) and OpenAPI 3.1 generated from a single source of truth.
-- Live OpenAPI 3.1 spec served as both JSON (`GET /openapi.json`) and YAML (`GET /openapi.yaml`) when `docs: true`, with Scalar UI theming and custom CSS via `docs.scalar`.
+- Live OpenAPI 3.1 spec served as both JSON (`GET /openapi.json`) and YAML (`GET /openapi.yaml`) when `docs: true`, with a choice of Scalar (default), Swagger UI, or Redoc via `docs.ui`, plus Scalar theming/custom CSS via `docs.scalar` and Redoc options via `docs.redoc`.
 - Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
 - RFC 7231 + RFC 5789 HTTP-method allowlist enforced inside `app.route()` (WebDAV, `TRACE`, `CONNECT` rejected at the framework boundary).
 - AI-friendly route metadata via optional `meta: { examples, extensions, summary, description, tags }`; examples are validated against your schemas at build time, surfaced as OpenAPI `examples` + `x-daloy-*` extensions, and dumped as `routes.json` / `routes.yaml` via `daloy inspect --ai`.
@@ -549,7 +564,8 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
 - `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, `Vary`-aware keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` in-memory default) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie` or `private`/`no-store`/`no-cache` responses. Complements `etag()`/`compression()`, which do not cache bodies.
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
-- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production).
+- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
+- `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.
 - `app.cron()` + standalone `Scheduler` in-process scheduled tasks at `@daloyjs/core/scheduler`: a queue-agnostic schedule primitive for periodic housekeeping (cache sweeps, token refresh, reconciliation). Fixed intervals or 5-field cron expressions (lists / ranges / steps / named months & days / `@hourly`–`@yearly` aliases / optional IANA `timeZone`), arithmetic cron parsing (no backtracking regex), fixed-rate **single-flight** (overlapping ticks are skipped, never run concurrently), per-run `timeoutMs` with `AbortSignal`, and graceful-shutdown integration (stop arming → await in-flight → abort after grace). Timers are `unref`'d. `parseCron()` / `nextCronRun()` exported standalone. Zero runtime dependencies.
@@ -561,7 +577,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `concurrencyLimit()` per-route / per-client concurrency limits + queueing at `@daloyjs/core/concurrency-limit`: HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies. HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies.
 - `requestDecompression()` inbound decompression-bomb guard at `@daloyjs/core/request-decompression`: core is safe by omission (it never decompresses request bodies), so this is the opt-in middleware for services that must accept compressed uploads. Inflates `gzip` / `deflate` bodies behind two caps enforced **during** inflation so a zip bomb is aborted before it is fully materialised: an absolute `maxDecompressedBytes` (required) and an expansion-ratio `maxRatio` (default `100`), both rejecting with `413`. The compressed upload itself is bounded by `maxCompressedBytes` (default 1 MiB) before a byte is inflated. Unknown, non-allowlisted, runtime-unsupported, or **layered** (`gzip, gzip`) encodings are refused `415`; malformed streams `400`; bodyless / uncompressed / `identity` / `GET` / `HEAD` traffic passes through untouched. Runs in `onRequest` and stashes the inflated bytes so schema-validated bodies and raw-body handlers both see the decompressed payload. `onBomb` observability hook, exported `decompressRequestBody()` for custom flows. Built on web-standard `DecompressionStream` (brotli excluded — not in the spec). Zero runtime dependencies.
 - `waf()` opt-in WAF-lite signature/anomaly inbound-inspection middleware at `@daloyjs/core/waf`: a first-party defense-in-depth layer for teams without an edge WAF (it does **not** replace ModSecurity / a CDN WAF). Wires DaloyJS' high-confidence injection signatures — SQLi, XSS, NoSQL-operator injection (reusing `hasMongoOperatorKeys` for a structural body check), and command injection — into a single scored inbound-inspection pass over the decoded path, the raw + decoded query string, an opt-in header allowlist, and the validated body. Each rule that fires adds an anomaly `score`; reaching `blockThreshold` (default `5`) rejects with a generic `403` (block mode) or merely reports via `onMatch` (log mode) so operators can tune against real traffic first. Per-rule enable/disable + score overrides, inspection-surface toggles, control-character-stripped log samples, and bounded scanning (`maxValueLength` / `maxBodyNodes`) keep a hostile payload from becoming CPU-DoS. The `403` body never names the rule that fired. Zero runtime dependencies.
-- Built-in docs UI Subresource Integrity (SRI): `DocsAssetOptions` lets `scalarHtml()` / `swaggerUiHtml()` and the `docs: { assets }` auto-mount pin version-exact `*Integrity` hashes (`sha256`/`sha384`/`sha512`) plus a `crossOrigin` value (default `"anonymous"`) on the CDN-loaded Scalar / Swagger UI `<script>` / `<link>` tags, so a poisoned jsDelivr asset can't execute. Malformed SRI values throw a `TypeError` at startup (browsers ignore unparseable `integrity`, so failing loud avoids a false sense of protection); self-hosting the assets via the same `assets` URLs stays supported. Zero runtime dependencies.
+- Built-in docs UI Subresource Integrity (SRI): `DocsAssetOptions` lets `scalarHtml()` / `swaggerUiHtml()` / `redocHtml()` and the `docs: { assets }` auto-mount pin version-exact `*Integrity` hashes (`sha256`/`sha384`/`sha512`) plus a `crossOrigin` value (default `"anonymous"`) on the CDN-loaded Scalar / Swagger UI / Redoc `<script>` / `<link>` tags, so a poisoned jsDelivr asset can't execute. Malformed SRI values throw a `TypeError` at startup (browsers ignore unparseable `integrity`, so failing loud avoids a false sense of protection); self-hosting the assets via the same `assets` URLs stays supported. Zero runtime dependencies.
 - HTTP Message Signatures (RFC 9421) at `@daloyjs/core/http-signatures`: first-party sign/verify for server-to-server request authentication via the standard `Signature` / `Signature-Input` headers — complements the inbound-only webhook HMAC and `clientCertAuth()` mTLS. `signMessage()` / `signRequest()` build an RFC 9421 signature base over derived components (`@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@query-param`, `@status`) and HTTP fields with Structured-Fields header serialization; `verifyMessage()` / `verifyRequest()` and the `httpSignatureAuth()` middleware check them. Algorithms `hmac-sha256` / `ed25519` / `ecdsa-p256-sha256` / `ecdsa-p384-sha384` / `rsa-pss-sha512` / `rsa-v1_5-sha256` via WebCrypto (no `node:` imports). Secure-by-default verify: a **mandatory `algorithms` allowlist** (no implicit "any alg"), optional per-key alg pinning to defeat algorithm-confusion, a required `created` timestamp with a 300s freshness window, `created`-in-future / `expires` skew rejection, configurable `requiredComponents`, a 32-byte raw-HMAC floor, and `nonce` replay defense; the middleware answers a missing/invalid signature with `401` + `Cache-Control: no-store` and stamps the verified result on `ctx.state.httpSignature`. Ships RFC 9530 `contentDigest()` / `verifyContentDigest()` to bind the request body. Zero runtime dependencies.
 - `compression()` built on web-standard `CompressionStream` (prefers `br` > `gzip` > `deflate`), with BREACH-aware always-on guards (skips `Set-Cookie`, `Authorization`, session / CSRF cookies, already-compressed content types), `minimumSize: 1024`, negative-compression-ratio post-check, no configurable `compressLevel` knob (CPU-DoS defense — `level: 9` is refused at construction), always-on `Vary: Accept-Encoding`, and strong → weak ETag downgrade per RFC 9110 §8.8.3.
 - `etag()` helper auto-skips on `Set-Cookie` and private / no-store / no-cache `Cache-Control` (cross-tenant fingerprinting defense).

package/dist/app.d.ts

@@ -2,7 +2,7 @@ import { WebSocketRegistry, type WebSocketHandler } from "./websocket.js";
 import { type Logger } from "./logger.js";
 import type { HttpMethod, Hooks, PathString, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
 import { type OpenAPIInfo, type OpenAPIOptions } from "./openapi.js";
-import { type DocsAssetOptions, type DocsContentSecurityPolicyOptions, type ScalarReferenceConfiguration } from "./docs.js";
+import { type DocsAssetOptions, type DocsContentSecurityPolicyOptions, type RedocConfiguration, type ScalarReferenceConfiguration } from "./docs.js";
 import { type SecureHeadersOptions } from "./middleware.js";
 import { type LoadSheddingOptions } from "./load-shedding.js";
 import { MetricsRegistry, type HttpMetricsOptions } from "./metrics.js";
@@ -299,7 +299,7 @@ export interface AppOptions {
     /**
      * Enable the built-in API documentation surface — a `/openapi.json` route
      * that serves the live OpenAPI 3.1 spec and a `/docs` route that serves a
-     * Scalar (default) or Swagger UI HTML page that loads it. This is the
+     * Scalar (default), Swagger UI, or Redoc HTML page that loads it. This is the
      * one-line equivalent of FastAPI's automatic `/docs` UI.
      *
      * - `false` (default) — never mount. Write your own with `generateOpenAPI`
@@ -309,7 +309,7 @@ export interface AppOptions {
      *   is a "secure by default" choice: production deployments should opt in
      *   explicitly so internal APIs do not accidentally publish a browsable
      *   schema.
-      * - object — full configuration (custom paths, UI choice, title, Scalar UI
+      * - object — full configuration (custom paths, UI choice, title, per-UI
       *   config, CSP overrides). The `enabled` field on the object can override the
      *   auto/prod rule.
      *
@@ -353,10 +353,21 @@ export interface DocsRouteOptions {
      * @since 0.13.1
      */
     openapiYamlPath?: PathString | false;
-    /** Which built-in UI to render. Default `"scalar"` (smaller payload, modern UI). */
-    ui?: "scalar" | "swagger";
-    /** Scalar API reference UI configuration. Ignored when `ui: "swagger"`. */
+    /**
+     * Which built-in UI to render. Default `"scalar"` (smaller payload, modern
+     * UI). `"swagger"` renders classic Swagger UI; `"redoc"` (since 0.39.0)
+     * renders Redoc.
+     */
+    ui?: "scalar" | "swagger" | "redoc";
+    /** Scalar API reference UI configuration. Ignored unless `ui` is `"scalar"`. */
     scalar?: ScalarReferenceConfiguration;
+    /**
+     * Redoc UI configuration, forwarded to `Redoc.init`. Ignored unless
+     * `ui: "redoc"`.
+     *
+     * @since 0.39.0
+     */
+    redoc?: RedocConfiguration;
     /** Page `<title>`. Defaults to the resolved OpenAPI `info.title`. */
     title?: string;
     /**

package/dist/app.js

@@ -5,7 +5,7 @@ import { validate } from "./schema.js";
 import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
-import { docsContentSecurityPolicy, scalarHtml, swaggerUiHtml, } from "./docs.js";
+import { docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
 import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
 import { COMPRESSION_HOOK_MARKER } from "./compression.js";
 import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
@@ -830,6 +830,14 @@ export class App {
                 }),
             });
         }
+        // Redoc builds a Web Worker from a `blob:` URL, which the strict docs CSP
+        // would otherwise block; grant `worker-src 'self' blob:` for that UI only
+        // (unless the caller explicitly overrode it). Scalar / Swagger UI keep the
+        // tighter default. The policy is deterministic from `ui` + `opts.csp`, so
+        // compute it once at mount time instead of per request.
+        const docsCsp = docsContentSecurityPolicy(ui === "redoc"
+            ? { ...opts.csp, allowBlobWorkers: opts.csp?.allowBlobWorkers ?? true }
+            : opts.csp);
         this.route({
             method: "GET",
             path: docsPath,
@@ -847,18 +855,25 @@ export class App {
                         title,
                         assets: opts.assets,
                     })
-                    : scalarHtml({
-                        specUrl: openapiPath,
-                        title,
-                        configuration: opts.scalar,
-                        assets: opts.assets,
-                    });
+                    : ui === "redoc"
+                        ? redocHtml({
+                            specUrl: openapiPath,
+                            title,
+                            configuration: opts.redoc,
+                            assets: opts.assets,
+                        })
+                        : scalarHtml({
+                            specUrl: openapiPath,
+                            title,
+                            configuration: opts.scalar,
+                            assets: opts.assets,
+                        });
                 return {
                     status: 200,
                     body: html,
                     headers: {
                         "content-type": "text/html; charset=utf-8",
-                        "content-security-policy": docsContentSecurityPolicy(opts.csp),
+                        "content-security-policy": docsCsp,
                         "x-content-type-options": "nosniff",
                         "referrer-policy": "no-referrer",
                     },

package/dist/docs.d.ts

@@ -1,9 +1,9 @@
 /**
  * Built-in API documentation handlers.
  *
- * Scalar and Swagger UI helpers serve a single HTML page that loads the spec
- * at `specUrl` and fetches UI assets from a CDN by default. No build step,
- * no extra deps.
+ * Scalar, Swagger UI, and Redoc helpers serve a single HTML page that loads
+ * the spec at `specUrl` and fetches UI assets from a CDN by default. No build
+ * step, no extra deps.
  *
  * (You can self-host the assets if your CSP forbids CDNs.)
  */
@@ -92,6 +92,89 @@ export interface ScalarReferenceConfiguration {
     spec?: never;
     url?: never;
 }
+/**
+ * Subset of Redoc standalone configuration safe to serialize from the server.
+ *
+ * Every field is a plain JSON value, so the whole object is forwarded verbatim
+ * to `Redoc.init(specUrl, configuration, element)` in the generated page. The
+ * index signature accepts any additional Redoc option (the standalone bundle's
+ * option set drifts across versions); the named fields exist for editor
+ * autocompletion of the common, stable ones. Function-typed options are not
+ * representable here on purpose — they cannot cross the server→HTML boundary.
+ *
+ * @since 0.39.0
+ */
+export interface RedocConfiguration {
+    [key: string]: ScalarJsonValue | undefined;
+    /** Disable the search bar (also skips spawning the search Web Worker). */
+    disableSearch?: boolean;
+    /** Minimum query length before search runs. */
+    minCharacterLengthToInitSearch?: number;
+    /** Which responses to expand by default, e.g. `"200,201"` or `"all"`. */
+    expandResponses?: string;
+    /** Expand the single-property schema field instead of collapsing it. */
+    expandSingleSchemaField?: boolean;
+    /** Expand `default` server-variable values in the sidebar. */
+    expandDefaultServerVariables?: boolean;
+    /** How deep to expand generated JSON samples; a number or `"all"`. */
+    jsonSampleExpandLevel?: number | string;
+    /** How deep to expand nested schemas; a number or `"all"`. */
+    schemasExpansionLevel?: number | string;
+    /** Hide the "Download" button(s) for the spec. */
+    hideDownloadButtons?: boolean;
+    /** Override the URL used by the download button. */
+    downloadDefinitionUrl?: string;
+    /** Hide the API host from the docs. */
+    hideHostname?: boolean;
+    /** Hide the loading spinner. */
+    hideLoading?: boolean;
+    /** Hide the request payload sample tab. */
+    hideRequestPayloadSample?: boolean;
+    /** Hide the `pattern` shown for string schemas. */
+    hideSchemaPattern?: boolean;
+    /** Hide schema title captions. */
+    hideSchemaTitles?: boolean;
+    /** Hide the entire Security section. */
+    hideSecuritySection?: boolean;
+    /** Hide the single-sample tab when there is only one request sample. */
+    hideSingleRequestSampleTab?: boolean;
+    /** Largest number of enum values to show before collapsing. */
+    maxDisplayedEnumValues?: number;
+    /** Collapse sidebar items on selection (single-expanded menu behaviour). */
+    menuToggle?: boolean;
+    /** Use the browser's native scrollbars instead of custom ones. */
+    nativeScrollbars?: boolean;
+    /** Show only required fields in request samples. */
+    onlyRequiredInSamples?: boolean;
+    /** Render the path in the middle panel instead of the right one. */
+    pathInMiddlePanel?: boolean;
+    /** Index of the request sample shown first. */
+    payloadSampleIdx?: number;
+    /** Sort required properties before optional ones. */
+    requiredPropsFirst?: boolean;
+    /** Pixels of fixed offset for in-page anchor scrolling; a number or selector. */
+    scrollYOffset?: number | string;
+    /** Show vendor `x-` extensions; `true`/`false` or an allowlist of names. */
+    showExtensions?: boolean | string[];
+    /** Show object schema examples. */
+    showObjectSchemaExamples?: boolean;
+    /** Show the HTTP verb badge for webhooks. */
+    showWebhookVerb?: boolean;
+    /** Use a simple `oneOf` type label instead of an expandable selector. */
+    simpleOneOfTypeLabel?: boolean;
+    /** Sort enum values alphabetically. */
+    sortEnumValuesAlphabetically?: boolean;
+    /** Sort operations alphabetically. */
+    sortOperationsAlphabetically?: boolean;
+    /** Sort schema properties alphabetically. */
+    sortPropsAlphabetically?: boolean;
+    /** Sort tags alphabetically. */
+    sortTagsAlphabetically?: boolean;
+    /** Nested Redoc theme object (colors, typography, sidebar, etc.). */
+    theme?: {
+        [key: string]: ScalarJsonValue | undefined;
+    };
+}
 /**
  * Override CDN URLs and pin Subresource Integrity (SRI) hashes for the docs
  * UI assets.
@@ -134,6 +217,15 @@ export interface DocsAssetOptions {
      * @since 0.37.0
      */
     swaggerUiBundleIntegrity?: string;
+    /** Override the Redoc standalone bundle URL (useful for self-hosting). */
+    redocScriptUrl?: string;
+    /**
+     * SRI hash for {@link redocScriptUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.39.0
+     */
+    redocScriptIntegrity?: string;
     /**
      * `crossorigin` attribute value emitted alongside any pinned integrity
      * hash. SRI on a cross-origin asset requires CORS, so this defaults to
@@ -163,6 +255,15 @@ export interface ScalarHtmlOptions extends DocsOptions {
     /** Forwarded to the Scalar `<script id="api-reference">` tag. */
     configuration?: ScalarReferenceConfiguration;
 }
+/**
+ * Options for {@link redocHtml}; adds Redoc-specific UI configuration.
+ *
+ * @since 0.39.0
+ */
+export interface RedocHtmlOptions extends DocsOptions {
+    /** Forwarded as the options object to `Redoc.init(specUrl, configuration, element)`. */
+    configuration?: RedocConfiguration;
+}
 /** Options for {@link docsContentSecurityPolicy}. */
 export interface DocsContentSecurityPolicyOptions {
     /** Extra origins to allow for `script-src` / `style-src` (defaults to jsDelivr). */
@@ -171,6 +272,16 @@ export interface DocsContentSecurityPolicyOptions {
     scriptNonce?: string;
     /** When `false`, omits `'unsafe-inline'` from `style-src`. Defaults to `true`. */
     allowInlineStyles?: boolean;
+    /**
+     * When `true`, append `worker-src 'self' blob:` so a UI that constructs a
+     * Web Worker from a `blob:` URL can run under this CSP. Redoc does this for
+     * its search index, so the auto-mounted docs route enables it automatically
+     * for `ui: "redoc"`; Scalar and Swagger UI do not need it. Defaults to
+     * `false`, leaving the policy unchanged.
+     *
+     * @since 0.39.0
+     */
+    allowBlobWorkers?: boolean;
 }
 /** Options for {@link htmlResponse}. */
 export interface HtmlResponseOptions extends DocsContentSecurityPolicyOptions {
@@ -190,6 +301,21 @@ export declare function scalarHtml(opts: ScalarHtmlOptions): string;
  * {@link scalarHtml} but emits the classic Swagger UI bundle.
  */
 export declare function swaggerUiHtml(opts: DocsOptions): string;
+/**
+ * Render a Redoc HTML page that loads `opts.specUrl`. Same usage as
+ * {@link scalarHtml} / {@link swaggerUiHtml} but emits the Redoc standalone
+ * bundle and forwards {@link RedocHtmlOptions.configuration} to `Redoc.init`.
+ *
+ * Redoc constructs a Web Worker from a `blob:` URL for its search index, so
+ * serve this page with a CSP that allows `worker-src 'self' blob:` — pass
+ * `allowBlobWorkers: true` to {@link docsContentSecurityPolicy} /
+ * {@link htmlResponse} (the `docs: { ui: "redoc" }` auto-mount does this for
+ * you). The spec URL and configuration are embedded with `<`-escaped JSON so
+ * an attacker-controlled value cannot break out of the inline `<script>`.
+ *
+ * @since 0.39.0
+ */
+export declare function redocHtml(opts: RedocHtmlOptions): string;
 /**
  * Build a Content-Security-Policy string compatible with the docs HTML
  * produced by {@link scalarHtml} / {@link swaggerUiHtml}.

package/dist/docs.js

@@ -1,9 +1,9 @@
 /**
  * Built-in API documentation handlers.
  *
- * Scalar and Swagger UI helpers serve a single HTML page that loads the spec
- * at `specUrl` and fetches UI assets from a CDN by default. No build step,
- * no extra deps.
+ * Scalar, Swagger UI, and Redoc helpers serve a single HTML page that loads
+ * the spec at `specUrl` and fetches UI assets from a CDN by default. No build
+ * step, no extra deps.
  *
  * (You can self-host the assets if your CSP forbids CDNs.)
  */
@@ -90,6 +90,39 @@ export function swaggerUiHtml(opts) {
 <script${nonce}>window.onload=()=>SwaggerUIBundle({url:"${url}",dom_id:"#swagger"});</script>
 </body></html>`;
 }
+/**
+ * Render a Redoc HTML page that loads `opts.specUrl`. Same usage as
+ * {@link scalarHtml} / {@link swaggerUiHtml} but emits the Redoc standalone
+ * bundle and forwards {@link RedocHtmlOptions.configuration} to `Redoc.init`.
+ *
+ * Redoc constructs a Web Worker from a `blob:` URL for its search index, so
+ * serve this page with a CSP that allows `worker-src 'self' blob:` — pass
+ * `allowBlobWorkers: true` to {@link docsContentSecurityPolicy} /
+ * {@link htmlResponse} (the `docs: { ui: "redoc" }` auto-mount does this for
+ * you). The spec URL and configuration are embedded with `<`-escaped JSON so
+ * an attacker-controlled value cannot break out of the inline `<script>`.
+ *
+ * @since 0.39.0
+ */
+export function redocHtml(opts) {
+    const title = escapeHtml(opts.title ?? "API Docs");
+    const scriptUrl = escapeHtml(opts.assets?.redocScriptUrl ??
+        `${JSDELIVR_ORIGIN}/npm/redoc/bundles/redoc.standalone.js`);
+    const scriptSri = integrityAttr(opts.assets?.redocScriptIntegrity, opts.assets?.crossOrigin);
+    const nonce = nonceAttr(opts.scriptNonce);
+    const specArg = jsonForScript(opts.specUrl);
+    const optionsArg = jsonForScript(opts.configuration ?? {});
+    return `<!doctype html>
+<html><head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+</head><body>
+<div id="redoc"></div>
+<script src="${scriptUrl}"${scriptSri}${nonce}></script>
+<script${nonce}>Redoc.init(${specArg},${optionsArg},document.getElementById("redoc"));</script>
+</body></html>`;
+}
 /**
  * Build a Content-Security-Policy string compatible with the docs HTML
  * produced by {@link scalarHtml} / {@link swaggerUiHtml}.
@@ -107,13 +140,19 @@ export function docsContentSecurityPolicy(opts = {}) {
     const styleSrc = ["'self'", ...assetOrigins];
     if (opts.allowInlineStyles !== false)
         styleSrc.push("'unsafe-inline'");
-    return [
+    const directives = [
         "default-src 'self'",
         `script-src ${scriptSrc.join(" ")}`,
         `style-src ${styleSrc.join(" ")}`,
         "img-src 'self' data: https:",
         "connect-src 'self'",
-    ].join("; ");
+    ];
+    // Redoc spawns a Web Worker from a `blob:` URL; without an explicit
+    // worker-src the browser falls back to script-src, which forbids `blob:`
+    // and breaks the page. Scope this relaxation to callers that opt in.
+    if (opts.allowBlobWorkers)
+        directives.push("worker-src 'self' blob:");
+    return directives.join("; ");
 }
 /**
  * Wrap a docs HTML string in a `Response` with safe defaults:
@@ -138,6 +177,16 @@ export function htmlResponse(html, opts = {}) {
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 }
+/**
+ * Serialize a value as a JSON literal safe to embed inside an inline
+ * `<script>` element. `JSON.stringify` already escapes quotes and backslashes;
+ * we additionally escape `<` (so `</script>`, `<!--`, and `<script` can't end
+ * or reopen the script) and the U+2028/U+2029 line separators that are illegal
+ * in older JS string literals. The result is valid JSON *and* valid JS.
+ */
+function jsonForScript(value) {
+    return JSON.stringify(value).replace(/[<\u2028\u2029]/g, (c) => ({ "<": "\\u003c", "\u2028": "\\u2028", "\u2029": "\\u2029" })[c]);
+}
 function scalarConfigurationAttr(specUrl, configuration) {
     if (!configuration)
         return "";

package/dist/index.d.ts

@@ -72,7 +72,7 @@ export type { RequestIdOptions, SecureHeadersOptions, CspDirectivesOptions, Cors
 export type { BearerAuthOptions, BearerAuthVerifyHook } from "./middleware.js";
 export { createLogger, noopLogger, DEFAULT_REDACT_KEYS } from "./logger.js";
 export type { Logger, LogLevel, ConsoleLoggerOptions, LoggerRedactionOptions, } from "./logger.js";
-export type { ScalarJsonPrimitive, ScalarJsonValue, ScalarReferenceConfiguration, ScalarTheme, DocsAssetOptions, } from "./docs.js";
+export type { ScalarJsonPrimitive, ScalarJsonValue, ScalarReferenceConfiguration, ScalarTheme, RedocConfiguration, RedocHtmlOptions, DocsAssetOptions, } from "./docs.js";
 export { formatStartupBanner, printStartupBanner } from "./banner.js";
 export type { StartupBannerLink, StartupBannerOptions } from "./banner.js";
 export { sseStream, sseResponse, ndjsonStream, ndjsonResponse, } from "./streaming.js";

package/dist/metrics.js

@@ -434,19 +434,22 @@ export function httpMetrics(opts) {
                     return "/";
                 }
             })();
-            // Always balance the in-flight gauge, even for excluded paths whose
-            // onRequest already incremented it.
             const started = START_TIMES.get(ctx.request);
             START_TIMES.delete(ctx.request);
+            // Only balance in-flight and record metrics when onRequest was actually
+            // called for this Request. Framework-synthesised contexts such as an OPTIONS
+            // preflight handled via preflightHooks (no registered OPTIONS route) invoke
+            // onSend without a prior groupHook onRequest, so started is undefined and
+            // decrementing the gauge would drive it negative.
+            if (started === undefined)
+                return;
             inFlight.dec();
             if (opts.exclude && opts.exclude(path))
                 return;
             const method = ctx.request.method.toUpperCase();
             const route = routeLabel(ctx);
             requests.inc({ method, route, status: res.status });
-            if (started !== undefined) {
-                duration.observe({ method, route }, (nowMs() - started) / 1000);
-            }
+            duration.observe({ method, route }, (nowMs() - started) / 1000);
         },
     };
 }

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:13d65a19-3d28-58c5-a6ec-e129e3a7ae94",
+  "serialNumber": "urn:uuid:deb5f2f9-6f46-5dd8-9ab5-2c301ddf6df0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-16T19:48:14.214Z",
+    "timestamp": "2026-06-17T18:06:01.531Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.38.3"
+        "version": "0.39.0"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.38.3",
+      "bom-ref": "pkg:npm/@daloyjs/core@0.39.0",
       "name": "@daloyjs/core",
-      "version": "0.38.3",
+      "version": "0.39.0",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@0.38.3",
+      "purl": "pkg:npm/@daloyjs/core@0.39.0",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.38.3",
+        "tagId": "swidtag--daloyjs-core-0.39.0",
         "name": "@daloyjs/core",
-        "version": "0.38.3",
+        "version": "0.39.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.38.3",
+      "ref": "pkg:npm/@daloyjs/core@0.39.0",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-0.38.3",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.38.3-13d65a19-3d28-58c5-a6ec-e129e3a7ae94",
+  "name": "@daloyjs/core-0.39.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.39.0-deb5f2f9-6f46-5dd8-9ab5-2c301ddf6df0",
   "creationInfo": {
-    "created": "2026-06-16T19:48:14.214Z",
+    "created": "2026-06-17T18:06:01.531Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.38.3",
+      "versionInfo": "0.39.0",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@0.38.3"
+          "referenceLocator": "pkg:npm/@daloyjs/core@0.39.0"
         }
       ]
     }

package/dist/tracing.js

@@ -86,8 +86,13 @@ export function otelTracing(opts) {
         if (url) {
             attrs["url.path"] = url.pathname;
             attrs["url.scheme"] = url.protocol.replace(/:$/, "");
-            if (url.host)
-                attrs["server.address"] = url.host;
+            // Per the OTel HTTP semantic conventions `server.address` is the host
+            // WITHOUT the port (which belongs in `server.port`), so derive both from
+            // `url.hostname`/`url.port` rather than `url.host` (which concatenates them).
+            if (url.hostname)
+                attrs["server.address"] = url.hostname;
+            if (url.port)
+                attrs["server.port"] = Number(url.port);
             if (url.search)
                 attrs["url.query"] = url.search.replace(/^\?/, "");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.38.3",
+  "version": "0.39.0",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
   "type": "module",
   "publishConfig": {