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}