Crate turmoil_net 

Deterministic network simulation for turmoil.

turmoil-net is a simulated socket stack. Production code imports tokio::net; tests swap the import for shim::tokio::net and run the same code against a fully deterministic network.

The crate README has the motivation and code examples. The module list below is a map of the code:

• shim — drop-in replacements for tokio::net types. Production code changes one import and runs unchanged.
• fixture — batteries-included scheduler + runtime for the common shapes (fixture::lo single-host, fixture::ClientServer multi-host). Start here; drop to the primitives when you outgrow them.
• Net / EnterGuard — the primitives the fixtures are built on. Build a topology with Net::add_host, install it with Net::enter, drive the fabric with EnterGuard::egress_all / EnterGuard::evaluate / EnterGuard::deliver.
• Rule / Verdict / rule — packet-level fault injection. Rules see every non-loopback packet and decide Pass / Deliver (with optional delay) / Drop.
• netstat — Linux-style socket snapshot for debugging a test.

Modules

fixture

Batteries-included test fixtures.

shim

Drop-in replacements for tokio::net types. Production code imports these behind a #[cfg] in tests and compiles unchanged; every type, method, and error kind mirrors tokio::net exactly.

Structs

EnterGuard

HostId

KernelConfig

Tunable limits for a host’s network stack (MTU, buffer caps, backlog, retransmit thresholds). Constructed via Self::default and adjusted with the builder-style setters. Pass to Net::with_config to apply to every host added afterwards.

Latency

A rule that delays every packet by a fixed duration.

Net

Netstat

NetstatEntry

Packet

An IP-layer packet. UDS lives outside this model — Unix sockets bypass the network stack and deliver socket-to-socket.

RuleGuard

RAII handle for a rule installed via rule or EnterGuard::rule. Drop uninstalls the rule; RuleGuard::forget leaks it instead, leaving the rule installed for the rest of the simulation.

RuleId

Handle returned by every installer. The RuleId is stable for the life of the rule — uninstalling twice is a no-op.

TcpFlags

TCP control flags.

TcpSegment

TCP segment. Fields mirror what a real kernel needs for state-machine decisions; anything not listed here (urgent pointer, options beyond MSS, checksum) is intentionally omitted.

UdpDatagram

UDP datagram — (src_port, dst_port, payload). Addresses live on the enclosing Packet.

Enums

NetstatState

Renderable TCP state. Mirrors the state names Linux netstat prints (LISTEN, SYN_SENT, ESTABLISHED, …).

Proto

Transport

Transport-layer payload of a Packet.

Verdict

What should happen to a packet.

Traits

Rule

Decides the fate of each packet the fabric sees.

ToIpAddr

A value that resolves to a single IpAddr against the installed Net’s name table. Hostnames are allocated from 192.168.0.0/16 on first sight (idempotent on reuse); IP literals pass through. Implemented for string-like types and the IP types themselves.

ToIpAddrs

A value that resolves to zero or more IpAddrs. Blanket impl for every ToIpAddr.

Functions

lookup_host

Resolve name against the installed Net’s DNS. Returns None if there is no Net installed, or if the name isn’t registered and can’t be parsed as an IP literal.

netstat

Snapshot a host’s socket table, Linux netstat-style. host accepts a hostname (resolved via DNS like Net::add_host) or a literal IP. Panics if no Net is installed, or if the address doesn’t match a registered host. Loopback isn’t routable on its own — pass a hostname or the host’s configured IP.

rule

Install a rule and return a guard that uninstalls it on drop. Callable from any task inside an installed Net. Panics if no Net is installed.

set_current

Pin which host subsequent sys calls (i.e. socket syscalls from the caller’s task) talk to.