Skip to content

api-reference.md

Latest commit

 

History

History
47 lines (33 loc) · 3.99 KB

api-reference.md

File metadata and controls

47 lines (33 loc) · 3.99 KB

API Reference

Authoritative API documentation for the Rust crates lives in rustdoc, generated directly from source. This chapter explains how to produce and browse it.

Generating rustdoc locally

The whole-workspace rustdoc is built with cargo doc. The pre-push lefthook hook also runs this command, so the docs are guaranteed to compile on master.

# Build rustdoc for every workspace member without recursing into transitive deps.
cargo doc --workspace --no-deps

# Same, but also opens the index page in the default browser.
cargo doc --workspace --no-deps --open

# Document private items too — useful when working inside a single crate.
cargo doc -p aa-gateway --no-deps --document-private-items --open

The HTML output lands in target/doc/. Open target/doc/aa_core/index.html (or any other crate's index) directly if you'd rather not use --open.

Note on eBPF crates — aa-ebpf* requires a nightly toolchain to build the BPF target. CI excludes these crates from the standard build matrix and validates them in a dedicated job. For rustdoc on macOS or non-Linux machines, run cargo doc --workspace --no-deps --exclude aa-ebpf to skip them.

Per-crate API surface

Once rustdoc is built (target/doc/<crate>/index.html), the most-frequented entry points are:

Crate rustdoc entry Highlights
aa-core target/doc/aa_core/index.html Domain newtypes (AgentId, TeamId), ActionType enum, common traits
aa-proto target/doc/aa_proto/index.html Generated protobuf message types — wire format source of truth
aa-runtime target/doc/aa_runtime/index.html Tokio runtime wrapper, agent lifecycle hooks
aa-proxy target/doc/aa_proxy/index.html MitM HTTPS proxy primitives
aa-gateway target/doc/aa_gateway/index.html Policy engine, agent registry, budget tracker
aa-api target/doc/aa_api/index.html HTTP layer with utoipa-generated OpenAPI spec
aa-cli target/doc/aa_cli/index.html aasm operator binary surface (clap commands)
aa-ffi-python target/doc/aa_ffi_python/index.html PyO3 bindings — symbols exposed to Python
aa-ffi-node target/doc/aa_ffi_node/index.html napi-rs bindings — symbols exposed to Node.js
aa-ffi-go target/doc/aa_ffi_go/index.html cgo C-ABI shims for the Go SDK
aa-wasm target/doc/aa_wasm/index.html wasm-bindgen surface for in-browser embedding
conformance target/doc/conformance/index.html Cross-SDK protocol vector harness

The HTTP API (served by aa-api) additionally publishes a generated OpenAPI v1 spec. Validate the spec with npx @stoplight/spectral-cli lint openapi/v1.yaml.

Hosted documentation (deferred)

Publishing rustdoc to docs.rs and the mdBook to GitHub Pages is out of scope for v0.0.1. Both are tracked as follow-up Stories under Epic AAASM-13. Until then, run cargo doc --workspace --no-deps --open and mdbook serve docs --open locally.