![Build status](https://github.com/lulf/dove/workflows/Dove%20CI/badge.svg)
![crates.io](https://img.shields.io/crates/v/dove.svg)

# Dove - Rust AMQP 1.0 Library

Dove is an open source Rust implementation of the AMQP 1.0 OASIS standard (http://www.amqp.org/). The Advanced Message Queuing Protocol (AMQP) is an open standard for passing business messages between applications or organizations.  It connects systems, feeds business processes with the information they need and reliably transmits onward the instructions that achieve their goals. 

Dove aims to be an AMQP 1.0 implementation with the following properties:

* Low footprint - efficient memory usage and pay only for what you use.
* Portable - minimize the number of dependencies and use portable APIs.

The library supports only the basics right now: Establishing connections, creating sessions, links and sending and receiving message. Most AMQP 1.0 types have been implemented, and conversion for many Rust native types exists. Support for SASL ANONYMOUS and PLAIN.

Dove exposes two different APIs:

* An API for writing messaging applications using async rust.
* A low level connection API that allows you to send and receive frames defined as rust types.

## Examples

Client examples can be found in the [examples/](https://github.com/lulf/dove/tree/master/examples) directory. You can run them like this:

```
cargo run --example send amqp://localhost:5672/myqueue "Hello, World"
cargo run --example receive amqp://localhost:5672/myqueue
```

## Building

```
cargo build
```

## Testing

Testing uses [testcontainers-rs](https://github.com/testcontainers/testcontainers-rs) which requires docker to run:

```
RUST_LOG=info cargo test
```

## Supported features

* Async-await API for creating connections, sessions and links.
* Most of the AMQP 1.0 type system, but there are probably some edge cases that have not yet been tested.
* SASL ANONYMOUS and PLAIN
* Tested against Apache ActiveMQ Artemis, Apache Qpid Dispatch Router and Apache Qpid Broker J.

## Not supported features

See [TODO Issues](https://github.com/lulf/dove/issues?q=is%3Aissue+is%3Aopen+label%3Atodo) for a list of features that are not yet implemented.


## Modules

* types - AMQP type system with encoding and decoding
* frame_codec - AMQP frame codec utility
* convert - Convertion of rust types and AMQP types
* encoding - AMQP type encoding
* decoding - AMQP type decoding
* error - AMQP error types and error handling data types
* framing - API for frame types and encoding/decoding of frames
* transport - API for the underlying transport/network
* message - API for working with messages
* sasl - SASL handling
* conn - Low level API for sending and recieving frames on a connection
* driver - Functionality for handling most control logic.
* container - API for writing applications
* url - utilities for handling AMQP urls