simrpc 0.1 → 0.2

data/LICENSE

@@ -1,4 +1,4 @@
- Copyright (c) 2009 Mohammed Morsi <movitto@yahoo.com>
+ Copyright (c) 2010 Mohammed Morsi <movitto@yahoo.com>
 
  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation

data/README.rdoc

@@ -0,0 +1,79 @@
+== Simrpc - A Simple RPC library using AMQP as the transport mechanism
+
+Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+
+Simrpc is made available under the MIT License
+
+=== Intro
+Simrpc is a simple Ruby module for rpc communication
+that uses Apache QPID as the transport mechanism. 
+
+Developers define class / function schemas in xml and register handlers
+to be invoked when schema methods are called. Schema classes and members
+are mapped to Ruby classes via Ruby's builtin introspection mechanisms.
+
+To install simrpc simply run:
+   gem install simrpc
+
+Source code is available via:
+   git clone http://github.com/movitto/simrpc
+
+=== Using
+Generate documentation via
+  rake rdoc
+
+Also see specs for detailed usage.
+
+The primary interface to simrpc is provided by the 'node' module which 
+defines Simrpc::Node. This class should be instantiated using a custom identifier
+for every simrpc endpoint you want to establish (nodes that share
+an identifier will share a message queue) after which it can be used to 
+register handlers to schema methods and invoke remote methods.
+
+
+== Example
+
+    TEST_SCHEMA = 
+             "<schema>"+
+             "  <method name='foo_method'>" +
+             "    <param type='int' name='some_int'/>"+
+             "    <param type='float' name='floating_point_number'/>"+
+             "    <return_value type='str' name='a_string' />" +
+             "    <return_value type='obj' name='my_class_instance' associated='MyClass' />" +
+             "  </method>"+
+             "  <method name='bar_method'>" +
+             "    <param type='array' name='byte_array' associated='int'/>"+
+             "    <return_value type='int' name='bool_success' />"+
+             "  </method>"+
+             "  <class name='MyClass'>"+
+             "    <member type='str' name='str_member' />" +
+             "    <member type='float' name='float_member' />" +
+             "    <member type='obj' name='associated_obj' ignore_null='true' />" +
+             "  </class>"+
+             "</schema>"
+
+    class MyClass
+      attr_accessor :str_member
+      attr_accessor :float_member
+      attr_accessor :associated_obj
+    end
+
+    server = Node.new(:id => "server3", :schema => TEST_SCHEMA)
+    client = Node.new(:id => "client3", :schema => TEST_SCHEMA, :destination => "server3")
+
+    server.handle_method("foo_method") { |some_int, floating_point_number|
+       some_int # => 10
+       floating_point_number # => 15.4
+
+       ["stuff", MyClass.new("foobar", 4.2)]
+    }   
+
+    a_str, my_class_instance = client.foo_method(10, 15.4)
+
+    a_str # => "stuff"
+    my_class_instance.str_member # => "foobar"
+    my_class_instance.float_member # => 4.2 
+
+
+=== Authors
+ Mohammed Morsi <movitto@yahoo.com>

data/Rakefile

@@ -0,0 +1,46 @@
+# simrpc project Rakefile
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# See LICENSE for the License of this software
+
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+
+GEM_NAME="simrpc"
+PKG_VERSION=0.2
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+end
+
+Rake::RDocTask.new do |rd|
+    rd.main = "README.rdoc"
+    rd.rdoc_dir = "doc/site/api"
+    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end
+
+PKG_FILES = FileList['lib/**/*.rb', 'LICENSE', 'Rakefile', 'README.rdoc', 'spec/**/*.rb' ]
+
+SPEC = Gem::Specification.new do |s|
+    s.name = GEM_NAME
+    s.version = PKG_VERSION
+    s.files = PKG_FILES
+
+    s.required_ruby_version = '>= 1.8.1'
+    s.required_rubygems_version = Gem::Requirement.new(">= 1.3.3")
+    # FIXME require qpid
+
+    s.author = "Mohammed Morsi"
+    s.email = "movitto@yahoo.com"
+    s.date = %q{2010-03-11}
+    s.description = %q{simrpc is a simple Ruby module for rpc communication, using Apache QPID as the transport mechanism.}
+    s.summary     = %q{simrpc is a simple Ruby module for rpc communication, using Apache QPID as the transport mechanism.}
+    s.homepage = %q{http://projects.morsi.org/Simrpc}
+end
+
+Rake::GemPackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+    pkg.need_zip = true
+end

data/lib/simrpc/common.rb

@@ -0,0 +1,46 @@
+# simrpc common module, methods that don't fit elsewhere
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+#
+# 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.
+
+require 'logger'
+
+module Simrpc
+
+# Logger helper class
+class Logger
+  private
+    def self._instantiate_logger
+       unless defined? @@logger
+         @@logger = ::Logger.new(STDOUT)
+         @@logger.level = ::Logger::FATAL # FATAL ERROR WARN INFO DEBUG
+       end
+    end
+  public
+    def self.method_missing(method_id, *args)
+       _instantiate_logger
+       @@logger.send(method_id, args)
+    end
+end
+
+end

data/lib/simrpc/exceptions.rb

@@ -0,0 +1,30 @@
+# simrpc exceptions, may be thrown in simrpc operations
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+#
+# 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.
+
+class InvalidSchemaClass < RuntimeError
+   def self(msg = '')
+     super(msg)
+   end
+end

data/lib/simrpc/message.rb

@@ -0,0 +1,156 @@
+# simrpc message module
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+#
+# 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.
+
+module Simrpc
+
+# the message module provides the Message definition,
+# including a header with routing info and a body
+# with any number of data fields
+module Message
+
+# Simrpc::Message formatter helper module
+class Formatter
+
+  # helper method to format a data field,
+  # prepending a fixed size to it
+  def self.format_with_size(data)
+    # currently size is set to a 8 digit int
+    len = "%08d" % data.to_s.size
+    len + data.to_s
+  end
+
+  # helper method to parse a data field
+  # off the front of a data sequence, using the
+  # formatted size. Returns parsed data field
+  # and remaining data sequence. If optional
+  # class is given, the from_s method will
+  # be invoked w/ the parsed data field and
+  # returned with the remaining data sequence
+  # instead
+  def self.parse_from_formatted(data, data_class = nil)
+     len = data[0...8].to_i
+     parsed = data[8...8+len]
+     remaining = data[8+len...data.size]
+     return parsed, remaining if data_class.nil?
+     return data_class.from_s(parsed), remaining
+  end
+end
+
+# a single field trasnmitted via a message,
+# containing a key / value pair
+class Field
+  attr_accessor :name, :value
+
+  def initialize(args = {})
+    @name   = args[:name].nil?  ? "" : args[:name]
+    @value  = args[:value].nil? ? "" : args[:value]
+  end
+
+  def to_s
+    Formatter::format_with_size(@name) + Formatter::format_with_size(@value)
+  end
+
+  def self.from_s(data)
+    field = Field.new
+    field.name,  data = Formatter::parse_from_formatted(data)
+    field.value, data = Formatter::parse_from_formatted(data)
+    return field
+  end
+end
+
+# header contains various descriptive properies
+# about a message
+class Header
+  attr_accessor :type, :target
+
+  def initialize(args = {})
+     @type   = args[:type].nil?   ? "" : args[:type]
+     @target = args[:target].nil? ? "" : args[:target]
+  end
+
+  def to_s
+    Formatter::format_with_size(@type) + Formatter::format_with_size(@target)
+  end
+
+  def self.from_s(data)
+    header = Header.new
+    header.type,   data = Formatter::parse_from_formatted(data)
+    header.target, data = Formatter::parse_from_formatted(data)
+    return header
+  end
+end
+
+# body consists of a list of data fields
+class Body
+   attr_accessor :fields
+
+   def initialize
+     @fields = []
+   end
+
+   def to_s
+      s = ''
+      @fields.each { |field|
+        fs = field.to_s
+        s += Formatter::format_with_size(fs)
+      }
+      return s
+   end
+
+   def self.from_s(data)
+     body = Body.new
+     while(data != "")
+        field, data = Formatter::parse_from_formatted(data)
+        field = Field.from_s field
+        body.fields.push field
+     end
+     return body
+   end
+end
+
+# message contains a header / body
+class Message
+   attr_accessor :header, :body
+
+   def initialize
+      @header = Header.new
+      @body   = Body.new
+   end
+
+   def to_s
+      Formatter::format_with_size(@header) + Formatter::format_with_size(@body)
+   end
+
+   def self.from_s(data)
+      message = Message.new
+      message.header, data = Formatter::parse_from_formatted(data, Header)
+      message.body,   data = Formatter::parse_from_formatted(data, Body)
+      return message
+   end
+end
+
+end # module Message
+
+end # module Simrpc

data/lib/simrpc/node.rb

@@ -0,0 +1,206 @@
+# simrpc node module
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+#
+# 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.
+
+module Simrpc
+
+# Simrpc Method Message Controller, generates and handles method messages
+class MethodMessageController
+  public
+    # initialize with a specified schema definition
+    def initialize(schema_def)
+      @schema_def = schema_def
+    end
+
+    # generate new new method message, setting the message
+    # target to the specified method name, and setting the fields
+    # on the message to the method arguments
+    def generate(method_name, args)
+       @schema_def.methods.each { |method|
+         if method.name == method_name
+           msg = Message::Message.new
+           msg.header.type = 'request'
+           msg.header.target = method.name
+
+           # loop through each param, convering corresponding
+           # argument to message field and adding it to msg
+           i = 0
+           method.parameters.each { |param|
+             field = Message::Field.new
+             field.name = param.name
+             field.value = param.to_s(args[i], @schema_def)
+             msg.body.fields.push field
+             i += 1
+           }
+
+           return msg
+         end
+       }
+       return nil
+    end
+
+    # should be invoked when a message is received,
+    # takes a message, converts it into a method call, and calls the corresponding
+    # handler in the provided schema. Takes return arguments and sends back to caller
+    def message_received(node, message, reply_to)
+       message = Message::Message::from_s(message)
+       @schema_def.methods.each { |method|
+
+         if method.name == message.header.target
+           Logger.info "received method #{method.name} message "
+
+           # for request messages, dispatch to method handler
+           if message.header.type != 'response' && method.handler != nil
+               # order the params
+               params = []
+               method.parameters.each { |data_field|
+                 value_field = message.body.fields.find { |f| f.name == data_field.name }
+                 params.push data_field.from_s(value_field.value, @schema_def) unless value_field.nil? # TODO what if value_field is nil
+               }
+
+               Logger.info "invoking #{method.name} handler "
+
+               # invoke method handler
+               return_values = method.handler.call(*params)  # FIXME handlers can't use 'return' as this will fall through here
+                                                             # FIXME throw a catch block around this call to catch all handler exceptions
+               return_values = [return_values] unless return_values.is_a? Array
+
+               # if method returns no values, do not return response
+               unless method.return_values.size == 0
+
+                  # consruct and send response message using return values
+                  response = Message::Message.new
+                  response.header.type = 'response'
+                  response.header.target = method.name
+                  (0...method.return_values.size).each { |rvi|
+                    field = Message::Field.new
+                    field.name = method.return_values[rvi].name
+                    field_def = method.return_values.find { |rv| rv.name == field.name }
+                    field.value = field_def.to_s(return_values[rvi], @schema_def) unless field_def.nil? # TODO what if field_def is nil
+                    response.body.fields.push field
+                  }
+                  Logger.info "responding to #{reply_to}"
+                  node.send_message(reply_to, response)
+
+               end
+
+           # for response values just return converted return values
+           else
+               results = []
+               method.return_values.each { |data_field|
+                 value_field = message.body.fields.find { |f| f.name == data_field.name }
+                 results.push data_field.from_s(value_field.value, @schema_def) unless value_field.nil? # TODO what if value_field is nil
+               }
+               return results
+           end
+         end
+       }
+    end
+end
+
+# Simrpc Node represents ths main api which to communicate and send/listen for data.
+class Node
+
+   # Instantiate it w/ a specified id
+   # or one will be autogenerated. Specify schema (or location) containing
+   # data and methods which to invoke and/or handle. Optionally specify
+   # a remote destination which to send new messages to. Automatically listens
+   # for incoming messages.
+   def initialize(args = {})
+      @id = args[:id] if args.has_key? :id
+      @schema = args[:schema]
+      @schema_file = args[:schema_file]
+      @destination = args[:destination]
+
+      if !@schema.nil?
+        @schema_def = Schema::Parser.parse(:schema => @schema)
+      elsif !@schema_file.nil?
+        @schema_def = Schema::Parser.parse(:file => @schema_file)
+      end
+      raise ArgumentError, "schema_def cannot be nil" if @schema_def.nil?
+      @mmc = MethodMessageController.new(@schema_def)
+      @message_lock = Semaphore.new(1)
+      @message_lock.wait
+
+      # FIXME currently not allowing for any other params to be passed into
+      # QpidAdapter::Node such as broker ip or port, NEED TO FIX THIS
+      @qpid_node = QpidAdapter::Node.new(:id => @id)
+      @qpid_node.async_accept { |node, msg, reply_to|
+          results = @mmc.message_received(node, msg, reply_to)
+          message_received(results)
+      }
+   end
+
+   def id
+     return @id unless @id.nil?
+     return @qpid_node.node_id
+   end
+
+   # implements, message_received callback to be notified when qpid receives a message
+   def message_received(results)
+       @message_results = results
+       @message_lock.signal
+   end
+
+   # wait until the node is no longer accepting messages
+   def join
+       @qpid_node.join
+   end
+
+   # add a handler which to invoke when an schema method is invoked
+   def handle_method(method, &handler)
+      @schema_def.methods.each { |smethod|
+         if smethod.name == method.to_s
+             smethod.handler = handler
+             break
+         end
+      }
+   end
+
+   # send method request to remote destination w/ the specified args
+   def send_method(method_name, destination, *args)
+      # generate and send new method message
+      msg = @mmc.generate(method_name, args)
+      @qpid_node.send_message(destination + "-queue", msg)
+
+      # FIXME race condition if response is received b4 wait is invoked
+
+      # block if we are expecting return values
+      if @schema_def.methods.find{|m| m.name == method_name}.return_values.size != 0
+        @message_lock.wait # block until response received
+
+        # return return values
+        #@message_received.body.fields.collect { |f| f.value }
+        return *@message_results
+      end
+   end
+
+   # can invoke schema methods directly on Node instances, this will catch
+   # them and send them onto the destination
+   def method_missing(method_id, *args)
+     send_method(method_id.to_s, @destination, *args)
+   end
+end
+
+end # module Simrpc