A Rust Client for the RabbitMQ HTTP API

This is a Rust client for the RabbitMQ HTTP API.

This is not an AMQP 0-9-1 client (see amqprs), an AMQP 1.0 client (see fe2o3-amqp) or RabbitMQ Stream protocol client library.

Project Maturity

This library is relatively young, breaking API changes are possible.

Dependency

Blocking Client

rabbitmq_http_client = { version = "0.15.0", features = ["core", "blocking"] }

Async Client

rabbitmq_http_client = { version = "0.15.0", features = ["core", "async"] }

Blocking Client with Tabled Support

rabbitmq_http_client = { version = "0.15.0", features = ["core", "blocking", "tabled"] }

Async CLient with Tabled Support

rabbitmq_http_client = { version = "0.15.0", features = ["core", "async", "tabled"] }

Usage

Overview

This library offers two client implementations: a blocking one and an async one, in rabbitmq_http_client::blocking_api and rabbitmq_http_client::api, respectively.

Both API versions and tabled support are optional features.

Code Examples

Documentation for async API follows that of the blocking API.

Blocking API

The examples below do not cover the entire API. Most ``

Instantiate a Client

use rabbitmq_http_client::blocking_api::ClientBuilder;

// a type alias for convenience
type APIClient<'a> = Client<&'a str, &'a str, &'a str>;

let endpoint = "http://localhost:15672/api";
let username = "username";
let password = "password";

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

// list cluster nodes
let _ = rc.list_nodes();

// list user connections
let _ = rc.list_connections();

// fetch information and metrics of a specific queue
let _ = rc.get_queue_info("/", "qq.1");

List Cluster Nodes

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

let _ = rc.list_nodes();

List Client Connections

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

let _ = rc.list_connections();

Fetch Metrics of a Specific Queue or Stream

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

// fetch information and metrics of a specific queue or stream
let _ = rc.get_queue_info("/", "qq.1");

Async API

Instantiate a Client

use rabbitmq_http_client::api::ClientBuilder;

// a type alias for convenience
type APIClient<'a> = Client<&'a str, &'a str, &'a str>;

let endpoint = "http://localhost:15672/api";
let username = "username";
let password = "password";
let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

List Cluster Members

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

rc.list_nodes().await;

List Client Connections

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

rc.list_connections().await;

Fetch Metrics of a Specific Queue or Stream

let rc = ClientBuilder::new().with_endpoint(&endpoint).with_basic_auth_credentials(&username, &password).build();

rc.get_queue_info("/", "qq.1").await;

TLS Support

This client library was designed to make very few assumptions about how the underlying HTTP client, reqwest, is set up, in particular when it comes to TLS and crypto.

To use TLS connections to the HTTP API, use the ClientBuilder interface in reqwest to configure TLS, then combine the constructed client with this library's blocking_api::ClientBuilder or api::ClientBuilder's with_client function:

use reqwest::blocking::Client as HTTPClient;

// this is reqwest's `ClientBuilder`
let mut b = HTTPClient::builder()
    .user_agent("my-app")
    .min_tls_version(reqwest::tls::Version::TLS_1_2)
    .danger_accept_invalid_certs(false)
    .danger_accept_invalid_hostnames(false);

// add a CA certificate bundle file to the list of trusted roots
// for x.509 peer verification
b.add_root_certificate(ca_certificate_path);

let httpc = b.build()
let username = "example";
let password = "ex4mple $eKr37;

// make sure the endpoint uses TLS and the correct port for TLS-enabled connections
let endpoint = "https://example.domain:15671/api"

// this is this library's `ClientBuilder`
let client = ClientBuilder::new()
    .with_endpoint(endpoint)
    .with_basic_auth_credentials(username, password)
    // pass in the pre-configured HTTP client
    .with_client(httpc)
    .build();

This design decision means that with this HTTP API client, it's up to the user to make some key TLS-related choices, for example, what certificate store to use for x.509 peer verification, what the acceptable minimum TLS version should be, and so on.

Defaults

By default this client will use native-tls.

This means that the default list of trusted CA certificates (roots) is managed via the OS-specific mechanisms such as the Keychain on macOS or the local openssl version and its standard directories for trusted (root) CA certificates.

License

This crate, rabbitmq-http-api-client-rs, is dual-licensed under the Apache Software License 2.0 and the MIT license.