feat(hooks): make useBluetoothHRM data liveness timeout configurable (#1536)

* feat(hooks): make `useBluetoothHRM` data liveness timeout configurable

This change addresses the feedback from PR #1438 by making the `DATA_LIVENESS_TIMEOUT_MS` in the `useBluetoothHRM` hook configurable.

The hook now accepts an optional `dataLivenessTimeoutMs` parameter, defaulting to the previous hardcoded value of 10 seconds for backward compatibility.

A new `disconnectionReason` state has been added to the hook's return value to provide more granular feedback on the connection status. The UI has been updated to display more informative messages based on this reason.

Additionally, a comprehensive suite of unit tests has been added for the `useBluetoothHRM` hook to verify the new functionality and prevent future regressions.

* fix(tests): resolve linting error in useBluetoothHRM test

This commit fixes a linting error in `tests/unit/useBluetoothHRM.test.ts` by replacing an `any` type with a more specific type inferred from the `useBluetoothHRM` hook's return value.

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

app/client/connect/page.tsx

@@ -20,10 +20,18 @@ export default function ConnectPage() {
     batteryLevel,
     isConnected,
     isSupported,
+    disconnectionReason,
   } = useBluetoothHRM()
 
   const { connectionStatus, hrmData } = useWebSocket()
 
+  let deviceStatusMessage = deviceStatus
+  if (disconnectionReason === 'timeout') {
+    deviceStatusMessage = 'Connection unstable. Trying to reconnect...'
+  } else if (disconnectionReason === 'signal_loss') {
+    deviceStatusMessage = 'Signal lost. Trying to reconnect...'
+  }
+
   const handleConnect = () => {
     const age = userAge ? parseInt(userAge, 10) : 0
     connectAndStream(userName, age)
@@ -56,7 +64,7 @@ export default function ConnectPage() {
       userAge={userAge}
       setUserAge={setUserAge}
       isConnected={isConnected}
-      deviceStatus={deviceStatus}
+      deviceStatus={deviceStatusMessage}
       batteryLevel={batteryLevel}
       onConnect={handleConnect}
       onDisconnect={disconnect}

hooks/useBluetoothHRM.ts

@@ -56,9 +56,18 @@ const withTimeout = <T>(
   })
 }
 
-const useBluetoothHRM = () => {
+interface UseBluetoothHRMProps {
+  dataLivenessTimeoutMs?: number
+}
+
+type DisconnectionReason = 'manual' | 'timeout' | 'signal_loss' | null
+
+const useBluetoothHRM = (props: UseBluetoothHRMProps = {}) => {
+  const { dataLivenessTimeoutMs = 10000 } = props
   const { sendData, connectionStatus } = useWebSocket()
   const [deviceStatus, setDeviceStatus] = useState('Disconnected')
+  const [disconnectionReason, setDisconnectionReason] =
+    useState<DisconnectionReason>(null)
   const [savedDevice, setSavedDevice] = useState<BluetoothDevice | null>(null)
   const [batteryLevel, setBatteryLevel] = useState<number | null>(null)
   const [isSupported] = useState(
@@ -90,24 +99,29 @@ const useBluetoothHRM = () => {
 
   // Watchdog for stale data
   useEffect(() => {
+    // A timeout of 0 disables the watchdog
+    if (!dataLivenessTimeoutMs) return
+
     const interval = setInterval(() => {
       if (
         statusRef.current.startsWith('Connected') &&
         lastDataTime.current > 0
       ) {
-        if (Date.now() - lastDataTime.current > 10000) {
+        if (Date.now() - lastDataTime.current > dataLivenessTimeoutMs) {
           console.warn('Bluetooth data stale. Forcing reconnection...')
+          setDisconnectionReason('timeout')
           setDeviceStatus('Connection unstable. Reconnecting...')
           if (deviceRef.current?.gatt?.connected)
             deviceRef.current.gatt.disconnect()
         }
       }
-    }, 2000)
+    }, 2000) // Check every 2s
     return () => clearInterval(interval)
-  }, [])
+  }, [dataLivenessTimeoutMs])
 
   const disconnect = useCallback(() => {
     isManualDisconnect.current = true
+    setDisconnectionReason('manual')
     if (reconnectTimeoutRef.current) clearTimeout(reconnectTimeoutRef.current)
     if (deviceRef.current?.gatt?.connected) deviceRef.current.gatt.disconnect()
 
@@ -162,6 +176,7 @@ const useBluetoothHRM = () => {
     setBatteryLevel(null)
     if (!isManualDisconnect.current && deviceRef.current) {
       console.log('Attempting auto-reconnect...')
+      setDisconnectionReason('signal_loss')
       setDeviceStatus('Signal Lost. Retrying...')
       const deviceToReconnect = deviceRef.current
       reconnectTimeoutRef.current = setTimeout(() => {
@@ -250,6 +265,7 @@ const useBluetoothHRM = () => {
         setSavedDevice(device)
         setCookie('hrm_device_id', device.id)
         isManualDisconnect.current = false
+        setDisconnectionReason(null)
         return true
       } catch (error) {
         console.error('GATT Connection failed:', error)
@@ -333,6 +349,7 @@ const useBluetoothHRM = () => {
     batteryLevel,
     isConnected: deviceStatus.startsWith('Connected'),
     isSupported, // Export this flag
+    disconnectionReason,
   }
 }
 

tests/unit/useBluetoothHRM.test.ts

@@ -0,0 +1,229 @@
+/**
+ * @jest-environment jsdom
+ */
+import { renderHook, act } from '@testing-library/react'
+import useBluetoothHRM from '@/hooks/useBluetoothHRM'
+import { useWebSocket } from '@/context/WebSocketContext'
+
+// Mock the WebSocket context
+jest.mock('@/context/WebSocketContext', () => ({
+  useWebSocket: jest.fn(),
+}))
+
+// Mock navigator.bluetooth
+const mockBluetooth = {
+  requestDevice: jest.fn(),
+  getDevices: jest.fn(),
+}
+Object.defineProperty(navigator, 'bluetooth', {
+  value: mockBluetooth,
+  writable: true,
+})
+
+describe('useBluetoothHRM', () => {
+  let mockSendData: jest.Mock
+  let mockCharacteristic: {
+    startNotifications: jest.Mock
+    addEventListener: jest.Mock
+    removeEventListener: jest.Mock
+  }
+  let mockGattServer: {
+    connect: jest.Mock
+    disconnect: jest.Mock
+    getPrimaryService: jest.Mock
+  }
+  let mockDevice: {
+    id: string
+    name: string
+    gatt: {
+      connected: boolean
+      connect: jest.Mock
+      disconnect: jest.Mock
+    }
+    addEventListener: jest.Mock
+    removeEventListener: jest.Mock
+  }
+
+  beforeEach(() => {
+    jest.useFakeTimers()
+    mockSendData = jest.fn()
+    ;(useWebSocket as jest.Mock).mockReturnValue({
+      sendData: mockSendData,
+      connectionStatus: 'Connected',
+    })
+
+    mockCharacteristic = {
+      startNotifications: jest.fn().mockResolvedValue(undefined),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+    }
+    const mockService = {
+      getCharacteristic: jest.fn().mockResolvedValue(mockCharacteristic),
+    }
+    mockGattServer = {
+      connect: jest.fn().mockResolvedValue({
+        getPrimaryService: jest.fn().mockResolvedValue(mockService),
+      }),
+      disconnect: jest.fn(),
+      getPrimaryService: jest.fn().mockResolvedValue(mockService),
+    }
+
+    mockDevice = {
+      id: 'test-device-id',
+      name: 'Test HRM',
+      gatt: {
+        connected: false,
+        connect: jest.fn().mockResolvedValue(mockGattServer),
+        disconnect: jest.fn(),
+      },
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+    }
+
+    mockBluetooth.requestDevice.mockResolvedValue(mockDevice)
+    mockBluetooth.getDevices.mockResolvedValue([])
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+    jest.clearAllMocks()
+  })
+
+  type UseBluetoothHRMReturn = ReturnType<typeof useBluetoothHRM>
+
+  const simulateConnection = async (hook: {
+    result: { current: UseBluetoothHRMReturn }
+  }) => {
+    await act(async () => {
+      hook.result.current.connectAndStream('Test User', 30)
+      await Promise.resolve() // Allow promises to resolve
+    })
+    // Simulate gatt connected state
+    Object.defineProperty(mockDevice.gatt, 'connected', {
+      value: true,
+      writable: true,
+    })
+  }
+
+  it('should use default timeout of 10 seconds and trigger reconnect', async () => {
+    const { result } = renderHook(() => useBluetoothHRM())
+
+    await simulateConnection({ result })
+    expect(result.current.isConnected).toBe(true)
+
+    // Advance time past the 10s timeout to the next 2s interval check
+    act(() => {
+      jest.advanceTimersByTime(12000)
+    })
+
+    expect(result.current.deviceStatus).toContain('Connection unstable')
+    expect(result.current.disconnectionReason).toBe('timeout')
+    expect(mockDevice.gatt.disconnect).toHaveBeenCalled()
+  })
+
+  it('should use custom timeout from props', async () => {
+    const { result } = renderHook(() =>
+      useBluetoothHRM({ dataLivenessTimeoutMs: 5000 })
+    )
+    await simulateConnection({ result })
+    expect(result.current.isConnected).toBe(true)
+
+    // Advance time by 4 seconds (less than timeout)
+    act(() => {
+      jest.advanceTimersByTime(4000)
+    })
+    expect(result.current.deviceStatus).not.toContain('Connection unstable')
+
+    // Advance time by another 2 seconds (total 6s, more than timeout)
+    act(() => {
+      jest.advanceTimersByTime(2000)
+    })
+
+    expect(result.current.deviceStatus).toContain('Connection unstable')
+    expect(result.current.disconnectionReason).toBe('timeout')
+  })
+
+  it('should disable watchdog if timeout is 0', async () => {
+    const { result } = renderHook(() =>
+      useBluetoothHRM({ dataLivenessTimeoutMs: 0 })
+    )
+    await simulateConnection({ result })
+    expect(result.current.isConnected).toBe(true)
+
+    // Advance time by a large amount
+    act(() => {
+      jest.advanceTimersByTime(20000)
+    })
+
+    expect(result.current.deviceStatus).not.toContain('Connection unstable')
+    expect(result.current.disconnectionReason).toBe(null)
+  })
+
+  it('should set disconnectionReason to "manual" on disconnect', async () => {
+    const { result } = renderHook(() => useBluetoothHRM())
+    await simulateConnection({ result })
+    expect(result.current.isConnected).toBe(true)
+
+    act(() => {
+      result.current.disconnect()
+    })
+
+    expect(result.current.isConnected).toBe(false)
+    expect(result.current.disconnectionReason).toBe('manual')
+  })
+
+  it('should reset disconnectionReason on successful reconnect', async () => {
+    const { result } = renderHook(() =>
+      useBluetoothHRM({ dataLivenessTimeoutMs: 2000 })
+    )
+    await simulateConnection({ result })
+
+    // Trigger a timeout. Timeout is 2s, watchdog checks every 2s.
+    // The check at T=2s will be (2000-0) > 2000 (false).
+    // The check at T=4s will be (4000-0) > 2000 (true).
+    act(() => {
+      jest.advanceTimersByTime(4000)
+    })
+    expect(result.current.disconnectionReason).toBe('timeout')
+
+    // Simulate gatt disconnected state
+    Object.defineProperty(mockDevice.gatt, 'connected', {
+      value: false,
+      writable: true,
+    })
+
+    // Simulate gatt server disconnection event
+    const onDisconnectedCallback = mockDevice.addEventListener.mock.calls.find(
+      (call) => call[0] === 'gattserverdisconnected'
+    )[1]
+    act(() => {
+      onDisconnectedCallback()
+    })
+
+    // It should now be trying to reconnect
+    expect(result.current.deviceStatus).toContain('Signal Lost. Retrying...')
+    expect(result.current.disconnectionReason).toBe('signal_loss')
+
+    // Advance timers for the reconnect delay
+    act(() => {
+      jest.advanceTimersByTime(2000)
+    })
+
+    // Simulate successful reconnection
+    await act(async () => {
+      await Promise.resolve() // Allow promises to resolve after reconnect attempt
+    })
+    Object.defineProperty(mockDevice.gatt, 'connected', {
+      value: true,
+      writable: true,
+    })
+
+    // Re-check status after reconnect logic (might need another tick)
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    expect(result.current.isConnected).toBe(true)
+    expect(result.current.disconnectionReason).toBe(null)
+  })
+})