@jskit-ai/realtime 0.1.4

package/package.descriptor.mjs

@@ -0,0 +1,142 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/realtime",
+  version: "0.1.4",
+  description: "Thin, generic realtime runtime wrappers for socket.io server and client.",
+  options: {
+    "realtime-redis-url": {
+      required: true,
+      allowEmpty: true,
+      values: [],
+      defaultValue: "",
+      promptLabel: "Realtime Redis URL",
+      promptHint: "Leave empty to use in-memory socket adapter."
+    }
+  },
+  dependsOn: [
+    "@jskit-ai/kernel"
+  ],
+  capabilities: {
+    provides: [
+      "runtime.realtime",
+      "runtime.realtime.client"
+    ],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/RealtimeServiceProvider.js",
+      providers: [
+        {
+          entrypoint: "src/server/RealtimeServiceProvider.js",
+          export: "RealtimeServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: [
+        {
+          entrypoint: "src/client/RealtimeClientProvider.js",
+          export: "RealtimeClientProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server",
+          summary: "Exports RealtimeServiceProvider only."
+        },
+        {
+          subpath: "./client",
+          summary: "Exports RealtimeClientProvider only."
+        },
+        {
+          subpath: "./client/listeners",
+          summary: "Exports client listener registration helpers for provider-level realtime subscriptions."
+        },
+        {
+          subpath: "./client/composables/*",
+          summary: "Exports component-level realtime socket composables."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "runtime.realtime"
+        ],
+        client: [
+          "runtime.realtime.client",
+          "runtime.realtime.client.socket",
+          "realtime.web.connection.indicator"
+        ]
+      }
+    },
+    ui: {
+      placements: {
+        outlets: [],
+        contributions: [
+          {
+            id: "realtime.connection.indicator",
+            host: "shell-layout",
+            position: "top-right",
+            surfaces: ["*"],
+            order: 950,
+            componentToken: "realtime.web.connection.indicator",
+            source: "mutations.text#realtime-placement-indicator"
+          }
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/kernel": "0.1.4",
+        "@socket.io/redis-adapter": "^8.3.0",
+        "redis": "^5.8.2",
+        "socket.io": "^4.8.3",
+        "socket.io-client": "^4.8.3"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [],
+    vite: {
+      proxy: [
+        {
+          id: "realtime-socket-io",
+          path: "/socket.io",
+          changeOrigin: true,
+          ws: true
+        }
+      ]
+    },
+    text: [
+      {
+        file: ".env",
+        op: "upsert-env",
+        key: "REALTIME_REDIS_URL",
+        value: "${option:realtime-redis-url}",
+        reason: "Configure optional Redis backplane URL for realtime socket adapter.",
+        category: "runtime-config",
+        id: "realtime-redis-url"
+      },
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"realtime.connection.indicator\"",
+        value:
+          "\naddPlacement({\n  id: \"realtime.connection.indicator\",\n  host: \"shell-layout\",\n  position: \"top-right\",\n  surfaces: [\"*\"],\n  order: 950,\n  componentToken: \"realtime.web.connection.indicator\"\n});\n",
+        reason: "Append realtime connection indicator placement into app-owned placement registry.",
+        category: "realtime-web",
+        id: "realtime-placement-indicator"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@jskit-ai/realtime",
+  "version": "0.1.4",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./server/RealtimeServiceProvider": "./src/server/RealtimeServiceProvider.js",
+    "./server/runtime": "./src/server/runtime.js",
+    "./server/tokens": "./src/server/tokens.js",
+    "./client": "./src/client/RealtimeClientProvider.js",
+    "./client/RealtimeClientProvider": "./src/client/RealtimeClientProvider.js",
+    "./client/listeners": "./src/client/listeners.js",
+    "./client/composables/*": "./src/client/composables/*.js",
+    "./client/runtime": "./src/client/runtime.js",
+    "./client/tokens": "./src/client/tokens.js"
+  },
+  "dependencies": {
+    "@socket.io/redis-adapter": "^8.3.0",
+    "@jskit-ai/kernel": "0.1.4",
+    "redis": "^5.8.2",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3"
+  }
+}

package/src/client/RealtimeClientProvider.js

@@ -0,0 +1,302 @@
+import { createSocketIoClient, disconnectSocketIoClient } from "./runtime.js";
+import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  CLIENT_MODULE_ENV_TOKEN,
+  CLIENT_MODULE_VUE_APP_TOKEN
+} from "@jskit-ai/kernel/client/moduleBootstrap";
+import { resolveClientBootstrapDebugEnabled } from "@jskit-ai/kernel/client";
+import RealtimeConnectionIndicator from "./components/RealtimeConnectionIndicator.js";
+import {
+  REALTIME_RUNTIME_CLIENT_TOKEN,
+  REALTIME_SOCKET_CLIENT_TOKEN,
+  REALTIME_SOCKET_CLIENT_INJECTION_KEY
+} from "./tokens.js";
+import { resolveRealtimeClientListeners } from "./listeners.js";
+
+const REALTIME_CONNECTION_INDICATOR_COMPONENT_TOKEN = "realtime.web.connection.indicator";
+
+const REALTIME_RUNTIME_CLIENT_API = Object.freeze({
+  createSocketIoClient,
+  disconnectSocketIoClient
+});
+
+function createProviderLogger(app, { debugEnabled = false } = {}) {
+  return Object.freeze({
+    debug: (...args) => {
+      if (debugEnabled !== true) {
+        return;
+      }
+      if (app && typeof app.info === "function") {
+        app.info(...args);
+        return;
+      }
+      console.info(...args);
+    },
+    info: (...args) => {
+      if (app && typeof app.info === "function") {
+        app.info(...args);
+        return;
+      }
+      console.info(...args);
+    },
+    warn: (...args) => {
+      if (app && typeof app.warn === "function") {
+        app.warn(...args);
+        return;
+      }
+      console.warn(...args);
+    },
+    error: (...args) => {
+      if (app && typeof app.error === "function") {
+        app.error(...args);
+        return;
+      }
+      console.error(...args);
+    }
+  });
+}
+
+function resolveRealtimeClientConfig(app) {
+  const appConfig = app && typeof app.has === "function" && app.has("appConfig") ? normalizeObject(app.make("appConfig")) : {};
+  const env = app && typeof app.has === "function" && app.has(CLIENT_MODULE_ENV_TOKEN) ? normalizeObject(app.make(CLIENT_MODULE_ENV_TOKEN)) : {};
+  const realtime = normalizeObject(appConfig.realtime);
+  const realtimeClient = normalizeObject(appConfig.realtimeClient);
+  const url = normalizeText(realtimeClient.url);
+  const options = normalizeObject(realtimeClient.options);
+  const explicitDebugEnabled =
+    typeof realtimeClient.debug === "boolean"
+      ? realtimeClient.debug
+      : typeof realtime.debug === "boolean"
+        ? realtime.debug
+        : undefined;
+  const hasRealtimeDebugEnvOverride = Object.hasOwn(env, "VITE_REALTIME_DEBUG");
+  const debugEnabled = hasRealtimeDebugEnvOverride
+    ? resolveClientBootstrapDebugEnabled({
+        env,
+        debugEnabled: undefined,
+        debugEnvKey: "VITE_REALTIME_DEBUG"
+      })
+    : resolveClientBootstrapDebugEnabled({
+        env,
+        debugEnabled: explicitDebugEnabled,
+        debugEnvKey: "VITE_REALTIME_DEBUG"
+      });
+
+  return Object.freeze({
+    url,
+    options,
+    debugEnabled
+  });
+}
+
+class RealtimeClientProvider {
+  static id = REALTIME_RUNTIME_CLIENT_TOKEN;
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("RealtimeClientProvider requires application singleton().");
+    }
+
+    app.singleton(REALTIME_RUNTIME_CLIENT_TOKEN, () => REALTIME_RUNTIME_CLIENT_API);
+    app.singleton(REALTIME_CONNECTION_INDICATOR_COMPONENT_TOKEN, () => RealtimeConnectionIndicator);
+    app.singleton(REALTIME_SOCKET_CLIENT_TOKEN, (scope) => {
+      const realtimeRuntime = scope.make(REALTIME_RUNTIME_CLIENT_TOKEN);
+      const realtimeClientConfig = resolveRealtimeClientConfig(scope);
+      return realtimeRuntime.createSocketIoClient({
+        url: realtimeClientConfig.url,
+        options: realtimeClientConfig.options
+      });
+    });
+  }
+
+  boot(app) {
+    if (!app || typeof app.make !== "function") {
+      throw new Error("RealtimeClientProvider requires application make().");
+    }
+
+    const realtimeClientConfig = resolveRealtimeClientConfig(app);
+    const logger = createProviderLogger(app, {
+      debugEnabled: realtimeClientConfig.debugEnabled
+    });
+    const socket = app.make(REALTIME_SOCKET_CLIENT_TOKEN);
+    const listeners = resolveRealtimeClientListeners(app);
+    const detach = [];
+
+    logger.debug(
+      {
+        providerId: RealtimeClientProvider.id,
+        listenerCount: listeners.length,
+        listeners: listeners.map((listener) => ({
+          listenerId: listener.listenerId,
+          event: listener.event
+        }))
+      },
+      "Realtime client booted listeners."
+    );
+
+    if (typeof socket.on === "function") {
+      const onConnect = () => {
+        logger.debug(
+          {
+            providerId: RealtimeClientProvider.id,
+            socketConnected: true
+          },
+          "Realtime client socket connected."
+        );
+      };
+      const onDisconnect = (reason) => {
+        logger.debug(
+          {
+            providerId: RealtimeClientProvider.id,
+            socketConnected: false,
+            reason: String(reason || "")
+          },
+          "Realtime client socket disconnected."
+        );
+      };
+      const onConnectError = (error) => {
+        logger.warn(
+          {
+            providerId: RealtimeClientProvider.id,
+            error: String(error?.message || error || "unknown error")
+          },
+          "Realtime client socket connect error."
+        );
+      };
+
+      socket.on("connect", onConnect);
+      socket.on("disconnect", onDisconnect);
+      socket.on("connect_error", onConnectError);
+      detach.push(() => {
+        if (typeof socket.off === "function") {
+          socket.off("connect", onConnect);
+          socket.off("disconnect", onDisconnect);
+          socket.off("connect_error", onConnectError);
+        }
+      });
+
+      if (realtimeClientConfig.debugEnabled === true && typeof socket.onAny === "function") {
+        const onAnyDebug = (eventName, payload) => {
+          logger.debug(
+            {
+              providerId: RealtimeClientProvider.id,
+              event: String(eventName || ""),
+              payloadScope: payload?.scope || null,
+              payloadEntityId: payload?.entityId || null
+            },
+            "Realtime client received socket event."
+          );
+        };
+        socket.onAny(onAnyDebug);
+        detach.push(() => {
+          if (typeof socket.offAny === "function") {
+            socket.offAny(onAnyDebug);
+          }
+        });
+      }
+    }
+
+    for (const listener of listeners) {
+      const invoke = (eventName, payload) => {
+        const context = Object.freeze({
+          event: eventName,
+          payload,
+          socket,
+          app
+        });
+
+        if (listener.matches && listener.matches(context) !== true) {
+          logger.debug(
+            {
+              listenerId: listener.listenerId,
+              event: eventName
+            },
+            "Realtime client listener skipped event by matches()."
+          );
+          return;
+        }
+
+        logger.debug(
+          {
+            listenerId: listener.listenerId,
+            event: eventName,
+            payloadScope: payload?.scope || null,
+            payloadEntityId: payload?.entityId || null
+          },
+          "Realtime client listener handling event."
+        );
+
+        Promise.resolve(listener.handle(context)).catch((error) => {
+          logger.error(
+            {
+              listenerId: listener.listenerId,
+              event: eventName,
+              error: String(error?.message || error || "unknown error")
+            },
+            "Realtime client listener failed."
+          );
+        });
+      };
+
+      if (listener.event === "*") {
+        if (typeof socket.onAny === "function") {
+          const onAny = (eventName, payload) => invoke(eventName, payload);
+          socket.onAny(onAny);
+          detach.push(() => {
+            if (typeof socket.offAny === "function") {
+              socket.offAny(onAny);
+            }
+          });
+        }
+        continue;
+      }
+
+      if (typeof socket.on === "function") {
+        const onEvent = (payload) => invoke(listener.event, payload);
+        socket.on(listener.event, onEvent);
+        detach.push(() => {
+          if (typeof socket.off === "function") {
+            socket.off(listener.event, onEvent);
+          }
+        });
+      }
+    }
+
+    this.socket = socket;
+    this.detach = detach;
+
+    if (!app.has(CLIENT_MODULE_VUE_APP_TOKEN)) {
+      return;
+    }
+
+    const vueApp = app.make(CLIENT_MODULE_VUE_APP_TOKEN);
+    if (!vueApp || typeof vueApp.provide !== "function") {
+      return;
+    }
+    vueApp.provide(REALTIME_SOCKET_CLIENT_INJECTION_KEY, socket);
+  }
+
+  shutdown(app) {
+    if (Array.isArray(this.detach)) {
+      for (const release of this.detach) {
+        if (typeof release === "function") {
+          try {
+            release();
+          } catch {}
+        }
+      }
+    }
+    this.detach = [];
+
+    if (!this.socket) {
+      return;
+    }
+
+    const runtimeApi =
+      app && typeof app.make === "function" ? app.make(REALTIME_RUNTIME_CLIENT_TOKEN) : REALTIME_RUNTIME_CLIENT_API;
+    runtimeApi.disconnectSocketIoClient(this.socket);
+    this.socket = null;
+  }
+}
+
+export { RealtimeClientProvider };

package/src/client/components/RealtimeConnectionIndicator.js

@@ -0,0 +1,122 @@
+import { computed, defineComponent, h, onBeforeUnmount, onMounted, ref } from "vue";
+import { EMPTY_REALTIME_SOCKET, useRealtimeSocket } from "../composables/useRealtimeEvent.js";
+
+const ROOT_STYLE = Object.freeze({
+  alignItems: "center",
+  display: "inline-flex",
+  height: "32px",
+  justifyContent: "center",
+  width: "32px"
+});
+
+const DOT_STYLE = Object.freeze({
+  borderRadius: "9999px",
+  boxShadow: "0 0 0 2px rgba(255, 255, 255, 0.82)",
+  display: "block",
+  height: "10px",
+  width: "10px"
+});
+
+const SR_ONLY_STYLE = Object.freeze({
+  border: "0",
+  clip: "rect(0, 0, 0, 0)",
+  clipPath: "inset(50%)",
+  height: "1px",
+  margin: "-1px",
+  overflow: "hidden",
+  padding: "0",
+  position: "absolute",
+  whiteSpace: "nowrap",
+  width: "1px"
+});
+
+function resolveTooltipText({ realtimeAvailable, connected }) {
+  if (!realtimeAvailable) {
+    return "Realtime is unavailable. Live updates are disabled for this page.";
+  }
+  if (connected) {
+    return "Realtime is connected. Live updates are active.";
+  }
+  return "Realtime is disconnected. The client will keep trying to reconnect.";
+}
+
+const RealtimeConnectionIndicator = defineComponent({
+  name: "RealtimeConnectionIndicator",
+  setup() {
+    const socket = useRealtimeSocket({ required: false });
+    const connected = ref(Boolean(socket?.connected));
+    const realtimeAvailable = socket !== EMPTY_REALTIME_SOCKET;
+    let detach = null;
+
+    const tooltipText = computed(() => {
+      return resolveTooltipText({
+        realtimeAvailable,
+        connected: connected.value
+      });
+    });
+
+    const statusLabel = computed(() => (connected.value ? "Realtime connected" : "Realtime disconnected"));
+
+    const dotStyle = computed(() => ({
+      ...DOT_STYLE,
+      backgroundColor: connected.value ? "#22c55e" : "#ef4444"
+    }));
+
+    function syncConnected(nextState) {
+      connected.value = Boolean(nextState);
+    }
+
+    function bindSocketStatusListeners() {
+      if (!realtimeAvailable || typeof socket.on !== "function") {
+        syncConnected(false);
+        return;
+      }
+
+      syncConnected(socket.connected);
+
+      const onConnect = () => syncConnected(true);
+      const onDisconnect = () => syncConnected(false);
+      const onConnectError = () => syncConnected(false);
+
+      socket.on("connect", onConnect);
+      socket.on("disconnect", onDisconnect);
+      socket.on("connect_error", onConnectError);
+
+      detach = () => {
+        if (typeof socket.off === "function") {
+          socket.off("connect", onConnect);
+          socket.off("disconnect", onDisconnect);
+          socket.off("connect_error", onConnectError);
+        }
+      };
+    }
+
+    onMounted(() => {
+      bindSocketStatusListeners();
+    });
+
+    onBeforeUnmount(() => {
+      if (typeof detach === "function") {
+        detach();
+      }
+      detach = null;
+    });
+
+    return () =>
+      h(
+        "span",
+        {
+          style: ROOT_STYLE,
+          title: tooltipText.value,
+          "aria-label": statusLabel.value
+        },
+        [
+          h("span", { style: dotStyle.value, "aria-hidden": "true" }),
+          h("span", { style: SR_ONLY_STYLE }, statusLabel.value)
+        ]
+      );
+  }
+});
+
+export { RealtimeConnectionIndicator };
+export default RealtimeConnectionIndicator;