@gcoredev/fastedge-test 0.1.7 → 0.2.0

package/docs/API.md

@@ -2,6 +2,8 @@
 
 The `@gcoredev/fastedge-test` debugger server exposes a REST API for loading WASM modules, executing requests, and managing test configuration.
 
+> **Note on header values.** Response-side and hook-result headers use `Record<string, string | string[]>` — single-valued headers are a `string`, multi-valued headers (notably `Set-Cookie` per RFC 6265) are a `string[]`. Request-side header inputs are single-valued `Record<string, string>`.
+
 ## Base URL
 
 ```
@@ -257,22 +259,16 @@ For **HTTP-WASM**, provide either `path` (preferred) or `url` (legacy). When `pa
 }
 ```
 
-For **Proxy-WASM**, the top-level `url` field is required. The full CDN flow is controlled via nested `request`, `response`, and `properties` fields:
+For **Proxy-WASM**, the top-level `url` field is required. The full CDN flow is controlled via nested `request` and `properties` fields. The upstream response is generated at runtime — either by a real fetch against `url`, or by the built-in responder when `url === "built-in"`:
 
 ```typescript
 {
-  url: string;                          // Request URL (required)
+  url: string;                          // Request URL, or "built-in" (required)
   request?: {
     method?: string;                    // HTTP method (default: "GET")
     headers?: Record<string, string>;   // Request headers (default: {})
     body?: string;                      // Request body (default: "")
   };
-  response?: {
-    headers?: Record<string, string>;   // Simulated upstream response headers (default: {})
-    body?: string;                      // Simulated upstream response body (default: "")
-    status?: number;                    // Simulated upstream response status (default: 200)
-    statusText?: string;                // Simulated upstream response status text (default: "OK")
-  };
   properties?: Record<string, unknown>; // CDN properties (default: {})
 }
 ```
@@ -285,7 +281,7 @@ For **Proxy-WASM**, the top-level `url` field is required. The full CDN flow is
   result: {
     status: number;
     statusText: string;
-    headers: Record<string, string>;
+    headers: Record<string, string | string[]>;
     body: string;
     contentType: string | null;
     isBase64?: boolean;
@@ -303,7 +299,7 @@ For **Proxy-WASM**, the top-level `url` field is required. The full CDN flow is
   finalResponse: {
     status: number;
     statusText: string;
-    headers: Record<string, string>;
+    headers: Record<string, string | string[]>;
     body: string;
     contentType: string;
     isBase64?: boolean;
@@ -319,13 +315,13 @@ type HookResult = {
   returnCode: number | null;
   logs: Array<{ level: number; message: string }>;
   input: {
-    request: { headers: Record<string, string>; body: string };
-    response: { headers: Record<string, string>; body: string };
+    request: { headers: Record<string, string | string[]>; body: string };
+    response: { headers: Record<string, string | string[]>; body: string };
     properties?: Record<string, unknown>;
   };
   output: {
-    request: { headers: Record<string, string>; body: string };
-    response: { headers: Record<string, string>; body: string };
+    request: { headers: Record<string, string | string[]>; body: string };
+    response: { headers: Record<string, string | string[]>; body: string };
     properties?: Record<string, unknown>;
   };
   properties: Record<string, unknown>;
@@ -377,12 +373,6 @@ curl -X POST http://localhost:5179/api/execute \
       "headers": { "host": "example.com" },
       "body": ""
     },
-    "response": {
-      "headers": { "content-type": "text/html" },
-      "body": "<html/>",
-      "status": 200,
-      "statusText": "OK"
-    },
     "properties": {}
   }'
 ```
@@ -475,13 +465,13 @@ type HookResult = {
   returnCode: number | null;
   logs: Array<{ level: number; message: string }>;
   input: {
-    request: { headers: Record<string, string>; body: string };
-    response: { headers: Record<string, string>; body: string };
+    request: { headers: Record<string, string | string[]>; body: string };
+    response: { headers: Record<string, string | string[]>; body: string };
     properties?: Record<string, unknown>;
   };
   output: {
-    request: { headers: Record<string, string>; body: string };
-    response: { headers: Record<string, string>; body: string };
+    request: { headers: Record<string, string | string[]>; body: string };
+    response: { headers: Record<string, string | string[]>; body: string };
     properties?: Record<string, unknown>;
   };
   properties: Record<string, unknown>;
@@ -556,22 +546,18 @@ Requires a WASM module to be loaded via `POST /api/load`. Accepts an optional [`
 
 ```typescript
 {
-  url: string | "built-in";            // Full request URL, or "built-in" to use the URL from loaded config
+  url: string | "built-in";            // Full request URL, or "built-in" to use the built-in responder
   request?: {
     method?: string;                   // HTTP method (default: "GET")
     url?: string;
     headers?: Record<string, string>;  // Request headers (default: {})
     body?: string;                     // Request body (default: "")
   };
-  response?: {
-    headers?: Record<string, string>;  // Simulated upstream response headers (default: {})
-    body?: string;                     // Simulated upstream response body (default: "")
-  };
   properties: Record<string, unknown>; // CDN properties (required; use {} if none)
 }
 ```
 
-The `response` object for this endpoint does not accept `status` or `statusText` — the full flow always uses `200 OK` as the simulated upstream status. Use `POST /api/execute` if you need to control those values.
+The upstream response is generated at runtime — either by a real fetch against `url`, or by the built-in responder when `url === "built-in"`.
 
 **Response**
 
@@ -582,7 +568,7 @@ The `response` object for this endpoint does not accept `status` or `statusText`
   finalResponse: {
     status: number;
     statusText: string;
-    headers: Record<string, string>;
+    headers: Record<string, string | string[]>;
     body: string;
     contentType: string;
     isBase64?: boolean;
@@ -606,10 +592,6 @@ curl -X POST http://localhost:5179/api/send \
       "headers": { "content-type": "application/json" },
       "body": "{\"key\":\"value\"}"
     },
-    "response": {
-      "headers": { "content-type": "application/json" },
-      "body": "{\"result\":\"ok\"}"
-    },
     "properties": {
       "client.geo.country": "DE"
     }
@@ -670,8 +652,8 @@ curl -X POST http://localhost:5179/api/send \
 
 **Error Responses**
 
-| Status | Condition                                                                   |
-| ------ | --------------------------------------------------------------------------- |
+| Status | Condition                                                                    |
+| ------ | ---------------------------------------------------------------------------- |
 | `400`  | Validation failed (missing `url` or `properties`), or no WASM module loaded |
 | `500`  | Execution failed                                                             |
 
@@ -712,10 +694,6 @@ type ProxyWasmConfig = {
     headers: Record<string, string>;
     body: string;
   };
-  response?: {
-    headers: Record<string, string>;
-    body: string;
-  };
   properties: Record<string, unknown>;
   dotenv?: { enabled?: boolean; path?: string };
 };
@@ -758,10 +736,6 @@ curl http://localhost:5179/api/config
       "headers": {},
       "body": ""
     },
-    "response": {
-      "headers": {},
-      "body": ""
-    },
     "properties": {}
   },
   "valid": true
@@ -816,10 +790,6 @@ curl -X POST http://localhost:5179/api/config \
         "headers": { "accept": "text/html" },
         "body": ""
       },
-      "response": {
-        "headers": {},
-        "body": ""
-      },
       "properties": {
         "client.geo.country": "US"
       }

package/docs/DEBUGGER.md

@@ -98,13 +98,12 @@ curl http://localhost:5179/health
 
 ## Environment Variables
 
-| Variable             | Type     | Default | Description                                                                                                                |
-| -------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `PORT`               | `number` | unset   | Port the HTTP server listens on. Defaults to `5179` when not set.                                                         |
-| `PROXY_RUNNER_DEBUG` | `"1"`    | unset   | Enable verbose debug logging for WebSocket and runner activity.                                                            |
-| `VSCODE_INTEGRATION` | `"true"` | unset   | Set to `"true"` when running in VSCode extension context; enables the `<workspace>` path placeholder in WASM path loading. |
-| `WORKSPACE_PATH`     | `string` | unset   | Absolute path to the workspace root; used as the `.env` file base and for port file placement.                             |
-| `FASTEDGE_RUN_PATH`  | `string` | unset   | Override the path to the `fastedge-run` CLI binary used to execute WASM modules.                                          |
+| Variable             | Type     | Default | Description                                                                                     |
+| -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `PORT`               | `number` | unset   | Port the HTTP server listens on. Defaults to `5179` when not set.                              |
+| `PROXY_RUNNER_DEBUG` | `"1"`    | unset   | Enable verbose debug logging for WebSocket and runner activity.                                 |
+| `WORKSPACE_PATH`     | `string` | unset   | Absolute path to the workspace root; used as the `.env` file base and for port file placement. |
+| `FASTEDGE_RUN_PATH`  | `string` | unset   | Override the path to the `fastedge-run` CLI binary used to execute WASM modules.               |
 
 ### Usage examples
 

package/docs/INDEX.md

@@ -79,12 +79,13 @@ import { defineTestSuite, runAndExit } from "@gcoredev/fastedge-test/test";
 | `runFlow`                    | function | Executes a single request flow directly                              |
 | `runHttpRequest`             | function | Executes a single HTTP request directly                              |
 | `loadConfigFile`             | function | Loads and validates a `fastedge-config.test.json` file               |
+| `mockOrigins`                | function | Creates mock HTTP origins that respond to outgoing HTTP calls        |
 | `assertRequestHeader`        | function | Asserts a header is present on the outgoing request                  |
 | `assertNoRequestHeader`      | function | Asserts a header is absent from the outgoing request                 |
 | `assertResponseHeader`       | function | Asserts a header is present on the final response                    |
 | `assertNoResponseHeader`     | function | Asserts a header is absent from the final response                   |
 | `assertFinalStatus`          | function | Asserts the final HTTP status code                                   |
-| `assertFinalHeader`          | function | Asserts a header on the final response (alias for response header)   |
+| `assertFinalHeader`          | function | Asserts a header on the final response                               |
 | `assertReturnCode`           | function | Asserts the proxy-wasm return code                                   |
 | `assertLog`                  | function | Asserts a log entry was emitted                                      |
 | `assertNoLog`                | function | Asserts a log entry was not emitted                                  |
@@ -101,6 +102,8 @@ import { defineTestSuite, runAndExit } from "@gcoredev/fastedge-test/test";
 | `assertHttpContentType`      | function | Asserts the HTTP response Content-Type header                        |
 | `assertHttpLog`              | function | Asserts a log entry was emitted during HTTP request handling         |
 | `assertHttpNoLog`            | function | Asserts a log entry was not emitted during HTTP request handling     |
+| `MockOriginsHandle`          | type     | Handle returned by `mockOrigins` — use to stop the mock servers      |
+| `MockOriginsOptions`         | type     | Options accepted by `mockOrigins`                                    |
 | `TestSuite`                  | type     | Suite definition — one of `wasmPath` or `wasmBuffer` plus test cases |
 | `TestCase`                   | type     | A single test scenario with config and assertions                    |
 | `TestResult`                 | type     | Result of a single test case execution                               |

package/docs/RUNNER.md

@@ -102,10 +102,6 @@ interface IWasmRunner {
     method: string,
     headers: Record<string, string>,
     body: string,
-    responseHeaders: Record<string, string>,
-    responseBody: string,
-    responseStatus: number,
-    responseStatusText: string,
     properties: Record<string, unknown>,
     enforceProductionPropertyRules: boolean
   ): Promise<FullFlowResult>;
@@ -161,7 +157,7 @@ const runner = await createRunner('./my-http-app.wasm');
 let response = await runner.execute({ path: '/moved', method: 'GET', headers: {} });
 if (response.status >= 300 && response.status < 400 && response.headers['location']) {
   response = await runner.execute({
-    path: response.headers['location'], // e.g. "/new-location"
+    path: response.headers['location'] as string, // e.g. "/new-location"
     method: 'GET',
     headers: {},
   });
@@ -192,10 +188,6 @@ callFullFlow(
   method: string,
   headers: Record<string, string>,
   body: string,
-  responseHeaders: Record<string, string>,
-  responseBody: string,
-  responseStatus: number,
-  responseStatusText: string,
   properties: Record<string, unknown>,
   enforceProductionPropertyRules: boolean
 ): Promise<FullFlowResult>
@@ -203,22 +195,20 @@ callFullFlow(
 
 **Parameters**
 
-| Parameter                        | Type                      | Description                                                                                                          |
-| -------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `url`                            | `string`                  | Full request URL, or `BUILTIN_SHORTHAND` (`"built-in"`) to use the built-in responder instead of a real origin fetch |
-| `method`                         | `string`                  | HTTP method                                                                                                          |
-| `headers`                        | `Record<string, string>`  | Request headers                                                                                                      |
-| `body`                           | `string`                  | Request body                                                                                                         |
-| `responseHeaders`                | `Record<string, string>`  | Upstream response headers (used as initial state for response hooks)                                                 |
-| `responseBody`                   | `string`                  | Upstream response body                                                                                               |
-| `responseStatus`                 | `number`                  | Upstream response status code                                                                                        |
-| `responseStatusText`             | `string`                  | Upstream response status text                                                                                        |
-| `properties`                     | `Record<string, unknown>` | Shared properties passed to all hooks                                                                                |
-| `enforceProductionPropertyRules` | `boolean`                 | When `true`, restricts property access to match CDN production behavior                                              |
+| Parameter                        | Type                      | Description                                                                                                           |
+| -------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `url`                            | `string`                  | Full request URL, or `BUILTIN_SHORTHAND` (`"built-in"`) to use the built-in responder instead of a real origin fetch  |
+| `method`                         | `string`                  | HTTP method                                                                                                           |
+| `headers`                        | `Record<string, string>`  | Request headers                                                                                                       |
+| `body`                           | `string`                  | Request body                                                                                                          |
+| `properties`                     | `Record<string, unknown>` | Shared properties passed to all hooks                                                                                 |
+| `enforceProductionPropertyRules` | `boolean`                 | When `true`, restricts property access to match CDN production behavior                                               |
+
+The upstream response is generated at runtime — either by a real HTTP fetch against `url`, or by the built-in responder when `url === "built-in"`. There is no caller-provided mock response.
 
 Hook execution order: `onRequestHeaders` → `onRequestBody` → *(real HTTP fetch or built-in responder)* → `onResponseHeaders` → `onResponseBody`.
 
-**Local response short-circuit:** If a WASM module calls `send_http_response` (proxy-wasm: `proxy_send_local_response`) during `onRequestHeaders` or `onRequestBody` and returns `StopIteration` (return code `1`), the remaining hooks and origin fetch are **skipped**. The `finalResponse` in the result is built from the locally-sent status, headers, and body — matching CDN production behavior. This is how redirect modules (e.g., geo-redirect) and early error responses work.
+**Local response short-circuit.** If a WASM module calls `proxy_send_local_response` during `onRequestHeaders` or `onRequestBody` and returns `StopIteration` (return code `1`), the remaining hooks and origin fetch are skipped. The `finalResponse` in the result is built from the locally-sent status, headers, and body — matching CDN production behavior. This is how redirect modules (e.g., geo-redirect) and early error responses work.
 
 Only available on `ProxyWasmRunner`. Calling on `HttpWasmRunner` throws.
 
@@ -314,16 +304,17 @@ const result: FullFlowResult = await runner.callFullFlow(
   'GET',
   { 'accept': 'application/json' },
   '',
-  {}, '', 200, 'OK', {}, true,
+  {},   // properties
+  true, // enforceProductionPropertyRules
 );
 ```
 
 **Built-in responder behavior** — controlled by request headers set before the origin phase:
 
-| Header               | Effect                                                                          |
-| -------------------- | ------------------------------------------------------------------------------- |
-| `x-debugger-status`  | HTTP status code for the generated response (default: `200`)                    |
-| `x-debugger-content` | Response body mode: `"body-only"`, `"status-only"`, or full JSON echo (default) |
+| Header               | Effect                                                                           |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `x-debugger-status`  | HTTP status code for the generated response (default: `200`)                     |
+| `x-debugger-content` | Response body mode: `"body-only"`, `"status-only"`, or full JSON echo (default)  |
 
 When `x-debugger-content` is omitted, the built-in responder returns a JSON echo of the request method, headers, body, and URL. Both control headers are stripped before response hooks execute so they do not appear in hook input state.
 
@@ -345,13 +336,13 @@ interface RunnerConfig {
 }
 ```
 
-| Field                            | Type       | Default       | Description                                                                                                                                                                                                                                                                                                                        |
-| -------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dotenv.enabled`                 | `boolean`  | `false`       | Whether to load `.env` files                                                                                                                                                                                                                                                                                                       |
-| `dotenv.path`                    | `string`   | `undefined`   | Directory to load dotenv files from. When omitted, `fastedge-run` uses the process CWD — correct for most npm package users whose `.env` files live at the project root. Only set this when your dotenv files are in a non-standard location (e.g. a test fixture directory).                                                      |
-| `enforceProductionPropertyRules` | `boolean`  | `true`        | Restrict property access to match CDN production behavior                                                                                                                                                                                                                                                                          |
-| `runnerType`                     | `WasmType` | auto-detected | Override WASM type detection                                                                                                                                                                                                                                                                                                       |
-| `httpPort`                       | `number`   | `undefined`   | HTTP-WASM only. Pin the spawned `fastedge-run` subprocess to a specific port instead of allocating from the dynamic pool (8100–8199). `load()` throws if the port is busy — there is no fallback to dynamic allocation. Intended for Codespaces/Docker port-forwarding or external tooling requiring a fixed address. Ignored for proxy-wasm runners. |
+| Field                            | Type       | Default         | Description                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dotenv.enabled`                 | `boolean`  | `false`         | Whether to load `.env` files                                                                                                                                                                                                                                                                                                                 |
+| `dotenv.path`                    | `string`   | `undefined`     | Directory to load dotenv files from. When omitted, `fastedge-run` uses the process CWD — correct for most npm package users whose `.env` files live at the project root. Only set this when your dotenv files are in a non-standard location (e.g. a test fixture directory).                                                                |
+| `enforceProductionPropertyRules` | `boolean`  | `true`          | Restrict property access to match CDN production behavior                                                                                                                                                                                                                                                                                    |
+| `runnerType`                     | `WasmType` | *auto-detected* | Override WASM type detection                                                                                                                                                                                                                                                                                                                 |
+| `httpPort`                       | `number`   | `undefined`     | HTTP-WASM only. Pin the spawned `fastedge-run` subprocess to a specific port instead of allocating from the dynamic pool (8100–8199). `load()` throws if the port is busy — there is no fallback to dynamic allocation. Intended for Codespaces/Docker port-forwarding or external tooling requiring a fixed address. Ignored for proxy-wasm. |
 
 ### HttpRequest & HttpResponse
 
@@ -366,7 +357,11 @@ interface HttpRequest {
 interface HttpResponse {
   status: number;
   statusText: string;
-  headers: Record<string, string>;
+  // Node's IncomingHttpHeaders (from "node:http"):
+  //   known single-valued headers (content-type, location, etag, …) are typed as string
+  //   set-cookie is always string[] when present
+  //   unknown headers are string | string[] | undefined
+  headers: IncomingHttpHeaders;
   body: string;
   contentType: string | null;
   isBase64?: boolean;
@@ -380,20 +375,37 @@ interface HttpResponse {
 
 `HttpResponse.logs` contains log entries captured from the `fastedge-run` process stdout/stderr during the request.
 
+**Multi-valued headers.** `Set-Cookie` is preserved as a `string[]` — each `Set-Cookie` header emitted by the WASM app (or an upstream origin) becomes a separate array entry. This matches RFC 6265 §3 and Node's fetch behavior. Example:
+
+```typescript
+const response = await runner.execute({ path: '/login', method: 'POST', headers: {} });
+const cookies = response.headers['set-cookie']; // string[] | undefined
+for (const cookie of cookies ?? []) {
+  console.log(cookie);
+}
+```
+
+Single-valued headers read as plain strings with no narrowing needed:
+
+```typescript
+const location = response.headers['location'];        // string | undefined
+const contentType = response.headers['content-type']; // string | undefined
+```
+
 ### HookCall
 
 ```typescript
 type HookCall = {
   hook: string;
   request: {
-    headers: HeaderMap;
+    headers: HeaderRecord;
     body: string;
     method?: string;
     path?: string;
     scheme?: string;
   };
-  response: {
-    headers: HeaderMap;
+  response?: {
+    headers: HeaderRecord;
     body: string;
     status?: number;
     statusText?: string;
@@ -404,14 +416,16 @@ type HookCall = {
 };
 ```
 
-| Field                            | Description                                                                                         |
-| -------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `hook`                           | Hook name: `"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`       |
-| `request`                        | Request state passed to the hook                                                                    |
-| `response`                       | Response state passed to the hook                                                                   |
-| `properties`                     | Shared properties (e.g. `request.path`, `vm_config`, `plugin_config`)                               |
-| `dotenvEnabled`                  | Optional per-call dotenv override. Use `applyDotenv()` for persistent changes.                      |
-| `enforceProductionPropertyRules` | Defaults to `true`. Set to `false` to allow property reads that would be blocked on production CDN. |
+| Field                            | Description                                                                                                                                                                  |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hook`                           | Hook name: `"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`                                                                                |
+| `request`                        | Request state passed to the hook                                                                                                                                             |
+| `response`                       | Seed state for response hooks called via `callHook()`. Ignored by `callFullFlow()` and by request hooks — the full-flow path generates the upstream response at runtime.     |
+| `properties`                     | Shared properties (e.g. `request.path`, `vm_config`, `plugin_config`)                                                                                                       |
+| `dotenvEnabled`                  | Optional per-call dotenv override. Use `applyDotenv()` for persistent changes.                                                                                              |
+| `enforceProductionPropertyRules` | Defaults to `true`. Set to `false` to allow property reads that would be blocked on production CDN.                                                                         |
+
+`HeaderRecord` is `Record<string, string | string[]>` — multi-valued headers (e.g. multiple `Set-Cookie`) are represented as `string[]`.
 
 ### HookResult
 
@@ -420,26 +434,26 @@ type HookResult = {
   returnCode: number | null;
   logs: { level: number; message: string }[];
   input: {
-    request: { headers: HeaderMap; body: string };
-    response: { headers: HeaderMap; body: string };
+    request: { headers: HeaderRecord; body: string };
+    response: { headers: HeaderRecord; body: string };
     properties?: Record<string, unknown>;
   };
   output: {
-    request: { headers: HeaderMap; body: string };
-    response: { headers: HeaderMap; body: string };
+    request: { headers: HeaderRecord; body: string };
+    response: { headers: HeaderRecord; body: string };
     properties?: Record<string, unknown>;
   };
   properties: Record<string, unknown>;
 };
 ```
 
-| Field        | Description                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `returnCode` | The numeric value returned by the WASM hook export, or `null` if the export was not found |
-| `logs`       | Log entries emitted via `proxy_log` during hook execution                                  |
-| `input`      | Request/response state as seen by the hook before execution                                |
-| `output`     | Request/response state after hook execution (reflects WASM mutations)                      |
-| `properties` | All shared properties after hook execution                                                 |
+| Field        | Description                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------- |
+| `returnCode` | The numeric value returned by the WASM hook export, or `null` if the export was not found  |
+| `logs`       | Log entries emitted via `proxy_log` during hook execution                                   |
+| `input`      | Request/response state as seen by the hook before execution                                 |
+| `output`     | Request/response state after hook execution (reflects WASM mutations)                       |
+| `properties` | All shared properties after hook execution                                                  |
 
 ### FullFlowResult
 
@@ -449,7 +463,7 @@ type FullFlowResult = {
   finalResponse: {
     status: number;
     statusText: string;
-    headers: HeaderMap;
+    headers: HeaderRecord;
     body: string;
     contentType: string;
     isBase64?: boolean;
@@ -458,19 +472,23 @@ type FullFlowResult = {
 };
 ```
 
-| Field                  | Description                                                                                                                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hookResults`          | A `Record` keyed by hook name (`"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`), each containing a `HookResult`                          |
-| `finalResponse`        | The final response after all hooks have executed, or the local response if a hook short-circuited (see `callFullFlow`). `body` is base64-encoded when `isBase64` is `true`. |
-| `calculatedProperties` | Runtime properties computed from the request URL (e.g. `request.path`, `request.host`)                                                                                      |
+| Field                  | Description                                                                                                                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hookResults`          | A `Record` keyed by hook name (`"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`), each containing a `HookResult`                           |
+| `finalResponse`        | The final response after all hooks have executed, or the local response if a hook short-circuited (see `callFullFlow`). `body` is base64-encoded when `isBase64` is `true`.  |
+| `calculatedProperties` | Runtime properties computed from the request URL (e.g. `request.path`, `request.host`)                                                                                       |
 
 ### Supporting Types
 
 ```typescript
 type WasmType = 'http-wasm' | 'proxy-wasm';
 
+// Single-valued headers only — used as callFullFlow input parameters
 type HeaderMap = Record<string, string>;
 
+// Single- or multi-valued headers — used in HookCall, HookResult, and FullFlowResult
+type HeaderRecord = Record<string, string | string[]>;
+
 type LogEntry = {
   level: number;
   message: string;
@@ -498,7 +516,7 @@ interface IStateManager {
   emitRequestStarted(
     url: string,
     method: string,
-    headers: Record<string, string>,
+    headers: Record<string, string | string[]>,
     source?: EventSource,
   ): void;
 
@@ -507,12 +525,12 @@ interface IStateManager {
     returnCode: number | null,
     logCount: number,
     input: {
-      request: { headers: Record<string, string>; body: string };
-      response: { headers: Record<string, string>; body: string };
+      request: { headers: Record<string, string | string[]>; body: string };
+      response: { headers: Record<string, string | string[]>; body: string };
     },
     output: {
-      request: { headers: Record<string, string>; body: string };
-      response: { headers: Record<string, string>; body: string };
+      request: { headers: Record<string, string | string[]>; body: string };
+      response: { headers: Record<string, string | string[]>; body: string };
     },
     source?: EventSource,
   ): void;
@@ -522,7 +540,7 @@ interface IStateManager {
     finalResponse: {
       status: number;
       statusText: string;
-      headers: Record<string, string>;
+      headers: Record<string, string | string[]>;
       body: string;
       contentType: string;
       isBase64?: boolean;
@@ -544,7 +562,7 @@ interface IStateManager {
     response: {
       status: number;
       statusText: string;
-      headers: Record<string, string>;
+      headers: Record<string, string | string[] | undefined>;
       body: string;
       contentType: string | null;
       isBase64?: boolean;
@@ -575,19 +593,15 @@ async function testCdnApp() {
   try {
     // Execute the full CDN request/response lifecycle
     const result: FullFlowResult = await runner.callFullFlow(
-      'https://example.com/api/data',         // request URL
-      'GET',                                   // method
-      { 'accept': 'application/json' },        // request headers
-      '',                                      // request body
-      { 'content-type': 'application/json' },  // upstream response headers
-      '{"key":"value"}',                       // upstream response body
-      200,                                     // upstream response status
-      'OK',                                    // upstream response status text
+      'https://example.com/api/data',   // request URL
+      'GET',                            // method
+      { 'accept': 'application/json' }, // request headers
+      '',                               // request body
       {
         'request.path': '/api/data',
         'request.host': 'example.com',
-      },                                       // shared properties
-      true,                                    // enforce production property rules
+      },                                // shared properties
+      true,                             // enforce production property rules
     );
 
     // Inspect hook results
@@ -647,7 +661,8 @@ async function testCdnAppOffline() {
       'GET',
       { 'accept': 'application/json' },
       '',
-      {}, '', 200, 'OK', {}, true,
+      {},   // properties
+      true, // enforceProductionPropertyRules
     );
 
     console.log('Final status:', result.finalResponse.status);