pnpr 共享构建产物槽位一次性写入机制：从 409 Conflict 到幂等重试的完整实现

pnpr 共享构建产物槽位一次性写入机制：从 409 Conflict 到幂等重试的完整实现

【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm

导读

在 pnpm 的 Rust 侧基础设施 pnpr 中，共享构建产物存储（shared artifact store）承担着缓存与复用 native addon、工作区任务产物等构建结果的职责。.changeset/artifact-slots-are-write-once.md这一变更声明了该存储的一项核心语义：已发布的构建产物槽位是一次性写入（write-once）的——同一个输入键（input key）与同一组兼容性约束（compatibility constraints）只能对应一个产物，向已被占用的槽位发布不同内容会得到409 Conflict，与重新发布同名name@version的行为一致；而重复发布完全相同的内容仍被视为幂等重试并成功返回。阅读本文后，你将掌握该不可变语义的设计动机、槽位与作用域的底层判定原理、幂等与冲突的区分逻辑，以及升级已有 registry 时旧数据如何被安全保留。

变更声明解读：一段 changeset 背后的完整语义

该 changeset 属于@pnpm/pnpr包的 patch 级别变更，原文要点如下：

• 已发布的构建产物不可变：一个输入键 + 一组兼容性约束只能容纳一个产物；
• 在其上发布不同的产物，返回409 Conflict，与重新发布name@version的规则一致；
• 重复发布完全相同的产物仍然成功（幂等）；
• 由更早版本已存储的产物保留其槽位，升级一个已填充数据的 registry 不会让这些旧产物变得可被替换。

这意味着该变更同时锁定了三个维度：内容不变性（不同内容被拒绝）、操作幂等性（相同内容可重试）、向后兼容性（存量数据不失效）。后文将逐一在源码中找到它们的实现证据。

为什么需要"写一次"：与 npmname@version同一套信任模型

在 错误定义 中，VersionAlreadyPublished与ArtifactAlreadyPublished两个错误并排定义，注释直接点明了设计动机：

One input key and one set of compatibility constraints admit one artifact, for the same reason aname@versionadmits one tarball: a consumer that resolved it once must not be handed different bytes later.

也就是说，只要解析方曾经拿到过某个产物，之后就不能被换给不同的字节——否则缓存与校验链路的信任基础就会被破坏。源码注释还补充了一个安全视角：

Replacing a claimed slot is an operator action against the store, not something a publishing credential can do — a stolen one would otherwise be able to swap an artifact for a dependency nobody has looked at in a year.

即：替换已占用槽位属于运维动作（直接操作存储），发布凭证（凭据）没有权限做到——否则一份被窃取的凭证就能把一年无人问津的产物悄悄换成恶意内容。这正是该变更对"谁可以写、什么可以写"给出的边界。

错误映射方面，artifact_already_published被注册为独立的存储日志错误码（见 错误映射），对外即表现为409 Conflict。

槽位如何计算：input key、subject 与兼容性约束的三元定位

"一个输入键 + 一组兼容性约束"在实现上并不是直接拼接字符串，而是经过两次确定性哈希，得到两个对象路径片段。见 artifact_identity.rs：

• entry_digest(key, subject)：对输入键（input key，例如workspace-task:v1:inputs=abc）与产物主题（subject，如某个 workspace 任务的packages/app+build）做 SHA-256，得到该输入的 entry 路径；
• compatibility_slot(compatibility)：对兼容性约束做 SHA-256，得到该 entry 下的槽位路径。

兼容性约束有两种形态，compatibility_slot的处理也不同（源码）：

• Universal：直接使用固定的universal域；
• Tagged：以tagged为前缀逐项哈希标签，且先排序再哈希——因为标签集合的匹配与顺序无关，两种顺序若被哈希成不同槽位，就等于给同一平台发了两个可发布的槽位；排序后即规范化。

代码注释对槽位的定义说得非常直白："one per set of compatibility constraints, so auniversalbuild and a glibc-2.31 build coexist while two builds advertising the same constraints do not"（每种兼容性约束集一个槽位，universal 构建与 glibc-2.31 构建可共存，而宣称相同约束的两个构建不能）。

存储路径采用{owner}/entries/{entry}/{slot}.json的布局，其中变体文件名为 64 位十六进制 +.json，由is_variant_file识别（源码），owner 与 entry 同样是 64 位十六进制摘要片段。这意味着整个对象存储的寻址是内容寻址与语义寻址的混合：entry 由输入键决定，slot 由平台约束决定，而最终落盘的 envelope 由产物字节决定。

作用域声明：冲突判定的一线战场

槽位之上的冲突裁决发生在"作用域"（scope）层。一个产物声称覆盖某些作用域（平台标签），发布时逐一向{owner}/entries/{entry}/scopes/{scope}写入作用域标记（scope marker），标记内容为持有者的 envelope 摘要。见 scopes.rs 的 claim_scopes：

• 每个 scope 都是一次条件创建（conditional create），两个仅部分重叠的发布会在它们共享的 scope 上竞争，从而被正确排序；
• 冲突判定结果是一个三态枚举SlotClaim：
  • Held：envelope 已存在且与本次发布完全相同——视为幂等重试，本次发布无需再做任何写入；
  • HeldByAnother：该槽位已被不同内容占用——上升为RegistryError::ArtifactAlreadyPublished；
  • Free：槽位空闲，可以继续存储。

universal 产物与 tagged 产物互相感知的方式值得一提：universal 产物占用保留键UNIVERSAL_SCOPE，并在声明后检查是否已存在任何 tagged scope（claim_universal_scope）；tagged 产物则在声明完自己的所有 scope 后回头检查 universal 标记（claim_tagged_scopes）。这样即使两种产物"声称"的方式完全不同，也能在作用域上正确互斥。

发布流程中的两次防线：预检查与落盘对账

冲突判定不是只做一次。在 publication.rs 的 publish_reserving 中可以看到分阶段的防御：

1. 发布前预检查（publication_is_complete）：如果变体文件已存在且与本次 envelope 逐字节相同、且所有 scope 标记均为自己持有，则直接返回false表示"无需写入"——这是幂等重试的快速路径，且发生在预留配额之前，因此一个配额已满的 owner 依然有权重试自己的产物（源码）；
2. 配额预留：计算新增字节数并预留 owner 配额；
3. 作用域声明：得到上述三态结果；
4. 存储新 blob 与 envelope：对每个 blob 做条件创建，幂等地复用已存在的字节（resolve_new_blobs）；
5. 落盘对账（settle_envelope）：envelope 条件创建失败时，读回胜者并逐字节比对。如果胜者的字节与本次不同，才返回ArtifactAlreadyPublished；如果相同，则仍视为幂等成功。

为什么需要最后一步对账？源码注释给出了关键推理：

Two publications can both find the slot empty, so losing the create is not by itself an idempotent retry: whoever won may have stored something else, and reporting success would tell a publisher its artifact is the one being served when it is not.

两个发布可能同时看到槽位为空，此时条件创建失败本身并不能证明"输给了自己"——胜者可能存了别的内容。测试 losing_a_race_for_a_slot_is_not_reported_as_idempotent 专门构造了这种竞争：输方在创建时才发现槽位被占，若仅凭"创建失败"就返回幂等成功，发布方会误以为线上服务的是自己的产物。因此必须以读回比对为准。

旧数据保留：backfill 机制如何保护升级前的存量产物

changeset 最后一句"由更早版本已存储的产物保留其槽位"在实现上对应backfill_scopes（scopes.rs）：引入作用域标记之前的存量 entry 没有标记，新版本的发布流程会回溯（backfill）扫描该 entry 下所有已存储的变体，读取每个变体的 envelope，解析其兼容性约束，为这些旧产物补写 scope 标记，最后写入一个 sentinel 标记表示"全部完成"。

几个实现要点：

• 回溯只对尚未写入任何标记的 entry 运行一次，且以 sentinel 为准——因为标记是逐条写入的，若扫描中途失败，下次发布会重新执行，确保"扫描过"与"全部写入"不被混淆（测试 a_backfill_that_did_not_finish_runs_again 验证了这一点）；
• 多个旧变体若触及同一 scope，标记只写一次，避免一次回溯变成对每条变体的重复预留与释放（测试 a_backfill_writes_each_marker_once_however_many_variants_reach_it 验证 usage 文档只被写入一次）；
• 回写标记同样受配额约束：owner 配额已满时不能写入标记（测试 an_owner_with_no_room_cannot_have_markers_written_for_them）。

配套测试还覆盖了两种重要的存量场景：

• 旧命名布局：直接以 envelope 摘要命名的变体文件同样声明其槽位，否则已持有一个产物的存储会留下"可替换"的漏洞（an_artifact_stored_under_the_older_name_still_claims_its_slot）；
• 任意写入顺序与位置：无论变体的标签顺序如何、在 listing 中的排序位置多靠后，只要与目标槽位匹配，就必须被识别为占用者（a_legacy_artifact_claims_its_slot_whatever_its_order_or_position）。

测试矩阵：不可变语义的完整验证

围绕本次变更，仓库在 behavior.rs 与 publication.rs 中沉淀了成体系的测试，可作为语义的验收清单：

其中"拥挤 entry"测试对应一个值得注意的边界：如果某个 entry 因历史原因同时存有多个互相重叠的产物，这些产物的任何重发都会被拒绝（而非被误报为"已发布"）——因为对于特定消费者而言，它们都不是唯一的"那个产物"，把冲突报成幂等会掩盖损坏状态，令其无人修复。

实战要点：面向使用者的行为指南

结合上述实现，面向 pnpr shared artifact store 的使用者可以提炼出以下可直接依赖的结论：

• 幂等重发是安全的：CI 断线重跑、发布脚本重试，只要产物的输入键、subject、兼容性约束与字节完全一致，重发不会产生冲突、不会重复计费（预检查发生在配额预留之前）；
• 内容变更必须换键：修改产物内容后重发同一输入键会得到409 Conflict（artifact_already_published）。正确的做法是为新的构建输入产生新的 input key（例如把依赖摘要、源码摘要纳入 key），让新内容落到新槽位；
• 平台矩阵天然并行：不同兼容性标签之间互不干扰，为多平台（linux-x64、linux-arm64、darwin、win32 等）并行构建与发布是设计内支持的场景；
• 升级部署无需迁移：由旧版本写入的存量产物会被自动回溯补写标记并保留槽位，升级已填充数据的 registry 不会让旧产物变得可被覆盖；
• 替换槽位是运维动作：若确实需要覆盖某个产物（如安全事故处置），需要绕过发布 API 直接操作对象存储，发布凭证本身无法完成替换。

从源码结构看，该机制的全部实现集中在 shared-artifacts crate 的publication、scopes、artifact_identity三个模块中，存储布局常量（缓存目录shared-artifacts/v0、对象前缀.pnpr-artifacts/v0、活跃发布过期时间 1 小时、续期间隔 5 分钟等）定义在 lib.rs，感兴趣可以沿这些入口继续深入阅读，或通过 pnpr 的测试目录 观察各种故障注入（写入后报错、并发竞争、配额耗尽）下的行为。整体上，artifact-slots-are-write-once这次 patch 级变更虽然只是一段话，却为共享产物存储补齐了"内容不可变、重试幂等、存量兼容"三项关键语义，使其与 npmname@version的发布信任模型保持了一致。

【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm