diff --git a/Session_Summaries/2026-03-15_IDE-Proxy-Implementation.md b/Session_Summaries/2026-03-15_IDE-Proxy-Implementation.md new file mode 100644 index 0000000..f135d5c --- /dev/null +++ b/Session_Summaries/2026-03-15_IDE-Proxy-Implementation.md @@ -0,0 +1,151 @@ +# 2026-03-15 – Dev IDE proxy implementation + +## Summary + +DNS/Traefik routing experiment for dev IDEs was abandoned and replaced with +a secure API proxy model. IDE access is now fully implemented in the API +with a short-lived token system. + +--- + +## What Was Removed from API + +Deleted files: + +- `src/services/devRouting.js` +- `src/services/devDePublisher.js` + +Removed dev-routing hooks from: + +- `src/api/provisionAgent.js` +- `src/routes/containers.js` + +`src/services/proxyClient.js` was intentionally **not deleted** — it is +still used by the game edge publish path. Removing it would break game routing. + +Dev provisioning now only performs: container creation, agent configuration, +runtime installation, optional `enable_code_server` flag. No DNS or Traefik +routing is created for dev containers. + +--- + +## What Was Implemented + +### Dev IDE Proxy (`src/routes/devProxy.js`) + +Mounted in `src/app.js`. + +Routes: + +``` +GET /api/dev/:id/ide +GET /api/dev/:id/ide/* +``` + +Behavior: + +- validates authentication +- verifies container ownership +- requires `ctype === "dev"` +- requires container IP +- proxies to `http://:6000` +- rewrites `/api/dev/:id/ide/...` → `/...` +- WebSocket support via `http-proxy-middleware` (`ws: true`) +- `server.on("upgrade")` handler wired for WS proxy + +Dependency added: `http-proxy-middleware` + +--- + +### IDE Token System (`POST /api/dev/:id/ide-token`) + +Problem: opening `/api/dev/:id/ide` in a new tab loses `Authorization: Bearer` header. + +Solution: short-lived signed IDE tokens. + +Response: + +```json +{ + "token": "", + "url": "/api/dev/6062/ide?token=", + "expiresIn": 300 +} +``` + +Token details: + +- signed by API +- payload: `sub`, `vmid`, `type: "dev-ide"` +- default TTL: 300 seconds +- env overrides: `API_AUTH_IDE_TTL_SECONDS`, `API_AUTH_IDE_SECRET` + +Proxy accepts either `Authorization: Bearer` or `?token=`. +WebSocket upgrades validate the same token. + +--- + +### Server Status Endpoint (`GET /api/servers/:id/status`) + +File: `src/routes/serverStatus.js` + +Mounted in `src/app.js`. + +Behavior: + +- requires authentication +- verifies container ownership +- loads Redis key `agent:` +- returns cached agent status fields + +Fields include: `state`, `runtimeInstalled`, `devProvisioned`, `devReadyAt`, +`codeServerInstalled`, `codeServerRunning`, `workspaceRoot`, `serverRoot`, +`lastCrashClassification`. + +Source: `src/utils/agentPoller.js` polls agent `/status` and caches to Redis. + +--- + +## Frontend Flow + +1. Portal calls `POST /api/dev/:id/ide-token` +2. API returns `{ url, token, expiresIn }` +3. Portal opens new tab at returned URL +4. API validates token and proxies to container + +--- + +## What Was NOT Changed + +- game provisioning flow +- game edge publish path +- game mod APIs +- game telemetry polling +- agent poller logic +- game file routes +- console transport + +Game infrastructure remains exactly as before. + +--- + +## Next Session — Agent Change Required + +code-server currently launches with `--auth password`. + +Must be changed to: + +```bash +code-server \ + --bind-addr 0.0.0.0:6000 \ + --auth none \ + --base-path /api/dev//ide \ + /home/dev/workspace +``` + +Reasons: + +- removes password prompt (API token is now sole auth) +- `--base-path` required for correct asset loading through proxy path + +This is an agent-side change to the code-server addon launch script.