diff options
| -rw-r--r-- | README.md | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 000000000000..e1be3581b8c3 --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +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 |