the first release of client replica

[XiaochenCui]

This is the first release of client-replica, check the RFC for details: https://github.com/XiaochenCui/puter/blob/fs/client-replica/doc/RFCS/20250821_client_replica_file_system.md

It's safe to merge and deploy it without update the config, no client will use client-replica in this case.

How to review

• The implementation of fs-tree-manager process: src/fs_tree_manager
  • entry: src/fs_tree_manager/server.go
  • protobuf generated code: src/fs_tree_manager/go and src/fs_tree_manager/js
  • merkle tree: src/fs_tree_manager/merkle
  • core data structure and rpc: src/fs_tree_manager/proto/fs_tree_manager.proto
• Client (puter-js): src/puter-js/src/modules/FileSystem/replica
• puter backend (act as a proxy): src/backend/src/routers/filesystem_api/fs_tree_manager

Other code are hooks for integration with the existing codebase.

Config

• init config file: cp src/fs_tree_manager/example-config.yaml src/fs_tree_manager/config.yaml
• update config src/fs_tree_manager/config.yaml, set mysql args to the same as puter backend
• update puter backend config, set the endpoint of fs_tree_manager:

{
  ...
  "services": {
    ...
    "client-replica": {
      "enabled": true,
      "fs_tree_manager_url": "<ip>:<port>"
    }
  }
}

Deploy

# build
docker build -t fs_tree_manager -f src/fs_tree_manager/Dockerfile src/fs_tree_manager

# run
docker compose -f src/fs_tree_manager/docker-compose.yml up

Whitelist

Whitelist is done by permission service:

        const svc_permission = Context.get('services').get('permission');
        const can_access = await svc_permission.check('endpoint:replica/fetch');
        if ( ! can_access ) {
            return socket.emit('replica/fetch/error', {
                success: false,
                error: { message: 'permission denied' },
            });
        }

[XiaochenCui]

@KernelDeimos @jelveh this PR is ready for review/merge