@cf-platform/cim

@cf-platform/cim

基于 WebSocket 的 CIM 协议传输层库，负责 Protobuf 编解码和 WebSocket 连接管理。不包含心跳检测、自动重连、认证流程等业务逻辑——这些由上层 @cf-platform/mq 的 CimAdapter 提供。

定位

┌─────────────────────────────────┐
│ @cf-platform/mq  (业务层)        │
│ • 心跳管理 / 重连策略 / 鉴权流程   │
├─────────────────────────────────┤
│ @cf-platform/cim (传输层) ← 本库  │
│ • WebSocket 连接                 │
│ • Protobuf 编解码 (Message/       │
│   ReplyBody/SentBody)            │
│ • PING→PONG 自动响应             │
└─────────────────────────────────┘

特性

• WebSocket 连接 — 纯粹的 WebSocket 生命周期管理
• Protobuf 编解码 — 手写轻量 Protobuf 实现，零外部依赖（无 google-protobuf/Closure Library）
• int64 varint — varint 编解码完整支持 int64（时间戳 / ID 等），不被截断到 32 位
• PING/PONG — 自动响应服务端心跳
• 类型安全 — 完整 TypeScript 类型定义
• 极轻量 — ES 包仅 ~10.5 kB (gzip ~2.9 kB)

安装

npm install @cf-platform/cim

快速开始

import { CIM } from '@cf-platform/cim'

const cim = new CIM({
  url: 'wss://127.0.0.1:8080'
})

// 绑定回调
cim.onOpen = (event) => console.log('WebSocket 已连接')
cim.onMessage = (msg) => console.log('收到消息:', msg)
cim.onReply = (reply) => console.log('收到回复:', reply)
cim.onClose = (event) => console.log('连接关闭:', event.code)
cim.onError = (event) => console.error('连接错误')
cim.onPing = () => console.log('收到服务端心跳')

// 建立连接
cim.connect()

// 发送消息
cim.sendMessage({
  key: 'send_message',
  content: 'Hello World',
  receiver: 'user456'
})

// 关闭连接
cim.close()

提示：大多数场景下你不需要直接使用本库，推荐使用 @cf-platform/mq 的 createCimMq()，它在本库之上提供了心跳检测、自动重连、认证管理等完整功能。

API 文档

CIMOptions

参数	类型	默认值	必填	描述
url	string	-	✓	WebSocket 服务器地址（ws:// 或 wss://）
protocols	string | string[]	-		WebSocket 子协议

CIM 类

构造函数

constructor(options: CIMOptions)

连接管理

方法	返回值	描述
connect()	void	建立 WebSocket 连接
reconnect()	void	重新连接（等价于 close + connect）
close()	void	关闭连接，清理所有事件监听

消息发送

方法	返回值	描述
sendMessage(data)	boolean	编码为 Protobuf 并发送，返回是否成功
sendPong()	void	发送 PONG 心跳响应（通常由内部自动调用）

状态查询

方法	返回值	描述
getConnectionState()	number	WebSocket readyState (0-3)
isConnected()	boolean	readyState === OPEN
isConnecting()	boolean	readyState === CONNECTING
isClosing()	boolean	readyState === CLOSING
isClosed()	boolean	readyState === CLOSED

回调钩子

回调	类型	触发时机
onOpen	(event: Event) => void	WebSocket 连接建立
onClose	(event: CloseEvent) => void	WebSocket 连接关闭
onError	(event: Event) => void	WebSocket 连接错误
onMessage	(msg: ReceivedMessage) => void	收到 Protobuf 解码后的普通消息
onReply	(reply: ReplyMessage) => void	收到 Protobuf 解码后的回复消息
onPing	() => void	收到服务端 PING（上层可用于心跳超时重置）

导出的枚举和常量

MessageType

enum MessageType {
  PONG = 0,       // 客户端发送心跳
  PING = 1,       // 服务端发送心跳
  MESSAGE = 2,    // 服务端发送消息
  SENT_BODY = 3,  // 客户端发送消息
  REPLY_BODY = 4  // 服务端回复消息
}

AuthenticationConstants

const AuthenticationConstants = {
  PONG_BODY:          new Uint8Array([80, 79, 78, 71]),
  CODE_UNAUTHORIZED:  '401',
  CODE_OK:            '200',
  CLIENT_BIND:        'client_bind',
  CLIENT_CLOSED:      'client_closed',
  CLIENT_HANDSHAKE:   'client_handshake',
  FORCE_OFFLINE:      '999'
}

类型定义

// 发送消息结构（protobuf map<string,string>，value 仅支持 string）
interface CIMMessage {
  key: string
  [key: string]: string
}

// 解码后的普通消息
interface ReceivedMessage {
  action?: string
  content?: string
  sender?: string
  receiver?: string
  timestamp?: number
  [key: string]: any
}

// 解码后的回复消息
interface ReplyMessage {
  code: string
  key: string
  message: string
  timestamp: number
  data: Record<string, any>
}

与 @cf-platform/mq 的关系

本库是 CIM 协议的传输层实现。如需完整功能，请使用 @cf-platform/mq：

功能	@cf-platform/cim	@cf-platform/mq (CimAdapter)
WebSocket 连接
Protobuf 编解码
PING→PONG 响应
心跳超时检测
自动重连
CLIENT_BIND 认证
HANDSHAKE 鉴权
强制下线处理
EventManager 事件

更新日志

v2.0.1 (修复)

• 修复 varint 64 位截断 — readVarint/writeVarint 原先用 >>> 0 截断到 uint32，导致 timestamp/id 等 int64 字段在 Date.now() 量级（> 2^32）时丢失高位。现改用「低位按位 + 高位加权」/「取模分段」实现，正确支持到 Number.MAX_SAFE_INTEGER
• 修复 map 反序列化字段顺序依赖 — ReplyBody/SentBody 的 map<string,string> 反序列化原先假定 entry 内 key(字段1) 在 value(字段2) 之前。现用临时变量收集后统一 set，兼容任意字段顺序
• 移除未使用的 _manualClose 内部状态

v2.0.0 (重构)

• Breaking: 移除心跳检测、自动重连、认证流程 — 迁移至 @cf-platform/mq 的 CimAdapter
• Breaking: 移除 CustomEvents、LoginConfiguration、LoginParams 类型
• Breaking: CIMOptions 精简为 url + protocols
• Protobuf 手写 TS 实现，移除 google-protobuf 依赖（SDK 体积从 ~8000 行降至 ~270 行）
• 新增 onPing、onReply 回调钩子
• CIM 退化为纯传输层，职责单一

许可证

ISC