pikasTech-HWLAB/docs/dev-edge-health.md

HWLAB DEV Edge Health

This check is DEV-only and targets the frozen endpoint:

node scripts/dev-edge-health-smoke.mjs --live --report /tmp/hwlab-dev-gate/report.json

The smoke is read-only. It does not touch PROD, restart services, read secrets, or substitute UniDesk backend/provider-gateway/microservice-proxy for HWLAB runtime.

Health Evidence

GET http://74.48.78.17:16667/health must return HWLAB DEV JSON with:

• serviceId for the HWLAB service answering the request;
• environment: "dev";
• commit evidence;
• image evidence;
• service evidence.

hwlab-cloud-api also serves GET /health/live for k3s probes and edge forwarding checks.

db in the cloud-api health payload is a redacted configuration gate. It reports required env names, presence, missing names, and Secret reference names only. Runtime health additionally reports redacted DB readiness layers: configReady, envInjected, endpointSource, connectionAttempted, connectionResult, and liveConnected. It must not expose a connection string, token, password, DB host, username, or claim fixture output as live DB evidence.

Required DEV DB config names:

• HWLAB_CLOUD_DB_URL from Secret reference hwlab-cloud-api-dev-db/database-url.
• HWLAB_CLOUD_DB_SSL_MODE=disable.
• Runtime TCP dial target: the redacted host parsed from HWLAB_CLOUD_DB_URL, reported as endpointSource="secret-url-host".

cloud-api-db is only an optional desired alias. Until this repo owns the Service plus Endpoint or EndpointSlice manifests and rollout/apply contract, it is not a readiness authority, is not the TCP probe target, and a missing alias must not reverse-fail live DB success from the Secret URL host.

When the Secret/env is absent, the health JSON should keep db.connected: false, set db.status: "blocked", and list the missing env names so gate reports can identify cloud-api-db-health-gate. When the env is present but no live DB probe is attempted, the gate remains blocked with connectionResult: "not_attempted". When a probe is attempted but liveConnected is false, the gate remains blocked/degraded with the redacted connection classifier. connectionResult: "dns_error" with classification: "dns_resolution_failed" means DB endpoint DNS failed from the cloud-api runtime for the Secret URL host. Env presence alone is not live DB evidence.

The Code Agent provider Secret for #143 is a separate blocker. The edge-health report may record only key-presence evidence for hwlab-code-agent-provider/openai-api-key and runtime error classification such as provider_secret_missing; it must not read or print provider Secret values. Do not collapse this #143 provider Secret gap into the DB live blocker.

Route Classification

The smoke classifies failures into these blockers:

• frp_blocker: public :16667 is unavailable and frps control or tunnel health ports also refuse connections.
• edge_proxy_blocker: frps is reachable, but public :16667 refuses.
• k3s_service_blocker: k3s is observable but HWLAB DEV services/endpoints are missing.
• dns_port_firewall_blocker: public endpoint times out or cannot be resolved as a port/network path.
• app_health_blocker: public HTTP reaches an app but health JSON is wrong, missing evidence, returns an HTTP error, or reports DB env injected without a live DB connection.

Machine-Readable Diagnosis

Blocked frp_blocker and edge_proxy_blocker reports now include a diagnosis object in /tmp/hwlab-dev-gate/dev-edge-health.json with:

• likelyLayer: the most likely broken layer, such as master-edge/frps;
• confidence: coarse confidence for the diagnosis;
• likelyCause: a single-sentence blocker summary;
• evidence: the TCP probes that support the diagnosis;
• notProven: layers this probe did not rule out;
• nextTask: the smallest read-only follow-up or ops action.

Current Blocker

The committed report at /tmp/hwlab-dev-gate/dev-edge-health.json records a read-only live run where public http://74.48.78.17:16667/health/live returned HWLAB DEV health from hwlab-cloud-api, DB config was present, and runtime health attempted a redacted TCP DB probe. The probe was not connected: connected=false, liveConnected=false, liveDbEvidence=false, connectionResult="dns_error", and classification="dns_resolution_failed". This is a DB live readiness blocker for #49, not proof that DB is connected.

The same report records the #143 Code Agent provider Secret gap separately as provider_secret_missing when key-presence evidence for hwlab-code-agent-provider/openai-api-key is absent. DB live readiness, provider-backed Code Agent chat, M3 hardware trusted-loop proof, M4 live agent loop, and M5 DEV-LIVE acceptance remain separate evidence layers.

DEV FRP Contract

deploy/frp/frps.dev.toml reserves public 16666 for hwlab-cloud-web and public 16667 as a TCP remotePort for hwlab-dev-edge-proxy. Do not bind vhostHTTPPort = 16667 in the same frps config; that collides with the TCP proxy and can keep the DEV route from registering cleanly.