@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/socket/client/socket.ts

@@ -0,0 +1,203 @@
+import type { LoggerFriendly } from "#Project/src/log/logger.ts"
+import { Logger } from "#Project/src/log/logger.ts"
+import type { BuildEvents, SubscriberEntry } from "#Source/event/index.ts"
+import { EventManager } from "#Source/event/index.ts"
+
+import type { SocketUnitEvents, SocketUnitOptions, SocketUnitSnapshot, SocketUnitStatus } from "./socket-unit.ts"
+import { SocketUnit } from "./socket-unit.ts"
+
+/**
+ * 表示客户端 Socket 进入 ready 态时的事件负载。
+ */
+export interface SocketConnectedEvent {
+  clientId: string | undefined
+}
+
+/**
+ * 表示客户端 Socket 离开 ready 态时的事件负载。
+ */
+export interface SocketClosedEvent {
+  clientId: string | undefined
+}
+
+/**
+ * 表示客户端 Socket 派发业务消息时的事件负载。
+ */
+export interface SocketMessageEvent<Message> {
+  clientId: string
+  message: Message
+}
+
+/**
+ * 表示客户端 Socket 对外派发的事件表。
+ */
+export type SocketEvents<Message> = BuildEvents<{
+  connect: (payload: SocketConnectedEvent) => void
+  close: (payload: SocketClosedEvent) => void
+  message: (payload: SocketMessageEvent<Message>) => void
+}>
+
+/**
+ * 表示客户端 Socket 的公开状态类型。
+ */
+export type SocketStatus = SocketUnitStatus
+
+/**
+ * 表示客户端 Socket 的构造参数。
+ */
+export interface SocketOptions<Message> extends SocketUnitOptions<Message> {
+}
+/**
+ * 此 Socket 类并不直接创建和管理 WebSocket 实例，而是管理很多 SocketUnit，
+ * SocketUnit 是 WebSocket 实例的实际管理者。这样可以做到当 WebSocket 实例
+ * 出现连接不稳定或断线重连等情况时，Socket 的功能对使用者来说始终是稳定的。
+ */
+export class Socket<Message> implements LoggerFriendly {
+  protected readonly options: SocketUnitOptions<Message>
+
+  readonly logger: Logger
+
+  protected clientId: string | undefined
+  protected legacyUnitSet: Set<SocketUnit<Message>>
+  protected unit: SocketUnit<Message>
+
+  eventManager: EventManager<SocketEvents<Message>>
+  protected messageSubscriberEntry!: SubscriberEntry<SocketUnitEvents<Message>, 'message'>
+  protected statusSubscriberEntry!: SubscriberEntry<SocketUnitEvents<Message>, 'status'>
+  protected lastUnitReadyToWork: boolean
+
+  constructor(options: SocketUnitOptions<Message>) {
+    this.options = options
+
+    this.logger = Logger.fromOptions(options).setDefaultName("Socket")
+    this.clientId = undefined
+    this.legacyUnitSet = new Set()
+    this.unit = this.createUnit()
+    this.lastUnitReadyToWork = this.unit.getSnapshot().isReadyToWork
+
+    this.eventManager = new EventManager<SocketEvents<Message>>()
+    this.prepareEventManager()
+  }
+
+  protected createUnit(): SocketUnit<Message> {
+    return new SocketUnit<Message>({
+      ...this.options,
+      logger: Logger.derive(this.logger).setName("SocketUnit")
+    })
+  }
+
+  protected replaceCurrentUnit(unit: SocketUnit<Message>): void {
+    this.unit = unit
+    this.lastUnitReadyToWork = unit.getSnapshot().isReadyToWork
+    this.prepareEventManager()
+
+    if (this.clientId !== undefined) {
+      this.unit.setClientId(this.clientId)
+    }
+  }
+
+  protected prepareEventManager(): void {
+    if (this.messageSubscriberEntry !== undefined) {
+      this.messageSubscriberEntry.unsubscribe()
+    }
+    if (this.statusSubscriberEntry !== undefined) {
+      this.statusSubscriberEntry.unsubscribe()
+    }
+
+    this.messageSubscriberEntry = this.unit.eventManager.subscribe('message', (message) => {
+      const clientId = this.unit.getSnapshot().clientId
+      if (clientId === undefined) {
+        this.logger.warn('Message event skipped because clientId is not ready.')
+        return
+      }
+
+      this.eventManager.emit('message', { clientId, message })
+    })
+
+    this.statusSubscriberEntry = this.unit.eventManager.subscribe('status', (status) => {
+      this.handleUnitStatusChange(status)
+    })
+  }
+
+  protected handleUnitStatusChange(_status: SocketUnitStatus): void {
+    const previousReadyToWork = this.lastUnitReadyToWork
+    const snapshot = this.unit.getSnapshot()
+    const nextReadyToWork = snapshot.isReadyToWork
+
+    this.lastUnitReadyToWork = nextReadyToWork
+
+    if (previousReadyToWork === false && nextReadyToWork === true) {
+      this.eventManager.emit('connect', { clientId: snapshot.clientId })
+    }
+
+    if (
+      previousReadyToWork === true
+      && nextReadyToWork === false
+    ) {
+      this.eventManager.emit('close', { clientId: snapshot.clientId })
+    }
+  }
+
+  /**
+   * 设置当前 Socket 对外暴露的 clientId。
+   */
+  setClientId(clientId: string): void {
+    this.clientId = clientId
+    this.unit.setClientId(clientId)
+    this.handleUnitStatusChange(this.unit.getStatus())
+  }
+
+  /**
+   * 返回当前活跃 SocketUnit 的状态。
+   */
+  getStatus(): SocketStatus {
+    return this.unit.getStatus()
+  }
+
+  /**
+   * 返回当前活跃 SocketUnit 的快照。
+   */
+  getSnapshot(): SocketUnitSnapshot {
+    return this.unit.getSnapshot()
+  }
+
+  /**
+   * 打开当前活跃的 SocketUnit。
+   */
+  async open(): Promise<void> {
+    await this.unit.open()
+  }
+
+  /**
+   * 重建当前活跃的 SocketUnit 连接。
+   */
+  async reopen(): Promise<void> {
+    await this.unit.reopen()
+  }
+
+  /**
+   * 关闭当前活跃的 SocketUnit 连接。
+   */
+  async close(): Promise<void> {
+    await this.unit.close()
+  }
+
+  /**
+   * 异步回收当前 SocketUnit，并切换到新的运行单元。
+   */
+  reset(): void {
+    const legacyUnit = this.unit
+    this.legacyUnitSet.add(legacyUnit)
+    void legacyUnit.reset(() => {
+      this.legacyUnitSet.delete(legacyUnit)
+    })
+    this.replaceCurrentUnit(this.createUnit())
+  }
+
+  /**
+   * 向当前活跃的 SocketUnit 发送业务消息。
+   */
+  sendMessage(message: Message): void {
+    this.unit.sendMessage(message)
+  }
+}

package/src/socket/common/index.ts

@@ -0,0 +1,2 @@
+export type * from "./socket-unit-common.ts"
+export * from "./socket-unit-heartbeat.ts"

package/src/socket/common/socket-unit-common.ts

@@ -0,0 +1,23 @@
+/**
+ * 表示 SocketUnit 当前所处的生命周期阶段。
+ */
+export type SocketUnitLifecycleState = "IDLE" | "RUNNING" | "CLOSED"
+
+/**
+ * 表示当前传输对象由谁负责创建和销毁。
+ */
+export type SocketUnitTransportOwnership = "OWNED" | "INJECTED"
+
+/**
+ * 表示客户端与服务端 SocketUnit 共享的基础快照结构。
+ */
+export interface SocketUnitBaseSnapshot<ClientId, Status, HeartbeatSnapshot> {
+  status: Status
+  clientId: ClientId
+  lifecycleState: SocketUnitLifecycleState
+  isReadyToWork: boolean
+  hasTransport: boolean
+  pendingActionCount: number
+  transportOwnership: SocketUnitTransportOwnership
+  heartbeat: HeartbeatSnapshot
+}

package/src/socket/common/socket-unit-heartbeat.ts

@@ -0,0 +1,427 @@
+import type { LoggerFriendly, LoggerFriendlyOptions } from "#Source/log/index.ts"
+import { Logger } from "#Source/log/index.ts"
+
+/**
+ * 表示主动心跳轮次使用的消息处理器。
+ */
+export interface ActiveHeartbeatMessageHandler<Message> {
+  buildPingMessage: (clientId: string) => Message
+  verifyPongMessage: (clientId: string, message: Message) => boolean
+}
+
+/**
+ * 表示被动响应心跳时使用的消息处理器。
+ */
+export interface PassiveHeartbeatMessageHandler<Message> {
+  verifyPingMessage: (clientId: string, message: Message) => boolean
+  buildPongMessage: (clientId: string, message: Message) => Message
+}
+
+/**
+ * 表示主动心跳消息处理器的构造器。
+ */
+export type ActiveHeartbeatMessageHandlerGenerator<Message> = () => ActiveHeartbeatMessageHandler<Message>
+
+/**
+ * 表示被动心跳消息处理器的构造器。
+ */
+export type PassiveHeartbeatMessageHandlerGenerator<Message> = () => PassiveHeartbeatMessageHandler<Message>
+
+/**
+ * 表示 SocketUnitHeartbeat 的配置项。
+ */
+export interface SocketUnitHeartbeatOptions<Message> extends LoggerFriendlyOptions {
+  enableActiveHeartbeat?: boolean | undefined
+  enablePassiveHeartbeat?: boolean | undefined
+  heartbeatInterval?: number | undefined
+  maxResponseTime?: number | undefined
+  maxHeartbeatLostCount?: number | undefined
+  activeHeartbeatMessageHandlerGenerator?: ActiveHeartbeatMessageHandlerGenerator<Message> | undefined
+  passiveHeartbeatMessageHandlerGenerator?: PassiveHeartbeatMessageHandlerGenerator<Message> | undefined
+}
+
+/**
+ * 验证心跳配置是否满足统一运行时的基本约束。
+ */
+export const validateSocketUnitHeartbeatOptions = <Message>(options: SocketUnitHeartbeatOptions<Message>): void => {
+  if (
+    options.enableActiveHeartbeat === true
+    && options.activeHeartbeatMessageHandlerGenerator === undefined
+  ) {
+    throw new Error("Active heartbeat message handler is required when active heartbeat is enabled.")
+  }
+
+  if (
+    options.enablePassiveHeartbeat === true
+    && options.passiveHeartbeatMessageHandlerGenerator === undefined
+  ) {
+    throw new Error("Passive heartbeat message handler is required when passive heartbeat is enabled.")
+  }
+
+  if (
+    options.heartbeatInterval !== undefined
+    && (!Number.isFinite(options.heartbeatInterval) || options.heartbeatInterval <= 0)
+  ) {
+    throw new Error("Heartbeat interval must be a positive finite number.")
+  }
+
+  if (
+    options.maxResponseTime !== undefined
+    && (!Number.isFinite(options.maxResponseTime) || options.maxResponseTime <= 0)
+  ) {
+    throw new Error("Max response time must be a positive finite number.")
+  }
+
+  if (
+    options.maxHeartbeatLostCount !== undefined
+    && (!Number.isFinite(options.maxHeartbeatLostCount) || options.maxHeartbeatLostCount < 1)
+  ) {
+    throw new Error("Max heartbeat lost count must be at least 1.")
+  }
+}
+
+/**
+ * 表示补齐默认值后的心跳配置。
+ */
+export interface ResolvedSocketUnitHeartbeatOptions<Message> extends LoggerFriendlyOptions {
+  enableActiveHeartbeat: boolean
+  enablePassiveHeartbeat: boolean
+  heartbeatInterval: number
+  maxResponseTime: number
+  maxHeartbeatLostCount: number
+  activeHeartbeatMessageHandlerGenerator?: ActiveHeartbeatMessageHandlerGenerator<Message> | undefined
+  passiveHeartbeatMessageHandlerGenerator?: PassiveHeartbeatMessageHandlerGenerator<Message> | undefined
+}
+
+/**
+ * 为心跳配置补齐统一运行时所需的默认值。
+ */
+export const resolveSocketUnitHeartbeatOptions = <Message>(options: SocketUnitHeartbeatOptions<Message>): ResolvedSocketUnitHeartbeatOptions<Message> => {
+  return {
+    ...options,
+    enableActiveHeartbeat: options.enableActiveHeartbeat ?? false,
+    enablePassiveHeartbeat: options.enablePassiveHeartbeat ?? false,
+    heartbeatInterval: options.heartbeatInterval ?? 30 * 1_000,
+    maxResponseTime: options.maxResponseTime ?? 10 * 1_000,
+    maxHeartbeatLostCount: options.maxHeartbeatLostCount ?? 3,
+    activeHeartbeatMessageHandlerGenerator: options.activeHeartbeatMessageHandlerGenerator,
+    passiveHeartbeatMessageHandlerGenerator: options.passiveHeartbeatMessageHandlerGenerator,
+  }
+}
+
+/**
+ * 表示心跳运行时与外部 SocketUnit 之间的回调边界。
+ */
+export interface SocketUnitHeartbeatCallbacks {
+  sendMessage: (message: { action: string, messageString: string }) => boolean
+  close: () => void
+}
+
+/**
+ * 表示单个心跳轮次的状态。
+ */
+export type SocketUnitHeartbeatStateStatus = "waiting" | "success" | "fail"
+
+/**
+ * 表示统一心跳运行时内部保留的一条轮次记录。
+ */
+export interface SocketUnitHeartbeatState<Message> {
+  activeHeartbeatMessageHandler: ActiveHeartbeatMessageHandler<Message>
+  responseTimer: ReturnType<typeof setTimeout> | undefined
+  status: SocketUnitHeartbeatStateStatus
+  pingMessageString: string | undefined
+  pongMessageString: string | undefined
+}
+
+/**
+ * 表示单个心跳轮次对外暴露的只读快照。
+ */
+export interface SocketUnitHeartbeatStateSnapshot {
+  status: SocketUnitHeartbeatStateStatus
+  hasPendingResponseTimer: boolean
+  pingMessageString: string | undefined
+  pongMessageString: string | undefined
+}
+
+/**
+ * 表示统一心跳运行时的聚合快照。
+ */
+export interface SocketUnitHeartbeatSnapshot {
+  enabledActiveHeartbeat: boolean
+  enabledPassiveHeartbeat: boolean
+  isRunning: boolean
+  waitingCount: number
+  successCount: number
+  failCount: number
+  recentStates: SocketUnitHeartbeatStateSnapshot[]
+}
+
+/**
+ * 管理 SocketUnit 的统一心跳运行时。
+ */
+export class SocketUnitHeartbeat<Message> implements LoggerFriendly {
+  protected readonly options: ResolvedSocketUnitHeartbeatOptions<Message>
+  protected readonly callbacks: SocketUnitHeartbeatCallbacks
+
+  readonly logger: Logger
+
+  protected heartbeatTimer: ReturnType<typeof setInterval> | undefined
+  protected heartbeatStates: Array<SocketUnitHeartbeatState<Message>>
+
+  constructor(
+    options: SocketUnitHeartbeatOptions<Message>,
+    callbacks: SocketUnitHeartbeatCallbacks,
+  ) {
+    validateSocketUnitHeartbeatOptions(options)
+
+    this.options = resolveSocketUnitHeartbeatOptions(options)
+    this.callbacks = callbacks
+
+    this.logger = Logger.fromOptions(options).setDefaultName("SocketUnitHeartbeat")
+
+    this.heartbeatTimer = undefined
+    this.heartbeatStates = []
+  }
+
+
+  /**
+   * 返回统一心跳运行时的诊断快照。
+   */
+  getSnapshot(): SocketUnitHeartbeatSnapshot {
+    let waitingCount = 0
+    let successCount = 0
+    let failCount = 0
+
+    const recentStates = this.heartbeatStates.map((heartbeatState) => {
+      switch (heartbeatState.status) {
+        case "waiting": {
+          waitingCount = waitingCount + 1
+          break
+        }
+        case "success": {
+          successCount = successCount + 1
+          break
+        }
+        case "fail": {
+          failCount = failCount + 1
+          break
+        }
+        default: {
+          throw new Error("Unexpected heartbeat state status.")
+        }
+      }
+
+      return {
+        status: heartbeatState.status,
+        hasPendingResponseTimer: heartbeatState.responseTimer !== undefined,
+        pingMessageString: heartbeatState.pingMessageString,
+        pongMessageString: heartbeatState.pongMessageString,
+      }
+    })
+
+    return {
+      enabledActiveHeartbeat: this.options.enableActiveHeartbeat,
+      enabledPassiveHeartbeat: this.options.enablePassiveHeartbeat,
+      isRunning: this.heartbeatTimer !== undefined,
+      waitingCount,
+      successCount,
+      failCount,
+      recentStates,
+    }
+  }
+
+  /**
+   * 在启用主动心跳时启动轮询调度。
+   */
+  start(clientId: string): void {
+    if (this.options.enableActiveHeartbeat === false) {
+      return
+    }
+
+    if (this.heartbeatTimer !== undefined) {
+      return
+    }
+
+    this.heartbeatTimer = setInterval(() => {
+      this.runActiveHeartbeat(clientId)
+    }, this.options.heartbeatInterval)
+  }
+
+  /**
+   * 停止心跳调度并清理全部轮次状态。
+   */
+  stop(): void {
+    if (this.heartbeatTimer !== undefined) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = undefined
+    }
+
+    this.heartbeatStates.forEach((heartbeatState) => {
+      if (heartbeatState.responseTimer !== undefined) {
+        clearTimeout(heartbeatState.responseTimer)
+      }
+    })
+    this.heartbeatStates = []
+  }
+
+  protected runActiveHeartbeat(clientId: string): void {
+    const activeHeartbeatMessageHandler = this.options.activeHeartbeatMessageHandlerGenerator!()
+    const heartbeatState: SocketUnitHeartbeatState<Message> = {
+      activeHeartbeatMessageHandler,
+      responseTimer: undefined,
+      status: "waiting",
+      pingMessageString: undefined,
+      pongMessageString: undefined,
+    }
+    this.heartbeatStates.push(heartbeatState)
+
+    const pingMessage = activeHeartbeatMessageHandler.buildPingMessage(clientId)
+    const pingMessageString = JSON.stringify(pingMessage)
+    heartbeatState.pingMessageString = pingMessageString
+
+    const sendResult = this.callbacks.sendMessage({
+      action: "Active heartbeat ping send",
+      messageString: pingMessageString,
+    })
+    if (sendResult === true) {
+      this.logger.info(`Active heartbeat ping message sent: ${clientId}, ${pingMessageString}`)
+    }
+    else {
+      heartbeatState.status = "fail"
+      this.callbacks.close()
+      return
+    }
+
+    heartbeatState.responseTimer = setTimeout(() => {
+      if (heartbeatState.status !== "waiting") {
+        return
+      }
+
+      heartbeatState.responseTimer = undefined
+      heartbeatState.status = "fail"
+      const timeoutCount = this.countConsecutiveHeartbeatTimeouts(this.heartbeatStates)
+      if (timeoutCount >= this.options.maxHeartbeatLostCount) {
+        this.logger.error("Heartbeat timeout limit reached. Closing WebSocket connection.")
+        this.callbacks.close()
+      }
+    }, this.options.maxResponseTime)
+  }
+
+  handleMessage(
+    clientId: string,
+    message: Message,
+  ): boolean {
+    const activeHandleResult = this.handleActiveHeartbeatMessage(
+      clientId, message
+    )
+    if (activeHandleResult === true) {
+      return true
+    }
+
+    const passiveHandleResult = this.handlePassiveHeartbeatMessage(
+      clientId, message
+    )
+    return passiveHandleResult
+  }
+
+  protected handleActiveHeartbeatMessage(
+    clientId: string,
+    message: Message,
+  ): boolean {
+    if (this.options.enableActiveHeartbeat === false) {
+      return false
+    }
+
+    const heartbeatState = this.findMatchingWaitingHeartbeatState(clientId, message)
+    if (heartbeatState === undefined) {
+      return false
+    }
+
+    const messageString = JSON.stringify(message)
+    this.logger.info(`Active heartbeat pong message received: ${clientId}, ${messageString}`)
+    if (heartbeatState.responseTimer !== undefined) {
+      clearTimeout(heartbeatState.responseTimer)
+      heartbeatState.responseTimer = undefined
+    }
+    heartbeatState.pongMessageString = messageString
+    heartbeatState.status = "success"
+    this.cleanupHeartbeatStatesAfterSuccess(heartbeatState)
+    return true
+  }
+
+  protected handlePassiveHeartbeatMessage(
+    clientId: string,
+    message: Message,
+  ): boolean {
+    if (this.options.enablePassiveHeartbeat === false) {
+      return false
+    }
+
+    const passiveHeartbeatMessageHandler = this.options.passiveHeartbeatMessageHandlerGenerator!()
+    if (passiveHeartbeatMessageHandler.verifyPingMessage(clientId, message) === false) {
+      return false
+    }
+
+    const messageString = JSON.stringify(message)
+    this.logger.info(`Passive heartbeat ping message received: ${clientId}, ${messageString}`)
+    const pongMessage = passiveHeartbeatMessageHandler.buildPongMessage(clientId, message)
+    const pongMessageString = JSON.stringify(pongMessage)
+    const sendResult = this.callbacks.sendMessage({
+      action: "Passive heartbeat pong send",
+      messageString: pongMessageString,
+    })
+    if (sendResult === true) {
+      this.logger.info(`Passive heartbeat pong message sent: ${clientId}, ${pongMessageString}`)
+    }
+    return true
+  }
+
+  protected findMatchingWaitingHeartbeatState(
+    clientId: string,
+    message: Message,
+  ): SocketUnitHeartbeatState<Message> | undefined {
+    for (let index = this.heartbeatStates.length - 1; index >= 0; index = index - 1) {
+      const heartbeatState = this.heartbeatStates[index]!
+
+      if (heartbeatState.status !== "waiting") {
+        continue
+      }
+
+      if (heartbeatState.activeHeartbeatMessageHandler.verifyPongMessage(clientId, message) === true) {
+        return heartbeatState
+      }
+    }
+
+    return undefined
+  }
+
+  protected countConsecutiveHeartbeatTimeouts(
+    heartbeatStates: Array<SocketUnitHeartbeatState<Message>>,
+  ): number {
+    let timeoutCount = 0
+
+    for (let index = heartbeatStates.length - 1; index >= 0; index = index - 1) {
+      const heartbeatState = heartbeatStates[index]!
+
+      if (heartbeatState.status === "fail") {
+        timeoutCount = timeoutCount + 1
+        continue
+      }
+
+      break
+    }
+
+    return timeoutCount
+  }
+
+  protected cleanupHeartbeatStatesAfterSuccess(
+    successState: SocketUnitHeartbeatState<Message>,
+  ): void {
+    const successStateIndex = this.heartbeatStates.lastIndexOf(successState)
+    if (successStateIndex === -1) {
+      return
+    }
+
+    this.heartbeatStates.splice(0, successStateIndex + 1)
+  }
+}

package/src/socket/index.ts

@@ -0,0 +1,3 @@
+export * from "./common/index.ts"
+export * as Server from "./server/index.ts"
+export * as Client from "./client/index.ts"

package/src/socket/server/index.ts

@@ -0,0 +1,3 @@
+export * from "./socket.ts"
+export * from "./socket-unit.ts"
+export * from "./server.ts"