@jskit-ai/realtime 0.1.155 → 0.1.157

package/src/server/RealtimeProvider.js

@@ -0,0 +1,98 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { createRealtimeDelivery } from "./realtimeDelivery.js";
+import { registerSocketAudienceBootstrap } from "./realtimeAudience.js";
+import {
+  closeSocketIoRedisConnections,
+  closeSocketIoServer,
+  configureSocketIoRedisAdapter,
+  createSocketIoServer,
+  resolveRealtimeRedisNamespace,
+  resolveRealtimeRedisUrl
+} from "./runtime.js";
+
+const stateByCapability = new WeakMap();
+
+function parseDebugFlag(value, fallback = null) {
+  if (typeof value === "boolean") return value;
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) return fallback;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
+function debugEnabled(config, env) {
+  return parseDebugFlag(env?.JSKIT_REALTIME_DEBUG, parseDebugFlag(config?.realtime?.debug, false));
+}
+
+function createRealtimeCapability({ io }) {
+  const capability = Object.freeze({
+    diagnostics() {
+      const state = stateByCapability.get(capability);
+      return Object.freeze({
+        connectedClients: Number.isInteger(Number(io?.engine?.clientsCount))
+          ? Number(io.engine.clientsCount)
+          : null,
+        redisConfigured: state?.redisConnection?.enabled === true
+      });
+    }
+  });
+  return capability;
+}
+
+const RealtimeProvider = defineProvider({
+  id: "runtime.realtime",
+  requires: {
+    config: "runtime.config",
+    env: "runtime.env",
+    events: "runtime.events",
+    fastify: "runtime.fastify",
+    logger: "runtime.logger"
+  },
+  optional: {
+    authService: "auth.service",
+    database: "runtime.database",
+    workspaces: "workspaces.core"
+  },
+  provides: {
+    realtime: "runtime.realtime"
+  },
+  setup({ config, database, env, events, fastify, logger }) {
+    const io = createSocketIoServer({ fastify });
+    const providerLogger = createProviderLogger(logger, { debugEnabled: debugEnabled(config, env) });
+    const delivery = createRealtimeDelivery({ io, database, logger: providerLogger });
+    const realtime = createRealtimeCapability({ io });
+    stateByCapability.set(realtime, { io, providerLogger, redisConnection: null });
+    events.register({
+      id: "runtime.realtime.delivery",
+      matches: (event) => Boolean(normalizeText(event?.realtime?.event)),
+      handle: delivery.handle
+    });
+    return { realtime };
+  },
+  async boot({ authService, env, workspaces }, { outputs }) {
+    const state = stateByCapability.get(outputs.realtime);
+    if (!state) throw new Error("Realtime runtime state is unavailable.");
+    registerSocketAudienceBootstrap({
+      io: state.io,
+      logger: state.providerLogger,
+      authService,
+      workspaces
+    });
+    state.redisConnection = await configureSocketIoRedisAdapter(state.io, {
+      redisUrl: resolveRealtimeRedisUrl(env),
+      redisNamespace: resolveRealtimeRedisNamespace(env)
+    });
+  },
+  async shutdown(_dependencies, { outputs }) {
+    const state = stateByCapability.get(outputs.realtime);
+    if (!state) return;
+    await closeSocketIoServer(state.io);
+    await closeSocketIoRedisConnections(state.redisConnection || {});
+    stateByCapability.delete(outputs.realtime);
+  }
+});
+
+export { RealtimeProvider };

package/src/server/realtimeAudience.js

@@ -0,0 +1,220 @@
+import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const ALL_CLIENTS_ROOM = "clients";
+const ALL_USERS_ROOM = "users";
+
+function normalizeArray(value) {
+  const queue = Array.isArray(value) ? [...value] : [value];
+  const list = [];
+  while (queue.length > 0) {
+    const entry = queue.shift();
+    if (Array.isArray(entry)) queue.push(...entry);
+    else if (entry != null) list.push(entry);
+  }
+  return list;
+}
+
+function roomForUser(userId) {
+  return `user:${String(userId || "").trim()}`;
+}
+
+function roomForWorkspace(workspaceId) {
+  return `workspace:${String(workspaceId || "").trim()}`;
+}
+
+function roomForWorkspaceUser(workspaceId, userId) {
+  return `workspace:${String(workspaceId || "").trim()}:user:${String(userId || "").trim()}`;
+}
+
+function resolveScopeWorkspaceId(scope = {}) {
+  const kind = normalizeText(scope?.kind).toLowerCase();
+  if (kind === "workspace") return normalizeRecordId(scope.id, { fallback: null });
+  if (kind === "workspace_user") {
+    return normalizeRecordId(scope.workspaceId || scope.id, { fallback: null });
+  }
+  return normalizeRecordId(scope?.workspaceId, { fallback: null });
+}
+
+function resolveScopeUserId(scope = {}) {
+  const kind = normalizeText(scope?.kind).toLowerCase();
+  if (kind === "user") return normalizeRecordId(scope.id, { fallback: null });
+  return normalizeRecordId(scope?.userId, { fallback: null });
+}
+
+function applyAudiencePreset(preset, { event, rooms, flags, logger }) {
+  const normalized = normalizeText(preset).toLowerCase();
+  if (!normalized || normalized === "none") return;
+  if (normalized === "all_clients") {
+    flags.broadcastAllClients = true;
+    return;
+  }
+  if (normalized === "all_users") {
+    rooms.add(ALL_USERS_ROOM);
+    return;
+  }
+  if (normalized === "actor_user") {
+    const actorId = normalizeRecordId(event?.actorId, { fallback: null });
+    if (actorId) rooms.add(roomForUser(actorId));
+    return;
+  }
+  if (normalized === "all_workspace_users") {
+    const workspaceId = resolveScopeWorkspaceId(event?.scope);
+    if (workspaceId) rooms.add(roomForWorkspace(workspaceId));
+    else logger.warn({ audience: normalized, scope: event?.scope || null }, "Realtime audience requires a workspace scope.");
+    return;
+  }
+  if (normalized === "event_scope") {
+    const scopeKind = normalizeText(event?.scope?.kind).toLowerCase();
+    const workspaceId = resolveScopeWorkspaceId(event?.scope);
+    const userId = resolveScopeUserId(event?.scope);
+    if (scopeKind === "workspace" && workspaceId) rooms.add(roomForWorkspace(workspaceId));
+    else if (scopeKind === "workspace_user" && workspaceId && userId) {
+      rooms.add(roomForWorkspaceUser(workspaceId, userId));
+    } else if (scopeKind === "user" && userId) rooms.add(roomForUser(userId));
+    else rooms.add(ALL_USERS_ROOM);
+    return;
+  }
+  logger.warn({ audience: normalized }, "Realtime ignored an unknown audience preset.");
+}
+
+function addAudienceRooms(selection, state) {
+  if (!selection || typeof selection !== "object" || Array.isArray(selection)) return;
+  const { event, rooms, flags, logger } = state;
+  if (Object.hasOwn(selection, "preset")) {
+    applyAudiencePreset(selection.preset, state);
+  }
+  if (selection.broadcast === true) flags.broadcastAllClients = true;
+
+  const directRoom = normalizeText(selection.room);
+  if (directRoom) rooms.add(directRoom);
+  for (const entry of normalizeArray(selection.rooms)) {
+    const room = normalizeText(entry);
+    if (room) rooms.add(room);
+  }
+
+  const directUserId = normalizeRecordId(selection.userId, { fallback: null });
+  if (directUserId) rooms.add(roomForUser(directUserId));
+  for (const entry of normalizeArray(selection.userIds)) {
+    const userId = normalizeRecordId(entry, { fallback: null });
+    if (userId) rooms.add(roomForUser(userId));
+  }
+
+  const directWorkspaceId = normalizeRecordId(selection.workspaceId, { fallback: null });
+  if (directWorkspaceId) rooms.add(roomForWorkspace(directWorkspaceId));
+  for (const entry of normalizeArray(selection.workspaceIds)) {
+    const workspaceId = normalizeRecordId(entry, { fallback: null });
+    if (workspaceId) rooms.add(roomForWorkspace(workspaceId));
+  }
+
+  for (const entry of normalizeArray([selection.workspaceUser, selection.workspaceUsers])) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const workspaceId = normalizeRecordId(entry.workspaceId, { fallback: null });
+    const userId = normalizeRecordId(entry.userId, { fallback: null });
+    if (workspaceId && userId) rooms.add(roomForWorkspaceUser(workspaceId, userId));
+  }
+
+  if (!event || !logger) throw new TypeError("Realtime audience state is incomplete.");
+}
+
+function collectUserIds(rows) {
+  const ids = new Set();
+  for (const row of normalizeArray(rows)) {
+    const rawId = typeof row === "number" ? row : row?.userId || row?.user_id || row?.id;
+    const id = normalizeRecordId(rawId, { fallback: null });
+    if (id) ids.add(id);
+  }
+  return [...ids];
+}
+
+async function resolveAudienceTargets(audience, event, { database = null, logger }) {
+  const rooms = new Set();
+  const flags = { broadcastAllClients: false };
+  const state = { event, rooms, flags, logger };
+
+  for (const entry of normalizeArray(audience)) {
+    if (typeof entry === "string") {
+      applyAudiencePreset(entry, state);
+      continue;
+    }
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    addAudienceRooms(entry, state);
+    if (typeof entry.userQuery === "function") {
+      if (typeof database?.knex !== "function") {
+        logger.warn("Realtime audience userQuery requires runtime.database.");
+        continue;
+      }
+      const rows = await entry.userQuery({ knex: database.knex, event });
+      for (const userId of collectUserIds(rows)) rooms.add(roomForUser(userId));
+    }
+  }
+
+  return Object.freeze({
+    broadcastAllClients: flags.broadcastAllClients,
+    rooms: Object.freeze([...rooms])
+  });
+}
+
+function parseCookieHeader(value = "") {
+  const cookies = {};
+  for (const entry of String(value || "").split(";")) {
+    const separator = entry.indexOf("=");
+    if (separator < 1) continue;
+    const key = entry.slice(0, separator).trim();
+    if (!key) continue;
+    const rawValue = entry.slice(separator + 1).trim();
+    try {
+      cookies[key] = decodeURIComponent(rawValue);
+    } catch {
+      cookies[key] = rawValue;
+    }
+  }
+  return cookies;
+}
+
+async function resolveSocketActorId(authService, socket) {
+  if (typeof authService?.authenticateRequest !== "function") return null;
+  const handshakeHeaders = socket?.handshake?.headers || {};
+  const requestHeaders = socket?.request?.headers || {};
+  const host = normalizeText(handshakeHeaders.host || requestHeaders.host);
+  const remoteAddress = normalizeText(
+    socket?.request?.socket?.remoteAddress || socket?.conn?.remoteAddress || socket?.handshake?.address
+  );
+  const request = {
+    cookies: parseCookieHeader(handshakeHeaders.cookie || requestHeaders.cookie)
+  };
+  if (host) request.headers = { host };
+  if (remoteAddress) request.socket = { remoteAddress };
+  const result = await authService.authenticateRequest(request);
+  return result?.authenticated === true
+    ? normalizeRecordId(result?.actor?.id, { fallback: null })
+    : null;
+}
+
+function registerSocketAudienceBootstrap({ io, logger, authService = null, workspaces = null }) {
+  if (typeof io?.on !== "function") return;
+  io.on("connection", async (socket) => {
+    try {
+      socket.join(ALL_CLIENTS_ROOM);
+      const actorId = await resolveSocketActorId(authService, socket);
+      if (!actorId) return;
+      socket.data = socket.data && typeof socket.data === "object" ? socket.data : {};
+      socket.data.actorId = actorId;
+      socket.join(ALL_USERS_ROOM);
+      socket.join(roomForUser(actorId));
+      const repository = workspaces?.repositories?.workspaceMemberships;
+      const workspaceIds = typeof repository?.listActiveWorkspaceIdsByUserId === "function"
+        ? await repository.listActiveWorkspaceIdsByUserId(actorId)
+        : [];
+      for (const rawId of normalizeArray(workspaceIds)) {
+        const workspaceId = normalizeRecordId(rawId, { fallback: null });
+        if (!workspaceId) continue;
+        socket.join(roomForWorkspace(workspaceId));
+        socket.join(roomForWorkspaceUser(workspaceId, actorId));
+      }
+    } catch (error) {
+      logger.warn({ error: String(error?.message || error) }, "Realtime socket audience bootstrap failed.");
+    }
+  });
+}
+
+export { registerSocketAudienceBootstrap, resolveAudienceTargets };

package/src/server/realtimeDelivery.js

@@ -0,0 +1,41 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveAudienceTargets } from "./realtimeAudience.js";
+
+function publicRealtimePayload(event) {
+  const { realtime, ...canonical } = event && typeof event === "object" ? event : {};
+  const payload = realtime?.payload;
+  if (payload != null && (!payload || typeof payload !== "object" || Array.isArray(payload))) {
+    throw new TypeError("Realtime event payload must be an object when provided.");
+  }
+  return Object.freeze({ ...(payload || {}), ...canonical });
+}
+
+function createRealtimeDelivery({ io, database = null, logger }) {
+  if (!io || typeof io.emit !== "function" || typeof io.to !== "function") {
+    throw new TypeError("Realtime delivery requires a Socket.IO server.");
+  }
+  if (!logger || typeof logger.warn !== "function") {
+    throw new TypeError("Realtime delivery requires a logger.");
+  }
+
+  return Object.freeze({
+    async handle(event = {}) {
+      const eventName = normalizeText(event?.realtime?.event);
+      if (!eventName) return;
+      const targets = await resolveAudienceTargets(event.realtime.audience, event, { database, logger });
+      const payload = publicRealtimePayload(event);
+      if (targets.broadcastAllClients) io.emit(eventName, payload);
+      for (const room of targets.rooms) io.to(room).emit(eventName, payload);
+      logger.debug({
+        socketEvent: eventName,
+        rooms: targets.rooms,
+        broadcastAllClients: targets.broadcastAllClients,
+        connectedClients: Number.isInteger(Number(io?.engine?.clientsCount))
+          ? Number(io.engine.clientsCount)
+          : null
+      }, "Realtime delivered an action event.");
+    }
+  });
+}
+
+export { createRealtimeDelivery };

package/test/entrypoints.boundary.test.js

@@ -1,20 +1,20 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import * as serverApi from "../src/server/RealtimeServiceProvider.js";
+import * as serverApi from "../src/server/RealtimeProvider.js";
 import * as serverRuntimeApi from "../src/server/runtime.js";
 import * as clientApi from "../src/client/RealtimeClientProvider.js";
 import * as clientRuntimeApi from "../src/client/runtime.js";
-import * as clientListenerApi from "../src/client/listeners.js";
 
 test("server entrypoint exports provider only", () => {
-  assert.equal(typeof serverApi.RealtimeServiceProvider, "function");
-  assert.deepEqual(Object.keys(serverApi).sort(), ["RealtimeServiceProvider"]);
+  assert.equal(typeof serverApi.RealtimeProvider, "object");
+  assert.deepEqual(Object.keys(serverApi).sort(), ["RealtimeProvider"]);
 });
 
 test("client entrypoint exports provider only", () => {
-  assert.equal(typeof clientApi.RealtimeClientProvider, "function");
-  assert.deepEqual(Object.keys(clientApi).sort(), ["RealtimeClientProvider"]);
+  assert.equal(typeof clientApi.RealtimeClientProvider, "object");
+  assert.equal(typeof clientApi.resolveRealtimeClientConfig, "function");
+  assert.deepEqual(Object.keys(clientApi).sort(), ["RealtimeClientProvider", "resolveRealtimeClientConfig"]);
 });
 
 test("server runtime entrypoint exports server-only helpers", () => {
@@ -26,9 +26,3 @@ test("client runtime entrypoint exports client-only helpers", () => {
   assert.equal(typeof clientRuntimeApi.createSocketIoClient, "function");
   assert.equal(typeof clientRuntimeApi.disconnectSocketIoClient, "function");
 });
-
-test("client listeners entrypoint exports realtime listener registration helpers", () => {
-  assert.equal(typeof clientListenerApi.registerRealtimeClientListener, "function");
-  assert.equal(typeof clientListenerApi.resolveRealtimeClientListeners, "function");
-  assert.equal(typeof clientListenerApi.normalizeRealtimeClientListener, "function");
-});