ENG-4691: rustyroute cargo-fuzz target + OSS-Fuzz submission

[jimbofreedman]

ENG-4691 — cargo-fuzz target + OSS-Fuzz submission

Continuously fuzz the graph reader so malformed inputs can't panic, OOM, or segfault.

What changed

• fuzz/ — self-contained cargo-fuzz package (its own [workspace] root, so it's excluded from the root build now and if a root workspace is ever added). Two targets:
  • load_archive — feeds arbitrary bytes to Graph::from_bytes. Promotes a copy of the transient buffer to 'static, then reclaims it so RSS stays flat across libFuzzer's in-process iterations — a plain Box::leak would trip a false-positive OOM with the 411 KB seed driving -max_len up. The promoted borrow and the Graph holding it are confined to an inner scope, so neither is live when the allocation is freed.
  • route_inputs — fixed 50 km graph, fuzzes from/to/blocked composition. Arbitrary is hand-written (not derived) so the blocked-id count comes from a single u8, capping the set at 255 — an unbounded Vec<u32> would grow with fuzzer input size and surface as slow-unit/OOM false positives unrelated to route correctness.
  • Committed seed: one valid 100 km archive (411,248 B, RRG1+v1).
• .github/workflows/fuzz.yaml — nightly cargo-fuzz quick-pass: builds both targets, runs load_archive -- -max_total_time=60 per PR. Mirrors ci.yaml conventions; nightly is the sole deviation (sanitizers require it), and the gnu target is pinned because ASan is incompatible with a statically linked libc.
• oss-fuzz/projects/rustyroute/ — Dockerfile, build.sh, project.yaml for a google/oss-fuzz submission, plus a README.md runbook. Seed shipped via <target>_seed_corpus.zip. build.sh pins the same gnu triple as the CI workflow and derives its copy path from it; the Dockerfile uses absolute $SRC paths to match.
• tests/fuzz_workflow.rs — 12 durable tests locking the workflow shape, fuzz-crate structure, seed header, OSS-Fuzz file validity, and the acceptance guard that root cargo metadata excludes the fuzz package.

Verification

CI on the current head is the authoritative gate — fmt, clippy -D warnings, tests across 6 OS/toolchain combos, 3 feature rows, docs (-D warnings), coverage, pre-commit e2e, and the fuzz job that builds both targets and runs the 60s load_archive pass.

The figures below were measured locally on the pre-review tree (2a9599a). The three review-fix commits after it were verified by CI only — this dev environment has no Rust toolchain installed, so local re-runs were not possible:

• cargo fmt --all --check, cargo clippy --all-targets --all-features -- -D warnings: clean
• cargo test: 26 test binaries, 0 failures
• cargo fuzz run load_archive -- -max_total_time=30: 58,160 runs, exit 0, no crash, RSS flat
• cargo fuzz run route_inputs: clean; single-seed replay clean
• cargo metadata --format-version 1: rustyroute-fuzz absent from members and packages
• OSS-Fuzz build.sh dry-run: emits both ELF fuzzer binaries + load_archive_seed_corpus.zip

Follow-up (external, not in this PR)

Both submission prerequisites are now satisfied in-repo:

• Two maintainer contacts — project.yaml auto_ccs lists jimbo@spot-ship.com and jimbo@freedman.io.
• Public repo — spotship/rustyroute is public.

What remains is deliberately not done here: the submission PR to google/oss-fuzz (fork, copy projects/rustyroute/, validate with infra/helper.py check_build, open the PR) is left as a human follow-up by request. Approval then takes 1–3 weeks, after which the tracking link goes on ENG-4691. Runbook: oss-fuzz/README.md.

Note on validation limits. The oss-fuzz/ staging files are locked by content assertions in tests/fuzz_workflow.rs, but nothing here executes an actual OSS-Fuzz build — that needs infra/helper.py build_fuzzers/check_build against the real tooling. Worth running before opening the submission PR.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a first-class fuzzing setup to continuously harden rustyroute’s graph loading and routing APIs against malformed inputs, with both a nightly GitHub Actions quick-pass and an OSS-Fuzz submission staging area. This fits into the repo’s existing CI/testing approach by introducing workflow-structure tests that prevent the fuzzing/OSS-Fuzz scaffolding from drifting silently.

Changes:

• Introduces a standalone fuzz/ cargo-fuzz package with two libFuzzer targets (load_archive, route_inputs) plus a committed seed corpus.
• Adds a nightly GitHub Actions workflow (fuzz.yaml) to build both fuzz targets and run a bounded load_archive fuzz pass per PR.
• Stages OSS-Fuzz project files under oss-fuzz/ and adds integration tests to lock the intended repository/workflow structure.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/fuzz_workflow.rs	Adds integration tests asserting the fuzz workflow shape, fuzz-crate structure, seed header validity, OSS-Fuzz file presence, and that root cargo metadata excludes the fuzz package.
oss-fuzz/README.md	Documents how to submit the staged OSS-Fuzz project directory to google/oss-fuzz and how to validate locally.
oss-fuzz/projects/rustyroute/project.yaml	Adds OSS-Fuzz project configuration (language, contacts, engines, sanitizers).
oss-fuzz/projects/rustyroute/Dockerfile	Adds an OSS-Fuzz base-builder Rust Dockerfile that clones this repo and stages build.sh.
oss-fuzz/projects/rustyroute/build.sh	Builds fuzz targets in OSS-Fuzz and copies fuzzer binaries + seed corpus zip into $OUT.
fuzz/fuzz_targets/route_inputs.rs	Adds a structured-input fuzz target exercising Graph::route on a fixed baked-in graph.
fuzz/fuzz_targets/load_archive.rs	Adds a bytes-input fuzz target exercising Graph::from_bytes, with buffer lifetime management to avoid RSS growth across iterations.
fuzz/Cargo.toml	Defines the standalone cargo-fuzz package/workspace and declares both fuzz binaries plus dependencies.
fuzz/.gitignore	Ignores fuzz artifacts/corpora while allowing committed seed_* files.
CHANGELOG.md	Documents the new fuzzing + OSS-Fuzz scaffolding addition.
.github/workflows/fuzz.yaml	Adds the nightly cargo-fuzz workflow (build both targets, run load_archive with a time bound).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

oss-fuzz/README.md:28

• This step refers to “replace the TODO placeholder” in auto_ccs, but project.yaml doesn’t include a placeholder entry—only a TODO comment. Reword to “add” the co-maintainer address under auto_ccs.

1. Confirm the co-maintainer email and replace the `TODO` placeholder in
   `project.yaml` `auto_ccs`.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

fuzz/fuzz_targets/load_archive.rs:19

• Graph::from_bytes takes &'static [u8] because Graph stores that slice internally (see src/loader.rs:179-187). Creating a &'static [u8] from a freshly allocated buffer and then freeing it at the end of the iteration violates the 'static contract and can be UB even if the reference is scoped (the compiler may assume 'static data remains valid for the program lifetime). This can make the fuzz target produce misleading results.

To keep RSS flat without unsound lifetime extension, reuse a single process-lifetime buffer with fixed capacity (never reallocated) and copy/truncate each input into it before calling from_bytes.

fuzz_target!(|data: &[u8]| {
    // `Graph::from_bytes` takes `&'static [u8]`. Promote a copy of the
    // transient fuzz buffer to `'static`, then reclaim it after use so RSS
    // stays flat across libFuzzer's many in-process iterations. A plain
    // `Box::leak` would accumulate one copy per iteration and — with the
    // large committed seed driving `-max_len` up — climb toward
    // `-rss_limit_mb` and trip a false-positive OOM crash.
    let ptr = Box::into_raw(data.to_vec().into_boxed_slice());

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

fuzz/fuzz_targets/load_archive.rs:34

• Same issue here: referencing src/loader.rs:<line> in a SAFETY comment will go stale. Point at the enum variant/type name (and optionally the module) instead of a line number.

    // SAFETY: a `Graph` holds only `GraphBacking::Static(&'static [u8])`
    // (src/loader.rs:167) — a borrow, not an owner — and both it and `leaked`
    // went out of scope above, so no reference into `ptr` survives.
    // Reconstructing the `Box` to free it is sound.