code-coordinator 0.5.46__py3-none-any.whl

coord/dashboard/webapp/src/realtime/RealtimeProvider.tsx

@@ -0,0 +1,112 @@
+/**
+ * Wires the SSE connection (`connection.ts`) to react-query invalidation and
+ * exposes the live connection state via context (#1549).
+ *
+ * Mount once, at the root, inside `QueryClientProvider` (see `main.tsx`).
+ * Every screen that wants the honest live/reconnecting/stale indicator reads
+ * `useConnectionStatus()`; nothing else needs to know an `EventSource` is
+ * involved.
+ */
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react'
+import { useQueryClient, type QueryClient } from '@tanstack/react-query'
+import {
+  createSseConnection,
+  type ConnectionStatus,
+  type EventSourceFactory,
+} from './connection'
+import { EVENT_TYPES, EVENT_QUERY_KEYS, RESYNC_QUERY_KEYS } from './events'
+
+const SSE_URL = '/events'
+
+const INITIAL_STATUS: ConnectionStatus = { state: 'connecting', lastLiveAt: null, attempt: 0 }
+
+const ConnectionStatusContext = createContext<ConnectionStatus>(INITIAL_STATUS)
+
+/** The current SSE connection state — live / reconnecting / disconnected / connecting. */
+// eslint-disable-next-line react-refresh/only-export-components -- a hook alongside its provider component is the standard context pattern (see components/ui/badge.tsx for the same precedent).
+export function useConnectionStatus(): ConnectionStatus {
+  return useContext(ConnectionStatusContext)
+}
+
+interface RealtimeProviderProps {
+  children: ReactNode
+  /** Test-only seam; production always uses the browser's native `EventSource`. */
+  createEventSource?: EventSourceFactory
+  /** Test-only seam for pointing at a fixture/mock stream. */
+  url?: string
+  /** Test-only seam for exact backoff timing; production uses connection.ts's default schedule. */
+  backoffScheduleMs?: readonly number[]
+}
+
+function invalidate(queryClient: QueryClient, type: string): void {
+  for (const key of EVENT_QUERY_KEYS[type] ?? []) {
+    void queryClient.invalidateQueries({ queryKey: key })
+  }
+}
+
+function resync(queryClient: QueryClient): void {
+  for (const key of RESYNC_QUERY_KEYS) {
+    void queryClient.invalidateQueries({ queryKey: key })
+  }
+}
+
+export function RealtimeProvider({
+  children,
+  createEventSource,
+  url,
+  backoffScheduleMs,
+}: RealtimeProviderProps) {
+  const queryClient = useQueryClient()
+  const [status, setStatus] = useState<ConnectionStatus>(INITIAL_STATUS)
+
+  // useQuery/useQueryClient give a stable-enough client in practice, but the
+  // connection object is only ever created once (see the lazy ref below) —
+  // route every callback through a ref so it always sees the current client
+  // rather than closing over whatever was live at construction time.
+  const queryClientRef = useRef(queryClient)
+  queryClientRef.current = queryClient
+
+  // The connection is created exactly once per component instance (lazy
+  // useRef initializer) and driven by start()/stop() from the effect below.
+  // This is deliberate: StrictMode's mount -> cleanup -> mount replay must
+  // reuse the SAME connection object so its start()'s token bump is what
+  // guards the superseded socket, rather than constructing two independent
+  // connections that both think they're the only one.
+  const connRef = useRef<ReturnType<typeof createSseConnection> | null>(null)
+  const prevStateRef = useRef<ConnectionStatus['state']>('connecting')
+  if (connRef.current === null) {
+    connRef.current = createSseConnection({
+      url: url ?? SSE_URL,
+      eventTypes: EVENT_TYPES,
+      createEventSource,
+      backoffScheduleMs,
+      onEvent: (type, data) => {
+        invalidate(queryClientRef.current, type)
+        // board_updated carries a fresh timestamp/summary but no assignment
+        // identity worth threading further -- data is otherwise unused today.
+        void data
+      },
+      onStatusChange: (next) => {
+        // The only path to 'live' is from 'connecting' (first-ever connect,
+        // nothing to resync) or from 'reconnecting' (a real recovery, where
+        // events may have been missed -- see events.ts RESYNC_QUERY_KEYS).
+        if (next.state === 'live' && prevStateRef.current === 'reconnecting') {
+          resync(queryClientRef.current)
+        }
+        prevStateRef.current = next.state
+        setStatus(next)
+      },
+    })
+  }
+
+  useEffect(() => {
+    const conn = connRef.current
+    if (!conn) return
+    conn.start()
+    return () => conn.stop()
+  }, [])
+
+  return (
+    <ConnectionStatusContext.Provider value={status}>{children}</ConnectionStatusContext.Provider>
+  )
+}

coord/dashboard/webapp/src/realtime/__tests__/RealtimeProvider.test.tsx

@@ -0,0 +1,189 @@
+/**
+ * React-level tests for RealtimeProvider (#1549): event -> query-key
+ * invalidation, the honest connection-state context, and the StrictMode
+ * double-mount trap the module doc comment (connection.ts) describes --
+ * exercised here with React's actual `<StrictMode>`, not just simulated.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { act, render, screen, waitFor } from '@testing-library/react'
+import React from 'react'
+import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query'
+import { RealtimeProvider, useConnectionStatus } from '../RealtimeProvider'
+import type { SseHandle } from '../connection'
+
+// ── Fake EventSource (same shape as connection.test.ts's) ────────────────────
+
+class FakeEventSource implements SseHandle {
+  static instances: FakeEventSource[] = []
+  static reset(): void {
+    FakeEventSource.instances = []
+  }
+
+  url: string
+  closed = false
+  onopen: ((ev: unknown) => void) | null = null
+  onerror: ((ev: unknown) => void) | null = null
+  private listeners = new Map<string, Array<(ev: { data: string }) => void>>()
+
+  constructor(url: string) {
+    this.url = url
+    FakeEventSource.instances.push(this)
+  }
+
+  addEventListener(type: string, listener: (ev: { data: string }) => void): void {
+    const list = this.listeners.get(type) ?? []
+    list.push(listener)
+    this.listeners.set(type, list)
+  }
+
+  close(): void {
+    this.closed = true
+  }
+
+  emitOpen(): void {
+    this.onopen?.({})
+  }
+
+  emitError(): void {
+    this.onerror?.({})
+  }
+
+  emitMessage(type: string, data: unknown): void {
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener({ data: JSON.stringify(data) })
+    }
+  }
+}
+
+function lastInstance(): FakeEventSource {
+  const inst = FakeEventSource.instances[FakeEventSource.instances.length - 1]
+  if (!inst) throw new Error('no FakeEventSource created')
+  return inst
+}
+
+function openInstances(): FakeEventSource[] {
+  return FakeEventSource.instances.filter((i) => !i.closed)
+}
+
+beforeEach(() => {
+  FakeEventSource.reset()
+})
+
+// ── Test fixtures ────────────────────────────────────────────────────────────
+
+/** Renders the connection status as text, for assertions. */
+function StatusProbe() {
+  const { state } = useConnectionStatus()
+  return <span data-testid="status">{state}</span>
+}
+
+/** A query whose fetch count is observable, standing in for ['pipeline']. */
+function pipelineFetcher() {
+  return vi.fn().mockResolvedValue(['ok'])
+}
+
+function PipelineProbe({ queryFn }: { queryFn: () => Promise<string[]> }) {
+  const { data } = useQuery({ queryKey: ['pipeline'], queryFn })
+  return <span data-testid="pipeline">{data?.length ?? 0}</span>
+}
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false, staleTime: Infinity } },
+  })
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('RealtimeProvider', () => {
+  it('exposes connecting -> live via context as the stream opens', async () => {
+    render(
+      <QueryClientProvider client={createTestQueryClient()}>
+        <RealtimeProvider createEventSource={(url) => new FakeEventSource(url) as unknown as SseHandle}>
+          <StatusProbe />
+        </RealtimeProvider>
+      </QueryClientProvider>,
+    )
+
+    await waitFor(() => expect(FakeEventSource.instances.length).toBeGreaterThan(0))
+    expect(screen.getByTestId('status').textContent).toBe('connecting')
+
+    act(() => lastInstance().emitOpen())
+    await waitFor(() => expect(screen.getByTestId('status').textContent).toBe('live'))
+  })
+
+  it('invalidates the pipeline query when an assignment_started event arrives', async () => {
+    const queryClient = createTestQueryClient()
+    const queryFn = pipelineFetcher()
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <RealtimeProvider createEventSource={(url) => new FakeEventSource(url) as unknown as SseHandle}>
+          <PipelineProbe queryFn={queryFn} />
+        </RealtimeProvider>
+      </QueryClientProvider>,
+    )
+
+    await waitFor(() => expect(queryFn).toHaveBeenCalledTimes(1))
+    act(() => lastInstance().emitOpen())
+
+    act(() => lastInstance().emitMessage('assignment_started', { assignment_id: 'w-1' }))
+
+    await waitFor(() => expect(queryFn).toHaveBeenCalledTimes(2))
+  })
+
+  it('resyncs the pipeline query on recovery from a drop, not on the first connect', async () => {
+    const queryClient = createTestQueryClient()
+    const queryFn = pipelineFetcher()
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <RealtimeProvider
+          createEventSource={(url) => new FakeEventSource(url) as unknown as SseHandle}
+          backoffScheduleMs={[5]}
+        >
+          <PipelineProbe queryFn={queryFn} />
+        </RealtimeProvider>
+      </QueryClientProvider>,
+    )
+
+    await waitFor(() => expect(queryFn).toHaveBeenCalledTimes(1))
+    act(() => lastInstance().emitOpen())
+    // First-ever connect: no resync, still just the initial fetch.
+    expect(queryFn).toHaveBeenCalledTimes(1)
+
+    // Drop, then a fresh socket recovers.
+    act(() => lastInstance().emitError())
+    await waitFor(() => expect(FakeEventSource.instances).toHaveLength(2))
+    act(() => lastInstance().emitOpen())
+
+    // Recovery from a real drop resyncs, on top of whatever the SSE event
+    // stream itself triggered.
+    await waitFor(() => expect(queryFn.mock.calls.length).toBeGreaterThanOrEqual(2))
+  })
+
+  it('survives the StrictMode double-mount replay with exactly one live socket', async () => {
+    render(
+      <React.StrictMode>
+        <QueryClientProvider client={createTestQueryClient()}>
+          <RealtimeProvider
+            createEventSource={(url) => new FakeEventSource(url) as unknown as SseHandle}
+          >
+            <StatusProbe />
+          </RealtimeProvider>
+        </QueryClientProvider>
+      </React.StrictMode>,
+    )
+
+    // StrictMode's mount -> cleanup -> mount may create an early socket that
+    // gets superseded; only one should remain open.
+    await waitFor(() => expect(openInstances()).toHaveLength(1))
+
+    act(() => openInstances()[0].emitOpen())
+    await waitFor(() => expect(screen.getByTestId('status').textContent).toBe('live'))
+
+    // The status only reflects the surviving socket -- a stale callback from
+    // any closed socket must not have flipped it back.
+    expect(screen.getByTestId('status').textContent).toBe('live')
+  })
+})

coord/dashboard/webapp/src/realtime/__tests__/connection.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Unit tests for the framework-agnostic SSE client (#1549).
+ *
+ * A fake `EventSource`-shaped handle stands in for the browser API so these
+ * tests can drive open/error/message deterministically and assert on the
+ * exact connection-state sequence, without any real network or timers other
+ * than Vitest's fake ones.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { createSseConnection, type ConnectionStatus, type SseHandle } from '../connection'
+
+// ── Fake EventSource ─────────────────────────────────────────────────────────
+
+class FakeEventSource implements SseHandle {
+  static instances: FakeEventSource[] = []
+  static reset(): void {
+    FakeEventSource.instances = []
+  }
+
+  url: string
+  closed = false
+  onopen: ((ev: unknown) => void) | null = null
+  onerror: ((ev: unknown) => void) | null = null
+  private listeners = new Map<string, Array<(ev: { data: string }) => void>>()
+
+  constructor(url: string) {
+    this.url = url
+    FakeEventSource.instances.push(this)
+  }
+
+  addEventListener(type: string, listener: (ev: { data: string }) => void): void {
+    const list = this.listeners.get(type) ?? []
+    list.push(listener)
+    this.listeners.set(type, list)
+  }
+
+  close(): void {
+    this.closed = true
+  }
+
+  emitOpen(): void {
+    this.onopen?.({})
+  }
+
+  emitError(): void {
+    this.onerror?.({})
+  }
+
+  emitMessage(type: string, data: unknown): void {
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener({ data: JSON.stringify(data) })
+    }
+  }
+}
+
+function lastInstance(): FakeEventSource {
+  const inst = FakeEventSource.instances[FakeEventSource.instances.length - 1]
+  if (!inst) throw new Error('no FakeEventSource created')
+  return inst
+}
+
+/** `Array.prototype.at` needs es2022 lib; the project targets es2020 (tsconfig.json). */
+function last<T>(arr: readonly T[]): T | undefined {
+  return arr[arr.length - 1]
+}
+
+beforeEach(() => {
+  FakeEventSource.reset()
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function setup(overrides: Partial<Parameters<typeof createSseConnection>[0]> = {}) {
+  const events: Array<{ type: string; data: unknown }> = []
+  const statuses: ConnectionStatus[] = []
+  const conn = createSseConnection({
+    url: '/events',
+    eventTypes: ['assignment_started', 'board_updated'],
+    onEvent: (type, data) => events.push({ type, data }),
+    onStatusChange: (status) => statuses.push({ ...status }),
+    createEventSource: (url) => new FakeEventSource(url) as unknown as SseHandle,
+    backoffScheduleMs: [100, 200, 400],
+    jitterFraction: 0,
+    now: () => Date.now(),
+    ...overrides,
+  })
+  return { conn, events, statuses }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('createSseConnection', () => {
+  it('opens a socket at the given URL and reports live on open', () => {
+    const { conn, statuses } = setup()
+    conn.start()
+
+    expect(FakeEventSource.instances).toHaveLength(1)
+    expect(lastInstance().url).toBe('/events')
+    expect(last(statuses)).toMatchObject({ state: 'connecting' })
+
+    lastInstance().emitOpen()
+
+    expect(last(statuses)).toMatchObject({ state: 'live', attempt: 0 })
+    expect(last(statuses)?.lastLiveAt).not.toBeNull()
+  })
+
+  it('forwards subscribed events as parsed JSON', () => {
+    const { conn, events } = setup()
+    conn.start()
+    lastInstance().emitOpen()
+
+    lastInstance().emitMessage('assignment_started', { assignment_id: 'w-1' })
+    lastInstance().emitMessage('board_updated', { timestamp: 123 })
+
+    expect(events).toEqual([
+      { type: 'assignment_started', data: { assignment_id: 'w-1' } },
+      { type: 'board_updated', data: { timestamp: 123 } },
+    ])
+  })
+
+  it('goes disconnected -> reconnecting -> live on a drop and recovery', () => {
+    const { conn, statuses } = setup()
+    conn.start()
+    lastInstance().emitOpen()
+    expect(last(statuses)?.state).toBe('live')
+
+    // The stream drops.
+    lastInstance().emitError()
+    expect(last(statuses)).toMatchObject({ state: 'disconnected', attempt: 1 })
+
+    // Backoff timer fires -> a new attempt starts.
+    vi.advanceTimersByTime(200)
+    expect(FakeEventSource.instances).toHaveLength(2)
+    expect(last(statuses)).toMatchObject({ state: 'reconnecting', attempt: 1 })
+
+    // The new socket opens successfully.
+    lastInstance().emitOpen()
+    expect(last(statuses)).toMatchObject({ state: 'live', attempt: 0 })
+  })
+
+  it('uses the backoff schedule and caps at its last entry', () => {
+    const { conn, statuses } = setup()
+    conn.start()
+    lastInstance().emitOpen()
+
+    // Fail three times in a row; each retry should wait the schedule's next
+    // entry (100, 200, 400), and a fourth failure should reuse 400 (the cap).
+    lastInstance().emitError() // attempt 1 scheduled, delay 100
+    vi.advanceTimersByTime(99)
+    expect(FakeEventSource.instances).toHaveLength(1) // not yet retried
+
+    vi.advanceTimersByTime(1)
+    expect(FakeEventSource.instances).toHaveLength(2) // retried at 100ms
+
+    lastInstance().emitError() // attempt 2 scheduled, delay 200
+    vi.advanceTimersByTime(199)
+    expect(FakeEventSource.instances).toHaveLength(2)
+    vi.advanceTimersByTime(1)
+    expect(FakeEventSource.instances).toHaveLength(3)
+
+    lastInstance().emitError() // attempt 3 scheduled, delay 400
+    vi.advanceTimersByTime(400)
+    expect(FakeEventSource.instances).toHaveLength(4)
+
+    lastInstance().emitError() // attempt 4 scheduled, delay capped at 400
+    vi.advanceTimersByTime(400)
+    expect(FakeEventSource.instances).toHaveLength(5)
+
+    expect(last(statuses)?.state).toBe('reconnecting')
+  })
+
+  it('start() is idempotent-safe: a second start() supersedes the first socket', () => {
+    const { conn, statuses } = setup()
+    conn.start()
+    const first = lastInstance()
+
+    conn.start()
+    const second = lastInstance()
+
+    expect(first).not.toBe(second)
+    expect(first.closed).toBe(true)
+
+    // The superseded socket's late callbacks must not affect state.
+    const countBefore = statuses.length
+    first.emitOpen()
+    expect(statuses.length).toBe(countBefore)
+
+    // Only the current socket's events matter.
+    second.emitOpen()
+    expect(last(statuses)).toMatchObject({ state: 'live' })
+  })
+
+  it('stop() closes the socket, cancels pending retries, and silences further callbacks', () => {
+    const { conn, statuses } = setup()
+    conn.start()
+    lastInstance().emitOpen()
+    lastInstance().emitError()
+    expect(last(statuses)?.state).toBe('disconnected')
+
+    conn.stop()
+    expect(lastInstance().closed).toBe(true)
+
+    const countBeforeAdvance = statuses.length
+    vi.advanceTimersByTime(10_000)
+    // No retry socket should have been created, and no further status changes.
+    expect(FakeEventSource.instances).toHaveLength(1)
+    expect(statuses.length).toBe(countBeforeAdvance)
+  })
+
+  it('resets intent/backoff state on every start(), mirroring the StrictMode double-mount replay', () => {
+    const { conn, statuses } = setup()
+
+    // Mount -> effect -> cleanup -> mount, exactly as StrictMode replays in dev.
+    conn.start()
+    conn.stop()
+    conn.start()
+
+    expect(FakeEventSource.instances).toHaveLength(2)
+    expect(FakeEventSource.instances[0].closed).toBe(true)
+
+    // The live connection is the second socket; opening it must report
+    // attempt 0 -- proof that stop()+start() didn't leak stale backoff state.
+    lastInstance().emitOpen()
+    expect(last(statuses)).toMatchObject({ state: 'live', attempt: 0 })
+  })
+
+  it('treats a synchronously-throwing EventSource factory as a failed attempt', () => {
+    let calls = 0
+    const statusesFor: ConnectionStatus[] = []
+    const conn = createSseConnection({
+      url: '/events',
+      eventTypes: [],
+      onEvent: () => {},
+      onStatusChange: (s) => statusesFor.push({ ...s }),
+      createEventSource: () => {
+        calls += 1
+        if (calls === 1) throw new Error('boom')
+        return new FakeEventSource('/events') as unknown as SseHandle
+      },
+      backoffScheduleMs: [50],
+      jitterFraction: 0,
+    })
+
+    conn.start()
+    expect(last(statusesFor)?.state).toBe('disconnected')
+
+    vi.advanceTimersByTime(50)
+    expect(calls).toBe(2)
+  })
+})