jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

Update API Codex current state for Node 24 modernization and hardening

Browse Source
This commit is contained in:
jester 2026-04-19 21:09:02 +00:00
parent fa504660bd
commit 0737f08354
1 changed files with 25 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Codex/API/CURRENT_STATE.md
View File

@ -2,6 +2,13 @@
This file records what is believed to be implemented now. This file records what is believed to be implemented now.
## Runtime / dependency baseline
- API is now tracked against Node 24 with repo-local pinning via `package.json` engines and `.nvmrc`.
- Direct `node-fetch` dependency has been removed and API code now uses built-in global `fetch`.
- Dependency / audit cleanup has been performed and the reported audit state is clean.
- Prisma config has been migrated out of deprecated `package.json#prisma` into `prisma.config.ts`.
- Prisma generate / validate checks reportedly pass on the current API baseline.
## Readiness / agent state model ## Readiness / agent state model
- API is the heartbeat authority by polling agents. - API is the heartbeat authority by polling agents.
- Agent does not push state to API. - Agent does not push state to API.
@ -18,6 +25,7 @@ This file records what is believed to be implemented now.
- `assertAgentReady()` uses semantic readiness. - `assertAgentReady()` uses semantic readiness.
- Poller only caches `ready: true` when `/ready` returns semantic success. - Poller only caches `ready: true` when `/ready` returns semantic success.
- Provisioning requires semantic readiness before success/persist/publish. - Provisioning requires semantic readiness before success/persist/publish.
- Timeout handling in `agentClient.js` has been modernized to `AbortSignal.timeout(...)`.
## Backup support ## Backup support
- API forwards game backup operations. - API forwards game backup operations.
@ -26,11 +34,20 @@ This file records what is believed to be implemented now.
- `POST /api/game/servers/:id/backups` - `POST /api/game/servers/:id/backups`
- `POST /api/game/servers/:id/backups/restore?id=<backup_id>` - `POST /api/game/servers/:id/backups/restore?id=<backup_id>`
- `DELETE /api/game/servers/:id/backups/:backupId` - `DELETE /api/game/servers/:id/backups/:backupId`
- Restore start is async at the API layer and Portal is expected to poll status rather than hold the restore POST open.
- API forwards agent HTTP status codes for backup responses. - API forwards agent HTTP status codes for backup responses.
- Successful backup responses currently pass through the agent body. - Successful backup responses currently pass through the agent body.
- Non-OK backup responses currently use the shared agent response envelope: `{ error: <fallback>, details: <agent_body> }`. - Non-OK backup responses currently use the shared agent response envelope: `{ error: <fallback>, details: <agent_body> }`.
- Backup response shape normalization remains open. - Backup response shape normalization remains open.
## File proxy / route compatibility
- Duplicated game file proxy logic has been extracted into `src/routes/helpers/gameFileProxy.js` in the API repo.
- Route compatibility is intentionally preserved between:
- `/api/game/servers/:id/files...`
- `/api/servers/:id/files...`
- Streamed upload / download / file edit forwarding still exists outside the generic non-streaming agent helper path.
- Compatibility between canonical game routes and legacy/compatibility server routes should be treated as part of the API contract.
## Agent contract alignment already done ## Agent contract alignment already done
- `/start`, `/stop`, `/restart` forwarded as POST. - `/start`, `/stop`, `/restart` forwarded as POST.
- `/console/command` forwarded as POST JSON. - `/console/command` forwarded as POST JSON.
@ -43,6 +60,8 @@ This file records what is believed to be implemented now.
- Stripe webhooks are mounted with raw body parsing before normal JSON middleware. - Stripe webhooks are mounted with raw body parsing before normal JSON middleware.
- Billing scheduler starts in-process and performs limited reminder/reconciliation work. - Billing scheduler starts in-process and performs limited reminder/reconciliation work.
- Admin users are billing-exempt in billing flows. - Admin users are billing-exempt in billing flows.
- JWT verification has reportedly been tightened to fixed algorithm plus issuer/audience separation for access, refresh, and IDE proxy tokens.
- Pre-hardening tokens may no longer verify and a re-login may be required after this change.
## Hosted IDE proxy ## Hosted IDE proxy
- `POST /api/dev/:id/ide-token` issues short-lived IDE proxy tokens. - `POST /api/dev/:id/ide-token` issues short-lived IDE proxy tokens.
@ -53,6 +72,12 @@ This file records what is believed to be implemented now.
- `POST /api/dev/:id/codeserver/start` -> Agent `POST /dev/codeserver/start` - `POST /api/dev/:id/codeserver/start` -> Agent `POST /dev/codeserver/start`
- `POST /api/dev/:id/codeserver/stop` -> Agent `POST /dev/codeserver/stop` - `POST /api/dev/:id/codeserver/stop` -> Agent `POST /dev/codeserver/stop`
- `POST /api/dev/:id/codeserver/restart` -> Agent `POST /dev/codeserver/restart` - `POST /api/dev/:id/codeserver/restart` -> Agent `POST /dev/codeserver/restart`
- IDE proxy cookie hardening is expected to include `httpOnly`, `sameSite: "lax"`, and secure-cookie behavior tied to public HTTPS or explicit secure-cookie config.
- Sensitive proxy logging has reportedly been reduced so cookies and forwarded header detail are not exposed in normal logs.
## Node 24 cleanup already reflected in API repo
- `RegExp.escape(...)` is used where host / suffix regex escaping was previously manual.
- Selected built-in imports have been normalized to `node:` style.
## Still true ## Still true
- websocket console proxy wiring remains outside `agentClient.js` - websocket console proxy wiring remains outside `agentClient.js`