@agent-relay/dashboard 2.0.81 → 2.0.82

package/src/components/hooks/usePresence.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Tests for usePresence hook - WebSocket message handling logic
+ *
+ * These tests focus on the message parsing and state update logic
+ * without requiring React Testing Library.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { UserPresence, TypingIndicator } from './usePresence';
+
+// Test the message handling logic in isolation
+describe('usePresence message handling', () => {
+  // Simulate the state update functions from the hook
+  let onlineUsers: UserPresence[] = [];
+  let typingUsers: TypingIndicator[] = [];
+  const currentUsername = 'testuser';
+
+  // Replicated message handling logic from the hook
+  function handleMessage(data: string) {
+    const msg = JSON.parse(data);
+
+    switch (msg.type) {
+      case 'presence_list':
+        onlineUsers = msg.users || [];
+        break;
+
+      case 'presence_join':
+        onlineUsers = onlineUsers.filter((u) => u.username !== msg.user.username);
+        onlineUsers.push(msg.user);
+        break;
+
+      case 'presence_leave':
+        onlineUsers = onlineUsers.filter((u) => u.username !== msg.username);
+        typingUsers = typingUsers.filter((t) => t.username !== msg.username);
+        break;
+
+      case 'typing':
+        // Ignore self
+        if (msg.username === currentUsername) break;
+
+        if (msg.isTyping) {
+          typingUsers = typingUsers.filter((t) => t.username !== msg.username);
+          typingUsers.push({
+            username: msg.username,
+            avatarUrl: msg.avatarUrl,
+            startedAt: Date.now(),
+          });
+        } else {
+          typingUsers = typingUsers.filter((t) => t.username !== msg.username);
+        }
+        break;
+    }
+  }
+
+  beforeEach(() => {
+    onlineUsers = [];
+    typingUsers = [];
+  });
+
+  describe('presence_list', () => {
+    it('should set online users from presence_list message', () => {
+      const users: UserPresence[] = [
+        { username: 'alice', connectedAt: '2024-01-01T00:00:00Z', lastSeen: '2024-01-01T00:00:00Z' },
+        { username: 'bob', avatarUrl: 'https://example.com/bob.jpg', connectedAt: '2024-01-01T00:00:00Z', lastSeen: '2024-01-01T00:00:00Z' },
+      ];
+
+      handleMessage(JSON.stringify({ type: 'presence_list', users }));
+
+      expect(onlineUsers).toEqual(users);
+    });
+
+    it('should handle empty users list', () => {
+      handleMessage(JSON.stringify({ type: 'presence_list', users: [] }));
+      expect(onlineUsers).toEqual([]);
+    });
+
+    it('should handle missing users field', () => {
+      handleMessage(JSON.stringify({ type: 'presence_list' }));
+      expect(onlineUsers).toEqual([]);
+    });
+  });
+
+  describe('presence_join', () => {
+    it('should add new user to online users', () => {
+      const user: UserPresence = {
+        username: 'alice',
+        avatarUrl: 'https://example.com/alice.jpg',
+        connectedAt: '2024-01-01T00:00:00Z',
+        lastSeen: '2024-01-01T00:00:00Z',
+      };
+
+      handleMessage(JSON.stringify({ type: 'presence_join', user }));
+
+      expect(onlineUsers).toHaveLength(1);
+      expect(onlineUsers[0].username).toBe('alice');
+      expect(onlineUsers[0].avatarUrl).toBe('https://example.com/alice.jpg');
+    });
+
+    it('should replace existing user with same username', () => {
+      // Add initial user
+      handleMessage(JSON.stringify({
+        type: 'presence_join',
+        user: { username: 'alice', avatarUrl: 'old.jpg', connectedAt: '2024-01-01T00:00:00Z', lastSeen: '2024-01-01T00:00:00Z' },
+      }));
+
+      // Update same user
+      handleMessage(JSON.stringify({
+        type: 'presence_join',
+        user: { username: 'alice', avatarUrl: 'new.jpg', connectedAt: '2024-01-01T01:00:00Z', lastSeen: '2024-01-01T01:00:00Z' },
+      }));
+
+      expect(onlineUsers).toHaveLength(1);
+      expect(onlineUsers[0].avatarUrl).toBe('new.jpg');
+    });
+  });
+
+  describe('presence_leave', () => {
+    it('should remove user from online users', () => {
+      // Add users
+      handleMessage(JSON.stringify({
+        type: 'presence_list',
+        users: [
+          { username: 'alice', connectedAt: '2024-01-01T00:00:00Z', lastSeen: '2024-01-01T00:00:00Z' },
+          { username: 'bob', connectedAt: '2024-01-01T00:00:00Z', lastSeen: '2024-01-01T00:00:00Z' },
+        ],
+      }));
+
+      expect(onlineUsers).toHaveLength(2);
+
+      // Remove alice
+      handleMessage(JSON.stringify({ type: 'presence_leave', username: 'alice' }));
+
+      expect(onlineUsers).toHaveLength(1);
+      expect(onlineUsers[0].username).toBe('bob');
+    });
+
+    it('should also remove user from typing users', () => {
+      // Add user typing
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: true }));
+      expect(typingUsers).toHaveLength(1);
+
+      // User leaves
+      handleMessage(JSON.stringify({ type: 'presence_leave', username: 'alice' }));
+
+      expect(typingUsers).toHaveLength(0);
+    });
+
+    it('should handle removing non-existent user', () => {
+      handleMessage(JSON.stringify({ type: 'presence_leave', username: 'nonexistent' }));
+      expect(onlineUsers).toEqual([]);
+    });
+  });
+
+  describe('typing', () => {
+    it('should add user to typing users when isTyping is true', () => {
+      handleMessage(JSON.stringify({
+        type: 'typing',
+        username: 'alice',
+        avatarUrl: 'https://example.com/alice.jpg',
+        isTyping: true,
+      }));
+
+      expect(typingUsers).toHaveLength(1);
+      expect(typingUsers[0].username).toBe('alice');
+      expect(typingUsers[0].avatarUrl).toBe('https://example.com/alice.jpg');
+      expect(typingUsers[0].startedAt).toBeGreaterThan(0);
+    });
+
+    it('should remove user from typing users when isTyping is false', () => {
+      // Start typing
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: true }));
+      expect(typingUsers).toHaveLength(1);
+
+      // Stop typing
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: false }));
+      expect(typingUsers).toHaveLength(0);
+    });
+
+    it('should ignore typing indicator from self', () => {
+      handleMessage(JSON.stringify({
+        type: 'typing',
+        username: 'testuser', // Same as currentUsername
+        isTyping: true,
+      }));
+
+      expect(typingUsers).toHaveLength(0);
+    });
+
+    it('should update typing user if they type again', async () => {
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: true }));
+      const firstStartedAt = typingUsers[0].startedAt;
+
+      // Wait sufficient time for timestamp differentiation (50ms is reliable across systems)
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: true }));
+
+      expect(typingUsers).toHaveLength(1);
+      // The startedAt should be updated (or at least the same since it uses Date.now())
+      expect(typingUsers[0].startedAt).toBeGreaterThanOrEqual(firstStartedAt);
+    });
+
+    it('should handle multiple users typing', () => {
+      handleMessage(JSON.stringify({ type: 'typing', username: 'alice', isTyping: true }));
+      handleMessage(JSON.stringify({ type: 'typing', username: 'bob', isTyping: true }));
+      handleMessage(JSON.stringify({ type: 'typing', username: 'charlie', isTyping: true }));
+
+      expect(typingUsers).toHaveLength(3);
+      expect(typingUsers.map(t => t.username)).toEqual(['alice', 'bob', 'charlie']);
+    });
+  });
+});
+
+describe('presence join message format', () => {
+  it('should construct correct join message', () => {
+    const user = { username: 'testuser', avatarUrl: 'https://example.com/test.jpg' };
+    const message = JSON.stringify({
+      type: 'presence',
+      action: 'join',
+      user,
+    });
+
+    const parsed = JSON.parse(message);
+    expect(parsed.type).toBe('presence');
+    expect(parsed.action).toBe('join');
+    expect(parsed.user.username).toBe('testuser');
+    expect(parsed.user.avatarUrl).toBe('https://example.com/test.jpg');
+  });
+});
+
+describe('typing message format', () => {
+  it('should construct correct typing message', () => {
+    const message = JSON.stringify({
+      type: 'typing',
+      isTyping: true,
+      username: 'testuser',
+      avatarUrl: 'https://example.com/test.jpg',
+    });
+
+    const parsed = JSON.parse(message);
+    expect(parsed.type).toBe('typing');
+    expect(parsed.isTyping).toBe(true);
+    expect(parsed.username).toBe('testuser');
+  });
+});

package/src/components/hooks/usePresence.ts

@@ -0,0 +1,377 @@
+/**
+ * usePresence Hook
+ *
+ * Manages user presence and typing indicators via WebSocket.
+ * - Tracks which users are currently online
+ * - Sends/receives typing indicator events
+ * - Handles user presence announcements
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { getWebSocketUrl } from '../../lib/config';
+
+/** User presence information */
+export interface UserPresence {
+  /** Username (GitHub username in cloud mode) */
+  username: string;
+  /** Optional avatar URL */
+  avatarUrl?: string;
+  /** When the user came online */
+  connectedAt: string;
+  /** Last activity timestamp */
+  lastSeen: string;
+  /** Whether user is currently typing */
+  isTyping?: boolean;
+}
+
+/** Typing indicator information */
+export interface TypingIndicator {
+  /** Username of the person typing */
+  username: string;
+  /** Avatar URL if available */
+  avatarUrl?: string;
+  /** Timestamp when typing started */
+  startedAt: number;
+}
+
+export interface UsePresenceOptions {
+  /** Current user info (if logged in) */
+  currentUser?: {
+    username: string;
+    avatarUrl?: string;
+  };
+  /** WebSocket URL (defaults to same as main WebSocket) */
+  wsUrl?: string;
+  /** Whether to auto-connect */
+  autoConnect?: boolean;
+  /** Optional handler for additional messages (e.g., channel_message) */
+  onEvent?: (event: any) => void;
+  /** Workspace ID for channel subscription (cloud mode) */
+  workspaceId?: string;
+}
+
+/** Connection quality state for UI indicators */
+export type PresenceConnectionState = 'connected' | 'reconnecting' | 'disconnected';
+
+export interface UsePresenceReturn {
+  /** List of online users */
+  onlineUsers: UserPresence[];
+  /** Currently typing users (excluding self) */
+  typingUsers: TypingIndicator[];
+  /** Send typing indicator */
+  sendTyping: (isTyping: boolean) => void;
+  /** Whether connected to presence system */
+  isConnected: boolean;
+  /** Granular connection quality: 'connected', 'reconnecting', or 'disconnected' */
+  connectionState: PresenceConnectionState;
+}
+
+/**
+ * Get the presence WebSocket URL using centralized config
+ */
+function getPresenceUrl(): string {
+  return getWebSocketUrl('/ws/presence');
+}
+
+export function usePresence(options: UsePresenceOptions = {}): UsePresenceReturn {
+  const { currentUser, wsUrl, autoConnect = true, onEvent, workspaceId } = options;
+
+  const [onlineUsers, setOnlineUsers] = useState<UserPresence[]>([]);
+  const [typingUsers, setTypingUsers] = useState<TypingIndicator[]>([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [connectionState, setConnectionState] = useState<PresenceConnectionState>('disconnected');
+
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const reconnectAttemptsRef = useRef(0);
+  const typingTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const isConnectingRef = useRef(false); // Prevent race conditions
+  const hasConnectedBeforeRef = useRef(false);
+  const currentUserRef = useRef(currentUser);
+  currentUserRef.current = currentUser; // Keep ref in sync with prop
+  const workspaceIdRef = useRef(workspaceId);
+  workspaceIdRef.current = workspaceId; // Keep ref in sync with prop
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent; // Keep ref in sync with callback prop
+
+  // Clear stale typing indicators (after 3 seconds of no update)
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const now = Date.now();
+      setTypingUsers((prev) =>
+        prev.filter((t) => now - t.startedAt < 3000)
+      );
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, []);
+
+  const connect = useCallback(() => {
+    const user = currentUserRef.current;
+    if (!user) return; // Don't connect without user info
+    if (wsRef.current?.readyState === WebSocket.OPEN) return;
+    if (isConnectingRef.current) return; // Prevent concurrent connect attempts
+
+    // Track reconnection state
+    if (hasConnectedBeforeRef.current) {
+      setConnectionState('reconnecting');
+    }
+
+    isConnectingRef.current = true;
+    const url = wsUrl || getPresenceUrl();
+
+    try {
+      const ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        isConnectingRef.current = false;
+        setIsConnected(true);
+        setConnectionState('connected');
+        reconnectAttemptsRef.current = 0;
+        hasConnectedBeforeRef.current = true;
+
+        // Announce presence (use ref to get latest user info)
+        const currentUserInfo = currentUserRef.current;
+        if (currentUserInfo) {
+          ws.send(JSON.stringify({
+            type: 'presence',
+            action: 'join',
+            user: {
+              username: currentUserInfo.username,
+              avatarUrl: currentUserInfo.avatarUrl,
+            },
+          }));
+
+          // Subscribe to channel messages for this workspace (cloud mode)
+          // This enables receiving real-time channel messages from other users
+          const wsId = workspaceIdRef.current;
+          if (wsId) {
+            ws.send(JSON.stringify({
+              type: 'subscribe_channels',
+              workspaceId: wsId,
+            }));
+          }
+        }
+      };
+
+      ws.onclose = () => {
+        isConnectingRef.current = false;
+        setIsConnected(false);
+        wsRef.current = null;
+
+        // Reconnect with backoff and jitter (only if not intentionally disconnected)
+        if (currentUserRef.current) {
+          setConnectionState('reconnecting');
+          const baseDelay = Math.min(
+            500 * Math.pow(2, reconnectAttemptsRef.current),
+            15000
+          );
+          // Add jitter to prevent thundering herd
+          const delay = Math.round(baseDelay * (0.5 + Math.random() * 0.5));
+          reconnectAttemptsRef.current++;
+
+          console.log(`[WS:Presence] Reconnecting (attempt ${reconnectAttemptsRef.current})...`);
+
+          reconnectTimeoutRef.current = setTimeout(() => {
+            connect();
+          }, delay);
+        } else {
+          setConnectionState('disconnected');
+        }
+      };
+
+      ws.onerror = (event) => {
+        console.error('[usePresence] Error:', event);
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data);
+
+          switch (msg.type) {
+            case 'presence_list':
+              // Full list of online users
+              setOnlineUsers(msg.users || []);
+              break;
+
+            case 'presence_join':
+              // User came online
+              setOnlineUsers((prev) => {
+                const filtered = prev.filter((u) => u.username !== msg.user.username);
+                return [...filtered, msg.user];
+              });
+              // Also forward to onEvent for activity feed
+              onEventRef.current?.(msg);
+              break;
+
+            case 'presence_leave':
+              // User went offline
+              setOnlineUsers((prev) =>
+                prev.filter((u) => u.username !== msg.username)
+              );
+              setTypingUsers((prev) =>
+                prev.filter((t) => t.username !== msg.username)
+              );
+              // Also forward to onEvent for activity feed
+              onEventRef.current?.(msg);
+              break;
+
+            case 'typing':
+              // Typing indicator update
+              if (msg.username === currentUserRef.current?.username) break; // Ignore self
+
+              if (msg.isTyping) {
+                setTypingUsers((prev) => {
+                  const filtered = prev.filter((t) => t.username !== msg.username);
+                  return [
+                    ...filtered,
+                    {
+                      username: msg.username,
+                      avatarUrl: msg.avatarUrl,
+                      startedAt: Date.now(),
+                    },
+                  ];
+                });
+              } else {
+                setTypingUsers((prev) =>
+                  prev.filter((t) => t.username !== msg.username)
+                );
+              }
+              break;
+
+            default:
+              onEventRef.current?.(msg);
+          }
+        } catch (e) {
+          console.error('[usePresence] Failed to parse message:', e);
+        }
+      };
+
+      wsRef.current = ws;
+    } catch (e) {
+      console.error('[usePresence] Failed to create WebSocket:', e);
+    }
+  }, [wsUrl]); // Use ref for currentUser to avoid dependency
+
+  const disconnect = useCallback(() => {
+    // Clear reconnect timeout first
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    }
+
+    // Reset connecting flag
+    isConnectingRef.current = false;
+
+    if (wsRef.current) {
+      // Prevent auto-reconnect by removing onclose handler before closing
+      const ws = wsRef.current;
+      ws.onclose = null;
+      ws.onerror = null;
+
+      // Send leave message before closing
+      const user = currentUserRef.current;
+      if (ws.readyState === WebSocket.OPEN && user) {
+        ws.send(JSON.stringify({
+          type: 'presence',
+          action: 'leave',
+          username: user.username,
+        }));
+      }
+      ws.close();
+      wsRef.current = null;
+    }
+
+    setIsConnected(false);
+    setConnectionState('disconnected');
+  }, []); // Use ref for currentUser to avoid dependency
+
+  // Send typing indicator
+  const sendTyping = useCallback((isTyping: boolean) => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) return;
+    const user = currentUserRef.current;
+    if (!user) return;
+
+    // Clear any existing timeout first
+    if (typingTimeoutRef.current) {
+      clearTimeout(typingTimeoutRef.current);
+      typingTimeoutRef.current = null;
+    }
+
+    wsRef.current.send(JSON.stringify({
+      type: 'typing',
+      isTyping,
+      username: user.username,
+      avatarUrl: user.avatarUrl,
+    }));
+
+    // Only set auto-clear timeout when starting to type
+    if (isTyping) {
+      typingTimeoutRef.current = setTimeout(() => {
+        typingTimeoutRef.current = null;
+        sendTyping(false);
+      }, 3000);
+    }
+  }, []); // Use ref for currentUser to avoid dependency
+
+  // Connect when user is available
+  useEffect(() => {
+    if (!autoConnect || !currentUserRef.current) return;
+
+    // Prevent connecting if already connected or connecting
+    if (wsRef.current && wsRef.current.readyState !== WebSocket.CLOSED) {
+      return;
+    }
+
+    connect();
+
+    return () => {
+      disconnect();
+    };
+    // Callbacks are now stable (use refs internally), so only need to depend on user identity
+  }, [autoConnect, currentUser?.username, connect, disconnect]);
+
+  // Send leave on page unload
+  useEffect(() => {
+    const handleUnload = () => {
+      const user = currentUserRef.current;
+      if (wsRef.current?.readyState === WebSocket.OPEN && user) {
+        wsRef.current.send(JSON.stringify({
+          type: 'presence',
+          action: 'leave',
+          username: user.username,
+        }));
+      }
+    };
+
+    window.addEventListener('beforeunload', handleUnload);
+    return () => window.removeEventListener('beforeunload', handleUnload);
+  }, []); // Use ref for currentUser to avoid dependency
+
+  // Visibility change listener: reconnect when tab becomes visible
+  useEffect(() => {
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible') {
+        // Check if connection is dead and reconnect
+        if (currentUserRef.current && (!wsRef.current || wsRef.current.readyState === WebSocket.CLOSED)) {
+          console.log('[WS:Presence] Tab visible, reconnecting...');
+          reconnectAttemptsRef.current = 0; // Reset attempts for visibility-triggered reconnect
+          connect();
+        }
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [connect]);
+
+  return {
+    onlineUsers,
+    typingUsers,
+    sendTyping,
+    isConnected,
+    connectionState,
+  };
+}