src/workerd/api/streams/

Web Streams API: ReadableStream, WritableStream, TransformStream. See README.md for terse reference (classification, state machines, safety patterns). See docs/streams.md for narrative tutorial.

ARCHITECTURE

Dual implementation behind unified API:

• Internal (internal.h): kj-backed, byte-only, single pending read, no JS queue
• Standard (standard.h): WHATWG spec, JS promises, value+byte, dual queues (data + pending reads)

Controller pattern: ReadableStream → ReadableStreamController → impl-specific controller. 4 pipe loop variants (kj↔kj, kj↔JS, JS↔kj, JS↔JS) selected by stream type combination. Tee uses kj::Rc<Entry> shared refs (non-standard optimization, avoids data copies).

Key deps: util/state-machine.h (stream state FSM), util/weak-refs.h, util/ring-buffer.h.

FILE MAP

File	Role
readable.{h,c++}	ReadableStream public API, ReaderImpl, readers
writable.{h,c++}	WritableStream public API, WriterImpl, writer
transform.{h,c++}	Standard TransformStream (JS algorithms)
identity-transform-stream.{h,c++}	Internal identity transform (byte-only, 1:1 read↔write)
internal.{h,c++}	ReadableStreamInternalController, WritableStreamInternalController
standard.{h,c++}	ReadableStreamJsController, WritableStreamJsController — main complexity (~5400 lines combined)
readable-source.{h,c++}	ReadableStreamSource — kj AsyncInputStream adapter
writable-sink.{h,c++}	WritableStreamSink — kj AsyncOutputStream adapter
readable-source-adapter.{h,c++}	Standard→Internal bridge (wraps JS controller as ReadableStreamSource)
writable-sink-adapter.{h,c++}	Standard→Internal bridge (wraps JS controller as WritableStreamSink)
common.{h,c++}	Shared types: ReadResult, StreamStates, controller interfaces
queue.{h,c++}	ValueQueue/ByteQueue for Standard stream backpressure
compression.{h,c++}	CompressionStream/DecompressionStream (zlib transforms)
encoding.{h,c++}	TextEncoderStream/TextDecoderStream

INVARIANTS

These rules MUST be followed when modifying stream code:

1. Always use deferControllerStateChange() when calling code that may invoke JS callbacks during a read/write operation
2. Always use snapshot() when iterating over consumers if loop body may trigger JS
3. Never access this after calling a StateListener callback that may destroy the object
4. Always re-check lock state in lambda continuations that may execute after lock release
5. Use WeakRef for any handle that user code may hold longer than the underlying object
6. State before promises: Transition state before resolving promises; pop queue entries only after resolving/rejecting their associated promises
7. No dangling captures: Prefer capturing this + re-acquiring refs inside lambdas over capturing raw references that may become dangling

See README.md §Safety Pattern Catalog for detailed When/Why/How for each pattern.

CODE REVIEW RULE

When reviewing changes to streams code, check whether the change requires updates to any of these documentation files:

• README.md — if the change alters stream classification (e.g. new stream type), state machine behavior, pipe loop selection, or introduces/modifies a safety pattern
• docs/streams.md — if the change affects user-visible behavior, data flow semantics, or backpressure mechanics that the tutorial describes
• This file (AGENTS.md) — if the change adds/removes files, changes the architecture summary, or introduces new invariants

Flag any needed doc updates in the review. Do not let behavioral or architectural changes land without corresponding documentation updates.