Add design documents and vcan test harness

.github/workflows/lint.yml

@@ -2,6 +2,7 @@ name: Lint
 on: push
 env:
     RUSTFLAGS: -D warnings
+    RUSTDOCFLAGS: -D warnings
     CARGO_TERM_COLOR: always
 
 jobs:
@@ -55,14 +56,16 @@ jobs:
             - name: Setup Rust toolchain
               uses: dtolnay/rust-toolchain@master
               with:
-                toolchain: stable
+                toolchain: "1.89"
                 components: clippy
             - name: Setup Rust cache
               uses: swatinem/rust-cache@v2
             - name: Build
               run: cargo build --all-targets --all-features
             - name: Clippy
               run: cargo clippy --no-deps --all-targets --all-features
+            - name: Docs
+              run: cargo doc --no-deps --document-private-items
 
     test:
         runs-on: ubuntu-latest
@@ -75,20 +78,37 @@ 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)"
                   echo "RATE=$RATE"
                   PERCENT="$(echo "($RATE * 100)/1" | bc)"
                   echo "PERCENT=$PERCENT"
                   echo "COVERAGE_PERCENT=$PERCENT" >> $GITHUB_ENV
+            # Run clippy twice - once with the 1.89 MSRV, and once with the latest stable toolchain
+            - name: Clippy
+              run: cargo clippy --no-deps --all-targets --all-features
             - name: Update coverage badge
               uses: schneegans/dynamic-badges-action@v1.7.0
               if: github.ref_name == github.event.repository.default_branch
@@ -105,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

.github/workflows/release.yml

@@ -16,9 +16,11 @@ jobs:
 
             - name: Extract Release Metadata
               shell: bash
+              env:
+                GH_TOKEN: ${{ secrets.CAN_UTILS_RS_RELEASE_TOKEN }}
               run: |
                 VERSION="$(.github/parse-manifest-key.sh Cargo.toml version)"
-                DESCRIPTION="$(.github/parse-manifest-key.sh Cargo.toml description)"
+                DESCRIPTION="$(gh repo view --json description | jq -r .description)"
                 echo "VERSION=$VERSION" >> "$GITHUB_ENV"
                 echo "DESCRIPTION=$DESCRIPTION" >> "$GITHUB_ENV"
 

Cargo.toml

@@ -3,10 +3,18 @@ resolver = "3"
 members = [
     "candumpr",
     "cangenr",
+    "vcan-fixture",
 ]
 
 [workspace.package]
 version = "0.1.0-rc0"
 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"

README.md

@@ -1,5 +1,9 @@
 # can-utils-rs
 
+![lint workflow](https://github.com/Notgnoshi/can-utils-rs/actions/workflows/lint.yml/badge.svg?event=push)
+![release workflow](https://github.com/Notgnoshi/can-utils-rs/actions/workflows/release.yml/badge.svg?event=push)
+![code coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Notgnoshi/55f3f6cae2abdc5d011d907624dfb883/raw/can-utils-rs-coverage.json)
+
 Opinionated rewrites of can-utils in Rust
 
 ## Purpose

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/candumpr-configuration.md

@@ -0,0 +1,13 @@
+# candumpr configuration
+
+**TODO**
+
+This document describes the TOML configuration file format for candumpr, covering:
+
+* File structure: top-level settings, `[defaults]`, and `[interfaces.<name>]` sections
+* All available configuration keys and their types, defaults, and valid values
+* Precedence rules: CLI flags, per-interface overrides, defaults, built-in defaults
+* List-valued options: replace (not merge) semantics
+* Interface discovery: CLI and TOML union, `any` constraints
+* Validation rules and error conditions
+* Example configurations for common deployment scenarios