Merge pull request #568 from Chris0Jeky/fix/510-board-list-polling

fix: throttle board list polling (#510)

Author: Chris0Jeky

frontend/taskdeck-web/src/composables/useBoardRealtime.ts

@@ -11,7 +11,12 @@ import { getToken } from '../utils/tokenStorage'
 const BOARD_MUTATION_EVENT = 'boardMutation'
 const BOARD_PRESENCE_EVENT = 'boardPresence'
 const RECONNECT_DELAYS_MS = [0, 2000, 5000, 10000]
-const FALLBACK_POLL_INTERVAL_MS = 15000
+const FALLBACK_POLL_INTERVAL_MS = 30000
+// Coalesce rapid burst events so the board is not re-fetched on every
+// individual mutation when multiple events arrive in quick succession (e.g.
+// bulk import, automation runs).  300 ms is imperceptible to users but
+// prevents the ~3 req/s thrash observed with rapid SignalR event bursts.
+const MUTATION_DEBOUNCE_MS = 300
 
 function resolveHubUrl(): string {
   const apiBase = import.meta.env.VITE_API_BASE_URL || 'http://localhost:5000/api'
@@ -43,6 +48,7 @@ export function createBoardRealtimeController(
   let editingCardId: string | null = null
   let fallbackTimer: ReturnType<typeof setInterval> | null = null
   let refreshInFlight = false
+  let mutationDebounceTimer: ReturnType<typeof setTimeout> | null = null
 
   const stopFallbackPolling = () => {
     if (!fallbackTimer) {
@@ -62,17 +68,36 @@ export function createBoardRealtimeController(
     }, FALLBACK_POLL_INTERVAL_MS)
   }
 
-  const handleBoardMutation = async (event: BoardRealtimeEvent) => {
-    if (!subscribedBoardId || event.boardId !== subscribedBoardId || refreshInFlight) {
-      return
+  const cancelMutationDebounce = () => {
+    if (mutationDebounceTimer !== null) {
+      clearTimeout(mutationDebounceTimer)
+      mutationDebounceTimer = null
     }
+  }
 
-    refreshInFlight = true
-    try {
-      await options.fetchBoard(subscribedBoardId)
-    } finally {
-      refreshInFlight = false
+  const handleBoardMutation = (event: BoardRealtimeEvent) => {
+    if (!subscribedBoardId || event.boardId !== subscribedBoardId) {
+      return
     }
+
+    // Debounce: cancel any pending refresh scheduled by a prior burst event.
+    cancelMutationDebounce()
+
+    mutationDebounceTimer = setTimeout(() => {
+      mutationDebounceTimer = null
+
+      // Skip if a refresh is already in-flight (started by a previous debounced
+      // call that hasn't resolved yet).
+      if (refreshInFlight || !subscribedBoardId) {
+        return
+      }
+
+      const boardId = subscribedBoardId
+      refreshInFlight = true
+      void options.fetchBoard(boardId).finally(() => {
+        refreshInFlight = false
+      })
+    }, MUTATION_DEBOUNCE_MS)
   }
 
   const handleBoardPresence = (snapshot: BoardPresenceSnapshot) => {
@@ -124,6 +149,10 @@ export function createBoardRealtimeController(
   }
 
   const joinBoard = async (boardId: string) => {
+    // Cancel any debounced mutation fetch from the previous board so it cannot
+    // fire against the newly-subscribed boardId after subscribedBoardId changes.
+    cancelMutationDebounce()
+
     const hubConnection = ensureConnection()
 
     if (hubConnection.state === HubConnectionState.Disconnected) {
@@ -166,6 +195,7 @@ export function createBoardRealtimeController(
 
   const stop = async () => {
     stopFallbackPolling()
+    cancelMutationDebounce()
     editingCardId = null
 
     if (!connection) {

frontend/taskdeck-web/src/store/board/boardCrudStore.ts

@@ -7,8 +7,21 @@ import type { CreateBoardDto, UpdateBoardDto } from '../../types/board'
 import type { BoardState } from './boardState'
 import type { BoardHelpers } from './boardStoreHelpers'
 
+// Minimum gap between board-list fetches.  Multiple views (BoardsListView,
+// ActivityView, ReviewView, etc.) can call fetchBoards on mount in quick
+// succession; the throttle guard prevents duplicate network round-trips.
+const FETCH_BOARDS_THROTTLE_MS = 5000
+
 export function createBoardCrudActions(state: BoardState, helpers: BoardHelpers) {
+  let lastFetchBoardsAt = 0
+
   async function fetchBoards(search?: string, includeArchived = false) {
+    const now = Date.now()
+    // Allow forced refreshes (search/archive filter changes) to bypass throttle.
+    const isFilteredRequest = !!search || includeArchived
+    if (!isFilteredRequest && now - lastFetchBoardsAt < FETCH_BOARDS_THROTTLE_MS) {
+      return
+    }
     if (helpers.isDemoMode) {
       state.loading.value = true
       state.error.value = null
@@ -21,6 +34,7 @@ export function createBoardCrudActions(state: BoardState, helpers: BoardHelpers)
       state.loading.value = true
       state.error.value = null
       const freshBoards = await boardsApi.getBoards(search, includeArchived)
+      lastFetchBoardsAt = Date.now()
       state.boards.value = freshBoards
 
       // Preserve selection guard: only update activeBoardId if there is no

frontend/taskdeck-web/src/tests/composables/useBoardRealtime.spec.ts

@@ -120,23 +120,57 @@ describe('createBoardRealtimeController', () => {
   })
 
   it('refreshes board when matching board mutation event arrives', async () => {
+    vi.useFakeTimers()
     const fetchBoard = vi.fn(async () => undefined)
     const controller = createBoardRealtimeController({ fetchBoard })
 
     await controller.start('board-1')
-    await callbacks.boardMutation?.({ boardId: 'board-1' })
+    callbacks.boardMutation?.({ boardId: 'board-1' })
+
+    // The handler debounces the refresh — advance past the debounce window.
+    await vi.advanceTimersByTimeAsync(300)
 
     expect(fetchBoard).toHaveBeenCalledWith('board-1')
+    vi.useRealTimers()
   })
 
   it('ignores mutation events for other boards', async () => {
+    vi.useFakeTimers()
+    const fetchBoard = vi.fn(async () => undefined)
+    const controller = createBoardRealtimeController({ fetchBoard })
+
+    await controller.start('board-1')
+    callbacks.boardMutation?.({ boardId: 'board-2' })
+
+    // Advance past the debounce window to confirm nothing fires.
+    await vi.advanceTimersByTimeAsync(300)
+
+    expect(fetchBoard).not.toHaveBeenCalled()
+    vi.useRealTimers()
+  })
+
+  it('coalesces rapid burst mutation events into a single fetchBoard call', async () => {
+    vi.useFakeTimers()
     const fetchBoard = vi.fn(async () => undefined)
     const controller = createBoardRealtimeController({ fetchBoard })
 
     await controller.start('board-1')
-    await callbacks.boardMutation?.({ boardId: 'board-2' })
 
+    // Fire three mutation events in rapid succession (within the debounce window).
+    callbacks.boardMutation?.({ boardId: 'board-1' })
+    callbacks.boardMutation?.({ boardId: 'board-1' })
+    callbacks.boardMutation?.({ boardId: 'board-1' })
+
+    // Before the debounce window closes, fetchBoard should not have been called.
     expect(fetchBoard).not.toHaveBeenCalled()
+
+    // Advance past the debounce — only one fetch should fire for the burst.
+    await vi.advanceTimersByTimeAsync(300)
+    expect(fetchBoard).toHaveBeenCalledTimes(1)
+    expect(fetchBoard).toHaveBeenCalledWith('board-1')
+
+    vi.useRealTimers()
+    await controller.stop()
   })
 
   it('emits presence snapshots for the currently subscribed board', async () => {
@@ -175,6 +209,30 @@ describe('createBoardRealtimeController', () => {
     expect(mockConnection.invoke).toHaveBeenCalledWith('JoinBoard', 'board-2')
   })
 
+  it('cancels a pending debounce timer when switching boards', async () => {
+    // Regression: a board-A mutation event with a debounce timer pending must
+    // not fire fetchBoard after subscribedBoardId has advanced to board-B.
+    vi.useFakeTimers()
+    const fetchBoard = vi.fn(async () => undefined)
+    const controller = createBoardRealtimeController({ fetchBoard })
+
+    await controller.start('board-1')
+
+    // A mutation event for board-1 starts the 300 ms debounce timer.
+    callbacks.boardMutation?.({ boardId: 'board-1' })
+
+    // Switch to board-2 before the timer fires — must discard the pending timer.
+    await controller.switchBoard('board-2')
+
+    // Advance past the original debounce window.
+    await vi.advanceTimersByTimeAsync(300)
+
+    // fetchBoard must not have been called at all; the stale timer was cancelled.
+    expect(fetchBoard).not.toHaveBeenCalled()
+
+    await controller.stop()
+  })
+
   it('falls back to polling when websocket connection cannot start', async () => {
     vi.useFakeTimers()
     const fetchBoard = vi.fn(async () => undefined)
@@ -183,7 +241,7 @@ describe('createBoardRealtimeController', () => {
     const controller = createBoardRealtimeController({ fetchBoard })
     await controller.start('board-1')
 
-    await vi.advanceTimersByTimeAsync(15000)
+    await vi.advanceTimersByTimeAsync(30000)
     expect(fetchBoard).toHaveBeenCalledWith('board-1')
 
     await controller.stop()
@@ -207,15 +265,15 @@ describe('createBoardRealtimeController', () => {
     await controller.start('board-1')
     await controller.setEditingCard('card-1')
     await callbacks.reconnecting?.()
-    await vi.advanceTimersByTimeAsync(15000)
+    await vi.advanceTimersByTimeAsync(30000)
     expect(fetchBoard).toHaveBeenCalledWith('board-1')
 
     fetchBoard.mockClear()
     await callbacks.reconnected?.()
     expect(mockConnection.invoke).toHaveBeenCalledWith('JoinBoard', 'board-1')
     expect(mockConnection.invoke).toHaveBeenCalledWith('SetEditingCard', 'board-1', 'card-1')
 
-    await vi.advanceTimersByTimeAsync(15000)
+    await vi.advanceTimersByTimeAsync(30000)
     expect(fetchBoard).not.toHaveBeenCalled()
 
     await controller.stop()

frontend/taskdeck-web/src/tests/store/boardStore.spec.ts

@@ -729,6 +729,7 @@ describe('boardStore', () => {
     })
 
     it('preserves activeBoardId across fetchBoards when selected board still exists', async () => {
+      vi.useFakeTimers()
       // First load — sets selection to boardA (first item)
       vi.mocked(boardsApi.getBoards).mockResolvedValue([boardA, boardB])
       await store.fetchBoards()
@@ -737,35 +738,49 @@ describe('boardStore', () => {
       // User selects boardB
       store.activeBoardId = 'board-b'
 
+      // Advance past throttle window so the next fetchBoards is not suppressed.
+      vi.advanceTimersByTime(6000)
+
       // Poll cycle returns boards in a different order — boardB is still present
       vi.mocked(boardsApi.getBoards).mockResolvedValue([boardB, boardA])
       await store.fetchBoards()
 
       // Selection must NOT flip back to boardB (now first) or boardA
       expect(store.activeBoardId).toBe('board-b')
+      vi.useRealTimers()
     })
 
     it('falls back to first board when the selected board is removed from the list', async () => {
+      vi.useFakeTimers()
       vi.mocked(boardsApi.getBoards).mockResolvedValue([boardA, boardB])
       await store.fetchBoards()
       store.activeBoardId = 'board-b'
 
+      // Advance past throttle window so the next fetchBoards is not suppressed.
+      vi.advanceTimersByTime(6000)
+
       // boardB has been deleted on the server
       vi.mocked(boardsApi.getBoards).mockResolvedValue([boardA])
       await store.fetchBoards()
 
       expect(store.activeBoardId).toBe('board-a')
+      vi.useRealTimers()
     })
 
     it('sets activeBoardId to null when no boards remain after refresh', async () => {
+      vi.useFakeTimers()
       vi.mocked(boardsApi.getBoards).mockResolvedValue([boardA])
       await store.fetchBoards()
       store.activeBoardId = 'board-a'
 
+      // Advance past throttle window so the next fetchBoards is not suppressed.
+      vi.advanceTimersByTime(6000)
+
       vi.mocked(boardsApi.getBoards).mockResolvedValue([])
       await store.fetchBoards()
 
       expect(store.activeBoardId).toBeNull()
+      vi.useRealTimers()
     })
 
     it('clears activeBoardId when the active board is deleted', async () => {