Lyon
357a68bb95
Refs #49 Merged by commander after reviewing Code Queue task codex_1779422762669_1. Adds redacted DB readiness layering and refreshes DEV endpoint/report evidence. Follow-up: deploy/verify the new readiness probe in DEV via standard image CI/CD.
55 lines
2.2 KiB
Markdown
55 lines
2.2 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 and does not claim live database persistence.
|
|
|
|
## 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.
|
|
- The DB contract reports required env names, redacted Secret refs, env
|
|
injection, connection attempt status, connection result, and `liveConnected`
|
|
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 current runtime store is process-local memory:
|
|
|
|
- `runtime.adapter: "memory"`
|
|
- `runtime.durable: false`
|
|
- `runtime.status: "degraded"`
|
|
|
|
This is intentional for L1. 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:
|
|
|
|
- `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.ready`: currently aliases `db.liveConnected`.
|
|
|
|
Env presence alone is not treated as green. If the runtime has env injection
|
|
but `db.connectionAttempted` is false or `db.liveConnected` is false, the gate
|
|
must stay blocked/degraded with the reported blocker.
|
|
|
|
Fixture: `fixtures/cloud-api-runtime/minimal-runtime.json`.
|