wamp_client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 72e6d6b94bf4b5f244885438e6c122c952d5d084
+  data.tar.gz: 0366993e7d42a1e3673210af8c8b4a05b63206e9
+SHA512:
+  metadata.gz: 0de90b5fc4cdf71d2e76b587a232530b47fb8e0ebd961c5a77299f130714c575ac36061a5c0bdeb75de5a535d9711a07523b79360d1d1c777738f0314f70179a
+  data.tar.gz: bf65fac58f124abb76d0c4518067f28f2046a29ffcb1d7fb0aede645654ae9d445ffeafded1c3d94aa759e316f9fd2738f38c72f8a2c3b4d2550a6ff21f6a4e8

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea
+*.tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in wamp_client.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Eric Chapman
+
+MIT License
+
+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.md

@@ -0,0 +1,464 @@
+# WampClient
+
+[![Circle CI](https://circleci.com/gh/ericchapman/ruby_wamp_client/tree/master.svg?&style=shield&circle-token=92813c17f9c9510c4c644e41683e7ba2572e0b2a)](https://circleci.com/gh/ericchapman/ruby_wamp_client/tree/master)
+[![Codecov](https://img.shields.io/codecov/c/github/ericchapman/ruby_wamp_client/master.svg)](https://codecov.io/github/ericchapman/ruby_wamp_client)
+
+Client for talking to a WAMP Router.  This is defined at
+
+    https://tools.ietf.org/html/draft-oberstet-hybi-tavendo-wamp-02
+
+## Revision History
+
+ - v0.0.1:
+   - Initial Release
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wamp_client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wamp_client
+
+## Usage
+
+### Connection
+The connection object is used to instantiate and maintain a WAMP session as well as the underlying transport.  A user
+creates a connection and then operates on the session once the session has been established.
+
+Note that once "connection.open" is called, the library will automatically attempt to reconnect if the connection
+closes for any reason.  Calling "connection.close" will stop the reconnect logic as well as close the connection if it
+is open
+
+#### Creating a connection
+A connection can be created as follows
+
+```ruby
+require 'wamp_client'
+
+options = {
+    uri: 'ws://127.0.0.1:8080/ws',
+    realm: 'realm1'
+}
+connection = WampClient::Connection.new(options)
+
+connection.on_join do |session, details|
+  puts "Session Open"
+
+  # Register for something
+  def add(args, kwargs, details)
+    args[0] + args[1]
+  end
+  session.register('com.example.procedure', method(:add)) do |registration, error, details|
+
+    # Call It
+    session.call('com.example.procedure', [3,4]) do |result, error, details|
+      if result
+        puts result.args[0] # => 7
+      end
+    end
+
+  end
+
+
+end
+
+connection.open
+```
+
+#### Closing a connection
+A connection is closed by simply calling "close"
+
+```ruby
+connection.close
+```
+
+Note that the connection will still call "on_leave" and "on_disconnect" as it closes the session and the transport
+
+#### Callbacks
+A session has the following callbacks
+
+**on_connect** - Called when the transport is opened
+```ruby
+connection.on_connect do
+
+end
+```
+
+**on_join** - Called when the session is established
+```ruby
+connection.on_join do |session, details|
+
+end
+```
+
+**on_leave** - Called when the session is terminated
+```ruby
+connection.on_leave do |reason, details|
+
+end
+```
+
+**on_disconnect** - Called when the connection is terminated
+```ruby
+connection.on_disconnect do |reason|
+
+end
+```
+
+**oon_challenge** - Called when an authentication challenge is created
+```ruby
+connection.on_challenge do |authmethod, extra|
+
+end
+```
+
+### Authentication
+The library supports authentication.  Here is how to perform the different methods
+
+#### WAMPCRA
+To perform WAMP CRA, do the following
+
+```ruby
+require 'wamp_client'
+
+options = {
+    uri: 'ws://127.0.0.1:8080/ws',
+    realm: 'realm1',
+    authid: 'joe',
+    authmethods: ['wampcra']
+}
+connection = WampClient::Connection.new(options)
+
+connection.on_challenge do |authmethod, extra|
+  puts 'Challenge'
+  if authmethod == 'wampcra'
+    WampClient::Auth::Cra.sign('secret', extra[:challenge])
+  else
+    raise RuntimeError, "Unsupported auth method #{authmethod}"
+  end
+end
+
+connection.on_join do |session, details|
+  puts "Session Open"
+end
+
+connection.open
+```
+
+### Handlers and Callbacks
+This library makes extensive use of "blocks", "lambdas", "procs", and method pointers for any returned values because
+all communication is performed asynchronously.  The library defines two types of methods
+
+ - handlers - Can be called **AT ANY TIME**.  These can be blocks, lambdas, procs, or method pointers
+ - callbacks - Only invoked in response to specific call.  These are only blocks
+
+Note that all callbacks can be set to nil, handlers however cannot since the user is explicitly setting them up.
+
+#### Handlers
+All handlers are called with the following parameters
+
+ - args [Array] - Array of arguments
+ - kwargs [Hash] - Hash of key/value arguments
+ - details [Hash] - Hash containing some details about the call
+
+Some examples of this are shown below
+
+**lambda**
+
+```ruby
+handler = lambda do |args, kwargs, details|
+    # TODO: Do Something!!
+end
+session.subscribe('com.example.topic', handler)
+```
+
+**method**
+
+```ruby
+def handler(args, kwargs, details)
+    # TODO: Do Something!!
+end
+session.subscribe('com.example.topic', method(:handler))
+```
+
+#### Callbacks
+All callbacks are called with the following parameters
+
+ - result [Object] - Some object with the result information (depends on the call)
+ - error [Hash] - Hash containing "error", "args", and "kwargs" if an error occurred
+ - details [Hash] - Hash containing some details about the call
+
+An example of this is shown below
+
+```ruby
+session.call('com.example.procedure') do |result, error, details|
+    # TODO: Do something
+end
+```
+
+### Topic Subscriptions and Publications
+
+#### Subscribe
+This method subscribes to a topic.  The prototype for the method is
+
+```ruby
+subscribe(topic, handler, options={}, &callback)
+```
+
+where the parameters are defined as
+
+ - topic [String] - The topic to subscribe to
+ - handler [lambda] - The handler(args, kwargs, details) when an event is received
+ - options [Hash] - The options for the subscription
+ - callback [block] - The callback(subscription, error, details) called to signal if the subscription was a success or not
+
+To subscribe, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.subscribe('com.example.topic', handler)
+```
+
+If you would like confirmation of the success of the subscription, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.subscribe('com.example.topic', handler) do |subscription, error, details|
+  # TODO: Do something
+end
+```
+
+Options are
+
+ - match [String] - "exact", "prefix", or "wildcard"
+
+#### Unsubscribe
+This method unsubscribes from a topic.  The prototype for the method is as follows
+
+```ruby
+def unsubscribe(subscription, &callback)
+```
+
+where the parameters are defined as
+
+ - subscription [Subscription] - The subscription object from when the subscription was created
+ - callback [block] - The callback(subscription, error, details) called to signal if the unsubscription was a success or not
+
+To unsubscribe, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.subscribe('com.example.topic', handler) do |subscription, error, details|
+  @subscription = subscription
+end
+
+# At some later time...
+
+session.unsubscribe(@subscription)
+
+# or ...
+
+@subscription.unsubscribe
+
+```
+
+#### Publish
+This method publishes an event to all of the subscribers.  The prototype for the method is
+
+```ruby
+publish(topic, args=nil, kwargs=nil, options={}, &callback)
+```
+
+where the parameters are defined as
+
+ - topic [String] - The topic to publish the event to
+ - args [Array] - The arguments
+ - kwargs [Hash] - The keyword arguments
+ - options [Hash] - The options for the subscription
+ - callback [block] - The callback(publish, error, details) is called to signal if the publish was a success or not
+
+To publish, do the following
+
+```ruby
+session.publish('com.example.topic', [15], {param: value})
+```
+
+If you would like confirmation, do the following
+
+```ruby
+session.publish('com.example.topic', [15], {param: value}, {acknowledge: true}, callback) do |publish, error, details|
+  # TODO: Do something
+end
+```
+
+Options are
+
+ - acknowledge [Boolean] - set to "true" if you want the Broker to acknowledge if the Publish was successful or not
+ - disclose_me [Boolean] - "true" if the publisher would like the subscribers to know his identity
+ - exclude [Array[Integer]] - Array of session IDs to exclude
+ - exclude_authid [Array[String]] - Array of auth IDs to exclude
+ - exclude_authrole [Array[String]] - Array of auth roles to exclude
+ - eligible [Array[Integer]] - Array of session IDs to include
+ - eligible_authid [Array[String]] - Array of auth IDs to include
+ - eligible_authrole [Array[String]] - Array of auth roles to include
+ - exclude_me [Boolean] - set to "false" if you would like yourself to receive an event that you fired
+
+### Procedure Registrations and Calls
+
+#### Register
+This method registers to a procedure.  The prototype for the method is
+
+```ruby
+register(procedure, handler, options={}, &callback)
+```
+
+where the parameters are defined as
+
+ - procedure [String] - The procedure to register for
+ - handler [lambda] - The handler(args, kwargs, details) when a invocation is received
+ - options [Hash] - The options for the registration
+ - callback [block] - The callback(registration, error, details) called to signal if the registration was a success or not
+
+To register, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.register('com.example.procedure', handler)
+```
+
+If you would like confirmation of the success of the registration, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.register('com.example.procedure', handler, {}, callback) do |registration, error, details|
+  # TODO: Do something
+end
+```
+
+Options are
+
+ - match [String] - "exact", "prefix", or "wildcard"
+ - invoke [String] - "single", "roundrobin", "random", "first", "last"
+
+#### Unregister
+This method unregisters from a procedure.  The prototype for the method is as follows
+
+```ruby
+def unregister(registration, &callback)
+```
+
+where the parameters are defined as
+
+ - registration [Registration] - The registration object from when the registration was created
+ - callback [lambda] - The callback(registration, error, details) called to signal if the unregistration was a success
+   or not
+
+To unregister, do the following
+
+```ruby
+handler = lambda do |args, kwargs, details|
+  # TODO: Do something
+end
+
+session.register('com.example.procedure', handler, {}) do |registration, error, details|
+  @registration = registration
+end
+
+# At some later time...
+
+session.unregister(@registration)
+
+# or ...
+
+@registration.unregister
+
+```
+
+#### Call
+This method calls a procedure.  The prototype for the method is
+
+```ruby
+call(procedure, args=nil, kwargs=nil, options={}, &callback)
+```
+
+where the parameters are defined as
+
+ - procedure [String] - The procedure to invoke
+ - args [Array] - The arguments
+ - kwargs [Hash] - The keyword arguments
+ - options [Hash] - The options for the call
+ - callback [block] - The callback(result, error, details) called to signal if the call was a success or not
+
+To call, do the following
+
+```ruby
+session.call('com.example.procedure', [15], {param: value}, {}) do |result, error, details|
+  # TODO: Do something
+  args = result.args
+  kwargs = result.kwargs
+end
+```
+
+Options are
+
+ - receive_progress [Boolean] - "true" if you support results being able to be sent progressively
+ - disclose_me [Boolean] - "true" if the caller would like the callee to know the identity
+
+## Contributing
+
+1. Fork it ( https://github.com/ericchapman/ruby_wamp_client )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+### TODOs
+
+ - progressive_call_results (callee)
+ - call_timeout
+ - call_canceling
+
+### Testing
+
+The unit tests are run as follows
+
+    $ bundle exec rake spec
+
+### Scripts
+
+#### Message
+
+The *lib/wamp_client/message.rb* file and the *spec/message_spec.rb* file are autogenerated using the script
+*scripts/gen_message.rb*.  This is done as follows
+
+    $ cd scripts
+    $ ./gen_message.rb
+    $ mv message.rb.tmp ../lib/wamp_client/message.rb
+    $ mv message_spec.rb.tmp ../spec/message_spec.rb
+
+As I was writing the code for the messages I caught myself cutting and pasting allot and decided these would be
+better suited to be autogenerated.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/gem_tasks"
+
+Dir.glob('tasks/**/*.rake').each(&method(:import))

data/circle.yml

@@ -0,0 +1,3 @@
+test:
+  post:
+    - bundle exec rake spec

data/lib/wamp_client/auth.rb

@@ -0,0 +1,18 @@
+require 'openssl'
+require 'base64'
+
+module WampClient
+  module Auth
+    module Cra
+
+      # Generates the signature from the challenge
+      # @param key [String]
+      # @param challenge [String]
+      def self.sign(key, challenge)
+        hash  = OpenSSL::HMAC.digest('sha256', key, challenge)
+        Base64.encode64(hash).gsub(/\n/,'')
+      end
+
+    end
+  end
+end

data/lib/wamp_client/check.rb

@@ -0,0 +1,57 @@
+module WampClient
+  module Check
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      def check_equal(name, expected, value)
+        raise ArgumentError, "The '#{name}' argument must have the value '#{expected}'.  Instead the value was '#{value}'" unless value == expected
+      end
+
+      def check_gte(name, expected, value)
+        raise ArgumentError, "The '#{name}' argument must be greater than or equal to '#{expected}'.  Instead the value was '#{value}'" unless value >= expected
+      end
+
+      def check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument cannot be nil" if param.nil? and not nil_allowed
+      end
+
+      def check_int(name, param, nil_allowed=false)
+        check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument must be an integer" unless param.nil? or param.is_a? Integer
+      end
+
+      def check_string(name, param, nil_allowed=false)
+        check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument must be a string" unless param.nil? or param.is_a? String
+      end
+
+      def check_bool(name, param, nil_allowed=false)
+        check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument must be a boolean" unless param.nil? or !!param == param
+      end
+
+      def check_dict(name, param, nil_allowed=false)
+        check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument must be a hash" unless param.nil? or param.is_a? Hash
+      end
+
+      def check_list(name, param, nil_allowed=false)
+        check_nil(name, param, nil_allowed)
+        raise ArgumentError, "The '#{name}' argument must be an array" unless param.nil? or param.is_a? Array
+      end
+
+      def check_uri(name, param, nil_allowed=false)
+        check_string(name, param, nil_allowed)
+      end
+
+      def check_id(name, param, nil_allowed=false)
+        check_int(name, param, nil_allowed)
+      end
+    end
+
+  end
+end