knitting 0.1.63 → 0.1.73

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);
+};

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

@@ -0,0 +1,250 @@
+/**
+ * `KnittingSharedBuffer` -- a thread-level pool of shared byte
+ * regions whose handle mimics `SharedArrayBuffer` rather than `Buffer`.
+ *
+ * Shape:
+ *
+ *   - Each thread owns one pool: its own arena SAB, its own lock sector, its
+ *     own identity space. Nothing is shared between pools except the SABs a
+ *     descriptor points at.
+ *   - `alloc(n)` takes a region from the lazy registry
+ *     (`lazy-region-registry.ts`). Identity exhaustion is not a failure: it
+ *     falls back to a standalone `SharedArrayBuffer`, so the pool never blocks
+ *     and never evicts a live borrow.
+ *   - The **region** owns the bytes. Views are minted from it (`u8()`,
+ *     `view(Ctor)`) and are plain, non-owning typed arrays. That is the same
+ *     split JS already has between a `SharedArrayBuffer` and its views, and it
+ *     is what keeps a `Float64Array` over the region from being silently
+ *     orphaned when some unrelated `Uint8Array` over it is dropped.
+ *   - The wire form is a descriptor, never bytes. A consumer thread attaches
+ *     to the producer's SABs once and materializes its own region handle.
+ *   - Release is one XOR into the owning lane's shared word, from whichever
+ *     thread holds the last handle.
+ *
+ * Why GC-driven release is safe here, given the lazy registry:
+ *
+ *   An identity is reusable only after the owner has *observed* its release
+ *   toggle (`reconcile` clears the used bit only when hostLast ^ workerBits
+ *   agree). So an identity cannot be handed out again while a release for it
+ *   is still outstanding, which means a late release can never apply to a
+ *   newer generation -- there is no ABA to protect against with a generation
+ *   counter. A forgotten handle costs one identity until the collector runs;
+ *   it cannot corrupt a live region. That degradation is capacity-only, and
+ *   the standalone-SAB fallback is what keeps it from turning into a stall.
+ *
+ *   That argument holds for exactly one releaser per identity, which is why
+ *   sending a region is `moveTo()` and not `describe()`. Two releasers
+ *   reintroduce the ABA the toggle cannot see: the first release lets
+ *   `reconcile` recycle the identity into a new region, and the second one
+ *   then frees a live stranger, whose bytes the next `alloc` hands out while
+ *   it is still being read. `describe()` is inspection only.
+ *
+ * What it still cannot do: revoke a view that was already minted. Minting is
+ * checked -- `u8()` after release throws instead of handing back a window onto
+ * somebody else's recycled bytes -- but a view handed out earlier and retained
+ * past release keeps aliasing the region. That is a JS limitation, not a
+ * design choice, and it is why `copy()` exists.
+ */
+import { type LazyRegionRegistryMode } from "./lazy-region-registry.js";
+import { type ReadBodyOrReferOptions } from "./knitting-buffer-http.js";
+import type { KnittingBody } from "./knitting-body.js";
+export declare const KNITTING_BUFFER_CODEC = "knitting.buffer";
+export type KnittingBufferDescriptor = {
+    codec: typeof KNITTING_BUFFER_CODEC;
+    kind: "region";
+    lane: number;
+    slot: number;
+    byteOffset: number;
+    byteLength: number;
+} | {
+    codec: typeof KNITTING_BUFFER_CODEC;
+    kind: "buffer";
+    lane: number;
+    byteLength: number;
+    buffer: SharedArrayBuffer;
+};
+type ViewConstructor<T extends ArrayBufferView> = new (buffer: ArrayBufferLike, byteOffset: number, length: number) => T;
+/**
+ * Module-internal ownership transfer. Reachable only through the allocator's
+ * `moveTo()`, which is the one place a region legitimately stops being ours.
+ */
+declare const DISOWN: unique symbol;
+/**
+ * An owned region of shared memory. Mints views; does not pretend to be one.
+ *
+ * Exported for `instanceof` and for typing. It is not constructible: regions
+ * come from `createKnittingAllocator().alloc()` or from adopting a descriptor.
+ */
+export declare class KnittingSharedBuffer {
+    #private;
+    constructor(mint: symbol, buffer: SharedArrayBuffer, byteOffset: number, byteLength: number, lane?: number, slot?: number, release?: (free: boolean) => void, trim?: (byteLength: number) => void);
+    get byteLength(): number;
+    get byteOffset(): number;
+    /** Owning lane, and the region identity within it (-1 for a standalone SAB). */
+    get lane(): number;
+    get slot(): number;
+    /** True once this handle is spent, whether by `release()` or by a move. */
+    get released(): boolean;
+    /** True when ownership was handed to a consumer by `allocator.moveTo()`. */
+    get moved(): boolean;
+    /**
+     * The standalone SharedArrayBuffer behind an overflow region, or undefined
+     * for a pooled one.
+     *
+     * Pooled regions deliberately have no way to reach their backing store: it
+     * is the whole arena, and handing it out would expose every other live
+     * region's bytes. An overflow region owns its buffer outright, so it is the
+     * only one that can travel as a buffer rather than as a descriptor.
+     */
+    static standaloneBufferOf(region: KnittingSharedBuffer): SharedArrayBuffer | undefined;
+    /**
+     * Surrender the identity without freeing it: after this the handle is inert
+     * and the consumer that adopted the descriptor is the sole releaser.
+     *
+     * A no-op on a spent handle, so a double `moveTo()` cannot hand the same
+     * identity to two consumers -- the second call throws before reaching here.
+     */
+    static [DISOWN](region: KnittingSharedBuffer): void;
+    /** The byte view. Memoized: repeated calls do not construct. */
+    u8(): Uint8Array;
+    /** A typed view over the whole region. Memoized per constructor. */
+    view<T extends ArrayBufferView>(Ctor: ViewConstructor<T>): T;
+    /**
+     * Give back the tail of a region that was reserved larger than needed, and
+     * report the region as `byteLength` bytes from here on.
+     *
+     * The point is streamed input of unknown length: an HTTP body with no
+     * `Content-Length` cannot be sized up front, so reserve an upper bound,
+     * write into it, then commit what actually arrived. Views minted before the
+     * commit are dropped, because their length is now wrong.
+     *
+     * Shrink only. Growing would mean relocating the bytes, which is the copy
+     * this whole path exists to avoid.
+     */
+    commit(byteLength: number): this;
+    /** An independently owned copy, valid after this region is released. */
+    copy(): Uint8Array;
+    release(): void;
+    [Symbol.dispose](): void;
+}
+/** A region handed over directly. One `instanceof`. */
+export declare const detectByInstance: (value: unknown) => KnittingSharedBuffer | undefined;
+/**
+ * A view this pool minted. One WeakMap hit, and it never touches `.buffer` --
+ * which matters because reading `.buffer` on a heap-backed typed array can
+ * materialize the ArrayBuffer wrapper on first access.
+ */
+export declare const detectByMintedView: (value: unknown) => KnittingSharedBuffer | undefined;
+/**
+ * Any view that lands inside a pool arena, including a `subarray` of a minted
+ * view. Costs a `.buffer` read, a WeakMap hit, and a binary search over the
+ * live extent table.
+ */
+export declare const detectByArena: (value: unknown) => KnittingBufferDescriptor | undefined;
+/**
+ * The full check the codec would run on a payload value. Returns a descriptor
+ * to ship by reference, or undefined to serialize the value normally.
+ *
+ * Detection only: like `describe()`, it does not transfer ownership. Whatever
+ * ships the descriptor owes the consumer one of the two safe pairings
+ * documented on `describe()`.
+ */
+export declare const detectRegion: (value: unknown) => KnittingBufferDescriptor | undefined;
+/**
+ * Bump window, and therefore the pool's memory high-water.
+ *
+ * Deliberately small. A wide window makes *allocation* cheaper -- the bump
+ * pointer runs longer before it has to reconcile and reclaim holes -- but that
+ * only counts the bookkeeping, never the bytes. Once real traffic writes them
+ * the ranking inverts: a wide window sprays consecutive regions across cold
+ * memory, and the cache misses cost more than the reconcile it avoided.
+ * Locality wins, so the default is a small multiple of a typical live set
+ * rather than the whole arena.
+ *
+ * It is a default, not a recommendation: size it to `payload x in-flight`.
+ * Two concurrent 1 MiB payloads do not fit here, and a reservation the window
+ * cannot satisfy takes the overflow path rather than waiting. `stats()`
+ * reports `overflows` precisely so this is visible instead of mysterious.
+ */
+export declare const DEFAULT_ARENA_BYTE_LENGTH: number;
+export type KnittingAllocatorOptions = {
+    lane?: number;
+    slots?: number;
+    /** Bump window; see `DEFAULT_ARENA_BYTE_LENGTH` for why small is the default. */
+    arenaByteLength?: number;
+    /**
+     * Collector backstop for a missed release.
+     *   true       register every region
+     *   false      never register: a missed release leaks an identity
+     *   "pressure" register only once live identities cross the watermark
+     *
+     * "pressure" applies the same argument as the lazy reconcile: while the pool
+     * is roomy a forgotten identity costs nothing, so paying the registration
+     * cost on every region to reclaim it early buys nothing. Registration starts
+     * when scarcity makes reclaim worth its price. Worst case is bounded: regions handed out while
+     * roomy are never registered, so at watermark w at most w of the identities
+     * can be stranded before every new region becomes reclaimable.
+     */
+    gcBackstop?: boolean | "pressure";
+    backstopWatermark?: number;
+};
+/** This pool's own counters merged with its region registry's. */
+export type KnittingAllocatorStats = {
+    pooled: number;
+    overflows: number;
+    registered: number;
+    live: number;
+    slots: number;
+    mode: LazyRegionRegistryMode;
+    tableLength: number;
+    tailEnd: number;
+    highWater: number;
+    reconciles: number;
+    firstFits: number;
+    appends: number;
+    resets: number;
+};
+/** What a consumer thread needs to attach: SABs, not pointers. */
+export type KnittingAllocatorTransport = {
+    lane: number;
+    lockSAB: SharedArrayBuffer;
+    arena: SharedArrayBuffer;
+    slots: number;
+    arenaByteLength: number;
+};
+/** Written out rather than inferred: JSR cannot resolve an inferred return type. */
+export type KnittingAllocator = {
+    lane: number;
+    /** Bump window this pool was built with; the ceiling on a pooled region. */
+    arenaByteLength: number;
+    alloc: (byteLength: number) => KnittingSharedBuffer;
+    allocUpTo: (maxByteLength: number) => KnittingSharedBuffer;
+    allocOrRefer: (request: Request, options: ReadBodyOrReferOptions) => Promise<KnittingBody>;
+    describe: (region: KnittingSharedBuffer) => KnittingBufferDescriptor;
+    moveTo: (region: KnittingSharedBuffer) => KnittingBufferDescriptor;
+    reconcile: () => boolean;
+    stats: () => KnittingAllocatorStats;
+    resetCounters: () => void;
+    transport: () => KnittingAllocatorTransport;
+};
+/** The consumer side of another thread's pool: it adopts, it never allocates. */
+export type AttachedKnittingAllocator = {
+    lane: number;
+    adopt: (descriptor: KnittingBufferDescriptor | SharedArrayBuffer, options?: {
+        gcBackstop?: boolean;
+        borrow?: boolean;
+    }) => KnittingSharedBuffer;
+};
+export declare const createKnittingAllocator: ({ lane, slots, arenaByteLength, gcBackstop, backstopWatermark, }?: KnittingAllocatorOptions) => KnittingAllocator;
+/**
+ * The consumer side of another thread's pool. It never allocates; it
+ * materializes regions over the producer's arena and releases the producer's
+ * identity with one XOR into the shared word.
+ */
+export declare const attachKnittingAllocator: ({ lane, lockSAB, arena, slots }: {
+    lane: number;
+    lockSAB: SharedArrayBuffer;
+    arena: SharedArrayBuffer;
+    slots: number;
+}) => AttachedKnittingAllocator;
+export {};