# Instructions for AI Agents
## What is This Codebase?
This is a Rust client for the [RabbitMQ HTTP API](https://www.rabbitmq.com/docs/http-api-reference).
See [CONTRIBUTING.md](./CONTRIBUTING.md) for test running instructions and development setup.
## Build System
All the standard Cargo commands apply but with one important detail: make sure to add `--all-features` so that
both the async and blocking client are built, tested, linted, and so on.
* `cargo build --all-features` to build
* `RUSTFLAGS="-D warnings" cargo nextest run --all-features` to run tests
* `RUSTFLAGS="-D warnings" cargo clippy --all-features` to lint
* `cargo fmt` to reformat
* `cargo publish` to publish the crate
Always run `cargo check --all-features` before making changes to verify the codebase compiles cleanly.
If compilation fails, investigate and fix compilation errors before proceeding with any modifications.
## The Async and Blocking Clients
This library provides two clients:
* An async client, `rabbitmq_http_client::api::Client`, defined in `src/api/client.rs`
* A blocking client, `rabbitmq_http_client::blocking_api::BlockingClient`, defined in `src/blocking_api/client.rs`
They have very similar APIs except that all functions of the async client are, well, `async`.
## Key Files
* Async client: `src/api/*.rs`
* Blocking client: `src/blocking_api/*.rs`
* Error types: `src/error.rs`
* HTTP API request types: `src/requests/*.rs`
* HTTP API response types: `src/responses/*.rs`
* Types shared between requests and responses: `src/commons.rs`
* Definition transformations: `src/transformers.rs`
## Test Suite Layout
Tests are consolidated into three test binaries (plus the lib unit test binary) for faster compilation:
* `tests/integration/` — integration tests that require a locally running RabbitMQ node
* `async_*.rs` modules test the async client (Tokio runtime-based, uses `async` functions)
* `blocking_*.rs` modules test the blocking client (regular functions)
* `test_helpers.rs` contains helper functions shared by integration test modules
* `tests/unit/` — unit tests (`unit_*_tests.rs` modules, needs a locally running RabbitMQ node)
* `tests/proptests/` — property-based tests (of which `unit_*_proptests.rs` doesn't need a locally running RabbitMQ node)
Each directory has a `main.rs` crate root that declares all modules.
See [CONTRIBUTING.md](./CONTRIBUTING.md) for step-by-step Docker setup instructions for the local test environment.
### `nextest` Test Filters
Key [`nextest` filterset predicates](https://nexte.st/docs/filtersets/reference/):
* `test(pattern)`: matches test names using a substring (e.g. `test(list_nodes)`)
* `binary(pattern)`: matches the test binary name (e.g. `binary(integration)`, `binary(unit)`, `binary(proptests)`)
* `package(name)`: matches by package (e.g. `package(rabbitmq_http_client)`)
* `test(=exact_name)`: an exact test name match
* `test(/regex/)`: like `test(pattern)` but uses regular expression matching
* Set operations: `expr1 + expr2` (union), `expr1 - expr2` (difference), `not expr` (negation)
To run all tests in a specific module, use `cargo nextest run --all-features -E 'test(async_queue_tests::)'`.
To run only unit and property-based tests (no RabbitMQ needed): `cargo nextest run --all-features -E 'binary(unit) + binary(proptests)'`.
### Property-based Tests
Property-based tests are written using [proptest](https://docs.rs/proptest/latest/proptest/) and
use a naming convention: they begin with `prop_`.
To run the property-based tests specifically, use `cargo nextest run --all-features -E 'binary(proptests)'`.
## Source of Domain Knowledge
* [RabbitMQ HTTP API](https://www.rabbitmq.com/docs/http-api-reference)
* [RabbitMQ Documentation](https://www.rabbitmq.com/docs/)
Treat this documentation as the ultimate first party source of truth.
## Change Log
If asked to perform change log updates, consult and modify `CHANGELOG.md` and stick to its
existing writing style.
## Releases
### How to Roll (Produce) a New Release
Suppose the current development version in `Cargo.toml` is `0.N.0` and `CHANGELOG.md` has
a `## v0.N.0 (in development)` section at the top.
To produce a new release:
1. Update the changelog: replace `(in development)` with today's date, e.g. `(Feb 20, 2026)`. Make sure all notable changes since the previous release are listed
2. Update the version references in `README.md` to `0.N.0`. This must be done *before* the release commit is made and the release is tagged, so that the published version matches what users see in the README
3. Commit with the message `0.N.0` (just the version number, nothing else)
4. Tag the commit: `git tag v0.N.0`
5. Bump the dev version: back on `main`, set `Cargo.toml` version to `0.(N+1).0`
6. Add a new `## v0.(N+1).0 (in development)` section to `CHANGELOG.md` with `No changes yet.` underneath
7. Commit with the message `Bump dev version`
8. Push: `git push && git push --tags`
The tag push triggers `.github/workflows/release.yml`, which publishes the crate to crates.io
via Trusted Publishing (OIDC) and creates a GitHub Release with changelog notes. No manual
`cargo publish` needed.
### GitHub Actions
The release workflow uses [`michaelklishin/rust-build-package-release-action`](https://github.com/michaelklishin/rust-build-package-release-action).
For verifying YAML file syntax, use `yq`, Ruby or Python YAML modules (whichever is available).
## Git Commits
* Do not commit changes automatically without an explicit permission to do so
* Never add yourself as a git commit coauthor
* Never mention yourself in commit messages in any way (no "Generated by", no AI tool links, etc)