474 websocket add a snack bar to notify the user on websocket status changes (#483)

* [#474] added snackbar for websocket status

* [#474 & #447] added ping to complete browser online/offline status

* [#447] ping timeout as an env var

Author: Eriikah

__test__/features/websocket/WebSocketGate.test.tsx

@@ -12,3 +12,5 @@ var DEBUG = false;
 var LANG = "en";
 var WEBSOCKET_URL = "wss://calendar.example.com";
 var WS_DEBOUNCE_PERIOD_MS = 100; // milliseconds, remove or set to 0 to disable debounce
+var WS_PING_PERIOD_MS = 30000;
+var WS_PING_TIMEOUT_PERIOD_MS = 35000;

public/.env.example.js

@@ -299,6 +299,13 @@
     "endDate": "End Date",
     "endTime": "End Time"
   },
+  "websocket": {
+    "browserOnline": "You’re back online. Reconnecting live updates…",
+    "browserOffline": "You’re offline. Live updates are paused until the connection is restored.",
+    "reconnected": "Live updates are back.",
+    "error": "There was a problem with live updates: %{error}",
+    "closedUnexpectedly": "Live updates were interrupted. Trying to reconnect…"
+  },
   "months": {
     "standalone": {
       "0": "January",

src/locales/en.json

@@ -300,6 +300,13 @@
     "endDate": "Date de la fin",
     "endTime": "Heure de la fin"
   },
+  "websocket": {
+    "browserOnline": "Vous êtes de nouveau en ligne. Reconnexion des mises à jour en temps réel…",
+    "browserOffline": "Vous êtes hors ligne. Les mises à jour en temps réel sont mises en pause jusqu’au rétablissement de la connexion.",
+    "reconnected": "Les mises à jour en temps réel sont de nouveau actives.",
+    "error": "Un problème est survenu avec les mises à jour en temps réel : %{error}",
+    "closedUnexpectedly": "Les mises à jour en temps réel ont été interrompues. Tentative de reconnexion…"
+  },
   "months": {
     "standalone": {
       "0": "Janvier",

src/locales/fr.json

@@ -300,6 +300,13 @@
     "endDate": "Дата окончания",
     "endTime": "Время окончания"
   },
+  "websocket": {
+    "browserOnline": "Вы снова в сети. Подключаем обновления в реальном времени…",
+    "browserOffline": "Вы не в сети. Обновления в реальном времени приостановлены до восстановления соединения.",
+    "reconnected": "Обновления в реальном времени снова работают.",
+    "error": "Произошла ошибка в обновлениях в реальном времени: %{error}",
+    "closedUnexpectedly": "Обновления в реальном времени были прерваны. Пробуем переподключиться…"
+  },
   "months": {
     "standalone": {
       "0": "Январь",

src/locales/ru.json

@@ -298,6 +298,13 @@
     "endDate": "Ngày kết thúc",
     "endTime": "Giờ kết thúc"
   },
+  "websocket": {
+    "browserOnline": "Bạn đã trực tuyến trở lại. Đang kết nối lại cập nhật thời gian thực…",
+    "browserOffline": "Bạn đang ngoại tuyến. Cập nhật thời gian thực sẽ tạm dừng cho đến khi kết nối được khôi phục.",
+    "reconnected": "Cập nhật thời gian thực đã hoạt động trở lại.",
+    "error": "Đã xảy ra sự cố với cập nhật thời gian thực: %{error}",
+    "closedUnexpectedly": "Cập nhật thời gian thực đã bị gián đoạn. Đang thử kết nối lại…"
+  },
   "months": {
     "standalone": {
       "0": "Tháng 1",

src/locales/vi.json

@@ -58,7 +58,10 @@ class IntersectionObserverMock {
 }
 
 (global as any).IntersectionObserver = IntersectionObserverMock;
-
+if (typeof window !== "undefined") {
+  (window as any).WS_PING_PERIOD_MS = 5000;
+  (window as any).WS_PING_TIMEOUT_PERIOD_MS = 5000;
+}
 // Suppress jsdom CSS selector parsing errors for Emotion/MUI
 if (typeof window !== "undefined" && window.getComputedStyle) {
   const originalGetComputedStyle = window.getComputedStyle;

src/setupTests.ts

@@ -2,12 +2,18 @@ import { useAppDispatch, useAppSelector } from "@/app/hooks";
 import { AppDispatch } from "@/app/store";
 import { useSelectedCalendars } from "@/utils/storage/useSelectedCalendars";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useI18n } from "twake-i18n";
 import type { WebSocketWithCleanup } from "./connection";
 import { closeWebSocketConnection } from "./connection/lifecycle/closeWebSocketConnection";
 import { establishWebSocketConnection } from "./connection/lifecycle/establishWebSocketConnection";
 import { useWebSocketReconnect } from "./connection/lifecycle/useWebSocketReconnect";
 import { updateCalendars } from "./messaging/updateCalendars";
 import { syncCalendarRegistrations } from "./operations";
+import { WebSocketStatusSnackbar } from "./WebSocketStatusSnackbar";
+import {
+  setupWebSocketPing,
+  type PingCleanup,
+} from "./connection/lifecycle/pingWebSocket";
 
 export function WebSocketGate() {
   const socketRef = useRef<WebSocketWithCleanup | null>(null);
@@ -16,12 +22,19 @@ export function WebSocketGate() {
   const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const reconnectAttemptsRef = useRef(0);
   const isConnectingRef = useRef(false);
+  const pingCleanupRef = useRef<PingCleanup | null>(null);
 
   const connectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const CONNECT_TIMEOUT_MS = 10_000;
 
   const hadSocketBeforeRef = useRef(false);
   const justReconnectedRef = useRef(false);
+  const [websocketStatus, setWebSocketStatus] = useState("");
+  const [websocketStatusSerity, setWebSocketStatusSerity] = useState<
+    "success" | "info" | "warning" | "error" | undefined
+  >();
+
+  const { t } = useI18n();
 
   const dispatch = useAppDispatch();
   const isAuthenticated = useAppSelector((state) =>
@@ -81,6 +94,8 @@ export function WebSocketGate() {
           `WebSocket closed unexpectedly (code: ${event.code}, reason: ${event.reason || "none"}). ` +
             `Attempting to reconnect...`
         );
+        setWebSocketStatus(t("websocket.closedUnexpectedly"));
+        setWebSocketStatusSerity("warning");
         scheduleReconnect();
       } else {
         reconnectAttemptsRef.current = 0;
@@ -92,6 +107,10 @@ export function WebSocketGate() {
 
   const onError = useCallback((error: Event) => {
     console.error("WebSocket error:", error);
+    const errorMessage =
+      (error as ErrorEvent)?.message ?? error.type ?? "unknown";
+    setWebSocketStatus(t("websocket.error", { error: errorMessage }));
+    setWebSocketStatusSerity("error");
   }, []);
 
   const callBacks = useMemo(
@@ -110,15 +129,15 @@ export function WebSocketGate() {
   // Reset reconnection state on successful connection and mark for calendar re-sync
   useEffect(() => {
     if (isSocketOpen) {
-      console.log("WebSocket connected successfully");
-
       if (connectTimeoutRef.current) {
         clearTimeout(connectTimeoutRef.current);
         connectTimeoutRef.current = null;
       }
 
       if (hadSocketBeforeRef.current) {
         justReconnectedRef.current = true;
+        setWebSocketStatus(t("websocket.reconnected"));
+        setWebSocketStatusSerity("success");
       }
 
       hadSocketBeforeRef.current = true;
@@ -227,7 +246,8 @@ export function WebSocketGate() {
   // Handle browser online/offline events
   useEffect(() => {
     const handleOnline = () => {
-      console.log("Browser is online, attempting WebSocket reconnection");
+      setWebSocketStatus(t("websocket.browserOnline"));
+      setWebSocketStatusSerity("success");
       if (!isSocketOpen && isAuthenticatedRef.current) {
         reconnectAttemptsRef.current = 0;
         clearReconnectTimeout();
@@ -236,9 +256,8 @@ export function WebSocketGate() {
     };
 
     const handleOffline = () => {
-      console.log(
-        "Browser is offline, pausing WebSocket reconnection attempts"
-      );
+      setWebSocketStatus(t("websocket.browserOffline"));
+      setWebSocketStatusSerity("warning");
       cleanupConnection();
     };
 
@@ -260,5 +279,52 @@ export function WebSocketGate() {
     };
   }, [isSocketOpen, isAuthenticated, clearReconnectTimeout]);
 
-  return null;
+  useEffect(() => {
+    // Only set up ping if socket is open
+    if (!isSocketOpen || !socketRef.current) {
+      // Clean up existing ping if socket closed
+      if (pingCleanupRef.current) {
+        pingCleanupRef.current.stop();
+        pingCleanupRef.current = null;
+      }
+      return;
+    }
+
+    // Set up ping monitoring
+    const pingCleanup = setupWebSocketPing(socketRef.current, {
+      onConnectionDead: () => {
+        console.warn("WebSocket connection appears dead (no pong received)");
+        setWebSocketStatus(t("websocket.browserOffline"));
+        setWebSocketStatusSerity("warning");
+
+        // Trigger reconnection
+        if (socketRef.current) {
+          socketRef.current.close();
+        }
+      },
+      onPingFail: () => {
+        console.warn("Failed to send ping");
+      },
+    });
+
+    pingCleanupRef.current = pingCleanup;
+
+    return () => {
+      if (pingCleanupRef.current) {
+        pingCleanupRef.current.stop();
+        pingCleanupRef.current = null;
+      }
+    };
+  }, [isSocketOpen]);
+
+  return websocketStatus ? (
+    <WebSocketStatusSnackbar
+      message={websocketStatus}
+      severity={websocketStatusSerity}
+      onClose={() => {
+        setWebSocketStatus("");
+        setWebSocketStatusSerity(undefined);
+      }}
+    />
+  ) : null;
 }

src/websocket/WebSocketGate.tsx

@@ -0,0 +1,37 @@
+import { Alert, Button, Snackbar } from "@linagora/twake-mui";
+import { useI18n } from "twake-i18n";
+
+export function WebSocketStatusSnackbar({
+  message,
+  severity,
+  onClose,
+}: {
+  message: string;
+  severity: "success" | "info" | "warning" | "error" | undefined;
+  onClose: () => void;
+}) {
+  const { t } = useI18n();
+  return (
+    <Snackbar
+      open={!!message}
+      onClose={onClose}
+      autoHideDuration={
+        severity === "warning" || severity === "error" ? null : 6000
+      }
+      anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
+    >
+      <Alert
+        severity={severity}
+        onClose={onClose}
+        sx={{ width: "100%" }}
+        action={
+          <Button color="inherit" size="small" onClick={onClose}>
+            {t("common.ok")}
+          </Button>
+        }
+      >
+        {message}
+      </Alert>
+    </Snackbar>
+  );
+}