reinhardt-utils 0.1.0-alpha.11

Utility functions aggregator for Reinhardt
Documentation

reinhardt-utils

Common utilities and helper functions

Overview

Collection of utility functions and helpers used throughout the framework.

Includes date/time utilities, string manipulation, encoding/decoding, and other common operations.

Installation

Add reinhardt to your Cargo.toml:

[dependencies]
reinhardt = { version = "0.1.0-alpha.1", features = ["utils"] }

# Or use a preset:
# reinhardt = { version = "0.1.0-alpha.1", features = ["standard"] }  # Recommended
# reinhardt = { version = "0.1.0-alpha.1", features = ["full"] }      # All features

Then import utility features:

use reinhardt::utils::cache::{Cache, InMemoryCache};
use reinhardt::utils::logging::{Logger, LogLevel};
use reinhardt::utils::storage::{Storage, LocalStorage};
use reinhardt::utils::core::html::{escape, unescape};

Note: Utility features are included in the standard and full feature presets.

Features

Implemented ✓

HTML Utilities (html module)

  • HTML Escaping/Unescaping
    • escape(): Escapes HTML special characters (<, >, &, ", ')
    • unescape(): Unescapes HTML entities
    • conditional_escape(): Conditional escaping with autoescape flag support
    • escape_attr(): HTML attribute value escaping (handles newlines and tabs)
  • HTML Manipulation
    • strip_tags(): Removes HTML tags
    • strip_spaces_between_tags(): Removes whitespace between tags
    • truncate_html_words(): Truncates by word count while preserving HTML tags
    • format_html(): HTML generation via placeholder replacement
  • Safe Strings
    • SafeString: Safe string type for bypassing automatic escaping

Encoding Utilities (encoding module)

  • URL Encoding
    • urlencode(): URL encoding (spaces converted to +)
    • urldecode(): URL decoding
  • JavaScript Escaping
    • escapejs(): JavaScript string escaping (handles quotes, control characters, special characters)
  • Slugification
    • slugify(): URL slug generation (lowercase, special character removal, hyphen-separated)
  • Text Processing
    • truncate_chars(): Truncate by character count (appends ...)
    • truncate_words(): Truncate by word count (appends ...)
    • wrap_text(): Wrap text at specified width
    • force_str(): Safely convert byte sequences to UTF-8 strings
    • force_bytes(): Convert strings to byte sequences
  • Line Break Processing
    • linebreaks(): Convert line breaks to <br> tags (with paragraph support)
    • linebreaksbr(): Convert line breaks to <br> tags (simple version)

Date/Time Formatting (dateformat module)

  • Django/PHP-style Formatting
    • format(): Date/time formatting with format strings
    • Supported format codes:
      • Year: Y (4-digit), y (2-digit)
      • Month: m (zero-padded), n (no padding), F (full name), M (abbreviated)
      • Day: d (zero-padded), j (no padding), l (day name), D (day abbreviated)
      • Hour: H (24-hour), h (12-hour), G/g (unpadded versions)
      • Minute: i, Second: s
      • AM/PM: A (uppercase), a (lowercase)
  • Shortcut Functions (shortcuts submodule)
    • iso_date(): YYYY-MM-DD format
    • iso_datetime(): YYYY-MM-DD HH:MM:SS format
    • us_date(): MM/DD/YYYY format
    • eu_date(): DD/MM/YYYY format
    • full_date(): "Monday, January 1, 2025" format
    • short_date(): "Jan 1, 2025" format
    • time_24(): 24-hour format time
    • time_12(): 12-hour format time (with AM/PM)

Text Manipulation (text module)

  • Case Conversion
    • capfirst(): Capitalize first letter of each word
    • title(): Title case conversion (first letter uppercase, rest lowercase)
  • Number Formatting
    • intcomma(): Add comma separators to integers (every 3 digits)
    • floatcomma(): Add comma separators to floating-point numbers
    • ordinal(): Add ordinal suffixes (1st, 2nd, 3rd, 4th, etc.)
  • Singular/Plural
    • pluralize(): Toggle singular/plural based on count
  • Padding
    • ljust(): Left-justify (right padding)
    • rjust(): Right-justify (left padding)
    • center(): Center-align (both-side padding)
  • Phone Number Formatting
    • phone_format(): Convert 10/11-digit phone numbers to (XXX) XXX-XXXX format

Timezone Utilities (timezone module)

  • Basic DateTime Retrieval
    • now(): Current UTC time
    • localtime(): Current local time
  • Timezone Conversion
    • to_local(): UTC to local timezone conversion
    • to_utc(): Local to UTC conversion
    • to_timezone(): Timezone conversion by IANA name (currently UTC only)
  • Naive/Aware Conversion
    • make_aware_utc(): Convert naive datetime to UTC timezone-aware
    • make_aware_local(): Convert naive datetime to local timezone-aware
    • is_aware(): Check for timezone information presence (always true in Rust)
  • Parse/Format
    • parse_datetime(): Parse ISO 8601 datetime strings
    • format_datetime(): Output datetime in ISO 8601 format (RFC 3339)
  • Timezone Name Retrieval
    • get_timezone_name_utc(): Get timezone name for UTC datetime
    • get_timezone_name_local(): Get timezone name for local datetime

cache

Features

Core Cache API - Implemented ✓

  • Cache trait: Async-first trait for cache operations with generic type support
    • get<T>(): Retrieve values from cache with automatic deserialization
    • set<T>(): Store values with optional TTL (Time-To-Live)
    • delete(): Remove individual cache entries
    • has_key(): Check cache key existence
    • clear(): Remove all entries from cache
    • get_many(): Batch retrieval of multiple cache keys
    • set_many(): Batch storage of multiple values
    • delete_many(): Batch deletion of multiple keys
    • incr(): Atomic increment for numeric values
    • decr(): Atomic decrement for numeric values

Cache Backends - Implemented ✓

  • InMemoryCache: Thread-safe in-memory cache backend

    • Built on Arc<RwLock<HashMap>> for concurrent access
    • Automatic expiration with TTL support
    • with_default_ttl(): Configure default expiration time
    • cleanup_expired(): Manual cleanup of expired entries
    • JSON serialization via serde for type safety

  • RedisCache: Redis-backed distributed cache (requires redis-backend feature)

    • Connection pooling with ConnectionManager for efficient connection reuse
    • with_default_ttl(): Default TTL configuration
    • with_key_prefix(): Namespace support for multi-tenant scenarios
    • Automatic key prefixing for organized cache entries
    • Full Redis integration with all core operations implemented
    • Batch operations (get_many, set_many, delete_many) for improved performance
    • Atomic operations (incr, decr) using Redis native commands

Cache Key Management - Implemented ✓

  • CacheKeyBuilder: Utility for generating versioned cache keys
    • new(): Create builder with custom prefix
    • with_version(): Version-based cache invalidation
    • build(): Generate prefixed and versioned keys
    • build_many(): Batch key generation
    • Format: {prefix}:{version}:{key}

HTTP Middleware - Implemented ✓

  • CacheMiddleware: Automatic HTTP response caching

    • Request method filtering (GET-only by default via cache_get_only)
    • Response status code filtering (2xx-only by default via cache_success_only)
    • Cache-Control header parsing (max-age, no-cache, no-store directives)
    • Configurable cache timeout with CacheMiddlewareConfig
    • Query parameter-aware cache key generation
    • Full response caching (status, headers, body)

  • CacheMiddlewareConfig: Middleware configuration

    • with_default_timeout(): Set default cache duration
    • with_key_prefix(): Configure cache namespace
    • cache_all_methods(): Enable caching for non-GET requests
    • cache_all_responses(): Cache non-2xx responses
    • Custom Cache-Control header name support

Dependency Injection Support - Implemented ✓

  • CacheService: High-level service with DI integration

    • Automatic injection via reinhardt-di
    • Integrated CacheKeyBuilder for automatic key prefixing
    • Methods: get(), set(), delete() with automatic key building
    • Access to underlying cache via cache() method
    • Access to key builder via key_builder() method

  • RedisConfig: Redis configuration for DI (requires redis-backend feature)

    • new(): Custom Redis URL configuration
    • localhost(): Quick localhost setup
    • Automatic injection from singleton scope
    • Fallback to localhost if not configured

  • Injectable trait implementations:

    • InMemoryCache: Uses default singleton-based injection
    • CacheKeyBuilder: Custom default ("app" prefix, version 1)
    • RedisCache: Injects with RedisConfig dependency
    • CacheService: Composes cache and key builder via DI

Feature Flags - Implemented ✓

  • redis-backend: Enable Redis support (optional dependency)
  • memcached-backend: Enable Memcached support (optional dependency)
  • all-backends: Enable all backend implementations

logging

Features

Implemented ✓

Core Logging Infrastructure

  • Logger System: Core logger implementation with handler attachment support
    • Logger struct with warning level logging
    • LoggerHandle: Wrapper around Arc<Logger> for thread-safe logger access
    • LogHandler trait for extensible log processing
    • Thread-safe handler management
  • Log Levels: Support for Debug, Info, Warn, and Error severity levels
  • Log Records: Structured log record representation

Logging Configuration

  • Global Logging Manager: Singleton-based global logging initialization and management
    • init_global_logging() for one-time setup
    • get_logger(name) returns LoggerHandle for retrieving named loggers
    • Thread-safe access via once_cell
  • Configuration Structures:
    • LoggingConfig: Main configuration container
    • HandlerConfig: Handler-specific settings
    • LoggerConfig: Logger-specific settings

Log Handlers

  • Console Handler: Output logs to standard output/error
  • File Handler: Write logs to file system
  • JSON Handler: Structured JSON log output
  • Memory Handler: In-memory log storage for testing and debugging
    • Level-based filtering
    • Cloneable for test assertions

Formatters

  • Formatter Trait: Extensible log formatting interface
  • Standard Formatter: Default human-readable format
  • Server Formatter: Server-optimized log format
  • Control Character Escaping: escape_control_chars() utility for safe log output

Filters

  • Filter Trait: Generic log filtering interface
  • Callback Filter: Custom filter implementation support
  • Debug-based Filters:
    • RequireDebugTrue: Only log when debug mode is enabled
    • RequireDebugFalse: Only log when debug mode is disabled

Parameter Representation Utilities

  • Smart Parameter Truncation: Prevent log overflow with large data structures
    • repr_params(): Truncate arrays, objects, and nested structures
    • truncate_param(): Truncate individual string values
    • ReprParamsConfig: Configurable truncation behavior
  • Multi-batch Parameter Display: Show first/last items for large parameter sets
  • Character-level Truncation: Middle truncation preserving start/end context
  • SQLAlchemy-inspired Design: Based on proven parameter representation patterns

Convenience APIs

  • Global Logging Functions:
    • emit_warning(): Quick warning emission
    • attach_memory_handler(): Easy test handler attachment
  • Type Safety: Strongly-typed configuration and log levels
  • Async Support: Built on Tokio for async runtime compatibility

Security Logging

  • SecurityLogger: Dedicated logger for security-related events
    • Authentication events (success/failure)
    • Authorization violations
    • CSRF violations
    • Rate limit exceeded events
    • Suspicious file operations
    • Disallowed host access
  • SecurityError: Enum for categorizing security events
    • AuthenticationFailed, AuthorizationFailed, InvalidToken
    • RateLimitExceeded, SuspiciousActivity, CsrfViolation
    • InvalidInput, AccessDenied, DisallowedHost

Usage Example:

use reinhardt::utils::logging::security::{SecurityLogger, SecurityError};

let logger = SecurityLogger::new();

// Log authentication events
logger.log_auth_event(true, "user@example.com");  // INFO level
logger.log_auth_event(false, "attacker@evil.com"); // WARNING level

// Log security errors
logger.log_security_error(&SecurityError::CsrfViolation);  // ERROR level

// Log CSRF violation with details
logger.log_csrf_violation("http://evil.com");

// Log rate limit exceeded
logger.log_rate_limit_exceeded("192.168.1.1", 100);

// Log suspicious file operations
logger.log_suspicious_file_operation("delete", Path::new("/etc/passwd"));

// Log disallowed host access
logger.log_disallowed_host("malicious.com");

Log Level Mapping:

Event Log Level
Authentication success INFO
Authentication failure WARNING
CSRF violation ERROR
Rate limit exceeded WARNING
Authorization failure WARNING
Suspicious activity ERROR

static

Features

Core Functionality

✓ Implemented

  • Static File Configuration (StaticFilesConfig)

    • Configurable static root directory for collected files
    • Static URL path configuration with validation
    • Multiple source directories support via STATICFILES_DIRS
    • Media URL configuration and conflict detection

  • Storage Backends (Storage trait)

    • FileSystemStorage - Local file system storage
    • MemoryStorage - In-memory storage for testing
    • Extensible storage backend system

  • Static File Finder (StaticFilesFinder)

    • Locate files across multiple static directories
    • Support for collecting files from various sources
    • find_all() - Recursively discover all static files across configured directories
    • Efficient directory tree traversal with proper error handling

  • Hashed File Storage (HashedFileStorage)

    • File hashing for cache busting
    • Configurable hashing algorithms (MD5, SHA-256)
    • Automatic hash calculation and filename generation
    • Integration with manifest system

  • Manifest System (ManifestStaticFilesStorage)

    • JSON manifest for mapping original filenames to hashed versions
    • Versioned manifest format (currently V1)
    • Enables efficient static file lookup in production
    • Supports deployment workflows with pre-collected assets

  • Media Asset Management (Media, HasMedia)

    • CSS and JavaScript dependency declaration for forms and widgets
    • Media type organization (e.g., "all", "screen", "print")
    • HTML rendering for <link> and <script> tags
    • Dependency merging with duplicate prevention
    • Trait-based system for components to declare their assets

  • Static File Handler (StaticFileHandler)

    • HTTP request handling for static files
    • MIME type detection via mime_guess
    • Error handling with StaticError and StaticResult types
    • File serving with proper content types
    • Directory serving with automatic index file detection
    • Configurable index files (default: ["index.html"]) via with_index_files()
    • Serves index.html when accessing directories directly
    • ETag Support: Content-based ETag generation for conditional requests
      • Automatic ETag generation using hash of file content
      • Support for If-None-Match headers
      • 304 Not Modified responses for cached resources
      • Implemented in handler.rs (StaticFile::etag() method)

  • Configuration Validation (checks module)

    • Django-style system checks for static files configuration
    • Multiple check levels: Debug, Info, Warning, Error, Critical
    • Comprehensive validation rules:
      • static.E001 - STATIC_ROOT not set
      • static.E002 - STATIC_ROOT in STATICFILES_DIRS
      • static.E003 - STATIC_URL is empty
      • static.E004 - STATICFILES_DIRS entry is not a directory
      • static.W001 - STATIC_ROOT is subdirectory of STATICFILES_DIRS
      • static.W002 - STATIC_URL doesn't start with '/'
      • static.W003 - STATIC_URL doesn't end with '/'
      • static.W004 - STATICFILES_DIRS is empty
      • static.W005 - Directory doesn't exist
      • static.W006 - Duplicate STATICFILES_DIRS entries
      • static.W007 - MEDIA_URL doesn't start with '/'
      • static.W008 - MEDIA_URL doesn't end with '/'
      • static.W009 - MEDIA_URL prefix conflict with STATIC_URL
    • Helpful hints for fixing configuration issues

  • Health Check System (health module)

    • Health status monitoring (Healthy, Degraded, Unhealthy)
    • Async health check trait with async_trait
    • Health check manager for centralized monitoring
    • Detailed health reports with metadata support
    • Marker traits for specialized checks:
      • CacheHealthCheck - Cache-related health checks
      • DatabaseHealthCheck - Database-related health checks
    • Component-level health status tracking
    • Production-ready monitoring integration

  • Metrics Collection (metrics module)

    • Performance metrics tracking
    • Request timing and profiling (RequestTimer)
    • Request-specific metrics (RequestMetrics)
    • Centralized metrics collection (MetricsCollector)
    • Generic metric types for custom measurements

  • Middleware (StaticFilesMiddleware)

    • Request/response processing for static files
    • Integration with HTTP pipeline
    • Automatic static file serving in development

  • Dependency Resolution (DependencyGraph)

    • Track dependencies between static assets
    • Resolve asset loading order
    • Support for complex asset dependency chains

Implemented in Related Crates

  • collectstatic Command (implemented in reinhardt-commands)

    • ✓ CLI command for collecting static files from all sources
    • ✓ Copy files to STATIC_ROOT with optional processing
    • ✓ Integration with deployment workflows
    • ✓ Progress reporting and verbose output
    • See reinhardt-commands for details

  • GZip Compression (implemented in reinhardt-middleware)

    • ✓ Response compression for bandwidth optimization
    • ✓ Configurable compression level (0-9)
    • ✓ Minimum size threshold configuration
    • ✓ Content-type filtering (text/*, application/json, etc.)
    • ✓ Automatic Accept-Encoding detection
    • ✓ Compression only when beneficial (size check)
    • See reinhardt-middleware for details

  • Brotli Compression (implemented in reinhardt-middleware)

    • ✓ Advanced compression with better ratios than gzip
    • ✓ Configurable quality levels (Fast, Balanced, Best)
    • ✓ Window size configuration (10-24)
    • ✓ Content-type filtering
    • ✓ Automatic Accept-Encoding: br detection
    • ✓ Intelligent compression (only when beneficial)
    • See reinhardt-middleware for details

  • Cache-Control Header Management

    • ✓ Configurable cache policies per file type
    • ✓ Long-term caching for static assets (CSS, JS, fonts, images)
    • ✓ Short-term caching for HTML files
    • ✓ Flexible cache directives (public, private, no-cache, immutable, etc.)
    • ✓ max-age and s-maxage configuration
    • ✓ Vary header support
    • ✓ Pattern-based cache policies

  • CDN Integration

    • ✓ Multi-provider support (CloudFront, Fastly, Cloudflare, Custom)
    • ✓ CDN URL generation with path prefixes
    • ✓ Versioned URL generation
    • ✓ HTTPS/HTTP configuration
    • ✓ Custom header support
    • ✓ Cache invalidation request helpers
    • ✓ Wildcard purge support

  • Advanced Storage Backends (storage module)

    • S3Storage - S3-compatible storage backend (AWS S3, MinIO, LocalStack)
      • Configurable credentials (access key, secret key)
      • Custom endpoint support for S3-compatible services
      • Path-style addressing configuration
      • Path prefix support within buckets
    • AzureBlobStorage - Azure Blob Storage backend
      • Shared key and SAS token authentication
      • Custom endpoint support for Azure emulator
      • Container and path prefix configuration
    • GcsStorage - Google Cloud Storage backend
      • Service account credentials (JSON or file path)
      • Custom endpoint support for GCS emulator
      • Project ID and bucket configuration
    • StorageRegistry - Custom storage backend registration system
      • Dynamic registration of storage backends
      • Factory pattern for creating storage instances
      • Backend lifecycle management (register, unregister, clear)

  • Pages/SSR Integration (template_integration module)

    • TemplateStaticConfig - Configuration for static file generation in SSR contexts
    • Automatic hashed filename resolution via manifest
    • Supports custom static URLs (CDN, etc.)
    • Can be integrated with reinhardt-pages SSR and other rendering systems

  • File Processing Pipeline (processing module)

    • CSS/JavaScript minification (basic whitespace and comment removal)
    • Asset bundling with dependency resolution
    • Processing pipeline manager
    • Configurable optimization levels
    • Feature flag: processing (default: disabled)

  • Development Server Features (dev_server module)

    • File system watching with notify crate
    • Auto-reload notification system using broadcast channels
    • Development error pages with detailed debugging information
    • WebSocket-based reload notifications (port 35729 by default)
    • Smart reload strategies:
      • CSS files: Reload without full page refresh
      • Other files: Full page reload
    • Multiple path watching support
    • Client connection tracking
    • Feature flag: dev-server (default: disabled)

  • Advanced File Processing

    • Image optimization (PNG, JPEG, WebP) - Feature flag: image-optimization
    • Source map generation - Feature flag: source-maps
    • Asset compression (gzip, brotli) - Feature flag: compression
    • Minification for CSS and JavaScript
    • Asset bundling with dependency resolution

  • Advanced Minification (OXC-powered)

    • Variable renaming (mangling) - Feature flag: advanced-minification
    • Dead code elimination
    • Production-grade compression
    • Console.log removal option
    • Debugger statement removal

storage

Features

Implemented ✓

Core Storage Abstraction

  • Storage Trait: Async trait defining standard storage operations
    • File save, read, delete operations
    • File existence checking and metadata retrieval
    • Directory listing functionality
    • URL generation for file access
    • File timestamp operations (accessed, created, modified times)

File and Metadata Handling

  • FileMetadata: Comprehensive file metadata structure
    • Path, size, content type tracking
    • Creation and modification timestamps
    • Optional checksum support (SHA-256)
    • Builder pattern methods (with_content_type, with_checksum)
  • StoredFile: File representation with metadata and content

Error Handling

  • StorageError: Comprehensive error types
    • File not found errors
    • I/O error propagation
    • Invalid path detection
    • Storage full conditions
    • Permission denied errors
    • File already exists errors

Local Filesystem Storage

  • LocalStorage: Production-ready local filesystem backend
    • Automatic directory creation
    • Path traversal attack prevention
    • SHA-256 checksum computation
    • File timestamp retrieval (accessed, created, modified)
    • URL generation with configurable base URL
    • Comprehensive directory listing

In-Memory Storage

  • InMemoryStorage: Testing and development storage backend
    • Thread-safe in-memory file storage using Arc
    • Timestamp tracking (accessed, created, modified)
    • Directory-style path organization
    • Configurable file and directory permission modes
    • Django-style deconstruction for serialization
    • Clone support for easy testing

Prelude Module

  • Re-exports of commonly used types for convenient importing

utils-core

Features

Implemented ✓

HTML Utilities

  • HTML escaping - Escape/unescape HTML special characters for XSS prevention
  • Tag stripping - Remove HTML tags from text
  • Space normalization - Strip spaces between HTML tags
  • Attribute escaping - Escape values for safe use in HTML attributes
  • Template formatting - Simple placeholder-based HTML templating
  • Conditional escaping - Context-aware HTML escaping
  • SafeString - Mark strings as safe to bypass autoescaping
  • HTML truncation - Truncate HTML content to specified word count while preserving tags

Common Utilities

  • Type conversion helpers
  • String manipulation utilities
  • Collection helpers
  • Time and date utilities
  • Encoding/decoding utilities
  • Core abstraction types