jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
1fccec5753
zlh-grind/Codex/API/DECISIONS.md

2.9 KiB
Raw Blame History

API — Decisions

Settled

  • API is the heartbeat authority by polling agents.
  • Agent does not push heartbeat/state into API.
  • Semantic readiness uses /ready, not plain HTTP 200.
  • Portal should consume API-normalized state, not call agents directly for normal state/actions.
  • /api/instances and /api/containers are distinct contracts: instances is the active list/create surface, while containers is the cleanup/delete/orphan-remediation surface.
  • there is no API-native /api/agent/:serverId/:action route in zpack-api; any route with that shape is Portal-owned compatibility behavior rather than an API feature.
  • streaming upload proxy behavior should remain separate from generic non-streaming agentClient.js transport.
  • websocket console proxy behavior should remain separate from generic non-streaming agentClient.js transport.
  • API is now tracked on a Node 24 baseline with repo-local version pinning.
  • built-in global fetch is the intended fetch implementation; direct node-fetch dependency is no longer the preferred pattern.
  • duplicated game file proxy behavior should be folded into shared helper paths while preserving compatibility for both canonical and compatibility routes.
  • Prisma config should live in dedicated Prisma config, not deprecated package.json#prisma config.
  • JWT verification hardening is allowed to be contract-sensitive; access, refresh, and IDE proxy tokens may use distinct audience expectations.
  • hosted IDE proxy cookies should default to hardened behavior appropriate for public HTTPS deployments.
  • proxy logging should avoid exposing cookies or detailed forwarded-header values in routine logs.
  • legacy worker-based provisioning is no longer a live API path and should stay archived unless intentionally revived.
  • legacy port allocation / slot reservation is no longer part of the active provisioning model and should stay retired unless intentionally revived end to end.
  • Minecraft edge routing uses Velocity; API should call the bridge's real HTTP routes: POST /zpack/register, POST /zpack/unregister, and GET /zpack/status.
  • API must not depend on a nonexistent Velocity /zpack/list route for registration verification.
  • registered_with_proxy means Velocity accepted the backend into its routing table; it does not mean the Minecraft backend is confirmed playable.
  • proxy_ping_ok / proxy_ping_failed are the stronger proxy-side readiness signals because they come from Velocity pinging the registered backend.
  • Proxy lifecycle state belongs under ContainerInstance.payload.proxy, separate from agent readiness and agentState.
  • The Velocity bridge should report proxy lifecycle events to POST /internal/velocity/proxy-status using the same hashed X-Zpack-Secret auth style.

Tracking rule

  • when API work completes, remove it from OPEN_ITEMS.md
  • if it changes the long-lived architecture, update CURRENT_STATE.md or this file