@jskit-ai/realtime 0.1.219 → 0.1.221

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/realtime",
-  "version": "0.1.219",
+  "version": "0.1.221",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -20,8 +20,8 @@
     "socket.io-client": "^4.8.3"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.222",
-    "@jskit-ai/shell-web": "0.1.226",
+    "@jskit-ai/kernel": "0.1.224",
+    "@jskit-ai/shell-web": "0.1.228",
     "vue": "^3.5.13"
   },
   "description": "Thin, generic realtime runtime wrappers for socket.io server and client.",
@@ -79,7 +79,7 @@
           },
           {
             "subpath": "./client/composables/*",
-            "summary": "Exports component-level realtime socket composables."
+            "summary": "Exports realtime socket composables with subscriptions owned by their Vue effect scope."
           }
         ],
         "capabilities": {

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

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.1.219",
-    "@jskit-ai/shell-web": "0.1.226"
+    "@jskit-ai/realtime": "0.1.221",
+    "@jskit-ai/shell-web": "0.1.228"
   }
 }

package/src/client/composables/useRealtimeEvent.js

@@ -1,4 +1,4 @@
-import { inject, onBeforeUnmount, ref, unref, watch } from "vue";
+import { inject, onScopeDispose, ref, unref, watch } from "vue";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 const EMPTY_REALTIME_SOCKET = Object.freeze({
@@ -130,9 +130,7 @@ function useRealtimeEvent({
     { immediate: true }
   );
 
-  onBeforeUnmount(() => {
-    detach();
-  });
+  onScopeDispose(detach);
 
   return Object.freeze({
     active

package/src/server/RealtimeProvider.js

@@ -3,8 +3,10 @@ import { createProviderLogger } from "@jskit-ai/kernel/shared/support/providerLo
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { createRealtimeDelivery } from "./realtimeDelivery.js";
 import {
+  createSocketRequest,
   realtimeAuthenticationRequired,
-  registerSocketAudienceBootstrap
+  registerSocketAudienceBootstrap,
+  revalidateSocket
 } from "./realtimeAudience.js";
 import {
   closeSocketIoRedisConnections,
@@ -32,6 +34,64 @@ function debugEnabled(config, env) {
 
 function createRealtimeCapability({ io }) {
   const capability = Object.freeze({
+    onConnection(listener) {
+      if (typeof listener !== "function") throw new TypeError("Realtime connection listener must be a function.");
+      const state = stateByCapability.get(capability);
+      if (!state) throw new Error("Realtime runtime state is unavailable.");
+      const releases = new Map();
+      function attach(socket) {
+        if (releases.has(socket)) return;
+        let detach;
+        async function readRequest() {
+          const request = createSocketRequest(socket);
+          const actor = await revalidateSocket({
+            socket, request, authService: state.authService, workspaces: state.workspaces
+          });
+          if (!socket.connected || (!actor && realtimeAuthenticationRequired(state.authService))) {
+            throw Object.assign(new Error("Authentication required."), { statusCode: 401 });
+          }
+          if (actor) request.user = actor;
+          return request;
+        }
+        function release() {
+          socket.off("disconnect", release);
+          releases.delete(socket);
+          try { detach?.(); }
+          catch (error) {
+            state.providerLogger.warn({ error: String(error?.message || error) }, "Realtime connection cleanup failed.");
+          }
+        }
+        try {
+          detach = listener({
+            socket,
+            // Hosts authorize this real connection request through their own
+            // action boundary. Reading it alone does not grant local access.
+            readRequest,
+            async authenticate() {
+              const request = await readRequest();
+              if (!request.user) throw Object.assign(new Error("Authentication required."), { statusCode: 401 });
+              return request;
+            }
+          });
+          if (detach != null && typeof detach !== "function") {
+            throw new TypeError("Realtime connection listeners must return a cleanup function or undefined.");
+          }
+          releases.set(socket, release);
+          socket.on("disconnect", release);
+        } catch (error) {
+          state.providerLogger.warn({ error: String(error?.message || error) }, "Realtime connection listener failed.");
+        }
+      }
+      function stop() {
+        io.off("connection", attach);
+        for (const release of [...releases.values()]) release();
+        state.connectionListeners.delete(stop);
+      }
+      state.connectionListeners.add(stop);
+      io.on("connection", attach);
+      for (const socket of io.sockets.sockets.values()) attach(socket);
+      return stop;
+    },
     diagnostics() {
       const state = stateByCapability.get(capability);
       return Object.freeze({
@@ -69,6 +129,9 @@ const RealtimeProvider = defineProvider({
     const realtime = createRealtimeCapability({ io });
     stateByCapability.set(realtime, {
       authenticationRequired: false,
+      authService: null,
+      workspaces: null,
+      connectionListeners: new Set(),
       delivery: null,
       io,
       providerLogger,
@@ -79,6 +142,8 @@ const RealtimeProvider = defineProvider({
   async boot({ authService, database, env, events, workspaces }, { outputs }) {
     const state = stateByCapability.get(outputs.realtime);
     if (!state) throw new Error("Realtime runtime state is unavailable.");
+    state.authService = authService;
+    state.workspaces = workspaces;
     state.delivery = createRealtimeDelivery({
       io: state.io, database, logger: state.providerLogger, authService, workspaces
     });
@@ -104,6 +169,7 @@ const RealtimeProvider = defineProvider({
   async shutdown(_dependencies, { outputs }) {
     const state = stateByCapability.get(outputs.realtime);
     if (!state) return;
+    for (const release of [...state.connectionListeners]) release();
     state.delivery?.stop();
     await closeSocketIoServer(state.io);
     await closeSocketIoRedisConnections(state.redisConnection || {});

package/src/server/realtimeAudience.js

@@ -182,8 +182,7 @@ function parseCookieHeader(value = "") {
   return cookies;
 }
 
-async function resolveSocketActor(authService, socket) {
-  if (typeof authService?.authenticateRequest !== "function") return null;
+function createSocketRequest(socket) {
   const handshakeHeaders = socket?.handshake?.headers || {};
   const requestHeaders = socket?.request?.headers || {};
   const host = normalizeText(handshakeHeaders.host || requestHeaders.host);
@@ -201,6 +200,11 @@ async function resolveSocketActor(authService, socket) {
   if (Object.keys(headers).length > 0) request.headers = headers;
   request.socket = { encrypted: socket?.request?.socket?.encrypted === true };
   if (remoteAddress) request.socket.remoteAddress = remoteAddress;
+  return request;
+}
+
+async function resolveSocketActor(authService, socket, request = createSocketRequest(socket)) {
+  if (typeof authService?.authenticateRequest !== "function") return null;
   const result = await authService.authenticateRequest(request);
   const id = result?.authenticated === true
     ? normalizeRecordId(result?.actor?.id, { fallback: null }) : null;
@@ -268,8 +272,8 @@ function registerSocketAudienceBootstrap({ io, logger, authService = null, works
   });
 }
 
-async function revalidateSocket({ socket, authService, workspaces = null }) {
-  const actor = await resolveSocketActor(authService, socket);
+async function revalidateSocket({ socket, authService, workspaces = null, request }) {
+  const actor = await resolveSocketActor(authService, socket, request);
   const previousActorId = socket.data?.actorId;
   if ((!actor && realtimeAuthenticationRequired(authService)) ||
       (previousActorId && previousActorId !== actor?.id)) {
@@ -292,6 +296,7 @@ async function revalidateSocket({ socket, authService, workspaces = null }) {
 }
 
 export {
+  createSocketRequest,
   realtimeAuthenticationRequired,
   revalidateSocket,
   registerSocketAudienceBootstrap,

package/src/server/runtime.js

@@ -2,11 +2,32 @@ import { Server as SocketIoServer } from "socket.io";
 import { createAdapter as createSocketIoRedisAdapter } from "@socket.io/redis-adapter";
 import { createClient as createRedisClient } from "redis";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
 
 const SOCKET_IO_PATH = "/socket.io";
 const REDIS_URL_ENV_KEY = "REDIS_URL";
 const REDIS_NAMESPACE_ENV_KEY = "REDIS_NAMESPACE";
 
+function toRequestPathname(urlValue) {
+  const rawUrl = String(urlValue || "").trim() || "/";
+  try {
+    return normalizePathname(new URL(rawUrl, "http://localhost").pathname || "/");
+  } catch {
+    return normalizePathname(rawUrl.split("?")[0] || "/");
+  }
+}
+
+function registerSocketIoUpgradeHandoff(fastify) {
+  if (typeof fastify?.addHook !== "function") return;
+  fastify.addHook("onRequest", async (request, reply) => {
+    if (request?.ws !== true) return;
+    if (toRequestPathname(request?.raw?.url || request?.url) !== SOCKET_IO_PATH) return;
+    // The WebSocket plugin also routes this upgrade through Fastify. Leave it
+    // to Socket.IO instead of letting Fastify's missing-route response close it.
+    reply.hijack();
+  });
+}
+
 function resolveHttpServer({ httpServer = null, fastify = null } = {}) {
   if (httpServer && typeof httpServer === "object") {
     return httpServer;
@@ -38,6 +59,7 @@ function createSocketIoServer({
     ...source,
     path: SOCKET_IO_PATH
   };
+  registerSocketIoUpgradeHandoff(fastify);
   return new ServerCtor(server, normalizedOptions);
 }
 

package/test/providerRuntime.test.js

@@ -1,17 +1,104 @@
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
+import { once } from "node:events";
 import test from "node:test";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import { EventProvider } from "@jskit-ai/kernel/server/runtime";
 import { CLIENT_APP_CONFIG_GLOBAL_KEY, setClientAppConfig } from "../../kernel/client/appConfig.js";
 import { RealtimeClientProvider } from "../src/client/RealtimeClientProvider.js";
 import { RealtimeProvider } from "../src/server/RealtimeProvider.js";
+import { createSocketIoClient } from "../src/client/runtime.js";
 import { registerSocketAudienceBootstrap } from "../src/server/realtimeAudience.js";
 import { createRealtimeDelivery } from "../src/server/realtimeDelivery.js";
 import { attachDeferredAuthService, createDeferredAuthService } from "../../auth-core/src/server/deferredAuthService.js";
 
 const logger = Object.freeze({ debug() {}, info() {}, warn() {}, error() {} });
 
+async function connectionRequestFixture(t, authService = null) {
+  const http = createServer();
+  const connections = [];
+  const clients = [];
+  let realtime;
+  const probe = defineProvider({ id: "test.connection.request", requires: { realtime: "runtime.realtime" },
+    setup(dependencies) { realtime = dependencies.realtime; return {}; } });
+  const runtime = createCapabilityRuntime({ providers: [EventProvider, RealtimeProvider, probe], inputs: {
+    "runtime.config": {}, "runtime.env": {}, "runtime.fastify": { server: http }, "runtime.logger": logger,
+    ...(authService ? { "auth.service": authService } : {})
+  } });
+  await runtime.start();
+  const release = realtime.onConnection(connection => { connections.push(connection); });
+  t.after(async () => {
+    for (const client of clients) client.disconnect();
+    release();
+    await runtime.shutdown();
+  });
+  http.listen(0, "127.0.0.1");
+  await once(http, "listening");
+  const url = `http://127.0.0.1:${http.address().port}`;
+  return {
+    url,
+    async connect() {
+      const client = createSocketIoClient({ url, options: { transports: ["websocket"], autoConnect: false,
+        reconnection: false, extraHeaders: { Cookie: "session=fixture-session", Origin: url } } });
+      clients.push(client);
+      const connected = once(client, "connect", { signal: AbortSignal.timeout(5_000) });
+      client.connect();
+      await connected;
+      return { client, connection: connections.at(-1) };
+    }
+  };
+}
+
+test("connection request access preserves the local handshake without weakening authenticate", async t => {
+  const f = await connectionRequestFixture(t);
+  const { client, connection } = await f.connect();
+  const request = await connection.readRequest();
+  assert.deepEqual(request.cookies, { session: "fixture-session" });
+  assert.equal(request.headers.host, new URL(f.url).host);
+  assert.equal(request.headers.origin, f.url);
+  assert.equal(request.socket.remoteAddress, "127.0.0.1");
+  assert.equal(Object.hasOwn(request, "user"), false);
+  await assert.rejects(connection.authenticate(), { statusCode: 401 });
+  assert.equal(client.connected, true, "The host may still authorize a local request itself");
+  request.headers.origin = "https://forged.invalid";
+  request.cookies.session = "forged";
+  request.user = { id: "42" };
+  const next = await connection.readRequest();
+  assert.equal(next.headers.origin, f.url);
+  assert.equal(next.cookies.session, "fixture-session");
+  assert.equal(Object.hasOwn(next, "user"), false);
+  const disconnected = once(connection.socket, "disconnect", { signal: AbortSignal.timeout(5_000) });
+  client.disconnect();
+  await disconnected;
+  await assert.rejects(connection.readRequest(), { statusCode: 401 });
+});
+
+test("connection request access revalidates required hosted sessions and retires changed actors", async t => {
+  const sessions = new Map();
+  const reads = [];
+  const f = await connectionRequestFixture(t, {
+    realtime: { requireAuthentication: true },
+    async authenticateRequest(request) {
+      reads.push(request.cookies.session);
+      const actor = sessions.get(request.cookies.session);
+      return { authenticated: Boolean(actor), actor };
+    }
+  });
+  for (const nextActor of [null, { id: "43" }]) {
+    sessions.set("fixture-session", { id: "42", label: "Current actor" });
+    const { client, connection } = await f.connect();
+    assert.deepEqual((await connection.readRequest()).user, { id: "42", label: "Current actor" });
+    assert.equal((await connection.authenticate()).user.id, "42");
+    sessions.set("fixture-session", nextActor);
+    const disconnected = once(client, "disconnect", { signal: AbortSignal.timeout(5_000) });
+    await assert.rejects(connection.readRequest(), { statusCode: 401 });
+    await disconnected;
+    assert.equal(connection.socket.connected, false);
+  }
+  assert.ok(reads.length >= 8, "Every request facility call rechecks the current session");
+  assert.ok(reads.every(value => value === "fixture-session"));
+});
+
 test("RealtimeProvider waits for authentication boot before accessing the auth service", async () => {
   const authService = createDeferredAuthService();
   const authProvider = defineProvider({

package/test/realtimeEvent.test.js

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+import { createRenderer, effectScope, h, nextTick, ref } from "vue";
+import { useRealtimeEvent } from "../src/client/composables/useRealtimeEvent.js";
+
+const renderer = createRenderer({
+  createElement: () => ({}), createText: () => ({}), createComment: () => ({}),
+  setElementText() {}, setText() {}, insert() {}, remove() {}, patchProp() {},
+  parentNode() {}, nextSibling() {}
+});
+
+test("a component listener detaches on unmount", () => {
+  const socket = new EventEmitter();
+  const received = [];
+  let listener;
+  const app = renderer.createApp({ setup() {
+    listener = useRealtimeEvent({ event: "reply", onEvent: ({ payload }) => received.push(payload) });
+    return () => h("div");
+  } });
+  app.provide("jskit.realtime.runtime.client.socket", socket);
+  app.mount({});
+  socket.emit("reply", "first");
+  const wasActive = listener.active.value;
+  app.unmount();
+  assert.equal(wasActive, true);
+  socket.emit("reply", "late");
+  assert.equal(socket.listenerCount("reply"), 0);
+  assert.equal(listener.active.value, false);
+  assert.deepEqual(received, ["first"]);
+});
+
+test("a retained scope keeps its listener after screen unmount and releases it when stopped", async t => {
+  const socket = new EventEmitter();
+  const received = [];
+  const enabled = ref(true);
+  const event = ref("reply");
+  const retained = effectScope(true);
+  t.after(() => retained.stop());
+  const app = renderer.createApp({ setup() {
+    retained.run(() => useRealtimeEvent({ event, enabled, onEvent: ({ payload }) => received.push(payload) }));
+    return () => h("div");
+  } });
+  app.provide("jskit.realtime.runtime.client.socket", socket);
+  app.mount({});
+  app.unmount();
+  socket.emit("reply", "after navigation");
+  assert.deepEqual(received, ["after navigation"]);
+  enabled.value = false;
+  await nextTick();
+  assert.equal(socket.listenerCount("reply"), 0);
+  enabled.value = true;
+  event.value = "completed";
+  await nextTick();
+  assert.equal(socket.listenerCount("reply"), 0);
+  assert.equal(socket.listenerCount("completed"), 1);
+  socket.emit("completed", "saved answer");
+  assert.deepEqual(received, ["after navigation", "saved answer"]);
+  retained.stop();
+  assert.equal(socket.listenerCount("completed"), 0);
+  enabled.value = false;
+  enabled.value = true;
+  await nextTick();
+  assert.equal(socket.listenerCount("completed"), 0);
+});

package/test/serverRuntime.test.js

@@ -51,6 +51,41 @@ test("createSocketIoServer uses provided http server and fixed socket path", ()
   });
 });
 
+test("createSocketIoServer hands only its own Fastify WebSocket upgrades to Socket.IO", async () => {
+  const server = {};
+  const events = [];
+  let handoff;
+  const fastify = {
+    server,
+    addHook(name, handler) {
+      assert.equal(name, "onRequest");
+      handoff = handler;
+      events.push("handoff");
+    }
+  };
+  class FakeServer {
+    constructor(httpServer) {
+      assert.equal(httpServer, server);
+      events.push("socket.io");
+    }
+  }
+  createSocketIoServer({ fastify, ServerCtor: FakeServer });
+  assert.deepEqual(events, ["handoff", "socket.io"]);
+  for (const [request, expected] of [
+    [{ ws: true, raw: { url: "/socket.io/?EIO=4&transport=websocket" } }, true],
+    [{ ws: true, url: "/socket.io" }, true],
+    [{ ws: false, raw: { url: "/socket.io/" } }, false],
+    [{ raw: { url: "/socket.io/" } }, false],
+    [{ ws: true, raw: { url: "/socket.io-other" } }, false],
+    [{ ws: true, raw: { url: "/api/conversations/planning/voice" }, url: "/socket.io" }, false],
+    [{ ws: true }, false]
+  ]) {
+    let hijacked = false;
+    await handoff(request, { hijack() { hijacked = true; } });
+    assert.equal(hijacked, expected, JSON.stringify(request));
+  }
+});
+
 test("realtime leaves slow application upgrades and access denials to their route owner", { timeout: 5_000 }, async (t) => {
   const server = createServer();
   const sockets = new Set();