@k13engineering/linux-fuse 0.0.1 → 0.0.3

package/dist/lib/fuse-lowlevel.js

@@ -0,0 +1,133 @@
+import { read, write } from "./syscalls.js";
+
+/*type TIncomingRequest = {
+  header: {
+    opcode: bigint;
+    unique: bigint;
+    nodeid: bigint;
+    uid: bigint;
+    gid: bigint;
+    pid: bigint;
+  },
+  payload: Uint8Array
+};*/
+
+/*type TOutgoingResponse = {
+  header: {
+    error: bigint;
+    unique: bigint;
+  },
+  payload: Uint8Array
+};*/
+
+/*type TTryReadIncomingMessageResult = {
+  error: Error;
+  incomingMessage: undefined;
+  end: undefined;
+} | {
+  error: undefined;
+  incomingMessage: Uint8Array;
+  end: false;
+} | {
+  error: undefined;
+  incomingMessage: undefined;
+  end: false | true;
+};*/
+
+const EPERM = 1;
+const EAGAIN = 11;
+const ENODEV = 19;
+
+const createFuseLowLevel = ({
+  fuseFd,
+  maxMessageSize
+}/*: {
+  fuseFd: number;
+  maxMessageSize: number;
+}*/) => {
+
+  const incomingBuffer = new Uint8Array(maxMessageSize);
+
+  // eslint-disable-next-line complexity
+  const tryReadIncomingMessage = ()/*: TTryReadIncomingMessageResult*/ => {
+
+    const { errno, ret } = read({
+      fd: fuseFd,
+      buffer: incomingBuffer
+    });
+
+    if (errno !== undefined) {
+
+      if (errno === EPERM) {
+
+        // most likely the filesystem hasn't been mounted yet
+
+        return {
+          error: undefined,
+          incomingMessage: undefined,
+          end: false
+        };
+      }
+
+      if (errno === EAGAIN) {
+        // no message to read
+
+        return {
+          error: undefined,
+          incomingMessage: undefined,
+          end: false
+        };
+      }
+
+      if (errno === ENODEV) {
+        // the filesystem has been unmounted
+
+        return {
+          error: undefined,
+          incomingMessage: undefined,
+          end: true
+        };
+      }
+
+      throw Error(`errno ${errno} not implemented yet`);
+    }
+
+    const incomingMessage = incomingBuffer.slice(0, Number(ret));
+
+    return {
+      error: undefined,
+      incomingMessage,
+      end: false
+    };
+  };
+
+  const writeOutgoingMessage = ({ rawMessage }/*: { rawMessage: Uint8Array }*/) => {
+
+    const { errno, ret } = write({
+      fd: fuseFd,
+      buffer: rawMessage
+    });
+
+    if (errno !== undefined) {
+      throw Error(`write syscall failed with errno ${errno}`);
+    }
+
+    if (ret !== BigInt(rawMessage.length)) {
+      throw Error(`short write not supported yet`);
+    }
+  };
+
+  return {
+    tryReadIncomingMessage,
+    writeOutgoingMessage,
+  };
+};
+
+export {
+  createFuseLowLevel
+};
+
+/*export type {
+  TIncomingRequest,
+  TOutgoingResponse
+};*/

package/dist/lib/index.d.ts

@@ -0,0 +1,43 @@
+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 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 createDefaultInitResult: () => Extract<TFuseResponse, {
+    forOpcode: "INIT";
+    errorCode: undefined;
+}>["result"];
+export { createFuseFileSystem, openFuseFd, defaultFusePath, createConvenienceRequestHandler, moveMount, unmount, createDefaultInitResult, direntsToBuffer };
+export type { TRequiredFuseMountOptions, TMountAttributes, TFuseServerInterface, TDirent, };

package/dist/lib/index.js

@@ -0,0 +1,325 @@
+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";*/
+/*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 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,
+  direntsToBuffer
+};
+
+/*export type {
+  TRequiredFuseMountOptions,
+  TMountAttributes,
+  TFuseServerInterface,
+  TDirent,
+};*/

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 };