diff --git a/package.json b/package.json index 805dd68..8be5873 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mcp-play", - "version": "0.2.9", + "version": "0.2.10", "description": "A simple Node.js application to play with the Model Context Protocol.", "main": "src/server.ts", "type": "module", diff --git a/reference-docs/VERSION b/reference-docs/VERSION index 1866a36..13dead7 100644 --- a/reference-docs/VERSION +++ b/reference-docs/VERSION @@ -1 +1 @@ -0.2.9 +0.2.10 diff --git a/reference-docs/docs-index.json b/reference-docs/docs-index.json index 10c28e5..21ddf3e 100644 --- a/reference-docs/docs-index.json +++ b/reference-docs/docs-index.json @@ -1,9 +1,9 @@ { "schema_version": "1.0.0", - "generated_at": "2026-08-28T10:08:36.778Z", + "generated_at": "2026-09-09T13:28:16.173Z", "source": { "repo": "fastedge-plugin", - "commit": "7cbff02", + "commit": "99dc55a", "pipeline": "sync-reference-docs" }, "topics": [ @@ -17948,7 +17948,7 @@ { "id": "dotenv", "title": "Dotenv — Runtime Secrets and Environment Variables", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/dotenv.md", "skill": "test", "category": "testing", @@ -17967,9 +17967,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "dotenv", "runtime", "secrets", @@ -17980,7 +17980,7 @@ "debugger", "inject" ], - "content_sha256": "64bffc70a131a017941ce0e08399bc3f084612086f403804c82ed660578d9cad", + "content_sha256": "ede62a59c47091e9364115672676e1426c675e00fe32c359de4da248e37392a1", "sections": [ { "id": "dotenv#introduction", @@ -17997,9 +17997,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "dotenv", "runtime", "secrets", @@ -40058,7 +40058,7 @@ { "id": "runner-internals", "title": "Runner Internals — Low-Level Runner API", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/runner-internals.md", "skill": "test", "category": "testing", @@ -40074,9 +40074,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "runner", "internals", "low-level", @@ -40088,7 +40088,7 @@ "use", "you" ], - "content_sha256": "aa96ffe4e0ae041dec78b3572d4a1c7db7fa5230af8af284fb3fcf411c1ce02b", + "content_sha256": "f8ffe448fd45d415657ff99e594585019b5ad5f94259510b62135b2a198b7d6f", "sections": [ { "id": "runner-internals#introduction", @@ -40105,9 +40105,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "runner", "internals", "low-level", @@ -42002,7 +42002,7 @@ { "id": "server-api", "title": "Server API — REST and WebSocket Endpoints", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/server-api.md", "skill": "test", "category": "testing", @@ -42018,9 +42018,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "server", "api", "rest", @@ -42032,7 +42032,7 @@ "interfaces", "loading" ], - "content_sha256": "010065841f102e6664523d44b06366752135e355f6f1232ad6292e6f9f5474ca", + "content_sha256": "09e51b2fd4855b45f5e77f8980afd3158eec195a3970774624b82ccf412a182e", "sections": [ { "id": "server-api#introduction", @@ -42049,9 +42049,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "server", "api", "rest", @@ -42082,13 +42082,61 @@ "workspace_path" ] }, + { + "id": "server-api#authentication", + "heading": "Authentication", + "level": 2, + "anchor": "authentication", + "line_start": 22, + "line_end": 62, + "keywords": [ + "authentication", + "debugger", + "server", + "requires", + "session", + "token", + "api", + "requests.", + "health", + "only", + "unauthenticated", + "endpoint.", + "started", + "cli", + "npx", + "fastedge-debug", + "generates", + "random", + "32-byte", + "hex", + "prints", + "full", + "browser", + "url", + "stderr", + "open", + "http", + "localhost", + "5179", + "fragment", + "your", + "token.", + "requests", + "send", + "header", + "call", + "x-fastedge-token", + "websock" + ] + }, { "id": "server-api#rest-endpoints", "heading": "REST Endpoints", "level": 2, "anchor": "rest-endpoints", - "line_start": 22, - "line_end": 944, + "line_start": 63, + "line_end": 989, "keywords": [ "rest", "endpoints", @@ -42127,8 +42175,8 @@ "status", "service", "identity.", - "response", - "typescript" + "require", + "authentication." ] }, { @@ -42136,42 +42184,49 @@ "heading": "WebSocket Protocol", "level": 2, "anchor": "websocket-protocol", - "line_start": 945, - "line_end": 1355, + "line_start": 990, + "line_end": 1419, "keywords": [ "websocket", "protocol", - "connection", - "connect", - "localhost", - "port", - "default", - "5179", - "javascript", - "const", - "new", - "ws.addeventlistener", - "message", - "event", - "msg", - "json.parse", - "event.data", - "console.log", - "msg.type", - "msg.data", - "lifecycle", + "authentication", "server", "accepts", - "connections", - "immediately", - "sends", - "connection_status", - "confirming", - "current", - "client", - "count.", - "ping", - "pong" + "session", + "token", + "via", + "two", + "mechanisms", + "tried", + "order", + "sec-websocket-protocol", + "fastedge-token.", + "preferred", + "embedded", + "subprotocol", + "list", + "keeping", + "out", + "urls", + "proxy", + "access", + "logs.", + "echoes", + "matching", + "back", + "accept.", + "query", + "parameter", + "fallback", + "legacy", + "non-browser", + "tooling", + "cannot", + "set", + "subprotocols.", + "avoid", + "new", + "consumers" ] }, { @@ -42179,8 +42234,8 @@ "heading": "Server Startup", "level": 2, "anchor": "server-startup", - "line_start": 1356, - "line_end": 1369, + "line_start": 1420, + "line_end": 1433, "keywords": [ "server", "startup", @@ -42220,8 +42275,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 1370, - "line_end": 1377, + "line_start": 1434, + "line_end": 1441, "keywords": [ "see", "api", @@ -43302,7 +43357,7 @@ { "id": "test-config", "title": "test-config Reference", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/test-config.md", "skill": "test", "category": "testing", @@ -43318,9 +43373,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "test-config", "reference", "fastedge-config.test.json", @@ -43332,7 +43387,7 @@ "request", "cdn" ], - "content_sha256": "3b344c65f18d4b8b0ea6d8cf317af995a36a81b2c6545970826e882c4639bbdd", + "content_sha256": "d2aa0af179de503195984d8d43c319e612576d1803e50a48bfba3e56f71964aa", "sections": [ { "id": "test-config#introduction", @@ -43349,9 +43404,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "test-config", "reference", "fastedge-config.test.json", @@ -43384,7 +43439,7 @@ "level": 2, "anchor": "schema", "line_start": 16, - "line_end": 71, + "line_end": 76, "keywords": [ "schema", "config", @@ -43432,8 +43487,8 @@ "heading": "Runtime Secrets and Env Vars", "level": 2, "anchor": "runtime-secrets-and-env-vars", - "line_start": 72, - "line_end": 77, + "line_start": 77, + "line_end": 82, "keywords": [ "runtime", "secrets", @@ -43469,8 +43524,8 @@ "heading": "CDN Example", "level": 2, "anchor": "cdn-example", - "line_start": 78, - "line_end": 112, + "line_start": 83, + "line_end": 117, "keywords": [ "cdn", "example", @@ -43515,8 +43570,8 @@ "heading": "HTTP-WASM Example", "level": 2, "anchor": "http-wasm-example", - "line_start": 113, - "line_end": 141, + "line_start": 118, + "line_end": 146, "keywords": [ "http-wasm", "example", @@ -43555,8 +43610,8 @@ "heading": "What to Commit / Gitignore", "level": 2, "anchor": "what-to-commit-gitignore", - "line_start": 142, - "line_end": 156, + "line_start": 147, + "line_end": 161, "keywords": [ "commit", "gitignore", @@ -43591,8 +43646,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 157, - "line_end": 162, + "line_start": 162, + "line_end": 167, "keywords": [ "see", "test-framework", @@ -43628,7 +43683,7 @@ { "id": "test-framework", "title": "FastEdge Test Framework API", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/test-framework.md", "skill": "test", "category": "testing", @@ -43647,9 +43702,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "framework", "api", @@ -43660,7 +43715,7 @@ "runner", "apps." ], - "content_sha256": "d77a91d86abcea723b0f5729a8460588983d33123a8d247523b1e5cf5a7fecbc", + "content_sha256": "046dd1913006dc2ff73c2c1b4398ea2a73ac251e9fed019a38297ffddd51e90b", "sections": [ { "id": "test-framework#introduction", @@ -43677,9 +43732,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "test", "framework", @@ -44047,7 +44102,7 @@ { "id": "vscode-debugger", "title": "FastEdge Visual Debugger", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/vscode-debugger.md", "skill": "test", "category": "testing", @@ -44063,9 +44118,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "visual", "debugger", @@ -44077,7 +44132,7 @@ "gcoredev", "same" ], - "content_sha256": "5a505cc6e1aefcfc489819d1e757d797bd6e10328b985575fec1e9c9cc53df71", + "content_sha256": "ade9b731a6190837aef29b636c117116259983bad22d7cac5622eed085078dfc", "sections": [ { "id": "vscode-debugger#introduction", @@ -44094,9 +44149,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "visual", "debugger", @@ -44123,7 +44178,7 @@ "level": 2, "anchor": "two-ways-to-launch", "line_start": 17, - "line_end": 79, + "line_end": 82, "keywords": [ "two", "ways", @@ -44161,8 +44216,9 @@ "start", "visual", "npx", - "using", - "explicit" + "fastedge-debug", + "package", + "instal" ] }, { @@ -44170,8 +44226,8 @@ "heading": "Dual-Mode Behaviour", "level": 2, "anchor": "dual-mode-behaviour", - "line_start": 80, - "line_end": 94, + "line_start": 83, + "line_end": 97, "keywords": [ "dual-mode", "behaviour", @@ -44219,8 +44275,8 @@ "heading": "Providing Secrets and Environment Variables", "level": 2, "anchor": "providing-secrets-and-environment-variables", - "line_start": 95, - "line_end": 102, + "line_start": 98, + "line_end": 105, "keywords": [ "providing", "secrets", @@ -44255,8 +44311,8 @@ "heading": "What the UI Shows", "level": 2, "anchor": "what-the-ui-shows", - "line_start": 103, - "line_end": 108, + "line_start": 106, + "line_end": 111, "keywords": [ "shows", "provides", @@ -44286,8 +44342,8 @@ "heading": "Programmatic Usage", "level": 2, "anchor": "programmatic-usage", - "line_start": 109, - "line_end": 131, + "line_start": 112, + "line_end": 134, "keywords": [ "programmatic", "usage", @@ -44330,8 +44386,8 @@ "heading": "Environment Variables", "level": 2, "anchor": "environment-variables", - "line_start": 132, - "line_end": 157, + "line_start": 135, + "line_end": 160, "keywords": [ "environment", "variables", @@ -44380,8 +44436,8 @@ "heading": "Health Check", "level": 2, "anchor": "health-check", - "line_start": 158, - "line_end": 179, + "line_start": 161, + "line_end": 182, "keywords": [ "health", "check", @@ -44407,8 +44463,8 @@ "heading": "Port File", "level": 2, "anchor": "port-file", - "line_start": 180, - "line_end": 185, + "line_start": 183, + "line_end": 196, "keywords": [ "port", "file", @@ -44417,7 +44473,6 @@ "server", "writes", "bound", - "number", ".fastedge-debug", ".debug-port", "startup", @@ -44428,12 +44483,21 @@ "current", "working", "directory.", - "use", - "programmatic", - "discovery", - "starting", - "subprocess.", - "---" + "format", + "sha256_hash", + "decimal", + "number", + "colon", + "hex-encoded", + "sha-256", + "session", + "token.", + "extract", + "const", + "parseint", + "fs.readfilesync", + "utf8", + ".trim" ] }, { @@ -44441,8 +44505,8 @@ "heading": "Port Conflicts", "level": 2, "anchor": "port-conflicts", - "line_start": 186, - "line_end": 198, + "line_start": 197, + "line_end": 209, "keywords": [ "port", "conflicts", @@ -44480,8 +44544,8 @@ "heading": "Graceful Shutdown", "level": 2, "anchor": "graceful-shutdown", - "line_start": 199, - "line_end": 234, + "line_start": 210, + "line_end": 245, "keywords": [ "graceful", "shutdown", @@ -44529,8 +44593,8 @@ "heading": "What to Commit / Gitignore", "level": 2, "anchor": "what-to-commit-gitignore", - "line_start": 235, - "line_end": 249, + "line_start": 246, + "line_end": 260, "keywords": [ "commit", "gitignore", @@ -44559,8 +44623,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 250, - "line_end": 257, + "line_start": 261, + "line_end": 268, "keywords": [ "see", "api", diff --git a/reference-docs/docs-index.local.json b/reference-docs/docs-index.local.json index 8eb9512..0a140d0 100644 --- a/reference-docs/docs-index.local.json +++ b/reference-docs/docs-index.local.json @@ -1,9 +1,9 @@ { "schema_version": "1.0.0", - "generated_at": "2026-08-28T10:08:36.778Z", + "generated_at": "2026-09-09T13:28:16.173Z", "source": { "repo": "fastedge-plugin", - "commit": "7cbff02", + "commit": "99dc55a", "pipeline": "sync-reference-docs" }, "topics": [ @@ -17984,7 +17984,7 @@ { "id": "dotenv", "title": "Dotenv — Runtime Secrets and Environment Variables", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/dotenv.md", "skill": "test", "category": "testing", @@ -18003,9 +18003,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "dotenv", "runtime", "secrets", @@ -18016,7 +18016,7 @@ "debugger", "inject" ], - "content_sha256": "64bffc70a131a017941ce0e08399bc3f084612086f403804c82ed660578d9cad", + "content_sha256": "ede62a59c47091e9364115672676e1426c675e00fe32c359de4da248e37392a1", "sections": [ { "id": "dotenv#introduction", @@ -18033,9 +18033,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "dotenv", "runtime", "secrets", @@ -40144,7 +40144,7 @@ { "id": "runner-internals", "title": "Runner Internals — Low-Level Runner API", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/runner-internals.md", "skill": "test", "category": "testing", @@ -40160,9 +40160,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "runner", "internals", "low-level", @@ -40174,7 +40174,7 @@ "use", "you" ], - "content_sha256": "aa96ffe4e0ae041dec78b3572d4a1c7db7fa5230af8af284fb3fcf411c1ce02b", + "content_sha256": "f8ffe448fd45d415657ff99e594585019b5ad5f94259510b62135b2a198b7d6f", "sections": [ { "id": "runner-internals#introduction", @@ -40191,9 +40191,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "runner", "internals", "low-level", @@ -42092,7 +42092,7 @@ { "id": "server-api", "title": "Server API — REST and WebSocket Endpoints", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/server-api.md", "skill": "test", "category": "testing", @@ -42108,9 +42108,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "server", "api", "rest", @@ -42122,7 +42122,7 @@ "interfaces", "loading" ], - "content_sha256": "010065841f102e6664523d44b06366752135e355f6f1232ad6292e6f9f5474ca", + "content_sha256": "09e51b2fd4855b45f5e77f8980afd3158eec195a3970774624b82ccf412a182e", "sections": [ { "id": "server-api#introduction", @@ -42139,9 +42139,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "server", "api", "rest", @@ -42172,13 +42172,61 @@ "workspace_path" ] }, + { + "id": "server-api#authentication", + "heading": "Authentication", + "level": 2, + "anchor": "authentication", + "line_start": 22, + "line_end": 62, + "keywords": [ + "authentication", + "debugger", + "server", + "requires", + "session", + "token", + "api", + "requests.", + "health", + "only", + "unauthenticated", + "endpoint.", + "started", + "cli", + "npx", + "fastedge-debug", + "generates", + "random", + "32-byte", + "hex", + "prints", + "full", + "browser", + "url", + "stderr", + "open", + "http", + "localhost", + "5179", + "fragment", + "your", + "token.", + "requests", + "send", + "header", + "call", + "x-fastedge-token", + "websock" + ] + }, { "id": "server-api#rest-endpoints", "heading": "REST Endpoints", "level": 2, "anchor": "rest-endpoints", - "line_start": 22, - "line_end": 944, + "line_start": 63, + "line_end": 989, "keywords": [ "rest", "endpoints", @@ -42217,8 +42265,8 @@ "status", "service", "identity.", - "response", - "typescript" + "require", + "authentication." ] }, { @@ -42226,42 +42274,49 @@ "heading": "WebSocket Protocol", "level": 2, "anchor": "websocket-protocol", - "line_start": 945, - "line_end": 1355, + "line_start": 990, + "line_end": 1419, "keywords": [ "websocket", "protocol", - "connection", - "connect", - "localhost", - "port", - "default", - "5179", - "javascript", - "const", - "new", - "ws.addeventlistener", - "message", - "event", - "msg", - "json.parse", - "event.data", - "console.log", - "msg.type", - "msg.data", - "lifecycle", + "authentication", "server", "accepts", - "connections", - "immediately", - "sends", - "connection_status", - "confirming", - "current", - "client", - "count.", - "ping", - "pong" + "session", + "token", + "via", + "two", + "mechanisms", + "tried", + "order", + "sec-websocket-protocol", + "fastedge-token.", + "preferred", + "embedded", + "subprotocol", + "list", + "keeping", + "out", + "urls", + "proxy", + "access", + "logs.", + "echoes", + "matching", + "back", + "accept.", + "query", + "parameter", + "fallback", + "legacy", + "non-browser", + "tooling", + "cannot", + "set", + "subprotocols.", + "avoid", + "new", + "consumers" ] }, { @@ -42269,8 +42324,8 @@ "heading": "Server Startup", "level": 2, "anchor": "server-startup", - "line_start": 1356, - "line_end": 1369, + "line_start": 1420, + "line_end": 1433, "keywords": [ "server", "startup", @@ -42310,8 +42365,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 1370, - "line_end": 1377, + "line_start": 1434, + "line_end": 1441, "keywords": [ "see", "api", @@ -43396,7 +43451,7 @@ { "id": "test-config", "title": "test-config Reference", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/test-config.md", "skill": "test", "category": "testing", @@ -43412,9 +43467,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "test-config", "reference", "fastedge-config.test.json", @@ -43426,7 +43481,7 @@ "request", "cdn" ], - "content_sha256": "3b344c65f18d4b8b0ea6d8cf317af995a36a81b2c6545970826e882c4639bbdd", + "content_sha256": "d2aa0af179de503195984d8d43c319e612576d1803e50a48bfba3e56f71964aa", "sections": [ { "id": "test-config#introduction", @@ -43443,9 +43498,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "test-config", "reference", "fastedge-config.test.json", @@ -43478,7 +43533,7 @@ "level": 2, "anchor": "schema", "line_start": 16, - "line_end": 71, + "line_end": 76, "keywords": [ "schema", "config", @@ -43526,8 +43581,8 @@ "heading": "Runtime Secrets and Env Vars", "level": 2, "anchor": "runtime-secrets-and-env-vars", - "line_start": 72, - "line_end": 77, + "line_start": 77, + "line_end": 82, "keywords": [ "runtime", "secrets", @@ -43563,8 +43618,8 @@ "heading": "CDN Example", "level": 2, "anchor": "cdn-example", - "line_start": 78, - "line_end": 112, + "line_start": 83, + "line_end": 117, "keywords": [ "cdn", "example", @@ -43609,8 +43664,8 @@ "heading": "HTTP-WASM Example", "level": 2, "anchor": "http-wasm-example", - "line_start": 113, - "line_end": 141, + "line_start": 118, + "line_end": 146, "keywords": [ "http-wasm", "example", @@ -43649,8 +43704,8 @@ "heading": "What to Commit / Gitignore", "level": 2, "anchor": "what-to-commit-gitignore", - "line_start": 142, - "line_end": 156, + "line_start": 147, + "line_end": 161, "keywords": [ "commit", "gitignore", @@ -43685,8 +43740,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 157, - "line_end": 162, + "line_start": 162, + "line_end": 167, "keywords": [ "see", "test-framework", @@ -43723,7 +43778,7 @@ { "id": "test-framework", "title": "FastEdge Test Framework API", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/test-framework.md", "skill": "test", "category": "testing", @@ -43742,9 +43797,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "framework", "api", @@ -43755,7 +43810,7 @@ "runner", "apps." ], - "content_sha256": "d77a91d86abcea723b0f5729a8460588983d33123a8d247523b1e5cf5a7fecbc", + "content_sha256": "046dd1913006dc2ff73c2c1b4398ea2a73ac251e9fed019a38297ffddd51e90b", "sections": [ { "id": "test-framework#introduction", @@ -43772,9 +43827,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "test", "framework", @@ -44143,7 +44198,7 @@ { "id": "vscode-debugger", "title": "FastEdge Visual Debugger", - "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f updated: 2026-08-25 -->", + "description": "auto-updated: true sources: - id: fastedge-test ref: main commit: 93d8046c3b98a65b18e189d435f760c8861d481f updated: 2026-09-09 -->", "path": "reference/test/vscode-debugger.md", "skill": "test", "category": "testing", @@ -44159,9 +44214,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "visual", "debugger", @@ -44173,7 +44228,7 @@ "gcoredev", "same" ], - "content_sha256": "5a505cc6e1aefcfc489819d1e757d797bd6e10328b985575fec1e9c9cc53df71", + "content_sha256": "ade9b731a6190837aef29b636c117116259983bad22d7cac5622eed085078dfc", "sections": [ { "id": "vscode-debugger#introduction", @@ -44190,9 +44245,9 @@ "ref", "main", "commit", - "9c4ab58dddbffed3e446ab10e9249f07edc6165f", + "93d8046c3b98a65b18e189d435f760c8861d481f", "updated", - "2026-08-25", + "2026-09-09", "fastedge", "visual", "debugger", @@ -44219,7 +44274,7 @@ "level": 2, "anchor": "two-ways-to-launch", "line_start": 17, - "line_end": 79, + "line_end": 82, "keywords": [ "two", "ways", @@ -44257,8 +44312,9 @@ "start", "visual", "npx", - "using", - "explicit" + "fastedge-debug", + "package", + "instal" ] }, { @@ -44266,8 +44322,8 @@ "heading": "Dual-Mode Behaviour", "level": 2, "anchor": "dual-mode-behaviour", - "line_start": 80, - "line_end": 94, + "line_start": 83, + "line_end": 97, "keywords": [ "dual-mode", "behaviour", @@ -44315,8 +44371,8 @@ "heading": "Providing Secrets and Environment Variables", "level": 2, "anchor": "providing-secrets-and-environment-variables", - "line_start": 95, - "line_end": 102, + "line_start": 98, + "line_end": 105, "keywords": [ "providing", "secrets", @@ -44351,8 +44407,8 @@ "heading": "What the UI Shows", "level": 2, "anchor": "what-the-ui-shows", - "line_start": 103, - "line_end": 108, + "line_start": 106, + "line_end": 111, "keywords": [ "shows", "provides", @@ -44382,8 +44438,8 @@ "heading": "Programmatic Usage", "level": 2, "anchor": "programmatic-usage", - "line_start": 109, - "line_end": 131, + "line_start": 112, + "line_end": 134, "keywords": [ "programmatic", "usage", @@ -44426,8 +44482,8 @@ "heading": "Environment Variables", "level": 2, "anchor": "environment-variables", - "line_start": 132, - "line_end": 157, + "line_start": 135, + "line_end": 160, "keywords": [ "environment", "variables", @@ -44476,8 +44532,8 @@ "heading": "Health Check", "level": 2, "anchor": "health-check", - "line_start": 158, - "line_end": 179, + "line_start": 161, + "line_end": 182, "keywords": [ "health", "check", @@ -44503,8 +44559,8 @@ "heading": "Port File", "level": 2, "anchor": "port-file", - "line_start": 180, - "line_end": 185, + "line_start": 183, + "line_end": 196, "keywords": [ "port", "file", @@ -44513,7 +44569,6 @@ "server", "writes", "bound", - "number", ".fastedge-debug", ".debug-port", "startup", @@ -44524,12 +44579,21 @@ "current", "working", "directory.", - "use", - "programmatic", - "discovery", - "starting", - "subprocess.", - "---" + "format", + "sha256_hash", + "decimal", + "number", + "colon", + "hex-encoded", + "sha-256", + "session", + "token.", + "extract", + "const", + "parseint", + "fs.readfilesync", + "utf8", + ".trim" ] }, { @@ -44537,8 +44601,8 @@ "heading": "Port Conflicts", "level": 2, "anchor": "port-conflicts", - "line_start": 186, - "line_end": 198, + "line_start": 197, + "line_end": 209, "keywords": [ "port", "conflicts", @@ -44576,8 +44640,8 @@ "heading": "Graceful Shutdown", "level": 2, "anchor": "graceful-shutdown", - "line_start": 199, - "line_end": 234, + "line_start": 210, + "line_end": 245, "keywords": [ "graceful", "shutdown", @@ -44625,8 +44689,8 @@ "heading": "What to Commit / Gitignore", "level": 2, "anchor": "what-to-commit-gitignore", - "line_start": 235, - "line_end": 249, + "line_start": 246, + "line_end": 260, "keywords": [ "commit", "gitignore", @@ -44655,8 +44719,8 @@ "heading": "See Also", "level": 2, "anchor": "see-also", - "line_start": 250, - "line_end": 257, + "line_start": 261, + "line_end": 268, "keywords": [ "see", "api", diff --git a/reference-docs/dotenv.md b/reference-docs/dotenv.md index 703e31f..cbabefa 100644 --- a/reference-docs/dotenv.md +++ b/reference-docs/dotenv.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # Dotenv — Runtime Secrets and Environment Variables diff --git a/reference-docs/runner-internals.md b/reference-docs/runner-internals.md index 4c708cc..fc4926e 100644 --- a/reference-docs/runner-internals.md +++ b/reference-docs/runner-internals.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # Runner Internals — Low-Level Runner API diff --git a/reference-docs/server-api.md b/reference-docs/server-api.md index 6dcdd4b..e70d14f 100644 --- a/reference-docs/server-api.md +++ b/reference-docs/server-api.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # Server API — REST and WebSocket Endpoints @@ -13,12 +13,53 @@ The `@gcoredev/fastedge-test` debugger server exposes REST and WebSocket interfa **Base URL:** `http://localhost:5179` -The port can be overridden via the `PORT` environment variable. When `WORKSPACE_PATH` is set, the active port is written to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and deleted on shutdown. +The port can be overridden via the `PORT` environment variable. When `WORKSPACE_PATH` is set, the active port is written to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and deleted on shutdown. The file contains `PORT:SHA256_HASH`, where `PORT` is the decimal port number and `SHA256_HASH` is the hex-encoded SHA-256 of the session token. Consumers that only need the port should parse the prefix up to the first colon (e.g. `parseInt(content.split(":")[0], 10)`). > **Note on header values.** Response-side and hook-result headers use `Record` — 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`. --- +## Authentication + +The debugger server requires a session token on all `/api/*` requests. `/health` is the only unauthenticated endpoint. + +When started from the CLI (`npx fastedge-debug`), the server generates a random 32-byte hex token and prints the full browser URL to stderr: + +``` +Open: http://localhost:5179/#token= +``` + +The fragment after `#token=` is your session token. + +**HTTP requests** — send the token as a header on every `/api/*` call: + +``` +x-fastedge-token: +``` + +**WebSocket** — two mechanisms exist, tried in preference order: + +1. **`Sec-WebSocket-Protocol: fastedge-token.`** (preferred) — the token is embedded in the subprotocol list rather than the URL, keeping it out of proxy and server access logs. The server echoes the subprotocol back on accept. +2. **`?token=` query parameter** (fallback) — for legacy or non-browser tooling that cannot set subprotocols. Avoid this form in new consumers: the token appears in server and proxy logs. + +```javascript +const ws = new WebSocket( + `ws://127.0.0.1:5179/ws`, + [`fastedge-token.${token}`], +); +``` + +**Environment variables related to authentication and binding:** + +| Variable | Default | Description | +|---|---|---| +| `FASTEDGE_DEBUG_TOKEN` | unset | Inject a known token instead of generating one. When set, the `Open:` URL is not printed to stderr. | +| `FASTEDGE_BIND_HOST` | `127.0.0.1` | Interface the HTTP server binds to. | +| `FASTEDGE_EXPECTED_HOST` | unset | Extra hostname (suffix match) allowed in `Host` / `Origin` headers — for Codespaces forwarded URLs. | +| `WORKSPACE_PATH` | `process.cwd()` | Workspace root; affects `.env` resolution, port file, and config file placement. | + +--- + ## REST Endpoints ### Common Headers @@ -44,7 +85,7 @@ X-Source: ai_agent #### GET /health -Returns server status and service identity. +Returns server status and service identity. Does not require authentication. **Response** @@ -85,7 +126,7 @@ Returns the number of currently connected WebSocket clients. Useful in CI toolin **Example** ```bash -curl http://localhost:5179/api/client-count +curl -H "x-fastedge-token: " http://localhost:5179/api/client-count ``` ```json @@ -133,6 +174,7 @@ Loads a WASM binary into the runner. Accepts a file path or base64-encoded binar ```bash curl -X POST http://localhost:5179/api/load \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "wasmPath": "/home/user/project/build/module.wasm", "dotenv": { "enabled": true } @@ -152,6 +194,7 @@ curl -X POST http://localhost:5179/api/load \ ```bash curl -X POST http://localhost:5179/api/load \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "wasmBase64": "AGFzbQEAAAA...", "dotenv": { "enabled": false } @@ -170,6 +213,7 @@ curl -X POST http://localhost:5179/api/load \ ```bash curl -X POST http://localhost:5179/api/load \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "wasmPath": "/home/user/project/build/app.wasm", "httpPort": 8100 @@ -224,6 +268,7 @@ Requires a WASM module already loaded via `POST /api/load`. ```bash curl -X PATCH http://localhost:5179/api/dotenv \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "dotenv": { "enabled": true, "path": "/home/user/project" } }' @@ -344,6 +389,7 @@ type HookResult = { ```bash curl -X POST http://localhost:5179/api/execute \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -H "X-Source: api" \ -d '{ "path": "/api/data?format=json", @@ -374,6 +420,7 @@ curl -X POST http://localhost:5179/api/execute \ ```bash curl -X POST http://localhost:5179/api/execute \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -H "X-Source: api" \ -d '{ "url": "https://example.com/page", @@ -415,11 +462,7 @@ curl -X POST http://localhost:5179/api/execute \ "calculatedProperties": { "request.url": "https://example.com/page", "request.host": "example.com", - "request.path": "/page", - "request.query": "", - "request.scheme": "https", - "request.extension": "", - "request.method": "GET" + "request.path": "/page" } } ``` @@ -472,6 +515,7 @@ Requires a WASM module loaded via `POST /api/load`. ```bash curl -X POST http://localhost:5179/api/call \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "hook": "onRequestHeaders", "request": { @@ -573,6 +617,7 @@ Requires a WASM module loaded via `POST /api/load`. Accepts optional `X-Source` ```bash curl -X POST http://localhost:5179/api/send \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -H "X-Source: ai_agent" \ -d '{ "url": "https://example.com/api/resource", @@ -630,11 +675,7 @@ curl -X POST http://localhost:5179/api/send \ "calculatedProperties": { "request.url": "https://example.com/api/resource", "request.host": "example.com", - "request.path": "/api/resource", - "request.query": "", - "request.scheme": "https", - "request.extension": "", - "request.method": "POST" + "request.path": "/api/resource" } } ``` @@ -710,7 +751,7 @@ type TestConfig = ProxyWasmConfig | HttpWasmConfig; **Example** ```bash -curl http://localhost:5179/api/config +curl -H "x-fastedge-token: " http://localhost:5179/api/config ``` ```json @@ -768,6 +809,7 @@ The `config` object must match one of the two `TestConfig` variants. `appType` a ```bash curl -X POST http://localhost:5179/api/config \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -H "X-Source: api" \ -d '{ "config": { @@ -803,14 +845,14 @@ curl -X POST http://localhost:5179/api/config \ #### POST /api/config/save-as -Saves the provided configuration to an arbitrary file path. Creates intermediate directories as needed. Appends `.json` if the path does not already end in `.json`. +Saves the provided configuration to a file path previously vended by the save dialog. The path must have been registered by `/api/config/show-save-dialog` first; unregistered paths are rejected with `403`. The path is single-use — it is removed from the pending set once consumed. Creates intermediate directories as needed. **Request Body** ```typescript { config: object; // The configuration object to serialize as JSON - filePath: string; // Target file path (absolute or relative to project root) + filePath: string; // A path previously returned by the save dialog } ``` @@ -819,7 +861,7 @@ Saves the provided configuration to an arbitrary file path. Creates intermediate ```typescript { ok: true; - savedPath: string; // Resolved absolute path where the file was written + savedPath: string; // The file path where the config was written } ``` @@ -828,6 +870,7 @@ Saves the provided configuration to an arbitrary file path. Creates intermediate ```bash curl -X POST http://localhost:5179/api/config/save-as \ -H "Content-Type: application/json" \ + -H "x-fastedge-token: " \ -d '{ "config": { "appType": "proxy-wasm", @@ -839,7 +882,7 @@ curl -X POST http://localhost:5179/api/config/save-as \ }, "properties": {} }, - "filePath": "configs/staging.test" + "filePath": "/home/user/project/configs/staging.test.json" }' ``` @@ -855,6 +898,7 @@ curl -X POST http://localhost:5179/api/config/save-as \ | Status | Condition | |---|---| | `400` | Missing `config` or `filePath` | +| `403` | `filePath` was not vended by the save dialog (or was already used) | | `500` | File write or directory creation failed | --- @@ -937,6 +981,7 @@ When a request body fails schema validation (Zod), `error` is a flattened Zod er | Status | Meaning | |---|---| | `400` | Invalid request body, missing required fields, or precondition not met (e.g. no WASM loaded) | +| `403` | Host/token check failed, or a save-as path was not vended by the save dialog | | `404` | Resource not found (config file, schema file) | | `500` | Internal server error during execution or I/O | @@ -944,18 +989,37 @@ When a request body fails schema validation (Zod), `error` is a flattened Zod er ## WebSocket Protocol +### Authentication + +The server accepts the session token via two mechanisms, tried in this order: + +1. **`Sec-WebSocket-Protocol: fastedge-token.`** (preferred) — the token is embedded in the subprotocol list, keeping it out of URLs and proxy access logs. The server echoes the matching subprotocol back on accept. +2. **`?token=` query parameter** (fallback) — for legacy or non-browser tooling that cannot set subprotocols. Avoid in new consumers: the token appears in server and proxy logs. + +```javascript +const token = new URL(location.href).hash.slice("#token=".length); +const ws = new WebSocket(`ws://127.0.0.1:5179/ws`, [`fastedge-token.${token}`]); +``` + +Fallback URL form: + +``` +ws://127.0.0.1:/ws?token= +``` + ### Connection Connect to: ``` -ws://localhost:{port}/ws +ws://127.0.0.1:{port}/ws ``` Default port: `5179`. ```javascript -const ws = new WebSocket('ws://localhost:5179/ws'); +const token = new URL(location.href).hash.slice("#token=".length); +const ws = new WebSocket(`ws://127.0.0.1:5179/ws`, [`fastedge-token.${token}`]); ws.addEventListener('message', (event) => { const msg = JSON.parse(event.data); @@ -965,7 +1029,7 @@ ws.addEventListener('message', (event) => { ### Lifecycle -1. **Connect** — server accepts all connections and immediately sends a `connection_status` event confirming the connection and current client count. +1. **Connect** — server validates the token and origin, then immediately sends a `connection_status` event confirming the connection and current client count. 2. **Ping / pong** — 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. @@ -1363,7 +1427,7 @@ import { startServer } from '@gcoredev/fastedge-test/server'; The server listens on port `5179` by default. Override with the `PORT` environment variable. When the preferred port is busy, the server tries up to 10 sequential ports before failing. -When `WORKSPACE_PATH` is set, the active port is written to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and removed on shutdown. Use this file to discover the port dynamically in CI or multi-process tooling. +When `WORKSPACE_PATH` is set, the active port is written to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and removed on shutdown. The file contains `PORT:SHA256_HASH` — consumers that only need the port should parse the prefix up to the first colon (e.g. `parseInt(content.split(":")[0], 10)`). Use this file to discover the port dynamically in CI or multi-process tooling. --- diff --git a/reference-docs/test-config.md b/reference-docs/test-config.md index f6c0ffd..26f33ff 100644 --- a/reference-docs/test-config.md +++ b/reference-docs/test-config.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # test-config Reference @@ -56,6 +56,11 @@ Supply fields explicitly to avoid editor warnings, or add the `$schema` field an Without `httpPort`, the runner allocates a port from the 8100–8199 range for each test run. The allocated port is not stable across runs. +Use port pinning when: +- **Codespaces / Docker port-forwarding**: Port-forward rules reference a specific port number. Without pinning, the port changes between runs and breaks the forwarding rule. +- **Stable live-preview URLs**: Browser tabs or external tooling pointing at a fixed URL require a stable port. +- **External tooling integration**: Monitoring, load testing, or proxy configurations that hard-code a target address. + If the pinned port is already in use, `HttpWasmRunner.load()` throws immediately with a descriptive error. There is no fallback to dynamic allocation. Pinning a port inside the 8100–8199 dynamic pool is allowed by the schema but risks collisions with other concurrent debug sessions. For shared environments, choose a port outside the pool (e.g. 8250). ### Built-In Responder diff --git a/reference-docs/test-framework.md b/reference-docs/test-framework.md index 4b0a2ee..78fcfef 100644 --- a/reference-docs/test-framework.md +++ b/reference-docs/test-framework.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # FastEdge Test Framework API diff --git a/reference-docs/vscode-debugger.md b/reference-docs/vscode-debugger.md index 3d97053..f4643c3 100644 --- a/reference-docs/vscode-debugger.md +++ b/reference-docs/vscode-debugger.md @@ -3,8 +3,8 @@ sources: - id: fastedge-test ref: main - commit: 9c4ab58dddbffed3e446ab10e9249f07edc6165f - updated: 2026-08-25 + commit: 93d8046c3b98a65b18e189d435f760c8861d481f + updated: 2026-09-09 --> # FastEdge Visual Debugger @@ -29,21 +29,24 @@ Use the **`FastEdge: Debug Application`** command from the Command Palette to op npm install --save-dev @gcoredev/fastedge-test # Start the visual debugger -npx @gcoredev/fastedge-test - -# Or using the explicit binary name (preferred): npx fastedge-debug ``` -> The shorthand `npx @gcoredev/fastedge-test` works because the package declares exactly one `bin` entry. Prefer the explicit `fastedge-debug` form — it stays correct if a second binary is ever added. - If the package is not installed, fetch and run it in one shot: ```bash npx -p @gcoredev/fastedge-test fastedge-debug ``` -Opens the debugger UI at `http://localhost:5179`. +> The shorthand `npx @gcoredev/fastedge-test` works because the package declares exactly one `bin` entry. Prefer the explicit `fastedge-debug` form — it stays correct if a second binary is ever added. + +Opens the debugger UI at `http://localhost:5179`. In CLI mode the server also prints the full browser URL with the session token in the fragment: + +``` +Open: http://localhost:5179/#token= +``` + +Open that URL directly — the frontend reads the `#token=` fragment and includes it as an `x-fastedge-token` header on every API request. See the API reference for authentication details, including the `x-fastedge-token` header and WebSocket token parameter. Custom port: ```bash @@ -179,7 +182,15 @@ curl http://localhost:5179/health ## Port File -When `WORKSPACE_PATH` is set, the server writes the bound port number to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and deletes it on shutdown. When `WORKSPACE_PATH` is not set, the file is written under the current working directory. Use this file for programmatic port discovery when starting the server as a subprocess. +When `WORKSPACE_PATH` is set, the server writes the bound port to `$WORKSPACE_PATH/.fastedge-debug/.debug-port` on startup and deletes it on shutdown. When `WORKSPACE_PATH` is not set, the file is written under the current working directory. + +The file format is `PORT:SHA256_HASH` — the decimal port number, a colon, then the hex-encoded SHA-256 of the session token. To extract just the port: + +```js +const port = parseInt(fs.readFileSync(".fastedge-debug/.debug-port", "utf8").trim().split(":")[0], 10); +``` + +Use this file for programmatic port discovery when starting the server as a subprocess. ---