mod_rand/lib.rs
1//! # mod-rand
2//!
3//! Tiered random number generation for Rust. Zero dependencies. Pick
4//! the tier appropriate to your threat model.
5//!
6//! ## Tiers
7//!
8//! - **[`tier1`]**: Deterministic seedable PRNG (xoshiro256\*\*).
9//! For simulation, fixture data, non-security shuffling. Always
10//! available, works in `no_std`.
11//! - **[`tier2`]**: Process-unique seeds derived from PID + time +
12//! counter. For tempdir names, request IDs, log correlation. Fast
13//! enough for high-frequency use. Not cryptographic.
14//! - **[`tier3`]**: OS-backed cryptographic random. For tokens, keys,
15//! session IDs. Calls platform syscalls directly.
16//!
17//! ## Quick example
18//!
19//! ```
20//! use mod_rand::tier1::Xoshiro256;
21//!
22//! let mut rng = Xoshiro256::seed_from_u64(42);
23//! let n: u64 = rng.next_u64();
24//! ```
25//!
26//! ## Choosing a tier
27//!
28//! | Use case | Tier |
29//! |-----------------------------------|------|
30//! | Test fixtures, simulation | 1 |
31//! | Tempdir names, request IDs | 2 |
32//! | Auth tokens, session IDs, keys | 3 |
33//!
34//! ## Status
35//!
36//! `v0.1.0` is a placeholder release. Real implementation lands in
37//! `0.9.x`. See the [CHANGELOG](https://github.com/jamesgober/mod-rand/blob/main/CHANGELOG.md)
38//! for what's stable.
39
40#![cfg_attr(docsrs, feature(doc_cfg))]
41#![cfg_attr(not(feature = "std"), no_std)]
42#![warn(missing_docs)]
43#![warn(rust_2018_idioms)]
44
45pub mod tier1;
46
47#[cfg(feature = "tier2")]
48pub mod tier2;
49
50#[cfg(feature = "tier3")]
51pub mod tier3;