MCM-15 — WebSocket Real-Time Delivery

← Back to Notification System overview

As an Orchestration User,
I want deployment status changes (started, succeeded, failed) to appear instantly in the notification bell,
so that I do not have to manually refresh the page to check on a running stack.

Acceptance Criteria

• The frontend establishes a single authenticated WebSocket connection per browser session on login.
• The server pushes notification events to the connected client within 2 seconds of the triggering event.
• On reconnection after a network drop, the client requests all notifications missed since the last-received sequence ID — no events are silently lost.
• WebSocket authentication uses the same JWT access token as REST API calls; expired tokens cause a controlled disconnect with a 4401 close code, prompting re-login.
• Multiple open browser tabs for the same user all receive the same events independently (server fans out per session, not per user, to avoid cross-tab message duplication in the drawer).
• The connection gracefully handles idle periods via server-sent ping frames every 30 seconds; the client closes and reconnects if no ping is received within 60 seconds.

---

Technical Design

This story is the transport layer behind the notification bell: on login the frontend opens one authenticated WebSocket connection per browser tab, reusing the same JWT access token as REST calls, and the notification service fans out events per session — not per user — so two tabs for the same user each get an independent stream instead of one swallowing the other's badge update. Fan-out state is shared via a pub/sub broker (e.g. Redis) rather than held in a single instance's memory, so the service can scale horizontally past 10,000 concurrent connections while still targeting a P95 delivery latency of ≤ 2 seconds from event trigger to client receipt. Each event carries a monotonic sequence ID; on reconnect — whether from an idle-ping timeout, a network drop, or an expired token forcing a 4401 close — the client sends its last-seen sequence ID and the server replays anything missed, so no event is silently lost.

---

UI / Frontend Changes

• No new visible screens — this story is the transport layer behind the Notification Bell's live badge and drawer updates.
• Client establishes and manages a single authenticated WebSocket connection per browser tab on login, with automatic reconnect/backoff logic.
• Reconnect flow silently re-syncs missed events (via last-seen sequence ID) without a visible loading state to the user.
• Expired-token disconnects (4401) redirect the user to the login page rather than failing silently.