Module generic_id

adaptive_pipeline_domain::value_objects

Module generic_id 

Source
Expand description

§Generic ID Value Object

This module provides a generic, type-safe ID value object system for the adaptive pipeline system. It uses ULID (Universally Unique Lexicographically Sortable Identifier) with phantom types to create type-safe, category-specific identifiers.

§Overview

The generic ID system provides:

  • Type Safety: Compile-time enforcement of ID categories
  • ULID-Based: Uses ULID for sortable, unique identifiers
  • Category Validation: Category-specific validation rules
  • Zero-Cost Abstractions: Phantom types with no runtime overhead
  • Serialization: Support for persistence and transmission

§Architecture

The ID system follows Domain-Driven Design principles:

  • Value Object: Immutable value object with equality semantics
  • Type Safety: Phantom types prevent ID category mixing at compile time
  • Rich Domain Model: Encapsulates ID-related business logic
  • Validation: Comprehensive validation of ID formats and constraints

§Key Features

§ULID Properties

  • Sortable: Lexicographically sortable by creation time
  • Unique: Globally unique identifiers
  • Compact: 26-character string representation
  • URL-Safe: Safe for use in URLs and file names
  • Case-Insensitive: Base32 encoding is case-insensitive

§Type Safety

  • Compile-Time Checking: Prevent mixing different ID types
  • Category Enforcement: Each ID category has specific validation
  • Zero Runtime Cost: Phantom types have no runtime overhead
  • Rich Type System: Leverage Rust’s type system for correctness

§Validation and Constraints

  • Format Validation: Validate ULID format and structure
  • Category Validation: Category-specific validation rules
  • Nil Handling: Configurable nil value handling per category
  • Custom Constraints: Support for custom validation logic

§Usage Examples

§Basic ID Creation

§ID Parsing and Validation

§Type Safety Demonstration

§Custom ID Categories

§ID Collections and Sorting

§Serialization and Deserialization

§ID Categories

§Built-in Categories

  • PipelineIdCategory: For pipeline instances

    • Validation: Standard ULID validation
    • Use case: Identify pipeline execution instances

  • FileIdCategory: For file references

    • Validation: Standard ULID validation
    • Use case: Identify files in the system

  • UserIdCategory: For user identification

    • Validation: Standard ULID validation
    • Use case: Identify users and sessions

  • StageIdCategory: For pipeline stages

    • Validation: Standard ULID validation
    • Use case: Identify individual pipeline stages

§Custom Categories

Create custom ID categories by implementing the IdCategory trait:

  • Category Name: Unique identifier for the category
  • Validation Logic: Custom validation rules
  • Nil Handling: Configure whether nil values are allowed

§ULID Properties

§Format

  • Length: 26 characters
  • Encoding: Base32 (Crockford’s Base32)
  • Case: Case-insensitive
  • Characters: 0-9, A-Z (excluding I, L, O, U)

§Structure

01AN4Z07BY      79KA1307SR9X4MV3
|----------|    |----------------|
 Timestamp          Randomness
   48bits             80bits

§Properties

  • Sortable: Lexicographically sortable by timestamp
  • Unique: 80 bits of randomness ensure uniqueness
  • Compact: More compact than UUID strings
  • URL-Safe: Safe for use in URLs without encoding

§Validation Rules

§Format Validation

  • Length: Must be exactly 26 characters
  • Characters: Must contain only valid Base32 characters
  • Structure: Must follow ULID structure

§Category Validation

  • Nil Handling: Check if nil values are allowed
  • Custom Rules: Apply category-specific validation
  • Timestamp Validation: Validate timestamp ranges

§Security Considerations

  • Randomness: Ensure sufficient randomness
  • Predictability: Prevent ID prediction attacks
  • Information Leakage: Minimize information leakage

§Error Handling

§ID Errors

  • Invalid Format: ID format is invalid
  • Parse Error: Cannot parse ID from string
  • Validation Error: ID fails category validation
  • Nil Error: Nil ID where not allowed

§Category Errors

  • Unknown Category: Category is not recognized
  • Validation Failure: Category-specific validation failed
  • Constraint Violation: ID violates category constraints

§Performance Considerations

§Memory Usage

  • Compact Storage: ULID is more compact than UUID
  • Zero-Cost Types: Phantom types have no runtime cost
  • Efficient Comparison: Fast comparison operations

§Generation Performance

  • Fast Generation: ULID generation is very fast
  • No Network: No network calls required
  • Thread-Safe: Safe for concurrent generation

§Parsing Performance

  • Fast Parsing: Efficient Base32 parsing
  • Validation: Fast validation algorithms
  • Caching: Cache validation results when appropriate

§Integration

The generic ID system integrates with:

  • Domain Entities: Identify domain entities uniquely
  • Database: Use as primary keys and foreign keys
  • API: Consistent ID format across APIs
  • Logging: Include IDs in logs for tracing

§Thread Safety

The generic ID system is thread-safe:

  • Immutable: IDs are immutable after creation
  • Safe Generation: ULID generation is thread-safe
  • Concurrent Access: Safe concurrent access to ID data

§Future Enhancements

Planned enhancements include:

  • ID Registry: Centralized ID category registry
  • Migration Support: Support for migrating between ID formats
  • Performance Optimization: Further performance optimizations
  • Enhanced Validation: More sophisticated validation rules

Modules§

generic_id_utils
Utility functions for working with generic IDs

Structs§

GenericId
Generic identifier value object for domain entities

Traits§

IdCategory
ID category trait for type-specific behavior