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

XiaochenCui · XiaochenCui · commit 1efc8e727e54 · 2025-07-31T15:03:28.000-07:00
diff --git a/src/backend/src/api/APIError.js b/src/backend/src/api/APIError.js
@@ -17,6 +17,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 const { URLSearchParams } = require("node:url");
+const config = require("../config");
 const { quot } = require('@heyputer/putility').libs.string;
 
 /**
@@ -518,14 +519,19 @@ 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
      * @returns
      */
     static create (status, source, fields = {}) {
+        if ( config.env === 'dev' ) {
+            console.trace('APIError.create', status, source, fields);
+        }
+
         // Just the error code
         if ( typeof status === 'string' ) {
             const code = this.codes[status];
diff --git a/src/backend/src/filesystem/hl_operations/hl_mkdir.js b/src/backend/src/filesystem/hl_operations/hl_mkdir.js
@@ -287,7 +287,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(parent_node)
             : await this._get_existing_top_parent({ top_parent: parent_node })
             ;
 
@@ -468,28 +468,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 {FSNodeContext} dir - The directory to create.
+     * @returns {Promise<FSNodeContext>} The created directory.
+     */
+    async _create_dir (dir) {
+        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],
         });
 
diff --git a/src/backend/src/filesystem/node/selectors.js b/src/backend/src/filesystem/node/selectors.js
@@ -89,7 +89,33 @@ class NodeChildSelector {
 
     setPropertiesKnownBySelector (node) {
         node.name = this.name;
-        // no properties known
+
+        // try to get the full path recursively
+        //
+        // TODO (xiaochen): this is a hack to get the absolute path and should be removed once
+        // we have a better solution. We need the absolute path so that `MountpointService`
+        // can determine the mountpoint and provider for the node.
+        const stack = [this.name];
+        let current = this.parent;
+        while ( current ) {
+            if ( current instanceof NodeChildSelector ) {
+                stack.push(current.name);
+                current = current.parent;
+            } else if ( current instanceof NodePathSelector ) {
+                stack.push(current.value);
+                current = null;
+            } else if ( current instanceof RootNodeSelector ) {
+                current = null;
+            } else {
+                // for other selectors, we can't determine the absolute path
+                return;
+            }
+        }
+
+        node.path = '/';
+        stack.reverse().forEach(item => {
+            node.path = _path.join(node.path, item);
+        });
     }
 
     describe () {
diff --git a/src/backend/src/helpers.js b/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;
diff --git a/src/backend/src/modules/puterfs/MountpointService.js b/src/backend/src/modules/puterfs/MountpointService.js
@@ -66,6 +66,9 @@ class MountpointService extends BaseService {
             '/': {
                 mounter: 'puterfs',
             },
+            '/tmp': {
+                mounter: 'memoryfs',
+            },
         };
 
         for ( const path of Object.keys(mountpoints) ) {
diff --git a/src/backend/src/modules/puterfs/PuterFSModule.js b/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);
     }
 }
 
diff --git a/src/backend/src/modules/puterfs/customfs/MemoryFSProvider.js b/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,
+};
diff --git a/src/backend/src/modules/puterfs/customfs/MemoryFSService.js b/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,
+};
diff --git a/src/backend/src/modules/puterfs/customfs/README.md b/src/backend/src/modules/puterfs/customfs/README.md
@@ -0,0 +1,15 @@
+# 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.
+
+## NullFSProvider
+
+A FS provider that mimics `/dev/null`.
+
+## LinuxFSProvider
+
+Provide the ability to mount a Linux directory as a FS provider.
diff --git a/src/backend/src/services/auth/ACLService.js b/src/backend/src/services/auth/ACLService.js
@@ -22,6 +22,7 @@ const FSNodeParam = require("../../api/filesystem/FSNodeParam");
 const { NodePathSelector } = require("../../filesystem/node/selectors");
 const { get_user } = require("../../helpers");
 const configurable_auth = require("../../middleware/configurable_auth");
+const { MemoryFSProvider } = require("../../modules/puterfs/customfs/MemoryFSProvider");
 const { Context } = require("../../util/context");
 const { Endpoint } = require("../../util/expressutil");
 const BaseService = require("../BaseService");
@@ -344,6 +345,14 @@ class ACLService extends BaseService {
     * - Explicit permissions in the ACL hierarchy
     */
     async _check_fsNode (actor, fsNode, mode) {
+        // We currently need this ad-hoc check for "MemoryFSProvider" since the related
+        // ACL permission logic is not yet implemented for "MemoryFSProvider".
+        // 
+        // TODO (xiaochen): remove this branch after the related ACL permission logic is implemented for "MemoryFSProvider".
+        if ( fsNode.provider instanceof MemoryFSProvider && fsNode.entry.is_public ) {
+            return true;
+        }
+
         const context = Context.get();
 
         actor = Actor.adapt(actor);
diff --git a/tools/api-tester/README.md b/tools/api-tester/README.md
diff --git a/tools/api-tester/lib/TestSDK.js b/tools/api-tester/lib/TestSDK.js
diff --git a/tools/api-tester/tests/mkdir.js b/tools/api-tester/tests/mkdir.js

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,9 @@ class PuterFSModule extends AdvancedBase {`
`40`	`40`
`41`	`41`	`const DatabaseFSEntryFetcher = require("./DatabaseFSEntryFetcher");`
`42`	`42`	`services.registerService('fsEntryFetcher', DatabaseFSEntryFetcher);`
	`43`	`+`
	`44`	`+ const { MemoryFSService } = require('./customfs/MemoryFSService');`
	`45`	`+ services.registerService('memoryfs', MemoryFSService);`
`43`	`46`	`}`
`44`	`47`	`}`
`45`	`48`