Skip to content

refactor: harden protocol, actors, WAL, and plugins - #1

Merged
FireflyF09 merged 3 commits into
mainfrom
refactor/optimize-code-quality
Oct 4, 2026
Merged

FireflyF09 merged 3 commits into
mainfrom
refactor/optimize-code-quality

Conversation

@ExplodingKonjac

Copy link
Copy Markdown
Contributor

背景

本分支针对服务端代码质量、Actor 并发一致性、WAL 恢复语义、插件运行时安全,以及与官方 phira-mp 客户端的协议兼容性进行了修复和重构。

主要问题包括:房间成员状态同时存在于 Actor 和连接注册表、加入/断开/踢出路径可能留下 Ghost member、WAL 对损坏尾帧过度宽容、插件默认权限过高,以及服务端 Message::Played 扩展字段与官方 v1 客户端协议不一致。

主要改动

协议与传输

  • 恢复官方 v1 Message::Played 的四字段布局,详细判定统计保留在服务端记录和插件事件中。
  • 增加协议版本常量并在创建接收任务前拒绝不支持的版本。
  • 二进制读取器增加长度溢出和 ULEB128 溢出校验。
  • 解码失败现在会让接收任务返回错误,避免继续保留损坏连接。
  • 增加协议 golden 测试和 ULEB 溢出回归测试。

Room Actor 与成员一致性

  • Room Actor 初始化时同步已有玩家和观战者,避免首个快照丢失创建者。
  • AddUser 将连接引用带入 Actor 命令,在同一串行操作中完成连接注册和权威成员提交。
  • 容量检查改为基于 Actor 成员集合,并拒绝重复加入。
  • 断开、管理员踢出、强制转移和正常离开统一经过 Actor 路径。
  • 踢出/移除会清理 Actor 成员、实时数据、展示名和进度订阅。
  • 加入补偿守护持续到 user.room 完成绑定,避免取消时留下 Ghost member。
  • 修复聊天历史容量为 0 时仍保留一条消息的问题。

WAL 与持久化

  • Replay、pending scan 和 compact 只容忍语法不完整的尾部写入。
  • 已能解析但 checksum 错误或版本不支持的尾帧现在 fail-closed,不会被静默删除。
  • 更新 WAL 故障注入和回归测试,覆盖 checksum 损坏、尾部截断、compact 和恢复场景。

插件系统与 ABI

  • 默认插件能力改为最小权限集合;admin、room.manage、HTTP、TCP、文件、加密等权限必须由 sidecar 显式授予。
  • WIT timer API 增加 timer capability 校验。
  • 修复插件执行槽等待逻辑和并发竞争处理。
  • 插件 TCP 清理不再阻塞 Tokio worker,也不会遗留等待回复的阻塞线程。
  • 统一文档、SDK 示例、测试插件和 ABI 说明到 phira-plugin-v3 / abi-wit-v3。

兼容性与风险

  • 默认协议仍是官方 Phira-mp v1;未协商的扩展字段不会再写入官方兼容包。
  • 插件缺少 capability sidecar 时将获得低权限默认集合,已有依赖隐式高权限的插件需要补充 sidecar。
  • WASM API 集成测试仍受仓库现有 cfg(any()) 守卫影响,预编译 fixture 尚未重新生成;ABI 合约和生命周期基础测试仍通过。

验证

  • cargo check --workspace --all-features
  • cargo clippy --workspace --all-features --all-targets -- -D warnings
  • cargo test --workspace --all-features
  • 协议 golden、WAL 故障测试、Room Actor 测试、SSE 测试、WIT ABI capability 合约测试

完整测试套件在首轮实现提交上通过;review 修复后重新运行了编译检查及协议、WAL、房间和能力相关回归测试。

@FireflyF09
FireflyF09 merged commit ee2f7e1 into main Oct 4, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants