Crate domain_key

Expand description

§domain-key 🚀

High-performance, type-safe, domain-agnostic key system for Rust applications.

domain-key provides a flexible and efficient foundation for creating domain-specific keys with compile-time type safety, runtime validation, and extensive performance optimizations. This library focuses on zero-cost abstractions and maximum performance through feature-based optimization profiles.

§✨ Key Features

🔒 Type Safety: Different key types cannot be mixed at compile time
🏎️ High Performance: Up to 75% performance improvements through advanced optimizations
🎯 Domain Agnostic: No built-in assumptions about specific domains
💾 Memory Efficient: Smart string handling with stack allocation for short keys
🛡️ DoS Resistant: Optional protection against HashDoS attacks
🔧 Extensible: Easy to add new domains and validation rules
📦 Zero-Cost Abstractions: No runtime overhead for type separation

§🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                          │
│  Business Logic  │  Domain Models  │  API Endpoints            │
└─────────────────┬───────────────────┬───────────────────────────┘
                  │                   │
                  ▼                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                   TYPE SAFETY LAYER                            │
│  Key<UserDomain> │ Key<SessionDomain> │ Key<CacheDomain>        │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                 PERFORMANCE LAYER                              │
│  Stack Alloc │ Caching │ Specialized Ops │ Thread-Local        │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                  STORAGE LAYER                                 │
│  SmartString + Cached Hash + Cached Length + Optimizations     │
└─────────────────────────────────────────────────────────────────┘

§🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
domain-key = { version = "0.1", features = ["fast"] }

Define a domain and create keys:

use domain_key::{Key, KeyDomain};

// 1. Define your domain
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
struct UserDomain;

impl KeyDomain for UserDomain {
    const DOMAIN_NAME: &'static str = "user";
    const MAX_LENGTH: usize = 32;
    const TYPICALLY_SHORT: bool = true; // Optimization hint
}

// 2. Create a type alias
type UserKey = Key<UserDomain>;

// 3. Use it!
let user_key = UserKey::new("john_doe")?;
let composed_key = UserKey::from_parts(&["user", "123", "profile"], "_")?;

println!("Domain: {}", user_key.domain());
println!("Length: {}", user_key.len()); // O(1) with optimizations
println!("Key: {}", user_key.as_str());

§🏎️ Performance Features

§Feature-Based Optimization Profiles

# Maximum performance (modern CPUs with AES-NI)
features = ["fast"]

# DoS protection + good performance
features = ["secure"]

# Cryptographic security
features = ["crypto"]

# All optimizations enabled
features = ["fast", "std", "serde"]

§Build for Maximum Performance

# Enable CPU-specific optimizations
RUSTFLAGS="-C target-cpu=native" cargo build --release --features="fast"

§Performance Improvements

Operation	Standard	Optimized	Improvement
Key Creation (short)	100%	128%	28% faster
String Operations	100%	175%	75% faster
Hash Operations	100%	140%	40% faster
Length Access	O(n)	O(1)	Constant time

§📖 Advanced Examples

§Performance-Optimized Usage

use domain_key::{Key, KeyDomain};

#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
struct OptimizedDomain;

impl KeyDomain for OptimizedDomain {
    const DOMAIN_NAME: &'static str = "optimized";
    const EXPECTED_LENGTH: usize = 16; // Optimization hint
    const TYPICALLY_SHORT: bool = true; // Enable stack allocation
}

type OptimizedKey = Key<OptimizedDomain>;

// Basic optimized key creation
let user_key = OptimizedKey::new("user_12345")?;
let session_key = OptimizedKey::new("session_abc123")?;

// Batch operations with from_parts
let user_ids = vec![1, 2, 3, 4, 5];
let user_keys: Result<Vec<_>, _> = user_ids.iter()
    .map(|&id| OptimizedKey::from_parts(&["user", &id.to_string()], "_"))
    .collect();
let user_keys = user_keys?;

// Optimized operations for repeated use
let key = OptimizedKey::new("user_profile_settings_theme")?;
let parts: Vec<&str> = key.split('_').collect(); // Uses optimizations when available

§🔧 Feature Flags Reference

§Hash Algorithm Features (choose one for best results)

fast - GxHash (40% faster, requires modern CPU with AES-NI)
secure - AHash (DoS protection, balanced performance)
crypto - Blake3 (cryptographically secure)
Default - Standard hasher (good compatibility)

§Core Features

std - Standard library support (enabled by default)
serde - Serialization support (enabled by default)
no_std - No standard library (disables std-dependent features)

§🛡️ Security Considerations

domain-key provides multiple levels of security depending on your needs:

DoS Protection: Use secure feature for AHash with DoS resistance
Cryptographic Security: Use crypto feature for Blake3 cryptographic hashing
Input Validation: Comprehensive validation pipeline with custom rules
Type Safety: Compile-time prevention of key type mixing
Memory Safety: Rust’s ownership system + additional optimizations

Re-exports§

pub use domain::domain_info;
pub use domain::DefaultDomain;
pub use domain::IdentifierDomain;
pub use domain::KeyDomain;
pub use domain::PathDomain;
pub use error::ErrorCategory;
pub use error::KeyParseError;
pub use key::Key;
pub use key::KeyValidationInfo;
pub use key::SplitCache;
pub use key::SplitIterator;
pub use validation::IntoKey;
pub use features::hash_algorithm;
pub use features::performance_info;
pub use features::PerformanceInfo;
pub use utils::new_split_cache;
pub use key::DEFAULT_MAX_KEY_LENGTH;
pub use validation::*;

Modules§

domain: Domain trait and related functionality for domain-key
error: Error types and error handling for domain-key
features: Feature detection and runtime performance information for domain-key
key: Core Key implementation for domain-key
prelude: Prelude module for convenient imports
utils: Utility functions and helper types for domain-key
validation: Validation utilities and helper traits for domain-key

Macros§

batch_keys: Create multiple keys at once with error handling
define_domain: Define a key domain with minimal boilerplate
key_type: Create a key type alias
static_key: Create a compile-time validated static key
test_domain: Generate test cases for key domains

Type Aliases§

KeyResult: Result type for key operations

Crate domain_keyCopy item path