Code Queue Review
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# HWLAB DEV Edge Health
|
|
|
|
This check is DEV-only and targets the frozen endpoint:
|
|
|
|
```sh
|
|
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.
|