@gcoredev/fastedge-test 0.1.6 → 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
 
 ```
@@ -93,16 +95,19 @@ Loads a WASM binary into the runner. Accepts either a file path or a base64-enco
 
 **Request Body**
 
-Exactly one of `wasmPath` or `wasmBase64` must be provided.
+Exactly one of `wasmPath` or `wasmBase64` must be provided; providing both is an error.
 
 ```typescript
 {
-  wasmPath?: string;   // Absolute path to a .wasm file on the server filesystem
-  wasmBase64?: string; // Base64-encoded WASM binary
+  wasmPath?: string;    // Absolute path to a .wasm file on the server filesystem
+  wasmBase64?: string;  // Base64-encoded WASM binary; mutually exclusive with wasmPath
   dotenv?: {
-    enabled: boolean;  // Whether to load .env files for this module
-    path?: string;     // Directory containing .env files (defaults to server CWD)
+    enabled?: boolean;  // Whether to load .env files for this module
+    path?: string;      // Directory containing .env files (defaults to server CWD)
   };
+  httpPort?: number;    // HTTP-WASM only. Pin the runner subprocess to this port (1024–65535).
+                        // Load fails immediately if the port is already in use.
+                        // Ignored for proxy-wasm modules.
 }
 ```
 
@@ -153,11 +158,31 @@ curl -X POST http://localhost:5179/api/load \
 }
 ```
 
+**Example — pin HTTP-WASM to a specific port**
+
+```bash
+curl -X POST http://localhost:5179/api/load \
+  -H "Content-Type: application/json" \
+  -d '{
+    "wasmPath": "/home/user/project/build/app.wasm",
+    "httpPort": 8100
+  }'
+```
+
+```json
+{
+  "ok": true,
+  "wasmType": "http-wasm",
+  "resolvedPath": "/home/user/project/build/app.wasm"
+}
+```
+
 **Error Responses**
 
 | Status | Condition                                                                                                   |
 | ------ | ----------------------------------------------------------------------------------------------------------- |
 | `400`  | Validation failed, missing both `wasmPath` and `wasmBase64`, invalid path, or path does not end in `.wasm` |
+| `400`  | `httpPort` is specified and already in use (HTTP-WASM only)                                                 |
 | `500`  | WASM load failed or runner initialization error                                                             |
 
 ---
@@ -234,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: {})
 }
 ```
@@ -262,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;
@@ -280,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;
@@ -296,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>;
@@ -354,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": {}
   }'
 ```
@@ -452,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>;
@@ -533,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**
 
@@ -559,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;
@@ -583,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"
     }
@@ -647,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                                                             |
 
@@ -689,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 };
 };
@@ -703,6 +704,7 @@ type HttpWasmConfig = {
   description?: string;
   appType: "http-wasm";
   wasm?: { path: string; description?: string };
+  httpPort?: number; // Pin the runner subprocess to this port (1024–65535)
   request: {
     method: string;
     path: string;
@@ -734,10 +736,6 @@ curl http://localhost:5179/api/config
       "headers": {},
       "body": ""
     },
-    "response": {
-      "headers": {},
-      "body": ""
-    },
     "properties": {}
   },
   "valid": true
@@ -792,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

@@ -71,7 +71,7 @@ process.kill(process.pid, "SIGTERM");
 PORT=8080 npx fastedge-debug
 ```
 
-If the preferred port is already in use, the server tries the next port sequentially, repeating up to 10 times (for example, `5179` through `5188` by default). If no free port is found in that range, the server exits with an error. Set `PORT` to a specific value to bypass auto-increment when a predictable port is required.
+If the preferred port is already in use, the server tries the next port sequentially, up to 50 ports (for example, `5179` through `5228` by default). If no free port is found in that range, the server exits with an error. Set `PORT` to a specific value to bypass auto-increment when a predictable port is required.
 
 The server writes the bound port number to `.fastedge-debug/.debug-port` under `WORKSPACE_PATH` (if set) or the current working directory, and deletes the file on shutdown. Use this file for programmatic port discovery when starting the server as a subprocess.
 
@@ -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                               |