2016-02-08 23:36:50 +01:00
|
|
|
STOMP on Erlang
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
`stomp.erl` is a simple Erlang client for the [STOMP protocol][] in version 1.2.
|
|
|
|
|
|
|
|
|
|
Currently only subscribing to queues is supported.
|
|
|
|
|
|
|
|
|
|
It provides an application called `stomp` which takes configuration of the form:
|
|
|
|
|
|
|
|
|
|
```erlang
|
|
|
|
|
[{stomp, #{host => "stomp-server.somedomain.sexy", % required
|
2016-02-09 01:17:21 +01:00
|
|
|
port => 61613, % optional
|
2016-02-08 23:36:50 +01:00
|
|
|
login => <<"someuser">>, % optional
|
|
|
|
|
passcode => <<"hunter2>>, % optional
|
|
|
|
|
}}].
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Types
|
|
|
|
|
|
|
|
|
|
The following types are used in `stomp.erl`, you can include them from
|
|
|
|
|
`stomp.hrl`:
|
|
|
|
|
|
|
|
|
|
```erlang
|
|
|
|
|
%% Client ack modes, refer to the STOMP protocol documentation
|
|
|
|
|
-type ack_mode() :: client | client_individual | auto.
|
|
|
|
|
|
|
|
|
|
%% Subscriptions are enumerated from 0
|
|
|
|
|
-type sub_id() :: integer().
|
|
|
|
|
|
|
|
|
|
%% Message IDs (for acknowledgements) are simple strings. They are
|
|
|
|
|
%% extracted from the 'ack' field of the header in client or client-individual
|
|
|
|
|
%% mode, and from the 'message-id' field in auto mode.
|
|
|
|
|
-type message_id() :: binary().
|
|
|
|
|
|
|
|
|
|
%% A STOMP message as received from a queue subscription
|
|
|
|
|
-record(stomp_msg, { headers :: #{ binary() => binary() },
|
|
|
|
|
body :: binary() }.
|
|
|
|
|
-type stomp_msg() :: #stomp_msg{}.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Once the application starts it will register a process under the name
|
|
|
|
|
`stomp_worker` and expose the following API:
|
|
|
|
|
|
|
|
|
|
## Subscribing to a queue
|
|
|
|
|
|
|
|
|
|
```erlang
|
|
|
|
|
%% Subscribe to a destination, receive the subscription ID
|
|
|
|
|
-spec subscribe(binary(), % Destination (e.g. <<"/queue/lizards">>)
|
|
|
|
|
ack_mode(), % Client-acknowledgement mode
|
|
|
|
|
-> {ok, sub_id()}.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This synchronous call subscribes to a message queue. The `stomp_worker` will
|
2016-02-09 01:17:21 +01:00
|
|
|
link itself to the caller and forward received messages as
|
2016-02-08 23:36:50 +01:00
|
|
|
`{msg, sub_id(), stomp_msg()}`.
|
|
|
|
|
|
|
|
|
|
Depending on the acknowledgement mode specified on connecting, the subscriber
|
|
|
|
|
may have to acknowledge receival of messages.
|
|
|
|
|
|
|
|
|
|
## Acknowledging messages
|
|
|
|
|
|
|
|
|
|
```erlang
|
|
|
|
|
%% Acknowledge a message ID.
|
|
|
|
|
%% This is not required in auto mode. In client mode it will acknowledge the
|
|
|
|
|
%% received messages up to the ID specified. In client-individual mode every
|
|
|
|
|
%% single message has to be acknowledged.
|
|
|
|
|
-spec ack(sub_id(), message_id()) -> ok.
|
|
|
|
|
|
|
|
|
|
%% Explicitly "unacknowledge" a message
|
|
|
|
|
-spec nack(sub_id(), message_id()) -> ok.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Both of these calls are asynchronous and will return immediately. Note that in
|
|
|
|
|
the case of the `stomp_worker` crashing before a message acknowledgement is
|
|
|
|
|
handled, the message *may* be delivered again. Your consumer needs to be able to
|
|
|
|
|
handle this.
|
|
|
|
|
|
|
|
|
|
[STOMP protocol]: https://stomp.github.io/stomp-specification-1.2.html
|
