depot/third_party/tvl/net/stomp_erl/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:

[{stomp, #{host     => "stomp-server.somedomain.sexy", % required
           port     => 61613,                          % optional
           login    => <<"someuser">>,                 % optional
           passcode => <<"hunter2>>,                   % optional
 }}].

Types

The following types are used in stomp.erl, you can include them from stomp.hrl:

%% 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

%% 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 link itself to the caller 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

%% 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.