@gcoredev/fastedge-test 0.0.1-beta.4 → 0.1.0-beta.3

package/docs/HYBRID_LOADING.md

@@ -1,546 +0,0 @@
-# Hybrid WASM Loading: Path vs Buffer
-
-## Overview
-
-FastEdge-debugger now supports **two modes** for loading WASM binaries:
-
-1. **Path-based loading** (new, optimized) - Provide a file path
-2. **Buffer-based loading** (legacy, backward compatible) - Provide binary data
-
-This hybrid approach provides **significant performance improvements** for local development while maintaining compatibility with remote/browser scenarios.
-
----
-
-## Performance Impact
-
-### For 12MB WASM File
-
-| Metric | Buffer Mode | Path Mode | Improvement |
-|--------|-------------|-----------|-------------|
-| **Startup Time** | 1.45-3.9s | <1ms | **70-95% faster** |
-| **Network Transfer** | 16MB (base64) | ~100 bytes | **99.999% less** |
-| **Memory Usage** | 48-60MB (4 copies) | 12MB (1 copy) | **75-80% less** |
-
-### Why Path Mode is Faster
-
-**Buffer Mode (Legacy)**:
-```
-File (12MB) → Read → ArrayBuffer → base64 encode (16MB) →
-JSON POST → Network → base64 decode → Buffer →
-Write temp file → Spawn process
-```
-
-**Path Mode (Optimized)**:
-```
-Path string (~50 bytes) → JSON POST →
-Network → Validate path → Spawn process
-```
-
-**Result**: Eliminates ~72MB of data movement!
-
----
-
-## API Changes
-
-### POST /api/load
-
-#### New Parameters
-
-```typescript
-interface LoadRequest {
-  // Option 1: Path-based (preferred)
-  wasmPath?: string;
-
-  // Option 2: Buffer-based (fallback)
-  wasmBase64?: string;
-
-  // Common options
-  dotenvEnabled?: boolean;
-}
-```
-
-#### Example: Path-based Loading
-
-```bash
-curl -X POST http://localhost:5179/api/load \
-  -H "Content-Type: application/json" \
-  -d '{
-    "wasmPath": "/workspace/target/wasm32-wasi/release/app.wasm",
-    "dotenvEnabled": true
-  }'
-```
-
-#### Example: Buffer-based Loading (Legacy)
-
-```bash
-# Read WASM file and encode to base64
-WASM_BASE64=$(base64 -w 0 app.wasm)
-
-curl -X POST http://localhost:5179/api/load \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"wasmBase64\": \"$WASM_BASE64\",
-    \"dotenvEnabled\": true
-  }"
-```
-
-#### Response (Same for Both)
-
-```json
-{
-  "ok": true,
-  "wasmType": "http-wasm"
-}
-```
-
----
-
-## Runner Interface Changes
-
-### IWasmRunner.load()
-
-**Before**:
-```typescript
-load(buffer: Buffer, config?: RunnerConfig): Promise<void>
-```
-
-**After**:
-```typescript
-load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void>
-```
-
-### Usage Examples
-
-#### HTTP WASM Runner
-
-```typescript
-import { HttpWasmRunner } from './runner/HttpWasmRunner';
-import { PortManager } from './runner/PortManager';
-
-const portManager = new PortManager();
-const runner = new HttpWasmRunner(portManager, true);
-
-// Path-based loading (optimized)
-await runner.load('/path/to/app.wasm');
-
-// OR Buffer-based loading (legacy)
-const buffer = await fs.readFile('/path/to/app.wasm');
-await runner.load(buffer);
-
-// Execute request (same for both)
-const response = await runner.execute({
-  path: '/',
-  method: 'GET',
-  headers: {},
-  body: '',
-});
-```
-
-#### Proxy WASM Runner
-
-```typescript
-import { ProxyWasmRunner } from './runner/ProxyWasmRunner';
-
-const runner = new ProxyWasmRunner();
-
-// Path-based loading
-await runner.load('/path/to/filter.wasm');
-
-// OR Buffer-based loading
-const buffer = await fs.readFile('/path/to/filter.wasm');
-await runner.load(buffer);
-
-// Call hook (same for both)
-const result = await runner.callHook({
-  hook: 'onRequestHeaders',
-  request: { headers: {}, body: '' },
-  response: { headers: {}, body: '' },
-  properties: {},
-});
-```
-
----
-
-## Security
-
-### Path Validation
-
-All file paths are validated for security:
-
-```typescript
-import { validatePath, isPathSafe } from './utils/pathValidator';
-
-// Validate with options
-const result = validatePath(inputPath, {
-  workspaceRoot: '/workspace',      // Restrict to workspace
-  requireWasmExtension: true,       // Must end in .wasm
-  checkExists: true,                // File must exist
-  allowAbsolute: true,              // Allow absolute paths
-});
-
-if (!result.valid) {
-  throw new Error(result.error);
-}
-
-// Use normalized path
-const safePath = result.normalizedPath;
-```
-
-### Blocked Paths
-
-The following paths are automatically blocked:
-
-- `/etc`, `/sys`, `/proc`, `/dev`, `/boot`, `/root` (Unix)
-- `C:\Windows`, `C:\Program Files` (Windows)
-- `.ssh`, `.aws`, `.kube` (credentials)
-- `node_modules` (large directories)
-
-### Path Traversal Prevention
-
-```typescript
-// These are BLOCKED
-validatePath('../../../etc/passwd');  // Escapes workspace
-validatePath('/etc/passwd');          // System path
-validatePath('~/.ssh/id_rsa');        // Credentials
-
-// These are ALLOWED (if file exists)
-validatePath('/workspace/app.wasm');          // Within workspace
-validatePath('./target/wasm32-wasi/app.wasm'); // Relative path
-```
-
----
-
-## Use Cases
-
-### ✅ Best for Path-Based Loading
-
-1. **VSCode Extension**
-   - Workspace files are locally accessible
-   - ~3s faster startup for 12MB WASM
-   - No memory overhead
-
-2. **GitHub Codespaces**
-   - Files are local to container
-   - Same performance benefits
-   - Works seamlessly
-
-3. **Local Development**
-   - Developer's machine
-   - Fast iteration cycles
-   - Minimal resource usage
-
-4. **AI Agents (MCP/Claude)**
-   - AI knows file paths
-   - No need to read files
-   - Simple integration
-
-5. **CLI Tools**
-   - Direct path passing
-   - Standard Unix convention
-   - Simple UX
-
-### ❌ Requires Buffer-Based Loading
-
-1. **Web UI (Browser Only)**
-   - No filesystem access
-   - Must use File API
-   - Falls back to buffer
-
-2. **Remote Debugger**
-   - Frontend ≠ backend machine
-   - File doesn't exist remotely
-   - Must transfer content
-
-3. **In-Memory WASM Generation**
-   - Compiler generates WASM
-   - No file on disk
-   - Must use buffer
-
----
-
-## VSCode Extension Integration
-
-### Detection Logic
-
-```typescript
-// Detect if running in VSCode
-const isVSCodeExtension = window.vscodeApi !== undefined;
-
-export async function uploadWasm(
-  file: File,
-  dotenvEnabled: boolean = true,
-): Promise<{ path: string; wasmType: WasmType }> {
-
-  // Use path-based loading in VSCode
-  if (isVSCodeExtension && file.path) {
-    return await fetch(`${API_BASE}/load`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        wasmPath: file.path,
-        dotenvEnabled
-      }),
-    }).then(r => r.json());
-  }
-
-  // Fallback to buffer-based loading
-  const buffer = await file.arrayBuffer();
-  const base64 = btoa(
-    new Uint8Array(buffer).reduce(
-      (data, byte) => data + String.fromCharCode(byte),
-      '',
-    ),
-  );
-
-  return await fetch(`${API_BASE}/load`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ wasmBase64: base64, dotenvEnabled }),
-  }).then(r => r.json());
-}
-```
-
-### No File Access Limitations
-
-- VSCode extension runs in Node.js environment
-- Full filesystem access to workspace
-- Cross-platform path handling (Windows/Unix)
-- Symlinks handled automatically
-
----
-
-## Implementation Details
-
-### HTTP WASM Runner
-
-**Key Optimization**: Skip temp file creation
-
-```typescript
-async load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void> {
-  let wasmPath: string;
-
-  if (typeof bufferOrPath === 'string') {
-    // Path provided - use directly (no temp file!)
-    wasmPath = bufferOrPath;
-    this.tempWasmPath = null;  // Don't cleanup
-  } else {
-    // Buffer provided - write to temp file
-    wasmPath = await writeTempWasmFile(bufferOrPath);
-    this.tempWasmPath = wasmPath;  // Cleanup later
-  }
-
-  // Spawn process with path
-  this.process = spawn(this.cliPath, [
-    'http',
-    '-p', this.port.toString(),
-    '-w', wasmPath,
-    '--wasi-http', 'true',
-  ]);
-}
-```
-
-### Proxy WASM Runner
-
-**Key Optimization**: Read once, compile once
-
-```typescript
-async load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void> {
-  let buffer: Buffer;
-
-  if (typeof bufferOrPath === 'string') {
-    // Path provided - read file
-    buffer = await readFile(bufferOrPath);
-  } else {
-    // Buffer provided - use directly
-    buffer = bufferOrPath;
-  }
-
-  // Compile once and reuse
-  this.module = await WebAssembly.compile(new Uint8Array(buffer));
-}
-```
-
----
-
-## Testing
-
-### Running Tests
-
-```bash
-# Path validator tests (unit)
-pnpm test pathValidator
-
-# Hybrid loading tests (integration)
-pnpm test hybrid-loading
-
-# All tests
-pnpm test
-```
-
-### Test Coverage
-
-**Path Validator** (22 tests):
-- ✅ Valid path validation
-- ✅ Path normalization (../, ./)
-- ✅ Workspace root restriction
-- ✅ Path traversal prevention
-- ✅ Dangerous path blocking
-- ✅ Extension validation
-- ✅ Existence checking
-- ✅ Absolute/relative paths
-
-**Hybrid Loading** (15 tests):
-- ✅ HTTP WASM: buffer vs path modes
-- ✅ Proxy WASM: buffer vs path modes
-- ✅ Identical execution results
-- ✅ Error handling
-- ✅ Performance characteristics
-- ✅ Memory management
-
----
-
-## Migration Guide
-
-### Frontend Changes
-
-**Before**:
-```typescript
-const buffer = await file.arrayBuffer();
-const base64 = btoa(/* ... */);
-
-await fetch('/api/load', {
-  body: JSON.stringify({ wasmBase64: base64 })
-});
-```
-
-**After (with path support)**:
-```typescript
-// Try path first (if available)
-if (file.path) {
-  await fetch('/api/load', {
-    body: JSON.stringify({ wasmPath: file.path })
-  });
-} else {
-  // Fallback to buffer
-  const buffer = await file.arrayBuffer();
-  const base64 = btoa(/* ... */);
-  await fetch('/api/load', {
-    body: JSON.stringify({ wasmBase64: base64 })
-  });
-}
-```
-
-### Backend Changes
-
-**No changes required!** Backward compatible.
-
-Existing code using `runner.load(buffer)` continues to work.
-
----
-
-## Troubleshooting
-
-### "File not found" Error
-
-```typescript
-// Error: File not found: /path/to/app.wasm
-
-// Fix: Ensure file exists
-fs.existsSync('/path/to/app.wasm'); // Should be true
-
-// Fix: Use absolute path
-const absolutePath = path.resolve('./app.wasm');
-```
-
-### "Invalid path" Error
-
-```typescript
-// Error: Invalid path
-
-// Fix: Ensure .wasm extension
-'/path/to/app.wasm' // ✅ Good
-'/path/to/app.wat' // ❌ Bad
-
-// Fix: Stay within workspace
-'/workspace/app.wasm'     // ✅ Good
-'/../../../etc/passwd'    // ❌ Bad
-```
-
-### "Access to system path not allowed"
-
-```typescript
-// Error: Access to system path '/etc' is not allowed
-
-// Fix: Don't access system paths
-'/workspace/app.wasm'  // ✅ Good
-'/etc/passwd'          // ❌ Bad
-```
-
----
-
-## Future Enhancements
-
-### Phase 2: Frontend Path Detection
-- [ ] Detect VSCode extension context
-- [ ] Extract file path from File object
-- [ ] Auto-select path vs buffer mode
-- [ ] Update UI to show loading mode
-
-### Phase 3: Monitoring
-- [ ] Add telemetry for path vs buffer usage
-- [ ] Track startup time metrics
-- [ ] Measure memory usage
-- [ ] Analyze error rates
-
-### Phase 4: File Watching
-- [ ] Watch WASM file for changes
-- [ ] Auto-reload on file modification
-- [ ] Hot-reload during development
-- [ ] WebSocket notification to clients
-
----
-
-## Changelog
-
-### 2026-02-11 - Phase 1: Hybrid Loading (Backward Compatible)
-
-**Added**:
-- Path validation utility (`utils/pathValidator.ts`)
-- `wasmPath` parameter to `/api/load` endpoint
-- Support for `Buffer | string` in runner `load()` methods
-- Security checks for path traversal and dangerous paths
-- Comprehensive test suite (37 tests)
-
-**Changed**:
-- `IWasmRunner.load()` signature to accept `Buffer | string`
-- HTTP WASM runner skips temp file when path provided
-- Proxy WASM runner reads from path when provided
-- WASM type detector accepts `Buffer | string`
-
-**Performance**:
-- 70-95% faster startup for large WASMs
-- 75-80% less memory usage
-- 99.999% less network bandwidth
-
-**Backward Compatibility**:
-- ✅ All existing code continues to work
-- ✅ Buffer-based loading fully supported
-- ✅ No breaking changes to API
-
----
-
-## Summary
-
-The hybrid loading approach provides:
-
-✅ **Massive performance improvements** for local development
-✅ **Full backward compatibility** with existing code
-✅ **Robust security** with path validation
-✅ **Flexibility** to choose the right mode for each scenario
-✅ **Future-proof** architecture for enhancements
-
-**When to use**:
-- **Path mode**: VSCode, Codespaces, local dev, CLI tools (99% of cases)
-- **Buffer mode**: Web UI, remote debugging, in-memory WASM (1% of cases)
-
-**Result**: Faster, more efficient debugger that scales to large WASM binaries!

package/docs/LOCAL_SERVER.md

@@ -1,153 +0,0 @@
-# Local Debugger Server
-
-The `@gcoredev/fastedge-test` package includes a full visual debugger server — an Express-based HTTP server with a React UI, REST API, and WebSocket log streaming. This is the same server embedded in the [FastEdge VSCode extension](https://marketplace.visualstudio.com/items?itemName=Gcore.fastedge).
-
-Use it when you want an interactive local environment to load WASM binaries and test them via a browser UI — without needing VSCode.
-
----
-
-## Running the Server
-
-### Via npx (no install required)
-
-```bash
-npx @gcoredev/fastedge-test
-```
-
-Opens the debugger at `http://localhost:5179`.
-
-### Global install
-
-```bash
-npm install -g @gcoredev/fastedge-test
-fastedge-debug
-```
-
-### Custom port
-
-```bash
-PORT=8080 npx @gcoredev/fastedge-test
-# Opens at http://localhost:8080
-```
-
----
-
-## What You Get
-
-Once running, open `http://localhost:5179` in your browser:
-
-- **Load a WASM binary** — drag-and-drop or select from disk
-- **Send test requests** — configure URL, method, headers, body
-- **Inspect results** — view response, modified headers, hook return codes
-- **Real-time logs** — streamed via WebSocket as your WASM executes
-- **Save/load test config** — persist test cases to `test-config.json`
-
-Both FastEdge binary types are supported and auto-detected:
-- **CDN (proxy-wasm)** — request/response filter binaries
-- **HTTP-WASM** — component model HTTP handler binaries
-
----
-
-## Programmatic Usage
-
-If you want to start the server from your own script or test setup:
-
-```typescript
-import { startServer } from '@gcoredev/fastedge-test/server';
-
-// Start on default port (5179) or override via PORT env var
-await startServer();
-
-// Start on a custom port
-await startServer(8080);
-```
-
-`startServer(port?)` returns a `Promise<void>` that resolves once the server is listening.
-
-> **Note**: When using `startServer()` programmatically, the process stays alive until terminated. Use `SIGTERM` or `SIGINT` to shut it down gracefully — both are handled automatically.
-
-### Example: Start server in a script, run tests, shut down
-
-```typescript
-import { startServer } from '@gcoredev/fastedge-test/server';
-import { defineTestSuite, runAndExit } from '@gcoredev/fastedge-test/test';
-
-// Start the visual server alongside headless tests
-await startServer(5179);
-console.log('Debugger running at http://localhost:5179');
-
-// Also run automated tests in the same process
-await runAndExit(defineTestSuite({
-  wasmPath: './build/app.wasm',
-  tests: [ /* ... */ ],
-}));
-```
-
----
-
-## REST API
-
-The server exposes a REST API that the browser UI uses internally. You can also call it directly from scripts, agents, or other tools.
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/health` | Check server is running |
-| `POST` | `/api/load` | Load a WASM binary (base64 or file path) |
-| `POST` | `/api/execute` | Execute a request against the loaded WASM |
-| `POST` | `/api/send` | Run a full CDN flow (proxy-wasm) |
-| `POST` | `/api/call` | Invoke a specific proxy-wasm hook |
-| `GET` | `/api/config` | Get current test configuration |
-| `POST` | `/api/config` | Save test configuration |
-| `GET` | `/api/schema/:name` | Fetch a JSON Schema for request validation |
-
-See **[API.md](./API.md)** for full endpoint documentation, request/response shapes, and examples.
-
-### Quick example — load and execute via curl
-
-```bash
-# Load a WASM binary by file path
-curl -s -X POST http://localhost:5179/api/load \
-  -H "Content-Type: application/json" \
-  -d '{"wasmPath": "/path/to/app.wasm"}'
-
-# Execute a request
-curl -s -X POST http://localhost:5179/api/execute \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://example.com/page",
-    "method": "GET",
-    "headers": { "user-agent": "curl/7.0" }
-  }'
-```
-
----
-
-## WebSocket Log Streaming
-
-Logs emitted by your WASM binary are streamed in real time over WebSocket:
-
-```javascript
-const ws = new WebSocket('ws://localhost:5179/ws');
-ws.onmessage = (event) => {
-  const msg = JSON.parse(event.data);
-  console.log(msg); // { type: 'log', level: 'info', message: '...' }
-};
-```
-
-The browser UI connects to this automatically — you only need this if building custom tooling.
-
----
-
-## VSCode Extension
-
-If you use VSCode, the debugger is already built into the [FastEdge extension](https://marketplace.visualstudio.com/items?itemName=Gcore.fastedge) — no separate install needed. The extension starts the server automatically when you open a FastEdge project.
-
-The standalone server (this page) is for developers not using VSCode who want the same interactive debugging experience in a browser.
-
----
-
-## Related
-
-- **[REST API Reference](./API.md)** — Full endpoint documentation
-- **[Test Framework Guide](./TEST_FRAMEWORK.md)** — Headless programmatic testing (no server needed)
-- **[WASM Loading Guide](./HYBRID_LOADING.md)** — Path vs buffer loading tradeoffs