WampRails

This library allows the GEM wamp_client to be integrated into a Rails application.

The 'wamp_client' GEM uses the Event Machine implementation of Web Sockets to connect to the WAMP router. This requires the Rails application to spin off an independent thread where the EM reactor will run.

The library also wraps the connection logic under the library so that the Rails application doesn't need to handle it.

All calls to the library are implemented as "commands". When a call is made to the client, the library will create a command and do the following

• If the thread is the same thread as the EM reactor, it will immediately execute the command
• Else place the command into the queue that the reactor will check on every tick

This ensures that the Rails application does not need to worry about the thread.

This however has the side effect where all calls to the library are executed synchronously (they will block the current thread) unless the callback is nil.

Revision History

• v0.0.2:
  • Added 'routes' to the client
• v0.0.1:
  • Initial Revision

Installation

Add this line to your application's Gemfile:

gem 'wamp_rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install wamp_rails

Usage

Connection

The client is initialized as shown below. The options are the same as 'wamp_client' with the addition of the 'name' option which is used for logging.

options = {
  name: 'main router',
  uri: 'ws://router.example.com,
  realm: 'realm1'
}

wamp_client = WampRails::Client.new(options)
wamp_client.open

Commands

The client currently supports the following commands from the WampClient library

• call
• publish
• register
• subscribe

The methods have the same parameters as the WampClient library

Controllers

The 'register' and 'subscribe' commands require 'handlers' to be implemented. In order to ensure thread safety and consistency with Rails, the handlers are implemented as 'controller' classes.

When a call or publish is received, the library will instantiate the supplied class with following methods available

• args (Array) - The arguments
• kwargs (Hash) - The keyword arguments
• details (Hash) - The details
• client [WampRails::Client) - The client. This can be used if the handler needs to send a Wamp message

Procedure

To create a register controller, create a class that subclasses from 'WampRails::Controller::Procedure' and implements 'handler'. See below

class MyRegisterController < WampRails:::Controller::Procedure

  def handler
    the_args = self.args
    the_kwargs = self.kwargs
    the_details = self.details
    the_client = self.client
   
    # Do Something
   
    # Return the result (see WampClient for more details on implementing procedures)
    true
  end

end

Subscription

To create a subscribe controller, create a class that subclasses from 'WampRails::Controller::Subscription' and implements 'handler'. See below

class MySubscribeController < WampRails:::Controller::Subscription

  def handler
    the_args = self.args
    the_kwargs = self.kwargs
    the_details = self.details
    the_client = self.client
   
    # Do Something
   
  end

end

Routes

Routes are created using the 'routes' block. This must be called BEFORE 'open'. Below is an example

options = {
  uri: 'ws://router.example.com,
  realm: 'realm1'
}

wamp_client = WampRails::Client.new(options)

# Configure the Routes
wamp_client.routes do
  add_subscription 'topic', MySubscriptionClass
  add_subscription 'topic.*', MyWildcardSubscriptionClass, {wildcard: true}
  
  add_procedure 'procedure.', MyPrefixProcedureClass, {prefix: true}
end

wamp_client.open

When 'routes' is used, the client object will automatically re-register/subscribe to the procedures/topics on reconnect. Otherwise if 'register' or 'subscribe' are going to be called directly, then the system must wait for the connection to become active by calling

wamp_client.wait_for_active