workerd 流管道 pipeTo/pipeThrough 双实现一致性测试指南分歧账本、挂起纪律与兼容性标志【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd本文基于 workerdCloudflare Workers 的 JavaScript / Wasm 运行时源码中的 piping 测试套件规范 展开系统讲解pipeTo/pipeThrough在 C 与 TypeScript 两套流实现下的行为规范、已知分歧、测试组织方式与底层实现原理。读完本文你将理解 workerd 如何以测试为规范工件锁定流管道语义掌握 11 条双实现分歧的具体表现并能在实际开发中借助该套件验证流管道行为。套件定位为什么 workerd 需要专门的 piping 测试workerd 同时维护着两套 Web Streams 实现一套是基于 V8 的 C 原生实现src/workerd/api/streams/下的ReadableStreamInternalController、WritableStreamInternalController等另一套是 TypeScript 实现由typescript_implemented_streams兼容性标志开启见 which-impl.js 中的globalThis.Cloudflare.compatibilityFlags[typescript_implemented_streams]。两套实现都必须遵循 WHATWG Streams 规范而流管道piping是连接可读流与可写流的核心编排机制涉及锁、背压、错误/关闭传播、AbortSignal 等大量状态机细节是两套实现最易产生行为分歧的区域。src/tests/streams/piping/套件正是为此而生。其 AGENTS.md 开篇即声明了本套件的核心方法论测试即规范normative artifactAGENTS.md 只是对 piping 行为的非正式规范Informal specification真正的权威工件是套件内的测试代码本身文档与测试保持 lockstep同步演进。边界清晰端点endpoint自身的行为如 writable、transform、readable、readable-byte 的状态机细节属于兄弟套件writable、transform、readable、readable-byte 等而 identity↔identity 的管道包括循环 pipeThrough 钉死用例位于 identity 套件的pipe-integration.js见 identity 套件。与 WPT 互补而非重复套件是对//src/wpt:streams的补充complements。piping 中前向错误传播error-propagation-forward等 WPT 已覆盖的种子簇由本套件以双实现对照的方式重写钉死而 WPT 的close-propagation-backward与error-propagation-backward在 C 实现下因挂起hang而被禁用这块领土由本套件的close-propagation.js以**有界观察BOUNDED observations**方式接管。套件结构与运行方式模块地图AGENTS.md 给出了完整的模块地图各模块的职责如下表所示模块覆盖范围pipe-matrix.js整体迁移自 pipe-streams-test.js35 个用例pipeThrough pipeTo 在 JS↔native 所有方向上的组合、prevent* 选项组合、预中止与读取中途的 AbortSignal、tee 分支管道、排队关闭的目标端对应分歧账本 #1-#4api-surface.js品牌检查brand check账本 #5、选项 getter 读取顺序、抛异常的 getter、非法 signal、已锁定的 pipeThrough 端点error-propagation.js前向传播矩阵starts-errored × prevent* × truthy 强制转换、hwm 0 目标端账本 #6、自定义错误类型保持迁移自 streams-error-edge-cases-test.jsclose-propagation.jsWPT 禁用的反向传播领土有界观察对已管道化锁定目标端的外部 close/abort、写入抛错的反向传播账本 #7、空闲目标端 controller 报错账本 #8flow-control.js背压链迁移自 streams-backpressure-test.js、目标端停滞时的读取预取上限interop.js取消传播 ×2迁移自 api/streams/streams-test.js、FixedLengthStream账本 #9、预置端点配对账本 #10special-buffers.jsSharedArrayBuffer 与可扩容 ArrayBuffer 视图流经 native 与 JS 管道端点迁移自 pipe-write-special-buffer-test.js强化为内容校验账本 #11legacy-pipes.js无兼容性标志未开流构造器的 legacy 单元data-volumes.js端到端管道数据量1 MiB pipeTo JS→JS、8 MiB pipeThrough 链、1 MiB JS→identity 带 body 回读、1 MiB identity→JS 带并发写入者——全部字节级精确这些模块通过 main.js 作为入口聚合导出Explicit named re-exports only仅显式具名再导出并由 piping-modules.capnp 统一嵌入embed为 workerd worker 模块保证所有测试单元嵌入完全相同的代码。四个 Bazel 测试单元Bazel 构建文件 通过wd_test规则把同一套测试模块注册到四个单元piping-cpp.wd-test针对 C 实现的主单元默认日期配置。piping-ts.wd-test以--experimental参数运行针对 TypeScript 实现。piping-cpp-pedantic.wd-testC 主单元外加**无日期dateless**的pedantic_wpt标志经探测该标志在本套件表面上无可观察差异因此共享模块无需分叉unbranched。piping-cpp-legacy.wd-test无标志的旧版回归守护单元仅 C。注意其generate_all_compat_flags_variant False——因为在 2999-12-31 的全兼容标志日期下该单元刻意省略的标志会全部打开从而失去回归意义。piping-cpp.wd-test 中钉死了主单元所依赖的兼容性标志集合nodejs_compat, streams_enable_constructors, transformstream_enable_standard_constructor, capture_async_api_throws, workers_api_getters_setters_on_prototype, set_tostring_tag, fixup-transform-stream-backpressure, writable_stream_spec_compliant_writer,其中nodejs_compat提供node:assert与node:test的mockstreams_enable_constructorstransformstream_enable_standard_constructor提供 JS 支持的管道端点其余标志则与兄弟套件一致地控制拒绝/抛出形态、访问器位置、泵背压与 writer 行为。运行方式为标准的 Bazel 测试流程例如bazel test //src/tests/streams/piping:piping-cpp各单元目标名由wd_test依据src属性生成。C 与 TypeScript 双实现分歧账本AGENTS.md 的核心是一份 11 条目的分歧账本Divergence ledger逐条记录了 C 与 TypeScript 两套实现的可观察差异及其钉死位置pinned in。以下完整继承并对照源码展开#领域CTypeScript钉死位置1非字节块管道进 native identity字符串按 UTF-8 编码后两端都能通过数字块使管道失败——C 拒绝并报 This WritableStream only supports writing byte types.通过非致命的写入拒绝管道路径非致命 write-rejection 管道路径暴露 identity 的校验 TypeError目标端中止下游读取拒绝pipeThroughJsToInternal2完成 pipeThrough 后的可写锁保持锁定getWriter 抛异常规范 finalize管道落定时两端锁都释放——输出 done 之后一个宏任务macrotask.locked确定性为 false 且 getWriter() 成功释放级联与输出的 done 投递不同步因此循环退出瞬间的读取未规定.locked与 getWriter 共享同一谓词在任一瞬时永不互相矛盾pipeThroughJsToInternalCloses3关闭后写入的拒绝消息This WritableStream has been closed.Cannot write to a stream that is closing or closedCLOSED_WRITE_MSG辅助常量pipeToInternalToJsSimple、pipeToInternalToJsClose4在 pipeTo 之前排队 ws.close()管道锁定两端、等待以 This destination writable stream is closed. 取消源然后RESOLVES见测试中 TODO(conform)管道立即 REJECTDestination closed before the pipe completed以同一错误取消源preventCancel 抑制从未观察到锁被持有pipeToJsToJsCloseQueuedDestination(PreventCancel)5对损坏this的 pipeTo 品牌检查同步抛错在 capture_async_api_throws 包装之前WPT general.any 种子带坏目标端的真实流则 REJECT两端都 REJECT规范行为brandChecks6目标端 hwm 0从不渴望无论如何写入一个可用块——忽略 desiredSizeWPT dest never desires chunks 种子族从不写入规范行为sourceErroredAfterChunkHwmZero7preventCancel 的失败管道后的源队列尚未写入的块仍可读预读read-ahead已消费它新的读取会 PEND有界观察destWriteThrowsMidPipePreventCancel8管道等待读取时目标端 controller error()半传播以该错误取消源但FULFILL管道 promiseREJECT 管道并以该错误取消源规范行为destControllerErrorsMidPipe9经管道触发的 FixedLengthStream 长度违规溢出管道永不落定有界观察下溢永不落定溢出REJECT 抛 RangeError下溢永不落定非一致性对齐fixedLengthStreamPipeOverflow/Underflow10已关闭源 → 已关闭目标端REJECT 抛 TypeErrorC 偏差规范的顺序化关闭条件给予前向关闭优先权FULFILL规范行为WPT multiple-propagation closed readable to closed writable 钉死 fulfillmentclosedSourceToClosedDest11SharedArrayBuffer 支持视图进 CompressionStream复制共享字节可往返写入路径 REJECT 抛 TypeError The provided value is not of type (ArrayBuffer or ArrayBufferView)规范无 [AllowShared] 的 BufferSource——而其 identity 流接受同一视图sabViewThroughCompressionRoundTrip账本条目在源码中的具体形态账本 #1非字节块pipe-matrix.js 的pipeThroughJsToInternal演示了完整过程——chunks依次为[hello, there, hello, 123]字符串块在两种实现下都被 UTF-8 编码穿过 identity数字块123触发写入拒绝。TypeScript 路径通过reader.read()的rejects断言 TypeError消息为IdentityTransformStream: chunk must be a BufferSource or stringC 路径则通过consumeStream拒绝消息为 This WritableStream only supports writing byte types.且断言output中三个字符串块全部到达。账本 #2管道结束后的锁释放pipeThroughJsToInternalCloses 是理解锁语义的关键用例。它揭示了规范 pipe finalize 的微妙之处释放级联经由微任务传播与 pipeThrough 输出流的 done 投递不同步pipeThrough 丢弃管道 promise因此在for await循环退出瞬间读取.locked属于未规定行为unspecified必须等待一个宏任务scheduler.wait(0)后状态才确定性落定——TypeScript 下.locked false且getWriter()成功C 下则保持locked true且getWriter()抛 This WritableStream is currently locked to a writer.。测试注释特别强调.locked与getWriter()共享同一谓词在任一瞬时不可能互相矛盾。账本 #4预排队关闭pipeToJsToJsCloseQueuedDestination 是行为差异最戏剧化的一条。C 的管道循环只在每次迭代顶部检查完全关闭的目标端因此排队中或在途的 close 不会阻止管道启动并发出读取当 close 算法在管道中途完成时WritableStreamJsController::doClose发现写侧管道锁仍被持有——该用例正是回归测试doClose必须释放源的管道锁并取消源因为关闭会反向传播而不是单独拆除写侧锁那会让源被永久锁定。测试中 C 路径断言源以This destination writable stream is closed.的 TypeError 被取消、管道 promiseresolve附 TODO(conform)规范的关闭必须反向传播本应让管道 promise 以该 TypeError 拒绝TypeScript 路径则断言立即拒绝锁从未被观察到持有。账本 #5品牌检查api-surface.js 的brandChecks展示了capture_async_api_throws 包装也无法捕获的同步抛错ReadableStream.prototype.pipeTo.call({}, ws)在 C 下同步throwsTypeError发生在 capture 包装之前TypeScript 下则返回被拒绝的 promise规范行为而真实流 坏目标端在两种实现下都 REJECT。账本 #6hwm 0 目标端error-propagation.js 的sourceErroredAfterChunkHwmZero用new CountQueuingStrategy({ highWaterMark: 0 })构造从不渴望的目标端。C 的管道循环忽略目标端 desiredSize仍然写入已入队的a断言wrote.length 1TypeScript 尊重背压从未写入断言wrote.length 0。两者都以源错误拒绝管道并把错误传给 abort 钩子。账本 #8空闲目标端报错close-propagation.js 的destControllerErrorsMidPipe用outcomeOf辅助函数Promise.racescheduler.wait(250)做有界观察源永不产出pull 不 enqueue管道等待读取时目标端wc.error(derr)。TypeScript 下管道 REJECT 且源以同一错误被取消C 下管道FULFILL但源同样以该错误被取消——半传播。账本 #9FixedLengthStreaminterop.js 中fixedLengthStreamPipeOverflow向声明长度 3 的流写入hello5 字节TypeScript 下管道 REJECT 抛 RangeErrorC 下管道永不落定有界观察 pending。fixedLengthStreamPipeUnderflow声明 5、只写 2 字节在两种实现下都永不落定——测试注释称之为非一致性的对齐parity of nonconformance关闭步骤本应暴露长度错误。账本 #10双关闭配对closedSourceToClosedDest 对应 WPT multiple-propagation 种子。规范的关闭条件按顺序求值源已关闭 → 前向关闭目标端对已关闭目标端平凡解析优先于 目标端已关闭 → TypeError反向关闭。TypeScript 遵循规范 FULFILLC 则应用目标端关闭的 TypeError 而 REJECT。账本 #11SAB 视图special-buffers.js 的sabViewThroughCompressionRoundTrip用SharedArrayBuffer支撑的Uint8Array视图经 CompressionStream 往返C 复制共享字节并成功往返TypeScript 的 CompressionStream 写入路径按规范 REJECTBufferSource 无 [AllowShared]而同一视图经 identity 流则被接受compression 套件的sharedArrayBufferChunkDiverges钉死直接写入形态。已验证的兼容性边界Parity除分歧账本外AGENTS.md 还专门列出值得注意的兼容性probed, pinned清单——这些行为在两种实现上已确认对齐并被测试钉死完整的前向错误传播核心矩阵起始即报错的拒绝/钩子身份在两端一致preventAbort/preventCancel含truthy 强制转换见 sourceStartsErroredPreventAbort 中对[true, yes]的遍历、preventAbort 下目标端保持可用选项装配getter 读取顺序为[preventAbort, preventCancel, preventClose, signal]见 optionGetterReadOrder通过Object.defineProperty的 getter 收集读取序列并deepStrictEqual断言抛异常的 getter 以该异常拒绝且不取任何锁坏 signal 抛 TypeError见 invalidSignalRejectedpipeThrough 对已锁定端点的同步抛错且不扰动另一侧见 pipeThroughLockedEndpoints自定义错误类型/实例的保持CustomStreamError的子类名与扩展属性code经 pipeTo / pipeThrough 后身份不变见 errorTypePreservationPipeTo / PipeThrough经 native identity与JS transform 的取消传播源以 CLOSED而非 errored结束所有锁释放见 cancelPropagationThroughIdentity / JsTransform对已管道化锁定目标端的外部 close()/abort() 拒绝而管道继续进行见 externalCloseOnPipedDestRejects带钩子身份的反向写入错误传播经pipeThrough().pipeTo()链的背压见 backpressurePipeChain目标端停滞时预读 ≤ 3源 hwm 1——与账本 #6 形成对照pipeStopsPullingWhenDestStalls 断言stalledPulls 3且停滞期间拉取数保持稳定FixedLengthStream 精确长度管道fixedLengthStreamPipeExact已关闭源 → 活跃目标端管道关闭目标端closedSourceToLiveDest。挂起纪律Hang disciplineAGENTS.md 用一节专门强调管道测试的挂起纪律这是本套件最独特的工程约束绝不要让管道带着一个活跃的无限源和一个可释放的停滞写入共存释放它会产生无界泵unbounded pump使两种实现上的事件循环饥饿120 秒 Bazel 超时。收尾wind down的正确顺序是先让源报错erroring the source FIRST再释放写入。flow-control.js 的pipeStopsPullingWhenDestStalls完整示范了这一纪律第一个 sink 写入用stuckpromise 停滞源有限10 块但从不关闭断言停滞期间只发生 1 次写入、拉取数 ≤ 3 且稳定收尾时先rc.error(srcErr)再releaseWrite()使管道在停滞写入落定后确定性拒绝。这正是为什么 WPT 的 backward 传播文件在 C 下被禁用、而本套件用outcomeOf带 250ms 超时的Promise.race做有界观察的原因——测试中钉死的 pending 结果是故意的缺陷钉deliberate defect pin而非漏洞。兼容性标志矩阵AGENTS.md 用一张表归纳了各标志的钉死范围标志主单元其他单元streams_enable_constructorstransformstream_enable_standard_constructor2022-11-30是JS 支持的端点piping-cpp-legacyJS 构造器抛标志命名错误NATIVE→NATIVE 管道body ↔ IdentityTransformStream无标志即可工作capture_async_api_throws账本 #5 的坏目标端拒绝形态—pedantic_wpt无日期 opt-inpiping-cpp-pedantic单元在本套件表面上零可观察差异其他nodejs_compat、getters-on-prototype、toString tag、backpressure fixup、spec-compliant writer与兄弟套件一致—legacy 单元的实际形态见 legacy-pipes.jslegacyJsEndpointsGated断言new ReadableStream({})/new WritableStream({})抛包含/streams_enable_constructors/的错误而legacyNativePipeTo/legacyNativePipeThrough证明new Response(hello).body与IdentityTransformStream之间的纯 native 管道在无标志下正常工作——这正是 Workers 在流构造器标志引入之前就有的核心用法响应体管道。注意 BUILD.bazel 中该单元的generate_all_compat_flags_variant False注释解释了原因日期推到 2999-12-31 时本单元刻意省略的标志会全部自动打开。pedantic 单元的意义在于pedantic_wpt由 which-impl.js 读取会调整 C 的完成操作协调abort/close/cancel 竞态使其与规范对齐经探测该标志在本套件表面上无差异因此共享模块无分叉运行——这本身就是两套实现行为已足够接近规范的证据。底层实现探源C Pipe 对象与锁状态机分歧账本中的许多条目都能在 C 源码中找到对应结构。internal.h 中的Pipe类是理解 C 管道实现的核心Pipe继承kj::PtrTarget是由目标端 controller 拥有的队列事件a queue event owned by the destination controller其生命周期贯穿管道全程它通过kj::WeakPipe弱引用weakRef检测自身是否仍存活——这直接解释了账本 #1、#4 等中途摧毁 Pipe场景的安全性包装方法不得跨委托调用持有强kj::PtrPipe因为checkSignal()会排空目标端队列、带取消原因的releaseSource()会运行用户 JS两者都可能销毁 Pipe弱引用保护的是不进入已死亡的 Pipe委托调用返回后无人再触碰 PipeState结构持有ownerWritableStream与weakRefisAborted()通过weakRef nullptr判断Pipe::Flags用位域打包preventAbort / preventClose / preventCancel三个布尔选项构造函数接收源、目标 controller、promise resolver 与可选的 AbortSignal。internal.h 还展示了源侧读锁与写锁的状态机ReadLockState StateMachineUnlocked, Locked, PipeLocked, ReaderLocked其中PipeLocked是管道持有的读锁状态Unlocked → PipeLockedtryPipeLock()与PipeLocked → UnlockedreleasePipeLock()构成管道锁的进出写侧同理有WriteLockState StateMachineUnlocked, Locked, PipeLocked, WriterLocked并注明PipeLocked → Unlocked的释放路径包括管道完成或 doClose/doError/drain 期间。第 355 行附近还提到用于使用 desiredSize 与 ready 实现背压信号的机制——这与账本 #6C 忽略 desiredSize形成有趣对照背压信号机制存在但管道循环的写入决策在 hwm 0 场景下并未完全遵守它。AbortSignal 的中途中止路径同样有清晰的代码对应。pipeToJsToInternalAbortMidRead 的注释完整描述了调用链内部管道循环的中止路径中读取续体观察到已中止的 signalPipe::State::checkSignal→Pipe::checkSignal随后取消并释放源同步运行该测试的 cancel 算法再排空目标端队列——在调用中途摧毁 Pipe 自身。该用例是对管道拆除加固pipe teardown hardening的回归测试debug 构建中若在调用期间持有强kj::PtrPipe会触发 PtrTarget 存活断言assert。JS→JS 变体 pipeToJsToJsAbortMidRead 则走WritableLockImpl::PipeLocked::checkSignal路径并验证中止续体不得触碰已销毁的锁状态。大数据量与特殊缓冲区验证字节级精确的数据量测试data-volumes.js 用素数取模连续模式PATTERN_MODULUS 251构造可校验的数据源与校验接收器patternChunk(offset, length)生成(offset i) % 251的字节模式verifyingSink在写入时逐字节校验模式连续性。四个用例覆盖1 MiBpipeToJS→JS8 MiBpipeThrough链1 MiB JS→identity带 body 回读1 MiB identity→JS带并发写入者。所有用例要求字节精确byte-exact且模式校验在任何字节错位处给出精确的断点位置——这比简单比较哈希更能定位实现缺陷。特殊缓冲区视图special-buffers.js 从长度检查强化为内容校验assertAllBytes逐字节断言SharedArrayBuffer 支撑的视图定义上不可转移与可扩容 ArrayBuffer 视图流经 native 与 JS 管道端点。要点SAB 视图经 CompressionStreamC 复制共享字节并往返TypeScript 按规范拒绝账本 #11两种情况下共享缓冲区都不被修改SAB / 可扩容视图经 IdentityTransformStream 与 JS 管道链JS 路径投递的是原视图本身、不做拷贝the very view uncopied可扩容缓冲区保持可扩容——这意味着 JS 管道端点在特殊缓冲区上表现为零拷贝传递。测试迁移史与维护约定AGENTS.md 末尾记录了本套件的来源这对理解测试组织的演进至关重要已删除或缩减的消费源pipe-streams-test.js与pipe-write-special-buffer-test.js整体删除streams-error-edge-cases-test.js−2、streams-backpressure-test.js−1、api/streams/streams-test.js−2partiallyReadStream与inspect保留。安全回归文件保持独立且权威identity-transform-stream-uaf、pipe-source-error-uaf等安全回归测试不与本套件混编——安全回归与功能测试的分层隔离是 workerd 流测试组织的一条明确约定。这也呼应了 AGENTS.md 的定位声明测试是规范工件。当流行为需要调整时先改测试、再改实现文档与测试同步演进kept in lockstep——这是本套件可长期作为可检索的行为规范的根本原因。结语把测试当作可检索的流管道规范src/tests/streams/piping/AGENTS.md及其套件展示了 workerd 处理双实现、单规范这一难题的完整方法论以测试为规范工件、以分歧账本显式记录偏差、以有界观察替代可能挂起的 WPT 用例、以兼容性标志矩阵管理日期驱动的行为开关、以模块地图保持套件的可维护性。对于任何需要理解 workerd 流管道语义、排查pipeTo/pipeThrough行为差异、或在自己的流实现中做一致性验证的开发者这份套件以及配套的 writable、transform、readable、identity 等兄弟套件都是比规范文档更精确、比 WPT 更贴近 workerd 实际行为的第一手资料。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
workerd 流管道 pipeTo/pipeThrough 双实现一致性测试指南：分歧账本、挂起纪律与兼容性标志
workerd 流管道 pipeTo/pipeThrough 双实现一致性测试指南分歧账本、挂起纪律与兼容性标志【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd本文基于 workerdCloudflare Workers 的 JavaScript / Wasm 运行时源码中的 piping 测试套件规范 展开系统讲解pipeTo/pipeThrough在 C 与 TypeScript 两套流实现下的行为规范、已知分歧、测试组织方式与底层实现原理。读完本文你将理解 workerd 如何以测试为规范工件锁定流管道语义掌握 11 条双实现分歧的具体表现并能在实际开发中借助该套件验证流管道行为。套件定位为什么 workerd 需要专门的 piping 测试workerd 同时维护着两套 Web Streams 实现一套是基于 V8 的 C 原生实现src/workerd/api/streams/下的ReadableStreamInternalController、WritableStreamInternalController等另一套是 TypeScript 实现由typescript_implemented_streams兼容性标志开启见 which-impl.js 中的globalThis.Cloudflare.compatibilityFlags[typescript_implemented_streams]。两套实现都必须遵循 WHATWG Streams 规范而流管道piping是连接可读流与可写流的核心编排机制涉及锁、背压、错误/关闭传播、AbortSignal 等大量状态机细节是两套实现最易产生行为分歧的区域。src/tests/streams/piping/套件正是为此而生。其 AGENTS.md 开篇即声明了本套件的核心方法论测试即规范normative artifactAGENTS.md 只是对 piping 行为的非正式规范Informal specification真正的权威工件是套件内的测试代码本身文档与测试保持 lockstep同步演进。边界清晰端点endpoint自身的行为如 writable、transform、readable、readable-byte 的状态机细节属于兄弟套件writable、transform、readable、readable-byte 等而 identity↔identity 的管道包括循环 pipeThrough 钉死用例位于 identity 套件的pipe-integration.js见 identity 套件。与 WPT 互补而非重复套件是对//src/wpt:streams的补充complements。piping 中前向错误传播error-propagation-forward等 WPT 已覆盖的种子簇由本套件以双实现对照的方式重写钉死而 WPT 的close-propagation-backward与error-propagation-backward在 C 实现下因挂起hang而被禁用这块领土由本套件的close-propagation.js以**有界观察BOUNDED observations**方式接管。套件结构与运行方式模块地图AGENTS.md 给出了完整的模块地图各模块的职责如下表所示模块覆盖范围pipe-matrix.js整体迁移自 pipe-streams-test.js35 个用例pipeThrough pipeTo 在 JS↔native 所有方向上的组合、prevent* 选项组合、预中止与读取中途的 AbortSignal、tee 分支管道、排队关闭的目标端对应分歧账本 #1-#4api-surface.js品牌检查brand check账本 #5、选项 getter 读取顺序、抛异常的 getter、非法 signal、已锁定的 pipeThrough 端点error-propagation.js前向传播矩阵starts-errored × prevent* × truthy 强制转换、hwm 0 目标端账本 #6、自定义错误类型保持迁移自 streams-error-edge-cases-test.jsclose-propagation.jsWPT 禁用的反向传播领土有界观察对已管道化锁定目标端的外部 close/abort、写入抛错的反向传播账本 #7、空闲目标端 controller 报错账本 #8flow-control.js背压链迁移自 streams-backpressure-test.js、目标端停滞时的读取预取上限interop.js取消传播 ×2迁移自 api/streams/streams-test.js、FixedLengthStream账本 #9、预置端点配对账本 #10special-buffers.jsSharedArrayBuffer 与可扩容 ArrayBuffer 视图流经 native 与 JS 管道端点迁移自 pipe-write-special-buffer-test.js强化为内容校验账本 #11legacy-pipes.js无兼容性标志未开流构造器的 legacy 单元data-volumes.js端到端管道数据量1 MiB pipeTo JS→JS、8 MiB pipeThrough 链、1 MiB JS→identity 带 body 回读、1 MiB identity→JS 带并发写入者——全部字节级精确这些模块通过 main.js 作为入口聚合导出Explicit named re-exports only仅显式具名再导出并由 piping-modules.capnp 统一嵌入embed为 workerd worker 模块保证所有测试单元嵌入完全相同的代码。四个 Bazel 测试单元Bazel 构建文件 通过wd_test规则把同一套测试模块注册到四个单元piping-cpp.wd-test针对 C 实现的主单元默认日期配置。piping-ts.wd-test以--experimental参数运行针对 TypeScript 实现。piping-cpp-pedantic.wd-testC 主单元外加**无日期dateless**的pedantic_wpt标志经探测该标志在本套件表面上无可观察差异因此共享模块无需分叉unbranched。piping-cpp-legacy.wd-test无标志的旧版回归守护单元仅 C。注意其generate_all_compat_flags_variant False——因为在 2999-12-31 的全兼容标志日期下该单元刻意省略的标志会全部打开从而失去回归意义。piping-cpp.wd-test 中钉死了主单元所依赖的兼容性标志集合nodejs_compat, streams_enable_constructors, transformstream_enable_standard_constructor, capture_async_api_throws, workers_api_getters_setters_on_prototype, set_tostring_tag, fixup-transform-stream-backpressure, writable_stream_spec_compliant_writer,其中nodejs_compat提供node:assert与node:test的mockstreams_enable_constructorstransformstream_enable_standard_constructor提供 JS 支持的管道端点其余标志则与兄弟套件一致地控制拒绝/抛出形态、访问器位置、泵背压与 writer 行为。运行方式为标准的 Bazel 测试流程例如bazel test //src/tests/streams/piping:piping-cpp各单元目标名由wd_test依据src属性生成。C 与 TypeScript 双实现分歧账本AGENTS.md 的核心是一份 11 条目的分歧账本Divergence ledger逐条记录了 C 与 TypeScript 两套实现的可观察差异及其钉死位置pinned in。以下完整继承并对照源码展开#领域CTypeScript钉死位置1非字节块管道进 native identity字符串按 UTF-8 编码后两端都能通过数字块使管道失败——C 拒绝并报 This WritableStream only supports writing byte types.通过非致命的写入拒绝管道路径非致命 write-rejection 管道路径暴露 identity 的校验 TypeError目标端中止下游读取拒绝pipeThroughJsToInternal2完成 pipeThrough 后的可写锁保持锁定getWriter 抛异常规范 finalize管道落定时两端锁都释放——输出 done 之后一个宏任务macrotask.locked确定性为 false 且 getWriter() 成功释放级联与输出的 done 投递不同步因此循环退出瞬间的读取未规定.locked与 getWriter 共享同一谓词在任一瞬时永不互相矛盾pipeThroughJsToInternalCloses3关闭后写入的拒绝消息This WritableStream has been closed.Cannot write to a stream that is closing or closedCLOSED_WRITE_MSG辅助常量pipeToInternalToJsSimple、pipeToInternalToJsClose4在 pipeTo 之前排队 ws.close()管道锁定两端、等待以 This destination writable stream is closed. 取消源然后RESOLVES见测试中 TODO(conform)管道立即 REJECTDestination closed before the pipe completed以同一错误取消源preventCancel 抑制从未观察到锁被持有pipeToJsToJsCloseQueuedDestination(PreventCancel)5对损坏this的 pipeTo 品牌检查同步抛错在 capture_async_api_throws 包装之前WPT general.any 种子带坏目标端的真实流则 REJECT两端都 REJECT规范行为brandChecks6目标端 hwm 0从不渴望无论如何写入一个可用块——忽略 desiredSizeWPT dest never desires chunks 种子族从不写入规范行为sourceErroredAfterChunkHwmZero7preventCancel 的失败管道后的源队列尚未写入的块仍可读预读read-ahead已消费它新的读取会 PEND有界观察destWriteThrowsMidPipePreventCancel8管道等待读取时目标端 controller error()半传播以该错误取消源但FULFILL管道 promiseREJECT 管道并以该错误取消源规范行为destControllerErrorsMidPipe9经管道触发的 FixedLengthStream 长度违规溢出管道永不落定有界观察下溢永不落定溢出REJECT 抛 RangeError下溢永不落定非一致性对齐fixedLengthStreamPipeOverflow/Underflow10已关闭源 → 已关闭目标端REJECT 抛 TypeErrorC 偏差规范的顺序化关闭条件给予前向关闭优先权FULFILL规范行为WPT multiple-propagation closed readable to closed writable 钉死 fulfillmentclosedSourceToClosedDest11SharedArrayBuffer 支持视图进 CompressionStream复制共享字节可往返写入路径 REJECT 抛 TypeError The provided value is not of type (ArrayBuffer or ArrayBufferView)规范无 [AllowShared] 的 BufferSource——而其 identity 流接受同一视图sabViewThroughCompressionRoundTrip账本条目在源码中的具体形态账本 #1非字节块pipe-matrix.js 的pipeThroughJsToInternal演示了完整过程——chunks依次为[hello, there, hello, 123]字符串块在两种实现下都被 UTF-8 编码穿过 identity数字块123触发写入拒绝。TypeScript 路径通过reader.read()的rejects断言 TypeError消息为IdentityTransformStream: chunk must be a BufferSource or stringC 路径则通过consumeStream拒绝消息为 This WritableStream only supports writing byte types.且断言output中三个字符串块全部到达。账本 #2管道结束后的锁释放pipeThroughJsToInternalCloses 是理解锁语义的关键用例。它揭示了规范 pipe finalize 的微妙之处释放级联经由微任务传播与 pipeThrough 输出流的 done 投递不同步pipeThrough 丢弃管道 promise因此在for await循环退出瞬间读取.locked属于未规定行为unspecified必须等待一个宏任务scheduler.wait(0)后状态才确定性落定——TypeScript 下.locked false且getWriter()成功C 下则保持locked true且getWriter()抛 This WritableStream is currently locked to a writer.。测试注释特别强调.locked与getWriter()共享同一谓词在任一瞬时不可能互相矛盾。账本 #4预排队关闭pipeToJsToJsCloseQueuedDestination 是行为差异最戏剧化的一条。C 的管道循环只在每次迭代顶部检查完全关闭的目标端因此排队中或在途的 close 不会阻止管道启动并发出读取当 close 算法在管道中途完成时WritableStreamJsController::doClose发现写侧管道锁仍被持有——该用例正是回归测试doClose必须释放源的管道锁并取消源因为关闭会反向传播而不是单独拆除写侧锁那会让源被永久锁定。测试中 C 路径断言源以This destination writable stream is closed.的 TypeError 被取消、管道 promiseresolve附 TODO(conform)规范的关闭必须反向传播本应让管道 promise 以该 TypeError 拒绝TypeScript 路径则断言立即拒绝锁从未被观察到持有。账本 #5品牌检查api-surface.js 的brandChecks展示了capture_async_api_throws 包装也无法捕获的同步抛错ReadableStream.prototype.pipeTo.call({}, ws)在 C 下同步throwsTypeError发生在 capture 包装之前TypeScript 下则返回被拒绝的 promise规范行为而真实流 坏目标端在两种实现下都 REJECT。账本 #6hwm 0 目标端error-propagation.js 的sourceErroredAfterChunkHwmZero用new CountQueuingStrategy({ highWaterMark: 0 })构造从不渴望的目标端。C 的管道循环忽略目标端 desiredSize仍然写入已入队的a断言wrote.length 1TypeScript 尊重背压从未写入断言wrote.length 0。两者都以源错误拒绝管道并把错误传给 abort 钩子。账本 #8空闲目标端报错close-propagation.js 的destControllerErrorsMidPipe用outcomeOf辅助函数Promise.racescheduler.wait(250)做有界观察源永不产出pull 不 enqueue管道等待读取时目标端wc.error(derr)。TypeScript 下管道 REJECT 且源以同一错误被取消C 下管道FULFILL但源同样以该错误被取消——半传播。账本 #9FixedLengthStreaminterop.js 中fixedLengthStreamPipeOverflow向声明长度 3 的流写入hello5 字节TypeScript 下管道 REJECT 抛 RangeErrorC 下管道永不落定有界观察 pending。fixedLengthStreamPipeUnderflow声明 5、只写 2 字节在两种实现下都永不落定——测试注释称之为非一致性的对齐parity of nonconformance关闭步骤本应暴露长度错误。账本 #10双关闭配对closedSourceToClosedDest 对应 WPT multiple-propagation 种子。规范的关闭条件按顺序求值源已关闭 → 前向关闭目标端对已关闭目标端平凡解析优先于 目标端已关闭 → TypeError反向关闭。TypeScript 遵循规范 FULFILLC 则应用目标端关闭的 TypeError 而 REJECT。账本 #11SAB 视图special-buffers.js 的sabViewThroughCompressionRoundTrip用SharedArrayBuffer支撑的Uint8Array视图经 CompressionStream 往返C 复制共享字节并成功往返TypeScript 的 CompressionStream 写入路径按规范 REJECTBufferSource 无 [AllowShared]而同一视图经 identity 流则被接受compression 套件的sharedArrayBufferChunkDiverges钉死直接写入形态。已验证的兼容性边界Parity除分歧账本外AGENTS.md 还专门列出值得注意的兼容性probed, pinned清单——这些行为在两种实现上已确认对齐并被测试钉死完整的前向错误传播核心矩阵起始即报错的拒绝/钩子身份在两端一致preventAbort/preventCancel含truthy 强制转换见 sourceStartsErroredPreventAbort 中对[true, yes]的遍历、preventAbort 下目标端保持可用选项装配getter 读取顺序为[preventAbort, preventCancel, preventClose, signal]见 optionGetterReadOrder通过Object.defineProperty的 getter 收集读取序列并deepStrictEqual断言抛异常的 getter 以该异常拒绝且不取任何锁坏 signal 抛 TypeError见 invalidSignalRejectedpipeThrough 对已锁定端点的同步抛错且不扰动另一侧见 pipeThroughLockedEndpoints自定义错误类型/实例的保持CustomStreamError的子类名与扩展属性code经 pipeTo / pipeThrough 后身份不变见 errorTypePreservationPipeTo / PipeThrough经 native identity与JS transform 的取消传播源以 CLOSED而非 errored结束所有锁释放见 cancelPropagationThroughIdentity / JsTransform对已管道化锁定目标端的外部 close()/abort() 拒绝而管道继续进行见 externalCloseOnPipedDestRejects带钩子身份的反向写入错误传播经pipeThrough().pipeTo()链的背压见 backpressurePipeChain目标端停滞时预读 ≤ 3源 hwm 1——与账本 #6 形成对照pipeStopsPullingWhenDestStalls 断言stalledPulls 3且停滞期间拉取数保持稳定FixedLengthStream 精确长度管道fixedLengthStreamPipeExact已关闭源 → 活跃目标端管道关闭目标端closedSourceToLiveDest。挂起纪律Hang disciplineAGENTS.md 用一节专门强调管道测试的挂起纪律这是本套件最独特的工程约束绝不要让管道带着一个活跃的无限源和一个可释放的停滞写入共存释放它会产生无界泵unbounded pump使两种实现上的事件循环饥饿120 秒 Bazel 超时。收尾wind down的正确顺序是先让源报错erroring the source FIRST再释放写入。flow-control.js 的pipeStopsPullingWhenDestStalls完整示范了这一纪律第一个 sink 写入用stuckpromise 停滞源有限10 块但从不关闭断言停滞期间只发生 1 次写入、拉取数 ≤ 3 且稳定收尾时先rc.error(srcErr)再releaseWrite()使管道在停滞写入落定后确定性拒绝。这正是为什么 WPT 的 backward 传播文件在 C 下被禁用、而本套件用outcomeOf带 250ms 超时的Promise.race做有界观察的原因——测试中钉死的 pending 结果是故意的缺陷钉deliberate defect pin而非漏洞。兼容性标志矩阵AGENTS.md 用一张表归纳了各标志的钉死范围标志主单元其他单元streams_enable_constructorstransformstream_enable_standard_constructor2022-11-30是JS 支持的端点piping-cpp-legacyJS 构造器抛标志命名错误NATIVE→NATIVE 管道body ↔ IdentityTransformStream无标志即可工作capture_async_api_throws账本 #5 的坏目标端拒绝形态—pedantic_wpt无日期 opt-inpiping-cpp-pedantic单元在本套件表面上零可观察差异其他nodejs_compat、getters-on-prototype、toString tag、backpressure fixup、spec-compliant writer与兄弟套件一致—legacy 单元的实际形态见 legacy-pipes.jslegacyJsEndpointsGated断言new ReadableStream({})/new WritableStream({})抛包含/streams_enable_constructors/的错误而legacyNativePipeTo/legacyNativePipeThrough证明new Response(hello).body与IdentityTransformStream之间的纯 native 管道在无标志下正常工作——这正是 Workers 在流构造器标志引入之前就有的核心用法响应体管道。注意 BUILD.bazel 中该单元的generate_all_compat_flags_variant False注释解释了原因日期推到 2999-12-31 时本单元刻意省略的标志会全部自动打开。pedantic 单元的意义在于pedantic_wpt由 which-impl.js 读取会调整 C 的完成操作协调abort/close/cancel 竞态使其与规范对齐经探测该标志在本套件表面上无差异因此共享模块无分叉运行——这本身就是两套实现行为已足够接近规范的证据。底层实现探源C Pipe 对象与锁状态机分歧账本中的许多条目都能在 C 源码中找到对应结构。internal.h 中的Pipe类是理解 C 管道实现的核心Pipe继承kj::PtrTarget是由目标端 controller 拥有的队列事件a queue event owned by the destination controller其生命周期贯穿管道全程它通过kj::WeakPipe弱引用weakRef检测自身是否仍存活——这直接解释了账本 #1、#4 等中途摧毁 Pipe场景的安全性包装方法不得跨委托调用持有强kj::PtrPipe因为checkSignal()会排空目标端队列、带取消原因的releaseSource()会运行用户 JS两者都可能销毁 Pipe弱引用保护的是不进入已死亡的 Pipe委托调用返回后无人再触碰 PipeState结构持有ownerWritableStream与weakRefisAborted()通过weakRef nullptr判断Pipe::Flags用位域打包preventAbort / preventClose / preventCancel三个布尔选项构造函数接收源、目标 controller、promise resolver 与可选的 AbortSignal。internal.h 还展示了源侧读锁与写锁的状态机ReadLockState StateMachineUnlocked, Locked, PipeLocked, ReaderLocked其中PipeLocked是管道持有的读锁状态Unlocked → PipeLockedtryPipeLock()与PipeLocked → UnlockedreleasePipeLock()构成管道锁的进出写侧同理有WriteLockState StateMachineUnlocked, Locked, PipeLocked, WriterLocked并注明PipeLocked → Unlocked的释放路径包括管道完成或 doClose/doError/drain 期间。第 355 行附近还提到用于使用 desiredSize 与 ready 实现背压信号的机制——这与账本 #6C 忽略 desiredSize形成有趣对照背压信号机制存在但管道循环的写入决策在 hwm 0 场景下并未完全遵守它。AbortSignal 的中途中止路径同样有清晰的代码对应。pipeToJsToInternalAbortMidRead 的注释完整描述了调用链内部管道循环的中止路径中读取续体观察到已中止的 signalPipe::State::checkSignal→Pipe::checkSignal随后取消并释放源同步运行该测试的 cancel 算法再排空目标端队列——在调用中途摧毁 Pipe 自身。该用例是对管道拆除加固pipe teardown hardening的回归测试debug 构建中若在调用期间持有强kj::PtrPipe会触发 PtrTarget 存活断言assert。JS→JS 变体 pipeToJsToJsAbortMidRead 则走WritableLockImpl::PipeLocked::checkSignal路径并验证中止续体不得触碰已销毁的锁状态。大数据量与特殊缓冲区验证字节级精确的数据量测试data-volumes.js 用素数取模连续模式PATTERN_MODULUS 251构造可校验的数据源与校验接收器patternChunk(offset, length)生成(offset i) % 251的字节模式verifyingSink在写入时逐字节校验模式连续性。四个用例覆盖1 MiBpipeToJS→JS8 MiBpipeThrough链1 MiB JS→identity带 body 回读1 MiB identity→JS带并发写入者。所有用例要求字节精确byte-exact且模式校验在任何字节错位处给出精确的断点位置——这比简单比较哈希更能定位实现缺陷。特殊缓冲区视图special-buffers.js 从长度检查强化为内容校验assertAllBytes逐字节断言SharedArrayBuffer 支撑的视图定义上不可转移与可扩容 ArrayBuffer 视图流经 native 与 JS 管道端点。要点SAB 视图经 CompressionStreamC 复制共享字节并往返TypeScript 按规范拒绝账本 #11两种情况下共享缓冲区都不被修改SAB / 可扩容视图经 IdentityTransformStream 与 JS 管道链JS 路径投递的是原视图本身、不做拷贝the very view uncopied可扩容缓冲区保持可扩容——这意味着 JS 管道端点在特殊缓冲区上表现为零拷贝传递。测试迁移史与维护约定AGENTS.md 末尾记录了本套件的来源这对理解测试组织的演进至关重要已删除或缩减的消费源pipe-streams-test.js与pipe-write-special-buffer-test.js整体删除streams-error-edge-cases-test.js−2、streams-backpressure-test.js−1、api/streams/streams-test.js−2partiallyReadStream与inspect保留。安全回归文件保持独立且权威identity-transform-stream-uaf、pipe-source-error-uaf等安全回归测试不与本套件混编——安全回归与功能测试的分层隔离是 workerd 流测试组织的一条明确约定。这也呼应了 AGENTS.md 的定位声明测试是规范工件。当流行为需要调整时先改测试、再改实现文档与测试同步演进kept in lockstep——这是本套件可长期作为可检索的行为规范的根本原因。结语把测试当作可检索的流管道规范src/tests/streams/piping/AGENTS.md及其套件展示了 workerd 处理双实现、单规范这一难题的完整方法论以测试为规范工件、以分歧账本显式记录偏差、以有界观察替代可能挂起的 WPT 用例、以兼容性标志矩阵管理日期驱动的行为开关、以模块地图保持套件的可维护性。对于任何需要理解 workerd 流管道语义、排查pipeTo/pipeThrough行为差异、或在自己的流实现中做一致性验证的开发者这份套件以及配套的 writable、transform、readable、identity 等兄弟套件都是比规范文档更精确、比 WPT 更贴近 workerd 实际行为的第一手资料。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
