exp-1a-encap-v2

Imported from yz4230/exp-1a-encap-v2 (AGENTS.md). Install upstream with npx 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 with pwru, nping, bpftrace, and related packet tools.
• vagrant rsync: sync local changes into /vagrant because the Vagrant folder uses rsync.
• sudo scripts/setup_testbed.sh --reset: recreate namespaces ns1, ns2, and ns3.
• 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 in results/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.