adaptive_pipeline_bootstrap/
lib.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// Production code safety enforced via CI and `make lint-strict`
9// (lib/bins checked separately from tests - tests may use unwrap/expect)
10
11//! # Bootstrap Module
12//!
13//! The bootstrap module sits **outside** the enterprise application layers
14//! (domain, application, infrastructure) and provides:
15//!
16//! - **Entry point** - Application lifecycle management
17//! - **Platform abstraction** - OS-specific operations (POSIX vs Windows)
18//! - **Signal handling** - Graceful shutdown (SIGTERM, SIGINT, SIGHUP)
19//! - **Argument parsing** - Secure CLI argument validation
20//! - **Dependency injection** - Composition root for wiring dependencies
21//! - **Error handling** - Unix exit code mapping
22//! - **Async coordination** - Shutdown coordination and cancellation
23//!
24//! ## Architecture Position
25//!
26//! ```text
27//! ┌─────────────────────────────────────────────┐
28//! │          BOOTSTRAP (This Module)            │
29//! │  - Entry Point                              │
30//! │  - DI Container (Composition Root)          │
31//! │  - Platform Abstraction                     │
32//! │  - Signal Handling                          │
33//! │  - Secure Arg Parsing                       │
34//! └─────────────────────────────────────────────┘
35//!                      │
36//!                      ▼
37//! ┌─────────────────────────────────────────────┐
38//! │         APPLICATION LAYER                   │
39//! │  - Use Cases                                │
40//! │  - Application Services                     │
41//! └─────────────────────────────────────────────┘
42//!                      │
43//!                      ▼
44//! ┌─────────────────────────────────────────────┐
45//! │           DOMAIN LAYER                      │
46//! │  - Business Logic                           │
47//! │  - Domain Services                          │
48//! │  - Entities & Value Objects                 │
49//! └─────────────────────────────────────────────┘
50//!                      ▲
51//!                      │
52//! ┌─────────────────────────────────────────────┐
53//! │       INFRASTRUCTURE LAYER                  │
54//! │  - Adapters                                 │
55//! │  - Repositories                             │
56//! │  - External Services                        │
57//! └─────────────────────────────────────────────┘
58//! ```
59//!
60//! ## Key Design Principles
61//!
62//! 1. **Separation from Enterprise Layers**
63//!    - Bootstrap can access all layers
64//!    - Enterprise layers cannot access bootstrap
65//!    - Clear architectural boundary
66//!
67//! 2. **Platform Abstraction**
68//!    - Abstract OS-specific functionality behind traits
69//!    - POSIX implementation for Linux/macOS
70//!    - Windows implementation with cross-platform stubs
71//!    - Compile-time platform selection
72//!
73//! 3. **Graceful Shutdown**
74//!    - Signal handlers (SIGTERM, SIGINT, SIGHUP)
75//!    - Cancellation token propagation
76//!    - Grace period with timeout enforcement
77//!    - Coordinated shutdown across components
78//!
79//! 4. **Security First**
80//!    - Input validation for all arguments
81//!    - Path traversal prevention
82//!    - Injection attack protection
83//!    - Privilege checking
84//!
85//! 5. **Testability**
86//!    - All components behind traits
87//!    - No-op implementations for testing
88//!    - Dependency injection for mocking
89//!
90//! ## Usage Example
91//!
92//! ```rust
93//! use adaptive_pipeline_bootstrap::platform::create_platform;
94//!
95//! #[tokio::main]
96//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
97//!     // Get platform abstraction
98//!     let platform = create_platform();
99//!     println!("Running on: {}", platform.platform_name());
100//!
101//!     // Bootstrap will handle:
102//!     // - Argument parsing
103//!     // - Signal handling setup
104//!     // - Dependency wiring
105//!     // - Application lifecycle
106//!     // - Graceful shutdown
107//!
108//!     Ok(())
109//! }
110//! ```
111//!
112//! ## Module Structure
113//!
114//! - `platform` - OS abstraction (Unix/Windows)
115//! - `signals` - Signal handling (SIGTERM, SIGINT, SIGHUP)
116//! - `cli` - Secure argument parsing
117//! - `config` - Application configuration
118//! - `exit_code` - Unix exit code enumeration
119//! - `logger` - Bootstrap-specific logging
120//! - `shutdown` - Shutdown coordination
121//! - `composition_root` - Dependency injection container
122//! - `app_runner` - Application lifecycle management
123
124// Re-export modules
125pub mod cli; // Now a module directory with parser and validator
126pub mod config;
127pub mod exit_code;
128pub mod logger;
129pub mod platform;
130pub mod shutdown;
131pub mod signals;
132
133// Future modules (to be implemented)
134// pub mod composition_root;
135// pub mod app_runner;
136
137// Re-export commonly used types
138pub use cli::{parse_and_validate, ValidatedCli, ValidatedCommand};
139pub use exit_code::{map_error_to_exit_code, result_to_exit_code, ExitCode};
140
141/// Bootstrap and parse CLI arguments
142///
143/// This is the main entry point for the bootstrap layer.
144/// It handles:
145/// 1. CLI parsing with clap
146/// 2. Security validation
147/// 3. Returns validated configuration
148///
149/// The caller is responsible for:
150/// - Running the application logic
151/// - Mapping results to exit codes using `result_to_exit_code`
152///
153/// # Returns
154///
155/// `ValidatedCli` with all arguments security-checked and validated
156///
157/// # Errors
158///
159/// Returns `cli::ParseError` if CLI parsing or validation fails.
160/// Clap will handle --help and --version automatically and exit the process.
161///
162/// # Example
163///
164/// ```no_run
165/// use adaptive_pipeline_bootstrap::{bootstrap_cli, result_to_exit_code};
166///
167/// #[tokio::main]
168/// async fn main() -> std::process::ExitCode {
169///     // Parse and validate CLI
170///     let validated_cli = match bootstrap_cli() {
171///         Ok(cli) => cli,
172///         Err(e) => {
173///             eprintln!("CLI Error: {}", e);
174///             return std::process::ExitCode::from(65); // EX_DATAERR
175///         }
176///     };
177///
178///     // Run application with validated config
179///     let result = run_application(validated_cli).await;
180///
181///     // Map result to exit code
182///     result_to_exit_code(result)
183/// }
184///
185/// async fn run_application(cli: adaptive_pipeline_bootstrap::ValidatedCli) -> Result<(), String> {
186///     // Application logic here
187///     Ok(())
188/// }
189/// ```
190pub fn bootstrap_cli() -> Result<ValidatedCli, cli::ParseError> {
191    cli::parse_and_validate()
192}
adaptive_pipeline_bootstrap/lib.rs

adaptive_pipeline_bootstrap/
lib.rs
