feat!: bidirectional per-device link impairment (#12)

`set_link_condition` previously applied netem only on the device-side veth — egress from the device. Download traffic flowed through the unimpaired bridge-side veth in the router namespace. For protocols that rely on bidirectional timing (QUIC holepunching, congestion control), this produced misleading results: measured RTT was half the configured latency.

We add a `LinkDirection` enum as a third parameter to `Device::set_link_condition`. The default is `Both`, which applies the same netem qdisc to both the device-side veth (outgoing) and the bridge-side veth (incoming). `Egress` and `Ingress` are available for asymmetric scenarios like modeling a bad uplink on a good downlink. The runner's `set-link-condition` step accepts an optional `direction` field defaulting to `"both"`.

`DeviceBuilder::iface()` no longer accepts an impairment argument. Impairment is set exclusively through `set_link_condition` after build, which makes the API consistent: one method, one place to configure direction. The config/TOML path uses an internal `iface_impaired()` method to preserve build-time impairment for sim files.

The `direction_permutations` test verifies all three modes with 500ms configured latency: egress-only and ingress-only each produce ~500ms RTT, while `Both` produces ~1000ms RTT. Assertion ranges are non-overlapping (single-direction upper bound < both-direction lower bound) to prove additivity without flaking on slow CI.

## Breaking changes

* **Changed** `Device::set_link_condition(ifname, impair)` now requires a third argument: `Device::set_link_condition(ifname, impair, direction)`. Use `LinkDirection::Both` for the new default (bidirectional) or `LinkDirection::Egress` to preserve old behavior.
* **Changed** `Lab::set_link_condition(a, b, impair)` now requires a fourth argument: `Lab::set_link_condition(a, b, impair, direction)`.
* **Changed** `DeviceBuilder::iface(ifname, router, impair)` is now `DeviceBuilder::iface(ifname, router)`. Use `device.set_link_condition(ifname, impair, direction)` after `.build().await?` instead.
* **Added** `LinkDirection` enum (`Both`, `Egress`, `Ingress`) — exported from `patchbay`.
* **Added** `direction` field to `LabEventKind::LinkConditionChanged`.
* **Removed** impairment parameter from `DeviceBuilder::iface()` and `Device::add_iface()`.

Author: Frando

README.md

@@ -36,14 +36,15 @@ let home = lab
 // A device behind the home router, with a lossy WiFi link.
 let dev = lab
     .add_device("laptop")
-    .iface("eth0", home.id(), Some(LinkCondition::Wifi))
+    .iface("eth0", home.id())
     .build()
     .await?;
+dev.set_link_condition("eth0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 
 // A server in the datacenter.
 let server = lab
     .add_device("server")
-    .iface("eth0", dc.id(), None)
+    .iface("eth0", dc.id())
     .build()
     .await?;
 
@@ -224,10 +225,11 @@ let home = lab.add_router("home")
 
 // Devices
 let dev = lab.add_device("phone")
-    .iface("wlan0", home.id(), Some(LinkCondition::Wifi))
-    .iface("eth0", dc.id(), None)
+    .iface("wlan0", home.id())
+    .iface("eth0", dc.id())
     .default_via("wlan0")
     .build().await?;
+dev.set_link_condition("wlan0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 ```
 
 ### Running code in namespaces
@@ -285,7 +287,7 @@ dev.set_link_condition("wlan0", Some(LinkCondition::Manual(LinkLimits {
     loss_pct: 5.0,
     latency_ms: 100,
     ..Default::default()
-}))).await?;
+})), LinkDirection::Both).await?;
 
 // Change NAT mode at runtime
 router.set_nat_mode(Nat::Corporate).await?;

docs/guide/getting-started.md

@@ -112,7 +112,7 @@ front of the router's downstream, assigning devices private addresses and
 masquerading their traffic, like a typical home WiFi router.
 
 ```rust
-use patchbay::{Nat, LinkCondition};
+use patchbay::{Nat, LinkCondition, LinkDirection};
 
 // A datacenter router whose devices get public IPs.
 let dc = lab.add_router("dc").build().await?;
@@ -130,16 +130,17 @@ real-world impairment like packet loss, latency, and jitter.
 // A server in the datacenter, with a clean link.
 let server = lab
     .add_device("server")
-    .iface("eth0", dc.id(), None)
+    .iface("eth0", dc.id())
     .build()
     .await?;
 
 // A laptop behind the home router, over a lossy WiFi link.
 let laptop = lab
     .add_device("laptop")
-    .iface("eth0", home.id(), Some(LinkCondition::Wifi))
+    .iface("eth0", home.id())
     .build()
     .await?;
+laptop.set_link_condition("eth0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 ```
 
 At this point you have five network namespaces — the IX root, two

docs/guide/running-code.md

@@ -169,21 +169,21 @@ Modify link impairment on the fly to simulate degrading or improving
 network quality:
 
 ```rust
-use patchbay::{LinkCondition, LinkLimits};
+use patchbay::{LinkCondition, LinkDirection, LinkLimits};
 
 // Switch to a 3G-like link.
-dev.set_link_condition("wlan0", Some(LinkCondition::Mobile3G)).await?;
+dev.set_link_condition("wlan0", Some(LinkCondition::Mobile3G), LinkDirection::Both).await?;
 
 // Apply custom impairment.
 dev.set_link_condition("wlan0", Some(LinkCondition::Manual(LinkLimits {
     rate_kbit: 500,
     loss_pct: 15.0,
     latency_ms: 200,
     ..Default::default()
-}))).await?;
+})), LinkDirection::Both).await?;
 
 // Remove all impairment and return to a clean link.
-dev.set_link_condition("wlan0", None).await?;
+dev.set_link_condition("wlan0", None, LinkDirection::Both).await?;
 ```
 
 ### Changing NAT at runtime

docs/guide/testing.md

@@ -57,12 +57,12 @@ async fn tcp_through_nat() -> Result<()> {
     // Server in the datacenter, client behind NAT.
     let server = lab
         .add_device("server")
-        .iface("eth0", dc.id(), None)
+        .iface("eth0", dc.id())
         .build()
         .await?;
     let client = lab
         .add_device("client")
-        .iface("eth0", home.id(), None)
+        .iface("eth0", home.id())
         .build()
         .await?;
 

docs/guide/topology.md

@@ -109,7 +109,7 @@ router. IP addresses are assigned automatically from the router's pool.
 ```rust
 let server = lab
     .add_device("server")
-    .iface("eth0", dc.id(), None)
+    .iface("eth0", dc.id())
     .build()
     .await?;
 ```
@@ -136,11 +136,13 @@ the physical link:
 ```rust
 let phone = lab
     .add_device("phone")
-    .iface("wlan0", home.id(), Some(LinkCondition::Wifi))
-    .iface("cell0", carrier.id(), Some(LinkCondition::Mobile4G))
+    .iface("wlan0", home.id())
+    .iface("cell0", carrier.id())
     .default_via("wlan0")
     .build()
     .await?;
+phone.set_link_condition("wlan0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
+phone.set_link_condition("cell0", Some(LinkCondition::Mobile4G), LinkDirection::Both).await?;
 ```
 
 The `.default_via("wlan0")` call sets which interface carries the default
@@ -169,12 +171,13 @@ The built-in presets model common access technologies:
 | `Mobile3G` | 3% | 100 ms | 30 ms | 2 Mbit/s |
 | `Satellite` | 0.5% | 600 ms | 50 ms | 10 Mbit/s |
 
-Apply a preset when building the interface:
+Apply a preset after building the device:
 
 ```rust
 let dev = lab.add_device("laptop")
-    .iface("eth0", home.id(), Some(LinkCondition::Wifi))
+    .iface("eth0", home.id())
     .build().await?;
+dev.set_link_condition("eth0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 ```
 
 ### Custom parameters
@@ -194,8 +197,9 @@ let degraded = LinkCondition::Manual(LinkLimits {
 });
 
 let dev = lab.add_device("laptop")
-    .iface("eth0", home.id(), Some(degraded))
+    .iface("eth0", home.id())
     .build().await?;
+dev.set_link_condition("eth0", Some(degraded), LinkDirection::Both).await?;
 ```
 
 ### Runtime changes
@@ -206,10 +210,10 @@ for example switching from WiFi to a congested 3G link and verifying that
 your application adapts:
 
 ```rust
-dev.set_link_condition("eth0", Some(LinkCondition::Mobile3G)).await?;
+dev.set_link_condition("eth0", Some(LinkCondition::Mobile3G), LinkDirection::Both).await?;
 
 // Later, restore a clean link.
-dev.set_link_condition("eth0", None).await?;
+dev.set_link_condition("eth0", None, LinkDirection::Both).await?;
 ```
 
 ## Regions

docs/reference/patterns.md

@@ -59,8 +59,8 @@ interfaces on different routers:
 
 ```rust
 let device = lab.add_device("client")
-    .iface("eth0", home.id(), None)      // physical: internet traffic
-    .iface("wg0", vpn_exit.id(), None)   // tunnel: corporate traffic
+    .iface("eth0", home.id())      // physical: internet traffic
+    .iface("wg0", vpn_exit.id())   // tunnel: corporate traffic
     .default_via("eth0")                  // default route on physical
     .build().await?;
 
@@ -187,14 +187,15 @@ let wifi_router = lab.add_router("wifi").nat(Nat::Home).build().await?;
 let cell_router = lab.add_router("cell").nat(Nat::Cgnat).build().await?;
 
 let device = lab.add_device("phone")
-    .iface("eth0", wifi_router.id(), Some(LinkCondition::Wifi))
+    .iface("eth0", wifi_router.id())
     .build().await?;
+device.set_link_condition("eth0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 
 // Simulate handoff with connectivity gap
 device.link_down("eth0").await?;
 tokio::time::sleep(Duration::from_millis(500)).await;
 device.replug_iface("eth0", cell_router.id()).await?;
-device.set_link_condition("eth0", Some(LinkCondition::Mobile4G)).await?;
+device.set_link_condition("eth0", Some(LinkCondition::Mobile4G), LinkDirection::Both).await?;
 device.link_up("eth0").await?;
 
 // Assert: application reconnects within X seconds
@@ -245,7 +246,7 @@ let device = lab.add_device("client").uplink(router.id()).build().await?;
 device.set_link_condition("eth0", Some(LinkCondition::Manual(LinkLimits {
     rate_kbit: 2_000,
     ..Default::default()
-})))?;
+})), LinkDirection::Both)?;
 ```
 
 ---
@@ -336,11 +337,11 @@ Network conditions worsen over time (moving away from WiFi AP, entering tunnel
 on cellular, weather affecting satellite).
 
 ```rust
-device.set_link_condition("eth0", Some(LinkCondition::Wifi)).await?;
+device.set_link_condition("eth0", Some(LinkCondition::Wifi), LinkDirection::Both).await?;
 tokio::time::sleep(Duration::from_secs(5)).await;
-device.set_link_condition("eth0", Some(LinkCondition::WifiBad)).await?;
+device.set_link_condition("eth0", Some(LinkCondition::WifiBad), LinkDirection::Both).await?;
 tokio::time::sleep(Duration::from_secs(5)).await;
-device.set_link_condition("eth0", None).await?;  // remove impairment
+device.set_link_condition("eth0", None, LinkDirection::Both).await?;  // remove impairment
 ```
 
 ### Intermittent connectivity

patchbay-cli/tests/fixtures/counter/tests/counter.rs

@@ -23,12 +23,12 @@ async fn udp_counter() -> anyhow::Result<()> {
     let dc = lab.add_router("dc").build().await?;
     let sender = lab
         .add_device("sender")
-        .iface("eth0", dc.id(), None)
+        .iface("eth0", dc.id())
         .build()
         .await?;
     let receiver = lab
         .add_device("receiver")
-        .iface("eth0", dc.id(), None)
+        .iface("eth0", dc.id())
         .build()
         .await?;
 

patchbay-runner/src/sim/mod.rs

@@ -271,6 +271,7 @@ pub enum Step {
         interface: Option<String>,
         #[serde(alias = "impair")]
         condition: Option<toml::Value>,
+        direction: Option<patchbay::LinkDirection>,
     },
     SetDefaultRoute {
         device: String,

patchbay-runner/src/sim/steps.rs

@@ -407,8 +407,10 @@ pub(crate) async fn execute_step(state: &mut SimState, step: &Step) -> Result<()
             device,
             interface,
             condition,
+            direction,
         } => {
             let condition = parse_link_condition(condition)?;
+            let direction = direction.unwrap_or_default();
             let dev = state
                 .lab
                 .device_by_name(device)
@@ -421,7 +423,8 @@ pub(crate) async fn execute_step(state: &mut SimState, step: &Step) -> Result<()
                     .name()
                     .to_string(),
             };
-            dev.set_link_condition(&ifname, condition).await?;
+            dev.set_link_condition(&ifname, condition, direction)
+                .await?;
         }
 
         // ── set-default-route ──────────────────────────────────────────────

patchbay/examples/simple.rs

@@ -1,5 +1,5 @@
 use anyhow::Result;
-use patchbay::{Lab, LinkCondition, RouterPreset};
+use patchbay::{Lab, RouterPreset};
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
 fn main() -> Result<()> {
@@ -30,14 +30,14 @@ async fn async_main() -> Result<()> {
     // A device behind the home router, with a lossy WiFi link.
     let dev = lab
         .add_device("laptop")
-        .iface("eth0", home.id(), Some(LinkCondition::Wifi))
+        .iface("eth0", home.id())
         .build()
         .await?;
 
     // A server in the datacenter.
     let server = lab
         .add_device("server")
-        .iface("eth0", dc.id(), None)
+        .iface("eth0", dc.id())
         .build()
         .await?;