@jskit-ai/realtime 0.1.185 → 0.1.187

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/realtime",
-  "version": "0.1.185",
+  "version": "0.1.187",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -20,8 +20,8 @@
     "socket.io-client": "^4.8.3"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.188",
-    "@jskit-ai/shell-web": "0.1.192",
+    "@jskit-ai/kernel": "0.1.190",
+    "@jskit-ai/shell-web": "0.1.194",
     "vue": "^3.5.13"
   },
   "description": "Thin, generic realtime runtime wrappers for socket.io server and client.",

package/patterns/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.1.185",
-    "@jskit-ai/shell-web": "0.1.192"
+    "@jskit-ai/realtime": "0.1.187",
+    "@jskit-ai/shell-web": "0.1.194"
   }
 }

package/src/client/RealtimeClientProvider.js

@@ -4,6 +4,7 @@ import { createProviderLogger } from "@jskit-ai/kernel/shared/support/providerLo
 import { getClientAppConfig, resolveClientBootstrapDebugEnabled, resolveMobileConfig } from "@jskit-ai/kernel/client";
 import RealtimeConnectionIndicator from "./components/RealtimeConnectionIndicator.js";
 import { createSocketIoClient, disconnectSocketIoClient } from "./runtime.js";
+import { attachSocketConnectionRecovery } from "./connectionRecovery.js";
 
 const REALTIME_RUNTIME_CLIENT_API = Object.freeze({
   createSocketIoClient,
@@ -59,6 +60,7 @@ function createRealtimeClient({ config, loggerInput } = {}) {
     initialized = true;
 
     if (typeof socket.on === "function") {
+      detach.push(attachSocketConnectionRecovery(socket));
       const onConnect = () => logger.debug({ socketConnected: true }, "Realtime client socket connected.");
       const onDisconnect = (reason) =>
         logger.debug(

package/src/client/components/RealtimeConnectionIndicator.js

@@ -3,10 +3,14 @@ import { EMPTY_REALTIME_SOCKET, useRealtimeSocket } from "../composables/useReal
 
 const ROOT_STYLE = Object.freeze({
   alignItems: "center",
+  background: "transparent",
+  border: "0",
+  borderRadius: "50%",
   display: "inline-flex",
-  height: "32px",
+  height: "48px",
   justifyContent: "center",
-  width: "32px"
+  padding: "0",
+  width: "48px"
 });
 
 const DOT_STYLE = Object.freeze({
@@ -37,7 +41,7 @@ function resolveTooltipText({ realtimeAvailable, connected }) {
   if (connected) {
     return "Realtime is connected. Live updates are active.";
   }
-  return "Realtime is disconnected. The client will keep trying to reconnect.";
+  return "Live updates are disconnected. Click to reconnect. If your session expired, sign in again.";
 }
 
 const RealtimeConnectionIndicator = defineComponent({
@@ -104,11 +108,14 @@ const RealtimeConnectionIndicator = defineComponent({
 
     return () =>
       h(
-        "span",
+        "button",
         {
-          style: ROOT_STYLE,
+          disabled: !realtimeAvailable || connected.value,
+          onClick: () => socket.connect?.(),
+          style: { ...ROOT_STYLE, cursor: realtimeAvailable && !connected.value ? "pointer" : "default" },
           title: tooltipText.value,
-          "aria-label": statusLabel.value
+          type: "button",
+          "aria-label": realtimeAvailable && !connected.value ? "Reconnect live updates" : statusLabel.value
         },
         [
           h("span", { style: dotStyle.value, "aria-hidden": "true" }),

package/src/client/connectionRecovery.js

@@ -0,0 +1,68 @@
+function attachSocketConnectionRecovery(socket) {
+  let timer = null;
+  let delay = 1_000;
+  let recovering = false;
+  const document = globalThis.document;
+  const window = globalThis.window;
+
+  function clearRetry() {
+    clearTimeout(timer);
+    timer = null;
+  }
+
+  function canRetry() {
+    return recovering && !socket.connected && !socket.active &&
+      socket.io.reconnection() &&
+      !document?.hidden && window?.navigator?.onLine !== false;
+  }
+
+  function scheduleRetry() {
+    if (timer !== null || !canRetry()) return;
+    timer = setTimeout(() => {
+      timer = null;
+      if (canRetry()) socket.connect();
+    }, delay);
+    delay = Math.min(delay * 2, 30_000);
+  }
+
+  function onConnect() {
+    clearRetry();
+    recovering = false;
+    delay = 1_000;
+  }
+
+  function onDisconnect(reason) {
+    clearRetry();
+    // Socket.IO retries transport failures itself, but not a server disconnect.
+    recovering = reason === "io server disconnect";
+    scheduleRetry();
+  }
+
+  function onConnectError() {
+    recovering = true;
+    scheduleRetry();
+  }
+
+  function onAvailable() {
+    if (!canRetry()) return;
+    clearRetry();
+    socket.connect();
+  }
+
+  socket.on("connect", onConnect);
+  socket.on("disconnect", onDisconnect);
+  socket.on("connect_error", onConnectError);
+  document?.addEventListener("visibilitychange", onAvailable);
+  window?.addEventListener("online", onAvailable);
+  return () => {
+    recovering = false;
+    clearRetry();
+    socket.off("connect", onConnect);
+    socket.off("disconnect", onDisconnect);
+    socket.off("connect_error", onConnectError);
+    document?.removeEventListener("visibilitychange", onAvailable);
+    window?.removeEventListener("online", onAvailable);
+  };
+}
+
+export { attachSocketConnectionRecovery };

package/test/clientRuntime.test.js

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { EventEmitter, once } from "node:events";
+import { createServer } from "node:http";
+import { Server } from "socket.io";
 
 import { createSocketIoClient, disconnectSocketIoClient } from "../src/client/runtime.js";
+import { attachSocketConnectionRecovery } from "../src/client/connectionRecovery.js";
 
 test("createSocketIoClient calls connect with fixed socket path", () => {
   const calls = [];
@@ -79,3 +83,132 @@ test("disconnectSocketIoClient is a no-op for missing socket", () => {
   disconnectSocketIoClient({});
   assert.equal(true, true);
 });
+
+function recoverySocket(t) {
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  const socket = Object.assign(new EventEmitter(), {
+    active: false,
+    connected: false,
+    connect: t.mock.fn(),
+    io: { reconnection: () => true }
+  });
+  const detach = attachSocketConnectionRecovery(socket);
+  t.after(detach);
+  return { socket, detach };
+}
+
+test("server disconnect recovery backs off middleware rejection and resets after connection", (t) => {
+  const { socket } = recoverySocket(t);
+  socket.emit("disconnect", "io server disconnect");
+  for (const [index, delay] of [1_000, 2_000, 4_000, 8_000, 16_000, 30_000, 30_000].entries()) {
+    t.mock.timers.tick(delay - 1);
+    assert.equal(socket.connect.mock.callCount(), index);
+    t.mock.timers.tick(1);
+    assert.equal(socket.connect.mock.callCount(), index + 1);
+    socket.emit("connect_error", new Error("Authentication required"));
+  }
+  socket.connected = true;
+  socket.emit("connect");
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 7);
+  socket.connected = false;
+  socket.emit("disconnect", "io server disconnect");
+  t.mock.timers.tick(1_000);
+  assert.equal(socket.connect.mock.callCount(), 8);
+});
+
+test("recovery leaves transport retries and intentional disconnects to Socket.IO", (t) => {
+  const { socket, detach } = recoverySocket(t);
+  socket.active = true;
+  socket.emit("disconnect", "transport close");
+  socket.emit("connect_error", new Error("Temporary transport error"));
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+  socket.active = false;
+  socket.emit("disconnect", "io server disconnect");
+  socket.emit("disconnect", "io client disconnect");
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+  socket.emit("disconnect", "io server disconnect");
+  detach();
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+  assert.equal(socket.eventNames().length, 0);
+});
+
+test("recovery respects reconnection disabled at startup or while a retry is pending", (t) => {
+  const { socket } = recoverySocket(t);
+  const client = createSocketIoClient({ options: { autoConnect: false, reconnection: false } });
+  socket.io = client.io;
+  t.after(() => client.disconnect());
+  socket.emit("disconnect", "io server disconnect");
+  socket.emit("connect_error", new Error("Rejected"));
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+  socket.io.reconnection(true);
+  socket.emit("connect_error", new Error("Rejected"));
+  socket.io.reconnection(false);
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+});
+
+test("hidden or offline pages resume recovery when available and remove their listeners on teardown", (t) => {
+  const previousDocument = globalThis.document;
+  const previousWindow = globalThis.window;
+  const document = Object.assign(new EventTarget(), { hidden: true });
+  const window = Object.assign(new EventTarget(), { navigator: { onLine: true } });
+  globalThis.document = document;
+  globalThis.window = window;
+  t.after(() => {
+    if (previousDocument === undefined) delete globalThis.document;
+    else globalThis.document = previousDocument;
+    if (previousWindow === undefined) delete globalThis.window;
+    else globalThis.window = previousWindow;
+  });
+  const { socket, detach } = recoverySocket(t);
+  socket.emit("disconnect", "io server disconnect");
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 0);
+  document.hidden = false;
+  window.navigator.onLine = false;
+  document.dispatchEvent(new Event("visibilitychange"));
+  assert.equal(socket.connect.mock.callCount(), 0);
+  window.navigator.onLine = true;
+  window.dispatchEvent(new Event("online"));
+  assert.equal(socket.connect.mock.callCount(), 1);
+  socket.emit("connect_error", new Error("Temporary failure"));
+  detach();
+  window.dispatchEvent(new Event("online"));
+  document.dispatchEvent(new Event("visibilitychange"));
+  t.mock.timers.tick(30_000);
+  assert.equal(socket.connect.mock.callCount(), 1);
+});
+
+test("a real server-forced disconnect reconnects through a fresh authenticated handshake", async (t) => {
+  const http = createServer();
+  const io = new Server(http);
+  let handshakes = 0;
+  io.use((_socket, next) => {
+    handshakes += 1;
+    if (handshakes === 2) return next(new Error("Temporary authentication lookup failure"));
+    next();
+  });
+  http.listen(0, "127.0.0.1");
+  await once(http, "listening");
+  const client = createSocketIoClient({ url: `http://127.0.0.1:${http.address().port}` });
+  const detach = attachSocketConnectionRecovery(client);
+  t.after(async () => {
+    detach();
+    client.disconnect();
+    await new Promise((resolve) => io.close(resolve));
+  });
+  await once(client, "connect", { signal: AbortSignal.timeout(5_000) });
+  const before = client.id;
+  const disconnected = once(client, "disconnect");
+  io.sockets.sockets.get(before).disconnect(true);
+  assert.equal((await disconnected)[0], "io server disconnect");
+  assert.equal(client.active, false);
+  await once(client, "connect", { signal: AbortSignal.timeout(8_000) });
+  assert.equal(handshakes, 3);
+  assert.notEqual(client.id, before);
+});