Skip to main content

gateflow/
lib.rs

1//! `gateflow` isolates test code inside a real, unprivileged Linux network
2//! namespace — not a simulated one.
3//!
4//! Crates like [`turmoil`](https://docs.rs/turmoil) and
5//! [`madsim`](https://docs.rs/madsim) get you fast, deterministic tests by
6//! *simulating* the network in userspace. `gateflow` takes the opposite
7//! trade: real kernel network namespaces, real sockets, real `tc netem`
8//! chaos — slower, but nothing is faked. If a test passes here, it passed
9//! against the same networking stack production runs on.
10//!
11//! # Status
12//!
13//! Early and incomplete. [`Sandbox`] is the entry point: a single
14//! unprivileged network namespace with a working loopback, optional real
15//! `tc netem` chaos on it ([`Sandbox::chaos`]), or (via
16//! [`Sandbox::paired`]) two namespaces wired together by a real veth
17//! pair. The `#[gateflow::isolated_net]` attribute macro (`macros`
18//! feature, see the `gateflow-macros` companion crate) wraps a test to
19//! run inside a plain (non-chaos, non-paired) sandbox. Resource limits
20//! Optional cgroup v2 resource limits and a defense-in-depth seccomp-BPF
21//! profile are available through [`CgroupLimits`] and [`SeccompProfile`].
22//!
23//! [`Sandbox`] is a thin builder over [`netns`]/[`chaos`]/[`veth`], which
24//! stay public for direct use if you want to skip it — see their own
25//! docs for the exact mechanisms and sentinel exit codes.
26//!
27//! # Platform
28//!
29//! Linux only. Namespace isolation is a Linux kernel feature with no
30//! portable equivalent.
31
32#![warn(missing_docs)]
33
34#[cfg(not(target_os = "linux"))]
35compile_error!(
36    "gateflow only supports Linux (namespace isolation is a Linux-specific kernel feature)"
37);
38
39pub mod chaos;
40pub mod error;
41pub mod hardening;
42pub mod netns;
43pub mod sandbox;
44pub mod veth;
45
46pub use error::Error;
47pub use hardening::{CgroupLimits, SeccompProfile};
48pub use sandbox::{PairedSandbox, Sandbox};
49
50/// Wraps a test function so its body runs inside a freshly created,
51/// unprivileged network namespace instead of the host's. Requires the
52/// `macros` feature. See [`gateflow_macros::isolated_net`] for the full
53/// docs.
54#[cfg(feature = "macros")]
55pub use gateflow_macros::isolated_net;