Transport and Cloud fallback

Rules

1. Prefer Edge — push inventory via edgezu-hostagent-gateway on LAN, when discoverable.
2. Fallback Cloud — direct POST /v1/ingest to the Ingestor service (same service Edge’s own telemetry uses — Cloud Backend has no ingest endpoint) when Edge unavailable.
3. Sticky — keep using last successful path.
4. Fail-fast — first failed push immediately tries the other path.
5. Rediscovery — periodically search for Edge again (mDNS _edgezu-gateway._tcp).

Implemented in hostzu-agent/src/transport.rs (TransportSelector, CloudTransport, EdgeTransport).

Known gap: Edge does not yet advertise _edgezu-gateway._tcp — the agent’s mDNS client (rule 5) exists and correctly falls back to Cloud when nothing answers, but nothing on Edge answers yet. Rediscovery will start working automatically once Edge-side advertisement ships; no agent changes needed.

Edge path

Host → POST /local/v1/host-inventory (X-Host-Token, validated against a Cloud-synced hash cache)
     → Edge queues it through the normal edgezu-agent flush loop (push_ingest → ingest_queue)
     → POST /v1/ingest (X-Device-Key = Edge's own device key, host_id in payload) — Ingestor

This is the same queued path every other kind (telemetry/log/discovery/etc.) uses — host_inventory is not special-cased on the Edge side, it’s just another push_ingest(kind, payload) call. A snapshot queued while Edge is briefly offline from Cloud is retried on the next flush, same as any other kind.

Cloud path

Host → POST /v1/ingest (Authorization: Bearer host_token, kind: host_inventory) — Ingestor

Both paths land on the same Ingestor endpoint (internal/domain/ingest, dispatching to internal/domain/hostinventory for this kind), which accepts either credential (HostTokenOrDeviceKey middleware) and resolves the host_agent row from the Bearer token directly, or from (tenant, host_id) — parsed out of the item payload — when arriving via device key.

MVP constraint

Assume one Edge per LAN. Multi-Edge selection is deferred — see root TODO.md.

Debug

Symptom	Likely cause
Always on Cloud, even with Edge present	Expected today — Edge doesn’t advertise mDNS yet (see gap above)
Flapping paths	Intermittent Edge reachability — check sticky/fail-fast logs
401 on ingest via Edge	Host token hash not yet synced to Edge’s cache (hostagent.sync_tokens command), or host was revoked
401 on ingest direct to Cloud	Revoked or expired host_token

See Troubleshooting — Host Agent transport.