fix: deduplicate concurrent refresh requests (#386)

This changes refresh handling so concurrent compatible refresh requests
join a single physical refresh instead of rerunning the same work, while
keeping locator state safe across configure and refresh boundaries.

- replace the coarse global refresh lock with a generation-aware
single-flight coordinator
- run physical refreshes on transient locator graphs and sync back the
shared Conda and Poetry state that later requests rely on
- canonicalize refresh parameters so compatible `searchPaths` requests
dedupe correctly and malformed non-empty array params still fail
- add coordinator unit coverage for joining, waiting, generation
boundaries, completion-window reuse, panic safety, and cache sync
helpers
- add a reusable JSONRPC integration test client plus real server tests
for configure/refresh behavior and concurrent refresh deduplication

Fixes #383

Author: karthiknadig

crates/pet-conda/src/lib.rs

@@ -16,7 +16,7 @@ use pet_core::{
     os_environment::Environment,
     python_environment::{PythonEnvironment, PythonEnvironmentKind},
     reporter::Reporter,
-    Locator, LocatorKind,
+    Locator, LocatorKind, RefreshStatePersistence, RefreshStateSyncScope,
 };
 use pet_fs::path::norm_case;
 use rayon::prelude::*;
@@ -216,11 +216,39 @@ impl Locator for Conda {
     fn get_kind(&self) -> LocatorKind {
         LocatorKind::Conda
     }
-    fn configure(&self, config: &pet_core::Configuration) {
-        if let Some(ref conda_exe) = config.conda_executable {
-            let mut conda_executable = self.conda_executable.write().unwrap();
-            conda_executable.replace(conda_exe.clone());
+    fn refresh_state(&self) -> RefreshStatePersistence {
+        RefreshStatePersistence::SyncedDiscoveryState
+    }
+    fn sync_refresh_state_from(&self, source: &dyn Locator, scope: &RefreshStateSyncScope) {
+        let source = source.as_any().downcast_ref::<Conda>().unwrap_or_else(|| {
+            panic!("attempted to sync Conda state from {:?}", source.get_kind())
+        });
+
+        match scope {
+            RefreshStateSyncScope::Full => {}
+            RefreshStateSyncScope::GlobalFiltered(kind)
+                if self.supported_categories().contains(kind) => {}
+            RefreshStateSyncScope::GlobalFiltered(_) | RefreshStateSyncScope::Workspace => {
+                return;
+            }
         }
+
+        self.environments.clear();
+        self.environments
+            .insert_many(source.environments.clone_map());
+
+        self.managers.clear();
+        self.managers.insert_many(source.managers.clone_map());
+
+        self.mamba_managers.clear();
+        self.mamba_managers
+            .insert_many(source.mamba_managers.clone_map());
+    }
+    fn configure(&self, config: &pet_core::Configuration) {
+        self.conda_executable
+            .write()
+            .unwrap()
+            .clone_from(&config.conda_executable);
     }
     fn supported_categories(&self) -> Vec<PythonEnvironmentKind> {
         vec![PythonEnvironmentKind::Conda]

crates/pet-core/src/lib.rs

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-use std::path::PathBuf;
+use std::{any::Any, path::PathBuf};
 
 use env::PythonEnv;
 use manager::EnvManager;
@@ -61,7 +61,26 @@ pub enum LocatorKind {
     WindowsStore,
 }
 
-pub trait Locator: Send + Sync {
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RefreshStatePersistence {
+    /// The locator keeps no mutable state across requests.
+    Stateless,
+    /// The locator keeps configured inputs only; refresh must not copy them back.
+    ConfiguredOnly,
+    /// The locator keeps cache-like state, but later requests can repopulate it on demand.
+    SelfHydratingCache,
+    /// The locator keeps refresh-discovered state that later requests depend on for correctness.
+    SyncedDiscoveryState,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RefreshStateSyncScope {
+    Full,
+    GlobalFiltered(PythonEnvironmentKind),
+    Workspace,
+}
+
+pub trait Locator: Any + Send + Sync {
     /// Returns the name of the locator.
     fn get_kind(&self) -> LocatorKind;
     /// Configures the locator with the given configuration.
@@ -100,6 +119,21 @@ pub trait Locator: Send + Sync {
     fn configure(&self, _config: &Configuration) {
         //
     }
+    /// Describes what mutable state, if any, must survive a refresh boundary.
+    ///
+    /// Refresh runs execute against transient locator graphs and then invoke
+    /// `sync_refresh_state_from()` on the long-lived shared locators.
+    fn refresh_state(&self) -> RefreshStatePersistence {
+        RefreshStatePersistence::Stateless
+    }
+    /// Copies correctness-critical post-refresh state from a transient locator into this
+    /// long-lived shared locator.
+    ///
+    /// Override this only when `refresh_state()` returns
+    /// `RefreshStatePersistence::SyncedDiscoveryState`.
+    fn sync_refresh_state_from(&self, _source: &dyn Locator, _scope: &RefreshStateSyncScope) {
+        //
+    }
     /// Returns a list of supported categories for this locator.
     fn supported_categories(&self) -> Vec<PythonEnvironmentKind>;
     /// Given a Python executable, and some optional data like prefix,
@@ -112,3 +146,9 @@ pub trait Locator: Send + Sync {
     /// Finds all environments specific to this locator.
     fn find(&self, reporter: &dyn Reporter);
 }
+
+impl dyn Locator {
+    pub fn as_any(&self) -> &dyn Any {
+        self
+    }
+}

crates/pet-linux-global-python/src/lib.rs

@@ -15,7 +15,7 @@ use pet_core::{
     env::PythonEnv,
     python_environment::{PythonEnvironment, PythonEnvironmentBuilder, PythonEnvironmentKind},
     reporter::Reporter,
-    Locator, LocatorKind,
+    Locator, LocatorKind, RefreshStatePersistence,
 };
 use pet_fs::path::resolve_symlink;
 use pet_python_utils::{env::ResolvedPythonEnv, executable::find_executables};
@@ -62,6 +62,9 @@ impl Locator for LinuxGlobalPython {
     fn get_kind(&self) -> LocatorKind {
         LocatorKind::LinuxGlobal
     }
+    fn refresh_state(&self) -> RefreshStatePersistence {
+        RefreshStatePersistence::SelfHydratingCache
+    }
     fn supported_categories(&self) -> Vec<PythonEnvironmentKind> {
         vec![PythonEnvironmentKind::LinuxGlobal]
     }

crates/pet-pipenv/src/lib.rs

@@ -11,7 +11,7 @@ use pet_core::LocatorKind;
 use pet_core::{
     python_environment::{PythonEnvironment, PythonEnvironmentBuilder, PythonEnvironmentKind},
     reporter::Reporter,
-    Configuration, Locator,
+    Configuration, Locator, RefreshStatePersistence,
 };
 use pet_fs::path::norm_case;
 use pet_python_utils::executable::find_executables;
@@ -418,10 +418,15 @@ impl Locator for PipEnv {
         LocatorKind::PipEnv
     }
 
+    fn refresh_state(&self) -> RefreshStatePersistence {
+        RefreshStatePersistence::ConfiguredOnly
+    }
+
     fn configure(&self, config: &Configuration) {
-        if let Some(exe) = &config.pipenv_executable {
-            self.pipenv_executable.write().unwrap().replace(exe.clone());
-        }
+        self.pipenv_executable
+            .write()
+            .unwrap()
+            .clone_from(&config.pipenv_executable);
     }
 
     fn supported_categories(&self) -> Vec<PythonEnvironmentKind> {