Crate product_os_random 

Product OS Random

A comprehensive random number generation library providing cryptographically secure RNGs, random text/number generators, and word/name generators. Supports no_std environments.

Features

This crate provides multiple feature flags to control functionality and dependencies:

Core Features

• default - Basic random generation with StdRng and getrandom support
• core - Full standard library support with StdRng, ThreadRng, and OsRng
• send_only - Send-safe RNG variants only
• constrained - Minimal allocation-only mode (no default RNG, user must provide)
• custom - Custom RNG support with spin locks for no_std environments
• custom_send_only - Custom Send-safe RNG support

Dataset Features

• words - Enable random word generation
• nouns - Enable random noun generation
• adjectives - Enable random adjective generation
• names - Enable random full name generation
• first_names - Enable random first name generation (requires inflections)
• last_names - Enable random last name generation (requires inflections)

Security Considerations

Cryptographic vs Non-Cryptographic RNGs

• CryptoRNG: Use for security-sensitive operations (passwords, keys, tokens). Implements CryptoRng marker trait indicating cryptographic security.
• RNG: General-purpose random generation. Some variants are cryptographically secure (like OsRng), others are not (like seeded StdRng).

Thread Safety

• RNG::Thread uses ThreadRng which is thread-local
• Custom RNG wrappers use Arc<Mutex<>> for thread-safe access
• All RNG variants implement Clone for easy distribution

Usage Examples

Convenience Functions (Recommended)

The simplest way to generate random data:

let password = product_os_random::random_password(16);
let code = product_os_random::random_alphanumeric(10);
let port = product_os_random::random_usize(1025, 65535);
let bytes = product_os_random::random_bytes(32);
let key = product_os_random::generate_random_key(32);

Stateful Generator with Custom RNG

use product_os_random::{RandomGenerator, RandomGeneratorTemplate, RNG};
use rand::SeedableRng;

// Create a seeded RNG for reproducible results
let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
let mut gen = RandomGenerator::new(Some(rng));

// Generate random data
let bytes = gen.get_random_bytes(32);
let number = gen.get_random_usize(1, 100);
let alphanumeric = gen.get_random_alphanumeric(10);

Cryptographic Key Generation

use product_os_random::RandomGenerator;

// Generate a cryptographic key
let key = RandomGenerator::generate_simple_key_one_time(32);
assert_eq!(key.len(), 32);

Using Feature-Gated Name Generation

use product_os_random::RandomGenerator;

let username = RandomGenerator::get_simple_random_username_one_time(
    Some(2),
    Some(4),
    Some("_".to_string())
);

let email = RandomGenerator::get_simple_random_email_one_time(
    Some(2),
    Some(3),
    None,
    vec!["example.com".to_string()]
);

Custom RNG Implementation

use product_os_random::{CustomRng, RNG};
use rand::SeedableRng;

let seed_rng = rand::rngs::StdRng::seed_from_u64(42);
let custom = CustomRng::new(seed_rng);
let rng = RNG::Custom(custom);

Performance Characteristics

• String Generation: Pre-allocates with String::with_capacity for efficiency
• Large Datasets: Names datasets are large (~400K lines total), consider binary size
• Lock Contention: Custom RNGs use mutexes, may have contention under high concurrency
• no_std Support: Minimal overhead when used without standard library features

Structs

Error

Error type of random number generators

RandomGenerator

High-level random data generator with stateful RNG.

Enums

CryptoRNG

Unified cryptographically secure RNG enum.

RNG

Unified RNG enum supporting multiple random number generator backends.

Traits

CryptoRng

A marker trait used to indicate that an RngCore or BlockRngCore implementation is supposed to be cryptographically secure.

RandomGeneratorTemplate

Template trait defining instance methods for random data generation.

Rng

An automatically-implemented extension trait on RngCore providing high-level generic methods for sampling values and other convenience methods.

RngCore

The core of a random number generator.

SeedableRng

A random number generator that can be explicitly seeded.