Add SystemClock (#8239)

This PR adds a `SystemClock` trait for abstracting away the system
clock.

This allows us to swap out the real system clock with a
`FakeSystemClock` in the tests, thus allowing the fake passage of time.

We're using this in `Telemetry` to better mock the clock for testing
purposes.

Release Notes:

- N/A

crates/clock/Cargo.toml

@@ -9,5 +9,10 @@ license = "GPL-3.0-or-later"
 path = "src/clock.rs"
 doctest = false
 
+[features]
+test-support = ["dep:parking_lot"]
+
 [dependencies]
+chrono.workspace = true
+parking_lot = { workspace = true, optional = true }
 smallvec.workspace = true

crates/clock/src/clock.rs

@@ -1,13 +1,17 @@
+mod system_clock;
+
 use smallvec::SmallVec;
 use std::{
     cmp::{self, Ordering},
     fmt, iter,
 };
 
-/// A unique identifier for each distributed node
+pub use system_clock::*;
+
+/// A unique identifier for each distributed node.
 pub type ReplicaId = u16;
 
-/// A [Lamport sequence number](https://en.wikipedia.org/wiki/Lamport_timestamp),
+/// A [Lamport sequence number](https://en.wikipedia.org/wiki/Lamport_timestamp).
 pub type Seq = u32;
 
 /// A [Lamport timestamp](https://en.wikipedia.org/wiki/Lamport_timestamp),
@@ -18,7 +22,7 @@ pub struct Lamport {
     pub value: Seq,
 }
 
-/// A [vector clock](https://en.wikipedia.org/wiki/Vector_clock)
+/// A [vector clock](https://en.wikipedia.org/wiki/Vector_clock).
 #[derive(Clone, Default, Hash, Eq, PartialEq)]
 pub struct Global(SmallVec<[u32; 8]>);
 

crates/clock/src/system_clock.rs

@@ -0,0 +1,59 @@
+use chrono::{DateTime, Utc};
+
+pub trait SystemClock: Send + Sync {
+    /// Returns the current date and time in UTC.
+    fn utc_now(&self) -> DateTime<Utc>;
+}
+
+pub struct RealSystemClock;
+
+impl SystemClock for RealSystemClock {
+    fn utc_now(&self) -> DateTime<Utc> {
+        Utc::now()
+    }
+}
+
+#[cfg(any(test, feature = "test-support"))]
+pub struct FakeSystemClockState {
+    now: DateTime<Utc>,
+}
+
+#[cfg(any(test, feature = "test-support"))]
+pub struct FakeSystemClock {
+    // Use an unfair lock to ensure tests are deterministic.
+    state: parking_lot::Mutex<FakeSystemClockState>,
+}
+
+#[cfg(any(test, feature = "test-support"))]
+impl Default for FakeSystemClock {
+    fn default() -> Self {
+        Self::new(Utc::now())
+    }
+}
+
+#[cfg(any(test, feature = "test-support"))]
+impl FakeSystemClock {
+    pub fn new(now: DateTime<Utc>) -> Self {
+        let state = FakeSystemClockState { now };
+
+        Self {
+            state: parking_lot::Mutex::new(state),
+        }
+    }
+
+    pub fn set_now(&self, now: DateTime<Utc>) {
+        self.state.lock().now = now;
+    }
+
+    /// Advances the [`FakeSystemClock`] by the specified [`Duration`](chrono::Duration).
+    pub fn advance(&self, duration: chrono::Duration) {
+        self.state.lock().now += duration;
+    }
+}
+
+#[cfg(any(test, feature = "test-support"))]
+impl SystemClock for FakeSystemClock {
+    fn utc_now(&self) -> DateTime<Utc> {
+        self.state.lock().now
+    }
+}