farcall 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f05a56fd2addc879cc18a3337bc554cfcb32b5fe
-  data.tar.gz: e106170eb6ea752a5e3e6a6e625561ab68e2e972
+  metadata.gz: 19db29955b2928e4a9994958f18117232d817b06
+  data.tar.gz: 1b5f72295699d3bf5c6e0ac391e4f85ca5e2fe41
 SHA512:
-  metadata.gz: e97aee1efa98146211c2fd40756b53015fb0257dbc7c5a3b7d114183db74e1746c1f63139c07b8e6d561f838654d0f3a5823cea502fe9cb25a305921d2244a15
-  data.tar.gz: ef66b3d81c8ffdf23209e28942811e3fac9496f6b8d8d227a8ab855bd76b02a8be2c8da0c93920c1794d4642f18c430d9aac8365872af2d3f3c5cb2978a6e048
+  metadata.gz: 9ce68694ca7fa01a3cf74ed975ce840de16206f3e31be89f438eb8a50bb159d60cf3bf288b899475ddd5d28075167c17291d247b8f11d43ffdb9c77ee6791d71
+  data.tar.gz: 265eac526e4d18307f84fcb23a14edff249c85d4b27289cd783a36b63746f0e73cff7cc7c4b867f4e391c0ab9ca1c478ff21cb6408a97b1d9eaf7e8d68fb6887

data/README.md

@@ -157,9 +157,10 @@ it could be easily connected to any evented data source.
 
 ## Documentation
 
+* Gem [online docs](http://www.rubydoc.info/gems/farcall)
+
 * [Farcall protocol](https://github.com/sergeych/farcall/wiki)
 
-* Gem [online docs](http://www.rubydoc.info/gems/farcall)
 
 ## Contributing
 

data/lib/farcall.rb

@@ -8,9 +8,14 @@ begin
   require 'farcall/boss_transport'
 rescue LoadError
 end
+begin
 require 'farcall/wsclient_transport'
 require 'farcall/em_wsserver_endpoint'
+rescue LoadError
+  $!.to_s =~ /em-websocket/ or raise
+end
 
+  
 
 module Farcall
   # Your code goes here...

data/lib/farcall/boss_transport.rb

@@ -6,7 +6,7 @@ module Farcall
   class BossTransport < Farcall::Transport
     include TransportBase
 
-    # Create json transport, see Farcall::Transpor#create for parameters
+    # Create json transport, see Farcall::Transport#create for parameters
     def initialize **params
       super()
       setup_streams **params

data/lib/farcall/em_farcall.rb

@@ -1,259 +1,261 @@
-begin
-  require 'hashie'
-  require 'eventmachine'
-  require_relative './promise'
+require 'hashie'
+require 'eventmachine'
+require_relative './promise'
 
+# As the eventmachine callback paradigm is completely different from the threaded paradigm
+# of the Farcall, that runs pretty well under JRuby and in multithreaded MRI, we provide
+# compatible but different implementations: {EmFarcall::Endpoint}, {EmFarcall::Interface}
+# and {EmFarcall::Provider}. Changes to adapt these are minimal except of the callback
+# paradigm. The rest is the same.
+#
+# The eventmachine is not a required dependency, to use EmFarcall place eventmachine _before_
+# _requiring_ _farcall:_
+#
+#     require 'eventmachine'
+#     require 'farcall'
+module EmFarcall
+  
+  # Endpoint that run in the reactor thread of the EM. Eventmachine should run by the time of
+  # creation of the endpoint. All the methods can be called from any thread, not only
+  # EM's reactor thread.
+  #
   # As the eventmachine callback paradigm is completely different from the threaded paradigm
-  # of the Farcall, that runs pretty well under JRuby and in multithreaded MRI, we provide
-  # compatible but different implementations: {EmFarcall::Endpoint}, {EmFarcall::Interface}
-  # and {EmFarcall::Provider}. Changes to adapt these are minimal except of the callback
-  # paradigm. The rest is the same.
+  # of the Farcall, that runs pretty well under
+  # JRuby and in multithreaded MRI, we provide
+  # compatible but different endpoint to run under EM.
   #
-  module EmFarcall
-
-    # Endpoint that run in the reactor thread of the EM. Eventmachine should rin by the time of
-    # creation of the endpoint. All the methods can be called from any thread, not only
-    # EM's reactor thread.
+  # Its main difference is that there is no sync_call, instead, calling remote commands
+  # from the endpoint and/ot interface can provide blocks that are called when the remote
+  # is executed.
+  #
+  # The EM version of the endpoint works with any 2 EM:C:Channels.
+  #
+  class Endpoint
+    
+    # Create new endpoint to work with input and output channels
     #
-    # As the eventmachine callback paradigm is completely different from the threaded paradigm
-    # of the Farcall, that runs pretty well under
-    # JRuby and in multithreaded MRI, we provide
-    # compatible but different endpoint to run under EM.
+    # @param [EM::Channel] input_channel
+    # @param [EM::Channel] output_channel
+    def initialize(input_channel, output_channel, errback=nil, provider: nil)
+      EM.schedule {
+        @input, @output, @errback = input_channel, output_channel, errback
+        @trace                    = false
+        @in_serial                = @out_serial = 0
+        @callbacks                = {}
+        @handlers                 = {}
+        @unnamed_handler          = -> (name, *args, **kwargs) {
+          raise NoMethodError, "method does not exist: #{name}"
+        }
+        @input.subscribe { |data|
+          process_input(data)
+        }
+        if provider
+          @provider         = provider
+          provider.endpoint = self
+        end
+      }
+    end
+    
+    # Set or get provider instance. When provider is set, its public methods are called by the remote
+    # and any possible exception are passed back to caller party. You can use any ruby class instance
+    # everything will work, operators, indexes[] and like.
+    attr_accessor :provider
+    
+    # Call the remote method with specified name and arguments calling block when done. Returns
+    # immediately a {Farcall::Promise} instance which could be used to control remote procedure
+    # invocation result asynchronously and effective.
     #
-    # Its main difference is that there is no sync_call, instead, calling remote commands
-    # from the endpoint and/ot interface can provide blocks that are called when the remote
-    # is executed.
+    # Also, if block is provided, it will be called when the remote will be called and possibly
+    # return some data. It receives single object paramter with two fields: result.error and
+    # result.result. It is also possible to use returned {Farcall::Promise} instance to set
+    # multiple callbacks with ease. Promise callbacks are called _after_ the block.
     #
-    # The EM version of the endpoint works with any 2 EM:C:Channels.
+    # `result.error` is not nil when the remote raised error, then `error[:class]` and
+    # `error.text` are set accordingly.
     #
-    class Endpoint
-
-      # Create new endpoint to work with input and output channels
-      #
-      # @param [EM::Channel] input_channel
-      # @param [EM::Channel] output_channel
-      def initialize(input_channel, output_channel, errback=nil, provider: nil)
-        EM.schedule {
-          @input, @output, @errback = input_channel, output_channel, errback
-          @trace                    = false
-          @in_serial                = @out_serial = 0
-          @callbacks                = {}
-          @handlers                 = {}
-          @unnamed_handler          = -> (name, *args, **kwargs) {
-            raise NoMethodError, "method does not exist: #{name}"
-          }
-          @input.subscribe { |data|
-            process_input(data)
-          }
-          if provider
-            @provider         = provider
-            provider.endpoint = self
+    # if error is nil then result.result receives any return data from the remote method.
+    #
+    # for example:
+    #
+    #   endpoint.call( 'some_func', 10, 20) { |done|
+    #      if done.error
+    #        puts "Remote error class: #{done.error[:class]}: #{done.error.text}"
+    #      else
+    #        puts "Remote returned #{done.result}"
+    #   }
+    #
+    # @param name [String] remote method name
+    # @return [Promise] object that call be used to set multiple handlers on success
+    #           or fail event. {Farcall::Promise#success} receives remote return result on
+    #           success and {Farcall::Promise#fail} receives error object.
+    def call(name, *args, **kwargs, &block)
+      promise = Farcall::Promise.new
+      EM.schedule {
+        @callbacks[@in_serial] = -> (result) {
+          block.call(result) if block != nil
+          if result.error
+            promise.set_fail result.error
+          else
+            promise.set_success result.result
           end
         }
+        send_block cmd: name, args: args, kwargs: kwargs
+      }
+      promise
+    end
+    
+    # Close the endpoint
+    def close
+      super
+    end
+    
+    # Report error via errback and the endpoint
+    def error text
+      STDERR.puts "farcall ws server error #{text}"
+      EM.schedule {
+        @errback.call(text) if @errback
+        close
+      }
+    end
+    
+    # Set handler to perform the named command. Block will be called when the remote party calls
+    # with parameters passed from the remote. The block returned value will be passed back to
+    # the caller.
+    #
+    # If the block raises the exception it will be reported to the caller as an error (depending
+    # on it's platofrm, will raise exception on its end or report error)
+    def on(name, &block)
+      @handlers[name.to_s] = block
+    end
+    
+    # Process remote command. First parameter passed to the block is the method name, the rest
+    # are optional arguments of the call:
+    #
+    #    endpoint.on_command { |name, *args, **kwargs|
+    #      if name == 'echo'
+    #        { args: args, keyword_args: kwargs }
+    #      else
+    #        raise "unknown command"
+    #      end
+    #    }
+    #
+    # raising exceptions from the block cause farcall error to be returned back th the caller.
+    def on_command &block
+      raise "unnamed handler should be present" unless block
+      @unnamed_handler = block
+    end
+    
+    # Same as #on_command (compatibilty method)
+    def on_remote_call &block
+      on_command block
+    end
+    
+    # Get the Farcall::RemoteInterface connnected to this endpoint. Any subsequent calls with
+    # return the same instance.
+    def remote
+      @remote ||= EmFarcall::Interface.new endpoint: self
+    end
+    
+    private
+    
+    # :nodoc: sends block with correct framing
+    def send_block **data
+      data[:serial] = @out_serial
+      @out_serial   += 1
+      @output << data
+    end
+    
+    # :nodoc:
+    def execute_command cmd, ref, args, kwargs
+      kwargs = (kwargs || {}).inject({}) {
+          |all, kv|
+        all[kv[0].to_sym] = kv[1]
+        all
+      }
+      args << kwargs if kwargs && !kwargs.empty?
+      result = if proc = @handlers[cmd.to_s]
+                 proc.call(*args)
+               elsif @provider
+                 provider.send :remote_call, cmd.to_sym, args
+               else
+                 @unnamed_handler.call(cmd, args)
+               end
+      send_block ref: ref, result: result
+    
+    rescue
+      if @trace
+        puts $!
+        puts $!.backtrace.join("\n")
       end
-
-      # Set or get provider instance. When provider is set, its public methods are called by the remote
-      # and any possible exception are passed back to caller party. You can use any ruby class instance
-      # everything will work, operators, indexes[] and like.
-      attr_accessor :provider
-
-      # Call remote with specified name and arguments calling block when done.
-      # if block is provided, it will be called when the remote will be called and possibly return
-      # some data.
-      #
-      # Block if present receives single object paramter with two fields: `result.error` and
-      # `result.result`. It is also possible to use returned {Farcall::Promise} instance to set
-      # multiple callbacks with ease. Promise callbacks are called _after_ the block.
-      #
-      # `result.error` is not nil when the remote raised error, then `error[:class]` and
-      # `error.text` are set accordingly.
-      #
-      # if error is nil then result.result receives any return data from the remote method.
-      #
-      # for example:
-      #
-      #   endpoint.call( 'some_func', 10, 20) { |done|
-      #      if done.error
-      #        puts "Remote error class: #{done.error[:class]}: #{done.error.text}"
-      #      else
-      #        puts "Remote returned #{done.result}"
-      #   }
-      #
-      # @param [String] name command name
-      # @return [Promise] object that call be used to set multiple handlers on success
-      #           or fail event. {Farcall::Promise#succsess} receives remote return result on
-      #           success and {Farcall::Promise#fail} receives error object.
-      def call(name, *args, **kwargs, &block)
-        promise = Farcall::Promise.new
-        EM.schedule {
-          @callbacks[@in_serial] = -> (result) {
-            block.call(result) if block != nil
-            if result.error
-              promise.set_fail result.error
-            else
-              promise.set_success result.result
-            end
-          }
-          send_block cmd: name, args: args, kwargs: kwargs
-        }
-        promise
-      end
-
-      # Close the endpoint
-      def close
-        super
-      end
-
-      # Report error via errback and the endpoint
-      def error text
-        STDERR.puts "farcall ws server error #{text}"
-        EM.schedule {
-          @errback.call(text) if @errback
-          close
-        }
-      end
-
-      # Set handler to perform the named command. Block will be called when the remote party calls
-      # with parameters passed from the remote. The block returned value will be passed back to
-      # the caller.
-      #
-      # If the block raises the exception it will be reported to the caller as an error (depending
-      # on it's platofrm, will raise exception on its end or report error)
-      def on(name, &block)
-        @handlers[name.to_s] = block
-      end
-
-      # Process remote command. First parameter passed to the block is the method name, the rest
-      # are optional arguments of the call:
-      #
-      #    endpoint.on_command { |name, *args, **kwargs|
-      #      if name == 'echo'
-      #        { args: args, keyword_args: kwargs }
-      #      else
-      #        raise "unknown command"
-      #      end
-      #    }
-      #
-      # raising exceptions from the block cause farcall error to be returned back th the caller.
-      def on_command &block
-        raise "unnamed handler should be present" unless block
-        @unnamed_handler = block
-      end
-
-      # Same as #on_command (compatibilty method)
-      def on_remote_call &block
-        on_command block
-      end
-
-      # Get the Farcall::RemoteInterface connnected to this endpoint. Any subsequent calls with
-      # return the same instance.
-      def remote
-        @remote ||= EmFarcall::Interface.new endpoint: self
-      end
-
-      private
-
-      # :nodoc: sends block with correct framing
-      def send_block **data
-        data[:serial] = @out_serial
-        @out_serial   += 1
-        @output << data
-      end
-
-      # :nodoc:
-      def execute_command cmd, ref, args, kwargs
-        kwargs = (kwargs || {}).inject({}) {
-            |all, kv|
-          all[kv[0].to_sym] = kv[1]
-          all
-        }
-        args << kwargs if kwargs && !kwargs.empty?
-        result = if proc = @handlers[cmd.to_s]
-                   proc.call(*args)
-                 elsif @provider
-                   provider.send :remote_call, cmd.to_sym, args
-                 else
-                   @unnamed_handler.call(cmd, args)
-                 end
-        send_block ref: ref, result: result
-
-      rescue
-        if @trace
-          puts $!
-          puts $!.backtrace.join("\n")
-        end
-        send_block ref: ref, error: { class: $!.class.name, text: $!.to_s }
-      end
-
-      # :nodoc: important that this method is called from reactor thread only
-      def process_input data
-        # To be free from :keys and 'keys'
-        data = Hashie::Mash.new(data) unless data.is_a?(Hashie::Mash)
-        if data.serial != @in_serial
-          error "framing error (wrong serial:)"
+      send_block ref: ref, error: { class: $!.class.name, text: $!.to_s }
+    end
+    
+    # :nodoc: important that this method is called from reactor thread only
+    def process_input data
+      # To be free from :keys and 'keys'
+      data = Hashie::Mash.new(data) unless data.is_a?(Hashie::Mash)
+      if data.serial != @in_serial
+        error "framing error (wrong serial:)"
+      else
+        @in_serial += 1
+        if (cmd = data.cmd) != nil
+          execute_command(cmd, data.serial, data.args || [], data.kwargs || {})
         else
-          @in_serial += 1
-          if (cmd = data.cmd) != nil
-            execute_command(cmd, data.serial, data.args || [], data.kwargs || {})
-          else
-            ref = data.ref
-            if ref
-              if (block = @callbacks.delete(ref)) != nil
-                block.call(Hashie::Mash.new(result: data.result, error: data.error))
-              end
-            else
-              error "framing error: no ref in block #{data.inspect}"
+          ref = data.ref
+          if ref
+            if (block = @callbacks.delete(ref)) != nil
+              block.call(Hashie::Mash.new(result: data.result, error: data.error))
             end
+          else
+            error "framing error: no ref in block #{data.inspect}"
           end
         end
       end
     end
-
-    # Interface to the remote provider via Farcall protocols. Works the same as if the object
-    # is local and yields block in return, unlike Farcall::Interface that blocks
+  end
+  
+  # Interface to the remote provider via Farcall protocols. Works the same as if the object
+  # is local and yields block in return, unlike Farcall::Interface that blocks
+  #
+  # RemoteInterface transparently creates methods as you call them to speedup subsequent
+  # calls.
+  #
+  class Interface
+    
+    # Create interface connected to some endpoint ar transpost.
     #
-    # RemoteInterface transparently creates methods as you call them to speedup subsequent
-    # calls.
+    # Please remember that Farcall::Transport instance could be used with only
+    # one connected object, unlike Farcall::Endpoint, which could be connected to several
+    # consumers.
     #
-    class Interface
-
-      # Create interface connected to some endpoint ar transpost.
-      #
-      # Please remember that Farcall::Transport instance could be used with only
-      # one connected object, unlike Farcall::Endpoint, which could be connected to several
-      # consumers.
-      #
-      # @param [Farcall::Endpoint|Farcall::Transport] arg either endpoint or a transport
-      #        to connect interface to
-      def initialize(endpoint)
-        @endpoint = endpoint
-      end
-
-      def method_missing(method_name, *arguments, **kw_arguments, &block)
-        instance_eval <<-End
+    # @param [Farcall::Endpoint|Farcall::Transport] arg either endpoint or a transport
+    #        to connect interface to
+    def initialize(endpoint)
+      @endpoint = endpoint
+    end
+    
+    def method_missing(method_name, *arguments, **kw_arguments, &block)
+      instance_eval <<-End
         def #{method_name} *arguments, **kw_arguments, &block
           @endpoint.call '#{method_name}', *arguments, **kw_arguments, &block
         end
-        End
-        @endpoint.call method_name, *arguments, **kw_arguments, &block
-      end
-
-      def respond_to_missing?(method_name, include_private = false)
-        true
-      end
+      End
+      @endpoint.call method_name, *arguments, **kw_arguments, &block
     end
-
-    class Provider < Farcall::Provider
-
-      attr_accessor :endpoint
-
-      def far_interface
-        endpoint.remote
-      end
-
+    
+    def respond_to_missing?(method_name, include_private = false)
+      true
+    end
+  end
+  
+  class Provider < Farcall::Provider
+    
+    attr_accessor :endpoint
+    
+    def far_interface
+      endpoint.remote
     end
+  
   end
-rescue LoadError
-  $!.to_s =~ /eventmachine/ or raise
 end
 

data/lib/farcall/em_wsserver_endpoint.rb

@@ -1,73 +1,76 @@
-begin
-  require 'em-websocket'
-  require 'eventmachine'
-  require_relative './em_farcall'
+require 'em-websocket'
+require 'eventmachine'
+require_relative './em_farcall'
 
-  module EmFarcall
-
-    # Farcall websocket client. To use it you must add to your Gemfile:
-    #
-    #   gem 'websocket-client-simple'
-    #
-    # then you can use it with EM:
-    #
-    #    endpoint = nil
-    #
-    #    EM::WebSocket.run(params) do |ws|
-    #      ws.onopen { |handshake|
-    #        # Check handshake.path, handshake query
-    #        # for example to select the provider, then connect Farcall to websocket:
-    #        endpoint = EmFarcall::WsServerEndpoint.new ws, provider: WsProvider.new
-    #      }
-    #    end
+module EmFarcall
+  
+  # Farcall websocket client, based on the websocket-client-simple gem. We do not put it into
+  # dependencies as it is not always needed, so add to your Gemfile first:
+  #
+  #   gem 'websocket-client-simple'
+  #
+  # and do not forget to require eventmachine before requiring the farcall. Now you can use it
+  # with EM:
+  #
+  #    require 'eventmachine'
+  #    require 'farcall'
+  #
+  #    # ....
+  #
+  #    endpoint = nil
+  #
+  #    EM::WebSocket.run(params) do |ws|
+  #      ws.onopen { |handshake|
+  #        # Check handshake.path, handshake query
+  #        # for example to select the provider, then connect Farcall to websocket:
+  #        endpoint = EmFarcall::WsServerEndpoint.new ws, provider: WsProvider.new
+  #      }
+  #    end
+  #
+  # now we can use it as usual: remote can call provder method, and we can call remote:
+  #
+  #    endpoint.remote.do_something( times: 4) { |result|
+  #    }
+  #
+  #
+  # We do not include it into gem dependencies as it uses EventMachine
+  # which is not needed under JRuby and weight alot (the resto of Farcall plays well with jruby
+  # and MRI threads)
+  #
+  # Due to event-driven nature of eventmachine, WsServerEndpoint uses special version of
+  # {EmFarcall::Endpoint} and {EmFarcall::WsProvider} which are code compatible with regular
+  # farcall classes except for the callback-style calls where appropriate.
+  class WsServerEndpoint < EmFarcall::Endpoint
+    
+    # Create endpoint with the already opened websocket instance. Note that all the handshake
+    # should be done prior to construct endpoint (e.g. you may want to have different endpoints
+    # for different paths and arguments)
     #
-    # now we can use it as usual: remote can call provder method, and we can call remote:
+    # See {EmFarcall::Endpoint} for methods to call remote interface and process remote requests.
     #
-    #    endpoint.remote.do_something( times: 4) { |result|
-    #    }
-    #
-    #
-    # We do not include it into gem dependencies as it uses EventMachine
-    # which is not needed under JRuby and weight alot (the resto of Farcall plays well with jruby
-    # and MRI threads)
-    #
-    # Due to event-driven nature of eventmachine, WsServerEndpoint uses special version of
-    # {EmFarcall::Endpoint} and {EmFarcall::WsProvider} which are code compatible with regular
-    # farcall classes except for the callback-style calls where appropriate.
-    class WsServerEndpoint < EmFarcall::Endpoint
-
-      # Create endpoint with the already opened websocket instance. Note that all the handshake
-      # should be done prior to construct endpoint (e.g. you may want to have different endpoints
-      # for different paths and arguments)
-      #
-      # See {EmFarcall::Endpoint} for methods to call remote interface and process remote requests.
-      #
-      # @param [EM::WebSocket] websocket socket in open state (handshake should be passed)
-      def initialize websocket, **kwargs
-        @input  = EM::Channel.new
-        @output = EM::Channel.new
-        super(@input, @output, **kwargs)
-
-        websocket.onmessage { |data|
-          @input << unpack(data)
-        }
-        @output.subscribe { |data|
-          websocket.send(pack data)
-        }
-      end
-
-      def unpack data
-        JSON.parse data
-      end
-
-      def pack data
-        JSON[data]
-      end
-
+    # @param [EM::WebSocket] websocket socket in open state (handshake should be passed)
+    def initialize websocket, **kwargs
+      @input  = EM::Channel.new
+      @output = EM::Channel.new
+      super(@input, @output, **kwargs)
+      
+      websocket.onmessage { |data|
+        @input << unpack(data)
+      }
+      @output.subscribe { |data|
+        websocket.send(pack data)
+      }
     end
-
+    
+    def unpack data
+      JSON.parse data
+    end
+    
+    def pack data
+      JSON[data]
+    end
+  
   end
-rescue LoadError
-  $!.to_s =~ /em-websocket/ or raise
+
 end
 

data/lib/farcall/endpoint.rb

@@ -31,8 +31,8 @@ module Farcall
 
       init_proc.call(self) if init_proc
 
+      # @!visibility private
       def push_input data
-        p 'me -- pusj!', data
         @in_buffer << data
         drain
       end
@@ -61,7 +61,7 @@ module Farcall
       @close_handler = block
     end
 
-    # :nodoc:
+    # @!visibility private
     def abort reason, exception = nil
       puts "*** Abort: reason #{reason || exception.to_s}"
       @abort_hadnler and @abort_hadnler.call reason, exception
@@ -78,13 +78,18 @@ module Farcall
       @close_handler and @close_handler.call
     end
 
-    # Call remote party. Retruns immediately. When remote party answers, calls the specified block
-    # if present. The block should take |error, result| parameters. If result's content hashes
-    # or result itself are instances of th Hashie::Mash. Error could be nil or
-    # {'class' =>, 'text' => } Hashie::Mash hash. result is always nil if error is presented.
+    # Call the remote party, non blocking, returns {Farcall::Promise} instance to handle the remote
+    # return valy asynchronously (recommended way).
     #
-    # Usually, using Farcall::Endpoint#interface or
-    # Farcall::RemoteInterface is more effective rather than this low-level method.
+    # Optionally the block could be provided
+    # that takes |error, result| parameters. Error must be  nil or
+    #
+    #     Hashie::Mash.new({'class' =>, 'text' => text [, data: {some_data}] })
+    #
+    # if error is presented, the result is always the nil.
+    #
+    # Usually, using {#remote} which returns
+    # {Farcall::Interface} is more effective rather than this low-level method.
     #
     # The returned {Farcall::Promise} instance let add any number of callbacks on commend execution,
     # success or failure.
@@ -140,7 +145,7 @@ module Farcall
         same_thread or resource.wait(mutex)
       }
       if error
-        raise Farcall::RemoteError.new(error['class'], error['text'])
+        raise Farcall::RemoteError.new(error['class'], error['text'], error['data'])
       end
       result
     end
@@ -171,8 +176,9 @@ module Farcall
     end
 
 
-    # Get the Farcall::RemoteInterface connnected to this endpoint. Any subsequent calls with
+    # Get the {Farcall::Interface} connnected to this endpoint. Any subsequent calls with
     # return the same instance.
+    # @return [Farcall::Interface] the remote interface instance
     def remote
       @remote ||= Farcall::Interface.new endpoint: self
     end
@@ -224,8 +230,9 @@ module Farcall
           rescue Exception => e
             # puts e
             # puts e.backtrace.join("\n")
-
-            _send ref: serial, error: { 'class' => e.class.name, 'text' => e.to_s }
+           error_data = { 'class' => e.class.name, 'text' => e.to_s }
+           e.respond_to?(:data) and error_data[:data] = e.data
+            _send ref: serial, error: error_data
           end
 
         when ref
@@ -300,14 +307,15 @@ module Farcall
 
   end
 
-  # Intervace to the remote provider via Farcall protocols. Works the same as if the object
-  # would be in local data, but slower :) The same as calling Farcall::Endpoint#interface
-  #
-  # RemoteInterface transparently creates methods as you call them to speedup subsequent
-  # calls.
+  # Interface to the remote provider via Farcall protocols. Works the same as the normal, local
+  # object, but slower. This interface is returned by {Farcall::Endpoint#remote}. The Interface
+  # transparently creates methods as you call them to speed up subsequent calls.
   #
   # There is no way to check that the remote responds to some method other than call it and
-  # catch the exception
+  # catch the exception.
+  #
+  # See {Farcall::RemoteError} for more information on passing errors.
+  #
   #
   class Interface
 
@@ -317,7 +325,7 @@ module Farcall
     # one connected object, unlike Farcall::Endpoint, which could be connected to several
     # consumers.
     #
-    # @param [Farcall::Endpoint|Farcall::Transport] arg either endpoint or a transport
+    # @param arg [Farcall::Endpoint|Farcall::Transport] either endpoint or a transport
     #        to connect interface to
     def initialize endpoint: nil, transport: nil, provider: nil, **params
       @endpoint = if endpoint
@@ -328,8 +336,10 @@ module Farcall
       provider and @endpoint.provider = provider
     end
 
+    # the {Farcall::Endpoint} to which this interface is connected.
     attr :endpoint
 
+    # used internally to synthesize the proxy method.
     def method_missing(method_name, *arguments, **kw_arguments, &block)
       instance_eval <<-End
         def #{method_name} *arguments, **kw_arguments
@@ -339,6 +349,7 @@ module Farcall
       @endpoint.sync_call method_name, *arguments, **kw_arguments
     end
 
+    # used internally to synthesize the proxy method.
     def respond_to_missing?(method_name, include_private = false)
       true
     end

data/lib/farcall/transport.rb

@@ -4,12 +4,30 @@ module Farcall
   class Error < StandardError
   end
 
-  # The error occured while executin remote method
+  # The error occured while executin remote method. Inf an exception is raused while executing remote
+  # method, it will be passed back and raised in the caller thread with an instance of this class.
+  #
+  # The remote can throw regular or extended errors.
+  # Extended errors can pass any data to the other end, which will be available as {#data}.
+  #
+  # To carry error data just raise any exception which respnd_to(:data), which should return hash
+  # with any application specific error data, as in this sample error class:
+  #
+  #    class MyError < StandardError
+  #        def data
+  #          { foo: bar }
+  #        end
+  #    end
+  #
   class RemoteError < Error
+    # The class of the remote error. Usually string name of the class or any other useful string
+    # identifier.
     attr :remote_class
+    # data passed by the remote error or an empty hash
+    attr :data
 
-    def initialize remote_class, text
-      @remote_class = remote_class
+    def initialize remote_class, text, data={}
+      @remote_class, @data = remote_class, data
       super "#{remote_class}: #{text}"
     end
   end
@@ -27,7 +45,7 @@ module Farcall
     #
     #   - socket: connect transport to some socket (should be connected)
     #
-    #   - input and aoutput: two stream-like objects which support read(length) and write(data)
+    #   - input and output: two stream-like objects which support read(length) and write(data)
     #                        parameters
     #
     def self.create format: :json, **params

data/lib/farcall/version.rb

@@ -1,3 +1,3 @@
 module Farcall
-  VERSION = "0.4.1"
+  VERSION = "0.4.3"
 end

data/spec/endpoint_spec.rb

@@ -44,7 +44,7 @@ end
 describe 'endpoint' do
   include Farcall
 
-  it 'runs on commands' do
+  it 'runs commands' do
     tc = Farcall::LocalConnection.new
 
     ea = Farcall::Endpoint.new tc.a
@@ -56,6 +56,26 @@ describe 'endpoint' do
     rs = eb.remote.command_one("uno", 'due', tre: 3)
     rs.return_one[0].should == ['uno', 'due']
     rs.return_one[1].should == { 'tre' => 3}
+  end
+  
+  it 'return extended errors' do
+    class ExtendedError < StandardError
+      def data
+        { extended: 'information'}
+      end
+    end
+
+    tc = Farcall::LocalConnection.new
+
+    ea = Farcall::Endpoint.new tc.a
+    eb = Farcall::Endpoint.new tc.b
+
+    ea.on('emit_extended_error') { |args, kwargs|
+      raise ExtendedError, "SOME TEXT"
+    }
+    expect( ->{eb.remote.emit_extended_error("uno", 'due', tre: 3)} ).to raise_error { |error|
+      error.data['extended'].should == 'information'
+    }
 
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: farcall
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - sergeych
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-01 00:00:00.000000000 Z
+date: 2016-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie