path: root/README.md

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
           port     => 61613,                          % required
           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
                pid())      % PID of the process that wants to receive messages
                -> {ok, sub_id()}.
```

This synchronous call subscribes to a message queue. The `stomp_worker` will
link itself to the PID and forward received messages as
`{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