@prsm/realtime 1.0.0

package/src/server/managers/pubsub.js

@@ -0,0 +1,242 @@
+import { serverLogger } from "../../shared/index.js"
+import { PUB_SUB_CHANNEL_PREFIX, RECORD_PUB_SUB_CHANNEL } from "../utils/constants.js"
+
+export class PubSubManager {
+  constructor({ subClient, pubClient, instanceId, connectionManager, recordManager, recordSubscriptions, getChannelSubscriptions, emitError, collectionManager }) {
+    this.subClient = subClient
+    this.pubClient = pubClient
+    this.instanceId = instanceId
+    this.connectionManager = connectionManager
+    this.recordManager = recordManager
+    this.recordSubscriptions = recordSubscriptions
+    this.getChannelSubscriptions = getChannelSubscriptions
+    this.emitError = emitError
+    this.collectionManager = collectionManager || null
+
+    this.collectionUpdateTimeouts = new Map()
+    this.collectionMaxDelayTimeouts = new Map()
+    this.pendingCollectionUpdates = new Map()
+    this.COLLECTION_UPDATE_DEBOUNCE_MS = 50
+    this.COLLECTION_MAX_DELAY_MS = 200
+  }
+
+  subscribeToInstanceChannel() {
+    const channel = `${PUB_SUB_CHANNEL_PREFIX}${this.instanceId}`
+    this._subscriptionPromise = new Promise((resolve, reject) => {
+      this.subClient.subscribe(channel, RECORD_PUB_SUB_CHANNEL, "mesh:collection:record-change")
+      this.subClient.psubscribe("mesh:presence:updates:*", (err) => {
+        if (err) {
+          this.emitError(new Error(`Failed to subscribe to channels/patterns: ${JSON.stringify({ cause: err })}`))
+          reject(err)
+          return
+        }
+        resolve()
+      })
+    })
+    this._setupMessageHandlers()
+    return this._subscriptionPromise
+  }
+
+  _setupMessageHandlers() {
+    this.subClient.on("message", async (channel, message) => {
+      if (channel.startsWith(PUB_SUB_CHANNEL_PREFIX)) {
+        this._handleInstancePubSubMessage(channel, message)
+      } else if (channel === RECORD_PUB_SUB_CHANNEL) {
+        this._handleRecordUpdatePubSubMessage(message)
+      } else if (channel === "mesh:collection:record-change") {
+        this._handleCollectionRecordChange(message)
+      } else {
+        const subscribers = this.getChannelSubscriptions(channel)
+        if (subscribers) {
+          for (const connection of subscribers) {
+            if (!connection.isDead) {
+              connection.send({ command: "mesh/subscription-message", payload: { channel, message } })
+            }
+          }
+        }
+      }
+    })
+
+    this.subClient.on("pmessage", async (pattern, channel, message) => {
+      if (pattern === "mesh:presence:updates:*") {
+        const subscribers = this.getChannelSubscriptions(channel)
+        if (subscribers) {
+          try {
+            const payload = JSON.parse(message)
+            subscribers.forEach((connection) => {
+              if (!connection.isDead) {
+                connection.send({ command: "mesh/presence-update", payload })
+              } else {
+                subscribers.delete(connection)
+              }
+            })
+          } catch (e) {
+            this.emitError(new Error(`Failed to parse presence update: ${message}`))
+          }
+        }
+      }
+    })
+  }
+
+  _handleInstancePubSubMessage(_channel, message) {
+    try {
+      const parsedMessage = JSON.parse(message)
+      if (!parsedMessage || !Array.isArray(parsedMessage.targetConnectionIds) || !parsedMessage.command || typeof parsedMessage.command.command !== "string") {
+        throw new Error("Invalid message format")
+      }
+      const { targetConnectionIds, command } = parsedMessage
+      targetConnectionIds.forEach((connectionId) => {
+        const connection = this.connectionManager.getLocalConnection(connectionId)
+        if (connection && !connection.isDead) connection.send(command)
+      })
+    } catch (err) {
+      this.emitError(new Error(`Failed to parse message: ${message}`))
+    }
+  }
+
+  _handleRecordUpdatePubSubMessage(message) {
+    try {
+      const parsedMessage = JSON.parse(message)
+      const { recordId, newValue, patch, version, deleted } = parsedMessage
+      if (!recordId || typeof version !== "number") throw new Error("Invalid record update message format")
+      const subscribers = this.recordSubscriptions.get(recordId)
+      if (!subscribers) return
+      subscribers.forEach((mode, connectionId) => {
+        const connection = this.connectionManager.getLocalConnection(connectionId)
+        if (connection && !connection.isDead) {
+          if (deleted) {
+            connection.send({ command: "mesh/record-deleted", payload: { recordId, version } })
+          } else if (mode === "patch" && patch) {
+            connection.send({ command: "mesh/record-update", payload: { recordId, patch, version } })
+          } else if (mode === "full" && newValue !== undefined) {
+            connection.send({ command: "mesh/record-update", payload: { recordId, full: newValue, version } })
+          }
+        } else if (!connection || connection.isDead) {
+          subscribers.delete(connectionId)
+          if (subscribers.size === 0) this.recordSubscriptions.delete(recordId)
+        }
+      })
+      if (deleted) this.recordSubscriptions.delete(recordId)
+    } catch (err) {
+      this.emitError(new Error(`Failed to parse record update message: ${message}`))
+    }
+  }
+
+  async _handleCollectionRecordChange(changedRecordId) {
+    if (!this.collectionManager) return
+    const collectionSubsMap = this.collectionManager.getCollectionSubscriptions()
+    const affectedCollections = new Set()
+    for (const [collectionId] of collectionSubsMap.entries()) {
+      affectedCollections.add(collectionId)
+    }
+    for (const collectionId of affectedCollections) {
+      const existingTimeout = this.collectionUpdateTimeouts.get(collectionId)
+      if (existingTimeout) clearTimeout(existingTimeout)
+      if (!this.pendingCollectionUpdates.has(collectionId)) {
+        this.pendingCollectionUpdates.set(collectionId, new Set())
+      }
+      this.pendingCollectionUpdates.get(collectionId).add(changedRecordId)
+      const debounceTimeout = setTimeout(async () => {
+        await this._processCollectionUpdates(collectionId)
+      }, this.COLLECTION_UPDATE_DEBOUNCE_MS)
+      this.collectionUpdateTimeouts.set(collectionId, debounceTimeout)
+      if (!this.collectionMaxDelayTimeouts.has(collectionId)) {
+        const maxDelayTimeout = setTimeout(async () => {
+          await this._processCollectionUpdates(collectionId)
+        }, this.COLLECTION_MAX_DELAY_MS)
+        this.collectionMaxDelayTimeouts.set(collectionId, maxDelayTimeout)
+      }
+    }
+  }
+
+  async _processCollectionUpdates(collectionId) {
+    const changedRecordIds = this.pendingCollectionUpdates.get(collectionId)
+    if (!changedRecordIds || changedRecordIds.size === 0) return
+    const debounceTimeout = this.collectionUpdateTimeouts.get(collectionId)
+    const maxDelayTimeout = this.collectionMaxDelayTimeouts.get(collectionId)
+    if (debounceTimeout) { clearTimeout(debounceTimeout); this.collectionUpdateTimeouts.delete(collectionId) }
+    if (maxDelayTimeout) { clearTimeout(maxDelayTimeout); this.collectionMaxDelayTimeouts.delete(collectionId) }
+    this.pendingCollectionUpdates.delete(collectionId)
+    if (!this.collectionManager) return
+    const subscribers = this.collectionManager.getCollectionSubscriptions().get(collectionId)
+    if (!subscribers || subscribers.size === 0) return
+
+    for (const [connectionId, { version: currentCollVersion }] of subscribers.entries()) {
+      try {
+        const connection = this.connectionManager.getLocalConnection(connectionId)
+        if (!connection || connection.isDead) continue
+
+        const newRecords = await this.collectionManager.resolveCollection(collectionId, connection)
+        const newRecordIds = newRecords.map((record) => record.id)
+        const previousRecordIdsKey = `mesh:collection:${collectionId}:${connectionId}`
+        const previousRecordIdsStr = await this.pubClient.get(previousRecordIdsKey)
+        const previousRecordIds = previousRecordIdsStr ? JSON.parse(previousRecordIdsStr) : []
+
+        const addedIds = newRecordIds.filter((id) => !previousRecordIds.includes(id))
+        const added = newRecords.filter((record) => addedIds.includes(record.id))
+        const removedIds = previousRecordIds.filter((id) => !newRecordIds.includes(id))
+
+        const removed = []
+        for (const removedId of removedIds) {
+          try {
+            const record = await this.recordManager.getRecord(removedId)
+            removed.push(record || { id: removedId })
+          } catch { removed.push({ id: removedId }) }
+        }
+
+        const deletedRecords = []
+        for (const recordId of changedRecordIds) {
+          if (previousRecordIds.includes(recordId) && !newRecordIds.includes(recordId)) {
+            deletedRecords.push(recordId)
+          }
+        }
+
+        const changeAffectsMembership = added.length > 0 || removed.length > 0
+        const deletionAffectsExistingMember = deletedRecords.length > 0
+
+        if (changeAffectsMembership || deletionAffectsExistingMember) {
+          const newCollectionVersion = currentCollVersion + 1
+          this.collectionManager.updateSubscriptionVersion(collectionId, connectionId, newCollectionVersion)
+          await this.pubClient.set(previousRecordIdsKey, JSON.stringify(newRecordIds))
+          connection.send({
+            command: "mesh/collection-diff",
+            payload: { collectionId, added, removed, version: newCollectionVersion },
+          })
+        }
+
+        for (const recordId of changedRecordIds) {
+          if (newRecordIds.includes(recordId)) {
+            try {
+              const { record, version } = await this.recordManager.getRecordAndVersion(recordId)
+              if (record) {
+                connection.send({ command: "mesh/record-update", payload: { recordId, version, full: record } })
+              }
+            } catch (recordError) {
+              serverLogger.info(`Record ${recordId} not found during collection update (likely deleted).`)
+            }
+          }
+        }
+      } catch (connError) {
+        this.emitError(new Error(`Error processing collection ${collectionId} for connection ${connectionId}: ${connError}`))
+      }
+    }
+  }
+
+  getSubscriptionPromise() { return this._subscriptionPromise }
+  getPubSubChannel(instanceId) { return `${PUB_SUB_CHANNEL_PREFIX}${instanceId}` }
+
+  async cleanup() {
+    for (const timeout of this.collectionUpdateTimeouts.values()) clearTimeout(timeout)
+    this.collectionUpdateTimeouts.clear()
+    for (const timeout of this.collectionMaxDelayTimeouts.values()) clearTimeout(timeout)
+    this.collectionMaxDelayTimeouts.clear()
+    this.pendingCollectionUpdates.clear()
+    if (this.subClient && this.subClient.status !== "end") {
+      const channel = `${PUB_SUB_CHANNEL_PREFIX}${this.instanceId}`
+      await Promise.all([
+        new Promise((resolve) => { this.subClient.unsubscribe(channel, RECORD_PUB_SUB_CHANNEL, "mesh:collection:record-change", () => resolve()) }),
+        new Promise((resolve) => { this.subClient.punsubscribe("mesh:presence:updates:*", () => resolve()) }),
+      ])
+    }
+  }
+}

package/src/server/managers/record-subscriptions.js

@@ -0,0 +1,123 @@
+import { RECORD_PUB_SUB_CHANNEL } from "../utils/constants.js"
+
+export class RecordSubscriptionManager {
+  constructor({ pubClient, recordManager, emitError, persistenceManager }) {
+    this.pubClient = pubClient
+    this.recordManager = recordManager
+    this.persistenceManager = persistenceManager || null
+    this.exposedRecords = []
+    this.exposedWritableRecords = []
+    this.recordGuards = new Map()
+    this.writableRecordGuards = new Map()
+    this.recordSubscriptions = new Map()
+    this.emitError = emitError
+  }
+
+  setPersistenceManager(persistenceManager) {
+    this.persistenceManager = persistenceManager
+  }
+
+  exposeRecord(recordPattern, guard) {
+    this.exposedRecords.push(recordPattern)
+    if (guard) this.recordGuards.set(recordPattern, guard)
+  }
+
+  exposeWritableRecord(recordPattern, guard) {
+    this.exposedWritableRecords.push(recordPattern)
+    if (guard) this.writableRecordGuards.set(recordPattern, guard)
+  }
+
+  async isRecordExposed(recordId, connection) {
+    const readPattern = this.exposedRecords.find((pattern) =>
+      typeof pattern === "string" ? pattern === recordId : pattern.test(recordId)
+    )
+    let canRead = false
+    if (readPattern) {
+      const guard = this.recordGuards.get(readPattern)
+      if (guard) {
+        try { canRead = await Promise.resolve(guard(connection, recordId)) }
+        catch { canRead = false }
+      } else {
+        canRead = true
+      }
+    }
+    if (canRead) return true
+    const writePattern = this.exposedWritableRecords.find((pattern) =>
+      typeof pattern === "string" ? pattern === recordId : pattern.test(recordId)
+    )
+    if (writePattern) return true
+    return false
+  }
+
+  async isRecordWritable(recordId, connection) {
+    const matchedPattern = this.exposedWritableRecords.find((pattern) =>
+      typeof pattern === "string" ? pattern === recordId : pattern.test(recordId)
+    )
+    if (!matchedPattern) return false
+    const guard = this.writableRecordGuards.get(matchedPattern)
+    if (guard) {
+      try { return await Promise.resolve(guard(connection, recordId)) }
+      catch { return false }
+    }
+    return true
+  }
+
+  addSubscription(recordId, connectionId, mode) {
+    if (!this.recordSubscriptions.has(recordId)) {
+      this.recordSubscriptions.set(recordId, new Map())
+    }
+    this.recordSubscriptions.get(recordId).set(connectionId, mode)
+  }
+
+  removeSubscription(recordId, connectionId) {
+    const recordSubs = this.recordSubscriptions.get(recordId)
+    if (recordSubs?.has(connectionId)) {
+      recordSubs.delete(connectionId)
+      if (recordSubs.size === 0) this.recordSubscriptions.delete(recordId)
+      return true
+    }
+    return false
+  }
+
+  getSubscribers(recordId) {
+    return this.recordSubscriptions.get(recordId)
+  }
+
+  async writeRecord(recordId, newValue, options) {
+    const updateResult = await this.recordManager.publishUpdate(recordId, newValue, options?.strategy || "replace")
+    if (!updateResult) return
+    const { patch, version, finalValue } = updateResult
+    if (this.persistenceManager) {
+      this.persistenceManager.handleRecordUpdate(recordId, finalValue, version)
+    }
+    const messagePayload = { recordId, newValue: finalValue, patch, version }
+    try {
+      await this.pubClient.publish(RECORD_PUB_SUB_CHANNEL, JSON.stringify(messagePayload))
+    } catch (err) {
+      this.emitError(new Error(`Failed to publish record update for "${recordId}": ${err}`))
+    }
+  }
+
+  cleanupConnection(connection) {
+    const connectionId = connection.id
+    this.recordSubscriptions.forEach((subscribers, recordId) => {
+      if (subscribers.has(connectionId)) {
+        subscribers.delete(connectionId)
+        if (subscribers.size === 0) this.recordSubscriptions.delete(recordId)
+      }
+    })
+  }
+
+  async publishRecordDeletion(recordId, version) {
+    const messagePayload = { recordId, deleted: true, version }
+    try {
+      await this.pubClient.publish(RECORD_PUB_SUB_CHANNEL, JSON.stringify(messagePayload))
+    } catch (err) {
+      this.emitError(new Error(`Failed to publish record deletion for "${recordId}": ${err}`))
+    }
+  }
+
+  getRecordSubscriptions() {
+    return this.recordSubscriptions
+  }
+}

package/src/server/managers/records.js

@@ -0,0 +1,110 @@
+import jsonpatch from "fast-json-patch"
+import { deepMerge, isObject, serverLogger } from "../../shared/index.js"
+import { RECORD_KEY_PREFIX, RECORD_VERSION_KEY_PREFIX } from "../utils/constants.js"
+
+export class RecordManager {
+  constructor({ redis, server }) {
+    this.redis = redis
+    this.server = server
+    this.recordUpdateCallbacks = []
+    this.recordRemovedCallbacks = []
+  }
+
+  getServer() { return this.server }
+  getRedis() { return this.redis }
+
+  recordKey(recordId) { return `${RECORD_KEY_PREFIX}${recordId}` }
+  recordVersionKey(recordId) { return `${RECORD_VERSION_KEY_PREFIX}${recordId}` }
+
+  async getRecord(recordId) {
+    const data = await this.redis.get(this.recordKey(recordId))
+    return data ? JSON.parse(data) : null
+  }
+
+  async getVersion(recordId) {
+    const version = await this.redis.get(this.recordVersionKey(recordId))
+    return version ? parseInt(version, 10) : 0
+  }
+
+  async getRecordAndVersion(recordId) {
+    const pipeline = this.redis.pipeline()
+    pipeline.get(this.recordKey(recordId))
+    pipeline.get(this.recordVersionKey(recordId))
+    const results = await pipeline.exec()
+    const recordData = results?.[0]?.[1]
+    const versionData = results?.[1]?.[1]
+    const record = recordData ? JSON.parse(recordData) : null
+    const version = versionData ? parseInt(versionData, 10) : 0
+    return { record, version }
+  }
+
+  async publishUpdate(recordId, newValue, strategy = "replace") {
+    const recordKey = this.recordKey(recordId)
+    const versionKey = this.recordVersionKey(recordId)
+    const { record: oldValue, version: oldVersion } = await this.getRecordAndVersion(recordId)
+
+    let finalValue
+    if (strategy === "merge") {
+      finalValue = isObject(oldValue) && isObject(newValue) ? { ...oldValue, ...newValue } : newValue
+    } else if (strategy === "deepMerge") {
+      finalValue = isObject(oldValue) && isObject(newValue) ? deepMerge(oldValue, newValue) : newValue
+    } else {
+      finalValue = newValue
+    }
+
+    const patch = jsonpatch.compare(oldValue ?? {}, finalValue ?? {})
+    if (patch.length === 0) return null
+
+    const newVersion = oldVersion + 1
+    const pipeline = this.redis.pipeline()
+    pipeline.set(recordKey, JSON.stringify(finalValue))
+    pipeline.set(versionKey, newVersion.toString())
+    await pipeline.exec()
+
+    if (this.recordUpdateCallbacks.length > 0) {
+      Promise.all(
+        this.recordUpdateCallbacks.map(async (callback) => {
+          try { await callback({ recordId, value: finalValue }) }
+          catch (error) { serverLogger.error(`Error in record update callback for ${recordId}:`, error) }
+        })
+      ).catch((error) => {
+        serverLogger.error(`Error in record update callbacks for ${recordId}:`, error)
+      })
+    }
+
+    return { patch, version: newVersion, finalValue }
+  }
+
+  async deleteRecord(recordId) {
+    const { record, version } = await this.getRecordAndVersion(recordId)
+    if (!record) return null
+
+    const pipeline = this.redis.pipeline()
+    pipeline.del(this.recordKey(recordId))
+    pipeline.del(this.recordVersionKey(recordId))
+    await pipeline.exec()
+
+    if (this.recordRemovedCallbacks.length > 0) {
+      Promise.all(
+        this.recordRemovedCallbacks.map(async (callback) => {
+          try { await callback({ recordId, value: record }) }
+          catch (error) { serverLogger.error(`Error in record removed callback for ${recordId}:`, error) }
+        })
+      ).catch((error) => {
+        serverLogger.error(`Error in record removed callbacks for ${recordId}:`, error)
+      })
+    }
+
+    return { version }
+  }
+
+  onRecordUpdate(callback) {
+    this.recordUpdateCallbacks.push(callback)
+    return () => { this.recordUpdateCallbacks = this.recordUpdateCallbacks.filter((cb) => cb !== callback) }
+  }
+
+  onRecordRemoved(callback) {
+    this.recordRemovedCallbacks.push(callback)
+    return () => { this.recordRemovedCallbacks = this.recordRemovedCallbacks.filter((cb) => cb !== callback) }
+  }
+}

package/src/server/managers/redis.js

@@ -0,0 +1,61 @@
+import { Redis } from "ioredis"
+
+export class RedisManager {
+  _redis = null
+  _pubClient = null
+  _subClient = null
+  _isShuttingDown = false
+
+  initialize(options, onError) {
+    this._onRedisConnect = null
+    this._onRedisDisconnect = null
+
+    this._redis = new Redis({
+      retryStrategy: (times) => {
+        if (this._isShuttingDown) return null
+        if (times > 10) return null
+        return Math.min(1000 * Math.pow(2, times), 30000)
+      },
+      ...options,
+    })
+    this._redis.on("error", (err) => onError(new Error(`Redis error: ${err}`)))
+    this._redis.on("connect", () => { if (this._onRedisConnect) this._onRedisConnect() })
+    this._redis.on("close", () => { if (!this._isShuttingDown && this._onRedisDisconnect) this._onRedisDisconnect() })
+    this._pubClient = this._redis.duplicate()
+    this._subClient = this._redis.duplicate()
+  }
+
+  get redis() {
+    if (!this._redis) throw new Error("Redis not initialized")
+    return this._redis
+  }
+
+  get pubClient() {
+    if (!this._pubClient) throw new Error("Redis pub client not initialized")
+    return this._pubClient
+  }
+
+  get subClient() {
+    if (!this._subClient) throw new Error("Redis sub client not initialized")
+    return this._subClient
+  }
+
+  disconnect() {
+    this._isShuttingDown = true
+    if (this._pubClient) { this._pubClient.disconnect(); this._pubClient = null }
+    if (this._subClient) { this._subClient.disconnect(); this._subClient = null }
+    if (this._redis) { this._redis.disconnect(); this._redis = null }
+  }
+
+  get isShuttingDown() { return this._isShuttingDown }
+  set isShuttingDown(value) { this._isShuttingDown = value }
+
+  async enableKeyspaceNotifications() {
+    const result = await this.redis.config("GET", "notify-keyspace-events")
+    const currentConfig = Array.isArray(result) && result.length > 1 ? result[1] : ""
+    let newConfig = currentConfig || ""
+    if (!newConfig.includes("E")) newConfig += "E"
+    if (!newConfig.includes("x")) newConfig += "x"
+    await this.redis.config("SET", "notify-keyspace-events", newConfig)
+  }
+}

package/src/server/managers/rooms.js

@@ -0,0 +1,129 @@
+import { deepMerge, isObject, serverLogger } from "../../shared/index.js"
+
+export class RoomManager {
+  constructor({ redis }) {
+    this.redis = redis
+  }
+
+  roomKey(roomName) { return `mesh:room:${roomName}` }
+  connectionsRoomKey(connectionId) { return `mesh:connection:${connectionId}:rooms` }
+  roomMetadataKey(roomName) { return `mesh:roommeta:${roomName}` }
+
+  async getRoomConnectionIds(roomName) {
+    return this.redis.smembers(this.roomKey(roomName))
+  }
+
+  async connectionIsInRoom(roomName, connection) {
+    const connectionId = typeof connection === "string" ? connection : connection.id
+    return !!(await this.redis.sismember(this.roomKey(roomName), connectionId))
+  }
+
+  async addToRoom(roomName, connection) {
+    const connectionId = typeof connection === "string" ? connection : connection.id
+    await this.redis.sadd(this.roomKey(roomName), connectionId)
+    await this.redis.sadd(this.connectionsRoomKey(connectionId), roomName)
+  }
+
+  async getRoomsForConnection(connection) {
+    const connectionId = typeof connection === "string" ? connection : connection.id
+    return await this.redis.smembers(this.connectionsRoomKey(connectionId))
+  }
+
+  async getAllRooms() {
+    const keys = await this.redis.keys("mesh:room:*")
+    return keys.map((key) => key.replace("mesh:room:", ""))
+  }
+
+  async removeFromRoom(roomName, connection) {
+    const connectionId = typeof connection === "string" ? connection : connection.id
+    const pipeline = this.redis.pipeline()
+    pipeline.srem(this.roomKey(roomName), connectionId)
+    pipeline.srem(this.connectionsRoomKey(connectionId), roomName)
+    await pipeline.exec()
+  }
+
+  async removeFromAllRooms(connection) {
+    const connectionId = typeof connection === "string" ? connection : connection.id
+    const rooms = await this.redis.smembers(this.connectionsRoomKey(connectionId))
+    const pipeline = this.redis.pipeline()
+    for (const room of rooms) {
+      pipeline.srem(this.roomKey(room), connectionId)
+    }
+    pipeline.del(this.connectionsRoomKey(connectionId))
+    await pipeline.exec()
+  }
+
+  async clearRoom(roomName) {
+    const connectionIds = await this.getRoomConnectionIds(roomName)
+    const pipeline = this.redis.pipeline()
+    for (const connectionId of connectionIds) {
+      pipeline.srem(this.connectionsRoomKey(connectionId), roomName)
+    }
+    pipeline.del(this.roomKey(roomName))
+    await pipeline.exec()
+  }
+
+  async deleteRoom(roomName) {
+    const connectionIds = await this.getRoomConnectionIds(roomName)
+    const pipeline = this.redis.pipeline()
+    for (const connectionId of connectionIds) {
+      pipeline.srem(this.connectionsRoomKey(connectionId), roomName)
+    }
+    pipeline.del(this.roomKey(roomName))
+    pipeline.del(this.roomMetadataKey(roomName))
+    await pipeline.exec()
+  }
+
+  async cleanupConnection(connection) {
+    const rooms = await this.redis.smembers(this.connectionsRoomKey(connection.id))
+    const pipeline = this.redis.pipeline()
+    for (const room of rooms) {
+      pipeline.srem(this.roomKey(room), connection.id)
+    }
+    pipeline.del(this.connectionsRoomKey(connection.id))
+    await pipeline.exec()
+  }
+
+  async setMetadata(roomName, metadata, options) {
+    let finalMetadata
+    const strategy = options?.strategy || "replace"
+    if (strategy === "replace") {
+      finalMetadata = metadata
+    } else {
+      const existingMetadata = await this.getMetadata(roomName)
+      if (strategy === "merge") {
+        finalMetadata = isObject(existingMetadata) && isObject(metadata)
+          ? { ...existingMetadata, ...metadata }
+          : metadata
+      } else if (strategy === "deepMerge") {
+        finalMetadata = isObject(existingMetadata) && isObject(metadata)
+          ? deepMerge(existingMetadata, metadata)
+          : metadata
+      }
+    }
+    await this.redis.hset(this.roomMetadataKey(roomName), "data", JSON.stringify(finalMetadata))
+  }
+
+  async getMetadata(roomName) {
+    const data = await this.redis.hget(this.roomMetadataKey(roomName), "data")
+    return data ? JSON.parse(data) : null
+  }
+
+  async getAllMetadata() {
+    const keys = await this.redis.keys("mesh:roommeta:*")
+    const result = []
+    if (keys.length === 0) return result
+    const pipeline = this.redis.pipeline()
+    keys.forEach((key) => pipeline.hget(key, "data"))
+    const results = await pipeline.exec()
+    keys.forEach((key, index) => {
+      const roomName = key.replace("mesh:roommeta:", "")
+      const data = results?.[index]?.[1]
+      if (data) {
+        try { result.push({ id: roomName, metadata: JSON.parse(data) }) }
+        catch (e) { serverLogger.error(`Failed to parse metadata for room ${roomName}:`, e) }
+      }
+    })
+    return result
+  }
+}

package/src/server/message-stream.js

@@ -0,0 +1,20 @@
+import { EventEmitter } from "node:events"
+
+export class MessageStream extends EventEmitter {
+  constructor() {
+    super()
+    this.setMaxListeners(100)
+  }
+
+  publishMessage(channel, message, instanceId) {
+    this.emit("message", { channel, message, instanceId, timestamp: Date.now() })
+  }
+
+  subscribeToMessages(callback) {
+    this.on("message", callback)
+  }
+
+  unsubscribeFromMessages(callback) {
+    this.off("message", callback)
+  }
+}