knitting 0.1.63 → 0.1.73

package/src/knitting_buffer_pointer.cc

@@ -9,6 +9,7 @@
 #include <memory>
 #include <mutex>
 #include <unordered_map>
+#include <vector>
 
 namespace knitting_buffer_pointer {
 
@@ -27,12 +28,51 @@ struct RetainedBackingStore {
   std::shared_ptr<v8::BackingStore> store;
   size_t byte_offset;
   size_t byte_length;
+  // The isolate that produced the move. This is only a registry hold: a
+  // consumer's adopted ArrayBuffer owns its own shared_ptr.
+  v8::Isolate* producer_isolate;
 };
 
 std::mutex backing_mutex;
 uint64_t next_backing_id = 1;
 std::unordered_map<uint64_t, RetainedBackingStore> retained_backings;
 
+// Node tears a worker down without running its JavaScript finalizers. Both
+// registries are process-global, so discard holds produced by that environment
+// during teardown. Any consumer that adopted a backing store already has an
+// independent shared_ptr and is unaffected.
+void CleanupEnvironment(void* data) {
+  v8::Isolate* isolate = static_cast<v8::Isolate*>(data);
+  // Collect first, destroy on scope exit: releasing a hold must not run under
+  // the registry lock that found it.
+  std::vector<std::unique_ptr<RetainedReference>> released_refs;
+  std::vector<RetainedBackingStore> released_backings;
+
+  {
+    std::lock_guard<std::mutex> lock(retained_mutex);
+    for (auto it = retained_refs.begin(); it != retained_refs.end();) {
+      if (it->second->isolate != isolate) {
+        ++it;
+        continue;
+      }
+      released_refs.push_back(std::move(it->second));
+      it = retained_refs.erase(it);
+    }
+  }
+
+  {
+    std::lock_guard<std::mutex> lock(backing_mutex);
+    for (auto it = retained_backings.begin(); it != retained_backings.end();) {
+      if (it->second.producer_isolate != isolate) {
+        ++it;
+        continue;
+      }
+      released_backings.push_back(std::move(it->second));
+      it = retained_backings.erase(it);
+    }
+  }
+}
+
 void ThrowType(v8::Isolate* isolate, const char* message) {
   isolate->ThrowException(v8::Exception::TypeError(
     v8::String::NewFromUtf8(isolate, message).ToLocalChecked()
@@ -318,7 +358,18 @@ void RetainBackingStore(const v8::FunctionCallbackInfo<v8::Value>& args) {
   uintptr_t address = reinterpret_cast<uintptr_t>(base + byte_offset);
 
   // Detach only after taking the shared_ptr; ordinary JS buffers use no key.
-  DetachDefaultArrayBuffer(buffer);
+  // A failed detach must not be ignored: retaining the store while the source
+  // stays live hands the consumer an "owned" buffer that still aliases memory
+  // the producer can write. WASM memory and externally pinned buffers are the
+  // ones that land here, and the caller falls back to copying.
+  if (!DetachDefaultArrayBuffer(buffer)) {
+    ThrowType(
+      isolate,
+      "retainBackingStore requires a detachable ArrayBuffer; this buffer "
+      "cannot be moved without leaving the source aliasing it"
+    );
+    return;
+  }
 
   uint64_t token = 0;
   {
@@ -327,7 +378,9 @@ void RetainBackingStore(const v8::FunctionCallbackInfo<v8::Value>& args) {
     if (token == 0) token = next_backing_id++;
     retained_backings.emplace(
       token,
-      RetainedBackingStore{ std::move(store), byte_offset, byte_length }
+      RetainedBackingStore{
+        std::move(store), byte_offset, byte_length, isolate
+      }
     );
   }
 
@@ -410,6 +463,8 @@ void Initialize(
   v8::Local<v8::Value>,
   v8::Local<v8::Context>
 ) {
+  v8::Isolate* isolate = exports->GetIsolate();
+  node::AddEnvironmentCleanupHook(isolate, CleanupEnvironment, isolate);
   NODE_SET_METHOD(exports, "getPointer", GetPointer);
   NODE_SET_METHOD(exports, "retainPointer", RetainPointer);
   NODE_SET_METHOD(exports, "releasePointer", ReleasePointer);

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>;