openart-realtime-sdk 1.0.1 → 1.0.3

package/dist/server/index.js

@@ -1,2 +1,610 @@
-export * from './handler.js';
-export * from './realtime.js';
+import z from 'zod/v4';
+import * as z2 from 'zod/v4/core';
+
+// src/shared/types.ts
+z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("connected"),
+    channel: z.string(),
+    cursor: z.string().optional()
+  }),
+  z.object({ type: z.literal("reconnect"), timestamp: z.number() }),
+  z.object({ type: z.literal("error"), error: z.string() }),
+  z.object({ type: z.literal("disconnected"), channels: z.array(z.string()) }),
+  z.object({ type: z.literal("ping"), timestamp: z.number() })
+]);
+var userEvent = z.object({
+  id: z.string(),
+  data: z.unknown(),
+  event: z.string(),
+  channel: z.string()
+});
+
+// src/server/utils.ts
+function compareStreamIds(a, b) {
+  const [aTime = 0, aSeq = 0] = a.split("-").map(Number);
+  const [bTime = 0, bSeq = 0] = b.split("-").map(Number);
+  if (aTime !== bTime) return aTime - bTime;
+  return aSeq - bSeq;
+}
+function parseStreamResponse(response) {
+  if (!Array.isArray(response)) return [];
+  return response.map((item) => {
+    const id = item[0];
+    const fields = item[1];
+    const data = {};
+    if (Array.isArray(fields)) {
+      for (let i = 0; i < fields.length; i += 2) {
+        const key = fields[i];
+        if (typeof key === "string") {
+          data[key] = fields[i + 1];
+        }
+      }
+    }
+    if (typeof data.data === "string") {
+      try {
+        data.data = JSON.parse(data.data);
+      } catch {
+      }
+    }
+    return { ...data, id };
+  });
+}
+
+// src/server/handler.ts
+function handle(config) {
+  return async (request) => {
+    const requestStartTime = Date.now();
+    const { searchParams } = new URL(request.url);
+    const rawChannels = searchParams.getAll("channel").length > 0 ? searchParams.getAll("channel") : ["default"];
+    const channels = [...new Set(rawChannels)];
+    const redis = config.realtime._redis;
+    const logger = config.realtime._logger;
+    const subscriptionManager = config.realtime._subscriptionManager;
+    const maxRecoveryLimit = config.maxRecoveryLimit ?? 2e3;
+    if (config.middleware) {
+      const result = await config.middleware({ request, channels });
+      if (result) return result;
+    }
+    if (!redis || !subscriptionManager) {
+      logger.error("No Redis instance provided to Realtime");
+      return new Response(JSON.stringify({ error: "Redis not configured" }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    let cleanup;
+    const unsubs = [];
+    let reconnectTimeout;
+    let keepaliveInterval;
+    let isClosed = false;
+    let handleAbort;
+    const stream = new ReadableStream({
+      async start(controller) {
+        if (request.signal.aborted) {
+          controller.close();
+          return;
+        }
+        cleanup = async () => {
+          if (isClosed) return;
+          isClosed = true;
+          clearTimeout(reconnectTimeout);
+          clearInterval(keepaliveInterval);
+          if (handleAbort) {
+            request.signal.removeEventListener("abort", handleAbort);
+          }
+          unsubs.forEach((unsub) => unsub());
+          try {
+            if (!request.signal.aborted) controller.close();
+            logger.info("\u2705 Connection closed successfully.");
+          } catch (err) {
+            logger.error("\u26A0\uFE0F Error closing controller:", err);
+          }
+        };
+        handleAbort = async () => {
+          await cleanup?.();
+        };
+        request.signal.addEventListener("abort", handleAbort);
+        const safeEnqueue = (data) => {
+          if (isClosed) return;
+          if (controller.desiredSize && controller.desiredSize <= 0) {
+            logger.warn?.("\u26A0\uFE0F Client too slow, dropping message to prevent OOM.");
+            return;
+          }
+          try {
+            controller.enqueue(data);
+          } catch (err) {
+            logger.error("\u26A0\uFE0F Error closing controller:", err);
+          }
+        };
+        const elapsedMs = Date.now() - requestStartTime;
+        const remainingMs = config.realtime._maxDurationSecs * 1e3 - elapsedMs;
+        const streamDurationMs = Math.max(remainingMs - 2e3, 1e3);
+        reconnectTimeout = setTimeout(async () => {
+          const reconnectEvent = {
+            type: "reconnect",
+            timestamp: Date.now()
+          };
+          safeEnqueue(json(reconnectEvent));
+          await cleanup?.();
+        }, streamDurationMs);
+        let buffer = [];
+        let isHistoryReplayed = false;
+        const lastHistoryIds = /* @__PURE__ */ new Map();
+        const onManagerMessage = (message, encodedMessage) => {
+          logger.debug?.("\u2B07\uFE0F  Received event:", message);
+          if (!isHistoryReplayed) {
+            buffer.push(message);
+          } else {
+            safeEnqueue(encodedMessage);
+          }
+        };
+        const executeHistoryPipeline = async () => {
+          const pipeline = redis.pipeline();
+          const channelAcks = /* @__PURE__ */ new Map();
+          for (const channel of channels) {
+            const connectedEvent = {
+              type: "connected",
+              channel
+            };
+            safeEnqueue(json(connectedEvent));
+            const lastAck = searchParams.get(`last_ack_${channel}`) ?? String(Date.now());
+            channelAcks.set(channel, lastAck);
+            pipeline.xrange(
+              channel,
+              `(${lastAck}`,
+              "+",
+              "COUNT",
+              maxRecoveryLimit
+            );
+          }
+          try {
+            return await pipeline.exec();
+          } catch (error) {
+            logger.error("Error executing history pipeline:", error);
+            return null;
+          }
+        };
+        const processHistoryResults = (results) => {
+          if (!results) return;
+          results.forEach((result, index) => {
+            const [err, rawMissing] = result;
+            const channel = channels[index];
+            if (!channel) return;
+            if (err) {
+              logger.error(
+                `Error fetching history for channel ${channel}:`,
+                err
+              );
+              return;
+            }
+            const missingMessages = parseStreamResponse(rawMissing);
+            if (missingMessages.length > 0) {
+              missingMessages.forEach((value) => {
+                const eventWithId = value;
+                const event = userEvent.safeParse(eventWithId);
+                if (event.success) safeEnqueue(json(event.data));
+              });
+              lastHistoryIds.set(
+                channel,
+                missingMessages[missingMessages.length - 1]?.id ?? ""
+              );
+            }
+          });
+        };
+        const flushBuffer = () => {
+          for (const msg of buffer) {
+            const channelLastId = lastHistoryIds.get(msg.channel);
+            if (channelLastId && compareStreamIds(msg.id, channelLastId) <= 0)
+              continue;
+            safeEnqueue(json(msg));
+          }
+          buffer = [];
+          isHistoryReplayed = true;
+          logger.info("\u2705 Subscription established:", { channels });
+        };
+        try {
+          const [_, historyResults] = await Promise.all([
+            Promise.all(
+              channels.map(async (channel) => {
+                const unsub = await subscriptionManager.subscribe(
+                  channel,
+                  onManagerMessage
+                );
+                unsubs.push(unsub);
+              })
+            ),
+            executeHistoryPipeline()
+          ]);
+          processHistoryResults(historyResults);
+          flushBuffer();
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : "Unknown error";
+          logger.error("\u26A0\uFE0F Redis subscriber error:", errorMessage);
+          const errorEvent = {
+            type: "error",
+            error: errorMessage
+          };
+          safeEnqueue(json(errorEvent));
+        }
+        keepaliveInterval = setInterval(() => {
+          const pingEvent = {
+            type: "ping",
+            timestamp: Date.now()
+          };
+          safeEnqueue(json(pingEvent));
+        }, 6e4);
+      },
+      async cancel() {
+        if (isClosed) return;
+        await cleanup?.();
+      }
+    });
+    return new StreamingResponse(stream);
+  };
+}
+var encoder = new TextEncoder();
+function json(data) {
+  return encoder.encode(`data: ${JSON.stringify(data)}
+
+`);
+}
+var StreamingResponse = class extends Response {
+  constructor(res, init) {
+    super(res, {
+      ...init,
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Content-Encoding": "none",
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Headers": "Cache-Control",
+        ...init?.headers
+      }
+    });
+  }
+};
+
+// src/server/subscription-manager.ts
+var encoder2 = new TextEncoder();
+var SubscriptionManager = class {
+  redis;
+  subRedis;
+  // Map<ChannelName, Set<Listener>>
+  listeners = /* @__PURE__ */ new Map();
+  unsubscribeTimers = /* @__PURE__ */ new Map();
+  logger;
+  constructor(redis, logger) {
+    this.redis = redis;
+    this.subRedis = redis.duplicate();
+    this.logger = logger;
+    this.setupMessageListener();
+  }
+  setupMessageListener() {
+    this.subRedis.on("message", (channel, messageStr) => {
+      const handlers = this.listeners.get(channel);
+      if (!handlers || handlers.size === 0) return;
+      try {
+        let payload;
+        if (messageStr.startsWith("{") || messageStr.startsWith("[")) {
+          try {
+            payload = JSON.parse(messageStr);
+          } catch {
+            payload = { data: messageStr };
+          }
+        } else {
+          payload = { data: messageStr };
+        }
+        const result = userEvent.safeParse(payload);
+        if (result.success) {
+          const encodedMessage = encoder2.encode(
+            `data: ${JSON.stringify(result.data)}
+
+`
+          );
+          this.logger.debug?.(
+            `[SubscriptionManager] Dispatching message to ${handlers.size} listeners on ${channel}`
+          );
+          handlers.forEach((listener) => {
+            try {
+              listener(result.data, encodedMessage);
+            } catch (listenerErr) {
+              this.logger.error(
+                `[SubscriptionManager] Error in listener for ${channel}:`,
+                listenerErr
+              );
+            }
+          });
+        }
+      } catch (err) {
+        this.logger.error(
+          `[SubscriptionManager] Error processing message on ${channel}:`,
+          err
+        );
+      }
+    });
+    this.subRedis.on("error", (err) => {
+      this.logger.error("[SubscriptionManager] Redis subscription error:", err);
+    });
+  }
+  async subscribe(channel, listener) {
+    if (this.unsubscribeTimers.has(channel)) {
+      clearTimeout(this.unsubscribeTimers.get(channel));
+      this.unsubscribeTimers.delete(channel);
+      this.logger.debug?.(
+        `[SubscriptionManager] Cancelled pending unsubscribe for: ${channel}`
+      );
+    }
+    if (!this.listeners.has(channel)) {
+      this.listeners.set(channel, /* @__PURE__ */ new Set());
+      this.logger.debug?.(
+        `[SubscriptionManager] Subscribing to Redis channel: ${channel}`
+      );
+      await this.subRedis.subscribe(channel);
+    }
+    const channelListeners = this.listeners.get(channel);
+    channelListeners.add(listener);
+    return () => {
+      const currentListeners = this.listeners.get(channel);
+      if (currentListeners) {
+        currentListeners.delete(listener);
+        if (currentListeners.size === 0) {
+          if (this.unsubscribeTimers.has(channel)) {
+            clearTimeout(this.unsubscribeTimers.get(channel));
+          }
+          const timer = setTimeout(() => {
+            this.listeners.delete(channel);
+            this.unsubscribeTimers.delete(channel);
+            this.logger.debug?.(
+              `[SubscriptionManager] Unsubscribing from Redis channel: ${channel}`
+            );
+            this.subRedis.unsubscribe(channel).catch((err) => {
+              this.logger.error(
+                `[SubscriptionManager] Error unsubscribing from ${channel}:`,
+                err
+              );
+            });
+          }, 2e3);
+          this.unsubscribeTimers.set(channel, timer);
+        }
+      }
+    };
+  }
+  async disconnect() {
+    await this.subRedis.quit().catch(() => this.subRedis.disconnect());
+  }
+};
+
+// src/server/realtime.ts
+var DEFAULT_VERCEL_FLUID_TIMEOUT = 300;
+var RealtimeBase = class {
+  channels = {};
+  _schema;
+  _verbose;
+  _history;
+  /** @internal */
+  _redis;
+  /** @internal */
+  _subscriptionManager;
+  /** @internal */
+  _maxDurationSecs;
+  /** @internal */
+  _logger;
+  constructor(data) {
+    Object.assign(this, data);
+    this._schema = data.schema || {};
+    this._redis = data.redis;
+    this._maxDurationSecs = data.maxDurationSecs ?? DEFAULT_VERCEL_FLUID_TIMEOUT;
+    this._verbose = data.verbose ?? false;
+    this._history = typeof data.history === "boolean" ? {} : data.history ?? {};
+    this._logger = data.logger ?? {
+      info: (...args) => {
+        if (this._verbose) console.log(...args);
+      },
+      warn: (...args) => {
+        console.warn(...args);
+      },
+      error: (...args) => {
+        console.error(...args);
+      },
+      debug: (...args) => {
+        if (this._verbose) console.debug(...args);
+      }
+    };
+    if (this._redis) {
+      this._subscriptionManager = new SubscriptionManager(
+        this._redis,
+        this._logger
+      );
+    }
+    Object.assign(this, this.createEventHandlers("default"));
+  }
+  createEventHandlers(channel, historyOverride) {
+    const historyConfig = {
+      ...this._history,
+      ...typeof historyOverride === "boolean" ? {} : historyOverride ?? {}
+    };
+    let unsubscribe = void 0;
+    let pingInterval = void 0;
+    const startPingInterval = () => {
+      pingInterval = setInterval(() => {
+        this._redis?.publish(
+          channel,
+          JSON.stringify({ type: "ping", timestamp: Date.now() })
+        );
+      }, 6e4);
+    };
+    const stopPingInterval = () => {
+      if (pingInterval) clearInterval(pingInterval);
+    };
+    const historyFunc = async (args) => {
+      const redis = this._redis;
+      if (!redis) throw new Error("Redis not configured.");
+      const start = args?.start ? String(args.start) : "-";
+      const end = args?.end ? String(args.end) : "+";
+      const limit = args?.limit ?? 1e3;
+      const rawHistory = await redis.xrange(
+        channel,
+        start,
+        end,
+        "COUNT",
+        limit
+      );
+      const historyMessages = parseStreamResponse(rawHistory);
+      return historyMessages.map((value) => {
+        if (typeof value === "object" && value !== null) {
+          const { id, channel: channel2, event, data } = value;
+          return { data, event, id, channel: channel2 };
+        }
+        return null;
+      }).filter((item) => item !== null);
+    };
+    const unsubscribeFunc = () => {
+      if (unsubscribe) {
+        unsubscribe();
+        this._logger.info("\u2705 Connection closed successfully.");
+      }
+    };
+    const subscribeFunc = async ({
+      events,
+      onData,
+      history
+    }) => {
+      const redis = this._redis;
+      if (!redis) throw new Error("Redis not configured.");
+      const subManager = this._subscriptionManager;
+      if (!subManager) throw new Error("SubscriptionManager not initialized.");
+      const buffer = [];
+      let isHistoryReplayed = false;
+      let lastHistoryId = null;
+      const onMessage = (message) => {
+        if (events && !events.includes(message.event)) return;
+        if (!isHistoryReplayed) {
+          buffer.push(message);
+        } else {
+          onData(message);
+        }
+      };
+      const unsubFromManager = await subManager.subscribe(channel, onMessage);
+      try {
+        if (history) {
+          const start = typeof history === "object" && history.start ? String(history.start) : "-";
+          const end = typeof history === "object" && history.end ? String(history.end) : "+";
+          const limit = typeof history === "object" ? history.limit : void 0;
+          let rawMessages = [];
+          if (limit) {
+            rawMessages = await redis.xrange(
+              channel,
+              start,
+              end,
+              "COUNT",
+              limit
+            );
+          } else {
+            rawMessages = await redis.xrange(channel, start, end);
+          }
+          const messages = parseStreamResponse(rawMessages);
+          for (const message of messages) {
+            const typedMessage = message;
+            if (!typedMessage.event || events && !events.includes(typedMessage.event))
+              continue;
+            const result = userEvent.safeParse(message);
+            if (result.success) {
+              onData(
+                result.data
+              );
+            }
+          }
+          if (messages.length > 0) {
+            lastHistoryId = messages[messages.length - 1]?.id ?? null;
+          }
+        }
+        for (const message of buffer) {
+          if (lastHistoryId && compareStreamIds(message.id, lastHistoryId) <= 0)
+            continue;
+          onData(message);
+        }
+        buffer.length = 0;
+        isHistoryReplayed = true;
+        startPingInterval();
+      } catch (err) {
+        unsubFromManager();
+        throw err;
+      }
+      unsubscribe = () => {
+        stopPingInterval();
+        unsubFromManager();
+      };
+      return unsubscribe;
+    };
+    const findSchema = (path) => {
+      let current = this._schema;
+      for (const key of path) {
+        if (!current || typeof current !== "object") return void 0;
+        current = current[key];
+      }
+      const typedCurrent = current;
+      return typedCurrent?._zod || typedCurrent?._def ? current : void 0;
+    };
+    const emitFunc = async (event, data, opts) => {
+      const pathParts = event.split(".");
+      const schema = findSchema(pathParts);
+      if (schema) {
+        z2.parse(schema, data);
+      }
+      if (!this._redis) {
+        this._logger.warn("No Redis instance provided to Realtime.");
+        return;
+      }
+      const currentHistoryConfig = {
+        ...historyConfig,
+        ...typeof opts?.history === "boolean" ? {} : opts?.history ?? {}
+      };
+      const xaddArgs = [channel];
+      if (currentHistoryConfig.maxLength) {
+        xaddArgs.push("MAXLEN", "~", currentHistoryConfig.maxLength);
+      }
+      xaddArgs.push("*");
+      const dataStr = typeof data === "object" ? JSON.stringify(data) : String(data);
+      xaddArgs.push("data", dataStr);
+      xaddArgs.push("event", event);
+      xaddArgs.push("channel", channel);
+      const id = await this._redis.xadd(...xaddArgs);
+      const payload = {
+        data,
+        event,
+        channel,
+        id
+      };
+      const pipeline = this._redis.pipeline();
+      if (currentHistoryConfig.expireAfterSecs) {
+        pipeline.expire(channel, currentHistoryConfig.expireAfterSecs);
+      }
+      pipeline.publish(channel, JSON.stringify(payload));
+      await pipeline.exec();
+      this._logger.info(`\u2B06\uFE0F  Emitted event:`, {
+        id,
+        data,
+        event,
+        channel
+      });
+    };
+    return {
+      history: historyFunc,
+      unsubscribe: unsubscribeFunc,
+      subscribe: subscribeFunc,
+      emit: emitFunc
+    };
+  }
+  channel(channel, history) {
+    if (!this.channels[channel]) {
+      this.channels[channel] = this.createEventHandlers(channel, history);
+    }
+    return this.channels[channel];
+  }
+};
+var Realtime = RealtimeBase;
+
+export { Realtime, StreamingResponse, handle, json };

package/dist/shared/index.cjs

@@ -1,12 +1,29 @@
 'use strict';
 
-var types = require('./types');
+var z = require('zod/v4');
 
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+var z__default = /*#__PURE__*/_interopDefault(z);
 
-Object.keys(types).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return types[k]; }
-	});
+// src/shared/types.ts
+var systemEvent = z__default.default.discriminatedUnion("type", [
+  z__default.default.object({
+    type: z__default.default.literal("connected"),
+    channel: z__default.default.string(),
+    cursor: z__default.default.string().optional()
+  }),
+  z__default.default.object({ type: z__default.default.literal("reconnect"), timestamp: z__default.default.number() }),
+  z__default.default.object({ type: z__default.default.literal("error"), error: z__default.default.string() }),
+  z__default.default.object({ type: z__default.default.literal("disconnected"), channels: z__default.default.array(z__default.default.string()) }),
+  z__default.default.object({ type: z__default.default.literal("ping"), timestamp: z__default.default.number() })
+]);
+var userEvent = z__default.default.object({
+  id: z__default.default.string(),
+  data: z__default.default.unknown(),
+  event: z__default.default.string(),
+  channel: z__default.default.string()
 });
+
+exports.systemEvent = systemEvent;
+exports.userEvent = userEvent;

package/dist/shared/index.js

@@ -1 +1,22 @@
-export * from './types';
+import z from 'zod/v4';
+
+// src/shared/types.ts
+var systemEvent = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("connected"),
+    channel: z.string(),
+    cursor: z.string().optional()
+  }),
+  z.object({ type: z.literal("reconnect"), timestamp: z.number() }),
+  z.object({ type: z.literal("error"), error: z.string() }),
+  z.object({ type: z.literal("disconnected"), channels: z.array(z.string()) }),
+  z.object({ type: z.literal("ping"), timestamp: z.number() })
+]);
+var userEvent = z.object({
+  id: z.string(),
+  data: z.unknown(),
+  event: z.string(),
+  channel: z.string()
+});
+
+export { systemEvent, userEvent };