From c0e790a2e325aa6b167acd8e58614acf78bdb537 Mon Sep 17 00:00:00 2001 From: Ethan Jackson Date: Mon, 10 Aug 2026 10:28:38 -0700 Subject: [PATCH 1/2] endor: satisfy clippy::manual_assert_eq under Rust 1.97 Rust 1.97 promoted clippy::manual_assert_eq to the pedantic group. The repo denies pedantic, so `cargo local` fails on current main whenever the new toolchain is in use. This commit rewrites the two `assert!(a == b)` invariants in `endor::types` as `assert_eq!`, and updates the matching `#[should_panic(expected = ...)]` test to the new panic message that `assert_eq!` emits ("assertion `left == right` failed"). The change is split out from larger in-progress work so it can land first and unblock the toolchain bump. --- src/endor/types.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/endor/types.rs b/src/endor/types.rs index 116d4ad..8cac513 100644 --- a/src/endor/types.rs +++ b/src/endor/types.rs @@ -71,7 +71,7 @@ impl Base { /// `manager::Manager::reconcile`. #[must_use] pub(crate) fn sign(&self, keypair: &ImidKeypair) -> Endor { - assert!(self.endorser == keypair.to_imid()); + assert_eq!(self.endorser, keypair.to_imid()); let issued = SystemTime::now() .duration_since(UNIX_EPOCH) @@ -146,7 +146,7 @@ impl Endor { #[cfg(test)] #[must_use] pub fn with_timestamps(&self, keypair: &ImidKeypair, issued: u64, expires: u64) -> Endor { - assert!(self.base.endorser == keypair.to_imid()); + assert_eq!(self.base.endorser, keypair.to_imid()); let mut data: proto::EndorsementData = (&self.base).into(); data.issued = issued; @@ -472,7 +472,7 @@ mod tests { } #[test] - #[should_panic(expected = "assertion failed")] + #[should_panic(expected = "assertion `left == right` failed")] fn test_sign_with_wrong_keypair_panics() { let mut fix = TestFixture::new(); From 33128ee709774d9299cc80fa3a5abf55130d02dd Mon Sep 17 00:00:00 2001 From: Ethan Jackson Date: Mon, 10 Aug 2026 10:57:50 -0700 Subject: [PATCH 2/2] Simplify README.md --- README.md | 213 +++++--------------------------------------- docs/development.md | 199 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 219 insertions(+), 193 deletions(-) create mode 100755 docs/development.md diff --git a/README.md b/README.md index 5a15ba6..c8e348c 100644 --- a/README.md +++ b/README.md @@ -1,204 +1,31 @@ # intermesh -Intermesh is a trust-based identity mesh written in Rust. Nodes exchange signed -control statements about names, addresses, and policy. Each node evaluates that -state locally to build its own view of the mesh. By bringing control to the -node, Intermesh distributes responsibility for trust across the network. +Intermesh is a research prototype from the +[NetSys Lab](https://netsys.cs.berkeley.edu/) at UC Berkeley exploring +disaggregated control in service meshes: what it takes for independently +operated meshes to interoperate across partial-trust boundaries without a +shared control plane. -Intermesh runs on Linux. Build and test on Linux to match production and CI. +Nodes exchange signed, time-bounded endorsements about names, addresses, and +policy. Each node runs a Datalog-style trust engine that derives its own local +view of the mesh from that authenticated control state, so admission, +disclosure, and peering are explicit policy rather than the implicit behavior +of a central controller. -## Getting Started +## Status -### Platform +Intermesh exists to explore a research idea, and it shows. It is not +production ready, not audited, and not meant to be deployed; interfaces, +policy semantics, and wire formats change without notice. -- Linux is required for Intermesh build and test workflows. -- Use a Linux host directly (bare metal, VM, or cloud instance), or use - Docker Desktop/Colima and run your workflow in a Linux container (mount the - repo and the Docker socket). +## Development -### Prompt-Driven Setup (especially useful on macOS/Windows) - -If you are on macOS or Windows and want an assistant to drive setup, paste this -into Claude Code (or similar). - -Budget 10-20 minutes (sometimes a touch longer) for a first run. Most of that -is unattended downloads and a cold Rust build. Several steps print nothing for -minutes at a time; that is normal, not a hang. - -```text -I need a Linux-based Intermesh dev environment on this machine. -Create the smallest reliable setup and explain each step briefly. - -Requirements: -- Intermesh tooling must run in Linux -- Docker daemon must be available -- Read this Intermesh README (where this prompt came from) first and treat it - as the source of truth -- Repo is already cloned at (ask user if no path was provided) -- Prefer manual tool install in Linux (rustup + protoc + cmake + ruby + - pkg-config + musl-tools + git + build-essential) -- If using a container: mount the repo and the Docker socket, and set - DOCKER_BUILDKIT=1 (the e2e image build requires BuildKit) -- If using a container: ensure docker CLI, buildx, and docker compose are - installed in that container -- Set LANG=C.UTF-8 and LC_ALL=C.UTF-8 before running cargo local -- Nix is optional, not required - -Please: -1) Detect host OS and choose a Linux execution path (native Linux, or Linux container/VM). -2) Give exact commands to set up dependencies. -3) Run verification commands and show pass/fail: - - docker info - - cargo --version - - cargo local -4) Warn me before any step that takes more than a few minutes, and say how - long it should take. The first cargo local runs 10-20 minutes and goes - silent for long stretches; do not report it as hung or kill it. -5) If a step fails, show likely cause and next command to run. -6) End with a short checklist of what is done vs what is still needed. -``` - -### Docker - -Docker is required for e2e tests. Install it with your distro package manager -on Linux, then confirm: - -```bash -docker info -``` - -## Setup - -### Option 1: Manual Setup (recommended) - -If you want a straightforward, roll-your-own setup, install: - -- `rustup` (then run `rustup toolchain install` in this repo) -- `protoc` -- `cmake` -- `ruby` -- `pkg-config` -- `musl-tools` -- `git` -- a C toolchain (`build-essential` on Debian/Ubuntu) -- `flock` (usually provided by `util-linux`) - -`rust-toolchain.toml` pins Rust, clippy, rustfmt, rust-analyzer, and targets. - -### Option 2: Nix + direnv - -Nix gives a reproducible dev shell with the exact toolchain and versions: - -- Install [Nix](https://nixos.org/) (the - [Determinate installer](https://github.com/DeterminateSystems/nix-installer) - is the easiest path) -- Install [direnv](https://direnv.net/) and hook it into your shell -- From repo root: `direnv allow` - -If you'd rather not manage tool versions yourself, use this. - -## Verify Your Setup - -Run the full local check: - -```bash -cargo local -``` - -This runs formatting, lint, build, unit tests, and e2e tests. - -Expect 10-20 minutes the first time. The cold Rust build and the e2e image -build take most of the time, and both go quiet for minutes at a time. Later -runs are much faster once the build cache and the e2e base image are warm. - -## Core Commands - -- `cargo build` - build the project -- `cargo test [filter]` - run unit tests; pass a filter to run just the tests - whose name matches it, e.g. `cargo test my_test_name` -- `cargo lint` - run format check, clippy, and custom lints -- `cargo local` - lint + build + unit tests + e2e tests -- `cargo all` - `local` plus perf tests and VM tests when Incus is available -- `cargo deps` - dependency freshness and vulnerability checks - -## E2E Tests - -```bash -cargo test-e2e # run all e2e tests -cargo test-e2e test_name # run a specific test -``` - -E2E tests run Docker containers on a local bridge network with binaries built -from your working tree. - -If you run inside a dev container, install `docker` CLI + buildx + compose in -that container so commands like `cargo test-e2e` and `docker compose` work. - -## VM Tests - -VM tests run intermesh across isolated local [Incus](https://linuxcontainers.org/incus/) -VMs. They run in CI, so most contributors never need a local Incus setup; -reach for them when you want guest-level network realism before pushing. - -You only need this if you plan to run VM tests locally. The Nix shell includes -the `incus` CLI, but it does not install or configure the host Incus daemon. -Your host should be able to launch the Ubuntu 24.04 cloud VM image: - -```bash -incus image info images:ubuntu/24.04/cloud --vm -incus launch images:ubuntu/24.04/cloud intermesh-incus-check --vm --ephemeral -incus delete --force intermesh-incus-check -``` - -Quick commands: +Intermesh is written in Rust and builds and tests on Linux. ```bash -cargo xtask vm-image # ensure the cached VM image exists, print its alias -cargo test-vm # run all VM tests; fails if Incus is unavailable -cargo test-vm test_name # run a specific test -cargo xtask clean-vm-images # drop cached local Intermesh VM images +cargo local # lint + build + unit tests + e2e tests +cargo all # local, plus perf and VM tests ``` -`cargo all` attempts VM tests and skips them when Incus is unavailable. - -## Local Mesh Demo - -The repo ships a small local mesh demo in `sandbox/`: - -```bash -# first run takes time -cd sandbox && docker compose up -d -``` - -See `sandbox/README.md` for what to try once it's up and running. - -## Day-to-Day Workflow - -A tight loop that works well: - -1. `cargo test [filter]` -2. `cargo lint` -3. `cargo test-e2e [filter]` -4. `cargo local` before push - -## Common Gotchas - -- **Docker daemon not reachable:** start Docker and re-run `docker info` -- **Lint fails with `invalid byte sequence in US-ASCII`:** set - `LANG=C.UTF-8 LC_ALL=C.UTF-8` -- **First e2e run is slow:** expected; the e2e base image and build cache have - to warm up. Long silent stretches are normal, so let it finish -- **VM tests skipped:** expected without a local Incus setup -- **Using a Linux dev container on macOS/Windows:** set - `CARGO_TARGET_DIR` to a container-local path to avoid host/guest target dir - conflicts (for example `export CARGO_TARGET_DIR=/tmp/intermesh-target`) - -Stuck on something platform-specific? File a GitHub issue: - - -## Next Steps - -1. Get `cargo local` passing -2. Run `cargo test-e2e` once to warm the environment -3. Bring up the `sandbox/` demo mesh -4. Pick a small issue and follow the day-to-day loop above +See [docs/development.md](docs/development.md) for environment setup, e2e and +VM test details, and the local mesh demo in `sandbox/`. diff --git a/docs/development.md b/docs/development.md new file mode 100755 index 0000000..59baabb --- /dev/null +++ b/docs/development.md @@ -0,0 +1,199 @@ +# Development Guide + +Environment setup, testing, and workflow for working on Intermesh. + +## Getting Started + +### Platform + +- Linux is required for Intermesh build and test workflows. +- Use a Linux host directly (bare metal, VM, or cloud instance), or use + Docker Desktop/Colima and run your workflow in a Linux container (mount the + repo and the Docker socket). + +### Prompt-Driven Setup (especially useful on macOS/Windows) + +If you are on macOS or Windows and want an assistant to drive setup, paste this +into Claude Code (or similar). + +Budget 10-20 minutes (sometimes a touch longer) for a first run. Most of that +is unattended downloads and a cold Rust build. Several steps print nothing for +minutes at a time; that is normal, not a hang. + +```text +I need a Linux-based Intermesh dev environment on this machine. +Create the smallest reliable setup and explain each step briefly. + +Requirements: +- Intermesh tooling must run in Linux +- Docker daemon must be available +- Read this Intermesh development guide (where this prompt came from) first + and treat it as the source of truth +- Repo is already cloned at (ask user if no path was provided) +- Prefer manual tool install in Linux (rustup + protoc + cmake + ruby + + pkg-config + musl-tools + git + build-essential) +- If using a container: mount the repo and the Docker socket, and set + DOCKER_BUILDKIT=1 (the e2e image build requires BuildKit) +- If using a container: ensure docker CLI, buildx, and docker compose are + installed in that container +- Set LANG=C.UTF-8 and LC_ALL=C.UTF-8 before running cargo local +- Nix is optional, not required + +Please: +1) Detect host OS and choose a Linux execution path (native Linux, or Linux container/VM). +2) Give exact commands to set up dependencies. +3) Run verification commands and show pass/fail: + - docker info + - cargo --version + - cargo local +4) Warn me before any step that takes more than a few minutes, and say how + long it should take. The first cargo local runs 10-20 minutes and goes + silent for long stretches; do not report it as hung or kill it. +5) If a step fails, show likely cause and next command to run. +6) End with a short checklist of what is done vs what is still needed. +``` + +### Docker + +Docker is required for e2e tests. Install it with your distro package manager +on Linux, then confirm: + +```bash +docker info +``` + +## Setup + +### Option 1: Manual Setup (recommended) + +If you want a straightforward, roll-your-own setup, install: + +- `rustup` (then run `rustup toolchain install` in this repo) +- `protoc` +- `cmake` +- `ruby` +- `pkg-config` +- `musl-tools` +- `git` +- a C toolchain (`build-essential` on Debian/Ubuntu) +- `flock` (usually provided by `util-linux`) + +`rust-toolchain.toml` pins Rust, clippy, rustfmt, rust-analyzer, and targets. + +### Option 2: Nix + direnv + +Nix gives a reproducible dev shell with the exact toolchain and versions: + +- Install [Nix](https://nixos.org/) (the + [Determinate installer](https://github.com/DeterminateSystems/nix-installer) + is the easiest path) +- Install [direnv](https://direnv.net/) and hook it into your shell +- From repo root: `direnv allow` + +If you'd rather not manage tool versions yourself, use this. + +## Verify Your Setup + +Run the full local check: + +```bash +cargo local +``` + +This runs formatting, lint, build, unit tests, and e2e tests. + +Expect 10-20 minutes the first time. The cold Rust build and the e2e image +build take most of the time, and both go quiet for minutes at a time. Later +runs are much faster once the build cache and the e2e base image are warm. + +## Core Commands + +- `cargo build` - build the project +- `cargo test [filter]` - run unit tests; pass a filter to run just the tests + whose name matches it, e.g. `cargo test my_test_name` +- `cargo lint` - run format check, clippy, and custom lints +- `cargo local` - lint + build + unit tests + e2e tests +- `cargo all` - `local` plus perf tests and VM tests when Incus is available +- `cargo deps` - dependency freshness and vulnerability checks + +## E2E Tests + +```bash +cargo test-e2e # run all e2e tests +cargo test-e2e test_name # run a specific test +``` + +E2E tests run Docker containers on a local bridge network with binaries built +from your working tree. + +If you run inside a dev container, install `docker` CLI + buildx + compose in +that container so commands like `cargo test-e2e` and `docker compose` work. + +## VM Tests + +VM tests run intermesh across isolated local [Incus](https://linuxcontainers.org/incus/) +VMs. They run in CI, so most contributors never need a local Incus setup; +reach for them when you want guest-level network realism before pushing. + +You only need this if you plan to run VM tests locally. The Nix shell includes +the `incus` CLI, but it does not install or configure the host Incus daemon. +Your host should be able to launch the Ubuntu 24.04 cloud VM image: + +```bash +incus image info images:ubuntu/24.04/cloud --vm +incus launch images:ubuntu/24.04/cloud intermesh-incus-check --vm --ephemeral +incus delete --force intermesh-incus-check +``` + +Quick commands: + +```bash +cargo xtask vm-image # ensure the cached VM image exists, print its alias +cargo test-vm # run all VM tests; fails if Incus is unavailable +cargo test-vm test_name # run a specific test +cargo xtask clean-vm-images # drop cached local Intermesh VM images +``` + +`cargo all` attempts VM tests and skips them when Incus is unavailable. + +## Local Mesh Demo + +The repo ships a small local mesh demo in `sandbox/`: + +```bash +# first run takes time +cd sandbox && docker compose up -d +``` + +See `sandbox/README.md` for what to try once it's up and running. + +## Day-to-Day Workflow + +A tight loop that works well: + +1. `cargo test [filter]` +2. `cargo lint` +3. `cargo test-e2e [filter]` +4. `cargo local` before push + +## Common Gotchas + +- **Docker daemon not reachable:** start Docker and re-run `docker info` +- **Lint fails with `invalid byte sequence in US-ASCII`:** set + `LANG=C.UTF-8 LC_ALL=C.UTF-8` +- **First e2e run is slow:** expected; the e2e base image and build cache have + to warm up. Long silent stretches are normal, so let it finish +- **VM tests skipped:** expected without a local Incus setup +- **Using a Linux dev container on macOS/Windows:** set + `CARGO_TARGET_DIR` to a container-local path to avoid host/guest target dir + conflicts (for example `export CARGO_TARGET_DIR=/tmp/intermesh-target`) + +Stuck on something platform-specific? File a GitHub issue: + + +## Next Steps + +1. Get `cargo local` passing +2. Run `cargo test-e2e` once to warm the environment +3. Bring up the `sandbox/` demo mesh +4. Pick a small issue and follow the day-to-day loop above