mirror of
https://github.com/pgsty/minio.git
synced 2026-10-06 09:45:58 +03:00
docs: archive issue 77 design, adversarial reviews and acceptance evidence
Signed-off-by: Feng Ruohang <rh@vonng.com>
This commit is contained in:
Feng Ruohang
@@ -0,0 +1,20 @@
|
||||
package cmd
|
||||
import (
|
||||
"net/http"
|
||||
"testing"
|
||||
"time"
|
||||
"github.com/minio/minio/internal/auth"
|
||||
)
|
||||
func TestIssue77PlanAdoptionBaseline(t *testing.T) {
|
||||
defer DetectTestLeak(t)()
|
||||
ExecObjectLayerAPITest(ExecObjectLayerAPITestArgs{t:t,objAPITest:func(_ ObjectLayer, instanceType,bucket string,_ http.Handler,_ auth.Credentials,t *testing.T){
|
||||
before,err:=globalBucketMetadataSys.GetConfigFromDisk(t.Context(),bucket);if err!=nil{t.Fatal(err)}
|
||||
if len(before.PolicyConfigJSON)!=0 || !before.PolicyConfigUpdatedAt.Equal(before.Created) {t.Fatalf("unexpected initial state: %#v",before)}
|
||||
olderCreated:=before.Created.Add(-time.Hour)
|
||||
if err:=globalSiteReplicationSys.PeerBucketMakeWithVersioningHandler(t.Context(),bucket,MakeBucketOptions{CreatedAt:olderCreated});err!=nil{t.Fatal(err)}
|
||||
after,err:=globalBucketMetadataSys.GetConfigFromDisk(t.Context(),bucket);if err!=nil{t.Fatal(err)}
|
||||
falseTombstone:=len(after.PolicyConfigJSON)==0 && after.PolicyConfigUpdatedAt.After(after.Created)
|
||||
t.Logf("%s ADOPTION_BASELINE: previous Created=%s field=%s; after Created=%s field=%s; nil with field>Created=%v",instanceType,before.Created.Format(time.RFC3339Nano),before.PolicyConfigUpdatedAt.Format(time.RFC3339Nano),after.Created.Format(time.RFC3339Nano),after.PolicyConfigUpdatedAt.Format(time.RFC3339Nano),falseTombstone)
|
||||
if !falseTombstone {t.Fatal("expected to reproduce default timestamp becoming an apparent tombstone")}
|
||||
}})
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
=== RUN TestIssue77PlanAdoptionBaseline
|
||||
issue77_plan_adoption_test.go:17: ErasureSD ADOPTION_BASELINE: previous Created=2026-09-12T09:49:46.959131+08:00 field=2026-09-12T09:49:46.959131+08:00; after Created=2026-09-12T08:49:46.959131+08:00 field=2026-09-12T09:49:46.959131+08:00; nil with field>Created=true
|
||||
issue77_plan_adoption_test.go:17: Erasure ADOPTION_BASELINE: previous Created=2026-09-12T09:49:47.012956+08:00 field=2026-09-12T09:49:47.012956+08:00; after Created=2026-09-12T08:49:47.012956+08:00 field=2026-09-12T09:49:47.012956+08:00; nil with field>Created=true
|
||||
--- PASS: TestIssue77PlanAdoptionBaseline (0.13s)
|
||||
PASS
|
||||
ok github.com/minio/minio/cmd 1.458s
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"worktree": "$TMPDIR",
|
||||
"source_commit": "5c576581631561c446f30ae5b566f0aa793adc1c",
|
||||
"scope": "diagnostic of existing code only; no product implementation",
|
||||
"command": "GOWORK=off go test ./cmd -run '^TestIssue77PlanAdoptionBaseline$' -count=1 -v",
|
||||
"exit_code": 0,
|
||||
"outcome": "Both ObjectLayers reproduced a nil default state becoming an apparent tombstone after Created moved earlier; no product fix implemented.",
|
||||
"temporary_worktree_removed": true,
|
||||
"archive_note": "Workstation paths normalized; billing data and raw model traces omitted. Original hashes are retained in archive-manifest.json."
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
# 作者补充核验
|
||||
|
||||
S1：`internal/logger/logonce.go:95` 按错误正文而非只按 key 去重。动态时间进入正文会绕过去重。修订要求：稳定的原因错误，动态详情放 logger ReqInfo，沿用现有每小时清理机制；不新增日志/限频框架。
|
||||
|
||||
S2：当前 silo-pkg 的 ActionSet.MarshalJSON 与 ResourceSet.MarshalJSON 直接枚举 map。实测同一个已解析 BucketPolicy 连续 json.Marshal 100 次，得到 4 种字节序列。源代码探针为 policy-encoding-probe.go.txt；使用项目 go.mod 选择的 pgsty/silo-pkg/v3 v3.13.4-0.20260910091716-2d8fd3cbbf07，命令为 GOWORK=off go run <探针临时路径>。
|
||||
|
||||
因此普通 json.Marshal 不能当作稳定排序键。v2 需要一个仅用于 Server 桶策略比较的确定性表示，对已通过现有解析器校验的策略排序集合成员；不能为了这一点修改依赖或持久化 wire 格式。
|
||||
|
||||
以上为作者在外部 v1 评审期间做的独立补查，不冒充 Claude 的评审发现，也不代表已经实现修复。
|
||||
@@ -0,0 +1,32 @@
|
||||
# v1 对抗评审意见与 v2 处置
|
||||
|
||||
评审者：真实 Claude Code 2.1.258，审查消息模型为 `claude-opus-5`，CLI 明确使用 `--effort max`。首轮对 main `5c576581631561c446f30ae5b566f0aa793adc1c` 的冻结 v1 给出 **NO_GO**，耗时约 24 分钟。完整输出见 [首轮评审](opus5-max-v1.md)，调用证据见 [元数据](opus5-max-v1.metadata.json)。
|
||||
|
||||
本文件记录作者核对源码后的处置，不能代替评审者的后续结论。v2 尚未实现。
|
||||
|
||||
| ID | 处置 | v2 中的具体变化与理由 |
|
||||
| --- | --- | --- |
|
||||
| R1 / P1 | 接受 | 选择其方案 b：保留合法零 quota 文档，取消普通 quota PUT 的出站 nil 改写。补充落盘/事件状态三元组一致性。Policy 保留既有 peer 空策略=删除语义，本地/导入/bulk 也归一成删除；说明空策略本地 GET 行为变化。导入空 Policy 用现有专用 nil 事件，避免 bulk omitempty 漏发。 |
|
||||
| R2 / P1 | 接受，缩小实现方式 | 比较有效归一状态，复用已有 Object Lock→Versioning 规则；bulk 按最终接受的 Object Lock 处理 Versioning。saveMetadata 用指针让调用方保留 Save 后快照；公共 Update/Delete 签名保持不变，需要发送归一载荷的本地路径使用内部结果。写明同时间 live 键较大者胜，导入 hook 来自提交快照。 |
|
||||
| R3 / P1 | 接受“不得缺省即删除”的要求；纠正部分依据 | RawMessage 的 nil/空切片确实被 omitempty 省略，但显式 JSON null 解码为非 nil 的字节 `null`；非空 JSON 的空策略也可明确表达。实际 madmin-go/Go 编解码探针已验证。因此不采纳“bulk Policy 不可能表达语义删除、只有 Tags/SSE 可以”的绝对结论。v2 列出真实 wire 判定：未提供保留、Policy 提供但语义空则删除、Quota 提供的零值/null 仍为 live，Tags/SSE 显式空字符串删除；T5 经真实 marshal/unmarshal 验证。 |
|
||||
| R4 / P2 | 接受 | 选源和 apply 都使用 <= Created 的 baseline 判定；候选不晚于目标 Created 时逐目标跳过并限频诊断。独立创建世代冲突需运维，不纳入 T9 自动收敛。 |
|
||||
| R5 / P2 | 接受但保留兼容例外 | 三种内部状态明确化，非零 baseline 事件不覆盖真实配置。零时间专用事件依 O1 保留兼容应用，它是明确例外；修复后的正常发送端不得产生该状态。 |
|
||||
| R6 / P2 | 接受 | 比较视图统一把零字段时间回退到 Created，bulk 原始读取与 load/defaultTimestamps 不再得到不同裁决。 |
|
||||
| R7 / P2 | 接受 | 六类 heal 的源/目标循环跳过 unknown/空 deployment ID；单个 peer 失败继续健康目标，覆盖可达站点不被占位项阻断。 |
|
||||
| R8 / P2 | 接受 | 明确四类清空走现有 parse=false 新对象；bulk 原始读取后保存。不改 Quota getter 或无关解析分支；保留磁盘/缓存/重载回归。 |
|
||||
| R9 / P2 | 接受 | 显式保留 Object Lock 载荷在 legacy Tags 字段时的回退与排序测试。 |
|
||||
| R10 / P2 | 接受 | 升级文档点名旧 Tag heal 无 UpdatedAt，说明其到达时间/legacy-zero 污染不能自动修复。 |
|
||||
| O1 / 缩减 | 接受 | 删除 on 模式拒绝零时间的新行为；两种模式统一兼容。开关改名 METADATA_TOMBSTONES，只控制新增墓碑导出/初次同步。 |
|
||||
| O2 / 缩减 | 接受 | 沿用现有 env.Get 的 on/off 写法，不加配置框架。 |
|
||||
| O3 / 缩减 | 接受 | 旧/新真实进程只作一次性升级冒烟；长期回归用真实 wire/SRInfo 模拟。保留修复版双站点实验以验证实际最终收敛。 |
|
||||
| O4 / 缩减 | 接受 | 明确复用现有 lockBucketMetadataAcquireHook / RMW 屏障，不新增产品测试钩子。 |
|
||||
| O5 / 缩减 | 接受 | 删除无行为意义的 deployment ID 日志裁决要求；它不参与持久化排序。 |
|
||||
| O6 / 缩减 | 部分接受 | 删除不必要的 stale-conflict 警告，剩三类。保留 indeterminate 并明确真实触发条件：未知 Created、不可用来源、有实质差异却无合法候选；它不等于 before-created。 |
|
||||
|
||||
## 作者补充核验
|
||||
|
||||
- **S1：日志去重。** `internal/logger/logonce.go:95-123` 同时依赖稳定 key 和错误正文，变化时间放正文会导致每轮记录。v2 使用固定原因错误，动态详情放 ReqInfo，不新增框架。
|
||||
- **S2：Policy JSON 编码。** 当前 silo-pkg 的 ActionSet/ResourceSet MarshalJSON 枚举 map。同一个已解析策略编码 100 次得到 4 种结果，因此 v1 的普通 JSON 比较键不稳定。v2 增加 Server 内的策略比较键，对已校验策略的集合数组/对象键排序，不改变 wire 或依赖。探针见 [policy-encoding-probe.go.txt](policy-encoding-probe.go.txt)。
|
||||
- **S3：R3 的实际 wire 边界。** 使用项目选定的 madmin-go v3.0.110 与 silo-pkg 执行真实编解码，确认显式 null 与 omitted 不同，带 Version 的空 Statement 策略通过现有解析且 IsEmpty=true。源码和输出见 [wire-state-probe.go.txt](wire-state-probe.go.txt)、[wire-state-probe.log](wire-state-probe.log)。`cmd/bucket-quota.go:99-110` 证实 Quota null 由现有解析器接受为零值对象；不把它改成删除。
|
||||
|
||||
以上均为方案核查和小型诊断。没有修改产品源文件，没有把首轮 NO_GO 改写为通过；后续复审针对冻结 v2 独立给出结论。
|
||||
@@ -0,0 +1,31 @@
|
||||
# v2 对抗复审意见与 v3 处置
|
||||
|
||||
第二轮由相同 Claude Code / `claude-opus-5 --effort max` 执行，仅有 Read/Grep/Glob 工具，耗时约 11 分钟。结论 **NO_GO，1 个新增阻断**；明确确认首轮 R1/R2/R3 已全部关闭，并承认首轮 R3 关于 RawMessage 的部分依据错误。见 [第二轮原文](opus5-max-v2.md)、[调用证据](opus5-max-v2.metadata.json)。
|
||||
|
||||
## P1-1：历史桶字段时间等于 Created
|
||||
|
||||
接受阻断。源码核对确认历史配置可合法带 `UpdatedAt == Created`，MakeBucketHook 还会把同一 Created 传给新站点。v2 把等号也拒绝，会阻断初次同步，并因 heal 过滤 baseline 而无法补救。
|
||||
|
||||
对评审中的小处事实作校正：当前 `applyLegacyConfigs` 末尾已经调用 `defaultTimestamps()`，因此“迁移后磁盘字段仍为零”不普遍成立；**字段等于 Created 的反例成立，不影响阻断判断**。
|
||||
|
||||
v3 的最小修订是保留 baseline 的弱初值语义，不引入新 wire 字段或重盖到达时间：
|
||||
|
||||
| 输入/目标 | v3 行为 |
|
||||
| --- | --- |
|
||||
| 历史 live@Created → 空 baseline | 接受初始化，保存相同源时间；初次同步和 heal 一致 |
|
||||
| baseline-live → baseline-live | 稳定比较键较大者胜；全 baseline-live 也能收敛 |
|
||||
| baseline-live → 真实 live/tombstone | 不覆盖；真实状态优先级先于时间比较 |
|
||||
| 空/nil@Created → 任意已有配置 | 不能作为删除，不清空 |
|
||||
| 非零时间严格早于目标 Created | 原有创建保护，成功/no-op 与有界诊断 |
|
||||
| 全为空 baseline | found=false，安静不写入 |
|
||||
|
||||
T7/T8 新增上述用例，特别是历史桶从初次同步到完整一轮 heal 的验收；六类类型约束、删除 parse=false、旧事件不能复活 tombstone 均保留。
|
||||
|
||||
## 四条 P2
|
||||
|
||||
1. **Policy 稳定键：接受目标，不叠加第二种判等。** v3 明确对已解析策略完整 JSON 树做递归排序，覆盖 NotAction/NotResource 与 Condition，保留数字精度，并由两站点独立解析验证同键。未采纳 Equals 优先再用另一种键的建议：当前 `BucketPolicy.Equals` 对 Statement 次序敏感，而 `BPStatement.Equals` 忽略 Sid，两套判等混用可能使同时间冲突的比较不一致。公开统计现用 Equals 不变。当前 BPStatement 不支持 NotPrincipal，不为此新增语法或改 silo-pkg。
|
||||
2. **off 并非禁止删除：接受。** 直写 Policy 原有墓碑在 off 仍参与 heal；普通删除事件一直复制；只有新增 Tags/SSE/Quota 墓碑导出与初次发送受开关控制。
|
||||
3. **off 期间过时 RPC：接受。** 隐藏墓碑使部分旧 RPC 仍被尝试、在接收端被排序拒绝；这是升级阶段明确代价，不要求零 RPC，不加每轮日志。稳定无额外 RPC 的验收要求明确放在完整状态可见之后。
|
||||
4. **空策略 API 行为：接受。** T1 明确带合法 Version 的空策略 PUT 成功，随后 GET NotFound，落盘与专用删除事件三元组一致；不能误改为 4xx。
|
||||
|
||||
三个实现提交没有增加，也没有新增协议、框架、依赖或长期集成门槛。v3 只需对本次 baseline 规则与以上说明做最后针对性复审；已关闭的首轮问题不重开全仓库审查。当前仍是设计文件，没有实现或执行实现期测试。
|
||||
@@ -0,0 +1,19 @@
|
||||
# v3 通过后的作者实测与 v4 最小补充
|
||||
|
||||
Opus 第三轮已经给出 **GO_WITH_NONBLOCKING_NOTES，实施前阻断 0**，确认历史 baseline-live 初始化规则正确。见 [第三轮意见](opus5-max-v3.md)。其两条可执行非阻断说明（历史初值第二轮不再广播、deployment ID 不参与比较/持久化）已明确写入 v4。
|
||||
|
||||
## S4：接管改变 Created 会把默认时间变成假墓碑
|
||||
|
||||
这是作者补查发现，不冒称为 Opus 结论。
|
||||
|
||||
当前 `PeerBucketMakeWithVersioningHandler`（`cmd/site-replication.go:946-961`）先加载并补齐默认字段时间，再调用 SetCreatedAt 改写 Created。若桶被接管到较早的共同 Created，原本 `PolicyUpdatedAt == oldCreated` 且 policy=nil 的缺省状态，变成 `PolicyUpdatedAt > newCreated`，新排序/导出规则便会把它当成真实删除。
|
||||
|
||||
已在固定 main 上的独立 worktree 执行 `GOWORK=off go test ./cmd -run '^TestIssue77PlanAdoptionBaseline$' -count=1 -v`：ErasureSD 与 Erasure（默认多盘）都复现了该条件。Created 前移一小时，nil Policy 的字段时间留在原 Created。测试 PASS 的含义是**旧代码确实出现该现象**，不是修复通过；详见 [测试源码](adoption-baseline-probe.go.txt)、[实际输出](adoption-baseline-probe.log)、[元数据](adoption-baseline-probe.metadata.json)。测试只新增在临时 worktree，没有改产品代码。
|
||||
|
||||
## 最小修订
|
||||
|
||||
在现有接管锁内记住 oldCreated，执行现有 SetCreatedAt 得到 newCreated；仅当 Created 改变时，将本轮六类字段中原本为 0 或 oldCreated 的默认时间调整为 newCreated，再执行既有 bootstrap。所有真实字段时间（原本 > oldCreated）及载荷不动。绝不能仅以 nil 载荷识别默认状态，否则会丢失真正删除时间。
|
||||
|
||||
这不是另做 #78 的配置接管修复，而是让 #77 新比较器需要的 baseline 不变量跨越已有 SetCreatedAt 写入路径仍成立。只在提交 1 加小分支，T8 增加默认时间维持 baseline、真实 PUT/DELETE 时间保留的断言；没有增加实现提交、存储字段、协议、锁或依赖。
|
||||
|
||||
v4 其余行为与已通过的 v3 相同；第四轮只核查这个接管增量。
|
||||
@@ -0,0 +1,32 @@
|
||||
# Issue #77 最终方案评审记录
|
||||
|
||||
2026-09-12，最终计划为 [issue-77-plan.md](../../issue-77-plan.md)。固定代码基准为 main `5c576581631561c446f30ae5b566f0aa793adc1c`；当日重新查询 #77 仍为 OPEN。
|
||||
|
||||
**结论：GO_WITH_NONBLOCKING_NOTES，实施前阻断 0。** 作者已把末轮非阻断说明落实到定稿，可进入实现；本轮没有修改产品代码、提交 PR、关闭 Issue 或发布制品。
|
||||
|
||||
## 实际执行的外部评审
|
||||
|
||||
使用本机 Claude Code 2.1.258，每轮均明确传入 `--model claude-opus-5 --effort max`，在固定 main 的隔离 worktree 中执行，仅提供 Read/Grep/Glob。所有记录到的评审 assistant 消息模型均为 `claude-opus-5`。CLI 的用量信息另含少量辅助模型调用，已如实保留在 metadata；这不是用其它模型代替 Opus 评审。
|
||||
|
||||
| 轮次 | 待审快照 | 结果 | 处置 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1，全面方案审查 | [v1](plan-v1.md) | [NO_GO，3 个 P1](opus5-max-v1.md) | 修正零 quota 保存/发送不一致、Object Lock 归一后的提交快照、bulk wire 删除规则；缩减开关及验收范围 |
|
||||
| 2，修订复审 | [v2](plan-v2.md) | [NO_GO，新增 1 个 P1](opus5-max-v2.md) | 首轮 3 项确认关闭；修正历史 live@Created 的初始化回归 |
|
||||
| 3，历史初值增量 | [v3](plan-v3.md) | [GO_WITH_NONBLOCKING_NOTES，0 阻断](opus5-max-v3.md) | baseline-live 可初始化、不能覆盖真实状态；默认空值不能删除 |
|
||||
| 4，接管增量 | [v4](plan-v4.md) | [GO_WITH_NONBLOCKING_NOTES，0 阻断](opus5-max-v4.md) | 作者实测假墓碑后新增最小时间归一分支，经 Opus 确认必要性与充分性 |
|
||||
|
||||
逐项记录：[首轮处置](decisions-v2.md)、[第二轮处置](decisions-v3.md)、[接管增量](decisions-v4.md)。每轮相邻的 `opus5-max-vN.metadata.json` 保存命令、模型、工具、耗时、源 SHA、待审计划哈希及结果哈希。
|
||||
|
||||
## 末轮非阻断说明的落实
|
||||
|
||||
- T8 已明确 Created 前移、后移与不变三种情况；历史 baseline-live 第一轮补齐，第二轮无额外写入/广播。
|
||||
- 保持只调整 #77 六类字段，在实现注释中说明边界。不采纳扩大到其它配置时间的可选建议：那些时间不是新比较器的输入，没有必要同批改变其行为。
|
||||
- Policy 稳定键与公开计数的判等职责明确；Sid 差异可以触发一次状态同步，但不重做 #91 的既有统计语义。递归规范化和数字精度由 T2 验证。
|
||||
|
||||
定稿相对于第四轮冻结快照只补充上述验收/注释说明和评审状态，没有新增实现范围。
|
||||
|
||||
## 证据边界
|
||||
|
||||
作者实测使用了实际 Go 编解码、当前 silo-pkg 的 Policy 编码，以及 ErasureSD/默认多盘 ObjectLayer 的接管路径。接管诊断 PASS 表示在未修复 main 上成功观察到假墓碑条件。既有问题复现记录见 [当前核验](../../issue-77-current.md)。
|
||||
|
||||
外部 reviewer 做的是源代码与方案核查，没有运行新实现测试；现在不存在本轮产品实现。局部回归、race、完整 CI、修复版双站点收敛、一次性升级冒烟均是后续实现阶段的验收，不得把本次评审结论当成这些验证已经通过。
|
||||
@@ -0,0 +1,124 @@
|
||||
Write 工具在本会话被禁用，无法落盘评审文件，因此评审报告直接输出如下。
|
||||
|
||||
# SILO #77 修复计划 v1 对抗评审
|
||||
|
||||
基准：worktree = main `5c576581631561c446f30ae5b566f0aa793adc1c`。本次只做方案评审：未改产品代码、未运行测试、未写 GitHub、未调用其他代理。
|
||||
|
||||
**证据分级**：**[源码]** 本次在该 SHA 直接确认（给文件:行）／**[复现]** `issue-77/current-tests.log` 已记录／**[推论]** 由源码事实推导、未执行／**[待验]** 需实现期测试。
|
||||
|
||||
---
|
||||
|
||||
## 结论：NO_GO
|
||||
|
||||
方向正确，但 §3 / §5 / §6 三处**契约文字**按字面实现会产生新的不收敛与潜在错删。计划约 85% 的内容经源码核对成立，不需要推翻结构——**修订 R1、R2、R3 后复审即可进入实现**。
|
||||
|
||||
---
|
||||
|
||||
## P1 阻断项
|
||||
|
||||
### R1 零配额在发送端被改写成删除，本地却保留 live 文档 → off（默认）永不收敛，on 主动删除本地合法文档
|
||||
|
||||
**源码位置**
|
||||
- `cmd/admin-bucket-handlers.go:85` 本地写入用的是**原始请求体** `data`；
|
||||
- `cmd/admin-bucket-handlers.go:97-99` `if quotaConfig.Size == 0 && quotaConfig.Quota == 0 { bucketMeta.Quota = nil }` —— 发出的事件被改写成**删除**；
|
||||
- `cmd/site-replication.go:2088-2107` 对端 `quota == nil` 走 `Delete`；
|
||||
- `madmin-go v3.0.110 quota-commands.go:54-60` `Quota == 0` 时 `IsValid()` 恒真（`{}` 是合法 live 文档），且该版本**只有 `SetBucketQuota`，没有删除端点** —— "清除配额"只能走这条零值 PUT；
|
||||
- `cmd/site-replication.go:4090-4094` 导出端仅在 `len(QuotaConfigJSON) > 0` 时带出时间，删除时间被隐藏。**[源码]**
|
||||
|
||||
**计划条目**：已确定契约"合法的空 quota 对象 `{}`…不能仅因配额为零就改写为 nil"；§3"同时间真实删除大于 live"；提交 3 tombstone 导出；完成条件"四类 DELETE"、T7。
|
||||
|
||||
**触发步骤**
|
||||
1. A 站点执行等价于 `mc quota clear`（零值 SetBucketQuota）。
|
||||
2. A 落盘 live `{...}`@T；发出的事件是 `Quota=nil`@T。
|
||||
3. B 按计划落盘 tombstone@T。
|
||||
4. **off（默认）**：B 的 tombstone 时间不导出 → B 候选被当 baseline 过滤 → 选源永远是 A 的 live@T → 推给 B → B 按"同时间删除优先"拒绝 → **每 30 秒（`site-replication.go:4651`）一次 RPC + 一次拒绝日志，永不收敛**。
|
||||
5. **on**：B 导出 tombstone@T → 同时间删除胜 → heal 反过来**删除 A 上合法的 live 文档**。
|
||||
|
||||
**影响**：这是清除配额的常规路径。主干今天同样不收敛（到达时间更大导致拒绝），所以**不是回归，但计划声称会修而按 v1 修不了**，T1/T7 不可达成。**[源码]+[推论]**
|
||||
|
||||
**同类第二处**：`cmd/bucket-policy-handlers.go:87-109` 本地存 live 的"语义为空"策略，`cmd/admin-handlers-site-replication.go:233-237` 在接收端判为删除。Policy 仍能收敛，只因 `site-replication.go:4069-4070` **无条件**导出 `PolicyUpdatedAt`。可见根因是"发送端语义 ≠ 本地落盘语义"，不是导出策略。
|
||||
|
||||
**最小修正（二选一，必须成对，不能只改一侧）**
|
||||
- (a) 解析后 quota 为零值结构时本地也走 `Delete`（parse=false），事件仍为 nil；或
|
||||
- (b) 取消 `Quota = nil` 改写，事件携带真实文档。
|
||||
|
||||
并把"同一次本地操作，落盘状态与发出事件状态必须是同一状态"写成契约不变量；T1 增加三元组 (kind, payload, time) 一致性断言。
|
||||
|
||||
---
|
||||
|
||||
### R2 `saveMetadata` 内部静默归一化：落盘载荷 ≠ 比较载荷 ≠ 事件载荷；§6"无状态变化不保存"按字面不可实现；§3 未定义字节序方向
|
||||
|
||||
**源码位置**
|
||||
- `cmd/bucket-metadata.go:391-399` `parseAllConfigs` 在 `objectLockConfig != nil` 且 versioning 文档解析失败 / `!Enabled()` / `PrefixesExcluded()` 时改写 `VersioningConfigXML` 为常量，**不改 `VersioningConfigUpdatedAt`**；
|
||||
- `cmd/bucket-metadata.go:581-603` `Save` 每次保存前都调 `parseAllConfigs` → 归一化发生在**每一次** `saveMetadata`；
|
||||
- `cmd/bucket-metadata-sys.go:232-243` `saveMetadata(…, meta BucketMetadata)` **按值接收**，归一化只作用于被落盘/入缓存的副本，调用方手里的结构仍未归一化；
|
||||
- `cmd/admin-bucket-handlers.go:1094-1116` 导入把未归一化的 `merged` 赋回 `*meta`，随后 `hook.Versioning = enc(meta.VersioningConfigXML)` —— **发出的载荷与落盘载荷不同，时间戳却相同**；
|
||||
- `cmd/admin-bucket-handlers.go:823-835` 导入只拒绝 `Suspended`，**不拒绝 `PrefixesExcluded()`**（`internal/bucket/versioning/versioning.go:153-155`：`ExcludedPrefixes` 或 `ExcludeFolders` 均算）；
|
||||
- `cmd/bucket-versioning-handler.go:68-84` S3 PUT 只在**本地** LockEnabled 时拒绝 prefix-excluded；
|
||||
- 现有回归 `cmd/site-replication-object-lock_test.go:149-167` 已把该机制固化为断言。**[源码][复现-通过]**
|
||||
|
||||
**计划条目**：§3"live/live 按稳定载荷字节序比较""apply 和 heal 使用同一比较函数"；§6"无状态变化时不保存、不通知"；提交 1 完成条件"导入的持久化时间与实际发出的事件一致"。
|
||||
|
||||
**为什么阻断**
|
||||
1. §6 只能在 `saveMetadata` 之前比较，而真正落盘的是归一化之后的结构——**规则按字面无法实现**，"无变化"的判定可能与磁盘不符。
|
||||
2. 计划把到达时间换成源时间后，**同一时间戳 + 不同载荷成为正常可达状态**（Object Lock 在站点间短暂不对称时必然出现）；旧代码靠"到达时间总在前进"意外掩盖了它。
|
||||
3. §3 **没写明大者胜还是小者胜**。以 `…<Status>Enabled</Status><ExcludedPrefixes>` 对 `…<Status>Enabled</Status></VersioningConfiguration>` 为例，分歧字节是 `E`(0x45) 与 `/`(0x2F)：方向选错，heal 每轮把未归一化文档推给已归一化站点，对方再归一化 → 重复写 + 全节点 `LoadBucketMetadata` 广播；方向选对则一轮收敛。**让正确性取决于未写明的字节序方向不可接受。**
|
||||
4. 导入路径违反提交 1 完成条件的实质：时间一致、状态不一致。
|
||||
|
||||
**诚实边界**：我**没有**证明这会无限发散。Object Lock 不可删除，`healOLockConfigMetadata`（`5379-5447`）通常 1 轮内补齐，之后两侧归一化结果相同并收敛。实际损害是"窗口期重复写/广播 + 实现定义的裁决"。**[源码]+[推论]，永久性未证实。**
|
||||
|
||||
**最小修正**：比较器对 Versioning 先做与 `parseAllConfigs` 相同的归一化再比较；`saveMetadata` 回写/返回已持久化结构，导入与所有 hook 用**落盘后的字节**；§6 改为"以归一化后的落盘表示判定状态变化"；§3 写明字节序方向并注明它只用于真并发冲突，不得用来消化序列化差异。
|
||||
|
||||
---
|
||||
|
||||
### R3 §5 的"bulk 中显式提供且为空 = 删除"对 Policy/Quota 在线路上不可表达；按字面实现存在"缺省即删除"的错删路径
|
||||
|
||||
**源码位置**
|
||||
- `madmin-go v3.0.110 cluster-commands.go:501-530`：`Policy`/`Quota` 是 `json.RawMessage` + `omitempty` —— **nil 与空切片都会被省略**，解码端永远拿到 nil；而 `Tags/SSEConfig/Versioning/ObjectLockConfig` 是 `*string`，`ptr("")` 可表达"提供且为空"；
|
||||
- `cmd/site-replication.go:1653-1697` bulk 一律按 `!= nil` 判"是否提供"；
|
||||
- `cmd/admin-bucket-handlers.go:1103-1131` 导入发出的正是 `Type` 为空的 bulk 事件，且只填本次导入涉及的字段。**[源码]**
|
||||
|
||||
**风险**：对 Policy/Quota，这条规则要么是走不到的死代码，要么诱导实现者写 `len(item.Policy) == 0 ⇒ 删除` —— 那样**每个只导入 tags 的 bulk 事件都会删掉对端 bucket policy**，正是 #77 要消灭的错删类。这是规范缺陷，不是当前代码缺陷。**[源码]+[推论]**
|
||||
|
||||
**最小修正**：§5 改为——bulk 只有 Tags/SSE 能表达删除（显式空 base64 串）；Policy/Quota 删除只走专用事件；bulk 缺省字段任何情况下不改变该字段。T5 补两条断言。
|
||||
|
||||
---
|
||||
|
||||
## P2（建议同批修订）
|
||||
|
||||
- **R4 before-created 扩大到六类，但选源端不做同一判定。** `site-replication.go:1646-1651`（bulk 已有）、`2035-2040`（CORS 先例）、`bucket-metadata.go:190-197`（`SetCreatedAt` 无条件覆盖）、`site-replication.go:5486-5512`（`healBucket` 不修复两站点 Created 分歧）。§提交 2 只过滤 `==0` 与 `==CreatedAt`，**不过滤"早于自身 Created"**：分区期间两站点各自建过同名桶后，较老站点的真实配置被永久拒绝，heal 每轮仍选中它并挡住其它候选（今天会收敛）。**最小修正**：选源与 apply 用同一可用性判定（`time <= 自身 CreatedAt` 视为 baseline）；对 `目标 CreatedAt > 候选时间` 按目标跳过并记一次 `before-created`；计划中明确这是**终态不收敛、需运维介入**，不计入 T9。
|
||||
- **R5 比较器缺第三种 kind（baseline）。** `site-replication.go:1851-1898` 的 `corsReplicationState` 已有三值模型。§3 只定义"删除 vs live"，把"创建默认/未知"放在选源侧 → 任何异常发送端发出的 `nil + 创建默认时间` 在 apply 侧会被当 tombstone，同时间即可删掉对端 live。**最小修正**：六类复用 CORS 三值模型（baseline = 时间为零或不晚于 Created），apply 对 baseline 一律 no-op；顺带获得 `latestCORSConfig`（`5315-5329`）的稳定选择语义。
|
||||
- **R6 两个入口读到的"当前字段时间"来源不同。** `site-replication.go:1641` 用 `readBucketMetadata`（**不调** `defaultTimestamps`），`bucket-metadata.go:230-238` 才补默认值 → 同一记录在两条路径上分别是 `0` 与 `Created`，事件时间恰等于 `Created` 时裁决不同。**最小修正**：比较器统一 `if fieldTime.IsZero() { fieldTime = meta.Created }`。
|
||||
- **R7 heal 中不可达站点占位项会中途终止本轮修复。** `3136-3142` 把不可达站点填 `SRInfo{}`，`3219` 以空 DeploymentID 进入 `BucketStats`；`5006-5009`、`5070-5073`、`5145-5148` 等处 `getAdminClient("")` 失败即 `return`，**放弃该类型剩余站点**，且是否提前退出取决于 map 顺序。与 T9 承诺冲突。**最小修正**：两处循环都跳过 `info.Sites` 中不存在的 dID 并计入 `indeterminate`。
|
||||
- **R8 parse=true 置空字段留下已解析缓存。** `bucket-metadata.go:401-413`（versioning、quota）与 `334-338`（notification）在载荷为空时**无 else 分支**（即 [复现] `QUOTA_CACHE`）。§6 的"删除走 parse=false"规避有效且最小，但应写成显式不变量并在 T7 加断言。**不建议**本轮补 else —— 会改变 `GetQuotaConfig` 返回语义（`bucket-metadata-sys.go:572-581` 不做 nil 判断），超出范围。
|
||||
- **R9 Object Lock 的 legacy `Tags` 载荷回退必须保留。** `site-replication.go:1787-1796` + 回归 `site-replication-object-lock_test.go:132-138`。提交 1 的重构容易丢掉；T3 应显式覆盖"Type=ObjectLockConfig、载荷在 Tags 字段"的排序行为。
|
||||
- **R10 off 模式下 legacy-zero 事件盖上本地新时间后永久胜出。** `site-replication.go:5011-5015` 至今不带 `UpdatedAt`（[复现] `TAG_WIRE_TIME`）。计划已有"升级后由操作者重新提交"的兜底，建议在文档条目里点名这个具体来源。
|
||||
|
||||
---
|
||||
|
||||
## 过度设计 / 可缩减
|
||||
|
||||
- **O1 开关承担三件事，只有一件有证据。** 证据（quota 缓存复现）只支持"tombstone 导出需等全站点升级"。"on 模式拒绝零源时间事件"没有对应缺陷，且计划已修复树内唯一的零时间发送端；保留它只会在误开时让 heal 每 30 秒报错。**建议把开关收缩为单一含义**：是否导出/发送真实删除状态（含初次同步）；零时间事件两种模式统一按 legacy-zero 兼容应用 + 限频记录。
|
||||
- **O2 开关实现不需要新框架。** `cmd/common-main.go:902` 已有 `env.Get(name, config.EnableOff) == config.EnableOn` 的两行先例，照抄即可。
|
||||
- **O3 T8 的"固定旧版与修复版两个 SILO 进程"不必作为提交门槛。** 旧版对线路的可观测差异只有两点（heal 事件不带 `UpdatedAt`；导出不含 nil 载荷时间），进程内构造 `SRInfo`/`SRBucketMeta` 即可完整覆盖；降级为一次性人工冒烟。
|
||||
- **O4 T4 不需要新建"确定性锁屏障"。** 已有 `lockBucketMetadataAcquireHook`（`bucket-metadata-sys.go:249-255`）与 `bucket-metadata-lock_test.go` 的 `runBucketMetadataRMWConflict` 模式可直接复用。
|
||||
- **O5 §3 的 deployment ID 规则可删。** "仅在状态完全相同时用于日志来源"无可观测行为；复用 `latestCORSConfig`（`5322` 的 `cmp == 0 && dID > latestID`）即自动获得稳定性。
|
||||
- **O6 `indeterminate` 缺少明确产生条件。** 若采纳 R4，`before-created` 与 `indeterminate` 会合并，应减为三类，不要为对称保留空类别。
|
||||
|
||||
---
|
||||
|
||||
## 经核对成立、不应削减
|
||||
|
||||
锁外 getter→Update 竞态（[复现] `TestIssue77CurrentPeerCheckBeforeLock` 失败）；bulk 绕过逐字段排序（`1653-1697` 无字段时间比较，[复现] 失败）；选源前过滤创建默认值（[复现] 5/32、2/32 错删 Policy；六处重复写法 `4966-4982`、`5038-5054`、`5104-5120`、`5178-5194`、`5253-5269`、`5393-5409` 抽函数是净减法）；Tag 远端 heal 缺 `UpdatedAt`（`5011-5015`）；同内容不同时间不同步（[复现] `BARRIER_NOT_HEALED`）；复用 `metadata.lock` 与 `saveMetadata` 的物理桶检查（`232-243`）、放弃 `peer-require-existing`；导入 `updatedAt := UTCNow()`（`723`）在 ZIP 开始时取一次且可能早于随后创建的桶 `Created`，per-bucket `commitAt` 修正必要。另：`lockBucketMetadataWithTimeout` 不可重入，重入会挂到 `globalOperationTimeout`（非永久死锁但同样不可接受），"不循环调用公开 handler"正确；实现内部 apply 时须沿用 `updateAndParse` 传递 lock-ctx，否则 `loadBucketMetadataParse` 的迁移分支（`bucket-metadata.go:252`、`282`）会再次取锁。
|
||||
|
||||
---
|
||||
|
||||
## 实施前必须修订的条目
|
||||
|
||||
1. **R1** 零值配额的发送端/本地写一致性 + "落盘状态 == 发出状态"不变量。
|
||||
2. **R2** §6 比较基准改为归一化后的落盘表示；`saveMetadata` 回写已持久化结构；导入 hook 用落盘字节；§3 写明同时间载荷序方向及适用边界。
|
||||
3. **R3** §5 重写 bulk 删除语义（仅 Tags/SSE 可表达；缺省永不改变字段）+ 对应断言。
|
||||
|
||||
建议一并吸收 R4、R5 措辞修正与 O1、O3、O4 缩减，再做一次短复审即可进入实现。
|
||||
|
||||
**实现阶段需要运行（本次未运行）**：把两份审计用例改为确定性回归并先记录未修复失败；R1 零配额两侧三元组一致 + off/on 各一轮 heal 无重复 RPC；R2 Object Lock 桶 + prefix-excluded/ExcludeFolders versioning 走导入与 peer 两条路径，断言"发出载荷 == 落盘载荷"且第二轮 heal 无写入；R3 bulk 缺省/空串两类断言；既有回归 `TestPeerBucketObjectLockMetadata*`、`TestPeerBucketAdoption*`、`TestQueuedMetadataUpdateAfterDelete`、`TestSiteReplicationStatusAccountsPerSiteAndSurvivesMalformedConfig`、CORS 站点复制用例，加目标 race 与完整 Go CI。
|
||||
@@ -0,0 +1,46 @@
|
||||
{
|
||||
"reviewer": "Claude Code",
|
||||
"cli_version": "2.1.258",
|
||||
"requested_model": "claude-opus-5",
|
||||
"requested_effort": "max",
|
||||
"source_commit": "5c576581631561c446f30ae5b566f0aa793adc1c",
|
||||
"permission_mode": "plan",
|
||||
"tools": [
|
||||
"Read",
|
||||
"Grep",
|
||||
"Glob"
|
||||
],
|
||||
"round": 1,
|
||||
"plan_snapshot": "plan-v1.md",
|
||||
"command": "claude --print --model claude-opus-5 --effort max --safe-mode --permission-mode plan --tools Read,Grep,Glob --strict-mcp-config --no-session-persistence --output-format stream-json --verbose",
|
||||
"status": "completed",
|
||||
"model_configuration_reference": "https://code.claude.com/docs/en/model-config",
|
||||
"observed_model": "claude-opus-5",
|
||||
"session_id": "9fb76061-6bcc-490c-a96b-9a1d4f9daa84",
|
||||
"observed_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"verdict": "NO_GO",
|
||||
"subtype": "success",
|
||||
"is_error": false,
|
||||
"duration_ms": 1437147,
|
||||
"num_turns": 57,
|
||||
"assistant_models": [
|
||||
"claude-opus-5"
|
||||
],
|
||||
"plan_sha256": "0218a2ca59750acd6a24dc5ece1d55a19762a863f1a2de8edc6ffc9b4ab072e0",
|
||||
"auxiliary_model_note": "CLI may report small auxiliary model calls in model_usage; assistant_models lists the actual recorded review message models. max was explicitly supplied in the CLI command.",
|
||||
"collected_at_utc": "2026-09-12T01:57:46.010985+00:00",
|
||||
"stream_sha256": "a145cd75ebf2ab3b722c7e1764036fcac8e3245ed2de3c2390dc0b5826e63d16",
|
||||
"review_sha256": "8a3b750a261ef520acbe658395d3303cea0835b07184b96022781a2a5d0d4dcf",
|
||||
"used_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read",
|
||||
"Write"
|
||||
],
|
||||
"temporary_review_worktree_removed": true,
|
||||
"archive_note": "Workstation paths normalized; billing data and raw model traces omitted. Original hashes are retained in archive-manifest.json."
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
# SILO #77 修复计划 v2 对抗复审（Claude Code Opus 5，只读）
|
||||
|
||||
基准 worktree = main `5c576581631561c446f30ae5b566f0aa793adc1c`。本轮只针对 v1→v2 的修订差异做源码核验：未改产品代码、未运行测试、未调用其他代理。
|
||||
|
||||
## 首轮三个阻断的关闭判断
|
||||
|
||||
**R1（零配额发送端改写 / 落盘≠出站）：已关闭。** v2 取消 `admin-bucket-handlers.go:97-99` 的 `Quota=nil` 改写后，`mc quota clear` 两侧都落 live 零值文档：`bucket-quota.go:99-110` 对 `{}`/`null` 均解析为零值且 `IsValid()` 为真，`isBktQuotaCfgReplicated`（`site-replication.go:3850-3888`）此时 `numquotaCfgs==total`、Type 相同 → 判为已复制，`quotaCfgSet`（`3635`）仍为 false，#91 计数不受影响。接收端 `PeerBucketQuotaConfigHandler:2089` 会重新 `json.Marshal` 导致字节不同，但 v2 §2 规定 Quota 比较键取"解析结果的 JSON 编码"，`madmin.BucketQuota` 是定长结构体、编码确定，不会因此空转。Policy 侧改成本地/导入/bulk 统一按 `IsEmpty()` 删除，与既有 `admin-handlers-site-replication.go:233-237` 一致，三元组不变量成立。
|
||||
|
||||
**R2（saveMetadata 静默归一 / §6 不可实现 / 字节序方向未定）：已关闭。** `saveMetadata`（`bucket-metadata-sys.go:232`）全部 6 个调用点（`site-replication.go:961/1708/2049`、`bucket-metadata-sys.go:203/222/354`、`admin-bucket-handlers.go:1095`）传入的都是调用方自有值，改指针回写无别名风险；导入 hook 改用提交快照后，`1110-1127` 与落盘文档不再分叉；比较改用 `parseAllConfigs:391-399` 同一条 Object Lock→Enabled 归一规则，方向也已写明"键较大者胜"且禁止用字节序补偿隐式改写。
|
||||
|
||||
**R3（bulk 删除语义）：已关闭，且首轮依据确属错误。** 复核确认：`json.RawMessage` 显式 `null` 解码为非 nil 的 `[]byte("null")`（探针 log 第 3-4 行），`policy/bucket-policy.go:78` 允许 `Version==""`，故 `null` 与 `{"Version":...,"Statement":[]}` 都能通过 `ParseBucketPolicyConfig` 且 `IsEmpty()` 为真；`*string` 的 `null` 才退化成 nil。v2 的逐字段规则与 `PeerBucketMetadataUpdateHandler:1653-1697` 的 `!=nil` 约定一致，也堵住了"`len==0 ⇒ 删除"的错删诱导。唯一 bulk 生产者（导入 `1103-1131`）在 `omitempty` 下漏发空 Policy 的问题，v2 用专用 nil 事件补齐，处置正确。
|
||||
|
||||
## P1（新增阻断，1 项）
|
||||
|
||||
**P1-1：`fieldTime <= Created` 一律判 baseline，会让历史桶的配置在初次同步中被静默丢弃且 heal 永不修复。**
|
||||
|
||||
反例（全部为已修复版本、同一桶世代、合法带时间事件，属计划承诺范围）：
|
||||
|
||||
1. A 站点有 2020 年前迁移来的桶。`applyLegacyConfigs`（`bucket-metadata.go:482-513`）不写任何 `*UpdatedAt`，`convertLegacyConfigs` 保存后磁盘上这些字段仍是零值；每次 `loadBucketMetadataParse:236-238` → `defaultTimestamps:534-561` 把 `PolicyConfigUpdatedAt` 补成 **正好等于 Created**。
|
||||
2. 运维执行 `AddPeerClusters`。`MakeBucketHook:821-823` 把 `createdAt` 传给对端，`PeerBucketMakeWithVersioningHandler:950` 的 `SetCreatedAt` 使 B 的 `Created` 与 A **完全相等**。
|
||||
3. `syncToAllPeers:2217-2228` 发出 Policy@Created（非零，因此不走 legacy-zero 例外）。
|
||||
4. 按 v2 §3"非零事件**不晚于**目标桶 Created 时成功/no-op，记录 before-created" → B 直接 no-op，policy 落不下去。
|
||||
5. 按 v2 §2/提交 2.1，A 的候选是 baseline → 过滤 → "无候选，显式 found=false" → 永远不 heal，只产出 indeterminate。
|
||||
|
||||
主干今天这条路径是成功的（`PeerBucketPolicyHandler:1718-1746` 无 before-created 检查，直接应用），bulk 侧 `1646` 也只拒绝 **严格早于** Created。因此这是回归，不是遗留缺陷；Tags/SSE/Quota 同理，Object Lock 因 `955-959` 自举侥幸掩盖。T1–T9 没有"字段时间等于 Created 的历史桶初次同步"用例，实现期不会被发现。
|
||||
|
||||
最小修正（两句契约 + 一行验收）：①把 apply 侧边界改成**严格早于** Created 才 before-created；`fieldTime == Created` 保留 baseline 的"弱"语义。②baseline 只是排序上低于任何非 baseline 候选，不是"不可用"：目标该字段自身也是 baseline/缺失时，baseline-live 仍可确立初值，仅在存在非 baseline 候选时被压制；全 baseline 且内容不同时按既定键排序取胜者，而不是报 indeterminate。③T7/T8 增加一行"全部字段时间等于 Created 的历史桶，初次同步与一轮 heal 后各站点一致"。
|
||||
|
||||
## P2（仍需改动）
|
||||
|
||||
- **Policy 比较键的构造方式。** 递归排序自造规范 JSON 需要覆盖 `Condition` 的 `map[string]map[string]ValueSet`、`NotAction/NotResource/NotPrincipal`，一旦两站点对同一策略算出不同键，同时间平局会各自选出不同胜者 → 每轮互推、不收敛。建议判等直接复用现成的 `BucketPolicy.Equals`（`site-replication.go:3912` 已在用），规范串只用于同时间平局排序，并复用 `ActionSet.String()`（silo-pkg `policy/actionset.go:151-158`，已排序）。同时把"键必须是**已解析策略**的纯函数、跨站点必须一致"写成不变量，T2 补一条"两站点各自字节 → 相同键"断言。
|
||||
- **开关语义与 Policy 的实际不对称需写进文档。** `site-replication.go:4069-4070` 无条件导出 `PolicyUpdatedAt`，因此提交 1/2 落地后，**开关 off 时 Policy 删除照样会经 heal 传播**，只有 Tags/SSE/Quota 被门控。v2 表格里"初次同步的真实删除：off 保留已有行为"容易被读成"off 完全不传播删除"，运维会据此做错误的升级判断。
|
||||
- **off 模式下的稳定态 RPC 要写进验收预期。** 持有 Tags/SSE/Quota 墓碑的站点在 off 下导出不带时间 → 每轮仍被选为待修复目标 → 每 30s（`4651`）一次必然被拒的 RPC。提交 2 的"对已归一且相同的目标不写入、不发 RPC"不覆盖该情形。请明确这是 off 期间的预期代价，并禁止为它加每轮日志（会与 §3 的三类有界日志冲突）。
|
||||
- **空策略 PUT 的对外行为补一条断言。** v2 让本地 `PutBucketPolicy` 对 `{"Version":"2012-10-17","Statement":[]}`（`bucket-policy-handlers.go:98-101` 只拒空 Version，该文档合法）改走删除。T1 请断言"PUT 返回成功、GET 返回 NotFound、出站专用事件与落盘一致"，避免实现时误改成 4xx。
|
||||
|
||||
## 作者补查核验
|
||||
|
||||
**S1 成立。** `internal/logger/logonce.go:109` 仅在 `prev.Err.Error() == nerr.Error()` 时抑制；正文含变化时间会每轮重新打印（且分支不更新 map，等于完全失效）。固定正文 + ReqInfo 的做法正确。
|
||||
|
||||
**S2 成立。** `policy/actionset.go:144-168` 的 `MarshalJSON → ToSlice` 直接遍历 map 不排序，`json.Marshal(BucketPolicy)` 确实不稳定，v1 的字节比较键不可用；v2 另建比较键的结论正确（构造方式见上 P2）。
|
||||
|
||||
---
|
||||
|
||||
**结论：NO_GO。实施前阻断数：1（P1-1）。** 首轮 R1/R2/R3 三项均已实质关闭，R4–R10、O1–O6 的处置未引入新的明确阻断；余下 4 条 P2 建议与 P1-1 一并修订即可进入实现，不需要再做全量复审。
|
||||
@@ -0,0 +1,50 @@
|
||||
{
|
||||
"reviewer": "Claude Code",
|
||||
"cli_version": "2.1.258",
|
||||
"requested_model": "claude-opus-5",
|
||||
"requested_effort": "max",
|
||||
"source_commit": "5c576581631561c446f30ae5b566f0aa793adc1c",
|
||||
"permission_mode": "plan",
|
||||
"tools": [
|
||||
"Read",
|
||||
"Grep",
|
||||
"Glob"
|
||||
],
|
||||
"round": 2,
|
||||
"plan_snapshot": "plan-v2.md",
|
||||
"plan_sha256": "2b2c712b17f757ca1a8501714c6c2472bd442a6be50b29d92f2d87e23c412ba8",
|
||||
"command": "claude --print --model claude-opus-5 --effort max --safe-mode --permission-mode plan --tools Read,Grep,Glob --strict-mcp-config --no-session-persistence --output-format stream-json --verbose",
|
||||
"status": "completed",
|
||||
"observed_model": "claude-opus-5",
|
||||
"session_id": "e40ce534-ece8-430f-841d-99add4fab13d",
|
||||
"observed_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"assistant_models": [
|
||||
"claude-opus-5"
|
||||
],
|
||||
"subtype": "success",
|
||||
"is_error": false,
|
||||
"duration_ms": 666254,
|
||||
"num_turns": 41,
|
||||
"collected_at_utc": "2026-09-12T01:40:02.942542+00:00",
|
||||
"stream_sha256": "7b3aa8de142e77b4ea1bca468685a04203261021c7978c3a97a27d1febacacab",
|
||||
"review_sha256": "848a476f18ce88208b72d8bf6cb49a2316b2b14dcba64ad66e636fe0a3d70595",
|
||||
"used_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"auxiliary_model_note": "CLI may report small auxiliary model calls in model_usage; assistant_models lists the actual recorded review message models. max was explicitly supplied in the CLI command.",
|
||||
"verdict": "NO_GO",
|
||||
"blocking_findings": 1,
|
||||
"closed_previous_blockers": [
|
||||
"R1",
|
||||
"R2",
|
||||
"R3"
|
||||
],
|
||||
"temporary_review_worktree_removed": true,
|
||||
"archive_note": "Workstation paths normalized; billing data and raw model traces omitted. Original hashes are retained in archive-manifest.json."
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
## P1-1：已关闭
|
||||
|
||||
v2 的阻断链条有三个环节，v3 逐个断开：
|
||||
|
||||
1. **apply 侧边界**：计划 §2 第 39 行改为「非零事件**严格早于**目标桶 Created 才成功/no-op 并记录 before-created」，并明写「等于目标 Created 的 live 事件可更新仍是 baseline 的目标字段，时间仍保存为源 Created」。v2 反例第 4 步（`==` 被判 before-created）不再成立。
|
||||
2. **heal 候选**：第 37 行只把「空 baseline」排除出源，baseline-live 是初始化候选；提交 2.1（第 72 行）过滤条件同样是「严格早于**自身** Created」，等于 Created 不被滤掉。v2 反例第 5 步（found=false 永不修复）不再成立。
|
||||
3. **验收**：T8 第 111 行有「历史字段时间全部等于 Created 的桶经初次同步和一轮 heal 后一致」，T7 第 110 行有 baseline-live 初始化与同级收敛。
|
||||
|
||||
## 四条反例核验
|
||||
|
||||
1. **历史 live@Created → 空字段**：初次同步走 apply 分支（baseline-live 胜空 baseline，时间存原值 Created）；漏发时 heal 也能选到该候选。写入后两侧同为 baseline-live@Created、键相等，按第 40 行「键、状态级别和源时间相同为 no-op」+ 提交 2.4 稳定。✅
|
||||
2. **较晚空默认值**：第 40 行排序先比状态级别，「任何真实 live/tombstone 都胜 baseline」，且空 baseline 既不是源也不是删除（37/39 行、decisions 表第 18 行）。时间更晚的空默认值无法压过较早真实修改。✅
|
||||
3. **不复活真实删除 / 同级收敛**：baseline-live「永远不能覆盖真实 live/tombstone」在 heal 选源与 apply 两侧同一套规则（提交 2 标题即「选源与应用同规则」），因此 off 模式下墓碑隐藏时，被选中的 baseline-live 推到持有墓碑的站点仍被接收端拒绝——是过时 RPC，不是复活。全 baseline-live 不同载荷按同一稳定键较大者胜，两侧独立计算同键（第 41 行纯函数不变量），单轮收敛且不回摆。✅
|
||||
4. **四条 P2**：均落到契约或验收行（41 行取消双判等、92 行 off≠禁止删除且不加每轮日志、T1 空策略 PUT 成功/GET NotFound）。剩余风险是 Policy 键的实现细节（递归排序与大整数精度），已转为 T2 断言，属实现期验证，非方案阻断。✅
|
||||
|
||||
## 非阻断注记
|
||||
|
||||
- 比较键含 Sid，而公开统计仍用忽略 Sid 的 `Equals`：仅 Sid 差异时 heal 会写一次、状态接口报已复制；收敛后二者一致，不会持续分歧。
|
||||
- 建议把 T8 历史桶那行的「一轮 heal」补一句第二轮无写入/广播（与第 78 行完成条件同口径），可选。
|
||||
- 第 40 行末「同状态来源不参与持久化冲突裁决」措辞含糊，实现前口头澄清即可。
|
||||
|
||||
**结论：GO_WITH_NONBLOCKING_NOTES。实施前阻断数：0。** 未发现新反例；已关闭范围（R1/R2/R3、六类 handler、导入、计数、调用图）未重审。
|
||||
@@ -0,0 +1,43 @@
|
||||
{
|
||||
"reviewer": "Claude Code",
|
||||
"cli_version": "2.1.258",
|
||||
"requested_model": "claude-opus-5",
|
||||
"requested_effort": "max",
|
||||
"source_commit": "5c576581631561c446f30ae5b566f0aa793adc1c",
|
||||
"permission_mode": "plan",
|
||||
"tools": [
|
||||
"Read",
|
||||
"Grep",
|
||||
"Glob"
|
||||
],
|
||||
"round": 3,
|
||||
"plan_snapshot": "plan-v3.md",
|
||||
"plan_sha256": "8c4ab51a397246a07bb1cc967df3377d26ac084b7928191eb8fecacf6e7c3aed",
|
||||
"command": "claude --print --model claude-opus-5 --effort max --safe-mode --permission-mode plan --tools Read,Grep,Glob --strict-mcp-config --no-session-persistence --output-format stream-json --verbose",
|
||||
"status": "completed",
|
||||
"observed_model": "claude-opus-5",
|
||||
"session_id": "3ae0c14b-58cf-415d-8d2d-3a388d322534",
|
||||
"observed_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"subtype": "success",
|
||||
"is_error": false,
|
||||
"duration_ms": 181195,
|
||||
"num_turns": 4,
|
||||
"collected_at_utc": "2026-09-12T01:50:13.403953+00:00",
|
||||
"stream_sha256": "728542385eb75e02050c17a389b49d2b4dfacdf1c54801fc6792694f91f08cff",
|
||||
"review_sha256": "557ef70288a9a3939842a2f76d63694e2c103a8bfcaa99b7c161ee89e1f58061",
|
||||
"assistant_models": [
|
||||
"claude-opus-5"
|
||||
],
|
||||
"used_tools": [
|
||||
"Read"
|
||||
],
|
||||
"auxiliary_model_note": "CLI may report small auxiliary model calls in model_usage; assistant_models lists the actual recorded review message models. max was explicitly supplied in the CLI command.",
|
||||
"verdict": "GO_WITH_NONBLOCKING_NOTES",
|
||||
"blocking_findings": 0,
|
||||
"temporary_review_worktree_removed": true,
|
||||
"archive_note": "Workstation paths normalized; billing data and raw model traces omitted. Original hashes are retained in archive-manifest.json."
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
## 复核结论（第四轮，仅针对接管增量）
|
||||
|
||||
**必要性成立，证据链闭合。** `loadBucketMetadataParse` 内 `defaultTimestamps`（`cmd/bucket-metadata.go:534`）先把字段时间补成 oldCreated，随后 `SetCreatedAt`（`:190-197`）无条件改写 `Created`，两者之间无补偿；probe 日志两个 ObjectLayer 均得 `nil with field>Created=true`，与 v4 新比较器「时间 > Created 即真实状态、nil 载荷即 tombstone」直接相撞，会伪造删除并向外广播。补丁点选在 `cmd/site-replication.go:946-950` 现有 `lockBucketMetadata` 内，位置正确。
|
||||
|
||||
**充分性成立。** 用「为 0 或 == oldCreated」判定默认值，与计划 §39「等于 Created 仍属 baseline」同一口径，重映射不改变任何状态级别；真实（> oldCreated）时间与全部载荷不动，故不覆盖真修改/真删除。不触 payload、不新增写入或广播路径，#78 配置保护不受影响；baseline-live 之间按稳定键而非时间决胜，平移时间不改变胜负。
|
||||
|
||||
另补一条支持性事实：`enablePeerBucketVersioning:901` 与 handler `:957` 的 `IsZero` 守卫在此路径上已被 `defaultTimestamps` 提前失效，bootstrap 分支本身无法把时间修正到 newCreated——归一化是唯一补救，必要性比 decisions-v4 描述的更强。
|
||||
|
||||
**两点非阻断修正：**
|
||||
|
||||
1. `SetCreatedAt` 对方向无约束，newCreated 也可能晚于 oldCreated；此时旧默认时间变成「严格早于自身 Created」，按 §37 被当作无效候选过滤，历史 baseline-live 静默丧失初始化能力。计划正文写的是「如果 Created 改变」（双向，正确），但 decisions-v4 §S4 与 T8 只写「前移」。T8 应补后移方向断言。
|
||||
2. `defaultTimestamps` 覆盖 11 个字段，补丁只归一六类，其余五类接管后遗留 != Created 的伪真实时间。#77 比较器不读它们，不阻断；实现时请在代码注释写明限定理由，或直接对该函数的全集做同样归一（同等成本，不扩大范围）。
|
||||
|
||||
未发现范围外扩、未证实假设或与已关闭项的冲突；独立桶世代合并仍在既定边界外，正确。
|
||||
|
||||
**GO_WITH_NONBLOCKING_NOTES；实施前阻断数 0。**
|
||||
@@ -0,0 +1,46 @@
|
||||
{
|
||||
"reviewer": "Claude Code",
|
||||
"cli_version": "2.1.258",
|
||||
"requested_model": "claude-opus-5",
|
||||
"requested_effort": "max",
|
||||
"source_commit": "5c576581631561c446f30ae5b566f0aa793adc1c",
|
||||
"permission_mode": "plan",
|
||||
"tools": [
|
||||
"Read",
|
||||
"Grep",
|
||||
"Glob"
|
||||
],
|
||||
"round": 4,
|
||||
"plan_snapshot": "plan-v4.md",
|
||||
"plan_sha256": "fbfd37498ab32a589d06254f32182869d5d49fc97722416c46c10b41e5f77816",
|
||||
"command": "claude --print --model claude-opus-5 --effort max --safe-mode --permission-mode plan --tools Read,Grep,Glob --strict-mcp-config --no-session-persistence --output-format stream-json --verbose",
|
||||
"status": "completed",
|
||||
"observed_model": "claude-opus-5",
|
||||
"session_id": "72c12e7b-d830-4f3a-9066-5fa829de7a4f",
|
||||
"observed_tools": [
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"subtype": "success",
|
||||
"is_error": false,
|
||||
"duration_ms": 112227,
|
||||
"num_turns": 10,
|
||||
"collected_at_utc": "2026-09-12T01:55:02.590226+00:00",
|
||||
"stream_sha256": "d8f3509c695749cb5fae9e2f7142b887e48a950a5d96818f73a05529feab2bea",
|
||||
"review_sha256": "cf10b9d7963ff2b7d4c0fbb1fe744a0e853549eaf7ce675a94cc000f74fe6682",
|
||||
"assistant_models": [
|
||||
"claude-opus-5"
|
||||
],
|
||||
"used_tools": [
|
||||
"Grep",
|
||||
"Read"
|
||||
],
|
||||
"auxiliary_model_note": "CLI may report small auxiliary model calls in model_usage; assistant_models lists the actual recorded review message models. max was explicitly supplied in the CLI command.",
|
||||
"verdict": "GO_WITH_NONBLOCKING_NOTES",
|
||||
"blocking_findings": 0,
|
||||
"nonblocking_notes_disposition": "Final plan adds Created earlier/later/unchanged acceptance and a comment limiting timestamp normalization to the six fields. No implementation scope change.",
|
||||
"final_plan_sha256": "2ee214694f16e5949ed58290364770149aee3748faee3614122fee189ef83add",
|
||||
"temporary_review_worktree_removed": true,
|
||||
"archive_note": "Workstation paths normalized; billing data and raw model traces omitted. Original hashes are retained in archive-manifest.json."
|
||||
}
|
||||
@@ -0,0 +1,103 @@
|
||||
# Issue #77 最小充分修复计划
|
||||
|
||||
版本：v1，2026-09-12。状态：作者自审完成，待 Claude Code Opus 5 Max 对抗评审。
|
||||
|
||||
基准：`pgsty/silo` main `5c576581631561c446f30ae5b566f0aa793adc1c`。本计划只授权设计与评审，不表示已实现、合并或发布。复现材料见 [当前核验](../../issue-77-current.md)。
|
||||
|
||||
## 目标与范围
|
||||
|
||||
让修复版本间的 Policy、Tags、SSE、Quota、Versioning、Object Lock 桶配置，在合法带源时间的 peer 事件被延迟、重复、乱序或漏发后，能按同一规则应用并由 heal 最终收敛；删除状态必须落盘、能传播，不能被较旧配置复活。桶元数据批量导入的复制入口属于同一范围。
|
||||
|
||||
本轮不重做 #91 的计数、#76 的 Object Lock wire 字段、#78 的桶接管、#103/#156 的整记录锁和删除保护。CORS、Lifecycle/expiry、notification、对象数据复制、MRF、resync、IAM 均不改变其语义。支持与验收对象是协调的 PGSTY 栈；不引入为了上游 MinIO 兼容而修改依赖的工作。
|
||||
|
||||
## 已确定的行为契约
|
||||
|
||||
| 类型 | 专用事件 nil 或解码后空内容 | bulk 字段未提供/null | 真实删除状态导出 |
|
||||
| --- | --- | --- | --- |
|
||||
| Policy / Tags / SSE / Quota | 删除；保留源时间，删除走现有 parse=false 路径 | 不修改该字段 | Policy 保留现状；另三类受下述单一开关控制 |
|
||||
| Versioning / Object Lock | no-op，不能通过 heal 删除配置 | 不修改该字段 | 不新增删除语义 |
|
||||
|
||||
合法的空 quota 对象 `{}` 仍按现有 quota 解析语义处理，不能仅因配额为零就改写为 nil。Policy 空策略继续使用现有专用 admin handler 的判空行为。所有既有字段编码、公开 getter 的 NotFound 行为、RPC 返回结构及权限要求保持不变。
|
||||
|
||||
1. **读取原始字段时间。** 排序使用 `BucketMetadata` 的原始 `*UpdatedAt` 字段，不能用会隐藏删除时间的公开 getter，也不能用整记录 `lastUpdate()` 代替字段时间。
|
||||
2. **创建边界与未知值。** `UpdatedAt == 0` 或 `UpdatedAt == CreatedAt` 的记录不能作为 heal 的权威候选。后者沿用既有创建默认值约定，包括无法恢复真实修改时间的旧记录；全部为此类状态时不写入并给出有界诊断。peer 事件早于当前桶 CreatedAt 时不应用。新产生的实际配置写入时间必须严格大于 CreatedAt。
|
||||
3. **带时间事件的确定性次序。** 先比较源时间；相同时间下，真实删除大于 live，live/live 按稳定载荷字节序比较；内容和时间均相同则 no-op。Policy/Quota 使用既有解析后 JSON 编码作为比较表示；XML 使用解码后的实际文档字节。apply 和 heal 使用同一个比较函数。deployment ID 只在完全相同状态下用于选取日志中的来源，不能作为未持久化的冲突元数据。
|
||||
4. **本地新操作不倒退。** 对上述六类的实际本地写入，锁内分配 `max(UTCNow(), CreatedAt+1ns, 当前字段时间+1ns)`。其他配置类型保持原有 UTCNow 行为。保留现有 Object Lock 强制 Enabled versioning 的规则，不改变 suspend、prefix exclusion、retention 的合法性。
|
||||
5. **nil 与删除区分。** 只有可删除类型的专用事件，或 bulk 中明确提供且按既有规则解析为空的可删除字段，表示删除。bulk 的 nil 必须继续表示未提供。Versioning/Object Lock 的 nil/空输入在任何路径均不能清空配置。
|
||||
6. **写入原子性。** 原始读取、比较、修改及保存全部在现有桶 `metadata.lock` 内。更新用现有 parse=true 路径，删除用 parse=false 路径；bulk 保留当前原始读取、最后统一解析保存的方式，避免 Quota 已解析缓存残留。任何字段校验失败不得保存部分 bulk。无状态变化时不保存、不通知；有变化时成功保存一次，解锁后再通知。
|
||||
|
||||
## 实施顺序
|
||||
|
||||
### 提交 1：原子排序与本地事件时间
|
||||
|
||||
改动主要在 `cmd/bucket-metadata-sys.go`、`cmd/site-replication.go` 和 `cmd/admin-bucket-handlers.go`，只增加六类字段的内部访问/比较/更新时间能力，不引入注册表、接口插件或复制框架。
|
||||
|
||||
- 复用现有 `updateAndParse` 的加载、类型设置、保存和通知边界，增加内部 peer 源时间输入及是否应用的结果。公开 `Update/Delete` 的签名保持不变；专用 peer handler 的公开 error-only 签名也不变。
|
||||
- 六个 peer handler 删除锁外 getter 判旧，使用内部源时间更新/删除路径。对非零源时间执行上述比较，持久化原始源时间而非到达时间；重复和被拒绝的旧事件不落盘。
|
||||
- 批量 `PeerBucketMetadataUpdateHandler` 对六类已提供字段在其已有整记录锁内执行同一比较。不能循环调用会再次取得桶锁的公开 handler。保留 bulk 中未提供字段、既有 CORS 分支以及一次保存语义。
|
||||
- 普通本地六类写入用字段内单调时间。`enablePeerBucketVersioning` 在实际修改现有配置时也用该时间函数；仅缺失字段的创建 bootstrap 保留 CreatedAt 默认值，不给默认配置伪造一次新修改。
|
||||
- **导入生成端一并修复。** 在每桶最终提交锁内，对本次导入涉及的六类字段分配一个共同 `commitAt`：严格大于 CreatedAt 和这些字段现存时间，并且不早于锁内当前时刻。覆盖导入暂存对象中这些字段的时间后，再调用现有 `applyImportedBucketMetadata`。发送 bulk hook 的 UpdatedAt 必须是同一个 commitAt，不能再用整个 ZIP 请求开始时的 updatedAt。未导入字段不改；CORS 继续自己的时间函数和独立事件，Lifecycle/notification 不参与这个时间上界。
|
||||
- 原样保留 `saveMetadata` 的物理桶存在检查、桶删除锁序、后台通知上下文和加载/迁移路径。不得另加一套 peer-require-existing 或新锁。
|
||||
- 对真实历史桶 `Created == 0`，仅在该少见路径取得现有物理桶 Created 并补齐，再按现有默认时间规则加载；物理桶不存在就返回现有错误。若物理创建时间也未知，不能用本次到达时间伪造桶世代：不应用并报告 indeterminate。
|
||||
|
||||
提交 1 的完成条件：六类 peer PUT 落盘保留源时间；四类 DELETE 后旧 PUT 不复活；相同内容重复事件不保存；getter→Update 竞态和 bulk 旧事件覆盖被挡住；本地后续写入可以胜过已有未来源时间；导入的持久化时间与实际发出的事件一致。
|
||||
|
||||
### 提交 2：heal 统一选源与状态同步
|
||||
|
||||
改动主要在 `cmd/site-replication.go`。
|
||||
|
||||
- 先过滤未知/创建默认状态和 update-only 的空候选，再从剩余候选中按相同比较器选最新；必须显式返回 found=false。取消“先用 map 首项初始化，再判断是否默认”的写法。
|
||||
- 为 Policy、Tags、SSE、Quota、Versioning、Object Lock 六类 heal 替换对应选源循环。不触碰 CORS、Lifecycle 或对象数据修复路径。
|
||||
- 本地 heal 通过提交 1 的源时间更新/删除路径；远端 heal 保留对应事件类型并携带选中状态的源时间，补齐 Tag 的 UpdatedAt。
|
||||
- heal 是否写入由完整状态比较决定，不再由公开 mismatch 计数或仅 payload 相等决定。即使内容相同，较旧时间也必须同步；完全相同的状态不保存、不发送。
|
||||
- 保留 #91 的 payload/数量统计语义和字段，不为实现时间戳同步更改 madmin API。持续 indeterminate 或因桶创建边界拒绝而留下的状态差异通过提交 3 的日志解释。
|
||||
|
||||
提交 2 的完成条件：map 顺序不影响选源；默认状态不能删除真配置；全默认/未知状态不修改磁盘；nil 不清空 Versioning/Object Lock；Quota 删除后磁盘和缓存一致；远端 Tag 时间完整；同内容不同时间、同时间不同内容都能确定性收敛。
|
||||
|
||||
### 提交 3：删除传播与有界诊断
|
||||
|
||||
使用一个启动配置开关，暂定名称 `MINIO_SITE_REPLICATION_METADATA_CONVERGENCE`，`off` 为默认，`on` 为显式启用。不加入 madmin/silo-pkg 字段、不新增 RPC、不构建通用能力协商。
|
||||
|
||||
| 行为 | off：兼容升级阶段 | on：全站点修复后 |
|
||||
| --- | --- | --- |
|
||||
| 有源时间的 peer apply、锁内排序、heal | 使用提交 1/2 的修复 | 同左 |
|
||||
| 专用事件零源时间 | 保留旧版兼容：锁内按本地新操作时间应用，限频记录兼容降级；此类事件不在排序收敛保证内 | 拒绝为无效事件，不写入 |
|
||||
| bulk 零源时间 | 维持当前拒绝行为 | 同左 |
|
||||
| Tags/SSE/Quota nil payload 时间导出 | 维持旧版 payload 条件导出 | 导出真实删除时间；零/创建默认仍不是删除事件 |
|
||||
| Policy 时间导出 | 保持已有行为 | 保持已有行为 |
|
||||
| 初次同步的删除状态 | 保持已有行为 | Policy/Tags/SSE/Quota 的真实删除也发送专用 nil + source time 事件 |
|
||||
|
||||
这里的开关只隔离新增的删除传播和不再接受无时间事件的行为。它不证明远端能力；启用的明确条件是所有参与站点、每站点全部节点都已部署包含提交 1/2/3 的修复版本，旧请求已排空。配置同一站点内必须一致。任何旧节点仍在线时保持 off。
|
||||
|
||||
- exporter 只把可区分的真实删除状态作为新增导出对象，不把新桶默认配置改成删除。Policy 已有导出保留，选择端过滤默认值。
|
||||
- `syncToAllPeers` 也使用同一状态判断发送真实删除；不能只修定期元数据查询而遗漏初次同步。保持现有逐类型 RPC 和编码。
|
||||
- 复用已有日志去重/限频设施，固定为有限的原因集合：legacy-zero、stale-conflict、before-created、indeterminate。精确重复属于正常 no-op，不记警告；普通顺序已知的旧事件不制造每轮噪音；仅实际错误/持续无法收敛的原因记录桶、配置类型、当前/源时间，不输出完整策略或配置。
|
||||
- stale 与 before-created 保持 RPC 成功/no-op；缺桶、非法 payload 和 on 模式下的零时间仍返回相应错误。不开新重试循环。
|
||||
- 更新 Server 的 site-replication 文档，写清 off/on、全节点升级条件、零时间兼容降级和回滚限制。回滚/降级前先在所有修复节点关闭该开关，再滚动降级；旧软件原有缺陷会恢复，不宣称回滚后仍具备收敛保证。
|
||||
- 旧版本已经记录成到达时间的历史值不能推导回真实源时间。升级完成后，操作者在看到各站点状态后选择权威配置，重新提交需要纠正的配置/删除；不得自动把时间归零或选任意站点强制覆盖。
|
||||
|
||||
## 最小验收矩阵
|
||||
|
||||
以下均为缺陷或上述修复引入的行为边界；不把发布制品、外部上游服务或不相关产品作为本计划硬门槛。
|
||||
|
||||
| 组 | 必须验证 | 验证层 |
|
||||
| --- | --- | --- |
|
||||
| T1 | 六类 PUT 原样源时间；四类 DELETE；较旧 PUT/DELETE 不回退；精确重复无写入 | 真实 admin 路由 + 两种 ObjectLayer + 磁盘重载 |
|
||||
| T2 | 同时间不同 live 状态两种到达顺序结果相同；可删除类型 PUT/DELETE 同时间删除获胜 | 比较器确定性测试 + 代表性真实 handler |
|
||||
| T3 | Versioning/Object Lock nil/空不删除；保留 lock→Enabled versioning 约束；空 quota 对象语义 | 类型回归 + 现有 #76/#78 测试 |
|
||||
| T4 | 旧 peer 在锁前通过检查，较新写入先提交后旧 peer 再落锁，不能覆盖；并发不同字段均保留 | 确定性锁屏障 + 两种 ObjectLayer，针对性 race |
|
||||
| T5 | bulk 有旧字段/新字段/未提供字段混合，分别忽略/应用/保留；非法字段不部分保存；不能借 bulk 复活墓碑 | admin bulk 路由 + 磁盘/缓存 |
|
||||
| T6 | 本地操作的时间大于收到的未来时间；两个相邻本地提交不倒序；ZIP 导入期间插入写入，最终提交字段与发出的 bulk 时间完全一致 | 本地 API、import 路由、捕获 RPC |
|
||||
| T7 | 多站点排序排列、默认/零时间、全部无候选、空 update-only；同 payload 新时间、同时间冲突；Tag 出站源时间；Quota nil 后缓存清空 | heal + 本地/远端路径 |
|
||||
| T8 | 保存/缓存失效/进程重启后墓碑仍有效；缺桶/排队写入/真实零 Created 历史桶；on/off 与新旧发送端混合；初次同步携带真实删除 | ObjectLayer、现有删除测试、固定旧版与修复版两个 SILO 进程 |
|
||||
| T9 | 短暂断线、事件漏发/重复/乱序后重新连通，六类允许状态收敛；开关 on 后旧零时间事件失败且无修改；日志有界 | 隔离的双站点/多节点实验 |
|
||||
|
||||
实现期间先把已有审计用例改成确定性正式回归：不能将反复遍历 map 的概率复现直接提交为生产测试。先记录未修复失败，再验证修复后通过。完成局部修复后运行相关现有回归、目标 race、仓库必需的格式/静态检查与完整 Go CI；同一基准通过后不因形式要求反复全量测试。
|
||||
|
||||
## 作者自审结论
|
||||
|
||||
- 必要：六类共享的是字段排序与锁内写入；删除、编码、bulk 未提供字段和 Object Lock 约束仍按类型处理。
|
||||
- 充分：普通本地写、专用 peer、bulk/import、local/remote heal、导出、初次同步、重载均在清单内。没有继续保留绕过排序的实际写入入口。
|
||||
- 最小：复用一把已有锁、现有持久化和通知、一套小的字段比较逻辑；只加一个针对实际混合版本风险的开关。没有存储 schema、SDK、Console、客户端或新协议依赖。
|
||||
- 明确限制：off 模式、无时间旧事件、任意未升级节点和已污染的历史时间不承诺自动收敛；on 模式的验收仅针对修复 PGSTY 栈的合法状态与已知桶世代。
|
||||
- 当前只批准进入外部方案评审。任何对抗评审发现的具体遗漏或多余工作，应先修订本文件并复审，再决定进入实现。
|
||||
@@ -0,0 +1,118 @@
|
||||
# Issue #77 最小充分修复计划
|
||||
|
||||
版本：v2，2026-09-12。状态：已处理首轮对抗评审并完成作者复核，待 Claude Code Opus 5 Max 复审。
|
||||
|
||||
基准：`pgsty/silo` main `5c576581631561c446f30ae5b566f0aa793adc1c`。本轮交付是方案与评审，不表示已经实现、合并或发布。问题证据见 [当前核验](../../issue-77-current.md)，首轮意见及处置见 [评审处置](decisions-v2.md)。
|
||||
|
||||
## 目标与边界
|
||||
|
||||
修复 Policy、Tags、SSE、Quota、Versioning、Object Lock 六类桶配置的源时间丢失、锁外判旧、heal 错选源和删除传播不完整。覆盖普通本地写入、专用 peer 事件、bulk/import、local/remote heal、元数据导出与初次同步。
|
||||
|
||||
在修复 PGSTY 栈、同一已知桶世代、合法带源时间事件的范围内，使重复、乱序和漏发后的状态能够确定性收敛。开关关闭期间新增删除信息不可见，不承诺完整删除收敛；无时间旧事件、旧版污染时间和桶创建世代冲突需要单独解释，不能自动推断历史真相。
|
||||
|
||||
不重做 #91 的计数、#76 的 Object Lock wire 修复、#78 的桶接管、#103/#156 的锁与删除保护。不改变 CORS、Lifecycle/expiry、notification、对象复制、MRF、resync、IAM 的语义；不改存储 schema、SDK、Console、mcli 或 silo-pkg，不新建能力协商、复制框架、锁或重试系统。
|
||||
|
||||
## 行为契约
|
||||
|
||||
### 1. 明确事件、缺省值与删除
|
||||
|
||||
| 类型 | 专用事件 | bulk 字段未提供 | bulk 字段明确提供 |
|
||||
| --- | --- | --- | --- |
|
||||
| Policy | nil 为删除；沿用现有解析器 `IsEmpty()` 为删除 | 保留 | 非空 RawMessage 按现有解析器处理；语义空策略归一为删除 |
|
||||
| Quota | nil 为删除；非 nil 按现有 quota 解析器处理 | 保留 | 非空 RawMessage 按现有解析器处理，零 quota 仍是 live 文档 |
|
||||
| Tags / SSE | nil 或 base64 解码后空内容为删除 | 保留 | 空字符串为删除，其他内容按原规则解码、校验 |
|
||||
| Versioning / Object Lock | nil/空内容为 no-op | 保留 | nil/空内容仍为 no-op，不能清空配置 |
|
||||
|
||||
“未提供”必须依据真实 wire 类型判定：Policy/Quota 的 `json.RawMessage` 为 nil 或空切片时经 `omitempty` 省略；**显式 JSON `null` 解码后是非 nil 的 `[]byte("null")`**，不能与缺省混淆。按现有解析器，Policy `null` 是语义空策略，Quota `null` 是零值 quota 文档。`*string` 类型的 JSON `null` 则解码为 nil。不得使用统一的 `len(payload)==0 => 删除` 来处理 bulk。
|
||||
|
||||
合法 `{}`/零值 quota 保持 live；取消普通 quota PUT 出站时“零配额改写为 nil”的逻辑，保存与发送同一个语义状态。Policy 保留现有专用 peer 的“空策略=删除”解释，本地 PUT、导入和 bulk 统一归一为同样的删除状态；这是需要写入兼容说明的小范围变化：空策略本地立即按删除处理，GET 返回既有 NotFound 行为，不再先保留空文档、等复制后才被清除。
|
||||
|
||||
**同一次操作的落盘状态与出站事件，经同一归一规则后，必须具有相同的 `(kind, payload key, source time)`。** JSON 的无意义编码次序不要求字节相同；Object Lock 改写后的有效 Versioning 文档必须来自提交结果。
|
||||
|
||||
### 2. 统一状态与排序
|
||||
|
||||
内部仅需一个小状态表示：baseline / live / tombstone，以及比较键和字段源时间。复用 CORS 已有设计思路，不改 CORS 本身或扩展为通用框架。
|
||||
|
||||
- 使用 `BucketMetadata` 原始字段时间；字段时间为零时在比较视图中补为 Created，与 `defaultTimestamps()` 一致，不借用会隐藏墓碑时间的 getter 或整记录 `lastUpdate()`。
|
||||
- 在已知 Created 下，零时间或 `fieldTime <= Created` 是 baseline；它不能成为 heal 权威源，也不能作为带时间 peer 更新覆盖实际状态。Versioning/Object Lock 的空候选无论时间如何都不参与选源。
|
||||
- 专用 peer 的零时间保留兼容例外：锁内按本地新操作分配时间并限频记录 legacy-zero；不受删除传播开关影响，不在源时间排序保证之内。bulk 零时间仍按现状拒绝。
|
||||
- 非零事件不晚于目标桶 Created 时成功/no-op，记录 before-created。heal 同时过滤源端 baseline；对候选时间不晚于目标 Created 的目标跳过，不能每轮继续发送必然拒绝的 RPC。不同桶世代不能自动合并，需要运维处理，不纳入收敛承诺。
|
||||
- 有效状态先按源时间排序；同时间 tombstone 胜 live；同时间 live/live 的**稳定比较键字节序较大者胜**。键与时间相同为 no-op。同状态来源按现有稳定遍历/选源方式取即可，deployment ID 不参与持久化冲突裁决。
|
||||
- Quota 使用现有解析结果的 JSON 编码作为比较键。Policy 在 Server 内生成确定性比较表示：既有解析器校验/去重后，对 JSON 对象键和集合数组递归排序，包括 Statement、Action、Resource、Principal、Condition 值。普通 `json.Marshal(BucketPolicy)` 不稳定，不能直接作键；不为此修改 silo-pkg 或 wire/schema。
|
||||
- XML 使用有效文档字节，保留大小写和实际内容；Versioning 先应用下述现有 Object Lock 约束。比较器不能依靠字节序方向来补偿保存阶段的隐式改写。
|
||||
|
||||
### 3. 先得到有效状态，再比较与提交
|
||||
|
||||
原始读取、类型处理、比较、修改及保存均在现有 `metadata.lock` 内。内部入口必须传递现有 lock context，避免 legacy migration 再次取锁。
|
||||
|
||||
- 提取并复用 `parseAllConfigs` 已有的 Object Lock→Enabled Versioning 归一规则，使比较视图和真正保存一致；不得扩大 suspend、prefix exclusion、retention 的限制。bulk 先确定实际接受的 Object Lock，再比较该约束下的 Versioning，并在最终提交前应用同一规则。
|
||||
- 以归一化后的有效 `(kind, key, time)` 判定变化；更新了时间也算变化。完全重复不保存、不通知；一次 bulk 校验失败不保存部分结果；成功至多保存一次，解锁后通知。
|
||||
- 可删除字段清空必须基于现有 parse=false 的新加载对象，不能在已经解析且仍持有旧 quota 的对象上执行 Update(nil)。bulk 保留原始读取再解析保存的方式。不要顺手修改 Quota getter 或所有 `parseAllConfigs` 空分支。
|
||||
- 保存函数必须让需要发送 hook 的调用方拿到**本次提交的最终快照**，不能先解锁再读取“最新”状态拼接旧时间。最小做法是让内部 `saveMetadata` 接收元数据指针并回写 Save 的归一化结果，机械更新现有少量调用；对外 `Update/Delete` 签名不变，新增内部提交结果仅供需要该快照的本地 handler/import 使用。不得原地修改已发布到缓存的引用字段。
|
||||
- 保留现有物理桶存在检查、删除锁序、迁移、后台通知上下文。真实历史桶 Created 为零时仅走少见的物理桶 Created 补齐路径；物理桶缺失返回现有错误；创建时间仍未知则不伪造到达时间，报告 indeterminate。
|
||||
|
||||
## 三个实现提交
|
||||
|
||||
### 提交 1：原子 apply、发送一致性与本地时间
|
||||
|
||||
主要文件：`cmd/bucket-metadata-sys.go`、`cmd/bucket-metadata.go`、`cmd/site-replication.go`、`cmd/admin-bucket-handlers.go`，以及实际需要提交快照的本地配置 handler。
|
||||
|
||||
1. 在现有 update/delete 内部路径增加源时间、状态比较和提交结果；公开签名不变。六个 peer handler 移除锁外 getter 判旧，锁内持久化原始源时间。保留 Object Lock 的 legacy Tags 字段载荷回退。
|
||||
2. bulk 对明确提供的六类字段在已有锁内逐字段比较，再原子保存；未提供字段不动，不能循环调用会重入锁的公开 handler。保留 CORS 独立分支与既有行为。
|
||||
3. 六类本地实际写入在锁内分配 `max(UTCNow(), Created+1ns, 当前字段时间+1ns)`。其他类型不变。`enablePeerBucketVersioning` 的实际变更也使用它，只有缺失配置的创建 bootstrap 继续 Created 默认值。
|
||||
4. quota 本地 PUT 保留零值文档并原样表示该语义；Policy 空策略本地与 peer 一致走删除。需要归一化的本地 handler 从本次提交快照生成 hook；其他内容不发生归一变化的路径可保留既有编码，但必须满足三元组一致性。
|
||||
5. 导入在每桶最终提交锁内，为本次涉及的六类字段生成共同 commitAt，严格大于 Created 和这些字段当前时间且不早于锁内现在。该时间同时用于落盘和 bulk hook，不能沿用 ZIP 开始时间。bulk hook 从最终提交快照构建；若导入的空 Policy 已归一成删除，另外使用现有专用 Policy nil 事件表达它，不能因 `omitempty` 漏发。未导入字段不改，Object Lock 的既有派生 Versioning 修正保留原时间语义；CORS 继续独立时间/事件，其他字段不参与该上界。
|
||||
|
||||
完成条件：六类源时间落盘；旧事件不能越过锁覆盖新状态；四类删除不会被旧 PUT 复活；真实 wire、落盘和出站状态一致；重复无写入；bulk 与 import 没有绕过排序或静默遗漏删除。
|
||||
|
||||
### 提交 2：heal 选源与应用同规则
|
||||
|
||||
主要文件：`cmd/site-replication.go`。
|
||||
|
||||
1. 先过滤 baseline、无效来源和 update-only 空配置，再选最大状态；无候选必须显式返回 found=false。消除六处“先 seed map 首项，再过滤默认值”的写法。
|
||||
2. 选源和目标遍历都跳过 `info.Sites` 中不存在的 deployment ID，包括不可达站点的空 ID 占位项；单一 peer 失败记录后继续其它目标，不因 map 顺序放弃健康站点。不改变状态计数或新建重试机制。
|
||||
3. 本地 heal 使用提交 1 的源时间 update/delete；远端仍用原有逐类型 RPC，全部携带源时间，补齐 Tag 的 UpdatedAt。
|
||||
4. 比较完整有效状态，去掉公开 mismatch/payload-only 对写入的门控；同内容较旧时间也同步。对已归一且相同的目标不写入、不发 RPC。Versioning 比较使用与该站点 Object Lock 一致的有效文档；全站点 Lock 状态补齐后不再因旧原始文档产生空转。
|
||||
5. 保留 #91 的计数与公开字段；创建世代冲突、无可用来源通过有限诊断解释。已知 baseline 且各站点无实质差异时安静 no-op。
|
||||
|
||||
完成条件：map 顺序不影响结果；默认值不再删真配置；同内容不同时间、同时间冲突最终一致；Tag 时间完整；Quota 删除后磁盘、缓存、重载一致；不可达占位项不阻断健康目标；第二轮稳定 heal 无写入/广播。
|
||||
|
||||
### 提交 3：新增删除传播与有界诊断
|
||||
|
||||
只增加一个启动开关，暂定 `MINIO_SITE_REPLICATION_METADATA_TOMBSTONES=off/on`，默认 off；实现沿用现有 env 开关写法，不做能力协商。
|
||||
|
||||
| 行为 | off：升级阶段 | on：所有参与节点修复后 |
|
||||
| --- | --- | --- |
|
||||
| 带时间 peer apply、锁内排序与 heal | 使用提交 1/2 | 同左 |
|
||||
| 专用事件零时间 | 兼容应用并记录 legacy-zero | 同左，不新增协议拒绝 |
|
||||
| Tags/SSE/Quota nil payload 时间导出 | 保留旧版条件导出 | 导出 `time > Created` 的真实删除时间 |
|
||||
| Policy 时间导出 | 保留已有行为 | 保留已有行为 |
|
||||
| 初次同步的真实删除 | 保留已有行为 | Policy/Tags/SSE/Quota 都发送专用 nil + source time 事件 |
|
||||
|
||||
开关只控制**新增**删除信息的导出/初次发送，普通本地删除事件照常复制。它不检测或证明远端能力。启用条件是所有参与站点的全部节点已经修复，同一站点配置一致，旧请求排空；旧节点仍在线时保持 off。此隔离有实证依据：旧版接到新增 Quota heal 墓碑会留下已解析缓存残留。
|
||||
|
||||
日志仅保留三个实际原因：legacy-zero、before-created、indeterminate（未知创建时间、缺失/不可达来源或有实际差异却无可用候选）。精确重复、正常旧事件和成功裁决的同时间冲突不记警告。复用 `LogOnceIf`，以稳定的桶/字段/原因作为 key，**错误正文也必须稳定**；变化的时间与 peer 详情放入日志 ReqInfo，沿用现有每小时清理，不新增限流框架、不输出完整策略。
|
||||
|
||||
Server 文档解释启用顺序和回滚：降级前所有修复节点先关开关，然后滚动降级；旧软件缺陷会恢复。点名旧版 Tag heal 无 UpdatedAt 的来源。旧版到达时间污染、legacy-zero 产生的新本地时间以及创建世代分歧无法自动还原；操作者查看状态后在权威站点重新提交需要纠正的配置/删除。历史世代冲突先处理桶身份，不能靠任意站点强刷绕过创建保护。
|
||||
|
||||
## 最小验收矩阵
|
||||
|
||||
| 组 | 必须覆盖 | 证据方式 |
|
||||
| --- | --- | --- |
|
||||
| T1 | 六类 PUT 源时间；四类 DELETE；旧事件不回退；重复无写入；零 quota、空 Policy 的落盘/出站三元组一致 | 真实 admin/S3 路由、ErasureSD/Erasure16、磁盘重载、RPC 捕获 |
|
||||
| T2 | 同时间两种到达顺序结果相同、删除优先；Policy 多 Action/Resource/Principal/Condition 集合反复编码与排列后键稳定 | 确定性比较器测试与代表性真实 handler |
|
||||
| T3 | Versioning/Object Lock nil/空 no-op；legacy Tags 载荷回退；Object Lock + prefix exclusion/ExcludeFolders 在普通写、peer、bulk/import 后有效状态一致，第二轮 heal 无额外写入 | 原有 #76/#78 回归加针对性用例 |
|
||||
| T4 | 锁前旧事件排队、较新写先提交后旧事件不得覆盖；不同字段并发均保留 | 复用已有 `lockBucketMetadataAcquireHook` / RMW 屏障、两种 ObjectLayer、目标 race |
|
||||
| T5 | bulk 新/旧/缺省字段混合；真实 JSON 编解码的 nil、空 RawMessage、显式 null、空字符串、空策略、零 quota；非法字段不部分保存；只导入 tags 不修改 Policy/Quota | 真实 bulk 路由、缓存与磁盘 |
|
||||
| T6 | 本地时间胜过已有未来时间；相邻提交不倒序；ZIP 导入期间插入写入，最终落盘和发出事件的状态与时间一致，空 Policy 删除不漏发 | 本地 API、import 路由与 RPC 捕获 |
|
||||
| T7 | 多站点排序排列、baseline/全无候选、空 update-only；同内容新时间；Tag 源时间；Quota 删除清缓存；空 deployment ID 不阻断其它目标；世代冲突跳过且不反复发 RPC | 确定性 heal 本地/远端用例 |
|
||||
| T8 | 墓碑经保存/缓存失效/重启仍有效；缺桶、排队写入、零 Created 历史桶；开关 on/off、legacy-zero 与初次同步删除 | ObjectLayer 与进程内旧版 wire/SRInfo 模拟；复用既有删除/迁移回归 |
|
||||
| T9 | 修复版双站点短暂断线、漏发/重复/乱序后六类合法配置收敛；删除传播启用后第二轮稳定无写入；日志确实有界 | 隔离双站点实验，不把未知桶世代或零时间事件算成通过 |
|
||||
|
||||
固定旧版与修复版混合进程仅作一次性升级冒烟，不新增为长期提交门槛。将已有审计用例改成正式确定性回归，不能把遍历 map 的概率复现直接提交。先记录未修复失败，再验证通过；复用原有 Object Lock、adoption、metadata-lock、计数、CORS 回归，并在实现后运行目标 race、仓库必需检查和完整 Go CI。方案审查、局部测试、双站点结果、合并与发布是不同证据。
|
||||
|
||||
## 作者复核结论
|
||||
|
||||
三个提交分别处理写入正确性、heal 收敛和新增删除信息的升级边界；每项对应已证实缺陷或本次修复直接触及的实际路径。缩减了拒绝零时间的新协议行为、混合版本长期测试门槛和新锁屏障；保留已有持久化、通知与缓存语义。
|
||||
|
||||
首轮三个 P1 意见均已有明确处置：R1 修发送/保存一致性；R2 使用有效状态和提交快照；R3 给出经过实际编解码验证的逐字段规则，而非照搬其不准确的 RawMessage 推断。作者另补充了 Policy 非确定性编码与日志去重问题。外部复审未返回前不标记为可进入实现；后续仍须用实现期测试证明，而非把本计划当作修复完成。
|
||||
@@ -0,0 +1,120 @@
|
||||
# Issue #77 最小充分修复计划
|
||||
|
||||
版本：v3，2026-09-12。状态：首轮三个阻断已被 Opus 复审确认关闭；已修订第二轮发现的历史桶初始化边界，待最后的针对性复审。
|
||||
|
||||
基准：`pgsty/silo` main `5c576581631561c446f30ae5b566f0aa793adc1c`。本轮交付是方案与评审，不表示已经实现、合并或发布。问题证据见 [当前核验](../../issue-77-current.md)，意见处置见 [首轮处置](decisions-v2.md)、[第二轮处置](decisions-v3.md)。
|
||||
|
||||
## 目标与边界
|
||||
|
||||
修复 Policy、Tags、SSE、Quota、Versioning、Object Lock 六类桶配置的源时间丢失、锁外判旧、heal 错选源和删除传播不完整。覆盖普通本地写入、专用 peer 事件、bulk/import、local/remote heal、元数据导出与初次同步。
|
||||
|
||||
在修复 PGSTY 栈、同一已知桶世代、合法带源时间事件的范围内，使重复、乱序和漏发后的状态能够确定性收敛。开关关闭期间新增删除信息不可见，不承诺完整删除收敛；无时间旧事件、旧版污染时间和桶创建世代冲突需要单独解释，不能自动推断历史真相。
|
||||
|
||||
不重做 #91 的计数、#76 的 Object Lock wire 修复、#78 的桶接管、#103/#156 的锁与删除保护。不改变 CORS、Lifecycle/expiry、notification、对象复制、MRF、resync、IAM 的语义；不改存储 schema、SDK、Console、mcli 或 silo-pkg，不新建能力协商、复制框架、锁或重试系统。
|
||||
|
||||
## 行为契约
|
||||
|
||||
### 1. 明确事件、缺省值与删除
|
||||
|
||||
| 类型 | 专用事件 | bulk 字段未提供 | bulk 字段明确提供 |
|
||||
| --- | --- | --- | --- |
|
||||
| Policy | nil 为删除；沿用现有解析器 `IsEmpty()` 为删除 | 保留 | 非空 RawMessage 按现有解析器处理；语义空策略归一为删除 |
|
||||
| Quota | nil 为删除；非 nil 按现有 quota 解析器处理 | 保留 | 非空 RawMessage 按现有解析器处理，零 quota 仍是 live 文档 |
|
||||
| Tags / SSE | nil 或 base64 解码后空内容为删除 | 保留 | 空字符串为删除，其他内容按原规则解码、校验 |
|
||||
| Versioning / Object Lock | nil/空内容为 no-op | 保留 | nil/空内容仍为 no-op，不能清空配置 |
|
||||
|
||||
“未提供”必须依据真实 wire 类型判定：Policy/Quota 的 `json.RawMessage` 为 nil 或空切片时经 `omitempty` 省略；**显式 JSON `null` 解码后是非 nil 的 `[]byte("null")`**，不能与缺省混淆。按现有解析器，Policy `null` 是语义空策略，Quota `null` 是零值 quota 文档。`*string` 类型的 JSON `null` 则解码为 nil。不得使用统一的 `len(payload)==0 => 删除` 来处理 bulk。
|
||||
|
||||
合法 `{}`/零值 quota 保持 live；取消普通 quota PUT 出站时“零配额改写为 nil”的逻辑，保存与发送同一个语义状态。Policy 保留现有专用 peer 的“空策略=删除”解释，本地 PUT、导入和 bulk 统一归一为同样的删除状态；这是需要写入兼容说明的小范围变化：空策略本地立即按删除处理，GET 返回既有 NotFound 行为，不再先保留空文档、等复制后才被清除。
|
||||
|
||||
**同一次操作的落盘状态与出站事件，经同一归一规则后，必须具有相同的 `(kind, payload key, source time)`。** JSON 的无意义编码次序不要求字节相同；Object Lock 改写后的有效 Versioning 文档必须来自提交结果。
|
||||
|
||||
### 2. 统一状态与排序
|
||||
|
||||
内部仅需一个小状态表示：baseline / live / tombstone，以及比较键和字段源时间。baseline 可携带历史有效配置，但没有真实修改时间；它绝不能被当成删除。复用 CORS 已有设计思路，不改 CORS 本身或扩展为通用框架。
|
||||
|
||||
- 使用 `BucketMetadata` 原始字段时间；字段时间为零时在比较视图中补为 Created，与 `defaultTimestamps()` 一致，不借用会隐藏墓碑时间的 getter 或整记录 `lastUpdate()`。
|
||||
- 在已知 Created 下，零字段时间回退后等于 Created 的状态是 baseline：有有效非空配置的 baseline-live 可作为初始化候选；空 baseline 只是缺省值，不能作为删除或 heal 来源。真正严格早于自身 Created 的字段不是候选；Versioning/Object Lock 的空候选无论时间如何都不参与选源。真实 live/tombstone 的时间必须大于 Created。
|
||||
- 专用 peer 的零时间保留兼容例外：锁内按本地新操作分配时间并限频记录 legacy-zero；不受删除传播开关影响，不在源时间排序保证之内。bulk 零时间仍按现状拒绝。
|
||||
- 非零事件**严格早于**目标桶 Created 才成功/no-op 并记录 before-created，heal 对这种目标跳过。等于目标 Created 的 live 事件可更新仍是 baseline 的目标字段，时间仍保存为源 Created，不盖上到达时间；同时间的空/nil 只算空 baseline，不能删除配置。不同桶世代不能自动合并，需要运维处理，不纳入收敛承诺。
|
||||
- 排序先比较是否为真实状态：任何真实 live/tombstone 都胜 baseline，不能让较晚创建的默认值压过较早的真实修改。真实状态之间再比较源时间，同时间 tombstone 胜 live、live/live 的**稳定比较键字节序较大者胜**。baseline-live 只胜空 baseline，或在 baseline-live 之间按同一稳定键较大者胜；永远不能覆盖真实 live/tombstone。所有候选都是 baseline-live 时仍可确定性初始化并收敛；全部为空 baseline 才安静 found=false。键、状态级别和源时间相同为 no-op。同状态来源不参与持久化冲突裁决。
|
||||
- Quota 使用现有解析结果的 JSON 编码作为比较键。Policy 在 Server 内生成确定性比较表示：既有解析器校验/去重后，对其**完整 JSON 树**的对象键和集合数组递归排序，统一覆盖 Statement、Action/NotAction、Resource/NotResource、Principal、Condition；保留数字类型和精度。比较键必须是已解析策略的纯函数，同一配置从两个站点分别解析也必须得到相同键。普通 `json.Marshal(BucketPolicy)` 不稳定，不能直接作键；不增加依赖不支持的 NotPrincipal 语法，不改 wire/schema。新状态比较仅使用这一套键：不把忽略 Sid 且对 Statement 顺序敏感的 `BucketPolicy.Equals` 再叠加为另一套判等规则，既有公开统计对 Equals 的使用保持不变。
|
||||
- XML 使用有效文档字节，保留大小写和实际内容；Versioning 先应用下述现有 Object Lock 约束。比较器不能依靠字节序方向来补偿保存阶段的隐式改写。
|
||||
|
||||
### 3. 先得到有效状态，再比较与提交
|
||||
|
||||
原始读取、类型处理、比较、修改及保存均在现有 `metadata.lock` 内。内部入口必须传递现有 lock context，避免 legacy migration 再次取锁。
|
||||
|
||||
- 提取并复用 `parseAllConfigs` 已有的 Object Lock→Enabled Versioning 归一规则，使比较视图和真正保存一致；不得扩大 suspend、prefix exclusion、retention 的限制。bulk 先确定实际接受的 Object Lock，再比较该约束下的 Versioning，并在最终提交前应用同一规则。
|
||||
- 以归一化后的有效 `(kind, key, time)` 判定变化；更新了时间也算变化。完全重复不保存、不通知；一次 bulk 校验失败不保存部分结果；成功至多保存一次，解锁后通知。
|
||||
- 可删除字段清空必须基于现有 parse=false 的新加载对象，不能在已经解析且仍持有旧 quota 的对象上执行 Update(nil)。bulk 保留原始读取再解析保存的方式。不要顺手修改 Quota getter 或所有 `parseAllConfigs` 空分支。
|
||||
- 保存函数必须让需要发送 hook 的调用方拿到**本次提交的最终快照**，不能先解锁再读取“最新”状态拼接旧时间。最小做法是让内部 `saveMetadata` 接收元数据指针并回写 Save 的归一化结果，机械更新现有少量调用；对外 `Update/Delete` 签名不变，新增内部提交结果仅供需要该快照的本地 handler/import 使用。不得原地修改已发布到缓存的引用字段。
|
||||
- 保留现有物理桶存在检查、删除锁序、迁移、后台通知上下文。真实历史桶 Created 为零时仅走少见的物理桶 Created 补齐路径；物理桶缺失返回现有错误；创建时间仍未知则不伪造到达时间，报告 indeterminate。
|
||||
|
||||
## 三个实现提交
|
||||
|
||||
### 提交 1：原子 apply、发送一致性与本地时间
|
||||
|
||||
主要文件：`cmd/bucket-metadata-sys.go`、`cmd/bucket-metadata.go`、`cmd/site-replication.go`、`cmd/admin-bucket-handlers.go`，以及实际需要提交快照的本地配置 handler。
|
||||
|
||||
1. 在现有 update/delete 内部路径增加源时间、状态比较和提交结果；公开签名不变。六个 peer handler 移除锁外 getter 判旧，锁内持久化原始源时间。保留 Object Lock 的 legacy Tags 字段载荷回退。
|
||||
2. bulk 对明确提供的六类字段在已有锁内逐字段比较，再原子保存；未提供字段不动，不能循环调用会重入锁的公开 handler。保留 CORS 独立分支与既有行为。
|
||||
3. 六类本地实际写入在锁内分配 `max(UTCNow(), Created+1ns, 当前字段时间+1ns)`。其他类型不变。`enablePeerBucketVersioning` 的实际变更也使用它，只有缺失配置的创建 bootstrap 继续 Created 默认值。
|
||||
4. quota 本地 PUT 保留零值文档并原样表示该语义；Policy 空策略本地与 peer 一致走删除。需要归一化的本地 handler 从本次提交快照生成 hook；其他内容不发生归一变化的路径可保留既有编码，但必须满足三元组一致性。
|
||||
5. 导入在每桶最终提交锁内，为本次涉及的六类字段生成共同 commitAt，严格大于 Created 和这些字段当前时间且不早于锁内现在。该时间同时用于落盘和 bulk hook，不能沿用 ZIP 开始时间。bulk hook 从最终提交快照构建；若导入的空 Policy 已归一成删除，另外使用现有专用 Policy nil 事件表达它，不能因 `omitempty` 漏发。未导入字段不改，Object Lock 的既有派生 Versioning 修正保留原时间语义；CORS 继续独立时间/事件，其他字段不参与该上界。
|
||||
|
||||
完成条件：六类源时间落盘；旧事件不能越过锁覆盖新状态；四类删除不会被旧 PUT 复活；真实 wire、落盘和出站状态一致；重复无写入；bulk 与 import 没有绕过排序或静默遗漏删除。
|
||||
|
||||
### 提交 2：heal 选源与应用同规则
|
||||
|
||||
主要文件：`cmd/site-replication.go`。
|
||||
|
||||
1. 先过滤空 baseline、无效来源、严格早于自身 Created 的字段和 update-only 空配置，再按上述强弱排序选最大状态；无候选必须显式返回 found=false。保留历史 baseline-live 的初次同步和 heal 能力，消除六处“先 seed map 首项，再过滤默认值”的写法。
|
||||
2. 选源和目标遍历都跳过 `info.Sites` 中不存在的 deployment ID，包括不可达站点的空 ID 占位项；单一 peer 失败记录后继续其它目标，不因 map 顺序放弃健康站点。不改变状态计数或新建重试机制。
|
||||
3. 本地 heal 使用提交 1 的源时间 update/delete；远端仍用原有逐类型 RPC，全部携带源时间，补齐 Tag 的 UpdatedAt。
|
||||
4. 比较完整有效状态，去掉公开 mismatch/payload-only 对写入的门控；同内容较旧时间也同步。对已归一且相同的目标不写入、不发 RPC。Versioning 比较使用与该站点 Object Lock 一致的有效文档；全站点 Lock 状态补齐后不再因旧原始文档产生空转。
|
||||
5. 保留 #91 的计数与公开字段；创建世代冲突、无可用来源通过有限诊断解释。已知 baseline 且各站点无实质差异时安静 no-op。
|
||||
|
||||
完成条件：map 顺序不影响结果；默认空值不再删真配置；历史 baseline-live 可以初始化新站点、不能覆盖真实状态；同内容不同时间、同时间冲突最终一致；Tag 时间完整；Quota 删除后磁盘、缓存、重载一致；不可达占位项不阻断健康目标；完整状态已可见且稳定时，第二轮 heal 无写入/广播。
|
||||
|
||||
### 提交 3：新增删除传播与有界诊断
|
||||
|
||||
只增加一个启动开关，暂定 `MINIO_SITE_REPLICATION_METADATA_TOMBSTONES=off/on`，默认 off；实现沿用现有 env 开关写法，不做能力协商。
|
||||
|
||||
| 行为 | off：升级阶段 | on：所有参与节点修复后 |
|
||||
| --- | --- | --- |
|
||||
| 带时间 peer apply、锁内排序与 heal | 使用提交 1/2 | 同左 |
|
||||
| 专用事件零时间 | 兼容应用并记录 legacy-zero | 同左，不新增协议拒绝 |
|
||||
| Tags/SSE/Quota nil payload 时间导出 | 保留旧版条件导出 | 导出 `time > Created` 的真实删除时间 |
|
||||
| Policy 时间导出 | 保留已有行为 | 保留已有行为 |
|
||||
| 初次同步的真实删除 | 保留已有行为 | Policy/Tags/SSE/Quota 都发送专用 nil + source time 事件 |
|
||||
|
||||
开关只控制**新增**删除信息的导出/初次发送，普通本地删除事件照常复制。**off 不等于禁止删除传播：Policy 墓碑原本已导出，修复后在 off 下也照常参与 heal；Tags/SSE/Quota 的新增墓碑信息才被门控。** off 期间这些字段的隐藏墓碑会使 heal 继续尝试过时 RPC，由接收端排序拒绝；这是状态不可见时的已知代价，不承诺第二轮零 RPC，也不为这种正常拒绝增加每轮日志。
|
||||
|
||||
开关不检测或证明远端能力。启用条件是所有参与站点的全部节点已经修复，同一站点配置一致，旧请求排空；旧节点仍在线时保持 off。此隔离有实证依据：旧版接到新增 Quota heal 墓碑会留下已解析缓存残留。
|
||||
|
||||
日志仅保留三个实际原因：legacy-zero、before-created、indeterminate（未知创建时间、缺失/不可达来源或有实际差异却无可用候选）。精确重复、正常旧事件和成功裁决的同时间冲突不记警告。复用 `LogOnceIf`，以稳定的桶/字段/原因作为 key，**错误正文也必须稳定**；变化的时间与 peer 详情放入日志 ReqInfo，沿用现有每小时清理，不新增限流框架、不输出完整策略。
|
||||
|
||||
Server 文档解释启用顺序和回滚：降级前所有修复节点先关开关，然后滚动降级；旧软件缺陷会恢复。点名旧版 Tag heal 无 UpdatedAt 的来源。旧版到达时间污染、legacy-zero 产生的新本地时间以及创建世代分歧无法自动还原；操作者查看状态后在权威站点重新提交需要纠正的配置/删除。历史世代冲突先处理桶身份，不能靠任意站点强刷绕过创建保护。
|
||||
|
||||
## 最小验收矩阵
|
||||
|
||||
| 组 | 必须覆盖 | 证据方式 |
|
||||
| --- | --- | --- |
|
||||
| T1 | 六类 PUT 源时间；四类 DELETE；旧事件不回退；重复无写入；零 quota 三元组一致；带合法 Version 的空 Policy PUT 成功、GET NotFound、专用删除事件与落盘一致 | 真实 admin/S3 路由、ErasureSD/Erasure16、磁盘重载、RPC 捕获 |
|
||||
| T2 | 同时间两种到达顺序结果相同、删除优先；Policy 多集合及 NotAction/NotResource/Condition 反复编码与排列后，两站点独立解析得到相同键；Sid 差异及大整数不被错误合并 | 确定性比较器测试与代表性真实 handler |
|
||||
| T3 | Versioning/Object Lock nil/空 no-op；legacy Tags 载荷回退；Object Lock + prefix exclusion/ExcludeFolders 在普通写、peer、bulk/import 后有效状态一致，第二轮 heal 无额外写入 | 原有 #76/#78 回归加针对性用例 |
|
||||
| T4 | 锁前旧事件排队、较新写先提交后旧事件不得覆盖；不同字段并发均保留 | 复用已有 `lockBucketMetadataAcquireHook` / RMW 屏障、两种 ObjectLayer、目标 race |
|
||||
| T5 | bulk 新/旧/缺省字段混合；真实 JSON 编解码的 nil、空 RawMessage、显式 null、空字符串、空策略、零 quota；非法字段不部分保存；只导入 tags 不修改 Policy/Quota | 真实 bulk 路由、缓存与磁盘 |
|
||||
| T6 | 本地时间胜过已有未来时间；相邻提交不倒序；ZIP 导入期间插入写入，最终落盘和发出事件的状态与时间一致，空 Policy 删除不漏发 | 本地 API、import 路由与 RPC 捕获 |
|
||||
| T7 | map 排列、空 baseline/全无候选；baseline-live 初始化与同级冲突收敛，但不能覆盖真实 live/tombstone；nil@Created 不删除配置；空 update-only；Tag 时间、Quota 清缓存、空 ID、世代冲突 | 确定性 heal 本地/远端用例 |
|
||||
| T8 | 墓碑经保存/缓存失效/重启仍有效；缺桶、排队写入、零 Created；历史字段时间全部等于 Created 的桶经初次同步和一轮 heal 后一致；on/off 与 legacy-zero，off 下 Policy 仍 heal、其它隐藏墓碑允许被拒 RPC 但无每轮警告 | ObjectLayer 与进程内旧版 wire/SRInfo 模拟；复用既有删除/迁移回归 |
|
||||
| T9 | 修复版双站点短暂断线、漏发/重复/乱序后六类合法配置收敛；删除传播启用后第二轮稳定无写入；日志确实有界 | 隔离双站点实验，不把未知桶世代或零时间事件算成通过 |
|
||||
|
||||
固定旧版与修复版混合进程仅作一次性升级冒烟，不新增为长期提交门槛。将已有审计用例改成正式确定性回归，不能把遍历 map 的概率复现直接提交。先记录未修复失败，再验证通过；复用原有 Object Lock、adoption、metadata-lock、计数、CORS 回归，并在实现后运行目标 race、仓库必需检查和完整 Go CI。方案审查、局部测试、双站点结果、合并与发布是不同证据。
|
||||
|
||||
## 作者复核结论
|
||||
|
||||
三个提交分别处理写入正确性、heal 收敛和新增删除信息的升级边界；每项对应已证实缺陷或本次修复直接触及的实际路径。缩减了拒绝零时间的新协议行为、混合版本长期测试门槛和新锁屏障；保留已有持久化、通知与缓存语义。
|
||||
|
||||
Opus 第二轮已确认首轮 R1/R2/R3 实质关闭，并确认作者的 Policy 编码和日志去重补查。v3 修正第二轮新增的历史桶 baseline-live 初始化回归，补齐相关验收与 off 模式说明，保留三个实现提交。最后针对性复审返回前不标记为可进入实现；后续仍须用实现期测试证明，而非把本计划当作修复完成。
|
||||
@@ -0,0 +1,121 @@
|
||||
# Issue #77 最小充分修复计划
|
||||
|
||||
版本：v4，2026-09-12。状态：Opus 已对 v3 给出 GO_WITH_NONBLOCKING_NOTES、0 阻断；作者追加实测发现接管时默认时间需随 Created 保持 baseline，补入提交 1 后待该增量复核。
|
||||
|
||||
基准：`pgsty/silo` main `5c576581631561c446f30ae5b566f0aa793adc1c`。本轮交付是方案与评审，不表示已经实现、合并或发布。问题证据见 [当前核验](../../issue-77-current.md)，意见处置见 [首轮处置](decisions-v2.md)、[第二轮处置](decisions-v3.md)、[接管边界补查](decisions-v4.md)。
|
||||
|
||||
## 目标与边界
|
||||
|
||||
修复 Policy、Tags、SSE、Quota、Versioning、Object Lock 六类桶配置的源时间丢失、锁外判旧、heal 错选源和删除传播不完整。覆盖普通本地写入、专用 peer 事件、bulk/import、local/remote heal、元数据导出与初次同步。
|
||||
|
||||
在修复 PGSTY 栈、同一已知桶世代、合法带源时间事件的范围内，使重复、乱序和漏发后的状态能够确定性收敛。开关关闭期间新增删除信息不可见，不承诺完整删除收敛；无时间旧事件、旧版污染时间和桶创建世代冲突需要单独解释，不能自动推断历史真相。
|
||||
|
||||
不重做 #91 的计数、#76 的 Object Lock wire 修复、#78 的桶接管、#103/#156 的锁与删除保护。不改变 CORS、Lifecycle/expiry、notification、对象复制、MRF、resync、IAM 的语义；不改存储 schema、SDK、Console、mcli 或 silo-pkg，不新建能力协商、复制框架、锁或重试系统。
|
||||
|
||||
## 行为契约
|
||||
|
||||
### 1. 明确事件、缺省值与删除
|
||||
|
||||
| 类型 | 专用事件 | bulk 字段未提供 | bulk 字段明确提供 |
|
||||
| --- | --- | --- | --- |
|
||||
| Policy | nil 为删除；沿用现有解析器 `IsEmpty()` 为删除 | 保留 | 非空 RawMessage 按现有解析器处理；语义空策略归一为删除 |
|
||||
| Quota | nil 为删除；非 nil 按现有 quota 解析器处理 | 保留 | 非空 RawMessage 按现有解析器处理，零 quota 仍是 live 文档 |
|
||||
| Tags / SSE | nil 或 base64 解码后空内容为删除 | 保留 | 空字符串为删除，其他内容按原规则解码、校验 |
|
||||
| Versioning / Object Lock | nil/空内容为 no-op | 保留 | nil/空内容仍为 no-op，不能清空配置 |
|
||||
|
||||
“未提供”必须依据真实 wire 类型判定：Policy/Quota 的 `json.RawMessage` 为 nil 或空切片时经 `omitempty` 省略；**显式 JSON `null` 解码后是非 nil 的 `[]byte("null")`**，不能与缺省混淆。按现有解析器，Policy `null` 是语义空策略，Quota `null` 是零值 quota 文档。`*string` 类型的 JSON `null` 则解码为 nil。不得使用统一的 `len(payload)==0 => 删除` 来处理 bulk。
|
||||
|
||||
合法 `{}`/零值 quota 保持 live；取消普通 quota PUT 出站时“零配额改写为 nil”的逻辑，保存与发送同一个语义状态。Policy 保留现有专用 peer 的“空策略=删除”解释，本地 PUT、导入和 bulk 统一归一为同样的删除状态；这是需要写入兼容说明的小范围变化：空策略本地立即按删除处理，GET 返回既有 NotFound 行为，不再先保留空文档、等复制后才被清除。
|
||||
|
||||
**同一次操作的落盘状态与出站事件，经同一归一规则后，必须具有相同的 `(kind, payload key, source time)`。** JSON 的无意义编码次序不要求字节相同；Object Lock 改写后的有效 Versioning 文档必须来自提交结果。
|
||||
|
||||
### 2. 统一状态与排序
|
||||
|
||||
内部仅需一个小状态表示：baseline / live / tombstone，以及比较键和字段源时间。baseline 可携带历史有效配置，但没有真实修改时间；它绝不能被当成删除。复用 CORS 已有设计思路，不改 CORS 本身或扩展为通用框架。
|
||||
|
||||
- 使用 `BucketMetadata` 原始字段时间；字段时间为零时在比较视图中补为 Created，与 `defaultTimestamps()` 一致，不借用会隐藏墓碑时间的 getter 或整记录 `lastUpdate()`。
|
||||
- 在已知 Created 下，零字段时间回退后等于 Created 的状态是 baseline：有有效非空配置的 baseline-live 可作为初始化候选；空 baseline 只是缺省值，不能作为删除或 heal 来源。真正严格早于自身 Created 的字段不是候选；Versioning/Object Lock 的空候选无论时间如何都不参与选源。真实 live/tombstone 的时间必须大于 Created。
|
||||
- 专用 peer 的零时间保留兼容例外：锁内按本地新操作分配时间并限频记录 legacy-zero；不受删除传播开关影响，不在源时间排序保证之内。bulk 零时间仍按现状拒绝。
|
||||
- 非零事件**严格早于**目标桶 Created 才成功/no-op 并记录 before-created，heal 对这种目标跳过。等于目标 Created 的 live 事件可更新仍是 baseline 的目标字段，时间仍保存为源 Created，不盖上到达时间；同时间的空/nil 只算空 baseline，不能删除配置。不同桶世代不能自动合并，需要运维处理，不纳入收敛承诺。
|
||||
- 排序先比较是否为真实状态：任何真实 live/tombstone 都胜 baseline，不能让较晚创建的默认值压过较早的真实修改。真实状态之间再比较源时间，同时间 tombstone 胜 live、live/live 的**稳定比较键字节序较大者胜**。baseline-live 只胜空 baseline，或在 baseline-live 之间按同一稳定键较大者胜；永远不能覆盖真实 live/tombstone。所有候选都是 baseline-live 时仍可确定性初始化并收敛；全部为空 baseline 才安静 found=false。键、状态级别和源时间相同为 no-op。deployment ID 不参与上述比较，也不作为新字段保存。
|
||||
- Quota 使用现有解析结果的 JSON 编码作为比较键。Policy 在 Server 内生成确定性比较表示：既有解析器校验/去重后，对其**完整 JSON 树**的对象键和集合数组递归排序，统一覆盖 Statement、Action/NotAction、Resource/NotResource、Principal、Condition；保留数字类型和精度。比较键必须是已解析策略的纯函数，同一配置从两个站点分别解析也必须得到相同键。普通 `json.Marshal(BucketPolicy)` 不稳定，不能直接作键；不增加依赖不支持的 NotPrincipal 语法，不改 wire/schema。新状态比较仅使用这一套键：不把忽略 Sid 且对 Statement 顺序敏感的 `BucketPolicy.Equals` 再叠加为另一套判等规则，既有公开统计对 Equals 的使用保持不变。
|
||||
- XML 使用有效文档字节，保留大小写和实际内容；Versioning 先应用下述现有 Object Lock 约束。比较器不能依靠字节序方向来补偿保存阶段的隐式改写。
|
||||
|
||||
### 3. 先得到有效状态，再比较与提交
|
||||
|
||||
原始读取、类型处理、比较、修改及保存均在现有 `metadata.lock` 内。内部入口必须传递现有 lock context，避免 legacy migration 再次取锁。
|
||||
|
||||
- 提取并复用 `parseAllConfigs` 已有的 Object Lock→Enabled Versioning 归一规则，使比较视图和真正保存一致；不得扩大 suspend、prefix exclusion、retention 的限制。bulk 先确定实际接受的 Object Lock，再比较该约束下的 Versioning，并在最终提交前应用同一规则。
|
||||
- 以归一化后的有效 `(kind, key, time)` 判定变化；更新了时间也算变化。完全重复不保存、不通知；一次 bulk 校验失败不保存部分结果；成功至多保存一次，解锁后通知。
|
||||
- 可删除字段清空必须基于现有 parse=false 的新加载对象，不能在已经解析且仍持有旧 quota 的对象上执行 Update(nil)。bulk 保留原始读取再解析保存的方式。不要顺手修改 Quota getter 或所有 `parseAllConfigs` 空分支。
|
||||
- 保存函数必须让需要发送 hook 的调用方拿到**本次提交的最终快照**，不能先解锁再读取“最新”状态拼接旧时间。最小做法是让内部 `saveMetadata` 接收元数据指针并回写 Save 的归一化结果，机械更新现有少量调用；对外 `Update/Delete` 签名不变，新增内部提交结果仅供需要该快照的本地 handler/import 使用。不得原地修改已发布到缓存的引用字段。
|
||||
- 保留现有物理桶存在检查、删除锁序、迁移、后台通知上下文。真实历史桶 Created 为零时仅走少见的物理桶 Created 补齐路径；物理桶缺失返回现有错误；创建时间仍未知则不伪造到达时间，报告 indeterminate。
|
||||
|
||||
## 三个实现提交
|
||||
|
||||
### 提交 1：原子 apply、发送一致性与本地时间
|
||||
|
||||
主要文件：`cmd/bucket-metadata-sys.go`、`cmd/bucket-metadata.go`、`cmd/site-replication.go`、`cmd/admin-bucket-handlers.go`，以及实际需要提交快照的本地配置 handler。
|
||||
|
||||
1. 在现有 update/delete 内部路径增加源时间、状态比较和提交结果；公开签名不变。六个 peer handler 移除锁外 getter 判旧，锁内持久化原始源时间。保留 Object Lock 的 legacy Tags 字段载荷回退。
|
||||
2. bulk 对明确提供的六类字段在已有锁内逐字段比较，再原子保存；未提供字段不动，不能循环调用会重入锁的公开 handler。保留 CORS 独立分支与既有行为。
|
||||
3. 六类本地实际写入在锁内分配 `max(UTCNow(), Created+1ns, 当前字段时间+1ns)`。其他类型不变。`enablePeerBucketVersioning` 的实际变更也使用它，只有缺失配置的创建 bootstrap 继续 Created 默认值。
|
||||
接管已有桶时保留原 Created，再执行现有 `SetCreatedAt`；如果 Created 改变，仅将这六类中原本为零或等于原 Created 的默认字段时间调整到新 Created，随后再做既有 versioning/lock bootstrap。原本晚于旧 Created 的真实修改/删除时间及其配置保持不变。不能仅凭 payload 为 nil 判断默认值。该小分支用于防止原默认时间因 Created 前移被误识别为墓碑，复用已有接管锁，不重做 #78 的配置保护。
|
||||
4. quota 本地 PUT 保留零值文档并原样表示该语义；Policy 空策略本地与 peer 一致走删除。需要归一化的本地 handler 从本次提交快照生成 hook；其他内容不发生归一变化的路径可保留既有编码，但必须满足三元组一致性。
|
||||
5. 导入在每桶最终提交锁内，为本次涉及的六类字段生成共同 commitAt，严格大于 Created 和这些字段当前时间且不早于锁内现在。该时间同时用于落盘和 bulk hook，不能沿用 ZIP 开始时间。bulk hook 从最终提交快照构建；若导入的空 Policy 已归一成删除，另外使用现有专用 Policy nil 事件表达它，不能因 `omitempty` 漏发。未导入字段不改，Object Lock 的既有派生 Versioning 修正保留原时间语义；CORS 继续独立时间/事件，其他字段不参与该上界。
|
||||
|
||||
完成条件：六类源时间落盘；旧事件不能越过锁覆盖新状态；四类删除不会被旧 PUT 复活；真实 wire、落盘和出站状态一致；重复无写入；bulk 与 import 没有绕过排序或静默遗漏删除。
|
||||
|
||||
### 提交 2：heal 选源与应用同规则
|
||||
|
||||
主要文件：`cmd/site-replication.go`。
|
||||
|
||||
1. 先过滤空 baseline、无效来源、严格早于自身 Created 的字段和 update-only 空配置，再按上述强弱排序选最大状态；无候选必须显式返回 found=false。保留历史 baseline-live 的初次同步和 heal 能力，消除六处“先 seed map 首项，再过滤默认值”的写法。
|
||||
2. 选源和目标遍历都跳过 `info.Sites` 中不存在的 deployment ID，包括不可达站点的空 ID 占位项；单一 peer 失败记录后继续其它目标，不因 map 顺序放弃健康站点。不改变状态计数或新建重试机制。
|
||||
3. 本地 heal 使用提交 1 的源时间 update/delete；远端仍用原有逐类型 RPC，全部携带源时间，补齐 Tag 的 UpdatedAt。
|
||||
4. 比较完整有效状态，去掉公开 mismatch/payload-only 对写入的门控；同内容较旧时间也同步。对已归一且相同的目标不写入、不发 RPC。Versioning 比较使用与该站点 Object Lock 一致的有效文档；全站点 Lock 状态补齐后不再因旧原始文档产生空转。
|
||||
5. 保留 #91 的计数与公开字段；创建世代冲突、无可用来源通过有限诊断解释。已知 baseline 且各站点无实质差异时安静 no-op。
|
||||
|
||||
完成条件：map 顺序不影响结果；默认空值不再删真配置；历史 baseline-live 可以初始化新站点、不能覆盖真实状态；同内容不同时间、同时间冲突最终一致；Tag 时间完整；Quota 删除后磁盘、缓存、重载一致；不可达占位项不阻断健康目标；完整状态已可见且稳定时，第二轮 heal 无写入/广播。
|
||||
|
||||
### 提交 3：新增删除传播与有界诊断
|
||||
|
||||
只增加一个启动开关，暂定 `MINIO_SITE_REPLICATION_METADATA_TOMBSTONES=off/on`，默认 off；实现沿用现有 env 开关写法，不做能力协商。
|
||||
|
||||
| 行为 | off：升级阶段 | on：所有参与节点修复后 |
|
||||
| --- | --- | --- |
|
||||
| 带时间 peer apply、锁内排序与 heal | 使用提交 1/2 | 同左 |
|
||||
| 专用事件零时间 | 兼容应用并记录 legacy-zero | 同左，不新增协议拒绝 |
|
||||
| Tags/SSE/Quota nil payload 时间导出 | 保留旧版条件导出 | 导出 `time > Created` 的真实删除时间 |
|
||||
| Policy 时间导出 | 保留已有行为 | 保留已有行为 |
|
||||
| 初次同步的真实删除 | 保留已有行为 | Policy/Tags/SSE/Quota 都发送专用 nil + source time 事件 |
|
||||
|
||||
开关只控制**新增**删除信息的导出/初次发送，普通本地删除事件照常复制。**off 不等于禁止删除传播：Policy 墓碑原本已导出，修复后在 off 下也照常参与 heal；Tags/SSE/Quota 的新增墓碑信息才被门控。** off 期间这些字段的隐藏墓碑会使 heal 继续尝试过时 RPC，由接收端排序拒绝；这是状态不可见时的已知代价，不承诺第二轮零 RPC，也不为这种正常拒绝增加每轮日志。
|
||||
|
||||
开关不检测或证明远端能力。启用条件是所有参与站点的全部节点已经修复，同一站点配置一致，旧请求排空；旧节点仍在线时保持 off。此隔离有实证依据：旧版接到新增 Quota heal 墓碑会留下已解析缓存残留。
|
||||
|
||||
日志仅保留三个实际原因：legacy-zero、before-created、indeterminate（未知创建时间、缺失/不可达来源或有实际差异却无可用候选）。精确重复、正常旧事件和成功裁决的同时间冲突不记警告。复用 `LogOnceIf`，以稳定的桶/字段/原因作为 key，**错误正文也必须稳定**；变化的时间与 peer 详情放入日志 ReqInfo，沿用现有每小时清理，不新增限流框架、不输出完整策略。
|
||||
|
||||
Server 文档解释启用顺序和回滚：降级前所有修复节点先关开关，然后滚动降级；旧软件缺陷会恢复。点名旧版 Tag heal 无 UpdatedAt 的来源。旧版到达时间污染、legacy-zero 产生的新本地时间以及创建世代分歧无法自动还原；操作者查看状态后在权威站点重新提交需要纠正的配置/删除。历史世代冲突先处理桶身份，不能靠任意站点强刷绕过创建保护。
|
||||
|
||||
## 最小验收矩阵
|
||||
|
||||
| 组 | 必须覆盖 | 证据方式 |
|
||||
| --- | --- | --- |
|
||||
| T1 | 六类 PUT 源时间；四类 DELETE；旧事件不回退；重复无写入；零 quota 三元组一致；带合法 Version 的空 Policy PUT 成功、GET NotFound、专用删除事件与落盘一致 | 真实 admin/S3 路由、ErasureSD/Erasure16、磁盘重载、RPC 捕获 |
|
||||
| T2 | 同时间两种到达顺序结果相同、删除优先；Policy 多集合及 NotAction/NotResource/Condition 反复编码与排列后，两站点独立解析得到相同键；Sid 差异及大整数不被错误合并 | 确定性比较器测试与代表性真实 handler |
|
||||
| T3 | Versioning/Object Lock nil/空 no-op；legacy Tags 载荷回退；Object Lock + prefix exclusion/ExcludeFolders 在普通写、peer、bulk/import 后有效状态一致，第二轮 heal 无额外写入 | 原有 #76/#78 回归加针对性用例 |
|
||||
| T4 | 锁前旧事件排队、较新写先提交后旧事件不得覆盖；不同字段并发均保留 | 复用已有 `lockBucketMetadataAcquireHook` / RMW 屏障、两种 ObjectLayer、目标 race |
|
||||
| T5 | bulk 新/旧/缺省字段混合；真实 JSON 编解码的 nil、空 RawMessage、显式 null、空字符串、空策略、零 quota；非法字段不部分保存；只导入 tags 不修改 Policy/Quota | 真实 bulk 路由、缓存与磁盘 |
|
||||
| T6 | 本地时间胜过已有未来时间；相邻提交不倒序；ZIP 导入期间插入写入，最终落盘和发出事件的状态与时间一致，空 Policy 删除不漏发 | 本地 API、import 路由与 RPC 捕获 |
|
||||
| T7 | map 排列、空 baseline/全无候选；baseline-live 初始化与同级冲突收敛，但不能覆盖真实 live/tombstone；nil@Created 不删除配置；空 update-only；Tag 时间、Quota 清缓存、空 ID、世代冲突 | 确定性 heal 本地/远端用例 |
|
||||
| T8 | 墓碑经保存/缓存失效/重启仍有效；缺桶、排队写入、零 Created；历史字段时间等于 Created 的桶经初次同步、一轮 heal 后一致，第二轮无写入/广播；接管前移 Created 后默认时间仍是 baseline，真实 PUT/DELETE 时间不变；on/off 与 legacy-zero，off 下 Policy 仍 heal、其它隐藏墓碑允许被拒 RPC 但无每轮警告 | ObjectLayer 与进程内旧版 wire/SRInfo 模拟；复用既有删除/迁移回归 |
|
||||
| T9 | 修复版双站点短暂断线、漏发/重复/乱序后六类合法配置收敛；删除传播启用后第二轮稳定无写入；日志确实有界 | 隔离双站点实验，不把未知桶世代或零时间事件算成通过 |
|
||||
|
||||
固定旧版与修复版混合进程仅作一次性升级冒烟，不新增为长期提交门槛。将已有审计用例改成正式确定性回归，不能把遍历 map 的概率复现直接提交。先记录未修复失败，再验证通过；复用原有 Object Lock、adoption、metadata-lock、计数、CORS 回归，并在实现后运行目标 race、仓库必需检查和完整 Go CI。方案审查、局部测试、双站点结果、合并与发布是不同证据。
|
||||
|
||||
## 作者复核结论
|
||||
|
||||
三个提交分别处理写入正确性、heal 收敛和新增删除信息的升级边界；每项对应已证实缺陷或本次修复直接触及的实际路径。缩减了拒绝零时间的新协议行为、混合版本长期测试门槛和新锁屏障；保留已有持久化、通知与缓存语义。
|
||||
|
||||
Opus 第二轮已确认首轮 R1/R2/R3 实质关闭，第三轮确认 v3 的历史桶初始化边界修正，给出 0 阻断。作者随后在两个真实 ObjectLayer 上补查到接管改变 Created 会把旧默认时间变成假墓碑，v4 仅补充默认时间随接管保持 baseline 的分支与回归。所有变更仍在三个实现提交内；该增量复审返回前不标记最终方案通过，后续仍须用实现期测试证明，而非把本计划当作修复完成。
|
||||
@@ -0,0 +1,14 @@
|
||||
package main
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"github.com/pgsty/silo-pkg/v3/policy"
|
||||
)
|
||||
func main() {
|
||||
p,err:=policy.ParseBucketPolicyConfig(strings.NewReader(`{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":["s3:GetObject","s3:PutObject"],"Resource":["arn:aws:s3:::issue77-test/a/*","arn:aws:s3:::issue77-test/b/*"]}]}`),"issue77-test")
|
||||
if err!=nil {panic(err)}
|
||||
variants:=map[string]int{}
|
||||
for i:=0;i<100;i++ {b,err:=json.Marshal(p);if err!=nil{panic(err)};variants[string(b)]++}
|
||||
fmt.Printf("100 encodings of the same parsed BucketPolicy produced %d distinct byte sequences\n",len(variants))
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
package main
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"github.com/minio/madmin-go/v3"
|
||||
"github.com/pgsty/silo-pkg/v3/policy"
|
||||
)
|
||||
func main() {
|
||||
for _, raw := range []string{`{"bucket":"b"}`, `{"bucket":"b","policy":null,"quota":null}`, `{"bucket":"b","policy":{"Version":"2012-10-17","Statement":[]},"quota":{}}`} {
|
||||
var x madmin.SRBucketMeta
|
||||
if err:=json.Unmarshal([]byte(raw),&x);err!=nil{panic(err)}
|
||||
fmt.Printf("wire=%s\nPolicy nil=%t bytes=%q; Quota nil=%t bytes=%q\n",raw,x.Policy==nil,[]byte(x.Policy),x.Quota==nil,[]byte(x.Quota))
|
||||
if len(x.Policy)>0 && !bytes.Equal(x.Policy,[]byte("null")) {
|
||||
p,err:=policy.ParseBucketPolicyConfig(bytes.NewReader(x.Policy),"b")
|
||||
if err!=nil{panic(err)}
|
||||
fmt.Printf("Policy parses successfully, IsEmpty=%t\n",p.IsEmpty())
|
||||
}
|
||||
}
|
||||
for _, v := range []json.RawMessage{nil,{},[]byte("null")} {
|
||||
b,err:=json.Marshal(madmin.SRBucketMeta{Bucket:"b",Policy:v});if err!=nil{panic(err)}
|
||||
fmt.Printf("encoded raw=%q -> %s\n",[]byte(v),b)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
wire={"bucket":"b"}
|
||||
Policy nil=true bytes=""; Quota nil=true bytes=""
|
||||
wire={"bucket":"b","policy":null,"quota":null}
|
||||
Policy nil=false bytes="null"; Quota nil=false bytes="null"
|
||||
wire={"bucket":"b","policy":{"Version":"2012-10-17","Statement":[]},"quota":{}}
|
||||
Policy nil=false bytes="{\"Version\":\"2012-10-17\",\"Statement\":[]}"; Quota nil=false bytes="{}"
|
||||
Policy parses successfully, IsEmpty=true
|
||||
encoded raw="" -> {"type":"","bucket":"b","updatedAt":"0001-01-01T00:00:00Z","expiryUpdatedAt":"0001-01-01T00:00:00Z"}
|
||||
encoded raw="" -> {"type":"","bucket":"b","updatedAt":"0001-01-01T00:00:00Z","expiryUpdatedAt":"0001-01-01T00:00:00Z"}
|
||||
encoded raw="null" -> {"type":"","bucket":"b","policy":null,"updatedAt":"0001-01-01T00:00:00Z","expiryUpdatedAt":"0001-01-01T00:00:00Z"}
|
||||
Reference in New Issue
Block a user