@k13engineering/linux-fuse 0.0.1 → 0.0.2

package/dist/lib/index.js

@@ -0,0 +1,313 @@
+import { createFuseLowLevel } from "./fuse-lowlevel.js";
+import { createFuseServer, /*type TRequestHandler */} from "./server.js";
+import {
+  FSCONFIG_CMD_CREATE,
+  FSCONFIG_SET_FLAG,
+  FSCONFIG_SET_STRING,
+  FSMOUNT_CLOEXEC,
+  FSOPEN_CLOEXEC,
+} from "./constants.js";
+import nodeFs from "node:fs";
+import { fsconfig, fsmount, fsopen } from "./syscalls.js";
+import { openFuseFd, defaultFusePath } from "./linux.js";
+import { createConvenienceRequestHandler } from "./convenience.js";
+import { mountAttributesToBitmask, moveMount, unmount, /*type TMountAttributes, *//*type TRequiredFuseMountOptions */} from "./mount.js";
+import { createPoller } from "@k13engineering/uv-poll";
+/*import type { TFuseResponse } from "./protocol.ts";*/
+
+const UV_EBADF = -9;
+
+const MAX_ALLOWED_WRITE = 32n * 1024n * 1024n;
+
+const createFuseFileSystem = ({
+  fuseFd,
+  requestHandler,
+  sniff,
+}/*: {
+  fuseFd: number;
+  requestHandler: TRequestHandler;
+
+  sniff?: {
+    rawMessageFromKernel: (args: { data: Uint8Array }) => void;
+    rawMessageToKernel: (args: { data: Uint8Array }) => void;
+  }
+}*/) => {
+
+  let lowLevel = createFuseLowLevel({
+    fuseFd,
+    maxMessageSize: 1 * 1024 * 1024 + 4096,
+  });
+
+  const server = createFuseServer({
+    requestHandler: {
+      // eslint-disable-next-line complexity
+      handleRequest: async ({ request }) => {
+        const response = await requestHandler.handleRequest({ request });
+
+        if (response !== undefined && response.forOpcode === "INIT" && response.errorCode === undefined) {
+
+          if (response.result.maxWrite >= MAX_ALLOWED_WRITE) {
+            throw Error(`maxWrite of ${response.result.maxWrite} is too large, refusing to operate`);
+          }
+
+          lowLevel = createFuseLowLevel({
+            fuseFd,
+            maxMessageSize: Number(response.result.maxWrite) + 4096,
+          });
+        }
+
+        return response;
+      }
+    },
+    sendMessageToKernel: ({ rawMessageToKernel }) => {
+      sniff?.rawMessageToKernel({ data: rawMessageToKernel });
+      lowLevel.writeOutgoingMessage({
+        rawMessage: rawMessageToKernel
+      });
+    }
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  let ended = false;
+  let closed = false;
+
+  const poller = createPoller({
+    fd: fuseFd
+  });
+
+  const handlePollError = ({ errorCode }/*: { errorCode: number }*/) => {
+    if (errorCode === UV_EBADF) {
+      // EBADF is raised when the kernel unmounts the filesystem
+      ended = true;
+      return;
+    }
+
+    throw Error(`poll error with code ${errorCode}`);
+  };
+
+  // eslint-disable-next-line complexity
+  const next = () => {
+
+    if (closed) {
+      throw Error("BUG: should not be called after close");
+    }
+
+    const { error: readError, incomingMessage, end } = lowLevel.tryReadIncomingMessage();
+    if (readError !== undefined) {
+      throw readError;
+    }
+
+    if (end) {
+      ended = true;
+      return;
+    }
+
+    if (incomingMessage !== undefined) {
+      sniff?.rawMessageFromKernel({ data: incomingMessage });
+      server.processRequest({
+        rawIncomingRequest: incomingMessage
+      });
+    }
+
+    poller.armOnce({
+      error: ({ errorCode }) => {
+        handlePollError({ errorCode });
+      },
+
+      readable: () => {
+        next();
+      }
+    });
+  };
+
+  poller.armOnce({
+    error: ({ errorCode }) => {
+      handlePollError({ errorCode });
+    },
+
+    readable: () => {
+      next();
+    }
+  });
+
+  /*type TFsMountResult = {
+    error: Error;
+    mountFd: undefined;
+  } | {
+    error: undefined;
+    mountFd: number;
+  };*/
+
+  // eslint-disable-next-line max-statements
+  const mountDetached = ({
+    otherOptions,
+    requiredOptions,
+    mountAttributes,
+  }/*: {
+    otherOptions: {
+      default_permissions?: boolean;
+      allow_other?: boolean;
+      allow_root?: boolean;
+    } | Record<string, string | boolean>;
+    requiredOptions: TRequiredFuseMountOptions;
+    mountAttributes: TMountAttributes;
+  }*/)/*: TFsMountResult*/ => {
+
+    const { errno: fsopenErrno, fsfd } = fsopen({
+      fileSystemName: "fuse",
+      flags: FSOPEN_CLOEXEC
+    });
+
+    if (fsopenErrno !== undefined) {
+      return {
+        error: Error(`fsopen syscall failed with errno ${fsopenErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    const configureString = ({ key, value }/*: { key: string; value: string }*/) => {
+      const { errno } = fsconfig({
+        fd: fsfd,
+        command: FSCONFIG_SET_STRING,
+        key,
+        value,
+        auxiliaryValue: 0,
+      });
+
+      if (errno !== undefined) {
+        throw Error(`fsconfig syscall failed with errno ${errno} when setting ${key}=${value}`);
+      }
+    };
+
+    const configureFlag = ({ key, value }/*: { key: string; value: boolean }*/) => {
+      if (!value) {
+        return;
+      }
+
+      const { errno } = fsconfig({
+        fd: fsfd,
+        command: FSCONFIG_SET_FLAG,
+        key,
+        value: undefined,
+        auxiliaryValue: 0,
+      });
+
+      if (errno !== undefined) {
+        throw Error(`fsconfig syscall failed with errno ${errno} when setting flag ${key}`);
+      }
+    };
+
+    const forbiddenOptions = ["fd", "rootmode", "user_id", "group_id"];
+
+    Object.keys(otherOptions).forEach((key) => {
+      const value = otherOptions[key /*as keyof typeof otherOptions*/];
+
+      if (forbiddenOptions.includes(key)) {
+        throw Error(`option ${key} is not allowed as it is required for correct mounting`);
+      }
+
+      if (value === undefined) {
+        return;
+      }
+
+      if (typeof value === "boolean") {
+        configureFlag({ key, value });
+      } else {
+        configureString({ key, value });
+      }
+    });
+
+    configureString({ key: "fd", value: `${fuseFd}` });
+    configureString({ key: "rootmode", value: `${requiredOptions.rootmode.toString(8)}` });
+    configureString({ key: "user_id", value: `${requiredOptions.user_id}` });
+    configureString({ key: "group_id", value: `${requiredOptions.group_id}` });
+
+    const { errno: createErrno } = fsconfig({
+      fd: fsfd,
+      command: FSCONFIG_CMD_CREATE,
+      key: undefined,
+      value: undefined,
+      auxiliaryValue: 0,
+    });
+    if (createErrno !== undefined) {
+
+      nodeFs.closeSync(fsfd);
+
+      return {
+        error: Error(`fsconfig CMD_CREATE syscall failed with errno ${createErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    const { errno: mountErrno, mountFd } = fsmount({
+      fd: fsfd,
+      flags: FSMOUNT_CLOEXEC,
+      mountAttributesBitmask: mountAttributesToBitmask({
+        mountAttributes
+      })
+    });
+
+    nodeFs.closeSync(fsfd);
+
+    if (mountErrno !== undefined) {
+      return {
+        error: Error(`fsmount syscall failed with errno ${mountErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    return {
+      error: undefined,
+      mountFd,
+    };
+  };
+
+  const close = () => {
+    if (closed) {
+      throw Error("already closed");
+    }
+
+    closed = true;
+
+    poller.close();
+    nodeFs.closeSync(fuseFd);
+  };
+
+  return {
+    mountDetached,
+    close,
+  };
+};
+
+const createDefaultInitResult = ()/*: Extract<TFuseResponse, { forOpcode: "INIT", errorCode: undefined }>["result"]*/ => {
+  return {
+    major: 7n,
+    minor: 45n,
+    maxReadahead: 4096n,
+    flags: 0n,
+    maxBackground: 0n,
+    congestionThreshold: 0n,
+    maxWrite: 1n * 1024n * 1024n,
+    timeGran: 1n,
+    maxPages: 0n,
+    mapAlignment: 0n,
+    flags2: 0n,
+    maxStackDepth: 0n,
+    requestTimeout: 0n,
+  };
+};
+
+export {
+  createFuseFileSystem,
+  openFuseFd,
+  defaultFusePath,
+  createConvenienceRequestHandler,
+  moveMount,
+  unmount,
+  createDefaultInitResult
+};
+
+/*export type {
+  TRequiredFuseMountOptions,
+  TMountAttributes,
+};*/

package/dist/lib/linux.d.ts

@@ -0,0 +1,12 @@
+type TOpenResult = {
+    error: Error;
+    fuseFd: undefined;
+} | {
+    error: undefined;
+    fuseFd: number;
+};
+declare const defaultFusePath = "/dev/fuse";
+declare const openFuseFd: ({ fusePath }: {
+    fusePath: string;
+}) => TOpenResult;
+export { defaultFusePath, openFuseFd };

package/dist/lib/linux.js

@@ -0,0 +1,32 @@
+import nodeFs from "node:fs";
+
+/*type TOpenResult = {
+  error: Error;
+  fuseFd: undefined;
+} | {
+  error: undefined;
+  fuseFd: number;
+};*/
+
+const defaultFusePath = "/dev/fuse";
+
+const openFuseFd = ({ fusePath }/*: { fusePath: string }*/)/*: TOpenResult*/ => {
+  try {
+    const fuseFd = nodeFs.openSync(fusePath, nodeFs.constants.O_RDWR | nodeFs.constants.O_NONBLOCK);
+
+    return {
+      error: undefined,
+      fuseFd,
+    };
+  } catch (err) {
+    return {
+      error: Error(`failed to open "${defaultFusePath}": ${err}`),
+      fuseFd: undefined,
+    };
+  }
+};
+
+export {
+  defaultFusePath,
+  openFuseFd
+};

package/dist/lib/message.d.ts

@@ -0,0 +1,50 @@
+type TParsedMessageFromKernel = {
+    header: {
+        opcode: bigint;
+        unique: bigint;
+        nodeid: bigint;
+        uid: bigint;
+        gid: bigint;
+        pid: bigint;
+    };
+    payload: Uint8Array;
+};
+type TParsedMessageToKernel = {
+    header: {
+        error: bigint;
+        unique: bigint;
+    };
+    payload: Uint8Array;
+};
+type TParseMessageFromKernelResult = {
+    error: Error;
+    parsedMessageFromKernel: undefined;
+} | {
+    error: undefined;
+    parsedMessageFromKernel: TParsedMessageFromKernel;
+};
+type TParseMessageToKernelResult = {
+    error: Error;
+    parsedMessageToKernel: undefined;
+} | {
+    error: undefined;
+    parsedMessageToKernel: TParsedMessageToKernel;
+};
+declare const createMessageFromKernelParser: () => {
+    parseMessageFromKernel: ({ data }: {
+        data: Uint8Array;
+    }) => TParseMessageFromKernelResult;
+    formatMessageFromKernel: ({ parsedMessageFromKernel }: {
+        parsedMessageFromKernel: TParsedMessageFromKernel;
+    }) => Uint8Array;
+};
+declare const createMessageToKernelParser: () => {
+    formatMessageToKernel: ({ parsedMessageToKernel }: {
+        parsedMessageToKernel: TParsedMessageToKernel;
+    }) => Uint8Array;
+    parseMessageToKernel: ({ data }: {
+        data: Uint8Array;
+    }) => TParseMessageToKernelResult;
+};
+export { createMessageFromKernelParser, createMessageToKernelParser };
+export type { TParsedMessageFromKernel, TParsedMessageToKernel };

package/dist/lib/message.js

@@ -0,0 +1,177 @@
+import { fuseInHeaderParser, fuseOutHeaderParser } from "./abi.js";
+
+
+/*type TParsedMessageFromKernel = {
+  header: {
+    opcode: bigint;
+    unique: bigint;
+    nodeid: bigint;
+    uid: bigint;
+    gid: bigint;
+    pid: bigint;
+  },
+  payload: Uint8Array
+};*/
+
+/*type TParsedMessageToKernel = {
+  header: {
+    error: bigint;
+    unique: bigint;
+  },
+  payload: Uint8Array
+};*/
+
+/*type TParseMessageFromKernelResult = {
+  error: Error;
+  parsedMessageFromKernel: undefined;
+} | {
+  error: undefined;
+  parsedMessageFromKernel: TParsedMessageFromKernel;
+};*/
+
+/*type TParseMessageToKernelResult = {
+  error: Error;
+  parsedMessageToKernel: undefined;
+} | {
+  error: undefined;
+  parsedMessageToKernel: TParsedMessageToKernel;
+};*/
+
+const createMessageFromKernelParser = () => {
+
+  const parseMessageFromKernel = ({ data }/*: { data: Uint8Array }*/)/*: TParseMessageFromKernelResult*/ => {
+
+    const inHeader = data.subarray(0, fuseInHeaderParser.size);
+    if (inHeader.length < fuseInHeaderParser.size) {
+      return {
+        error: Error(`invalid message: expected at least ${fuseInHeaderParser.size} bytes for header, got ${inHeader.length} bytes`),
+        parsedMessageFromKernel: undefined,
+      };
+    }
+
+    const parsedInHeader = fuseInHeaderParser.parse({
+      data: inHeader
+    });
+
+    const length = Number(parsedInHeader.len);
+
+
+    if (data.length !== length) {
+      return {
+        error: Error(`invalid message length: expected ${length} bytes, got ${data.length} bytes`),
+        parsedMessageFromKernel: undefined,
+      };
+    }
+
+    const payload = data.slice(fuseInHeaderParser.size, length);
+
+    return {
+      error: undefined,
+      parsedMessageFromKernel: {
+        header: {
+          opcode: parsedInHeader.opcode,
+          unique: parsedInHeader.unique,
+          nodeid: parsedInHeader.nodeid,
+          uid: parsedInHeader.uid,
+          gid: parsedInHeader.gid,
+          pid: parsedInHeader.pid,
+        },
+        payload
+      }
+    };
+  };
+
+  const formatMessageFromKernel = ({ parsedMessageFromKernel }/*: { parsedMessageFromKernel: TParsedMessageFromKernel }*/)/*: Uint8Array*/ => {
+    const messageBuffer = new Uint8Array(fuseInHeaderParser.size + parsedMessageFromKernel.payload.length);
+
+    const formattedHeader = fuseInHeaderParser.format({
+      value: {
+        opcode: parsedMessageFromKernel.header.opcode,
+        unique: parsedMessageFromKernel.header.unique,
+        nodeid: parsedMessageFromKernel.header.nodeid,
+        uid: parsedMessageFromKernel.header.uid,
+        gid: parsedMessageFromKernel.header.gid,
+        pid: parsedMessageFromKernel.header.pid,
+        len: BigInt(messageBuffer.length),
+        // TODO: what is this
+        total_extlen: 0n,
+        padding: 0n,
+      },
+    });
+
+    messageBuffer.set(formattedHeader, 0);
+    messageBuffer.set(parsedMessageFromKernel.payload, formattedHeader.length);
+
+    return messageBuffer;
+  };
+
+  return {
+    parseMessageFromKernel,
+    formatMessageFromKernel
+  };
+};
+
+const createMessageToKernelParser = () => {
+
+  const formatMessageToKernel = ({ parsedMessageToKernel }/*: { parsedMessageToKernel: TParsedMessageToKernel }*/)/*: Uint8Array*/ => {
+    const messageBuffer = new Uint8Array(fuseOutHeaderParser.size + parsedMessageToKernel.payload.length);
+
+    const formattedHeader = fuseOutHeaderParser.format({
+      value: {
+        error: parsedMessageToKernel.header.error,
+        unique: parsedMessageToKernel.header.unique,
+        len: BigInt(messageBuffer.length),
+      },
+    });
+
+    messageBuffer.set(formattedHeader, 0);
+    messageBuffer.set(parsedMessageToKernel.payload, formattedHeader.length);
+
+    return messageBuffer;
+  };
+
+  const parseMessageToKernel = ({ data }/*: { data: Uint8Array }*/)/*: TParseMessageToKernelResult*/ => {
+    const outHeader = data.subarray(0, fuseOutHeaderParser.size);
+
+    const parsedOutHeader = fuseOutHeaderParser.parse({
+      data: outHeader
+    });
+
+    const length = Number(parsedOutHeader.len);
+
+    if (data.length !== length) {
+      return {
+        error: Error(`invalid message length: expected ${length} bytes, got ${data.length} bytes`),
+        parsedMessageToKernel: undefined,
+      };
+    }
+
+    const payload = data.slice(fuseOutHeaderParser.size, length);
+
+    return {
+      error: undefined,
+      parsedMessageToKernel: {
+        header: {
+          error: parsedOutHeader.error,
+          unique: parsedOutHeader.unique,
+        },
+        payload
+      }
+    };
+  };
+
+  return {
+    formatMessageToKernel,
+    parseMessageToKernel
+  };
+};
+
+export {
+  createMessageFromKernelParser,
+  createMessageToKernelParser
+};
+
+/*export type {
+  TParsedMessageFromKernel,
+  TParsedMessageToKernel
+};*/

package/dist/lib/mount.d.ts

@@ -0,0 +1,33 @@
+type TRequiredFuseMountOptions = {
+    rootmode: number;
+    user_id: number;
+    group_id: number;
+};
+type TMountAttributes = {
+    MOUNT_ATTR_RDONLY?: boolean;
+    MOUNT_ATTR_NOSUID?: boolean;
+    MOUNT_ATTR_NODEV?: boolean;
+    MOUNT_ATTR_NOEXEC?: boolean;
+    MOUNT_ATTR_NOSYMFOLLOW?: boolean;
+    MOUNT_ATTR_NODIRATIME?: boolean;
+    customFlags?: bigint;
+};
+declare const mountAttributesToBitmask: ({ mountAttributes }: {
+    mountAttributes: TMountAttributes;
+}) => bigint;
+type TUnmountResult = {
+    error: Error | undefined;
+};
+declare const moveMount: ({ mountFd, newMountPoint, }: {
+    mountFd: number;
+    newMountPoint: string;
+}) => {
+    error: any;
+};
+declare const unmount: ({ mountPoint, force, detach }: {
+    mountPoint: string;
+    force: boolean;
+    detach: boolean;
+}) => TUnmountResult;
+export { mountAttributesToBitmask, moveMount, unmount, };
+export type { TRequiredFuseMountOptions, TMountAttributes, };