swaitsandClaude Opus 4.7
7e39781318
Passphrase-based peer rendezvous for iroh-gossip swarms over the public Mainline DHT. Two nodes that share a passphrase + application salt find each other and join the same gossip topic — no bootstrap server, no prior knowledge of peer addresses. The algorithm is a clock-free variant of HyParView-style partition healing on BEP 44 mutable items, with K-sharded slots, logical aging with random-tie eviction, vouching of up to V neighbors at age 1, and a two-layer AEAD record envelope. Full spec in PROTOCOL.md. Ships with: * 119 tests (unit / property / integration / doctest) all green * 100% mutation-testing catch rate (cargo-mutants) * cargo-fuzz harnesses for the parse surface * Kani proofs of no-UB / no-panic on crypto::epoch_of and wire::decode_entries across their full symbolic input spaces * Stateright distributed-system model: safety invariants S1 + S2 proved exhaustively for N ≤ 6, K ≤ 3; liveness witness under weak fairness * Miri green on the synchronous modules * cargo-deny + cargo-audit clean * criterion benches * Full-matrix CI (Linux + macOS + Windows × stable + MSRV 1.93.0) * Dedicated nightly lane for Miri / mutation / fuzz / Kani / Stateright Pinned iroh 0.98.x. License MIT. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
95 lines
3.2 KiB
Markdown
95 lines
3.2 KiB
Markdown
# Contributing to iroh-gossip-rendezvous
|
||
|
||
Bug reports, feature requests, and pull requests welcome.
|
||
|
||
## Developer setup
|
||
|
||
```sh
|
||
# Clone the repo.
|
||
git clone https://github.com/swaits/iroh-gossip-rendezvous
|
||
cd iroh-gossip-rendezvous
|
||
|
||
# Install the dev toolchain. Most tools are lightweight; Kani is the
|
||
# heaviest and only needed if you're running formal proofs.
|
||
cargo install --locked \
|
||
cargo-nextest \
|
||
cargo-llvm-cov \
|
||
cargo-deny \
|
||
cargo-audit \
|
||
cargo-semver-checks \
|
||
cargo-mutants \
|
||
cargo-fuzz
|
||
|
||
# Optional: Kani bounded model checker (needed only for `just kani`).
|
||
cargo install --locked kani-verifier
|
||
cargo kani setup # one-time; downloads the solver toolchain.
|
||
|
||
# Optional: just (task runner). Most distros package it; via cargo:
|
||
cargo install just
|
||
|
||
# Sanity check.
|
||
just check
|
||
```
|
||
|
||
MSRV is **1.93.0**. Newer Rust features are not allowed in the main
|
||
crate; they are allowed in `dev-dependencies` and examples only.
|
||
|
||
## Local testing
|
||
|
||
Every CI lane is replayable locally via `just`:
|
||
|
||
| Task | What it runs |
|
||
|---|---|
|
||
| `just check` | fmt check + clippy + nextest + doctests (the fast CI lane) |
|
||
| `just test` | nextest + doctests only |
|
||
| `just fmt` | apply rustfmt |
|
||
| `just clippy` | lint only |
|
||
| `just deny` | cargo-deny (licenses, advisories, bans) |
|
||
| `just audit` | cargo-audit (RUSTSEC) |
|
||
| `just semver` | cargo-semver-checks vs last published |
|
||
| `just coverage` | cargo-llvm-cov HTML report |
|
||
| `just mutants` | cargo-mutants (30–90 min) |
|
||
| `just fuzz TARGET=x` | 60s fuzz run (nightly toolchain required) |
|
||
| `just miri` | cargo-miri on sync modules (nightly) |
|
||
| `just kani` | Kani proofs (`kani` feature) |
|
||
| `just model-bfs` | Stateright BFS N=4, K=3 |
|
||
| `just model-random` | Stateright random N=20, K=3, 10⁷ steps |
|
||
| `just bench` | criterion (not a release gate) |
|
||
| `just docs` | open rustdoc locally |
|
||
| `just all` | everything, in order |
|
||
|
||
## Before you open a PR
|
||
|
||
- `just check` must pass locally.
|
||
- Add tests for new behavior. Aim for ≥90% coverage on the module you
|
||
touched; crate-wide minimum is 85%.
|
||
- If you change the wire format, the protocol spec, or public API, update
|
||
`PROTOCOL.md` / `CHANGELOG.md` / doctests as appropriate.
|
||
- If you touch the algorithmic core (`keys`, `wire`, `crypto`, `merge`,
|
||
`protocol`), re-run `just mutants` and `just kani` locally.
|
||
- Breaking API changes require `cargo-semver-checks` to flag them and a
|
||
major/minor version bump depending on the semver rules.
|
||
|
||
## Where things live
|
||
|
||
See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the module map.
|
||
|
||
- Algorithm spec: [`PROTOCOL.md`](PROTOCOL.md).
|
||
- Security posture: [`SECURITY.md`](SECURITY.md).
|
||
- API docs: run `just docs` or visit <https://docs.rs/iroh-gossip-rendezvous>.
|
||
|
||
## Style
|
||
|
||
- `rustfmt` with default config; `clippy pedantic + nursery` with the
|
||
module-level allows documented in `Cargo.toml`'s `[lints.clippy]` block.
|
||
- `unwrap_used`, `expect_used`, `panic` denied in non-test code. If you
|
||
need one, justify it with a SAFETY comment and `#[allow(...)]`.
|
||
- Keep async code in `protocol.rs` / `rendezvous.rs` / `gossip_glue.rs`.
|
||
Algorithmic core (`keys`, `wire`, `crypto`, `merge`) must stay pure —
|
||
Miri and Kani both want sync code.
|
||
|
||
## License
|
||
|
||
By contributing, you agree that your contributions will be licensed under
|
||
the [MIT license](LICENSE).
|