Merge pull request #2121 from posit-dev/sagerb-debounce-on-watchers

UX: Add debounce and throttling to main query methods

extensions/vscode/package.json

@@ -538,6 +538,7 @@
   "dependencies": {
     "@hypersphere/omnibus": "0.1.6",
     "@vscode/codicons": "^0.0.36",
+    "async-mutex": "^0.5.0",
     "axios": "^1.7.4",
     "debounce": "^2.1.0",
     "eventsource": "^2.0.2",

extensions/vscode/src/constants.ts

@@ -116,3 +116,9 @@ export const enum Views {
   HelpAndFeedback = "posit.publisher.helpAndFeedback",
   Logs = "posit.publisher.logs",
 }
+
+export const DebounceDelaysMS = {
+  file: 1000,
+  refreshRPackages: 1000,
+  refreshPythonPackages: 1000,
+};

extensions/vscode/src/utils/throttle.ts

@@ -0,0 +1,42 @@
+// Copyright (C) 2024 by Posit Software, PBC.
+
+import { Mutex, MutexInterface } from "async-mutex";
+
+/**
+ * This method allows throttling of a method (typically an API call), where only
+ * one call is active, and the last one which is requested while an existing call
+ * is still active, is then executed after the current call completes.
+ *
+ * We do not need any intermediate calls to be executed, because we're using this functionality
+ * with pure functions, which we simply need to execute the latest request.
+ *
+ * For example, if all of these come in sequence very quickly, and the API call is long:
+ *
+ * call() // A
+ * call() // B
+ * call() // C
+ * call() // D
+ *
+ * Call A will be executed and if it takes a long time, only Call D will be executed. Under the
+ * covers, when Call B comes in, it is queued up using the mutex, but then Call C cancels Call B
+ * (using mutex.cancel()), and Call C waits on the mutex, then Call D cancels Call C and waits on
+ * the mutex, which is then executed when Call A releases the mutex.
+ */
+export const throttleWithLastPending = async (
+  mutex: Mutex,
+  fn: () => Promise<void>,
+) => {
+  if (mutex.isLocked()) {
+    // we have calls waiting, so cancel them, since we're here now and taking their place
+    mutex.cancel();
+  }
+  let release: MutexInterface.Releaser | undefined;
+  try {
+    release = await mutex.acquire();
+    return await fn();
+  } finally {
+    if (release) {
+      release();
+    }
+  }
+};

extensions/vscode/src/utils/webviewConduit.ts

@@ -63,14 +63,11 @@ export class WebviewConduit {
   };
 
   public sendMsg = (msg: HostToWebviewMessage) => {
-    const e = JSON.stringify(msg);
+    // don't send messages if the Webview hasn't initialized yet
     if (!this.target) {
-      console.warn(
-        `Warning: WebviewConduit::sendMsg queueing up msg called before webview reference established with init(): ${e}`,
-      );
-      this.pendingMsgs.push(msg);
       return;
     }
+    const e = JSON.stringify(msg);
     this.target.postMessage(e);
   };
 }

extensions/vscode/src/views/homeView.ts

@@ -20,6 +20,7 @@ import {
   workspace,
 } from "vscode";
 import { isAxiosError } from "axios";
+import { Mutex } from "async-mutex";
 
 import {
   Configuration,
@@ -68,18 +69,17 @@ import { selectNewOrExistingConfig } from "src/multiStepInputs/selectNewOrExisti
 import { RPackage, RVersionConfig } from "src/api/types/packages";
 import { calculateTitle } from "src/utils/titles";
 import { ConfigWatcherManager, WatcherManager } from "src/watchers";
-import { Commands, Contexts, Views } from "src/constants";
+import { Commands, Contexts, DebounceDelaysMS, Views } from "src/constants";
 import { showProgress } from "src/utils/progress";
 import { newCredential } from "src/multiStepInputs/newCredential";
 import { PublisherState } from "src/state";
+import { throttleWithLastPending } from "src/utils/throttle";
 
 enum HomeViewInitialized {
   initialized = "initialized",
   uninitialized = "uninitialized",
 }
 
-const fileEventDebounce = 200;
-
 export class HomeViewProvider implements WebviewViewProvider, Disposable {
   private disposables: Disposable[] = [];
 
@@ -137,8 +137,8 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       "activeConfigChanged",
       (cfg: Configuration | ConfigurationError | undefined) => {
         this.sendRefreshedFilesLists();
-        this.onRefreshPythonPackages();
-        this.onRefreshRPackages();
+        this.refreshPythonPackages();
+        this.refreshRPackages();
 
         this.configWatchers?.dispose();
         if (cfg && isConfigurationError(cfg)) {
@@ -147,33 +147,33 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
         this.configWatchers = new ConfigWatcherManager(cfg);
 
         this.configWatchers.configFile?.onDidChange(
-          this.sendRefreshedFilesLists,
+          this.debounceSendRefreshedFilesLists,
           this,
         );
 
         this.configWatchers.pythonPackageFile?.onDidCreate(
-          this.onRefreshPythonPackages,
+          this.debounceRefreshPythonPackages,
           this,
         );
         this.configWatchers.pythonPackageFile?.onDidChange(
-          this.onRefreshPythonPackages,
+          this.debounceRefreshPythonPackages,
           this,
         );
         this.configWatchers.pythonPackageFile?.onDidDelete(
-          this.onRefreshPythonPackages,
+          this.debounceRefreshPythonPackages,
           this,
         );
 
         this.configWatchers.rPackageFile?.onDidCreate(
-          this.onRefreshRPackages,
+          this.debounceRefreshRPackages,
           this,
         );
         this.configWatchers.rPackageFile?.onDidChange(
-          this.onRefreshRPackages,
+          this.debounceRefreshRPackages,
           this,
         );
         this.configWatchers.rPackageFile?.onDidDelete(
-          this.onRefreshRPackages,
+          this.debounceRefreshRPackages,
           this,
         );
       },
@@ -197,9 +197,9 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       case WebviewToHostMessageType.SAVE_SELECTION_STATE:
         return await this.onSaveSelectionState(msg);
       case WebviewToHostMessageType.REFRESH_PYTHON_PACKAGES:
-        return await this.onRefreshPythonPackages();
+        return await this.debounceRefreshPythonPackages();
       case WebviewToHostMessageType.REFRESH_R_PACKAGES:
-        return await this.onRefreshRPackages();
+        return await this.debounceRefreshRPackages();
       case WebviewToHostMessageType.VSCODE_OPEN_RELATIVE:
         return await this.onRelativeOpenVSCode(msg);
       case WebviewToHostMessageType.SCAN_PYTHON_PACKAGE_REQUIREMENTS:
@@ -209,7 +209,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       case WebviewToHostMessageType.VSCODE_OPEN:
         return await this.onVSCodeOpen(msg);
       case WebviewToHostMessageType.REQUEST_FILES_LISTS:
-        return this.sendRefreshedFilesLists();
+        return this.debounceSendRefreshedFilesLists();
       case WebviewToHostMessageType.INCLUDE_FILE:
         return this.updateFileList(msg.content.path, FileAction.INCLUDE);
       case WebviewToHostMessageType.EXCLUDE_FILE:
@@ -470,7 +470,12 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
     );
   }
 
-  private async onRefreshPythonPackages() {
+  public debounceRefreshPythonPackages = debounce(
+    this.refreshPythonPackages,
+    DebounceDelaysMS.refreshPythonPackages,
+  );
+
+  private async refreshPythonPackages() {
     const activeConfiguration = await this.state.getSelectedConfiguration();
     let pythonProject = true;
     let packages: string[] = [];
@@ -512,7 +517,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
             pythonProject = false;
           } else {
             const summary = getSummaryStringFromError(
-              "homeView::onRefreshPythonPackages",
+              "homeView::refreshPythonPackages",
               error,
             );
             window.showInformationMessage(summary);
@@ -532,7 +537,12 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
     });
   }
 
-  private async onRefreshRPackages() {
+  public debounceRefreshRPackages = debounce(
+    this.refreshRPackages,
+    DebounceDelaysMS.refreshRPackages,
+  );
+
+  private async refreshRPackages() {
     const activeConfiguration = await this.state.getSelectedConfiguration();
     let rProject = true;
     let packages: RPackage[] = [];
@@ -575,7 +585,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
             rProject = false;
           } else {
             const summary = getSummaryStringFromError(
-              "homeView::onRefreshRPackages",
+              "homeView::refreshRPackages",
               error,
             );
             window.showInformationMessage(summary);
@@ -1251,21 +1261,33 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
     }
   };
 
-  public refreshContentRecords = async () => {
-    await this.refreshContentRecordData();
-    this.updateWebViewViewContentRecords();
-    useBus().trigger(
-      "activeContentRecordChanged",
-      await this.state.getSelectedContentRecord(),
+  private refreshContentRecordsMutex = new Mutex();
+  public refreshContentRecords = () => {
+    return throttleWithLastPending(
+      this.refreshContentRecordsMutex,
+      async () => {
+        await this.refreshContentRecordData();
+        this.updateWebViewViewContentRecords();
+        useBus().trigger(
+          "activeContentRecordChanged",
+          await this.state.getSelectedContentRecord(),
+        );
+      },
     );
   };
 
-  public refreshConfigurations = async () => {
-    await this.refreshConfigurationData();
-    this.updateWebViewViewConfigurations();
-    useBus().trigger(
-      "activeConfigChanged",
-      await this.state.getSelectedConfiguration(),
+  private refreshConfigurationsMutex = new Mutex();
+  public refreshConfigurations = () => {
+    return throttleWithLastPending(
+      this.refreshConfigurationsMutex,
+      async () => {
+        await this.refreshConfigurationData();
+        this.updateWebViewViewConfigurations();
+        useBus().trigger(
+          "activeConfigChanged",
+          await this.state.getSelectedConfiguration(),
+        );
+      },
     );
   };
 
@@ -1299,6 +1321,10 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
     }
   };
 
+  public debounceSendRefreshedFilesLists = debounce(async () => {
+    return await this.sendRefreshedFilesLists();
+  }, DebounceDelaysMS.file);
+
   public initiatePublish(target: PublishProcessParams) {
     this.initiateDeployment(
       target.deploymentName,
@@ -1612,7 +1638,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       ),
       commands.registerCommand(
         Commands.PythonPackages.Refresh,
-        this.onRefreshPythonPackages,
+        this.refreshPythonPackages,
         this,
       ),
       commands.registerCommand(
@@ -1641,7 +1667,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       ),
       commands.registerCommand(
         Commands.RPackages.Refresh,
-        this.onRefreshRPackages,
+        this.refreshRPackages,
         this,
       ),
       commands.registerCommand(
@@ -1651,6 +1677,7 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
       ),
     );
 
+    // directories
     watchers.positDir?.onDidDelete(() => {
       this.refreshContentRecords();
       this.refreshConfigurations();
@@ -1661,19 +1688,18 @@ export class HomeViewProvider implements WebviewViewProvider, Disposable {
     }, this);
     watchers.contentRecordsDir?.onDidDelete(this.refreshContentRecords, this);
 
+    // configurations
     watchers.configurations?.onDidCreate(this.refreshConfigurations, this);
-    watchers.configurations?.onDidDelete(this.refreshConfigurations, this);
     watchers.configurations?.onDidChange(this.refreshConfigurations, this);
+    watchers.configurations?.onDidDelete(this.refreshConfigurations, this);
 
+    // content records
     watchers.contentRecords?.onDidCreate(this.refreshContentRecords, this);
-    watchers.contentRecords?.onDidDelete(this.refreshContentRecords, this);
     watchers.contentRecords?.onDidChange(this.refreshContentRecords, this);
+    watchers.contentRecords?.onDidDelete(this.refreshContentRecords, this);
 
-    const fileEventCallback = debounce(
-      this.sendRefreshedFilesLists,
-      fileEventDebounce,
-    );
-    watchers.allFiles?.onDidCreate(fileEventCallback, this);
-    watchers.allFiles?.onDidDelete(fileEventCallback, this);
+    // all files
+    watchers.allFiles?.onDidCreate(this.debounceSendRefreshedFilesLists, this);
+    watchers.allFiles?.onDidDelete(this.debounceSendRefreshedFilesLists, this);
   }
 }