Project

stomp_out

0.0
No commit activity in last 3 years
No release in over 3 years
This implementation of STOMP is aimed at environments where a network connection, such as a WebSocket or TCP socket, is created and then raw data from that connection is passed to/from the STOMP client or server messaging layer provided by this gem.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 2.0
>= 0
~> 10.0

Runtime

~> 1.4
 Project Readme

<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