farcall 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e62f0ec5501d7053137341f5ec5f46100b692b61
-  data.tar.gz: 9549befd37e328bef65639d99953ee15bae8da2c
+  metadata.gz: 339d4022a832e4cb3a7f54a253ec9b7628d31cab
+  data.tar.gz: 0daea40eb900be7e661790743a6b756229c0870e
 SHA512:
-  metadata.gz: 37f168b9631e06851ca3ebb9f84b19dd145836878210a3d7050b343b43f6e57c9bf7790f1969e9fb951270e941a7a10b14bb0f9b537ed6c2e6d805989ce2f974
-  data.tar.gz: 103a6f0f987801726f1876bf6f696926aada0644ed815d6ec50a06d04ced6c483f972d4011494957daec606aadc7b34e0a00793aa3e74123248bb7529b470f07
+  metadata.gz: 28b1ef4372a5fd8d01900096af1d2360aae63bc4bbe3e973cb181d55db5a3dcad91c1d7f6fe1c3c947f4b97b8e562753a2d879453aba5490843ecb562f8909e2
+  data.tar.gz: fe16ade1825ff61a668ff12438c5d6befce8c14a34cbe52f446bd27c2447175c324b7e862577c5b401960e9d3e38d1869d336bc543ffd3ca36b1c18ac72de900

data/README.md

@@ -2,15 +2,18 @@
 
 ## News
 
-Since 0.3.0 farcall gem provides websocket client and server out of the box. 
+* websocket client and server out of the box. ./javascript folder there is compatible client implementation that works in most browsers with WebSocket support. Just add it to you web project and enjoy.
+
+* buffering of incoming data in transport to not loose incoming packets beofre Endpoint is connected
 
 ## Description
 
 The simple and elegant cross-platform RPC protocol that uses any formatter/transport capable of
 transmitting dictionary-like objects, for example, JSON, 
 [BOSS](https://github.com/sergeych/boss_protocol), XML, BSON and many others. This gem
-supports out of the box JSON and [BOSS](https://github.com/sergeych/boss_protocol) protocols and
-streams and sockets as the media.
+provides out of the box JSON and [BOSS](https://github.com/sergeych/boss_protocol) protocols and
+websockets (clientm server, and javascript version for the browser or mayme some node app),
+ EventMachine channels, streams and sockets.
 
 There is also optional support for eventmachine based wbesocket server and regular client websocket
 connection. All you need is to include gem 'em-websocket' and/or gem 'websocket-client-simple'. 

data/javascript/farcall_wsclient.coffee

@@ -0,0 +1,278 @@
+root = exports ? this
+# Farcall RPC protocol client over WebSocket transport.
+#
+# This script has no external dependencies except that if you want to use self-test, you'll
+# need underscore.js. Test silently fails if can't find it.
+#
+# See protocol at github: https://github.com/sergeych/farcall/
+#
+# provided under MIT license.
+#
+# @author real.sergeych@gmail.com
+#
+class root.WsFarcall
+
+  # Create transport connected to the given url. A shortcut of (new WsFarrcall(url))
+  @open: (url) ->
+    new WsFarcall(url)
+
+  # Construct a protocol endpoint connected to the given url (must be ws:// or wss:// websocket
+  # url)
+  constructor: (@url) ->
+    @in_serial = 0
+    @out_serial = 0
+    @openHandlers = []
+    @closeHandlers = []
+    @ws = new WebSocket(@url)
+    @connected = false
+    @promises = {}
+    @commandHandlers = {}
+    @ws.onopen = =>
+      @connected = true
+      cb(this) for cb in @openHandlers
+
+    @ws.onclose = =>
+      @connected = false
+      cb(this) for cb in @closeHandlers
+
+    @ws.onmessage = (message) =>
+      @trace and console.log ">>> #{message.data}"
+      @_receive(JSON.parse message.data)
+
+  # add open callback. The callback takes a single argument - the WsFarcall instance
+  onopen: (callback) ->
+    @openHandlers.push callback
+
+  # add close callback. The callback takes a single argument - the WsFarcall instance
+  onclose: (callback) ->
+    @closeHandlers.push callback
+
+  # close the protocol and socket
+  close: ->
+    @ws.close()
+
+  # Call remote function with the specified name. Arguments can be list and.or keyword arguments.
+  # The Farcall arguments can be a list, a dictionary (keywords hash), or both. If the last argument
+  # is the object, it will be treated as dictionary argument. Add extra {} to the end of list if
+  # need.
+  #
+  # Returns Promise instance so you can add .success() (or .done()), fail() and always() handlers to
+  # it. On success callback receives whatever data remote function has returned, on error it receives
+  # the arcall standard error object, e.g. { error: { class: string, text: another_sting} } object.
+  #
+  # always handler receives and object { result: {}, error: {}} where only one of the two is set
+  #
+  call: (name, args...) ->
+    [args, kwargs] = splitArgs(args)
+    promise = @promises[@out_serial] = new Promise()
+    @_send cmd: name, args: args, kwargs: kwargs
+    promise
+
+  # Add an local remote-callable function. The callback receives whatever arguments are send from
+  # thre remote caller and its returned value will be passed to the remote. On error it should throw
+  # an exception.
+  on: (name, callback) ->
+    @commandHandlers[name] = callback
+
+  _receive: (data) ->
+    if data.serial != @in_serial++
+      console.error "farcall framing error"
+      @close()
+    else
+      if data.ref != undefined
+        promise = @promises[data.ref]
+        delete @promises[data.ref]
+        if data.error == undefined
+          promise.setDone(data.result)
+        else
+          promise.setFail(data.error)
+      else
+        @_processCall data
+
+  _send: (params) ->
+    params.serial = @out_serial++
+    params = JSON.stringify(params)
+    @trace and console.log "<<< #{params}"
+    @ws.send params
+
+  _processCall: (data) ->
+    handler = @commandHandlers[data.cmd]
+    if handler
+      try
+        data.args.push data.kwargs
+        @_send ref: data.serial, result: handler(data.args...)
+      catch e
+        @_send ref: data.serial, error: {class: 'RuntimeError', text: e.message}
+    else
+      @_send
+        ref: data.serial, error: {class: 'NoMethodError', text: "method not found: #{data.cmd}"}
+
+  @selfTest: (url, callback) ->
+    if _?.isEqual(1, 1)
+      p1 = false
+      p2 = false
+      p3 = false
+      cb = false
+      cbr = false
+      done = false
+      WsFarcall.open(url + '/fartest').onopen (fcall) ->
+        fcall.call('ping', 1, 2, 3, {hello: 'world'})
+        .done (data) ->
+          p1 = checkEquals(data, {pong: [1, 2, 3, {hello: 'world'}]})
+        fcall.call('ping', 2, 2, 3, {hello: 'world'})
+        .done (data) ->
+          p2 = checkEquals(data, {pong: [2, 2, 3, {hello: 'world'}]})
+        fcall.call('ping', 3, 2, 3, {hello: 'world'})
+        .done (data) ->
+          p3 = checkEquals(data, {pong: [3, 2, 3, {hello: 'world'}]})
+
+        fcall.on 'test_callback', (args...) ->
+          cb = checkEquals(args, [5, 4, 3, {hello: 'world'}])
+          # The callback request should have time to be processed
+          setTimeout ->
+                       done = true
+                       ok = p1 and p2 and p3 and cb and cbr
+                       text = switch
+                         when !cb
+                           'callback was not called or wrong data'
+                         when !cbr
+                           'callback request did not return'
+                         else
+                           if ok then '' else 'ping data wrong'
+                       callback(ok, text)
+                     , 80
+
+        fcall.call('callback', 'test_callback', 5, 4, 3, hello: 'world')
+        .done (data) ->
+          cbr = true
+
+      setTimeout ->
+                   callback(false, 'timed out') if !done
+                 , 5000
+    else
+      # can't pass test = we need underscore for it
+      callback(false, "Can't test: need underscpre.js")
+
+# Promise object let set any number of callbacks on the typical comletion events, namely success,
+# failure and operation is somehow completed (always).
+#
+# The promise has 3 states: initial (operation us inder way), done and failed. When the operation
+# is done or failed, attempt to add new handlers of the proper type will cause it immediate
+# invocation.
+#
+# Promise can be set to equer success or error only once. All suitable handlers are called one time
+# when the state is set.
+root.WsFarcall.Promise = class Promise
+
+  constructor: ->
+    [@done_handlers, @fail_handlers, @always_handlers] = ([] for i in [1..3])
+    @state = null
+    @data = @error = undefined
+
+  # Add callback on the success event. Can be called any number of times, all callbacks will be
+  # invoked. If the state is already set to done, the callback fires immediately.
+  #
+  # callback receives whatever data passed to the #setSuccess() call.
+  done: (callback) ->
+    if @state
+      callback(@data) if @state == 'done'
+    else
+      @done_handlers.push callback
+    this
+
+  # same as done()
+  success: (callback) ->
+    @done(callback)
+
+  # Add callback on the failure event. Can be called any number of times, all callbacks will be
+  # invoked. If the state is already set to failure, the callback fires immediately.
+  #
+  # callback receives whatever data passed to the #setFail() call.
+  fail: (callback) ->
+    if @state
+      callback(@error) if @state == 'fail'
+    else
+      @fail_handlers.push callback
+    this
+
+  # Add callback on the both sucess and failure event. Can be called any number of times, all
+  # callbacks will be invoked. If the state is already set to eqither done or failure, the callback
+  # fires immediately.
+  #
+  # callback receives { error: {class: c. text: t}, result: any } object where only one (error or
+  # result) exist.
+  #
+  # always callbacks are executed after all of #success() or #fail().
+  always: (callback) ->
+    if @state
+      callback data: @data, error: @error
+    else
+      @always_handlers.push callback
+    this
+
+  # set promise to success state. If the state is already set to any, does noting. Calls all
+  # corresponding callbacks passing them the `data` parameter.
+  setSuccess: (data) ->
+    if !@state
+      @state = 'done'
+      @data = data
+      cb(data) for cb in @done_handlers
+      @done = null
+      @_fireAlways()
+    this
+
+  # same as #setSuccess()
+  setDone: (data) ->
+    @setSuccess data
+
+  # set promise to failure state. If the state is already set to any, does noting. Calls all
+  # corresponding callbacks passing them the `data` parameter.
+  setFail: (error) ->
+    if !@state
+      @state = 'fail'
+      @error = error
+      cb(error) for cb in @fail_handlers
+      @fail = null
+      @_fireAlways()
+    this
+
+  isSuccess: ->
+    @state == 'done'
+
+  isFail: ->
+    @state == 'fail'
+
+  # same as #isFail
+  isError: ->
+    @state == 'fail'
+
+  # promise is either done of fail (e.g. completed)
+  isCompleted: ->
+    !!@state
+
+  _fireAlways: ->
+    cb({error: @error, data: @data}) for cb in @always_handlers
+    @always = null
+
+
+# Split javascript arguments array to args and kwargs of the Farcall notaion
+# e.g. if the last argument is the pbject, it will be treated as kwargs.
+splitArgs = (args) ->
+  last = args[args.length - 1]
+  if typeof(last) == 'object'
+    [args[0..-2], last]
+  else
+    [args, {}]
+
+
+# For self-test only, relies on underscore.js
+checkEquals = (a, b, text) ->
+  if _.isEqual a, b
+    true
+  else
+    console.error "#{text ? 'ERROR'}: not equal:"
+    console.error "expected: #{JSON.stringify b}"
+    console.error "got:      #{JSON.stringify a}"
+    false
+
+

data/javascript/farcall_wsclient.js

@@ -0,0 +1,379 @@
+// Generated by CoffeeScript 1.8.0
+(function() {
+  var Promise, checkEquals, root, splitArgs,
+    __slice = [].slice;
+
+  root = typeof exports !== "undefined" && exports !== null ? exports : this;
+
+  root.WsFarcall = (function() {
+    WsFarcall.open = function(url) {
+      return new WsFarcall(url);
+    };
+
+    function WsFarcall(url) {
+      this.url = url;
+      this.in_serial = 0;
+      this.out_serial = 0;
+      this.openHandlers = [];
+      this.closeHandlers = [];
+      this.ws = new WebSocket(this.url);
+      this.connected = false;
+      this.promises = {};
+      this.commandHandlers = {};
+      this.ws.onopen = (function(_this) {
+        return function() {
+          var cb, _i, _len, _ref, _results;
+          _this.connected = true;
+          _ref = _this.openHandlers;
+          _results = [];
+          for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+            cb = _ref[_i];
+            _results.push(cb(_this));
+          }
+          return _results;
+        };
+      })(this);
+      this.ws.onclose = (function(_this) {
+        return function() {
+          var cb, _i, _len, _ref, _results;
+          _this.connected = false;
+          _ref = _this.closeHandlers;
+          _results = [];
+          for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+            cb = _ref[_i];
+            _results.push(cb(_this));
+          }
+          return _results;
+        };
+      })(this);
+      this.ws.onmessage = (function(_this) {
+        return function(message) {
+          _this.trace && console.log(">>> " + message.data);
+          return _this._receive(JSON.parse(message.data));
+        };
+      })(this);
+    }
+
+    WsFarcall.prototype.onopen = function(callback) {
+      return this.openHandlers.push(callback);
+    };
+
+    WsFarcall.prototype.onclose = function(callback) {
+      return this.closeHandlers.push(callback);
+    };
+
+    WsFarcall.prototype.close = function() {
+      return this.ws.close();
+    };
+
+    WsFarcall.prototype.call = function() {
+      var args, kwargs, name, promise, _ref;
+      name = arguments[0], args = 2 <= arguments.length ? __slice.call(arguments, 1) : [];
+      _ref = splitArgs(args), args = _ref[0], kwargs = _ref[1];
+      promise = this.promises[this.out_serial] = new Promise();
+      this._send({
+        cmd: name,
+        args: args,
+        kwargs: kwargs
+      });
+      return promise;
+    };
+
+    WsFarcall.prototype.on = function(name, callback) {
+      return this.commandHandlers[name] = callback;
+    };
+
+    WsFarcall.prototype._receive = function(data) {
+      var promise;
+      if (data.serial !== this.in_serial++) {
+        console.error("farcall framing error");
+        return this.close();
+      } else {
+        if (data.ref !== void 0) {
+          promise = this.promises[data.ref];
+          delete this.promises[data.ref];
+          if (data.error === void 0) {
+            return promise.setDone(data.result);
+          } else {
+            return promise.setFail(data.error);
+          }
+        } else {
+          return this._processCall(data);
+        }
+      }
+    };
+
+    WsFarcall.prototype._send = function(params) {
+      params.serial = this.out_serial++;
+      params = JSON.stringify(params);
+      this.trace && console.log("<<< " + params);
+      return this.ws.send(params);
+    };
+
+    WsFarcall.prototype._processCall = function(data) {
+      var e, handler;
+      handler = this.commandHandlers[data.cmd];
+      if (handler) {
+        try {
+          data.args.push(data.kwargs);
+          return this._send({
+            ref: data.serial,
+            result: handler.apply(null, data.args)
+          });
+        } catch (_error) {
+          e = _error;
+          return this._send({
+            ref: data.serial,
+            error: {
+              "class": 'RuntimeError',
+              text: e.message
+            }
+          });
+        }
+      } else {
+        return this._send({
+          ref: data.serial,
+          error: {
+            "class": 'NoMethodError',
+            text: "method not found: " + data.cmd
+          }
+        });
+      }
+    };
+
+    WsFarcall.selfTest = function(url, callback) {
+      var cb, cbr, done, p1, p2, p3;
+      if (typeof _ !== "undefined" && _ !== null ? _.isEqual(1, 1) : void 0) {
+        p1 = false;
+        p2 = false;
+        p3 = false;
+        cb = false;
+        cbr = false;
+        done = false;
+        WsFarcall.open(url + '/fartest').onopen(function(fcall) {
+          fcall.call('ping', 1, 2, 3, {
+            hello: 'world'
+          }).done(function(data) {
+            return p1 = checkEquals(data, {
+              pong: [
+                1, 2, 3, {
+                  hello: 'world'
+                }
+              ]
+            });
+          });
+          fcall.call('ping', 2, 2, 3, {
+            hello: 'world'
+          }).done(function(data) {
+            return p2 = checkEquals(data, {
+              pong: [
+                2, 2, 3, {
+                  hello: 'world'
+                }
+              ]
+            });
+          });
+          fcall.call('ping', 3, 2, 3, {
+            hello: 'world'
+          }).done(function(data) {
+            return p3 = checkEquals(data, {
+              pong: [
+                3, 2, 3, {
+                  hello: 'world'
+                }
+              ]
+            });
+          });
+          fcall.on('test_callback', function() {
+            var args;
+            args = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
+            cb = checkEquals(args, [
+              5, 4, 3, {
+                hello: 'world'
+              }
+            ]);
+            return setTimeout(function() {
+              var ok, text;
+              done = true;
+              ok = p1 && p2 && p3 && cb && cbr;
+              text = (function() {
+                switch (false) {
+                  case !!cb:
+                    return 'callback was not called or wrong data';
+                  case !!cbr:
+                    return 'callback request did not return';
+                  default:
+                    if (ok) {
+                      return '';
+                    } else {
+                      return 'ping data wrong';
+                    }
+                }
+              })();
+              return callback(ok, text);
+            }, 80);
+          });
+          return fcall.call('callback', 'test_callback', 5, 4, 3, {
+            hello: 'world'
+          }).done(function(data) {
+            return cbr = true;
+          });
+        });
+        return setTimeout(function() {
+          if (!done) {
+            return callback(false, 'timed out');
+          }
+        }, 5000);
+      } else {
+        return callback(false, "Can't test: need underscpre.js");
+      }
+    };
+
+    return WsFarcall;
+
+  })();
+
+  root.WsFarcall.Promise = Promise = (function() {
+    function Promise() {
+      var i, _ref;
+      _ref = (function() {
+        var _i, _results;
+        _results = [];
+        for (i = _i = 1; _i <= 3; i = ++_i) {
+          _results.push([]);
+        }
+        return _results;
+      })(), this.done_handlers = _ref[0], this.fail_handlers = _ref[1], this.always_handlers = _ref[2];
+      this.state = null;
+      this.data = this.error = void 0;
+    }
+
+    Promise.prototype.done = function(callback) {
+      if (this.state) {
+        if (this.state === 'done') {
+          callback(this.data);
+        }
+      } else {
+        this.done_handlers.push(callback);
+      }
+      return this;
+    };
+
+    Promise.prototype.success = function(callback) {
+      return this.done(callback);
+    };
+
+    Promise.prototype.fail = function(callback) {
+      if (this.state) {
+        if (this.state === 'fail') {
+          callback(this.error);
+        }
+      } else {
+        this.fail_handlers.push(callback);
+      }
+      return this;
+    };
+
+    Promise.prototype.always = function(callback) {
+      if (this.state) {
+        callback({
+          data: this.data,
+          error: this.error
+        });
+      } else {
+        this.always_handlers.push(callback);
+      }
+      return this;
+    };
+
+    Promise.prototype.setSuccess = function(data) {
+      var cb, _i, _len, _ref;
+      if (!this.state) {
+        this.state = 'done';
+        this.data = data;
+        _ref = this.done_handlers;
+        for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+          cb = _ref[_i];
+          cb(data);
+        }
+        this.done = null;
+        this._fireAlways();
+      }
+      return this;
+    };
+
+    Promise.prototype.setDone = function(data) {
+      return this.setSuccess(data);
+    };
+
+    Promise.prototype.setFail = function(error) {
+      var cb, _i, _len, _ref;
+      if (!this.state) {
+        this.state = 'fail';
+        this.error = error;
+        _ref = this.fail_handlers;
+        for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+          cb = _ref[_i];
+          cb(error);
+        }
+        this.fail = null;
+        this._fireAlways();
+      }
+      return this;
+    };
+
+    Promise.prototype.isSuccess = function() {
+      return this.state === 'done';
+    };
+
+    Promise.prototype.isFail = function() {
+      return this.state === 'fail';
+    };
+
+    Promise.prototype.isError = function() {
+      return this.state === 'fail';
+    };
+
+    Promise.prototype.isCompleted = function() {
+      return !!this.state;
+    };
+
+    Promise.prototype._fireAlways = function() {
+      var cb, _i, _len, _ref;
+      _ref = this.always_handlers;
+      for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+        cb = _ref[_i];
+        cb({
+          error: this.error,
+          data: this.data
+        });
+      }
+      return this.always = null;
+    };
+
+    return Promise;
+
+  })();
+
+  splitArgs = function(args) {
+    var last;
+    last = args[args.length - 1];
+    if (typeof last === 'object') {
+      return [args.slice(0, -1), last];
+    } else {
+      return [args, {}];
+    }
+  };
+
+  checkEquals = function(a, b, text) {
+    if (_.isEqual(a, b)) {
+      return true;
+    } else {
+      console.error("" + (text != null ? text : 'ERROR') + ": not equal:");
+      console.error("expected: " + (JSON.stringify(b)));
+      console.error("got:      " + (JSON.stringify(a)));
+      return false;
+    }
+  };
+
+}).call(this);

data/lib/farcall/boss_transport.rb

@@ -8,18 +8,13 @@ module Farcall
 
     # Create json transport, see Farcall::Transpor#create for parameters
     def initialize **params
+      super()
       setup_streams **params
       @formatter = Boss::Formatter.new(@output)
       @formatter.set_stream_mode
-    end
-
-    def on_data_received= block
-      super
-      if block && !@thread
-        @thread = Thread.start {
-          load_loop
-        }
-      end
+      @thread = Thread.start {
+        load_loop
+      }
     end
 
     def send_data hash
@@ -39,7 +34,7 @@ module Farcall
 
     def load_loop
       Boss::Parser.new(@input).each { |object|
-        on_data_received and on_data_received.call object
+        push_input object
       }
     rescue Errno::EPIPE
       close

data/lib/farcall/em_farcall.rb

@@ -1,6 +1,7 @@
 begin
   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
@@ -60,7 +61,9 @@ begin
       # if block is provided, it will be called when the remote will be called and possibly return
       # some data.
       #
-      # Block receives single object paramter with two fields: `result.error` and `result.result`.
+      # 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.
@@ -77,15 +80,23 @@ begin
       #   }
       #
       # @param [String] name command name
-      # @return [Endpoint] self
+      # @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 {
-          if block
-            @callbacks[@in_serial] = block
-          end
+          @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
         }
-        self
+        promise
       end
 
       # Close the endpoint

data/lib/farcall/endpoint.rb

@@ -1,4 +1,5 @@
 require 'hashie'
+require_relative 'promise'
 
 module Farcall
 
@@ -20,9 +21,22 @@ module Farcall
 
     # Create endpoint connected to some transport
     # @param [Farcall::Transport] transport
-    def initialize(transport)
+    def initialize(transport, init_proc=nil)
       @transport                  = transport
       @in_serial                  = @out_serial = 0
+      @send_lock    = Mutex.new
+      @receive_lock = Mutex.new
+      @handlers     = {}
+      @waiting      = {}
+
+      init_proc.call(self) if init_proc
+
+      def push_input data
+        p 'me -- pusj!', data
+        @in_buffer << data
+        drain
+      end
+
       @transport.on_data_received = -> (data) {
         begin
           _received(data)
@@ -30,11 +44,10 @@ module Farcall
           abort :format_error, $!
         end
       }
+    end
 
-      @send_lock    = Mutex.new
-      @receive_lock = Mutex.new
-      @handlers     = {}
-      @waiting      = {}
+    def self.open(transport, &block)
+      Endpoint.new(transport, block)
     end
 
     # The provided block will be called if endpoint functioning will be aborted.
@@ -70,20 +83,28 @@ module Farcall
     # 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.
     #
-    # It is desirable to use Farcall::Endpoint#interface or
-    # Farcall::RemoteInterface rather than this low-level method.
+    # Usually, using Farcall::Endpoint#interface or
+    # Farcall::RemoteInterface 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.
     #
     # @param [String] name of the remote command
+    # @return [Farcall::Promise] instance
     def call(name, *args, **kwargs, &block)
+      promise = Farcall::Promise.new
       @send_lock.synchronize {
-        if block != nil
-          @waiting[@out_serial] = {
-              time: Time.new,
-              proc: block
+          @waiting[@out_serial] = -> (error, result) {
+            block.call(error, result) if block
+            if error
+              promise.set_fail error
+            else
+              promise.set_success result
+            end
           }
           _send(cmd: name.to_s, args: args, kwargs: kwargs)
-        end
       }
+      promise
     end
 
     # Call the remote party and wait for the return.
@@ -210,7 +231,7 @@ module Farcall
         when ref
 
           ref or abort 'no reference in return'
-          (w = @waiting.delete ref) != nil and w[:proc].call(error, result)
+          (proc = @waiting.delete ref) != nil and proc.call(error, result)
 
         else
           abort 'unknown command'

data/lib/farcall/json_transport.rb

@@ -92,18 +92,13 @@ module Farcall
 
     # Create json transport, see Farcall::Transpor#create for parameters
     def initialize delimiter: "\x00", **params
+      super()
       setup_streams **params
       @delimiter = delimiter
       @dlength   = -delimiter.length
-    end
-
-    def on_data_received= block
-      super
-      if block && !@thread
-        @thread = Thread.start {
-          load_loop
-        }
-      end
+      @thread = Thread.start {
+        load_loop
+      }
     end
 
     def send_data hash
@@ -126,7 +121,7 @@ module Farcall
       while !@input.eof?
         buffer << @input.read(1)
         if buffer[@dlength..-1] == @delimiter
-          on_data_received and on_data_received.call(JSON.parse(buffer[0...@dlength]))
+          push_input JSON.parse(buffer[0...@dlength])
           buffer = ''
         end
       end

data/lib/farcall/promise.rb

@@ -0,0 +1,113 @@
+module Farcall
+  # Promise let set multiple callbacks on different completion events: success, fail and completion.
+  # Promisee guarantte that corresponing callbacks will be called and only once. Callbacks added
+  # after completion are being called immediately.
+  #
+  # Promise state can be changed only once by calling either #set_success( or #set_fail().
+  # Its subsequent invocations raise errors.
+  #
+  class Promise
+
+    # returns data passed to the call to #set_success(data), or nil
+    attr :data
+
+    # returns data passed to the call to #set_success(error), or nil
+    attr :error
+
+    def initialize
+      @state                   = nil
+      @success, @fail, @always = [], [], []
+    end
+
+    def succsess?
+      @state == :success
+    end
+
+    def fail?
+      @state == :fail
+    end
+
+    # the promise is completed after one of #set_success(data) and #set_fail(error) is called.
+    def completed?
+      @state == :completed
+    end
+
+    # Add handler for the success event. If the promise is already #success? then the block
+    # is called immediately, otherwise when and if the promise reach this state.
+    #
+    # block receives data parameter passed to #set_success(data)
+    #
+    # @return [Proomise] self
+    def success &block
+      if !completed?
+        @success << block
+      elsif succsess?
+        block.call(@data)
+      end
+      self
+    end
+
+    # Add handler for the fail event. If the promise is already #fail? then the block
+    # is called immediately, otherwise when and if the promise reach this state.
+    #
+    # Block receives error parameter passed to the #set_fail(data)
+    #
+    # @return [Proomise] self
+    def fail &block
+      if !completed?
+        @fail << block
+      elsif fail?
+        block.call(@error)
+      end
+      self
+    end
+
+    # Add handler to the completion event that will receive promise instance as the parameter (thus
+    # able to check state and ready #data or #error value).
+    #
+    # Note that `always` handlers are called after `success` or `fail` ones.
+    #
+    # @return [Proomise] self
+    def always &block
+      if !completed?
+        @always << block
+      else
+        block.call(self)
+      end
+      self
+    end
+
+    # same as #always
+    alias finished always
+
+    # Set the promise as #completed? with #success? state and invoke proper handlers passing `data`
+    # which is also available with #data property.
+    #
+    # If invoked when already #completed?, raises error.
+    def set_success data
+      raise "state is already set" if @state
+      @state = :success
+      @data  = data
+      invoke @success, data
+    end
+
+    # Set the promise as #completed? with #fail? state and invoke proper handlers. passing `error`
+    # which is also available with #error property.
+    #
+    # If invoked when already #completed?, raises error.
+    def set_fail error
+      raise "state is already set" if @state
+      @state = :fail
+      @error = error
+      invoke @fail, error
+    end
+
+    private
+
+    def invoke list, data
+      list.each { |proc| proc.call(data) }
+      @always.each { |proc| proc.call(self) }
+      @always = @success = @fail = nil
+    end
+  end
+end

data/lib/farcall/transport.rb

@@ -51,6 +51,10 @@ module Farcall
     # to call super first.
     attr_accessor :on_data_received, :on_abort, :on_close
 
+    def initialize
+      @in_buffer = []
+    end
+
     # Utility function. Calls the provided block on data reception. Resets the
     # block with #on_data_received
     def receive_data &block
@@ -72,8 +76,29 @@ module Farcall
       @closed
     end
 
+    # set handler and drain all input packets that may be buffered by the time.
+    def on_data_received= proc
+      @on_data_received = proc
+      drain
+    end
+
+    # Input buffering: transport may start before configure endpoint delegates observer, so
+    # the transport can simply push it here and rely on default buffering.
+    def push_input data
+      @in_buffer << data
+      drain
+    end
+
     protected
 
+    def drain
+      if @in_buffer.size > 0 && on_data_received
+        @in_buffer.each { |x| on_data_received.call(x) }
+        @in_buffer.clear
+      end
+    end
+
+
     # Call it when your connection is closed
     def connection_closed
       close
@@ -99,6 +124,7 @@ module Farcall
       attr_accessor :other
 
       def initialize other_loop = nil
+        super()
         if other_loop
           other_loop.other = self
           @other           = other_loop

data/lib/farcall/version.rb

@@ -1,3 +1,3 @@
 module Farcall
-  VERSION = "0.3.4"
+  VERSION = "0.4.0"
 end

data/lib/farcall/wsclient_transport.rb

@@ -25,6 +25,7 @@ begin
       # JSON encodgin over standard websocket protocol.
       def initialize ws_url
         # The stranges bug around in the WebSocket::Client (actually in his eventemitter)
+        super()
         me = self
 
         is_open = Semaphore.new
@@ -39,9 +40,7 @@ begin
         }
 
         @ws.on(:message) { |m|
-          # puts "ws client received #{JSON.parse m.data}"
-          me.on_data_received and me.on_data_received.call(JSON.parse m.data)
-          # puts "and sent"
+          me.push_input JSON.parse(m.data)
         }
         @ws.on(:close) { close }
         is_open.wait_set
@@ -53,6 +52,7 @@ begin
       end
 
     end
+
   end
 rescue LoadError
   $!.to_s =~ /websocket/ or raise

data/spec/websock_spec.rb

@@ -229,5 +229,59 @@ describe 'em_farcall' do
     standard_check_wsclient(cnt1, r1, r2, r3)
   end
 
+  it 'calls from server to client' do
+    data1 = nil
+    data2 = nil
+    done  = nil
+
+    order         = 0
+    block_order   = 0
+    promise_order = 0
+
+    EM.run {
+      params = {
+          :host => 'localhost',
+          :port => 8088
+      }
+      EM::WebSocket.run(params) do |ws|
+        ws.onopen { |handshake|
+          server = EmFarcall::WsServerEndpoint.new ws
+
+          # EM channels are synchronous so if we call too early call will be simply lost. This,
+          # though, should not happen to the socket - so why?
+          server.call(:test_method, 'hello', foo: :bar) { block_order = order+=1 }.success { |result|
+            data2         = result
+            promise_order = order += 1
+          }.fail { |e|
+            puts "Error #{e}"
+          }.always { |item|
+            done = item
+            EM.stop
+          }
+        }
+      end
+
+      EM.defer {
+        t1 = Farcall::WebsocketJsonClientTransport.new 'ws://localhost:8088/test'
+        Farcall::Endpoint.open(t1) { |client|
+          client.on(:test_method) { |args, kwargs|
+            data1 = { 'nice' => [args, kwargs] }
+            { done: :success }
+          }
+        }
+      }
+
+      EM.add_timer(1) {
+        EM.stop
+      }
+    }
+    data1.should == { 'nice' => [['hello'], { 'foo' => 'bar' }] }
+    data2.should == { 'done' => 'success' }
+    done.should be_instance_of(Farcall::Promise)
+    block_order.should == 1
+    promise_order.should == 2
+    done.data.should == data2
+  end
+
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: farcall
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - sergeych
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-24 00:00:00.000000000 Z
+date: 2016-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -125,6 +125,8 @@ files:
 - README.md
 - Rakefile
 - farcall.gemspec
+- javascript/farcall_wsclient.coffee
+- javascript/farcall_wsclient.js
 - lib/farcall.rb
 - lib/farcall/boss_transport.rb
 - lib/farcall/em_farcall.rb
@@ -132,6 +134,7 @@ files:
 - lib/farcall/endpoint.rb
 - lib/farcall/json_transport.rb
 - lib/farcall/monitor_lock.rb
+- lib/farcall/promise.rb
 - lib/farcall/transport.rb
 - lib/farcall/version.rb
 - lib/farcall/wsclient_transport.rb