Struct ShardableUuid

pub struct ShardableUuid(/* private fields */);

Expand description

VPR’s canonical UUID representation (32 lowercase hex characters, no hyphens).

This wrapper type guarantees that once constructed, the contained UUID is in VPR’s canonical format. It provides type safety for UUID operations and ensures consistent path derivation across the system.

§Why no hyphens?

The hyphen-free format is specifically chosen to support the sharding scheme for patient directories. The sharded_dir method uses simple string slicing to extract shard prefixes:

550e8400e29b41d4a716446655440000
^^^^
||└─ shard level 2: chars[2..4] = "0e"
└──── shard level 1: chars[0..2] = "55"

This creates paths like /patient_data/clinical/55/0e/550e8400e29b41d4a716446655440000.

If hyphens were present, we’d need to strip them before sharding or handle them in the slicing logic, adding unnecessary complexity. The hyphen-free format gives us a clean, predictable character stream that’s trivial to slice and use directly as filesystem paths.

Note: Other identifiers that don’t use sharding (such as letter IDs) may use RFC 4122 format with hyphens for better readability.

§When to use this type

Use this wrapper whenever you are:

Accepting a UUID string from outside the core (CLI input, API request, etc), or
Deriving a sharded storage path for a patient.
Generating new patient identifiers.

Once you have a ShardableUuid, you can safely assume the internal UUID is valid and in canonical form.

§Construction

ShardableUuid::new generates a new canonical UUID (for new patient records).
ShardableUuid::parse validates an externally supplied identifier.

§Errors

ShardableUuid::parse returns [UuidError::InvalidInput] if the input is not already canonical.

§Display format

When displayed or converted to string, ShardableUuid always produces the canonical 32-character lowercase hex format without hyphens.

Implementations§

§

impl ShardableUuid

pub fn new() -> ShardableUuid

Generates a new UUID in VPR’s canonical form.

This is suitable for allocating a fresh identifier during patient creation. The generated UUID is cryptographically secure and follows RFC 4122 version 4.

§Returns

Returns a newly generated canonical UUID wrapped in ShardableUuid.

pub fn parse(input: &str) -> Result<ShardableUuid, UuidError>

Validates and parses a UUID string that must already be in VPR’s canonical form.

This does not normalise other common UUID forms (for example, hyphenated or uppercase). Callers must provide the canonical representation. This strict validation ensures consistency and prevents issues with different UUID representations.

§Arguments

input - UUID string to validate and wrap. Must be exactly 32 lowercase hex characters.

§Returns

Returns a validated ShardableUuid on success.

§Errors

Returns [UuidError::InvalidInput] if input is not in canonical form.

pub fn from_uuid(uuid: Uuid) -> ShardableUuid

Creates a ShardableUuid from an existing uuid::Uuid.

This constructor wraps a Uuid that is already known to be valid, avoiding the overhead of string parsing and validation. Use this when converting internal Uuid values that are already validated.