[ShuweiShen772]

背景

启用 MC_ENABLE_HA_REBUILD=1 后，Mooncake master 故障切换期间会经历选举和元数据重建阶段。此时 Store 查询可能暂时返回 RPC_FAIL、UNAVAILABLE_IN_CURRENT_STATUS 或 REPLICA_IS_NOT_READY。

此前，RealClient::get_buffer_internal() 会将对象不存在和其他读取错误都转换为 nullptr；Python MooncakeDistributedStore.get() 又将 nullptr 转换为空 bytes。调用方因此无法区分“key 确实不存在”和“HA 重建期间 Store 暂时不可用”。

对于可选 KV 缓存，暂时不可用可以由上层作为缓存未命中处理并继续计算；但通用 Store API 不应把暂时错误伪装成 key 不存在。

修改内容

• 新增 get_buffer_with_status()，保留底层读取错误码，区分 OBJECT_NOT_FOUND 与其他错误。
• Python get() 仅在确认 OBJECT_NOT_FOUND 时返回空 bytes；其他 Store 错误抛出 RuntimeError。
• 增加 ha_get_retry_timeout_ms，用于需要等待数据恢复的调用方显式启用有界重试。默认值为 0，即默认不重试，避免缓存请求在 HA 重建期间长时间阻塞。
• 增加错误分类回归测试，并更新 Python API 文档。

测试结果

• mooncake_store 和 Python store 模块编译通过。
• C++ 回归测试 RealClientTest.GetBufferWithStatusDistinguishesUnavailableFromMissing 通过。
• 普通 Store put/get、确实不存在的 key 返回空 bytes 的冒烟测试通过。
• 在修改版 Store 客户端上进行 0.3.12 联测：12 路 Store 客户端和 12 路 Router 流式请求持续并发，期间 SIGKILL master：
  • master 在 17.239 秒后恢复为 serving。
  • gate 关闭期间有 9 次 GET 返回显式暂时错误，不再被伪装成空 bytes；这些错误全部发生在 gate 关闭窗口内，窗口外 GET 错误为 0。
  • 有 1,427 次 put 在 gate 关闭窗口内被拒绝，窗口外 put 失败为 0。
  • 4,874 次成功 put 在 master 恢复后全部读回一致；无内容不匹配、长度错误或读回失败。
  • Router 流式请求 540/540 成功；测试结束时 master 健康且 /v1/models 正常。

兼容性说明

真实不存在的 key 仍返回空 bytes。Store 暂时不可用等其他错误现在会显式抛出 RuntimeError。HA rebuild 客户端默认不等待重试；需要等待真实数据恢复的调用方可显式设置 ha_get_retry_timeout_ms。可选 KV 缓存应由上层将暂时不可用按缓存未命中处理并继续计算。