Firmiana
  • 简体中文

      • 同步

      /sync 端点是客户端接收新事件和维护客户端状态的主要机制。

      GET /sync

      GET /_matrix/client/v3/sync?filter=...&since=...&timeout=30000&full_state=true

      参数

      参数类型说明
      filterJSON过滤器对象（或已保存的过滤器 ID）
      sincestring增量同步的流令牌
      timeoutint长轮询超时时间（毫秒，最大 30 秒）
      full_statebool不论 since 如何，包含所有状态事件

      响应结构

      {
  "next_batch": "s72595_0_0",
  "rooms": {
    "join": {
      "!room:localhost": {
        "timeline": { "events": [...], "limited": false },
        "state": { "events": [...] },
        "ephemeral": { "events": [...] },
        "account_data": { "events": [...] }
      }
    },
    "invite": {},
    "leave": {}
  },
  "presence": { "events": [...] },
  "device_lists": { "changed": [...], "left": [...] },
  "device_one_time_keys_count": { "signed_curve25519": 50 }
}

      流令牌

      流令牌是不透明字符串，编码了事件流中的位置。用于：

      • 增量同步：since 参数从之前的位置恢复
      • 分页：/messages 和 /context 使用 from/to 令牌
      • 间隙检测：timeline.limited = true 表示事件丢失（客户端应重新同步）

      令牌是 (room_id, stream_ordering) 元组的 base64 编码。

      长轮询

      当 timeout > 0 时，服务器会保持连接打开直到：

      • 有新事件到达
      • 超时到期
      • 需要发送心跳

      这减少了客户端轮询频率和延迟。

      过滤器

      过滤器控制 /sync 中出现哪些事件：

      {
  "room": {
    "rooms": ["!room:localhost"],
    "state": { "types": ["m.room.member"] },
    "timeline": { "limit": 50 },
    "ephemeral": { "types": ["m.typing", "m.receipt"] }
  },
  "presence": { "types": ["m.presence"] }
}

      过滤器可以通过 POST /filter 保存并按 ID 引用。

      临时事件

      临时事件不会长期持久化，但会包含在 /sync 中：

      事件说明
      m.typing当前正在输入的用户
      m.receipt已读回执
      m.read_markers已读标记位置
      m.presence用户在线/离线状态

      账户数据

      账户数据事件是用户特定的，包含在每次同步响应中：

      事件说明
      m.push_rules推送通知规则（动态注入）
      m.ignored_user_list忽略的用户（动态注入）
      m.direct私聊房间映射

      设备列表

      当用户加入、退出或被封禁时，设备列表变更通知系统会触发 /sync 响应中的 device_lists.changed / device_lists.left 条目。这允许端到端加密客户端跟踪需要加密的设备。