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

Update API current state for route split and archived legacy provisioning

Browse Source
This commit is contained in:
jester 2026-04-24 18:15:16 +00:00
parent 1967b3b1bf
commit ada24e1edf
1 changed files with 22 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Codex/API/CURRENT_STATE.md
View File

@ -9,6 +9,13 @@ This file records what is believed to be implemented now.
- Prisma config has been migrated out of deprecated `package.json#prisma` into `prisma.config.ts`. - 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. - Prisma generate / validate checks reportedly pass on the current API baseline.
## Route and lifecycle split
- `/api/instances` and `/api/containers` are different operational surfaces and should not be treated as duplicates.
- `GET /api/instances` lists `ContainerInstance` rows and is still used for lookup/discovery by some Portal-side code paths.
- `POST /api/instances` is the active agent-driven provisioning entrypoint.
- `DELETE /api/containers/:vmid` is the cleanup/delete/orphan-remediation route used for failed creates, agent failures, manual deletions, and other orphaned container cases.
- Current delete cleanup has been updated to derive archive metadata from current instance fields (`payload`, `engineType`, `allocatedPorts`) instead of assuming the pre-v2 `game` / `variant` / `ports` fields are still present on `ContainerInstance`.
## 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.
@ -26,6 +33,13 @@ This file records what is believed to be implemented now.
- 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(...)`. - Timeout handling in `agentClient.js` has been modernized to `AbortSignal.timeout(...)`.
- A final alignment pass is still needed in merged live status so any Portal-facing `agentReady` field fully matches semantic `/ready` rather than looser cache presence.
## Provisioning / post-provision flow
- `src/api/provisionAgent.js` is the active provisioning path.
- The older worker-based provisioning chain has been archived for reference and is no longer treated as a live API path.
- Post-provision edge publishing is still active.
- Post-provision behavior has been adjusted away from legacy port-allocation commits and should be understood as request-driven / payload-driven.
## Backup support ## Backup support
- API forwards game backup operations. - API forwards game backup operations.
@ -52,6 +66,8 @@ This file records what is believed to be implemented now.
- `/start`, `/stop`, `/restart` forwarded as POST. - `/start`, `/stop`, `/restart` forwarded as POST.
- `/console/command` forwarded as POST JSON. - `/console/command` forwarded as POST JSON.
- `/ready` is part of poller/readiness logic. - `/ready` is part of poller/readiness logic.
- There is no API-native `/api/agent/:serverId/:action` route in `zpack-api`.
- The reviewed Portal repo contained a Portal-side bridge with that shape which calls `/api/instances` for IP lookup and then contacts the agent directly; static review did not find an obvious current frontend caller for that bridge.
## Billing / auth lifecycle ## Billing / auth lifecycle
- API issues access tokens and refresh tokens. - API issues access tokens and refresh tokens.
@ -75,10 +91,12 @@ This file records what is believed to be implemented now.
- IDE proxy cookie hardening is expected to include `httpOnly`, `sameSite: "lax"`, and secure-cookie behavior tied to public HTTPS or explicit secure-cookie config. - 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. - Sensitive proxy logging has reportedly been reduced so cookies and forwarded header detail are not exposed in normal logs.
## Legacy / archived behavior
- legacy port allocation / slot reservation is no longer part of the live route mounts and has been archived for reference
- legacy worker provisioning, detached reconcile helpers, and explicit `.old` files have been moved under archive for reference rather than kept in the live tree
- websocket console proxy wiring remains outside `agentClient.js`
- raw streaming upload proxy behavior remains outside `agentClient.js`
## Node 24 cleanup already reflected in API repo ## Node 24 cleanup already reflected in API repo
- `RegExp.escape(...)` is used where host / suffix regex escaping was previously manual. - `RegExp.escape(...)` is used where host / suffix regex escaping was previously manual.
- Selected built-in imports have been normalized to `node:` style. - Selected built-in imports have been normalized to `node:` style.
## Still true
- websocket console proxy wiring remains outside `agentClient.js`
- raw streaming upload proxy behavior remains outside `agentClient.js`