@parsrun/realtime 0.1.0

package/dist/hono.d.ts

@@ -0,0 +1,76 @@
+import { Context, MiddlewareHandler, Hono } from 'hono';
+import { SSEAdapter } from './adapters/sse.js';
+import { RealtimeAdapter, SSEAdapterOptions } from './types.js';
+
+/**
+ * @parsrun/realtime - Hono Integration
+ * Middleware and routes for Hono framework
+ */
+
+/**
+ * Hono realtime context variables
+ */
+interface RealtimeVariables {
+    realtime: {
+        adapter: RealtimeAdapter;
+        sessionId: string;
+        userId: string | undefined;
+    };
+}
+/**
+ * SSE route options
+ */
+interface SSERouteOptions {
+    /** Get session ID from context (default: query param or random) */
+    getSessionId?: (c: Context) => string;
+    /** Get user ID from context (default: from auth) */
+    getUserId?: (c: Context) => string | undefined;
+    /** Channels the user can subscribe to */
+    getChannels?: (c: Context) => string[];
+    /** Called when connection opens */
+    onConnect?: (c: Context, sessionId: string) => void | Promise<void>;
+    /** Called when connection closes */
+    onDisconnect?: (c: Context, sessionId: string) => void | Promise<void>;
+}
+/**
+ * Durable Objects route options
+ */
+interface DORouteOptions {
+    /** Durable Object namespace binding name */
+    namespaceBinding: string;
+    /** Channel prefix */
+    channelPrefix?: string;
+    /** Authorize connection */
+    authorize?: (c: Context, channel: string) => boolean | Promise<boolean>;
+}
+/**
+ * Create SSE realtime middleware
+ * Adds SSE adapter to context
+ */
+declare function sseMiddleware(options?: SSEAdapterOptions): MiddlewareHandler<{
+    Variables: RealtimeVariables;
+}>;
+/**
+ * Create SSE subscription endpoint
+ * Client connects to this endpoint to receive events
+ */
+declare function createSSEHandler(adapter: SSEAdapter, options?: SSERouteOptions): (c: Context) => Response | Promise<Response>;
+/**
+ * Create complete SSE routes for Hono
+ */
+declare function createSSERoutes(adapter: SSEAdapter, options?: SSERouteOptions): Hono;
+/**
+ * Create Durable Objects realtime routes for Hono
+ * Proxies requests to the appropriate Durable Object
+ */
+declare function createDORoutes(options: DORouteOptions): Hono;
+/**
+ * Broadcast helper for use in route handlers
+ */
+declare function broadcast(adapter: RealtimeAdapter, channel: string, event: string, data: unknown): Promise<void>;
+/**
+ * Send to user helper
+ */
+declare function sendToUser(adapter: RealtimeAdapter, channel: string, userId: string, event: string, data: unknown): Promise<void>;
+
+export { type DORouteOptions, type RealtimeVariables, type SSERouteOptions, broadcast, createDORoutes, createSSEHandler, createSSERoutes, sendToUser, sseMiddleware };

package/dist/hono.js

@@ -0,0 +1,551 @@
+// src/hono.ts
+import { Hono } from "hono";
+
+// src/types.ts
+var RealtimeError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "RealtimeError";
+  }
+};
+var RealtimeErrorCodes = {
+  CONNECTION_FAILED: "CONNECTION_FAILED",
+  CHANNEL_NOT_FOUND: "CHANNEL_NOT_FOUND",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
+  RATE_LIMITED: "RATE_LIMITED",
+  ADAPTER_ERROR: "ADAPTER_ERROR",
+  INVALID_MESSAGE: "INVALID_MESSAGE"
+};
+function createMessage(options) {
+  return {
+    id: crypto.randomUUID(),
+    event: options.event,
+    channel: options.channel,
+    data: options.data,
+    senderId: options.senderId,
+    timestamp: Date.now(),
+    metadata: options.metadata
+  };
+}
+function formatSSEEvent(message) {
+  const lines = [];
+  lines.push(`id:${message.id}`);
+  lines.push(`event:${message.event}`);
+  lines.push(`data:${JSON.stringify(message)}`);
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+// src/adapters/sse.ts
+var DEFAULT_OPTIONS = {
+  pingInterval: 3e4,
+  connectionTimeout: 0,
+  maxConnectionsPerChannel: 1e3,
+  retryDelay: 3e3
+};
+var SSEAdapter = class {
+  type = "sse";
+  options;
+  connections = /* @__PURE__ */ new Map();
+  channelSubscribers = /* @__PURE__ */ new Map();
+  presence = /* @__PURE__ */ new Map();
+  pingIntervalId = null;
+  constructor(options = {}) {
+    this.options = {
+      pingInterval: options.pingInterval ?? DEFAULT_OPTIONS.pingInterval,
+      connectionTimeout: options.connectionTimeout ?? DEFAULT_OPTIONS.connectionTimeout,
+      maxConnectionsPerChannel: options.maxConnectionsPerChannel ?? DEFAULT_OPTIONS.maxConnectionsPerChannel,
+      retryDelay: options.retryDelay ?? DEFAULT_OPTIONS.retryDelay
+    };
+    if (this.options.pingInterval > 0) {
+      this.startPingInterval();
+    }
+  }
+  /**
+   * Create SSE response for a new connection
+   */
+  createConnection(sessionId, userId) {
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const connection = {
+      sessionId,
+      userId,
+      channels: /* @__PURE__ */ new Set(),
+      writer,
+      state: "open",
+      createdAt: Date.now(),
+      lastPingAt: Date.now()
+    };
+    this.connections.set(sessionId, connection);
+    const encoder = new TextEncoder();
+    writer.write(encoder.encode(`retry:${this.options.retryDelay}
+
+`));
+    const response = new Response(readable, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no"
+        // Disable nginx buffering
+      }
+    });
+    return { response, connection };
+  }
+  /**
+   * Close a connection
+   */
+  async closeConnection(sessionId) {
+    const connection = this.connections.get(sessionId);
+    if (!connection) return;
+    connection.state = "closed";
+    for (const channel of connection.channels) {
+      await this.unsubscribe(channel, sessionId);
+      await this.removePresence(channel, sessionId);
+    }
+    try {
+      await connection.writer.close();
+    } catch {
+    }
+    this.connections.delete(sessionId);
+  }
+  /**
+   * Get a connection by session ID
+   */
+  getConnection(sessionId) {
+    return this.connections.get(sessionId);
+  }
+  /**
+   * Get all active connections
+   */
+  getConnections() {
+    return this.connections;
+  }
+  // ============================================================================
+  // RealtimeAdapter Implementation
+  // ============================================================================
+  async subscribe(channel, sessionId, handler) {
+    const connection = this.connections.get(sessionId);
+    if (!connection) {
+      throw new RealtimeError(
+        "Connection not found",
+        RealtimeErrorCodes.CONNECTION_FAILED
+      );
+    }
+    const subscribers = this.channelSubscribers.get(channel);
+    if (subscribers && subscribers.size >= this.options.maxConnectionsPerChannel) {
+      throw new RealtimeError(
+        "Channel subscriber limit reached",
+        RealtimeErrorCodes.RATE_LIMITED
+      );
+    }
+    if (!this.channelSubscribers.has(channel)) {
+      this.channelSubscribers.set(channel, /* @__PURE__ */ new Map());
+    }
+    this.channelSubscribers.get(channel).set(sessionId, handler);
+    connection.channels.add(channel);
+    await this.sendToConnection(connection, {
+      id: crypto.randomUUID(),
+      event: "channel:subscribe",
+      channel,
+      data: { channel },
+      timestamp: Date.now()
+    });
+  }
+  async unsubscribe(channel, sessionId) {
+    const subscribers = this.channelSubscribers.get(channel);
+    if (subscribers) {
+      subscribers.delete(sessionId);
+      if (subscribers.size === 0) {
+        this.channelSubscribers.delete(channel);
+      }
+    }
+    const connection = this.connections.get(sessionId);
+    if (connection) {
+      connection.channels.delete(channel);
+    }
+  }
+  async publish(channel, message) {
+    const subscribers = this.channelSubscribers.get(channel);
+    if (!subscribers) return;
+    const promises = [];
+    for (const [sessionId, handler] of subscribers) {
+      const connection = this.connections.get(sessionId);
+      if (connection && connection.state === "open") {
+        promises.push(this.sendToConnection(connection, message));
+        try {
+          const result = handler(message);
+          if (result instanceof Promise) {
+            promises.push(result.then(() => {
+            }));
+          }
+        } catch {
+        }
+      }
+    }
+    await Promise.allSettled(promises);
+  }
+  async sendToSession(sessionId, message) {
+    const connection = this.connections.get(sessionId);
+    if (!connection || connection.state !== "open") {
+      return false;
+    }
+    try {
+      await this.sendToConnection(connection, message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getSubscribers(channel) {
+    const subscribers = this.channelSubscribers.get(channel);
+    return subscribers ? Array.from(subscribers.keys()) : [];
+  }
+  async setPresence(channel, sessionId, userId, data) {
+    if (!this.presence.has(channel)) {
+      this.presence.set(channel, /* @__PURE__ */ new Map());
+    }
+    const now = Date.now();
+    const existing = this.presence.get(channel).get(sessionId);
+    const user = {
+      userId,
+      sessionId,
+      data,
+      joinedAt: existing?.joinedAt ?? now,
+      lastSeenAt: now
+    };
+    this.presence.get(channel).set(sessionId, user);
+    const eventType = existing ? "presence:update" : "presence:join";
+    await this.publish(channel, {
+      id: crypto.randomUUID(),
+      event: eventType,
+      channel,
+      data: {
+        type: existing ? "update" : "join",
+        user,
+        presence: await this.getPresence(channel)
+      },
+      timestamp: now
+    });
+  }
+  async removePresence(channel, sessionId) {
+    const channelPresence = this.presence.get(channel);
+    if (!channelPresence) return;
+    const user = channelPresence.get(sessionId);
+    if (!user) return;
+    channelPresence.delete(sessionId);
+    if (channelPresence.size === 0) {
+      this.presence.delete(channel);
+    }
+    await this.publish(channel, {
+      id: crypto.randomUUID(),
+      event: "presence:leave",
+      channel,
+      data: {
+        type: "leave",
+        user,
+        presence: await this.getPresence(channel)
+      },
+      timestamp: Date.now()
+    });
+  }
+  async getPresence(channel) {
+    const channelPresence = this.presence.get(channel);
+    if (!channelPresence) return [];
+    return Array.from(channelPresence.values());
+  }
+  async close() {
+    if (this.pingIntervalId) {
+      clearInterval(this.pingIntervalId);
+      this.pingIntervalId = null;
+    }
+    const closePromises = Array.from(this.connections.keys()).map(
+      (sessionId) => this.closeConnection(sessionId)
+    );
+    await Promise.allSettled(closePromises);
+    this.connections.clear();
+    this.channelSubscribers.clear();
+    this.presence.clear();
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  async sendToConnection(connection, message) {
+    if (connection.state !== "open") return;
+    const encoder = new TextEncoder();
+    const sseEvent = formatSSEEvent(message);
+    try {
+      await connection.writer.write(encoder.encode(sseEvent));
+    } catch (err) {
+      connection.state = "closed";
+      await this.closeConnection(connection.sessionId);
+    }
+  }
+  startPingInterval() {
+    this.pingIntervalId = setInterval(() => {
+      this.sendPingToAll();
+    }, this.options.pingInterval);
+  }
+  async sendPingToAll() {
+    const now = Date.now();
+    const encoder = new TextEncoder();
+    const pingEvent = `event:ping
+data:${now}
+
+`;
+    for (const [sessionId, connection] of this.connections) {
+      if (connection.state !== "open") continue;
+      if (this.options.connectionTimeout > 0 && now - connection.lastPingAt > this.options.connectionTimeout) {
+        await this.closeConnection(sessionId);
+        continue;
+      }
+      try {
+        await connection.writer.write(encoder.encode(pingEvent));
+        connection.lastPingAt = now;
+      } catch {
+        await this.closeConnection(sessionId);
+      }
+    }
+  }
+  /**
+   * Update last ping time (call when receiving client ping)
+   */
+  updateLastPing(sessionId) {
+    const connection = this.connections.get(sessionId);
+    if (connection) {
+      connection.lastPingAt = Date.now();
+    }
+  }
+  /**
+   * Get statistics
+   */
+  getStats() {
+    const connectionsByChannel = {};
+    for (const [channel, subscribers] of this.channelSubscribers) {
+      connectionsByChannel[channel] = subscribers.size;
+    }
+    return {
+      totalConnections: this.connections.size,
+      totalChannels: this.channelSubscribers.size,
+      connectionsByChannel
+    };
+  }
+};
+
+// src/hono.ts
+function sseMiddleware(options) {
+  const adapter = new SSEAdapter(options);
+  return async (c, next) => {
+    const sessionId = c.req.query("sessionId") || crypto.randomUUID();
+    const vars = c.var;
+    const userId = typeof vars["userId"] === "string" ? vars["userId"] : void 0;
+    c.set("realtime", {
+      adapter,
+      sessionId,
+      userId
+    });
+    await next();
+  };
+}
+function createSSEHandler(adapter, options = {}) {
+  return async (c) => {
+    const sessionId = options.getSessionId?.(c) || c.req.query("sessionId") || crypto.randomUUID();
+    const vars = c.var;
+    const userId = options.getUserId?.(c) || (typeof vars["userId"] === "string" ? vars["userId"] : void 0);
+    const channels = options.getChannels?.(c) || c.req.query("channels")?.split(",") || [];
+    const { response } = adapter.createConnection(sessionId, userId);
+    for (const channel of channels) {
+      await adapter.subscribe(channel, sessionId, () => {
+      });
+    }
+    if (options.onConnect) {
+      await options.onConnect(c, sessionId);
+    }
+    c.req.raw.signal.addEventListener("abort", async () => {
+      await adapter.closeConnection(sessionId);
+      if (options.onDisconnect) {
+        await options.onDisconnect(c, sessionId);
+      }
+    });
+    return response;
+  };
+}
+function createSSERoutes(adapter, options = {}) {
+  const app = new Hono();
+  app.get("/subscribe", createSSEHandler(adapter, options));
+  app.post("/subscribe/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const sessionId = c.req.query("sessionId");
+    if (!sessionId) {
+      return c.json({ error: "sessionId required" }, 400);
+    }
+    const connection = adapter.getConnection(sessionId);
+    if (!connection) {
+      return c.json({ error: "Connection not found" }, 404);
+    }
+    await adapter.subscribe(channel, sessionId, () => {
+    });
+    return c.json({ success: true, channel });
+  });
+  app.post("/unsubscribe/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const sessionId = c.req.query("sessionId");
+    if (!sessionId) {
+      return c.json({ error: "sessionId required" }, 400);
+    }
+    await adapter.unsubscribe(channel, sessionId);
+    return c.json({ success: true, channel });
+  });
+  app.post("/broadcast/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const body = await c.req.json();
+    const message = createMessage({
+      event: body.event,
+      channel,
+      data: body.data
+    });
+    await adapter.publish(channel, message);
+    return c.json({ success: true });
+  });
+  app.get("/presence/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const presence = await adapter.getPresence(channel);
+    return c.json(presence);
+  });
+  app.post("/presence/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const sessionId = c.req.query("sessionId");
+    const userId = c.req.query("userId") || sessionId;
+    const data = await c.req.json();
+    if (!sessionId) {
+      return c.json({ error: "sessionId required" }, 400);
+    }
+    await adapter.setPresence(channel, sessionId, userId, data);
+    return c.json({ success: true });
+  });
+  app.delete("/presence/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const sessionId = c.req.query("sessionId");
+    if (!sessionId) {
+      return c.json({ error: "sessionId required" }, 400);
+    }
+    await adapter.removePresence(channel, sessionId);
+    return c.json({ success: true });
+  });
+  app.get("/stats", (c) => {
+    return c.json(adapter.getStats());
+  });
+  return app;
+}
+function createDORoutes(options) {
+  const app = new Hono();
+  const prefix = options.channelPrefix ?? "channel:";
+  app.get("/ws/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    if (options.authorize) {
+      const authorized = await options.authorize(c, channel);
+      if (!authorized) {
+        return c.json({ error: "Unauthorized" }, 403);
+      }
+    }
+    const env = c.env;
+    const namespace = env[options.namespaceBinding];
+    if (!namespace) {
+      return c.json(
+        { error: `Namespace ${options.namespaceBinding} not found` },
+        500
+      );
+    }
+    const id = namespace.idFromName(`${prefix}${channel}`);
+    const stub = namespace.get(id);
+    const url = new URL(c.req.url);
+    url.pathname = `/ws/${channel}`;
+    return stub.fetch(new Request(url.toString(), c.req.raw));
+  });
+  app.post("/broadcast/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const env = c.env;
+    const namespace = env[options.namespaceBinding];
+    if (!namespace) {
+      return c.json(
+        { error: `Namespace ${options.namespaceBinding} not found` },
+        500
+      );
+    }
+    const id = namespace.idFromName(`${prefix}${channel}`);
+    const stub = namespace.get(id);
+    const body = await c.req.json();
+    const response = await stub.fetch(
+      new Request("https://do/broadcast", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      })
+    );
+    return new Response(response.body, {
+      status: response.status,
+      headers: response.headers
+    });
+  });
+  app.get("/presence/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const env = c.env;
+    const namespace = env[options.namespaceBinding];
+    if (!namespace) {
+      return c.json(
+        { error: `Namespace ${options.namespaceBinding} not found` },
+        500
+      );
+    }
+    const id = namespace.idFromName(`${prefix}${channel}`);
+    const stub = namespace.get(id);
+    const response = await stub.fetch(new Request("https://do/presence"));
+    return new Response(response.body, {
+      status: response.status,
+      headers: response.headers
+    });
+  });
+  app.get("/info/:channel", async (c) => {
+    const channel = c.req.param("channel");
+    const env = c.env;
+    const namespace = env[options.namespaceBinding];
+    if (!namespace) {
+      return c.json(
+        { error: `Namespace ${options.namespaceBinding} not found` },
+        500
+      );
+    }
+    const id = namespace.idFromName(`${prefix}${channel}`);
+    const stub = namespace.get(id);
+    const response = await stub.fetch(new Request("https://do/info"));
+    return new Response(response.body, {
+      status: response.status,
+      headers: response.headers
+    });
+  });
+  return app;
+}
+async function broadcast(adapter, channel, event, data) {
+  const message = createMessage({ event, channel, data });
+  await adapter.publish(channel, message);
+}
+async function sendToUser(adapter, channel, userId, event, data) {
+  const presence = await adapter.getPresence(channel);
+  const userSessions = presence.filter((p) => p.userId === userId);
+  const message = createMessage({ event, channel, data });
+  for (const session of userSessions) {
+    await adapter.sendToSession(session.sessionId, message);
+  }
+}
+export {
+  broadcast,
+  createDORoutes,
+  createSSEHandler,
+  createSSERoutes,
+  sendToUser,
+  sseMiddleware
+};
+//# sourceMappingURL=hono.js.map