Code Queue Review
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# Cloud API Runtime
|
|
|
|
The L1 `hwlab-cloud-api` runtime is a minimal local HTTP/JSON-RPC service. It
|
|
does not deploy to DEV or PROD from source tests and does not claim live
|
|
database persistence unless both DB readiness and the durable runtime adapter
|
|
readiness are live.
|
|
|
|
## Local Smoke
|
|
|
|
Run:
|
|
|
|
```sh
|
|
node scripts/cloud-api-runtime-smoke.mjs
|
|
```
|
|
|
|
The smoke starts `cmd/hwlab-cloud-api` on `127.0.0.1` with an ephemeral port
|
|
and verifies:
|
|
|
|
- `GET /health` reports `status: "degraded"` when live DB persistence is not
|
|
connected.
|
|
- `GET /health` reports DB readiness and runtime durable adapter readiness as
|
|
separate components. A memory adapter remains non-durable even when DB env
|
|
fields are present.
|
|
- The DB contract reports required env names, redacted Secret refs, env
|
|
injection, connection attempt status, connection result, `liveConnected`,
|
|
`liveDbEvidence`, DNS/TCP/auth/schema readiness layers, and redaction/safety
|
|
fields without exposing DB URL or secret values.
|
|
- `gateway.session.register`, `box.resource.register`,
|
|
`box.capability.report`, `hardware.invoke.shell`, `audit.event.query`, and
|
|
`evidence.record.query` round-trip through the same runtime store.
|
|
- Shell invoke requests are accepted as recorded cloud operations but report
|
|
`dispatchStatus: "not_connected"` until a real gateway shell adapter exists.
|
|
- Audit and evidence records use the protocol schema field names.
|
|
|
|
## Persistence Boundary
|
|
|
|
The default local runtime store is process-local memory:
|
|
|
|
- `runtime.adapter: "memory"`
|
|
- `runtime.durable: false`
|
|
- `runtime.status: "degraded"`
|
|
|
|
This remains the safe local default. DEV can opt into the durable adapter with
|
|
non-secret env flags:
|
|
|
|
- `HWLAB_CLOUD_RUNTIME_ADAPTER=postgres`
|
|
- `HWLAB_CLOUD_RUNTIME_DURABLE=true`
|
|
|
|
The Postgres adapter uses `HWLAB_CLOUD_DB_URL` from
|
|
`hwlab-cloud-api-dev-db/database-url`; source records only the Secret reference
|
|
and non-secret DNS contract. The adapter reports `runtime.ready: true` only
|
|
after a live schema query proves the required runtime tables and columns exist.
|
|
If DB auth or schema is missing, `/health/live` stays degraded and reports a
|
|
runtime blocker such as `runtime_durable_adapter_auth_blocked` or
|
|
`runtime_durable_adapter_schema_blocked`. Fixture data and env presence are
|
|
never promoted to `runtime.liveRuntimeEvidence`.
|
|
|
|
If `HWLAB_CLOUD_DB_URL` and `HWLAB_CLOUD_DB_SSL_MODE` are absent, health
|
|
reports `db.status: "blocked"`.
|
|
If both env vars are present, cloud-api attempts a short read-only TCP
|
|
connection to the DB endpoint from the injected runtime env. The health payload
|
|
keeps all endpoint details redacted and reports only:
|
|
|
|
The source-controlled DEV DNS contract for that endpoint is
|
|
`cloud-api-db.hwlab-dev.svc.cluster.local:5432`. The actual connection string
|
|
still comes from `hwlab-cloud-api-dev-db/database-url`; source records only the
|
|
non-secret host/service/namespace/port contract.
|
|
`.invalid` hosts, including `hwlab-dev-db.invalid`, are forbidden as DEV
|
|
runtime targets and may be used only as negative fixtures.
|
|
|
|
- `db.configReady`: required env names are present.
|
|
- `db.connectionAttempted`: the runtime tried the live connection path.
|
|
- `db.connectionResult`: redacted classifier such as `connected`, `refused`,
|
|
`timeout`, `dns_error`, `invalid_url`, or `unsupported_protocol`.
|
|
- `db.liveConnected`: the TCP connection completed.
|
|
- `db.liveDbEvidence`: true only when the live connection completed; env
|
|
presence, fixtures, and disabled probes must keep this false.
|
|
- `db.redaction` and `db.safety`: confirm values/endpoints are redacted and
|
|
secret material was not read by the health path.
|
|
- `db.readinessLayers`: records DNS, TCP, auth, and schema status separately so
|
|
DNS/TCP repair cannot be confused with authenticated schema readiness.
|
|
- `db.ready`: currently aliases `db.liveConnected`.
|
|
|
|
Env presence alone is not treated as green. If the runtime has env injection
|
|
but `db.connectionAttempted` is false, `db.liveConnected` is false, or
|
|
`db.liveDbEvidence` is false, the gate must stay blocked/degraded with the
|
|
reported blocker.
|
|
|
|
Fixture: `fixtures/cloud-api-runtime/minimal-runtime.json`.
|
|
|
|
## Code Agent Provider Boundary
|
|
|
|
`hwlab-cloud-api` supports OpenAI Responses for the Code Agent chat endpoint.
|
|
DEV source contracts require `OPENAI_API_KEY` from Secret
|
|
`hwlab-code-agent-provider/openai-api-key` and
|
|
`HWLAB_CODE_AGENT_OPENAI_BASE_URL` through the DEV egress/proxy URL. Runtime
|
|
health and `/v1` may report provider status, missing env names, Secret ref
|
|
names, model, and redacted egress status, but must never print the API key or a
|
|
Bearer token.
|