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

Update API Codex current state

Browse Source
This commit is contained in:
jester 2026-04-29 18:20:35 +00:00
parent cd521513b3
commit fa79a6a7d0
1 changed files with 26 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Codex/API/CURRENT_STATE.md
View File

@ -25,6 +25,7 @@ This file records what is believed to be implemented now.
- `/status` for detailed state snapshot - `/status` for detailed state snapshot
- Portal should rely on API-normalized state, not direct agent state. - Portal should rely on API-normalized state, not direct agent state.
- Proxy lifecycle is now tracked separately from agent readiness under `ContainerInstance.payload.proxy`. - Proxy lifecycle is now tracked separately from agent readiness under `ContainerInstance.payload.proxy`.
- `ContainerInstance.payload.edge` and `ContainerInstance.payload.proxy` are now merged through an atomic JSON merge helper so edge publish state and Velocity callback state do not clobber each other during near-simultaneous writes.
## Readiness cleanup already done ## Readiness cleanup already done
- `agentClient.js` centralizes non-streaming agent transport. - `agentClient.js` centralizes non-streaming agent transport.
@ -52,8 +53,25 @@ This file records what is believed to be implemented now.
- Accepted proxy lifecycle statuses are `registered_with_proxy`, `proxy_ping_ok`, and `proxy_ping_failed`. - Accepted proxy lifecycle statuses are `registered_with_proxy`, `proxy_ping_ok`, and `proxy_ping_failed`.
- Proxy lifecycle callbacks are stored under `ContainerInstance.payload.proxy` with source, status, server name, address, port, duplicate flag, timestamps, latency, detail, and last event time. - Proxy lifecycle callbacks are stored under `ContainerInstance.payload.proxy` with source, status, server name, address, port, duplicate flag, timestamps, latency, detail, and last event time.
- `GET /api/servers/:id/status` now includes the stored `proxy` object beside agent-derived live status. - `GET /api/servers/:id/status` now includes the stored `proxy` object beside agent-derived live status.
- `GET /api/servers/:id/status` derives Minecraft connection state from agent readiness, persisted edge state, Velocity registration state, and backend ping state.
- When Velocity has registered a backend but has not posted a separate `proxy_ping_ok`, API can treat an agent-confirmed Minecraft ping (`readySource: "minecraft_ping"`) as a backend ping fallback unless Velocity explicitly reported `proxy_ping_failed`.
- The bridge should set `ZPACK_PROXY_STATUS_ENDPOINT` to the API internal callback URL, for example `http://<api-host>:4000/internal/velocity/proxy-status`. - The bridge should set `ZPACK_PROXY_STATUS_ENDPOINT` to the API internal callback URL, for example `http://<api-host>:4000/internal/velocity/proxy-status`.
## Host / LXC lifecycle state
- `/api/servers/:id/host/status` exposes the underlying Proxmox LXC state for both game and dev containers.
- Host status now distinguishes container power state from agent/game runtime state.
- Host status response includes `hostStatus`, `powerState`, `running`, active `operation`, and selected Proxmox stats.
- `hostStatus` can report `running`, `stopped`, `starting`, `stopping`, or `restarting`.
- Host lifecycle routes now return `202 Accepted` with an operation object and `statusUrl` instead of blocking until Proxmox finishes:
- `POST /api/servers/:id/host/start`
- `POST /api/servers/:id/host/stop`
- `POST /api/servers/:id/host/restart`
- Overlapping host lifecycle operations return `409 host_operation_in_progress`.
- Host lifecycle operation state is cached under Redis `hostop:<vmid>` with a short TTL and is also surfaced in `GET /api/servers` as `hostOperation`.
- `GET /api/servers` includes Proxmox-backed `hostStatus` and `powerState` so Portal list views can show LXC-level start/stop/restart state for game and dev containers.
- Host lifecycle routes now perform ownership checks before touching Proxmox.
- Proxmox client can resolve the actual node for an LXC via `/cluster/resources` instead of assuming every VMID lives on the configured default `PROXMOX_NODE`.
## Backup support ## Backup support
- API forwards game backup operations. - API forwards game backup operations.
- Current API route shape: - Current API route shape:
@ -113,6 +131,14 @@ 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.
## Console / outbound socket stability
- Console WebSocket proxy attachment is guarded so the console upgrade handler is only attached once per HTTP server.
- Console proxy raw socket error logging is guarded to avoid stacking duplicate socket listeners.
- API raises listener limits on inbound HTTP sockets and console WebSocket sockets to avoid false-positive listener warnings under proxy/websocket fan-out.
- Axios-backed outbound clients now use shared HTTP/HTTPS agent helpers that raise outbound socket listener limits at socket creation time.
- The outbound socket agent helper is used by Proxmox, OPNsense, Cloudflare, and Prometheus metrics query paths.
- A temporary `MaxListenersExceededWarning` tracer exists in `src/app.js` to log emitter/event/count/stack if listener warnings recur.
## Legacy / archived behavior ## Legacy / archived behavior
- legacy port allocation / slot reservation is no longer part of the live route mounts and has been archived for reference - 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 - legacy worker provisioning, detached reconcile helpers, and explicit `.old` files have been moved under archive for reference rather than kept in the live tree