Skip to content

[PR] fix(server): unconditional 304 from the codex catalog endpoint no longer manufactures a phantom cache hit - #4864

Merged
ranxianglei merged 9 commits into
masterfrom
2026-10-26_catalog-304-conditional
Oct 27, 2026
Merged

ranxianglei merged 9 commits into
masterfrom
2026-10-26_catalog-304-conditional

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

这是啥问题

模型目录缓存(codex-catalog-cache)对任何 304 都当作"缓存仍新鲜":重放缓存的完整 200 目录、把新鲜期再续 6 小时。但 304 只有在请求带了条件头(If-None-Match / If-Modified-Since)时才合法——wrapper 自己从不发条件头,客户端带了的场景重放是正确的;问题是无条件请求也收到 304(某些透明中间盒会乱答):这时重放等于凭空造了一次成功——幻影新鲜 6 小时、真实响应头全丢、relay 还把这当真实拉取记账。

根因(代码坐标)

src/server/codex-catalog-cache.ts 304 分支(原 :214-219):if (status === 304) { if (!entry) return result; remember({...entry, savedAt: clock()}); return replay(entry, false); } ——不看请求是否带过条件头,一律按命中续期。

改动

304 分支加一道条件头门:headers(请求头,new Headers(init.headers) 已在作用域)带过 if-none-match 或 if-modified-since 才重放+续期;否则与其它非预期状态同样处理——invalidate() 丢缓存,把怪响应原样透传给调用方。

验证

  • 原有 revalidation 测试补上了它名字里一直暗含的条件头(请求侧加 if-none-match),行为不变
  • 新测试:无条件 304 → 透传(调用方看到的就是 304)+ 缓存失效(断网后不再幻影救援)
  • tests/codex-catalog-cache.test.ts 全绿(9+1);typecheck 干净

关联

精读块 C 结论之二(其一为 #4863 msgIds 烧号)

ci-check and others added 3 commits October 26, 2026 21:05
…r a send-failure give-up (#4599)

#4516 (bc50f1a) replaced the post-give-up warn log with a state write that
clobbered the 'send-failed' register value, breaking #4125's pinned contract
(the register must stay 'send-failed' after a send-failure give-up). The
user-facing intent of #4516 — accurate oversized-refusal wording — is kept by
mapping 'send-failed' onto the dead-equivalent sentence in fallbackOversizeRefusal.
Master absorbed this branch's fix with refinements (#4824: the send-failed
register contract + the #4516/#4125 wording); taking master's side leaves
the branch with no remaining diff vs master.
…ec — no phantom hit

The catalog cache replayed its cached 200 on ANY 304 and extended
freshness by another maxAge. That is correct only when the request
was conditional (the end client sent if-none-match / if-modified-
since; the wrapper itself never sends a validator). A 304 answered
to an UNCONDITIONAL GET is off-spec — some transparent middleboxes
do it anyway — and treating it as a hit manufactured a phantom
success: six more hours of freshness, all real response headers
discarded, and the relay billing it as a genuine catalog fetch.

Gate the 304 branch on the request having carried a conditional
header; otherwise invalidate the cache and pass the odd response
through, same as any other unexpected status.

The existing revalidation test now models the conditional header
its name always implied; a new test pins the off-spec passthrough
plus cache invalidation.
@ranxianglei ranxianglei added the ci:full Run the FULL CI matrix (all e2e lanes + 12-leg test matrix) on this PR label Oct 26, 2026
@ranxianglei ranxianglei changed the title fix(server): unconditional 304 from the codex catalog endpoint no longer manufactures a phantom cache hit [PR] fix(server): unconditional 304 from the codex catalog endpoint no longer manufactures a phantom cache hit Oct 26, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复。 open+closed issue 与在途 PR 均无同主题条目(按「codex catalog 304 / 幻影缓存」检索)。唯一相关项是今天刚合入 master 的 1b8a0ab12(来自 #4801 review)——它只给同一现象加日志、不动行为,与本 PR 方向恰好冲突,见下。

标签: bug / codex / scope/wiring / p3(请求管道层缺陷;p3:触发条件是 off-spec 中间盒对无条件 GET 答 304,无已确认的生产事故记录,后果有界)。

审核进行中,初步结论(独立核验过,非复读 PR 描述):

  1. 修法本身成立:304 分支的条件头门正确——无条件 304 走与其它非预期状态一致的 invalidate()+原样透传;我独立确认了 wrapper 确实从不发条件头(src/ 里唯一 If-None-Match 在 src/update-policy.ts:560,是更新策略的独立路径,不经 relay 目录拉取);门的两向(条件→重放续期 / 无条件→透传+失效)都有测试钉住,符合 Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617 双向断言纪律。
  2. 发现真冲突,且不是机械冲突:分支基线是 05c379e,master 此后合入了 1b8a0ab12 fix(model-catalog): log the 304 replay to unconditional GETs once per credential(#4801 review)。该 commit message 明确写了决策:保留重放("availability-first: codex clients expect a complete 200 catalog"),只加每凭据一次 warn 让网关 304 循环可见。本 PR 的决策是停止重放。两者在同一行代码上语义对立——解冲突必须二选一,这是契约级取舍,不是 rebase 能自动解决的。
  3. 按决策升级规则,我会立一个 decision request issue 列选项(A 采纳本 PR / B 维持 master 现状 / C 折中:重放但不续期+标 offline-cache)+ 我的推荐,请 owner 拍板;拍板后我按选定方向完成 rebase。

CI 尚未开始(head 6381f05)。本地定向测试依赖安装中,全量以远程 CI 为准。八问结论随后补上。

@ranxianglei

Copy link
Copy Markdown
Owner Author

#4801 → #4852 → #4823 → #4834 → #4863 → #4864 → #4866

Conflict in src/server/codex-catalog-cache.ts (the 304 branch): master
added a once-per-credential warn log while KEEPING the replay
(availability-first stopgap, 1b8a0ab from the #4801 review); this
branch replaces the replay with invalidate()+passthrough for off-spec
unconditional 304s. Resolved by union of intent:

- Unconditional 304 (no if-none-match/if-modified-since on the request):
  invalidate() + pass the raw response through (this PR's fix), plus
  master's once-per-credential warn so a gateway looping on the off-spec
  answer stays visible in the logs.
- Conditional 304 (client sent a validator): unchanged negotiated
  revalidation — replay cached 200 and extend freshness.
- Renamed replayNoted -> offSpec304Noted: nothing is replayed on the
  off-spec path anymore, the old name would lie.

Behavior change vs current master (intended, this PR's purpose): an
unconditional 304 previously replayed the cached catalog as a full 200
and extended its freshness; now the cache entry is dropped and the 304
is forwarded as-is, same treatment as every other unexpected status.

Verified locally: npm run typecheck clean; targeted
node --import tsx --test tests/codex-catalog-cache.test.ts 10/10 pass
(includes both 304 case pins). Full-suite verdict = remote CI.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

冲突已解决并推送(merge commit 1426c8c),PR head 恢复干净:mergeable=True,状态 behind(master 又前进了,不阻塞合并)。自动解冲突第 1/2 次成功。

冲突怎么解的——取两边意图的并集,不是二选一:

master 在完全相同的位置单独合过一个止血提交(1b8a0ab12,出自 #4801 评审):保留重放、加一条每凭据一次的 warn 日志(理由写明「availability-first:codex clients expect a complete 200 catalog」)。本 PR 的方向是把重放换成丢缓存+透传。两边在同几行上写了互斥的行为。按意图合并:

  • 行为跟本 PR:无条件 304(请求没带 if-none-match / if-modified-since)→ invalidate() 丢缓存 + 原响应照传,与其它非预期状态同桶处理;条件 304(客户端带了校验头)→ 维持协商重验证(replay 缓存 200 + 续期),不动;
  • 可观测性保留 master 的止血:每凭据一次 warn 留着——网关若循环回这个 off-spec 响应,日志里必须看得见;消息文案更新为描述实际动作(dropping cached catalog and passing the response through),不再说 replaying;
  • 顺手把 replayNoted 改名 offSpec304Noted:那条路径现在不再有任何重放,旧名与事实不符。

结构化八问:

  1. 是什么问题:本 PR 修「无条件 GET 收到 304 被当成缓存命中」(phantom hit,还顺带续期新鲜度)。冲突本身是两条工作流对同一发现各自响应、互不知情,在同一代码段写了互斥行为。
  2. 什么原因导致的:分支切出后,master 合入了「保留重放+加日志」的止血;本 PR 实现的是「丢缓存+透传」。语义冲突,非文本冲突——不存在同时保留两种行为的文本合并。
  3. 影响范围与严重程度:只影响 codex lane 的模型目录获取路径,且只在「中间盒/网关对无条件 GET 回 304」这一退化场景触发;正常上游回 200,零影响。修的是 p2 级缓存语义缺陷,无用户面停摆。
  4. 怎么修复的:意图并集——行为采用根因修法(off-spec 304 归入模块既有的「其它意外状态」桶),可观测性保留止血日志;两侧声明过的意图都没丢。
  5. 是否有回归:触碰路径的既有行为逐项过——条件 304 重放(保持,测试钉住)、401/403/权威删除的失效逻辑(未动)、临时 5xx 回落缓存(未动)、offline-cache 兜底(未动)。无 fail-fast 变吞错、无阈值漂移。行为变更披露(旧→新):无条件 304 旧(master 现值)= 重放缓存 200 + 续期 + 一次性 warn;新 = 丢缓存 + 原始 304 透传 + 一次性 warn。这正是本 PR 要改的东西(PR 的全部目的),不是顺带漂移。
  6. 是否破坏缓存:本修复本身就是缓存策略修正——无条件 304 不再延长缓存有效期(那才是 bug);合法的条件重验证照常续期。其它缓存/重试/去重策略不受影响。
  7. 是否改了设计方向:没有。未引入新机制,只是把 off-spec 304 折进模块已有的意外状态处理桶,方向与本 PR 描述一致。
  8. 是否引入新配置:没有。无新 env/config/默认值。

验证:typecheck 干净;定向 tests/codex-catalog-cache.test.ts 10/10 绿(含条件/无条件 304 两个 case 的钉死);全量套件按纪律留给远程 CI。无需 decision-request issue——并集方案不丢失任何一侧意图,行为切换随本 PR 本身等你合并拍板。

你贴的链(#4801 → #4852 → #4823 → #4834 → #4863 → #4864 → #4866)收到;核过链尾 #4866(thinking forms 单源化 + 死 import 清理)与本 PR 文件零重叠,无热文件竞争。

判定:冲突已解、已推送,PR 回到干净状态,待 CI 与 review/合并。

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-26_catalog-304-conditional (75efc14)

Latest build — install this exact version

npm install -g billion-context@0.0.6314-pr.4864.38f4b16

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
75efc14 billion-context@0.0.6314-pr.4864.38f4b16 build
3643d2d billion-context@0.0.6309-pr.4864.f913f6f build
d465a62 billion-context@0.0.6302-pr.4864.97a0884 build
1426c8c billion-context@0.0.6299-pr.4864.6a84bb6 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr4864.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

审核完成 — 结构化八问:

  1. 是什么问题:codex 模型目录缓存把任何 304 都当「缓存仍新鲜」——重放缓存的 200 目录并把新鲜期再续 6 小时。但 304 只在请求带条件头时合法;无条件请求收到 304(透明中间盒 off-spec 乱答)时,重放=凭空造一次成功。
  2. 什么原因:304 分支不区分请求是否带条件头,一律按命中续期(src/server/codex-catalog-cache.ts 原 :214-219)。独立核实 wrapper 确实从不发条件头——src/ 唯一 If-None-Match 在 src/update-policy.ts:560(更新策略的独立路径,不经 relay 目录拉取)——所以该路径正常流量里收到的 304 都来自中间盒/网关。
  3. 影响范围与严重程度:仅 codex 车道、且经过会对无条件 GET 答 304 的网关的用户面;无已确认生产事故记录([PR] chore: empty PR (no changes) #4801 review 是防御性加日志)。后果:陈旧目录被钉住(savedAt 每次重置)、真实响应头丢失、relay 误记账。局部功能缺陷 → p3。
  4. 怎么修复的:304 分支加一道条件头门——带 if-none-match/if-modified-since 才重放+续期;否则与其它非预期状态同处理:invalidate() 丢缓存+怪响应原样透传。门的两向都有测试钉住(Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617 双向断言纪律满足);新测试同时断言透传与失效后「不再幻影救援」。
  5. 回归问题:逐项审过既有行为——条件请求 304 重放+续期(不变)、200 主路径(不变)、5xx/offline 救援(不变)、401/403/404/429 含磁盘失效(不变)、键分离/malformed/oversize(不变)。唯一行为变更(有意,披露):无条件 304:旧=幻影重放+续 6h → 新=丢缓存+原样透传。裸 304 透传不是新失败形状——master 在 !entry 情形本就有此出口,调用方已容忍。
  6. 是否破坏缓存:不涉及。不动会话上下文缓存/重试/增量游标/去重键;本模块管的 codex 目录缓存本身就是修复对象,其失效策略正是被修的东西。
  7. 是否改了设计方向:是——无条件 304 的降级语义从「静默救援」改为「诚实失败」,这正是需要 owner 拍板的点(见下),已立 decision request: codex-catalog unconditional 304 — passthrough+invalidate (#4864) vs keep replay+log (#4801 review) #4870。
  8. 是否引入新配置:不涉及。

验证(独立复现,非复读 PR 描述):

  • PR head 定向测试 tests/codex-catalog-cache.test.ts:10/10 通过(9 原有+1 新增,与描述一致)
  • PR head typecheck:干净
  • 全量 CI:已触发、排队中(head 6381f05),终判以远程 CI 为准

暂不合并的两个阻塞项:

  1. 与 master 语义冲突:今天刚合入的 1b8a0ab12([PR] chore: empty PR (no changes) #4801 review)在同一行代码上明确选了「保留重放」("availability-first: codex clients expect a complete 200 catalog"),只加每凭据一次 warn 日志;本 PR 选「停止重放」。解冲突=二选一,属契约级取舍。已按决策升级规则立 decision request: codex-catalog unconditional 304 — passthrough+invalidate (#4864) vs keep replay+log (#4801 review) #4870(A 采纳本 PR / B 维持现状 / C 折中:重放但不续期+标 offline-cache;我推荐 C)。
  2. 真合并冲突存在:分支基线 05c379e,master 已推进到 24e71f6;merge-tree 模拟确认 src/server/codex-catalog-cache.ts 内容冲突。decision request: codex-catalog unconditional 304 — passthrough+invalidate (#4864) vs keep replay+log (#4801 review) #4870 拍板后我按选定方向 rebase(选项 A 的话,[PR] chore: empty PR (no changes) #4801 的日志逻辑在门后变死代码,需一并删改)。

判定:修法质量本身过审——机制正确、测试有牙、diff 干净(2 文件、无无关改动、未动 version);hold 等 owner 对 #4870 的方向拍板,拍板后收敛(rebase+跟进)+ 远程 CI 绿即可合。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

第二次同步完成:master 又前进了 2 个提交(#4871 文档 PR + #4834 的 MESSAGE-IDENTITY.md 文档更新,均为纯文档),干净合入本分支(merge commit d465a62,零冲突、零代码改动),已推送。PR 恢复干净:mergeable=True,当前状态 blocked(等 CI/review,不是冲突)。

八问速答(本轮无实质变化,细节见上一条完整八问):

  1. 是什么问题:无新问题——master 再次前进触发系统重报冲突,实际只多了两个纯文档提交。
  2. 什么原因导致的:fast-moving master + 通知时序;已核实这 2 个提交对 codex-catalog-cache.ts 及其测试文件的触碰为 0 个 commit。
  3. 影响范围与严重程度:无,docs-only。
  4. 怎么修复的:直接 merge,无需解冲突。
  5. 是否有回归:无——本轮未动任何代码文件(仅 AGENTS.md / MESSAGE-IDENTITY.md)。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入新配置:不涉及。

判定:冲突已再解、分支已对齐最新 master,待 CI 绿与 review/合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

跟进:冲突已被 lane 自行解决,我已对新 head 复核

审核期间分支推进了两轮 merge master(1426c8c → d465a62),现 head 完全包含当前 master,src/server/codex-catalog-cache.ts 的内容冲突解法:保留本 PR 的条件头门,同时保留 #4801 的每凭据一次 warn 日志——日志移进无条件 304 分支内部、措辞随新行为改写("dropping cached catalog and passing the response through",新集合 offSpec304Noted)。即事实方向 = 选项 A(诚实失败)+ 可见性保留,#4801 的可用性立场被让位。

d465a62 独立复核:

  • 定向测试 tests/codex-catalog-cache.test.ts:10/10 通过
  • typecheck:干净(0 error)
  • 远程 CI 该 sha:18 绿、其余进行中/排队、无失败

唯一余项:owner 对 #4870 拍板——认可 A(现状零改动,CI 全绿即可合)或改走 C(重放但不续期+标 offline-cache,我的推荐,需再改一处小 diff)。八问结论见上条评论,对新 head 全部仍然成立(冲突解决未改变任何已审行为面)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI 收敛跟进:d465a62 上 e2e-native-pi / e2e-native-opencode / e2e-pi-codex-ws 三车道红。判定为继承性/环境性(同窗口另两个分支 head 同名车道同红;本 PR diff 与这三条车道零交集)。已按 CI 协调纪律把 origin/ci-fixes(f5939a1 intercept 修复)与最新 master(23158db,#4873/#4835/#4839 等)merge 进分支,新 head 75efc147a;lockfile 冲突按最新 master 侧(kernel 0.0.167)解决;合并后本地定向测试 10/10 + typecheck 干净。已在 #4599 留一行记录。新 sha 的 CI 结果出来后我再报最终判定。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

进度汇报(会话曾被守护进程重启,补报状态):

已完成:

  1. 代码审核通过——条件头门修法正确,wrapper 不发条件头、relay 透传客户端 init 均独立核实;定向测试 10/10 + typecheck 干净(在 d465a62 上实测)。
  2. CI 红已收敛——d465a62 上 e2e-native-pi / e2e-native-opencode / e2e-pi-codex-ws 三车道红,判定继承性(同窗口另两个分支 head 同名车道同红,本 PR diff 与这三条车道零交集);已按协调纪律 merge origin/ci-fixes(f5939a1)+ 最新 master(23158db)进分支,lockfile 冲突按最新 master 侧解,新 head 75efc147a 已推送,合并后本地定向测试+typecheck 干净。CI Control Center: Centralized CI Failure Handling & Status Sync (Comment all CI issues here; do not open new issues) | CI 总控: CI 失败集中处理与状态同步(所有 CI 问题在此评论, 勿开新 issue) #4599 已留一行记录。

进行中:等 75efc147a 的远程 CI 出结果(GitHub API 限流窗口,恢复后我会短轮询确认)。最终判定(CI 全绿即可合 / 或 owner 在 #4870 拍板改走 C)随后补上。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

最终判定:CI 全绿,可合(待 owner 在 #4870 拍板方向)

75efc147a(含 ci-fixes + 最新 master)的远程 CI:59 项 check-run = 58 success + 1 skipped(red-signal,设计内跳过)+ 0 failure。之前 d465a62 上的三条 e2e 车道红确认为继承性/环境性——收敛后全绿。

收工八问(简表,详版见本线程前一条):

  1. 是什么问题:codex 目录缓存把无条件请求收到的 304 也当命中,凭空造出 6h 幻影新鲜。
  2. 什么原因:304 分支不校验请求是否带条件头,一律重放+续期。
  3. 影响面:仅当透明中间盒对无条件 GET 乱答 304 时触发;后果是陈旧目录被掩盖、真实响应头丢失(体验/正确性瑕疵,非不可用)。
  4. 怎么修的:304 分支加条件头门——带 if-none-match/if-modified-since 才重放续期,否则与意外状态同处理(invalidate+原样透传)。
  5. 回归:无。条件 304 路径字节级不变;裸 304 此前在无缓存时本就透传,调用方早已容忍该形状;200/5xx/离线路径未触碰。
  6. 缓存破坏:无新增失效源;仅多了一条本就该丢缓存的失效路径。
  7. 设计方向:无转向;与 [PR] chore: empty PR (no changes) #4801 的冲突按「保留门 + 保留每凭据 warn(移入无条件分支)」解决,可见性不丢。
  8. 新配置:无。

行为变更披露(旧→新):无条件 304 旧=重放缓存+续期 6h+丢真实响应头;新=丢缓存+透传 304。原因:无条件 304 是 off-spec 应答,重放等于伪造成功。

合并建议:代码与 CI 均已就绪。唯一余项是 #4870 的方向拍板——当前分支实现的是选项 A(+warn);owner 认可 A 即可直接合,若改走 C(重放但不续期+标 offline-cache)我再补一处小 diff。

@ranxianglei
ranxianglei merged commit 7cc6df5 into master Oct 27, 2026
59 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.867-master.7cc6df5 (rolling master tag).

npm install -g billion-context@0.0.867-master.7cc6df5  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working ci:full Run the FULL CI matrix (all e2e lanes + 12-leg test matrix) on this PR codex p3 scope/wiring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant