knitting 0.1.63 → 0.1.70

package/src/knitting_doorbell.cc

@@ -0,0 +1,220 @@
+#include <node.h>
+#include <uv.h>
+#include <v8.h>
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <unordered_set>
+
+namespace knitting_doorbell {
+
+struct CompletionDoorbell {
+  uv_async_t async;
+  v8::Isolate* isolate;
+  v8::Global<v8::Context> context;
+  v8::Global<v8::Function> callback;
+  std::atomic<bool> closed{false};
+};
+
+std::mutex doorbells_mutex;
+std::unordered_set<CompletionDoorbell*> doorbells;
+
+void ThrowType(v8::Isolate* isolate, const char* message) {
+  isolate->ThrowException(v8::Exception::TypeError(
+    v8::String::NewFromUtf8(isolate, message).ToLocalChecked()
+  ));
+}
+
+void ThrowUv(v8::Isolate* isolate, const char* message, int status) {
+  const char* uv_message = uv_strerror(status);
+  v8::Local<v8::String> detail = v8::String::NewFromUtf8(
+    isolate,
+    uv_message == nullptr ? message : uv_message
+  ).ToLocalChecked();
+  isolate->ThrowException(v8::Exception::Error(detail));
+}
+
+bool ReadDoorbellPointer(
+  const v8::FunctionCallbackInfo<v8::Value>& args,
+  CompletionDoorbell** out
+) {
+  v8::Isolate* isolate = args.GetIsolate();
+  if (args.Length() < 1 || !args[0]->IsBigInt()) {
+    ThrowType(isolate, "completion doorbell pointer must be a bigint");
+    return false;
+  }
+
+  bool lossless = false;
+  uint64_t raw = args[0].As<v8::BigInt>()->Uint64Value(&lossless);
+  if (!lossless || raw == 0) {
+    ThrowType(isolate, "completion doorbell pointer must be non-zero");
+    return false;
+  }
+
+  *out = reinterpret_cast<CompletionDoorbell*>(
+    static_cast<uintptr_t>(raw)
+  );
+  return true;
+}
+
+void DisposeDoorbell(uv_handle_t* handle) {
+  auto* doorbell = static_cast<CompletionDoorbell*>(handle->data);
+  if (doorbell == nullptr) return;
+  doorbell->callback.Reset();
+  doorbell->context.Reset();
+  delete doorbell;
+}
+
+void InvokeDoorbell(uv_async_t* async) {
+  auto* doorbell = static_cast<CompletionDoorbell*>(async->data);
+  if (doorbell == nullptr || doorbell->closed.load(std::memory_order_acquire)) {
+    return;
+  }
+
+  v8::Isolate* isolate = doorbell->isolate;
+  v8::HandleScope scope(isolate);
+  v8::Local<v8::Context> context = doorbell->context.Get(isolate);
+  v8::Local<v8::Function> callback = doorbell->callback.Get(isolate);
+  if (context.IsEmpty() || callback.IsEmpty()) return;
+
+  v8::Context::Scope context_scope(context);
+  v8::TryCatch try_catch(isolate);
+  // This is called by Node's event-loop thread, not the worker that rang the
+  // handle. Do not let a user callback exception escape into libuv.
+  v8::MaybeLocal<v8::Value> call_result = callback->Call(
+    context,
+    v8::Undefined(isolate),
+    0,
+    nullptr
+  );
+  (void)call_result;
+}
+
+void CleanupDoorbell(void* data);
+
+void CloseDoorbell(CompletionDoorbell* doorbell, bool remove_cleanup_hook) {
+  bool should_close = false;
+  {
+    std::lock_guard<std::mutex> lock(doorbells_mutex);
+    auto found = doorbells.find(doorbell);
+    if (found == doorbells.end()) return;
+    doorbell->closed.store(true, std::memory_order_release);
+    doorbells.erase(found);
+    should_close = true;
+  }
+
+  if (remove_cleanup_hook) {
+    node::RemoveEnvironmentCleanupHook(
+      doorbell->isolate,
+      CleanupDoorbell,
+      doorbell
+    );
+  }
+  if (should_close && !uv_is_closing(reinterpret_cast<uv_handle_t*>(&doorbell->async))) {
+    uv_close(reinterpret_cast<uv_handle_t*>(&doorbell->async), DisposeDoorbell);
+  }
+}
+
+void CleanupDoorbell(void* data) {
+  CloseDoorbell(static_cast<CompletionDoorbell*>(data), false);
+}
+
+void CreateCompletionDoorbell(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  if (args.Length() < 1 || !args[0]->IsFunction()) {
+    ThrowType(isolate, "createCompletionDoorbell(callback) requires a function");
+    return;
+  }
+
+  uv_loop_t* loop = node::GetCurrentEventLoop(isolate);
+  if (loop == nullptr) {
+    ThrowUv(isolate, "Node event loop is unavailable", UV_EINVAL);
+    return;
+  }
+
+  auto* doorbell = new CompletionDoorbell();
+  doorbell->isolate = isolate;
+  doorbell->async.data = doorbell;
+  const int status = uv_async_init(loop, &doorbell->async, InvokeDoorbell);
+  if (status != 0) {
+    delete doorbell;
+    ThrowUv(isolate, "uv_async_init failed", status);
+    return;
+  }
+
+  doorbell->context.Reset(isolate, isolate->GetCurrentContext());
+  doorbell->callback.Reset(isolate, args[0].As<v8::Function>());
+  {
+    std::lock_guard<std::mutex> lock(doorbells_mutex);
+    doorbells.insert(doorbell);
+  }
+  node::AddEnvironmentCleanupHook(isolate, CleanupDoorbell, doorbell);
+
+  args.GetReturnValue().Set(v8::BigInt::NewFromUnsigned(
+    isolate,
+    static_cast<uint64_t>(reinterpret_cast<uintptr_t>(doorbell))
+  ));
+}
+
+void RingCompletionDoorbell(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  CompletionDoorbell* doorbell = nullptr;
+  if (!ReadDoorbellPointer(args, &doorbell)) return;
+
+  int status = UV_EINVAL;
+  {
+    // The registry guards a host close racing a worker-thread ring. Holding it
+    // through uv_async_send is safe: the send is non-blocking and coalesced.
+    std::lock_guard<std::mutex> lock(doorbells_mutex);
+    if (
+      doorbells.contains(doorbell) &&
+      !doorbell->closed.load(std::memory_order_acquire)
+    ) {
+      status = uv_async_send(&doorbell->async);
+    }
+  }
+  args.GetReturnValue().Set(status == 0);
+}
+
+void UnrefCompletionDoorbell(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  CompletionDoorbell* doorbell = nullptr;
+  if (!ReadDoorbellPointer(args, &doorbell)) return;
+
+  bool found = false;
+  {
+    std::lock_guard<std::mutex> lock(doorbells_mutex);
+    if (doorbells.contains(doorbell)) {
+      uv_unref(reinterpret_cast<uv_handle_t*>(&doorbell->async));
+      found = true;
+    }
+  }
+  args.GetReturnValue().Set(found);
+}
+
+void CloseCompletionDoorbell(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  CompletionDoorbell* doorbell = nullptr;
+  if (!ReadDoorbellPointer(args, &doorbell)) return;
+
+  bool found = false;
+  {
+    std::lock_guard<std::mutex> lock(doorbells_mutex);
+    found = doorbells.contains(doorbell);
+  }
+  if (found) CloseDoorbell(doorbell, true);
+  args.GetReturnValue().Set(found);
+}
+
+void Initialize(
+  v8::Local<v8::Object> exports,
+  v8::Local<v8::Value>,
+  v8::Local<v8::Context>
+) {
+  NODE_SET_METHOD(exports, "createCompletionDoorbell", CreateCompletionDoorbell);
+  NODE_SET_METHOD(exports, "ringCompletionDoorbell", RingCompletionDoorbell);
+  NODE_SET_METHOD(exports, "unrefCompletionDoorbell", UnrefCompletionDoorbell);
+  NODE_SET_METHOD(exports, "closeCompletionDoorbell", CloseCompletionDoorbell);
+}
+
+NODE_MODULE_CONTEXT_AWARE(NODE_GYP_MODULE_NAME, Initialize)
+
+}  // namespace knitting_doorbell

package/src/memory/knitting-body.d.ts

@@ -0,0 +1,44 @@
+/**
+ * One handle for a request body, whichever way it travels.
+ *
+ * A body uses either pooled arena bytes or a moved `BufferReference`;
+ * `allocOrRefer()` hides that choice behind one disposable handle.
+ *
+ * The host owns the body, while each send holds it until the call settles, so
+ * early disposal cannot recycle bytes still in use by a worker. The worker gets
+ * a `Uint8Array` and never releases the body.
+ *
+ * The bytes are valid only until the host releases. A worker that wants to
+ * keep them past the call must copy.
+ */
+import { type KnittingAllocator, type KnittingBufferDescriptor } from "./knitting-buffer.js";
+import { BufferReference } from "../connections/buffer-reference.js";
+/** What `allocator.transport()` hands a worker so it can attach once. */
+export type KnittingTransport = ReturnType<KnittingAllocator["transport"]>;
+/**
+ * The value a body travels as. Three shapes, because a body has three homes:
+ * the arena (a descriptor), the heap (a moved reference), or a standalone
+ * buffer when the body did not fit the arena. `openBody` resolves all three.
+ */
+export type KnittingBodyWire = KnittingBufferDescriptor | BufferReference | SharedArrayBuffer;
+/** The host's handle: send `wire`, read `u8()`, and dispose when done. */
+export type KnittingBody = {
+    /** Pass this as the task argument. */
+    readonly wire: KnittingBodyWire;
+    readonly byteLength: number;
+    /** The bytes on the host side, whichever transport was chosen. */
+    u8(): Uint8Array;
+    release(): void;
+    [Symbol.dispose](): void;
+};
+/**
+ * Attach this worker to the host's arena and return the opener.
+ *
+ * Call it once per worker from a bootstrap module -- `transport()` nests
+ * SharedArrayBuffers in an object, which survives the bootstrap's structured
+ * clone but not a task payload's encoding.
+ *
+ * The returned function is total over `KnittingBodyWire`: whatever the host
+ * chose, the task sees bytes.
+ */
+export declare const createBodyReader: (transport: KnittingTransport) => ((wire: KnittingBodyWire) => Uint8Array);

package/src/memory/knitting-body.js

@@ -0,0 +1,51 @@
+/**
+ * One handle for a request body, whichever way it travels.
+ *
+ * A body uses either pooled arena bytes or a moved `BufferReference`;
+ * `allocOrRefer()` hides that choice behind one disposable handle.
+ *
+ * The host owns the body, while each send holds it until the call settles, so
+ * early disposal cannot recycle bytes still in use by a worker. The worker gets
+ * a `Uint8Array` and never releases the body.
+ *
+ * The bytes are valid only until the host releases. A worker that wants to
+ * keep them past the call must copy.
+ */
+import { attachKnittingAllocator, } from "./knitting-buffer.js";
+import { isBufferReferenceValue, } from "../connections/buffer-reference.js";
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+/**
+ * True for a buffer that arrived over a transport.
+ *
+ * knitting ships a SharedArrayBuffer by pointer and rebuilds it branded as an
+ * ArrayBuffer, so `instanceof SharedArrayBuffer` is false on the far side even
+ * though the memory is shared.
+ */
+const isTransportedBuffer = (value) => (hasSharedArrayBuffer && value instanceof SharedArrayBuffer) ||
+    value instanceof ArrayBuffer;
+/**
+ * Attach this worker to the host's arena and return the opener.
+ *
+ * Call it once per worker from a bootstrap module -- `transport()` nests
+ * SharedArrayBuffers in an object, which survives the bootstrap's structured
+ * clone but not a task payload's encoding.
+ *
+ * The returned function is total over `KnittingBodyWire`: whatever the host
+ * chose, the task sees bytes.
+ */
+export const createBodyReader = (transport) => {
+    const lane = attachKnittingAllocator(transport);
+    return (wire) => {
+        // Moved: this worker holds the only live alias, and the host releases the
+        // reference once the call settles.
+        if (isBufferReferenceValue(wire))
+            return wire.toUint8Array();
+        // A body too large for the arena travels as its own buffer. It carries no
+        // identity, so there is nothing to borrow and nothing to release.
+        if (isTransportedBuffer(wire))
+            return lane.adopt(wire).u8();
+        // Pooled: borrowed for the call. `borrow` is what makes it impossible for
+        // this worker to release an identity the host still owns.
+        return lane.adopt(wire, { borrow: true }).u8();
+    };
+};

package/src/memory/knitting-buffer-http.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Read an HTTP request body into a pooled shared-memory region.
+ *
+ * Two strategies, because neither wins everywhere:
+ *
+ *   - **Materialize.** Let the runtime assemble the body on the heap, then
+ *     copy it into a region. One copy, no per-chunk bookkeeping.
+ *   - **Stream.** Preallocate a region of the declared length and write each
+ *     chunk straight into it. No heap body at all, but a reader per request.
+ *
+ * A small body arrives as a single chunk, so streaming saves no copy and still
+ * pays for the reader; a large one is split across many chunks, and there
+ * writing straight into the region wins on p99 as much as on throughput. The
+ * crossover is the body size at which chunking starts, so it depends on the
+ * runtime and the network in front of it -- `HTTP_BODY_STREAM_THRESHOLD_BYTES`
+ * is a starting point, not a constant of nature. `bench/http-body-oha.ts`
+ * sweeps it.
+ *
+ * Streaming needs a length up front, so a body with no `Content-Length` is
+ * always materialized. Reserving an upper bound instead is possible with
+ * `allocator.allocUpTo()` but is a worse default: the reservation has to fit
+ * the bump window, and a bound that does not fit takes the standalone-SAB
+ * valve.
+ */
+import type { KnittingAllocator, KnittingSharedBuffer } from "./knitting-buffer.js";
+import { BufferReference } from "../connections/buffer-reference.js";
+/**
+ * Bodies at least this large stream, if their length is known in advance.
+ *
+ * The crossover between the two strategies is runtime-dependent; re-measure
+ * with `bench/http-body-oha.ts` if body sizes cluster near it.
+ */
+export declare const HTTP_BODY_STREAM_THRESHOLD_BYTES: number;
+/**
+ * Bodies at or above this size are moved with `BufferReference` by
+ * `readBodyOrRefer`.
+ *
+ * Intentionally higher than `SHARED_RETURN_MIN_BYTES`, the crossover for an
+ * already materialized buffer: request handling has to consume the stream
+ * first, so the move only pays once the body is large enough to dominate that.
+ * Tune it for the application's body sizes and in-flight request count.
+ */
+export declare const HTTP_BODY_REFERENCE_THRESHOLD_BYTES: number;
+export type ReadBodyOptions = {
+    /**
+     * Bodies of at least this many bytes stream into a preallocated region
+     * instead of being materialized first. Below the crossover, streaming is
+     * slower; see `HTTP_BODY_STREAM_THRESHOLD_BYTES`.
+     */
+    streamThresholdBytes?: number;
+    /**
+     * Reject a body larger than this.
+     *
+     * A declared length is a claim by the client, and the memory is committed
+     * on the strength of that claim before a single byte arrives -- so an
+     * unbounded default is a request-sized allocation primitive for anyone who
+     * can send a header. A body that declares nothing is read against the same
+     * cap rather than buffered whole and measured afterwards.
+     *
+     * `readBodyIntoRegion` defaults it to the allocator's `arenaByteLength`,
+     * which is the most a pooled region can hold anyway. The helpers that
+     * allocate somewhere else cannot infer a bound and require one.
+     */
+    maxByteLength?: number;
+};
+/** `readBodyIntoBytes` allocates through a caller-supplied function, so only
+ * the caller knows what that allocation can afford. */
+export type ReadBodyIntoBytesOptions = ReadBodyOptions & {
+    maxByteLength: number;
+};
+/** `readBodyOrRefer` exists to handle bodies too large for the arena, so
+ * neither the pool nor the crossover implies a bound. */
+export type ReadBodyOrReferOptions = ReadBodyOptions & {
+    maxByteLength: number;
+    /** Move bodies at or above this size with `BufferReference`. */
+    referenceAboveBytes?: number;
+};
+/** What these helpers need of an allocator: a region, and its ceiling. */
+export type RegionAllocator = Pick<KnittingAllocator, "alloc" | "arenaByteLength">;
+export type ReadBodyPayload = KnittingSharedBuffer | BufferReference;
+/**
+ * Read `request`'s body into bytes from `allocate`.
+ *
+ * The generic form behind `readBodyIntoRegion`. `allocate` may be anything
+ * that hands back a writable `Uint8Array` of the requested size -- a
+ * `KnittingAllocator` region's view, or `pool.sharedArgBytes`, which borrows
+ * from the arena the workers already read from, so the bytes reach a task
+ * without a further copy.
+ *
+ * The returned view is exactly the bytes that arrived, which is not
+ * necessarily what `Content-Length` claimed.
+ */
+export declare const readBodyIntoBytes: (request: Request, allocate: (byteLength: number) => Uint8Array, { streamThresholdBytes, maxByteLength, }: ReadBodyIntoBytesOptions) => Promise<Uint8Array>;
+/**
+ * Read `request`'s body into a region from `allocator`.
+ *
+ * The caller owns the region and must `release()` it (or let the
+ * allocator's collector backstop reclaim it). The returned region's
+ * `byteLength` is what
+ * actually arrived, which is not necessarily what `Content-Length` claimed.
+ */
+export declare const readBodyIntoRegion: (request: Request, allocator: RegionAllocator, { streamThresholdBytes, maxByteLength, }?: ReadBodyOptions) => Promise<KnittingSharedBuffer>;
+/**
+ * Read a request body into the representation that is cheaper to transport.
+ *
+ * Below `referenceAboveBytes`, the result is a `KnittingSharedBuffer` owned by
+ * the supplied allocator. At or above it, the request is materialized into a
+ * heap `ArrayBuffer` and moved into a `BufferReference`; constructing the
+ * reference detaches the materialized source. The caller owns the result and
+ * must release a `KnittingSharedBuffer` or `BufferReference` when finished.
+ *
+ * A missing `Content-Length` is materialized before choosing the result, so a
+ * genuinely large chunked body still takes the reference path. This helper is
+ * for thread workers; `BufferReference` cannot cross a process boundary.
+ */
+export declare const readBodyOrRefer: (request: Request, allocator: RegionAllocator, { referenceAboveBytes, ...bodyOptions }: ReadBodyOrReferOptions) => Promise<ReadBodyPayload>;

package/src/memory/knitting-buffer-http.js

@@ -0,0 +1,255 @@
+/**
+ * Read an HTTP request body into a pooled shared-memory region.
+ *
+ * Two strategies, because neither wins everywhere:
+ *
+ *   - **Materialize.** Let the runtime assemble the body on the heap, then
+ *     copy it into a region. One copy, no per-chunk bookkeeping.
+ *   - **Stream.** Preallocate a region of the declared length and write each
+ *     chunk straight into it. No heap body at all, but a reader per request.
+ *
+ * A small body arrives as a single chunk, so streaming saves no copy and still
+ * pays for the reader; a large one is split across many chunks, and there
+ * writing straight into the region wins on p99 as much as on throughput. The
+ * crossover is the body size at which chunking starts, so it depends on the
+ * runtime and the network in front of it -- `HTTP_BODY_STREAM_THRESHOLD_BYTES`
+ * is a starting point, not a constant of nature. `bench/http-body-oha.ts`
+ * sweeps it.
+ *
+ * Streaming needs a length up front, so a body with no `Content-Length` is
+ * always materialized. Reserving an upper bound instead is possible with
+ * `allocator.allocUpTo()` but is a worse default: the reservation has to fit
+ * the bump window, and a bound that does not fit takes the standalone-SAB
+ * valve.
+ */
+import { BufferReference } from "../connections/buffer-reference.js";
+/**
+ * Bodies at least this large stream, if their length is known in advance.
+ *
+ * The crossover between the two strategies is runtime-dependent; re-measure
+ * with `bench/http-body-oha.ts` if body sizes cluster near it.
+ */
+export const HTTP_BODY_STREAM_THRESHOLD_BYTES = 192 * 1024;
+/**
+ * Bodies at or above this size are moved with `BufferReference` by
+ * `readBodyOrRefer`.
+ *
+ * Intentionally higher than `SHARED_RETURN_MIN_BYTES`, the crossover for an
+ * already materialized buffer: request handling has to consume the stream
+ * first, so the move only pays once the body is large enough to dominate that.
+ * Tune it for the application's body sizes and in-flight request count.
+ */
+export const HTTP_BODY_REFERENCE_THRESHOLD_BYTES = 2 * 1024 * 1024;
+/** The declared body length, or -1 when it is absent or not a sane integer. */
+const declaredLength = (request) => {
+    const header = request.headers.get("content-length");
+    if (header === null)
+        return -1;
+    const value = Number(header);
+    return Number.isSafeInteger(value) && value >= 0 ? value : -1;
+};
+/**
+ * Read a body whose length was not declared, against `maxByteLength`.
+ *
+ * Buffering the whole thing and checking afterwards is the same exposure as
+ * trusting `Content-Length`: an attacker only has to omit the header. Reading
+ * against the cap stops at the first chunk that crosses it, and cancels the
+ * stream so the sender stops rather than filling a socket buffer.
+ */
+const materialize = async (request, maxByteLength) => {
+    if (!Number.isFinite(maxByteLength) || request.body === null) {
+        return request.bytes !== undefined
+            ? await request.bytes()
+            : new Uint8Array(await request.arrayBuffer());
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = request.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxByteLength) {
+                await reader.cancel();
+                throw new RangeError(`body is over the ${maxByteLength} byte limit`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (let i = 0; i < chunks.length; i++) {
+        out.set(chunks[i], at);
+        at += chunks[i].byteLength;
+    }
+    return out;
+};
+/**
+ * Read `request`'s body into bytes from `allocate`.
+ *
+ * The generic form behind `readBodyIntoRegion`. `allocate` may be anything
+ * that hands back a writable `Uint8Array` of the requested size -- a
+ * `KnittingAllocator` region's view, or `pool.sharedArgBytes`, which borrows
+ * from the arena the workers already read from, so the bytes reach a task
+ * without a further copy.
+ *
+ * The returned view is exactly the bytes that arrived, which is not
+ * necessarily what `Content-Length` claimed.
+ */
+export const readBodyIntoBytes = async (request, allocate, { streamThresholdBytes = HTTP_BODY_STREAM_THRESHOLD_BYTES, maxByteLength, }) => {
+    if (!Number.isSafeInteger(maxByteLength) || maxByteLength < 0) {
+        throw new RangeError("maxByteLength must be a non-negative safe integer");
+    }
+    const req = request;
+    const declared = declaredLength(req);
+    if (declared > maxByteLength) {
+        throw new RangeError(`body declares ${declared} bytes, over the ${maxByteLength} limit`);
+    }
+    if (declared >= streamThresholdBytes && req.body !== null) {
+        const out = allocate(declared);
+        let at = 0;
+        const reader = req.body.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (at + value.byteLength > declared) {
+                    throw new RangeError(`body exceeds its declared ${declared} bytes`);
+                }
+                out.set(value, at);
+                at += value.byteLength;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        return at === declared ? out : out.subarray(0, at);
+    }
+    const bytes = await materialize(req, maxByteLength);
+    if (bytes.byteLength > maxByteLength) {
+        throw new RangeError(`body is ${bytes.byteLength} bytes, over the ${maxByteLength} limit`);
+    }
+    const out = allocate(bytes.byteLength);
+    out.set(bytes);
+    return out;
+};
+/**
+ * Read `request`'s body into a region from `allocator`.
+ *
+ * The caller owns the region and must `release()` it (or let the
+ * allocator's collector backstop reclaim it). The returned region's
+ * `byteLength` is what
+ * actually arrived, which is not necessarily what `Content-Length` claimed.
+ */
+export const readBodyIntoRegion = async (request, allocator, { streamThresholdBytes = HTTP_BODY_STREAM_THRESHOLD_BYTES, 
+// The arena is the ceiling on a pooled region: a larger body cannot be
+// pooled at all, it can only take the standalone-SAB valve, which is the
+// allocation an attacker would be aiming for.
+maxByteLength = allocator.arenaByteLength, } = {}) => {
+    const req = request;
+    const declared = declaredLength(req);
+    if (declared > maxByteLength) {
+        throw new RangeError(`body declares ${declared} bytes, over the ${maxByteLength} limit`);
+    }
+    // Stream only when the length is known and large enough to pay for it.
+    if (declared >= streamThresholdBytes && req.body !== null) {
+        const region = allocator.alloc(declared);
+        try {
+            const out = region.u8();
+            let at = 0;
+            const reader = req.body.getReader();
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    // Content-Length is a claim, not a guarantee. Writing past the
+                    // region would corrupt whatever region follows it in the arena.
+                    if (at + value.byteLength > declared) {
+                        throw new RangeError(`body exceeds its declared ${declared} bytes`);
+                    }
+                    out.set(value, at);
+                    at += value.byteLength;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            // A body shorter than it claimed leaves a tail of stale arena bytes;
+            // commit hands that tail back and reports the real length.
+            return at === declared ? region : region.commit(at);
+        }
+        catch (error) {
+            region.release();
+            throw error;
+        }
+    }
+    const bytes = await materialize(req, maxByteLength);
+    if (bytes.byteLength > maxByteLength) {
+        throw new RangeError(`body is ${bytes.byteLength} bytes, over the ${maxByteLength} limit`);
+    }
+    const region = allocator.alloc(bytes.byteLength);
+    try {
+        region.u8().set(bytes);
+        return region;
+    }
+    catch (error) {
+        region.release();
+        throw error;
+    }
+};
+const copyBytesIntoRegion = (bytes, allocator) => {
+    const region = allocator.alloc(bytes.byteLength);
+    try {
+        region.u8().set(bytes);
+        return region;
+    }
+    catch (error) {
+        region.release();
+        throw error;
+    }
+};
+/**
+ * Read a request body into the representation that is cheaper to transport.
+ *
+ * Below `referenceAboveBytes`, the result is a `KnittingSharedBuffer` owned by
+ * the supplied allocator. At or above it, the request is materialized into a
+ * heap `ArrayBuffer` and moved into a `BufferReference`; constructing the
+ * reference detaches the materialized source. The caller owns the result and
+ * must release a `KnittingSharedBuffer` or `BufferReference` when finished.
+ *
+ * A missing `Content-Length` is materialized before choosing the result, so a
+ * genuinely large chunked body still takes the reference path. This helper is
+ * for thread workers; `BufferReference` cannot cross a process boundary.
+ */
+export const readBodyOrRefer = async (request, allocator, { referenceAboveBytes = HTTP_BODY_REFERENCE_THRESHOLD_BYTES, ...bodyOptions }) => {
+    if (!Number.isSafeInteger(referenceAboveBytes) || referenceAboveBytes < 0) {
+        throw new RangeError("referenceAboveBytes must be a non-negative safe integer");
+    }
+    // Reference allocations need an explicit runtime size bound.
+    if (!Number.isSafeInteger(bodyOptions.maxByteLength) ||
+        bodyOptions.maxByteLength < 0) {
+        throw new RangeError("maxByteLength must be a non-negative safe integer");
+    }
+    const req = request;
+    const declared = declaredLength(req);
+    // A known-large body can stream directly into the heap buffer that will be
+    // moved. A body without a length must also use this path so we can choose on
+    // the actual byte count after consuming it.
+    if (declared < 0 || declared >= referenceAboveBytes) {
+        const bytes = await readBodyIntoBytes(request, (byteLength) => new Uint8Array(byteLength), bodyOptions);
+        if (bytes.byteLength >= referenceAboveBytes) {
+            return new BufferReference(bytes);
+        }
+        return copyBytesIntoRegion(bytes, allocator);
+    }
+    return readBodyIntoRegion(request, allocator, bodyOptions);
+};