knitting 0.1.55 → 0.1.60

package/src/connections/bun.js

@@ -0,0 +1,225 @@
+import { assertNamedSharedMemoryIsReopenable, checkPosixResult, DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, detectPosixPlatform, encodeCString, getPosixLibcPath, LINUX_O_CREAT, LINUX_O_EXCL, makeDarwinSharedMemoryName, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, posixError, PROT_READ, PROT_WRITE, setCloseOnExec, SHM_OPEN_STACK_PAD, shmOpenModeIsStackPassed, toPosixSharedMemoryName, } from "./posix.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
+import { createBunWindowsConnectionPrimitives, isWindowsRuntime, } from "./windows.js";
+const FFIType = {
+    i32: 5,
+    i64: 7,
+    u32: 6,
+    usize: 8,
+    ptr: 12,
+};
+const getBunFFI = () => {
+    const ffi = globalThis.Bun?.FFI;
+    if (typeof ffi?.dlopen !== "function" ||
+        typeof ffi?.toArrayBuffer !== "function") {
+        throw new Error("Bun FFI is not available in this runtime");
+    }
+    return ffi;
+};
+export const openBunLibc = () => getBunFFI().dlopen(getPosixLibcPath(), {
+    ...getBunCreateSymbols(),
+    ftruncate: {
+        args: [FFIType.i32, FFIType.i64],
+        returns: FFIType.i32,
+    },
+    dup: {
+        args: [FFIType.i32],
+        returns: FFIType.i32,
+    },
+    fcntl: {
+        args: [FFIType.i32, FFIType.i32, FFIType.i32],
+        returns: FFIType.i32,
+    },
+    mmap: {
+        args: [
+            FFIType.ptr,
+            FFIType.usize,
+            FFIType.i32,
+            FFIType.i32,
+            FFIType.i32,
+            FFIType.i64,
+        ],
+        returns: FFIType.ptr,
+    },
+    munmap: {
+        args: [FFIType.ptr, FFIType.usize],
+        returns: FFIType.i32,
+    },
+    close: {
+        args: [FFIType.i32],
+        returns: FFIType.i32,
+    },
+});
+const getBunCreateSymbols = (platform = detectPosixPlatform()) => platform === "darwin"
+    ? {
+        shm_open: {
+            args: shmOpenModeIsStackPassed(platform)
+                ? [
+                    FFIType.ptr,
+                    FFIType.i32,
+                    ...SHM_OPEN_STACK_PAD.map(() => FFIType.i32),
+                    FFIType.u32,
+                ]
+                : [FFIType.ptr, FFIType.i32, FFIType.u32],
+            returns: FFIType.i32,
+        },
+        shm_unlink: {
+            args: [FFIType.ptr],
+            returns: FFIType.i32,
+        },
+    }
+    : {
+        memfd_create: {
+            args: [FFIType.ptr, FFIType.u32],
+            returns: FFIType.i32,
+        },
+        shm_open: {
+            args: [FFIType.ptr, FFIType.i32, FFIType.u32],
+            returns: FFIType.i32,
+        },
+        shm_unlink: {
+            args: [FFIType.ptr],
+            returns: FFIType.i32,
+        },
+    };
+const callShmOpen = (shmOpen, name, flags, mode, platform) => shmOpenModeIsStackPassed(platform)
+    ? shmOpen(name, flags, ...SHM_OPEN_STACK_PAD, mode)
+    : shmOpen(name, flags, mode);
+const isBunMmapFailed = (pointer) => !pointer || pointer < 0 || pointer >= Number.MAX_SAFE_INTEGER;
+const createBunSharedMemoryFd = (name, platform, libc) => {
+    if (platform === "darwin") {
+        const shmOpen = libc.symbols.shm_open;
+        const shmUnlink = libc.symbols.shm_unlink;
+        if (shmOpen === undefined || shmUnlink === undefined) {
+            throw new Error("shm_open symbols are not available");
+        }
+        const shmName = encodeCString(makeDarwinSharedMemoryName(name, "bun"));
+        const fd = checkPosixResult(callShmOpen(shmOpen, shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE, platform), "shm_open failed");
+        shmUnlink(shmName);
+        try {
+            return setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const memfdCreate = libc.symbols.memfd_create;
+    if (memfdCreate === undefined) {
+        throw new Error("memfd_create symbol is not available");
+    }
+    const fd = checkPosixResult(memfdCreate(encodeCString(name), 0), "memfd_create failed");
+    try {
+        return setCloseOnExec(libc, fd);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+const createNamedBunSharedMemoryFd = (name, mode, platform, libc) => {
+    const shmOpen = libc.symbols.shm_open;
+    if (shmOpen === undefined) {
+        throw new Error("shm_open symbol is not available");
+    }
+    const createFlags = platform === "darwin" ? DARWIN_O_CREAT : LINUX_O_CREAT;
+    const exclusiveFlags = platform === "darwin" ? DARWIN_O_EXCL : LINUX_O_EXCL;
+    const flags = mode === "create"
+        ? O_RDWR | createFlags | exclusiveFlags
+        : O_RDWR;
+    const shmMode = platform === "darwin" ? DARWIN_SHM_MODE : POSIX_SHM_MODE;
+    const shmName = encodeCString(toPosixSharedMemoryName(name));
+    const fd = checkPosixResult(callShmOpen(shmOpen, shmName, flags, shmMode, platform), "shm_open failed");
+    if (mode === "create") {
+        assertNamedSharedMemoryIsReopenable(platform, fd, () => callShmOpen(shmOpen, shmName, O_RDWR, shmMode, platform), libc.symbols.close);
+    }
+    try {
+        return setCloseOnExec(libc, fd);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const mapBunSharedMemory = (options, libc = openBunLibc()) => {
+    const sourceFd = options.name === undefined ? expectFd(options.fd) : -1;
+    const size = expectPositiveSize(options.size);
+    let fd = sourceFd;
+    if (options.name !== undefined) {
+        fd = createNamedBunSharedMemoryFd(options.name, "open", detectPosixPlatform(), libc);
+    }
+    else if (options.duplicateFd !== false) {
+        fd = checkPosixResult(libc.symbols.dup(sourceFd), "dup(fd) failed");
+        try {
+            setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const pointer = libc.symbols.mmap(null, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
+    if (isBunMmapFailed(pointer)) {
+        const error = posixError("mmap failed");
+        if (options.duplicateFd !== false)
+            libc.symbols.close(fd);
+        throw error;
+    }
+    const arrayBuffer = getBunFFI().toArrayBuffer(pointer, 0, size);
+    return {
+        runtime: "bun",
+        fd,
+        name: options.name,
+        size,
+        byteLength: arrayBuffer.byteLength,
+        buffer: arrayBuffer,
+        kind: "external-array-buffer",
+        arrayBuffer,
+        unsafePointer: pointer,
+        close: () => {
+            libc.symbols.munmap(pointer, size);
+            libc.symbols.close(fd);
+        },
+    };
+};
+export const createBunSharedMemory = (options, libc = openBunLibc()) => {
+    const size = expectPositiveSize(readCreateSize(options));
+    const mode = readCreateMode(options);
+    const name = mode === "anonymous"
+        ? readCreateName(options, "knitting_shared_memory")
+        : readRequiredCreateName(options);
+    const platform = detectPosixPlatform();
+    const fd = mode === "anonymous"
+        ? createBunSharedMemoryFd(name, platform, libc)
+        : createNamedBunSharedMemoryFd(name, mode, platform, libc);
+    try {
+        if (mode !== "open") {
+            checkPosixResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed");
+        }
+        const mapping = mapBunSharedMemory({ fd, size, duplicateFd: false }, libc);
+        if (mode !== "anonymous") {
+            return { ...mapping, name };
+        }
+        return mapping;
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const unlinkBunSharedMemory = (name, libc = openBunLibc()) => {
+    const shmUnlink = libc.symbols.shm_unlink;
+    if (shmUnlink === undefined) {
+        throw new Error("shm_unlink symbol is not available");
+    }
+    return shmUnlink(encodeCString(toPosixSharedMemoryName(name))) === 0;
+};
+export const createBunPosixConnectionPrimitives = (libc = openBunLibc()) => ({
+    runtime: "bun",
+    createSharedMemory: (options) => createBunSharedMemory(options, libc),
+    mapSharedMemory: (options) => mapBunSharedMemory(options, libc),
+    unlinkSharedMemory: (name) => unlinkBunSharedMemory(name, libc),
+});
+export const createBunConnectionPrimitives = (libc) => isWindowsRuntime()
+    ? createBunWindowsConnectionPrimitives()
+    : createBunPosixConnectionPrimitives(libc);

package/src/connections/deno.d.ts

@@ -0,0 +1,24 @@
+import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+type DenoLibc = {
+    symbols: {
+        memfd_create?: (name: Uint8Array, flags: number) => number;
+        shm_open?: (name: Uint8Array, flags: number, ...rest: number[]) => number;
+        shm_unlink?: (name: Uint8Array) => number;
+        __error?: () => unknown;
+        __errno_location?: () => unknown;
+        ftruncate: (fd: number, length: bigint) => number;
+        dup: (fd: number) => number;
+        fcntl: (fd: number, cmd: number, arg: number) => number;
+        mmap: (address: null, length: number, protection: number, flags: number, fd: number, offset: bigint) => unknown;
+        munmap: (address: unknown, length: number) => number;
+        close: (fd: number) => number;
+    };
+    close: () => void;
+};
+export declare const openDenoLibc: () => DenoLibc;
+export declare const mapDenoSharedMemory: (options: MapSharedMemoryOptions, libc?: DenoLibc) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createDenoSharedMemory: (options: number | CreateSharedMemoryOptions, libc?: DenoLibc) => SharedMemoryMapping<ArrayBuffer>;
+export declare const unlinkDenoSharedMemory: (name: string, libc?: DenoLibc) => boolean;
+export declare const createDenoPosixConnectionPrimitives: (libc?: DenoLibc) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export declare const createDenoConnectionPrimitives: (libc?: DenoLibc) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export {};

package/src/connections/deno.js

@@ -0,0 +1,226 @@
+import { assertNamedSharedMemoryIsReopenable, checkPosixResult, DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, detectPosixPlatform, encodeCString, getErrnoSymbolName, getPosixLibcPath, LINUX_O_CREAT, LINUX_O_EXCL, makeDarwinSharedMemoryName, makeErrnoReader, MAP_SHARED, O_RDWR, POSIX_SHM_MODE, posixError, PROT_READ, PROT_WRITE, setCloseOnExec, SHM_OPEN_STACK_PAD, shmOpenModeIsStackPassed, toPosixSharedMemoryName, } from "./posix.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readCreateSize, readRequiredCreateName, } from "./types.js";
+import { createDenoWindowsConnectionPrimitives, isWindowsRuntime, } from "./windows.js";
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno === undefined) {
+        throw new Error("Deno shared memory primitives can only run in Deno");
+    }
+    return deno;
+};
+const getDenoErrnoSymbols = (platform = detectPosixPlatform()) => ({
+    [getErrnoSymbolName(platform)]: {
+        parameters: [],
+        result: "pointer",
+    },
+});
+export const openDenoLibc = () => getDeno().dlopen(getPosixLibcPath(), {
+    ...getDenoCreateSymbols(),
+    ...getDenoErrnoSymbols(),
+    ftruncate: {
+        parameters: ["i32", "i64"],
+        result: "i32",
+    },
+    dup: {
+        parameters: ["i32"],
+        result: "i32",
+    },
+    fcntl: {
+        parameters: ["i32", "i32", "i32"],
+        result: "i32",
+    },
+    mmap: {
+        parameters: ["pointer", "usize", "i32", "i32", "i32", "i64"],
+        result: "pointer",
+    },
+    munmap: {
+        parameters: ["pointer", "usize"],
+        result: "i32",
+    },
+    close: {
+        parameters: ["i32"],
+        result: "i32",
+    },
+});
+const getDenoCreateSymbols = (platform = detectPosixPlatform()) => platform === "darwin"
+    ? {
+        shm_open: {
+            parameters: shmOpenModeIsStackPassed(platform)
+                ? [
+                    "buffer",
+                    "i32",
+                    ...SHM_OPEN_STACK_PAD.map(() => "i32"),
+                    "u32",
+                ]
+                : ["buffer", "i32", "u32"],
+            result: "i32",
+        },
+        shm_unlink: {
+            parameters: ["buffer"],
+            result: "i32",
+        },
+    }
+    : {
+        memfd_create: {
+            parameters: ["buffer", "u32"],
+            result: "i32",
+        },
+        shm_open: {
+            parameters: ["buffer", "i32", "u32"],
+            result: "i32",
+        },
+        shm_unlink: {
+            parameters: ["buffer"],
+            result: "i32",
+        },
+    };
+const callShmOpen = (shmOpen, name, flags, mode, platform) => shmOpenModeIsStackPassed(platform)
+    ? shmOpen(name, flags, ...SHM_OPEN_STACK_PAD, mode)
+    : shmOpen(name, flags, mode);
+const errnoOf = (libc, platform = detectPosixPlatform()) => makeErrnoReader(platform === "darwin"
+    ? libc.symbols.__error
+    : libc.symbols.__errno_location, (pointer) => new Int32Array(new (getDeno().UnsafePointerView)(pointer).getArrayBuffer(4))[0]);
+const isDenoMmapFailed = (pointer) => {
+    if (pointer === null)
+        return true;
+    const value = getDeno().UnsafePointer?.value(pointer);
+    return value === -1n || value === BigInt.asUintN(64, -1n);
+};
+const createDenoSharedMemoryFd = (name, platform, libc) => {
+    if (platform === "darwin") {
+        const shmOpen = libc.symbols.shm_open;
+        const shmUnlink = libc.symbols.shm_unlink;
+        if (shmOpen === undefined || shmUnlink === undefined) {
+            throw new Error("shm_open symbols are not available");
+        }
+        const shmName = encodeCString(makeDarwinSharedMemoryName(name, "deno"));
+        const fd = checkPosixResult(callShmOpen(shmOpen, shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE, platform), "shm_open failed", errnoOf(libc, platform), platform);
+        shmUnlink(shmName);
+        try {
+            return setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const memfdCreate = libc.symbols.memfd_create;
+    if (memfdCreate === undefined) {
+        throw new Error("memfd_create symbol is not available");
+    }
+    const fd = checkPosixResult(memfdCreate(encodeCString(name), 0), "memfd_create failed", errnoOf(libc, platform), platform);
+    try {
+        return setCloseOnExec(libc, fd);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+const createNamedDenoSharedMemoryFd = (name, mode, platform, libc) => {
+    const shmOpen = libc.symbols.shm_open;
+    if (shmOpen === undefined) {
+        throw new Error("shm_open symbol is not available");
+    }
+    const createFlags = platform === "darwin" ? DARWIN_O_CREAT : LINUX_O_CREAT;
+    const exclusiveFlags = platform === "darwin" ? DARWIN_O_EXCL : LINUX_O_EXCL;
+    const flags = mode === "create"
+        ? O_RDWR | createFlags | exclusiveFlags
+        : O_RDWR;
+    const shmMode = platform === "darwin" ? DARWIN_SHM_MODE : POSIX_SHM_MODE;
+    const shmName = encodeCString(toPosixSharedMemoryName(name));
+    const fd = checkPosixResult(callShmOpen(shmOpen, shmName, flags, shmMode, platform), "shm_open failed", errnoOf(libc, platform), platform);
+    if (mode === "create") {
+        assertNamedSharedMemoryIsReopenable(platform, fd, () => callShmOpen(shmOpen, shmName, O_RDWR, shmMode, platform), libc.symbols.close, errnoOf(libc, platform));
+    }
+    try {
+        return setCloseOnExec(libc, fd);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const mapDenoSharedMemory = (options, libc = openDenoLibc()) => {
+    const sourceFd = options.name === undefined ? expectFd(options.fd) : -1;
+    const size = expectPositiveSize(options.size);
+    let fd = sourceFd;
+    if (options.name !== undefined) {
+        fd = createNamedDenoSharedMemoryFd(options.name, "open", detectPosixPlatform(), libc);
+    }
+    else if (options.duplicateFd !== false) {
+        fd = checkPosixResult(libc.symbols.dup(sourceFd), "dup(fd) failed", errnoOf(libc));
+        try {
+            setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const pointer = libc.symbols.mmap(null, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
+    if (isDenoMmapFailed(pointer)) {
+        const error = posixError("mmap failed", errnoOf(libc));
+        if (options.duplicateFd !== false)
+            libc.symbols.close(fd);
+        throw error;
+    }
+    const arrayBuffer = new (getDeno().UnsafePointerView)(pointer)
+        .getArrayBuffer(size);
+    return {
+        runtime: "deno",
+        fd,
+        name: options.name,
+        size,
+        byteLength: arrayBuffer.byteLength,
+        buffer: arrayBuffer,
+        kind: "external-array-buffer",
+        arrayBuffer,
+        unsafePointer: pointer,
+        close: () => {
+            libc.symbols.munmap(pointer, size);
+            libc.symbols.close(fd);
+        },
+    };
+};
+export const createDenoSharedMemory = (options, libc = openDenoLibc()) => {
+    const size = expectPositiveSize(readCreateSize(options));
+    const mode = readCreateMode(options);
+    const name = mode === "anonymous"
+        ? readCreateName(options, "knitting_shared_memory")
+        : readRequiredCreateName(options);
+    const platform = detectPosixPlatform();
+    const fd = mode === "anonymous"
+        ? createDenoSharedMemoryFd(name, platform, libc)
+        : createNamedDenoSharedMemoryFd(name, mode, platform, libc);
+    try {
+        if (mode !== "open") {
+            checkPosixResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed", errnoOf(libc, platform), platform);
+        }
+        const mapping = mapDenoSharedMemory({ fd, size, duplicateFd: false }, libc);
+        if (mode !== "anonymous") {
+            return { ...mapping, name };
+        }
+        return mapping;
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const unlinkDenoSharedMemory = (name, libc = openDenoLibc()) => {
+    const shmUnlink = libc.symbols.shm_unlink;
+    if (shmUnlink === undefined) {
+        throw new Error("shm_unlink symbol is not available");
+    }
+    return shmUnlink(encodeCString(toPosixSharedMemoryName(name))) === 0;
+};
+export const createDenoPosixConnectionPrimitives = (libc = openDenoLibc()) => ({
+    runtime: "deno",
+    createSharedMemory: (options) => createDenoSharedMemory(options, libc),
+    mapSharedMemory: (options) => mapDenoSharedMemory(options, libc),
+    unlinkSharedMemory: (name) => unlinkDenoSharedMemory(name, libc),
+});
+export const createDenoConnectionPrimitives = (libc) => isWindowsRuntime()
+    ? createDenoWindowsConnectionPrimitives()
+    : createDenoPosixConnectionPrimitives(libc);

package/src/connections/external-array-buffer.d.ts

@@ -0,0 +1,2 @@
+export declare const detachExternalArrayBuffer: (buffer: ArrayBuffer) => boolean;
+export declare const requireDetachedExternalArrayBuffer: (buffer: ArrayBuffer) => void;

package/src/connections/external-array-buffer.js

@@ -0,0 +1,33 @@
+export const detachExternalArrayBuffer = (buffer) => {
+    if (buffer.byteLength === 0)
+        return true;
+    const detachable = buffer;
+    try {
+        if (typeof detachable.transferToFixedLength === "function") {
+            detachable.transferToFixedLength(0);
+            return buffer.byteLength === 0;
+        }
+    }
+    catch {
+    }
+    try {
+        if (typeof detachable.transfer === "function") {
+            detachable.transfer(0);
+            return buffer.byteLength === 0;
+        }
+    }
+    catch {
+    }
+    try {
+        structuredClone(buffer, { transfer: [buffer] });
+        return buffer.byteLength === 0;
+    }
+    catch {
+        return false;
+    }
+};
+export const requireDetachedExternalArrayBuffer = (buffer) => {
+    if (detachExternalArrayBuffer(buffer))
+        return;
+    throw new Error("knitting: could not detach external ArrayBuffer; refusing to unmap memory still reachable from JavaScript");
+};

package/src/connections/file-descriptor.d.ts

@@ -0,0 +1,39 @@
+import { type ConnectionRuntime, type SharedMemoryBuffer, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+export type FileDescriptorMetadata = {
+    version: 1;
+    fd: number;
+    name?: string;
+    size: number;
+    byteLength: number;
+    runtime?: ConnectionRuntime;
+    kind?: SharedMemoryMapping["kind"];
+    baseAddressMod64?: number;
+};
+type FileDescriptorMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+export declare class FileDescriptor {
+    #private;
+    readonly fd: number;
+    readonly name?: string;
+    readonly size: number;
+    readonly byteLength: number;
+    readonly runtime?: ConnectionRuntime;
+    readonly kind?: SharedMemoryMapping["kind"];
+    readonly baseAddressMod64?: number;
+    constructor(metadata: FileDescriptorMetadata, mapping?: SharedMemoryMapping);
+    static fromMapping(mapping: SharedMemoryMapping): FileDescriptor;
+    static fromMetadata(metadata: unknown): FileDescriptor;
+    static parse(serialized: string): FileDescriptor;
+    toMetadata(): FileDescriptorMetadata;
+    toJSON(): FileDescriptorMetadata;
+    stringify(): string;
+    stringifyMetadata(): string;
+    toString(): string;
+    attach(mapping: SharedMemoryMapping): this;
+    get mapping(): SharedMemoryMapping | undefined;
+    map(mapper: FileDescriptorMapper): SharedMemoryMapping;
+    getBuffer(mapper?: FileDescriptorMapper): SharedMemoryBuffer;
+    getSharedArrayBuffer(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+    getSAB(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+}
+export declare const parseFileDescriptorMetadata: (input: unknown) => FileDescriptorMetadata;
+export {};