# 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)
