@nifrajs/aws-lambda 2.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @nifrajs/aws-lambda
+
+AWS Lambda adapter for nifra - API Gateway HTTP API (payload v2) and Lambda Function URLs, buffered or streaming, with post-decode body limits and single-site header merging. Dependency-free.
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+## Install
+
+```sh
+bun add @nifrajs/aws-lambda
+```
+
+## Use
+
+```ts
+// handler.ts - one app per container, built at module scope
+import { handle, streamHandle, type LambdaEnv } from "@nifrajs/aws-lambda"
+import { server } from "@nifrajs/core"
+
+const app = server<LambdaEnv>()
+  .get("/", (c) => c.json({ ip: c.clientIp, requestId: c.env.context?.awsRequestId }))
+
+export const handler = handle(app) // API Gateway HTTP API (v2) + Function URLs
+// or, on a Function URL with InvokeMode: RESPONSE_STREAM:
+// export const handler = streamHandle(app)
+```
+
+How it holds the line:
+
+- **Post-decode body limits.** The body is decoded (base64 or UTF-8) and its real `byteLength` checked against `maxBodyBytes` (default 1,000,000 - match your app's setting if you changed it) *before* a `Request` is constructed. The event's own length claims are never trusted; over the limit answers a flat `413`.
+- **One header merge site.** Request headers come from the v2 `headers` map plus the separate `cookies` array in exactly one function; the array is canonical, so a `cookie` key smuggled into `headers` never reaches the app. Response `Set-Cookie` values travel in the result's `cookies` array, one entry each - never comma-joined.
+- **Base64 honesty.** Response `isBase64Encoded` is decided by a strict UTF-8 decode of the actual bytes, never by content-type guessing. Binary round-trips exactly; text ships as text.
+- **Client IP.** `event.requestContext.http.sourceIp` feeds core's client-IP seam; `X-Forwarded-For` trust stays where it belongs, in the app's `clientIp` server option.
+- **Flat errors.** Uncaught failures collapse to the same `{"ok":false,"error":"internal_error"}` 500 as every other nifra runtime - the event is never echoed.
+- **Freeze-safe `waitUntil`.** Background work settles before the handler returns, so Lambda's container freeze cannot strand it.
+
+The event and invocation context ride on `c.env.event` / `c.env.context` (type your app `server<LambdaEnv>()`). REST APIs (payload v1) and ALB events are out of scope; API Gateway does not support response streaming - `streamHandle` is for Function URLs.
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * AWS Lambda adapter for nifra - runs an app behind API Gateway HTTP APIs (payload format v2) and
+ * Lambda Function URLs (the same v2 shape), buffered via {@link handle} or streamed via
+ * {@link streamHandle}. REST APIs (payload v1) and ALB events are out of scope.
+ *
+ * Security posture, by construction:
+ * - Request headers are assembled from the event in exactly one place ({@link requestHeaders}):
+ *   the `headers` map plus the separate `cookies` array. There is no second merge site, and the
+ *   `cookies` array is canonical - a `cookie` key smuggled into `headers` never reaches the app.
+ * - The body is decoded first (base64 or UTF-8) and its real `byteLength` checked against
+ *   `maxBodyBytes` *before* a `Request` is constructed. The event's own claims about length -
+ *   `content-length` or the encoded size - are never trusted.
+ * - Response `isBase64Encoded` is decided by what the bytes actually are (strict UTF-8 decode),
+ *   never by content-type guessing.
+ * - Uncaught errors become the same flat `internal_error` 500 as every other nifra runtime; the
+ *   event is never echoed.
+ *
+ * The adapter is dependency-free: it accepts anything with a fetch-shaped `fetch` method and
+ * declares the Lambda event/`awslambda` shapes structurally.
+ */
+/** Platform fields the adapter feeds into `app.fetch` (mirrors nifra core's `Platform`). */
+export interface LambdaPlatform {
+    readonly env: LambdaEnv;
+    readonly clientIp?: string | undefined;
+    readonly waitUntil?: (promise: Promise<unknown>) => void;
+}
+/** Anything with a fetch-shaped entry point - a nifra `server()` app satisfies this. */
+export interface FetchHandler {
+    fetch(request: Request, platform?: LambdaPlatform): Response | Promise<Response>;
+}
+/**
+ * The slice of an API Gateway HTTP API / Function URL payload-v2 event the adapter reads.
+ * Extra fields pass through untouched on `c.env.event`.
+ */
+export interface LambdaEvent {
+    readonly rawPath?: string;
+    readonly rawQueryString?: string;
+    readonly headers?: Readonly<Record<string, string | undefined>>;
+    /** Payload v2 delivers cookies here, not in `headers` - this array is the canonical source. */
+    readonly cookies?: readonly string[];
+    readonly body?: string | null;
+    readonly isBase64Encoded?: boolean;
+    readonly requestContext?: {
+        readonly domainName?: string;
+        readonly http?: {
+            readonly method?: string;
+            readonly sourceIp?: string;
+        };
+    };
+}
+/** The Lambda invocation context. The adapter only forwards it; declare fields structurally. */
+export interface LambdaContext {
+    readonly awsRequestId?: string;
+    readonly functionName?: string;
+    readonly [key: string]: unknown;
+}
+/** What handlers see as `c.env` (declare your app as `server<LambdaEnv>()` for typed access). */
+export interface LambdaEnv {
+    readonly event: LambdaEvent;
+    readonly context: LambdaContext | undefined;
+}
+/** A payload-v2 result object, as API Gateway and Function URLs consume it. */
+export interface LambdaResult {
+    statusCode: number;
+    headers: Record<string, string>;
+    /** `Set-Cookie` values travel here (payload v2), one entry per cookie - never comma-joined. */
+    cookies?: string[];
+    body: string;
+    isBase64Encoded: boolean;
+}
+export interface LambdaOptions {
+    /**
+     * Reject request bodies whose *decoded* size exceeds this many bytes with a flat 413 before a
+     * `Request` is constructed. Defaults to 1,000,000 (nifra core's default). Set it to match your
+     * app's `maxBodyBytes` if you customized that.
+     */
+    readonly maxBodyBytes?: number;
+}
+/** The Node `Writable`-shaped stream Lambda hands a streaming handler. Declared structurally. */
+export interface ResponseStream {
+    write(chunk: Uint8Array | string): unknown;
+    end(): unknown;
+    once?(event: string, listener: () => void): unknown;
+}
+/**
+ * A buffered Lambda handler for API Gateway HTTP APIs (payload v2) and Function URLs.
+ *
+ * ```ts
+ * import { handle } from "@nifrajs/aws-lambda"
+ * import { app } from "./app.js" // built once per container, at module scope
+ *
+ * export const handler = handle(app)
+ * ```
+ */
+export declare function handle(app: FetchHandler, options?: LambdaOptions): (event: LambdaEvent, context?: LambdaContext) => Promise<LambdaResult>;
+/**
+ * A streaming Lambda handler for Function URLs with `InvokeMode: RESPONSE_STREAM`, via the
+ * runtime's `awslambda.streamifyResponse`. Response bytes flow as the app produces them - no
+ * buffering, no base64. Requires the managed AWS Lambda Node runtime (the `awslambda` global);
+ * API Gateway does not support response streaming - use {@link handle} there.
+ */
+export declare function streamHandle(app: FetchHandler, options?: LambdaOptions): (event: LambdaEvent, responseStream: ResponseStream, context?: LambdaContext) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,224 @@
+/**
+ * AWS Lambda adapter for nifra - runs an app behind API Gateway HTTP APIs (payload format v2) and
+ * Lambda Function URLs (the same v2 shape), buffered via {@link handle} or streamed via
+ * {@link streamHandle}. REST APIs (payload v1) and ALB events are out of scope.
+ *
+ * Security posture, by construction:
+ * - Request headers are assembled from the event in exactly one place ({@link requestHeaders}):
+ *   the `headers` map plus the separate `cookies` array. There is no second merge site, and the
+ *   `cookies` array is canonical - a `cookie` key smuggled into `headers` never reaches the app.
+ * - The body is decoded first (base64 or UTF-8) and its real `byteLength` checked against
+ *   `maxBodyBytes` *before* a `Request` is constructed. The event's own claims about length -
+ *   `content-length` or the encoded size - are never trusted.
+ * - Response `isBase64Encoded` is decided by what the bytes actually are (strict UTF-8 decode),
+ *   never by content-type guessing.
+ * - Uncaught errors become the same flat `internal_error` 500 as every other nifra runtime; the
+ *   event is never echoed.
+ *
+ * The adapter is dependency-free: it accepts anything with a fetch-shaped `fetch` method and
+ * declares the Lambda event/`awslambda` shapes structurally.
+ */
+const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const assertBodyLimit = (value) => {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError("maxBodyBytes must be a non-negative safe integer");
+};
+const TEXT_ENCODER = new TextEncoder();
+// `fatal` makes invalid UTF-8 throw (the base64 signal); `ignoreBOM` keeps a leading BOM in the
+// decoded string so a clean decode always re-encodes byte-identically - the honesty invariant.
+const UTF8_STRICT = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const nodeBuffer = globalThis.Buffer;
+const fromBase64 = (data) => {
+    if (nodeBuffer !== undefined)
+        return nodeBuffer.from(data, "base64");
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+};
+const toBase64 = (bytes) => {
+    if (nodeBuffer !== undefined)
+        return nodeBuffer.from(bytes).toString("base64");
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+};
+/**
+ * The single place request headers come from. Payload v2 pre-joins repeated headers with commas in
+ * `headers` and moves cookies into the `cookies` array; that array is set last, unconditionally,
+ * so it is canonical even against an event that (out of spec) also carries a `cookie` header.
+ */
+const requestHeaders = (event) => {
+    const headers = new Headers();
+    if (event.headers !== undefined) {
+        for (const [name, value] of Object.entries(event.headers)) {
+            if (value !== undefined)
+                headers.set(name, value);
+        }
+    }
+    if (event.cookies !== undefined && event.cookies.length > 0) {
+        headers.set("cookie", event.cookies.join("; "));
+    }
+    else {
+        headers.delete("cookie");
+    }
+    return headers;
+};
+const flatError = (status, code) => new Response(`{"ok":false,"error":"${code}"}`, {
+    status,
+    headers: { "content-type": "application/json" },
+});
+/**
+ * Build the `Request`, or a flat error `Response` when the event must be rejected before the app
+ * runs. The body is decoded and measured first - a 413 here means no `Request` ever existed.
+ */
+const toRequest = (event, maxBodyBytes) => {
+    const method = event.requestContext?.http?.method ?? "GET";
+    const headers = requestHeaders(event);
+    const authority = event.requestContext?.domainName ?? headers.get("host") ?? "localhost";
+    const path = event.rawPath !== undefined && event.rawPath !== "" ? event.rawPath : "/";
+    const query = event.rawQueryString !== undefined && event.rawQueryString !== ""
+        ? `?${event.rawQueryString}`
+        : "";
+    const url = `https://${authority}${path}${query}`;
+    let body;
+    if (event.body !== undefined && event.body !== null && method !== "GET" && method !== "HEAD") {
+        body = event.isBase64Encoded === true ? fromBase64(event.body) : TEXT_ENCODER.encode(event.body);
+        if (body.byteLength > maxBodyBytes)
+            return flatError(413, "payload_too_large");
+    }
+    return body === undefined
+        ? new Request(url, { method, headers })
+        : new Request(url, { method, headers, body });
+};
+/**
+ * Response headers as a plain object for the v2 result, with `set-cookie` split out into the
+ * `cookies` array (comma-joining cookies corrupts them) and `content-length` dropped - the
+ * transport owns framing, and a stale length from before base64 re-encoding must not survive.
+ */
+const resultHeaders = (response) => {
+    const headers = {};
+    for (const [name, value] of response.headers) {
+        if (name === "set-cookie" || name === "content-length")
+            continue;
+        headers[name] = value;
+    }
+    return { headers, cookies: response.headers.getSetCookie() };
+};
+const toResult = async (response) => {
+    const { headers, cookies } = resultHeaders(response);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    let body;
+    let isBase64Encoded;
+    try {
+        body = UTF8_STRICT.decode(bytes);
+        isBase64Encoded = false;
+    }
+    catch {
+        body = toBase64(bytes);
+        isBase64Encoded = true;
+    }
+    const result = { statusCode: response.status, headers, body, isBase64Encoded };
+    if (cookies.length > 0)
+        result.cookies = cookies;
+    return result;
+};
+const INTERNAL_ERROR = () => flatError(500, "internal_error");
+/** Run the app for one event. Never throws: failures collapse to the flat 500. */
+const invoke = async (app, event, context, maxBodyBytes) => {
+    const pending = [];
+    try {
+        const built = toRequest(event, maxBodyBytes);
+        if (built instanceof Response)
+            return { response: built, pending };
+        const response = await app.fetch(built, {
+            env: { event, context },
+            clientIp: event.requestContext?.http?.sourceIp,
+            waitUntil: (promise) => {
+                pending.push(promise);
+            },
+        });
+        return { response, pending };
+    }
+    catch {
+        return { response: INTERNAL_ERROR(), pending };
+    }
+};
+// Background work must settle before the handler returns - Lambda freezes the container the
+// moment it does, so a fire-and-forget promise would silently stall until (maybe) the next
+// invocation thaws it. `allSettled` so a failed background task cannot corrupt the response.
+const settle = (pending) => pending.length > 0 ? Promise.allSettled(pending) : undefined;
+/**
+ * A buffered Lambda handler for API Gateway HTTP APIs (payload v2) and Function URLs.
+ *
+ * ```ts
+ * import { handle } from "@nifrajs/aws-lambda"
+ * import { app } from "./app.ts" // built once per container, at module scope
+ *
+ * export const handler = handle(app)
+ * ```
+ */
+export function handle(app, options = {}) {
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    assertBodyLimit(maxBodyBytes);
+    return async (event, context) => {
+        const { response, pending } = await invoke(app, event, context, maxBodyBytes);
+        try {
+            const result = await toResult(response);
+            await settle(pending);
+            return result;
+        }
+        catch {
+            await settle(pending);
+            return {
+                statusCode: 500,
+                headers: { "content-type": "application/json" },
+                body: '{"ok":false,"error":"internal_error"}',
+                isBase64Encoded: false,
+            };
+        }
+    };
+}
+/**
+ * A streaming Lambda handler for Function URLs with `InvokeMode: RESPONSE_STREAM`, via the
+ * runtime's `awslambda.streamifyResponse`. Response bytes flow as the app produces them - no
+ * buffering, no base64. Requires the managed AWS Lambda Node runtime (the `awslambda` global);
+ * API Gateway does not support response streaming - use {@link handle} there.
+ */
+export function streamHandle(app, options = {}) {
+    const awslambda = globalThis.awslambda;
+    if (awslambda === undefined) {
+        throw new Error("[nifra/aws-lambda] streamHandle requires the AWS Lambda Node runtime (no `awslambda` global found) - use handle() elsewhere");
+    }
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    assertBodyLimit(maxBodyBytes);
+    return awslambda.streamifyResponse(async (event, responseStream, context) => {
+        const { response, pending } = await invoke(app, event, context, maxBodyBytes);
+        const { headers, cookies } = resultHeaders(response);
+        const metadata = { statusCode: response.status, headers };
+        if (cookies.length > 0)
+            metadata.cookies = cookies;
+        const out = awslambda.HttpResponseStream.from(responseStream, metadata);
+        try {
+            if (response.body !== null) {
+                for await (const chunk of response.body) {
+                    if (out.write(chunk) === false && typeof out.once === "function") {
+                        await new Promise((resolve) => {
+                            ;
+                            out.once("drain", resolve);
+                        });
+                    }
+                }
+            }
+        }
+        finally {
+            // Headers are already on the wire once `from` returns; on a mid-stream failure the only
+            // honest move left is to end the stream - never to emit a second response.
+            out.end();
+            await settle(pending);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA8FH,MAAM,sBAAsB,GAAG,SAAS,CAAA;AACxC,MAAM,eAAe,GAAG,CAAC,KAAa,EAAQ,EAAE;IAC9C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAC3C,MAAM,IAAI,UAAU,CAAC,kDAAkD,CAAC,CAAA;AAC5E,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAA;AACtC,gGAAgG;AAChG,+FAA+F;AAC/F,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAO9E,MAAM,UAAU,GAAI,UAAsC,CAAC,MAAM,CAAA;AAEjE,MAAM,UAAU,GAAG,CAAC,IAAY,EAAc,EAAE;IAC9C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACpE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IACvE,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,CAAC,KAAiB,EAAU,EAAE;IAC7C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC9E,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAA;AACrB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAW,EAAE;IACrD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;IAC7B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACnD,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACjD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,IAAY,EAAY,EAAE,CAC3D,IAAI,QAAQ,CAAC,wBAAwB,IAAI,IAAI,EAAE;IAC7C,MAAM;IACN,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;CAChD,CAAC,CAAA;AAEJ;;;GAGG;AACH,MAAM,SAAS,GAAG,CAAC,KAAkB,EAAE,YAAoB,EAAsB,EAAE;IACjF,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,CAAA;IAC1D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IACrC,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,EAAE,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,WAAW,CAAA;IACxF,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAA;IACtF,MAAM,KAAK,GACT,KAAK,CAAC,cAAc,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc,KAAK,EAAE;QAC/D,CAAC,CAAC,IAAI,KAAK,CAAC,cAAc,EAAE;QAC5B,CAAC,CAAC,EAAE,CAAA;IACR,MAAM,GAAG,GAAG,WAAW,SAAS,GAAG,IAAI,GAAG,KAAK,EAAE,CAAA;IAEjD,IAAI,IAA4B,CAAA;IAChC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC7F,IAAI,GAAG,KAAK,CAAC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAChG,IAAI,IAAI,CAAC,UAAU,GAAG,YAAY;YAAE,OAAO,SAAS,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,IAAI,KAAK,SAAS;QACvB,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACvC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;AACjD,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,aAAa,GAAG,CACpB,QAAkB,EACsC,EAAE;IAC1D,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,gBAAgB;YAAE,SAAQ;QAChE,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IACvB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAA;AAC9D,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAkB,EAAyB,EAAE;IACnE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;IACpD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;IAC1D,IAAI,IAAY,CAAA;IAChB,IAAI,eAAwB,CAAA;IAC5B,IAAI,CAAC;QACH,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAChC,eAAe,GAAG,KAAK,CAAA;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;QACtB,eAAe,GAAG,IAAI,CAAA;IACxB,CAAC;IACD,MAAM,MAAM,GAAiB,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAA;IAC5F,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;IAChD,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,GAAa,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAA;AAOvE,kFAAkF;AAClF,MAAM,MAAM,GAAG,KAAK,EAClB,GAAiB,EACjB,KAAkB,EAClB,OAAkC,EAClC,YAAoB,EACC,EAAE;IACvB,MAAM,OAAO,GAAuB,EAAE,CAAA;IACtC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;QAC5C,IAAI,KAAK,YAAY,QAAQ;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;QAClE,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;YACtC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;YACvB,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,IAAI,EAAE,QAAQ;YAC9C,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;gBACrB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACvB,CAAC;SACF,CAAC,CAAA;QACF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,CAAA;IAChD,CAAC;AACH,CAAC,CAAA;AAED,4FAA4F;AAC5F,2FAA2F;AAC3F,6FAA6F;AAC7F,MAAM,MAAM,GAAG,CAAC,OAAoC,EAAgC,EAAE,CACpF,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAE9D;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CACpB,GAAiB,EACjB,UAAyB,EAAE;IAE3B,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAA;IACnE,eAAe,CAAC,YAAY,CAAC,CAAA;IAC7B,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAA;QAC7E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAA;YACvC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;YACrB,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;YACrB,OAAO;gBACL,UAAU,EAAE,GAAG;gBACf,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,uCAAuC;gBAC7C,eAAe,EAAE,KAAK;aACvB,CAAA;QACH,CAAC;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAiB,EACjB,UAAyB,EAAE;IAE3B,MAAM,SAAS,GAAI,UAA8C,CAAC,SAAS,CAAA;IAC3E,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,6HAA6H,CAC9H,CAAA;IACH,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAA;IACnE,eAAe,CAAC,YAAY,CAAC,CAAA;IAC7B,OAAO,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE;QAC1E,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAA;QAC7E,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;QACpD,MAAM,QAAQ,GAAmB,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAA;QACzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAA;QAClD,MAAM,GAAG,GAAG,SAAS,CAAC,kBAAkB,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAA;QACvE,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;oBACxC,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;wBACjE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;4BAClC,CAAC;4BAAC,GAAG,CAAC,IAAyD,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;wBACnF,CAAC,CAAC,CAAA;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,wFAAwF;YACxF,2EAA2E;YAC3E,GAAG,CAAC,GAAG,EAAE,CAAA;YACT,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;QACvB,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nifrajs/aws-lambda",
+  "version": "2.12.0",
+  "description": "AWS Lambda adapter for nifra - API Gateway HTTP API (payload v2) and Function URLs, buffered or streaming, with post-decode body limits and single-site header merging. Dependency-free.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "aws",
+    "aws-lambda",
+    "api-gateway",
+    "serverless",
+    "adapter",
+    "edge"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/aws-lambda"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,344 @@
+/**
+ * AWS Lambda adapter for nifra - runs an app behind API Gateway HTTP APIs (payload format v2) and
+ * Lambda Function URLs (the same v2 shape), buffered via {@link handle} or streamed via
+ * {@link streamHandle}. REST APIs (payload v1) and ALB events are out of scope.
+ *
+ * Security posture, by construction:
+ * - Request headers are assembled from the event in exactly one place ({@link requestHeaders}):
+ *   the `headers` map plus the separate `cookies` array. There is no second merge site, and the
+ *   `cookies` array is canonical - a `cookie` key smuggled into `headers` never reaches the app.
+ * - The body is decoded first (base64 or UTF-8) and its real `byteLength` checked against
+ *   `maxBodyBytes` *before* a `Request` is constructed. The event's own claims about length -
+ *   `content-length` or the encoded size - are never trusted.
+ * - Response `isBase64Encoded` is decided by what the bytes actually are (strict UTF-8 decode),
+ *   never by content-type guessing.
+ * - Uncaught errors become the same flat `internal_error` 500 as every other nifra runtime; the
+ *   event is never echoed.
+ *
+ * The adapter is dependency-free: it accepts anything with a fetch-shaped `fetch` method and
+ * declares the Lambda event/`awslambda` shapes structurally.
+ */
+
+/** Platform fields the adapter feeds into `app.fetch` (mirrors nifra core's `Platform`). */
+export interface LambdaPlatform {
+  readonly env: LambdaEnv
+  readonly clientIp?: string | undefined
+  readonly waitUntil?: (promise: Promise<unknown>) => void
+}
+
+/** Anything with a fetch-shaped entry point - a nifra `server()` app satisfies this. */
+export interface FetchHandler {
+  fetch(request: Request, platform?: LambdaPlatform): Response | Promise<Response>
+}
+
+/**
+ * The slice of an API Gateway HTTP API / Function URL payload-v2 event the adapter reads.
+ * Extra fields pass through untouched on `c.env.event`.
+ */
+export interface LambdaEvent {
+  readonly rawPath?: string
+  readonly rawQueryString?: string
+  readonly headers?: Readonly<Record<string, string | undefined>>
+  /** Payload v2 delivers cookies here, not in `headers` - this array is the canonical source. */
+  readonly cookies?: readonly string[]
+  readonly body?: string | null
+  readonly isBase64Encoded?: boolean
+  readonly requestContext?: {
+    readonly domainName?: string
+    readonly http?: {
+      readonly method?: string
+      readonly sourceIp?: string
+    }
+  }
+}
+
+/** The Lambda invocation context. The adapter only forwards it; declare fields structurally. */
+export interface LambdaContext {
+  readonly awsRequestId?: string
+  readonly functionName?: string
+  readonly [key: string]: unknown
+}
+
+/** What handlers see as `c.env` (declare your app as `server<LambdaEnv>()` for typed access). */
+export interface LambdaEnv {
+  readonly event: LambdaEvent
+  readonly context: LambdaContext | undefined
+}
+
+/** A payload-v2 result object, as API Gateway and Function URLs consume it. */
+export interface LambdaResult {
+  statusCode: number
+  headers: Record<string, string>
+  /** `Set-Cookie` values travel here (payload v2), one entry per cookie - never comma-joined. */
+  cookies?: string[]
+  body: string
+  isBase64Encoded: boolean
+}
+
+export interface LambdaOptions {
+  /**
+   * Reject request bodies whose *decoded* size exceeds this many bytes with a flat 413 before a
+   * `Request` is constructed. Defaults to 1,000,000 (nifra core's default). Set it to match your
+   * app's `maxBodyBytes` if you customized that.
+   */
+  readonly maxBodyBytes?: number
+}
+
+/** The Node `Writable`-shaped stream Lambda hands a streaming handler. Declared structurally. */
+export interface ResponseStream {
+  write(chunk: Uint8Array | string): unknown
+  end(): unknown
+  once?(event: string, listener: () => void): unknown
+}
+
+interface StreamMetadata {
+  statusCode: number
+  headers: Record<string, string>
+  cookies?: string[]
+}
+
+/** The `awslambda` global the managed Node runtime injects for response streaming. */
+interface AwsLambdaGlobal {
+  streamifyResponse(
+    handler: (
+      event: LambdaEvent,
+      responseStream: ResponseStream,
+      context?: LambdaContext,
+    ) => Promise<void>,
+  ): (event: LambdaEvent, responseStream: ResponseStream, context?: LambdaContext) => Promise<void>
+  HttpResponseStream: {
+    from(stream: ResponseStream, metadata: StreamMetadata): ResponseStream
+  }
+}
+
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const assertBodyLimit = (value: number): void => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError("maxBodyBytes must be a non-negative safe integer")
+}
+
+const TEXT_ENCODER = new TextEncoder()
+// `fatal` makes invalid UTF-8 throw (the base64 signal); `ignoreBOM` keeps a leading BOM in the
+// decoded string so a clean decode always re-encodes byte-identically - the honesty invariant.
+const UTF8_STRICT = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true })
+
+interface BufferLike {
+  from(data: string, encoding: string): Uint8Array
+  from(data: Uint8Array): { toString(encoding: string): string }
+}
+
+const nodeBuffer = (globalThis as { Buffer?: BufferLike }).Buffer
+
+const fromBase64 = (data: string): Uint8Array => {
+  if (nodeBuffer !== undefined) return nodeBuffer.from(data, "base64")
+  const binary = atob(data)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+const toBase64 = (bytes: Uint8Array): string => {
+  if (nodeBuffer !== undefined) return nodeBuffer.from(bytes).toString("base64")
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+/**
+ * The single place request headers come from. Payload v2 pre-joins repeated headers with commas in
+ * `headers` and moves cookies into the `cookies` array; that array is set last, unconditionally,
+ * so it is canonical even against an event that (out of spec) also carries a `cookie` header.
+ */
+const requestHeaders = (event: LambdaEvent): Headers => {
+  const headers = new Headers()
+  if (event.headers !== undefined) {
+    for (const [name, value] of Object.entries(event.headers)) {
+      if (value !== undefined) headers.set(name, value)
+    }
+  }
+  if (event.cookies !== undefined && event.cookies.length > 0) {
+    headers.set("cookie", event.cookies.join("; "))
+  } else {
+    headers.delete("cookie")
+  }
+  return headers
+}
+
+const flatError = (status: number, code: string): Response =>
+  new Response(`{"ok":false,"error":"${code}"}`, {
+    status,
+    headers: { "content-type": "application/json" },
+  })
+
+/**
+ * Build the `Request`, or a flat error `Response` when the event must be rejected before the app
+ * runs. The body is decoded and measured first - a 413 here means no `Request` ever existed.
+ */
+const toRequest = (event: LambdaEvent, maxBodyBytes: number): Request | Response => {
+  const method = event.requestContext?.http?.method ?? "GET"
+  const headers = requestHeaders(event)
+  const authority = event.requestContext?.domainName ?? headers.get("host") ?? "localhost"
+  const path = event.rawPath !== undefined && event.rawPath !== "" ? event.rawPath : "/"
+  const query =
+    event.rawQueryString !== undefined && event.rawQueryString !== ""
+      ? `?${event.rawQueryString}`
+      : ""
+  const url = `https://${authority}${path}${query}`
+
+  let body: Uint8Array | undefined
+  if (event.body !== undefined && event.body !== null && method !== "GET" && method !== "HEAD") {
+    body = event.isBase64Encoded === true ? fromBase64(event.body) : TEXT_ENCODER.encode(event.body)
+    if (body.byteLength > maxBodyBytes) return flatError(413, "payload_too_large")
+  }
+
+  return body === undefined
+    ? new Request(url, { method, headers })
+    : new Request(url, { method, headers, body })
+}
+
+/**
+ * Response headers as a plain object for the v2 result, with `set-cookie` split out into the
+ * `cookies` array (comma-joining cookies corrupts them) and `content-length` dropped - the
+ * transport owns framing, and a stale length from before base64 re-encoding must not survive.
+ */
+const resultHeaders = (
+  response: Response,
+): { headers: Record<string, string>; cookies: string[] } => {
+  const headers: Record<string, string> = {}
+  for (const [name, value] of response.headers) {
+    if (name === "set-cookie" || name === "content-length") continue
+    headers[name] = value
+  }
+  return { headers, cookies: response.headers.getSetCookie() }
+}
+
+const toResult = async (response: Response): Promise<LambdaResult> => {
+  const { headers, cookies } = resultHeaders(response)
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  let body: string
+  let isBase64Encoded: boolean
+  try {
+    body = UTF8_STRICT.decode(bytes)
+    isBase64Encoded = false
+  } catch {
+    body = toBase64(bytes)
+    isBase64Encoded = true
+  }
+  const result: LambdaResult = { statusCode: response.status, headers, body, isBase64Encoded }
+  if (cookies.length > 0) result.cookies = cookies
+  return result
+}
+
+const INTERNAL_ERROR = (): Response => flatError(500, "internal_error")
+
+interface Invocation {
+  response: Response
+  pending: readonly Promise<unknown>[]
+}
+
+/** Run the app for one event. Never throws: failures collapse to the flat 500. */
+const invoke = async (
+  app: FetchHandler,
+  event: LambdaEvent,
+  context: LambdaContext | undefined,
+  maxBodyBytes: number,
+): Promise<Invocation> => {
+  const pending: Promise<unknown>[] = []
+  try {
+    const built = toRequest(event, maxBodyBytes)
+    if (built instanceof Response) return { response: built, pending }
+    const response = await app.fetch(built, {
+      env: { event, context },
+      clientIp: event.requestContext?.http?.sourceIp,
+      waitUntil: (promise) => {
+        pending.push(promise)
+      },
+    })
+    return { response, pending }
+  } catch {
+    return { response: INTERNAL_ERROR(), pending }
+  }
+}
+
+// Background work must settle before the handler returns - Lambda freezes the container the
+// moment it does, so a fire-and-forget promise would silently stall until (maybe) the next
+// invocation thaws it. `allSettled` so a failed background task cannot corrupt the response.
+const settle = (pending: readonly Promise<unknown>[]): Promise<unknown> | undefined =>
+  pending.length > 0 ? Promise.allSettled(pending) : undefined
+
+/**
+ * A buffered Lambda handler for API Gateway HTTP APIs (payload v2) and Function URLs.
+ *
+ * ```ts
+ * import { handle } from "@nifrajs/aws-lambda"
+ * import { app } from "./app.ts" // built once per container, at module scope
+ *
+ * export const handler = handle(app)
+ * ```
+ */
+export function handle(
+  app: FetchHandler,
+  options: LambdaOptions = {},
+): (event: LambdaEvent, context?: LambdaContext) => Promise<LambdaResult> {
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  assertBodyLimit(maxBodyBytes)
+  return async (event, context) => {
+    const { response, pending } = await invoke(app, event, context, maxBodyBytes)
+    try {
+      const result = await toResult(response)
+      await settle(pending)
+      return result
+    } catch {
+      await settle(pending)
+      return {
+        statusCode: 500,
+        headers: { "content-type": "application/json" },
+        body: '{"ok":false,"error":"internal_error"}',
+        isBase64Encoded: false,
+      }
+    }
+  }
+}
+
+/**
+ * A streaming Lambda handler for Function URLs with `InvokeMode: RESPONSE_STREAM`, via the
+ * runtime's `awslambda.streamifyResponse`. Response bytes flow as the app produces them - no
+ * buffering, no base64. Requires the managed AWS Lambda Node runtime (the `awslambda` global);
+ * API Gateway does not support response streaming - use {@link handle} there.
+ */
+export function streamHandle(
+  app: FetchHandler,
+  options: LambdaOptions = {},
+): (event: LambdaEvent, responseStream: ResponseStream, context?: LambdaContext) => Promise<void> {
+  const awslambda = (globalThis as { awslambda?: AwsLambdaGlobal }).awslambda
+  if (awslambda === undefined) {
+    throw new Error(
+      "[nifra/aws-lambda] streamHandle requires the AWS Lambda Node runtime (no `awslambda` global found) - use handle() elsewhere",
+    )
+  }
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  assertBodyLimit(maxBodyBytes)
+  return awslambda.streamifyResponse(async (event, responseStream, context) => {
+    const { response, pending } = await invoke(app, event, context, maxBodyBytes)
+    const { headers, cookies } = resultHeaders(response)
+    const metadata: StreamMetadata = { statusCode: response.status, headers }
+    if (cookies.length > 0) metadata.cookies = cookies
+    const out = awslambda.HttpResponseStream.from(responseStream, metadata)
+    try {
+      if (response.body !== null) {
+        for await (const chunk of response.body) {
+          if (out.write(chunk) === false && typeof out.once === "function") {
+            await new Promise<void>((resolve) => {
+              ;(out.once as (event: string, listener: () => void) => unknown)("drain", resolve)
+            })
+          }
+        }
+      }
+    } finally {
+      // Headers are already on the wire once `from` returns; on a mid-stream failure the only
+      // honest move left is to end the stream - never to emit a second response.
+      out.end()
+      await settle(pending)
+    }
+  })
+}