@mantiq/realtime 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/realtime
+
+WebSocket server, SSE, and channel system for MantiqJS — public, private, and presence channels.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/realtime
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mantiq/realtime",
+  "version": "0.0.1",
+  "description": "WebSocket, SSE, channels, broadcasting",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/realtime",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/realtime"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "realtime"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*",
+    "@mantiq/events": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/RealtimeServiceProvider.ts

@@ -0,0 +1,71 @@
+import { ServiceProvider, ConfigRepository, WebSocketKernel } from '@mantiq/core'
+import { BroadcastManager } from '@mantiq/events'
+import { WebSocketServer } from './server/WebSocketServer.ts'
+import { BunBroadcaster } from './broadcast/BunBroadcaster.ts'
+import { SSEManager } from './sse/SSEManager.ts'
+import type { RealtimeConfig } from './contracts/RealtimeConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/RealtimeConfig.ts'
+import { REALTIME, setRealtimeInstance } from './helpers/realtime.ts'
+
+/**
+ * Wires up the realtime server, broadcast driver, and SSE fallback.
+ *
+ * Register this provider in your application to enable WebSocket support:
+ *
+ * ```typescript
+ * // app.ts
+ * app.register(RealtimeServiceProvider)
+ * ```
+ *
+ * Then define channel authorization in your boot code:
+ *
+ * ```typescript
+ * import { realtime } from '@mantiq/realtime'
+ *
+ * realtime().channels.authorize('orders.*', async (userId, channel) => {
+ *   const orderId = channel.split('.')[1]
+ *   return await userOwnsOrder(userId, orderId)
+ * })
+ * ```
+ */
+export class RealtimeServiceProvider extends ServiceProvider {
+  override register(): void {
+    // Merge user config with defaults
+    let config = DEFAULT_CONFIG
+    try {
+      const configRepo = this.app.make(ConfigRepository)
+      const userConfig = configRepo.get<Partial<RealtimeConfig>>('realtime', {})
+      config = { ...DEFAULT_CONFIG, ...userConfig }
+    } catch {
+      // ConfigRepository not yet registered — use defaults
+    }
+
+    // WebSocket server — singleton
+    this.app.singleton(WebSocketServer, () => new WebSocketServer(config))
+    this.app.alias(WebSocketServer, REALTIME)
+
+    // SSE manager — singleton
+    this.app.singleton(SSEManager, () => new SSEManager(config))
+  }
+
+  override boot(): void {
+    const server = this.app.make(WebSocketServer)
+    setRealtimeInstance(server)
+
+    // Register with the WebSocket kernel so HttpKernel can route upgrades
+    const wsKernel = this.app.make(WebSocketKernel)
+    wsKernel.registerHandler(server)
+
+    // Register the 'bun' broadcast driver with BroadcastManager
+    try {
+      const broadcastManager = this.app.make(BroadcastManager)
+      broadcastManager.extend('bun', () => new BunBroadcaster(server.channels))
+    } catch {
+      // @mantiq/events not installed — broadcasting via events won't work,
+      // but direct channel.broadcast() still works
+    }
+
+    // Start heartbeat monitor
+    server.start()
+  }
+}

package/src/broadcast/BunBroadcaster.ts

@@ -0,0 +1,24 @@
+import type { Broadcaster } from '@mantiq/events'
+import type { ChannelManager } from '../channels/ChannelManager.ts'
+
+/**
+ * Broadcasts events to WebSocket subscribers via Bun's in-process pub/sub.
+ *
+ * This is the default broadcast driver for @mantiq/realtime.
+ * It works for single-server deployments. For multi-server setups,
+ * use the Redis driver instead.
+ *
+ * Registered with `BroadcastManager.extend('bun', ...)` during boot.
+ */
+export class BunBroadcaster implements Broadcaster {
+  constructor(private channelManager: ChannelManager) {}
+
+  /**
+   * Broadcast an event to all subscribers on the given channels.
+   */
+  async broadcast(channels: string[], event: string, data: Record<string, any>): Promise<void> {
+    for (const channel of channels) {
+      this.channelManager.broadcast(channel, event, data)
+    }
+  }
+}

package/src/channels/ChannelManager.ts

@@ -0,0 +1,309 @@
+import type { ChannelAuthorizer, PresenceMember } from '../contracts/Channel.ts'
+import { parseChannelName } from '../contracts/Channel.ts'
+import type { RealtimeSocket } from '../server/ConnectionManager.ts'
+import type { RealtimeConfig } from '../contracts/RealtimeConfig.ts'
+import { serialize } from '../protocol/Protocol.ts'
+
+/**
+ * Manages channel subscriptions, authorization, and presence tracking.
+ *
+ * Channels are created lazily on first subscribe and cleaned up when empty.
+ * Authorization callbacks are registered by the app in `routes/channels.ts`
+ * (or wherever the user configures them).
+ */
+export class ChannelManager {
+  /** channel name → set of subscribed sockets. */
+  private subscriptions = new Map<string, Set<RealtimeSocket>>()
+
+  /** Authorization callbacks keyed by channel pattern. */
+  private authorizers = new Map<string, ChannelAuthorizer>()
+
+  /** Presence members keyed by channel name → userId → member info. */
+  private presenceMembers = new Map<string, Map<string | number, PresenceMember>>()
+
+  constructor(private config: RealtimeConfig) {}
+
+  // ── Authorization Registration ──────────────────────────────────────────
+
+  /**
+   * Register an authorization callback for a channel pattern.
+   *
+   * Patterns support `*` wildcards:
+   * - `"orders.*"` matches `"private:orders.1"`, `"private:orders.42"`
+   * - `"chat.*"` matches `"presence:chat.room1"`
+   *
+   * The pattern is matched against the base name (without the prefix).
+   */
+  authorize(pattern: string, callback: ChannelAuthorizer): void {
+    this.authorizers.set(pattern, callback)
+  }
+
+  // ── Subscribe / Unsubscribe ─────────────────────────────────────────────
+
+  /**
+   * Subscribe a socket to a channel.
+   * Returns true if subscribed, false if auth denied.
+   */
+  async subscribe(ws: RealtimeSocket, channel: string): Promise<boolean> {
+    const { type, baseName } = parseChannelName(channel)
+    const userId = ws.data.userId
+
+    // Private and presence channels require authorization
+    if (type !== 'public') {
+      if (userId === undefined) {
+        ws.send(serialize({ event: 'error', message: 'Authentication required', channel }))
+        return false
+      }
+
+      const authorizer = this.findAuthorizer(baseName)
+      if (!authorizer) {
+        ws.send(serialize({ event: 'error', message: 'No authorization handler for this channel', channel }))
+        return false
+      }
+
+      const result = await authorizer(userId, channel, ws.data.metadata)
+
+      if (result === false) {
+        ws.send(serialize({ event: 'error', message: 'Unauthorized', channel }))
+        return false
+      }
+
+      // Presence channels: result can be member info object
+      if (type === 'presence') {
+        const memberInfo = typeof result === 'object' ? result : {}
+        this.addPresenceMember(channel, userId, memberInfo, ws)
+      }
+    }
+
+    // Add to subscription set
+    if (!this.subscriptions.has(channel)) {
+      this.subscriptions.set(channel, new Set())
+    }
+    this.subscriptions.get(channel)!.add(ws)
+
+    // Track in the socket's context
+    ws.data.channels.add(channel)
+
+    // Subscribe to Bun's pub/sub topic for this channel
+    ws.subscribe(channel)
+
+    // Confirm subscription
+    ws.send(serialize({ event: 'subscribed', channel }))
+
+    // For presence: send current members list
+    if (type === 'presence') {
+      const members = this.getPresenceMembers(channel)
+      ws.send(serialize({
+        event: 'member:here',
+        channel,
+        data: members.map((m) => ({ userId: m.userId, info: m.info })),
+      }))
+    }
+
+    return true
+  }
+
+  /**
+   * Unsubscribe a socket from a channel.
+   */
+  unsubscribe(ws: RealtimeSocket, channel: string): void {
+    const subs = this.subscriptions.get(channel)
+    if (subs) {
+      subs.delete(ws)
+      if (subs.size === 0) {
+        this.subscriptions.delete(channel)
+      }
+    }
+
+    ws.data.channels.delete(channel)
+    ws.unsubscribe(channel)
+
+    // Handle presence leave
+    const { type } = parseChannelName(channel)
+    if (type === 'presence' && ws.data.userId !== undefined) {
+      this.removePresenceMember(channel, ws.data.userId, ws)
+    }
+
+    ws.send(serialize({ event: 'unsubscribed', channel }))
+  }
+
+  /**
+   * Remove a socket from all channels (called on disconnect).
+   */
+  removeFromAll(ws: RealtimeSocket): void {
+    for (const channel of [...ws.data.channels]) {
+      const subs = this.subscriptions.get(channel)
+      if (subs) {
+        subs.delete(ws)
+        if (subs.size === 0) {
+          this.subscriptions.delete(channel)
+        }
+      }
+
+      // Handle presence leave
+      const { type } = parseChannelName(channel)
+      if (type === 'presence' && ws.data.userId !== undefined) {
+        this.removePresenceMember(channel, ws.data.userId, ws)
+      }
+    }
+    ws.data.channels.clear()
+  }
+
+  // ── Whisper (client-to-client) ──────────────────────────────────────────
+
+  /**
+   * Forward a whisper to all subscribers of a channel except the sender.
+   * Only allowed on private and presence channels.
+   */
+  whisper(ws: RealtimeSocket, channel: string, type: string, data: Record<string, any>): void {
+    const { type: channelType } = parseChannelName(channel)
+    if (channelType === 'public') {
+      ws.send(serialize({ event: 'error', message: 'Whisper not allowed on public channels', channel }))
+      return
+    }
+
+    if (!ws.data.channels.has(channel)) {
+      ws.send(serialize({ event: 'error', message: 'Not subscribed to channel', channel }))
+      return
+    }
+
+    // Publish to all subscribers via Bun pub/sub (sender excluded automatically by Bun)
+    ws.publish(channel, JSON.stringify({
+      event: `client:${type}`,
+      channel,
+      data,
+    }))
+  }
+
+  // ── Broadcast (server → clients) ───────────────────────────────────────
+
+  /**
+   * Broadcast an event to all subscribers of a channel.
+   * Called by the BunBroadcaster when a ShouldBroadcast event is dispatched.
+   */
+  broadcast(channel: string, event: string, data: Record<string, any>): void {
+    const subs = this.subscriptions.get(channel)
+    if (!subs || subs.size === 0) return
+
+    const message = serialize({ event, channel, data })
+    for (const ws of subs) {
+      try {
+        ws.send(message)
+      } catch {
+        // Connection may have closed
+      }
+    }
+  }
+
+  // ── Presence ────────────────────────────────────────────────────────────
+
+  private addPresenceMember(
+    channel: string,
+    userId: string | number,
+    info: Record<string, any>,
+    ws: RealtimeSocket,
+  ): void {
+    if (!this.presenceMembers.has(channel)) {
+      this.presenceMembers.set(channel, new Map())
+    }
+
+    const members = this.presenceMembers.get(channel)!
+    const isNew = !members.has(userId)
+
+    members.set(userId, {
+      userId,
+      info,
+      joinedAt: Date.now(),
+    })
+
+    // Notify other subscribers about the new member
+    if (isNew) {
+      const subs = this.subscriptions.get(channel)
+      if (subs) {
+        const msg = serialize({ event: 'member:joined', channel, data: { userId, info } })
+        for (const sub of subs) {
+          if (sub !== ws) {
+            try { sub.send(msg) } catch { /* ignore */ }
+          }
+        }
+      }
+    }
+  }
+
+  private removePresenceMember(
+    channel: string,
+    userId: string | number,
+    _ws: RealtimeSocket,
+  ): void {
+    const members = this.presenceMembers.get(channel)
+    if (!members) return
+
+    // Only remove if the user has no other connections to this channel
+    const subs = this.subscriptions.get(channel)
+    if (subs) {
+      for (const sub of subs) {
+        if (sub.data.userId === userId) return // user still has another connection
+      }
+    }
+
+    members.delete(userId)
+    if (members.size === 0) {
+      this.presenceMembers.delete(channel)
+    }
+
+    // Notify remaining subscribers
+    if (subs) {
+      const msg = serialize({ event: 'member:left', channel, data: { userId } })
+      for (const sub of subs) {
+        try { sub.send(msg) } catch { /* ignore */ }
+      }
+    }
+  }
+
+  getPresenceMembers(channel: string): PresenceMember[] {
+    const members = this.presenceMembers.get(channel)
+    return members ? [...members.values()] : []
+  }
+
+  // ── Query ───────────────────────────────────────────────────────────────
+
+  getSubscribers(channel: string): RealtimeSocket[] {
+    return [...(this.subscriptions.get(channel) ?? [])]
+  }
+
+  getChannels(): string[] {
+    return [...this.subscriptions.keys()]
+  }
+
+  subscriberCount(channel: string): number {
+    return this.subscriptions.get(channel)?.size ?? 0
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  /**
+   * Find an authorizer that matches a channel base name.
+   * Supports glob-style `*` wildcards.
+   */
+  private findAuthorizer(baseName: string): ChannelAuthorizer | null {
+    // Exact match first
+    if (this.authorizers.has(baseName)) {
+      return this.authorizers.get(baseName)!
+    }
+
+    // Wildcard match
+    for (const [pattern, callback] of this.authorizers) {
+      if (this.matchPattern(pattern, baseName)) {
+        return callback
+      }
+    }
+
+    return null
+  }
+
+  private matchPattern(pattern: string, name: string): boolean {
+    // Convert glob pattern to regex: "orders.*" → /^orders\.(.+)$/
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '(.+)')
+    return new RegExp(`^${escaped}$`).test(name)
+  }
+}

package/src/contracts/Channel.ts

@@ -0,0 +1,40 @@
+/**
+ * Channel type classification based on name prefix.
+ *
+ * - `public`   — no auth, anyone can subscribe (e.g. "chat.1")
+ * - `private`  — auth required, server validates (e.g. "private:orders.5")
+ * - `presence` — auth + member tracking (e.g. "presence:room.3")
+ */
+export type ChannelType = 'public' | 'private' | 'presence'
+
+/**
+ * Authorization callback for private/presence channels.
+ * Returns `true` to allow, `false` to deny, or an object for presence member info.
+ */
+export type ChannelAuthorizer = (
+  userId: string | number,
+  channelName: string,
+  metadata?: Record<string, any>,
+) => boolean | Record<string, any> | Promise<boolean | Record<string, any>>
+
+/**
+ * Presence member info stored per connection.
+ */
+export interface PresenceMember {
+  userId: string | number
+  info: Record<string, any>
+  joinedAt: number
+}
+
+/**
+ * Parse a channel name into its type and base name.
+ */
+export function parseChannelName(name: string): { type: ChannelType; baseName: string } {
+  if (name.startsWith('presence:')) {
+    return { type: 'presence', baseName: name.slice(9) }
+  }
+  if (name.startsWith('private:')) {
+    return { type: 'private', baseName: name.slice(8) }
+  }
+  return { type: 'public', baseName: name }
+}

package/src/contracts/RealtimeConfig.ts

@@ -0,0 +1,72 @@
+/**
+ * Configuration for @mantiq/realtime.
+ */
+export interface RealtimeConfig {
+  /** Enable/disable the realtime server. */
+  enabled: boolean
+
+  /** Broadcast driver: 'bun' (in-process) | 'redis' (multi-server) | 'log' | 'null'. */
+  driver: string
+
+  /** WebSocket server settings. */
+  websocket: {
+    /** Path for WebSocket connections. Clients connect to ws://host:port/<path>. */
+    path: string
+    /** Max connections per user (0 = unlimited). */
+    maxConnectionsPerUser: number
+    /** Max total connections (0 = unlimited). */
+    maxConnections: number
+    /** Heartbeat interval in ms. Server pings, client must pong. */
+    heartbeatInterval: number
+    /** Close connection if no pong after this many ms. */
+    heartbeatTimeout: number
+  }
+
+  /** SSE fallback settings. */
+  sse: {
+    enabled: boolean
+    /** Path for SSE connections. */
+    path: string
+    /** Keep-alive interval in ms. */
+    keepAliveInterval: number
+  }
+
+  /** Presence channel settings. */
+  presence: {
+    /** How long to keep a member listed after disconnect (ms). */
+    memberTtl: number
+  }
+
+  /** Redis driver settings (only used when driver is 'redis'). */
+  redis: {
+    host: string
+    port: number
+    password?: string
+    prefix: string
+  }
+}
+
+export const DEFAULT_CONFIG: RealtimeConfig = {
+  enabled: true,
+  driver: 'bun',
+  websocket: {
+    path: '/ws',
+    maxConnectionsPerUser: 10,
+    maxConnections: 0,
+    heartbeatInterval: 25_000,
+    heartbeatTimeout: 10_000,
+  },
+  sse: {
+    enabled: true,
+    path: '/_sse',
+    keepAliveInterval: 15_000,
+  },
+  presence: {
+    memberTtl: 30_000,
+  },
+  redis: {
+    host: '127.0.0.1',
+    port: 6379,
+    prefix: 'mantiq_realtime:',
+  },
+}

package/src/errors/RealtimeError.ts

@@ -0,0 +1,6 @@
+export class RealtimeError extends Error {
+  constructor(message: string, public readonly context?: Record<string, any>) {
+    super(message)
+    this.name = 'RealtimeError'
+  }
+}

package/src/helpers/realtime.ts

@@ -0,0 +1,42 @@
+import type { WebSocketServer } from '../server/WebSocketServer.ts'
+
+/**
+ * Symbol for container binding.
+ */
+export const REALTIME = Symbol('Realtime')
+
+/**
+ * Internal reference set by RealtimeServiceProvider.boot().
+ */
+let _instance: WebSocketServer | null = null
+
+/**
+ * Set the singleton instance (called by the service provider).
+ */
+export function setRealtimeInstance(instance: WebSocketServer): void {
+  _instance = instance
+}
+
+/**
+ * Get the WebSocketServer instance.
+ *
+ * ```typescript
+ * import { realtime } from '@mantiq/realtime'
+ *
+ * // Register channel authorization
+ * realtime().channels.authorize('orders.*', async (userId, channel) => {
+ *   return userId === getOrderOwner(channel)
+ * })
+ *
+ * // Broadcast from server code
+ * realtime().channels.broadcast('public:news', 'breaking', { title: '...' })
+ * ```
+ */
+export function realtime(): WebSocketServer {
+  if (!_instance) {
+    throw new Error(
+      'Realtime not initialized. Register RealtimeServiceProvider in your application.',
+    )
+  }
+  return _instance
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// @mantiq/realtime — public API exports
+
+// ── Service Provider ────────────────────────────────────────────────────────
+export { RealtimeServiceProvider } from './RealtimeServiceProvider.ts'
+
+// ── Server ──────────────────────────────────────────────────────────────────
+export { WebSocketServer } from './server/WebSocketServer.ts'
+export { ConnectionManager } from './server/ConnectionManager.ts'
+export type { RealtimeSocket } from './server/ConnectionManager.ts'
+
+// ── Channels ────────────────────────────────────────────────────────────────
+export { ChannelManager } from './channels/ChannelManager.ts'
+
+// ── Broadcast ───────────────────────────────────────────────────────────────
+export { BunBroadcaster } from './broadcast/BunBroadcaster.ts'
+
+// ── SSE ─────────────────────────────────────────────────────────────────────
+export { SSEManager } from './sse/SSEManager.ts'
+export type { SSEConnection } from './sse/SSEManager.ts'
+
+// ── Protocol ────────────────────────────────────────────────────────────────
+export { parseClientMessage, serialize } from './protocol/Protocol.ts'
+export type {
+  ClientMessage,
+  ServerMessage,
+  SubscribeMessage,
+  UnsubscribeMessage,
+  WhisperMessage,
+  BroadcastMessage,
+  MemberJoinedMessage,
+  MemberLeftMessage,
+  MemberHereMessage,
+} from './protocol/Protocol.ts'
+
+// ── Contracts ───────────────────────────────────────────────────────────────
+export type { RealtimeConfig } from './contracts/RealtimeConfig.ts'
+export { DEFAULT_CONFIG } from './contracts/RealtimeConfig.ts'
+export { parseChannelName } from './contracts/Channel.ts'
+export type { ChannelType, ChannelAuthorizer, PresenceMember } from './contracts/Channel.ts'
+
+// ── Errors ──────────────────────────────────────────────────────────────────
+export { RealtimeError } from './errors/RealtimeError.ts'
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+export { realtime, REALTIME } from './helpers/realtime.ts'
+
+// ── Testing ─────────────────────────────────────────────────────────────────
+export { RealtimeFake } from './testing/RealtimeFake.ts'