@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/tests/unit/route/uri/search.spec.ts

@@ -0,0 +1,107 @@
+import { expect, test } from "vitest"
+
+import {
+  isSearchIncludes,
+  isSearchLooseEqual,
+  isSearchLooseIncludes,
+  isSearchStrictEqual,
+  isSearchStrictIncludes,
+  neatenQueryString,
+  neatenSearch,
+  queryObjectToQueryString,
+  queryObjectToSearch,
+  queryStringToQueryObject,
+  queryStringToSearch,
+  searchToQueryObject,
+  searchToQueryString,
+  toQueryObject,
+  toQueryString,
+  toSearch,
+} from "#Source/route/index.ts"
+
+test("neatenSearch ensures the search string starts with a question mark", () => {
+  expect(neatenSearch("a=1&b=2&c=3")).toBe("?a=1&b=2&c=3")
+  expect(neatenSearch("?a=1&b=2&c=3")).toBe("?a=1&b=2&c=3")
+})
+
+test("neatenQueryString removes a leading question mark when present", () => {
+  expect(neatenQueryString("?name=mobius")).toBe("name=mobius")
+  expect(neatenQueryString("name=mobius")).toBe("name=mobius")
+})
+
+test("queryStringToQueryObject decodes keys and values and preserves later equals signs", () => {
+  expect(queryStringToQueryObject("?na%20me=mobius%20model&formula=a%3Db&empty="))
+    .toEqual({ "na me": "mobius model", formula: "a=b", empty: "" })
+  expect(queryStringToQueryObject("a=1&b=2&c=3")).toEqual({ a: "1", b: "2", c: "3" })
+  expect(queryStringToQueryObject("?a=1&b=2&c=3")).toEqual({ a: "1", b: "2", c: "3" })
+})
+
+test("queryObjectToQueryString encodes keys and values into a query string", () => {
+  expect(queryObjectToQueryString({ "na me": "mobius model", formula: "a=b" }))
+    .toBe("na%20me=mobius%20model&formula=a%3Db")
+  expect(queryObjectToQueryString({ a: "1", b: "2", c: "3" })).toBe("a=1&b=2&c=3")
+})
+
+test("searchToQueryString aliases query-string normalization for search input", () => {
+  expect(searchToQueryString("?a=1&b=2&c=3")).toBe("a=1&b=2&c=3")
+})
+
+test("searchToQueryObject parses search input into a query object", () => {
+  expect(searchToQueryObject("?name=mobius&mode=stable")).toEqual({ name: "mobius", mode: "stable" })
+  expect(searchToQueryObject("?a=1&b=2&c=3")).toEqual({ a: "1", b: "2", c: "3" })
+})
+
+test("queryStringToSearch aliases search normalization for query-string input", () => {
+  expect(queryStringToSearch("a=1&b=2&c=3")).toBe("?a=1&b=2&c=3")
+})
+
+test("queryObjectToSearch serializes a query object into search format", () => {
+  expect(queryObjectToSearch({ name: "mobius model", mode: "a=b" })).toBe("?name=mobius%20model&mode=a%3Db")
+  expect(queryObjectToSearch({ a: "1", b: "2", c: "3" })).toBe("?a=1&b=2&c=3")
+})
+
+test("toSearch returns search format for both strings and objects", () => {
+  expect(toSearch("a=1&b=2&c=3")).toBe("?a=1&b=2&c=3")
+  expect(toSearch("?a=1&b=2&c=3")).toBe("?a=1&b=2&c=3")
+  expect(toSearch({ a: "1", b: "2", c: "3" })).toBe("?a=1&b=2&c=3")
+})
+
+test("toQueryString returns query-string format for both strings and objects", () => {
+  expect(toQueryString("a=1&b=2&c=3")).toBe("a=1&b=2&c=3")
+  expect(toQueryString("?a=1&b=2&c=3")).toBe("a=1&b=2&c=3")
+  expect(toQueryString({ a: "1", b: "2", c: "3" })).toBe("a=1&b=2&c=3")
+})
+
+test("queryObject returns parsed query objects for both strings and objects", () => {
+  const queryObject = { a: "1", b: "2", c: "3" }
+
+  expect(toQueryObject("a=1&b=2&c=3")).toEqual({ a: "1", b: "2", c: "3" })
+  expect(toQueryObject("?a=1&b=2&c=3")).toEqual({ a: "1", b: "2", c: "3" })
+  expect(toQueryObject(queryObject)).toBe(queryObject)
+  expect(toQueryObject("")).toEqual({})
+})
+
+test("isSearchLooseIncludes checks whether all requested query keys exist", () => {
+  expect(isSearchLooseIncludes("?a=1&b=2", ["a"])).toBe(true)
+  expect(isSearchLooseIncludes("?a=1&b=2", ["a", "c"])).toBe(false)
+})
+
+test("isSearchStrictIncludes checks whether query key sets are identical", () => {
+  expect(isSearchStrictIncludes("?a=1&b=2", ["b", "a"])).toBe(true)
+  expect(isSearchStrictIncludes("?ab=1&c=2", ["a", "bc"])).toBe(false)
+})
+
+test("isSearchIncludes supports required and optional query keys", () => {
+  expect(isSearchIncludes("?a=1&b=2", { a: "required", b: "optional" })).toBe(true)
+  expect(isSearchIncludes("?a=1&b=2", { a: "required" })).toBe(false)
+})
+
+test("isSearchLooseEqual checks whether target query values are a matching subset", () => {
+  expect(isSearchLooseEqual("?a=1&b=2", "?a=1")).toBe(true)
+  expect(isSearchLooseEqual("?a=1&b=2", { a: "1", c: "3" })).toBe(false)
+})
+
+test("isSearchStrictEqual checks whether query key sets and values are identical", () => {
+  expect(isSearchStrictEqual("?a=1&b=2", "?b=2&a=1")).toBe(true)
+  expect(isSearchStrictEqual("?a=1&b=2", "?a=1")).toBe(false)
+})

package/tests/unit/socket/client.spec.ts

@@ -0,0 +1,208 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { Client } from "#Source/socket/index.ts"
+
+type FakeEventMap = {
+  close: { code: number; reason: string }
+  error: Event
+  message: { data: string }
+  open: Event
+}
+
+class FakeWebSocket {
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  static readonly CLOSING = 2
+  static readonly CLOSED = 3
+  static instances: FakeWebSocket[] = []
+
+  readonly url: string
+  readonly sentMessages: string[]
+  readyState: number
+
+  private readonly listeners: {
+    [K in keyof FakeEventMap]: Set<(event: FakeEventMap[K]) => void>
+  }
+
+  constructor(url: string) {
+    this.url = url
+    this.sentMessages = []
+    this.readyState = FakeWebSocket.CONNECTING
+    this.listeners = {
+      close: new Set(),
+      error: new Set(),
+      message: new Set(),
+      open: new Set(),
+    }
+
+    FakeWebSocket.instances.push(this)
+  }
+
+  addEventListener<K extends keyof FakeEventMap>(type: K, listener: (event: FakeEventMap[K]) => void): void {
+    this.listeners[type].add(listener)
+  }
+
+  removeEventListener<K extends keyof FakeEventMap>(type: K, listener: (event: FakeEventMap[K]) => void): void {
+    this.listeners[type].delete(listener)
+  }
+
+  send(message: string): void {
+    if (this.readyState !== FakeWebSocket.OPEN) {
+      throw new Error("FakeWebSocket is not open.")
+    }
+
+    this.sentMessages.push(message)
+  }
+
+  close(): void {
+    if (this.readyState === FakeWebSocket.CLOSED) {
+      return
+    }
+
+    this.readyState = FakeWebSocket.CLOSED
+    this.emit("close", { code: 1_000, reason: "" })
+  }
+
+  simulateOpen(): void {
+    this.readyState = FakeWebSocket.OPEN
+    this.emit("open", new Event("open"))
+  }
+
+  simulateMessage(message: unknown): void {
+    this.emit("message", { data: JSON.stringify(message) })
+  }
+
+  simulateError(): void {
+    this.emit("error", new Event("error"))
+  }
+
+  private emit<K extends keyof FakeEventMap>(type: K, event: FakeEventMap[K]): void {
+    for (const listener of this.listeners[type]) {
+      listener(event)
+    }
+  }
+}
+
+afterEach(() => {
+  FakeWebSocket.instances = []
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+test("Client.SocketUnit queues work until ready, deduplicates status events, and keeps runtime listeners after error", async () => {
+  vi.stubGlobal("WebSocket", FakeWebSocket)
+
+  const socketUnit = new Client.SocketUnit<{ type: string }>({
+    url: "ws://socket.test",
+  })
+  const statuses: string[] = []
+  const messages: Array<{ type: string }> = []
+
+  socketUnit.eventManager.subscribe("status", (status) => {
+    statuses.push(status)
+  })
+  socketUnit.eventManager.subscribe("message", (message) => {
+    messages.push(message)
+  })
+
+  socketUnit.setClientId("client-1")
+  socketUnit.sendMessage({ type: "queued-before-open" })
+
+  expect(socketUnit.getSnapshot().pendingActionCount).toBe(1)
+
+  const openPromise = socketUnit.open()
+  const firstWebSocket = FakeWebSocket.instances[0]!
+
+  expect(socketUnit.getStatus()).toBe("CONNECTING")
+
+  firstWebSocket.simulateOpen()
+  await openPromise
+
+  expect(firstWebSocket.sentMessages).toEqual([
+    JSON.stringify({ type: "queued-before-open" }),
+  ])
+  expect(statuses).toEqual(["CONNECTING", "OPEN"])
+
+  firstWebSocket.simulateMessage({ type: "message-1" })
+  firstWebSocket.simulateMessage({ type: "message-2" })
+  firstWebSocket.simulateError()
+  firstWebSocket.simulateMessage({ type: "message-3" })
+
+  expect(messages).toEqual([
+    { type: "message-1" },
+    { type: "message-2" },
+    { type: "message-3" },
+  ])
+  expect(statuses).toEqual(["CONNECTING", "OPEN"])
+
+  await expect(socketUnit.safeOpen()).rejects.toThrow("Socket is already open")
+
+  await socketUnit.close()
+  expect(socketUnit.getStatus()).toBe("UNINSTANTIATED")
+
+  let resetCount = 0
+  await socketUnit.reset(() => {
+    resetCount = resetCount + 1
+  })
+
+  expect(resetCount).toBe(1)
+  expect(socketUnit.getSnapshot()).toMatchObject({
+    clientId: undefined,
+    pendingActionCount: 0,
+    status: "UNINSTANTIATED",
+  })
+})
+
+test("Client.Socket emits connect close and message events from stable ready-to-work transitions", async () => {
+  vi.stubGlobal("WebSocket", FakeWebSocket)
+
+  const socket = new Client.Socket<{ type: string }>({
+    url: "ws://socket.test",
+  })
+  const connectClientIds: Array<string | undefined> = []
+  const closeClientIds: Array<string | undefined> = []
+  const forwardedMessages: Array<{ clientId: string; message: { type: string } }> = []
+
+  socket.eventManager.subscribe("connect", ({ clientId }) => {
+    connectClientIds.push(clientId)
+  })
+  socket.eventManager.subscribe("close", ({ clientId }) => {
+    closeClientIds.push(clientId)
+  })
+  socket.eventManager.subscribe("message", (payload) => {
+    forwardedMessages.push(payload)
+  })
+
+  socket.setClientId("client-2")
+  socket.sendMessage({ type: "queued-before-open" })
+
+  const openPromise = socket.open()
+  const firstWebSocket = FakeWebSocket.instances[0]!
+  firstWebSocket.simulateOpen()
+  await openPromise
+
+  expect(connectClientIds).toEqual(["client-2"])
+  expect(firstWebSocket.sentMessages).toEqual([
+    JSON.stringify({ type: "queued-before-open" }),
+  ])
+
+  firstWebSocket.simulateMessage({ type: "hello" })
+  firstWebSocket.simulateMessage({ type: "hello-again" })
+
+  expect(forwardedMessages).toEqual([
+    { clientId: "client-2", message: { type: "hello" } },
+    { clientId: "client-2", message: { type: "hello-again" } },
+  ])
+  expect(connectClientIds).toEqual(["client-2"])
+
+  await socket.close()
+  expect(closeClientIds).toEqual(["client-2"])
+
+  socket.reset()
+
+  expect(socket.getSnapshot()).toMatchObject({
+    clientId: "client-2",
+    isReadyToWork: false,
+    status: "UNINSTANTIATED",
+  })
+})

package/tests/unit/socket/server.spec.ts

@@ -0,0 +1,133 @@
+import type { AddressInfo } from "node:net"
+
+import { afterEach, expect, test, vi } from "vitest"
+import { WebSocket as WsClient } from "ws"
+
+import { Server } from "#Source/socket/index.ts"
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test("Server.createWebSocketServer returns usable local URLs and stable lifecycle helpers", async () => {
+  const webSocketServer = Server.createWebSocketServer({ port: 0 })
+
+  expect(webSocketServer.isRunning()).toBe(false)
+
+  const runningResult = await webSocketServer.run()
+  const address = webSocketServer.safeGetServer().address() as AddressInfo
+
+  expect(runningResult.server).toBe(webSocketServer.safeGetServer())
+  expect(runningResult.urlList).toContain(`ws://127.0.0.1:${address.port}`)
+  expect(runningResult.urlList).toContain(`ws://localhost:${address.port}`)
+  expect(runningResult.urlList).toContain(`ws://[::1]:${address.port}`)
+  expect(webSocketServer.isRunning()).toBe(true)
+
+  await webSocketServer.close()
+
+  expect(webSocketServer.isRunning()).toBe(false)
+})
+
+test("Server.Socket attach does not take over an already running server lifecycle", async () => {
+  const webSocketServer = Server.createWebSocketServer({ port: 0 })
+  await webSocketServer.run()
+
+  const socket = new Server.Socket<{ type: string }>({
+    webSocketServer,
+    onMessage: () => {
+      // no op
+    },
+  })
+
+  socket.attach()
+
+  expect(socket.getSnapshot()).toMatchObject({
+    isRunning: true,
+    isStarted: true,
+    managesWebSocketServerLifecycle: false,
+  })
+
+  await socket.close()
+
+  expect(webSocketServer.isRunning()).toBe(true)
+
+  await webSocketServer.close()
+})
+
+test("Server.Socket exposes stable connect timing and forwards messages for active connections", async () => {
+  const webSocketServer = Server.createWebSocketServer({ port: 0 })
+  const socket = new Server.Socket<{ type: string }>({
+    webSocketServer,
+    onMessage: () => {
+      // no-op
+    },
+  })
+
+  const connectPromise = new Promise<string>((resolve) => {
+    socket.eventManager.subscribe("connect", ({ clientId }) => {
+      const socketUnitSnapshot = socket.getSocketUnitSnapshot(clientId)
+
+      expect(socketUnitSnapshot).toMatchObject({
+        clientId,
+        isReadyToWork: true,
+        status: "OPEN",
+      })
+
+      resolve(clientId)
+    })
+  })
+  const inboundMessagePromise = new Promise<{ clientId: string; message: { type: string } }>((resolve) => {
+    socket.eventManager.subscribe("message", (payload) => {
+      resolve(payload)
+    })
+  })
+  const closePromise = new Promise<string>((resolve) => {
+    socket.eventManager.subscribe("close", ({ clientId }) => {
+      resolve(clientId)
+    })
+  })
+
+  await socket.open()
+
+  const address = webSocketServer.safeGetServer().address() as AddressInfo
+  const client = new WsClient(`ws://127.0.0.1:${address.port}`)
+
+  await new Promise<void>((resolve, reject) => {
+    client.once("open", () => {
+      resolve()
+    })
+    client.once("error", reject)
+  })
+
+  const clientId = await connectPromise
+
+  client.send(JSON.stringify({ type: "hello-server" }))
+
+  await expect(inboundMessagePromise).resolves.toEqual({
+    clientId,
+    message: { type: "hello-server" },
+  })
+
+  const outboundMessagePromise = new Promise<string>((resolve, reject) => {
+    client.once("message", (message) => {
+      resolve(message.toString())
+    })
+    client.once("error", reject)
+  })
+
+  socket.sendMessage(clientId, { type: "hello-client" })
+
+  await expect(outboundMessagePromise).resolves.toBe(JSON.stringify({ type: "hello-client" }))
+
+  client.close()
+
+  await expect(closePromise).resolves.toBe(clientId)
+
+  await socket.close()
+
+  expect(socket.getSnapshot()).toMatchObject({
+    activeSocketUnitCount: 0,
+    isRunning: false,
+    isStarted: false,
+  })
+})

package/tests/unit/socket/socket-unit-heartbeat.spec.ts

@@ -0,0 +1,214 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import {
+  SocketUnitHeartbeat,
+  resolveSocketUnitHeartbeatOptions,
+  validateSocketUnitHeartbeatOptions,
+} from "#Source/socket/index.ts"
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+})
+
+test("SocketUnitHeartbeat validates required handlers and resolves default values", () => {
+  expect(() => validateSocketUnitHeartbeatOptions({
+    enableActiveHeartbeat: true,
+  })).toThrow("Active heartbeat message handler is required")
+
+  expect(() => validateSocketUnitHeartbeatOptions({
+    enablePassiveHeartbeat: true,
+  })).toThrow("Passive heartbeat message handler is required")
+
+  expect(() => validateSocketUnitHeartbeatOptions({
+    heartbeatInterval: 0,
+  })).toThrow("Heartbeat interval must be a positive finite number.")
+
+  expect(() => validateSocketUnitHeartbeatOptions({
+    maxResponseTime: 0,
+  })).toThrow("Max response time must be a positive finite number.")
+
+  expect(() => validateSocketUnitHeartbeatOptions({
+    maxHeartbeatLostCount: 0,
+  })).toThrow("Max heartbeat lost count must be at least 1.")
+
+  const resolvedOptions = resolveSocketUnitHeartbeatOptions({})
+
+  expect(resolvedOptions).toMatchObject({
+    enableActiveHeartbeat: false,
+    enablePassiveHeartbeat: false,
+    heartbeatInterval: 30_000,
+    maxResponseTime: 10_000,
+    maxHeartbeatLostCount: 3,
+  })
+})
+
+test("SocketUnitHeartbeat unifies active and passive handling with newest-first matching", async () => {
+  vi.useFakeTimers()
+
+  const sentMessages: Array<{ action: string; messageString: string }> = []
+  const close = vi.fn(() => {
+    throw new Error("Heartbeat close should not be called in this test.")
+  })
+  const heartbeat = new SocketUnitHeartbeat<{ kind: string; round?: number }>({
+    enableActiveHeartbeat: true,
+    enablePassiveHeartbeat: true,
+    heartbeatInterval: 100,
+    maxResponseTime: 500,
+    maxHeartbeatLostCount: 2,
+    activeHeartbeatMessageHandlerGenerator: () => {
+      return {
+        buildPingMessage: () => {
+          return { kind: "ping" }
+        },
+        verifyPongMessage: (_clientId, message) => {
+          return message.kind === "pong"
+        },
+      }
+    },
+    passiveHeartbeatMessageHandlerGenerator: () => {
+      return {
+        verifyPingMessage: (_clientId, message) => {
+          return message.kind === "ping-from-peer"
+        },
+        buildPongMessage: () => {
+          return { kind: "pong-from-peer" }
+        },
+      }
+    },
+  }, {
+    sendMessage: (message) => {
+      sentMessages.push(message)
+      return true
+    },
+    close,
+  })
+
+  expect(heartbeat.getSnapshot()).toMatchObject({
+    enabledActiveHeartbeat: true,
+    enabledPassiveHeartbeat: true,
+    failCount: 0,
+    isRunning: false,
+    recentStates: [],
+    successCount: 0,
+    waitingCount: 0,
+  })
+
+  heartbeat.start("client-1")
+
+  expect(heartbeat.getSnapshot().isRunning).toBe(true)
+
+  await vi.advanceTimersByTimeAsync(100)
+  await vi.advanceTimersByTimeAsync(100)
+
+  const waitingSnapshot = heartbeat.getSnapshot()
+
+  expect(sentMessages).toHaveLength(2)
+  expect(waitingSnapshot.waitingCount).toBe(2)
+  expect(waitingSnapshot.recentStates).toHaveLength(2)
+  expect(waitingSnapshot.recentStates.every((state) => {
+    return state.status === "waiting" && state.hasPendingResponseTimer === true
+  })).toBe(true)
+
+  const activeHandled = heartbeat.handleMessage("client-1", { kind: "pong" })
+
+  expect(activeHandled).toBe(true)
+  expect(heartbeat.getSnapshot()).toMatchObject({
+    failCount: 0,
+    recentStates: [],
+    successCount: 0,
+    waitingCount: 0,
+  })
+
+  const passiveHandled = heartbeat.handleMessage("client-1", { kind: "ping-from-peer" })
+
+  expect(passiveHandled).toBe(true)
+  expect(sentMessages.at(-1)).toEqual({
+    action: "Passive heartbeat pong send",
+    messageString: JSON.stringify({ kind: "pong-from-peer" }),
+  })
+
+  heartbeat.stop()
+
+  expect(close).not.toHaveBeenCalled()
+  expect(heartbeat.getSnapshot()).toMatchObject({
+    isRunning: false,
+    recentStates: [],
+    waitingCount: 0,
+  })
+})
+
+test("SocketUnitHeartbeat closes transport after consecutive timeout limit is reached", async () => {
+  vi.useFakeTimers()
+
+  let closeCount = 0
+  const heartbeat = new SocketUnitHeartbeat<{ kind: string }>({
+    enableActiveHeartbeat: true,
+    heartbeatInterval: 100,
+    maxResponseTime: 10,
+    maxHeartbeatLostCount: 2,
+    activeHeartbeatMessageHandlerGenerator: () => {
+      return {
+        buildPingMessage: () => {
+          return { kind: "ping" }
+        },
+        verifyPongMessage: () => {
+          return false
+        },
+      }
+    },
+  }, {
+    sendMessage: () => {
+      return true
+    },
+    close: () => {
+      closeCount = closeCount + 1
+    },
+  })
+
+  heartbeat.start("client-2")
+
+  await vi.advanceTimersByTimeAsync(100)
+  await vi.advanceTimersByTimeAsync(10)
+  expect(heartbeat.getSnapshot().failCount).toBe(1)
+  expect(closeCount).toBe(0)
+
+  await vi.advanceTimersByTimeAsync(100)
+  await vi.advanceTimersByTimeAsync(10)
+  expect(heartbeat.getSnapshot().failCount).toBeGreaterThanOrEqual(1)
+  expect(closeCount).toBe(1)
+})
+
+test("SocketUnitHeartbeat stays idle when active heartbeat is disabled and ignores unmatched messages", () => {
+  const heartbeat = new SocketUnitHeartbeat<{ kind: string }>({
+    enablePassiveHeartbeat: true,
+    passiveHeartbeatMessageHandlerGenerator: () => {
+      return {
+        verifyPingMessage: (_clientId, message) => {
+          return message.kind === "ping"
+        },
+        buildPongMessage: () => {
+          return { kind: "pong" }
+        },
+      }
+    },
+  }, {
+    sendMessage: () => {
+      return true
+    },
+    close: () => {
+      throw new Error("Heartbeat close should not be called in this test.")
+    },
+  })
+
+  heartbeat.start("client-3")
+
+  expect(heartbeat.getSnapshot()).toMatchObject({
+    isRunning: false,
+    recentStates: [],
+    waitingCount: 0,
+  })
+
+  expect(heartbeat.handleMessage("client-3", { kind: "unmatched" })).toBe(false)
+  expect(heartbeat.handleMessage("client-3", { kind: "ping" })).toBe(true)
+})