@holo-js/flux 0.1.9 → 0.2.0

package/dist/index.d.ts

@@ -84,6 +84,15 @@ interface FluxClient<TManifest extends GeneratedBroadcastManifest = GeneratedBro
 type PusherConnectorOptions = {
     readonly transport?: 'mock';
 };
+type HoloWebSocketConnectorOptions = {
+    readonly key?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly scheme?: 'http' | 'https' | 'ws' | 'wss';
+    readonly authEndpoint?: string;
+    readonly configEndpoint?: string;
+};
 type PusherConnectorDebug = {
     emitEvent(channel: string, event: string, payload: BroadcastJsonObject): void;
     emitNotification(channel: string, payload: BroadcastJsonObject): void;
@@ -96,6 +105,7 @@ type ConnectorDebugCarrier = {
 type SubscriptionRegistry = Map<string, Set<() => void>>;
 declare function createUnavailableConnector(): FluxConnector;
 declare function createPusherConnector(options?: PusherConnectorOptions): FluxConnector & ConnectorDebugCarrier;
+declare function createHoloWebSocketConnector(options?: HoloWebSocketConnectorOptions): FluxConnector;
 declare function createSubscription<TManifest extends GeneratedBroadcastManifest, TChannel extends string>(channelName: TChannel, kind: FluxChannelKind, connector: FluxConnector, registry: SubscriptionRegistry): FluxSubscription<TManifest, TChannel> & {
     readonly __presenceMembers: () => readonly BroadcastJsonObject[];
     readonly __onPresenceChange: (callback: (members: readonly BroadcastJsonObject[]) => void) => () => void;
@@ -107,6 +117,7 @@ declare function getFluxClient(): FluxClient;
 declare function resetFluxClient(): void;
 declare const flux: FluxClient<GeneratedBroadcastManifest>;
 declare const fluxInternals: {
+    createHoloWebSocketConnector: typeof createHoloWebSocketConnector;
     createUnavailableConnector: typeof createUnavailableConnector;
     createPusherConnector: typeof createPusherConnector;
     createPresenceSubscription: typeof createPresenceSubscription;

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/index.ts
+var WEB_SOCKET_OPEN = 1;
 function normalizeRequiredString(value, label) {
   const normalized = value.trim();
   if (!normalized) {
@@ -210,6 +211,410 @@ function createPusherConnector(options = {}) {
     }
   });
 }
+function parseJsonObject(value) {
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return Object.freeze({});
+  }
+  return parsed;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseWireData(value) {
+  if (typeof value === "string") {
+    return parseJsonObject(value);
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return Object.freeze({});
+}
+function normalizeOptionalConnectorString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function normalizeOptionalConnectorPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function normalizeOptionalConnectorScheme(value) {
+  if (value === "http" || value === "https" || value === "ws" || value === "wss") {
+    return value;
+  }
+  return void 0;
+}
+function mergeHoloWebSocketConnectorOptions(discovered, explicit) {
+  return Object.freeze({
+    ...discovered,
+    ...typeof explicit.key === "undefined" ? {} : { key: explicit.key },
+    ...typeof explicit.host === "undefined" ? {} : { host: explicit.host },
+    ...typeof explicit.port === "undefined" ? {} : { port: explicit.port },
+    ...typeof explicit.path === "undefined" ? {} : { path: explicit.path },
+    ...typeof explicit.scheme === "undefined" ? {} : { scheme: explicit.scheme },
+    ...typeof explicit.authEndpoint === "undefined" ? {} : { authEndpoint: explicit.authEndpoint },
+    ...typeof explicit.configEndpoint === "undefined" ? {} : { configEndpoint: explicit.configEndpoint }
+  });
+}
+function normalizeHoloWebSocketConnectorConfig(value) {
+  if (!isRecord(value)) {
+    return Object.freeze({});
+  }
+  return Object.freeze({
+    ...normalizeOptionalConnectorString(value.key) ? { key: normalizeOptionalConnectorString(value.key) } : {},
+    ...normalizeOptionalConnectorString(value.host) ? { host: normalizeOptionalConnectorString(value.host) } : {},
+    ...normalizeOptionalConnectorPort(value.port) ? { port: normalizeOptionalConnectorPort(value.port) } : {},
+    ...normalizeOptionalConnectorString(value.path) ? { path: normalizeOptionalConnectorString(value.path) } : {},
+    ...normalizeOptionalConnectorScheme(value.scheme) ? { scheme: normalizeOptionalConnectorScheme(value.scheme) } : {},
+    ...normalizeOptionalConnectorString(value.authEndpoint) ? { authEndpoint: normalizeOptionalConnectorString(value.authEndpoint) } : {}
+  });
+}
+function canDiscoverHoloWebSocketConnectorOptions(globals) {
+  return !!globals.fetch && !!globals.location && typeof globals.window !== "undefined";
+}
+function hasExplicitHoloWebSocketConnectorOptions(options) {
+  return typeof options.key !== "undefined" || typeof options.host !== "undefined" || typeof options.port !== "undefined" || typeof options.path !== "undefined" || typeof options.scheme !== "undefined" || typeof options.authEndpoint !== "undefined";
+}
+async function resolveHoloWebSocketConnectorOptions(options, globals) {
+  if (!canDiscoverHoloWebSocketConnectorOptions(globals)) {
+    return options;
+  }
+  try {
+    const response = await globals.fetch(options.configEndpoint ?? "/broadcasting/config", {
+      headers: {
+        accept: "application/json"
+      },
+      credentials: "same-origin"
+    });
+    if (!response.ok) {
+      return options;
+    }
+    return mergeHoloWebSocketConnectorOptions(
+      normalizeHoloWebSocketConnectorConfig(await response.json()),
+      options
+    );
+  } catch {
+    return options;
+  }
+}
+function wireChannelName(kind, name) {
+  if (kind === "private") {
+    return `private-${name}`;
+  }
+  if (kind === "presence") {
+    return `presence-${name}`;
+  }
+  return name;
+}
+function resolveWireChannelKey(channel) {
+  if (channel.startsWith("private-")) {
+    return `private:${channel.slice("private-".length)}`;
+  }
+  if (channel.startsWith("presence-")) {
+    return `presence:${channel.slice("presence-".length)}`;
+  }
+  return `public:${channel}`;
+}
+function resolveBrowserHost(host, globals) {
+  const normalized = host?.trim();
+  if (!normalized || normalized === "0.0.0.0" || normalized === "127.0.0.1") {
+    return globals.location?.hostname?.trim() || normalized || "127.0.0.1";
+  }
+  return normalized;
+}
+function resolveWebSocketScheme(scheme, globals) {
+  if (scheme === "wss" || scheme === "https") {
+    return "wss";
+  }
+  if (scheme === "ws" || scheme === "http") {
+    return "ws";
+  }
+  return globals.location?.protocol === "https:" ? "wss" : "ws";
+}
+function createHoloWebSocketConnector(options = {}) {
+  const channels = /* @__PURE__ */ new Map();
+  const statusListeners = /* @__PURE__ */ new Set();
+  let status = "idle";
+  let socket;
+  let connecting;
+  let resolvedOptions;
+  let socketId;
+  const setStatus = (next) => {
+    if (status === next) {
+      return;
+    }
+    status = next;
+    notifyStatusListeners(statusListeners, status);
+  };
+  const sendMessage = (message) => {
+    if (socket?.readyState === WEB_SOCKET_OPEN) {
+      socket.send(JSON.stringify(message));
+    }
+  };
+  const authorizeSubscription = async (state) => {
+    if (state.kind === "public") {
+      return Object.freeze({});
+    }
+    const endpoint = resolvedOptions?.authEndpoint;
+    if (!endpoint) {
+      return Object.freeze({});
+    }
+    const globals = globalThis;
+    if (!globals.fetch) {
+      throw new Error("[@holo-js/flux] Private channel authorization requires fetch support in this runtime.");
+    }
+    const channel = wireChannelName(state.kind, state.name);
+    const currentSocketId = normalizeRequiredString(socketId ?? "", "Socket id");
+    const response = await globals.fetch(endpoint, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/x-www-form-urlencoded;charset=UTF-8"
+      },
+      credentials: "same-origin",
+      body: new URLSearchParams({
+        channel_name: channel,
+        socket_id: currentSocketId
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`[@holo-js/flux] Channel authorization failed with HTTP ${response.status}.`);
+    }
+    const body = await response.json();
+    if (!isRecord(body) || typeof body.auth !== "string") {
+      throw new Error("[@holo-js/flux] Channel authorization response is invalid.");
+    }
+    return Object.freeze({
+      auth: body.auth,
+      ...typeof body.channel_data === "string" ? { channel_data: body.channel_data } : {}
+    });
+  };
+  const flushSubscriptions = () => {
+    for (const state of channels.values()) {
+      if (state.subscribed) {
+        continue;
+      }
+      state.subscribed = true;
+      if (state.kind === "public" || !resolvedOptions?.authEndpoint) {
+        sendMessage({
+          event: "pusher:subscribe",
+          data: {
+            channel: wireChannelName(state.kind, state.name)
+          }
+        });
+        continue;
+      }
+      void authorizeSubscription(state).then((auth) => {
+        sendMessage({
+          event: "pusher:subscribe",
+          data: {
+            channel: wireChannelName(state.kind, state.name),
+            ...auth
+          }
+        });
+      }, () => {
+        state.subscribed = false;
+      });
+    }
+  };
+  const handleMessage = (event) => {
+    if (typeof event.data !== "string") {
+      return;
+    }
+    const message = parseJsonObject(event.data);
+    const eventName = typeof message.event === "string" ? message.event : "";
+    const channel = typeof message.channel === "string" ? message.channel : void 0;
+    const payload = parseWireData(message.data);
+    if (eventName === "pusher:connection_established") {
+      socketId = typeof payload.socket_id === "string" ? payload.socket_id : void 0;
+      flushSubscriptions();
+      return;
+    }
+    if (!channel) {
+      return;
+    }
+    const state = channels.get(resolveWireChannelKey(channel));
+    if (!state) {
+      return;
+    }
+    if (eventName === "pusher_internal:subscription_succeeded") {
+      const presence = payload.presence;
+      if (presence && typeof presence === "object" && !Array.isArray(presence)) {
+        const hash = presence.hash;
+        state.members = Object.freeze(
+          hash && typeof hash === "object" && !Array.isArray(hash) ? Object.values(hash) : []
+        );
+        for (const callback of state.memberListeners) {
+          callback(state.members);
+        }
+      }
+      return;
+    }
+    if (eventName === "pusher_internal:member_added") {
+      const member = parseWireData(payload.member);
+      state.members = Object.freeze([...state.members, member]);
+      for (const callback of state.memberListeners) {
+        callback(state.members);
+      }
+      return;
+    }
+    if (eventName === "pusher_internal:member_removed") {
+      const member = parseWireData(payload.member);
+      const key = presenceMemberKey(member);
+      state.members = Object.freeze(state.members.filter((candidate) => presenceMemberKey(candidate) !== key));
+      for (const callback of state.memberListeners) {
+        callback(state.members);
+      }
+      return;
+    }
+    if (eventName.startsWith("client-")) {
+      const whisper = eventName.slice("client-".length);
+      for (const callback of state.whisperListeners.get(whisper) ?? []) {
+        callback(payload);
+      }
+      return;
+    }
+    for (const callback of state.eventListeners.get(eventName) ?? []) {
+      callback(payload);
+    }
+  };
+  const ensureConnected = async () => {
+    const globals = globalThis;
+    const WebSocketConstructor = globals.WebSocket;
+    if (!WebSocketConstructor || !canDiscoverHoloWebSocketConnectorOptions(globals) && !hasExplicitHoloWebSocketConnectorOptions(options)) {
+      return;
+    }
+    if (socket?.readyState === WEB_SOCKET_OPEN) {
+      flushSubscriptions();
+      return;
+    }
+    if (connecting) {
+      await connecting;
+      return;
+    }
+    resolvedOptions = canDiscoverHoloWebSocketConnectorOptions(globals) ? await resolveHoloWebSocketConnectorOptions(options, globals) : options;
+    const scheme = resolveWebSocketScheme(resolvedOptions.scheme, globals);
+    const host = resolveBrowserHost(resolvedOptions.host, globals);
+    const port = resolvedOptions.port ?? 8080;
+    const path = resolvedOptions.path?.trim() || "/app";
+    const key = resolvedOptions.key?.trim() || "app-key";
+    const normalizedPath = `/${path.replace(/^\/+|\/+$/g, "")}`;
+    const url = `${scheme}://${host}:${port}${normalizedPath}/${encodeURIComponent(key)}`;
+    setStatus("connecting");
+    connecting = new Promise((resolve, reject) => {
+      const nextSocket = new WebSocketConstructor(url);
+      socket = nextSocket;
+      nextSocket.addEventListener("open", () => {
+        setStatus("connected");
+        flushSubscriptions();
+        resolve();
+      });
+      nextSocket.addEventListener("message", handleMessage);
+      nextSocket.addEventListener("close", () => {
+        socket = void 0;
+        connecting = void 0;
+        for (const state of channels.values()) {
+          state.subscribed = false;
+        }
+        setStatus("disconnected");
+      });
+      nextSocket.addEventListener("error", () => {
+        connecting = void 0;
+        setStatus("disconnected");
+        reject(new Error("[@holo-js/flux] WebSocket connection failed."));
+      });
+    }).finally(() => {
+      connecting = void 0;
+    });
+    await connecting;
+  };
+  const ensureChannel = (name, kind) => {
+    const key = `${kind}:${name}`;
+    const existing = channels.get(key);
+    if (existing) {
+      return existing;
+    }
+    const state = {
+      name,
+      kind,
+      eventListeners: /* @__PURE__ */ new Map(),
+      whisperListeners: /* @__PURE__ */ new Map(),
+      notificationListeners: /* @__PURE__ */ new Set(),
+      memberListeners: /* @__PURE__ */ new Set(),
+      members: Object.freeze([]),
+      subscribed: false
+    };
+    channels.set(key, state);
+    return state;
+  };
+  return Object.freeze({
+    async connect() {
+      await ensureConnected();
+    },
+    async disconnect() {
+      socket?.close();
+      socket = void 0;
+      connecting = void 0;
+      channels.clear();
+      setStatus("disconnected");
+    },
+    getStatus() {
+      return status;
+    },
+    onStatusChange(callback) {
+      statusListeners.add(callback);
+      return () => {
+        statusListeners.delete(callback);
+      };
+    },
+    subscribe(channel, kind) {
+      const state = ensureChannel(channel, kind);
+      void ensureConnected().catch(() => void 0);
+      return Object.freeze({
+        name: state.name,
+        kind: state.kind,
+        get members() {
+          return state.members;
+        },
+        onEvent(event, callback) {
+          return addCallback(state.eventListeners, event, callback);
+        },
+        onMembersChange(callback) {
+          state.memberListeners.add(callback);
+          return () => {
+            state.memberListeners.delete(callback);
+          };
+        },
+        onNotification(callback) {
+          state.notificationListeners.add(callback);
+          return () => {
+            state.notificationListeners.delete(callback);
+          };
+        },
+        onWhisper(name, callback) {
+          return addCallback(state.whisperListeners, name, callback);
+        },
+        async sendWhisper(name, payload) {
+          await ensureConnected();
+          sendMessage({
+            event: `client-${name}`,
+            channel: wireChannelName(state.kind, state.name),
+            data: payload
+          });
+        },
+        leave() {
+          if (state.subscribed) {
+            sendMessage({
+              event: "pusher:unsubscribe",
+              data: {
+                channel: wireChannelName(state.kind, state.name)
+              }
+            });
+          }
+          channels.delete(`${state.kind}:${state.name}`);
+        }
+      });
+    }
+  });
+}
 function createSubscription(channelName, kind, connector, registry) {
   const connectorChannel = connector.subscribe(channelName, kind);
   let active = true;
@@ -450,7 +855,12 @@ function createFluxClient(options = {}) {
   };
   return Object.freeze(client);
 }
-var defaultFluxClient = createFluxClient();
+function createDefaultFluxClient() {
+  return createFluxClient({
+    connector: createHoloWebSocketConnector()
+  });
+}
+var defaultFluxClient = createDefaultFluxClient();
 function configureFluxClient(options) {
   defaultFluxClient = "channel" in options ? options : createFluxClient(options);
   return defaultFluxClient;
@@ -459,7 +869,7 @@ function getFluxClient() {
   return defaultFluxClient;
 }
 function resetFluxClient() {
-  defaultFluxClient = createFluxClient();
+  defaultFluxClient = createDefaultFluxClient();
 }
 var flux = new Proxy({}, {
   get(_target, property) {
@@ -473,6 +883,7 @@ var flux = new Proxy({}, {
   }
 });
 var fluxInternals = {
+  createHoloWebSocketConnector,
   createUnavailableConnector,
   createPusherConnector,
   createPresenceSubscription,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/flux",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Holo-JS Framework - framework-agnostic realtime client skeleton for broadcast and presence",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/broadcast": "^0.1.9"
+    "@holo-js/broadcast": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",