canopy-ui 0.6.2 → 0.7.0

package/src/presence/pageKey.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { pageKeyFor, type RouteRule } from './pageKey'
+
+const ACE_RULES: RouteRule[] = [
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)\/steps\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: m[4] }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: 'run overview' }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/activity/,
+    build: (m) => ({ workspace: m[1], resource: 'activity', subLocation: 'Activity' }),
+  },
+]
+
+describe('pageKeyFor', () => {
+  it('collapses every step of a run onto one key, keeping the step as sub-location', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001/steps/idea-to-pdd', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    expect(a?.pageKey).toBe('ace:dimagi-team:opp:bednet/run-001')
+    expect(b?.pageKey).toBe(a?.pageKey)
+    expect(a?.subLocation).toBe('idea-to-pdd')
+    expect(b?.subLocation).toBe('run overview')
+  })
+
+  it('keeps different runs of the same opp on different keys', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-002', ACE_RULES)
+    expect(a?.pageKey).not.toBe(b?.pageKey)
+  })
+
+  it('namespaces by app so two apps never collide', () => {
+    const ace = pageKeyFor('ace', '/w/dimagi-team/activity', ACE_RULES)
+    const canopy = pageKeyFor('canopy', '/w/dimagi-team/activity', ACE_RULES)
+    expect(ace?.pageKey).toBe('ace:dimagi-team:activity')
+    expect(canopy?.pageKey).toBe('canopy:dimagi-team:activity')
+  })
+
+  it('returns null for unmatched routes rather than a catch-all key', () => {
+    expect(pageKeyFor('ace', '/totally/unknown', ACE_RULES)).toBeNull()
+  })
+
+  it('is order-sensitive: the first matching rule wins', () => {
+    const loose: RouteRule[] = [
+      { pattern: /^\/w\/([^/]+)\/opps/, build: (m) => ({ workspace: m[1], resource: 'opps', subLocation: 'Opps' }) },
+      ...ACE_RULES,
+    ]
+    expect(pageKeyFor('ace', '/w/x/opps/bednet/runs/run-001', loose)?.pageKey).toBe('ace:x:opps')
+  })
+})

package/src/presence/pageKey.ts

@@ -0,0 +1,37 @@
+/** A resolved presence location: which roster to join, and where in it you are. */
+export interface PageLocation {
+  /** `<app>:<workspace|global>:<resource>` — the roster identity. */
+  pageKey: string
+  /** Human-readable position within the resource, for the expanded panel. */
+  subLocation: string
+}
+
+export interface RouteRule {
+  pattern: RegExp
+  build: (m: RegExpMatchArray) => { workspace: string; resource: string; subLocation: string }
+}
+
+/**
+ * Resolve a pathname to a presence location. Pure — the single place
+ * grouping correctness lives.
+ *
+ * Rules are evaluated in order and the first match wins, so more specific
+ * patterns must be listed before looser ones.
+ *
+ * Returns null when nothing matches. Callers render no badge in that case;
+ * grouping every unrecognised route under one catch-all key would put
+ * unrelated strangers in the same roster.
+ */
+export function pageKeyFor(
+  app: string,
+  pathname: string,
+  rules: RouteRule[],
+): PageLocation | null {
+  for (const rule of rules) {
+    const m = pathname.match(rule.pattern)
+    if (!m) continue
+    const { workspace, resource, subLocation } = rule.build(m)
+    return { pageKey: `${app}:${workspace}:${resource}`, subLocation }
+  }
+  return null
+}

package/src/presence/usePresence.test.ts

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { usePresence } from './usePresence'
+
+class FakeSocket {
+  static last: FakeSocket | null = null
+  static created = 0
+  static OPEN = 1
+  readyState = 0
+  sent: string[] = []
+  onopen: (() => void) | null = null
+  onmessage: ((e: { data: string }) => void) | null = null
+  onclose: (() => void) | null = null
+  constructor(public url: string) {
+    FakeSocket.last = this
+    FakeSocket.created += 1
+  }
+  send(frame: string) {
+    this.sent.push(frame)
+  }
+  close() {
+    this.readyState = 3
+  }
+  open() {
+    this.readyState = FakeSocket.OPEN
+    this.onopen?.()
+  }
+  deliver(payload: unknown) {
+    this.onmessage?.({ data: JSON.stringify(payload) })
+  }
+}
+
+beforeEach(() => {
+  vi.stubGlobal('WebSocket', FakeSocket as unknown as typeof WebSocket)
+  vi.useFakeTimers()
+  FakeSocket.created = 0
+})
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+  FakeSocket.last = null
+})
+
+const LOC = { pageKey: 'ace:ws:opp:a/run-001', subLocation: 'run overview' }
+
+describe('usePresence', () => {
+  it('sends presence.enter once the socket opens', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    expect(JSON.parse(FakeSocket.last!.sent[0])).toEqual({
+      type: 'presence.enter',
+      page_key: LOC.pageKey,
+      sub_location: LOC.subLocation,
+    })
+  })
+
+  it('exposes the roster the server broadcasts', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: {
+          page_key: LOC.pageKey,
+          viewers: [{ email: 'a@x.com', name: 'A', sub_location: 'idea-to-pdd', idle: false, self: true }],
+        },
+      }),
+    )
+    expect(result.current.viewers).toEqual([
+      { email: 'a@x.com', name: 'A', subLocation: 'idea-to-pdd', idle: false, self: true },
+    ])
+  })
+
+  it('ignores a roster for a page key it is no longer on', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: { page_key: 'ace:ws:opp:STALE/run-999', viewers: [
+          { email: 'z@x.com', name: 'Z', sub_location: '', idle: false, self: false }] },
+      }),
+    )
+    expect(result.current.viewers).toEqual([])
+  })
+
+  it('re-enters without reconnecting when the location changes', () => {
+    const { rerender } = renderHook(
+      ({ location }) => usePresence({ url: 'ws://x/ws/presence/', location }),
+      { initialProps: { location: LOC } },
+    )
+    act(() => FakeSocket.last!.open())
+    const socket = FakeSocket.last!
+    rerender({ location: { pageKey: 'ace:ws:activity', subLocation: 'Activity' } })
+    expect(FakeSocket.last).toBe(socket) // same socket, no reconnect
+    expect(JSON.parse(socket.sent[socket.sent.length - 1])).toEqual({
+      type: 'presence.enter',
+      page_key: 'ace:ws:activity',
+      sub_location: 'Activity',
+    })
+  })
+
+  it('heartbeats every 20 seconds', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() => void vi.advanceTimersByTime(20_000))
+    expect(JSON.parse(FakeSocket.last!.sent[1])).toEqual({ type: 'presence.heartbeat', idle: false })
+  })
+
+  it('clears the roster and sends nothing when there is no location', () => {
+    const { result } = renderHook(() =>
+      usePresence({ url: 'ws://x/ws/presence/', location: null }),
+    )
+    expect(result.current.viewers).toEqual([])
+    expect(FakeSocket.last).toBeNull()
+  })
+
+  it('backs off exponentially while reconnects keep failing, up to a ceiling', () => {
+    // A tab left open past session expiry is closed with 4001 on every
+    // attempt. A flat retry hammers a handshake every 2s forever; the delay
+    // must grow and then cap.
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    expect(FakeSocket.created).toBe(1)
+
+    const failOnce = (expectedDelay: number) => {
+      const before = FakeSocket.created
+      act(() => FakeSocket.last!.onclose!())
+      // Nothing reconnects a millisecond early...
+      act(() => void vi.advanceTimersByTime(expectedDelay - 1))
+      expect(FakeSocket.created).toBe(before)
+      // ...and exactly one reconnect lands on the deadline.
+      act(() => void vi.advanceTimersByTime(1))
+      expect(FakeSocket.created).toBe(before + 1)
+    }
+
+    failOnce(2_000)
+    failOnce(4_000)
+    failOnce(8_000)
+    failOnce(16_000)
+    failOnce(32_000)
+    failOnce(60_000) // ceiling, not 64_000
+    failOnce(60_000) // and it stays there
+  })
+
+  it('resets the backoff once a socket actually opens', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(2_000))
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(4_000)) // now at a 4s delay
+
+    act(() => FakeSocket.last!.open()) // a good connection clears the streak
+
+    const before = FakeSocket.created
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(2_000))
+    expect(FakeSocket.created).toBe(before + 1)
+  })
+
+  it('clears the previous page\'s viewers on navigation even when the socket is not open', () => {
+    // Otherwise the old page's avatars linger on the new page until a roster
+    // for it arrives — which, on a dead socket, may be never.
+    const { result, rerender } = renderHook(
+      ({ location }) => usePresence({ url: 'ws://x/ws/presence/', location }),
+      { initialProps: { location: LOC } },
+    )
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: {
+          page_key: LOC.pageKey,
+          viewers: [{ email: 'a@x.com', name: 'A', sub_location: '', idle: false, self: false }],
+        },
+      }),
+    )
+    expect(result.current.viewers).toHaveLength(1)
+
+    FakeSocket.last!.readyState = 3 // socket dropped, reconnect pending
+    rerender({ location: { pageKey: 'ace:ws:activity', subLocation: 'Activity' } })
+    expect(result.current.viewers).toEqual([])
+  })
+
+  it('swallows a synchronous WebSocket constructor throw and stays on an empty roster', () => {
+    class ThrowingSocket {
+      constructor() {
+        throw new Error('mixed content: refused to connect to insecure WebSocket')
+      }
+    }
+    vi.stubGlobal('WebSocket', ThrowingSocket as unknown as typeof WebSocket)
+
+    let hook!: ReturnType<typeof renderHook<{ viewers: unknown[] }, void>>
+    expect(() => {
+      hook = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    }).not.toThrow()
+    expect(hook.result.current.viewers).toEqual([])
+  })
+})

package/src/presence/usePresence.ts

@@ -0,0 +1,188 @@
+import { useEffect, useRef, useState } from 'react'
+import type { PageLocation } from './pageKey'
+
+export interface Viewer {
+  email: string
+  name: string
+  subLocation: string
+  idle: boolean
+  self: boolean
+}
+
+export interface UsePresenceOptions {
+  url: string
+  location: PageLocation | null
+}
+
+const HEARTBEAT_MS = 20_000
+const IDLE_AFTER_MS = 120_000
+// Reconnect backoff. A flat retry is wrong for the permanent-failure case:
+// a tab left open past session expiry is closed with 4001 on every attempt,
+// so a flat 2s retry hammers a handshake forever. Double up to a ceiling and
+// reset on a socket that actually opens.
+const RECONNECT_BASE_MS = 2_000
+const RECONNECT_MAX_MS = 60_000
+
+/**
+ * One presence socket per tab.
+ *
+ * Navigation re-keys the existing connection with a fresh `presence.enter`
+ * rather than reconnecting — a socket per page would churn handshakes on
+ * every click.
+ *
+ * Every failure path degrades to an empty roster. Presence is an
+ * enhancement; it must never surface an error to the user.
+ */
+export function usePresence({ url, location }: UsePresenceOptions): { viewers: Viewer[] } {
+  const [viewers, setViewers] = useState<Viewer[]>([])
+  const wsRef = useRef<WebSocket | null>(null)
+  const locationRef = useRef(location)
+  const idleRef = useRef(false)
+  locationRef.current = location
+
+  // Socket lifecycle. Deliberately NOT keyed on `location` — the socket
+  // outlives navigation.
+  useEffect(() => {
+    if (!location) {
+      setViewers([])
+      return
+    }
+    let closedByCleanup = false
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+    let heartbeat: ReturnType<typeof setInterval> | null = null
+    let reconnectDelay = RECONNECT_BASE_MS
+
+    const scheduleReconnect = () => {
+      if (closedByCleanup) return
+      reconnectTimer = setTimeout(open, reconnectDelay)
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS)
+    }
+
+    const send = (frame: unknown) => {
+      const ws = wsRef.current
+      if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(frame))
+    }
+
+    const enter = () => {
+      const loc = locationRef.current
+      if (loc) send({ type: 'presence.enter', page_key: loc.pageKey, sub_location: loc.subLocation })
+    }
+
+    function open() {
+      let sock: WebSocket
+      try {
+        sock = new WebSocket(url)
+      } catch {
+        // Synchronous construction failure (malformed URL, mixed-content
+        // scheme mismatch, …): treat exactly like any other connection
+        // failure — stay on the empty roster and retry on the normal
+        // reconnect cadence, never propagate.
+        setViewers([])
+        scheduleReconnect()
+        return
+      }
+      wsRef.current = sock
+      sock.onopen = () => {
+        // A socket that actually opened means the failure that got us here
+        // is over; start the next backoff series from the bottom.
+        reconnectDelay = RECONNECT_BASE_MS
+        enter()
+        heartbeat = setInterval(
+          () => send({ type: 'presence.heartbeat', idle: idleRef.current }),
+          HEARTBEAT_MS,
+        )
+      }
+      sock.onmessage = (e) => {
+        try {
+          const msg = JSON.parse(e.data)
+          if (msg.event !== 'presence.roster') return
+          // Drop rosters for a page we have already navigated away from —
+          // an in-flight broadcast can land after the re-key.
+          if (msg.data?.page_key !== locationRef.current?.pageKey) return
+          setViewers(
+            (msg.data.viewers ?? []).map((v: Record<string, unknown>) => ({
+              email: String(v.email ?? ''),
+              name: String(v.name ?? ''),
+              subLocation: String(v.sub_location ?? ''),
+              idle: Boolean(v.idle),
+              self: Boolean(v.self),
+            })),
+          )
+        } catch {
+          // Malformed frame: ignore. Never surface.
+        }
+      }
+      sock.onclose = () => {
+        if (wsRef.current === sock) wsRef.current = null
+        if (heartbeat) clearInterval(heartbeat)
+        setViewers([])
+        scheduleReconnect()
+      }
+    }
+    open()
+
+    return () => {
+      closedByCleanup = true
+      if (reconnectTimer) clearTimeout(reconnectTimer)
+      if (heartbeat) clearInterval(heartbeat)
+      wsRef.current?.close()
+      wsRef.current = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url, location === null])
+
+  // Re-key on navigation. Deps are the primitive fields, not `location`
+  // itself — callers (e.g. pageKeyFor) may return a fresh object each
+  // render, and keying on identity would re-send presence.enter on every
+  // render instead of only on an actual location change.
+  useEffect(() => {
+    // Clear FIRST, unconditionally. If the socket is not open yet the old
+    // page's avatars are already wrong — leaving them up until a roster for
+    // the new page arrives (which, on a dead socket, may be never) shows
+    // strangers as viewing the page you just navigated to.
+    setViewers([])
+    const ws = wsRef.current
+    if (!location || !ws || ws.readyState !== WebSocket.OPEN) return
+    ws.send(
+      JSON.stringify({
+        type: 'presence.enter',
+        page_key: location.pageKey,
+        sub_location: location.subLocation,
+      }),
+    )
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location?.pageKey, location?.subLocation])
+
+  // Idle tracking: hidden for longer than IDLE_AFTER_MS. Reports an
+  // observable fact (the tab is not frontmost), never an attention claim.
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const flush = () => {
+      const ws = wsRef.current
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'presence.heartbeat', idle: idleRef.current }))
+      }
+    }
+    const onVisibility = () => {
+      if (document.hidden) {
+        timer = setTimeout(() => {
+          idleRef.current = true
+          flush()
+        }, IDLE_AFTER_MS)
+      } else {
+        if (timer) clearTimeout(timer)
+        if (idleRef.current) {
+          idleRef.current = false
+          flush()
+        }
+      }
+    }
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      if (timer) clearTimeout(timer)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [])
+
+  return { viewers }
+}