Skip to main content

sandboxrs_windows/
lib.rs

1//! No-admin Windows process sandbox library with a `std::process::Command`-like API.
2//!
3//! The [API guide](https://github.com/TarunKurella/sandboxrs-windows/blob/main/docs/API.md)
4//! documents stream defaults, backend selection, lifecycle behavior, and the
5//! error model.
6//!
7//! ```no_run
8//! use sandboxrs_windows::Sandbox;
9//!
10//! let sandbox = Sandbox::builder(r"C:\repo")
11//!     .read_only(r"C:\Users\me\.rustup")
12//!     .read_write(r"C:\temp\sandboxrs")
13//!     .build()?;
14//!
15//! let output = sandbox
16//!     .command("cargo")
17//!     .arg("test")
18//!     .output()?;
19//! # Ok::<(), sandboxrs_windows::SandboxError>(())
20//! ```
21
22mod backend;
23mod builder;
24mod child;
25mod command;
26mod error;
27mod filesystem;
28#[cfg(windows)]
29mod job;
30mod output;
31mod sandbox;
32
33pub use builder::SandboxBuilder;
34pub use child::SandboxChild;
35pub use command::SandboxCommand;
36pub use error::SandboxError;
37pub use output::SandboxOutput;
38pub use sandbox::{BackendProbe, BackendProbeEntry, Sandbox};
39
40/// Standard stream mode for a sandboxed command.
41///
42/// This mirrors `std::process::Stdio`, which is opaque and therefore cannot be
43/// inspected by a library after it is passed.
44#[derive(Debug, Clone, Copy, PartialEq, Eq)]
45pub enum Stdio {
46    /// Attach the corresponding standard handle inherited by the host process.
47    Inherit,
48    /// Connect the stream to `NUL`.
49    Null,
50    /// Create a parent-visible pipe for the stream.
51    Piped,
52}
53
54impl Stdio {
55    /// Inherit the host process's corresponding standard stream.
56    pub fn inherit() -> Self {
57        Self::Inherit
58    }
59
60    /// Connect the stream to `NUL`.
61    pub fn null() -> Self {
62        Self::Null
63    }
64
65    /// Create a pipe that is exposed on [`SandboxChild`].
66    pub fn piped() -> Self {
67        Self::Piped
68    }
69}
70
71/// Backend that enforces a sandboxed execution.
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
73pub enum BackendKind {
74    /// The experimental composable Windows Sandbox API.
75    WindowsSandboxApi,
76    /// A regular AppContainer profile launched with `SECURITY_CAPABILITIES`.
77    AppContainer,
78}
79
80impl BackendKind {
81    /// Stable machine-readable name.
82    pub fn as_str(self) -> &'static str {
83        match self {
84            Self::WindowsSandboxApi => "windows-sandbox-api",
85            Self::AppContainer => "appcontainer",
86        }
87    }
88
89    /// Human-readable backend name for logs and diagnostics.
90    pub fn label(self) -> &'static str {
91        match self {
92            Self::WindowsSandboxApi => "Windows Sandbox API",
93            Self::AppContainer => "AppContainer",
94        }
95    }
96}
97
98/// Backend selection preference.
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100pub enum BackendPreference {
101    /// Probe the modern API first, then use AppContainer when it is usable.
102    Auto,
103    /// Require the experimental composable Windows Sandbox API.
104    WindowsSandboxApi,
105    /// Require the AppContainer backend.
106    AppContainer,
107}
108
109/// Resource and lifecycle limits applied through the Job Object.
110#[derive(Debug, Clone, Copy, Default)]
111#[allow(dead_code)]
112pub(crate) struct ResourceLimits {
113    pub(crate) max_processes: Option<u32>,
114    pub(crate) max_memory: Option<u64>,
115}
116
117impl std::fmt::Display for BackendKind {
118    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
119        f.write_str(self.as_str())
120    }
121}