Module: Sinatra::RPC

Defined in:
lib/sinatra/rpc.rb,
lib/sinatra/rpc/fault.rb,
lib/sinatra/rpc/utils.rb,
lib/sinatra/rpc/helpers.rb,
lib/sinatra/rpc/version.rb,
lib/sinatra/rpc/serializer.rb,
lib/sinatra/rpc/handler/echo.rb,
lib/sinatra/rpc/serializer/base.rb,
lib/sinatra/rpc/serializer/xmlrpc.rb,
lib/sinatra/rpc/handler/introspection.rb

Overview

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.

Examples:

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

Defined Under Namespace

Modules: Fault, Handler, Helpers, Serializer, Utils Classes: NotFound

Constant Summary collapse

VERSION = 
"0.1.0"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.registered(app) ⇒ Object

Callback executed when the app registers this extension module. Here we set the default property values and register standard error codes and handlers.



86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/sinatra/rpc.rb', line 86

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

Instance Method Details

#add_rpc_handler(namespace = nil, handler) ⇒ Object

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).

Examples:

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

Parameters:

  • namespace (String) (defaults to: nil) —

    the (optional) namespace for all the exposed methods

  • handler (Object, Class) —

    a handler instance, or its class (if a no-arg constructor is available)



75
76
77
78
 
# File 'lib/sinatra/rpc.rb', line 75

def add_rpc_handler(namespace = nil, handler)
  handler = handler.new if Class === handler
  settings.rpc_method_index.merge! Utils.rpc_methods namespace, handler
end

#register_rpc_fault(fault_name, error_code) ⇒ Object

Generate a new fault class. The class will be a subclass of RuntimeError, and always include the Fault module.

Examples:

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
require "sinatra/base"
require "sinatra/rpc"

class MyApp < Sinatra::Base
  register Sinatra::RPC
  register_rpc_fault :some_error, 399
end

Parameters:

  • fault_name (String, Symbol) —

    An identifier for the fault; if the name is e.g. 'bad_request', a new class named BadRequestFault is generated

  • error_code (Integer) —

    A unique numeric code for this fault



55
56
57
 
# File 'lib/sinatra/rpc.rb', line 55

def register_rpc_fault(fault_name, error_code)
  Fault.register fault_name, error_code
end