ADR 18: Gateway Connectivity Presence and Push Updates

Status: Proposed Date: 2026-04-25

Context

The web file explorer currently resolves gateway status during route matching and renders a single status line in the shell layout. This is sufficient for initial page load but does not provide responsive connectivity feedback when runtime conditions change (for example, ingress restarts during local rebuilds, short proxy interruptions, or transient network loss).

Users need fast, understandable status transitions similar to progressive web application connectivity indicators. The status experience must avoid noisy error strings, reduce false negatives during short restarts, and keep the UI responsive while preserving Substratum's modular monolith boundaries.

At the same time, a single mechanism is not enough:

• Browser connectivity signals are immediate but only indicate internet reachability, not gateway readiness.
• Polling can detect gateway health but may lag and create unnecessary load when healthy.
• Push channels provide near real-time updates but require reconnect behavior and a fallback path.

Decision

Adopt a hybrid connectivity presence model for browser clients:

1. Client connection state machine

   • Introduce explicit UI states for connectivity presence (for example: connected, reconnecting, offline, degraded).
   • Drive display copy and behavior from this state machine instead of raw transport errors.

2. Immediate browser signal integration

   • Use browser online and offline events for instant UX feedback.
   • Treat these events as advisory signals that influence state transitions, not as authoritative gateway health.

3. Gateway health probing with adaptive cadence

   • Keep an HTTP health probe to ingress as the authoritative gateway readiness signal.
   • Use adaptive retry/backoff while unhealthy and a calmer steady interval while healthy.
   • Require consecutive success/failure thresholds to reduce visual flapping.

4. Server push for real-time status transitions

   • Add a server push channel from ingress to browser clients (prefer Server-Sent Events for one-way presence updates).
   • Broadcast coarse-grained system presence events (for example: gateway_up, gateway_degraded, gateway_down) without exposing sensitive internals.
   • Automatically fall back to health probing when the push channel is unavailable.

5. Transport and payload resilience

   • Require tolerant client handling for non-JSON/intermediate responses during restart windows.
   • Normalize transport failures into domain-level connectivity states.

This decision defines the architecture and interaction contract. Concrete endpoint names, payload schemas, and implementation sequencing are tracked in implementation plans and module-level documentation.

Consequences

• Positive: Improves perceived responsiveness and trust by reflecting connectivity changes quickly.
• Positive: Reduces brittle status behavior during local rebuilds and short ingress restarts.
• Positive: Balances freshness and efficiency by combining push updates with adaptive polling fallback.
• Positive: Keeps architecture modular by modeling connectivity as a dedicated cross-boundary concern.
• Negative: Adds coordination complexity across ingress, API client, and file explorer state management.
• Negative: Introduces operational considerations for long-lived push connections and reconnect strategy.
• Negative: Requires careful event semantics to avoid exposing implementation details or noisy transitions.