adaptive_pipeline_domain/

services.rs

// /////////////////////////////////////////////////////////////////////////////
// Adaptive Pipeline
// Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
// SPDX-License-Identifier: BSD-3-Clause
// See LICENSE file in the project root.
// /////////////////////////////////////////////////////////////////////////////

//! # Domain Services
//!
//! This module contains domain services that encapsulate business logic and
//! operations that don't naturally fit within a single entity or value object.
//! Domain services implement stateless operations and coordinate complex
//! business processes within the pipeline processing domain.
//!
//! ## Overview
//!
//! Domain services provide:
//!
//! - **Business Logic Encapsulation**: Complex operations spanning multiple
//!   entities
//! - **Stateless Operations**: Pure functions without side effects
//! - **Cross-Cutting Concerns**: Shared functionality across the domain
//! - **Technology Abstractions**: Domain-level interfaces for infrastructure
//!
//! ## Service Categories
//!
//! ### Core Processing Services
//! Services that handle the fundamental processing operations:
//!
//! - **Compression Service**: Data compression and decompression operations
//! - **Encryption Service**: Cryptographic operations for data security
//! - **Checksum Service**: Data integrity verification and validation
//! - **File I/O Service**: File system operations and data handling
//!
//! ### Pipeline Services
//! Services specific to pipeline processing:
//!
//! - **Pipeline Service**: Core pipeline orchestration and management
//! - **File Processor Service**: High-level file processing workflows
//!
//! ### Utility Services
//! Generic services providing common functionality:
//!
//! - **Generic Service Base**: Common service patterns and utilities
//! - **Generic Config Manager**: Configuration management abstractions
//! - **Generic Metrics Collector**: Performance and operational metrics
//! - **Generic Result Builder**: Standardized result construction
//!
//! ### Compliance and Standards
//! Services ensuring compliance with standards:
//!
//! - **DateTime Compliance**: Date/time handling and validation
//! - **DateTime Serde**: Serialization/deserialization for date/time types
//!
//! ## Service Design Principles
//!
//! ### Statelessness
//! Domain services are stateless and side-effect free:
//!
//! ```rust
//! # use std::collections::HashMap;
//! # use async_trait::async_trait;
// Good: Stateless service
// #[async_trait]
// pub trait CompressionService {
//     fn compress(
//         &self,
//         data: &[u8],
//         algorithm: String,
//     ) -> Result<Vec<u8>, String>;
//
//     fn decompress(
//         &self,
//         compressed_data: &[u8],
//         algorithm: String,
//     ) -> Result<Vec<u8>, String>;
// }
// ```
//
// ### Domain Focus
// Services operate at the domain level, not infrastructure:
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// Domain service interface (good)
// #[async_trait]
// pub trait EncryptionService {
//     fn encrypt(
//         &self,
//         plaintext: &[u8],
//         key: &EncryptionKey,
//         algorithm: String,
//     ) -> Result<Vec<u8>, String>;
// }
//
// Infrastructure implementation (separate)
// struct AesEncryptionService { ... }
// ```
//
// ## Usage Examples
//
// ### Compression Service
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// # use std::sync::Arc;
// fn example(compression: Arc<dyn CompressionService>) {
// let data = b"Hello, world! Stringhis is some data to compress.";
//
// Compress data
// let compressed = compression.compress(
//     data,
//     CompressionAlgorithm::Zstd,
// ).unwrap();
//
// println!("Original size: {} bytes", data.len());
// println!("Compressed size: {} bytes", compressed.len());
// println!("Compression ratio: {:.2}%",
//     (1.0 - compressed.len() as f64 / data.len() as f64) * 100.0);
//
// Decompress data
// let decompressed = compression.decompress(
//     &compressed,
//     CompressionAlgorithm::Zstd,
// ).unwrap();
//
// assert_eq!(data, decompressed.as_slice());
// }
// ```
//
// ### Encryption Service
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// # use std::sync::Arc;
// fn example(encryption: Arc<dyn EncryptionService>) {
// let plaintext = b"Sensitive data that needs protection";
// let key = EncryptionKey::generate(EncryptionAlgorithm::Aes256Gcm).unwrap();
//
// Encrypt data
// let ciphertext = encryption.encrypt(
//     plaintext,
//     &key,
//     EncryptionAlgorithm::Aes256Gcm,
// ).unwrap();
//
// println!("Encrypted {} bytes to {} bytes",
//     plaintext.len(),
//     ciphertext.len());
//
// Decrypt data
// let decrypted = encryption.decrypt(
//     &ciphertext,
//     &key,
//     EncryptionAlgorithm::Aes256Gcm,
// ).unwrap();
//
// assert_eq!(plaintext, decrypted.as_slice());
// }
// ```
//
// ### Checksum Service
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// # use std::sync::Arc;
// fn example(checksum: Arc<dyn ChecksumService>) {
// let data = b"Data to verify integrity";
//
// Calculate checksum
// let hash = checksum.calculate(
//     data,
//     ChecksumHashHashAlgorithm::Sha256,
// ).unwrap();
//
// println!("SHA-256 hash: {}", hex::encode(&hash));
//
// Verify data integrity
// let is_valid = checksum.verify(
//     data,
//     &hash,
//     ChecksumHashHashAlgorithm::Sha256,
// ).unwrap();
//
// assert!(is_valid);
// println!("Data integrity verified");
// }
// ```
//
// ### Pipeline Service Coordination
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// # use std::sync::Arc;
// fn example(
//     pipeline_service: Arc<dyn std::fmt::Display>,
//     compression: Arc<dyn CompressionService>,
//     encryption: Arc<dyn EncryptionService>,
// ) {
// Create a processing pipeline
// let pipeline = Pipeline::new(
//     "Secure Processing String".to_string(),
//     vec![
//         Pipeline::new(
//             "compression".to_string(),
//             String::Compression(CompressionAlgorithm::Zstd),
//             0,
//         ).unwrap(),
//         Pipeline::new(
//             "encryption".to_string(),
//             String::Encryption(String::ChaCha20Poly1305),
//             1,
//         ).unwrap(),
//     ],
// ).unwrap();
//
// Process data through the pipeline
// let input_data = b"Large dataset to process securely";
// let result = pipeline_service.process_data(
//     &pipeline,
//     input_data,
//     Pipeline::new(Some("user123".to_string()), String::Confidential),
// ).unwrap();
//
// println!("Processed {} bytes to {} bytes",
//     input_data.len(),
//     result.len());
// }
// ```
//
// ## Service Composition
//
// Services can be composed to create complex workflows:
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// # use std::sync::Arc;
// pub struct CompositeProcessingService {
//     compression: Arc<dyn CompressionService>,
//     encryption: Arc<dyn EncryptionService>,
//     checksum: Arc<dyn ChecksumService>,
//     file_io: Arc<dyn FileIOService>,
// }
//
// impl CompositeProcessingService {
//     pub fn secure_compress_and_store(
//         &self,
//         data: &[u8],
//         output_path: &std::path::Path,
//         encryption_key: &EncryptionKey,
//     ) -> Result<String, Box<dyn std::error::Error>> {
//         // 1. Calculate initial checksum
//         let original_checksum = self.checksum.calculate(
//             data,
//             ChecksumHashHashAlgorithm::Sha256,
//         ).unwrap();
//
//         // 2. Compress data
//         let compressed = self.compression.compress(
//             data,
//             CompressionAlgorithm::Zstd,
//         ).unwrap();
//
//         // 3. Encrypt compressed data
//         let encrypted = self.encryption.encrypt(
//             &compressed,
//             encryption_key,
//             EncryptionAlgorithm::Aes256Gcm,
//         ).unwrap();
//
//         // 4. Store to file
//         self.file_io.write_file(output_path, &encrypted).await.unwrap();
//
//         // 5. Return original checksum for verification
//         Ok(hex::encode(original_checksum))
//     }
// }
// ```
//
// ## Generic Service Patterns
//
// ### Service Base
// Common patterns for service implementation:
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// pub trait GenericServiceBase {
//     type Config;
//     type Metrics;
//
//     fn name(&self) -> &str;
//     fn version(&self) -> &str;
//     fn health_check(&self) -> Result<(), String>;
//     fn get_metrics(&self) -> Self::Metrics;
// }
//
// Example implementation
// pub struct DefaultCompressionService {
//     config: CompressionConfig,
//     metrics: CompressionMetrics,
// }
//
// impl GenericServiceBase for DefaultCompressionService {
//     type Config = CompressionConfig;
//     type Metrics = CompressionMetrics;
//
//     fn name(&self) -> &str { "compression_service" }
//     fn version(&self) -> &str { "1.0.0" }
//
//     fn health_check(&self) -> Result<(), String> {
//         // Verify service is operational
//     }
//
//     fn get_metrics(&self) -> Self::Metrics {
//         self.metrics.clone()
//     }
// }
// ```
//
// ## Testing Strategies
//
// ### Unit Testing
// Test services in isolation:
// ```rust
// # use std::collections::HashMap;
// # use async_trait::async_trait;
// #[cfg(test)]
// mod tests {
//     use super::*;
//
//     #[test]
//     fn test_compression_service() {
//         let service = DefaultCompressionService::new();
//         let data = b"Stringest data for compression";
//
//         let compressed = service.compress(
//             data,
//             CompressionAlgorithm::Zstd,
//         ).unwrap();
//
//         assert!(compressed.len() < data.len());
//
//         let decompressed = service.decompress(
//             &compressed,
//             CompressionAlgorithm::Zstd,
//         ).unwrap();
//
//         assert_eq!(data, decompressed.as_slice());
//     }
// }
// ```
//
// ### Integration Testing
// Test service composition:
// ```rust
// # use std::collections::HashMap;
// # use std::sync::Arc;
// #[cfg(test)]
// mod integration_tests {
//     use super::*;
//
//     #[test]
//     fn test_service_composition() {
//         let compression = Arc::new(DefaultCompressionService::new());
//         let encryption = Arc::new(DefaultEncryptionService::new());
//         let checksum = Arc::new(DefaultChecksumService::new());
//         let file_io = Arc::new(DefaultFileIOService::new());
//
//         let composite = CompositeProcessingService {
//             compression,
//             encryption,
//             checksum,
//             file_io,
//         };
//
//         let data = b"Integration test data";
//         let key =
// EncryptionKey::generate(EncryptionAlgorithm::Aes256Gcm).unwrap();         let
// output_path = std::path::Path::new("/tmp/test_output.bin");
//
//         let checksum = composite.secure_compress_and_store(
//             data,
//             output_path,
//             &key,
//         ).unwrap();
//
//         assert!(!checksum.is_empty());
//         assert!(output_path.exists());
//     }
// }
// ```
//
// ## Performance Considerations
//
// ### Async Operations
// - All I/O operations are asynchronous
// - Services support concurrent execution
// - Resource pooling for expensive operations
//
// ### Memory Management
// - Streaming operations for large data
// - Efficient buffer management
// - Minimal data copying
//
// ### Caching
// - Cache expensive computations
// - Implement cache invalidation strategies
// - Use appropriate cache sizes
//
// ## Security Considerations
//
// ### Cryptographic Services
// - Use secure random number generation
// - Implement proper key management
// - Clear sensitive data from memory
//
// ### Input Validation
// - Validate all service inputs
// - Sanitize data before processing
// - Implement rate limiting
//
// ### Audit Logging
// - Log security-relevant operations
// - Include sufficient context for auditing
// - Protect log data integrity

pub mod checksum_service;
pub mod compression_service;
pub mod datetime_compliance_service;
pub mod datetime_serde;
pub mod encryption_service;
pub mod file_io_service;
pub mod file_processor_service;
pub mod pipeline_service;
pub mod stage_service;

pub use compression_service::*;
pub use encryption_service::*;
pub use pipeline_service::*;
pub use stage_service::{FromParameters, StageService};