Двунаправленная связь в 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,
  };
}