protobuf 1.0.0

data/lib/protobuf/rpc/error.rb

@@ -0,0 +1,34 @@
+require 'protobuf/rpc/rpc.pb'
+
+module Protobuf
+  module Rpc
+    
+    autoload :BadRequestData, 'protobuf/rpc/error/server_error'
+    autoload :BadRequestProto, 'protobuf/rpc/error/server_error'
+    autoload :ServiceNotFound, 'protobuf/rpc/error/server_error'
+    autoload :MethodNotFound, 'protobuf/rpc/error/server_error'
+    autoload :RpcError, 'protobuf/rpc/error/server_error'
+    autoload :RpcFailed, 'protobuf/rpc/error/server_error'
+    
+    autoload :InvalidRequestProto, 'protobuf/rpc/error/client_error'
+    autoload :BadResponseProto, 'protobuf/rpc/error/client_error'
+    autoload :UnknownHost, 'protobuf/rpc/error/client_error'
+    autoload :IOError, 'protobuf/rpc/error/client_error'
+    
+    # Base RpcError class for client and server errors
+    class PbError < StandardError
+      attr_reader :error_type
+      
+      def initialize message='An unknown RpcError occurred', error_type='RPC_ERROR'
+        @error_type = error_type.is_a?(String) ? Protobuf::Socketrpc::ErrorReason.const_get(error_type) : error_type
+        super message
+      end
+      
+      def to_response response
+        response.error = message
+        response.error_reason = @error_type
+      end
+    end
+    
+  end
+end

data/lib/protobuf/rpc/error/client_error.rb

@@ -0,0 +1,31 @@
+require 'protobuf/rpc/error'
+
+module Protobuf
+  module Rpc
+    
+    class InvalidRequestProto < PbError
+      def initialize message='Invalid request type given'
+        super message, 'INVALID_REQUEST_PROTO'
+      end
+    end
+    
+    class BadResponseProto < PbError
+      def initialize message='Bad response type from server'
+        super message, 'BAD_RESPONSE_PROTO'
+      end
+    end
+    
+    class UnkownHost < PbError
+      def initialize message='Unknown host or port'
+        super message, 'UNKNOWN_HOST'
+      end
+    end
+    
+    class IOError < PbError
+      def initialize message='IO Error occurred'
+        super message, 'IO_ERROR'
+      end
+    end
+    
+  end
+end

data/lib/protobuf/rpc/error/server_error.rb

@@ -0,0 +1,43 @@
+require 'protobuf/rpc/rpc.pb'
+
+module Protobuf
+  module Rpc
+    
+    class BadRequestData < PbError
+      def initialize message='Unable to parse request'
+        super message, 'BAD_REQUEST_DATA'
+      end
+    end
+    
+    class BadRequestProto < PbError
+      def initialize message='Request is of wrong type'
+        super message, 'BAD_REQUEST_PROTO'
+      end
+    end
+    
+    class ServiceNotFound < PbError
+      def initialize message='Service class not found'
+        super message, 'SERVICE_NOT_FOUND'
+      end
+    end
+    
+    class MethodNotFound < PbError
+      def initialize message='Service method not found'
+        super message, 'METHOD_NOT_FOUND'
+      end
+    end
+    
+    class RpcError < PbError
+      def initialize message='RPC exception occurred'
+        super message, 'RPC_ERROR'
+      end
+    end
+    
+    class RpcFailed < PbError
+      def initialize message='RPC failed'
+        super message, 'RPC_FAILED'
+      end
+    end
+    
+  end
+end

data/lib/protobuf/rpc/rpc.pb.rb

@@ -0,0 +1,107 @@
+### Generated by rprotoc. DO NOT EDIT!
+### <proto file: rpc.proto>
+# // Copyright (c) 2009 Shardul Deo
+# //
+# // 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.
+# 
+# // Author: Shardul Deo
+# //
+# // Protobufs needed for socket rpcs.
+# 
+# package protobuf.socketrpc;
+# 
+# message Request {
+# 
+#   // RPC service full name
+#   required string service_name = 1;
+#   
+#   // RPC method name
+#   required string method_name = 2;
+#   
+#   // RPC request proto
+#   required bytes request_proto = 3;
+# }
+# 
+# message Response {
+# 
+#   // RPC response proto
+#   optional bytes response_proto = 1;
+#   
+#   // Error, if any
+#   optional string error = 2;
+#   
+#   // Was callback invoked
+#   optional bool callback = 3 [default = false];
+#   
+#   // Error Reason
+#   optional ErrorReason error_reason = 4;
+# }
+# 
+# // Possible error reasons
+# // The server-side errors are returned in the response from the server.
+# // The client-side errors are returned by the client-side code when it doesn't 
+# // have a response from the server.
+# enum ErrorReason {
+# 
+#   // Server-side errors
+#   BAD_REQUEST_DATA = 0; // Server received bad request data
+#   BAD_REQUEST_PROTO = 1; // Server received bad request proto
+#   SERVICE_NOT_FOUND = 2; // Service not found on server
+#   METHOD_NOT_FOUND = 3; // Method not found on server
+#   RPC_ERROR = 4; // Rpc threw exception on server
+#   RPC_FAILED = 5; // Rpc failed on server
+#   
+#   // Client-side errors (these are returned by the client-side code)
+#   INVALID_REQUEST_PROTO = 6; // Rpc was called with invalid request proto
+#   BAD_RESPONSE_PROTO = 7; // Server returned a bad response proto
+#   UNKNOWN_HOST = 8; // Could not find supplied host
+#   IO_ERROR = 9; // I/O error while communicating with server
+# }
+
+require 'protobuf/message/message'
+require 'protobuf/message/enum'
+require 'protobuf/message/extend'
+
+module Protobuf
+  module Socketrpc
+    class Request < ::Protobuf::Message
+      required :string, :service_name, 1
+      required :string, :method_name, 2
+      required :bytes, :request_proto, 3
+    end
+    class Response < ::Protobuf::Message
+      optional :bytes, :response_proto, 1
+      optional :string, :error, 2
+      optional :bool, :callback, 3, :default => false
+      optional :ErrorReason, :error_reason, 4
+    end
+    class ErrorReason < ::Protobuf::Enum
+      define :BAD_REQUEST_DATA, 0
+      define :BAD_REQUEST_PROTO, 1
+      define :SERVICE_NOT_FOUND, 2
+      define :METHOD_NOT_FOUND, 3
+      define :RPC_ERROR, 4
+      define :RPC_FAILED, 5
+      define :INVALID_REQUEST_PROTO, 6
+      define :BAD_RESPONSE_PROTO, 7
+      define :UNKNOWN_HOST, 8
+      define :IO_ERROR, 9
+    end
+  end
+end

data/lib/protobuf/rpc/server.rb

@@ -0,0 +1,183 @@
+require 'eventmachine'
+require 'socket'
+require 'protobuf/common/logger'
+require 'protobuf/rpc/rpc.pb'
+require 'protobuf/rpc/buffer'
+require 'protobuf/rpc/error'
+require 'protobuf/rpc/stat'
+
+module Protobuf
+  module Rpc
+    class Server < EventMachine::Connection
+      include Protobuf::Logger::LogMethods
+      
+      # Initialize a new read buffer for storing client request info
+      def post_init
+        log_debug '[server] Post init, new read buffer created'
+        
+        @stats = Protobuf::Rpc::Stat.new(:SERVER, true)
+        @stats.client = Socket.unpack_sockaddr_in(get_peername)
+        
+        @buffer = Protobuf::Rpc::Buffer.new :read
+        @did_respond = false
+      end
+      
+      # Receive a chunk of data, potentially flushed to handle_client
+      def receive_data data
+        log_debug '[server] receive_data: %s' % data
+        @buffer << data
+        handle_client if @buffer.flushed?
+      end
+      
+      # Invoke the service method dictated by the proto wrapper request object
+      def handle_client
+        @stats.request_size = @buffer.size
+        
+        # Setup the initial request and response
+        @request = Protobuf::Socketrpc::Request.new
+        @response = Protobuf::Socketrpc::Response.new
+        
+        # Parse the protobuf request from the socket
+        log_debug '[server] Parsing request from client'
+        parse_request_from_buffer
+      
+        # Determine the service class and method name from the request
+        log_debug '[server] Extracting procedure call info from request'
+        parse_service_info
+        
+        # Call the service method
+        log_debug '[server] Dispatching client request to service'
+        invoke_rpc_method
+        
+      rescue => error
+        # Ensure we're handling any errors that try to slip out the back door
+        log_error error.message
+        log_error error.backtrace.join("\n")
+        handle_error(error)
+        send_response
+      end
+      
+      private
+      
+      # Assuming all things check out, we can call the service method
+      def invoke_rpc_method
+        # Get a new instance of the service
+        @service = @klass.new
+        
+        # Define our response callback to perform the "successful" response to our client
+        # This decouples the service's rpc method from our response to the client,
+        # allowing the service to be the dictator for when the response should be sent back.
+        #
+        # In other words, we don't send the response once the service method finishes executing
+        # since the service may perform it's own operations asynchronously.
+        @service.on_send_response do |response|
+          unless @did_respond
+            parse_response_from_service(response)
+            send_response
+          end
+        end
+        
+        @service.on_rpc_failed do |error|
+          unless @did_respond
+            handle_error(error)
+            send_response
+          end
+        end
+        
+        # Call the service method
+        log_debug '[server] Invoking %s#%s with request %s' % [@klass.name, @method, @request.inspect]
+        @service.__send__ @method, @request
+      end
+      
+      # Parse the incoming request object into our expected request object
+      def parse_request_from_buffer
+        begin
+          log_debug '[server] parsing request from buffer: %s' % @buffer.data.inspect
+          @request.parse_from_string @buffer.data
+        rescue => error
+          exc = BadRequestData.new 'Unable to parse request: %s' % error.message
+          log_error exc.message
+          raise exc
+        end
+      end
+      
+      # Read out the response from the service method,
+      # setting it on the pb request, and serializing the
+      # response to the protobuf response wrapper
+      def parse_response_from_service response
+        begin
+          expected = @klass.rpcs[@klass][@method].response_type
+          
+          # Cannibalize the response if it's a Hash
+          response = expected.new(response) if response.is_a?(Hash)
+          actual = response.class
+          
+          log_debug '[server] response (should/actual): %s/%s' % [expected.name, actual.name]
+          
+          # Determine if the service tried to change response types on us
+          if expected == actual
+            begin
+              # Response types match, so go ahead and serialize
+              log_debug '[server] serializing response: %s' % response.inspect
+              @response.response_proto = response.serialize_to_string
+            rescue
+              raise BadResponseProto, $!.message
+            end
+          else
+            # response types do not match, throw the appropriate error
+            raise BadResponseProto, 'Response proto changed from %s to %s' % [expected.name, actual.name]
+          end
+        rescue => error
+          log_error error.message
+          log_error error.backtrace.join("\n")
+          handle_error(error)
+        end
+      end
+      
+      # Write the response wrapper to the client
+      def send_response
+        raise 'Response already sent to client' if @did_respond
+        log_debug '[server] Sending response to client: %s' % @response.inspect
+        response_buffer = Protobuf::Rpc::Buffer.new(:write, @response)
+        send_data(response_buffer.write)
+        @stats.response_size = response_buffer.size
+        @stats.end
+        @stats.log_stats
+        @did_respond = true
+      end
+      
+      # Client error handler. Receives an exception object and writes it into the @response
+      def handle_error error
+        log_debug '[server] handle_error: %s' % error.inspect
+        if error.is_a? PbError
+          error.to_response @response
+        elsif error.is_a? ClientError
+          PbError.new(error.message, error.code.to_s).to_response @response
+        else
+          message = error.is_a?(String) ? error : error.message
+          PbError.new(message, 'RPC_ERROR').to_response @response
+        end
+      end
+      
+      # Parses and returns the service and method name from the request wrapper proto
+      def parse_service_info
+        @klass, @method = nil, nil
+        
+        begin
+          @klass = Util.constantize(@request.service_name)
+        rescue
+          raise ServiceNotFound, "Service class #{@request.service_name} is not found"
+        end
+        
+        @method = Util.underscore(@request.method_name).to_sym
+        unless @klass.instance_methods.include?(@method)
+          raise MethodNotFound, "Service method #{@request.method_name} is not defined by the service"
+        end
+        
+        @stats.service = @klass.name
+        @stats.method = @method
+      end
+      
+    end
+  end
+end

data/lib/protobuf/rpc/service.rb

@@ -0,0 +1,244 @@
+require 'protobuf/common/logger'
+require 'protobuf/rpc/client'
+require 'protobuf/rpc/error'
+
+module Protobuf
+  module Rpc
+    
+    # Object to encapsulate the request/response types for a given service method
+    # 
+    RpcMethod = Struct.new "RpcMethod", :service, :method, :request_type, :response_type
+    
+    class Service
+      include Protobuf::Logger::LogMethods
+    
+      attr_reader :request
+      attr_accessor :response, :async_responder
+      private :request, :response, :response=
+      
+      DEFAULT_LOCATION = {
+        :host => 'localhost',
+        :port => 9939
+      }
+      
+      # Class methods are intended for use on the client-side.
+      #
+      class << self
+        
+        # You MUST add the method name to this list if you are adding
+        # instance methods below, otherwise stuff will definitely break
+        NON_RPC_METHODS = %w( rpcs call_rpc on_rpc_failed rpc_failed request response method_missing async_responder on_send_response send_response  )
+        
+        # Override methods being added to the class
+        # If the method isn't already a private instance method, or it doesn't start with rpc_, 
+        # or it isn't in the reserved method list (NON_RPC_METHODS),
+        # We want to remap the method such that we can wrap it in before and after behavior,
+        # most notably calling call_rpc against the method. See call_rpc for more info.
+        def method_added old
+          new_method = :"rpc_#{old}"
+          return if private_instance_methods.include?(new_method) or old =~ /^rpc_/ or NON_RPC_METHODS.include?(old.to_s)
+          
+          alias_method new_method, old
+          private new_method
+          
+          begin
+            define_method(old) do |pb_request|
+              call_rpc old.to_sym, pb_request
+            end
+          rescue ArgumentError => e
+            # Wrap a known issue where an instance method was defined in the class without
+            # it being ignored with NON_RPC_METHODS. 
+            raise ArgumentError, "#{e.message} (Note: This could mean that you need to add the method #{old} to the NON_RPC_METHODS list)"
+          end
+        end
+      
+        # Generated service classes should call this method on themselves to add rpc methods
+        # to the stack with a given request and response type
+        def rpc method, request_type, response_type
+          rpcs[self] ||= {}
+          rpcs[self][method] = RpcMethod.new self, method, request_type, response_type
+        end
+
+        # Shorthand for @rpcs class instance var
+        def rpcs
+          @rpcs ||= {}
+        end
+        
+        # Create a new client for the given service.
+        # See Client#initialize and ClientConnection::DEFAULT_OPTIONS
+        # for all available options.
+        #
+        def client options={}
+          configure
+          Client.new({
+            :service => self,
+            :async => false,
+            :host => self.host,
+            :port => self.port
+          }.merge(options))
+        end
+        
+        # Allows service-level configuration of location.
+        # Useful for system-startup configuration of a service
+        # so that any Clients using the Service.client sugar
+        # will not have to configure the location each time.
+        # 
+        def configure config={}
+          locations[self] ||= {}
+          locations[self][:host] = config[:host] if config.key? :host
+          locations[self][:port] = config[:port] if config.key? :port
+        end
+        
+        # Shorthand call to configure, passing a string formatted as hostname:port
+        # e.g. 127.0.0.1:9933
+        # e.g. localhost:0
+        #
+        def located_at location
+          return if location.nil? or location.downcase.strip !~ /[a-z0-9.]+:\d+/
+          host, port = location.downcase.strip.split ':'
+          configure :host => host, :port => port.to_i
+        end
+        
+        # The host location of the service
+        def host
+          configure
+          locations[self][:host] || DEFAULT_LOCATION[:host]
+        end
+        
+        # The port of the service on the destination server
+        def port
+          configure
+          locations[self][:port] || DEFAULT_LOCATION[:port]
+        end
+      
+        # Shorthand for @locations class instance var
+        def locations
+          @locations ||= {}
+        end
+        
+      end
+      
+      # If a method comes through that hasn't been found, and it
+      # is defined in the rpcs method list, we know that the rpc
+      # stub has been created, but no implementing method provides the
+      # functionality, so throw an appropriate error, otherwise go to super
+      # 
+      def method_missing m, *params
+        if rpcs.key?(m)
+          exc = MethodNotFound.new "#{self}##{m} was defined as a valid rpc method, but was not implemented."
+          log_error exc.message
+          raise exc
+        else
+          log_error '-------------- [service] %s#%s not rpc method, passing to super' % [self.class.name, m.to_s]
+          super m, params
+        end
+      end
+
+      # Convenience wrapper around the rpc method list for a given class
+      def rpcs
+        self.class.rpcs[self.class]
+      end
+      
+      # Callback register for the server when a service
+      # method calls rpc_failed. Called by Service#rpc_failed.
+      def on_rpc_failed &rpc_failure_callback
+        @rpc_failure_callback = rpc_failure_callback
+      end
+      
+      # Automatically fail a service method.
+      # NOTE: This shortcuts the @async_responder paradigm. There is
+      # not any way to get around this currently (and I'm not sure you should want to).
+      #
+      def rpc_failed message="RPC Failed while executing service method #{@current_method}"
+        if @rpc_failure_callback.nil?
+          exc = RuntimeError.new 'Unable to invoke rpc_failed, no failure callback is setup.' 
+          log_error exc.message
+          raise exc
+        end
+        error = message.is_a?(String) ? RpcFailed.new(message) : message
+        log_warn '[service] RPC Failed: %s' % error.message
+        @rpc_failure_callback.call(error)
+      end
+      
+      # Callback register for the server to be notified
+      # when it is appropriate to generate a response to the client.
+      # Used in conjunciton with Service#send_response.
+      # 
+      def on_send_response &responder
+        @responder = responder
+      end
+      
+      # Tell the server to generate response and send it to the client.
+      #
+      # NOTE: If @async_responder is set to true, this MUST be called by
+      # the implementing service method, otherwise the connection
+      # will timeout since no data will be sent.
+      #
+      def send_response
+        if @responder.nil?
+          exc = RuntimeError.new "Unable to send response, responder is nil. It appears you aren't inside of an RPC request/response cycle."
+          log_error exc.message
+          raise exc
+        end
+        @responder.call @response
+      end
+  
+    private
+      
+      # Call the rpc method that was previously privatized.
+      # call_rpc allows us to wrap the normal method call with 
+      # before and after behavior, most notably setting up the request
+      # and response instances.
+      # 
+      # Implementing rpc methods should be aware
+      # that request and response are implicitly available, and
+      # that response should be manipulated during the rpc method,
+      # as there is no way to reliably determine the response like
+      # a normal (http-based) controller method would be able to.
+      #
+      # Async behavior of responding can be achieved in the rpc method
+      # by explicitly setting self.async_responder = true. It is then
+      # the responsibility of the service method to send the response,
+      # by calling self.send_response without any arguments. The rpc
+      # server is setup to handle synchronous and asynchronous responses.
+      #
+      def call_rpc method, pb_request
+        @current_method = method
+        
+        # Allows the service to set whether or not
+        # it would like to asynchronously respond to the connected client(s)
+        @async_responder = false
+        
+        begin
+          # Setup the request
+          @request = rpcs[method].request_type.new
+          @request.parse_from_string pb_request.request_proto
+        rescue
+          exc = BadRequestProto.new 'Unable to parse request: %s' % $!.message
+          log_error exc.message
+          log_error $!.backtrace.join("\n")
+          raise exc
+        end
+        
+        # Setup the response
+        @response = rpcs[method].response_type.new
+
+        log_debug '[service] calling service method %s#%s' % [self.class.name, method]
+        # Call the aliased rpc method (e.g. :rpc_find for :find)
+        __send__("rpc_#{method}".to_sym)
+        log_debug '[service] completed service method %s#%s' % [self.class.name, method]
+        
+        # Pass the populated response back to the server
+        # Note this will only get called if the rpc method didn't explode (by design)
+        if @async_responder
+          log_debug '[service] async request, not sending response (yet)'
+        else
+          log_debug '[service] trigger server send_response'
+          send_response
+        end
+      end
+      
+    end
+    
+  end
+end