118 lines
6.9 KiB
Markdown
118 lines
6.9 KiB
Markdown
---
|
|
status: approved
|
|
created: 2026-07-30
|
|
owner: kandev
|
|
---
|
|
|
|
# WebSocket Connectivity Warning
|
|
|
|
## Why
|
|
|
|
Kandev can look current while its live WebSocket updates are delayed or unavailable. Users need a
|
|
quiet but unavoidable indication that task, session, and workspace state may be stale, without
|
|
showing permanent healthy-state chrome or flashing for harmless reconnects.
|
|
|
|
## What
|
|
|
|
- Kandev derives one transient connectivity severity from the continuous time since its canonical
|
|
application WebSocket last entered `connected`:
|
|
- **Healthy/grace:** no warning before 3 seconds offline.
|
|
- **Unstable:** yellow from 3 seconds offline until 10 seconds offline.
|
|
- **Lost:** red from 10 seconds offline until the connection recovers.
|
|
- Transitions among `connecting`, `reconnecting`, `disconnected`, and `error` belong to the same
|
|
continuous offline interval. They do not restart either threshold.
|
|
- Any `connected` transition clears the warning immediately. A later disconnect starts a new grace
|
|
interval.
|
|
- The yellow detail reads **Connection unstable. Reconnecting to Kandev.**
|
|
- The red detail reads **Connection lost for at least 10 seconds. Live updates may be stale.**
|
|
- Color is never the only signal. The active surface exposes the matching detail as an accessible
|
|
status name and through hover/focus on fine-pointer layouts or tap on phone.
|
|
- Desktop and tablet show exactly one warning:
|
|
- When **App status bar** is enabled, its built-in connection item is problem-only: absent while
|
|
healthy or in grace, yellow while unstable, and red while lost.
|
|
- When **App status bar** is disabled, a problem-only connection indicator appears in the persistent
|
|
app-sidebar footer beside the theme control. The fallback is absent while healthy or in grace.
|
|
- Phone uses its existing native Status paths rather than adding a persistent bar or overlay:
|
|
- Existing Status entry points receive yellow/red warning treatment.
|
|
- Route chrome that leads to a nested Status action, such as the Home or Settings menu, carries
|
|
the same warning treatment so the issue is visible before opening the menu.
|
|
- When **App status bar** is disabled, these paths appear only during an active warning and open a
|
|
connection-only Status drawer. Plugin contributions and metrics stay disabled.
|
|
- The warning does not alter reconnect attempts, WebSocket subscriptions, queued requests, or
|
|
last-known application data.
|
|
|
|
## State machine
|
|
|
|
| State | Entry | Visible result | Exit |
|
|
|---|---|---|---|
|
|
| `healthy` | WebSocket enters `connected` | No warning | First non-`connected` status |
|
|
| `grace` | A continuous offline interval starts | No warning | `connected`, or 3 seconds elapse |
|
|
| `unstable` | The same interval reaches 3 seconds | Yellow warning | `connected`, or 10 seconds elapse |
|
|
| `lost` | The same interval reaches 10 seconds | Red warning | `connected` |
|
|
|
|
The state is client-local and transient. A page reload starts a new connection attempt and grace
|
|
interval; no outage timestamp or warning history persists.
|
|
|
|
## Failure modes
|
|
|
|
- If the reconnect client exhausts its attempts, the warning remains red until a later
|
|
`connected` transition or page reload. It does not claim that retries are still running.
|
|
- If the optional App status surface is disabled, an active warning bypasses only its visibility
|
|
gate. It does not mount metrics, plugin status contributions, or a desktop/tablet status bar.
|
|
- If a responsive presentation changes during an outage, the current severity moves to the new
|
|
canonical surface without resetting its offline interval or rendering duplicate warnings.
|
|
- If the warning timer owner unmounts, it cancels pending thresholds and does not update stale
|
|
application state.
|
|
|
|
## Responsive and mobile contract
|
|
|
|
- Desktop outcome: one problem-only warning in the enabled bottom status bar or, when that bar is
|
|
disabled, beside the sidebar theme control.
|
|
- Phone entry points reuse the shipped Page/Office top-bar Status button, task bottom-nav Status
|
|
action, and Home/Settings menu paths. The persistent route control signals severity before the
|
|
nested Status action is opened.
|
|
- The existing App Status drawer is the nearest shipped mobile exemplar. It contributes the inset
|
|
bottom surface, fixed summary, one safe-area-aware internal scroll owner, 44 px rows, dismissal,
|
|
and focus return.
|
|
- A short connection explanation belongs in that temporary drawer; it does not justify a new route
|
|
or full-height surface.
|
|
- Connection timing and severity are shared across breakpoints. Mobile-specific code only chooses
|
|
presentation and touch entry points.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** a connected client, **WHEN** its WebSocket is offline for less than 3 seconds and
|
|
reconnects, **THEN** no connectivity warning appears.
|
|
- **GIVEN** a connected client, **WHEN** its WebSocket remains offline for 3 seconds, **THEN** one
|
|
yellow warning appears with **Connection unstable. Reconnecting to Kandev.**
|
|
- **GIVEN** the same outage, **WHEN** it reaches 10 seconds, **THEN** the existing warning becomes
|
|
red with **Connection lost for at least 10 seconds. Live updates may be stale.**
|
|
- **GIVEN** an unstable or lost warning, **WHEN** any reconnect attempt enters `connected`, **THEN**
|
|
the warning disappears immediately and a later outage receives a fresh grace interval.
|
|
- **GIVEN** reconnect attempts cycle through non-connected raw statuses, **WHEN** the continuous
|
|
outage crosses a threshold, **THEN** the threshold is measured from the original disconnect.
|
|
- **GIVEN** App status bar enabled on desktop or tablet, **WHEN** connection severity changes,
|
|
**THEN** only its built-in connection item reflects the warning and no sidebar fallback appears.
|
|
- **GIVEN** App status bar disabled on desktop or tablet, **WHEN** connection severity becomes
|
|
unstable or lost, **THEN** one warning indicator appears beside the sidebar theme control and exposes
|
|
the matching detail on hover and focus.
|
|
- **GIVEN** App status bar disabled on phone, **WHEN** connection severity becomes unstable or
|
|
lost, **THEN** persistent route chrome signals the issue and its Status path opens a
|
|
connection-only, touch-sized drawer without metrics or plugin contributions.
|
|
- **GIVEN** a phone warning, **WHEN** the user opens and dismisses Status, **THEN** the connection
|
|
detail is readable, the drawer stays within the viewport, and focus returns to the trigger.
|
|
- **GIVEN** an active warning, **WHEN** the viewport crosses between phone and wider layouts,
|
|
**THEN** the severity remains unchanged and exactly one canonical warning surface is visible.
|
|
|
|
## Out of scope
|
|
|
|
- Latency, packet-loss, heartbeat-quality, or REST-health sampling.
|
|
- Changing reconnect delays, retry limits, queueing, resubscription, or missed-event recovery.
|
|
- Manual reconnect actions, recovery toasts, healthy-state success messages, outage history, or
|
|
persisted incident timestamps.
|
|
- A new phone bar, toast, route, full-screen alert, or desktop top-bar injection.
|
|
|
|
## Implementation plan
|
|
|
|
[WebSocket connectivity warning plan](../../plans/ws-connectivity-warning/plan.md)
|