@antelopejs/dms 0.9.8 → 0.11.0

package/frontend-vue/layers/dms-core/app/build/utils/crossTab.ts

@@ -0,0 +1,199 @@
+/**
+ * Coordination between the tabs of one browser profile, for the long-lived
+ * streams a dashboard keeps open.
+ *
+ * Over HTTP/1.1 a browser opens at most six connections per host, and a
+ * streaming response holds one for as long as it lives: one stream per tab
+ * starves every other request once a few tabs are open. One tab is elected
+ * (a Web Lock, released by the browser when the tab goes, however it goes),
+ * opens the stream, and relays it to the others over a BroadcastChannel.
+ *
+ * Web Locks need a secure context (HTTPS, or localhost). Where either API is
+ * missing, every tab is its own leader on a bus of its own: the behaviour of a
+ * stream per tab, unchanged.
+ *
+ * @internal
+ */
+
+const TAB_LOCK_SEPARATOR = ":tab:";
+
+export type TabMessageHandler = (message: unknown) => void;
+
+/** The browser APIs the coordination rides on; injected by the tests. */
+export interface CrossTabEnvironment {
+  locks?: LockManager;
+  createChannel?: (name: string) => BroadcastChannel;
+}
+
+export interface TabBus {
+  /** Sends to every tab on the bus, this one included. */
+  post(message: unknown): void;
+  listen(handler: TabMessageHandler): () => void;
+  close(): void;
+}
+
+/** A lock this tab holds until it releases it or goes. */
+export interface HeldLock {
+  /** Resolves once the lock is held: until then, nobody can wait on it. */
+  held: Promise<void>;
+  release(): void;
+}
+
+/** What the running browser offers. */
+export function browserCrossTabEnvironment(): CrossTabEnvironment {
+  const locks = globalThis.navigator?.locks;
+  const canBroadcast = typeof globalThis.BroadcastChannel === "function";
+  if (!locks || !canBroadcast) return {};
+  return { locks, createChannel: (name) => new BroadcastChannel(name) };
+}
+
+/** Whether the tabs can share: without both APIs each tab stays on its own. */
+export function canShareAcrossTabs(environment: CrossTabEnvironment): boolean {
+  return !!environment.locks && !!environment.createChannel;
+}
+
+export function openTabBus(
+  name: string,
+  environment: CrossTabEnvironment,
+): TabBus {
+  const listeners = new Set<TabMessageHandler>();
+  const deliver = (message: unknown) => {
+    for (const listener of [...listeners]) listener(message);
+  };
+  const channel = canShareAcrossTabs(environment)
+    ? environment.createChannel!(name)
+    : undefined;
+  if (channel) channel.onmessage = (event) => deliver(event.data);
+  return {
+    // A BroadcastChannel never echoes to its sender: this tab's own
+    // listeners hear the message directly.
+    post: (message) => {
+      channel?.postMessage(message);
+      deliver(message);
+    },
+    listen: (handler) => {
+      listeners.add(handler);
+      return () => listeners.delete(handler);
+    },
+    close: () => {
+      listeners.clear();
+      channel?.close();
+    },
+  };
+}
+
+/**
+ * Runs `lead` in one tab at a time per `name`. When the leading tab resigns
+ * or goes, the next waiting tab takes over and runs its own `lead`.
+ *
+ * @param lead Starts the leader's work; returns what stops it
+ * @returns Resigns: stops the work when leading, or stops waiting
+ */
+export function electLeader(
+  name: string,
+  environment: CrossTabEnvironment,
+  lead: () => () => void,
+): () => void {
+  if (!canShareAcrossTabs(environment)) return lead();
+  const abort = new AbortController();
+  let isResigned = false;
+  let stepDown: (() => void) | undefined;
+  environment
+    .locks!.request(name, { signal: abort.signal }, () => {
+      // Granted while the resignation was on its way.
+      if (isResigned) return;
+      return new Promise<void>((resolve) => {
+        const stop = lead();
+        stepDown = () => {
+          stop();
+          resolve();
+        };
+      });
+    })
+    .catch(() => {});
+  return () => {
+    isResigned = true;
+    abort.abort();
+    stepDown?.();
+    stepDown = undefined;
+  };
+}
+
+export function tabLockName(name: string, tabId: string): string {
+  return `${name}${TAB_LOCK_SEPARATOR}${tabId}`;
+}
+
+/** Holds `name` until released; the browser releases it when the tab goes. */
+export function holdLock(
+  name: string,
+  environment: CrossTabEnvironment,
+): HeldLock {
+  if (!canShareAcrossTabs(environment)) {
+    return { held: Promise.resolve(), release: () => {} };
+  }
+  const abort = new AbortController();
+  let release: (() => void) | undefined;
+  let isReleased = false;
+  const held = new Promise<void>((resolveHeld) => {
+    environment
+      .locks!.request(name, { signal: abort.signal }, () => {
+        if (isReleased) return;
+        resolveHeld();
+        return new Promise<void>((resolve) => {
+          release = resolve;
+        });
+      })
+      .catch(() => {});
+  });
+  return {
+    held,
+    release: () => {
+      isReleased = true;
+      abort.abort();
+      release?.();
+      release = undefined;
+    },
+  };
+}
+
+/**
+ * Calls `onReleased` once nobody holds `name` any more: when the tab holding
+ * it releases it or goes. Never called once `signal` aborts.
+ */
+export function whenReleased(
+  name: string,
+  environment: CrossTabEnvironment,
+  onReleased: () => void,
+  signal: AbortSignal,
+): void {
+  if (!canShareAcrossTabs(environment)) return;
+  environment
+    .locks!.request(name, { signal }, () => {
+      if (!signal.aborted) onReleased();
+    })
+    .catch(() => {});
+}
+
+/**
+ * One source for every tab of the browser: the elected tab opens it, and what
+ * it emits reaches each tab's `onMessage`, the leader's included.
+ *
+ * @param open Opens the source, handing it what relays a message; returns
+ *   what closes it
+ * @returns Leaves: closes the source when leading, and stops listening
+ */
+export function shareAcrossTabs(
+  name: string,
+  open: (emit: (message: unknown) => void) => () => void,
+  onMessage: TabMessageHandler,
+  environment: CrossTabEnvironment = browserCrossTabEnvironment(),
+): () => void {
+  const bus = openTabBus(name, environment);
+  const unlisten = bus.listen(onMessage);
+  const resign = electLeader(name, environment, () => open(bus.post));
+  return () => {
+    resign();
+    unlisten();
+    bus.close();
+  };
+}

package/frontend-vue/layers/dms-core/app/build/utils/sharedRealtimeConnection.ts

@@ -0,0 +1,410 @@
+import {
+  isUnauthorizedStreamError,
+  openSseStream,
+  type SseStreamHandle,
+} from "../../composables/realtime/useSseStream";
+import {
+  browserCrossTabEnvironment,
+  type CrossTabEnvironment,
+  electLeader,
+  holdLock,
+  openTabBus,
+  type TabBus,
+  tabLockName,
+  whenReleased,
+} from "./crossTab";
+
+/**
+ * The realtime connection one browser shares between its tabs: the elected tab
+ * holds `GET /api/realtime/connection` and relays it, each tab opens its own
+ * session on it. See `crossTab.ts` for why.
+ *
+ * @internal
+ */
+
+const HELLO_EVENT = "hello";
+const SESSION_EVENT = "session";
+const SESSION_HEADER = "x-realtime-session";
+const CONNECTION_HEADER = "x-realtime-connection";
+const RECONNECT_INITIAL_DELAY_MS = 500;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+const RECONNECT_MULTIPLIER = 2;
+
+interface ConnectionMessage {
+  kind: "connection";
+  /** `null` while the leader has no stream open. */
+  connectionId: string | null;
+}
+
+interface FrameMessage {
+  kind: "frame";
+  connectionId: string;
+  /** Unset on a frame of the connection itself, which every tab receives. */
+  sessionId?: string;
+  event: string;
+  data: unknown;
+}
+
+/** A tab joining asks the leader for the connection it holds. */
+interface QueryMessage {
+  kind: "query";
+}
+
+/** A tab's session on the connection, for the leader to end once it goes. */
+interface SessionMessage {
+  kind: "session";
+  connectionId: string;
+  sessionId: string;
+  tabId: string;
+}
+
+/**
+ * A tab whose session request the backend answered without knowing the
+ * connection asks the leader to open a new one.
+ */
+interface ReopenMessage {
+  kind: "reopen";
+  connectionId: string;
+}
+
+type HubMessage =
+  | ConnectionMessage
+  | FrameMessage
+  | QueryMessage
+  | SessionMessage
+  | ReopenMessage;
+
+export interface StreamRecovery {
+  refreshSession: () => Promise<boolean>;
+  redirectToAuth: () => Promise<void>;
+}
+
+export interface SharedRealtimeConnectionOptions extends StreamRecovery {
+  /** Scopes the election and the relay: one connection per name. */
+  name: string;
+  streamUrl: string;
+  sessionCloseUrl: string;
+  /** The connection to open a session on; `undefined` while there is none. */
+  onConnection: (connectionId: string | undefined) => void;
+  /**
+   * A frame of one tab's session, or of the connection itself (the dev
+   * reload signal) when `sessionId` is unset.
+   */
+  onFrame: (
+    sessionId: string | undefined,
+    eventName: string,
+    data: unknown,
+  ) => void;
+  environment?: CrossTabEnvironment;
+}
+
+export interface SharedRealtimeConnection {
+  /** Hands this tab's session to the leader, which ends it once the tab goes. */
+  announceSession: (connectionId: string, sessionId: string) => void;
+  /**
+   * Asks the leader to replace `connectionId` with a new stream: the backend
+   * answered a session request on it as a connection it does not know.
+   */
+  reopen: (connectionId: string) => void;
+  leave: () => void;
+}
+
+export interface Reconnector {
+  isCancelled(): boolean;
+  schedule(open: () => void): void;
+  resetDelay(): void;
+  cancel(): void;
+}
+
+export const createReconnector = (): Reconnector => {
+  let isCancelled = false;
+  let delay = RECONNECT_INITIAL_DELAY_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return {
+    isCancelled: () => isCancelled,
+    schedule: (open) => {
+      // A pending reconnect absorbs concurrent triggers: one attempt at a time.
+      if (isCancelled || timer) return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        open();
+      }, delay);
+      delay = Math.min(delay * RECONNECT_MULTIPLIER, RECONNECT_MAX_DELAY_MS);
+    },
+    resetDelay: () => {
+      delay = RECONNECT_INITIAL_DELAY_MS;
+    },
+    cancel: () => {
+      isCancelled = true;
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+};
+
+/** Retries after a failure, refreshing the browser session first on a 401. */
+export const recoverFromError = (
+  error: unknown,
+  retry: () => void,
+  recovery: StreamRecovery,
+): void => {
+  if (!isUnauthorizedStreamError(error)) {
+    retry();
+    return;
+  }
+  void recovery.refreshSession().then((isRefreshed) => {
+    if (isRefreshed) {
+      retry();
+    } else {
+      void recovery.redirectToAuth();
+    }
+  }, retry);
+};
+
+interface StreamCallbacks extends StreamRecovery {
+  onEvent: (eventName: string, data: unknown) => void;
+  onDisconnected: () => void;
+}
+
+interface KeptStream {
+  /** Drops the open stream and opens a new one. */
+  reopen: () => void;
+  stop: () => void;
+}
+
+/**
+ * Keeps one stream open until cancelled. The server ends the stream when it
+ * stops (a dev reload included), so a clean EOF reconnects just like an error
+ * does: the stream has no business completion.
+ */
+const connectWithBackoff = (
+  url: string,
+  callbacks: StreamCallbacks,
+): KeptStream => {
+  const reconnector = createReconnector();
+  let activeHandle: SseStreamHandle | undefined;
+  const open = () => {
+    if (reconnector.isCancelled()) return;
+    activeHandle?.close();
+    const handle: SseStreamHandle = openSseStream({
+      url,
+      onEvent: (eventName, data) => {
+        if (handle !== activeHandle) return;
+        reconnector.resetDelay();
+        callbacks.onEvent(eventName, data);
+      },
+      onError: (error) => {
+        if (!retire(handle)) return;
+        recoverFromError(error, reconnect, callbacks);
+      },
+      onClose: (reason) => {
+        if (reason !== "eof" || !retire(handle)) return;
+        reconnect();
+      },
+    });
+    activeHandle = handle;
+  };
+  const reconnect = () => reconnector.schedule(open);
+  const retire = (handle: SseStreamHandle): boolean => {
+    if (handle !== activeHandle || reconnector.isCancelled()) return false;
+    activeHandle = undefined;
+    callbacks.onDisconnected();
+    return true;
+  };
+  open();
+  return {
+    reopen: () => {
+      const handle = activeHandle;
+      if (!handle || !retire(handle)) return;
+      handle.close();
+      reconnect();
+    },
+    stop: () => {
+      reconnector.cancel();
+      activeHandle?.close();
+      activeHandle = undefined;
+    },
+  };
+};
+
+const readConnectionId = (data: unknown): string | null => {
+  const connectionId = (data as { connectionId?: unknown } | null)
+    ?.connectionId;
+  return typeof connectionId === "string" ? connectionId : null;
+};
+
+interface SessionFrame {
+  sessionId?: unknown;
+  event?: unknown;
+  data?: unknown;
+}
+
+interface LeaderContext {
+  options: SharedRealtimeConnectionOptions;
+  environment: CrossTabEnvironment;
+  bus: TabBus;
+  tabId: string;
+}
+
+const closeSession = (
+  url: string,
+  connectionId: string,
+  sessionId: string,
+): void => {
+  void fetch(url, {
+    method: "POST",
+    headers: { [CONNECTION_HEADER]: connectionId, [SESSION_HEADER]: sessionId },
+    credentials: "include",
+  }).catch(() => {});
+};
+
+/**
+ * The elected tab's share: the stream, relayed on the bus, and the sessions
+ * of the other tabs, each ended once its tab is gone.
+ */
+const lead = ({ options, environment, bus, tabId }: LeaderContext) => {
+  const watchers = new AbortController();
+  const sessionsByTab = new Map<string, Set<string>>();
+  let connectionId: string | null = null;
+
+  const publish = (next: string | null) => {
+    connectionId = next;
+    bus.post({ kind: "connection", connectionId: next });
+  };
+
+  const endSessionsOf = (otherTabId: string) => {
+    const sessionIds = sessionsByTab.get(otherTabId) ?? new Set<string>();
+    sessionsByTab.delete(otherTabId);
+    // The sessions of a connection that went ended with it.
+    if (!connectionId) return;
+    for (const sessionId of sessionIds) {
+      closeSession(options.sessionCloseUrl, connectionId, sessionId);
+    }
+  };
+
+  const watchSession = (message: SessionMessage) => {
+    // This tab's own sessions end with the stream it holds.
+    if (message.tabId === tabId || message.connectionId !== connectionId) {
+      return;
+    }
+    const known = sessionsByTab.get(message.tabId);
+    if (known) {
+      known.add(message.sessionId);
+      return;
+    }
+    sessionsByTab.set(message.tabId, new Set([message.sessionId]));
+    whenReleased(
+      tabLockName(options.name, message.tabId),
+      environment,
+      () => endSessionsOf(message.tabId),
+      watchers.signal,
+    );
+  };
+
+  const unlisten = bus.listen((raw) => {
+    const message = raw as HubMessage;
+    if (message.kind === "query")
+      bus.post({ kind: "connection", connectionId });
+    if (message.kind === "session") watchSession(message);
+    if (message.kind === "reopen" && message.connectionId === connectionId) {
+      stream.reopen();
+    }
+  });
+
+  // The tabs may still hold the connection of a leader that went: they drop it.
+  publish(null);
+  const stream = connectWithBackoff(options.streamUrl, {
+    onEvent: (eventName, data) => {
+      if (eventName === HELLO_EVENT) {
+        sessionsByTab.clear();
+        publish(readConnectionId(data));
+        return;
+      }
+      if (!connectionId) return;
+      if (eventName !== SESSION_EVENT) {
+        bus.post({ kind: "frame", connectionId, event: eventName, data });
+        return;
+      }
+      const frame = data as SessionFrame | null;
+      if (typeof frame?.sessionId !== "string") return;
+      if (typeof frame.event !== "string") return;
+      bus.post({
+        kind: "frame",
+        connectionId,
+        sessionId: frame.sessionId,
+        event: frame.event,
+        data: frame.data,
+      });
+    },
+    onDisconnected: () => publish(null),
+    refreshSession: options.refreshSession,
+    redirectToAuth: options.redirectToAuth,
+  });
+
+  return () => {
+    watchers.abort();
+    unlisten();
+    stream.stop();
+    publish(null);
+  };
+};
+
+const createTabId = (): string =>
+  globalThis.crypto?.randomUUID?.() ??
+  `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+/**
+ * Joins the browser's realtime connection for `options.name`, electing this
+ * tab to hold it when no other tab does.
+ */
+export function joinSharedRealtimeConnection(
+  options: SharedRealtimeConnectionOptions,
+): SharedRealtimeConnection {
+  const environment = options.environment ?? browserCrossTabEnvironment();
+  const tabId = createTabId();
+  const bus = openTabBus(options.name, environment);
+  // Held before any session is announced: the leader waits on it to learn
+  // that this tab went.
+  const tabLock = holdLock(tabLockName(options.name, tabId), environment);
+  let connectionId: string | undefined;
+
+  const unlisten = bus.listen((raw) => {
+    const message = raw as HubMessage;
+    if (message.kind === "connection") {
+      const next = message.connectionId ?? undefined;
+      if (next === connectionId) return;
+      connectionId = next;
+      options.onConnection(next);
+      return;
+    }
+    if (message.kind === "frame" && message.connectionId === connectionId) {
+      options.onFrame(message.sessionId, message.event, message.data);
+    }
+  });
+
+  const resign = electLeader(options.name, environment, () =>
+    lead({ options, environment, bus, tabId }),
+  );
+  bus.post({ kind: "query" });
+
+  return {
+    announceSession: (sessionConnectionId, sessionId) => {
+      void tabLock.held.then(() =>
+        bus.post({
+          kind: "session",
+          connectionId: sessionConnectionId,
+          sessionId,
+          tabId,
+        }),
+      );
+    },
+    reopen: (reopenedConnectionId) =>
+      bus.post({ kind: "reopen", connectionId: reopenedConnectionId }),
+    leave: () => {
+      resign();
+      unlisten();
+      tabLock.release();
+      bus.close();
+    },
+  };
+}