mabi_chaos/
lib.rs

1//! # mabi-chaos
2//!
3//! Chaos engineering module for the OT protocol simulator.
4//!
5//! This crate provides a **trait-based, extensible chaos engineering framework**
6//! for testing the resilience of industrial protocol clients and systems.
7//!
8//! ## Architecture
9//!
10//! The chaos module is built around several key abstractions:
11//!
12//! - **[`Fault`]**: Core trait that all fault types implement
13//! - **[`FaultContext`]**: Execution context for fault injection
14//! - **[`FaultInjector`]**: Manages fault application to requests/responses
15//! - **[`ChaosEngine`]**: Orchestrates multiple faults and schedules
16//! - **[`Middleware`]**: Transparent fault injection layer
17//!
18//! ## Fault Categories
19//!
20//! ### Network Faults ([`network`])
21//! - Latency injection (constant, uniform, normal, log-normal)
22//! - Packet loss (random, burst)
23//! - Connection disruption (disconnect, timeout, reset)
24//! - Bandwidth throttling
25//!
26//! ### Device Faults ([`device`])
27//! - Device offline simulation
28//! - Slow response injection
29//! - Corrupted data responses
30//! - State transition failures
31//!
32//! ### Protocol Faults ([`protocol`])
33//! - Malformed packets
34//! - Invalid checksums
35//! - Out-of-order responses
36//! - Timeout simulation
37//!
38//! ## Usage
39//!
40//! ### Basic Usage
41//!
42//! ```rust,ignore
43//! use mabi_chaos::prelude::*;
44//!
45//! // Create a latency fault
46//! let latency = NetworkLatencyFault::builder()
47//!     .base_ms(100)
48//!     .jitter_ms(50)
49//!     .distribution(LatencyDistribution::Normal)
50//!     .build();
51//!
52//! // Create chaos engine
53//! let engine = ChaosEngine::builder()
54//!     .add_fault("latency", latency)
55//!     .build();
56//!
57//! // Apply to a target
58//! engine.enable("latency", "device-001").await;
59//! ```
60//!
61//! ### Scheduled Chaos
62//!
63//! ```rust,ignore
64//! use mabi_chaos::prelude::*;
65//!
66//! let schedule = ChaosSchedule::builder()
67//!     .name("resilience-test")
68//!     .add_entry(ChaosEntry::builder()
69//!         .start_secs(0.0)
70//!         .duration_secs(60.0)
71//!         .fault(ChaosType::NetworkLatency { base_ms: 100, jitter_ms: 50 })
72//!         .target("modbus-*")
73//!         .build())
74//!     .build();
75//!
76//! let scheduler = ChaosScheduler::new(schedule);
77//! scheduler.start();
78//! ```
79//!
80//! ### Middleware Pattern
81//!
82//! ```rust,ignore
83//! use mabi_chaos::middleware::ChaosMiddleware;
84//!
85//! let middleware = ChaosMiddleware::new(engine);
86//!
87//! // Wrap device operations
88//! let result = middleware.wrap_read(device, point_id).await;
89//! ```
90
91// =============================================================================
92// Module Declarations
93// =============================================================================
94
95pub mod error;
96pub mod fault;
97pub mod context;
98pub mod registry;
99pub mod engine;
100pub mod middleware;
101pub mod scheduler;
102
103// Fault implementations
104pub mod network;
105pub mod device;
106pub mod protocol;
107pub mod bacnet;
108
109// Configuration and prelude
110pub mod config;
111pub mod prelude;
112
113// =============================================================================
114// Re-exports
115// =============================================================================
116
117// Error types
118pub use error::{ChaosError, ChaosResult};
119
120// Core abstractions
121pub use fault::{Fault, FaultBehavior, FaultSeverity, FaultState, FaultMetadata};
122pub use context::{FaultContext, FaultContextBuilder, RequestPhase, TargetInfo};
123pub use registry::{FaultRegistry, FaultEntry, FaultFilter};
124pub use engine::{ChaosEngine, ChaosEngineBuilder, EngineState, EngineEvent};
125pub use middleware::{ChaosMiddleware, MiddlewareConfig, MiddlewareResult};
126pub use scheduler::{
127    ChaosScheduler, ChaosSchedule, ChaosEntry, ChaosType,
128    ActiveChaos, ChaosEvent, ScheduleState,
129};
130
131// Network faults
132pub use network::{
133    NetworkLatencyFault, LatencyConfig, LatencyDistribution,
134    PacketLossFault, PacketLossConfig, BurstConfig,
135    ConnectionFault, DisconnectMode, ConnectionConfig,
136    BandwidthFault, BandwidthConfig,
137};
138
139// Device faults
140pub use device::{
141    DeviceOfflineFault, OfflineConfig, OfflinePattern,
142    SlowResponseFault, SlowResponseConfig,
143    CorruptedDataFault, CorruptionConfig, CorruptionStrategy,
144    StateTransitionFault, TransitionConfig,
145};
146
147// Protocol faults
148pub use protocol::{
149    MalformedPacketFault, MalformedConfig, MalformationType,
150    ChecksumFault, ChecksumConfig,
151    TimeoutFault, TimeoutConfig, TimeoutPattern,
152    ReorderFault, ReorderConfig,
153};
154
155// BACnet faults
156pub use bacnet::{
157    ApduFault, ApduFaultConfig, ApduFaultType,
158    ServiceFault, ServiceFaultConfig, ServiceFaultType,
159    CovFault, CovFaultConfig, CovFaultType,
160    PropertyFault, PropertyFaultConfig, PropertyFaultType,
161    SegmentationFault, SegmentationFaultConfig, SegmentationFaultType,
162};
163
164// Configuration
165pub use config::{ChaosConfig, FaultConfig, ScheduleConfig, GlobalConfig};
mabi_chaos/lib.rs

mabi_chaos/
lib.rs
