@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/__tests__/provider.test.ts

@@ -0,0 +1,504 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// provider 连接单例管理单元测试（mock WebSocket，jsdom；不依赖真服务）。
+// 四场景（§6 步骤 1）：
+//   ① ticket 过期自动重取（401 → serverFn → 重连）
+//   ② 指数退避重连（对齐 use-notifications/sse-transport 参数）+ 上限 offline
+//   ③ desktop 版 / 无 VITE_COLLAB_WS_URL → noop provider（方法安全空操作）
+//   ④ 多 room 并存互不干扰（共享单连接，多路复用决策见 provider.ts 顶注释）
+// Hocuspocus 线格式：varString(room) + varUint(type) + payload；
+// type：0=Sync(0=Step1,1=Step2,2=Update) 1=Awareness 2=Auth(0=Authenticated,
+// 1=PermissionDenied)。编解码为本文件内手写最小实现，避免引 lib0 直依赖。
+// 假服务端语义（对齐真服务端 4.7 实测行为，见 multiplex.test.ts）：
+// 拒绝单 room 只回 PermissionDenied、不断开连接；鉴权按 room 计数。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+
+const mockCreateCollabTicketFn = vi.fn()
+vi.mock('@/server/serverFns/collab', () => ({
+  createCollabTicketFn: (...args: unknown[]) => mockCreateCollabTicketFn(...args),
+}))
+
+const mockIsDesktopEdition = vi.fn((): boolean => false)
+vi.mock('@/lib/edition-desktop', () => ({
+  isDesktopEdition: (): boolean => mockIsDesktopEdition(),
+}))
+
+import {
+  __resetCollabForTests,
+  __setWebSocketPolyfillForTests,
+  destroyProvider,
+  getOrCreateProvider,
+} from '../provider'
+import { isCollabEnabled } from '../env'
+
+// ---------------------------------------------------------------------------
+// lib0 兼容 varuint/varstring 最小编解码（7-bit LE + 续位标志）
+// ---------------------------------------------------------------------------
+
+function putVarUint(bytes: number[], n: number): void {
+  while (n > 127) {
+    bytes.push((n & 127) | 128)
+    n >>>= 7
+  }
+  bytes.push(n)
+}
+
+function putVarString(bytes: number[], s: string): void {
+  const utf8 = new TextEncoder().encode(s)
+  putVarUint(bytes, utf8.length)
+  for (const byte of utf8) bytes.push(byte)
+}
+
+class Reader {
+  private pos = 0
+  constructor(private readonly bytes: Uint8Array) {}
+  readVarUint(): number {
+    let n = 0
+    let shift = 0
+    for (;;) {
+      const b = this.bytes[this.pos++]!
+      n += (b & 127) << shift
+      if (!(b & 128)) return n
+      shift += 7
+    }
+  }
+  readVarString(): string {
+    const len = this.readVarUint()
+    const s = new TextDecoder().decode(this.bytes.subarray(this.pos, this.pos + len))
+    this.pos += len
+    return s
+  }
+}
+
+/** 服务端 → 客户端 Auth 回复（AuthMessageType：0=Token 1=PermissionDenied 2=Authenticated） */
+function authReply(room: string, subtype: 0 | 1 | 2, arg: string): Uint8Array {
+  const bytes: number[] = []
+  putVarString(bytes, room)
+  putVarUint(bytes, 2) // Auth
+  putVarUint(bytes, subtype)
+  putVarString(bytes, arg)
+  return new Uint8Array(bytes)
+}
+
+/** 服务端 → 客户端 SyncStepTwo（空 doc 全量：update=[0,0]） */
+function syncStepTwo(room: string): Uint8Array {
+  const bytes: number[] = []
+  putVarString(bytes, room)
+  putVarUint(bytes, 0) // Sync
+  putVarUint(bytes, 1) // SyncStep2
+  putVarUint(bytes, 2) // update varUint8Array 长度
+  bytes.push(0, 0) // 空全量 update
+  return new Uint8Array(bytes)
+}
+
+/** 客户端发的是否 Auth 消息（room, type=2） */
+function isAuthMessage(bytes: Uint8Array): boolean {
+  try {
+    const reader = new Reader(bytes)
+    reader.readVarString()
+    return reader.readVarUint() === 2
+  } catch {
+    return false
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mock WebSocket（EventTarget 风格——provider 用 addEventListener 挂接）
+// ---------------------------------------------------------------------------
+
+interface FakeServer {
+  /** 每 room 已拒绝次数（全局计数，跨 socket 实例） */
+  denyCounts: Map<string, number>
+  /** 前 N 次 Auth 拒绝（模拟 401/ticket 过期），之后放行 */
+  denyFirstAuthCount: number
+  /** 在集合内的 room 的 Auth 一律拒绝 */
+  denyRooms: Set<string>
+}
+
+class MockWebSocket extends EventTarget {
+  static instances: MockWebSocket[] = []
+  /** 测试在创建前挂的接线路径：给每个新实例装假服务端行为 */
+  static onCreated: ((ws: MockWebSocket) => void) | null = null
+
+  static reset(): void {
+    MockWebSocket.instances = []
+    MockWebSocket.onCreated = null
+  }
+
+  url: string
+  readyState = 0 // CONNECTING
+  binaryType = 'blob'
+  sent: Uint8Array[] = []
+  private fakeServer: FakeServer | null = null
+
+  constructor(url: string) {
+    super()
+    this.url = url
+    MockWebSocket.instances.push(this)
+    // 覆写 send 以驱动假服务端（客户端发 Auth → 服务端即时回执）
+    const originalSend = this.send.bind(this)
+    this.send = (data: ArrayBuffer | Uint8Array) => {
+      originalSend(data)
+      this.handleClientMessage(new Uint8Array(data as ArrayBuffer))
+    }
+    MockWebSocket.onCreated?.(this)
+  }
+
+  attachFakeServer(server: FakeServer): void {
+    this.fakeServer = server
+  }
+
+  send(data: ArrayBuffer | Uint8Array): void {
+    this.sent.push(new Uint8Array(data))
+  }
+
+  close(): void {
+    this.serverClose(1000, '')
+  }
+
+  // ---- 测试驱动（模拟服务端行为） ----
+
+  serverOpen(): void {
+    this.readyState = 1
+    this.dispatchEvent(new Event('open'))
+  }
+
+  serverSend(bytes: Uint8Array): void {
+    this.dispatchEvent(new MessageEvent('message', { data: bytes }))
+  }
+
+  serverClose(code: number, reason: string): void {
+    if (this.readyState === 3) return
+    this.readyState = 3
+    this.dispatchEvent(new CloseEvent('close', { code, reason }))
+  }
+
+  /** 解析客户端消息并按假服务端语义回执 */
+  private handleClientMessage(bytes: Uint8Array): void {
+    if (!this.fakeServer) return
+    try {
+      const reader = new Reader(bytes)
+      const room = reader.readVarString()
+      const type = reader.readVarUint()
+      if (type === 2) {
+        reader.readVarString() // token（不校验内容）
+        const server = this.fakeServer
+        const count = server.denyCounts.get(room) ?? 0
+        server.denyCounts.set(room, count + 1)
+        const denied =
+          server.denyRooms.has(room) || count < server.denyFirstAuthCount
+        if (denied) {
+          // 对齐真服务端 4.7：按文档拒绝（PermissionDenied），连接存活
+          this.serverSend(authReply(room, 1, 'ticket-expired'))
+        } else {
+          this.serverSend(authReply(room, 2, 'read-write'))
+        }
+      } else if (type === 0) {
+        const subtype = reader.readVarUint()
+        if (subtype === 0) this.serverSend(syncStepTwo(room))
+      }
+      // Awareness(1)/其他：不回执
+    } catch {
+      // 非 Hocuspocus 载荷，忽略
+    }
+  }
+}
+
+/** 安装假服务端；返回可动态操纵的 FakeServer */
+function installFakeServer(
+  options: { denyFirstAuthCount?: number; denyRooms?: string[] } = {},
+): FakeServer {
+  const server: FakeServer = {
+    denyCounts: new Map(),
+    denyFirstAuthCount: options.denyFirstAuthCount ?? 0,
+    denyRooms: new Set(options.denyRooms ?? []),
+  }
+  MockWebSocket.onCreated = (ws) => ws.attachFakeServer(server)
+  return server
+}
+
+const flush = async (): Promise<void> => {
+  await vi.advanceTimersByTimeAsync(0)
+}
+const advance = async (ms: number): Promise<void> => {
+  await vi.advanceTimersByTimeAsync(ms)
+}
+
+async function waitFor(
+  cond: () => boolean,
+  label: string,
+  { maxTicks = 100 }: { maxTicks?: number } = {},
+): Promise<void> {
+  for (let i = 0; i < maxTicks; i++) {
+    if (cond()) return
+    await flush()
+  }
+  throw new Error(`waitFor 超时：${label}`)
+}
+
+const ROOM = 'doc:knowledge:room-1'
+
+// ---------------------------------------------------------------------------
+
+describe('lib/collab/provider 连接单例管理', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.stubEnv('VITE_COLLAB_WS_URL', 'ws://collab.test')
+    vi.stubEnv('VITE_DEPLOY_TARGET', 'web')
+    mockIsDesktopEdition.mockReturnValue(false)
+    mockCreateCollabTicketFn.mockResolvedValue({ ticket: 't-1' })
+    __setWebSocketPolyfillForTests(MockWebSocket)
+  })
+
+  afterEach(() => {
+    __resetCollabForTests()
+    MockWebSocket.reset()
+    __setWebSocketPolyfillForTests(undefined)
+    vi.unstubAllEnvs()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  describe('场景① ticket 过期自动重取（401 → serverFn → 重连）', () => {
+    it('首次鉴权被拒后自动重取 ticket 重新鉴权（同一 socket 复用）', async () => {
+      installFakeServer({ denyFirstAuthCount: 1 })
+
+      const handle = getOrCreateProvider(ROOM)
+      expect(MockWebSocket.instances).toHaveLength(1)
+      // ticket 懒取：socket 打开（onOpen）前不调 serverFn
+      expect(mockCreateCollabTicketFn).not.toHaveBeenCalled()
+      expect(handle.getStatus()).toBe('connecting')
+
+      const ws = MockWebSocket.instances[0]!
+      ws.serverOpen()
+      await flush()
+      // 首次建连取 ticket，发出 Auth
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(1)
+      expect(ws.sent.filter(isAuthMessage)).toHaveLength(1)
+
+      // 假服务端对首次 Auth 回 PermissionDenied（401 等价物；连接存活）
+      // → 客户端退避 1000ms 后 re-attach → onOpen → 重取 ticket 重鉴权
+      await advance(999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(1)
+      await advance(1)
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(2)
+      expect(ws.sent.filter(isAuthMessage)).toHaveLength(2)
+      expect(handle.getStatus()).toBe('synced')
+      // 多路复用纪律：同一 socket 复用，不新建连接
+      expect(MockWebSocket.instances).toHaveLength(1)
+    })
+
+    it('恢复 synced 后失败计数清零（退避从 1000ms 重新开始）', async () => {
+      const server = installFakeServer({ denyFirstAuthCount: 2 })
+
+      const handle = getOrCreateProvider(ROOM)
+      const ws1 = MockWebSocket.instances[0]!
+      ws1.serverOpen()
+      await flush()
+      await waitFor(() => handle.getStatus() === 'connecting', '第 1 次被拒')
+      await advance(1000) // fail1 → 1000ms
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(2)
+      await advance(2000) // fail2 → 2000ms
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(3)
+      expect(handle.getStatus()).toBe('synced') // 第 3 次放行，计数清零
+
+      // 恢复后开始持续拒绝 + 网络断开触发重连（socket 级 fixed 1s）
+      server.denyRooms.add(ROOM)
+      ws1.serverClose(1006, 'connection-drop')
+      await advance(1000)
+      const ws2 = MockWebSocket.instances[1]!
+      ws2.serverOpen()
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(4) // 重连后重取
+      // 若计数未清零，此处退避应为 2000ms+；1000ms 即取到证明已清零
+      await advance(999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(4)
+      await advance(1)
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(5)
+    })
+  })
+
+  describe('场景② 指数退避重连 + 上限 offline', () => {
+    it('连续失败按 1s/2s/4s/8s/16s 退避，第 6 次失败进入 offline 停止重试', async () => {
+      installFakeServer({ denyRooms: [ROOM] })
+
+      const handle = getOrCreateProvider(ROOM)
+      const ws = MockWebSocket.instances[0]!
+      ws.serverOpen()
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(1) // fail1 → 1000ms
+
+      await advance(999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(1)
+      await advance(1) // t=1000 → 取第 2 次（fail2 → 2000ms）
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(2)
+
+      await advance(1999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(2)
+      await advance(1) // t=3000 → 第 3 次（fail3 → 4000ms）
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(3)
+
+      await advance(3999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(3)
+      await advance(1) // t=7000 → 第 4 次（fail4 → 8000ms）
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(4)
+
+      await advance(7999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(4)
+      await advance(1) // t=15000 → 第 5 次（fail5 → 16000ms）
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(5)
+
+      await advance(15999)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(5)
+      await advance(1) // t=31000 → 第 6 次（达上限）
+      await flush()
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(6)
+
+      // 第 6 次失败 → offline，停止重试
+      expect(handle.getStatus()).toBe('offline')
+      await advance(60000)
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(6)
+      // 全程复用同一条 socket（无连接churn）
+      expect(MockWebSocket.instances).toHaveLength(1)
+      expect(ws.sent.filter(isAuthMessage)).toHaveLength(6)
+    })
+  })
+
+  describe('场景③ desktop 版或无 VITE_COLLAB_WS_URL → noop provider', () => {
+    it('desktop 版：noop（不建连、不取 ticket、状态 offline、方法安全空操作）', () => {
+      mockIsDesktopEdition.mockReturnValue(true)
+
+      expect(isCollabEnabled()).toBe(false)
+      const handle = getOrCreateProvider(ROOM)
+      expect(mockCreateCollabTicketFn).not.toHaveBeenCalled()
+      expect(MockWebSocket.instances).toHaveLength(0)
+      expect(handle.getStatus()).toBe('offline')
+      // doc 可用（单机模式本地 Y.Doc）
+      expect(handle.doc).toBeInstanceOf(Y.Doc)
+      handle.doc.getText('t').insert(0, 'local-only')
+      expect(handle.doc.getText('t').toString()).toBe('local-only')
+      // 订阅安全：立即收到 offline 快照，退订安全
+      const seen: string[] = []
+      const unsubscribe = handle.onStatusChange((status) => seen.push(status))
+      expect(seen).toEqual(['offline'])
+      unsubscribe()
+      // 销毁幂等安全
+      handle.destroy()
+      expect(() => handle.destroy()).not.toThrow()
+      expect(() => destroyProvider(ROOM)).not.toThrow()
+    })
+
+    it('无 VITE_COLLAB_WS_URL：同上 noop', () => {
+      vi.stubEnv('VITE_COLLAB_WS_URL', '')
+      expect(isCollabEnabled()).toBe(false)
+
+      const handle = getOrCreateProvider(ROOM)
+      expect(mockCreateCollabTicketFn).not.toHaveBeenCalled()
+      expect(MockWebSocket.instances).toHaveLength(0)
+      expect(handle.getStatus()).toBe('offline')
+      handle.destroy()
+    })
+
+    it('noop 同 room 单例 + 销毁后重建为新实例', () => {
+      vi.stubEnv('VITE_COLLAB_WS_URL', '')
+      const a = getOrCreateProvider(ROOM)
+      const b = getOrCreateProvider(ROOM)
+      expect(b).toBe(a)
+      a.destroy()
+      const c = getOrCreateProvider(ROOM)
+      expect(c).not.toBe(a)
+    })
+  })
+
+  describe('场景④ 多 room 并存互不干扰（共享单连接）', () => {
+    const ROOM_A = 'doc:knowledge:room-a'
+    const ROOM_B = 'doc:knowledge:room-b'
+
+    it('两 room 共用一条 WebSocket，各自同步、销毁互不影响', async () => {
+      installFakeServer()
+
+      const handleA = getOrCreateProvider(ROOM_A)
+      const handleA2 = getOrCreateProvider(ROOM_A)
+      expect(handleA2).toBe(handleA) // 同 room 单例
+      const handleB = getOrCreateProvider(ROOM_B)
+
+      // 多路复用：一条共享连接
+      expect(MockWebSocket.instances).toHaveLength(1)
+      const ws = MockWebSocket.instances[0]!
+      ws.serverOpen()
+      await waitFor(
+        () => handleA.getStatus() === 'synced' && handleB.getStatus() === 'synced',
+        '两 room 均 synced',
+      )
+      expect(mockCreateCollabTicketFn).toHaveBeenCalledTimes(2)
+
+      // 各写各的 doc，互不串扰（本地 doc 独立 + 远端按 room 路由）
+      handleA.doc.getText('t').insert(0, 'AAA')
+      handleB.doc.getText('t').insert(0, 'BBB')
+      await flush()
+      expect(handleA.doc.getText('t').toString()).toBe('AAA')
+      expect(handleB.doc.getText('t').toString()).toBe('BBB')
+
+      // 销毁 A：B 不受影响，共享连接存活
+      destroyProvider(ROOM_A)
+      expect(handleB.getStatus()).toBe('synced')
+      expect(MockWebSocket.instances).toHaveLength(1)
+      expect(ws.readyState).toBe(1)
+      handleB.doc.getText('t').insert(0, '!')
+      await flush()
+      expect(handleB.doc.getText('t').toString()).toBe('!BBB')
+
+      // 全部销毁：共享连接关闭（引用计数归零）；重建为新实例
+      destroyProvider(ROOM_B)
+      await flush()
+      expect(ws.readyState).toBe(3)
+      expect(getOrCreateProvider(ROOM_A)).not.toBe(handleA)
+    })
+
+    it('A room 鉴权失败退避不影响 B room（共享连接保持）', async () => {
+      installFakeServer({ denyRooms: [ROOM_A] })
+
+      const handleA = getOrCreateProvider(ROOM_A)
+      const handleB = getOrCreateProvider(ROOM_B)
+      const ws = MockWebSocket.instances[0]!
+      ws.serverOpen()
+      await waitFor(() => handleB.getStatus() === 'synced', 'room B synced')
+      // A 被拒进入退避重试（connecting），B 正常同步
+      expect(handleA.getStatus()).toBe('connecting')
+      // B 持续可用
+      handleB.doc.getText('t').insert(0, 'B-OK')
+      await flush()
+      expect(handleB.doc.getText('t').toString()).toBe('B-OK')
+      // A 的反复失败没有影响共享 socket 与 B
+      await advance(31000)
+      expect(handleA.getStatus()).toBe('offline') // A 达上限停重试
+      expect(handleB.getStatus()).toBe('synced')
+      expect(ws.readyState).toBe(1)
+    })
+  })
+})