Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/atheriel/longears

The RabbitMQ client for R
https://github.com/atheriel/longears

r rabbitmq rabbitmq-client

Last synced: 3 months ago
JSON representation

The RabbitMQ client for R

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r setup, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

library(longears)

```

# longears



[![CRAN status](https://www.r-pkg.org/badges/version/longears)](https://cran.r-project.org/package=longears)

[![R-CMD-check](https://github.com/atheriel/longears/workflows/R-CMD-check/badge.svg)](https://github.com/atheriel/longears/actions)



**longears** is a fast and fully-featured RabbitMQ client for R, built on top of

the reference C library, [`librabbitmq`](https://github.com/alanxz/rabbitmq-c).



[RabbitMQ](https://www.rabbitmq.com/) itself is a highly popular, performant,

and robust open-source message broker used to build distributed systems.



**longears** implements a large portion of the Advanced Message Queuing Protocol

(AMQP) used by RabbitMQ , and the API largely reflects [the protocol itself](https://www.rabbitmq.com/amqp-0-9-1-reference.html).

However, this package is not a true low-level interface: it abstracts away many

details of AMQP for end users. See [Limitations](#Limitations) for details.



This package may be of interest to you if you wish to have R speak to your

organization's existing RabbitMQ servers; if you simply need a message queue

library, you may be better off with [**txtq**](https://cran.r-project.org/package=txtq),

[**litq**](https://cran.r-project.org/package=liteq), or the ZeroMQ package

[**rzmq**](https://cran.r-project.org/package=rzmq).



## Installation



To install **longears** as a source package you will need its system dependency,

`librabbitmq`. Normally if this library is missing during installation, the

`configure` script will attempt to download and build it directly (provided you

have `cmake` installed).



You may still wish to use your platform's provided `librabbitmq` instead,

especially if this process fails. On Debian-based systems (including Ubuntu) you

can get this library by running the following from the command line:



```shell

$ apt install librabbitmq-dev

```



For other platforms:



* macOS (via Homebrew): `brew install rabbitmq-c`

* Fedora-based: `yum install librabbitmq-devel`

* Arch-based: `pacman -S librabbitmq-c`

* Windows (via [Rtools](https://cran.r-project.org/bin/windows/Rtools/)):

  `pacman -Sy mingw-w64-{i686,x86_64}-rabbitmq-c`



**longears** is not yet available on CRAN. You can install it from GitHub with



``` r

# install.packages("remotes")

remotes::install_github("atheriel/longears")

```



## Basic Usage



If you are not already familiar with RabbitMQ and the message/queue/binding/exchange

terminology, I suggest their excellent [conceptual overview](https://www.rabbitmq.com/tutorials/amqp-concepts.html).



You will also need to have a local RabbitMQ server running with the default

settings to follow this guide.



```shell

$ # apt install rabbitmq-server

$ systemctl start rabbitmq-server

$ rabbitmqctl status

```



First, connect to the server (with the default settings):



```{r basic-connect}

conn <- amqp_connect()

conn

```



Create an exchange to route messages and a couple of queues to store them:



```{r basic-exchange}

amqp_declare_exchange(conn, "my.exchange", type = "fanout")

amqp_declare_queue(conn, "my.queue1")

amqp_declare_queue(conn, "my.queue2")

amqp_bind_queue(conn, "my.queue1", "my.exchange", routing_key = "#")

amqp_bind_queue(conn, "my.queue2", "my.exchange", routing_key = "#")

```



You can also set up a consumer for one of these queues with a callback:



```{r basic-consume}

received <- 0

consumer <- amqp_consume(conn, "my.queue2", function(msg) {

  received <<- received + 1

})

```



Now, send a few messages to this exchange:



```{r basic-publish}

amqp_publish(conn, "first", exchange = "my.exchange", routing_key = "#")

amqp_publish(conn, "second", exchange = "my.exchange", routing_key = "#")

```



Check if your messages are going into the queues:



```shell

$ rabbitmqctl list_queues

```



You can use `amqp_get()` to pull individual messages back into R:



```{r basic-get}

amqp_get(conn, "my.queue1")

amqp_get(conn, "my.queue1")

amqp_get(conn, "my.queue1")

```



Or you can use `amqp_listen()` to run consumer callbacks:



```{r basic-listen}

amqp_listen(conn, timeout = 1)

received

```



To clean things up, delete the queues, the exchange, and disconnect from the

server.



```{r basic-disconnect}

amqp_delete_queue(conn, "my.queue1")

amqp_delete_queue(conn, "my.queue2")

amqp_delete_exchange(conn, "my.exchange")

amqp_disconnect(conn)

conn

```



And check that the connection is closed:



```shell

$ rabbitmqctl list_connections

```



## Limitations



Some AMQP features are not present, notably transaction support (which there

are no plans to implement). Others are handled internally according to best

practices, even when they are not exposed through the API -- channels, message

acknowledgements, and prefetch counts are in this category. A design goal of

the package is to shield users from some details, especially if departures from

best practice are rare.



If you have need of an AMQP feature (or RabbitMQ extension) that is not

currently available or accessible, please consider filing an issue explaining

the use case you have in mind.



## License



The package is licensed under the GPL, version 2 or later.