stomp_out 0.1.0

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+cache: bundler
+bundler_args: --without debugger development
+rvm:
+ - 1.8
+ - 1.9
+ - 2.0
+ - 2.1
+script:
+ - bundle exec rake ci:spec

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+=== 0.1.0 (2015-01-21)
+
+Initial commit

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 RightScale, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,91 @@
+= Introduction
+
+StompOut is an implementation of the Simple Text Orientated Messaging Protocol (STOMP[http://stomp.github.io]).
+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[link:lib/stomp_out/client.rb] class exposes
+and the functions the Client subclass must implement.
+
+The Client exposes the following functions:
+* <b>receive_data</b> - process data received over connection from server
+* <b>connect</b> - connect to server
+* <b>message</b> - send message to given destination
+* <b>subscribe</b> - register to listen to given destination
+* <b>unsubscribe</b> - remove an existing subscription
+* <b>ack</b> - acknowledge consumption of a message from a subscription
+* <b>nack</b> - tell the server that a message was not consumed
+* <b>begin</b> - start a transaction
+* <b>commit</b> - commit a transaction
+* <b>abort</b> - roll back a transaction
+* <b>disconnect</b> - disconnect from the server
+* <b>subscriptions</b> - list active subscriptions
+* <b>transactions</b> - list active transactions
+
+The Client subclass must implement the following functions:
+* <b>send_data</b> - send data over connection to server
+* <b>on_connected</b> - handle notification that now connected
+* <b>on_message</b> - handle message received from server
+* <b>on_receipt</b> - handle notification that request was successfully handled by server
+* <b>on_error</b> - 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[link:lib/stomp_out/server.rb] class exposes
+and the functions the Server subclass must implement.
+
+The Server exposes the following functions:
+* <b>receive_data</b> - process data received over connection from client
+* <b>disconnect</b> - stop service in anticipation of connection being closed
+* <b>message</b> - send message from a subscribed destination to client
+
+The Server subsclass must implement the following functions:
+* <b>send_data</b> - send data over connection to client
+* <b>on_connect</b> - handle connect request from client including any authentication
+* <b>on_message</b> - handle delivery of message from client to given destination
+* <b>on_subscribe</b> - subscribe client to messages from given destination
+* <b>on_unsubscribe</b> - unsubscribe client from given destination
+* <b>on_ack</b> - handle acknowledgement from client that a message has been successfully processed
+* <b>on_nack</b> - handle negative acknowledgement from client for a message
+* <b>on_error</b> - handle notification that a client or server request failed and connection should be closed
+* <b>on_disconnect</b> - handle request from client to close connection
+
+The above functions should raise StompOut::ApplicationError[link:lib/stomp_out/errors.rb] for requests
+that violate any application specific constraints.
+
+= Example
+
+The gem contains client[link:examples/websocket_client.rb] and server[link:examples/websocket_server.rb]
+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 simple_uuid gem is used by the Server for generating subscription identifiers.
+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}[http://www.opensource.org/licenses/MIT]. Please see link:LICENSE for further details.
+
+Copyright (c) 2015 RightScale

data/Rakefile

@@ -0,0 +1,36 @@
+# -*-ruby-*-
+require 'rubygems'
+require 'rake'
+require 'right_develop'
+require 'spec/rake/spectask'
+require 'rubygems/package_task'
+require 'rake/clean'
+
+task :default => [:spec]
+
+desc "Run unit tests"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = Dir['**/*_spec.rb']
+  t.spec_opts = lambda do
+    IO.readlines(File.join(File.dirname(__FILE__), 'spec', 'spec.opts')).map {|l| l.chomp.split " "}.flatten
+  end
+end
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification; see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "stomp_out"
+  gem.homepage = "https://github.com/rightscale/stomp_out"
+  gem.license = "MIT"
+  gem.summary = %Q{Client and server for STOMP protocol that operate outboard of separately supplied network connection.}
+  gem.description = %Q{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.}
+  gem.email = "support@rightscale.com"
+  gem.authors = ["Lee Kirchhoff"]
+  gem.files.exclude "Gemfile*"
+  gem.files.exclude "spec/**/*"
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+CLEAN.include("pkg")
+
+RightDevelop::CI::RakeTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/examples/config.ru

@@ -0,0 +1,13 @@
+require 'rubygems'
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+require 'bundler/setup'
+require 'rack'
+require 'rack/server'
+require 'eventmachine'
+require 'rack/websocket'
+require 'stomp_out'
+require 'websocket_server'
+
+map '/' do
+  run WebSocketServerApp.new
+end

data/examples/websocket_client.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+require 'bundler/setup'
+require 'eventmachine'
+require 'faye/websocket'
+require 'trollop'
+require 'json'
+require 'stomp_out'
+
+# Example of a StompOut::Client subclass in a WebSocket environment
+class WebSocketClient < StompOut::Client
+
+  def initialize(options = {})
+    options = options.dup
+    @parent = options.delete(:parent)
+    @destination = options.delete(:destination)
+    @ack = options.delete(:ack) || "auto"
+    @message = options.delete(:message)
+    @receipts = {}
+
+    super(options)
+  end
+
+  def send_data(data)
+    @parent.send_data(data)
+  end
+
+  def on_connected(frame, session_id, server_name)
+    puts "connected to #{server_name} for session #{session_id}"
+    if @message
+      receipt_id = message(@destination, @message)
+      @receipts[receipt_id] = "message to #{@destination}" if receipt_id
+      close
+    else
+      puts "subscribing to #{@destination} with ack #{@ack}"
+      receipt_id = subscribe(@destination, @ack, receipt = true)
+      @receipts[receipt_id] = "subscribe to #{@destination} with ack #{@ack}" if receipt_id
+    end
+  end
+
+  def on_message(frame, destination, message, content_type, message_id, ack_id)
+    puts "received #{content_type} message #{message_id} from #{destination} " +
+         "with ack #{ack_id.inspect}: #{message.inspect}"
+    if @ack != "auto"
+      receipt_id = ack(ack_id)
+      @receipts[receipt_id] = "ack #{ack_id}" if receipt_id
+    end
+  end
+
+  def on_receipt(frame, receipt_id)
+    @subscribed = true if @receipts[receipt_id].to_s =~ /subscribe to/
+    puts "received receipt #{receipt_id} for #{@receipts.delete(receipt_id).inspect}"
+  end
+
+  def on_error(frame, error, details, receipt_id)
+    receipt = receipt_id ? " with receipt #{receipt_id.inspect}" : nil
+    puts "error#{receipt}: #{error}" + (details ? "\n#{details}" : "")
+    close
+  end
+
+  def close
+    if connected?
+      if @subscribed
+        @subscribed = false
+        puts "unsubscribing from #{@destination}"
+        receipt_id = unsubscribe(@destination)
+        @receipts[receipt_id] = "unsubscribe from #{@destination}" if receipt_id
+      end
+      receipt_id = disconnect
+      @receipts[receipt_id] = "disconnect" if receipt_id
+      @parent.stop
+    end
+  end
+end
+
+# Simple application using WebSocketClient
+class WebSocketClientApp
+
+  def self.run
+    r = WebSocketClientApp.new
+    options = r.parse_args
+    r.start(options)
+  end
+
+  def start(options)
+    ['INT', 'TERM'].each do |signal|
+      trap(signal) do stop end
+    end
+
+    EM.run do
+      @client = WebSocketClient.new(options.merge(:parent => self, :name => self.class.name, :auto_json => true))
+      @websocket = Faye::WebSocket::Client.new(options[:url])
+      @websocket.onerror = lambda { |e| puts "error #{e.message}"; stop }
+      @websocket.onclose = lambda { |e| puts "close #{e.code} #{e.reason}"; stop }
+      @websocket.onmessage = lambda { |e| puts "received #{e.data}"; @client.receive_data(JSON.load(e.data)) }
+      @client.connect
+    end
+  end
+
+  def send_data(data)
+    data = JSON.dump(data)
+    puts "sending: #{data}"
+    @websocket.send(data)
+  end
+
+  def stop
+    if EM.reactor_running?
+      @client.close if @client
+
+      EM.next_tick do
+        @websocket.close if @websocket
+        EM.next_tick { EM.stop }
+      end
+    end
+  end
+
+  def parse_args
+    options = {}
+
+    parser = Trollop::Parser.new do
+      opt :url, "server WebSocket URL", :default => nil, :type => String, :short => "-u", :required => true
+      opt :destination, "messaging destination", :default => nil, :type => String, :short => "-d", :required => true
+      opt :host, "server virtual host name", :default => nil, :type => String, :short => "-h"
+      opt :ack, "auto, client, or client-individual acks", :default => nil, :type => String, :short => "-a"
+      opt :receipt, "enable receipts", :default => nil, :short => "-r"
+      opt :message, "send message to destination", :default => nil, :type => String, :short => "-m"
+      version ""
+    end
+
+    parse do
+      options.merge!(parser.parse)
+    end
+  end
+
+  def parse
+    begin
+      yield
+    rescue Trollop::VersionNeeded
+      puts version
+      exit 0
+    rescue Trollop::HelpNeeded
+      puts "Usage: websocket_client --url <s> --destination <s> [--host <s> --ack <s> --receipt --message <s>]"
+      exit 0
+    rescue Trollop::CommandlineError => e
+      STDERR.puts e.message + "\nUse --help for additional information"
+      exit 1
+    end
+  end
+end
+
+WebSocketClientApp.run

data/examples/websocket_server.rb

@@ -0,0 +1,120 @@
+
+# Example of a StompOut::Server subclass in a WebSocket environment
+class WebSocketServer < StompOut::Server
+
+  def initialize(options = {})
+    options = options.dup
+    @parent = options.delete(:parent)
+    @subscriptions = {}
+    @message_ids = {}
+    super(options.merge(:name => self.class.name))
+  end
+
+  def send_data(data)
+    @parent.send_data(data)
+  end
+
+  def on_connect(frame, login, passcode, host, session_id)
+    true
+  end
+
+  def on_message(frame, destination, message, content_type)
+    @parent.deliver_message(destination, message, content_type)
+  end
+
+  def on_subscribe(frame, id, destination, ack_setting)
+    @subscriptions[id] = {:destination => destination, :ack_setting => ack_setting}
+  end
+
+  def on_unsubscribe(frame, id, destination)
+    @subscriptions.delete(id)
+  end
+
+  def on_ack(frame, id)
+    @parent.delete_message(@message_ids.delete(id))
+  end
+
+  def on_nack(frame, id)
+    @message_ids.delete(id)
+  end
+
+  def on_error(frame, error)
+    EM.next_tick { @parent.close_websocket }
+  end
+
+  def on_disconnect(frame, reason)
+    EM.next_tick { @parent.close_websocket }
+  end
+
+  def deliver_messages(destination, messages)
+    @subscriptions.each do |id, s|
+      if s[:destination] == destination
+        messages.each do |m|
+          headers = {
+            "subscription" => id,
+            "destination" => destination,
+            "message-id" => m[:id].to_s,
+            "content-type" => m[:content_type] }
+          message_id, ack_id = message(headers, m[:message])
+          if s[:ack_setting] == "auto"
+            @parent.delete_message(message_id)
+          else
+            @message_ids[ack_id] = message_id
+          end
+        end
+      end
+    end
+  end
+end
+
+# Simple WebSocket Rack application using WebSocketServer
+class WebSocketServerApp < Rack::WebSocket::Application
+
+  @@servers = {}
+  @@connections = {}
+  @@connection_id = 0
+  @@messages = Hash.new { |h, k| h[k] = [] }
+  @@message_id = 0
+
+  def on_open(env)
+    socket = env["async.connection"]
+    @@connections[socket] = @@connection_id += 1
+    puts "opened connection #{@@connection_id}"
+    @@servers[socket] = WebSocketServer.new(:parent => self)
+  end
+
+  def on_close(env)
+    socket = env["async.connection"]
+    connection = @@connections.delete(socket)
+    puts "closed connection #{connection}"
+    @@servers.delete(socket)
+  end
+
+  def on_error(env, error)
+    socket = env["async.connection"]
+    connection = @@connections[socket]
+    STDERR.puts "error on connection #{connection} (#{error})"
+  end
+
+  def on_message(env, message)
+    socket = env["async.connection"]
+    connection = @@connections[socket]
+    puts "received #{message} on connection #{connection}"
+    @@servers[socket].receive_data(JSON.load(message))
+  end
+
+  def send_data(data)
+    data = JSON.dump(data)
+    puts "sending #{data}"
+    super(data)
+  end
+
+  def deliver_message(destination, message, content_type)
+    @@messages[destination] << {:id => (@@message_id += 1).to_s, :message => message, :content_type => content_type}
+    @@servers.each_value { |s| s.deliver_messages(destination, @@messages[destination]) }
+  end
+
+  def delete_message(id)
+    @@messages.each_value { |ms| ms.reject! { |m| m[:id] == id } }
+  end
+end