client-replica: hide the debug widget

Author: XiaochenCui

doc/RFCS/20250821_client_replica_file_system.md

@@ -316,6 +316,10 @@ TODO
 - `puter.fs.replica.debug` - toggle debug widget and logs, may be merged with `puter.debugMode` in the future
 - `puter.fs.replica.fs_tree` - the in-memory FS Tree, should only be used by internal code
 
+### Websocket Lifecycle & Events
+
+TODO
+
 ### Code Location
 
 - `src/puter-js/src/modules/FileSystem/replica` - puter-js client

src/backend/src/routers/filesystem_api/fs_tree_manager/common.js

@@ -22,27 +22,60 @@ const {
 const { Struct } = require('google-protobuf/google/protobuf/struct_pb.js');
 
 const config = require('../../../config');
-const fsTreeManagerUrl = config.services?.['client-replica']?.fs_tree_manager_url;
-
-// Create gRPC client
-const client = new FSTreeManagerClient(fsTreeManagerUrl, grpc.credentials.createInsecure(), {
-    // Reconnect backoff (defaults can be slow: ~20s→120s)
-    //
-    // ref:
-    // - https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
-    // - https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md
-    'grpc.initial_reconnect_backoff_ms': 500,
-    'grpc.min_reconnect_backoff_ms': 500,
-    'grpc.max_reconnect_backoff_ms': 5000,
-
-    // // Keepalive so dead TCPs are detected quickly
-    // 'grpc.keepalive_time_ms': 15000,           // send PING every 15s
-    // 'grpc.keepalive_timeout_ms': 5000,         // wait 5s for PING ack
-    // 'grpc.keepalive_permit_without_calls': 1,  // allow pings when idle
-
-    // // (Optional) be polite about PING cadence
-    // 'grpc.http2.min_time_between_pings_ms': 10000,
-});
+
+// Singleton client instance
+let clientInstance = null;
+
+/**
+ * Get the gRPC client for the FS Tree Manager service
+ * Returns null if the client-replica service is not configured or disabled
+ * Creates and caches the client instance on first call
+ * @returns {FSTreeManagerClient|null} The gRPC client or null if not available
+ */
+function getClient() {
+    // Return cached instance if available
+    if ( clientInstance !== null ) {
+        return clientInstance;
+    }
+
+    const clientReplicaConfig = config.services?.['client-replica'];
+
+    // Return null if config is missing or disabled
+    if ( !clientReplicaConfig || !clientReplicaConfig.enabled ) {
+        clientInstance = null;
+        return null;
+    }
+
+    const fsTreeManagerUrl = clientReplicaConfig.fs_tree_manager_url;
+
+    // Return null if URL is not configured
+    if ( !fsTreeManagerUrl ) {
+        clientInstance = null;
+        return null;
+    }
+
+    // Create and cache gRPC client
+    clientInstance = new FSTreeManagerClient(fsTreeManagerUrl, grpc.credentials.createInsecure(), {
+        // Reconnect backoff (defaults can be slow: ~20s→120s)
+        //
+        // ref:
+        // - https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
+        // - https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md
+        'grpc.initial_reconnect_backoff_ms': 500,
+        'grpc.min_reconnect_backoff_ms': 500,
+        'grpc.max_reconnect_backoff_ms': 5000,
+
+        // // Keepalive so dead TCPs are detected quickly
+        // 'grpc.keepalive_time_ms': 15000,           // send PING every 15s
+        // 'grpc.keepalive_timeout_ms': 5000,         // wait 5s for PING ack
+        // 'grpc.keepalive_permit_without_calls': 1,  // allow pings when idle
+
+        // // (Optional) be polite about PING cadence
+        // 'grpc.http2.min_time_between_pings_ms': 10000,
+    });
+
+    return clientInstance;
+}
 
 /**
  * Sends a new filesystem entry to the gRPC service
@@ -62,6 +95,13 @@ async function sendFSNew(userId, metadata) {
             return;
         }
 
+        const client = getClient();
+        if ( !client ) {
+            // Client-replica service is not available, silently resolve
+            resolve();
+            return;
+        }
+
         const fsEntry = buildFsEntry(metadata);
         const request = new NewFSEntryRequest();
         request.setUserId(userId);
@@ -96,6 +136,13 @@ async function sendFSRemove(userId, uuid) {
             return;
         }
 
+        const client = getClient();
+        if ( !client ) {
+            // Client-replica service is not available, silently resolve
+            resolve();
+            return;
+        }
+
         const request = new RemoveFSEntryRequest();
         request.setUserId(userId);
         request.setUuid(uuid);
@@ -118,6 +165,13 @@ async function sendFSPurge(userId) {
             return;
         }
 
+        const client = getClient();
+        if ( !client ) {
+            // Client-replica service is not available, silently resolve
+            resolve();
+            return;
+        }
+
         const request = new PurgeReplicaRequest();
         request.setUserId(userId);
 
@@ -216,8 +270,8 @@ function buildFsEntry(metadataObj) {
 }
 
 module.exports = {
-    // gRPC client and protobuf classes
-    client,
+    // gRPC client function and protobuf classes
+    getClient,
     FSEntry,
     NewFSEntryRequest,
     RemoveFSEntryRequest,

src/backend/src/routers/filesystem_api/fs_tree_manager/fetch_replica.js

@@ -27,10 +27,19 @@ module.exports = {
     handler: async (socket, _data) => {
         // Import gRPC client and protobuf classes from common
         const {
-            client,
+            getClient,
             FetchReplicaRequest,
         } = require('./common');
 
+        const client = getClient();
+        if ( !client ) {
+            // Client-replica service is not available
+            return socket.emit('replica/fetch/error', {
+                success: false,
+                error: { message: 'client-replica service is not available' },
+            });
+        }
+
         // Build the request message
         const requestMsg = new FetchReplicaRequest();
         requestMsg.setUserId(socket.user.id);

src/backend/src/routers/filesystem_api/fs_tree_manager/pull_diff.js

@@ -27,11 +27,20 @@ module.exports = {
     handler: async (socket, data) => {
         // Import gRPC client and protobuf classes from common
         const {
-            client,
+            getClient,
             PullRequest,
             PullRequestItem,
         } = require('./common');
 
+        const client = getClient();
+        if (!client) {
+            // Client-replica service is not available
+            return socket.emit('replica/pull_diff/error', {
+                success: false,
+                error: { message: 'client-replica service is not available' },
+            });
+        }
+
         try {
             // Build the PullRequest message
             const requestMsg = new PullRequest();

src/gui/src/UI/UIDesktop.js

@@ -715,11 +715,10 @@ async function UIDesktop(options) {
         window.update_user_preferences(user_preferences);
     }
 
-    // Add replica status widget
-    h += `<div id="replica-status-widget" class="replica-status-widget">
+    // Add replica status widget (always create, but conditionally show)
+    h += `<div id="replica-status-widget" class="replica-status-widget" style="display: ${puter.fs.replica.debug ? 'flex' : 'none'};">
             <div class="replica-status-label">client-replica:</div>
             <div class="replica-status-value" id="replica-status-value">false</div>
-            <input type="checkbox" id="replica-status-toggle" class="replica-status-toggle">
           </div>`;
 
     // Append to <body>
@@ -728,33 +727,25 @@ async function UIDesktop(options) {
     // Initialize replica status widget function
     window.updateReplicaStatusWidget = function() {
         const statusElement = document.getElementById('replica-status-value');
-        const toggleElement = document.getElementById('replica-status-toggle');
-        if (statusElement && toggleElement) {
+        if (statusElement) {
             const isAvailable = puter.fs.replica.available === true;
             statusElement.textContent = isAvailable.toString();
             statusElement.className = `replica-status-value ${isAvailable}`;
-            toggleElement.checked = isAvailable;
         }
     };
 
-    // Handle toggle change
-    window.handleReplicaToggle = function() {
-        const toggleElement = document.getElementById('replica-status-toggle');
-        const statusElement = document.getElementById('replica-status-value');
-        if (toggleElement && statusElement) {
-            const newValue = toggleElement.checked;
-            statusElement.textContent = newValue.toString();
-            statusElement.className = `replica-status-value ${newValue}`;
-            puter.fs.replica.available = newValue;
+
+    // Function to show/hide widget based on debug flag
+    window.updateReplicaWidgetVisibility = function() {
+        const widget = document.getElementById('replica-status-widget');
+        if (widget) {
+            widget.style.display = puter.fs.replica.debug ? 'flex' : 'none';
         }
     };
 
     // Initialize widget and start polling
     setTimeout(() => {
-        const toggleElement = document.getElementById('replica-status-toggle');
-        if (toggleElement) {
-            toggleElement.addEventListener('change', window.handleReplicaToggle);
-        }
+        // Start polling immediately - the visibility is controlled by CSS
         setInterval(window.updateReplicaStatusWidget, 100);
     }, 100);
 

src/gui/src/css/style.css

@@ -5312,7 +5312,7 @@ fieldset[name=number-code] {
 .replica-status-widget {
     position: fixed;
     top: 10px;
-    right: 10px;
+    right: 50px;
     background: rgba(0, 0, 0, 0.8);
     color: white;
     padding: 8px 12px;
@@ -5328,6 +5328,10 @@ fieldset[name=number-code] {
     border: 1px solid rgba(255, 255, 255, 0.1);
 }
 
+.replica-status-widget.hidden {
+    display: none;
+}
+
 .replica-status-label {
     font-weight: 500;
     opacity: 0.8;

src/puter-js/src/modules/FileSystem/replica/manager.js

@@ -31,7 +31,7 @@ class ReplicaManager {
         this.fs_tree = null;
         this.last_local_update = 0; // milliseconds since epoch
 
-        this.debug = true;
+        this.debug = false;
     }
 
     /**
@@ -385,6 +385,18 @@ class ReplicaManager {
 
         this.available = false;
     }
+
+    /**
+     * Set the debug flag
+     */
+    setDebug(enabled) {
+        this.debug = enabled;
+
+        // Update widget visibility if the function exists (in GUI environment)
+        if (typeof window !== 'undefined' && window.updateReplicaWidgetVisibility) {
+            window.updateReplicaWidgetVisibility();
+        }
+    }
 }
 
 // Create singleton instance