sinatra-rpc 0.1.0

data/lib/sinatra/rpc/serializer.rb

@@ -0,0 +1,31 @@
+module Sinatra
+  module RPC
+    # All the classes defined in this module represent serialization
+    # mechanisms for RPC requests/responses.
+    module Serializer
+
+      # Find the right Serializer::Base subclass for the given 
+      # Content-Type HTTP request header.
+      #
+      # @param content_type [String] the value of the Content-Type header
+      # @return [Class] a Serializer class that can be used to
+      #   satisfy the request
+      def find(content_type)
+        @registry[content_type] or @registry[nil]
+      end
+
+      # Add a serializer for a list of content types to the 
+      # internal registry of Serializer classes.
+      def register(serializer_class, content_types)
+        @registry ||= {}
+        content_types.each do |c|
+          @registry[c] = serializer_class
+        end
+      end
+
+      extend self
+    end
+  end
+end
+
+require "sinatra/rpc/serializer/xmlrpc"

data/lib/sinatra/rpc/serializer/base.rb

@@ -0,0 +1,52 @@
+module Sinatra
+  module RPC
+    module Serializer
+      # The base class for all Serializer instances.
+      class Base
+
+        class << self
+          attr_reader :response_content_type
+          
+          # Set the list of content types supported by this serializer.
+          # @param content_types [*String] the list of supported content types;
+          #   if set to `nil`, this serializer is used as a default in case the
+          #   content type is not specified in the request.
+          def content_types(*content_types)
+            Sinatra::RPC::Serializer.register self, content_types
+            @response_content_type = content_types.compact.first
+          end
+        end
+
+        # The content type that should be set in responses. By default
+        # it is the first from the list of content types defined by the class.
+        # @return [String] the content type to set in the response header.
+        def content_type
+          self.class.response_content_type
+        end
+
+        # An hash of options to set with the response content type.
+        # For example, {charset: 'utf-8'} is used in XML-RPC.
+        # The default implementation returns an empty hash.
+        def content_type_options
+          {}
+        end
+
+        # Parse an incoming RPC request. This method must be implemented by
+        # subclasses.
+        # @param request [String] the body of the HTTP POST request.
+        # @return [Array] an array of the form ['handler.rpcMethod', [arg1, arg2, ...]] 
+        def parse(request)
+          raise NotImplementedError
+        end
+
+        # Convert the response object to a string to be used in the body of
+        # the HTTP response. Must be implemented by subclasses.
+        # @param response [Object] any response object
+        # @return [String] a string representation of the response
+        def dump(response)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/rpc/serializer/xmlrpc.rb

@@ -0,0 +1,37 @@
+require 'sinatra/rpc/serializer/base'
+require 'xmlrpc/marshal'
+
+module Sinatra
+  module RPC
+    module Serializer
+      # This class handles XML-RPC calls.
+      class XMLRPC < Base
+        content_types nil, 'text/xml'
+
+        # This initializer creates an internal XMLRPC::Marshal instance.
+        def initialize
+          @xmlrpc = ::XMLRPC::Marshal.new
+        end
+
+        # The charset is set to UTF-8.
+        # (see Base#content_type_options)
+        def content_type_options
+          {charset: 'utf-8'}
+        end
+
+        # (see Base#parse)
+        def parse(request)
+          @xmlrpc.load_call(request)
+        end
+
+        # (see Base#dump)
+        def dump(response)
+          if Sinatra::RPC::Fault === response 
+            response = ::XMLRPC::FaultException.new(response.code, response.message)
+          end
+          @xmlrpc.dump_response(response)
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/rpc/utils.rb

@@ -0,0 +1,107 @@
+require 'method_source'
+module Sinatra
+  module RPC
+    module Utils
+      # Returns the camelcase version of the given string.
+      # 
+      # @param string [String] the string to convert
+      # @param uppercase_first_letter [Boolean] set to true if the first letter of the 
+      #   result needs to be uppercase
+      # @return [String] the converted string
+      # @example
+      #
+      #     Sinatra::RPC::Utils.camelize 'my_test_method', false  # => 'myTestMethod'
+      #     Sinatra::RPC::Utils.camelize 'test_class'             # => 'TestClass'
+      #
+      def camelize(string, uppercase_first_letter = true)
+        tokens = string.to_s.split /_+/
+        first_token = (uppercase_first_letter ? tokens.first.capitalize : tokens.first.downcase)
+        ([first_token] + tokens[1..-1].map(&:capitalize)).join
+      end
+
+      # Converts a camelcase string to its underscore version.
+      #
+      # @param string [String] the string to convert
+      # @return [String] the converted string
+      def underscore(string)
+        word = string.to_s.dup
+        word.gsub!(/::/, '/')
+        word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+      # Extract the documentation for a given object method.
+      #
+      # @param method [Method] a method object
+      # @return [String] the method help, without initial comment characters (#)
+      def method_help(method)
+        method.comment.gsub(/^#\s/m, '').strip
+      end
+
+      # Extract the signature for a given object method, as a list of string starting
+      # with the return type. The information is retrieved only by parsing the documentation,
+      # and the value [['nil']] is returned if no documentation is available.
+      #
+      # @param method [Method] a method object
+      # @return [String] the method signature as a list of strings
+      def method_signature(method)
+        help = method_help(method)
+        params = []
+        ret = nil
+        help.each_line do |l|
+          case l 
+          when /@param[\s\w]+\[(\w+).*\]/
+            params << $1.downcase
+          when /@return[\s\w]+\[(\w+).*\]/
+            ret = $1.downcase
+          end
+        end
+        ret ||= 'nil'
+        [[ret] + params]
+      end
+
+      # Return a hash with all the methods in an object that can be exposed as
+      # RPC methods as keys. The values are themselves hashes containing the 
+      # object, the name of the Ruby method, a method description and its signature.
+      #
+      # @example
+      #
+      #     # A simple class.
+      #     class MyClass
+      #       # A simple method.
+      #       # @param folks [String] people to greet
+      #       # @return [String] the greeting
+      #       def greet(folks); "hi, #{folks}!"; end
+      #     end
+      #
+      #     Sinatra::RPC::Utils.rpc_methods 'myclass', MyClass.new
+      #     # => {'myclass.myMethod' => {
+      #     #      handler:   <MyClass instance>, 
+      #     #      method:    :my_method, 
+      #     #      help:      "A simple method.\n@param folks [String] ...",
+      #     #      signature: [['string', 'string']]
+      #     #    }
+      def rpc_methods(namespace = nil, object)
+        public_methods = object.class.instance_methods - Object.instance_methods
+        method_index = {}
+        public_methods.each do |method_name|
+          method = object.class.instance_method(method_name)
+          rpc_name = camelize method_name, false
+          key = [namespace, rpc_name].compact.join '.'
+          method_index[key] = {
+            handler: object,
+            method:  method_name,
+            help: method_help(method),
+            signature: method_signature(method)
+          }
+        end
+        method_index
+      end
+
+      extend self
+    end
+  end
+end

data/lib/sinatra/rpc/version.rb

@@ -0,0 +1,5 @@
+module Sinatra
+  module RPC
+    VERSION = "0.1.0"
+  end
+end

data/sinatra-rpc.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sinatra/rpc/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "sinatra-rpc"
+  spec.version       = Sinatra::RPC::VERSION
+  spec.authors       = ["Andrea Bernardo Ciddio"]
+  spec.email         = ["bcandrea@gmail.com"]
+  spec.description   = %q{A Sinatra extension module providing RPC server functionality}
+  spec.summary       = %q{The Sinatra::RPC module provides an extension that can be used to build RPC endpoints.}
+  spec.homepage      = "https://github.com/bcandrea/sinatra-rpc"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "method_source", "~> 0.8.0"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "rack-test"
+  spec.add_development_dependency "sinatra"
+end

data/spec/sinatra/rpc/fault_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe Sinatra::RPC::Fault do
+  it 'should generate exception classes' do
+    Sinatra::RPC::Fault.register :very_bad_request, 400
+    Sinatra::RPC::VeryBadRequestFault::CODE.should == 400
+    RuntimeError.should === Sinatra::RPC::VeryBadRequestFault.new
+    Sinatra::RPC::Fault.should === Sinatra::RPC::VeryBadRequestFault.new
+  end
+end

data/spec/sinatra/rpc/handler/echo_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+
+describe Sinatra::RPC::Handler::Echo do
+
+  before(:each) do
+    @echo = Sinatra::RPC::Handler::Echo.new
+  end
+
+  it 'returns the passed in argument' do
+    @echo.echo("a string").should == "a string"
+  end
+end

data/spec/sinatra/rpc/handler/introspection_spec.rb

@@ -0,0 +1,74 @@
+require 'spec_helper'
+
+describe Sinatra::RPC::Handler::Introspection do
+
+  before(:each) do
+    index = {
+      'ns.myMethod' => {
+        handler:   nil,
+        method:    :my_method, 
+        help:      "This is a test method.",
+        signature: [['nil']]
+      },
+      'ns.greet' => {
+        handler:   nil,
+        method:    :greet, 
+        help:      %q{
+Full method doc for greet.
+@param folks [String] people to greet
+@return [String] the greeting
+}.strip,
+        signature: [['string', 'string']]
+      },
+      'ns.bye' => {
+        handler:   nil,
+        method:    :bye, 
+        help:      %q{
+Partially documented.
+@param people [String] the people
+}.strip,
+        signature: [['nil', 'string']]
+      },
+      'ns.soLong' => {
+        handler:   nil,
+        method:    :so_long, 
+        help:      %q{
+Partially documented.
+@return [String] the result
+}.strip,
+        signature: [['string']]
+      },
+      'ns.multi' => {
+        handler:   nil,
+        method:    :multi, 
+        help:      %q{
+Multiple types.
+@param arg [String, Class] the arg
+@return [Array] the result
+}.strip,
+        signature: [['array', 'string']]
+      },
+    }
+    @settings = double('settings', rpc_method_index: index)
+    @app = double('app', settings: @settings)
+    @intro = Sinatra::RPC::Handler::Introspection.new @app
+  end
+
+  it 'should list all the methods in the correct order' do
+    @intro.list_methods.should == %w{ ns.bye ns.greet ns.multi ns.myMethod ns.soLong }
+  end
+
+  it 'should get the method signatures' do
+    @intro.method_signature('ns.multi').should == [['array', 'string']]
+    @intro.method_signature('ns.greet').should == [['string', 'string']]
+  end
+
+  it 'should get the method help' do
+    @intro.method_help('ns.myMethod').should == "This is a test method."
+    @intro.method_help('ns.soLong').should == %q{
+Partially documented.
+@return [String] the result
+}.strip
+  end
+
+end

data/spec/sinatra/rpc/helpers_spec.rb

@@ -0,0 +1,148 @@
+require 'spec_helper'
+
+describe Sinatra::RPC::Helpers do
+
+  before(:all) do
+    @registry = Sinatra::RPC::Serializer.instance_variable_get('@registry').dup
+    module HelpersTest
+      class Serializer1 < Sinatra::RPC::Serializer::Base
+        content_types 'application/x-app1', 'application/x-app2'
+      end
+
+      class Serializer2 < Sinatra::RPC::Serializer::Base
+        content_types nil, 'application/x-app3'
+      end
+
+      class MyClass
+        def my_method(text)
+          "this is #{text}"
+        end
+      end
+
+      class MyApp
+        include Sinatra::RPC::Helpers
+      end
+    end
+  end
+
+  after(:all) do
+    Sinatra::RPC::Serializer.instance_variable_set('@registry', @registry)
+  end
+
+  before(:each) do
+    @app = HelpersTest::MyApp.new
+  end
+
+  context '#select_serializer' do
+    it 'should generate the correct serializer instance' do
+      @app.select_serializer(nil).class.should == HelpersTest::Serializer2
+      @app.select_serializer('application/x-app2').class.should == HelpersTest::Serializer1
+    end
+  end
+
+  context '#call_rpc_method' do
+
+    before(:each) do
+      @app = HelpersTest::MyApp.new
+      @handler = HelpersTest::MyClass.new
+      @settings = double(:settings, 
+        rpc_method_index: {
+          'myClass.myMethod' => {
+            method: :my_method,
+            handler: @handler,
+            help: '',
+            signature: [['string', 'string']]
+          }
+        }
+      )
+      @app.stub(:settings) {@settings}
+    end
+
+    it 'should call the correct method' do
+      @app.call_rpc_method('myClass.myMethod', 'some text').should == 'this is some text'
+    end
+
+    it 'should raise a NotFound exception if the method does not exist' do
+      expect { 
+        @app.call_rpc_method 'myClass.someMethod', [42] 
+      }.to raise_error(Sinatra::RPC::NotFound)
+
+      expect { 
+        @app.call_rpc_method 'anotherMethod', ['arg1', 'arg2'] 
+      }.to raise_error(Sinatra::RPC::NotFound)
+    end
+  end
+
+  context '#handle_rpc' do
+    before(:each) do
+      @app = HelpersTest::MyApp.new
+      @serializer = double('serializer', 
+        parse: ['myClass.myMethod', ['some text']],
+        dump: '<the serialized object>',
+        content_type: 'test/content-type',
+        content_type_options: {})
+      @request_body = double('body', read: '<serialized request>')
+      @request = double('request', body: @request_body, env: {})
+      @app.stub(:content_type)
+      @app.stub(:select_serializer) {@serializer}
+      @app.stub(:call_rpc_method) { 'this is some text' }
+      @app.stub(:halt)
+    end
+
+    it 'should handle a successful RPC call' do
+      @app.handle_rpc(@request).should == '<the serialized object>'
+    end
+    
+    it 'should reject empty requests with a 400 error' do
+      @request_body.stub(:read) {''}
+      @app.should_receive(:halt).with(400).once
+      @app.handle_rpc(@request)
+    end
+
+    it 'should reply with a 404 when the method does not exist' do
+      @app.should_receive(:call_rpc_method).
+        with('myClass.myMethod', ['some text']).ordered.once.
+        and_raise(Sinatra::RPC::NotFound)
+      @app.should_receive(:halt).with(404).ordered.once
+      @app.handle_rpc(@request)
+    end
+
+    context 'with errors' do
+
+      before(:each) do
+        @serializer.stub(:dump) do |ex|
+          ex.message
+        end
+      end
+
+      it 'should transmit back an RPC fault' do
+        Sinatra::RPC::Fault.register(:this_is_a_test, 1234)
+        ex = Sinatra::RPC::ThisIsATestFault.new 'Problems!'
+        @app.should_receive(:call_rpc_method).
+          with('myClass.myMethod', ['some text']).ordered.once.and_raise(ex)
+        @serializer.should_receive(:dump).with(ex).ordered.once
+        @app.handle_rpc(@request).should == 'Problems!'
+      end
+
+      it 'should wrap argument errors' do
+
+        @app.should_receive(:call_rpc_method).
+          with('myClass.myMethod', ['some text']).ordered.once.
+          and_raise(ArgumentError.new('bad argument'))
+        @serializer.should_receive(:dump).with(
+          kind_of(Sinatra::RPC::BadRequestFault)).ordered.once
+        @app.handle_rpc(@request).should == 'bad argument'
+      end
+
+      it 'should wrap generic errors' do
+        @app.should_receive(:call_rpc_method).
+          with('myClass.myMethod', ['some text']).ordered.once.
+          and_raise(RuntimeError.new('a runtime error'))
+        @serializer.should_receive(:dump).with(
+          kind_of(Sinatra::RPC::GenericFault)).ordered.once
+        @app.handle_rpc(@request).should == "RuntimeError: a runtime error"
+      end
+    end
+  end
+
+end