@daloyjs/core 1.0.0-rc.4 → 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
 ```
@@ -474,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)
 
@@ -572,7 +574,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.0.0-rc.4`**, 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.
+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.
 
@@ -592,7 +594,7 @@ DaloyJS is at **`1.0.0-rc.4`**, 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.
@@ -662,7 +664,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `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): 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.
@@ -686,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;

package/dist/adapters/lambda.js

@@ -1,17 +1,56 @@
+import { setConnInfo } from "../conn-info.js";
 const TEXT_TYPE_RE = /^(text\/|application\/(json|xml|javascript|x-www-form-urlencoded|.*\+json|.*\+xml))/i;
 /**
  * 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 function toLambdaHandler(app) {
     return async (event) => {
-        const request = eventToRequest(event);
+        let request;
+        try {
+            request = eventToRequest(event);
+        }
+        catch {
+            return responseToLambda(badRequestResponse(), isV2Event(event));
+        }
         const response = await app.fetch(request);
         return responseToLambda(response, isV2Event(event));
     };
 }
+/**
+ * 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 function toLambdaStreamHandler(app) {
+    const runtime = lambdaStreamingRuntime();
+    return runtime.streamifyResponse(async (event, rawStream) => {
+        let request;
+        try {
+            request = eventToRequest(event);
+        }
+        catch {
+            await streamLambdaResponse(badRequestResponse(), rawStream, runtime);
+            return;
+        }
+        await streamLambdaResponse(await app.fetch(request), rawStream, runtime);
+    });
+}
 function eventToRequest(event) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(event.headers ?? {})) {
@@ -28,35 +67,37 @@ function eventToRequest(event) {
     }
     if ("cookies" in event && event.cookies?.length)
         headers.set("cookie", event.cookies.join("; "));
-    const method = isV2Event(event) ? event.requestContext?.http?.method ?? "GET" : event.httpMethod ?? "GET";
+    const method = isV2Event(event)
+        ? (event.requestContext?.http?.method ?? "GET")
+        : (event.httpMethod ?? "GET");
     const rawPath = isV2Event(event)
-        ? event.rawPath ?? event.requestContext?.http?.path ?? "/"
-        : event.path ?? event.requestContext?.path ?? "/";
+        ? (event.rawPath ?? event.requestContext?.http?.path ?? "/")
+        : (event.path ?? event.requestContext?.path ?? "/");
     const host = headers.get("host") ?? event.requestContext?.domainName ?? "localhost";
     const proto = headers.get("x-forwarded-proto") ?? "https";
-    const rawQueryString = isV2Event(event) ? event.rawQueryString ?? "" : queryStringForV1(event);
+    const rawQueryString = isV2Event(event) ? (event.rawQueryString ?? "") : queryStringForV1(event);
     const qs = rawQueryString ? `?${rawQueryString}` : "";
     const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
     const url = `${proto}://${host}${path}${qs}`;
     const init = { method, headers };
     if (method !== "GET" && method !== "HEAD" && event.body != null) {
-        init.body = event.isBase64Encoded
-            ? base64ToBytes(event.body)
-            : event.body;
+        init.body = event.isBase64Encoded ? base64ToBytes(event.body) : event.body;
+    }
+    const request = new Request(url, init);
+    // Fulfil the conn-info contract with the caller address API Gateway saw
+    // (v2: `requestContext.http.sourceIp`, v1: `requestContext.identity.sourceIp`),
+    // so `getConnInfo` / `resolveClientIp` work on Lambda. API Gateway and
+    // Function URLs only serve TLS.
+    const sourceIp = isV2Event(event)
+        ? event.requestContext?.http?.sourceIp
+        : event.requestContext?.identity?.sourceIp;
+    if (sourceIp) {
+        setConnInfo(request, { remoteAddress: sourceIp, tls: true });
     }
-    return new Request(url, init);
+    return request;
 }
 async function responseToLambda(res, useV2Response) {
-    const headers = {};
-    const getSetCookie = res.headers.getSetCookie;
-    const cookies = typeof getSetCookie === "function"
-        ? getSetCookie.call(res.headers)
-        : cookieFallback(res.headers);
-    res.headers.forEach((value, key) => {
-        if (key.toLowerCase() === "set-cookie")
-            return;
-        headers[key] = value;
-    });
+    const { headers, cookies } = responseHeaders(res);
     const contentType = res.headers.get("content-type") ?? "";
     const isText = TEXT_TYPE_RE.test(contentType);
     let body = "";
@@ -87,7 +128,10 @@ async function responseToLambda(res, useV2Response) {
 }
 function isV2Event(event) {
     const requestContext = event.requestContext;
-    return event.version === "2.0" || "rawPath" in event || "rawQueryString" in event || !!requestContext?.http;
+    return (event.version === "2.0" ||
+        "rawPath" in event ||
+        "rawQueryString" in event ||
+        !!requestContext?.http);
 }
 function queryStringForV1(event) {
     const values = new URLSearchParams();
@@ -107,6 +151,78 @@ function cookieFallback(headers) {
     const cookie = headers.get("set-cookie");
     return cookie ? [cookie] : [];
 }
+function responseHeaders(res) {
+    const headers = {};
+    const getSetCookie = res.headers.getSetCookie;
+    const cookies = typeof getSetCookie === "function"
+        ? getSetCookie.call(res.headers)
+        : cookieFallback(res.headers);
+    res.headers.forEach((value, key) => {
+        if (key.toLowerCase() !== "set-cookie")
+            headers[key] = value;
+    });
+    return { headers, cookies };
+}
+function badRequestResponse() {
+    return Response.json({
+        type: "https://daloyjs.dev/errors/bad-request",
+        title: "Bad Request",
+        status: 400,
+    }, { status: 400, headers: { "content-type": "application/problem+json" } });
+}
+function lambdaStreamingRuntime() {
+    const runtime = globalThis
+        .awslambda;
+    if (!runtime ||
+        typeof runtime.streamifyResponse !== "function" ||
+        typeof runtime.HttpResponseStream?.from !== "function") {
+        throw new Error("AWS Lambda response streaming runtime not detected; toLambdaStreamHandler requires the managed Node.js awslambda globals");
+    }
+    return runtime;
+}
+async function streamLambdaResponse(response, rawStream, runtime) {
+    const { headers, cookies } = responseHeaders(response);
+    const metadata = { statusCode: response.status, headers };
+    if (cookies.length)
+        metadata.multiValueHeaders = { "set-cookie": cookies };
+    const responseStream = runtime.HttpResponseStream.from(rawStream, metadata);
+    if (response.body) {
+        const reader = response.body.getReader();
+        try {
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                if (!responseStream.write(chunk.value))
+                    await waitForDrain(responseStream);
+            }
+        }
+        catch (error) {
+            await reader.cancel(error).catch(() => undefined);
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    responseStream.end();
+    if (responseStream.finished)
+        await responseStream.finished();
+}
+function waitForDrain(stream) {
+    return new Promise((resolve, reject) => {
+        const onDrain = () => {
+            stream.off?.("error", onError);
+            resolve();
+        };
+        const onError = (error) => {
+            stream.off?.("drain", onDrain);
+            reject(error);
+        };
+        stream.once("drain", onDrain);
+        stream.once("error", onError);
+    });
+}
 function base64ToBytes(b64) {
     const binary = atob(b64);
     const bytes = new Uint8Array(binary.length);

package/dist/adapters/node.d.ts

@@ -76,7 +76,14 @@ export interface NodeServerOptions {
 export interface NodeServerHandle {
     /** The underlying `node:http` `Server` instance, for advanced wiring (extra listeners, address introspection). */
     server: Server;
-    /** Port the server was asked to listen on ({@link NodeServerOptions.port}, default `3000`). */
+    /**
+     * Bound TCP port once the server emits `listening`.
+     *
+     * Before the listener is ready, this is the requested
+     * {@link NodeServerOptions.port} (default `3000`). In particular, callers
+     * using `port: 0` must await the server's `listening` event before reading
+     * this property to receive the OS-assigned ephemeral port.
+     */
     port: number;
     /** Graceful shutdown: drains {@link App.shutdown} hooks, destroys WebSocket sockets, then closes the server. Idempotent. */
     close(): Promise<void>;