Repository navigation
showcase 端点注释把 cacheTtl 的响应头写成 public, max-age=30 —— 运行时发的是 private，而 private 是安全规则 #5244
Description
发现于 #5238(#5040 E9 文档追平)。纯注释修真，零行为变更；与本 issue 的父单 #5231 同一类纪律(注释必须与实际一致),故挂为其子单。
事实
examples/app-showcase/src/system/apis/index.ts:80,TaskFeedEndpoint.cacheTtl 上方的注释:
// Seconds. Emitted as `Cache-Control: public, max-age=30` on a SUCCESSFUL
// answer only — never on a 401/429/5xx, ...
运行时发的不是 public。packages/runtime/src/endpoint-policy.ts 的 computeCacheControl:
if (!Number.isFinite(ttl) || ttl <= 0) return 'no-store';
return `private, max-age=${Math.floor(ttl)}`;
PR #5230 自己的真实 boot 探针 P1 也打印了实测值:
########## P1 GET /api/v1/apps/showcase/tasks (authed)
HTTP/1.1 200 OK
cache-control: private, max-age=30
注释的后半句(只随成功答案上线、不随 401/429/5xx)是对的,错的只有 public 这一个词。
为什么值得单独记一笔
private 在这条链上不是调优选择而是安全规则,endpoint-policy.ts 的文档块把理由写清楚了:任何一条响应都可能是按调用者 RLS 裁剪过的,所以共享缓存绝不能存下来再发给别人(#5040 §3.3 的 per-principal cache key 在没有服务端缓存时就落在这个 header 上)。
而这条注释所在的位置是 showcase —— 声明式端点唯一的一手示例,是 AI 作者最可能整段抄走的那份文件。抄走 public 的作者会顺理成章地推断「共享缓存可以存这条响应」,而这正好是该规则要挡住的推断。
修法
把 public 改成 private,并把「private 是安全规则不是调优」这半句带上(与 endpoint-policy.ts 的措辞对齐,不复述第二套规则)。顺带可核一下 cacheTtl: 0 的语义(no-store)是否也需要在示例里点一句。
边界
不动运行时,不动声明本身(cacheTtl: 30 是对的),不动 content/docs/releases/。
Activity
baozhoutao commentedon Aug 5, 2026
🔒 认领:PM 循环第 4 轮(cli 车道)
会话:
session_01VkPSGsX9o17MsGv3Lbxu2w分支:
claude/issue-5244-showcase-cachettl-commentWorktree:
objectstack-issue-5244域:
domain:cli文件面:
examples/app-showcase/src/system/apis/index.ts:80附近注释,纯注释修真零行为变更。与同批 #4633 / #5387 不相交。执行口径按 issue:
public→private,带上「private是安全规则不是调优」半句(措辞对齐packages/runtime/src/endpoint-policy.ts的文档块,引用而不复述第二套);顺带核cacheTtl: 0→no-store语义是否值得在示例点一句。⛔ 不动运行时、不动声明本身、不动 releases/。Generated by Claude Code
docs(examples): 把「every ttl」收紧成「every positive ttl」(#5244)
baozhoutao commentedon Aug 5, 2026
✅ 验收通过 —— PR #5395,转 ready 挂合并队列
对实况复核(cli 车道 PM,session_01VkPSGsX9o17MsGv3Lbxu2w):
public→private+ 「安全规则非调优,authRequired: false上同样成立」半句 + 引用computeCacheControl文档块而非复述第二套;cacheTtl: 0→no-store语义自然并入同一句引用。正确半句原样保留。零行为变更,运行时与声明未动。skip-changeset标签而非空 changeset(空 changeset 会静默卡死已 version 的发布:Release run 全绿,但 npm 和 Docker 什么都没发(17.0.0-rc.2 现在就卡着) #4898 的发布轮教训),标签已挂(此前的 Check Changeset 红来自挂标前的旧 run,新 run 覆盖)。max-age=30,不钉private—— 上线到线上的那一位安全指令在唯一观测真实 wire 的那层没有被钉住 #5396(dogfood 断言只钉max-age=30不钉private位)已按 finding 纪律立案,进分诊池。DataLoaderConfig.cacheTtl的 0 语义相反(0=不过期)一事,PM 采纳 dev 的「查过但立不成缺陷」判断 —— 同名键异语义确有 AI 混淆风险,但两类型语义可能各自正确;留在本报告与 PR 记录中,若后续再有人撞上再立案。转 ready 挂 auto-merge,跟到 MERGED。
Generated by Claude Code
docs(examples): showcase 的 cacheTtl 注释写成 private —— 运行时发的就是它,且它是安全规则 (o…