add deterministic_testing opt-in backend hidden behind cfg(test)

.cargo/config.toml

@@ -14,3 +14,5 @@ runner = 'node'
 
 [resolver]
 incompatible-rust-versions = "allow"
+[build]
+rustflags = ['--cfg', 'getrandom_backend="deterministic_testing"']

Cargo.toml

@@ -20,6 +20,11 @@ rustdoc-args = ["--cfg", "getrandom_backend=\"extern_impl\""]
 # use std to retrieve OS error descriptions
 std = []
 
+# Feature to enable deterministic testing -- has an MSRV of 1.85
+#
+# WARNING: This should only be enabled in dev-dependencies as it is for deterministic testing only.
+unsafe_deterministic_testing = ["dep:rand_core", "dep:chacha20"]
+
 # Optional backend: wasm_js
 #
 # This flag enables the wasm_js backend and uses it by default on wasm32 where
@@ -44,6 +49,11 @@ rand_core = { version = "0.10.0", optional = true }
 [target.'cfg(all(any(target_os = "linux", target_os = "android"), not(any(all(target_os = "linux", target_env = ""), getrandom_backend = "custom", getrandom_backend = "linux_raw", getrandom_backend = "rdrand", getrandom_backend = "rndr"))))'.dependencies]
 libc = { version = "0.2.154", default-features = false }
 
+# deterministic_testing
+[target.'cfg(getrandom_backend = "deterministic_testing")'.dependencies]
+chacha20 = { version = "0.10.0", features = ["rng"], optional = true }
+
+
 # apple-other
 [target.'cfg(any(target_os = "ios", target_os = "visionos", target_os = "watchos", target_os = "tvos"))'.dependencies]
 libc = { version = "0.2.154", default-features = false }
@@ -96,7 +106,7 @@ wasm-bindgen-test = "0.3"
 [lints.rust.unexpected_cfgs]
 level = "warn"
 check-cfg = [
-  'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "windows_legacy", "unsupported", "extern_impl"))',
+  'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "windows_legacy", "unsupported", "extern_impl", "deterministic_testing"))',
   'cfg(getrandom_msan)',
   'cfg(getrandom_test_linux_fallback)',
   'cfg(getrandom_test_linux_without_fallback)',

src/backends.rs

@@ -8,7 +8,10 @@
 //! regardless of what value it returns.
 
 cfg_if! {
-    if #[cfg(getrandom_backend = "custom")] {
+    if #[cfg(all(getrandom_backend = "deterministic_testing", feature = "unsafe_deterministic_testing"))] {
+        mod deterministic;
+        pub use deterministic::*;
+    } else if #[cfg(getrandom_backend = "custom")] {
         mod custom;
         pub use custom::*;
     } else if #[cfg(getrandom_backend = "linux_getrandom")] {

src/backends/deterministic.rs

@@ -0,0 +1,51 @@
+//! Deterministic testing backend — seeded ChaCha12 RNG, single-thread only.
+
+// This module is only compiled under `cfg(test)`, so `std` is always linked
+// even though the crate is `#![no_std]`.
+extern crate std;
+
+pub use crate::util::{inner_u32, inner_u64};
+
+use crate::Error;
+
+use chacha20::ChaCha12Rng;
+use core::mem::MaybeUninit;
+use rand_core::{Rng, SeedableRng};
+use std::sync::{Mutex, OnceLock};
+
+/// The RNG, initialised exactly once on first use.
+static RNG: OnceLock<Mutex<ChaCha12Rng>> = OnceLock::new();
+
+#[inline]
+pub fn fill_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
+    let rng = RNG.get_or_init(|| Mutex::new(ChaCha12Rng::from_seed([42u8; 32])));
+
+    let mut guard = rng.lock().unwrap();
+
+    // SAFETY: `fill_bytes` fully overwrites every byte of the slice, so
+    // treating uninitialized `MaybeUninit<u8>` as `u8` for the purpose of
+    // writing (never reading) is sound.
+    let dest_init = unsafe { dest.assume_init_mut() };
+    guard.fill_bytes(dest_init);
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_deterministic() {
+        let mut buf = [0u8; 32];
+        crate::fill(&mut buf).unwrap();
+        assert_eq!(
+            [
+                0x1b, 0x8c, 0x20, 0xcd, 0xe2, 0xdb, 0xb4, 0x3c, 0xd3, 0xc7, 0x9, 0xb2, 0x90, 0xac,
+                0x50, 0xdc, 0xd2, 0xbe, 0x2a, 0x87, 0xa3, 0xa2, 0x45, 0x44, 0xb5, 0xa5, 0x10, 0x9b,
+                0xc7, 0x6e, 0xa7, 0xfb,
+            ],
+            buf
+        );
+    }
+}