@k13engineering/linux-fuse 0.0.6 → 0.1.0

package/dist/lib/dirent.js

@@ -26,14 +26,30 @@ const align = ({ value, alignment }/*: { value: number; alignment: number }*/)/*
 // eslint-disable-next-line complexity
 const direntFileTypeToNative = ({ fileType }/*: { fileType: TDirentFileType }*/)/*: number*/ => {
   switch (fileType) {
-  case "DT_FIFO": return 1;
-  case "DT_CHR": return 2;
-  case "DT_DIR": return 4;
-  case "DT_BLK": return 6;
-  case "DT_REG": return 8;
-  case "DT_LNK": return 10;
-  case "DT_SOCK": return 12;
-  default: return 0;
+    case "DT_FIFO": {
+      return 1;
+    }
+    case "DT_CHR": {
+      return 2;
+    }
+    case "DT_DIR": {
+      return 4;
+    }
+    case "DT_BLK": {
+      return 6;
+    }
+    case "DT_REG": {
+      return 8;
+    }
+    case "DT_LNK": {
+      return 10;
+    }
+    case "DT_SOCK": {
+      return 12;
+    }
+    default: {
+      return 0;
+    }
   }
 };
 

package/dist/lib/filesystem.d.ts

@@ -0,0 +1,41 @@
+import { type TRequestHandler } from "./server.js";
+import { type TMountAttributes, type TRequiredFuseMountOptions } from "./mount.js";
+import type { TKernel } from "./kernel.js";
+import type { TSyscalls } from "./syscalls.js";
+type TFuseFileSystemOptions = {
+    fuseFd: number;
+    requestHandler: TRequestHandler;
+    sniff?: {
+        rawMessageFromKernel: (args: {
+            data: Uint8Array;
+        }) => void;
+        rawMessageToKernel: (args: {
+            data: Uint8Array;
+        }) => void;
+    };
+};
+type TFsMountResult = {
+    error: Error;
+    mountFd: undefined;
+} | {
+    error: undefined;
+    mountFd: number;
+};
+type TMountOptions = {
+    otherOptions: {
+        default_permissions?: boolean;
+        allow_other?: boolean;
+        allow_root?: boolean;
+    } | Record<string, string | boolean>;
+    requiredOptions: TRequiredFuseMountOptions;
+    mountAttributes: TMountAttributes;
+};
+declare const createFuseFileSystem: ({ syscalls, createPoller, fuseFd, requestHandler, sniff, }: TFuseFileSystemOptions & {
+    syscalls: TSyscalls;
+    createPoller: TKernel["createPoller"];
+}) => {
+    mountDetached: ({ otherOptions, requiredOptions, mountAttributes, }: TMountOptions) => TFsMountResult;
+    close: () => void;
+};
+export { createFuseFileSystem, };
+export type { TFuseFileSystemOptions, };

package/dist/lib/filesystem.js

@@ -0,0 +1,344 @@
+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,
+  FUSE_MIN_READ_BUFFER,
+} from "./constants.js";
+import {
+  mountAttributesToBitmask,
+  /*type TMountAttributes,
+  *//*type TRequiredFuseMountOptions
+*/} from "./mount.js";
+/*import type { TKernel } from "./kernel.ts";*/
+/*import type { TSyscalls } from "./syscalls.ts";*/
+
+const UV_EBADF = -9;
+
+const MAX_ALLOWED_WRITE = 32n * 1024n * 1024n;
+
+/*type TFuseFileSystemOptions = {
+  fuseFd: number;
+  requestHandler: TRequestHandler;
+
+  sniff?: {
+    rawMessageFromKernel: (args: { data: Uint8Array }) => void;
+    rawMessageToKernel: (args: { data: Uint8Array }) => void;
+  }
+};*/
+
+/*type TFsMountResult = {
+  error: Error;
+  mountFd: undefined;
+} | {
+  error: undefined;
+  mountFd: number;
+};*/
+
+/*type TMountOptions = {
+  otherOptions: {
+    default_permissions?: boolean;
+    allow_other?: boolean;
+    allow_root?: boolean;
+  } | Record<string, string | boolean>;
+  requiredOptions: TRequiredFuseMountOptions;
+  mountAttributes: TMountAttributes;
+};*/
+
+const forbiddenOptions = ["fd", "rootmode", "user_id", "group_id"];
+
+const closeFdOrThrow = ({ syscalls, fd }/*: { syscalls: Pick<TSyscalls, "close">; fd: number }*/) => {
+  const { errno } = syscalls.close({ fd });
+  if (errno !== undefined) {
+    throw Error(`close syscall failed with errno ${errno}`);
+  }
+};
+
+const createFuseFileSystem = ({
+  syscalls,
+  createPoller,
+  fuseFd,
+  requestHandler,
+  sniff,
+}/*: TFuseFileSystemOptions & {
+  syscalls: TSyscalls;
+  createPoller: TKernel["createPoller"];
+}*/) => {
+
+  let closed = false;
+
+  let lowLevel = createFuseLowLevel({
+    syscalls,
+    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({
+            syscalls,
+            fuseFd,
+            // the kernel rejects reads into buffers smaller than FUSE_MIN_READ_BUFFER
+            maxMessageSize: Math.max(FUSE_MIN_READ_BUFFER, Number(response.result.maxWrite) + 4096),
+          });
+        }
+
+        return response;
+      }
+    },
+    sendMessageToKernel: ({ rawMessageToKernel }) => {
+      if (closed) {
+        // a request finished after close, its file descriptor number may already be reused
+        return;
+      }
+
+      sniff?.rawMessageToKernel({ data: rawMessageToKernel });
+      lowLevel.writeOutgoingMessage({
+        rawMessage: rawMessageToKernel
+      });
+    }
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  let ended = 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}`);
+  };
+
+  // reads and processes one message, returns whether the fuse device should be polled further
+  // eslint-disable-next-line complexity
+  const processIncomingMessage = () => {
+
+    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 false;
+    }
+
+    if (incomingMessage !== undefined) {
+      sniff?.rawMessageFromKernel({ data: incomingMessage });
+      server.processRequest({
+        rawIncomingRequest: incomingMessage
+      });
+    }
+
+    return true;
+  };
+
+  const armPoller = () => {
+    poller.armOnce({
+      error: ({ errorCode }) => {
+        handlePollError({ errorCode });
+      },
+
+      readable: () => {
+        if (processIncomingMessage()) {
+          armPoller();
+        }
+      }
+    });
+  };
+
+  let polling = false;
+
+  // the kernel reports a fuse device that is not mounted yet as erroneous to poll, which looks the
+  // same as an unmount, so polling only starts once the device is connected by mountDetached
+  const startPolling = () => {
+    if (polling) {
+      return;
+    }
+
+    polling = true;
+    armPoller();
+  };
+
+  const configureAndMount = ({
+    fsfd,
+    otherOptions,
+    requiredOptions,
+    mountAttributesBitmask,
+  }/*: Omit<TMountOptions, "mountAttributes"> & {
+    fsfd: number;
+    mountAttributesBitmask: bigint;
+  }*/)/*: TFsMountResult*/ => {
+
+    const configureString = ({ key, value }/*: { key: string; value: string }*/) => {
+      const { errno } = syscalls.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 } = syscalls.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}`);
+      }
+    };
+
+    Object.keys(otherOptions).forEach((key) => {
+      const value = otherOptions[key /*as keyof typeof otherOptions*/];
+
+      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 } = syscalls.fsconfig({
+      fd: fsfd,
+      command: FSCONFIG_CMD_CREATE,
+      key: undefined,
+      value: undefined,
+      auxiliaryValue: 0,
+    });
+    if (createErrno !== undefined) {
+      return {
+        error: Error(`fsconfig CMD_CREATE syscall failed with errno ${createErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    const { errno: mountErrno, mountFd } = syscalls.fsmount({
+      fd: fsfd,
+      flags: FSMOUNT_CLOEXEC,
+      mountAttributesBitmask,
+    });
+
+    if (mountErrno !== undefined) {
+      return {
+        error: Error(`fsmount syscall failed with errno ${mountErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    return {
+      error: undefined,
+      mountFd,
+    };
+  };
+
+  const mountDetached = ({
+    otherOptions,
+    requiredOptions,
+    mountAttributes,
+  }/*: TMountOptions*/)/*: TFsMountResult*/ => {
+
+    // validate everything that can be validated before creating the filesystem context
+    Object.keys(otherOptions).forEach((key) => {
+      if (forbiddenOptions.includes(key)) {
+        throw Error(`option ${key} is not allowed as it is required for correct mounting`);
+      }
+    });
+
+    const mountAttributesBitmask = mountAttributesToBitmask({ mountAttributes });
+
+    const { errno: fsopenErrno, fsfd } = syscalls.fsopen({
+      fileSystemName: "fuse",
+      flags: FSOPEN_CLOEXEC
+    });
+
+    if (fsopenErrno !== undefined) {
+      return {
+        error: Error(`fsopen syscall failed with errno ${fsopenErrno}`),
+        mountFd: undefined,
+      };
+    }
+
+    try {
+      const result = configureAndMount({ fsfd, otherOptions, requiredOptions, mountAttributesBitmask });
+      if (result.error === undefined) {
+        startPolling();
+      }
+
+      return result;
+    } finally {
+      // the mount keeps its own reference, so the filesystem context is not needed afterwards
+      closeFdOrThrow({ syscalls, fd: fsfd });
+    }
+  };
+
+  const close = () => {
+    if (closed) {
+      throw Error("already closed");
+    }
+
+    closed = true;
+
+    poller.close();
+    closeFdOrThrow({ syscalls, fd: fuseFd });
+  };
+
+  return {
+    mountDetached,
+    close,
+  };
+};
+
+export {
+  createFuseFileSystem,
+};
+
+/*export type {
+  TFuseFileSystemOptions,
+};*/

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

@@ -1,3 +1,4 @@
+import type { TSyscalls } from "./syscalls.js";
 type TIncomingRequest = {
     header: {
         opcode: bigint;
@@ -29,7 +30,8 @@ type TTryReadIncomingMessageResult = {
     incomingMessage: undefined;
     end: false | true;
 };
-declare const createFuseLowLevel: ({ fuseFd, maxMessageSize }: {
+declare const createFuseLowLevel: ({ syscalls, fuseFd, maxMessageSize }: {
+    syscalls: Pick<TSyscalls, "read" | "write">;
     fuseFd: number;
     maxMessageSize: number;
 }) => {

package/dist/lib/fuse-lowlevel.js

@@ -1,4 +1,4 @@
-import { read, write } from "./syscalls.js";
+/*import type { TSyscalls } from "./syscalls.ts";*/
 
 /*type TIncomingRequest = {
   header: {
@@ -35,13 +35,16 @@ import { read, write } from "./syscalls.js";
 };*/
 
 const EPERM = 1;
+const ENOENT = 2;
 const EAGAIN = 11;
 const ENODEV = 19;
 
 const createFuseLowLevel = ({
+  syscalls,
   fuseFd,
   maxMessageSize
 }/*: {
+  syscalls: Pick<TSyscalls, "read" | "write">;
   fuseFd: number;
   maxMessageSize: number;
 }*/) => {
@@ -51,7 +54,7 @@ const createFuseLowLevel = ({
   // eslint-disable-next-line complexity
   const tryReadIncomingMessage = ()/*: TTryReadIncomingMessageResult*/ => {
 
-    const { errno, ret } = read({
+    const { errno, ret } = syscalls.read({
       fd: fuseFd,
       buffer: incomingBuffer
     });
@@ -89,7 +92,11 @@ const createFuseLowLevel = ({
         };
       }
 
-      throw Error(`errno ${errno} not implemented yet`);
+      return {
+        error: Error(`read syscall failed with errno ${errno}`),
+        incomingMessage: undefined,
+        end: undefined
+      };
     }
 
     const incomingMessage = incomingBuffer.slice(0, Number(ret));
@@ -103,11 +110,17 @@ const createFuseLowLevel = ({
 
   const writeOutgoingMessage = ({ rawMessage }/*: { rawMessage: Uint8Array }*/) => {
 
-    const { errno, ret } = write({
+    const { errno, ret } = syscalls.write({
       fd: fuseFd,
       buffer: rawMessage
     });
 
+    if (errno === ENOENT) {
+      // the kernel no longer waits for this reply, e.g. because the request was
+      // interrupted or the filesystem got unmounted while it was processed
+      return;
+    }
+
     if (errno !== undefined) {
       throw Error(`write syscall failed with errno ${errno}`);
     }

package/dist/lib/index.d.ts

@@ -1,43 +1,14 @@
-import { type TRequestHandler } from "./server.js";
-import { openFuseFd, defaultFusePath } from "./linux.js";
 import { createConvenienceRequestHandler } from "./convenience.js";
-import { moveMount, unmount, type TMountAttributes, type TRequiredFuseMountOptions } from "./mount.js";
+import { defaultFusePath } from "./linux.js";
+import type { TMountAttributes, TRequiredFuseMountOptions } from "./mount.js";
 import type { TFuseResponse } from "./protocol.js";
 import type { TFuseServerInterface } from "./convenience.js";
 import type { TDirent } from "./dirent.js";
 import { direntsToBuffer } from "./dirent.js";
-declare const createFuseFileSystem: ({ fuseFd, requestHandler, sniff, }: {
-    fuseFd: number;
-    requestHandler: TRequestHandler;
-    sniff?: {
-        rawMessageFromKernel: (args: {
-            data: Uint8Array;
-        }) => void;
-        rawMessageToKernel: (args: {
-            data: Uint8Array;
-        }) => void;
-    };
-}) => {
-    mountDetached: ({ otherOptions, requiredOptions, mountAttributes, }: {
-        otherOptions: {
-            default_permissions?: boolean;
-            allow_other?: boolean;
-            allow_root?: boolean;
-        } | Record<string, string | boolean>;
-        requiredOptions: TRequiredFuseMountOptions;
-        mountAttributes: TMountAttributes;
-    }) => {
-        error: Error;
-        mountFd: undefined;
-    } | {
-        error: undefined;
-        mountFd: number;
-    };
-    close: () => void;
-};
+declare const createFuseFileSystem: any, openFuseFd: any, moveMount: any, unmount: any, fchdir: any;
 declare const createDefaultInitResult: () => Extract<TFuseResponse, {
     forOpcode: "INIT";
     errorCode: undefined;
 }>["result"];
-export { createFuseFileSystem, openFuseFd, defaultFusePath, createConvenienceRequestHandler, moveMount, unmount, createDefaultInitResult, direntsToBuffer };
+export { createFuseFileSystem, openFuseFd, defaultFusePath, createConvenienceRequestHandler, moveMount, unmount, createDefaultInitResult, direntsToBuffer, fchdir, };
 export type { TRequiredFuseMountOptions, TMountAttributes, TFuseServerInterface, TDirent, };