refactor(common): move scanner/heal contracts into dedicated crates (#6615)

refactor(common): move scanner/heal domain contracts into dedicated crates

crates/common carried ~5.6K lines of scanner/heal domain code (metrics.rs,
heal_channel.rs, last_minute.rs) parked there to break dependency cycles;
every scanner type change recompiled all 11 rustfs-common dependents.

Pure move, zero renames, zero shape changes (backlog#1843):

- New crate rustfs-heal-contracts receives heal_channel.
- New crate rustfs-scanner-contracts receives metrics, last_minute, and the
  GLOBAL_INIT_TIME trio (metrics::report() reads it as the current-cycle
  fallback, so it must live below the shim to avoid a dependency cycle).
- rustfs-common re-exports everything at the old paths as a transitional
  shim; consumers migrate crate by crate, then the shims are deleted.

crates/scanner-contracts/Cargo.toml

@@ -0,0 +1,45 @@
+# Copyright 2024 RustFS Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[package]
+name = "rustfs-scanner-contracts"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+homepage.workspace = true
+description = "Scanner metrics and lifecycle-cycle contracts shared by the scanner, storage engine, and observability layers."
+keywords = ["scanner", "contracts", "metrics", "rustfs", "Minio"]
+categories = ["web-programming", "development-tools", "data-structures"]
+
+[lints]
+workspace = true
+
+[dependencies]
+chrono = { workspace = true, features = ["serde"] }
+jiff = { workspace = true, features = ["serde"] }
+metrics = { workspace = true }
+rmp-serde = { workspace = true }
+rustfs-heal-contracts = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+tokio = { workspace = true, features = ["sync"] }
+
+[dev-dependencies]
+serde_json = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+uuid = { workspace = true, features = ["v4"] }
+
+[lib]
+doctest = false

crates/scanner-contracts/src/init_time.rs

@@ -0,0 +1,34 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use std::sync::LazyLock;
+use tokio::sync::RwLock;
+
+/// Global initialization time of the RustFS node.
+pub static GLOBAL_INIT_TIME: LazyLock<RwLock<Option<DateTime<Utc>>>> = LazyLock::new(|| RwLock::new(None));
+
+/// Set the global RustFS initialization time to the current UTC time.
+pub async fn set_global_init_time_now() {
+    let now = Utc::now();
+    *GLOBAL_INIT_TIME.write().await = Some(now);
+}
+
+/// Get the global RustFS initialization time.
+///
+/// # Returns
+/// * `Option<DateTime<Utc>>` - The initialization time if set.
+pub async fn get_global_init_time() -> Option<DateTime<Utc>> {
+    *GLOBAL_INIT_TIME.read().await
+}

crates/scanner-contracts/src/last_minute.rs

@@ -0,0 +1,498 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+#[derive(Clone, Debug, Default, Copy)]
+pub struct AccElem {
+    pub total: u64,
+    pub size: u64,
+    pub n: u64,
+}
+
+impl AccElem {
+    pub fn add(&mut self, dur: &Duration) {
+        let dur = dur.as_secs();
+        self.total = self.total.wrapping_add(dur);
+        self.n = self.n.wrapping_add(1);
+    }
+
+    pub fn merge(&mut self, b: &AccElem) {
+        self.n = self.n.wrapping_add(b.n);
+        self.total = self.total.wrapping_add(b.total);
+        self.size = self.size.wrapping_add(b.size);
+    }
+
+    pub fn avg(&self) -> Duration {
+        if self.n >= 1 && self.total > 0 {
+            return Duration::from_secs(self.total / self.n);
+        }
+        Duration::from_secs(0)
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct LastMinuteLatency {
+    pub totals: Vec<AccElem>,
+    pub last_sec: u64,
+}
+
+impl Default for LastMinuteLatency {
+    fn default() -> Self {
+        Self {
+            totals: vec![AccElem::default(); 60],
+            last_sec: Default::default(),
+        }
+    }
+}
+
+impl LastMinuteLatency {
+    pub fn merge(&mut self, o: &LastMinuteLatency) -> LastMinuteLatency {
+        let mut merged = LastMinuteLatency::default();
+        let mut x = o.clone();
+        if self.last_sec > o.last_sec {
+            x.forward_to(self.last_sec);
+            merged.last_sec = self.last_sec;
+        } else {
+            self.forward_to(o.last_sec);
+            merged.last_sec = o.last_sec;
+        }
+
+        // Both operands must be read in their forwarded form so aged-out
+        // ring-buffer slots stay zeroed: `x` is the forwarded copy of `o`,
+        // and `self` is forwarded in place in the `else` branch above.
+        for i in 0..merged.totals.len() {
+            merged.totals[i] = AccElem {
+                total: self.totals[i].total.wrapping_add(x.totals[i].total),
+                n: self.totals[i].n.wrapping_add(x.totals[i].n),
+                size: self.totals[i].size.wrapping_add(x.totals[i].size),
+            }
+        }
+        merged
+    }
+
+    pub fn add(&mut self, t: &Duration) {
+        let sec = SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default().as_secs();
+        self.forward_to(sec);
+        let win_idx = sec % 60;
+        self.totals[win_idx as usize].add(t);
+        self.last_sec = sec;
+    }
+
+    pub fn add_all(&mut self, sec: u64, a: &AccElem) {
+        self.forward_to(sec);
+        let win_idx = sec % 60;
+        self.totals[win_idx as usize].merge(a);
+        self.last_sec = sec;
+    }
+
+    pub fn get_total(&mut self) -> AccElem {
+        let mut res = AccElem::default();
+        let sec = SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default().as_secs();
+        self.forward_to(sec);
+        for elem in self.totals.iter() {
+            res.merge(elem);
+        }
+        res
+    }
+
+    pub fn forward_to(&mut self, t: u64) {
+        if self.last_sec >= t {
+            return;
+        }
+        if t - self.last_sec >= 60 {
+            self.totals = vec![AccElem::default(); 60];
+            self.last_sec = t;
+            return;
+        }
+        while self.last_sec != t {
+            let idx = (self.last_sec + 1) % 60;
+            self.totals[idx as usize] = AccElem::default();
+            self.last_sec += 1;
+        }
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+
+    #[test]
+    fn test_acc_elem_add_multiple_durations() {
+        let mut elem = AccElem::default();
+
+        elem.add(&Duration::from_secs(3));
+        elem.add(&Duration::from_secs(7));
+        elem.add(&Duration::from_secs(2));
+
+        assert_eq!(elem.total, 12);
+        assert_eq!(elem.n, 3);
+        assert_eq!(elem.size, 0);
+    }
+
+    #[test]
+    fn test_acc_elem_add_subsecond_duration() {
+        let mut elem = AccElem::default();
+        // Duration less than 1 second should be truncated to 0
+        let duration = Duration::from_millis(500);
+
+        elem.add(&duration);
+
+        assert_eq!(elem.total, 0); // as_secs() truncates subsecond values
+        assert_eq!(elem.n, 1);
+    }
+
+    #[test]
+    fn test_acc_elem_merge_with_data() {
+        let mut elem1 = AccElem {
+            total: 10,
+            size: 100,
+            n: 2,
+        };
+        let elem2 = AccElem {
+            total: 15,
+            size: 200,
+            n: 3,
+        };
+
+        elem1.merge(&elem2);
+
+        assert_eq!(elem1.total, 25);
+        assert_eq!(elem1.size, 300);
+        assert_eq!(elem1.n, 5);
+    }
+
+    #[test]
+    fn test_acc_elem_avg_zero_count() {
+        let elem = AccElem {
+            total: 10,
+            size: 0,
+            n: 0,
+        };
+
+        let avg = elem.avg();
+        assert_eq!(avg, Duration::from_secs(0));
+    }
+
+    #[test]
+    fn test_acc_elem_avg_rounding() {
+        let elem = AccElem {
+            total: 10,
+            size: 0,
+            n: 3,
+        };
+
+        let avg = elem.avg();
+        assert_eq!(avg, Duration::from_secs(3)); // 10 / 3 = 3 (integer division)
+    }
+
+    #[test]
+    fn test_last_minute_latency_forward_to_past_time() {
+        let mut latency = LastMinuteLatency {
+            last_sec: 100,
+            ..Default::default()
+        };
+
+        // Add some data to verify it's not cleared
+        latency.totals[0].total = 10;
+        latency.totals[0].n = 1;
+
+        latency.forward_to(50); // Past time
+
+        assert_eq!(latency.last_sec, 100); // Should not change
+        assert_eq!(latency.totals[0].total, 10); // Data should remain
+        assert_eq!(latency.totals[0].n, 1);
+    }
+
+    #[test]
+    fn test_last_minute_latency_forward_to_large_gap() {
+        let mut latency = LastMinuteLatency {
+            last_sec: 100,
+            ..Default::default()
+        };
+
+        // Add some data to verify it's cleared
+        latency.totals[0].total = 10;
+        latency.totals[0].n = 1;
+
+        latency.forward_to(200); // Gap >= 60 seconds
+
+        assert_eq!(latency.last_sec, 200); // last_sec should be updated to target time
+
+        // All data should be cleared
+        for elem in &latency.totals {
+            assert_eq!(elem.total, 0);
+            assert_eq!(elem.size, 0);
+            assert_eq!(elem.n, 0);
+        }
+    }
+
+    #[test]
+    fn test_last_minute_latency_forward_to_small_gap() {
+        let mut latency = LastMinuteLatency {
+            last_sec: 100,
+            ..Default::default()
+        };
+
+        // Add data at specific indices
+        latency.totals[41].total = 10; // (100 + 1) % 60 = 41
+        latency.totals[42].total = 20; // (100 + 2) % 60 = 42
+
+        latency.forward_to(102); // Forward by 2 seconds
+
+        assert_eq!(latency.last_sec, 102);
+
+        // The slots that were advanced should be cleared
+        assert_eq!(latency.totals[41].total, 0); // Cleared during forward
+        assert_eq!(latency.totals[42].total, 0); // Cleared during forward
+    }
+
+    #[test]
+    fn test_last_minute_latency_add_all_multiple() {
+        let mut latency = LastMinuteLatency::default();
+
+        let acc_elem1 = AccElem {
+            total: 10,
+            size: 50,
+            n: 2,
+        };
+        let acc_elem2 = AccElem {
+            total: 20,
+            size: 100,
+            n: 4,
+        };
+
+        latency.add_all(1000, &acc_elem1);
+        latency.add_all(1000, &acc_elem2); // Same second
+
+        let idx = 1000 % 60;
+        assert_eq!(latency.totals[idx as usize].total, 30); // 10 + 20
+        assert_eq!(latency.totals[idx as usize].size, 150); // 50 + 100
+        assert_eq!(latency.totals[idx as usize].n, 6); // 2 + 4
+    }
+
+    #[test]
+    fn test_last_minute_latency_merge_different_times() {
+        let mut latency1 = LastMinuteLatency::default();
+        let mut latency2 = LastMinuteLatency::default();
+
+        latency1.last_sec = 1000;
+        latency2.last_sec = 1010; // 10 seconds later
+
+        // Add data to both
+        latency1.totals[0].total = 10;
+        latency2.totals[0].total = 20;
+
+        let merged = latency1.merge(&latency2);
+
+        assert_eq!(merged.last_sec, 1010); // Should use the later time
+        assert_eq!(merged.totals[0].total, 30);
+    }
+
+    #[test]
+    fn test_last_minute_latency_merge_ages_out_stale_slots_self_newer() {
+        // self.last_sec > o.last_sec branch: `o` is forwarded to self.last_sec,
+        // which zeroes the ring-buffer slots for seconds 1001..=1010, i.e.
+        // indices 41..=50. Data parked in one of those slots is stale and must
+        // be excluded from the merged result.
+        let mut newer = LastMinuteLatency::default();
+        let mut older = LastMinuteLatency::default();
+
+        newer.last_sec = 1010;
+        older.last_sec = 1000;
+
+        // Stale slot: second 1005 -> index 45, cleared by forward_to(1010).
+        let stale_idx = (1005 % 60) as usize;
+        older.totals[stale_idx].total = 111;
+        older.totals[stale_idx].n = 5;
+        older.totals[stale_idx].size = 999;
+
+        // In-window slot: older's own last_sec (1000 -> index 40) is kept.
+        let kept_idx = (1000 % 60) as usize;
+        older.totals[kept_idx].total = 3;
+        older.totals[kept_idx].n = 1;
+        older.totals[kept_idx].size = 30;
+
+        // newer's current data (1010 -> index 50) must survive.
+        let newer_idx = (1010 % 60) as usize;
+        newer.totals[newer_idx].total = 7;
+        newer.totals[newer_idx].n = 1;
+        newer.totals[newer_idx].size = 70;
+
+        let merged = newer.merge(&older);
+
+        assert_eq!(merged.last_sec, 1010);
+        // The stale older slot is aged out -> excluded from the sum.
+        assert_eq!(merged.totals[stale_idx].total, 0);
+        assert_eq!(merged.totals[stale_idx].n, 0);
+        assert_eq!(merged.totals[stale_idx].size, 0);
+        // In-window older data is retained.
+        assert_eq!(merged.totals[kept_idx].total, 3);
+        assert_eq!(merged.totals[kept_idx].n, 1);
+        // newer data is retained.
+        assert_eq!(merged.totals[newer_idx].total, 7);
+    }
+
+    #[test]
+    fn test_last_minute_latency_merge_ages_out_of_window_self_newer() {
+        // self.last_sec > o.last_sec with a full-window gap (>= 60s): all of
+        // `o` is aged out and only `self`'s data remains.
+        let mut newer = LastMinuteLatency::default();
+        let mut older = LastMinuteLatency::default();
+
+        newer.last_sec = 1070;
+        older.last_sec = 1000; // gap of 70 >= 60 -> all of older is aged out
+
+        // 1070 % 60 == 1000 % 60 == 10, so both write the same slot; the fix
+        // must yield exactly newer's value, not newer + stale older.
+        let idx = (1070 % 60) as usize;
+        older.totals[idx].total = 111;
+        older.totals[idx].n = 5;
+        older.totals[idx].size = 999;
+        newer.totals[idx].total = 7;
+        newer.totals[idx].n = 1;
+        newer.totals[idx].size = 70;
+
+        let merged = newer.merge(&older);
+
+        assert_eq!(merged.last_sec, 1070);
+        assert_eq!(merged.totals[idx].total, 7);
+        assert_eq!(merged.totals[idx].n, 1);
+        assert_eq!(merged.totals[idx].size, 70);
+    }
+
+    #[test]
+    fn test_last_minute_latency_merge_ages_out_of_window_o_newer() {
+        // Mirror of the above for the else branch: `self` is older and is
+        // forwarded to o.last_sec, aging out self's out-of-window data.
+        let mut older = LastMinuteLatency::default();
+        let mut newer = LastMinuteLatency::default();
+
+        older.last_sec = 1000;
+        newer.last_sec = 1070; // gap of 70 >= 60 -> all of older (self) is aged out
+
+        let idx = (1070 % 60) as usize; // 1000 % 60 == 1070 % 60 == 10
+        older.totals[idx].total = 111;
+        older.totals[idx].n = 5;
+        older.totals[idx].size = 999;
+        newer.totals[idx].total = 7;
+        newer.totals[idx].n = 1;
+        newer.totals[idx].size = 70;
+
+        let merged = older.merge(&newer);
+
+        assert_eq!(merged.last_sec, 1070);
+        // self's stale data aged out; only newer's data remains.
+        assert_eq!(merged.totals[idx].total, 7);
+        assert_eq!(merged.totals[idx].n, 1);
+        assert_eq!(merged.totals[idx].size, 70);
+    }
+
+    #[test]
+    fn test_last_minute_latency_window_wraparound() {
+        let mut latency = LastMinuteLatency::default();
+
+        // Test that indices wrap around correctly
+        for sec in 0..120 {
+            // Test for 2 minutes
+            let acc_elem = AccElem {
+                total: sec,
+                size: 0,
+                n: 1,
+            };
+            latency.add_all(sec, &acc_elem);
+
+            let expected_idx = sec % 60;
+            assert_eq!(latency.totals[expected_idx as usize].total, sec);
+        }
+    }
+
+    #[test]
+    fn test_edge_case_max_values() {
+        let mut elem = AccElem {
+            total: u64::MAX - 50,
+            size: u64::MAX - 50,
+            n: u64::MAX - 50,
+        };
+
+        let other = AccElem {
+            total: 100,
+            size: 100,
+            n: 100,
+        };
+
+        // This should not panic due to overflow, values will wrap around
+        elem.merge(&other);
+
+        // Values should wrap around due to overflow (wrapping_add behavior)
+        assert_eq!(elem.total, 49); // (u64::MAX - 50) + 100 wraps to 49
+        assert_eq!(elem.size, 49);
+        assert_eq!(elem.n, 49);
+    }
+
+    #[test]
+    fn test_forward_to_boundary_conditions() {
+        let mut latency = LastMinuteLatency {
+            last_sec: 59,
+            ..Default::default()
+        };
+
+        // Add data at the last slot
+        latency.totals[59].total = 100;
+        latency.totals[59].n = 1;
+
+        // Forward exactly 60 seconds (boundary case)
+        latency.forward_to(119);
+
+        // All data should be cleared
+        for elem in &latency.totals {
+            assert_eq!(elem.total, 0);
+            assert_eq!(elem.n, 0);
+        }
+    }
+
+    #[test]
+    fn test_get_total_with_data() {
+        let mut latency = LastMinuteLatency::default();
+
+        // Set a recent timestamp to avoid forward_to clearing data
+        let current_time = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("Time went backwards")
+            .as_secs();
+        latency.last_sec = current_time;
+
+        // Add data to multiple slots
+        latency.totals[0] = AccElem {
+            total: 10,
+            size: 100,
+            n: 1,
+        };
+        latency.totals[1] = AccElem {
+            total: 20,
+            size: 200,
+            n: 2,
+        };
+        latency.totals[59] = AccElem {
+            total: 30,
+            size: 300,
+            n: 3,
+        };
+
+        let total = latency.get_total();
+
+        assert_eq!(total.total, 60);
+        assert_eq!(total.size, 600);
+        assert_eq!(total.n, 6);
+    }
+}

crates/scanner-contracts/src/lib.rs

@@ -0,0 +1,19 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+pub mod init_time;
+pub mod last_minute;
+pub mod metrics;
+
+pub use init_time::{GLOBAL_INIT_TIME, get_global_init_time, set_global_init_time_now};