isolate_integration/lib.rs
1//! # Isolate Integration
2//!
3//! A Rust interface for the [ioi/isolate](https://github.com/ioi/isolate) sandbox program,
4//! providing secure process isolation with resource limits and control.
5//!
6//! This crate uses the `tokio` async runtime to manage sandbox lifecycle and execute commands.
7//!
8//! ## Prerequisites
9//!
10//! You must have `isolate` installed on your system. See the
11//! [ioi/isolate repository](https://github.com/ioi/isolate) for installation instructions.
12//!
13//! For cgroup-related features (recommended, such as `--cg-mem` option), ensure your system
14//! supports cgroup v2.
15//!
16//! ## Quick Start
17//!
18//! ```no_run
19//! use isolate_integration::{IsolateSandbox, ResourceLimits};
20//!
21//! #[tokio::main]
22//! async fn main() -> anyhow::Result<()> {
23//! // Create a sandbox with cgroup enabled by default
24//! let sandbox = IsolateSandbox::new(0)
25//! .with_stdin("input.txt")
26//! .with_stdout("output.txt")
27//! .with_stderr("error.txt");
28//!
29//! // Set resource limits
30//! let limits = ResourceLimits::new()
31//! .with_time_limit(1.0) // 1 second CPU time limit
32//! .with_cg_memory_limit(64 * 1024) // 64 MB memory limit
33//! .with_process_limit(1); // Allow only 1 process
34//!
35//! // Initialize the sandbox
36//! sandbox.init(&limits).await?;
37//!
38//! // Run a command
39//! let result = sandbox.run("echo", ["Hello, World!"], &limits).await?;
40//!
41//! println!("Exit code: {:?}", result.exit_code);
42//! println!("Time: {:.3}s", result.time_used);
43//! println!("Memory: {} KB", result.cg_memory_used.unwrap_or(0));
44//!
45//! // Cleanup
46//! sandbox.cleanup().await?;
47//!
48//! Ok(())
49//! }
50//! ```
51//!
52//! ## Features
53//!
54//! - **Resource Control**: Set limits on CPU time, memory, processes, and file operations
55//! - **Directory Binding**: Mount external directories into the sandbox with fine-grained permissions
56//! - **Environment Management**: Control environment variables passed to sandboxed processes
57//! - **I/O Redirection**: Redirect stdin, stdout, and stderr to files
58//! - **Cgroup Support**: Leverage cgroup v2 for precise resource control
59//! - **Async/Await**: Built on tokio for efficient async operations
60//!
61//! For more examples and detailed documentation, see the
62//! [repository README](https://github.com/yourusername/isolate-integration).
63
64pub mod sandbox;
65
66// Re-export commonly used types
67pub use sandbox::{
68 DirectoryOptions, DirectoryRule, EnvRule, ExecutionResult, IsolateSandbox, ResourceLimits,
69 SpecialOptions,
70};