Двонаправлений зв'язок у React: WebSockets, SSE та WebTransport

┌────────────────────────────────────────────────────────────────────────┐
│                   ПРОТОКОЛИ ПЕРЕДАЧІ ДАНИХ У REAL-TIME                 │
│                                                                        │
│ 1. WebSockets (TCP):                                                   │
│    Client <══════════════ Двонаправлений обмін (JSON/Binary) ══════════> Server│
│    • Плюси: низькі накладні витрати фреймів (2-10 байт), повний дуплекс│
│    • Мінуси: Head-of-Line Blocking на рівні TCP при втраті пакетів     │
│                                                                        │
│ 2. Server-Sent Events (HTTP/2 або HTTP/3):                             │
│    Client <────────────────── Потік подій (text/event-stream) ───────── Server│
│    Client ─── HTTP POST / RPC ───> (окремий канал для команд на сервер)│
│    • Плюси: нативний автореконнект, мультиплексування в HTTP/2         │
│    • Мінуси: тільки текст (UTF-8), однонаправлений від сервера         │
│                                                                        │
│ 3. WebTransport (QUIC / UDP):                                          │
│    Client <─ ─ ─ ─ ─ Ненадійні датаграми (Datagrams / UDP) ─ ─ ─ ─ ─ ─> Server│
│    Client <═══════ Мультиплексовані надійні потоки (Streams) ══════════> Server│
│    • Плюси: нульовий Head-of-Line Blocking між потоками, наднизька     │
│             затримка для відео/телеметрії/ігор                         │
└────────────────────────────────────────────────────────────────────────┘

'use client';

import * as React from 'react';

export type WebSocketStatus = 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED';

export interface UseWebSocketOptions<TIncoming, TOutgoing> {
  url: string;
  protocols?: string | string[];
  /** Базова затримка реконнекту в мс (за замовчуванням 1000) */
  baseReconnectDelayMs?: number;
  /** Максимальна затримка реконнекту в мс (за замовчуванням 30000) */
  maxReconnectDelayMs?: number;
  /** Інтервал відправлення Heartbeat пінгів у мс (за замовчуванням 30000) */
  heartbeatIntervalMs?: number;
  /** Таймаут відповіді на Heartbeat у мс (за замовчуванням 5000) */
  heartbeatTimeoutMs?: number;
  /** Повідомлення для пінгу (за замовчуванням { type: 'ping' }) */
  pingMessage?: TOutgoing;
  /** Максимальний розмір офлайн-черги повідомлень */
  maxQueueSize?: number;
  /** Автоматичне підключення при монтуванні */
  autoConnect?: boolean;
  onMessage?: (message: TIncoming) => void;
  onError?: (event: Event) => void;
  onOpen?: (event: Event) => void;
  onClose?: (event: CloseEvent) => void;
}

export interface UseWebSocketReturn<TIncoming, TOutgoing> {
  status: WebSocketStatus;
  sendMessage: (data: TOutgoing) => boolean;
  lastMessage: TIncoming | null;
  connect: () => void;
  disconnect: () => void;
}

export function useWebSocket<TIncoming = unknown, TOutgoing = unknown>(
  options: UseWebSocketOptions<TIncoming, TOutgoing>
): UseWebSocketReturn<TIncoming, TOutgoing> {
  const {
    url,
    protocols,
    baseReconnectDelayMs = 1000,
    maxReconnectDelayMs = 30000,
    heartbeatIntervalMs = 30000,
    heartbeatTimeoutMs = 5000,
    pingMessage = { type: 'ping' } as unknown as TOutgoing,
    maxQueueSize = 100,
    autoConnect = true,
    onMessage,
    onError,
    onOpen,
    onClose,
  } = options;

  const [status, setStatus] = React.useState<WebSocketStatus>('CLOSED');
  const [lastMessage, setLastMessage] = React.useState<TIncoming | null>(null);

  // Посилання на інфраструктурні об'єкти для ізоляції від перерендерів
  const wsRef = React.useRef<WebSocket | null>(null);
  const reconnectAttemptsRef = React.useRef<number>(0);
  const reconnectTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
  const heartbeatTimerRef = React.useRef<ReturnType<typeof setInterval> | null>(null);
  const heartbeatTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
  const messageQueueRef = React.useRef<string[]>([]);
  const isManuallyClosedRef = React.useRef<boolean>(false);

  // Сховище стабільних посилань на колбеки
  const callbacksRef = React.useRef({ onMessage, onError, onOpen, onClose });
  React.useEffect(() => {
    callbacksRef.current = { onMessage, onError, onOpen, onClose };
  });

  const clearTimers = React.useCallback(() => {
    if (reconnectTimerRef.current) {
      clearTimeout(reconnectTimerRef.current);
      reconnectTimerRef.current = null;
    }
    if (heartbeatTimerRef.current) {
      clearInterval(heartbeatTimerRef.current);
      heartbeatTimerRef.current = null;
    }
    if (heartbeatTimeoutRef.current) {
      clearTimeout(heartbeatTimeoutRef.current);
      heartbeatTimeoutRef.current = null;
    }
  }, []);

  // Розрахунок затримки за формулою Full Jitter
  const calculateBackoff = React.useCallback(
    (attempt: number): number => {
      const exponentialDelay = baseReconnectDelayMs * Math.pow(2, attempt);
      const cappedDelay = Math.min(maxReconnectDelayMs, exponentialDelay);
      return Math.floor(Math.random() * cappedDelay);
    },
    [baseReconnectDelayMs, maxReconnectDelayMs]
  );

  // Скидання накопичених офлайн-повідомлень у відкритий сокет
  const flushQueue = React.useCallback(() => {
    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) return;
    while (messageQueueRef.current.length > 0) {
      const payload = messageQueueRef.current.shift();
      if (payload) {
        wsRef.current.send(payload);
      }
    }
  }, []);

  // Моніторинг активності сокета через Ping-Pong
  const startHeartbeat = React.useCallback(() => {
    if (heartbeatTimerRef.current) clearInterval(heartbeatTimerRef.current);

    heartbeatTimerRef.current = setInterval(() => {
      if (wsRef.current?.readyState === WebSocket.OPEN) {
        wsRef.current.send(JSON.stringify(pingMessage));

        // Якщо відповідь не отримана протягом heartbeatTimeoutMs — сокет завис
        heartbeatTimeoutRef.current = setTimeout(() => {
          console.warn('[WebSocket]: Перевищено таймаут Heartbeat. Примусовий розрив зомбі-сокета...');
          wsRef.current?.close(4000, 'Heartbeat Timeout');
        }, heartbeatTimeoutMs);
      }
    }, heartbeatIntervalMs);
  }, [heartbeatIntervalMs, heartbeatTimeoutMs, pingMessage]);

  const connect = React.useCallback(() => {
    clearTimers();
    isManuallyClosedRef.current = false;

    try {
      setStatus('CONNECTING');
      const ws = new WebSocket(url, protocols);
      wsRef.current = ws;

      ws.onopen = (event) => {
        setStatus('OPEN');
        reconnectAttemptsRef.current = 0;
        startHeartbeat();
        flushQueue();
        callbacksRef.current.onOpen?.(event);
      };

      ws.onmessage = (event: MessageEvent<string>) => {
        // Будь-який вхідний пакет скидає таймаут завислого Heartbeat
        if (heartbeatTimeoutRef.current) {
          clearTimeout(heartbeatTimeoutRef.current);
          heartbeatTimeoutRef.current = null;
        }

        try {
          const parsedData = JSON.parse(event.data) as TIncoming;
          // Ігноруємо технічні відповіді на ping
          if ((parsedData as { type?: string })?.type === 'pong') return;

          setLastMessage(parsedData);
          callbacksRef.current.onMessage?.(parsedData);
        } catch {
          setLastMessage(event.data as unknown as TIncoming);
          callbacksRef.current.onMessage?.(event.data as unknown as TIncoming);
        }
      };

      ws.onerror = (event) => {
        callbacksRef.current.onError?.(event);
      };

      ws.onclose = (event) => {
        clearTimers();
        setStatus('CLOSED');
        wsRef.current = null;
        callbacksRef.current.onClose?.(event);

        if (!isManuallyClosedRef.current) {
          const delay = calculateBackoff(reconnectAttemptsRef.current);
          reconnectAttemptsRef.current += 1;
          reconnectTimerRef.current = setTimeout(() => {
            connect();
          }, delay);
        }
      };
    } catch {
      setStatus('CLOSED');
    }
  }, [url, protocols, clearTimers, startHeartbeat, flushQueue, calculateBackoff]);

  const disconnect = React.useCallback(() => {
    isManuallyClosedRef.current = true;
    clearTimers();
    if (wsRef.current) {
      setStatus('CLOSING');
      wsRef.current.close(1000, 'User Disconnect');
      wsRef.current = null;
    }
    setStatus('CLOSED');
  }, [clearTimers]);

  const sendMessage = React.useCallback(
    (data: TOutgoing): boolean => {
      const payload = typeof data === 'string' ? data : JSON.stringify(data);

      if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
        wsRef.current.send(payload);
        return true;
      }

      // Збереження в офлайн-чергу з витісненням найстаріших записів
      if (messageQueueRef.current.length >= maxQueueSize) {
        messageQueueRef.current.shift();
      }
      messageQueueRef.current.push(payload);
      return false;
    },
    [maxQueueSize]
  );

  React.useEffect(() => {
    if (autoConnect) {
      connect();
    }
    return () => {
      isManuallyClosedRef.current = true;
      clearTimers();
      if (wsRef.current) {
        wsRef.current.close();
      }
    };
  }, [autoConnect, connect, clearTimers]);

  return {
    status,
    sendMessage,
    lastMessage,
    connect,
    disconnect,
  };
}