企业官网建设流程全解析

workerd ReadableStream 测试套件深度解析：双实现对齐、18 条行为分歧台账与 WPT 补全策略

【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd

workerd 内置了两套 Web Streams 实现（C++ 传统实现与 TypeScript 新实现），src/tests/streams/readable/是专门针对"默认值流"ReadableStream的 WPT 风格测试套件。本篇基于该目录的规范文档 readable/AGENTS.md 展开，讲清这套"测试即规范"（the tests are the normative artifact）的测试是如何在 C++ 与 TypeScript 两套实现之间钉住每一条行为差异（Divergence Ledger）、如何配合兼容标志（compatibility flags）划分测试单元（cell），以及每个测试模块的覆盖边界，帮助阅读 workerd 源码或维护 Web Streams 兼容性测试的工程师快速建立全景认知。

一、套件定位：用"分歧台账"规范 ReadableStream 的双实现行为

readable/AGENTS.md 开篇即声明了本套件的方法论：测试本身就是规范性制品。该套件是 workerd 中值型 ReadableStream（ReadableStream默认形态，含ReadableStreamDefaultReader/ReadableStreamDefaultController）的非正式规范，并且与测试代码保持"锁步"（lockstep）演进。文档同时划定了边界：

• 字节流（type: 'bytes'、BYOB 场景）归属 readable-byte/ 套件；
• pipeTo/pipeThrough的测试矩阵归属 piping/ 套件；
• 本套件补全（COMPLEMENTS）WPT 测试（//src/wpt:streams，C++ 侧已知偏差以 expectedFailures 形式记录在 src/wpt/streams-test.ts）。

文档还揭示了一个重要的根因结论：探测 C++ 侧 expectedFailures 后发现，大量 WPT 失败并不源于行为上的能力缺口，而是收敛到少数几个构造期的分歧——最典型的是 C++ 构造函数拒绝highWaterMark: Infinity（整数转换失败）以及参数校验顺序不同。而"reentrancy 一族"测试在有限 hwm 下基本是双端对等的（parity）。这正是台账（Divergence Ledger）存在的原因：不是"让两边都变成谁都能过的模糊断言"，而是分叉断言、逐条钉死。

二、18 条分歧台账（C++ vs TypeScript）

台账是整个文档的核心资产。以下 18 条全部继承自 readable/AGENTS.md，"Pinned in" 列指明每条分歧被哪个测试钉住：

台账同时记录了若干已探测并钉住的相等性（parity）：pull 串行化（绝不被重入）、pull/async-start 拒绝错误对象身份保持、error-undefined 经 closed 透传、error() 两次或 close 完成后是 no-op（close 仍挂起的情况见 #18）、desiredSize 生命周期（1 → 0 close、null error、0 cancel）以及"有挂起 read 时 enqueue 跳过队列"、cancel-with-pending-pull、locked-stream cancel 拒绝但不运行 hook、tee 的错误传播身份 / pull-per-read 形态 / 部分读取后 tee、tee 重入崩溃回归、from() 经 return() 的 cancel 管道身份、async-iterator 协议交错（return/next 无 await）、chunk 以引用持有（变异可见、身份保持）+ 队列中 detach 可观察、以及除 #15 之外的整个集成面（body chunk 归一化，含消息 'This ReadableStream did not return bytes.'；disturbed 流构造 Response 抛 TypeError；locked 流构造 Response 被接受；clone 后双读；cancel 后再消费得 'Body has already been used'；readAll 的小/大/失败路径；以及 SELF fetch 往返——fetch body 与 Request body，即 workerd#5113 的形态）。

2.1 台账 #1～#3：构造期分歧的源码实证

这三条分歧集中在 construction.js，其头注释明确写道：本文件补全 WPTreadable-streams/general.any与constructor.any，而 C++ 侧 expectedFailures 在此收窄为"参数转换顺序"与"校验类型"两类。

#1 镜像对称的垃圾源校验（construction.js）：new ReadableStream(null)与new ReadableStream(42)恰好形成镜像——

if (usingTsImpl) { throws(() => new ReadableStream(null), { name: 'TypeError', message: 'Cannot convert undefined or null to object', }); new ReadableStream(42); // 原语包装对象可转换 } else { new ReadableStream(null); // C++ 接受 null throws(() => new ReadableStream(42), TypeError); }

#2 参数转换顺序（construction.js）：用 getter 探针记录读取次序。spec（TypeScript）先转换 queuingStrategy（size 先于 highWaterMark），再读 source 的 type；C++ 则先读 source.type，且 hwm 先于 size：

strictEqual(order.join(','), usingTsImpl ? 'strategy.size,strategy.hwm,source.type' : 'source.type,strategy.hwm,strategy.size');

#3 hwm 校验——台账中最有"系统性影响"的一条（construction.js）：-1/NaN时 TypeScript 抛 RangeError、C++ 抛 TypeError；而 spec 视为合法的Infinity被 C++ 的整数转换拒绝（消息为 'The value cannot be converted because it is not an integer.'）。正如台账所述，这一条是 C++ 侧大量 WPT reentrant/errors 用例失败的根因——WPT 原始用例常以Infinity作为默认策略，构造直接在 C++ 侧失败，后续所有断言连锁失守。

2.2 台账 #4/#5/#6：pull 时序与 start 抛错

source-algorithms.js 钉住了底层源钩子（start/pull/cancel）的调用时序。台账 #4 的pullCountShape（source-algorithms.js）在 hwm=1、pull 内 enqueue 的场景下断言 pull 计数形状：两边都先 pull 一次（计数 1），第一次 read 后 TypeScript 为 2（每次 read 后都 pull，spec），C++ 仍为 1（首次 read 由队列直接供给），第二次 read 后两边都为 3（C++ 把延迟的 pull 批量补发）。#5 的pullOnLastChunkRead进一步验证"队列排空后是否 pull"：TypeScript 拉、C++ 不拉。

而 #6 的syncStartThrow（source-algorithms.js）展示了最尖锐的分叉之一：

if (usingTsImpl) { // spec：同步抛出的 start() 从构造函数逃逸 strictEqual(caught, err); } else { // C++：构造成功，错误被流吞掉 strictEqual(await rejectionOf(rs.getReader().read()), err); }

作为对照，同文件还钉住了两端的 parity：pull 永不重入（pullSerialized）、pull 拒绝与二次抛错都以同一错误对象身份使流 errored（pullRejectionErrorsStream/pullThrowSecondCall）、异步 start 拒绝、cancel 与挂起 pull 共存时 cancel hook 恰好收到一次 reason（cancelWithPendingPull）。

2.3 台账 #10：队列算术——双精度 vs 整数化

queue-math.js 覆盖 WPT "floating-point-total-queue-size" 用例族。TypeScript 按 spec 全程双精度，能精确复现如0 - 1e-16 - 1 + 1e-16的浮点残差；C++ 队列按"类整数"跟踪：Number.MAX_SAFE_INTEGER附近的总和饱和（-2, -1, 1, 0形态），小数 size 直接截断为 0。更值得注意的是文档标注的已知缺陷：在 C++ 侧读取一个小数 size 的 chunk 会让 isolate 同步自旋（与 bad-strategies.js 中 invalid-size 挂起同族），因此queueMathNearZeroClamped/queueMathNearZeroEndsZero两个测试在 C++ 分支下只断言同步 enqueue 时刻的 desiredSize，绝不尝试 read（见 queue-math.js 中if (!usingTsImpl) return;的守卫）——这是"无法钉住就明确规避并注释原因"的工程化处理。

2.4 台账 #14：size() 内的重入 read

reentrancy.js 覆盖了 WPTreentrant-strategies种子。前三个场景（enqueue/close/cancel in size）双端对等：嵌套 enqueue 先到导致输出顺序反转、close 先于 chunk 可读、cancel hook 带 reason 运行。真正分叉的是 #14readInsideSize（reentrancy.js）：重入 read 注册于 spec 的"pending-read 检查"之后，于是 TypeScript 下正在途的 chunk 'a' 仍进队列、重入 read 由下一次绕过队列的 enqueue 'b' 满足（inner='b', next='a'）；C++ 则把在途 chunk 直接喂给重入 read（inner='a', next='b'），投递交换。测试中的守卫细节值得注意：由于 C++ 会直接满足重入 read，size()里必须用innerRead ??= reader.read()保证只在首次 enqueue 时埋点，否则每个后续 chunk 都会被捕获。

三、模块地图：每个文件钉住什么

readable/AGENTS.md 的 Module map 与本目录实际文件一一对应（模块清单以 readable-modules.capnp 中定义的List(Workerd.Worker.Module)常量为唯一真源）：

main.js 以显式具名 re-export汇总了上述全部测试名（绝不使用export *，重名必须在加载期暴露为 SyntaxError 而非静默丢测试），同时提供默认导出：一个回显请求体的 fetch 处理器，供集成测试通过SELF绑定把 ReadableStream 经 fetch 机制双向往返（对应台账中 "SELF fetch round-trips" 一项）：

export default { async fetch(request) { return new Response(request.body, { headers: { 'content-type': 'application/octet-stream' }, }); }, };

四、兼容标志与测试单元划分

4.1 标志台账

readable/AGENTS.md 的兼容性标志表如下（"Unflagged side" 一列说明无标志侧由谁钉住）：

4.2 四个 wd_test 单元（cell）

BUILD.bazel 定义了四个wd_test目标，测试源集统一为glob(["*.js"]) + ["readable-modules.capnp"]：

• readable-cpp.wd-test：C++ 实现主 cell，钉住 8 个兼容标志（nodejs_compat、streams_enable_constructors、transformstream_enable_standard_constructor、fixup-transform-stream-backpressure、capture_async_api_throws、workers_api_getters_setters_on_prototype、set_tostring_tag、writable_stream_spec_compliant_writer、enable_weak_ref），配置SELF自绑定，并为 gc.js 开启v8Flags = ["--expose-gc"]；
• readable-ts.wd-test：TypeScript 实现主 cell（bazel 侧额外传--experimental）。有意省略C++ cell 的全部语义标志——因为 TS 实现硬编码现代行为，标志的缺失本身就是"TS 实现不消费这些标志"的断言；它额外钉住typescript_implemented_streams与内部测试用expose_draining_reader，并声明 autogateworkerd-autogate-per-isolate-javascript-bootstrap；
• readable-cpp-pedantic.wd-test 对应的 bazel 目标：主 C++ cell + 无日期 opt-in 标志pedantic_wpt，探测结果为无差异，故共享模块不分叉运行；
• readable-cpp-legacy.wd-test：无标志的回归守卫，仅 C++ 侧运行，且显式generate_all_compat_flags_variant = False——因为 2999-12-31 的 all-compat-flags 变体本会把被省略的标志重新打开，与 cell 目的相悖。

这与父级文档 src/tests/streams/AGENTS.md 约定的整体机制一致：配置不设置 compatibilityDate，日期轴由 wd_test 变体机制持有（@变体跑在 2000-01-01，@all-compat-flags跑在 2999-12-31），测试必须在两个极端都通过；每个依赖日期门控的行为都以按名钉标志的方式在两个配置中固定。若某测试只在@all-compat-flags下失败，说明是某个日期门控标志改变了行为，应找到它（compatibility-date.capnp）并钉住它，而不是钉一个日期。

4.3 draining-reader：TS 侧的内部测试全局

文档特别指出，ts cell 额外设置内部测试标志expose_draining_reader，安装全局ReadableStreamDrainingReader——C++ 桥接消费 TypeScript 流所驱动的"批量排空管道"（bulk-drain conduit）。C++ 实现下不存在该全局；draining-reader.js 在两个 cell 中同时断言两侧事实（TS 侧验证排队积压 + close 哨兵的一次批量清出、值 chunk 对象身份透传、EOF 空批次、error/cancel 传播、锁排他；C++ 侧断言全局缺失）。

五、分歧断言模式：which-impl 而非放宽断言

父级文档 src/tests/streams/AGENTS.md 规定了套件的分歧处理原则：当实现有意不同时，不要放宽断言到"两边恰好都满足"的模糊条件，而是按实现分叉、分别钉死各自一侧的精确行为。本套件的实现入口是 which-impl.js：

export const usingTsImpl = globalThis.Cloudflare.compatibilityFlags['typescript_implemented_streams']; export const pedanticWpt = globalThis.Cloudflare.compatibilityFlags['pedantic_wpt'];

测试文件用usingTsImpl ? RangeError : TypeError这类三元表达式钉住分叉（如 construction.js），并"钉住每一个已知分歧：任何一侧改动都会让对应 cell 失败"，同时要求在断言分歧的文件头注释中记录该分歧。台账中每个测试名（garbageSourceValidation、pullCountShape等）在 main.js 的具名导出清单里都能找到对应项，形成"文档台账 → 测试名 → 源码断言"的完整追溯链。

六、运行方式与来源迁移史

运行方式继承自父级约定（见 src/tests/streams/AGENTS.md 的 Running 一节）：

bazel test //src/tests/streams/readable/... --nocache_test_results

每个 cell 带@all-compat-flags与@all-autogates变体，另有默认关闭的@gc-stress变体（需--test_tag_filters=显式启用）。测试通过workerd test的test()处理器执行，断言来自node:assert（两个主配置的标志清单里都有nodejs_compat）。

文档最后记录了套件的**消费来源（Consumed sources）**迁移史，说明其"从散装测试迁入 WPT 风格套件"的演进：

• streams-async-iterator-test.js（已删除，整体迁入async-iteration.js）；
• streams-tee-edge-cases-test.js的值流半部分（迁入tee.js）；
• streams-test.js的 from/readAll/reader/cancel 家族（BYOB + writable + TransformStream 测试留在原地）；
• api/streams/streams-test.js 的 tee 重入三件套 + ResponseTextLargeBody（迁入tee-reentrancy.js/integration-body.js）；
• ts-webstreams-test.js的三个对等 body 测试（其 TS 身份断言保留原地）；
• streams-js-test.js刻意不动：其用例交错值流与字节流两节，值流半部分将在 readable-byte 套件消费字节半部分时再迁移。

七、小结

src/tests/streams/readable/展示了一种可复用的兼容性工程范式：以"测试即规范"的立场，用一份编号台账把双实现之间的每一条可观察差异（含已知缺陷与有意偏离 spec 的行为）钉到具体测试上；用.capnp常量保证两个 cell 嵌入完全相同的测试代码；用"按名钉标志而非钉日期"的配置策略让测试在 2000-01-01 与 2999-12-31 两个极端日期下都稳定；再用 legacy cell 为旧 compat date 的存量 worker 保留回归守卫。对于需要维护双实现（或多实现）兼容性的项目，这套"分歧台账 + which-impl 分叉断言 + 单元级标志钉住"的组合是一个值得参照的完整样本。

【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd