Rust API reference
The full Rust API reference for every crate in this workspace is generated by cargo doc --document-private-items and published alongside this book - entry point at ./api/nixfleet_proto/ (the wire-types crate; use rustdoc’s sidebar + search to reach the other workspace crates). cargo doc --no-deps doesn’t emit a workspace-root index, so any per-crate page works as a starting point.
Why a separate site
Rust’s official tool (rustdoc) is what every developer expects to read for a Rust crate. It includes everything we’d otherwise have to recreate by hand:
- Type signatures (functions, structs, enums, traits)
- Per-field and per-variant docs
- Resolved cross-references (
[SomeType]-> working link) - Source links per item
- Search index
- IDE integration via
rust-analyzer(the same content you see hovering an identifier in your editor)
The output is HTML, not Markdown - so it lives next to the mdbook book rather than inside a chapter.
Where to start
Each crate has an index.html rooted at <crate-name>/index.html. Useful starting points:
nixfleet_proto- wire types (CheckinRequest,EvaluatedTarget,ReportEvent,FleetResolved,TrustConfig). The boundary contract between agent and control plane.nixfleet_control_plane::server- the long-running TLS server: handlers, middleware, reconcile loop, state.nixfleet_control_plane::dispatch- pure dispatch decision (theDecisionenum +decide_target).nixfleet_agent::activation- agent’s realise + switch + post-switch verify pipeline.nixfleet_reconciler- the pure decision engine (verify_artifact, reconcile, action emission).
Regenerating
nix run .#docs runs cargo doc --workspace --document-private-items --no-deps, then mdbook build, then copies target/doc/ into the published site at book/api/. Idempotent.
The --document-private-items flag means internal modules and private functions show up too - important for this codebase since the line between “framework public” and “internal” doesn’t always match the pub/private boundary.