knitting 0.1.50 → 0.1.52

package/src/connections/buffer-reference-native.js

@@ -0,0 +1,217 @@
+import { RUNTIME } from "../common/runtime.js";
+import { loadNodeBufferPointerAddon } from "./node-buffer-pointer.js";
+const isSharedArrayBufferInstance = (value) => typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer;
+const assertMovableSource = (source) => {
+    const buffer = ArrayBuffer.isView(source) ? source.buffer : source;
+    if (isSharedArrayBufferInstance(buffer)) {
+        throw new TypeError("BufferReference expects ArrayBuffer-backed views; SharedArrayBuffer is already " +
+            "shared and cannot be moved");
+    }
+};
+const readSourceRegion = (source) => {
+    if (ArrayBuffer.isView(source)) {
+        return {
+            buffer: source.buffer,
+            byteOffset: source.byteOffset,
+            byteLength: source.byteLength,
+        };
+    }
+    return { buffer: source, byteOffset: 0, byteLength: source.byteLength };
+};
+/** Detach `buffer`, returning a fixed-length buffer over the same bytes (the move). */
+const detachIntoFixedLength = (buffer) => {
+    const transferable = buffer;
+    if (typeof transferable.transferToFixedLength === "function") {
+        return transferable.transferToFixedLength();
+    }
+    if (typeof transferable.transfer === "function") {
+        return transferable.transfer();
+    }
+    throw new TypeError("BufferReference requires ArrayBuffer.prototype.transfer to move a buffer in this runtime");
+};
+// ---------------------------------------------------------------------------
+// Deno/Bun pin moved buffers in JS and expose non-owning FFI aliases.
+// Tokens stay producer-isolate-local; consumers materialize from the pointer.
+// ---------------------------------------------------------------------------
+const ffiPinned = new Map();
+let nextFfiToken = 1n;
+const pinTransferred = (buffer) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, buffer);
+    return token;
+};
+const pinShared = (sab) => {
+    const token = nextFfiToken++;
+    ffiPinned.set(token, sab);
+    return token;
+};
+const releaseFfi = (token) => {
+    ffiPinned.delete(token);
+};
+const produceSharedFfi = (sab, readPointer) => {
+    // SABs are shared, not detached; pin keeps producer bytes alive.
+    const pointer = readPointer(new Uint8Array(sab));
+    const token = pinShared(sab);
+    return { token, pointer, byteOffset: 0, byteLength: sab.byteLength };
+};
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno?.UnsafePointer === undefined || deno.UnsafePointerView === undefined) {
+        throw new Error("Deno FFI (UnsafePointer) is not available in this runtime");
+    }
+    return deno;
+};
+const getBunFFI = () => {
+    const ffi = globalThis.Bun?.FFI;
+    if (typeof ffi?.ptr !== "function" || typeof ffi?.toArrayBuffer !== "function") {
+        throw new Error("Bun FFI (ptr/toArrayBuffer) is not available in this runtime");
+    }
+    return ffi;
+};
+const produceFfi = (source, readPointer) => {
+    assertMovableSource(source);
+    const { buffer, byteOffset, byteLength } = readSourceRegion(source);
+    const moved = detachIntoFixedLength(buffer);
+    // Region view over the moved buffer; the pointer captures the offset.
+    const region = new Uint8Array(moved, byteOffset, byteLength);
+    const pointer = readPointer(region);
+    const token = pinTransferred(moved);
+    return { token, pointer, byteOffset, byteLength };
+};
+const finishAlias = (alias, copy) => {
+    if (copy) {
+        const owned = alias.slice(0);
+        return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+    }
+    return { buffer: alias, byteOffset: 0, byteLength: alias.byteLength };
+};
+const createDenoCapabilities = () => {
+    const deno = getDeno();
+    return {
+        runtime: "deno",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => deno.UnsafePointer.value(deno.UnsafePointer.of(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = denoAlias(deno, pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
+const denoAlias = (deno, pointer, byteLength) => {
+    const handle = deno.UnsafePointer.create(pointer);
+    if (handle === null || handle === undefined) {
+        throw new Error("Deno.UnsafePointer.create returned null");
+    }
+    return new deno.UnsafePointerView(handle).getArrayBuffer(byteLength);
+};
+const createBunCapabilities = () => {
+    const ffi = getBunFFI();
+    return {
+        runtime: "bun",
+        supportsOwningAdopt: false,
+        produce: (view) => produceFfi(view, (region) => BigInt(ffi.ptr(region))),
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: releaseFfi,
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => BigInt(ffi.ptr(region))),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = ffi.toArrayBuffer(Number(pointer), 0, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+};
+// ---------------------------------------------------------------------------
+// Node: addon-backed owning move via shared_ptr<BackingStore>.
+// Older prebuilds fall back to non-owning retain/wrap.
+// ---------------------------------------------------------------------------
+const createNodeCapabilities = () => {
+    const addon = loadNodeBufferPointerAddon();
+    const owning = typeof addon.retainBackingStore === "function" &&
+        typeof addon.adoptBackingStore === "function" &&
+        typeof addon.releaseBackingStore === "function";
+    // SABs use JS pins plus non-owning aliases so no native handle survives teardown.
+    const sharedCapabilities = {
+        supportsSharedAdopt: false,
+        produceShared: (sab) => produceSharedFfi(sab, (region) => addon.getPointer(region)),
+        adoptShared: ({ pointer, byteLength }) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return { buffer: alias, byteOffset: 0, byteLength, isShared: false };
+        },
+        releaseShared: releaseFfi,
+    };
+    if (owning) {
+        return {
+            runtime: "node",
+            supportsOwningAdopt: true,
+            produce: (source) => {
+                assertMovableSource(source);
+                const r = addon.retainBackingStore(source);
+                return {
+                    token: r.token,
+                    pointer: r.pointer,
+                    byteOffset: r.byteOffset,
+                    byteLength: r.byteLength,
+                };
+            },
+            adopt: ({ token, byteOffset, byteLength }, opts) => {
+                const buffer = addon.adoptBackingStore(token);
+                if (opts?.copy) {
+                    const owned = buffer.slice(byteOffset, byteOffset + byteLength);
+                    return { buffer: owned, byteOffset: 0, byteLength: owned.byteLength };
+                }
+                return { buffer, byteOffset, byteLength };
+            },
+            release: (token) => void addon.releaseBackingStore(token),
+            ...sharedCapabilities,
+        };
+    }
+    // Legacy fallback: producer pins via retainPointer, consumer wraps non-owning.
+    return {
+        runtime: "node",
+        supportsOwningAdopt: false,
+        produce: (source) => {
+            assertMovableSource(source);
+            const retained = addon.retainPointer(source);
+            const byteOffset = ArrayBuffer.isView(source) ? source.byteOffset : 0;
+            return {
+                token: retained.token,
+                pointer: retained.pointer,
+                byteOffset,
+                byteLength: retained.byteLength,
+            };
+        },
+        adopt: ({ pointer, byteLength }, opts) => {
+            const alias = addon.wrapPointer(pointer, byteLength);
+            return finishAlias(alias, opts?.copy);
+        },
+        release: (token) => void addon.releasePointer(token),
+        ...sharedCapabilities,
+    };
+};
+let cached;
+export const getBufferReferenceCapabilities = () => {
+    if (cached !== undefined)
+        return cached;
+    switch (RUNTIME) {
+        case "node":
+            return cached = createNodeCapabilities();
+        case "deno":
+            return cached = createDenoCapabilities();
+        case "bun":
+            return cached = createBunCapabilities();
+        default:
+            throw new Error(`BufferReference cannot run in runtime "${RUNTIME}"`);
+    }
+};

package/src/connections/buffer-reference.d.ts

@@ -0,0 +1,76 @@
+import { type BufferReferenceRuntime } from "./buffer-reference-native.js";
+export type { BufferReferenceRuntime } from "./buffer-reference-native.js";
+export declare const BUFFER_REFERENCE_KIND: "knitting.bufferReference";
+/** Named values for the `unsafe.BufferReferenceReturn` pool option. */
+export declare const BufferReferenceReturn: {
+    /** Safe default: Deno/Bun copy the returned bytes so they outlive the worker. */
+    readonly Copy: "copy";
+    /** Zero-copy: borrow the worker's backing store until the reference is released. */
+    readonly Borrow: "borrow";
+};
+export type BufferReferenceReturn = (typeof BufferReferenceReturn)[keyof typeof BufferReferenceReturn];
+export declare const BUFFER_REFERENCE_NUMERIC_TRANSFER: unique symbol;
+export declare const BUFFER_REFERENCE_RETURN_RELEASE_TOKEN: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+export declare const BUFFER_REFERENCE_CODEC_ID: "knitting.bufferReference";
+declare const BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY = "__knittingBufferReferenceRelease";
+export type BufferReferenceNumericMetadata = readonly [
+    pointerLow: number,
+    pointerHigh: number,
+    tokenLow: number,
+    tokenHigh: number,
+    byteOffset: number,
+    byteLength: number,
+    runtime: number,
+    originPid: number
+];
+export type BufferReferenceMetadata = {
+    readonly kind: typeof BUFFER_REFERENCE_KIND;
+    readonly origin: string;
+    readonly runtime: BufferReferenceRuntime;
+    readonly pointer: string;
+    /** Producer-side release handle (process-local). */
+    readonly token: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+};
+export type BufferReferenceReturnReleaseMessage = {
+    readonly [BUFFER_REFERENCE_RETURN_RELEASE_MESSAGE_KEY]: string;
+};
+type BufferReferenceReturnReleaser = (token: bigint) => void;
+type BufferSource = ArrayBufferView | ArrayBuffer;
+declare const PAYLOAD_TRANSPORT_FINALIZER: unique symbol;
+export declare const withBufferReferenceReturnReleaser: <T>(releaser: BufferReferenceReturnReleaser | undefined, run: () => T) => T;
+export declare const createBufferReferenceReturnReleaseMessage: (token: bigint) => BufferReferenceReturnReleaseMessage;
+export declare const readBufferReferenceReturnReleaseMessage: (value: unknown) => bigint | undefined;
+export declare const isBufferReferenceMetadata: (value: unknown) => value is BufferReferenceMetadata;
+/**
+ * Zero-copy handle for moving ArrayBuffer bytes to **thread** workers.
+ *
+ * Construction detaches the source. Consumers materialize the moved region in
+ * their isolate: owning on Node, alias/copy on Deno/Bun.
+ */
+export declare class BufferReference {
+    #private;
+    readonly [EXTERNAL_PAYLOAD_BRAND]: "knitting.bufferReference";
+    readonly runtime: BufferReferenceRuntime;
+    readonly origin: string;
+    readonly pointer: bigint;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    constructor(source: BufferSource);
+    constructor(source: BufferSource | undefined, meta: BufferReferenceMetadata);
+    static fromMetadata(meta: BufferReferenceMetadata): BufferReference;
+    toMetadata(): BufferReferenceMetadata;
+    [BUFFER_REFERENCE_NUMERIC_TRANSFER](): BufferReferenceNumericMetadata | undefined;
+    get isLocal(): boolean;
+    /** Prepare a returned reference before the worker-side producer hold drains. */
+    claimOwnership(releaser?: BufferReferenceReturnReleaser): this;
+    toArrayBuffer(): ArrayBuffer;
+    toUint8Array(): Uint8Array;
+    /** The source is moved on construction, so it is never retained here. */
+    get source(): undefined;
+    release(): void;
+    [Symbol.dispose](): void;
+    [PAYLOAD_TRANSPORT_FINALIZER](): (() => void) | undefined;
+}