@multiplatform.one/frappe 6.4.3 → 6.7.0

package/dist/cjs/realtime.cjs

@@ -40,11 +40,20 @@ function docRoomKey(doctype, name) {
 }
 class RealtimeModule {
   socket;
+  /** Live EventSource when the `"sse"` transport is active. */
+  eventSource;
   handlerMap = /* @__PURE__ */new Map();
   /** Tracks events with socket listeners attached to prevent duplicates. */
   attachedSocketEvents = /* @__PURE__ */new Set();
   /** Stored socket event handler references for proper cleanup. */
   socketEventHandlers = /* @__PURE__ */new Map();
+  /** Tracks SSE event types with listeners attached to prevent duplicates. */
+  attachedSseEvents = /* @__PURE__ */new Set();
+  /** Stored SSE listener references for proper cleanup. */
+  sseListeners = /* @__PURE__ */new Map();
+  /** One-shot debug notices for SSE's one-way limitations. */
+  sseRoomNoticeLogged = false;
+  sseEmitNoticeLogged = false;
   /** Active doc rooms — re-emitted on every (re)connect. */
   docRooms = /* @__PURE__ */new Map();
   /** Active list rooms — re-emitted on every (re)connect. */
@@ -159,8 +168,11 @@ class RealtimeModule {
     for (const resolve of this.healthyWaiters) resolve(ok);
     this.healthyWaiters.clear();
   }
+  isSSE() {
+    return this.config.transport === "sse";
+  }
   waitUntilHealthy(timeoutMs = 2e4) {
-    if (this.socketHealthy && this.socket?.connected) return Promise.resolve(true);
+    if (this.isHealthy()) return Promise.resolve(true);
     return new Promise(resolve => {
       const timer = setTimeout(() => {
         this.healthyWaiters.delete(onReady);
@@ -174,8 +186,8 @@ class RealtimeModule {
     });
   }
   async ensureConnected() {
-    if (this.socketHealthy && this.socket?.connected) return;
-    if (!this.socket && !this.isConnecting) {
+    if (this.isHealthy()) return;
+    if (!this.socket && !this.eventSource && !this.isConnecting) {
       await this.connect();
     }
     await this.waitUntilHealthy();
@@ -189,7 +201,16 @@ class RealtimeModule {
       this.socket.emit("doctype_subscribe", room.doctype);
     }
   }
+  /**
+   * Open the realtime transport now. Room-driven auto-connect
+   * (subscribeDoc/subscribeList) remains the primary lifecycle in both
+   * transports — this is public for SSE consumers that use no doc/list room
+   * bookkeeping: a one-way stream has nothing to emit on join, so nothing
+   * else would ever open it. Idempotent while a transport exists or a
+   * connect is in flight.
+   */
   async connect() {
+    if (this.isSSE()) return this.connectSSE();
     if (this.socket || this.isConnecting) return;
     this.isConnecting = true;
     try {
@@ -218,6 +239,153 @@ class RealtimeModule {
       throw err;
     }
   }
+  /**
+   * SSE branch of connect(): construct an EventSource against the configured
+   * stream URL. EventSource connects at construction, auto-reconnects on
+   * failure, and resumes missed frames itself by sending the stream's last
+   * `id:` as the `Last-Event-ID` request header — none of that is
+   * reimplemented here.
+   */
+  async connectSSE() {
+    if (this.eventSource || this.isConnecting) return;
+    this.isConnecting = true;
+    try {
+      const sse = this.config.sse;
+      const EventSourceCtor = sse?.EventSource ?? globalThis.EventSource;
+      if (!EventSourceCtor) {
+        throw new Error('[RealtimeModule] transport "sse" needs an EventSource implementation, and this runtime has no global EventSource (React Native and Node < 22 ship none). Pass a constructor via config.sse.EventSource \u2014 e.g. the "eventsource" npm package on Node or "react-native-sse" on React Native.');
+      }
+      const url = await this.buildSSEURL();
+      this.eventSource = new EventSourceCtor(url, {
+        withCredentials: sse?.withCredentials
+      });
+      this.initSSEHandlers();
+    } catch (err) {
+      this.isConnecting = false;
+      this.resolveHealthyWaiters(false);
+      throw err;
+    }
+  }
+  async buildSSEURL() {
+    const sse = this.config.sse;
+    let url;
+    if (sse?.url) {
+      url = sse.url;
+    } else if (sse?.path) {
+      const base = this.config.baseURL.replace(/\/$/, "");
+      url = `${base}${sse.path.startsWith("/") ? "" : "/"}${sse.path}`;
+    } else {
+      throw new Error('[RealtimeModule] transport "sse" requires config.sse.url or config.sse.path. There is no default stream path: SSE endpoints are server-specific (the SHC daemon serves "/api/method/shc.events.stream"; a real Frappe bench has no SSE endpoint at all), so a framework default would only ever 404.');
+    }
+    const params = Object.entries(this.config.sse?.queryParams ?? {});
+    if (params.length === 0) return url;
+    const parts = [];
+    for (const [key, value] of params) {
+      const resolved = typeof value === "function" ? await value() : value;
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(resolved)}`);
+    }
+    return `${url}${url.includes("?") ? "&" : "?"}${parts.join("&")}`;
+  }
+  initSSEHandlers() {
+    this.attachedSseEvents.clear();
+    this.sseListeners.clear();
+    this.attachSSEListener("open");
+    this.attachSSEListener("error");
+    this.attachSSEListener("message");
+    for (const type of this.config.sse?.events ?? []) {
+      this.attachSSEListener(type);
+    }
+    for (const event of this.handlerMap.keys()) {
+      this.attachSSEListener(event);
+    }
+  }
+  attachSSEListener(type) {
+    if (!this.eventSource || this.attachedSseEvents.has(type)) return;
+    const listener = event => {
+      this.handleSSEEvent(type, event);
+    };
+    this.sseListeners.set(type, listener);
+    this.attachedSseEvents.add(type);
+    this.eventSource.addEventListener(type, listener);
+  }
+  detachSSEListener(type) {
+    if (this.isCoreSSEType(type)) return;
+    if (!this.eventSource || !this.attachedSseEvents.has(type)) return;
+    const listener = this.sseListeners.get(type);
+    if (listener) {
+      this.eventSource.removeEventListener(type, listener);
+      this.sseListeners.delete(type);
+    }
+    this.attachedSseEvents.delete(type);
+  }
+  isCoreSSEType(type) {
+    return type === "open" || type === "error" || type === "message" || (this.config.sse?.events ?? []).includes(type);
+  }
+  /**
+   * Single entry point for everything the EventSource dispatches. Dataless
+   * events are transport lifecycle (`open`/`error` as plain Events); anything
+   * carrying `data` is a server frame — including frames the server
+   * classified `event: error`, which arrive as MessageEvents WITH data and
+   * must not be mistaken for connection errors.
+   */
+  handleSSEEvent(type, event) {
+    if (event?.data === void 0) {
+      if (type === "open") {
+        this.isConnecting = false;
+        this.socketHealthy = true;
+        this.emitToHandlers("connected", {
+          transport: "sse"
+        });
+        this.resolveHealthyWaiters(true);
+      } else if (type === "error") {
+        this.isConnecting = false;
+        this.socketHealthy = false;
+        this.emitToHandlers("disconnect", {
+          reason: "sse-error"
+        });
+        this.resolveHealthyWaiters(false);
+      }
+      return;
+    }
+    const frame = {
+      type,
+      data: String(event.data),
+      lastEventId: event.lastEventId ?? ""
+    };
+    const mapFrame = this.config.sse?.mapFrame;
+    if (mapFrame) {
+      let mapped;
+      try {
+        mapped = mapFrame(frame);
+      } catch (err) {
+        console.warn("[RealtimeModule] sse.mapFrame threw; frame dropped:", err);
+        return;
+      }
+      if (!mapped) return;
+      for (const {
+        event: mappedEvent,
+        payload: payload2
+      } of mapped) {
+        this.emitToHandlers(mappedEvent, payload2);
+      }
+      return;
+    }
+    let payload = frame.data;
+    try {
+      payload = JSON.parse(frame.data);
+    } catch {}
+    this.emitToHandlers(frame.type, payload);
+  }
+  /**
+   * Logged once: SSE is one-way, so doc/list room membership can't be sent
+   * upstream — rooms are recorded client-side (see getDocRooms/getListRooms)
+   * for mapFrame-driven filtering and for a future two-way transport.
+   */
+  logSSERoomNoticeOnce() {
+    if (this.sseRoomNoticeLogged) return;
+    this.sseRoomNoticeLogged = true;
+    console.debug("[RealtimeModule] SSE transport is one-way: doc/list room subscriptions are recorded client-side only (getDocRooms()/getListRooms()) and nothing is sent to the server \u2014 filter server-side via sse.queryParams or route frames with sse.mapFrame.");
+  }
   /**
    * Tear down the socket without clearing app handlers or room subscriptions.
    * Used by auth refresh so listeners/rooms survive credential rotation.
@@ -230,8 +398,17 @@ class RealtimeModule {
       this.socket.disconnect();
       this.socket = void 0;
     }
+    if (this.eventSource) {
+      for (const [type, listener] of this.sseListeners) {
+        this.eventSource.removeEventListener(type, listener);
+      }
+      this.eventSource.close();
+      this.eventSource = void 0;
+    }
     this.attachedSocketEvents.clear();
     this.socketEventHandlers.clear();
+    this.attachedSseEvents.clear();
+    this.sseListeners.clear();
     this.socketHealthy = false;
     this.isConnecting = false;
     this.resolveHealthyWaiters(false);
@@ -308,7 +485,11 @@ class RealtimeModule {
       this.handlerMap.set(event, handlerSet);
     }
     handlerSet.add(handler);
-    this.attachSocketListener(event);
+    if (this.isSSE()) {
+      this.attachSSEListener(event);
+    } else {
+      this.attachSocketListener(event);
+    }
   }
   off(event, handler) {
     const handlerSet = this.handlerMap.get(event);
@@ -316,7 +497,11 @@ class RealtimeModule {
     handlerSet.delete(handler);
     if (handlerSet.size === 0) {
       this.handlerMap.delete(event);
-      this.detachSocketListener(event);
+      if (this.isSSE()) {
+        this.detachSSEListener(event);
+      } else {
+        this.detachSocketListener(event);
+      }
     }
   }
   async subscribeDoc(doctype, name) {
@@ -324,14 +509,15 @@ class RealtimeModule {
       doctype,
       name
     });
+    if (this.isSSE()) this.logSSERoomNoticeOnce();
     await this.ensureConnected();
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       this.socket.emit("doc_subscribe", doctype, name);
     }
   }
   unsubscribeDoc(doctype, name) {
     this.docRooms.delete(docRoomKey(doctype, name));
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       this.socket.emit("doc_unsubscribe", doctype, name);
     }
     this.teardownWhenIdle();
@@ -348,14 +534,15 @@ class RealtimeModule {
       doctype,
       filters
     });
+    if (this.isSSE()) this.logSSERoomNoticeOnce();
     await this.ensureConnected();
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       this.socket.emit("doctype_subscribe", doctype);
     }
   }
   unsubscribeList(doctype) {
     this.listRooms.delete(doctype);
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       this.socket.emit("doctype_unsubscribe", doctype);
     }
     this.teardownWhenIdle();
@@ -371,13 +558,14 @@ class RealtimeModule {
    */
   teardownWhenIdle() {
     if (this.docRooms.size > 0 || this.listRooms.size > 0) return;
-    if (!this.socket && !this.isConnecting) return;
+    if (!this.socket && !this.eventSource && !this.isConnecting) return;
     this.emitToHandlers("disconnect", {
       reason: "idle-teardown"
     });
     this.softDisconnect();
   }
   isHealthy() {
+    if (this.isSSE()) return this.socketHealthy && this.eventSource !== void 0;
     return this.socketHealthy && this.socket?.connected === true;
   }
   disconnect() {
@@ -388,13 +576,20 @@ class RealtimeModule {
   }
   async updateAuth(auth) {
     this.config.auth = auth;
-    const shouldReconnect = this.docRooms.size > 0 || this.listRooms.size > 0;
+    const shouldReconnect = this.docRooms.size > 0 || this.listRooms.size > 0 || this.isSSE() && this.eventSource !== void 0;
     this.softDisconnect();
     if (shouldReconnect) {
       await this.connect();
     }
   }
   emit(event, data) {
+    if (this.isSSE()) {
+      if (!this.sseEmitNoticeLogged) {
+        this.sseEmitNoticeLogged = true;
+        console.debug("[RealtimeModule] emit() is a no-op under the SSE transport \u2014 SSE is one-way (server \u2192 client). Use HTTP calls for client \u2192 server communication.");
+      }
+      return;
+    }
     if (this.socket && this.socketHealthy) {
       this.socket.emit(event, data);
     }
@@ -402,4 +597,20 @@ class RealtimeModule {
   getSocket() {
     return this.socket;
   }
+  /** Live EventSource when the SSE transport is connected (undefined otherwise). */
+  getEventSource() {
+    return this.eventSource;
+  }
+  /**
+   * Doc rooms recorded by subscribeDoc. Under SSE these are client-side
+   * bookkeeping only (nothing is emitted upstream) — mapFrame-driven apps
+   * consult them to filter or route frames.
+   */
+  getDocRooms() {
+    return [...this.docRooms.values()];
+  }
+  /** List rooms recorded by subscribeList — same client-side semantics as getDocRooms. */
+  getListRooms() {
+    return [...this.listRooms.values()];
+  }
 }