fix(scanner): make distributed usage convergence authoritative (#5151)

* fix(scanner): make distributed usage cycles authoritative

* fix(scanner): close distributed refresh races

* fix(config): align scanner reload integration

* fix(admin): scope config test helpers

* fix(scanner): harden distributed usage convergence

* fix(scanner): preserve rolling activity compatibility

* fix(admin): expose non-secret optional config values

* fix(scanner): acknowledge distributed dirty usage

* fix(ecstore): make bucket mutations cancellation safe

* fix(scanner): preserve pending dirty acknowledgements

* test(obs): account for superseded scanner metric

* fix(api): reject excess detached bucket mutations

* test: close scanner convergence coverage gaps

* fix(scanner): make path tracking cleanup one-shot

---------

Co-authored-by: Henry Guo <marshawcoco@users.noreply.github.com>
Co-authored-by: houseme <housemecn@gmail.com>

crates/ecstore/src/disk/error.rs

@@ -231,6 +231,13 @@ impl DiskError {
         }
     }
 
+    pub fn is_internode_http_status(&self, status: u16) -> bool {
+        matches!(
+            self.internode_http_error_kind(),
+            Some(InternodeHttpErrorKind::HttpStatus(actual)) if actual.as_u16() == status
+        )
+    }
+
     // /// If all errors are of the same fatal disk error type, returns the corresponding error.
     // /// Otherwise, returns Ok.
     // pub fn check_disk_fatal_errs(errs: &[Option<Error>]) -> Result<()> {
@@ -981,6 +988,17 @@ mod tests {
         assert!(!disk_error.contains_io_error_kind(std::io::ErrorKind::TimedOut));
     }
 
+    #[test]
+    fn test_internode_http_status_classification() {
+        let too_many_requests = DiskError::from(rustfs_rio::new_test_internode_http_io_error(
+            rustfs_rio::InternodeHttpErrorKind::HttpStatus(http::StatusCode::TOO_MANY_REQUESTS),
+        ));
+
+        assert!(too_many_requests.is_internode_http_status(429));
+        assert!(!too_many_requests.is_internode_http_status(500));
+        assert!(!DiskError::FileNotFound.is_internode_http_status(429));
+    }
+
     #[test]
     fn test_metacache_output_stream_closed_classification_survives_clone() {
         let disk_error = DiskError::metacache_output_stream_closed();

crates/ecstore/src/disk/mod.rs

@@ -52,7 +52,7 @@ use local::LocalDisk;
 use rustfs_filemeta::{FileInfo, ObjectPartInfo, RawFileInfo};
 use rustfs_madmin::info_commands::DiskMetrics;
 use serde::{Deserialize, Serialize};
-use std::{fmt::Debug, path::PathBuf, sync::Arc};
+use std::{fmt::Debug, path::PathBuf, sync::Arc, time::Duration};
 use time::OffsetDateTime;
 use tokio::io::{AsyncRead, AsyncWrite};
 use uuid::Uuid;
@@ -453,6 +453,20 @@ impl DiskAPI for Disk {
 }
 
 impl Disk {
+    pub async fn ns_scanner_server_epoch(&self) -> Result<Option<Uuid>> {
+        match self {
+            Disk::Local(_) => Ok(None),
+            Disk::Remote(remote_disk) => remote_disk.ns_scanner_server_epoch().await,
+        }
+    }
+
+    pub async fn open_ns_scanner_stream(&self, request: NsScannerOpenRequest) -> Result<FileReader> {
+        match self {
+            Disk::Remote(remote_disk) => remote_disk.open_ns_scanner_stream(request).await,
+            Disk::Local(_) => Err(Error::other("namespace scanner stream requires a remote disk")),
+        }
+    }
+
     pub fn runtime_state(&self) -> RuntimeDriveHealthState {
         match self {
             Disk::Local(local_disk) => local_disk.runtime_state(),
@@ -498,6 +512,18 @@ impl Disk {
     }
 }
 
+#[derive(Debug)]
+pub struct NsScannerOpenRequest {
+    pub request_id: Uuid,
+    pub server_epoch: Uuid,
+    pub session_id: Uuid,
+    pub session_sequence: u64,
+    pub next_cycle: u64,
+    pub leader_epoch: u64,
+    pub body: Vec<u8>,
+    pub stall_timeout: Option<Duration>,
+}
+
 impl Disk {
     /// Reset drive health so `connect_load_init_formats` retries are not blocked by a prior
     /// transient mark-faulty (same disk handles are reused across retries).