feat!: replace LabOpts with Lab::builder() pattern (#31)

Replaces LabOpts with a LabBuilder accessed via Lab::builder().
Lab::new() remains as sugar for Lab::builder().build(). TOML config
loading moves to LabBuilder::config() which stores the config and
applies it during build.

```rust
// Simple
let lab = Lab::new().await?;

// With options
let lab = Lab::builder()
    .outdir(OutDir::Exact(path))
    .label("my-test")
    .build().await?;

// From TOML config
let lab = Lab::builder()
    .outdir_from_env()
    .config(parsed_toml)
    .build().await?;
```

## Breaking changes

* Removed: `LabOpts`. Use `Lab::builder()` instead.
* Removed: `Lab::with_opts(opts)`. Use `Lab::builder().build()` with the
same chain methods.
* Removed: `Lab::from_config(cfg)`. Use
`Lab::builder().config(cfg).build()`.
* Removed: `Lab::from_config_with_builder(cfg, builder)`. Use
`Lab::builder().config(cfg).build()`.
* Added: `LabBuilder` with all the methods from LabOpts plus `.config()`
and `.build()`.
* Added: `Lab::builder()` constructor.

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Author: Frando

patchbay-cli/src/native.rs

@@ -121,7 +121,9 @@ pub async fn inspect_command(input: PathBuf, work_dir: PathBuf) -> Result<()> {
     check_caps()?;
 
     let (topo, is_sim) = load_topology_for_inspect(&input)?;
-    let lab = patchbay_runner::Lab::from_config(topo.clone())
+    let lab = patchbay_runner::Lab::builder()
+        .config(topo.clone())
+        .build()
         .await
         .with_context(|| format!("build lab config from {}", input.display()))?;
 

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

@@ -14,12 +14,11 @@ fn init() {
 #[tokio::test(flavor = "current_thread")]
 async fn udp_counter() -> anyhow::Result<()> {
     let outdir = testdir::testdir!();
-    let lab = patchbay::Lab::with_opts(
-        patchbay::LabOpts::default()
-            .outdir(patchbay::OutDir::Nested(outdir))
-            .label("udp-counter"),
-    )
-    .await?;
+    let lab = patchbay::Lab::builder()
+        .outdir(patchbay::OutDir::Nested(outdir))
+        .label("udp-counter")
+        .build()
+        .await?;
     let dc = lab.add_router("dc").build().await?;
     let sender = lab
         .add_device("sender")

patchbay-runner/src/sim/runner.rs

@@ -8,7 +8,7 @@ use std::{
 };
 
 use anyhow::{anyhow, bail, Context, Result};
-use patchbay::{config::LabConfig, Lab, LabOpts};
+use patchbay::{config::LabConfig, Lab};
 use patchbay_utils::assets::{
     parse_binary_overrides, resolve_binary_source_path, BinaryOverride, PathResolveMode,
 };
@@ -810,10 +810,11 @@ async fn execute_single_sim(
     let setup = setup_topology_summary(&setup_base, Some(&topo));
 
     // ── Build lab ────────────────────────────────────────────────────────
-    let opts = LabOpts::default()
+    let lab = Lab::builder()
         .outdir(patchbay::OutDir::Exact(run_work_dir.to_path_buf()))
-        .label(sim_name);
-    let lab = Lab::from_config_with_opts(topo, opts)
+        .label(sim_name)
+        .config(topo)
+        .build()
         .await
         .context("step=configure-lab")?;
 

patchbay/src/lab.rs

@@ -1,4 +1,4 @@
-//! High-level lab API: [`Lab`], [`LabOpts`], [`Ix`], topology types.
+//! High-level lab API: [`Lab`], [`LabBuilder`], [`Ix`], topology types.
 
 use std::{
     collections::HashMap,
@@ -20,6 +20,7 @@ use tracing::{debug, debug_span};
 
 pub use crate::qdisc::LinkLimits;
 use crate::{
+    config::LabConfig,
     core::{
         self, CoreConfig, DeviceData, DownstreamPool, NetworkCore, NodeId, RouterData,
         RA_DEFAULT_ENABLED, RA_DEFAULT_INTERVAL_SECS, RA_DEFAULT_LIFETIME_SECS,
@@ -432,7 +433,7 @@ impl LabInner {
 /// A virtual network lab running in Linux network namespaces.
 ///
 /// `Lab` is cheaply cloneable. All methods take `&self` and use interior
-/// mutability. Use [`Lab::new`] or [`Lab::with_opts`] to create a lab,
+/// mutability. Use [`Lab::new`] or [`Lab::builder()`] to create a lab,
 /// then build routers and devices with [`Lab::add_router`] and
 /// [`Lab::add_device`].
 ///
@@ -473,32 +474,33 @@ pub struct Lab {
     pub(crate) inner: Arc<LabDropGuard>,
 }
 
-/// Options for constructing a [`Lab`].
+/// Builder for constructing a [`Lab`] with custom configuration.
 ///
-/// Use the builder methods to configure output directory and label, then pass
-/// to [`Lab::with_opts`].
+/// Use [`Lab::builder()`] to obtain a `LabBuilder`, configure output directory
+/// and label with the builder methods, then call [`.build()`](LabBuilder::build)
+/// to create the lab.
 ///
 /// # Example
 /// ```no_run
-/// # use patchbay::{Lab, LabOpts, OutDir};
+/// # use patchbay::{Lab, LabBuilder, OutDir};
 /// # #[tokio::main(flavor = "current_thread")]
 /// # async fn main() -> anyhow::Result<()> {
-/// let lab = Lab::with_opts(
-///     LabOpts::default()
-///         .outdir(OutDir::Nested("/tmp/patchbay-out".into()))
-///         .label("my-test"),
-/// )
-/// .await?;
+/// let lab = Lab::builder()
+///     .outdir(OutDir::Nested("/tmp/patchbay-out".into()))
+///     .label("my-test")
+///     .build()
+///     .await?;
 /// # Ok(())
 /// # }
 /// ```
 #[derive(Default)]
-pub struct LabOpts {
+pub struct LabBuilder {
     outdir: Option<OutDir>,
     label: Option<String>,
     ipv6_dad_mode: Ipv6DadMode,
     ipv6_provisioning_mode: Ipv6ProvisioningMode,
     allow_real_root: bool,
+    config: Option<LabConfig>,
 }
 
 /// Where the lab writes event logs and state files.
@@ -563,7 +565,7 @@ impl Ipv6Profile {
     }
 }
 
-impl LabOpts {
+impl LabBuilder {
     /// Sets the output directory for event log and state files.
     pub fn outdir(mut self, outdir: OutDir) -> Self {
         self.outdir = Some(outdir);
@@ -608,13 +610,30 @@ impl LabOpts {
         self
     }
 
+    /// Loads a TOML lab configuration. The config is applied during
+    /// [`build`](Self::build), creating all routers and devices defined
+    /// in the file. Builder options (outdir, label, etc.) take precedence
+    /// over config defaults.
+    pub fn config(mut self, cfg: LabConfig) -> Self {
+        self.config = Some(cfg);
+        self
+    }
+
     /// Applies a deployment profile that sets both DAD and v6 provisioning mode.
     pub fn ipv6_profile(mut self, profile: Ipv6Profile) -> Self {
         let (dad, provisioning) = profile.modes();
         self.ipv6_dad_mode = dad;
         self.ipv6_provisioning_mode = provisioning;
         self
     }
+
+    /// Builds the [`Lab`] with the configured options.
+    ///
+    /// If a TOML [`config`](Self::config) was set, all routers and devices
+    /// defined in the config are created during build.
+    pub async fn build(self) -> Result<Lab> {
+        Lab::build(self).await
+    }
 }
 
 impl Lab {
@@ -643,26 +662,32 @@ impl Lab {
                 anyhow::bail!(
                     "refusing to run as real root (not inside a user namespace). \
                      Call patchbay::init_userns() before creating a Lab, or use \
-                     LabOpts::default().allow_real_root() to bypass this check."
+                     Lab::builder().allow_real_root() to bypass this check."
                 );
             }
         }
         Ok(())
     }
 
+    /// Returns a [`LabBuilder`] for configuring and constructing a [`Lab`].
+    pub fn builder() -> LabBuilder {
+        LabBuilder::default()
+    }
+
     /// Creates a new lab with default address ranges and IX settings.
     ///
     /// Reads `PATCHBAY_OUTDIR` from the environment for event output.
-    /// Use [`Lab::with_opts`] for explicit configuration.
+    /// Use [`Lab::builder()`] for explicit configuration.
     pub async fn new() -> Result<Self> {
-        Self::with_opts(LabOpts::default().outdir_from_env()).await
+        Self::builder().outdir_from_env().build().await
     }
 
-    /// Creates a new lab with the given options.
-    pub async fn with_opts(opts: LabOpts) -> Result<Self> {
+    /// Internal constructor used by [`LabBuilder::build`].
+    async fn build(mut opts: LabBuilder) -> Result<Self> {
         if !opts.allow_real_root {
             Self::refuse_real_root()?;
         }
+        let config = opts.config.take();
         let pid = std::process::id();
         let pid_tag = pid % 9999 + 1;
         let lab_seq = LAB_COUNTER.fetch_add(1, Ordering::Relaxed);
@@ -778,6 +803,11 @@ impl Lab {
             gw_v6: cfg.ix_gw_v6,
         });
 
+        // Apply TOML config if provided.
+        if let Some(cfg) = config {
+            lab.apply_config(cfg).await?;
+        }
+
         Ok(lab)
     }
 
@@ -822,22 +852,13 @@ impl Lab {
     /// Parses `lab.toml`, builds the network, and returns a ready-to-use lab.
     pub async fn load(path: impl AsRef<Path>) -> Result<Self> {
         let text = std::fs::read_to_string(path).context("read lab config")?;
-        let cfg: crate::config::LabConfig = toml::from_str(&text).context("parse lab config")?;
-        Self::from_config(cfg).await
-    }
-
-    /// Builds a `Lab` from a parsed config, creating all namespaces and links.
-    pub async fn from_config(cfg: crate::config::LabConfig) -> Result<Self> {
-        Self::from_config_with_opts(cfg, LabOpts::default().outdir_from_env()).await
+        let cfg: LabConfig = toml::from_str(&text).context("parse lab config")?;
+        Self::builder().outdir_from_env().config(cfg).build().await
     }
 
-    /// Builds a `Lab` from a parsed config with explicit options.
-    pub async fn from_config_with_opts(
-        cfg: crate::config::LabConfig,
-        opts: LabOpts,
-    ) -> Result<Self> {
-        let lab = Self::with_opts(opts).await?;
-
+    /// Applies a parsed TOML config to an already-built lab, creating all
+    /// routers and devices defined in the config.
+    async fn apply_config(&self, cfg: LabConfig) -> Result<()> {
         // Region latency pairs from TOML config are ignored in the new region API.
         // TODO: support regions in TOML config via add_region / link_regions.
 
@@ -865,12 +886,12 @@ impl Lab {
             for name in ready {
                 let rcfg = pending.remove(name).unwrap();
                 let upstream = {
-                    let inner = lab.inner.core.lock().unwrap();
+                    let inner = self.inner.core.lock().unwrap();
                     rcfg.upstream
                         .as_deref()
                         .and_then(|n| inner.router_id_by_name(n))
                 };
-                let mut rb = lab
+                let mut rb = self
                     .add_router(&rcfg.name)
                     .nat(rcfg.nat)
                     .ip_support(rcfg.ip_support)
@@ -953,7 +974,7 @@ impl Lab {
                         .ok_or_else(|| {
                             anyhow!("device '{}' iface '{}' missing 'gateway'", dev_name, ifname)
                         })?;
-                    let router_id = lab
+                    let router_id = self
                         .inner
                         .core
                         .lock()
@@ -999,7 +1020,7 @@ impl Lab {
             result
         };
         for dev in dev_data {
-            let mut builder = lab.add_device(&dev.name);
+            let mut builder = self.add_device(&dev.name);
             for (ifname, router_id, impair) in dev.ifaces {
                 let config = IfaceConfig::routed(router_id);
                 let config = if let Some(cond) = impair {
@@ -1015,7 +1036,7 @@ impl Lab {
             builder.build().await?;
         }
 
-        Ok(lab)
+        Ok(())
     }
 
     // ── Builder methods (sync — just populate data structures) ──────────

patchbay/src/lib.rs

@@ -241,9 +241,9 @@ pub use iface::{Iface, IfaceConfig};
 pub use ipnet::Ipv4Net;
 pub use lab::{
     ConntrackTimeouts, DefaultRegions, Firewall, FirewallConfig, FirewallConfigBuilder, IpSupport,
-    Ipv6DadMode, Ipv6Profile, Ipv6ProvisioningMode, Ix, Lab, LabOpts, LinkCondition, LinkDirection,
-    LinkLimits, Nat, NatConfig, NatConfigBuilder, NatFiltering, NatMapping, NatV6Mode, OutDir,
-    Region, RegionLink, TestGuard,
+    Ipv6DadMode, Ipv6Profile, Ipv6ProvisioningMode, Ix, Lab, LabBuilder, LinkCondition,
+    LinkDirection, LinkLimits, Nat, NatConfig, NatConfigBuilder, NatFiltering, NatMapping,
+    NatV6Mode, OutDir, Region, RegionLink, TestGuard,
 };
 pub use metrics::MetricsBuilder;
 pub use router::{Router, RouterBuilder, RouterIface, RouterPreset};

patchbay/src/router.rs

@@ -851,7 +851,7 @@ impl RouterPreset {
     /// Returns the recommended IPv6 profile for this preset.
     ///
     /// All presets return [`Ipv6Profile::Realistic`](crate::lab::Ipv6Profile). Use
-    /// [`LabOpts::ipv6_profile`](crate::LabOpts::ipv6_profile) with [`Ipv6Profile::Deterministic`](crate::lab::Ipv6Profile::Deterministic) to
+    /// [`LabBuilder::ipv6_profile`](crate::LabBuilder::ipv6_profile) with [`Ipv6Profile::Deterministic`](crate::lab::Ipv6Profile::Deterministic) to
     /// override for fast, reproducible tests.
     pub fn recommended_ipv6_profile(self) -> crate::lab::Ipv6Profile {
         crate::lab::Ipv6Profile::Realistic

patchbay/src/tests/devtools.rs

@@ -19,7 +19,11 @@ use crate::consts;
 #[ignore]
 async fn simple_lab_for_e2e() -> Result<()> {
     check_caps()?;
-    let lab = Lab::with_opts(LabOpts::default().outdir_from_env().label("e2e-test")).await?;
+    let lab = Lab::builder()
+        .outdir_from_env()
+        .label("e2e-test")
+        .build()
+        .await?;
 
     // DC router (public, no NAT).
     let dc = lab.add_router("dc").build().await?;
@@ -178,12 +182,11 @@ async fn run_sync_preserves_async_events() -> Result<()> {
     let tmp =
         std::env::temp_dir().join(format!("patchbay-test-sync-events-{}", std::process::id()));
     let _ = std::fs::create_dir_all(&tmp);
-    let lab = Lab::with_opts(
-        LabOpts::default()
-            .outdir(OutDir::Exact(tmp.clone()))
-            .label("sync-events"),
-    )
-    .await?;
+    let lab = Lab::builder()
+        .outdir(OutDir::Exact(tmp.clone()))
+        .label("sync-events")
+        .build()
+        .await?;
 
     let dc = lab.add_router("dc").build().await?;
     let dev = lab.add_device("dev").iface("eth0", dc.id()).build().await?;

patchbay/src/tests/lifecycle.rs

@@ -53,7 +53,7 @@ default_via = "eth0"
 gateway = "dc1"
 "#;
     let parsed: config::LabConfig = toml::from_str(cfg)?;
-    let lab = Lab::from_config(parsed).await?;
+    let lab = Lab::builder().config(parsed).build().await?;
     assert!(lab.device_by_name("fetcher-0").is_some());
     assert!(lab.device_by_name("fetcher-1").is_some());
     assert!(lab.device_by_name("fetcher").is_none());
@@ -231,7 +231,10 @@ async fn add_device_after_build() -> Result<()> {
 #[tokio::test(flavor = "current_thread")]
 async fn drop_guard_flushes_with_outstanding_handles() -> Result<()> {
     let outdir = testdir::testdir!();
-    let lab = Lab::with_opts(LabOpts::default().outdir(OutDir::Exact(outdir.clone()))).await?;
+    let lab = Lab::builder()
+        .outdir(OutDir::Exact(outdir.clone()))
+        .build()
+        .await?;
     let guard = lab.test_guard();
     let dc = lab.add_router("dc").build().await?;
     let dev = lab.add_device("dev").iface("eth0", dc.id()).build().await?;

patchbay/tests/vm_smoke.rs

@@ -4,7 +4,7 @@
 use std::net::{IpAddr, SocketAddr};
 
 use anyhow::{Context, Result};
-use patchbay::{Lab, LabOpts, Nat, OutDir};
+use patchbay::{Lab, Nat, OutDir};
 use testdir::testdir;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
@@ -18,12 +18,11 @@ async fn tcp_through_nat() -> Result<()> {
     let outdir = testdir!();
     eprintln!("testdir: {}", outdir.display());
 
-    let lab = Lab::with_opts(
-        LabOpts::default()
-            .outdir(OutDir::Exact(outdir.clone()))
-            .label("vm-smoke"),
-    )
-    .await?;
+    let lab = Lab::builder()
+        .outdir(OutDir::Exact(outdir.clone()))
+        .label("vm-smoke")
+        .build()
+        .await?;
 
     let dc = lab.add_router("dc").build().await?;
     let home = lab.add_router("home").nat(Nat::Home).build().await?;