Merged
fix(registry): preserve atomic state writes on failure #385
fix(registry): preserve atomic state writes on failure #385
Merged
Yiyang ShaoAdd on 18 days ago
Yiyang ShaoCollaborators
18 days ago

Paired: GitHub #189 ↔ GitCode !385

问题与修复

注册中心集群状态通过 atomic_write_json 持久化,但所有写入共用 <目标>.tmp,并发写入会相互覆盖。两次 os.replace 失败后还会直接打开目标文件覆盖,既破坏原子性,也可能在写入中断时损坏旧状态。

  • 使用目标目录中的唯一临时文件,各写入者互不共享临时路径;文件完整写入、flush/fsync 并关闭后再替换目标。
  • PermissionError 时重试一次,持续失败则传播错误,保留原目标;其他存储错误直接传播。
  • 移除直接覆盖回退,失败后尽力清理本次临时文件,清理错误不掩盖原始错误。
  • 删除 register/store.py 的旧 _atomic_write,将 API 配置、服务状态、注册格式、向量配置、授权配置和租约配置六处调用迁移至公共 helper;各路径增加替换失败保留旧文件及传播异常的测试。
  • 在现有集群身份测试中验证保存失败后旧状态仍可加载;新增原子写入测试覆盖并发、临时锁、持续锁、存储/flush/序列化失败及无关 sidecar 文件保留。

验证

在隔离的临时 Python 环境中安装注册中心轻量依赖,从 AgentRegistry 目录执行:

  • python -B -m pytest tests/common tests/cluster tests/register tests/auth -q:266 passed,4 skipped(Windows 无法验证 POSIX 权限位)。
  • 补充 POSIX 权限回归用例:保留已有 0600/0640/0644,新文件明确使用 0644。测试过程有现有 FastAPI/Starlette 弃用提示,退出时出现后台 keepalive 线程关闭日志,pytest 退出码为 0。
  • git diff --cached --check:通过。
  • gitcode precommit check --run --yes:仓库没有 pre-commit 配置。

行为与范围

持续无法替换目标时,现在报告错误而非绕过原子替换。并发完整写入采用最后一次成功替换的结果,不提供读改写事务或跨进程版本排序。POSIX 替换前将已有目标权限复制到临时文件,新文件使用 0644;Windows 保留平台默认临时文件 ACL 行为。已执行文件 fsync,但没有增加父目录 fsync,因此不宣称完整的断电持久性保证。

本 PR 仅处理原子状态写入;Python 缓存清理已由独立 PR !377 完成并合入,不重复包含。

likedislike
Pull Request has been successfully merged by openJiuwen-bot.
(Thank you for Yiyang Shao's contribution.)
atomgit-bot
atomgit-bot
18 days ago Comments:

变更摘要

本 PR 修复注册中心状态持久化的原子性缺陷:atomic_write_json 此前让所有写入者共享 <目标>.tmp,并发写会相互覆盖,且在 os.replace 两次失败后直接打开目标文件覆盖,破坏原子性并可能损坏旧状态。改动后改为在目标目录内使用唯一的临时文件,完整写入并 flush/os.fsync 关闭后才执行替换;替换被拒绝时重试一次后抛出错误,其余存储错误直接传播,失败时尽力清理本次临时文件,旧目标保持不变。

主要改动

  • 唯一临时文件隔离并发写入: atomic_write_json 改用 tempfile.NamedTemporaryFile(dir=path.parent、prefix=f".{path.name}."、suffix=".tmp"、delete=False)生成写入者独享的临时路径,替代固定拼接的 path.with_suffix(...".tmp"),避免并发写入互相覆盖。
  • 写入完成后再替换目标: 新增 f.flush() 与 os.fsync(f.fileno()),确保临时文件内容完整落盘后才调用 os.replace,替换前不再存在半成品目标文件。
  • 移除直接覆盖回退,失败保留原目标: 只有 PermissionError 才 time.sleep(0.05) 后重试一次 os.replace,重试仍失败则向外传播异常;其他 OSError(如 ENOSPC、EIO)不再重试,也不再退化为直接覆盖目标文件。
  • 临时文件清理不掩盖原始错误: 将清理逻辑移入 finally,用 tmp_path.unlink(missing_ok=True) 并捕获 OSError 后忽略,保证原始写入/替换异常不被清理失败覆盖。
  • 补充原子写入与状态保留测试: 新增 AgentRegistry/tests/common/test_atomic.py 覆盖并发写入使用独立完整临时文件、替换权限重试与持续失败、存储/flush/序列化失败、无关 sidecar 文件保留等场景;test_identity.py 新增 test_failed_save_keeps_last_loadable_state,验证 ClusterState.save() 失败后磁盘上旧状态仍可被 ClusterState.load 加载。
likedislike
Incorrect?
atomgit-bot
atomgit-bot
18 days ago Comments:

代码审查

✅ 未发现问题

likedislike
Incorrect?
atomgit-bot
atomgit-bot
18 days ago Comments:

AtomGit AI 助手使用指南

在 PR 评论中使用命令即可触发。支持在普通评论和代码行评论中使用。

功能 命令 说明
代码审查 /ai review 检查代码质量、潜在问题、安全风险
PR 摘要 /ai summary 生成 PR 变更内容的结构化摘要
代码解释 /ai explain 解释代码变更的逻辑和意图
自由提问 @atomgit-bot <问题> 询问关于本 PR 的任何问题
帮助 /ai help 显示此帮助信息

免责声明

AI 助手可能存在误判,请结合自身判断。可以对评论点 👍 或 👎 帮助我们改进。

likedislike
Incorrect?
OopenJiuwen-botCollaborators
18 days ago Added label: sig/sig-agent-protocol
openJiuwen-botCollaborators
18 days ago Comments:

欢迎来到 openJiuwen 社区

Hey @YiyangShao , 感谢你对社区的贡献.

机器人使用手册

有关指令的使用,可以点击 此处 查看详情。开发人员可以在每个PR或Issue下方评论特定指令来触发机器人任务。

联系指引

有疑问可以联系 SIG: sig-agent-protocol ,
维护者是: @YiyangShao, @xinyu-jiuwen ,
审核者是: @gcw_hx9prznZ, @mingo007 .

likedislike
OopenJiuwen-botCollaborators
18 days ago Added label: openJiuwen-cla/yes
Oopenjiuwen-syncCollaborators
18 days ago Modify description of pull request
openJiuwen-botCollaborators
18 days ago Comments:

The pipeline(pipeline number:385) is running. Please wait a moment...

likedislike
OopenJiuwen-botCollaborators
18 days ago Added label: ci-running
OopenJiuwen-botCollaborators
18 days ago Removed label: ci-running
openJiuwen-botCollaborators
18 days ago Comments:
任务名称 结果 日志操作
静态检查 ✅SUCCESS 点此跳转
防投毒检查 ✅SUCCESS 点此跳转
开源合规检查 ✅SUCCESS 点此跳转
禁用词扫描 ✅SUCCESS 点此跳转
likedislike
OopenJiuwen-botCollaborators
18 days ago Added label: ci-successful
maoqiming
maoqimingCollaborators18 days agoStart code review1
AgentRegistry/a2x_registry/common/atomic.py
@@ -42,1 +50,4 @@
4250 tmp_path.unlink(missing_ok=True)
51+ except OSError:
52+ # Cleanup must not hide the original write/replace failure.
53+ pass
maoqiming
maoqiming18 days agoComments:

【review】设计问题。本 PR 修复了公共原子写入实现(唯一临时文件、fsync、失败时保留原文件并向上抛错),但 register 存储模块中保留的一份同逻辑本地 _atomic_write 拷贝并未迁移:临时文件名固定为目标文件名加 .tmp(并发写入会互相覆盖临时文件)、写后没有 fsync、replace 两次失败后还会以写模式直接打开目标文件覆盖(中途失败会留下损坏状态),且整个过程不抛异常。该函数被服务状态、注册配置、向量配置等 6 处持久化调用使用,合并后这些路径仍暴露在旧实现的数据损坏风险中。建议将这些调用点迁移到 atomic_write_json 并删除本地拷贝;若短期不迁移,至少去掉直接覆盖目标文件的兜底逻辑并让失败向上传播。

likedislike
maoqiming
maoqimingCollaborators16 days agoStart code review1
AgentRegistry/a2x_registry/common/atomic.py
@@ -33,3 +34,1 @@
33- except OSError:
34- import time
35- time.sleep(0.05)
34+ with tempfile.NamedTemporaryFile(
maoqiming
maoqiming16 days agoComments:

【review】文件权限。NamedTemporaryFile 在 POSIX 下以 0600 创建临时文件,os.replace 后目标文件权限会从原来的 0644/umask 默认值变为 0600;如果集群中其他进程或用户需要读取该状态文件,升级后可能出现权限拒绝。在替换前读取原目标文件的 mode 并 chmod 到临时文件(新建文件时显式指定期望 mode,例如 0644),并补充文件权限回归测试;如果 0600 是有意收紧,请在文档或变更说明中明确。

likedislike
YYiyang ShaoCollaborators
15 days ago Pushed 1 commits:abf1a546-fix(registry): unify dataset writes and preserve file modes
OopenJiuwen-botCollaborators
15 days ago Added label: stat/needs-squash
OopenJiuwen-botCollaborators
15 days ago Removed label: openJiuwen-cla/yes
OopenJiuwen-botCollaborators
15 days ago Removed label: ci-successful
openJiuwen-botCollaborators
15 days ago Comments:

Notification

This pull request has been changed(code update) or closed, so removes the following label(s): ci-successful.

likedislike
OopenJiuwen-botCollaborators
15 days ago Added label: openJiuwen-cla/yes
openJiuwen-botCollaborators
15 days ago Comments:

CLA 签署成功

YiyangShao, 感谢您的代码贡献。 所有的代码贡献者都已完成了 CLA 签署。 👍

likedislike
openJiuwen-botCollaborators
15 days ago Comments:

The pipeline(pipeline number:385) is running. Please wait a moment...

likedislike
OopenJiuwen-botCollaborators
15 days ago Added label: ci-running
YYiyang ShaoCollaborators
15 days ago Modify description of pull request
OopenJiuwen-botCollaborators
15 days ago Removed label: ci-running
openJiuwen-botCollaborators
15 days ago Comments:
任务名称 结果 日志操作
静态检查 ✅SUCCESS 点此跳转
防投毒检查 ✅SUCCESS 点此跳转
开源合规检查 ✅SUCCESS 点此跳转
禁用词扫描 ✅SUCCESS 点此跳转
A4P Java SDK UT ✅SUCCESS 点此跳转
likedislike
OopenJiuwen-botCollaborators
15 days ago Added label: ci-successful
YYiyang ShaoCollaborators
15 days ago Resolved final issue
maoqiming
maoqimingCollaborators
8 days ago Comments:

/lgtm
/approve

likedislike
OopenJiuwen-botCollaborators
8 days ago Added label: approved, lgtm-mingo007
openJiuwen-botCollaborators
8 days ago Comments:

Review Code Feedback

  • The label lgtm-mingo007, approved was added to this pull request. It means that mingo007 reviewed the code changes. 👋
Tips
  • If this pull request is not merged while all conditions are met, comment /check-pr to try again. 😄
likedislike
OopenJiuwen-botCollaborators
8 days ago Merged pull request
OopenJiuwen-botCollaborators
8 days ago Removed label: ci-successful