@web-ts-toolkit/express-runtime 0.43.0 → 0.44.0

package/{chunk-VPFBKM2K.mjs → chunk-QNRHWPTO.mjs}

@@ -5,6 +5,7 @@ import serverless from "serverless-http";
 
 // src/numeric-validation.ts
 var MAX_INTEGER_OPTION_VALUE = Number.MAX_SAFE_INTEGER;
+var MAX_TIMER_DURATION_MS = 2147483647;
 function validateFiniteInteger(value, options) {
   const min = options.min ?? Number.MIN_SAFE_INTEGER;
   const max = options.max ?? MAX_INTEGER_OPTION_VALUE;
@@ -35,6 +36,9 @@ function parsePortValue(value, name) {
   }
   return value;
 }
+function validateTimerDuration(value, name) {
+  return validateFiniteInteger(value, { name, min: 0, max: MAX_TIMER_DURATION_MS });
+}
 
 // src/index.ts
 var defaultLogger = {
@@ -103,20 +107,19 @@ function defaultRequestHook(req, maxBodyBytes = 1024 * 1024, logger = defaultLog
     logger.debug?.(" Skipping oversized serverless body for content-type parsing");
     return;
   }
-  const bodyStr = req.body.toString("utf8");
   const contentType = getHeaderValue(req.headers, "content-type");
   if (isJsonMediaType(contentType)) {
     if (isReadableRequest(req)) {
       return;
     }
     try {
-      req.body = JSON.parse(bodyStr);
+      req.body = JSON.parse(req.body.toString("utf8"));
     } catch (_error) {
       void _error;
     }
     return;
   }
-  req.body = bodyStr;
+  req.body = req.body.toString("utf8");
 }
 function getHeaderValue(headers, name) {
   if (!headers) return "";
@@ -216,11 +219,7 @@ function startLocalServer(app, options = {}) {
   const logger = options.logger ?? defaultLogger;
   const port = normalizePort(options.port);
   const host = options.host ?? process.env.HOST ?? "0.0.0.0";
-  const shutdownTimeout = validateFiniteInteger(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, {
-    name: "shutdownTimeout",
-    min: 0,
-    max: MAX_INTEGER_OPTION_VALUE
-  });
+  const shutdownTimeout = validateTimerDuration(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, "shutdownTimeout");
   const server = http.createServer(app);
   app.set("port", port);
   let state = "initializing";
@@ -392,6 +391,7 @@ function startLocalServer(app, options = {}) {
         done();
       }
     });
+    let shutdownFailed = false;
     let shutdownError;
     try {
       if (options.onShutdown) {
@@ -399,9 +399,10 @@ function startLocalServer(app, options = {}) {
       }
     } catch (err) {
       logger.error("onShutdown hook failed:", err);
+      shutdownFailed = true;
       shutdownError = err;
     }
-    if (shutdownError) {
+    if (shutdownFailed) {
       state = "failed";
       if (options.exitAfterShutdown) {
         process.exit(1);
@@ -420,7 +421,7 @@ function startLocalServer(app, options = {}) {
   };
   if (options.signals !== false) {
     const list = options.signals === void 0 || options.signals === true ? DEFAULT_SIGNALS : options.signals;
-    for (const sig of list) {
+    for (const sig of new Set(list)) {
       const handler = () => {
         void shutdown().catch(() => {
         });
@@ -477,8 +478,10 @@ function startLocalServer(app, options = {}) {
 
 export {
   MAX_INTEGER_OPTION_VALUE,
+  MAX_TIMER_DURATION_MS,
   validateFiniteInteger,
   parsePortValue,
+  validateTimerDuration,
   createExpressApp,
   defaultRequestHook,
   createServerlessHandler,

package/cli-api.d.mts

@@ -1,5 +1,5 @@
 import { LocalServerOptions, LocalServer } from './index.mjs';
-import { watch, existsSync } from 'node:fs';
+import { watch, mkdtempSync, lstatSync, writeFileSync, rmSync, existsSync } from 'node:fs';
 import { ChildProcess, fork } from 'node:child_process';
 import { Response, Request, Express } from 'express';
 import 'node:http';
@@ -25,7 +25,7 @@ interface DevArgs {
     watch: string[];
     /** File extensions to watch (default: ts,js,mjs,cjs,json). */
     watchExt: string[];
-    /** Debounce delay (ms) before restarting on file change (default: 500). */
+    /** Debounce delay (ms) before restarting on file change (default: 500). Must be a finite integer in `0..2147483647` (Node timer limit); `0` restarts without debouncing. */
     watchDelay: number;
 }
 interface BuildArgs {
@@ -125,6 +125,13 @@ declare function loadEnvFiles(paths: string[]): void;
  * loading the app module. Each module is `require()`-ed, running its
  * side effects (registering hooks, loading configs, etc.).
  *
+ * Resolution uses the current working directory captured when preloading
+ * starts, so programmatic consumers that change cwd between invocations
+ * resolve relative preloads (and bare dependencies) against the current
+ * invocation — consistent with call-time `loadEnvFiles`/`loadApp` — rather
+ * than the directory that was current when this module was first evaluated.
+ * Preloads run sequentially in list order. No sandbox is applied.
+ *
  * Public helper for programmatic CLI integrations that need the same preload
  * behavior as the binary before loading an app or handler module.
  */
@@ -139,6 +146,7 @@ interface WatchSupervisorDeps {
     watch?: typeof watch;
     existsSync?: typeof existsSync;
     logger?: Pick<Console, 'error'>;
+    /** Ms before SIGTERM escalates to SIGKILL. Must be a finite integer in `0..2147483647` (Node timer limit). */
     killTimeoutMs?: number;
     setTimeout?: typeof setTimeout;
     clearTimeout?: typeof clearTimeout;
@@ -163,6 +171,11 @@ interface WatchSupervisorController {
  * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
  * flags (the child runs without watch mode).
  *
+ * Generated options are placed before `--`, with the positional app module
+ * after it, so leading-dash module paths (e.g. `--app.js`, `--help`) parsed
+ * via `dev --watch ./src -- --app.js` keep their `--` protection and are not
+ * reinterpreted as flags (or help/version requests) by the child parser.
+ *
  * Public helper for CLI wrappers that supervise watch mode themselves and need
  * the same child argv reconstruction as `runWithWatch`.
  */
@@ -208,11 +221,53 @@ declare function generateRuntimeEntry(appPath: string, initPath?: string): strin
  * Public safety check for programmatic build integrations before invoking
  * `buildBundleFromEntryContent()` with `clean: true`.
  */
+/**
+ * Validate that `outDir` is safe to clean before invoking tsup.
+ * Prevents destructive `clean: true` combinations:
+ *  - filesystem root (physical)
+ *  - project cwd itself (physical)
+ *  - ancestors of the project cwd (physical, through symlinked aliases)
+ *  - symlinked output directories
+ *  - output that physically contains input files (appPath/initPath), or is
+ *    physically nested inside an input path
+ *
+ * Physical comparison canonicalizes cwd, outDir (via its nearest existing
+ * ancestor when it does not exist yet), and supplied input paths with
+ * `realpath`. Unexpected filesystem errors fail closed. Only `clean: false`
+ * skips validation.
+ *
+ * Public safety check for programmatic build integrations before invoking
+ * `buildBundleFromEntryContent()` with `clean: true`.
+ */
 declare function validateOutDirForClean(outDir: string, clean: boolean, appPath?: string, initPath?: string): void;
-declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
+/** Injectable filesystem/build seams for deterministic staging-failure tests. */
+interface BuildStagingDeps {
+    mkdtempSyncImpl?: typeof mkdtempSync;
+    lstatSyncImpl?: typeof lstatSync;
+    writeFileSyncImpl?: typeof writeFileSync;
+    rmSyncImpl?: typeof rmSync;
+    buildImpl?: (options: {
+        config: false;
+        entry: Record<string, string>;
+        tsconfig?: string;
+        format: string[];
+        target: string;
+        outDir: string;
+        clean: boolean;
+        external: string[];
+        sourcemap: boolean;
+        dts: boolean;
+        splitting: boolean;
+    }) => Promise<void>;
+}
+declare function buildBundleFromEntryContent(args: BuildEntryContentArgs, deps?: BuildStagingDeps): Promise<void>;
 /**
  * Bundle an Express app as a local runtime module. The output default-exports
  * the app and may additionally export an `init` hook for the `start` command.
+ *
+ * `express` and `@web-ts-toolkit/express-runtime` are always external, so the
+ * bundle must be deployed with both packages installed (`express` is a peer
+ * dependency). Additional externals can be passed via `BuildArgs.external`.
  */
 declare function buildRuntime(args: BuildArgs): Promise<void>;
 /**
@@ -220,17 +275,36 @@ declare function buildRuntime(args: BuildArgs): Promise<void>;
  * to the user's cwd (for node_modules resolution), lazy-loads the bundled
  * build tool, then cleans up.
  *
- * `express` is always external; additional externals can be passed via
- * `BuildArgs.external`.
+ * `express` and `@web-ts-toolkit/express-runtime` (imported by the generated
+ * entry) are always external; additional externals can be passed via
+ * `BuildArgs.external`. Deploy the bundle together with both packages
+ * installed (`express` is a peer dependency; `serverless-http` ships with the
+ * runtime package).
  */
 declare function buildServerless(args: BuildArgs): Promise<void>;
 /**
- * A platform-agnostic serverless handler function (the output of
- * `build-serverless`).
+ * A serverless handler callable as invoked by the local `start-serverless`
+ * adapter. The adapter supplies an AWS API Gateway REST API v1 event (see
+ * `ApiGatewayRestEvent`) and an empty record context (`{}`), then validates
+ * the unknown result via `applyServerlessResult`.
+ *
+ * Keep the parameters narrow: handlers requiring provider-specific event
+ * fields or rich Lambda-like contexts must not typecheck here, since the
+ * local adapter cannot supply them. The default
+ * `ServerlessHandler<Record<string, unknown>, Record<string, unknown>>` from
+ * `createServerlessHandler(app)` remains assignable, so cast-free
+ * `createServerlessAdapterApp(createServerlessHandler(app))` composition
+ * compiles.
+ */
+type GenericHandler = (event: ApiGatewayRestEvent, context: Record<string, unknown>) => Promise<unknown>;
+/**
+ * AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter.
+ *
+ * Declared as a type alias (not an interface) so the implicit index signature
+ * lets the default provider-generic `ServerlessHandler` (`Record<string,
+ * unknown>` event) accept it without casts.
  */
-type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
-/** AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter. */
-interface ApiGatewayRestEvent {
+type ApiGatewayRestEvent = {
     httpMethod: string;
     path: string;
     headers: Record<string, string>;
@@ -244,7 +318,7 @@ interface ApiGatewayRestEvent {
             sourceIp: string;
         };
     };
-}
+};
 /**
  * AWS API Gateway REST API v1 / Lambda proxy result shape returned by `serverless-http`.
  */
@@ -261,7 +335,12 @@ interface ServerlessAdapterOptions {
      * Maximum bytes to buffer for a single request body.
      * Default: 1048576 (1 MiB). Must be a finite non-negative integer.
      * When `0`, no body is allowed — any non-empty body receives `413`.
-     * The adapter never retains more than this limit plus at most one incoming chunk.
+     * Collection retains O(limit) chunk bytes: appending stops once the running
+     * total would exceed the limit (at most one chunk over the limit is observed
+     * before rejection). `Buffer.concat` then holds the chunks plus one output
+     * Buffer, and event translation adds a transient base64 copy (~4/3 of the
+     * body), so peak transient memory is a small multiple of the limit rather
+     * than an exact limit-plus-chunk ceiling.
      */
     maxBodyBytes?: number;
 }
@@ -277,19 +356,80 @@ declare function validateMaxBodyBytes(value: unknown): number;
  * bodies with a `LIMIT_EXCEEDED` error (413), stops retaining chunks after the limit,
  * removes owned listeners, and drains the request.
  * Distinguishes client aborts (`CLIENT_ABORT`) and stream errors from oversize.
+ *
+ * Memory phases (no unmeasured total-memory ceiling is claimed): chunk
+ * retention is O(limit) — appending stops once the running total would exceed
+ * `maxBytes`, so at most one chunk over the limit is observed before
+ * rejection; `Buffer.concat` then retains the chunks plus one output Buffer of
+ * the accepted size; `toServerlessEvent` adds a transient base64 copy (~4/3 of
+ * the body). Peak transient memory is therefore a small multiple of the limit.
  */
 declare function collectBody(req: Request, maxBytes: number): Promise<Buffer>;
 /**
  * Build an AWS API Gateway REST API v1 / Lambda proxy event from HTTP request components.
  *
+ * Path contract (origin-form request targets are preserved verbatim):
+ *
+ * - `url` is normally the raw origin-form target from `req.url`
+ *   (`/path?query`). The path is everything before the first literal `?`
+ *   (or `#`); it is never dot-segment-resolved, slash-collapsed, or
+ *   percent-decoded. `//admin/users`, `/a/../private`, `/a/./b`,
+ *   `/%2E%2E/private`, and `/a%2Fb` all reach the handler unchanged, so
+ *   wrapped routing sees the same target the client sent. Query splitting
+ *   and single-decode semantics are unchanged, and only a literal `?`
+ *   starts the query (an encoded `%3F` stays in the path).
+ * - A `#fragment`, never part of a real HTTP request target, is stripped
+ *   when present.
+ * - Absolute-form targets (`scheme://authority/path?query`, as sent to
+ *   proxies) are supported by stripping the scheme and authority and
+ *   preserving the raw path remainder (`http://h//a/../b?x=1` yields path
+ *   `//a/../b`); a missing remainder maps to `/`. Userinfo, host, and port
+ *   are ignored, not validated.
+ * - Asterisk-form (`*`, used by `OPTIONS *`) is supported with path `*`.
+ * - The empty string maps to `/` for backwards compatibility. Any other
+ *   target that is neither origin-form, absolute-form, nor asterisk-form
+ *   (e.g. `foo/bar`) is rejected with an `Error` (the local adapter turns
+ *   this into a 500 without invoking the handler).
+ *
+ * Intentional behavior change: this helper previously split the target via
+ * the WHATWG `URL` parser, which rewrote origin-form paths before routing
+ * (`//admin/users` was parsed as host `admin` plus path `/users`,
+ * `/a/../private` resolved to `/private`, and even encoded `%2E%2E` was
+ * decoded and then resolved). Those rewrites silently selected a different
+ * route; they are no longer performed.
+ *
+ * Header contract (HTTP boundary fidelity):
+ *
+ * - When the Node `rawHeaders` list (`[name, value, ...]` from
+ *   `IncomingMessage.rawHeaders`, optionally passed as the fifth argument)
+ *   is available, both header maps are derived from it. Names are
+ *   lowercased (HTTP names are case-insensitive, so `X-Repeat` and
+ *   `x-repeat` merge); values are preserved verbatim in wire order and
+ *   never split on commas (`"one, with comma"` stays one entry).
+ * - Otherwise the `headers` map (e.g. `req.headers` or `headersDistinct`)
+ *   is used as-is: array values are preserved entry-wise, string values
+ *   become single entries, and commas inside values are never split. Note
+ *   that `req.headers` has already joined duplicates (`"one, two"`), so
+ *   callers at the real HTTP boundary should pass `rawHeaders` (the local
+ *   adapter does) to keep repeated headers distinct.
+ * - The single-value map joins each multi-value entry with `", "`; the
+ *   multi-value map keeps every value in order. Response `set-cookie`
+ *   handling is unchanged (`applyServerlessResult` still emits each
+ *   `set-cookie` value as its own header and joins other multi-values
+ *   with `","`).
+ *
  * Public helper for adapters that need the same AWS REST API v1 event shape as
  * the `start-serverless` command.
  */
-declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): ApiGatewayRestEvent;
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer, rawHeaders?: unknown): ApiGatewayRestEvent;
 /**
  * Write a serverless handler result to an Express response.
  * Validates the complete AWS API Gateway REST API v1 / Lambda proxy result before writing anything.
  * `multiValueHeaders` wins over `headers` when the same header appears in both maps.
+ * An empty `multiValueHeaders` array is omitted (no header is emitted), but its
+ * name is still validated so invalid names fail closed even with zero values.
+ * If header/body application fails before headers are sent, any headers staged
+ * by this call are removed before the error propagates so a fallback 500 stays clean.
  *
  * Public helper for adapters that need the same AWS REST API v1 result-to-HTTP
  * translation as the `start-serverless` command.
@@ -298,14 +438,22 @@ declare function applyServerlessResult(result: unknown, res: Response): void;
 /**
  * Create an Express app that proxies all requests to a serverless handler.
  * Each HTTP request is translated into a serverless event, the handler is
- * invoked, and the result is written back to the response.
+ * invoked as `handler(event, {})` where `event` is an `ApiGatewayRestEvent`
+ * and the context is an empty record, and the result is written back to the
+ * response.
  *
- * Express body parsers are disabled; the raw request body is read directly
- * from the stream and passed as a Buffer (so the serverless handler's request
- * hook — including the #305 workaround — works identically to production).
+ * Express body parsers are disabled; the raw request body is buffered with
+ * `collectBody` and then base64-encoded into the AWS v1 string `body` field
+ * (`isBase64Encoded` is true for non-empty bodies, false with `body: ''` for
+ * empty ones), so `serverless-http` replays the decoded bytes through the
+ * Express request stream identically to production.
  * Bodies exceeding `maxBodyBytes` (default 1 MiB, 0 = empty bodies only) receive
  * `413 Payload Too Large` without invoking the handler; the request is drained
- * and retained memory is bounded to the limit plus at most one chunk.
+ * and chunk retention is O(limit) — appending stops once the running total
+ * would exceed the limit, so at most one chunk over the limit is observed
+ * before rejection. `Buffer.concat` retains the chunks plus one output Buffer
+ * and event translation adds a transient base64 copy (~4/3 of the body), so
+ * peak transient memory is a small multiple of the limit.
  */
 declare function createServerlessAdapterApp(handler: GenericHandler, options?: ServerlessAdapterOptions): Express;
 /**

package/cli-api.d.ts

@@ -1,5 +1,5 @@
 import { LocalServerOptions, LocalServer } from './index.js';
-import { watch, existsSync } from 'node:fs';
+import { watch, mkdtempSync, lstatSync, writeFileSync, rmSync, existsSync } from 'node:fs';
 import { ChildProcess, fork } from 'node:child_process';
 import { Response, Request, Express } from 'express';
 import 'node:http';
@@ -25,7 +25,7 @@ interface DevArgs {
     watch: string[];
     /** File extensions to watch (default: ts,js,mjs,cjs,json). */
     watchExt: string[];
-    /** Debounce delay (ms) before restarting on file change (default: 500). */
+    /** Debounce delay (ms) before restarting on file change (default: 500). Must be a finite integer in `0..2147483647` (Node timer limit); `0` restarts without debouncing. */
     watchDelay: number;
 }
 interface BuildArgs {
@@ -125,6 +125,13 @@ declare function loadEnvFiles(paths: string[]): void;
  * loading the app module. Each module is `require()`-ed, running its
  * side effects (registering hooks, loading configs, etc.).
  *
+ * Resolution uses the current working directory captured when preloading
+ * starts, so programmatic consumers that change cwd between invocations
+ * resolve relative preloads (and bare dependencies) against the current
+ * invocation — consistent with call-time `loadEnvFiles`/`loadApp` — rather
+ * than the directory that was current when this module was first evaluated.
+ * Preloads run sequentially in list order. No sandbox is applied.
+ *
  * Public helper for programmatic CLI integrations that need the same preload
  * behavior as the binary before loading an app or handler module.
  */
@@ -139,6 +146,7 @@ interface WatchSupervisorDeps {
     watch?: typeof watch;
     existsSync?: typeof existsSync;
     logger?: Pick<Console, 'error'>;
+    /** Ms before SIGTERM escalates to SIGKILL. Must be a finite integer in `0..2147483647` (Node timer limit). */
     killTimeoutMs?: number;
     setTimeout?: typeof setTimeout;
     clearTimeout?: typeof clearTimeout;
@@ -163,6 +171,11 @@ interface WatchSupervisorController {
  * Reconstruct the argv for the child process, stripping --watch/--ext/--delay
  * flags (the child runs without watch mode).
  *
+ * Generated options are placed before `--`, with the positional app module
+ * after it, so leading-dash module paths (e.g. `--app.js`, `--help`) parsed
+ * via `dev --watch ./src -- --app.js` keep their `--` protection and are not
+ * reinterpreted as flags (or help/version requests) by the child parser.
+ *
  * Public helper for CLI wrappers that supervise watch mode themselves and need
  * the same child argv reconstruction as `runWithWatch`.
  */
@@ -208,11 +221,53 @@ declare function generateRuntimeEntry(appPath: string, initPath?: string): strin
  * Public safety check for programmatic build integrations before invoking
  * `buildBundleFromEntryContent()` with `clean: true`.
  */
+/**
+ * Validate that `outDir` is safe to clean before invoking tsup.
+ * Prevents destructive `clean: true` combinations:
+ *  - filesystem root (physical)
+ *  - project cwd itself (physical)
+ *  - ancestors of the project cwd (physical, through symlinked aliases)
+ *  - symlinked output directories
+ *  - output that physically contains input files (appPath/initPath), or is
+ *    physically nested inside an input path
+ *
+ * Physical comparison canonicalizes cwd, outDir (via its nearest existing
+ * ancestor when it does not exist yet), and supplied input paths with
+ * `realpath`. Unexpected filesystem errors fail closed. Only `clean: false`
+ * skips validation.
+ *
+ * Public safety check for programmatic build integrations before invoking
+ * `buildBundleFromEntryContent()` with `clean: true`.
+ */
 declare function validateOutDirForClean(outDir: string, clean: boolean, appPath?: string, initPath?: string): void;
-declare function buildBundleFromEntryContent(args: BuildEntryContentArgs): Promise<void>;
+/** Injectable filesystem/build seams for deterministic staging-failure tests. */
+interface BuildStagingDeps {
+    mkdtempSyncImpl?: typeof mkdtempSync;
+    lstatSyncImpl?: typeof lstatSync;
+    writeFileSyncImpl?: typeof writeFileSync;
+    rmSyncImpl?: typeof rmSync;
+    buildImpl?: (options: {
+        config: false;
+        entry: Record<string, string>;
+        tsconfig?: string;
+        format: string[];
+        target: string;
+        outDir: string;
+        clean: boolean;
+        external: string[];
+        sourcemap: boolean;
+        dts: boolean;
+        splitting: boolean;
+    }) => Promise<void>;
+}
+declare function buildBundleFromEntryContent(args: BuildEntryContentArgs, deps?: BuildStagingDeps): Promise<void>;
 /**
  * Bundle an Express app as a local runtime module. The output default-exports
  * the app and may additionally export an `init` hook for the `start` command.
+ *
+ * `express` and `@web-ts-toolkit/express-runtime` are always external, so the
+ * bundle must be deployed with both packages installed (`express` is a peer
+ * dependency). Additional externals can be passed via `BuildArgs.external`.
  */
 declare function buildRuntime(args: BuildArgs): Promise<void>;
 /**
@@ -220,17 +275,36 @@ declare function buildRuntime(args: BuildArgs): Promise<void>;
  * to the user's cwd (for node_modules resolution), lazy-loads the bundled
  * build tool, then cleans up.
  *
- * `express` is always external; additional externals can be passed via
- * `BuildArgs.external`.
+ * `express` and `@web-ts-toolkit/express-runtime` (imported by the generated
+ * entry) are always external; additional externals can be passed via
+ * `BuildArgs.external`. Deploy the bundle together with both packages
+ * installed (`express` is a peer dependency; `serverless-http` ships with the
+ * runtime package).
  */
 declare function buildServerless(args: BuildArgs): Promise<void>;
 /**
- * A platform-agnostic serverless handler function (the output of
- * `build-serverless`).
+ * A serverless handler callable as invoked by the local `start-serverless`
+ * adapter. The adapter supplies an AWS API Gateway REST API v1 event (see
+ * `ApiGatewayRestEvent`) and an empty record context (`{}`), then validates
+ * the unknown result via `applyServerlessResult`.
+ *
+ * Keep the parameters narrow: handlers requiring provider-specific event
+ * fields or rich Lambda-like contexts must not typecheck here, since the
+ * local adapter cannot supply them. The default
+ * `ServerlessHandler<Record<string, unknown>, Record<string, unknown>>` from
+ * `createServerlessHandler(app)` remains assignable, so cast-free
+ * `createServerlessAdapterApp(createServerlessHandler(app))` composition
+ * compiles.
+ */
+type GenericHandler = (event: ApiGatewayRestEvent, context: Record<string, unknown>) => Promise<unknown>;
+/**
+ * AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter.
+ *
+ * Declared as a type alias (not an interface) so the implicit index signature
+ * lets the default provider-generic `ServerlessHandler` (`Record<string,
+ * unknown>` event) accept it without casts.
  */
-type GenericHandler = (event: unknown, context: unknown) => Promise<unknown>;
-/** AWS API Gateway REST API v1 / Lambda proxy event shape emitted by the local adapter. */
-interface ApiGatewayRestEvent {
+type ApiGatewayRestEvent = {
     httpMethod: string;
     path: string;
     headers: Record<string, string>;
@@ -244,7 +318,7 @@ interface ApiGatewayRestEvent {
             sourceIp: string;
         };
     };
-}
+};
 /**
  * AWS API Gateway REST API v1 / Lambda proxy result shape returned by `serverless-http`.
  */
@@ -261,7 +335,12 @@ interface ServerlessAdapterOptions {
      * Maximum bytes to buffer for a single request body.
      * Default: 1048576 (1 MiB). Must be a finite non-negative integer.
      * When `0`, no body is allowed — any non-empty body receives `413`.
-     * The adapter never retains more than this limit plus at most one incoming chunk.
+     * Collection retains O(limit) chunk bytes: appending stops once the running
+     * total would exceed the limit (at most one chunk over the limit is observed
+     * before rejection). `Buffer.concat` then holds the chunks plus one output
+     * Buffer, and event translation adds a transient base64 copy (~4/3 of the
+     * body), so peak transient memory is a small multiple of the limit rather
+     * than an exact limit-plus-chunk ceiling.
      */
     maxBodyBytes?: number;
 }
@@ -277,19 +356,80 @@ declare function validateMaxBodyBytes(value: unknown): number;
  * bodies with a `LIMIT_EXCEEDED` error (413), stops retaining chunks after the limit,
  * removes owned listeners, and drains the request.
  * Distinguishes client aborts (`CLIENT_ABORT`) and stream errors from oversize.
+ *
+ * Memory phases (no unmeasured total-memory ceiling is claimed): chunk
+ * retention is O(limit) — appending stops once the running total would exceed
+ * `maxBytes`, so at most one chunk over the limit is observed before
+ * rejection; `Buffer.concat` then retains the chunks plus one output Buffer of
+ * the accepted size; `toServerlessEvent` adds a transient base64 copy (~4/3 of
+ * the body). Peak transient memory is therefore a small multiple of the limit.
  */
 declare function collectBody(req: Request, maxBytes: number): Promise<Buffer>;
 /**
  * Build an AWS API Gateway REST API v1 / Lambda proxy event from HTTP request components.
  *
+ * Path contract (origin-form request targets are preserved verbatim):
+ *
+ * - `url` is normally the raw origin-form target from `req.url`
+ *   (`/path?query`). The path is everything before the first literal `?`
+ *   (or `#`); it is never dot-segment-resolved, slash-collapsed, or
+ *   percent-decoded. `//admin/users`, `/a/../private`, `/a/./b`,
+ *   `/%2E%2E/private`, and `/a%2Fb` all reach the handler unchanged, so
+ *   wrapped routing sees the same target the client sent. Query splitting
+ *   and single-decode semantics are unchanged, and only a literal `?`
+ *   starts the query (an encoded `%3F` stays in the path).
+ * - A `#fragment`, never part of a real HTTP request target, is stripped
+ *   when present.
+ * - Absolute-form targets (`scheme://authority/path?query`, as sent to
+ *   proxies) are supported by stripping the scheme and authority and
+ *   preserving the raw path remainder (`http://h//a/../b?x=1` yields path
+ *   `//a/../b`); a missing remainder maps to `/`. Userinfo, host, and port
+ *   are ignored, not validated.
+ * - Asterisk-form (`*`, used by `OPTIONS *`) is supported with path `*`.
+ * - The empty string maps to `/` for backwards compatibility. Any other
+ *   target that is neither origin-form, absolute-form, nor asterisk-form
+ *   (e.g. `foo/bar`) is rejected with an `Error` (the local adapter turns
+ *   this into a 500 without invoking the handler).
+ *
+ * Intentional behavior change: this helper previously split the target via
+ * the WHATWG `URL` parser, which rewrote origin-form paths before routing
+ * (`//admin/users` was parsed as host `admin` plus path `/users`,
+ * `/a/../private` resolved to `/private`, and even encoded `%2E%2E` was
+ * decoded and then resolved). Those rewrites silently selected a different
+ * route; they are no longer performed.
+ *
+ * Header contract (HTTP boundary fidelity):
+ *
+ * - When the Node `rawHeaders` list (`[name, value, ...]` from
+ *   `IncomingMessage.rawHeaders`, optionally passed as the fifth argument)
+ *   is available, both header maps are derived from it. Names are
+ *   lowercased (HTTP names are case-insensitive, so `X-Repeat` and
+ *   `x-repeat` merge); values are preserved verbatim in wire order and
+ *   never split on commas (`"one, with comma"` stays one entry).
+ * - Otherwise the `headers` map (e.g. `req.headers` or `headersDistinct`)
+ *   is used as-is: array values are preserved entry-wise, string values
+ *   become single entries, and commas inside values are never split. Note
+ *   that `req.headers` has already joined duplicates (`"one, two"`), so
+ *   callers at the real HTTP boundary should pass `rawHeaders` (the local
+ *   adapter does) to keep repeated headers distinct.
+ * - The single-value map joins each multi-value entry with `", "`; the
+ *   multi-value map keeps every value in order. Response `set-cookie`
+ *   handling is unchanged (`applyServerlessResult` still emits each
+ *   `set-cookie` value as its own header and joins other multi-values
+ *   with `","`).
+ *
  * Public helper for adapters that need the same AWS REST API v1 event shape as
  * the `start-serverless` command.
  */
-declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer): ApiGatewayRestEvent;
+declare function toServerlessEvent(method: string, url: string, headers: Record<string, string | string[] | undefined>, body: Buffer, rawHeaders?: unknown): ApiGatewayRestEvent;
 /**
  * Write a serverless handler result to an Express response.
  * Validates the complete AWS API Gateway REST API v1 / Lambda proxy result before writing anything.
  * `multiValueHeaders` wins over `headers` when the same header appears in both maps.
+ * An empty `multiValueHeaders` array is omitted (no header is emitted), but its
+ * name is still validated so invalid names fail closed even with zero values.
+ * If header/body application fails before headers are sent, any headers staged
+ * by this call are removed before the error propagates so a fallback 500 stays clean.
  *
  * Public helper for adapters that need the same AWS REST API v1 result-to-HTTP
  * translation as the `start-serverless` command.
@@ -298,14 +438,22 @@ declare function applyServerlessResult(result: unknown, res: Response): void;
 /**
  * Create an Express app that proxies all requests to a serverless handler.
  * Each HTTP request is translated into a serverless event, the handler is
- * invoked, and the result is written back to the response.
+ * invoked as `handler(event, {})` where `event` is an `ApiGatewayRestEvent`
+ * and the context is an empty record, and the result is written back to the
+ * response.
  *
- * Express body parsers are disabled; the raw request body is read directly
- * from the stream and passed as a Buffer (so the serverless handler's request
- * hook — including the #305 workaround — works identically to production).
+ * Express body parsers are disabled; the raw request body is buffered with
+ * `collectBody` and then base64-encoded into the AWS v1 string `body` field
+ * (`isBase64Encoded` is true for non-empty bodies, false with `body: ''` for
+ * empty ones), so `serverless-http` replays the decoded bytes through the
+ * Express request stream identically to production.
  * Bodies exceeding `maxBodyBytes` (default 1 MiB, 0 = empty bodies only) receive
  * `413 Payload Too Large` without invoking the handler; the request is drained
- * and retained memory is bounded to the limit plus at most one chunk.
+ * and chunk retention is O(limit) — appending stops once the running total
+ * would exceed the limit, so at most one chunk over the limit is observed
+ * before rejection. `Buffer.concat` retains the chunks plus one output Buffer
+ * and event translation adds a transient base64 copy (~4/3 of the body), so
+ * peak transient memory is a small multiple of the limit.
  */
 declare function createServerlessAdapterApp(handler: GenericHandler, options?: ServerlessAdapterOptions): Express;
 /**