sinatra-rpc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8fcab4c48c8b4a2f1ed7b7dfbd1c3671020b1ae9
+  data.tar.gz: a7857d2902d7bb8780f36287738e6b11122d157a
+SHA512:
+  metadata.gz: c17ffccd1215344c8fa82c37a1f02996f42310e8c2e410776e81a4abbfd81c3fa968b5f44da3555c3ca035f2d24e4db67bee843af1b35475de7582ee37ce2f22
+  data.tar.gz: cd9e615a3eec9dc3941bcbc842d6b009a64eb45dfcaa4f20d116d9e6ddaed3ab27385d2d2fe863b7065e60f640b2d087a2f73f2748ba667788c0e2d42d837cc2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andrea Bernardo Ciddio
+
+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,113 @@
+[![Build Status](https://travis-ci.org/bcandrea/sinatra-rpc.png?branch=master)](https://travis-ci.org/bcandrea/sinatra-rpc)
+[![Coverage Status](https://coveralls.io/repos/bcandrea/sinatra-rpc/badge.png)](https://coveralls.io/r/bcandrea/sinatra-rpc)
+
+# Sinatra::Rpc
+
+A simple [Sinatra extension module](http://www.sinatrarb.com/extensions.html) providing the functionality of an 
+[RPC server](http://wikipedia.org/wiki/Remote_procedure_call).
+
+This module allows exposure of all the public methods of any object via RPC. The only supported serialization 
+method is [XML-RPC](http://wikipedia.org/wiki/XML-RPC) at the moment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'sinatra-rpc'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sinatra-rpc
+
+## Usage
+
+### Minimal example
+
+The most basic example involves the definition of a _handler_ class first:
+
+```ruby
+class MyHandler
+  # A greeting method.
+  # @param people [String] the people to greet
+  # @return [String] the greeting
+  def hello(people)
+    "Hello, #{people}!"
+  end
+end
+```
+
+The class does not need to include any module or implement a specific API; however, its methods need to be 
+properly documented (following the [YARD](http://yardoc.org) conventions) to take advantage of the built-in 
+introspection (more on that later).
+
+Once the handler is defined, it can be added to a standard Sinatra application by registering the 
+`Sinatra::RPC` extension.
+
+```ruby
+require 'spec_helper'
+require 'sinatra/base'
+
+class MyApp < Sinatra::Base
+  register Sinatra::RPC
+  add_rpc_handler MyHandler
+
+  post '/RPC2' do
+    handle_rpc request
+  end
+end
+```
+
+This application class will respond to XMLRPC POST requests sent to the '/RPC2' path. It can be easily tested
+with the Ruby [built-in XMLRPC client](http://www.ruby-doc.org/stdlib/libdoc/xmlrpc/rdoc/XMLRPC/Client.html):
+
+```ruby
+require 'xmlrpc/client'
+cli = XMLRPC::Client.new_from_uri 'http://myserver/RPC2'
+cli.http_header_extra = {"accept-encoding" => "identity"}
+cli.call 'hello', 'World'  # => this call should return 'Hello, World!'
+```
+
+(the extra header is needed because of a bug in Ruby 2.0.0 and 2.1.0, see https://bugs.ruby-lang.org/issues/8182).
+
+### Namespacing and multiple handlers
+
+Of course multiple objects can be registered as handlers. The `add_rpc_handler` method takes an optional 
+namespace parameter that can be used to group and organize them.
+
+```ruby
+require 'spec_helper'
+require 'sinatra/base'
+
+class MyApp < Sinatra::Base
+  register Sinatra::RPC
+  add_rpc_handler MyHandler
+  add_rpc_handler 'customHandler', CustomHandlerClass.new(:some_argument)
+
+  post '/RPC2' do
+    handle_rpc request
+  end
+end
+```
+
+As you can see, handler instances can be passed as well as classes. 
+
+### Echo server and introspection
+
+The RPC server implements the commonly adopted introspection interface for XML-RPC: the `system.listMethods`, 
+`system.methodHelp` and `system.methodSignature` methods are automatically available. The metadata is only extracted
+from the YARD-style comments in the handler classes, so expect inaccurate results if the code is not completely
+documented.
+
+Another facility is a simple `test.echo` method, which just return the passed argument.
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/sinatra/rpc.rb

@@ -0,0 +1,99 @@
+require "sinatra/rpc/version"
+require "sinatra/rpc/helpers"
+require "sinatra/rpc/fault"
+require "sinatra/rpc/handler/echo"
+require "sinatra/rpc/handler/introspection"
+
+module Sinatra
+  # This extension provides the functionality of an RPC server. 
+  # The resulting server will handle all POST requests to /RPC2 and dispatch methods
+  # to the underlying handler objects. For example, calling the 'myHandler.myMethod'
+  # method will actually execute
+  #
+  #     my_handler.my_method
+  #
+  # on the target handler. RPC methods are usually camelcased, so an automatic 
+  # conversion to and from standard method names with underscores is performed at registration.
+  #
+  # @example Application class
+  #     require "sinatra/base"
+  #     require "sinatra/rpc"
+  #     
+  #     class MyApp < Sinatra::Base   
+  #       register Sinatra::RPC
+  #       
+  #       # Map custom error codes to Ruby exceptions: this will
+  #       # generate a class named SomeErrorFault
+  #       register_rpc_fault :some_error, 399
+  #       
+  #       # Add a new sub-handler in the 'myHandler' namespace
+  #       add_rpc_handler 'myHandler', MyHandlerClass.new(1, 2, 3, 4)
+  #       
+  #       # The class name is enough if there is a no-arg constructor
+  #       add_rpc_handler 'otherHandler', OtherHandler
+  #       
+  #       # If the handler namespace is omitted, all the methods are added directly 
+  #       # to the server (empty) namespace
+  #       add_rpc_handler MyDefaultRPCHandler
+  #
+  #       # Define the RPC endpoint (it must be a POST request)
+  #       post '/RPC2' do
+  #         handle_rpc(request)
+  #       end
+  #     end
+  module RPC
+
+    # (see Fault.register)
+    # @example
+    #     require "sinatra/base"
+    #     require "sinatra/rpc"
+    #         
+    #     class MyApp < Sinatra::Base
+    #       register Sinatra::RPC
+    #       register_rpc_fault :some_error, 399
+    #     end
+    def register_rpc_fault(fault_name, error_code)
+      Fault.register fault_name, error_code
+    end
+
+    # Add a new RPC handler object. If specified, the namespace is used as a
+    # prefix for all the RPC method calls. All the public methods exposed by the 
+    # handler object will be made available as RPC methods (with a camelcase name).
+    #
+    # @param namespace [String] the (optional) namespace for all the exposed methods
+    # @param handler [Object, Class] a handler instance, or its class (if a no-arg 
+    #   constructor is available)
+    # @example
+    #     require "sinatra/base"
+    #     require "sinatra/rpc"
+    #         
+    #     class MyApp < Sinatra::Base
+    #       register Sinatra::RPC
+    #       add_rpc_handler 'list', MyListInterface
+    #       add_rpc_handler BaseObject.new(some_status)
+    #     end
+    def add_rpc_handler(namespace = nil, handler)
+      handler = handler.new if Class === handler
+      settings.rpc_method_index.merge! Utils.rpc_methods namespace, handler
+    end
+
+    # A custom exception raised when a call is made to a non-existent handler or
+    # method.
+    class NotFound < RuntimeError; end
+
+    # Callback executed when the app registers this extension module. Here we set
+    # the default property values and register standard error codes and handlers.
+    def self.registered(app)
+      app.helpers Helpers
+
+      # Initialize the method index
+      app.set(:rpc_method_index, {})
+
+      # Register the echo handler class
+      app.add_rpc_handler 'test', Handler::Echo
+
+      # Register the introspection handler class
+      app.add_rpc_handler 'system', Handler::Introspection.new(app)
+    end
+  end
+end

data/lib/sinatra/rpc/fault.rb

@@ -0,0 +1,39 @@
+require "sinatra/rpc/utils"
+module Sinatra
+  module RPC
+
+    # This module is used to generate all custom RPC errors.
+    module Fault
+      # Generate a new fault class. The class will be a subclass of RuntimeError,
+      # and always include the Fault module.
+      #
+      # @param fault_name [String, Symbol] An identifier for the fault; if
+      #   the name is e.g. 'bad_request', a new class named BadRequestFault
+      #   is generated
+      # @param error_code [Integer] A unique numeric code for this fault
+      # @example
+      #     Sinatra::RPC::Fault.register :bad_request, 400
+      #     Sinatra::RPC::BadRequestFault::CODE                       # => 400
+      #     raise Sinatra::RPC::BadRequestFault, "Bad request"
+      #     RuntimeError === Sinatra::RPC::BadRequestFault.new        # => true
+      #     Sinatra::RPC::Fault === Sinatra::RPC::BadRequestFault.new # => true
+      def self.register(fault_name, error_code)
+        fault_class = Class.new(RuntimeError) do
+          include Sinatra::RPC::Fault
+          def code
+            self.class.const_get 'CODE'
+          end
+        end
+      
+        fault_class.const_set 'CODE', error_code
+
+        class_name = "#{Sinatra::RPC::Utils.camelize fault_name}Fault"
+        Sinatra::RPC.const_set(class_name, fault_class)
+      end
+
+      # Register some generic fault codes (can be overridden)
+      register :generic, -1
+      register :bad_request, 100
+    end
+  end
+end

data/lib/sinatra/rpc/handler/echo.rb

@@ -0,0 +1,17 @@
+module Sinatra
+  module RPC
+    module Handler
+      # A simple test handler. Its only purpose is to provide a method that 
+      # returns the passed string.
+      class Echo
+
+        # A simple echo method. It returns the passed string.
+        # @param object [String] the string to return
+        # @return [String] the string itself
+        def echo(string)
+          string
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/rpc/handler/introspection.rb

@@ -0,0 +1,44 @@
+module Sinatra
+  module RPC
+    module Handler
+      # The instrospection handler can be used to display metadata about the
+      # RPC server. It adds the `listMethods`, `methodSignature` and `methodHelp` RPC methods to 
+      # the `system` namespace.
+      class Introspection
+
+        # The initializer requires a reference the current application.
+        #
+        # @param app [Sinatra::Base] the current Sinatra application
+        def initialize(app)
+          @app = app
+        end
+
+        # List the available methods.
+        # @return [Array] the array of methods exposed by this RPC server.
+        def list_methods
+          index.keys.sort
+        end
+        
+        # Return the signature of the given method.
+        # @param method_name [String] the method name in the form `handler.methodName`.
+        # @return [Array] a list of the form [return, param1, param2, ...].
+        def method_signature(method_name)
+          index[method_name][:signature]
+        end
+        
+        # Return a help for the given method.
+        # @param method_name [String] the method name in the form `handler.methodName`.
+        # @return [String] a description of the method.
+        def method_help(method_name)
+          index[method_name][:help]
+        end
+
+        private
+
+          def index
+            @app.settings.rpc_method_index
+          end
+      end
+    end
+  end
+end

data/lib/sinatra/rpc/helpers.rb

@@ -0,0 +1,70 @@
+require 'sinatra/rpc/serializer'
+module Sinatra
+  module RPC
+    # Some methods to include in the app class.
+    module Helpers
+      
+      # Generate a serializer instance suitable for the incoming RPC request.
+      # (see Sinatra::RPC::Serializer.find)
+      def select_serializer(content_type)
+        Sinatra::RPC::Serializer.find(content_type).new
+      end
+
+      # Execute an RPC method with the given name and arguments.
+      #
+      # @param method [String] the RPC method name, e.g. 'system.listMethods'
+      # @param arguments [Array] the list of arguments
+      # @return [Object] the return value of the method call on the target handler
+      def call_rpc_method(method, arguments)
+        m = settings.rpc_method_index[method]
+        raise Sinatra::RPC::NotFound if m.nil?
+        m[:handler].send m[:method], *arguments
+      end
+
+      # Handle RPC requests. This method should be called inside a POST definition.
+      # @param request the incoming HTTP request object
+      # @example
+      #     class MyApp < Sinatra:Base
+      #       register Sinatra::RPC
+      #       add_rpc_handler MyHandlerClass
+      #
+      #       post '/RPC2' do
+      #         handle_rpc(request)
+      #       end
+      #     end
+      def handle_rpc(request)
+        # The request/response serializer can be XML-RPC (the default) 
+        # or any serializer implemented as a subclass of Sinatra::RPC::Serializer::Base.
+        # The serializer class is chosen by reading the 'Content-Type' header in the request.
+        serializer = select_serializer(request.env['CONTENT_TYPE'])
+        
+        body = request.body.read
+
+        # An empty request is not acceptable in RPC.
+        if body.empty?
+          halt 400
+        end
+
+        # Generate the response.
+        resp = begin
+          # Parse the contents of the request.
+          method, arguments = serializer.parse body
+
+          # Execute the method call.
+          call_rpc_method(method, arguments)
+        rescue Sinatra::RPC::NotFound
+          halt 404
+        rescue Sinatra::RPC::Fault => ex
+          ex
+        rescue ArgumentError => ex
+          Sinatra::RPC::BadRequestFault.new(ex.message)
+        rescue Exception => ex
+          Sinatra::RPC::GenericFault.new("#{ex.class.name}: #{ex.message}")
+        end
+ 
+        content_type(serializer.content_type, serializer.content_type_options)
+        serializer.dump(resp)
+      end
+    end
+  end
+end