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

Update API overview with active route boundaries and retired legacy flows

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

16
Codex/API/OVERVIEW.md
View File

@ -14,18 +14,34 @@ The API is the control plane for ZLH customer infrastructure. It accepts authent
- handle Stripe billing checkout, plan changes, webhooks, portal sessions, and limited reconciliation
- provide hosted IDE reverse proxy and websocket handling for dev containers
## Active route boundaries
- `/api/instances` is the active instance list/create surface
- `GET /api/instances` currently exposes `ContainerInstance` rows and is still used for lookup/discovery by some Portal-side code paths
- `POST /api/instances` is the agent-driven provisioning entrypoint
- `/api/containers/:vmid` is the cleanup/delete/orphan-remediation surface for partially created, manually deleted, or otherwise orphaned containers
- `/api/servers`, `/api/game`, `/api/dev`, and console proxy routes remain the main Portal-facing runtime/control surfaces
## Agent relationship
Agents own container-local behavior. The API owns the external contract.
The API polls agents instead of waiting for pushed state. `/health` is liveness, `/ready` is semantic readiness, and `/status` is the detailed runtime snapshot. The Portal should read API-normalized state rather than contacting agents directly.
There is no API-native `/api/agent/:serverId/:action` route in `zpack-api`. The reviewed Portal repo contained a Portal-side bridge route with that shape, but it is Portal-owned compatibility behavior rather than an API feature.
## Response and proxy behavior
Most non-streaming agent calls go through `agentClient.js`. Streaming upload and websocket console proxying stay outside that helper because they need raw socket or request-stream handling.
Backup responses are currently forwarded with the agent HTTP status. Successful bodies pass through. Non-OK bodies use the shared envelope `{ error, details }` until the backup response contract is normalized.
## Legacy / retired paths
- the older worker-based provisioning chain is no longer treated as a live API path and has been archived for reference
- legacy port allocation / slot reservation is no longer treated as part of the active provisioning model and has been removed from the live route mounts
- current provisioning and edge publish behavior should be understood as request-driven rather than allocator-driven
## Not owned here
- Portal-only UI behavior