refactor(netwatch)!: improve platform feature-gating and don't reexport netdev types

.github/workflows/ci.yaml

@@ -294,6 +294,33 @@ jobs:
     - name: clippy check (default features)
       run: cargo clippy --workspace --all-targets
 
+  external_types:
+    timeout-minutes: 30
+    name: Check external types
+    runs-on: ubuntu-latest
+    env:
+      RUSTC_WRAPPER: "sccache"
+      SCCACHE_GHA_ENABLED: "on"
+      # Pin to the nightly that the pinned `cargo-check-external-types`
+      # release was last tested against. Update both together, and keep the
+      # toolchain in sync with the `check-external-types` task in Makefile.toml.
+      CARGO_CHECK_EXTERNAL_TYPES_VERSION: "0.4.0"
+      TOOLCHAIN: "nightly-2025-10-18"
+    steps:
+    - uses: actions/checkout@v6
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: ${{ env.TOOLCHAIN }}
+    - name: Install sccache
+      uses: mozilla-actions/sccache-action@v0.0.9
+    - name: Install cargo-binstall
+      uses: cargo-bins/cargo-binstall@main
+    - uses: taiki-e/install-action@cargo-make
+    - name: Install cargo-check-external-types
+      run: cargo binstall cargo-check-external-types@${{ env.CARGO_CHECK_EXTERNAL_TYPES_VERSION }} --locked --no-confirm
+    - name: Check external types
+      run: cargo make check-external-types
+
   msrv:
     if: "github.event_name != 'pull_request' || ! contains(github.event.pull_request.labels.*.name, 'flaky-test')"
     timeout-minutes: 30

Makefile.toml

@@ -18,6 +18,17 @@ workspace = false
 command = "cargo"
 args = ["nextest", "run", "-p", "netwatch", "--test", "patchbay", "--profile", "patchbay", "${@}"]
 
+# Verifies netwatch does not leak unapproved external crate types (notably
+# `netdev`) through its public API. The allowlist lives in
+# `netwatch/Cargo.toml` under `[package.metadata.cargo_check_external_types]`.
+# Requires the nightly toolchain that the pinned `cargo-check-external-types`
+# release was tested against; keep both in sync with CI.
+[tasks.check-external-types]
+workspace = false
+toolchain = "${TOOLCHAIN:nightly-2025-10-18}"
+command = "cargo"
+args = ["check-external-types", "--manifest-path", "netwatch/Cargo.toml"]
+
 [tasks.format-check]
 workspace = false
 command = "cargo"

netwatch/Cargo.toml

@@ -18,6 +18,9 @@ workspace = true
 [dependencies]
 atomic-waker = "1.1.2"
 bytes = "1.7"
+# ipnet is pure arithmetic and builds everywhere, including wasm and esp-idf;
+# the `IpNet` public type uses it on every platform.
+ipnet = "2"
 n0-error = "=1.0.0-rc.0"
 n0-future = "0.3.1"
 n0-watcher = "=1.0.0-rc.0"
@@ -34,7 +37,6 @@ tracing = "0.1"
 
 # non-browser dependencies
 [target.'cfg(not(all(target_family = "wasm", target_os = "unknown")))'.dependencies]
-ipnet = "2"
 noq-udp = "=1.0.0-rc.1"
 libc = "0.2.139"
 socket2 = { version = "0.6", features = ["all"] }
@@ -108,3 +110,24 @@ cfg_aliases = { version = "0.2.1" }
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "iroh_docsrs"]
+
+# Types from these external crates are allowed to appear in netwatch's public
+# API. The list is enforced by `cargo check-external-types` (see the
+# `check-external-types` task in Makefile.toml). Notably absent is `netdev`:
+# its types must never leak, which is why the `interfaces` module mirrors them.
+[package.metadata.cargo_check_external_types]
+allowed_external_types = [
+    # IP network types used by `interfaces::IpNet`.
+    "ipnet::*",
+    # iroh-ecosystem error and reactive-state crates.
+    "n0_error::*",
+    "n0_watcher::*",
+    # UDP transmit/receive metadata used by the `udp` module.
+    "noq_udp::*",
+    # Error types surfaced by `From` impls on `netmon::Error`.
+    "tokio::sync::mpsc::error::SendError",
+    "tokio::sync::oneshot::error::RecvError",
+    # `State::last_unsuspend` is an `n0_future::time::Instant`, which resolves
+    # to tokio's `Instant` on non-wasm targets.
+    "tokio::time::instant::Instant",
+]

netwatch/build.rs

@@ -7,5 +7,11 @@ fn main() {
         wasm_browser: { all(target_family = "wasm", target_os = "unknown") },
         // Limited POSIX platforms (not wasm)
         posix_minimal: { target_os = "espidf" },
+        // Platforms where the `netdev` crate is available, i.e. everything
+        // except esp-idf and wasm-in-browser. Keep in sync with the `netdev`
+        // dependency target gate in Cargo.toml.
+        netdev: { not(any(target_os = "espidf", all(target_family = "wasm", target_os = "unknown"))) },
+        // BSD-derived platforms that share the `AF_ROUTE` routing-socket code.
+        bsd: { any(target_os = "freebsd", target_os = "openbsd", target_os = "netbsd", target_os = "macos", target_os = "ios") },
     }
 }