v0.2.5-pre.010.fix.001

crates/ksp-onchain-transport-lib/src/resilience.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/resilience.rs
-// version: 2
+// version: 3
 
 const DEFAULT_RATE_LIMIT_COOLDOWN: std::time::Duration = std::time::Duration::from_secs(1);
 const MAX_PROVIDER_RETRY_AFTER: std::time::Duration = std::time::Duration::from_secs(60);
@@ -71,6 +71,7 @@ impl HttpRetryDecision {
     }
 }
 
+/// Crate-internal `HttpRoleRuntime` state shared across the owning crate.
 pub(crate) struct HttpRoleRuntime {
     limits: crate::HttpRoleLimits,
     bucket: std::sync::Mutex<std::option::Option<HttpTokenBucketState>>,
@@ -84,6 +85,7 @@ pub(crate) struct HttpRoleRuntime {
 }
 
 impl HttpRoleRuntime {
+    /// Creates a new `HttpRoleRuntime` value.
     pub(crate) fn new(settings: &crate::HttpEndpointRoleSettings, notify: std::sync::Arc<tokio::sync::Notify>) -> Self {
         let bucket = match settings.limits().requests_per_second() {
             std::option::Option::Some(requests_per_second) => {
@@ -114,6 +116,7 @@ impl HttpRoleRuntime {
         };
     }
 
+    /// Returns the current availability.
     pub(crate) fn availability(&self, now: std::time::Instant) -> crate::HttpEndpointAvailability {
         if self.cooldown_remaining_at(now).is_some() {
             return crate::HttpEndpointAvailability::RateLimited;
@@ -124,14 +127,17 @@ impl HttpRoleRuntime {
         return crate::HttpEndpointAvailability::Available;
     }
 
+    /// Returns the current cooldown remaining.
     pub(crate) fn cooldown_remaining(&self) -> std::option::Option<std::time::Duration> {
         return self.cooldown_remaining_at(std::time::Instant::now());
     }
 
+    /// Returns the current max concurrent requests.
     pub(crate) fn max_concurrent_requests(&self) -> std::option::Option<u32> {
         return self.limits.max_concurrent_requests().map(|value| return value.get());
     }
 
+    /// Returns the current in flight requests.
     pub(crate) fn in_flight_requests(&self) -> std::option::Option<u32> {
         let semaphore = match &self.semaphore {
             std::option::Option::Some(value) => value,
@@ -149,18 +155,22 @@ impl HttpRoleRuntime {
         return std::option::Option::Some(maximum.saturating_sub(available_u32));
     }
 
+    /// Returns the current success count.
     pub(crate) fn success_count(&self) -> u64 {
         return self.success_count.load(std::sync::atomic::Ordering::Relaxed);
     }
 
+    /// Returns the current failure count.
     pub(crate) fn failure_count(&self) -> u64 {
         return self.failure_count.load(std::sync::atomic::Ordering::Relaxed);
     }
 
+    /// Returns the current rate limit count.
     pub(crate) fn rate_limit_count(&self) -> u64 {
         return self.rate_limit_count.load(std::sync::atomic::Ordering::Relaxed);
     }
 
+    /// Attempts to acquire.
     pub(crate) fn try_acquire(self: &std::sync::Arc<Self>, now: std::time::Instant) -> crate::RoleAdmissionAttempt {
         if let std::option::Option::Some(remaining) = self.cooldown_remaining_at(now) {
             let ready_at = match now.checked_add(remaining) {
@@ -189,6 +199,7 @@ impl HttpRoleRuntime {
         return crate::RoleAdmissionAttempt::Ready(HttpConcurrencyPermit { semaphore_permit, notify: std::sync::Arc::clone(&self.notify) });
     }
 
+    /// Records success.
     pub(crate) fn record_success(&self) {
         self.success_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         self.degraded.store(false, std::sync::atomic::Ordering::Relaxed);
@@ -196,6 +207,7 @@ impl HttpRoleRuntime {
         return;
     }
 
+    /// Records failure.
     pub(crate) fn record_failure(&self) {
         self.failure_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         self.degraded.store(true, std::sync::atomic::Ordering::Relaxed);
@@ -203,6 +215,7 @@ impl HttpRoleRuntime {
         return;
     }
 
+    /// Records rate limited.
     pub(crate) fn record_rate_limited(&self, provider_retry_after: std::option::Option<std::time::Duration>) -> std::time::Duration {
         self.failure_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         self.rate_limit_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
@@ -269,6 +282,7 @@ impl HttpRoleRuntime {
     }
 }
 
+/// Crate-internal `RoleAdmissionAttempt` variants used by the owning crate.
 pub(crate) enum RoleAdmissionAttempt {
     Ready(HttpConcurrencyPermit),
     BlockedUntil(std::time::Instant),
@@ -276,6 +290,7 @@ pub(crate) enum RoleAdmissionAttempt {
     Unavailable,
 }
 
+/// Crate-internal `HttpConcurrencyPermit` state shared across the owning crate.
 pub(crate) struct HttpConcurrencyPermit {
     semaphore_permit: std::option::Option<tokio::sync::OwnedSemaphorePermit>,
     notify: std::sync::Arc<tokio::sync::Notify>,