adaptive_pipeline_domain/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//! # Pipeline Domain
12//!
13//! The pipeline domain represents the core business logic and rules of the
14//! pipeline system. It implements Domain-Driven Design (DDD) patterns and is
15//! completely independent of external concerns like databases, file systems, or
16//! user interfaces.
17//!
18//! ## Module Structure
19//!
20//!
21//! ## Domain-Driven Design Concepts
22//!
23//! ### Entities
24//! Entities are objects that have a distinct identity that runs through time
25//! and different representations. They can change state while maintaining
26//! their identity.
27//!
28//! **Key Characteristics:**
29//! - Have unique identifiers
30//! - Can be mutated (state changes)
31//! - Identity persists through changes
32//! - Equality based on identity, not attributes
33//!
34//! **Examples in this domain:**
35//! - `Pipeline`: A processing workflow with stages
36//! - `PipelineStage`: An individual processing step
37//! - `ProcessingContext`: Runtime execution context
38//! - `SecurityContext`: Security and permission management
39//! - `ProcessingMetrics`: Performance and operational metrics
40//!
41//!
42//!
43//! ### Value Objects
44//! Value objects are immutable objects that represent concepts without
45//! identity. They are defined by their attributes and two value objects with
46//! the same attributes are considered equal.
47//!
48//! **Key Characteristics:**
49//! - Immutable (cannot be changed after creation)
50//! - No identity (equality based on attributes)
51//! - Self-validating (enforce business rules)
52//! - Side-effect free operations
53//!
54//! **Examples in this domain:**
55//! - `ChunkSize`: Represents the size of data chunks
56//! - `FileChunk`: Represents a piece of file data
57//! - `Algorithm`: Represents compression/encryption algorithms
58//! - `PipelineId`: Type-safe pipeline identifier
59//! - `StageOrder`: Stage ordering within pipelines
60//! - `WorkerCount`: Validated parallel worker count
61//!
62//!
63//!
64//! ### Domain Services
65//! Domain services contain business logic that doesn't naturally fit within
66//! an entity or value object. They are stateless and operate on domain objects.
67//!
68//! **Key Characteristics:**
69//! - Stateless operations
70//! - Express domain concepts
71//! - Coordinate between domain objects
72//! - Implement complex business rules
73//!
74//! **Examples in this domain:**
75//! - `CompressionService`: Handles data compression logic
76//! - `EncryptionService`: Manages data encryption/decryption
77//! - `ChecksumService`: Calculates and verifies data integrity
78//! - `PipelineService`: Orchestrates pipeline execution
79//! - `FileProcessorService`: High-level file processing
80//!
81//!
82//!
83//! ### Repositories
84//! Repositories provide an abstraction over data persistence, allowing the
85//! domain to work with collections of objects without knowing about storage
86//! details.
87//!
88//! **Key Characteristics:**
89//! - Abstract data access
90//! - Collection-oriented interface
91//! - Hide persistence technology
92//! - Support domain queries
93
94//!
95//! ### Domain Events
96//! Domain events represent significant occurrences within the domain that
97//! other parts of the system might be interested in.
98//!
99//! **Key Characteristics:**
100//! - Represent past occurrences
101//! - Immutable
102//! - Carry relevant data
103//! - Enable loose coupling
104//!
105//! **Examples in this domain:**
106//! - `PipelineCreated`: Emitted when a new pipeline is created
107//! - `ProcessingStarted`: Emitted when file processing begins
108//! - `ProcessingCompleted`: Emitted when processing finishes
109//! - `SecurityContextCreated`: Emitted for new security contexts
110//!
111//!
112//!
113//! ## Business Rules and Invariants
114//!
115//! The domain layer enforces important business rules:
116//!
117//! ### Pipeline Rules
118//! - Pipelines must have at least one stage
119//! - Stage order must be sequential and valid
120//! - Pipeline names must be unique within a context
121//!
122//! ### Chunk Processing Rules
123//! - Chunks must have non-zero size
124//! - Chunk sequence numbers must be sequential
125//! - Final chunks must be properly marked
126//!
127//! ### Security Rules
128//! - Security contexts must be validated
129//! - Encryption keys must meet strength requirements
130//! - Access permissions must be checked
131//!
132//! ## Error Handling
133//!
134//! The domain uses a comprehensive error system that categorizes different
135//! types of failures:
136//!
137//!
138//!
139//! ## Testing Domain Logic
140//!
141//! Domain objects are designed to be easily testable:
142
143pub mod aggregates;
144pub mod entities;
145pub mod error;
146pub mod events;
147pub mod repositories;
148pub mod services;
149pub mod value_objects;
150
151// Re-export commonly used types for convenient access
152// These exports provide a clean API surface for consumers of the domain layer
153pub use entities::{Pipeline, PipelineStage, ProcessingContext, ProcessingMetrics, SecurityContext, SecurityLevel};
154pub use error::PipelineError;
155pub use events::*;
156pub use value_objects::{ChunkSize, FileChunk};