@multiplatform.one/frappe 6.6.0 → 6.7.0

package/src/realtime.ts

@@ -12,6 +12,98 @@ export enum RealtimePlatform {
   ReactNative = "react-native",
 }
 
+export type RealtimeTransport = "socketio" | "sse";
+
+/** One SSE frame as received off the wire (before any mapping). */
+export interface SSEFrame {
+  /** SSE event type — the `event:` classification line, or `"message"` for unnamed frames. */
+  type: string;
+  /** Raw `data:` payload (SSE data is always a string). */
+  data: string;
+  /** The stream's last `id:` line as of this frame (empty when the server sent none). */
+  lastEventId: string;
+}
+
+/** One handler-map delivery produced by `RealtimeSSEConfig.mapFrame`. */
+export interface SSEMappedEvent {
+  event: string;
+  payload: unknown;
+}
+
+/** Minimal structural slice of a WHATWG `MessageEvent` the SSE transport reads. */
+export interface SSEMessageEventLike {
+  type?: string;
+  data?: unknown;
+  lastEventId?: string;
+}
+
+/**
+ * Minimal structural slice of the WHATWG EventSource interface used by the
+ * SSE transport. The global browser/Node implementation satisfies it, and so
+ * do the common polyfills (`eventsource` on npm, `react-native-sse`).
+ */
+export interface SSEEventSourceLike {
+  addEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+  removeEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+  close(): void;
+}
+
+export type SSEEventSourceConstructor = new (
+  url: string,
+  init?: { withCredentials?: boolean },
+) => SSEEventSourceLike;
+
+export interface RealtimeSSEConfig {
+  /** Absolute stream URL. Wins over `path` when both are set. */
+  url?: string;
+  /**
+   * Stream path resolved against `baseURL` (e.g.
+   * `"/api/method/shc.events.stream"` for the SHC daemon). One of `url` or
+   * `path` is REQUIRED: SSE endpoints are server-specific — a real Frappe
+   * bench has none at all — so a framework default would only ever 404, and
+   * `connect()` throws a descriptive error instead of guessing.
+   */
+  path?: string;
+  /**
+   * Browser EventSource credential mode: send cookies on the stream request.
+   * This is the primary browser auth path — EventSource cannot set request
+   * headers, so header-based token auth is impossible there (see
+   * `queryParams` for the token alternative).
+   */
+  withCredentials?: boolean;
+  /**
+   * Injectable EventSource constructor for runtimes without a global one
+   * (React Native, Node < 22, GJS) — e.g. the `eventsource` npm package or
+   * `react-native-sse`. When omitted the global `EventSource` is used, and
+   * `connect()` throws an error naming this option when neither exists.
+   */
+  EventSource?: SSEEventSourceConstructor;
+  /**
+   * Named SSE event types (`event:` classification lines) to listen for, in
+   * addition to unnamed `"message"` frames and handler-registered names.
+   * EventSource only dispatches a NAMED event when a listener for that exact
+   * type is attached, so `mapFrame`-driven apps — whose handler names differ
+   * from the wire's frame types — must list the server's classifications
+   * here (e.g. `["docker", "audit", "error", "event"]` for the SHC daemon).
+   */
+  events?: string[];
+  /**
+   * Translate one SSE frame into zero or more handler deliveries. Return
+   * `null`/`undefined` to drop the frame. When omitted, the default mapping
+   * delivers under the frame's `event:` type name with `JSON.parse(data)` as
+   * the payload (falling back to the raw string when the data isn't JSON).
+   */
+  mapFrame?: (frame: SSEFrame) => SSEMappedEvent[] | null | undefined;
+  /**
+   * Extra query parameters appended to the stream URL — the token-auth path
+   * for SSE (headers are off-limits in browsers, see `withCredentials`).
+   * Values may be getters; they are re-resolved every time the EventSource
+   * is (re)created, so a rotated token is picked up by `updateAuth()`'s
+   * reconnect.
+   */
+  queryParams?: Record<string, string | (() => string | Promise<string>)>;
+}
+
 export interface RealtimeConfig {
   auth?: AuthConfig;
   baseURL: string;
@@ -43,10 +135,28 @@ export interface RealtimeConfig {
   siteName?: string;
   platform?: RealtimePlatform;
   socketOptions?: Partial<ManagerOptions & SocketOptions>;
+  /**
+   * Wire transport for realtime events.
+   *
+   * - `"socketio"` (default): Frappe's real realtime server — Socket.IO with
+   *   doc/doctype rooms and two-way subscribe emits. Omitting `transport`
+   *   keeps this exact behavior.
+   * - `"sse"`: a one-way `text/event-stream` endpoint consumed via
+   *   EventSource. Built for Frappe-wire-compatible servers that serve
+   *   realtime as SSE instead of Socket.IO (e.g. the SHC daemon's
+   *   `GET /api/method/shc.events.stream`). Requires `sse.url` or `sse.path`.
+   *   Room subscriptions become client-side bookkeeping (nothing can be
+   *   emitted upstream) and `sse.mapFrame` decides how server frames fan out
+   *   to handler events. Missed-event resume via the `Last-Event-ID` header
+   *   is native EventSource behavior and is not reimplemented here.
+   */
+  transport?: RealtimeTransport;
+  /** SSE transport options — only read when `transport` is `"sse"`. */
+  sse?: RealtimeSSEConfig;
 }
 
-type DocRoom = { doctype: string; name: string };
-type ListRoom = { doctype: string; filters?: Record<string, unknown> };
+export type DocRoom = { doctype: string; name: string };
+export type ListRoom = { doctype: string; filters?: Record<string, unknown> };
 
 function docRoomKey(doctype: string, name: string) {
   return `${doctype}\0${name}`;
@@ -54,11 +164,20 @@ function docRoomKey(doctype: string, name: string) {
 
 export class RealtimeModule {
   private socket: Socket | undefined;
+  /** Live EventSource when the `"sse"` transport is active. */
+  private eventSource: SSEEventSourceLike | undefined;
   private handlerMap = new Map<string, Set<Handler>>();
   /** Tracks events with socket listeners attached to prevent duplicates. */
   private attachedSocketEvents = new Set<string>();
   /** Stored socket event handler references for proper cleanup. */
   private socketEventHandlers = new Map<string, (payload: unknown) => void>();
+  /** Tracks SSE event types with listeners attached to prevent duplicates. */
+  private attachedSseEvents = new Set<string>();
+  /** Stored SSE listener references for proper cleanup. */
+  private sseListeners = new Map<string, (event: SSEMessageEventLike) => void>();
+  /** One-shot debug notices for SSE's one-way limitations. */
+  private sseRoomNoticeLogged = false;
+  private sseEmitNoticeLogged = false;
   /** Active doc rooms — re-emitted on every (re)connect. */
   private docRooms = new Map<string, DocRoom>();
   /** Active list rooms — re-emitted on every (re)connect. */
@@ -220,8 +339,12 @@ export class RealtimeModule {
     this.healthyWaiters.clear();
   }
 
+  private isSSE(): boolean {
+    return this.config.transport === "sse";
+  }
+
   private waitUntilHealthy(timeoutMs = 20_000): Promise<boolean> {
-    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);
@@ -236,8 +359,8 @@ export class RealtimeModule {
   }
 
   private async ensureConnected(): Promise<void> {
-    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();
@@ -255,7 +378,16 @@ export class RealtimeModule {
     }
   }
 
-  private async connect() {
+  /**
+   * 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(): Promise<void> {
+    if (this.isSSE()) return this.connectSSE();
     if (this.socket || this.isConnecting) return;
     this.isConnecting = true;
     try {
@@ -297,6 +429,197 @@ export class RealtimeModule {
     }
   }
 
+  /**
+   * 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.
+   */
+  private async connectSSE(): Promise<void> {
+    if (this.eventSource || this.isConnecting) return;
+    this.isConnecting = true;
+    try {
+      const sse = this.config.sse;
+      const EventSourceCtor =
+        sse?.EventSource ?? (globalThis as { EventSource?: SSEEventSourceConstructor }).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 — 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;
+    }
+  }
+
+  private async buildSSEURL(): Promise<string> {
+    const sse = this.config.sse;
+    let url: string;
+    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;
+    // Built by string concatenation (not the URL constructor) so minimal URL
+    // polyfills (GJS) work; getters are re-resolved on every (re)creation so
+    // rotated tokens ride the next stream request.
+    const parts: string[] = [];
+    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("&")}`;
+  }
+
+  private initSSEHandlers(): void {
+    // New EventSource instance: reset tracking so listeners re-register fresh.
+    this.attachedSseEvents.clear();
+    this.sseListeners.clear();
+    // Lifecycle events + unnamed (`event:`-less) frames.
+    this.attachSSEListener("open");
+    this.attachSSEListener("error");
+    this.attachSSEListener("message");
+    // Named frame types the server classifies with `event:` lines —
+    // EventSource only dispatches a named event when a listener for that
+    // exact type is attached, so mapFrame-driven apps declare them up front.
+    for (const type of this.config.sse?.events ?? []) {
+      this.attachSSEListener(type);
+    }
+    // Handler-map keys mirror socket.io's attach-on-register semantics: with
+    // the default mapping, the frame type IS the handler event name.
+    for (const event of this.handlerMap.keys()) {
+      this.attachSSEListener(event);
+    }
+  }
+
+  private attachSSEListener(type: string): void {
+    if (!this.eventSource || this.attachedSseEvents.has(type)) return;
+    const listener = (event: SSEMessageEventLike) => {
+      this.handleSSEEvent(type, event);
+    };
+    this.sseListeners.set(type, listener);
+    this.attachedSseEvents.add(type);
+    this.eventSource.addEventListener(type, listener);
+  }
+
+  private detachSSEListener(type: string): void {
+    // Lifecycle types and declared server frame types stay attached even
+    // when a same-named app handler is removed — they feed health tracking
+    // and mapFrame routing, not just that one handler.
+    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);
+  }
+
+  private isCoreSSEType(type: string): boolean {
+    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.
+   */
+  private handleSSEEvent(type: string, event: SSEMessageEventLike): void {
+    if (event?.data === undefined) {
+      if (type === "open") {
+        this.isConnecting = false;
+        this.socketHealthy = true;
+        this.emitToHandlers("connected", { transport: "sse" });
+        this.resolveHealthyWaiters(true);
+      } else if (type === "error") {
+        // EventSource surfaces initial-connect failures and mid-stream drops
+        // through the same `error` event and keeps reconnecting on its own —
+        // report unhealthy and deliver a `disconnect` (never `connect_error`)
+        // so lifecycle consumers see one consistent signal, then stay out of
+        // the retry loop's way. The next `open` flips healthy again.
+        this.isConnecting = false;
+        this.socketHealthy = false;
+        this.emitToHandlers("disconnect", { reason: "sse-error" });
+        this.resolveHealthyWaiters(false);
+      }
+      return;
+    }
+    const frame: SSEFrame = {
+      type,
+      data: String(event.data),
+      lastEventId: event.lastEventId ?? "",
+    };
+    const mapFrame = this.config.sse?.mapFrame;
+    if (mapFrame) {
+      let mapped: SSEMappedEvent[] | null | undefined;
+      try {
+        mapped = mapFrame(frame);
+      } catch (err) {
+        // A throwing mapper must not kill the stream — drop the frame.
+        console.warn("[RealtimeModule] sse.mapFrame threw; frame dropped:", err);
+        return;
+      }
+      if (!mapped) return;
+      for (const { event: mappedEvent, payload } of mapped) {
+        this.emitToHandlers(mappedEvent, payload);
+      }
+      return;
+    }
+    // Default mapping: deliver under the SSE `event:` type name with the
+    // JSON-parsed data as payload, raw string when it isn't JSON.
+    let payload: unknown = frame.data;
+    try {
+      payload = JSON.parse(frame.data);
+    } catch {
+      // Not JSON — deliver the raw string.
+    }
+    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.
+   */
+  private logSSERoomNoticeOnce(): void {
+    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 — " +
+        "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.
@@ -310,8 +633,17 @@ export class RealtimeModule {
       this.socket.disconnect();
       this.socket = undefined;
     }
+    if (this.eventSource) {
+      for (const [type, listener] of this.sseListeners) {
+        this.eventSource.removeEventListener(type, listener);
+      }
+      this.eventSource.close();
+      this.eventSource = undefined;
+    }
     this.attachedSocketEvents.clear();
     this.socketEventHandlers.clear();
+    this.attachedSseEvents.clear();
+    this.sseListeners.clear();
     this.socketHealthy = false;
     this.isConnecting = false;
     this.resolveHealthyWaiters(false);
@@ -408,7 +740,11 @@ export class RealtimeModule {
     // handlers up front) booted a socket that nothing would ever close —
     // against an unreachable host that is an infinite reconnect-poll loop
     // surviving unmount (the fixture/mock-story socket leak).
-    this.attachSocketListener(event);
+    if (this.isSSE()) {
+      this.attachSSEListener(event);
+    } else {
+      this.attachSocketListener(event);
+    }
   }
 
   off(event: string, handler: Handler): void {
@@ -417,14 +753,23 @@ export 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: string, name: string): Promise<void> {
     this.docRooms.set(docRoomKey(doctype, name), { doctype, name });
+    // SSE: room membership is recorded client-side only — subscriptions
+    // cannot be emitted over a one-way stream. The room still drives the
+    // transport lifecycle (connect here, idle teardown on last unsubscribe)
+    // exactly like socket.io mode.
+    if (this.isSSE()) this.logSSERoomNoticeOnce();
     await this.ensureConnected();
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       // Positional args — frappe's handler signature is (doctype, docname).
       this.socket.emit("doc_subscribe", doctype, name);
     }
@@ -432,7 +777,7 @@ export class RealtimeModule {
 
   unsubscribeDoc(doctype: string, name: string): void {
     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();
@@ -447,15 +792,16 @@ export class RealtimeModule {
    */
   async subscribeList(doctype: string, filters?: Record<string, unknown>): Promise<void> {
     this.listRooms.set(doctype, { 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: string): void {
     this.listRooms.delete(doctype);
-    if (this.socket && this.socketHealthy) {
+    if (!this.isSSE() && this.socket && this.socketHealthy) {
       this.socket.emit("doctype_unsubscribe", doctype);
     }
     this.teardownWhenIdle();
@@ -472,7 +818,7 @@ export class RealtimeModule {
    */
   private teardownWhenIdle(): void {
     if (this.docRooms.size > 0 || this.listRooms.size > 0) return;
-    if (!this.socket && !this.isConnecting) return;
+    if (!this.socket && !this.eventSource && !this.isConnecting) return;
     // Surface the teardown to lifecycle listeners (connection indicators)
     // before the listeners are detached from the socket.
     this.emitToHandlers("disconnect", { reason: "idle-teardown" });
@@ -480,6 +826,9 @@ export class RealtimeModule {
   }
 
   isHealthy() {
+    // SSE has no `connected` flag to consult — health is tracked by the
+    // open/error lifecycle events on the live EventSource.
+    if (this.isSSE()) return this.socketHealthy && this.eventSource !== undefined;
     return this.socketHealthy && this.socket?.connected === true;
   }
 
@@ -496,7 +845,19 @@ export class RealtimeModule {
     // socket serves. Handlers alone (registered eagerly by the sync engine)
     // don't warrant a socket: an idle module stays idle across credential
     // rotation, and the next room join connects with the fresh auth.
-    const shouldReconnect = this.docRooms.size > 0 || this.listRooms.size > 0;
+    //
+    // SSE limitation: browsers give EventSource no way to set request
+    // headers, so `config.auth` (Authorization/Cookie headers) cannot ride
+    // the stream request the way it rides the socket.io handshake. SSE auth
+    // is cookies via `sse.withCredentials` and/or tokens via
+    // `sse.queryParams` getters — both take effect by RECREATING the
+    // EventSource, which is what this does. An explicitly opened stream
+    // (public connect(), no rooms) is recreated too: unlike socket.io mode,
+    // nothing else in the room lifecycle would ever reopen it.
+    const shouldReconnect =
+      this.docRooms.size > 0 ||
+      this.listRooms.size > 0 ||
+      (this.isSSE() && this.eventSource !== undefined);
     // Soft disconnect preserves handlers + rooms; hard disconnect() would wipe them
     // and make the post-check always false (previous production bug).
     this.softDisconnect();
@@ -506,6 +867,18 @@ export class RealtimeModule {
   }
 
   emit(event: string, data: unknown) {
+    if (this.isSSE()) {
+      // SSE is one-way (server → client): there is no upstream channel to
+      // carry app emits. Dropped, with a one-shot debug notice.
+      if (!this.sseEmitNoticeLogged) {
+        this.sseEmitNoticeLogged = true;
+        console.debug(
+          "[RealtimeModule] emit() is a no-op under the SSE transport — SSE is one-way " +
+            "(server → client). Use HTTP calls for client → server communication.",
+        );
+      }
+      return;
+    }
     if (this.socket && this.socketHealthy) {
       this.socket.emit(event, data);
     }
@@ -514,4 +887,23 @@ export class RealtimeModule {
   getSocket() {
     return this.socket;
   }
+
+  /** Live EventSource when the SSE transport is connected (undefined otherwise). */
+  getEventSource(): SSEEventSourceLike | undefined {
+    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(): DocRoom[] {
+    return [...this.docRooms.values()];
+  }
+
+  /** List rooms recorded by subscribeList — same client-side semantics as getDocRooms. */
+  getListRooms(): ListRoom[] {
+    return [...this.listRooms.values()];
+  }
 }