oskie_rpc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83c95d50dce23208e4a87cd0fdc01b8e7e02cb3c
-  data.tar.gz: e0b414711d5ab9b51479c149c6bd60e20ce5f5ea
+  metadata.gz: c78399fe3ca90c945e034f61daf677e6a722d376
+  data.tar.gz: d1584ec71a777b3dd6078e50acff5073dbf12ec1
 SHA512:
-  metadata.gz: fca7464ec46d3c3fe859684b1e8deb0e78cb6db969b155cb346d545fff2eb707f2e1385a921bf9efc08b6049013bf389249efa491bf1bd156008f28f27ba86d9
-  data.tar.gz: eb23f34873330d8f7fb78f5e3d327cab75fb59242d3bfd96bd1c0d4a0c0fb5abf636b0b42864041985c6e6c26d23c64e89def2df977391ee16b0e2a72ff8399e
+  metadata.gz: f357a816d8347f51871abf2d0e2e8e217afcbf81726f97f6a402e2bf4f4254e8ca4466b11c64e430e0af32f7c782ee44466cda06cbf558c226dbe9c7ad3d797e
+  data.tar.gz: 68dd5517d6d4df394e1800d133cb4b9a7b8ac45177f450bb71215ac17c7f4e9ff0bd0524c14da28ea78e1a6f0a42a6a931e8806fb8d028d6764094b0b1bfd82b

data/README.md

@@ -3,12 +3,13 @@
 Oskie RPC is an extremely simple and modular RPC library for Ruby.
 Design goals include:
 
-- Transport independent so no dependencies on TCP/IP, IO, or any other classes (it simply takes input and gives back output through callbacks).
-- Modular design using the [Filter Chain](https://github.com/chadrem/filter_chain) gem so that the protocol can be modified if you so desire.
+- Transport independent so no dependencies on TCP/IP, IO, or any other classes.
+- Modular protocol design using the [Filter Chain](https://github.com/chadrem/filter_chain).
 - Supports both messages and requests (requests can be replied to, messages can't).
 - Very simple binary protocol with data encoded in JSON.
-- Thread safe.
 - Easy to port to other languages.
+- Bi-directional.
+- Thread safe.
 
 ## Installation
 
@@ -24,9 +25,69 @@ Or install it yourself as:
 
     $ gem install oskie_rpc
 
-## Usage
+## Messages
+
+The ````Message```` class is the basic unit of work for Oskie RPC.
+Messages contain a few simple pieces of data:
+
+- ````command````: This is how you distinguish different types of messages.
+- ````params````: Optional data you pass in addition to a command.
+
+Messages are fire-and-forget.
+
+## Requests
+
+The ````Request```` class is a specialized type of message that expects a response.
+You use them if you need a return value value from the other end.
+Requests support timeouts (see below section on heartbeats).
+The default timeout is 60 seconds.
+
+## Responses
+
+The ````Response```` class is used to respond to a request.
+In general you don't work directly with this class.
+Responses are sent using the ````respond```` method on a request object.
+
+## Processors
+
+The ````Processor```` class is the engine for Oskie RPC.
+It is network agnostic and simply takes input, generates output, and executes callbacks.
+
+    # Create a processor and define its callbacks.
+    processor = OskieRpc::Processor.new do |p|
+      p.on(:message) do |message|
+        puts "Received message: #{message.inspect}"
+      end
+
+      p.on(:request) do |request|
+        puts "Received request: #{request.inspect}"
+        case request.command
+        when 'echo'
+          request.respond do
+            request.params # Last expression of the block is the return value.
+          end
+        end
+      end
+
+      p.on(:output) do |output|
+        puts "Generated output: #{output.inspect}"
+      end
+    end
+
+    # Send a message.
+    message = OskieRpc::Message.new('chat', :message => 'hello world')
+    processor.deliver(message)
+
+    # Simulate receiving a request (it will be echo'ed back).
+    processor << "\x00\x00\x00|{\"type\":\"rpcRequest\",\"request\":{\"command\":\"echo\",\"params\":{\"foo\":\"bar\"},\"messageId\":\"6c10b3ed-9f07-44c2-8f12-3e04cb7792e2\"}}"
+
+#### Heartbeats
 
-Coming soon.
+Processors require an external clock signal to properly timeout requests.
+This is done on purpose so that you can integrate with the timers provided by your networking framework.
+An alternative is to create your own clock using a dedicated thread that periodically wakes up.
+Your clock should call the processor's ````heartbeat```` method to signal that time has changed.
+A good rule of thumb is to call this method once per second.
 
 ## Contributing
 

data/lib/oskie_rpc/exceptions.rb

@@ -2,4 +2,7 @@ module OskieRpc
   class OskieRpcError < RuntimeError; end
   class MissingCallbackError < OskieRpcError; end
   class InvalidStateError < OskieRpcError; end
+  class UnknownPayloadTypeError < OskieRpcError; end
+  class UnknownDeliveryClassError < OskieRpcError; end
+  class ValidationError < OskieRpcError; end
 end

data/lib/oskie_rpc/message.rb

@@ -1,23 +1,43 @@
 module OskieRpc
-  class Message
-    attr_reader :command
-    attr_reader :uuid
-    attr_reader :data
-    attr_reader :processor
+  class Message < Package
+    attr_accessor :command
+    attr_accessor :params
 
-    def initialize(command, opts = {})
+    def initialize(command = '', params = {})
       @command = command
-      @uuid = opts[:uuid] || SecureRandom.uuid
-      @data = opts[:data]
-      @parser = opts[:processor]
+      @params = params
+      @message_id = SecureRandom.uuid
     end
 
-    def to_hash
+    def load(payload)
+      @command = payload['message']['command']
+      @params = payload['message']['params']
+      @message_id = payload['message']['messageId']
+
+      validate!
+
+      self
+    end
+
+    def dump
+      validate!
+
       {
-        :command => @command,
-        :uuid => @uuid,
-        :data => @data
+        'type' => 'rpcMessage',
+        'message' => {
+          'command' => @command,
+          'params' => @params,
+          'messageId' => @message_id
+        }
       }
     end
+
+    def validate!
+      @command.is_a?(String) || raise(ValidationError, "Command is not a string.")
+      @params.is_a?(Hash) || raise(ValidationError, "Params is not a hash.")
+      @message_id.is_a?(String) || raise(ValidationError, "Message ID is not a string.")
+
+      nil
+    end
   end
 end

data/lib/oskie_rpc/package.rb

@@ -0,0 +1,5 @@
+module OskieRpc
+  class Package
+    attr_accessor :message_id
+  end
+end

data/lib/oskie_rpc/processor.rb

@@ -1,33 +1,62 @@
 module OskieRpc
   class Processor
-    def initialize(opts = {}, &block)
-      @opts = opts
-      @lock = Mutex.new
+    def initialize(&block)
+      @lock = Monitor.new
       @input_chain = create_input_chain
       @output_chain = create_output_chain
       @callbacks = {}
+      @requests = SortedSet.new
       @state = :initializing
       block.call(self) if block
       raise MissingCallbackError, :message unless @callbacks[:message]
+      raise MissingCallbackError, :request unless @callbacks[:request]
       raise MissingCallbackError, :output unless @callbacks[:output]
       @state = :initialized
     end
 
     def <<(bytes)
-      @input_chain << bytes
+      @lock.synchronize do
+        @input_chain << bytes
+      end
 
       nil
     end
 
     def on(name, &block)
-      @callbacks[name.to_sym] = block
+      @lock.synchronize do
+        raise InvalidStateError unless @state == :initializing
+        @callbacks[name.to_sym] = block
+      end
 
       nil
     end
 
-    def deliver(message)
-      raise InvalidStateError unless @state == :initialized
-      @output_chain << message.to_hash
+    def deliver(delivery)
+      @lock.synchronize do
+        raise InvalidStateError unless @state == :initialized
+
+        if delivery.is_a?(Request)
+          delivery.__request_sent
+          @requests << delivery
+        end
+
+        @output_chain << delivery.dump
+      end
+
+      nil
+    end
+
+    def heartbeat
+      @lock.synchronize do
+        @requests.each do |request|
+          if request.timed_out?
+            @requests.delete(request)
+            request.__response_failed
+          else
+            return
+          end
+        end
+      end
 
       nil
     end
@@ -38,7 +67,8 @@ module OskieRpc
       FilterChain::Chain.new do |chain|
         chain.add(FilterChain::DemultiplexFilter.new)
         chain.add(FilterChain::DeserializeFilter.new(:format => :json))
-        chain.add(FilterChain::Terminator.new { |message| message_handler(message) })
+        chain.add(FilterChain::ProcFilter.new { |payload| payload_handler(payload) })
+        chain.add(FilterChain::Terminator.new { |delivery| delivery_handler(delivery) })
       end
     end
 
@@ -50,10 +80,45 @@ module OskieRpc
       end
     end
 
+    def payload_handler(payload)
+      message = case payload['type']
+      when 'rpcMessage' then Message.new
+      when 'rpcRequest' then Request.new
+      when 'rpcResponse' then Response.new
+      else
+        raise UnknownPayloadTypeError, payload['type']
+      end
+
+      message.load(payload)
+    end
+
+    def delivery_handler(delivery)
+      case delivery
+      when Message then message_handler(delivery)
+      when Request then request_handler(delivery)
+      when Response then response_handler(delivery)
+      else
+        raise UnknownDeliveryClassError, message.class.name
+      end
+    end
+
     def message_handler(message)
       @callbacks[:message].call(message)
     end
 
+    def request_handler(request)
+      request.__request_received(self)
+      @callbacks[:request].call(request)
+    end
+
+    def response_handler(response)
+      request = @requests.find { |request| request.message_id == response.message_id }
+      return unless request
+      @requests.delete(request) 
+      request.__response_received(response)
+    end
+
+
     def output_handler(bytes)
       @callbacks[:output].call(bytes)
     end

data/lib/oskie_rpc/request.rb

@@ -0,0 +1,96 @@
+module OskieRpc
+  class Request < Package
+    attr_accessor :command
+    attr_accessor :params
+    attr_accessor :timeout # Seconds.
+
+    def initialize(command = '', params = {})
+      @command = command
+      @params = params
+      @timeout = 60
+      @message_id = SecureRandom.uuid
+      @callbacks = {}
+      @state = :initialized
+    end
+
+    def <=>(request)
+      timeout_at <=> request.timeout_at
+    end
+
+    def load(payload)
+      @command = payload['request']['command']
+      @params = payload['request']['params']
+      @message_id = payload['request']['messageId']
+
+      validate!
+
+      self
+    end
+
+    def dump
+      validate!
+
+      {
+        'type' => 'rpcRequest',
+        'request' => {
+          'command' => @command,
+          'params' => @params,
+          'messageId' => @message_id
+        }
+      }
+    end
+
+    def on(name, &block)
+      @callbacks[name.to_sym] = block
+    end
+
+    def timed_out?
+      Time.now.utc > timeout_at
+    end
+
+    def timeout_at
+      @sent_at + timeout
+    end
+
+    def respond
+      raise InvalidStateError unless @state == :received
+      response = Response.new(message_id)
+      response.result = yield
+      @processor.deliver(response)
+
+      nil
+    end
+
+    def validate!
+      @command.is_a?(String) || raise(ValidationError, "Command is not a string.")
+      @params.is_a?(Hash) || raise(ValidationError, "Params is not a hash.")
+      @message_id.is_a?(String) || raise(ValidationError, "Message ID is not a string.")
+
+      nil
+    end
+
+    #
+    # Private API for use by Processor only.
+    #
+
+    def __request_sent
+      @state = :sent
+      @sent_at = Time.now.utc
+    end
+
+    def __request_received(processor)
+      @state = :received
+      @processor = processor
+    end
+
+    def __response_received(response)
+      @state = :responded
+      @callbacks[:response].call(response) if @callbacks[:response]
+    end
+
+    def __response_failed
+      @state = :failed
+      @callbacks[:failure].call if @callbacks[:failure]
+    end
+  end
+end

data/lib/oskie_rpc/response.rb

@@ -0,0 +1,37 @@
+module OskieRpc
+  class Response < Package
+    attr_accessor :result
+
+    def initialize(message_id = nil, result = nil)
+      @message_id = message_id
+      @result = result
+    end
+
+    def load(payload)
+      @result = payload['response']['result']
+      @message_id = payload['response']['messageId']
+
+      validate!
+
+      self
+    end
+
+    def dump
+      validate!
+
+      {
+        'type' => 'rpcResponse',
+        'response' => {
+          'result' => @result,
+          'messageId' => @message_id
+        }
+      }
+    end
+
+    def validate!
+      @message_id.is_a?(String) || raise(ValidationError, "Message ID is not a string.")
+
+      nil
+    end
+  end
+end

data/lib/oskie_rpc/version.rb

@@ -1,3 +1,3 @@
 module OskieRpc
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/oskie_rpc.rb

@@ -5,7 +5,10 @@ require "filter_chain"
 
 require "oskie_rpc/version"
 require "oskie_rpc/exceptions"
+require "oskie_rpc/package"
 require "oskie_rpc/message"
+require "oskie_rpc/request"
+require "oskie_rpc/response"
 require "oskie_rpc/processor"
 
 module OskieRpc

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oskie_rpc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chad Remesch
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-07-08 00:00:00.000000000 Z
+date: 2015-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: filter_chain
@@ -84,7 +84,10 @@ files:
 - lib/oskie_rpc.rb
 - lib/oskie_rpc/exceptions.rb
 - lib/oskie_rpc/message.rb
+- lib/oskie_rpc/package.rb
 - lib/oskie_rpc/processor.rb
+- lib/oskie_rpc/request.rb
+- lib/oskie_rpc/response.rb
 - lib/oskie_rpc/version.rb
 - oskie_rpc.gemspec
 homepage: