@k13engineering/linux-fuse 0.0.7 → 0.1.0

package/dist/lib/index.js

@@ -1,292 +1,20 @@
-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 { fchdir, 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 { linuxKernel } from "./kernel.js";
+import { createLinuxFuse } from "./linux-fuse.js";
+import { defaultFusePath } from "./linux.js";
+/*import type { TMountAttributes, TRequiredFuseMountOptions } from "./mount.ts";*/
 /*import type { TFuseResponse } from "./protocol.ts";*/
 /*import type { TFuseServerInterface } from "./convenience.ts";*/
 /*import type { TDirent } from "./dirent.ts";*/
 import { direntsToBuffer } from "./dirent.js";
 
-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 {
+  createFuseFileSystem,
+  openFuseFd,
+  moveMount,
+  unmount,
+  fchdir,
+} = createLinuxFuse({ kernel: linuxKernel });
 
 const createDefaultInitResult = ()/*: Extract<TFuseResponse, { forOpcode: "INIT", errorCode: undefined }>["result"]*/ => {
   return {

package/dist/lib/kernel.d.ts

@@ -0,0 +1,9 @@
+import { createPoller } from "@k13engineering/uv-poll";
+import { syscall } from "syscall-napi";
+type TKernel = {
+    syscall: typeof syscall;
+    createPoller: typeof createPoller;
+};
+declare const linuxKernel: TKernel;
+export { linuxKernel, };
+export type { TKernel, };

package/dist/lib/kernel.js

@@ -0,0 +1,21 @@
+import { createPoller } from "@k13engineering/uv-poll";
+import { syscall } from "syscall-napi";
+
+// everything that needs the real kernel goes through this interface, so it can be mocked in tests
+/*type TKernel = {
+  syscall: typeof syscall;
+  createPoller: typeof createPoller;
+};*/
+
+const linuxKernel/*: TKernel*/ = {
+  syscall,
+  createPoller,
+};
+
+export {
+  linuxKernel,
+};
+
+/*export type {
+  TKernel,
+};*/

package/dist/lib/linux-fuse.d.ts

@@ -0,0 +1,21 @@
+import { type TFuseFileSystemOptions } from "./filesystem.js";
+import type { TKernel } from "./kernel.js";
+declare const createLinuxFuse: ({ kernel }: {
+    kernel: TKernel;
+}) => {
+    createFuseFileSystem: (options: TFuseFileSystemOptions) => any;
+    openFuseFd: ({ fusePath }: {
+        fusePath: string;
+    }) => any;
+    moveMount: ({ mountFd, newMountPoint }: {
+        mountFd: number;
+        newMountPoint: string;
+    }) => any;
+    unmount: ({ mountPoint, force, detach }: {
+        mountPoint: string;
+        force: boolean;
+        detach: boolean;
+    }) => any;
+    fchdir: any;
+};
+export { createLinuxFuse, };

package/dist/lib/linux-fuse.js

@@ -0,0 +1,38 @@
+import { createFuseFileSystem, /*type TFuseFileSystemOptions */} from "./filesystem.js";
+/*import type { TKernel } from "./kernel.ts";*/
+import { openFuseFd } from "./linux.js";
+import { moveMount, unmount } from "./mount.js";
+import { createSyscalls } from "./syscalls.js";
+
+// binds the public API to a kernel, the default instance uses the real one
+const createLinuxFuse = ({ kernel }/*: { kernel: TKernel }*/) => {
+  const syscalls = createSyscalls({ kernel });
+
+  return {
+    createFuseFileSystem: (options/*: TFuseFileSystemOptions*/) => {
+      return createFuseFileSystem({
+        ...options,
+        syscalls,
+        createPoller: kernel.createPoller,
+      });
+    },
+
+    openFuseFd: ({ fusePath }/*: { fusePath: string }*/) => {
+      return openFuseFd({ syscalls, fusePath });
+    },
+
+    moveMount: ({ mountFd, newMountPoint }/*: { mountFd: number; newMountPoint: string }*/) => {
+      return moveMount({ syscalls, mountFd, newMountPoint });
+    },
+
+    unmount: ({ mountPoint, force, detach }/*: { mountPoint: string; force: boolean; detach: boolean }*/) => {
+      return unmount({ syscalls, mountPoint, force, detach });
+    },
+
+    fchdir: syscalls.fchdir,
+  };
+};
+
+export {
+  createLinuxFuse,
+};

package/dist/lib/linux.d.ts

@@ -1,3 +1,4 @@
+import type { TSyscalls } from "./syscalls.js";
 type TOpenResult = {
     error: Error;
     fuseFd: undefined;
@@ -6,7 +7,8 @@ type TOpenResult = {
     fuseFd: number;
 };
 declare const defaultFusePath = "/dev/fuse";
-declare const openFuseFd: ({ fusePath }: {
+declare const openFuseFd: ({ syscalls, fusePath }: {
+    syscalls: Pick<TSyscalls, "openat">;
     fusePath: string;
 }) => TOpenResult;
 export { defaultFusePath, openFuseFd };

package/dist/lib/linux.js

@@ -1,4 +1,6 @@
 import nodeFs from "node:fs";
+import { AT_FCWD, O_CLOEXEC } from "./constants.js";
+/*import type { TSyscalls } from "./syscalls.ts";*/
 
 /*type TOpenResult = {
   error: Error;
@@ -10,20 +12,25 @@ import nodeFs from "node:fs";
 
 const defaultFusePath = "/dev/fuse";
 
-const openFuseFd = ({ fusePath }/*: { fusePath: string }*/)/*: TOpenResult*/ => {
-  try {
-    const fuseFd = nodeFs.openSync(fusePath, nodeFs.constants.O_RDWR | nodeFs.constants.O_NONBLOCK);
+const openFuseFd = ({ syscalls, fusePath }/*: { syscalls: Pick<TSyscalls, "openat">; fusePath: string }*/)/*: TOpenResult*/ => {
+  const { errno, fd } = syscalls.openat({
+    dirFd: Number(AT_FCWD),
+    path: fusePath,
+    flags: nodeFs.constants.O_RDWR | nodeFs.constants.O_NONBLOCK | O_CLOEXEC,
+    mode: 0,
+  });
 
+  if (errno !== undefined) {
     return {
-      error: undefined,
-      fuseFd,
-    };
-  } catch (err) {
-    return {
-      error: Error(`failed to open "${defaultFusePath}": ${err}`),
+      error: Error(`failed to open "${fusePath}": openat syscall failed with errno ${errno}`),
       fuseFd: undefined,
     };
   }
+
+  return {
+    error: undefined,
+    fuseFd: fd,
+  };
 };
 
 export {

package/dist/lib/message.js

@@ -132,6 +132,12 @@ const createMessageToKernelParser = () => {
 
   const parseMessageToKernel = ({ data }/*: { data: Uint8Array }*/)/*: TParseMessageToKernelResult*/ => {
     const outHeader = data.subarray(0, fuseOutHeaderParser.size);
+    if (outHeader.length < fuseOutHeaderParser.size) {
+      return {
+        error: Error(`invalid message: expected at least ${fuseOutHeaderParser.size} bytes for header, got ${outHeader.length} bytes`),
+        parsedMessageToKernel: undefined,
+      };
+    }
 
     const parsedOutHeader = fuseOutHeaderParser.parse({
       data: outHeader

package/dist/lib/mount.d.ts

@@ -1,3 +1,4 @@
+import type { TSyscalls } from "./syscalls.js";
 type TRequiredFuseMountOptions = {
     rootmode: number;
     user_id: number;
@@ -18,13 +19,15 @@ declare const mountAttributesToBitmask: ({ mountAttributes }: {
 type TUnmountResult = {
     error: Error | undefined;
 };
-declare const moveMount: ({ mountFd, newMountPoint, }: {
+declare const moveMount: ({ syscalls, mountFd, newMountPoint, }: {
+    syscalls: Pick<TSyscalls, "move_mount">;
     mountFd: number;
     newMountPoint: string;
 }) => {
     error: any;
 };
-declare const unmount: ({ mountPoint, force, detach }: {
+declare const unmount: ({ syscalls, mountPoint, force, detach, }: {
+    syscalls: Pick<TSyscalls, "umount">;
     mountPoint: string;
     force: boolean;
     detach: boolean;

package/dist/lib/mount.js

@@ -8,7 +8,7 @@ import {
   MOUNT_ATTR_RDONLY,
   MOVE_MOUNT_F_EMPTY_PATH
 } from "./constants.js";
-import { move_mount, umount } from "./syscalls.js";
+/*import type { TSyscalls } from "./syscalls.ts";*/
 
 /*type TRequiredFuseMountOptions = {
   rootmode: number;
@@ -84,13 +84,15 @@ const MNT_DETACH = 2n;
 
 // for now, only export this simple variant for use with fuse
 const moveMount = ({
+  syscalls,
   mountFd,
   newMountPoint,
 }/*: {
+  syscalls: Pick<TSyscalls, "move_mount">;
   mountFd: number;
   newMountPoint: string;
 }*/) => {
-  const { errno: moveMountErrno } = move_mount({
+  const { errno: moveMountErrno } = syscalls.move_mount({
     fromFd: mountFd,
     fromPath: "",
     toFd: Number(AT_FCWD),
@@ -109,7 +111,17 @@ const moveMount = ({
   };
 };
 
-const unmount = ({ mountPoint, force, detach }/*: { mountPoint: string, force: boolean, detach: boolean }*/)/*: TUnmountResult*/ => {
+const unmount = ({
+  syscalls,
+  mountPoint,
+  force,
+  detach,
+}/*: {
+  syscalls: Pick<TSyscalls, "umount">;
+  mountPoint: string;
+  force: boolean;
+  detach: boolean;
+}*/)/*: TUnmountResult*/ => {
 
   let flags = 0n;
 
@@ -121,7 +133,7 @@ const unmount = ({ mountPoint, force, detach }/*: { mountPoint: string, force: b
     flags |= MNT_DETACH;
   }
 
-  const { errno } = umount({
+  const { errno } = syscalls.umount({
     target: mountPoint,
     flags,
   });

package/dist/lib/protocol.d.ts

@@ -892,6 +892,12 @@ type TGenericInterpretResult<T> = {
     interpreted: T;
 };
 declare const createMessageFromKernelInterpreter: () => {
+    applyInitResult: ({ result }: {
+        result: Extract<TFuseResponse, {
+            forOpcode: "INIT";
+            errorCode: undefined;
+        }>["result"];
+    }) => void;
     interpretMessageFromKernel: ({ parsedMessageFromKernel }: {
         parsedMessageFromKernel: TParsedMessageFromKernel;
     }) => TGenericInterpretResult<TFuseRequest>;