fs/memory-provider: init the memory provider (stat, mkdir api)

Author: XiaochenCui

src/backend/src/api/APIError.js

@@ -518,8 +518,9 @@ module.exports = class APIError {
      * is set to null. The first argument is used as the status code.
      *
      * @static
-     * @param {number} status
-     * @param {string|Error} message_or_source one of the following:
+     * @param {number|string} status
+     * @param {object} source
+     * @param {string|Error|object} fields one of the following:
      * - a string to use as the error message
      * - an Error object to use as the source of the error
      * - an object with a message property to use as the error message

src/backend/src/filesystem/FilesystemService.js

@@ -346,7 +346,7 @@ class FilesystemService extends BaseService {
         }
 
         const svc_mountpoint = this.services.get('mountpoint');
-        const provider = await svc_mountpoint.get_provider(selector);
+        const { provider } = await svc_mountpoint.get_provider(selector);
 
         let fsNode = new FSNodeContext({
             provider,

src/backend/src/filesystem/hl_operations/hl_mkdir.js

@@ -279,6 +279,8 @@ class HLMkdir extends HLFilesystemOperation {
             values.path = _path.basename(values.path);
         }
 
+        let { mountpoint } = await this.context.get('services').get('mountpoint').get_provider(values.parent.selector);
+
         let parent_node = values.parent || await fs.node(new RootNodeSelector());
         console.log('USING PARENT', parent_node.selector.describe());
 
@@ -287,7 +289,7 @@ class HLMkdir extends HLFilesystemOperation {
         // "top_parent" is the immediate parent of the target directory
         // (e.g: /home/foo/bar -> /home/foo)
         const top_parent = values.create_missing_parents
-            ? await this._create_top_parent({ top_parent: parent_node })
+            ? await this._create_dir({ dir: parent_node, mountpoint: mountpoint })
             : await this._get_existing_top_parent({ top_parent: parent_node })
             ;
 
@@ -468,28 +470,44 @@ class HLMkdir extends HLFilesystemOperation {
         return node;
     }
 
-    async _create_top_parent ({ top_parent }) {
-        if ( await top_parent.exists() ) {
-            if ( ! top_parent.entry.is_dir ) {
+    /**
+     * Creates a directory and all its ancestors.
+     *
+     * @param {FSNode} dir - The directory to create.
+     * @returns {Promise<FSNode>} The created directory.
+     */
+    async _create_dir ({ dir, mountpoint }) {
+        console.log('CREATING DIR', dir.selector.describe());
+
+        if ( await dir.exists() ) {
+            if ( ! dir.entry.is_dir ) {
                 throw APIError.create('dest_is_not_a_directory');
             }
-            return top_parent;
+            return dir;
         }
 
         const maybe_path_selector =
-            top_parent.get_selector_of_type(NodePathSelector);
+            dir.get_selector_of_type(NodePathSelector);
 
         if ( ! maybe_path_selector ) {
             throw APIError.create('dest_does_not_exist');
         }
 
-        const path = maybe_path_selector.value;
+        let path = maybe_path_selector.value;
 
         const fs = this.context.get('services').get('filesystem');
 
+        let parent = await fs.node(new RootNodeSelector());
+        if ( mountpoint && mountpoint !== '/' ) {
+            parent = await fs.node(new NodePathSelector(mountpoint));
+
+            // remove the mountpoint from the path
+            path = path.replace(mountpoint, '');
+        }
+
         const tree_op = new MkTree();
         await tree_op.run({
-            parent: await fs.node(new RootNodeSelector()),
+            parent: parent,
             tree: [path],
         });
 

src/backend/src/filesystem/node/selectors.js

@@ -89,7 +89,6 @@ class NodeChildSelector {
 
     setPropertiesKnownBySelector (node) {
         node.name = this.name;
-        // no properties known
     }
 
     describe () {

src/backend/src/helpers.js

@@ -97,6 +97,11 @@ async function is_user_signup_disabled() {
 }
 
 const chkperm = spanify('chkperm', async (target_fsentry, requester_user_id, action) => {
+    // TODO (xiaochen): remove this branch after the related ACL permission logic is implemented for "MemoryFSProvider".
+    if (target_fsentry.is_public) {
+        return true;
+    }
+
     // basic cases where false is the default response
     if(!target_fsentry)
         return false;

src/backend/src/modules/puterfs/MountpointService.js

@@ -19,7 +19,7 @@
  */
 // const Mountpoint = o => ({ ...o });
 
-const { RootNodeSelector, NodeUIDSelector } = require("../../filesystem/node/selectors");
+const { RootNodeSelector, NodeUIDSelector, NodePathSelector, NodeChildSelector } = require("../../filesystem/node/selectors");
 const BaseService = require("../../services/BaseService");
 
 /**
@@ -66,6 +66,9 @@ class MountpointService extends BaseService {
             '/': {
                 mounter: 'puterfs',
             },
+            '/tmp': {
+                mounter: 'memoryfs',
+            },
         };
 
         for ( const path of Object.keys(mountpoints) ) {
@@ -86,13 +89,25 @@ class MountpointService extends BaseService {
         });
     }
 
+    /**
+     * Gets the provider for a given selector.
+     *
+     * @param {NodePathSelector|NodeUIDSelector|RootNodeSelector|NodeChildSelector} selector - The selector to get the provider for.
+     * @returns {Promise<{provider: Provider, mountpoint: string}>} The provider for the given selector and the mountpoint.
+     */
     async get_provider (selector) {
         if ( selector instanceof RootNodeSelector ) {
-            return this.mountpoints_['/'].provider;
+            return {
+                provider: this.mountpoints_['/'].provider,
+                mountpoint: '/',
+            };
         }
 
         if ( selector instanceof NodeUIDSelector ) {
-            return this.mountpoints_['/'].provider;
+            return {
+                provider: this.mountpoints_['/'].provider,
+                mountpoint: '/',
+            };
         }
 
         const probe = {};
@@ -109,12 +124,18 @@ class MountpointService extends BaseService {
             }
 
             if ( longest_mount_path ) {
-                return this.mountpoints_[longest_mount_path].provider;
+                return {
+                    provider: this.mountpoints_[longest_mount_path].provider,
+                    mountpoint: longest_mount_path,
+                };
             }
         }
 
         // Use root mountpoint as fallback
-        return this.mountpoints_['/'].provider;
+        return {
+            provider: this.mountpoints_['/'].provider,
+            mountpoint: '/',
+        };
     }
 
     // Temporary solution - we'll develop this incrementally

src/backend/src/modules/puterfs/PuterFSModule.js

@@ -40,6 +40,9 @@ class PuterFSModule extends AdvancedBase {
 
         const DatabaseFSEntryFetcher = require("./DatabaseFSEntryFetcher");
         services.registerService('fsEntryFetcher', DatabaseFSEntryFetcher);
+
+        const { MemoryFSService } = require('./customfs/MemoryFSService');
+        services.registerService('memoryfs', MemoryFSService);
     }
 }
 

src/backend/src/modules/puterfs/customfs/MemoryFSProvider.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ * 
+ * This file is part of Puter.
+ * 
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const FSNodeContext = require("../../../filesystem/FSNodeContext");
+const _path = require('path');
+const { Context } = require("../../../util/context");
+
+class MemoryFSProvider {
+    constructor(mountpoint) {
+        this.mountpoint = mountpoint;
+
+        // key: relative path from the mountpoint, always starts with `/`
+        // value: file content
+        this.files = new Map();
+
+        // key: relative path from the mountpoint, always starts with `/`
+        // value: directory content
+        this.directories = new Set();
+
+        // The root directory (of the mountpoint) always exists.
+        this.directories.add('/');
+    }
+
+    /**
+     * Normalize the path to be relative to the mountpoint. Returns `/` if the path is empty/undefined.
+     * 
+     * @param {string} path - The path to normalize.
+     * @returns {string} - The normalized path, always starts with `/`.
+     */
+    _normalize_path (path) {
+        if ( ! path ) {
+            return '/';
+        }
+
+        if ( path.startsWith(this.mountpoint) ) {
+            path = path.slice(this.mountpoint.length);
+        }
+
+        if ( ! path.startsWith('/') ) {
+            path = '/' + path;
+        }
+
+        return path;
+    }
+
+    /**
+     * Performs a stat operation on the given FSNode.
+     *
+     * @param {Object} param
+     * @param {FSNodeContext} param.node - The node to stat.
+     * @returns {Promise<Object|null>} - The result of the stat operation, or `null` if the node doesn't exist.
+     *
+     * If the result is not null, the returned object includes following fields:
+     * - `is_dir` {boolean} — `true` if the node is a directory.
+     * - `public` {boolean} — `true` if the node is public (read/write access for everyone).
+     * - `user_id` {number} — The ID of the user who owns the node.
+     * 
+     * (ref: https://github.com/HeyPuter/puter/blob/8e58fabb7156d02c0e396ad26788e25ab0138db8/src/backend/src/services/database/sqlite_setup/0001_create-tables.sql#L70-L99)
+     */
+    async stat ({
+        node,
+    }) {
+        const inner_path = this._normalize_path(node?.path);
+
+        // for now, assume the path is a dir
+        if ( this.directories.has(inner_path) ) {
+            const full_path = _path.join(this.mountpoint, inner_path);
+
+            return {
+                is_public: true,
+
+                path: full_path,
+
+                name: _path.basename(full_path),
+
+                // TODO (xiaochen): get the user id from database, the `user_id` must be set no
+                // matter what.
+                user_id: 1,
+
+                is_dir: true,
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Create a new directory.
+     * 
+     * @param {Object} param
+     * @param {Context} param.context - The context of the operation.
+     * @param {FSNodeContext} param.parent - The parent node to create the directory in. Must exist and be a directory.
+     * @param {string} param.name - The name of the new directory.
+     * @returns {Promise<FSNodeContext>} - The new directory node.
+     */
+    async mkdir({ context, parent, name }) {
+        const inner_path = this._normalize_path(_path.join(parent.path, name));
+        const full_path = _path.join(this.mountpoint, inner_path);
+
+        this.directories.add(inner_path);
+
+        // create the node
+        const fs = context.get('services').get('filesystem');
+        const node = await fs.node(full_path);
+        return node;
+    }
+}
+
+module.exports = {
+    MemoryFSProvider,
+};

src/backend/src/modules/puterfs/customfs/MemoryFSService.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ * 
+ * This file is part of Puter.
+ * 
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const BaseService = require("../../../services/BaseService");
+const { MemoryFSProvider } = require("./MemoryFSProvider");
+
+class MemoryFSService extends BaseService {
+    async _init () {
+        const svc_mountpoint = this.services.get('mountpoint');
+        svc_mountpoint.register_mounter('memoryfs', this.as('mounter'));
+    }
+
+    static IMPLEMENTS = {
+        mounter: {
+            async mount ({ path, options }) {
+                const provider = new MemoryFSProvider(path);
+                return provider;
+            }
+        }
+    }
+}
+
+module.exports = {
+    MemoryFSService,
+};

src/backend/src/modules/puterfs/customfs/README.md

@@ -0,0 +1,28 @@
+# Custom FS Providers
+
+This directory contains custom FS providers that are not part of the core PuterFS.
+
+## MemoryFSProvider
+
+This is a demo FS provider that illustrates how to implement a custom FS provider.
+
+### TODO
+
+- Make all FS operations works.
+    - [x] `stat`
+    - [x] `mkdir`
+    - [ ] `write`
+    - [ ] `read`
+    - [ ] `rename`
+    - [ ] `copy`
+    - [ ] `move`
+- [ ] Remove hardcoded permission checks, use standard ACL.
+- [ ] Store file path relative to the mountpoint, so remounting can be done easily.
+
+## NullFSProvider
+
+A FS provider that mimics `/dev/null`.
+
+## LinuxFSProvider
+
+Provide the ability to mount a Linux directory as a FS provider.