From d46beda807c4ac68a007939af7c502e93a44247e Mon Sep 17 00:00:00 2001 From: Abhishek Date: Mon, 16 Nov 2026 15:12:01 +0000 Subject: [PATCH] feat(frontend): add SSE recovery banner with reconnect countdown Show a polite status banner when the realtime connection drops, with a countdown to the next retry, a Reconnect Now button, a short Connected! message on recovery and a refetch of the runtime-state query. useSse now exposes nextReconnectAt and a reconnectNow() helper. Its store snapshot is also a fresh copy per change now, because the in-place mutated object meant useSyncExternalStore never re-rendered subscribers. Closes #364 Signed-off-by: Abhishek --- .../src/features/realtime/RecoveryOverlay.tsx | 126 ++++++++++++- .../__tests__/RecoveryOverlay.test.tsx | 167 ++++++++++++++++++ frontend/src/hooks/useSse.reconnect.test.ts | 132 ++++++++++++++ frontend/src/hooks/useSse.ts | 47 ++++- 4 files changed, 466 insertions(+), 6 deletions(-) create mode 100644 frontend/src/features/realtime/__tests__/RecoveryOverlay.test.tsx create mode 100644 frontend/src/hooks/useSse.reconnect.test.ts diff --git a/frontend/src/features/realtime/RecoveryOverlay.tsx b/frontend/src/features/realtime/RecoveryOverlay.tsx index 2f3c9f06..62a1e66c 100644 --- a/frontend/src/features/realtime/RecoveryOverlay.tsx +++ b/frontend/src/features/realtime/RecoveryOverlay.tsx @@ -1,9 +1,13 @@ -// src/features/realtime/RecoveryOverlay.tsx — Gentle full-page overlay on comeback -// Shows when user returns after inactivity, provides encouragement +// src/features/realtime/RecoveryOverlay.tsx — Recovery surfaces for the realtime layer +// 1. Gentle full-page overlay on comeback (user returns after inactivity) +// 2. Small status banner while the SSE connection is down, with a retry countdown +import { useEffect, useState } from 'react'; import { motion, AnimatePresence } from 'framer-motion'; -import { ArrowRight, Sparkles } from 'lucide-react'; -import { useSse } from '../../hooks/useSse'; +import { ArrowRight, Sparkles, WifiOff } from 'lucide-react'; +import { useQueryClient } from '@tanstack/react-query'; +import { reconnectNow, useSse } from '../../hooks/useSse'; +import { useUserStore } from '../../store/userStore'; import { cn } from '../../lib/design-system/tokens.css'; import { copy } from '../../lib/copy'; @@ -18,7 +22,121 @@ interface RecoveryMessage { expiresAt: string; } +const CONNECTED_MESSAGE_MS = 1_500; +const RUNTIME_STATE_QUERY_KEY = ['runtime-state'] as const; + +/** Whole seconds left until `nextReconnectAt`, never negative. */ +export function secondsUntil(nextReconnectAt: number, now: number): number { + return Math.max(0, Math.ceil((nextReconnectAt - now) / 1000)); +} + +export function ConnectionRecoveryBanner() { + const isAuthenticated = useUserStore((s) => s.isAuthenticated); + const { connectionStatus, nextReconnectAt } = useSse(); + const queryClient = useQueryClient(); + // `interrupted` stays true from the first drop until the "Connected!" message is gone, + // so the first connect after page load (status 'connecting') never shows a banner. + const [interrupted, setInterrupted] = useState(false); + const [recovered, setRecovered] = useState(false); + const [now, setNow] = useState(() => Date.now()); + + useEffect(() => { + if (!isAuthenticated) { + setInterrupted(false); + setRecovered(false); + return; + } + if (connectionStatus === 'reconnecting') { + setInterrupted(true); + setRecovered(false); + } else if (connectionStatus === 'connected' && interrupted && !recovered) { + setRecovered(true); + // Events missed while offline are gone, so pull the runtime state fresh. + void queryClient.invalidateQueries({ queryKey: RUNTIME_STATE_QUERY_KEY }); + } + }, [isAuthenticated, connectionStatus, interrupted, recovered, queryClient]); + + useEffect(() => { + if (!recovered) return; + const timer = setTimeout(() => { + setRecovered(false); + setInterrupted(false); + }, CONNECTED_MESSAGE_MS); + return () => clearTimeout(timer); + }, [recovered]); + + const waiting = connectionStatus === 'reconnecting' && nextReconnectAt !== null; + useEffect(() => { + if (!waiting) return; + setNow(Date.now()); + const tick = setInterval(() => setNow(Date.now()), 1000); + return () => clearInterval(tick); + }, [waiting, nextReconnectAt]); + + if (!isAuthenticated) return null; + + const showBanner = interrupted && (recovered || connectionStatus !== 'connected'); + const seconds = waiting && nextReconnectAt !== null ? secondsUntil(nextReconnectAt, now) : 0; + const attemptInFlight = connectionStatus === 'connecting' || (waiting && seconds === 0); + + // The live region stays mounted so screen readers pick up the text changes inside it. + return ( +
+ + {showBanner && ( + + {recovered ? ( +

Connected!

+ ) : ( + <> +
+ )} +
+
+ ); +} + export function RecoveryOverlay() { + return ( + <> + + + + ); +} + +function ComebackOverlay() { const { eventHistory } = useSse(); // Filter for comeback messages diff --git a/frontend/src/features/realtime/__tests__/RecoveryOverlay.test.tsx b/frontend/src/features/realtime/__tests__/RecoveryOverlay.test.tsx new file mode 100644 index 00000000..6e1fbcce --- /dev/null +++ b/frontend/src/features/realtime/__tests__/RecoveryOverlay.test.tsx @@ -0,0 +1,167 @@ +import '@testing-library/jest-dom/vitest'; +import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'; +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import type { ReactNode } from 'react'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { useUserStore } from '../../../store/userStore'; +import { ConnectionRecoveryBanner, RecoveryOverlay, secondsUntil } from '../RecoveryOverlay'; + +const sse = vi.hoisted(() => ({ + state: { + connectionStatus: 'connected', + nextReconnectAt: null as number | null, + eventHistory: [] as unknown[], + }, + reconnectNow: vi.fn(), +})); +vi.mock('../../../hooks/useSse', () => ({ + useSse: () => sse.state, + reconnectNow: sse.reconnectNow, +})); +// Exit animations do not finish under fake timers, so render plain elements. +vi.mock('framer-motion', () => ({ + AnimatePresence: ({ children }: { children: ReactNode }) => <>{children}, + motion: new Proxy({}, { + get: (_t, tag: string) => + ({ children, initial, animate, exit, transition, ...rest }: Record) => { + void initial; void animate; void exit; void transition; + const Tag = tag as 'div'; + return {children as ReactNode}; + }, + }), +})); + +const queryClient = new QueryClient(); +const invalidate = vi.spyOn(queryClient, 'invalidateQueries'); + +function ui() { + return ( + + + + ); +} + +function setSse(connectionStatus: string, nextReconnectAt: number | null = null) { + sse.state.connectionStatus = connectionStatus; + sse.state.nextReconnectAt = nextReconnectAt; +} + +describe('ConnectionRecoveryBanner', () => { + beforeEach(() => { + vi.useFakeTimers(); + vi.setSystemTime(new Date('2026-01-01T00:00:00Z')); + useUserStore.setState({ isAuthenticated: true }); + setSse('connected'); + sse.state.eventHistory = []; + sse.reconnectNow.mockClear(); + invalidate.mockClear(); + }); + afterEach(() => { + cleanup(); + vi.useRealTimers(); + }); + + it('keeps an empty polite live region and no banner while connected', () => { + render(ui()); + const region = screen.getByRole('status'); + expect(region).toHaveAttribute('aria-live', 'polite'); + expect(region).toBeEmptyDOMElement(); + }); + + it('does not show a banner for the first connect after page load', () => { + setSse('connecting'); + render(ui()); + expect(screen.queryByText(/Reconnecting/)).toBeNull(); + expect(screen.queryByRole('button', { name: 'Reconnect Now' })).toBeNull(); + }); + + it('shows the reconnect message with a countdown that ticks down', () => { + setSse('reconnecting', Date.now() + 5_000); + render(ui()); + + expect(screen.getByRole('status')).toHaveTextContent('Reconnecting to live server...'); + expect(screen.getByText('Next attempt in 5s')).toBeInTheDocument(); + + act(() => { vi.advanceTimersByTime(2_000); }); + expect(screen.getByText('Next attempt in 3s')).toBeInTheDocument(); + }); + + it('Reconnect Now calls reconnectNow', () => { + setSse('reconnecting', Date.now() + 9_000); + render(ui()); + fireEvent.click(screen.getByRole('button', { name: 'Reconnect Now' })); + expect(sse.reconnectNow).toHaveBeenCalledTimes(1); + }); + + it('disables Reconnect Now while an attempt is already running', () => { + setSse('reconnecting', Date.now() + 9_000); + const view = render(ui()); + setSse('connecting'); + view.rerender(ui()); + expect(screen.getByRole('button', { name: 'Reconnect Now' })).toBeDisabled(); + expect(screen.queryByText(/Next attempt/)).toBeNull(); + }); + + it('shows Connected! for 1.5s on recovery, refreshes runtime state, then goes away', () => { + setSse('reconnecting', Date.now() + 3_000); + const view = render(ui()); + expect(invalidate).not.toHaveBeenCalled(); + + setSse('connected'); + view.rerender(ui()); + expect(screen.getByText('Connected!')).toBeInTheDocument(); + expect(screen.queryByRole('button', { name: 'Reconnect Now' })).toBeNull(); + expect(invalidate).toHaveBeenCalledTimes(1); + expect(invalidate).toHaveBeenCalledWith({ queryKey: ['runtime-state'] }); + + act(() => { vi.advanceTimersByTime(1_499); }); + expect(screen.getByText('Connected!')).toBeInTheDocument(); + act(() => { vi.advanceTimersByTime(1); }); + expect(screen.queryByText('Connected!')).toBeNull(); + expect(screen.getByRole('status')).toBeEmptyDOMElement(); + expect(invalidate).toHaveBeenCalledTimes(1); + }); + + it('shows a paused state with Reconnect Now once the hook has given up', () => { + setSse('reconnecting', Date.now() + 3_000); + const view = render(ui()); + setSse('disconnected'); + view.rerender(ui()); + + expect(screen.getByText('Live updates paused. We could not reach the server.')).toBeInTheDocument(); + fireEvent.click(screen.getByRole('button', { name: 'Reconnect Now' })); + expect(sse.reconnectNow).toHaveBeenCalledTimes(1); + }); + + it('renders nothing for a signed out user', () => { + useUserStore.setState({ isAuthenticated: false }); + setSse('reconnecting', Date.now() + 3_000); + const { container } = render(ui()); + expect(container).toBeEmptyDOMElement(); + }); +}); + +describe('RecoveryOverlay', () => { + afterEach(cleanup); + + it('still shows the comeback message next to the connection banner', () => { + useUserStore.setState({ isAuthenticated: true }); + setSse('connected'); + sse.state.eventHistory = [{ + type: 'behavioral_message', + stats: { id: 'c1', tone: 'calm', text: 'Glad you are back', context: 'comeback', expiresAt: '2999-01-01T00:00:00Z' }, + }]; + render(); + expect(screen.getByRole('dialog', { name: 'Welcome back' })).toBeInTheDocument(); + expect(screen.getByText('Glad you are back')).toBeInTheDocument(); + }); +}); + +describe('secondsUntil', () => { + it('rounds up and never goes below zero', () => { + expect(secondsUntil(10_001, 10_000)).toBe(1); + expect(secondsUntil(12_000, 10_000)).toBe(2); + expect(secondsUntil(9_000, 10_000)).toBe(0); + }); +}); diff --git a/frontend/src/hooks/useSse.reconnect.test.ts b/frontend/src/hooks/useSse.reconnect.test.ts new file mode 100644 index 00000000..f0fd3ec1 --- /dev/null +++ b/frontend/src/hooks/useSse.reconnect.test.ts @@ -0,0 +1,132 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +const post = vi.fn(); +vi.mock('../utils/axiosClient', () => ({ default: { post } })); + +class FakeEventSource { + static instances: FakeEventSource[] = []; + url: string; + onopen: (() => void) | null = null; + onmessage: ((ev: MessageEvent) => void) | null = null; + onerror: (() => void) | null = null; + close = vi.fn(); + constructor(url: string) { + this.url = url; + FakeEventSource.instances.push(this); + } +} + +async function loadHook() { + vi.resetModules(); + const sse = await import('./useSse'); + const { useUserStore } = await import('../store/userStore'); + useUserStore.setState({ isAuthenticated: true }); + return sse; +} + +describe('SSE reconnect scheduling and manual retry', () => { + beforeEach(() => { + vi.useFakeTimers(); + vi.setSystemTime(new Date('2026-01-01T00:00:00Z')); + post.mockReset(); + FakeEventSource.instances = []; + vi.stubGlobal('EventSource', FakeEventSource); + localStorage.setItem('devtrack_access_token', 'jwt'); + vi.spyOn(console, 'warn').mockImplementation(() => undefined); + }); + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); + localStorage.clear(); + }); + + it('exposes when the next attempt happens and clears it once the attempt starts', async () => { + post.mockRejectedValueOnce(new Error('down')); + post.mockResolvedValue({ data: { data: { ticket: 't' } } }); + const sse = await loadHook(); + const { useSse } = sse; + const { act, renderHook } = await import('@testing-library/react'); + const { QueryClient, QueryClientProvider } = await import('@tanstack/react-query'); + const { createElement } = await import('react'); + const client = new QueryClient(); + const wrapper = ({ children }: { children: React.ReactNode }) => + createElement(QueryClientProvider, { client }, children); + const { result, unmount } = renderHook(() => useSse(), { wrapper }); + + await act(async () => { await vi.advanceTimersByTimeAsync(0); }); + expect(result.current.connectionStatus).toBe('reconnecting'); + expect(result.current.nextReconnectAt).toBe(Date.now() + 3_000); + + await act(async () => { await vi.advanceTimersByTimeAsync(3_000); }); + expect(result.current.nextReconnectAt).toBeNull(); + expect(FakeEventSource.instances).toHaveLength(1); + unmount(); + }); + + it('reconnectNow skips the backoff wait and does not leave a second timer behind', async () => { + post.mockRejectedValueOnce(new Error('down')); + post.mockResolvedValue({ data: { data: { ticket: 't' } } }); + const { connectGlobalSse, reconnectNow, disconnectGlobalSse } = await loadHook(); + + await connectGlobalSse(vi.fn(), vi.fn()); + expect(FakeEventSource.instances).toHaveLength(0); + + reconnectNow(); + await vi.advanceTimersByTimeAsync(0); + expect(FakeEventSource.instances).toHaveLength(1); + + // the old 3s timer must have been cancelled, so nothing else connects + await vi.advanceTimersByTimeAsync(10_000); + expect(FakeEventSource.instances).toHaveLength(1); + expect(post).toHaveBeenCalledTimes(2); + disconnectGlobalSse(vi.fn()); + }); + + it('reconnectNow twice in a row only opens one stream', async () => { + post.mockRejectedValueOnce(new Error('down')); + post.mockResolvedValue({ data: { data: { ticket: 't' } } }); + const { connectGlobalSse, reconnectNow, disconnectGlobalSse } = await loadHook(); + + await connectGlobalSse(vi.fn(), vi.fn()); + reconnectNow(); + reconnectNow(); + await vi.advanceTimersByTimeAsync(0); + + expect(FakeEventSource.instances).toHaveLength(1); + expect(post).toHaveBeenCalledTimes(2); + disconnectGlobalSse(vi.fn()); + }); + + it('reconnectNow retries after the hook gave up with a fresh failure budget', async () => { + post.mockRejectedValue(new Error('rate limited')); + const { connectGlobalSse, reconnectNow, disconnectGlobalSse } = await loadHook(); + const setStatus = vi.fn(); + + await connectGlobalSse(setStatus, vi.fn()); + for (let i = 0; i < 4; i++) await vi.advanceTimersByTimeAsync(60_000); + expect(post).toHaveBeenCalledTimes(5); + expect(setStatus).toHaveBeenLastCalledWith('disconnected'); + + post.mockResolvedValue({ data: { data: { ticket: 'late' } } }); + reconnectNow(); + await vi.advanceTimersByTimeAsync(0); + + expect(post).toHaveBeenCalledTimes(6); + expect(FakeEventSource.instances).toHaveLength(1); + disconnectGlobalSse(vi.fn()); + }); + + it('reconnectNow does nothing while the stream is open', async () => { + post.mockResolvedValue({ data: { data: { ticket: 't' } } }); + const { connectGlobalSse, reconnectNow, disconnectGlobalSse } = await loadHook(); + + await connectGlobalSse(vi.fn(), vi.fn()); + FakeEventSource.instances[0].onopen?.(); + reconnectNow(); + await vi.advanceTimersByTimeAsync(0); + + expect(FakeEventSource.instances).toHaveLength(1); + expect(post).toHaveBeenCalledTimes(1); + disconnectGlobalSse(vi.fn()); + }); +}); diff --git a/frontend/src/hooks/useSse.ts b/frontend/src/hooks/useSse.ts index 6ad31a6c..a0deb669 100644 --- a/frontend/src/hooks/useSse.ts +++ b/frontend/src/hooks/useSse.ts @@ -89,6 +89,8 @@ interface UseSseResult { connectionStatus: ConnectionStatus; lastEvent: SseEvent | null; reconnectAttempt: number; + /** Epoch ms of the next scheduled reconnect attempt, or null when none is pending. */ + nextReconnectAt: number | null; diagnostics: SseDiagnostics; eventHistory: SseEvent[]; } @@ -134,6 +136,7 @@ interface StoreState { connectionStatus: ConnectionStatus; lastEvent: SseEvent | null; reconnectAttempt: number; + nextReconnectAt: number | null; connectedAt: number | null; lastEventAt: number | null; totalEventsReceived: number; @@ -148,6 +151,7 @@ const store: StoreState = { connectionStatus: 'disconnected', lastEvent: null, reconnectAttempt: 0, + nextReconnectAt: null, connectedAt: null, lastEventAt: null, totalEventsReceived: 0, @@ -177,12 +181,17 @@ function rememberEnvelopeId(id: string): void { type Listener = () => void; const listeners = new Set(); +// useSyncExternalStore only re-renders when the snapshot identity changes, and `store` is +// mutated in place, so hand React a fresh copy on every change. +let snapshot: StoreState = { ...store }; + function emitChange() { + snapshot = { ...store }; for (const l of listeners) l(); } function getSnapshot(): StoreState { - return store; + return snapshot; } interface HookCallbackRegistry { @@ -308,6 +317,7 @@ export async function connectGlobalSse( store.connectedAt = now; store.totalReconnects = store.reconnectAttempt > 0 ? store.totalReconnects + 1 : store.totalReconnects; store.consecutiveFailures = 0; + store.nextReconnectAt = null; store.connectionStatus = 'connected'; emitChange(); updateStatus('connected'); @@ -455,6 +465,7 @@ export function disconnectGlobalSse( } store.connectionStatus = 'disconnected'; store.reconnectAttempt = 0; + store.nextReconnectAt = null; store.lastEvent = null; store.eventHistory = []; store.lastEventId = null; @@ -477,16 +488,45 @@ function scheduleReconnect( ); store.reconnectAttempt = attempt + 1; + store.nextReconnectAt = Date.now() + delay; store.connectionStatus = 'reconnecting'; emitChange(); setSseStatus('reconnecting'); globalReconnectTimeout = setTimeout(() => { globalReconnectTimeout = null; + store.nextReconnectAt = null; connectGlobalSse(setSseStatus, setInfrastructureDegraded); }, delay); } +/** + * Skip the backoff wait and try to connect right away. Works while a retry is + * scheduled and after the hook gave up (`disconnected` once the failure cap is + * hit); it is a no-op while a connection attempt is already running or open, so + * a double click cannot open two streams. + */ +export function reconnectNow(): void { + if (store.connectionStatus === 'connected' || store.connectionStatus === 'connecting') return; + if (globalEventSource !== null) return; + + if (globalReconnectTimeout !== null) { + clearTimeout(globalReconnectTimeout); + globalReconnectTimeout = null; + } + // A manual retry gets a fresh failure budget, otherwise one more error would + // hit the cap again straight away after the hook had already given up. + if (store.connectionStatus === 'disconnected') { + globalConsecutiveFailures = 0; + store.consecutiveFailures = 0; + useUIStore.getState().setInfrastructureDegraded(false); + } + store.nextReconnectAt = null; + store.connectionStatus = 'connecting'; + emitChange(); + void connectGlobalSse(); +} + export function useSse(options: UseSseOptions = {}): UseSseResult { const { onEvent, extraInvalidateKeys = [], enabled = true } = options; @@ -495,7 +535,7 @@ export function useSse(options: UseSseOptions = {}): UseSseResult { const setSseStatus = (status: any) => useUIStore.getState().setSseStatus(status); const setInfrastructureDegraded = (degraded: boolean) => useUIStore.getState().setInfrastructureDegraded(degraded); - const { connectionStatus, lastEvent, reconnectAttempt } = useSyncExternalStore( + const { connectionStatus, lastEvent, reconnectAttempt, nextReconnectAt } = useSyncExternalStore( (listener) => { listeners.add(listener); return () => listeners.delete(listener); @@ -540,6 +580,7 @@ export function useSse(options: UseSseOptions = {}): UseSseResult { connectionStatus, lastEvent, reconnectAttempt, + nextReconnectAt, diagnostics: { connectedAt: store.connectedAt, lastEventAt: store.lastEventAt, @@ -561,6 +602,7 @@ export function __resetSseForTests(): void { store.connectionStatus = 'disconnected'; store.lastEvent = null; store.reconnectAttempt = 0; + store.nextReconnectAt = null; store.connectedAt = null; store.lastEventAt = null; store.totalEventsReceived = 0; @@ -569,6 +611,7 @@ export function __resetSseForTests(): void { store.eventHistory = []; store.lastEventId = null; activeCallbacks.clear(); + snapshot = { ...store }; } export const useXpUpdates = () => {