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
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 byGET /.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.$ ./coap-client coap://127.0.0.1/.well-known/core </ps>;rt="core.ps",</ps/%2F/topic1>;ct=0;sz=15600
$ ./coap-client coap://127.0.0.1/.well-known/core?rt=core.ps </ps>;rt="core.ps"
- 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".$ ./coap-client -m post coap://127.0.0.1/ps/%2f -e "<topic1>"
- Publish to a topic by
PUT /ps/vhost/topic1 "1033.3"
orPUT /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".$ ./coap-client -m put coap://127.0.0.1/ps/%2f/topic1 -e "1033.3"
- Get the most recent published value by
GET /ps/vhost/topic1
orGET /ps/vhost/topic1/key
$ ./coap-client coap://127.0.0.1/ps/%2f/topic1 1033.3
- Subscribe to a topic by
GET /ps/vhost/topic1 Observe:0
orGET /ps/vhost/topic1/key Observe:0
- Receive publications as
2.05 Content
$ ./coap-client coap://127.0.0.1/ps/%2f/topic1 -s 10
- Remove a topic by
DELETE /ps/vhost/topic1
The broker will delete the exchange "topic1" in a given vhost and terminate all CoAP observers of this topic.$ ./coap-client -m delete coap://127.0.0.1/ps/%2f/topic1
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.
This plug-in requires the
Last value caching exchange.
Please make sure that both rabbitmq_lvc
and rabbitmq_coap_pubsub
are installed.
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.
Key | Documentation |
---|---|
prefix |
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.
Default: [<<"ps">>] |
udp_listen |
Port for incoming coap:// requests.
Default: 5683 |
dtls_listen |
Port for incoming coaps:// requests.
Disabled by default. |
dtls_options |
Configuration of the DTLS server. Shall include at least certfile and keyfile fields. See ssl_option() for more details. |
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"}
]}
]}
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
- 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 (c) 2015 Petr Gotthard [email protected]. All Rights Reserved.
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.