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, that the entropy characters are uppercase hexadecimal, 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