Subdirectory AGENTS.md files provide component-specific context (key classes, where-to-look tables, local conventions and anti-patterns). - Suggest updates to AGENTS.md when you find new high-level information - You should always determine if the current repository was checked out standalone or as a submodule of the larger workers project. - If checked out as a submodule, be aware that there is additional documentation and context in the root of that repository that is not present here. Look for the ../../README.md, ../../AGENTS.md, and…
Custom Bazel rules (wd_* macros) for C++, TypeScript, Rust, Cap'n Proto, and test orchestration. Uses bzlmod (MODULE.bazel), not WORKSPACE. This is build system definitions, NOT build output (bazel-bin/). Conventions: //tools/clang-tidy:workerd-lint builds a shared-object clang-tidy plugin that adds workerd-specific static checks: - jsg-visit-for-gc: flags JSG resource types whose visitable fields (jsg::Ref, jsg::JsRef, jsg::V8Ref, jsg::Function, jsg::Promise, jsg::Value, etc., plus kj::Maybe/Array/Vector/ OneOf and jsg::Optional wrappers thereof) are missing from visitForGc(). - workerd-angled-includes - requires includes of workers/capnproto code from different directories to use…
TypeScript implementations of Cloudflare product APIs (AI, D1, R2, Vectorize, etc.). It is common, but not required, for top-level .ts files to re-export from internal/ via cloudflare-internal: specifiers. This allows for a clean separation between public API surface and internal implementation details. Each product test directory contains: Mock wiring uses wrapped bindings: moduleName = "cloudflare-internal:<product>-api" with innerBindings pointing fetcher at the mock service. Shared instrumentation-test-helper.js lives in internal/test/.
TypeScript and JavaScript layer implementing Node.js compatible built-in modules for Workers. It is split across multiple layers: It is common, but not required, for top-level .ts files to re-export from internal/ via node-internal: specifiers. This allows for a clean separation between public API surface and internal implementation details. See README.md for 12 policy rules governing compat scope and philosophy. node:* modules are gated behind the nodejs_compat compatibility flag. The node:asynchooks module can be enabled individually via the nodejsals compatibility flag.
Per-isolate JavaScript/TypeScript bootstrap: scripts that run synchronously at context creation, before any user code. Gated by the per-isolate-javascript-bootstrap autogate (config: workerd-autogate-per-isolate-javascript-bootstrap). C++ entry point: src/workerd/io/per-isolate-bootstrap.c++. - Scripts are compiled as functions with a context-extension object — the pseudo-globals require, module, exports, compatFlags, autogates, primordials, utils are in scope but NOT on globalThis (see perisolate-env.d.ts). - Module system is bootstrap CommonJS: require('webstreams/queue') + module.exports = {...}. The src/node/ ESM-only rule does NOT apply here. Circular requires are a FATAL startup error…
TypeScript reimplementations of crypto APIs that must be replaced when the typescriptimplementedstreams compat flag is on. Parent directory conventions (primordials discipline, private-brand dispatch, no instanceof) apply — see src/per_isolate/AGENTS.md. DigestStream is one of only two WritableStream subclasses in the runtime. When the streams flag swaps globalThis.WritableStream for the TypeScript class, a C++ subclass of the C++ WritableStream no longer passes the brand checks used by pipeTo, and instanceof WritableStream becomes false. Reimplementing the subclass in TypeScript is what restores the…
TypeScript reimplementation of the File System Access API's writable stream, needed when the typescriptimplementedstreams compat flag is on. Parent directory conventions (primordials discipline, private-brand dispatch, no instanceof) apply — see src/per_isolate/AGENTS.md. FileSystemWritableFileStream is one of only two WritableStream subclasses in the runtime. When the streams flag swaps globalThis.WritableStream for the TypeScript class, a C++ subclass of the C++ WritableStream no longer passes the brand checks used by pipeTo, and instanceof WritableStream becomes false. Reimplementing the subclass in TypeScript is what…
TypeScript Streams implementation with a backend-blind reader layer and two consumer backends behind the StreamConsumer/ByteStreamConsumer fence. Authoritative docs are IN-SOURCE — read the file headers first. Parent directory conventions (primordials discipline, JSG capture trap, private-brand dispatch, no instanceof) apply here — see src/per_isolate/AGENTS.md. The spec's tee() gives each branch its own controller and queue, fed by a reader on the original. The queued backend instead has ONE queue with N consumers (cursors), one per live branch: tee() forks the stream's…
Python Workers runtime layer. Replaces Pyodide's loader with a minimal substitute adding memory snapshot support. TS+Python; modules registered as pyodide-internal:* BUILTIN modules. pool/emscriptenSetup.ts runs in vanilla V8 isolate -- CANNOT import C++ extension modules. Python SDK (internal/workers-api/) now lives in cloudflare/workers-py and is installed from PyPI. Keep existing code for backward compatibility; new features go to workers-py. Tests live in src/workerd/server/tests/python/. pywdtest.bzl macro: expands %PYTHONFEATUREFLAGS template, handles multiple Pyodide versions, snapshot generation/loading, per-version compat flag isolation. Tests are size="enormous" by…
A dozen or so Rust crates — mostly libraries, plus the gen-compile-cache binary — linked into workerd via CXX FFI. No Cargo workspace — entirely Bazel-driven (wdrustcrate.bzl / wdrustbinary.bzl). Clippy pedantic+nursery enabled; allow-unwrap-in-tests; clippy.toml and rustfmt.toml live at the repository root and apply to every crate. Rust does not have to live here. A crate that belongs to a component lives beside that component's C++, in the same package, in a subdirectory named for the crate: e.g. workerd's entry point…
This directory contains workerd's in-tree fork of cxx-rs. It was imported from the former cloudflare/workerd-cxx repository. Changes to the fork and its workerd consumers should use the in-tree Bazel labels and land atomically. The fork adds KJ exceptions, smart pointers, data types, and bidirectional async interop. Do not assume stock cxx-rs behavior when changing bridge generation or runtime code. Run commands from the workerd repository root: Important targets: Dependencies come from workerd's @crates_vendor repository and @capnp-cpp; do not add a…
Test suites for the parts of the Node.js compatibility layer (src/node/) that sit on top of the Web Streams implementation: the node:stream web-interop adapters, node:net sockets over connect() stream halves, and the node:http client and server over fetch() bodies. One subdirectory per area. Every test here runs against both streams implementations — the legacy C++ one (src/workerd/api/streams/) and the TypeScript one (src/per_isolate/webstreams/) — to prove the node layer behaves identically on either. The suite rules are those of src/tests/streams/AGENTS.md, applied…
An informal specification of how a node:http ClientRequest drives fetch() and the web streams underneath it — the request body it gathers and hands to fetch(), and the Response body it pumps into its IncomingMessage — derived from and kept in lockstep with the test suite in this directory. The tests are the normative artifact; this document maps behaviors to the tests that assert them. Every test runs against the C++ streams implementation (http-client-cpp.wd-test) and the TypeScript one (http-client-ts.wd-test). The…
An informal specification of how a node:http Server drives the web streams underneath it — the Request body it pumps into the IncomingMessage, and the ReadableStream the ServerResponse builds as the body of the Response it hands back to fetch() — derived from and kept in lockstep with the test suite in this directory. The tests are the normative artifact; this document maps behaviors to the tests that assert them. Every test runs against the C++ streams implementation (http-server-cpp.wd-test) and…
An informal specification of how a node:net Socket drives the two web-stream halves of the connect() socket underneath it, derived from and kept in lockstep with the test suite in this directory. The tests are the normative artifact; this document maps behaviors to the tests that assert them. Every test runs against the C++ streams implementation (net-cpp.wd-test) and the TypeScript one (net-ts.wd-test). The general net surface (option validation, DNS, BlockList, SocketAddress, BoundSocket, abort signals, reconnect) is owned by src/workerd/api/node/tests/net-nodejs-test.js; this…
An informal specification of the node:stream web-interop surface — Readable.toWeb/fromWeb, Writable.toWeb/fromWeb, Duplex.toWeb/fromWeb, Duplex.from, Readable.from over a web stream, pipeline, compose, finished, addAbortSignal, node:stream/web, node:stream/consumers — derived from and kept in lockstep with the test suite in this directory. The tests are the normative artifact; this document maps behaviors to the tests that assert them. Every test runs against the C++ streams implementation (stream-cpp.wd-test) and the TypeScript one (stream-ts.wd-test); the divergence ledger pins the places where the node layer observes a…
Streams test suite, organized WPT-style: one subdirectory per functional area (identity/, encoding/, compression/, digest/, strategies/, readable/, readable-byte/, writable/, transform/, piping/, inspect/, r2-patterns/, iocontext/, cache/, htmlrewriter/, formdata/, sockets/, scaling/). Every test here runs against both streams implementations — the legacy C++ one (src/workerd/api/streams/) and the TypeScript one (src/per_isolate/webstreams/) — to prove parity. A test that only makes sense for one implementation's internals belongs elsewhere. - One file, one behavior. Decompose aggressively; the filename names the behavior. Shared setup helpers go in…
The Cache API consuming and producing stream bodies under both stream implementations. The tests are the normative artifact. The general Cache API surface (headers, vary, purge, instrumentation) is owned by src/workerd/api/tests/cache-*; this suite owns the STREAMS interaction only. All cells wire cacheApiOutbound to a loopback cache-backend worker (cache-backend.js). A cache.put() arrives there as a PUT whose body is the SERIALIZED HTTP RESPONSE (status line + headers + CRLFCRLF + body); the backend splits at the header boundary, verifies the continuous…
An informal specification of the two Compression Streams classes as implemented in workerd, derived from — and kept in lockstep with — the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/streams/compression.{h,c++}, built on internal streams over the shared api/compression.h CodecStage) and the TypeScript implementation (src/perisolate/webstreams/compression.ts, behind typescriptimplemented_streams) are covered. The two wrap the SAME C++ zlib codec (the TS pair drives utils.newCompressionCodec handles), so codec output is parity by construction; divergences live…
An informal specification of the Cloudflare-specific DigestStream (a WritableStream subclass computing a hash digest) as implemented in workerd, derived from — and kept in lockstep with — the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/crypto/crypto.{h,c++}) and the TypeScript implementation (src/perisolate/crypto/digest-stream.ts, behind typescriptimplemented_streams) are covered. Both drive the SAME native digest context (utils.createDigestContext → CRC/OpenSSL contexts and the WTF-8/toWellFormed string encoder), so hashing, string encoding, and byte counting are parity by construction;…
CloudflareAGENTS.md