Awesome

CoAP Publish-Subscribe interface to RabbitMQ

Plug-in for the RabbitMQ broker implementing the Publish-Subscribe Broker for the Constrained Application Protocol (CoAP), which is designed for the Constrained RESTful Environments.

The REST architecture style promotes client-server operations on cacheable resources. This plug-in implements a REST API for the the Last Value Cache; a CoAP resource represents an information in the cache and (AMQP) messages represent updates of the cached information.

This is an experimental implementation of the draft-koster-core-coap-pubsub-02. Not for operational use.

The implementation is based on the Generic Erlang CoAP Client/Server. It supports the following features:

CoAP core protocol RFC 7252, including (since Erlang/OTP 19.2) the DTLS-Secured CoAP
CoAP Observe option RFC 7641
Block-wise transfers in CoAP draft-ietf-core-block-18

Interactions

Quick Introduction

RabbitMQ will listen for UDP packets on port 5683. You can use the command-line tool from libcoap, or any other CoAP client and perform all standard operations:

Discover the /ps function and available resources by GET /.well-known/core. Thr broker will return a link to the pub/sub function and a list of resources that can be accessed by the user "anonymous", or an empty list if the user "anonymous" does not exist. <pre> $ ./coap-client coap://127.0.0.1/.well-known/core </ps>;rt="core.ps",</ps/%2F/topic1>;ct=0;sz=15600 </pre> <pre> $ ./coap-client coap://127.0.0.1/.well-known/core?rt=core.ps </ps>;rt="core.ps" </pre>
Create a topic by POST /ps/vhost "<topic1>". The broker will create an x-lvc exchange named "topic1" in a given vhost. The default vhost is called "/", which must be encoded as "%2f". <pre> $ ./coap-client -m post coap://127.0.0.1/ps/%2f -e "<topic1>" </pre>
Publish to a topic by PUT /ps/vhost/topic1 "1033.3" or PUT /ps/vhost/topic1/key "1033.3". The broker will publish a message to the exchange "topic1" in a given vhost, optionally using the routing key "key". <pre> $ ./coap-client -m put coap://127.0.0.1/ps/%2f/topic1 -e "1033.3" </pre>
Get the most recent published value by GET /ps/vhost/topic1 or GET /ps/vhost/topic1/key <pre> $ ./coap-client coap://127.0.0.1/ps/%2f/topic1 1033.3 </pre>
Subscribe to a topic by GET /ps/vhost/topic1 Observe:0 or GET /ps/vhost/topic1/key Observe:0
Receive publications as 2.05 Content <pre> $ ./coap-client coap://127.0.0.1/ps/%2f/topic1 -s 10 </pre>
Remove a topic by DELETE /ps/vhost/topic1<br/> The broker will delete the exchange "topic1" in a given vhost and terminate all CoAP observers of this topic. <pre> $ ./coap-client -m delete coap://127.0.0.1/ps/%2f/topic1 </pre>

RabbitMQ Behaviour

Each CoAP topic is implemented as an RabbitMQ exchange. Subscription to a topic is implemented using a temporary RabbitMQ queue bound to that exchange.

Names of the temporary queues are composed from a prefix coap/ and IP:port of the subscriber. For example, a subscription from 127.0.0.1:40212 will be served by the queue coap/127.0.0.1:40212. Deleting this queue will forcibly terminate the observer.

All CoAP clients are authenticated as a user "anonymous". By setting RabbitMQ permissions for this user you can restrict access rights of the CoAP clients. The authenticated DTLS access is not supported (for now).

The message attributes gets converted as shown in the following table:

AMQP	CoAP
message_id (<= 8 bytes)	ETag
4 bytes of SHA(message_id)	ETag (from AMQP)
expiration [milliseconds]	Max-Age [seconds]
content_type	Content-Format

The implementation intentionally differs from the draft-02 in the following aspects:

The POST and DELETE operations are idempotent. Creating a topic that already exist causes 2.01 "Created" instead of 4.03 "Forbidden". Similarly, deleting a topic that does not exist causes 2.02 "Deleted".
Topic values are listed under .well-known/core as standard resources.

Installation

This plug-in requires the Last value caching exchange. Please make sure that both rabbitmq_lvc and rabbitmq_coap_pubsub are installed.

RabbitMQ Configuration

To enable access via the plain CoAP (without authentication) you need to create the user "anonymous" with desired access rights.

To change the default settings you may add the rabbitmq_coap_pubsub section to your RabbitMQ Configuration.

<table> <tbody> <tr> <th>Key</th> <th>Documentation</th> </tr> <tr> <td><pre>prefix</pre></td> <td> Path to the pub/sub Function. The path is defined as a list of strings; each string defines one segment of the absolute path to the resource. <br/> Default: <pre>[<<"ps">>]</pre> </td> </tr> <tr> <td><pre>udp_listen</pre></td> <td> Port for incoming coap:// requests. <br/> Default: <pre>5683</pre> </td> </tr> <tr> <td><pre>dtls_listen</pre></td> <td> Port for incoming coaps:// requests. <br/> Disabled by default. </td> </tr> <tr> <td><pre>dtls_options</pre></td> <td> Configuration of the DTLS server. Shall include at least certfile and keyfile fields. See <a href="http://erlang.org/doc/man/ssl.html">ssl_option()</a> for more details. </td> </tr> </tbody> </table>

For example:

{rabbitmq_coap_pubsub, [
    {prefix, [<<"ps">>]},
    {udp_listen, 5683},
    {dtls_listen, 5684},
    {dtls_options, [
        {certfile, "/etc/rabbitmq/cert.pem"},
        {keyfile, "/etc/rabbitmq/key.pem"}
    ]}
]}

Installation from source

Build and activate the RabbitMQ plug-in rabbitmq-coap-pubsub. See the Plugin Development Guide for more details.

$ git clone -b stable https://github.com/gotthardp/rabbitmq-coap-pubsub.git
$ cd rabbitmq-coap-pubsub
$ make dist

History

0.2.0 (Dec 22, 2015) Compatible with RabbitMQ 3.6.x and later.
0.1.0 (Nov 14, 2015) First release. Compatible with RabbitMQ 3.5.x only.

Copyright and Licensing

This package is subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/.

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.