Firmiana
  • 简体中文

      • 联邦

      联邦允许主服务器之间相互通信，实现跨服务器的房间参与。

      联邦端点

      所有端点位于 /_matrix/federation/v1/ 下（邀请 v2 除外）。

      端点方法用途
      /send/{txnId}PUT发送事务（PDU + EDU）
      /make_join/{roomId}/{userId}GET准备加入事件
      /send_join/{roomId}/{eventId}PUT提交加入事件
      /make_leave/{roomId}/{userId}GET准备退出事件
      /send_leave/{roomId}/{eventId}PUT提交退出事件
      /invite/{roomId}/{eventId}PUT邀请远程用户（v2）
      /state/{roomId}GET获取房间状态
      /state_ids/{roomId}GET获取状态事件 ID
      /event_auth/{roomId}/{eventId}GET获取事件认证链
      /backfill/{roomId}GET回填事件
      /get_missing_events/{roomId}POST获取缺失事件
      /query/profileGET查询用户资料
      /query/directoryGET查询房间目录
      /query/publicRoomsGET查询公共房间
      /query/user_devicesGET查询用户设备
      /query/keysGET查询用户密钥
      /hierarchy/{roomId}GET获取空间层级
      /relations/{roomId}/{eventId}GET获取事件关系

      请求签名

      每个联邦请求都使用服务器的 ed25519 签名密钥进行签名。

      签名流程

      1. 构建请求体的规范 JSON
      2. 计算 SHA-256 哈希 → base64url（无填充）
      3. 构建签名字符串：origin destination method uri ts content_hash
      4. 使用服务器私钥签名
      5. 附加 Authorization: X-Matrix origin=...,destination=...,key=...,sig=...,ts=...

      验证

      FederationRequestSigningService.verifyRequestSignature() 检查：

      • Authorization 头格式（X-Matrix ...）
      • Origin/destination 匹配
      • 时钟偏差（5 分钟内）
      • 内容哈希完整性
      Note

      针对远程服务器公钥的加密签名验证目前为全接受模式。完整验证需要从 /_matrix/key/v2/server 获取远程签名密钥。

      密钥缓存

      FederationKeyCache 缓存远程服务器签名密钥：

      • TTL：密钥缓存可配置的时长
      • 负缓存：失败的密钥查找短暂缓存，避免频繁请求
      • 公证：通过 /_matrix/key/v2/query 向其他服务器查询目标服务器的密钥

      目标队列

      FederationDestinationQueue 管理出站事务：

      • 指数退避：失败的投递以递增延迟重试
      • 死亡检测：在重复失败后将目标标记为不可达
      • 事务 ID：每个目标单调递增

      EDU 处理

      临时数据单元（EDU）在服务器之间传递实时状态：

      EDU 类型来源用途
      m.typingTypingUserRepository输入通知
      m.presencePresenceRepository在线/离线状态
      m.receiptReceiptRepository已读回执

      服务器发现

      GET /.well-known/matrix/server → { "m.server": "example.com:8448" }
GET /_matrix/key/v2/server → { server_name, verify_keys, valid_until_ts }

      SigningKeyService 管理本地服务器的 ed25519 密钥对，支持自动轮换（7 天周期）。