invoca / stomp_out

Transport-independent implementation of the STOMP message exchange protocol.

<img src=“https://travis-ci.org/rightscale/stomp_out.svg?branch=master” alt=“Build Status” />

Introduction¶ ↑

StompOut is an implementation of the Simple Text Orientated Messaging Protocol (STOMP). Both a client and server interface to the protocol are provided. They are implemented independent of the underlying network protocol over which they are applied. In that sense they run outboard of the underlying connection, hence “Out” in the name. The Client and Server classes provide a function for receiving blocks of STOMP encoded data from the connection and they expect the subclass to implement a function for sending data that has been STOMP encoded over the connection.

The Client and Server classes support version 1.0, 1.1, and 1.2 of STOMP. The built-in version negotiation in the protocol determines which is actually applied for a given connection.

Interface¶ ↑

Client¶ ↑

There are two parts to the interface: the functions the StompOut::Client class exposes and the functions the Client subclass must implement.

The Client exposes the following functions:

• receive_data - process data received over connection from server

• connect - connect to server

• message - send message to given destination

• subscribe - register to listen to given destination

• unsubscribe - remove an existing subscription

• ack - acknowledge consumption of a message from a subscription

• nack - tell the server that a message was not consumed

• begin - start a transaction

• commit - commit a transaction

• abort - roll back a transaction

• disconnect - disconnect from the server

• subscriptions - list active subscriptions

• transactions - list active transactions

The Client subclass must implement the following functions:

• send_data - send data over connection to server

• on_connected - handle notification that now connected

• on_message - handle message received from server

• on_receipt - handle notification that request was successfully handled by server

• on_error - handle notification that a client request failed and connection should be closed

Server¶ ↑

There are two parts to the interface: the functions the StompOut::Server class exposes and the functions the Server subclass must implement.

The Server exposes the following functions:

• receive_data - process data received over connection from client

• disconnect - stop service in anticipation of connection being closed

• message - send message from a subscribed destination to client

The Server subsclass must implement the following functions:

• send_data - send data over connection to client

• on_connect - handle connect request from client including any authentication

• on_message - handle delivery of message from client to given destination

• on_subscribe - subscribe client to messages from given destination

• on_unsubscribe - unsubscribe client from given destination

• on_ack - handle acknowledgement from client that a message has been successfully processed

• on_nack - handle negative acknowledgement from client for a message

• on_error - handle notification that a client or server request failed and connection should be closed

• on_disconnect - handle request from client to close connection

The above functions should raise StompOut::ApplicationError for requests that violate any application specific constraints.

Example¶ ↑

The gem contains client and server examples of how it can be applied in a WebSocket environment. The server example can be run in the examples directory using thin:

thin -R config.ru start

The client example is a script that can executed against the server, e.g., to produce messages:

./websocket_client.rb -u ws://0.0.0.0:3000 -d /queue -m "hi"
./websocket_client.rb -u ws://0.0.0.0:3000 -d /queue -m "bye"

and to consume messages:

./websocket_client.rb -u ws://0.0.0.0:3000 -d /queue -a client -r

Dependencies¶ ↑

The eventmachine gem is used only if the STOMP heartbeat feature is used. The the json gem is used by the Client only if a content-type is “application/json” and the :auto_json option is enabled. The examples make use of the faye-websocket, eventmachine, trollop, and json gems.

License¶ ↑

This software is released under the MIT License. Please see LICENSE for further details.

Copyright © 2015 RightScale