@prsm/realtime 1.0.0

package/src/server/managers/channels.js

@@ -0,0 +1,118 @@
+export class ChannelManager {
+  constructor({ redis, pubClient, subClient, messageStream }) {
+    this.redis = redis
+    this.pubClient = pubClient
+    this.subClient = subClient
+    this.messageStream = messageStream
+    this.exposedChannels = []
+    this.channelGuards = new Map()
+    this.channelSubscriptions = {}
+    this.persistenceManager = null
+  }
+
+  setPersistenceManager(manager) {
+    this.persistenceManager = manager
+  }
+
+  exposeChannel(channel, guard) {
+    this.exposedChannels.push(channel)
+    if (guard) this.channelGuards.set(channel, guard)
+  }
+
+  async isChannelExposed(channel, connection) {
+    const matchedPattern = this.exposedChannels.find((pattern) =>
+      typeof pattern === "string" ? pattern === channel : pattern.test(channel)
+    )
+    if (!matchedPattern) return false
+    const guard = this.channelGuards.get(matchedPattern)
+    if (guard) {
+      try { return await Promise.resolve(guard(connection, channel)) }
+      catch { return false }
+    }
+    return true
+  }
+
+  async writeChannel(channel, message, history = 0, instanceId) {
+    const serialized = typeof message === "string" ? message : JSON.stringify(message)
+    const parsedHistory = parseInt(history, 10)
+    if (!isNaN(parsedHistory) && parsedHistory > 0) {
+      await this.pubClient.rpush(`mesh:history:${channel}`, serialized)
+      await this.pubClient.ltrim(`mesh:history:${channel}`, -parsedHistory, -1)
+    }
+    this.messageStream.publishMessage(channel, serialized, instanceId)
+    await this.pubClient.publish(channel, serialized)
+  }
+
+  addSubscription(channel, connection) {
+    if (!this.channelSubscriptions[channel]) {
+      this.channelSubscriptions[channel] = new Set()
+    }
+    this.channelSubscriptions[channel].add(connection)
+  }
+
+  removeSubscription(channel, connection) {
+    if (this.channelSubscriptions[channel]) {
+      this.channelSubscriptions[channel].delete(connection)
+      if (this.channelSubscriptions[channel].size === 0) {
+        delete this.channelSubscriptions[channel]
+      }
+      return true
+    }
+    return false
+  }
+
+  getSubscribers(channel) {
+    return this.channelSubscriptions[channel]
+  }
+
+  async subscribeToRedisChannel(channel) {
+    return new Promise((resolve, reject) => {
+      this.subClient.subscribe(channel, (err) => {
+        if (err) reject(err)
+        else resolve()
+      })
+    })
+  }
+
+  async unsubscribeFromRedisChannel(channel) {
+    return new Promise((resolve, reject) => {
+      this.subClient.unsubscribe(channel, (err) => {
+        if (err) reject(err)
+        else resolve()
+      })
+    })
+  }
+
+  async getChannelHistory(channel, limit, since) {
+    if (this.persistenceManager && since !== undefined) {
+      try {
+        const messages = await this.persistenceManager.getMessages(channel, since, limit)
+        return messages.map((msg) => msg.message)
+      } catch {
+        const historyKey = `mesh:history:${channel}`
+        return this.redis.lrange(historyKey, 0, limit - 1)
+      }
+    }
+    const historyKey = `mesh:history:${channel}`
+    return this.redis.lrange(historyKey, 0, limit - 1)
+  }
+
+  async getPersistedMessages(channel, since, limit) {
+    if (!this.persistenceManager) throw new Error("Persistence not enabled")
+    return this.persistenceManager.getMessages(channel, since, limit)
+  }
+
+  cleanupConnection(connection) {
+    for (const channel in this.channelSubscriptions) {
+      this.removeSubscription(channel, connection)
+    }
+  }
+
+  async cleanupAllSubscriptions() {
+    const channels = Object.keys(this.channelSubscriptions)
+    for (const channel of channels) {
+      try { await this.unsubscribeFromRedisChannel(channel) } catch {}
+    }
+    this.channelSubscriptions = {}
+  }
+}

package/src/server/managers/collections.js

@@ -0,0 +1,127 @@
+export class CollectionManager {
+  constructor({ redis, emitError }) {
+    this.redis = redis
+    this.emitError = emitError
+    this.exposedCollections = []
+    this.collectionSubscriptions = new Map()
+  }
+
+  exposeCollection(pattern, resolver) {
+    this.exposedCollections.push({ pattern, resolver })
+  }
+
+  async isCollectionExposed(collectionId, _connection) {
+    const matchedPattern = this.exposedCollections.find((entry) =>
+      typeof entry.pattern === "string" ? entry.pattern === collectionId : entry.pattern.test(collectionId)
+    )
+    return !!matchedPattern
+  }
+
+  async resolveCollection(collectionId, connection) {
+    const matchedPattern = this.exposedCollections.find((entry) =>
+      typeof entry.pattern === "string" ? entry.pattern === collectionId : entry.pattern.test(collectionId)
+    )
+    if (!matchedPattern) throw new Error(`Collection "${collectionId}" is not exposed`)
+    try {
+      return await Promise.resolve(matchedPattern.resolver(connection, collectionId))
+    } catch (error) {
+      this.emitError(new Error(`Failed to resolve collection "${collectionId}": ${error}`))
+      throw error
+    }
+  }
+
+  async addSubscription(collectionId, connectionId, connection) {
+    if (!this.collectionSubscriptions.has(collectionId)) {
+      this.collectionSubscriptions.set(collectionId, new Map())
+    }
+    const records = await this.resolveCollection(collectionId, connection)
+    const ids = records.map((record) => record.id)
+    const version = 1
+    this.collectionSubscriptions.get(collectionId).set(connectionId, { version })
+    await this.redis.set(`mesh:collection:${collectionId}:${connectionId}`, JSON.stringify(ids))
+    return { ids, records, version }
+  }
+
+  async removeSubscription(collectionId, connectionId) {
+    const collectionSubs = this.collectionSubscriptions.get(collectionId)
+    if (collectionSubs?.has(connectionId)) {
+      collectionSubs.delete(connectionId)
+      if (collectionSubs.size === 0) this.collectionSubscriptions.delete(collectionId)
+      await this.redis.del(`mesh:collection:${collectionId}:${connectionId}`)
+      return true
+    }
+    return false
+  }
+
+  async publishRecordChange(recordId) {
+    try {
+      await this.redis.publish("mesh:collection:record-change", recordId)
+    } catch (error) {
+      this.emitError(new Error(`Failed to publish record change for ${recordId}: ${error}`))
+    }
+  }
+
+  async cleanupConnection(connection) {
+    const connectionId = connection.id
+    const cleanupPromises = []
+    this.collectionSubscriptions.forEach((subscribers, collectionId) => {
+      if (!subscribers.has(connectionId)) return
+      subscribers.delete(connectionId)
+      if (subscribers.size === 0) this.collectionSubscriptions.delete(collectionId)
+      cleanupPromises.push(
+        this.redis.del(`mesh:collection:${collectionId}:${connectionId}`).then(() => {}).catch((err) => {
+          this.emitError(new Error(`Failed to clean up collection subscription for "${collectionId}": ${err}`))
+        })
+      )
+    })
+    await Promise.all(cleanupPromises)
+  }
+
+  async listRecordsMatching(pattern, options) {
+    try {
+      const recordKeyPrefix = "mesh:record:"
+      const keys = []
+      let cursor = "0"
+      do {
+        const result = await this.redis.scan(cursor, "MATCH", `${recordKeyPrefix}${pattern}`, "COUNT", options?.scanCount ?? 100)
+        cursor = result[0]
+        keys.push(...result[1])
+      } while (cursor !== "0")
+      if (keys.length === 0) return []
+      const records = await this.redis.mget(keys)
+      const cleanRecordIds = keys.map((key) => key.substring(recordKeyPrefix.length))
+      let processedRecords = records
+        .map((val, index) => {
+          if (val === null) return null
+          try {
+            const parsed = JSON.parse(val)
+            const recordId = cleanRecordIds[index]
+            return parsed.id === recordId ? parsed : { ...parsed, id: recordId }
+          } catch (e) {
+            this.emitError(new Error(`Failed to parse record for processing: ${val} - ${e.message}`))
+            return null
+          }
+        })
+        .filter((record) => record !== null)
+      if (options?.map) processedRecords = processedRecords.map(options.map)
+      if (options?.sort) processedRecords.sort(options.sort)
+      if (options?.slice) {
+        const { start, count } = options.slice
+        processedRecords = processedRecords.slice(start, start + count)
+      }
+      return processedRecords
+    } catch (error) {
+      this.emitError(new Error(`Failed to list records matching "${pattern}": ${error.message}`))
+      return []
+    }
+  }
+
+  getCollectionSubscriptions() { return this.collectionSubscriptions }
+
+  updateSubscriptionVersion(collectionId, connectionId, version) {
+    const collectionSubs = this.collectionSubscriptions.get(collectionId)
+    if (collectionSubs?.has(connectionId)) {
+      collectionSubs.set(connectionId, { version })
+    }
+  }
+}

package/src/server/managers/commands.js

@@ -0,0 +1,55 @@
+import { Context } from "../context.js"
+import { CodeError } from "../../shared/index.js"
+
+export class CommandManager {
+  constructor() {
+    this.commands = {}
+    this.globalMiddlewares = []
+    this.middlewares = {}
+  }
+
+  exposeCommand(command, callback, middlewares = []) {
+    this.commands[command] = callback
+    if (middlewares.length > 0) {
+      this.useMiddlewareWithCommand(command, middlewares)
+    }
+  }
+
+  useMiddleware(...middlewares) {
+    this.globalMiddlewares.push(...middlewares)
+  }
+
+  useMiddlewareWithCommand(command, middlewares) {
+    if (middlewares.length) {
+      this.middlewares[command] = this.middlewares[command] || []
+      this.middlewares[command] = middlewares.concat(this.middlewares[command])
+    }
+  }
+
+  async runCommand(id, commandName, payload, connection, server) {
+    const context = new Context(server, commandName, connection, payload)
+    try {
+      if (!this.commands[commandName]) {
+        throw new CodeError(`Command "${commandName}" not found`, "ENOTFOUND", "CommandError")
+      }
+      for (const middleware of this.globalMiddlewares) {
+        await middleware(context)
+      }
+      if (this.middlewares[commandName]) {
+        for (const middleware of this.middlewares[commandName]) {
+          await middleware(context)
+        }
+      }
+      const result = await this.commands[commandName](context)
+      connection.send({ id, command: commandName, payload: result })
+    } catch (err) {
+      const errorPayload = err instanceof Error
+        ? { error: err.message, code: err.code || "ESERVER", name: err.name || "Error" }
+        : { error: String(err), code: "EUNKNOWN", name: "UnknownError" }
+      connection.send({ id, command: commandName, payload: errorPayload })
+    }
+  }
+
+  getCommands() { return this.commands }
+  hasCommand(commandName) { return !!this.commands[commandName] }
+}

package/src/server/managers/connections.js

@@ -0,0 +1,111 @@
+import { deepMerge, isObject } from "../../shared/index.js"
+
+const CONNECTIONS_HASH_KEY = "mesh:connections"
+const CONNECTIONS_META_HASH_KEY = "mesh:connection-meta"
+const INSTANCE_CONNECTIONS_KEY_PREFIX = "mesh:connections:"
+
+export class ConnectionManager {
+  constructor({ redis, instanceId, roomManager }) {
+    this.redis = redis
+    this.instanceId = instanceId
+    this.roomManager = roomManager
+    this.localConnections = {}
+  }
+
+  getLocalConnections() {
+    return Object.values(this.localConnections)
+  }
+
+  getLocalConnection(id) {
+    return this.localConnections[id] ?? null
+  }
+
+  async registerConnection(connection) {
+    this.localConnections[connection.id] = connection
+    const pipeline = this.redis.pipeline()
+    pipeline.hset(CONNECTIONS_HASH_KEY, connection.id, this.instanceId)
+    pipeline.sadd(`${INSTANCE_CONNECTIONS_KEY_PREFIX}${this.instanceId}`, connection.id)
+    await pipeline.exec()
+  }
+
+  async deregisterConnection(connection) {
+    const instanceId = await this.redis.hget(CONNECTIONS_HASH_KEY, connection.id)
+    if (!instanceId) return
+    const pipeline = this.redis.pipeline()
+    pipeline.hdel(CONNECTIONS_HASH_KEY, connection.id)
+    pipeline.srem(`${INSTANCE_CONNECTIONS_KEY_PREFIX}${instanceId}`, connection.id)
+    await pipeline.exec()
+  }
+
+  async getInstanceIdsForConnections(connectionIds) {
+    if (connectionIds.length === 0) return {}
+    const instanceIds = await this.redis.hmget(CONNECTIONS_HASH_KEY, ...connectionIds)
+    const result = {}
+    connectionIds.forEach((id, index) => { result[id] = instanceIds[index] ?? null })
+    return result
+  }
+
+  async getAllConnectionIds() {
+    return this.redis.hkeys(CONNECTIONS_HASH_KEY)
+  }
+
+  async getLocalConnectionIds() {
+    return this.redis.smembers(`${INSTANCE_CONNECTIONS_KEY_PREFIX}${this.instanceId}`)
+  }
+
+  async setMetadata(connection, metadata, options) {
+    let finalMetadata
+    const strategy = options?.strategy || "replace"
+    if (strategy === "replace") {
+      finalMetadata = metadata
+    } else {
+      const existingMetadata = await this.getMetadata(connection)
+      if (strategy === "merge") {
+        finalMetadata = isObject(existingMetadata) && isObject(metadata)
+          ? { ...existingMetadata, ...metadata }
+          : metadata
+      } else if (strategy === "deepMerge") {
+        finalMetadata = isObject(existingMetadata) && isObject(metadata)
+          ? deepMerge(existingMetadata, metadata)
+          : metadata
+      }
+    }
+    const id = typeof connection === "string" ? connection : connection.id
+    await this.redis.hset(CONNECTIONS_META_HASH_KEY, id, JSON.stringify(finalMetadata))
+  }
+
+  async getMetadata(connection) {
+    const id = typeof connection === "string" ? connection : connection.id
+    const metadata = await this.redis.hget(CONNECTIONS_META_HASH_KEY, id)
+    return metadata ? JSON.parse(metadata) : null
+  }
+
+  async getAllMetadata() {
+    const connectionIds = await this.getAllConnectionIds()
+    return this._getMetadataForConnectionIds(connectionIds)
+  }
+
+  async getAllMetadataForRoom(roomName) {
+    const connectionIds = await this.roomManager.getRoomConnectionIds(roomName)
+    return this._getMetadataForConnectionIds(connectionIds)
+  }
+
+  async _getMetadataForConnectionIds(connectionIds) {
+    if (connectionIds.length === 0) return []
+    const values = await this.redis.hmget(CONNECTIONS_META_HASH_KEY, ...connectionIds)
+    return connectionIds.map((id, index) => {
+      try {
+        const raw = values[index]
+        return { id, metadata: raw ? JSON.parse(raw) : null }
+      } catch {
+        return { id, metadata: null }
+      }
+    })
+  }
+
+  async cleanupConnection(connection) {
+    delete this.localConnections[connection.id]
+    await this.deregisterConnection(connection)
+    await this.redis.hdel(CONNECTIONS_META_HASH_KEY, connection.id)
+  }
+}

package/src/server/managers/instance.js

@@ -0,0 +1,125 @@
+import { serverLogger } from "../../shared/index.js"
+
+export class InstanceManager {
+  constructor({ redis, instanceId }) {
+    this.redis = redis
+    this.instanceId = instanceId
+    this.heartbeatInterval = null
+    this.heartbeatTTL = 120
+    this.heartbeatFrequency = 15000
+    this.cleanupInterval = null
+    this.cleanupFrequency = 60000
+    this.cleanupLockTTL = 10
+  }
+
+  async start() {
+    await this._registerInstance()
+    await this._updateHeartbeat()
+    this.heartbeatInterval = setInterval(() => this._updateHeartbeat(), this.heartbeatFrequency)
+    this.heartbeatInterval.unref()
+    this.cleanupInterval = setInterval(() => this._performCleanup(), this.cleanupFrequency)
+    this.cleanupInterval.unref()
+  }
+
+  async stop() {
+    if (this.heartbeatInterval) { clearInterval(this.heartbeatInterval); this.heartbeatInterval = null }
+    if (this.cleanupInterval) { clearInterval(this.cleanupInterval); this.cleanupInterval = null }
+    await this._deregisterInstance()
+  }
+
+  async _registerInstance() {
+    await this.redis.sadd("mesh:instances", this.instanceId)
+  }
+
+  async _deregisterInstance() {
+    await this.redis.srem("mesh:instances", this.instanceId)
+    await this.redis.del(`mesh:instance:${this.instanceId}:heartbeat`)
+  }
+
+  async _updateHeartbeat() {
+    await this.redis.set(`mesh:instance:${this.instanceId}:heartbeat`, Date.now().toString(), "EX", this.heartbeatTTL)
+  }
+
+  async _acquireCleanupLock() {
+    const result = await this.redis.set("mesh:cleanup:lock", this.instanceId, "EX", this.cleanupLockTTL, "NX")
+    return result === "OK"
+  }
+
+  async _releaseCleanupLock() {
+    const script = 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end'
+    await this.redis.eval(script, 1, "mesh:cleanup:lock", this.instanceId)
+  }
+
+  async _performCleanup() {
+    try {
+      const lockAcquired = await this._acquireCleanupLock()
+      if (!lockAcquired) return
+      const registeredInstances = await this.redis.smembers("mesh:instances")
+      const allConnections = await this.redis.hgetall("mesh:connections")
+      const instanceIds = new Set([...registeredInstances, ...Object.values(allConnections)])
+      for (const instanceId of instanceIds) {
+        if (instanceId === this.instanceId) continue
+        const heartbeat = await this.redis.get(`mesh:instance:${instanceId}:heartbeat`)
+        if (!heartbeat) {
+          serverLogger.info(`Found dead instance: ${instanceId}`)
+          await this._cleanupDeadInstance(instanceId)
+        }
+      }
+    } catch (error) {
+      serverLogger.error("Error during cleanup:", error)
+    } finally {
+      await this._releaseCleanupLock()
+    }
+  }
+
+  async _cleanupDeadInstance(instanceId) {
+    try {
+      const connectionsKey = `mesh:connections:${instanceId}`
+      const connections = await this.redis.smembers(connectionsKey)
+      for (const connectionId of connections) {
+        await this._cleanupConnection(connectionId)
+      }
+      const allConnections = await this.redis.hgetall("mesh:connections")
+      for (const [connectionId, connInstanceId] of Object.entries(allConnections)) {
+        if (connInstanceId === instanceId) await this._cleanupConnection(connectionId)
+      }
+      await this.redis.srem("mesh:instances", instanceId)
+      await this.redis.del(connectionsKey)
+      serverLogger.info(`Cleaned up dead instance: ${instanceId}`)
+    } catch (error) {
+      serverLogger.error(`Error cleaning up instance ${instanceId}:`, error)
+    }
+  }
+
+  async _deleteMatchingKeys(pattern) {
+    const stream = this.redis.scanStream({ match: pattern })
+    const pipeline = this.redis.pipeline()
+    stream.on("data", (keys) => { for (const key of keys) pipeline.del(key) })
+    return new Promise((resolve, reject) => {
+      stream.on("end", async () => { await pipeline.exec(); resolve() })
+      stream.on("error", reject)
+    })
+  }
+
+  async _cleanupConnection(connectionId) {
+    try {
+      const roomsKey = `mesh:connection:${connectionId}:rooms`
+      const rooms = await this.redis.smembers(roomsKey)
+      const pipeline = this.redis.pipeline()
+      for (const room of rooms) {
+        pipeline.srem(`mesh:room:${room}`, connectionId)
+        pipeline.srem(`mesh:presence:room:${room}`, connectionId)
+        pipeline.del(`mesh:presence:room:${room}:conn:${connectionId}`)
+        pipeline.del(`mesh:presence:state:${room}:conn:${connectionId}`)
+      }
+      pipeline.del(roomsKey)
+      pipeline.hdel("mesh:connections", connectionId)
+      pipeline.hdel("mesh:connection-meta", connectionId)
+      await this._deleteMatchingKeys(`mesh:collection:*:${connectionId}`)
+      await pipeline.exec()
+      serverLogger.debug(`Cleaned up stale connection: ${connectionId}`)
+    } catch (error) {
+      serverLogger.error(`Error cleaning up connection ${connectionId}:`, error)
+    }
+  }
+}