Smoke test vcan creation in GitHub CI

Author: Notgnoshi

.github/workflows/lint.yml

@@ -78,13 +78,27 @@ jobs:
                 components: llvm-tools-preview
             - name: Setup Rust cache
               uses: swatinem/rust-cache@v2
+            - name: Setup vcan
+              id: vcan
+              run: |
+                  # Ubuntu 24.04 restricts unprivileged user namespaces via AppArmor.
+                  # The vcan-fixture crate needs user namespaces to create isolated vcan
+                  # interfaces without root.
+                  sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 2>/dev/null || true
+                  sudo apt-get install -y linux-modules-extra-"$(uname -r)" && \
+                      sudo modprobe vcan && \
+                      echo "available=true" >> "$GITHUB_OUTPUT" || true
             - name: Setup nextest
               uses: taiki-e/install-action@v2
               with:
                 tool: cargo-nextest,cargo-llvm-cov
             - name: Test
+              run: cargo llvm-cov --no-report nextest --all-features --no-tests=warn
+            - name: Test (vcan)
+              if: steps.vcan.outputs.available == 'true'
+              run: cargo llvm-cov --no-report nextest --all-features --run-ignored ignored-only
+            - name: Coverage report
               run: |
-                  cargo llvm-cov --no-report nextest --all-features --no-tests=warn
                   cargo llvm-cov report --cobertura --output-path coverage.xml
                   head coverage.xml
                   RATE="$(grep -o -m 1 -P '(?<=line-rate=").*?(?=")' coverage.xml | head -1)"
@@ -111,3 +125,16 @@ jobs:
                 valColorRange: ${{ env.COVERAGE_PERCENT }}
                 minColorRange: 40
                 maxColorRange: 65
+
+    # Canary job: verifies vcan is available on the runner. Shows yellow when the
+    # linux-modules-extra package drifts from the runner kernel version, which means the socketcan
+    # tests in the test job are being silently skipped.
+    vcan-available:
+        runs-on: ubuntu-latest
+        continue-on-error: true
+        steps:
+            - name: Setup vcan
+              run: |
+                  sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 2>/dev/null || true
+                  sudo apt-get install -y linux-modules-extra-"$(uname -r)"
+                  sudo modprobe vcan

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "3"
 members = [
     "candumpr",
     "cangenr",
+    "vcan-fixture",
 ]
 
 [workspace.package]
@@ -11,3 +12,9 @@ edition = "2024"
 license = "MIT"
 rust-version = "1.89"
 description = "Opinionated rewrites of can-utils in Rust"
+
+[workspace.dependencies]
+ctor = "0.6"
+eyre = "0.6"
+libc = "0.2"
+neli = "0.7"

candumpr/Cargo.toml

@@ -6,4 +6,12 @@ license.workspace = true
 rust-version.workspace = true
 description = "Log CAN traffic from multiple networks"
 
+[features]
+ci = []
+
 [dependencies]
+
+[dev-dependencies]
+ctor.workspace = true
+libc.workspace = true
+vcan-fixture = { path = "../vcan-fixture" }

candumpr/tests/smoke.rs

@@ -0,0 +1,96 @@
+use std::ffi::CString;
+use std::{io, mem, ptr};
+
+use vcan_fixture::VcanHarness;
+
+#[ctor::ctor]
+fn setup() {
+    vcan_fixture::enter_namespace();
+}
+
+/// Verify that we can receive CAN frames from multiple vcan interfaces. This is the basic
+/// operation that candumpr needs to perform.
+#[test]
+#[cfg_attr(feature = "ci", ignore = "requires vcan")]
+fn recv_frames_from_multiple_interfaces() {
+    let vcans = VcanHarness::new(2).unwrap();
+
+    #[repr(C)]
+    struct CanFrame {
+        can_id: u32,
+        len: u8,
+        _pad: u8,
+        _res0: u8,
+        _len8_dlc: u8,
+        data: [u8; 8],
+    }
+
+    // Send one frame on each interface and verify we can receive it on a separate socket.
+    for (i, iface) in vcans.names().iter().enumerate() {
+        let name_c = CString::new(iface.as_str()).unwrap();
+        let ifindex = unsafe { libc::if_nametoindex(name_c.as_ptr()) };
+        assert!(ifindex > 0, "interface {iface} not found");
+
+        let mut addr: libc::sockaddr_can = unsafe { mem::zeroed() };
+        addr.can_family = libc::AF_CAN as u16;
+        addr.can_ifindex = ifindex as i32;
+
+        // Separate tx and rx sockets. vcan delivers frames to all sockets bound to the
+        // interface except the sender.
+        let tx = unsafe { libc::socket(libc::PF_CAN, libc::SOCK_RAW, libc::CAN_RAW) };
+        let rx = unsafe { libc::socket(libc::PF_CAN, libc::SOCK_RAW, libc::CAN_RAW) };
+        assert!(tx >= 0, "tx socket: {}", io::Error::last_os_error());
+        assert!(rx >= 0, "rx socket: {}", io::Error::last_os_error());
+
+        for fd in [tx, rx] {
+            let ret = unsafe {
+                libc::bind(
+                    fd,
+                    ptr::from_ref(&addr).cast::<libc::sockaddr>(),
+                    mem::size_of::<libc::sockaddr_can>() as u32,
+                )
+            };
+            assert_eq!(ret, 0, "bind to {iface}: {}", io::Error::last_os_error());
+        }
+
+        // Use a different source address per interface so we can verify which frame we got.
+        let sa = i as u8;
+        let frame = CanFrame {
+            can_id: 0x18FECA00 | (sa as u32) | libc::CAN_EFF_FLAG,
+            len: 3,
+            _pad: 0,
+            _res0: 0,
+            _len8_dlc: 0,
+            data: [0xAA, 0xBB, sa, 0, 0, 0, 0, 0],
+        };
+
+        let written = unsafe {
+            libc::write(
+                tx,
+                ptr::from_ref(&frame).cast::<libc::c_void>(),
+                mem::size_of::<CanFrame>(),
+            )
+        };
+        assert_eq!(written as usize, mem::size_of::<CanFrame>());
+
+        let mut recv_frame: CanFrame = unsafe { mem::zeroed() };
+        let read = unsafe {
+            libc::read(
+                rx,
+                ptr::from_mut(&mut recv_frame).cast::<libc::c_void>(),
+                mem::size_of::<CanFrame>(),
+            )
+        };
+        assert_eq!(read as usize, mem::size_of::<CanFrame>());
+        assert_eq!(
+            recv_frame.can_id,
+            0x18FECA00 | (sa as u32) | libc::CAN_EFF_FLAG
+        );
+        assert_eq!(&recv_frame.data[..3], &[0xAA, 0xBB, sa]);
+
+        unsafe {
+            libc::close(tx);
+            libc::close(rx);
+        }
+    }
+}

docs/design/05-testing-strategy.md

@@ -0,0 +1,87 @@
+# Testing strategy
+
+## Status
+
+**DRAFT**
+
+## Scope
+
+This document specifies how candumpr (and other tools in this workspace) are tested, given that they
+depend on Linux socketcan interfaces that require either real hardware or elevated permissions to
+create.
+
+## Problem
+
+candumpr interacts directly with CAN sockets. Testing requires CAN interfaces, but:
+
+* Real CAN hardware is not available in CI.
+* Virtual CAN (vcan) interfaces require `CAP_NET_ADMIN` to create.
+* vcan interfaces are system-global resources, so parallel tests using shared interfaces cause
+  interference.
+* Tests must run in CI (GitHub Actions) and locally without requiring root.
+
+## Solution: user + network namespaces
+
+Each test process enters its own isolated Linux network namespace using
+`unshare(CLONE_NEWUSER | CLONE_NEWNET)`. Inside the namespace, the process has `CAP_NET_ADMIN`
+without real root privileges, vcan interfaces are private and isolated, and everything is cleaned up
+when the process exits. See the [vcan-fixture](../../vcan-fixture/) crate for the implementation.
+
+Constraint: `unshare(CLONE_NEWUSER)` requires a single-threaded process. The Rust test harness is
+multi-threaded, so namespace entry happens in a `ctor` constructor before `main()`.
+
+## Test tiers
+
+### Unit tests
+
+No sockets, no namespaces. Config parsing, filter compilation, output formatting, filename template
+expansion, duration/size parsing.
+
+### Integration tests
+
+Run inside user + network namespaces with vcan interfaces. Socket binding, filter application,
+multi-interface capture, file rotation, ZSTD streaming, address claim, device resilience.
+
+### End-to-end tests
+
+Run the actual binary inside a network namespace. Launch candumpr, send frames with cangenr, verify
+output files, signal handling, config file loading.
+
+## CI
+
+Tests that require vcan use `#[cfg_attr(feature = "ci", ignore = "requires vcan")]`. In CI,
+`--all-features` enables the `ci` feature, making them `#[ignore]`. They are then run as a separate
+step gated on whether vcan setup succeeded:
+
+A separate canary job (`vcan-available`) with `continue-on-error: true` shows yellow when the vcan
+module is unavailable on the runner, rather than silently skipping the tests.
+
+See [lint.yml](/.github/workflows/lint.yml) for the implementation.
+
+## Benchmarking
+
+Benchmarks compare candumpr against candump on 4 vcan interfaces with J1939 traffic.
+
+### Metrics
+
+* **Frame loss** (primary): frames sent vs. frames in output
+* **Throughput ceiling**: send rate at which frames start dropping
+* **CPU usage**: total CPU time (user + system)
+* **Memory usage**: peak RSS
+
+### Simulating the target environment
+
+The target is a ~4 core ~1 GHz ARM CPU. Use `taskset` to pin benchmarks to 4 cores:
+
+```sh
+taskset -c 0-3 cargo bench
+```
+
+Core count is the important variable for comparing architecture options (dedicated thread pairs vs.
+shared threads). Clock speed matters less for relative comparison. Final validation must happen on
+real target hardware.
+
+### Acceptance criteria
+
+candumpr must not drop frames at the realistic J1939 rate (2000 frames/s per interface, 8000
+frames/s aggregate). At higher rates, candumpr should drop fewer frames than candump.

vcan-fixture/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "vcan-fixture"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+description = "Build vcan interfaces in isolated network namespaces"
+
+[features]
+ci = []
+
+[dependencies]
+ctor.workspace = true
+eyre.workspace = true
+libc.workspace = true
+neli.workspace = true