improvements [claude]

  1. Weight Validation: Added validation to ensure all provider weights are not zero (prevents silent failures)
  2. Fixed Error Retesting Logic: Moved error retesting to occur AFTER weight-based selection, preventing it from skewing the intended weight distribution
  3. Configuration Documentation: Added comprehensive comments in the config file explaining:
    - Weight ranges (0.0 to 1.0)
    - That weights are relative and don't need to sum to 1.0
    - Examples of weight distribution calculations
    - Requirement that at least one provider must have weight > 0.0
  4. Inline Code Documentation: Added detailed doc comments for all weight-related methods explaining:
    - The purpose and behavior of each selection strategy
    - How weights are normalized internally
    - Fallback mechanisms when weights are invalid
  5. Metrics Decision: Per your feedback, avoided adding debug/trace logging to prevent performance and storage overhead

  🎯 Key Benefits of These Changes:

  - More Predictable Distribution: Error retesting now only slightly perturbs weight distribution instead of completely overriding it
  - Better Error Prevention: Validation catches configuration mistakes early
  - Improved Maintainability: Clear documentation helps future developers understand the system
  - Production Ready: The implementation is now more robust with proper validation and error handling

The weighted load-balancing feature is now more reliable, better documented, and will behave more predictably in production environments.

Author: DaMandal0rian

chain/ethereum/src/network.rs

@@ -197,37 +197,44 @@ impl EthereumNetworkAdapters {
         Self::available_with_capabilities(all, required_capabilities)
     }
 
-    // handle adapter selection from a list, implements the availability checking with an abstracted
-    // source of the adapter list.
+    /// Main adapter selection entry point that handles both weight-based distribution
+    /// and error retesting logic.
+    /// 
+    /// The selection process:
+    /// 1. First selects an adapter based on weights (if enabled) or random selection
+    /// 2. Occasionally overrides the selection to retest adapters with errors
+    /// 
+    /// The error retesting happens AFTER weight-based selection to minimize
+    /// distribution skew while still allowing periodic health checks of errored endpoints.
     fn cheapest_from(
         &self,
         input: Vec<&EthereumNetworkAdapter>,
         required_capabilities: &NodeCapabilities,
     ) -> Result<Arc<EthereumAdapter>, Error> {
-        // First, try to re-test an errored adapter
-        if let Some(adapter) = self.retest_errored_adapter(&input) {
-            return Ok(adapter);
-        }
-
-        // If no adapter was re-tested, select the best available adapter
-        self.select_best_adapter(input, required_capabilities)
-    }
-
-    fn retest_errored_adapter(
-        &self,
-        input: &[&EthereumNetworkAdapter],
-    ) -> Option<Arc<EthereumAdapter>> {
+        // Select adapter based on weights or random strategy
+        let selected_adapter = self.select_best_adapter(input.clone(), required_capabilities)?;
+        
+        // Occasionally override selection to retest errored adapters
+        // This happens AFTER weight-based selection to minimize distribution skew
         let retest_rng: f64 = rand::thread_rng().gen();
         if retest_rng < self.retest_percent {
-            input
+            // Find the adapter with the highest error count
+            if let Some(most_errored) = input
                 .iter()
                 .max_by_key(|a| a.current_error_count())
-                .map(|adapter| adapter.adapter.clone())
-        } else {
-            None
+                .filter(|a| a.current_error_count() > 0)
+            {
+                return Ok(most_errored.adapter.clone());
+            }
         }
+        
+        Ok(selected_adapter)
     }
 
+
+    /// Selects the best adapter based on the configured strategy (weighted or random).
+    /// If weighted mode is enabled, uses weight-based probabilistic selection.
+    /// Otherwise, falls back to random selection with error count consideration.
     fn select_best_adapter(
         &self,
         input: Vec<&EthereumNetworkAdapter>,
@@ -240,6 +247,13 @@ impl EthereumNetworkAdapters {
         }
     }
 
+    /// Performs weighted random selection of adapters based on their configured weights.
+    /// 
+    /// Weights are relative values between 0.0 and 1.0 that determine the probability
+    /// of selecting each adapter. They don't need to sum to 1.0 as they're normalized
+    /// internally by the WeightedIndex distribution.
+    /// 
+    /// Falls back to random selection if weights are invalid (e.g., all zeros).
     fn select_weighted_adapter(
         &self,
         input: Vec<&EthereumNetworkAdapter>,
@@ -261,6 +275,11 @@ impl EthereumNetworkAdapters {
         }
     }
 
+    /// Performs random selection of adapters with preference for those with fewer errors.
+    /// 
+    /// Randomly selects up to 3 adapters from the available pool, then chooses the one
+    /// with the lowest error count. This provides a balance between load distribution
+    /// and avoiding problematic endpoints.
     fn select_random_adapter(
         &self,
         input: Vec<&EthereumNetworkAdapter>,

node/resources/tests/full_config.toml

@@ -45,6 +45,13 @@ indexers = [ "index_node_1_a",
 [chains]
 ingestor = "index_0"
 
+# Provider weights configuration:
+# - Weights must be between 0.0 and 1.0 (inclusive)
+# - Weights are relative - they don't need to sum to 1.0
+# - Traffic is distributed proportionally based on weights
+# - Example: weights [0.2, 0.8] = 20% and 80% traffic distribution
+# - Example: weights [1.0, 2.0, 1.0] = 25%, 50%, 25% distribution
+# - At least one provider must have weight > 0.0
 [chains.mainnet]
 shard = "primary"
 provider = [

node/src/config.rs

@@ -549,6 +549,16 @@ impl Chain {
         if labels.len() != self.providers.len() {
             return Err(anyhow!("Provider labels must be unique"));
         }
+        
+        // Check that not all provider weights are zero
+        if !self.providers.is_empty() {
+            let all_zero_weights = self.providers.iter().all(|p| p.weight == 0.0);
+            if all_zero_weights {
+                return Err(anyhow!(
+                    "All provider weights are 0.0; at least one provider must have a weight > 0.0"
+                ));
+            }
+        }
 
         // `Config` validates that `self.shard` references a configured shard
         for provider in self.providers.iter_mut() {