Struct IdGenerator 

pub struct IdGenerator { /* private fields */ }

Generates TrackingIds according to a fixed policy.

Choosing an entropy width

IDs are random, so duplicates follow the birthday bound: with n IDs drawn from a space of N = 2^bits, the chance that at least two collide is approximately 1 - e^(-n²/2N).

Entropy	Body	1% collision risk at	50% collision risk at
32 bits	8 hex chars	~9,000 IDs	~77,000 IDs
48 bits	12 hex chars	~2.4 million	~20 million
64 bits	16 hex chars	~610 million	~5.1 billion

The default is 32 bits, which reproduces the familiar PKG-9ED9285C shape. For production systems that will ever issue more than a few thousand IDs, configure 64 bits. Widening later is a data migration; choosing it now is a one-line change.

Randomness alone cannot guarantee uniqueness at any width. A durable system should still enforce a unique constraint at the storage layer and retry on conflict.

Examples

use smart_package_tracker::{Checksum, IdGenerator};

let generator = IdGenerator::builder()
    .prefix("PKG")
    .entropy_bits(64)
    .checksum(Checksum::Iso7064Mod37_36)
    .build()?;

let id = generator.generate()?;
assert!(id.as_str().starts_with("PKG-"));
assert_eq!(id.body().len(), 17); // 16 hex characters + 1 check character
generator.validate(&id)?;

Implementations

impl IdGenerator

pub fn builder() -> IdGeneratorBuilder

Start building a generator with a custom policy.

pub fn prefix(&self) -> &str

The prefix placed before the separator.

pub fn entropy_bits(&self) -> u16

Bits of randomness in each generated ID.

pub fn checksum(&self) -> Checksum

The configured check-character scheme.

pub fn entropy_bytes(&self) -> usize

Number of random bytes needed per ID.

pub fn generate(&self) -> Result<TrackingId>

Available on crate feature os-rng only.

Generate an ID using the operating system’s cryptographic RNG.

Requires the os-rng feature (enabled by default). Without it, use generate_from_entropy.

Errors

Returns Error::Entropy if the OS entropy source is unavailable. This crate never silently falls back to a weaker source.

pub fn generate_from_entropy(&self, bytes: &[u8]) -> Result<TrackingId>

Generate an ID from caller-supplied entropy.

Useful for deterministic tests, for reproducing an ID from stored bytes, or when the entropy comes from an HSM or a database sequence rather than the OS.

Errors

Returns Error::InsufficientEntropy if fewer than entropy_bytes bytes are supplied. Extra bytes are ignored.

pub fn validate(&self, id: &TrackingId) -> Result<()>

Check that id was produced by this generator’s policy.

Verifies the prefix, the body length, and the check character. Note that this cannot prove provenance — it only rules out IDs that this policy could never have produced.

Errors

Returns Error::IdPolicyMismatch describing the first failure.

Trait Implementations

impl Clone for IdGenerator

fn clone(&self) -> IdGenerator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IdGenerator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for IdGenerator

fn default() -> Self

PKG- + 32 bits of entropy, no check character — the PKG-9ED9285C format. See the type-level docs before using this in production.

impl Eq for IdGenerator

impl PartialEq for IdGenerator

fn eq(&self, other: &IdGenerator) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for IdGenerator