aegis_resource/
lib.rs

1//! Aegis Resource Management
2//!
3//! This crate provides resource management functionality for the Aegis
4//! WebAssembly sandbox runtime, including:
5//!
6//! - Memory limiting via [`AegisResourceLimiter`]
7//! - CPU limiting via fuel management in [`FuelManager`]
8//! - Timeout management via epochs in [`EpochManager`]
9//!
10//! # Resource Management Strategy
11//!
12//! Aegis uses a multi-layered approach to resource management:
13//!
14//! 1. **Memory Limits**: Hard limits on linear memory growth
15//! 2. **Fuel Limits**: Deterministic CPU limiting via fuel consumption
16//! 3. **Epoch Timeouts**: Wall-clock timeout via epoch-based interruption
17//!
18//! ## Memory Limiting
19//!
20//! Memory limits are enforced via [`AegisResourceLimiter`], which implements
21//! Wasmtime's `ResourceLimiter` trait. This prevents guests from allocating
22//! unbounded memory.
23//!
24//! ```ignore
25//! use aegis_resource::limiter::{AegisResourceLimiter, LimiterConfig};
26//!
27//! let limiter = AegisResourceLimiter::new(
28//!     LimiterConfig::default().with_max_memory(64 * 1024 * 1024)
29//! );
30//! ```
31//!
32//! ## Fuel Limiting
33//!
34//! Fuel provides deterministic CPU limiting. Each WASM instruction consumes
35//! fuel, and execution traps when fuel is exhausted.
36//!
37//! ```ignore
38//! use aegis_resource::fuel::{FuelManager, FuelConfig};
39//!
40//! let manager = FuelManager::new(FuelConfig::new(1_000_000_000));
41//! ```
42//!
43//! ## Epoch Timeouts
44//!
45//! Epochs provide wall-clock timeout support. A background thread increments
46//! the epoch counter, and stores configured with deadlines will trap when
47//! the deadline is exceeded.
48//!
49//! ```ignore
50//! use aegis_resource::epoch::{EpochManager, EpochConfig};
51//!
52//! let manager = EpochManager::new(engine, EpochConfig::default())?;
53//! ```
54
55pub mod epoch;
56pub mod error;
57pub mod fuel;
58pub mod limiter;
59
60// Re-export main types
61pub use epoch::{EpochConfig, EpochManager, EpochStats, TimeoutGuard};
62pub use error::{ResourceError, ResourceResult};
63pub use fuel::{FuelConfig, FuelCostEstimates, FuelManager, FuelStats};
64pub use limiter::{AegisResourceLimiter, LimiterConfig, LimiterStats, MemoryGrowthEvent};
65
66/// Prelude module for convenient imports.
67pub mod prelude {
68    pub use crate::epoch::{EpochConfig, EpochManager, TimeoutGuard};
69    pub use crate::error::{ResourceError, ResourceResult};
70    pub use crate::fuel::{FuelConfig, FuelManager};
71    pub use crate::limiter::{AegisResourceLimiter, LimiterConfig};
72}
73
74#[cfg(test)]
75mod tests {
76    #[test]
77    fn test_prelude_imports() {
78        // Verify that prelude exports work
79        use crate::prelude::*;
80
81        let _config = LimiterConfig::default();
82        let _fuel = FuelConfig::default();
83        let _epoch = EpochConfig::default();
84    }
85}
aegis_resource/lib.rs

aegis_resource/
lib.rs
