From ada24e1edf83441fb7fd9f2e622a6ec1aeb67d15 Mon Sep 17 00:00:00 2001 From: jester Date: Fri, 24 Apr 2026 18:15:16 +0000 Subject: [PATCH] Update API current state for route split and archived legacy provisioning --- Codex/API/CURRENT_STATE.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Codex/API/CURRENT_STATE.md b/Codex/API/CURRENT_STATE.md index 0a0b0f3..2226591 100644 --- a/Codex/API/CURRENT_STATE.md +++ b/Codex/API/CURRENT_STATE.md @@ -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 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 - API is the heartbeat authority by polling agents. - 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. - Provisioning requires semantic readiness before success/persist/publish. - 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 - 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. - `/console/command` forwarded as POST JSON. - `/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 - 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. - 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 - `RegExp.escape(...)` is used where host / suffix regex escaping was previously manual. - 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`