Expand description
gateflow isolates test code inside a real, unprivileged Linux network
namespace — not a simulated one.
Crates like turmoil and
madsim get you fast, deterministic tests by
simulating the network in userspace. gateflow takes the opposite
trade: real kernel network namespaces, real sockets, real tc netem
chaos — slower, but nothing is faked. If a test passes here, it passed
against the same networking stack production runs on.
§Status
Early and incomplete. Sandbox is the entry point: a single
unprivileged network namespace with a working loopback, optional real
tc netem chaos on it (Sandbox::chaos), or (via
Sandbox::paired) two namespaces wired together by a real veth
pair. The #[gateflow::isolated_net] attribute macro (macros
feature, see the gateflow-macros companion crate) wraps a test to
run inside a plain (non-chaos, non-paired) sandbox. Resource limits
Optional cgroup v2 resource limits and a defense-in-depth seccomp-BPF
profile are available through CgroupLimits and SeccompProfile.
Sandbox is a thin builder over netns/chaos/veth, which
stay public for direct use if you want to skip it — see their own
docs for the exact mechanisms and sentinel exit codes.
§Platform
Linux only. Namespace isolation is a Linux kernel feature with no portable equivalent.
Re-exports§
pub use error::Error;pub use hardening::CgroupLimits;pub use hardening::SeccompProfile;pub use sandbox::PairedSandbox;pub use sandbox::Sandbox;
Modules§
- chaos
- Real kernel packet chaos (
tc qdisc ... netem) for a sandboxed test’s own loopback interface. - error
- Error types returned by
gateflow. - hardening
- Optional resource and syscall hardening for a sandboxed test.
- netns
- Unprivileged Linux user + network namespace creation.
- sandbox
- One coherent entry point for building a sandbox, instead of a
growing set of
fork_and_enter*/fork_veth_pairfree functions. - veth
- Real veth-pair connectivity between two sandboxed namespaces — no host
CAP_NET_ADMINrequired. See the//-NOTESblock innetns.rsfor why this needs a second namespace owned by the same user namespace rather than wiring into the host’s root netns.