Imported from yz4230/exp-1a-encap-v2 (
AGENTS.md). Install upstream withnpx skills add yz4230/exp-1a-encap-v2. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
This repository contains an SRv6 encapsulation measurement testbed. Keep configuration in pyproject.toml, uv.lock, and Vagrantfile. Operational code lives in scripts/: shell scripts build the Linux namespace testbed, while Python scripts parse traces and generate plots. Generated outputs belong under results/; commit only curated examples.
Build, Test, and Development Commands
uv sync --dev: install Python 3.13 dependencies and dev tools.uv run ruff check .: lint Python files.uv run ty check .: run static type checks.vagrant up: create the Ubuntu VM withpwru,nping,bpftrace, and related packet tools.vagrant rsync: sync local changes into/vagrantbecause the Vagrant folder uses rsync.sudo scripts/setup_testbed.sh --reset: recreate namespacesns1,ns2, andns3.sudo scripts/verify_encap.sh --sid-count 1 --packet-len 128: send one packet and verify SRH capture.sudo uv run scripts/run_matrix.py --out results/summary.csv: run the measurement matrix.uv run python scripts/plot_summary.py --input results/summary.csv: generate figures inresults/figures.
Run root-required scripts inside the Vagrant VM unless modifying host namespaces is intentional.
Coding Style & Naming Conventions
Python code uses 4-space indentation, type hints, pathlib.Path, and explicit argument parsing. Prefer standard CSV/path APIs over ad hoc text processing. Shell scripts should use Bash, set -euo pipefail, uppercase configuration variables, long option names, and clear validation errors.
Useful Tools
Use nping for controlled UDP packet generation, bpftrace for timing probes and map capture, and pwru to inspect where packets travel through the kernel. Prefer these inside the Vagrant VM so tooling and privileges match the expected environment.
Testing Guidelines
There is no dedicated automated test suite yet. For Python changes, run uv run ruff check . and uv run ty check .. For testbed changes, run setup_testbed.sh --reset followed by verify_encap.sh. For measurement changes, run a reduced matrix: sudo uv run scripts/run_matrix.py --sid-counts 1 --packet-lens 128 --count 10 --out results/smoke.csv.
Commit & Pull Request Guidelines
Recent commits use short, direct messages such as Improve SRv6 matrix measurement capture; prefer imperative, specific subjects. PRs should describe the measurement or tooling change, list validation commands run, and mention any generated files intentionally added under results/. Include screenshots or figure paths when plot output changes.
Security & Configuration Tips
Treat scripts that call sudo, ip netns, bpftrace, or tcpdump as privileged operations. Keep VM provisioning in Vagrantfile, and avoid committing local virtualenv, Vagrant state, or large raw traces.
