@daloyjs/core 1.0.0-rc.3 → 1.0.0-rc.5

package/README.md

@@ -22,7 +22,7 @@
 [![Security Responsible
 Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](https://github.com/daloyjs/daloy/blob/main/SECURITY.md)
 
-> A **runtime-portable TypeScript web framework** with built-in **contract-first routing**, **validation**, **OpenAPI (Hey API)**, **typed client generation**, **large-scale maintainability**, and **security-focused runtime plus supply-chain posture**.
+> The first TypeScript REST API framework built for secure AI-assisted services. DaloyJS combines runtime portability, contract-first OpenAPI, generated typed clients, zero-dependency runtime guardrails, and supply-chain-aware project defaults in one framework.
 
 **One-line API docs.** `new App({ openapi: { info: ... }, docs: true })` auto-mounts `GET /docs` (Scalar), `GET /openapi.json`, and `GET /openapi.yaml` — the same DX as FastAPI, without leaving TypeScript.
 
@@ -66,7 +66,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | **Portable supply-chain hardening** for the apps you build | [pnpm](https://pnpm.io/motivation) defaults + a zero-runtime-dep core | Hardened `.npmrc`, source-verified lockfiles, zero runtime deps, CycloneDX + SPDX SBOM, and npm provenance attestations.                                                                                  |
 
 ```
-framework test suite passing · ≥90% line + function coverage / ≥90% branch coverage · typechecks on TypeScript 6 with `strict: true`
+framework test suite passing · ≥90% line + function coverage / ≥90% branch coverage · typechecks on TypeScript 7 with `strict: true`
 runs on Node, Bun, Deno, Cloudflare, Vercel
 ~12.3M static-route ops/sec · ~1.5M dynamic-route ops/sec on M-class CPU
 ```
@@ -87,7 +87,7 @@ Each existing stack is excellent at one thing and forces tradeoffs everywhere el
 
 DaloyJS combines the wins:
 
-1. **Explicit contracts, minimal ceremony.** One `app.route({...})` is the source of truth for validation, types, OpenAPI, the typed client, and contract tests.
+1. **Explicit contracts, minimal ceremony.** One `app.get(path, contract, handler)` (or the matching shorthand, or `app.route({...})` for reusable contracts) is the source of truth for validation, types, OpenAPI, the typed client, and contract tests.
 2. **One source of truth for validation, typing, and docs** via [Standard Schema](https://github.com/standard-schema/standard-schema) — Zod 4 / Valibot / ArkType / TypeBox all work, no lock-in.
 3. **Portable core, optional runtime optimizations** — the only thing the core knows is `Request → Response`. Adapters live at the edge.
 4. **Security guardrails by default — bad defaults are bugs.** The core enforces body limits, prototype-pollution-safe JSON, path-traversal rejection, request timeouts, content-type checks, and RFC 9457 problem+json errors with prod-mode redaction. First-party middleware covers Helmet-grade headers, CORS, CSRF, rate limits, request ids, and signed-cookie sessions.
@@ -180,28 +180,64 @@ app.use(requestId());
 app.use(secureHeaders());
 app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 
-app.route({
-  method: "GET",
-  path: "/books/:id",
-  operationId: "getBookById",
-  tags: ["Books"],
-  request: { params: z.object({ id: z.string() }) },
-  responses: {
-    200: {
-      description: "Found",
-      body: z.object({ id: z.string(), title: z.string() }),
+app.get(
+  "/books/:id",
+  {
+    tags: ["Books"],
+    request: { params: z.object({ id: z.string() }) },
+    responses: {
+      200: {
+        description: "Found",
+        body: z.object({ id: z.string(), title: z.string() }),
+      },
+      404: { description: "Not found" },
     },
-    404: { description: "Not found" },
   },
-  handler: async ({ params }) => ({
+  async ({ params }) => ({
     status: 200,
     body: { id: params.id, title: `Book ${params.id}` },
   }),
-});
+);
 
 serve(app, { port: 3000 });
 ```
 
+For a concise route that keeps the full contract, use a method shorthand. The
+method and path produce a stable operation id (`getRoot` here), while the
+response schema preserves validation, OpenAPI, and data-exposure protection:
+
+```ts
+const app = new App().get(
+  "/",
+  { responses: { 200: { body: z.object({ hello: z.string() }) } } },
+  () => ({ status: 200, body: { hello: "world" } })
+);
+```
+
+There is intentionally no `app.get(path, handler)` form. If a streaming or
+proxy route genuinely needs to return a raw `Response`, declare a contract and
+set `acknowledgeNoResponseBodySchema: true`; otherwise DaloyJS fails closed
+rather than silently bypassing response-body validation. The same rule applies
+when `preBody` or `beforeHandle` short-circuits with a successful raw response;
+ordinary `4xx`/`5xx` hook denials remain secure by default without an opt-out.
+
+Add request schemas and other contract options as the endpoint grows:
+
+```ts
+app.post(
+  "/books",
+  {
+    request: { body: z.object({ title: z.string().min(1) }) },
+    responses: {
+      201: {
+        body: z.object({ id: z.string(), title: z.string() }),
+      },
+    },
+  },
+  ({ body }) => ({ status: 201, body: { id: "1", title: body.title } })
+);
+```
+
 ---
 
 ## OpenAPI + Hey API typed client
@@ -237,15 +273,32 @@ export default defineConfig({
 For TypeScript consumers in the same monorepo you can skip codegen entirely and use the **in-process typed client**:
 
 ```ts
-import { createClient } from "@daloyjs/core/client";
-const client = createClient(app, { baseUrl: "http://localhost:3000" });
+import { createInProcessClient } from "@daloyjs/core/client";
+const client = createInProcessClient(app);
 const r = await client.getBookById({ params: { id: "1" } });
 //    ^? { status: 200; body: { id: string; title: string } } | { status: 404; ... }
 ```
 
-> Method inference relies on **chaining** your `app.route(...)` calls (`new App().route(a).route(b)`) and letting
-> TypeScript infer the variable's type. A widening `const app: App` annotation, a `: App` factory return type, or
-> registering routes as separate statements erases the per-route types and collapses the client to an untyped surface.
+For multi-file applications, export each contract with `defineRoute()` and
+compose the literal tuple with `app.registerRoutes([...])`. This retains every
+operation across module boundaries:
+
+```ts
+import { App, defineRoute } from "@daloyjs/core";
+import { createInProcessClient } from "@daloyjs/core/client";
+import { listBooksRoute } from "./routes/list-books.js";
+import { getBookRoute } from "./routes/get-book.js";
+
+const app = new App().registerRoutes([listBooksRoute, getBookRoute] as const);
+const client = createInProcessClient(app); // typed, no socket or port
+```
+
+Chained `route()` calls remain supported. Avoid widening a composed app back to
+a bare `App` annotation, because that deliberately discards its route tuple.
+Callback-style `group()` and plugin `register()` provide runtime encapsulation,
+but TypeScript cannot widen the already-created parent variable from inside a
+callback. Export route tuples and compose them with `registerRoutes()` whenever
+the no-codegen client must include those module routes.
 
 ---
 
@@ -329,7 +382,10 @@ import { generateOpenAPI } from "@daloyjs/core/openapi";
 
 The UI is always contract-accurate — never stale. `create-daloy` templates opt in with `docs: true`.
 
-If you omit `openapi.info.title` / `info.version`, Daloy reads your project's `package.json` (`name`, `version`, `description`) automatically — no boilerplate. Deno projects without a `package.json` fall back to `deno.json` / `deno.jsonc`. Explicit values always win.
+If you omit `openapi.info`, the portable defaults are `DaloyJS API` / `0.0.0`.
+Set `openapi.info` (or the top-level `title`, `version`, and `description`) for
+real services. The core never reads the host filesystem, so the same docs
+bundle runs unchanged on Workers, Vercel, Bun, Deno, and Node.
 
 Prefer a factory? `createApp(options)` is exported as an alias of `new App(options)`.
 
@@ -418,15 +474,17 @@ for the full picture, plus the per-provider guides under [`/docs/auth`](https://
 
 ```text
 $ pnpm bench
-static route lookup        12,363,799 ops/sec
-dynamic 4-segment lookup    1,513,983 ops/sec
-miss                        4,763,878 ops/sec
+static route lookup         25,810,420 ops/sec
+dynamic 4-segment lookup     2,105,121 ops/sec
+miss                         7,742,635 ops/sec
 ```
 
-- Static (no-param) routes resolve via a single `Map.get` — **~12M ops/sec**.
+- After traversal checks, exact static routes resolve with an allocation-free
+  `Map.get` fast path — **~26M ops/sec**.
 - Dynamic routes walk a trie, **O(path-segments)** regardless of route count.
 - Body parsing is lazy and only runs when a route declares a body schema.
-- No regex on the hot path.
+- Path normalization and splitting use index/character scans rather than
+  regular expressions.
 
 ### Cold-start tip (serverless / edge)
 
@@ -465,13 +523,14 @@ Gate it in CI two ways: `daloy inspect --check <entry>` exits non-zero on any er
 const usersPlugin = {
   name: "users",
   register(app) {
-    app.route({
-      method: "GET",
-      path: "/me",
-      operationId: "me",
-      responses: { 200: { description: "ok" } },
-      handler: async () => ({ status: 200, body: { user: "alice" } }),
-    });
+    app.get(
+      "/me",
+      {
+        operationId: "me",
+        responses: { 200: { description: "ok" } },
+      },
+      async () => ({ status: 200, body: { user: "alice" } }),
+    );
   },
 };
 app.register(usersPlugin, { prefix: "/users", tags: ["Users"] });
@@ -515,7 +574,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.0.0-rc.3`**, a security-hardening release candidate. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before GA rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` GA onward, the API follows SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
+DaloyJS is at **`1.0.0-rc.5`**, a security-hardening release candidate. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before the stable release rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` stable onward, the API follows SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 
@@ -523,7 +582,10 @@ DaloyJS is at **`1.0.0-rc.3`**, a security-hardening release candidate. Because
 
 - 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 a choice of Scalar (default), Swagger UI, or Redoc via `docs.ui`, plus Scalar theming/custom CSS/auth defaults via `docs.scalar`, Swagger UI options via `docs.swagger` (including persisted Authorize credentials), Redoc options via `docs.redoc`, and a provider-neutral `docs.auth` launcher for local login routes or third-party OAuth2/OIDC providers.
-- Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
+- Filesystem-free OpenAPI metadata: explicit `openapi.info` / top-level metadata wins, with portable `DaloyJS API` / `0.0.0` fallbacks on every runtime.
+- Contract-required `get()` / `post()` / `put()` / `patch()` / `delete()` / `head()` shorthands with deterministic method+path operation IDs and the same validation, OpenAPI, response-exposure protection, and client typing as `route()`; there is no silent two-argument schema bypass.
+- Multi-file contract composition through `defineRoute()` + `app.registerRoutes([...])`, plus a typed `createInProcessClient(app)` that traverses the real pipeline without a socket.
+- Header/JWT/basic/mTLS authentication runs in the `preBody` phase before request-body I/O; body-aware WAF, idempotency, signature, and application middleware keep the validated `beforeHandle` phase.
 - 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`.
 - Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools (with `outputSchema`, `annotations`, and icons), resources, RFC 6570 resource templates, and prompts (with required-argument enforcement) over JSON-RPC 2.0 and validates `Origin` against DNS rebinding (with an `allowedOrigins` allowlist), while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes — with the JSON-RPC envelope schema surfaced in OpenAPI — for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app. Every `tools/call` argument is validated server-side against the tool's `inputSchema` (a dependency-free JSON-Schema subset — `type`/`required`/`properties`/`additionalProperties`/`enum`/`const`/bounds; exposed as `validateMcpInput()`) before the handler runs, rejecting a mismatch with JSON-RPC `-32602`; the JSON-RPC body is parsed with prototype-pollution-safe `safeJsonParse`; and an unauthenticated `mcpRoutes()` endpoint refuses to boot in production unless opted out with `mcpRoutes(path, handler, { public: true })`.
@@ -532,7 +594,7 @@ DaloyJS is at **`1.0.0-rc.3`**, a security-hardening release candidate. Because
 
 ### Runtimes and deployment
 
-- Adapters for Node (Heroku, Railway, Render, Fly.io), Bun, Deno, Cloudflare Workers, Vercel Node / Edge / Next.js / Netlify Edge, Fastly Compute, and AWS Lambda / Netlify Functions / Lambda Function URLs.
+- Adapters for Node (Heroku, Railway, Render, Fly.io), Bun, Deno, Cloudflare Workers, Vercel Node / Edge / Next.js / Netlify Edge, Fastly Compute, and AWS Lambda / Netlify Functions / Lambda Function URLs, including backpressure-safe Lambda response streaming via `toLambdaStreamHandler()`.
 - `daloy dev` watch loop delegates to the host runtime's native watcher (`node --watch`, `bun --hot`, or `deno run --watch`) with a `--runtime` override for cross-runtime `package.json` scripts.
 - `pnpm create daloy` scaffolder with Node, Bun, Deno, Cloudflare Worker, and Vercel templates, plus optional `--with-ci` GitHub Actions / Dependabot / CODEOWNERS / SECURITY.md hardening. The completion summary surfaces official install links (nodejs.org, pnpm.io, bun.sh) for any runtime or package manager your selections need but that is missing from `PATH`, and skips a doomed dependency install when the chosen package manager is absent.
 - Container-first templates: `HEALTHCHECK` to `/readyz`, `STOPSIGNAL SIGTERM`, non-root user, `tini` as PID 1.
@@ -600,9 +662,9 @@ 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()` / `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.
+- Built-in docs UI Subresource Integrity (SRI): the default Scalar / Swagger UI / Redoc / AsyncAPI assets use version-exact URLs with matching SHA-384 hashes and `crossorigin="anonymous"`, so a poisoned CDN asset cannot execute. `DocsAssetOptions` supports validated URL/hash overrides or self-hosting; malformed SRI values throw a `TypeError` instead of silently weakening the page. 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, a 2048-bit RSA modulus floor (NIST SP 800-131A, parity with the JWT verifier), 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.
+- `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`, a `maxCompressibleBytes` memory bound (default 1 MiB — larger responses stream uncompressed instead of buffering), 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).
 - `timing` / `timingSafeEqual` helpers.
 - `fileField({ magicBytes })` upload signature checks.
@@ -626,13 +688,13 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 
 - Plugin encapsulation (Fastify-style), decorators, structured logging, request-id propagation.
 - Lifecycle events: `onPluginInstalled`, `onShutdown`, `onClose`.
-- Connection-draining graceful shutdown with `Connection: close` on `503` and in-flight responses.
+- Connection-draining graceful shutdown with `Connection: close` on `503` and in-flight responses; the Node, Bun, and Deno adapters all wire it to `SIGTERM`/`SIGINT` by default.
 - `crashOnUnhandledRejection` default-on in production.
 - `app.healthcheck()` / `app.readinesscheck()` primitives with bearer-token auth and per-IP rate limit.
 - `disconnectStatusCode: 499` default for client-aborted requests.
 - `defineConfig({ schema, source })` boot-time typed configuration validation.
 - `app({ behindProxy })` declarative model (replaces `trustProxy`); `behindProxy.hops` collapses to the `(N+1)`-from-rightmost slot.
-- Adapter-independent `ConnInfo` abstraction: `getConnInfo()`, lazy `ctx.remoteAddress`, `ctx.remotePort`.
+- Adapter-independent `ConnInfo` abstraction: `getConnInfo()`, lazy `ctx.remoteAddress`, `ctx.remotePort` — populated by the Node, Bun, Deno, and Lambda adapters from the real peer socket / event source, never from spoofable headers.
 - `daloy doctor` production-posture validator with `--audit-secrets` and `--audit-defaults` (flags wildcard-credentials CORS, > 24h CORS `maxAge`, > 25 MiB blanket body limits, zero `idleTimeoutMs` in production, and unsafe opt-ins).
 - PSL-aware `subdomains()` helper with a `≤ 90 days` snapshot guard.
 - Secure-by-default multitenancy via `tenancy()` + `tenantScope()`: pluggable tenant resolution (subdomain / header / path / JWT claim / custom), refuse-unresolved + format-validated ids + no-enumeration `404` by default, and a key helper that partitions `rateLimit` / `concurrencyLimit` / `idempotency` / `responseCache` per tenant.

package/dist/adapters/bun.d.ts

@@ -2,7 +2,8 @@
  * Bun adapter — `Bun.serve` already speaks web-standard fetch,
  * so this is the smallest possible wrapper. The adapter passes through the
  * commonly-needed modern `Bun.serve` options (`idleTimeout`, `tls`,
- * `development`, `unix`) and exposes the server's `url` for ergonomic logging.
+ * `development`, `unix`), exposes the server's `url` for ergonomic logging,
+ * and wires graceful shutdown to SIGTERM/SIGINT like the Node adapter.
  */
 import type { App } from "../app.js";
 /** TLS material accepted by Bun's `serve({ tls })` option. */
@@ -32,6 +33,23 @@ export interface BunServeOptions {
     unix?: string;
     /** When supplied, Bun.serve listens on HTTPS. */
     tls?: BunTLSOptions;
+    /**
+     * Drain timeout in ms passed to {@link App.shutdown} during graceful
+     * shutdown (signal-triggered or via `stop()`). Default: 10000.
+     *
+     * @since 1.0.0
+     */
+    shutdownTimeoutMs?: number;
+    /**
+     * Listen for SIGTERM/SIGINT and shut down gracefully (drain
+     * {@link App.shutdown} hooks, then stop the Bun server and exit). Matches
+     * the Node and Deno adapters so rolling deploys under Kubernetes/systemd
+     * do not hard-kill in-flight requests. Set `false` to manage signals
+     * yourself. Default: true.
+     *
+     * @since 1.0.0
+     */
+    handleSignals?: boolean;
 }
 /** Handle returned by {@link serve} for shutdown and listener introspection. */
 export interface BunServerHandle {
@@ -39,7 +57,7 @@ export interface BunServerHandle {
     port: number;
     /** Server URL as reported by `Bun.serve` (e.g. for startup logging), if available. */
     url: URL | undefined;
-    /** Graceful stop: drains {@link App.shutdown} hooks first, then force-stops the Bun server. */
+    /** Graceful stop: drains {@link App.shutdown} hooks first, then force-stops the Bun server. Idempotent. */
     stop: () => Promise<void>;
 }
 /**

package/dist/adapters/bun.js

@@ -1,3 +1,4 @@
+import { setConnInfo } from "../conn-info.js";
 import { WS_READY_STATE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, encodeSendPayload, parseSubprotocols, validateSelectedSubprotocol, checkWebSocketOrigin, WebSocketProtocolError, } from "../websocket.js";
 /**
  * Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes.
@@ -12,16 +13,34 @@ export function serve(app, opts = {}) {
     if (!Bun?.serve)
         throw new Error("Bun runtime not detected");
     const hasWs = app.webSocketRoutes.size > 0;
+    const servesTls = opts.tls !== undefined;
+    // Fulfil the conn-info contract with the immediate TCP peer from Bun's
+    // native `server.requestIP()`, so `getConnInfo` / `resolveClientIp` /
+    // `behindProxy` work on Bun. Never derived from spoofable headers.
+    const tagConnInfo = (req, server) => {
+        const ip = server?.requestIP?.(req);
+        if (ip) {
+            setConnInfo(req, {
+                remoteAddress: ip.address,
+                remotePort: ip.port,
+                tls: servesTls,
+            });
+        }
+    };
     const cfg = {
         maxRequestBodySize: opts.maxRequestBodySize ?? 16 * 1024 * 1024,
         fetch: hasWs
             ? (req, server) => {
+                tagConnInfo(req, server);
                 if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
                     return tryBunUpgrade(app, req, server);
                 }
                 return app.fetch(req);
             }
-            : (req) => app.fetch(req),
+            : (req, server) => {
+                tagConnInfo(req, server);
+                return app.fetch(req);
+            },
         error: (err) => {
             // Last-resort handler reached only if app.fetch itself throws (it
             // normally catches everything). Log the error server-side but never
@@ -54,13 +73,30 @@ export function serve(app, opts = {}) {
     if (opts.tls)
         cfg.tls = opts.tls;
     const server = Bun.serve(cfg);
+    let stopped = false;
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        await app.shutdown(opts.shutdownTimeoutMs ?? 10_000);
+        server.stop(true);
+    };
+    if (opts.handleSignals !== false) {
+        // Parity with the Node/Deno adapters: without this, SIGTERM on a rolling
+        // deploy hard-kills the process — in-flight requests are dropped and
+        // `onShutdown`/`onClose` hooks never run. Bun implements Node's
+        // `process` signal events, so the same wiring works.
+        const onSignal = (sig) => {
+            app.log.info({ sig }, "DaloyJS received signal, shutting down");
+            void stop().then(() => process.exit(0));
+        };
+        process.once("SIGTERM", () => onSignal("SIGTERM"));
+        process.once("SIGINT", () => onSignal("SIGINT"));
+    }
     return {
         port: server.port,
         url: server.url,
-        stop: async () => {
-            await app.shutdown();
-            server.stop(true);
-        },
+        stop,
     };
 }
 async function tryBunUpgrade(app, req, server) {

package/dist/adapters/deno.js

@@ -1,3 +1,4 @@
+import { setConnInfo } from "../conn-info.js";
 /**
  * Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring.
  *
@@ -25,7 +26,21 @@ export function serve(app, opts = {}) {
         init.onListen = opts.onListen;
     if (opts.onError)
         init.onError = opts.onError;
-    const server = denoServe(init, (req) => app.fetch(req));
+    const servesTls = Boolean(opts.cert && opts.key);
+    const server = denoServe(init, (req, info) => {
+        // Fulfil the conn-info contract with the immediate TCP peer from
+        // `Deno.serve`'s handler info, so `getConnInfo` / `resolveClientIp` /
+        // `behindProxy` work on Deno. Never derived from spoofable headers.
+        const addr = info?.remoteAddr;
+        if (addr?.hostname !== undefined) {
+            setConnInfo(req, {
+                remoteAddress: addr.hostname,
+                remotePort: addr.port,
+                tls: servesTls,
+            });
+        }
+        return app.fetch(req);
+    });
     const onSignal = () => {
         void shutdown();
     };
@@ -46,13 +61,15 @@ export function serve(app, opts = {}) {
         }
         // Drain app-level hooks first (while the HTTP server can still respond),
         // then ask Deno to stop gracefully — `server.shutdown()` stops accepting
-        // new connections and lets in-flight requests finish. Aborting the listen
-        // signal happens last, purely as a safety net for runtimes that lack
-        // `HttpServer.shutdown()`. Doing it the other way around (aborting first)
-        // tears the listener down before in-flight requests can complete.
+        // new connections and lets in-flight requests finish. Abort only as a
+        // fallback for runtimes that lack `HttpServer.shutdown()`: Deno 2.9 closes
+        // the listener resource inside shutdown(), so aborting the same signal
+        // afterwards throws BadResource.
         await app.shutdown(opts.shutdownTimeoutMs ?? 10_000);
-        await server.shutdown?.();
-        controller.abort();
+        if (server.shutdown)
+            await server.shutdown();
+        else
+            controller.abort();
     };
     return { shutdown };
 }

package/dist/adapters/lambda.d.ts

@@ -29,10 +29,13 @@ export interface LambdaEventV1 {
     queryStringParameters?: Record<string, string | undefined> | null;
     /** Query parameters with every value per name; preferred over the single-value map. */
     multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
-    /** Request context; `domainName` is the host fallback and `path` the path fallback. */
+    /** Request context; `domainName` is the host fallback, `path` the path fallback, and `identity.sourceIp` the caller address seen by API Gateway. */
     requestContext?: {
         domainName?: string;
         path?: string;
+        identity?: {
+            sourceIp?: string;
+        };
     };
     /** Raw request body; base64-encoded when {@link LambdaEventV1.isBase64Encoded} is true. */
     body?: string;
@@ -51,11 +54,12 @@ export interface LambdaEventV2 {
     headers?: Record<string, string | undefined>;
     /** Request cookies as individual strings; re-joined with `; ` into a `cookie` header. */
     cookies?: string[];
-    /** Request context; `http.method`/`http.path` carry the method and path, `domainName` the host fallback. */
+    /** Request context; `http.method`/`http.path` carry the method and path, `http.sourceIp` the caller address, `domainName` the host fallback. */
     requestContext?: {
         http?: {
             method?: string;
             path?: string;
+            sourceIp?: string;
         };
         domainName?: string;
     };
@@ -100,10 +104,63 @@ export interface LambdaResponseV2 {
 export type LambdaResponse = LambdaResponseV1 | LambdaResponseV2;
 /** Async handler shape consumed by AWS Lambda / Netlify Functions runtimes. */
 export type LambdaHandler = (event: LambdaEvent) => Promise<LambdaResponse>;
+/**
+ * Writable response stream supplied to a response-streaming AWS Lambda handler.
+ *
+ * The contract intentionally models only the Node.js writable-stream methods
+ * used by DaloyJS, keeping the adapter free of Node-only imports while still
+ * respecting backpressure.
+ */
+export interface LambdaResponseStream {
+    /** Writes one response chunk and returns false when the producer must wait for `drain`. */
+    write(chunk: Uint8Array): boolean;
+    /** Ends the response after every previously written chunk has flushed. */
+    end(): void;
+    /** Registers a one-shot writable-stream event listener. */
+    once(event: "drain", listener: () => void): this;
+    /** Registers a one-shot writable-stream error listener. */
+    once(event: "error", listener: (error: Error) => void): this;
+    /** Removes a previously registered drain listener when supported. */
+    off?(event: "drain", listener: () => void): this;
+    /** Removes a previously registered error listener when supported. */
+    off?(event: "error", listener: (error: Error) => void): this;
+    /** Resolves when AWS has flushed the ended response stream, when provided by the runtime. */
+    finished?(): Promise<void>;
+}
+/** HTTP response metadata accepted by `awslambda.HttpResponseStream.from()`. */
+export interface LambdaStreamMetadata {
+    /** HTTP response status code. */
+    statusCode: number;
+    /** Single-value response headers, excluding `set-cookie`. */
+    headers: Record<string, string>;
+    /** Multi-value response headers, used to preserve every `set-cookie` value. */
+    multiValueHeaders?: Record<string, string[]>;
+}
+/** Async response-streaming handler shape consumed by the AWS Lambda Node.js runtime. */
+export type LambdaStreamHandler = (event: LambdaEvent, responseStream: LambdaResponseStream, context?: unknown) => Promise<void>;
 /**
  * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
  *
+ * A malformed event (e.g. a `Host`/path combination that cannot form a valid
+ * URL) is answered with a clean `400` problem+json instead of throwing out of
+ * the handler, which API Gateway would otherwise surface as an opaque `502`.
+ *
  * @param app - The DaloyJS {@link App} that serves each translated request.
  * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
  */
 export declare function toLambdaHandler(app: App): LambdaHandler;
+/**
+ * Wrap an {@link App} as an AWS Lambda response-streaming handler.
+ *
+ * The returned handler is decorated with the managed Node.js runtime's
+ * `awslambda.streamifyResponse()` helper, attaches status/headers with
+ * `HttpResponseStream.from()`, and pumps the web-standard response body while
+ * honoring writable-stream backpressure. The function throws during startup
+ * outside an AWS Lambda Node.js runtime so an accidentally buffered or broken
+ * deployment cannot start silently.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A response-streaming Lambda handler for Function URLs, API Gateway streaming proxy integrations, or `InvokeWithResponseStream`.
+ * @throws {Error} If the AWS Lambda response-streaming globals are unavailable.
+ */
+export declare function toLambdaStreamHandler(app: App): LambdaStreamHandler;