@mantiq/realtime 0.0.1

package/src/protocol/Protocol.ts

@@ -0,0 +1,138 @@
+/**
+ * Wire protocol for client ↔ server communication.
+ *
+ * All messages are JSON objects with an `event` field.
+ * Channel names encode their type via prefix: "private:", "presence:", or none (public).
+ */
+
+// ── Client → Server ─────────────────────────────────────────────────────────
+
+export interface SubscribeMessage {
+  event: 'subscribe'
+  channel: string
+}
+
+export interface UnsubscribeMessage {
+  event: 'unsubscribe'
+  channel: string
+}
+
+export interface WhisperMessage {
+  event: 'whisper'
+  channel: string
+  type: string
+  data: Record<string, any>
+}
+
+export interface PingMessage {
+  event: 'ping'
+}
+
+export type ClientMessage =
+  | SubscribeMessage
+  | UnsubscribeMessage
+  | WhisperMessage
+  | PingMessage
+
+// ── Server → Client ─────────────────────────────────────────────────────────
+
+export interface SubscribedMessage {
+  event: 'subscribed'
+  channel: string
+}
+
+export interface UnsubscribedMessage {
+  event: 'unsubscribed'
+  channel: string
+}
+
+export interface ErrorMessage {
+  event: 'error'
+  message: string
+  channel?: string
+}
+
+export interface PongMessage {
+  event: 'pong'
+}
+
+export interface BroadcastMessage {
+  event: string
+  channel: string
+  data: Record<string, any>
+}
+
+export interface MemberJoinedMessage {
+  event: 'member:joined'
+  channel: string
+  data: { userId: string | number; info: Record<string, any> }
+}
+
+export interface MemberLeftMessage {
+  event: 'member:left'
+  channel: string
+  data: { userId: string | number }
+}
+
+export interface MemberHereMessage {
+  event: 'member:here'
+  channel: string
+  data: Array<{ userId: string | number; info: Record<string, any> }>
+}
+
+export type ServerMessage =
+  | SubscribedMessage
+  | UnsubscribedMessage
+  | ErrorMessage
+  | PongMessage
+  | BroadcastMessage
+  | MemberJoinedMessage
+  | MemberLeftMessage
+  | MemberHereMessage
+
+// ── Parsing ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a raw WebSocket message into a typed client message.
+ * Returns null if the message is invalid.
+ */
+export function parseClientMessage(raw: string | Buffer): ClientMessage | null {
+  try {
+    const str = typeof raw === 'string' ? raw : raw.toString('utf-8')
+    const msg = JSON.parse(str)
+
+    if (typeof msg !== 'object' || msg === null || typeof msg.event !== 'string') {
+      return null
+    }
+
+    switch (msg.event) {
+      case 'subscribe':
+        if (typeof msg.channel !== 'string' || !msg.channel) return null
+        return { event: 'subscribe', channel: msg.channel }
+
+      case 'unsubscribe':
+        if (typeof msg.channel !== 'string' || !msg.channel) return null
+        return { event: 'unsubscribe', channel: msg.channel }
+
+      case 'whisper':
+        if (typeof msg.channel !== 'string' || !msg.channel) return null
+        if (typeof msg.type !== 'string' || !msg.type) return null
+        return { event: 'whisper', channel: msg.channel, type: msg.type, data: msg.data ?? {} }
+
+      case 'ping':
+        return { event: 'ping' }
+
+      default:
+        return null
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Serialize a server message to a JSON string.
+ */
+export function serialize(msg: ServerMessage): string {
+  return JSON.stringify(msg)
+}

package/src/server/ConnectionManager.ts

@@ -0,0 +1,192 @@
+import type { WebSocketContext } from '@mantiq/core'
+import type { RealtimeConfig } from '../contracts/RealtimeConfig.ts'
+import { RealtimeError } from '../errors/RealtimeError.ts'
+
+/**
+ * Bun's ServerWebSocket with our context attached.
+ */
+export interface RealtimeSocket {
+  readonly data: WebSocketContext
+  send(data: string | ArrayBuffer | Uint8Array, compress?: boolean): number
+  close(code?: number, reason?: string): void
+  subscribe(topic: string): void
+  unsubscribe(topic: string): void
+  publish(topic: string, data: string | ArrayBuffer | Uint8Array, compress?: boolean): number
+  isSubscribed(topic: string): boolean
+  readonly readyState: number
+  readonly remoteAddress: string
+}
+
+/**
+ * Tracks all active WebSocket connections.
+ *
+ * Handles per-user connection limits, heartbeat ping/pong,
+ * and provides lookup by userId or connection ID.
+ */
+export class ConnectionManager {
+  /** All active connections indexed by a unique connection ID. */
+  private connections = new Map<string, RealtimeSocket>()
+
+  /** User ID → set of connection IDs. */
+  private userConnections = new Map<string | number, Set<string>>()
+
+  /** Connection ID → last pong timestamp. */
+  private lastPong = new Map<string, number>()
+
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private connectionCounter = 0
+
+  constructor(private config: RealtimeConfig) {}
+
+  // ── Connection Lifecycle ────────────────────────────────────────────────
+
+  /**
+   * Register a new connection. Returns a unique connection ID.
+   * Throws if connection limits are exceeded.
+   */
+  add(ws: RealtimeSocket): string {
+    const userId = ws.data.userId
+    const maxTotal = this.config.websocket.maxConnections
+    const maxPerUser = this.config.websocket.maxConnectionsPerUser
+
+    // Check total connection limit
+    if (maxTotal > 0 && this.connections.size >= maxTotal) {
+      throw new RealtimeError('Max connections exceeded', { maxConnections: maxTotal })
+    }
+
+    // Check per-user limit
+    if (userId !== undefined && maxPerUser > 0) {
+      const userConns = this.userConnections.get(userId)
+      if (userConns && userConns.size >= maxPerUser) {
+        throw new RealtimeError('Max connections per user exceeded', { userId, maxPerUser })
+      }
+    }
+
+    const connId = `conn_${++this.connectionCounter}_${Date.now()}`
+    this.connections.set(connId, ws)
+    this.lastPong.set(connId, Date.now())
+
+    // Store in context metadata for reverse lookup
+    ws.data.metadata._connId = connId
+
+    // Track user connections
+    if (userId !== undefined) {
+      if (!this.userConnections.has(userId)) {
+        this.userConnections.set(userId, new Set())
+      }
+      this.userConnections.get(userId)!.add(connId)
+    }
+
+    return connId
+  }
+
+  /**
+   * Remove a connection.
+   */
+  remove(ws: RealtimeSocket): void {
+    const connId = ws.data.metadata._connId as string | undefined
+    if (!connId) return
+
+    this.connections.delete(connId)
+    this.lastPong.delete(connId)
+
+    const userId = ws.data.userId
+    if (userId !== undefined) {
+      const userConns = this.userConnections.get(userId)
+      if (userConns) {
+        userConns.delete(connId)
+        if (userConns.size === 0) this.userConnections.delete(userId)
+      }
+    }
+  }
+
+  /**
+   * Record a pong from a connection.
+   */
+  recordPong(ws: RealtimeSocket): void {
+    const connId = ws.data.metadata._connId as string | undefined
+    if (connId) this.lastPong.set(connId, Date.now())
+  }
+
+  // ── Lookup ──────────────────────────────────────────────────────────────
+
+  get(connId: string): RealtimeSocket | undefined {
+    return this.connections.get(connId)
+  }
+
+  getByUser(userId: string | number): RealtimeSocket[] {
+    const connIds = this.userConnections.get(userId)
+    if (!connIds) return []
+    return [...connIds].map((id) => this.connections.get(id)!).filter(Boolean)
+  }
+
+  getAll(): RealtimeSocket[] {
+    return [...this.connections.values()]
+  }
+
+  count(): number {
+    return this.connections.size
+  }
+
+  userCount(): number {
+    return this.userConnections.size
+  }
+
+  // ── Heartbeat ───────────────────────────────────────────────────────────
+
+  /**
+   * Start sending periodic pings. Connections that don't pong are closed.
+   */
+  startHeartbeat(): void {
+    if (this.heartbeatTimer) return
+
+    const interval = this.config.websocket.heartbeatInterval
+    const timeout = this.config.websocket.heartbeatTimeout
+
+    this.heartbeatTimer = setInterval(() => {
+      const now = Date.now()
+      const stale: RealtimeSocket[] = []
+
+      for (const [connId, ws] of this.connections) {
+        const lastPong = this.lastPong.get(connId) ?? 0
+        if (now - lastPong > interval + timeout) {
+          stale.push(ws)
+        } else {
+          // Send ping
+          try {
+            ws.send(JSON.stringify({ event: 'ping' }))
+          } catch {
+            stale.push(ws)
+          }
+        }
+      }
+
+      // Close stale connections
+      for (const ws of stale) {
+        try { ws.close(4000, 'Heartbeat timeout') } catch { /* already closed */ }
+      }
+    }, interval)
+  }
+
+  /**
+   * Stop the heartbeat timer.
+   */
+  stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+
+  shutdown(): void {
+    this.stopHeartbeat()
+    for (const ws of this.connections.values()) {
+      try { ws.close(1001, 'Server shutting down') } catch { /* ignore */ }
+    }
+    this.connections.clear()
+    this.userConnections.clear()
+    this.lastPong.clear()
+  }
+}

package/src/server/WebSocketServer.ts

@@ -0,0 +1,159 @@
+import type { MantiqRequest } from '@mantiq/core'
+import type { WebSocketContext, WebSocketHandler } from '@mantiq/core'
+import type { RealtimeConfig } from '../contracts/RealtimeConfig.ts'
+import type { RealtimeSocket } from './ConnectionManager.ts'
+import { ConnectionManager } from './ConnectionManager.ts'
+import { ChannelManager } from '../channels/ChannelManager.ts'
+import { parseClientMessage } from '../protocol/Protocol.ts'
+import { serialize } from '../protocol/Protocol.ts'
+
+/**
+ * The core WebSocket handler for @mantiq/realtime.
+ *
+ * Implements `WebSocketHandler` from @mantiq/core and orchestrates
+ * connection management, channel subscriptions, and message routing.
+ *
+ * Registered with `WebSocketKernel.registerHandler()` during boot.
+ */
+export class WebSocketServer implements WebSocketHandler {
+  readonly connections: ConnectionManager
+  readonly channels: ChannelManager
+
+  /** User-provided authentication callback. */
+  private authenticator: ((request: MantiqRequest) => Promise<{ userId?: string | number; metadata?: Record<string, any> } | null>) | null = null
+
+  constructor(private config: RealtimeConfig) {
+    this.connections = new ConnectionManager(config)
+    this.channels = new ChannelManager(config)
+  }
+
+  // ── Configuration ──────────────────────────────────────────────────────
+
+  /**
+   * Register an authentication callback for WebSocket connections.
+   *
+   * Called during upgrade to determine the user identity.
+   * Return `null` to reject the connection, or an object with userId/metadata.
+   *
+   * ```typescript
+   * realtime.authenticate(async (request) => {
+   *   const token = request.header('authorization')?.replace('Bearer ', '')
+   *   const user = await verifyToken(token)
+   *   return user ? { userId: user.id, metadata: { name: user.name } } : null
+   * })
+   * ```
+   */
+  authenticate(callback: (request: MantiqRequest) => Promise<{ userId?: string | number; metadata?: Record<string, any> } | null>): void {
+    this.authenticator = callback
+  }
+
+  // ── WebSocketHandler Implementation ────────────────────────────────────
+
+  /**
+   * Called by WebSocketKernel before upgrade.
+   * Authenticates the request and returns the WebSocket context.
+   */
+  async onUpgrade(request: MantiqRequest): Promise<WebSocketContext | null> {
+    // Check if the request is targeting our WebSocket path
+    const requestPath = request.path()
+    if (requestPath !== this.config.websocket.path) {
+      return null
+    }
+
+    let userId: string | number | undefined
+    let metadata: Record<string, any> = {}
+
+    if (this.authenticator) {
+      const result = await this.authenticator(request)
+      if (result === null) {
+        return null // Auth rejected
+      }
+      userId = result.userId
+      metadata = result.metadata ?? {}
+    }
+
+    return {
+      userId,
+      channels: new Set<string>(),
+      metadata,
+    }
+  }
+
+  /**
+   * Called when a WebSocket connection is established.
+   */
+  open(ws: RealtimeSocket): void {
+    try {
+      const connId = this.connections.add(ws)
+      ws.send(serialize({
+        event: 'connected',
+        channel: '',
+        data: { connectionId: connId },
+      } as any))
+    } catch (error: any) {
+      ws.send(serialize({ event: 'error', message: error.message }))
+      ws.close(4002, error.message)
+    }
+  }
+
+  /**
+   * Called when a message is received from a client.
+   */
+  async message(ws: RealtimeSocket, raw: string | Buffer): Promise<void> {
+    const msg = parseClientMessage(raw)
+    if (!msg) {
+      ws.send(serialize({ event: 'error', message: 'Invalid message format' }))
+      return
+    }
+
+    switch (msg.event) {
+      case 'subscribe':
+        await this.channels.subscribe(ws, msg.channel)
+        break
+
+      case 'unsubscribe':
+        this.channels.unsubscribe(ws, msg.channel)
+        break
+
+      case 'whisper':
+        this.channels.whisper(ws, msg.channel, msg.type, msg.data)
+        break
+
+      case 'ping':
+        this.connections.recordPong(ws)
+        ws.send(serialize({ event: 'pong' } as any))
+        break
+    }
+  }
+
+  /**
+   * Called when a WebSocket connection is closed.
+   */
+  close(ws: RealtimeSocket, _code: number, _reason: string): void {
+    this.channels.removeFromAll(ws)
+    this.connections.remove(ws)
+  }
+
+  /**
+   * Called when the WebSocket backpressure drains.
+   */
+  drain(_ws: RealtimeSocket): void {
+    // No-op — Bun handles backpressure automatically
+  }
+
+  // ── Server Lifecycle ───────────────────────────────────────────────────
+
+  /**
+   * Start the heartbeat monitor for stale connections.
+   */
+  start(): void {
+    this.connections.startHeartbeat()
+  }
+
+  /**
+   * Gracefully shut down: close all connections, stop heartbeat.
+   */
+  shutdown(): void {
+    this.connections.shutdown()
+  }
+}

package/src/sse/SSEManager.ts

@@ -0,0 +1,228 @@
+import type { RealtimeConfig } from '../contracts/RealtimeConfig.ts'
+
+/**
+ * Represents an active SSE connection.
+ */
+export interface SSEConnection {
+  id: string
+  userId?: string | number
+  channels: Set<string>
+  controller: ReadableStreamDefaultController
+  lastEventId: number
+  keepAliveTimer: ReturnType<typeof setInterval> | null
+}
+
+/**
+ * Manages Server-Sent Events connections as a fallback transport.
+ *
+ * SSE is unidirectional (server → client). Clients subscribe to channels
+ * via query params or a separate POST endpoint. The server pushes events
+ * via the SSE stream.
+ *
+ * This is a simpler alternative to WebSockets for environments that
+ * don't support them (firewalls, proxies, etc.).
+ */
+export class SSEManager {
+  /** All active SSE connections. */
+  private connections = new Map<string, SSEConnection>()
+
+  /** Channel → set of connection IDs. */
+  private channelSubscriptions = new Map<string, Set<string>>()
+
+  private connectionCounter = 0
+
+  constructor(private config: RealtimeConfig) {}
+
+  // ── Connection Lifecycle ──────────────────────────────────────────────
+
+  /**
+   * Create an SSE response for a new client connection.
+   *
+   * Usage in a route handler:
+   * ```typescript
+   * router.get('/_sse', (request) => {
+   *   return sseManager.connect(request)
+   * })
+   * ```
+   */
+  connect(options: {
+    userId?: string | number
+    channels?: string[]
+    lastEventId?: string
+  } = {}): Response {
+    const connId = `sse_${++this.connectionCounter}_${Date.now()}`
+
+    let connection: SSEConnection
+
+    const stream = new ReadableStream({
+      start: (controller) => {
+        connection = {
+          id: connId,
+          userId: options.userId,
+          channels: new Set(),
+          controller,
+          lastEventId: 0,
+          keepAliveTimer: null,
+        }
+
+        this.connections.set(connId, connection)
+
+        // Send initial connection event
+        this.sendEvent(connection, 'connected', { connectionId: connId })
+
+        // Subscribe to requested channels
+        if (options.channels) {
+          for (const channel of options.channels) {
+            this.subscribe(connId, channel)
+          }
+        }
+
+        // Start keep-alive
+        connection.keepAliveTimer = setInterval(() => {
+          try {
+            controller.enqueue(': keep-alive\n\n')
+          } catch {
+            this.disconnect(connId)
+          }
+        }, this.config.sse.keepAliveInterval)
+      },
+
+      cancel: () => {
+        this.disconnect(connId)
+      },
+    })
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      },
+    })
+  }
+
+  /**
+   * Disconnect an SSE client.
+   */
+  disconnect(connId: string): void {
+    const conn = this.connections.get(connId)
+    if (!conn) return
+
+    // Clear keep-alive
+    if (conn.keepAliveTimer) {
+      clearInterval(conn.keepAliveTimer)
+    }
+
+    // Remove from all channel subscriptions
+    for (const channel of conn.channels) {
+      const subs = this.channelSubscriptions.get(channel)
+      if (subs) {
+        subs.delete(connId)
+        if (subs.size === 0) {
+          this.channelSubscriptions.delete(channel)
+        }
+      }
+    }
+
+    // Close the stream
+    try {
+      conn.controller.close()
+    } catch { /* already closed */ }
+
+    this.connections.delete(connId)
+  }
+
+  // ── Channel Subscriptions ─────────────────────────────────────────────
+
+  /**
+   * Subscribe an SSE connection to a channel.
+   * Note: SSE only supports public channels (no auth handshake).
+   */
+  subscribe(connId: string, channel: string): boolean {
+    const conn = this.connections.get(connId)
+    if (!conn) return false
+
+    conn.channels.add(channel)
+
+    if (!this.channelSubscriptions.has(channel)) {
+      this.channelSubscriptions.set(channel, new Set())
+    }
+    this.channelSubscriptions.get(channel)!.add(connId)
+
+    this.sendEvent(conn, 'subscribed', { channel })
+    return true
+  }
+
+  /**
+   * Unsubscribe an SSE connection from a channel.
+   */
+  unsubscribe(connId: string, channel: string): void {
+    const conn = this.connections.get(connId)
+    if (!conn) return
+
+    conn.channels.delete(channel)
+
+    const subs = this.channelSubscriptions.get(channel)
+    if (subs) {
+      subs.delete(connId)
+      if (subs.size === 0) {
+        this.channelSubscriptions.delete(channel)
+      }
+    }
+  }
+
+  // ── Broadcasting ──────────────────────────────────────────────────────
+
+  /**
+   * Broadcast an event to all SSE connections subscribed to a channel.
+   */
+  broadcast(channel: string, event: string, data: Record<string, any>): void {
+    const subs = this.channelSubscriptions.get(channel)
+    if (!subs || subs.size === 0) return
+
+    for (const connId of subs) {
+      const conn = this.connections.get(connId)
+      if (conn) {
+        this.sendEvent(conn, event, { channel, data })
+      }
+    }
+  }
+
+  // ── Query ─────────────────────────────────────────────────────────────
+
+  count(): number {
+    return this.connections.size
+  }
+
+  getChannels(): string[] {
+    return [...this.channelSubscriptions.keys()]
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────
+
+  private sendEvent(conn: SSEConnection, event: string, data: any): void {
+    conn.lastEventId++
+    const payload = [
+      `id: ${conn.lastEventId}`,
+      `event: ${event}`,
+      `data: ${JSON.stringify(data)}`,
+      '',
+      '',
+    ].join('\n')
+
+    try {
+      conn.controller.enqueue(payload)
+    } catch {
+      this.disconnect(conn.id)
+    }
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────────
+
+  shutdown(): void {
+    for (const connId of [...this.connections.keys()]) {
+      this.disconnect(connId)
+    }
+  }
+}