@gcoredev/fastedge-test 0.0.1-beta.0 → 0.1.0-beta.2

package/docs/WEBSOCKET.md

@@ -0,0 +1,499 @@
+# WebSocket API
+
+Real-time event stream from the `@gcoredev/fastedge-test` server to connected clients.
+
+## Connection
+
+Connect to the WebSocket server at:
+
+```
+ws://localhost:{port}/ws
+```
+
+where `{port}` is the port the server is running on (default `5179`).
+
+```javascript
+const ws = new WebSocket("ws://localhost:5179/ws");
+
+ws.addEventListener("message", (event) => {
+  const msg = JSON.parse(event.data);
+  console.log(msg.type, msg.data);
+});
+```
+
+### Lifecycle
+
+1. **Connect** — the server accepts all connections and immediately sends a `connection_status` event confirming the connection and the current client count.
+2. **Ping / pong** — the server sends WebSocket `ping` frames every 15 seconds. Clients that have not responded within 30 seconds are terminated. Standard WebSocket clients handle pong automatically.
+3. **Disconnect** — when a client disconnects, the server broadcasts an updated `connection_status` to remaining clients.
+
+## Event Format
+
+Every event shares a common envelope:
+
+```typescript
+interface BaseEvent {
+  type: string; // event discriminant
+  timestamp: number; // Unix ms
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: object; // event-specific payload
+}
+```
+
+| Field       | Type                                      | Description                                         |
+| ----------- | ----------------------------------------- | --------------------------------------------------- |
+| `type`      | `string`                                  | Event discriminant — one of the values listed below |
+| `timestamp` | `number`                                  | Unix epoch in milliseconds                          |
+| `source`    | `'ui' \| 'ai_agent' \| 'api' \| 'system'` | What triggered the event                            |
+| `data`      | `object`                                  | Event-specific payload                              |
+
+## Event Types
+
+### wasm_loaded
+
+Fired when a WASM binary has been loaded and is ready to handle requests.
+
+```typescript
+interface WasmLoadedEvent {
+  type: "wasm_loaded";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    filename: string;
+    size: number;
+    runnerPort?: number | null;
+    wasmType: "proxy-wasm" | "http-wasm";
+    resolvedPath?: string | null;
+  };
+}
+```
+
+| Field           | Type                          | Description                                                          |
+| --------------- | ----------------------------- | -------------------------------------------------------------------- |
+| `filename`      | `string`                      | Name of the loaded WASM file                                         |
+| `size`          | `number`                      | File size in bytes                                                   |
+| `runnerPort?`   | `number \| null `             | Port the runner is listening on, if applicable. Omitted when not set |
+| `wasmType`      | `'proxy-wasm' \| 'http-wasm'` | The WASM filter type                                                 |
+| `resolvedPath?` | `string \| null `             | Absolute filesystem path to the loaded binary. Omitted when not set  |
+
+**Example:**
+
+```json
+{
+  "type": "wasm_loaded",
+  "timestamp": 1742734800000,
+  "source": "api",
+  "data": {
+    "filename": "filter.wasm",
+    "size": 204800,
+    "runnerPort": 8081,
+    "wasmType": "proxy-wasm",
+    "resolvedPath": "/workspace/filter.wasm"
+  }
+}
+```
+
+---
+
+### request_started
+
+Fired when the server begins processing an incoming request through the WASM filter.
+
+```typescript
+interface RequestStartedEvent {
+  type: "request_started";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+  };
+}
+```
+
+| Field     | Type                     | Description                       |
+| --------- | ------------------------ | --------------------------------- |
+| `url`     | `string`                 | Full request URL                  |
+| `method`  | `string`                 | HTTP method (`GET`, `POST`, etc.) |
+| `headers` | `Record<string, string>` | Request headers                   |
+
+**Example:**
+
+```json
+{
+  "type": "request_started",
+  "timestamp": 1742734800100,
+  "source": "api",
+  "data": {
+    "url": "https://example.com/api/resource",
+    "method": "GET",
+    "headers": {
+      "host": "example.com",
+      "user-agent": "curl/8.0"
+    }
+  }
+}
+```
+
+---
+
+### hook_executed
+
+Fired after each individual proxy-wasm hook completes. Multiple `hook_executed` events are emitted per request — one per hook phase that runs.
+
+Hook names are camelCase: `onRequestHeaders`, `onRequestBody`, `onResponseHeaders`, `onResponseBody`.
+
+```typescript
+interface HookExecutedEvent {
+  type: "hook_executed";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    hook: string;
+    returnCode: number | null;
+    logCount: number;
+    input: {
+      request: { headers: Record<string, string>; body: string };
+      response: { headers: Record<string, string>; body: string };
+    };
+    output: {
+      request: { headers: Record<string, string>; body: string };
+      response: { headers: Record<string, string>; body: string };
+    };
+  };
+}
+```
+
+| Field        | Type             | Description                                                |
+| ------------ | ---------------- | ---------------------------------------------------------- |
+| `hook`       | `string`         | Hook name (e.g. `onRequestHeaders`)                        |
+| `returnCode` | `number \| null` | Return code from the WASM filter, or `null` if unavailable |
+| `logCount`   | `number`         | Number of log lines emitted during this hook               |
+| `input`      | `object`         | Request and response state passed into the hook            |
+| `output`     | `object`         | Request and response state after the hook ran              |
+
+**Example:**
+
+```json
+{
+  "type": "hook_executed",
+  "timestamp": 1742734800200,
+  "source": "api",
+  "data": {
+    "hook": "onRequestHeaders",
+    "returnCode": 0,
+    "logCount": 2,
+    "input": {
+      "request": {
+        "headers": { "host": "example.com" },
+        "body": ""
+      },
+      "response": {
+        "headers": {},
+        "body": ""
+      }
+    },
+    "output": {
+      "request": {
+        "headers": { "host": "example.com", "x-injected": "true" },
+        "body": ""
+      },
+      "response": {
+        "headers": {},
+        "body": ""
+      }
+    }
+  }
+}
+```
+
+---
+
+### request_completed
+
+Fired when all hook phases have completed and a final response is available.
+
+`hookResults` keys are camelCase hook names (`onRequestHeaders`, `onRequestBody`, `onResponseHeaders`, `onResponseBody`).
+
+```typescript
+interface RequestCompletedEvent {
+  type: "request_completed";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    hookResults: Record<string, any>;
+    finalResponse: {
+      status: number;
+      statusText: string;
+      headers: Record<string, string>;
+      body: string;
+      contentType: string;
+      isBase64?: boolean;
+    };
+    calculatedProperties?: Record<string, unknown>;
+  };
+}
+```
+
+| Field                       | Type                                   | Description                                           |
+| --------------------------- | -------------------------------------- | ----------------------------------------------------- |
+| `hookResults`               | `Record<string, any>`                  | Per-hook execution results, keyed by hook name        |
+| `finalResponse.status`      | `number`                               | HTTP status code                                      |
+| `finalResponse.statusText`  | `string`                               | HTTP status text                                      |
+| `finalResponse.headers`     | `Record<string, string>`               | Response headers                                      |
+| `finalResponse.body`        | `string`                               | Response body (may be base64 if `isBase64` is `true`) |
+| `finalResponse.contentType` | `string`                               | Content-Type of the response                          |
+| `finalResponse.isBase64`    | `boolean \| undefined`                 | Whether `body` is base64-encoded                      |
+| `calculatedProperties`      | `Record<string, unknown> \| undefined` | Properties computed during execution, if any          |
+
+**Example:**
+
+```json
+{
+  "type": "request_completed",
+  "timestamp": 1742734800500,
+  "source": "api",
+  "data": {
+    "hookResults": {
+      "onRequestHeaders": { "returnCode": 0 },
+      "onResponseHeaders": { "returnCode": 0 }
+    },
+    "finalResponse": {
+      "status": 200,
+      "statusText": "OK",
+      "headers": { "content-type": "application/json" },
+      "body": "{\"ok\":true}",
+      "contentType": "application/json",
+      "isBase64": false
+    },
+    "calculatedProperties": {}
+  }
+}
+```
+
+---
+
+### request_failed
+
+Fired when request processing fails before a response can be produced.
+
+```typescript
+interface RequestFailedEvent {
+  type: "request_failed";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    error: string;
+    details?: string;
+  };
+}
+```
+
+| Field     | Type                  | Description                                        |
+| --------- | --------------------- | -------------------------------------------------- |
+| `error`   | `string`              | Short error message                                |
+| `details` | `string \| undefined` | Extended error detail or stack trace, if available |
+
+**Example:**
+
+```json
+{
+  "type": "request_failed",
+  "timestamp": 1742734800300,
+  "source": "api",
+  "data": {
+    "error": "WASM execution error",
+    "details": "RuntimeError: memory access out of bounds"
+  }
+}
+```
+
+---
+
+### properties_updated
+
+Fired when the set of active properties changes (e.g. after a properties configuration update).
+
+```typescript
+interface PropertiesUpdatedEvent {
+  type: "properties_updated";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    properties: Record<string, string>;
+  };
+}
+```
+
+| Field        | Type                     | Description                                |
+| ------------ | ------------------------ | ------------------------------------------ |
+| `properties` | `Record<string, string>` | Full current property map after the update |
+
+**Example:**
+
+```json
+{
+  "type": "properties_updated",
+  "timestamp": 1742734800050,
+  "source": "ui",
+  "data": {
+    "properties": {
+      "plugin.name": "my-filter",
+      "plugin.version": "1.0.0"
+    }
+  }
+}
+```
+
+---
+
+### http_wasm_request_completed
+
+Fired when an http-wasm filter finishes processing a request and a response is available.
+
+```typescript
+interface HttpWasmRequestCompletedEvent {
+  type: "http_wasm_request_completed";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    response: {
+      status: number;
+      statusText: string;
+      headers: Record<string, string>;
+      body: string;
+      contentType: string | null;
+      isBase64?: boolean;
+    };
+  };
+}
+```
+
+| Field                  | Type                     | Description                                           |
+| ---------------------- | ------------------------ | ----------------------------------------------------- |
+| `response.status`      | `number`                 | HTTP status code                                      |
+| `response.statusText`  | `string`                 | HTTP status text                                      |
+| `response.headers`     | `Record<string, string>` | Response headers                                      |
+| `response.body`        | `string`                 | Response body (may be base64 if `isBase64` is `true`) |
+| `response.contentType` | `string \| null`         | Content-Type, or `null` if absent                     |
+| `response.isBase64`    | `boolean \| undefined`   | Whether `body` is base64-encoded                      |
+
+**Example:**
+
+```json
+{
+  "type": "http_wasm_request_completed",
+  "timestamp": 1742734800600,
+  "source": "api",
+  "data": {
+    "response": {
+      "status": 200,
+      "statusText": "OK",
+      "headers": { "content-type": "text/plain" },
+      "body": "Hello, world!",
+      "contentType": "text/plain",
+      "isBase64": false
+    }
+  }
+}
+```
+
+---
+
+### http_wasm_log
+
+Fired in real-time as the http-wasm filter emits log lines during both execute and live modes. One event is emitted per log line.
+
+```typescript
+interface HttpWasmLogEvent {
+  type: "http_wasm_log";
+  timestamp: number;
+  source: "ui" | "ai_agent" | "api" | "system";
+  data: {
+    level: number;
+    message: string;
+  };
+}
+```
+
+| Field     | Type     | Description                                          |
+| --------- | -------- | ---------------------------------------------------- |
+| `level`   | `number` | Log level (follows proxy-wasm log level conventions) |
+| `message` | `string` | Log message text                                     |
+
+**Example:**
+
+```json
+{
+  "type": "http_wasm_log",
+  "timestamp": 1742734800250,
+  "source": "api",
+  "data": {
+    "level": 2,
+    "message": "processing request to /api/resource"
+  }
+}
+```
+
+---
+
+### connection_status
+
+Fired by the server in three situations:
+
+1. Immediately after a client connects (sent only to the connecting client).
+2. When any client connects or disconnects (broadcast to all clients).
+3. In response to a client `ping` message.
+
+```typescript
+interface ConnectionStatusEvent {
+  type: "connection_status";
+  timestamp: number;
+  source: "system";
+  data: {
+    connected: boolean;
+    clientCount: number;
+  };
+}
+```
+
+| Field         | Type      | Description                                                      |
+| ------------- | --------- | ---------------------------------------------------------------- |
+| `connected`   | `boolean` | Always `true` when received (indicates this client is connected) |
+| `clientCount` | `number`  | Total number of currently connected clients including this one   |
+
+**Example:**
+
+```json
+{
+  "type": "connection_status",
+  "timestamp": 1742734800010,
+  "source": "system",
+  "data": {
+    "connected": true,
+    "clientCount": 1
+  }
+}
+```
+
+## Client Messages
+
+The server accepts one client-to-server message type over WebSocket.
+
+### ping
+
+Requests a `connection_status` response from the server. Useful for verifying the connection is alive at the application level, independent of the underlying WebSocket ping/pong frames.
+
+```json
+{ "type": "ping" }
+```
+
+The server responds by sending a `connection_status` event to the requesting client.
+
+All other commands (loading WASM, triggering requests, updating properties) are submitted via the REST API, not over WebSocket.
+
+## See Also
+
+- `API.md` — REST endpoints for triggering requests, loading WASM, and updating properties
+- `TEST_FRAMEWORK.md` — Using WebSocket events in automated tests

package/docs/quickstart.md

@@ -0,0 +1,171 @@
+# Quickstart — @gcoredev/fastedge-test
+
+A local test runner and debugger for FastEdge WASM modules.
+
+## Install
+
+```bash
+npm install --save-dev @gcoredev/fastedge-test
+```
+
+```bash
+pnpm add -D @gcoredev/fastedge-test
+```
+
+Requires Node.js >= 22.12.
+
+## Option 1: Interactive Debugger
+
+Launch the interactive debugger UI to inspect your WASM module's request/response behavior in a browser.
+
+```bash
+npx fastedge-debug
+```
+
+The server starts on port `5179` by default. Open `http://localhost:5179` in your browser to use the debugger interface.
+
+Use the `PORT` environment variable to override the default port:
+
+```bash
+PORT=8080 npx fastedge-debug
+```
+
+See [DEBUGGER.md](DEBUGGER.md) for full usage details.
+
+## Option 2: Programmatic Test Suite
+
+Use `defineTestSuite` and `runAndExit` to write test scripts that run in CI or as standalone Node.js programs.
+
+```typescript
+import { defineTestSuite, runAndExit, runFlow } from "@gcoredev/fastedge-test/test";
+
+const suite = defineTestSuite({
+  wasmPath: "./dist/my-module.wasm",
+  tests: [
+    {
+      name: "redirects /old-path to /new-path",
+      async run(runner) {
+        const result = await runFlow(runner, {
+          url: "https://example.com/old-path",
+          method: "GET",
+        });
+
+        const location = result.finalResponse.headers["location"];
+        if (location !== "/new-path") {
+          throw new Error(`Expected location "/new-path", got "${location}"`);
+        }
+      },
+    },
+    {
+      name: "adds X-Custom-Header to response",
+      async run(runner) {
+        const result = await runFlow(runner, {
+          url: "https://example.com/",
+          method: "GET",
+          responseStatus: 200,
+          responseBody: "hello",
+        });
+
+        const header = result.finalResponse.headers["x-custom-header"];
+        if (!header) {
+          throw new Error("Expected x-custom-header to be present");
+        }
+      },
+    },
+  ],
+});
+
+await runAndExit(suite);
+```
+
+`runAndExit` prints a test summary and exits with code `0` (all pass) or `1` (any fail), making it suitable for CI pipelines.
+
+See [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md) for the full API reference including `runTestSuite`, `loadConfigFile`, and all `FlowOptions` fields.
+
+## Option 3: Low-Level Runner
+
+Use `createRunner` directly when you need full control over the runner lifecycle, or when integrating with an existing test framework such as Vitest or Jest.
+
+```typescript
+import { createRunner } from "@gcoredev/fastedge-test";
+
+const runner = await createRunner("./dist/my-module.wasm");
+
+try {
+  const result = await runner.callFullFlow(
+    "https://example.com/",   // url
+    "GET",                    // method
+    {                         // request headers
+      ":method": "GET",
+      ":path": "/",
+      ":authority": "example.com",
+      ":scheme": "https",
+    },
+    "",                       // request body
+    {},                       // response headers
+    "",                       // response body
+    200,                      // response status
+    "OK",                     // response status text
+    {},                       // properties
+    true,                     // enforceProductionPropertyRules
+  );
+
+  console.log(result.finalResponse);
+} finally {
+  await runner.cleanup();
+}
+```
+
+You can also load from an in-memory buffer using `createRunnerFromBuffer`:
+
+```typescript
+import { createRunnerFromBuffer } from "@gcoredev/fastedge-test";
+import { readFile } from "fs/promises";
+
+const buffer = await readFile("./dist/my-module.wasm");
+const runner = await createRunnerFromBuffer(buffer);
+```
+
+See [RUNNER.md](RUNNER.md) for the full `IWasmRunner` interface, `RunnerConfig` options, and `FullFlowResult` shape.
+
+## Configuration
+
+Place a `fastedge-config.test.json` file in your project root to define default request parameters, response stubs, and WASM properties for the interactive debugger.
+
+```json
+{
+  "$schema": "./node_modules/@gcoredev/fastedge-test/schemas/fastedge-config.test.schema.json",
+  "wasm": {
+    "path": "./dist/my-module.wasm"
+  },
+  "request": {
+    "method": "GET",
+    "url": "https://example.com/",
+    "headers": {
+      "accept": "text/html"
+    },
+    "body": ""
+  },
+  "response": {
+    "headers": {
+      "content-type": "text/html"
+    },
+    "body": "<html><body>Hello</body></html>"
+  },
+  "properties": {
+    "my-property": "value"
+  }
+}
+```
+
+The `$schema` field enables editor autocompletion and inline validation.
+
+See [TEST_CONFIG.md](TEST_CONFIG.md) for all configuration fields and their defaults.
+
+## Next Steps
+
+- [RUNNER.md](RUNNER.md) — `createRunner`, `createRunnerFromBuffer`, `IWasmRunner` interface, `RunnerConfig`
+- [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md) — `defineTestSuite`, `runAndExit`, `runFlow`, `runTestSuite`, `loadConfigFile`
+- [TEST_CONFIG.md](TEST_CONFIG.md) — `fastedge-config.test.json` schema reference
+- [DEBUGGER.md](DEBUGGER.md) — Interactive debugger usage and configuration
+- [API.md](API.md) — REST API reference for programmatic server integration