@chidchanun/bcp 0.2.11 → 0.2.13

package/packages/client/src/realtime.mjs

@@ -0,0 +1,936 @@
+// packages/server/src/realtime.ts
+import {
+  randomUUID
+} from "node:crypto";
+function createMemoryRealtimeBroker() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    async publish(message) {
+      for (const listener of listeners) {
+        await listener(cloneEnvelope(message));
+      }
+    },
+    subscribe(listener) {
+      if (typeof listener !== "function") {
+        throw new TypeError(
+          "BCP Realtime: broker listener must be a function."
+        );
+      }
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    clear() {
+      listeners.clear();
+    }
+  };
+}
+function createMemoryRealtimePresenceStore() {
+  const members = /* @__PURE__ */ new Map();
+  return {
+    async join(member) {
+      members.set(
+        presenceKey(
+          member.channel,
+          member.connectionId
+        ),
+        clonePresence(member)
+      );
+    },
+    async leave(channel, connectionId) {
+      members.delete(
+        presenceKey(
+          normalizeChannel(channel),
+          normalizeId(
+            connectionId,
+            "connection id"
+          )
+        )
+      );
+    },
+    async leaveConnection(connectionId) {
+      const id = normalizeId(
+        connectionId,
+        "connection id"
+      );
+      for (const [key, member] of members) {
+        if (member.connectionId === id) {
+          members.delete(key);
+        }
+      }
+    },
+    async touch(connectionId, updatedAt) {
+      const id = normalizeId(
+        connectionId,
+        "connection id"
+      );
+      assertFiniteNumber(
+        updatedAt,
+        "presence updatedAt"
+      );
+      for (const member of members.values()) {
+        if (member.connectionId === id) {
+          member.updatedAt = updatedAt;
+        }
+      }
+    },
+    async list(channel) {
+      const normalized = normalizeChannel(channel);
+      return Array.from(
+        members.values()
+      ).filter(
+        (member) => member.channel === normalized
+      ).sort(
+        (left, right) => left.joinedAt - right.joinedAt || left.connectionId.localeCompare(
+          right.connectionId
+        )
+      ).map(clonePresence);
+    },
+    clear() {
+      members.clear();
+    }
+  };
+}
+function createRealtime(options = {}) {
+  const broker = options.broker ?? createMemoryRealtimeBroker();
+  const presence = options.presence ?? createMemoryRealtimePresenceStore();
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const hubId = normalizeId(
+    idFactory(),
+    "hub id"
+  );
+  const heartbeatTimeoutMs = positiveInteger(
+    options.heartbeatTimeoutMs ?? 6e4,
+    "heartbeatTimeoutMs"
+  );
+  const connections = /* @__PURE__ */ new Map();
+  const subscriptions = /* @__PURE__ */ new Map();
+  const handlers = /* @__PURE__ */ new Map();
+  const heartbeatRunners = /* @__PURE__ */ new Set();
+  const unsubscribeBroker = broker.subscribe(
+    async (message) => {
+      await dispatchBrokerMessage(
+        message
+      );
+    }
+  );
+  const hub = {
+    id: hubId,
+    broker,
+    presence,
+    async connect(connectOptions = {}) {
+      const user = connectOptions.user ?? (options.authenticate ? await options.authenticate({
+        request: connectOptions.request,
+        data: connectOptions.data
+      }) ?? void 0 : void 0);
+      const connectionId = normalizeId(
+        connectOptions.connectionId ?? idFactory(),
+        "connection id"
+      );
+      if (connections.has(connectionId)) {
+        throw new Error(
+          `BCP Realtime: connection id "${connectionId}" already exists.`
+        );
+      }
+      const connectedAt = now();
+      assertFiniteNumber(
+        connectedAt,
+        "connection timestamp"
+      );
+      const internal = {
+        api: null,
+        user,
+        socket: connectOptions.socket,
+        channels: /* @__PURE__ */ new Set(),
+        connectedAt,
+        lastSeenAt: connectedAt,
+        connected: true,
+        cleanup: []
+      };
+      const api = {
+        id: connectionId,
+        user,
+        connectedAt,
+        get lastSeenAt() {
+          return internal.lastSeenAt;
+        },
+        get connected() {
+          return internal.connected;
+        },
+        get channels() {
+          return Array.from(
+            internal.channels
+          ).sort();
+        },
+        async join(rawChannel, joinOptions = {}) {
+          assertConnected(
+            internal,
+            connectionId
+          );
+          const channel = normalizeChannel(
+            rawChannel
+          );
+          if (options.authorizeChannel && !await options.authorizeChannel({
+            connection: api,
+            channel
+          })) {
+            throw new Error(
+              `BCP Realtime: connection "${connectionId}" is not authorized for channel "${channel}".`
+            );
+          }
+          if (internal.channels.has(channel)) {
+            return;
+          }
+          internal.channels.add(channel);
+          const timestamp = now();
+          const userId = user !== void 0 && options.getUserId ? optionalId(
+            options.getUserId(
+              user
+            )
+          ) : void 0;
+          await presence.join({
+            connectionId,
+            channel,
+            userId,
+            data: joinOptions.presence,
+            joinedAt: timestamp,
+            updatedAt: timestamp
+          });
+          await sendPresence(
+            channel,
+            "presence.join",
+            connectionId
+          );
+        },
+        async leave(rawChannel) {
+          const channel = normalizeChannel(
+            rawChannel
+          );
+          if (!internal.channels.delete(channel)) {
+            return;
+          }
+          await presence.leave(
+            channel,
+            connectionId
+          );
+          await sendPresence(
+            channel,
+            "presence.leave",
+            connectionId
+          );
+        },
+        async emit(rawChannel, rawEvent, payload) {
+          assertConnected(
+            internal,
+            connectionId
+          );
+          const channel = normalizeChannel(
+            rawChannel
+          );
+          if (!internal.channels.has(channel)) {
+            throw new Error(
+              `BCP Realtime: connection "${connectionId}" has not joined channel "${channel}".`
+            );
+          }
+          const event = normalizeEvent(
+            rawEvent
+          );
+          await api.touch();
+          const group = handlers.get(event);
+          if (group) {
+            for (const handler of group) {
+              await handler({
+                connection: api,
+                channel,
+                event,
+                payload
+              });
+            }
+          }
+        },
+        async send(event, payload, channel = "@system") {
+          await sendToConnection(
+            internal,
+            createEnvelope(
+              normalizeChannel(channel),
+              normalizeEvent(event),
+              payload
+            )
+          );
+        },
+        async touch() {
+          assertConnected(
+            internal,
+            connectionId
+          );
+          internal.lastSeenAt = now();
+          await presence.touch(
+            connectionId,
+            internal.lastSeenAt
+          );
+        },
+        async disconnect(code = 1e3, reason = "connection closed") {
+          if (!internal.connected) {
+            return;
+          }
+          internal.connected = false;
+          connections.delete(
+            connectionId
+          );
+          const channels = Array.from(
+            internal.channels
+          );
+          internal.channels.clear();
+          await presence.leaveConnection(
+            connectionId
+          );
+          for (const channel of channels) {
+            await sendPresence(
+              channel,
+              "presence.leave",
+              connectionId
+            );
+          }
+          for (const cleanup of internal.cleanup.splice(0)) {
+            cleanup();
+          }
+          await internal.socket?.close?.(
+            code,
+            reason
+          );
+        }
+      };
+      internal.api = api;
+      connections.set(
+        connectionId,
+        internal
+      );
+      if (connectOptions.socket) {
+        bindSocket(
+          internal,
+          api
+        );
+      }
+      return api;
+    },
+    attachSocket(socket, attachOptions = {}) {
+      return hub.connect({
+        ...attachOptions,
+        socket
+      });
+    },
+    async broadcast(channel, event, payload, broadcastOptions = {}) {
+      await broker.publish(
+        createEnvelope(
+          normalizeChannel(channel),
+          normalizeEvent(event),
+          payload,
+          broadcastOptions.excludeConnectionId
+        )
+      );
+    },
+    subscribe(channel, listener) {
+      const normalized = normalizeChannel(channel);
+      if (typeof listener !== "function") {
+        throw new TypeError(
+          "BCP Realtime: subscriber must be a function."
+        );
+      }
+      let group = subscriptions.get(normalized);
+      if (!group) {
+        group = /* @__PURE__ */ new Set();
+        subscriptions.set(
+          normalized,
+          group
+        );
+      }
+      group.add(listener);
+      return () => {
+        group?.delete(listener);
+        if (group?.size === 0) {
+          subscriptions.delete(
+            normalized
+          );
+        }
+      };
+    },
+    on(event, handler) {
+      const normalized = normalizeEvent(event);
+      if (typeof handler !== "function") {
+        throw new TypeError(
+          "BCP Realtime: event handler must be a function."
+        );
+      }
+      let group = handlers.get(normalized);
+      if (!group) {
+        group = /* @__PURE__ */ new Set();
+        handlers.set(
+          normalized,
+          group
+        );
+      }
+      group.add(handler);
+      return () => {
+        group?.delete(handler);
+        if (group?.size === 0) {
+          handlers.delete(normalized);
+        }
+      };
+    },
+    members(channel) {
+      return presence.list(
+        normalizeChannel(channel)
+      );
+    },
+    connection(id) {
+      return connections.get(
+        normalizeId(id, "connection id")
+      )?.api ?? null;
+    },
+    connections() {
+      return Array.from(
+        connections.values(),
+        (connection) => connection.api
+      );
+    },
+    async sweepStale() {
+      const cutoff = now() - heartbeatTimeoutMs;
+      const stale = Array.from(
+        connections.values()
+      ).filter(
+        (connection) => connection.lastSeenAt <= cutoff
+      );
+      for (const connection of stale) {
+        await connection.api.disconnect(
+          4e3,
+          "heartbeat timeout"
+        );
+      }
+      return stale.length;
+    },
+    startHeartbeat(heartbeatOptions = {}) {
+      const intervalMs = positiveInteger(
+        heartbeatOptions.intervalMs ?? Math.max(
+          1e3,
+          Math.floor(
+            heartbeatTimeoutMs / 2
+          )
+        ),
+        "heartbeat interval"
+      );
+      let running = true;
+      let stopPromise = null;
+      let timer;
+      const tick = async () => {
+        if (!running) {
+          return;
+        }
+        try {
+          for (const connection of connections.values()) {
+            await connection.api.send(
+              "realtime.ping",
+              {
+                timestamp: now()
+              }
+            );
+          }
+          await hub.sweepStale();
+        } catch (error) {
+          await reportError(error);
+        }
+        if (running) {
+          timer = setTimeout(
+            tick,
+            intervalMs
+          );
+        }
+      };
+      timer = setTimeout(
+        tick,
+        intervalMs
+      );
+      const runner = {
+        get running() {
+          return running;
+        },
+        stop() {
+          if (!stopPromise) {
+            running = false;
+            if (timer) {
+              clearTimeout(timer);
+            }
+            heartbeatRunners.delete(
+              runner
+            );
+            stopPromise = Promise.resolve();
+          }
+          return stopPromise;
+        }
+      };
+      heartbeatRunners.add(runner);
+      return runner;
+    },
+    sse(channel, sseOptions = {}) {
+      return createRealtimeSseResponse(
+        hub,
+        channel,
+        sseOptions
+      );
+    },
+    async close() {
+      await Promise.all(
+        Array.from(
+          heartbeatRunners,
+          (runner) => runner.stop()
+        )
+      );
+      await Promise.all(
+        Array.from(
+          connections.values(),
+          (connection) => connection.api.disconnect(
+            1001,
+            "realtime hub closing"
+          )
+        )
+      );
+      unsubscribeBroker();
+      subscriptions.clear();
+      handlers.clear();
+      await presence.close?.();
+      await broker.close?.();
+    }
+  };
+  return hub;
+  function createEnvelope(channel, event, payload, excludeConnectionId) {
+    return {
+      id: normalizeId(
+        idFactory(),
+        "message id"
+      ),
+      channel,
+      event,
+      payload,
+      timestamp: now(),
+      sourceId: hubId,
+      excludeConnectionId
+    };
+  }
+  async function dispatchBrokerMessage(message) {
+    const subscribers = subscriptions.get(
+      message.channel
+    );
+    if (subscribers) {
+      for (const listener of subscribers) {
+        try {
+          await listener(
+            cloneEnvelope(message)
+          );
+        } catch (error) {
+          await reportError(error);
+        }
+      }
+    }
+    for (const connection of connections.values()) {
+      if (!connection.connected || !connection.channels.has(
+        message.channel
+      ) || connection.api.id === message.excludeConnectionId) {
+        continue;
+      }
+      try {
+        await sendToConnection(
+          connection,
+          message
+        );
+      } catch (error) {
+        await reportError(error);
+      }
+    }
+  }
+  async function sendToConnection(connection, message) {
+    if (!connection.connected) {
+      return;
+    }
+    if (!connection.socket) {
+      return;
+    }
+    await connection.socket.send(
+      JSON.stringify({
+        type: "event",
+        ...message
+      })
+    );
+  }
+  async function sendPresence(channel, event, excludeConnectionId) {
+    const members = await presence.list(channel);
+    await broker.publish(
+      createEnvelope(
+        channel,
+        event,
+        {
+          members
+        },
+        excludeConnectionId
+      )
+    );
+  }
+  function bindSocket(internal, connection) {
+    const socket = internal.socket;
+    if (!socket) {
+      return;
+    }
+    internal.cleanup.push(
+      socket.onMessage(
+        async (raw) => {
+          try {
+            const message = parseSocketMessage(raw);
+            await connection.touch();
+            if (message.type === "ping") {
+              await connection.send(
+                "realtime.pong",
+                {
+                  timestamp: now()
+                }
+              );
+              return;
+            }
+            if (message.type === "join") {
+              await connection.join(
+                normalizeChannel(
+                  message.channel
+                ),
+                {
+                  presence: message.presence
+                }
+              );
+              return;
+            }
+            if (message.type === "leave") {
+              await connection.leave(
+                normalizeChannel(
+                  message.channel
+                )
+              );
+              return;
+            }
+            if (message.type === "event") {
+              await connection.emit(
+                normalizeChannel(
+                  message.channel
+                ),
+                normalizeEvent(
+                  message.event
+                ),
+                message.payload
+              );
+              return;
+            }
+            throw new Error(
+              "BCP Realtime: unsupported socket message type."
+            );
+          } catch (error) {
+            await reportError(error);
+            try {
+              await connection.send(
+                "realtime.error",
+                {
+                  message: formatError(error)
+                }
+              );
+            } catch {
+            }
+          }
+        }
+      )
+    );
+    internal.cleanup.push(
+      socket.onClose(
+        async () => {
+          await connection.disconnect(
+            1e3,
+            "socket closed"
+          );
+        }
+      )
+    );
+    if (socket.onError) {
+      internal.cleanup.push(
+        socket.onError(
+          async (error) => {
+            await reportError(error);
+          }
+        )
+      );
+    }
+  }
+  async function reportError(error) {
+    if (options.onError) {
+      await options.onError(error);
+    }
+  }
+}
+function createRealtimeSseResponse(hub, rawChannel, options = {}) {
+  const channel = normalizeChannel(
+    rawChannel
+  );
+  const encoder = new TextEncoder();
+  const eventName = options.event ? normalizeEvent(
+    options.event
+  ) : void 0;
+  const retryMs = options.retryMs === void 0 ? void 0 : positiveInteger(
+    options.retryMs,
+    "SSE retryMs"
+  );
+  const keepAliveMs = positiveInteger(
+    options.keepAliveMs ?? 15e3,
+    "SSE keepAliveMs"
+  );
+  const stream = new ReadableStream({
+    start(controller) {
+      let closed = false;
+      let timer;
+      let unsubscribe = () => void 0;
+      const close = () => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        unsubscribe();
+        try {
+          controller.close();
+        } catch {
+        }
+      };
+      const write = (value) => {
+        if (!closed) {
+          controller.enqueue(
+            encoder.encode(value)
+          );
+        }
+      };
+      if (retryMs !== void 0) {
+        write(
+          `retry: ${retryMs}
+
+`
+        );
+      }
+      write(
+        ": connected\n\n"
+      );
+      unsubscribe = hub.subscribe(
+        channel,
+        (message) => {
+          if (eventName && message.event !== eventName) {
+            return;
+          }
+          write(
+            serializeSseMessage(
+              message
+            )
+          );
+        }
+      );
+      const keepAlive = () => {
+        if (closed) {
+          return;
+        }
+        write(
+          `: keep-alive ${Date.now()}
+
+`
+        );
+        timer = setTimeout(
+          keepAlive,
+          keepAliveMs
+        );
+      };
+      timer = setTimeout(
+        keepAlive,
+        keepAliveMs
+      );
+      if (options.signal) {
+        if (options.signal.aborted) {
+          close();
+          return;
+        }
+        options.signal.addEventListener(
+          "abort",
+          close,
+          {
+            once: true
+          }
+        );
+      }
+    }
+  });
+  const headers = new Headers(
+    options.headers
+  );
+  headers.set(
+    "Content-Type",
+    "text/event-stream; charset=utf-8"
+  );
+  headers.set(
+    "Cache-Control",
+    "no-cache, no-transform"
+  );
+  headers.set(
+    "Connection",
+    "keep-alive"
+  );
+  headers.set(
+    "X-Accel-Buffering",
+    "no"
+  );
+  return new Response(
+    stream,
+    {
+      status: 200,
+      headers
+    }
+  );
+}
+function serializeSseMessage(message) {
+  const payload = JSON.stringify({
+    id: message.id,
+    channel: message.channel,
+    event: message.event,
+    payload: message.payload,
+    timestamp: message.timestamp
+  });
+  return `id: ${escapeSse(message.id)}
+event: ${escapeSse(message.event)}
+data: ${payload}
+
+`;
+}
+function parseSocketMessage(raw) {
+  if (typeof raw !== "string") {
+    throw new TypeError(
+      "BCP Realtime: socket messages must be UTF-8 strings."
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      "BCP Realtime: socket message must be valid JSON."
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      "BCP Realtime: socket message must be an object."
+    );
+  }
+  return parsed;
+}
+function cloneEnvelope(message) {
+  return {
+    ...message
+  };
+}
+function clonePresence(member) {
+  return {
+    ...member
+  };
+}
+function presenceKey(channel, connectionId) {
+  return `${channel}\0${connectionId}`;
+}
+function normalizeChannel(value) {
+  const channel = String(value ?? "").trim();
+  if (!channel) {
+    throw new TypeError(
+      "BCP Realtime: channel must be a non-empty string."
+    );
+  }
+  if (channel.length > 200) {
+    throw new TypeError(
+      "BCP Realtime: channel must not exceed 200 characters."
+    );
+  }
+  return channel;
+}
+function normalizeEvent(value) {
+  const event = String(value ?? "").trim();
+  if (!event) {
+    throw new TypeError(
+      "BCP Realtime: event must be a non-empty string."
+    );
+  }
+  if (event.length > 200) {
+    throw new TypeError(
+      "BCP Realtime: event must not exceed 200 characters."
+    );
+  }
+  return event;
+}
+function normalizeId(value, field) {
+  const id = String(value ?? "").trim();
+  if (!id) {
+    throw new TypeError(
+      `BCP Realtime: ${field} must be a non-empty string.`
+    );
+  }
+  return id;
+}
+function optionalId(value) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  const id = String(value).trim();
+  return id || void 0;
+}
+function positiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Realtime: ${field} must be a positive integer.`
+    );
+  }
+  return value;
+}
+function assertFiniteNumber(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Realtime: ${field} must be a finite number.`
+    );
+  }
+}
+function assertConnected(connection, id) {
+  if (!connection.connected) {
+    throw new Error(
+      `BCP Realtime: connection "${id}" is closed.`
+    );
+  }
+}
+function escapeSse(value) {
+  return value.replace(
+    /[\r\n]/g,
+    ""
+  );
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message || error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error) ?? String(error);
+  } catch {
+    return String(error);
+  }
+}
+export {
+  createMemoryRealtimeBroker,
+  createMemoryRealtimePresenceStore,
+  createRealtime,
+  createRealtimeSseResponse
+};