adaptive_pipeline/application/
commands.rs

1// /////////////////////////////////////////////////////////////////////////////
2// Adaptive Pipeline
3// Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
4// SPDX-License-Identifier: BSD-3-Clause
5// See LICENSE file in the project root.
6// /////////////////////////////////////////////////////////////////////////////
7
8//! # Application Commands
9//!
10//! This module implements the Command pattern as part of the CQRS (Command
11//! Query Responsibility Segregation) architecture. Commands represent
12//! operations that change system state and are designed to be immutable,
13//! self-contained instructions that can be validated, logged, and executed.
14//!
15//! ## Overview
16//!
17//! Application commands provide:
18//!
19//! - **State Modification**: Commands represent operations that change system
20//!   state
21//! - **Validation**: Commands can be validated before execution
22//! - **Auditability**: Commands provide a clear audit trail of operations
23//! - **Testability**: Commands can be easily unit tested in isolation
24//! - **Serialization**: Commands can be serialized for queuing or persistence
25//!
26//! ## CQRS Architecture
27//!
28//! ### Command Characteristics
29//!
30//! Commands in this system have the following characteristics:
31//!
32//! - **Immutable**: Once created, commands cannot be modified
33//! - **Self-Contained**: Commands contain all information needed for execution
34//! - **Validated**: Commands are validated before execution
35//! - **Auditable**: Commands provide clear operation tracking
36//! - **Asynchronous**: Commands can be executed asynchronously
37//!
38//! ### Command Lifecycle
39//!
40//! The typical command lifecycle follows these steps:
41//!
42//! 1. **Creation**: Command is created with required parameters
43//! 2. **Validation**: Command is validated for correctness
44//! 3. **Authorization**: User permissions are checked
45//! 4. **Execution**: Command is executed by appropriate handler
46//! 5. **Result**: Command execution result is returned
47//! 6. **Audit**: Command execution is logged for audit trail
48//!
49//! ## Command Types
50//!
51//! ### File Restoration Commands
52//!
53//! Commands related to restoring files from the pipeline format:
54//!
55//! - `RestoreFileCommand`: Restore a file from .adapipe format
56//! - Future commands for batch restoration, selective restoration, etc.
57//!
58//! ## Usage Patterns
59//!
60//! ### Basic Command Creation and Execution
61
62//!
63//! ### Command Validation
64
65//!
66//! ### Command Builder Pattern
67
68//!
69//! ### Asynchronous Command Processing
70
71//!
72//! ## Best Practices
73//!
74//! ### Command Design
75//!
76//! - **Immutability**: Commands should be immutable after creation
77//! - **Self-Validation**: Commands should validate their own parameters
78//! - **Rich Information**: Include all necessary context in the command
79//! - **Clear Intent**: Command names should clearly indicate their purpose
80//!
81//! ### Error Handling
82//!
83//! - **Validation Errors**: Catch validation errors before execution
84//! - **Execution Errors**: Handle execution failures gracefully
85//! - **Rollback**: Design commands to support rollback when possible
86//! - **Audit Trail**: Log all command executions for debugging
87//!
88//! ### Performance
89//!
90//! - **Async Execution**: Use async patterns for I/O-bound operations
91//! - **Batch Processing**: Group related commands for efficiency
92//! - **Resource Management**: Properly manage resources during execution
93//! - **Timeout Handling**: Implement appropriate timeouts for long operations
94//!
95//! ## Testing Strategies
96//!
97//! ### Unit Testing Commands
98
99//!
100//! ### Integration Testing
101//!
102//! Test commands with real handlers and infrastructure:
103
104use std::path::PathBuf;
105
106/// Command to restore a file from .adapipe format.
107///
108/// This command encapsulates all the information needed to restore a file from
109/// the pipeline's compressed and processed format back to its original form.
110/// It follows the Command pattern and supports the builder pattern for
111/// flexible configuration.
112///
113/// ## Command Properties
114///
115/// - **Immutable**: Once created, the command cannot be modified (except
116///   through builder methods)
117/// - **Self-Contained**: Contains all information needed for execution
118/// - **Validatable**: Can be validated before execution
119/// - **Auditable**: Provides clear operation tracking
120///
121/// ## Usage Examples
122///
123/// ### Basic File Restoration
124///
125///
126/// ### Advanced Configuration
127///
128///
129/// ### Batch Processing Setup
130///
131///
132/// ## Validation
133///
134/// Commands should be validated before execution to ensure:
135///
136/// - Source file exists and is readable
137/// - Target directory is writable
138/// - Sufficient disk space is available
139/// - Permissions allow the operation
140///
141/// ## Error Handling
142///
143/// Command execution can fail for various reasons:
144///
145/// - Source file not found or corrupted
146/// - Insufficient permissions
147/// - Disk space exhausted
148/// - Target file already exists (when overwrite is false)
149/// - Invalid .adapipe format
150///
151/// ## Performance Considerations
152///
153/// - Large files may require streaming restoration
154/// - Multiple commands can be processed concurrently
155/// - Progress tracking may be needed for long operations
156/// - Memory usage scales with file size and concurrency
157#[derive(Debug, Clone)]
158pub struct RestoreFileCommand {
159    /// Path to the .adapipe file to restore from
160    pub source_adapipe_path: PathBuf,
161    /// Target directory or file path for restoration
162    pub target_path: PathBuf,
163    /// Whether to overwrite existing files
164    pub overwrite: bool,
165    /// Whether to create missing directories
166    pub create_directories: bool,
167    /// Whether to validate permissions before restoration
168    pub validate_permissions: bool,
169}
170
171impl RestoreFileCommand {
172    pub fn new(source_adapipe_path: PathBuf, target_path: PathBuf) -> Self {
173        Self {
174            source_adapipe_path,
175            target_path,
176            overwrite: false,
177            create_directories: true,
178            validate_permissions: true,
179        }
180    }
181
182    pub fn with_overwrite(mut self, overwrite: bool) -> Self {
183        self.overwrite = overwrite;
184        self
185    }
186
187    pub fn with_create_directories(mut self, create_directories: bool) -> Self {
188        self.create_directories = create_directories;
189        self
190    }
191
192    pub fn with_permission_validation(mut self, validate: bool) -> Self {
193        self.validate_permissions = validate;
194        self
195    }
196}
197
198/// Result of file restoration command
199#[derive(Debug)]
200#[allow(dead_code)]
201pub struct RestoreFileResult {
202    /// Path where the file was restored
203    pub restored_path: PathBuf,
204    /// Number of bytes restored
205    pub bytes_restored: u64,
206    /// Whether checksum validation passed
207    pub checksum_verified: bool,
208    /// Calculated checksum of restored file
209    pub calculated_checksum: String,
210    /// Time taken for restoration
211    pub restoration_time_ms: u64,
212}
adaptive_pipeline/application/commands.rs

adaptive_pipeline/application/
commands.rs
