pikasTech-HWLAB/docs/cloud-api-runtime.md

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:

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, liveConnected, liveDbEvidence, 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 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:

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.

• 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.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.