56 lines
2.5 KiB
Markdown
56 lines
2.5 KiB
Markdown
# API — Current State
|
|
|
|
This file records what is believed to be implemented now.
|
|
|
|
## Readiness / agent state model
|
|
- API is the heartbeat authority by polling agents.
|
|
- Agent does not push state to API.
|
|
- API consumes:
|
|
- `/health` for liveness
|
|
- `/ready` for semantic readiness
|
|
- `/status` for detailed state snapshot
|
|
- Portal should rely on API-normalized state, not direct agent state.
|
|
|
|
## Readiness cleanup already done
|
|
- `agentClient.js` centralizes non-streaming agent transport.
|
|
- `getAgentReady()` remains low-level transport.
|
|
- `isAgentReadyResult()` is the shared semantic readiness helper.
|
|
- `assertAgentReady()` uses semantic readiness.
|
|
- Poller only caches `ready: true` when `/ready` returns semantic success.
|
|
- Provisioning requires semantic readiness before success/persist/publish.
|
|
|
|
## Backup support
|
|
- API forwards game backup operations.
|
|
- Current API route shape:
|
|
- `GET /api/game/servers/:id/backups`
|
|
- `POST /api/game/servers/:id/backups`
|
|
- `POST /api/game/servers/:id/backups/restore?id=<backup_id>`
|
|
- `DELETE /api/game/servers/:id/backups/:backupId`
|
|
- API forwards agent HTTP status codes for backup responses.
|
|
- Successful backup responses currently pass through the agent body.
|
|
- Non-OK backup responses currently use the shared agent response envelope: `{ error: <fallback>, details: <agent_body> }`.
|
|
- Backup response shape normalization remains open.
|
|
|
|
## Agent contract alignment already done
|
|
- `/start`, `/stop`, `/restart` forwarded as POST.
|
|
- `/console/command` forwarded as POST JSON.
|
|
- `/ready` is part of poller/readiness logic.
|
|
|
|
## Billing / auth lifecycle
|
|
- API issues access tokens and refresh tokens.
|
|
- Password reset tokens are stored hashed and exchanged through API routes.
|
|
- Stripe billing routes cover checkout, upgrade, downgrade, portal, and current billing state.
|
|
- Stripe webhooks are mounted with raw body parsing before normal JSON middleware.
|
|
- Billing scheduler starts in-process and performs limited reminder/reconciliation work.
|
|
- Admin users are billing-exempt in billing flows.
|
|
|
|
## Hosted IDE proxy
|
|
- `POST /api/dev/:id/ide-token` issues short-lived IDE proxy tokens.
|
|
- IDE proxy supports both tunnel paths under `/__ide/:id` and hosted `dev-<vmid>.<suffix>` hosts.
|
|
- Hosted IDE tokens can be delivered by query parameter and then persisted as the IDE proxy cookie.
|
|
- Hosted URL return is controlled by `DEV_IDE_RETURN_HOSTED_URL`.
|
|
|
|
## Still true
|
|
- websocket console proxy wiring remains outside `agentClient.js`
|
|
- raw streaming upload proxy behavior remains outside `agentClient.js`
|