krpc 0.1.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0f3c082901ab9699ece2d8033381250ec2990a7
-  data.tar.gz: 00a0e3ac5f6e4b7e4c105557f8ee68f62a143a6a
+  metadata.gz: 977be90d9516ca166de911cebca7bcac80bd174b
+  data.tar.gz: 29ed63e761d2198d580abb49f2f2a3c43b56ee31
 SHA512:
-  metadata.gz: 737ad5c400faf806f6211f5c4928d39126f2738bc401fe09926885444a4857000cd454bf5711904f3ba0a6778df0229928263c2852ac69016d7e53190b31eb24
-  data.tar.gz: 4c9a51a7828b56e27ca6be04f2ab9fcc53d7d0cabd042710e20af05ec36fea994b41878f6b8024a72199d9021eb405e9be7f418b10ff7db7e9e675177fb7a5b0
+  metadata.gz: c07dd473607aaa175c3167f8f1c68ec03473ad839e43fe70f772e63a11b05633485c9b1f1810df73b7132bf043e3fd6c76823dd8393f8ba5dba8da3cd42a56d1
+  data.tar.gz: 29709a970d7d2c80517d8e22174732325095d24acc0fc1ff8114dc37a1feba558db5e82af8b7e4e4866872fd629761c3e5610a81c63c570ee962650100953bc8

data/CHANGELOG.md

@@ -1,8 +1,23 @@
 
+v0.2.0  (26 Sep 2015)
+========
++ **Added Streaming support**:
+  + Stream creation by calling method with `_stream` suffix
++ **Improved in-REPL experience**:
+  + Added documentation content received from kRPC server to in-REPL documentation output
+  + Improved `to_s` and `inspect` methods in `KRPC::Gen::ClassBase` and `KRPC::Streaming::Stream` classes
++ Arguments of `KRPC::Client#initialize` method turned into keyword arguments
++ RPC methods are no longer bound to single `KRPC::Client` object (Fix #3)
++ Fixed arguments sometimes not correctly passed to RPC methods (due to Ruby 2.2.1 bug) (Fix #1)
++ Removed `required_params_count` parameter from `Client#build_request` method, and made that method public
++ `KRPC::TypeStore`'s methods changed, to be class level methods
++ Added dependency on *Nokogiri* and development dependency on *Pry* and *hanna-nouveau*
++ Minor improvements and fixes
+
 v0.1.1  (9 Sep 2015)
 ========
-+ Added KRPC.connect method
-+ Added block argument to Client#connect and Client#connect! methods
++ Added `KRPC.connect` method
++ Added block argument to `Client#connect` and `Client#connect!` methods
 
 v0.1.0  (6 Sep 2015)
 ========

data/README.md

@@ -13,7 +13,7 @@ Basic usage
 
 ```ruby
 require 'krpc'
-client = KRPC.connect("client name here")
+client = KRPC.connect(name: "client name here")
 vessel = client.space_center.active_vessel
 ctrl = vessel.control
 ctrl.sas = true
@@ -28,14 +28,12 @@ Most of the API is *very* similar to what can be found in (official) Python clie
 So official documentation at http://djungelorm.github.io/krpc/docs/ is definitely a good read.
 The rest of this file describes few differences there are between Ruby and Python client libraries.
 
-**NOTE:** Streaming is not supported in the current version of kRPC-rb.
-
 Connecting and disconnecting
 -------
 When you are in REPL, you can connect to kRPC server in this way:
 
 ```ruby
-client = KRPC.connect({name for client}, {host}, {rpc_port}, {stream_port})
+client = KRPC.connect(name: {name for the client}, host: {kRPC server host}, rpc_port: {kRPC server rpc port}, stream_port: {kRPC server stream port})
 # use client here...
 client.close
 ```
@@ -44,7 +42,7 @@ All of the `KRPC.connect`'s arguments are optional, so `client = KRPC.connect` m
 Alternatively you can be more explicit (yet still obtain the same result):
 
 ```ruby
-client = KRPC::Client.new({name for client}, {host}, {rpc_port}, {stream_port}).connect!
+client = KRPC::Client.new( {The same argument list as KRPC.connect has} ).connect!
 # use client here...
 client.close
 ```
@@ -87,12 +85,14 @@ The best way to explore the API is to run REPL and try what each method does for
 I highly recommend using [Pry](https://github.com/pry/pry) as REPL. This way you can `ls` any object you receive and see what methods you can call on it. When you want to know more about specific method, then just stuck `_doc` at the end of it's name and press enter:
 
 ```ruby
-[29] pry(main)> cl.space_center.transform_position_doc
+[29] pry(main)> client.space_center.transform_position_doc
 SpaceCenter.transform_position(
-	position :Array[Float, Float, Float],
-	from :ReferenceFrame,
-	to :ReferenceFrame
-) :Array[Float, Float, Float]
+	position :Array[Float, Float, Float], - Position vector in reference frame from.
+	from :ReferenceFrame, - The reference frame that the position vector is in.
+	to :ReferenceFrame - The reference frame to covert the position vector to.
+) :Array[Float, Float, Float] - The corresponding position vector in reference frame to.
+
+ Converts a position vector from one reference frame to another. 
 => nil
 ```
 
@@ -104,22 +104,48 @@ Combination of `ls`s and `_doc`s should teach you API in no time (also don't be
 ```ruby
 [31] pry(main)> sc = client.space_center;
 [32] pry(main)> ls sc
-KRPC::Doc::SuffixMethods#methods: method_missing
-KRPC::Services::ServiceBase#methods: client
+...
 KRPC::Services::SpaceCenter::AvailableToClassAndInstance#methods: 
   can_rails_warp_at  clear_target    draw_line               launch_vessel_from_vab  transform_position  transform_velocity
-  clear_drawing      draw_direction  launch_vessel_from_sph  transform_direction     transform_rotation  warp_to           
+  clear_drawing      draw_direction  launch_vessel_from_sph  transform_direction     transform_rotation  warp_to
 KRPC::Services::SpaceCenter#methods: 
   active_vessel   far_available              physics_warp_factor   rails_warp_factor=     target_body=          target_vessel   vessels      warp_rate
   active_vessel=  g                          physics_warp_factor=  remote_tech_available  target_docking_port   target_vessel=  warp_factor
-  bodies          maximum_rails_warp_factor  rails_warp_factor     target_body            target_docking_port=  ut              warp_mode  
-instance variables: @client
+  bodies          maximum_rails_warp_factor  rails_warp_factor     target_body            target_docking_port=  ut              warp_mode
+...
 [33] pry(main)> sc.warp_to_doc;
 SpaceCenter.warp_to(
-	ut :Float,
-	max_rails_rate :Float = 100000.0,
-	max_physics_rate :Float = 2.0
-) :nil
+	ut :Float, - The universal time to warp to, in seconds.
+	max_rails_rate :Float = 100000.0, - The maximum warp rate in regular "on-rails" time warp.
+	max_physics_rate :Float = 2.0 - The maximum warp rate in physical time warp.
+) :nil - When the time warp is complete.
+
+ Uses time acceleration to warp forward to a time in the future, specified by universal time ut. This call blocks until the desired time is reached. Uses regular "on-rails" or physical time warp as appropriate. For example, physical time warp is used when the active vessel is traveling through an atmosphere. When using regular "on-rails" time warp, the warp rate is limited by max_rails_rate, and when using physical time warp, the warp rate is limited by max_physics_rate.
+```
+
+Streaming
+-------
+A stream repeatedly executes a function on the server, with a fixed set of argument values. It provides a more efficient way of repeatedly getting the result of calling function on the server, without having to invoke it directly – which incurs communication overheads.
+
+To create a stream, call a method with `_stream` suffix. This will return `KRPC::Streaming::Stream` instance. You can call `get` (or `value`) on the `Stream` instance to get the recent value received by this stream. To deactivate the stream call `remove` (or `close`) on the `Stream` instance.
+
+Example without streaming:
+```ruby
+vessel = client.space_center.active_vessel
+refframe = vessel.orbit.body.reference_frame
+loop do
+  puts vessel.position(refframe)
+end
+```
+Equivalent example with streaming:
+```ruby
+vessel = client.space_center.active_vessel
+refframe = vessel.orbit.body.reference_frame
+pos_stream = vessel.position_stream(refframe)
+loop do
+  puts pos_stream.get
+end
+pos_stream.remove #note: dead code - just as an example
 ```
 
 Want to know more?

data/krpc.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |s|
   s.name          = "krpc"
-  s.version       = "0.1.1.1"
+  s.version       = "0.2.0"
   s.authors       = ["Tomasz Więch"]
   s.email         = ["tewu.dev@gmail.com"]
   
@@ -19,12 +19,15 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = ["README.md"]
   s.rdoc_options << "--markup" << "markdown" <<
                     "--format" << "hanna" <<
+                    "--title"  << "kRPC-rb API Docs" <<
                     "--main"   << "README.md"
   
   s.required_ruby_version = '>= 2.1.0'
 
   s.add_runtime_dependency "ruby_protobuf", "~> 0.4"
   s.add_runtime_dependency "colorize", "~> 0.7"
+  s.add_runtime_dependency "nokogiri", "~> 1.6"
   s.add_development_dependency "bundler", "~> 1.10"
+  s.add_development_dependency "pry", "~> 0.10"
+  s.add_development_dependency "hanna-nouveau", "~> 0.4"
 end
-

data/lib/krpc.rb

@@ -6,14 +6,9 @@ module KRPC
     # Connect to a kRPC server, generate services API and return Client object. If the block is
     # given, then it's called passing Client object and the connection to kRPC server is closed
     # at the end of the block.
-    def connect(name = Client::DEFAULT_NAME, host = Connection::DEFAULT_SERVER_HOST, rpc_port = Connection::DEFAULT_SERVER_RPC_PORT, stream_port = Connection::DEFAULT_SERVER_STREAM_PORT, &block)
-      client = Client.new(name, host, rpc_port, stream_port).connect!
-      if block_given?
-        begin block.call(client) ensure client.close end
-      end
-      client
+    def connect(*args, &block)
+      Client.new(*args).connect!(&block)
     end
     
   end
 end
-

data/lib/krpc/KRPC.pb.rb

@@ -122,4 +122,3 @@ module KRPC
     end
   end  
 end
-

data/lib/krpc/attributes.rb

@@ -78,4 +78,3 @@ module KRPC
     end
   end
 end
-

data/lib/krpc/client.rb

@@ -3,6 +3,7 @@ require 'krpc/service'
 require 'krpc/types'
 require 'krpc/encoder'
 require 'krpc/decoder'
+require 'krpc/streaming'
 require 'krpc/error'
 require 'krpc/core_extensions'
 require 'krpc/KRPC.pb'
@@ -18,7 +19,7 @@ module KRPC
   # `client.service_name.procedure_name(parameter, ...)`
   #
   # ### Example:
-  #     client = KRPC::Client.new("my client").connect!
+  #     client = KRPC::Client.new(name: "my client").connect!
   #     ctrl = client.space_center.active_vessel.control
   #     ctrl.activate_next_stage
   #     ctrl.throttle = 1 # Full ahead!
@@ -31,17 +32,18 @@ module KRPC
 
     include Doc::SuffixMethods
 
-    attr_reader :name, :rpc_connection, :stream_connection, :type_store, :krpc
-    
+    attr_reader :name, :rpc_connection, :stream_connection, :streams_manager, :krpc
+
     # Create new Client object, optionally specifying IP address and port numbers on witch kRPC 
     # server is listening and the name for this client (up to 32 bytes of UTF-8 encoded text).
-    def initialize(name = DEFAULT_NAME, host = Connection::DEFAULT_SERVER_HOST, rpc_port = Connection::DEFAULT_SERVER_RPC_PORT, stream_port = Connection::DEFAULT_SERVER_STREAM_PORT)
+    def initialize(name: DEFAULT_NAME, host: Connection::DEFAULT_SERVER_HOST, rpc_port: Connection::DEFAULT_SERVER_RPC_PORT, stream_port: Connection::DEFAULT_SERVER_STREAM_PORT)
       @name = name
-      @rpc_connection = RPCConncetion.new(name, host, rpc_port)
-      @stream_connection = StreamConncetion.new(rpc_connection, host, stream_port)
-      @type_store = Types::TypeStore.new
+      @rpc_connection = RPCConnection.new(name, host, rpc_port)
+      @stream_connection = StreamConnection.new(rpc_connection, host, stream_port)
+      @streams_manager = Streaming::StreamsManager.new(self)
+      @services = {}
       @krpc = Services::KRPC.new(self)
-      Doc.add_docstring_info(false, self.class, "krpc", return_type: @krpc.class)
+      Doc.add_docstring_info(false, self.class, "krpc", return_type: @krpc.class, xmldoc: "<doc><summary>Core kRPC service, e.g. for querying for the available services. Most of this functionality is used internally by the Ruby client and therefore does not need to be used directly from application code.</summary></doc>")
     end
     
     # Connect to a kRPC server on the IP address and port numbers specified during this client
@@ -51,6 +53,7 @@ module KRPC
     def connect(&block)
       rpc_connection.connect
       stream_connection.connect
+      streams_manager.start_streaming_thread
       call_block_and_close(block) if block_given?
       self
     end
@@ -68,6 +71,8 @@ module KRPC
     # Close connection to kRPC server. Returns `true` if the connection has closed or `false` if 
     # the client had been already disconnected.
     def close
+      streams_manager.remove_all_streams
+      streams_manager.stop_streaming_thread
       stream_connection.close
       rpc_connection.close
     end
@@ -93,7 +98,7 @@ module KRPC
     # To regenerate API create new Client object and call #generate_services_api! on it.
     #
     # ### Example
-    #       client = KRPC::Client.new("my client").connect # Notice that it is #connect being called, not #connect!
+    #       client = KRPC::Client.new(name: "my client").connect # Notice that it is 'Client#connect' being called, not 'Client#connect!'
     #       sc = client.space_center # => Exception (undefined method "space_center")
     #       client.generate_services_api!
     #       sc = client.space_center # => KRPC::Services::SpaceCenter object
@@ -107,12 +112,14 @@ module KRPC
       resp = krpc.get_services
       resp.services.each do |service_msg|
         next if service_msg.name == "KRPC"
-        service = Services.create_service(service_msg, self)
-        method_name = service.class.class_name.underscore
+        service_class = Services.create_service(service_msg)
+        method_name = service_class.class_name.underscore
         self.class.instance_eval do
-          define_method method_name do service end
+          define_method method_name do
+            @services[service_class.class_name] ||= service_class.new(self)
+          end
         end
-        Doc.add_docstring_info(false, self.class, method_name, return_type: service.class)
+        Doc.add_docstring_info(false, self.class, method_name, return_type: service_class, xmldoc: service_msg.documentation)
       end
       self
     end
@@ -123,9 +130,9 @@ module KRPC
     end
     
     # Execute an RPC.
-    def rpc(service, procedure, args=[], kwargs={}, param_names=[], param_types=[], required_params_count=0, param_default=[], return_type: nil)
+    def rpc(service, procedure, args=[], kwargs={}, param_names=[], param_types=[], param_default=[], return_type: nil)
       # Send request
-      req = build_request(service, procedure, args, kwargs, param_names, param_types, required_params_count, param_default)
+      req = build_request(service, procedure, args, kwargs, param_names, param_types, param_default)
       rpc_connection.send Encoder.encode_request(req)
       # Receive response
       resp_length = rpc_connection.recv_varint
@@ -138,23 +145,19 @@ module KRPC
       if return_type == nil
         nil
       else
-        Decoder.decode(resp.return_value, return_type, type_store)
+        Decoder.decode(resp.return_value, return_type, self)
       end
     rescue IOError => e
       raise(Exception, "RPC call attempt while not connected to server -- call Client#connect first") if not connected?
       raise e
     end
     
-    protected #----------------------------------
-    
-    def call_block_and_close(block)
-      begin block.call(self) ensure close end
-    end
-
     # Build a PB::Request object.
-    def build_request(service, procedure, args=[], kwargs={}, param_names=[], param_types=[], required_params_count=0, param_default=[])
+    def build_request(service, procedure, args=[], kwargs={}, param_names=[], param_types=[], param_default=[])
       begin
-        raise(ArgumentError, "param_names and param_types should be equal length\n\tparam_names = #{param_names}\n\tparam_types = #{param_types}") unless param_names.size == param_types.size
+        raise(ArgumentError, "param_names and param_types should be equal length\n\tparam_names = #{param_names}\n\tparam_types = #{param_types}") unless param_names.length == param_types.length
+        raise(ArgumentError, "param_names and param_default should be equal length\n\tparam_names = #{param_names}\n\tparam_default = #{param_default}") unless param_names.length == param_default.length
+        required_params_count = param_default.take_while(&:nil?).count
         raise ArgumentsNumberErrorSig.new(args.count, required_params_count..param_names.count) unless args.count <= param_names.count
         kwargs_remaining = kwargs.count
         
@@ -172,21 +175,26 @@ module KRPC
                   else raise ArgumentErrorSig.new("missing argument for parameter \"#{name}\"") 
                   end
             begin
-              arg = type_store.coerce_to(arg, param_types[i])
+              arg = TypeStore.coerce_to(arg, param_types[i])
             rescue ValueError
               raise ArgumentErrorSig.new("argument for parameter \"#{name}\" must be a #{param_types[i].ruby_type} -- got #{args[i]} of type #{args[i].class}")
             end
-            v = Encoder.encode(arg, param_types[i], type_store)
+            v = Encoder.encode(arg, param_types[i])
             PB::Argument.new(position: i, value: v)
           end
         end.compact
         raise ArgumentErrorSig.new("keyword arguments for non existing parameters: #{(kwargs.keys - param_names_symbols).join(", ")}") unless kwargs_remaining == 0
       rescue ArgumentErrorSig => err
-        raise err.with_signature(Doc.docstring_for_procedure(service, procedure))
+        raise err.with_signature(Doc.docstring_for_procedure(service, procedure, false))
       end
       PB::Request.new(service: service, procedure: procedure, arguments: req_args)
     end
     
+    protected #----------------------------------
+    
+    def call_block_and_close(block)
+      begin block.call(self) ensure close end
+    end
+    
   end
 end
-

data/lib/krpc/connection.rb

@@ -49,10 +49,9 @@ module KRPC
     def handshake; end
     def cleanup; end
     
-    def send(msg) @socket.send(msg,0) end
+    def send(msg) @socket.send(msg, 0) end
     def recv(maxlen = 1) @socket.recv(maxlen) end
     
-    
     def recv_varint
       int_val = 0
       shift = 0
@@ -62,21 +61,20 @@ module KRPC
         return int_val if (byte & 0b1000_0000) == 0
         shift += 7
         raise(RuntimeError, "too many bytes when decoding varint") if shift >= 64
-        sleep 0.1
       end
     end
     
     protected #----------------------------------
     
     def trim_fill(str, len, fill_char = "\x00")
-      str = str.encode("UTF-8")[0,len]
+      str = str.encode("UTF-8")[0, len]
       str + fill_char*(len-str.length)
     end
   end
 
   ##
   # TCP connection for sending RPC calls and retrieving it's results.
-  class RPCConncetion < Connection
+  class RPCConnection < Connection
     attr_reader :name, :client_id
     
     def initialize(name, host = DEFAULT_SERVER_HOST, port = DEFAULT_SERVER_RPC_PORT)
@@ -99,7 +97,7 @@ module KRPC
 
   ##
   # TCP connection for streaming.
-  class StreamConncetion < Connection
+  class StreamConnection < Connection
     attr_reader :rpc_connection
     
     def initialize(rpc_connection, host = DEFAULT_SERVER_HOST, port = DEFAULT_SERVER_STREAM_PORT)
@@ -118,4 +116,3 @@ module KRPC
   end
   
 end
-

data/lib/krpc/core_extensions.rb

@@ -26,3 +26,8 @@ class String
   end
 end
 
+class Array
+  def extract_kwargs!
+    last.is_a?(::Hash) ? pop : {}
+  end
+end

data/lib/krpc/decoder.rb

@@ -10,30 +10,30 @@ module KRPC
     class << self
     
       # Given a type object, and serialized data, decode the ruby value/object
-      def decode(data, type, type_store)
+      def decode(data, type, client)
         if type.is_a?(Types::MessageType) then decode_message(data, type)
         elsif type.is_a?(Types::ValueType) then decode_value(data, type)
         elsif type.is_a?(Types::EnumType) 
-          v = decode_value(data, type_store.as_type("int32"))
+          v = decode_value(data, TypeStore["int32"])
           type.ruby_type.key(v)
         elsif type.is_a?(Types::ClassType)
-          remote_oid = decode_value(data, type_store.as_type("uint64"))
+          remote_oid = decode_value(data, TypeStore["uint64"])
           if remote_oid != 0
-            type.ruby_type.new(remote_oid)
+            type.ruby_type.new(client, remote_oid)
           else nil end
         elsif type.is_a?(Types::ListType)
-          msg = decode_message(data, type_store.as_type("KRPC.List"))
-          msg.items.map{|x| decode(x, type.value_type, type_store)}.to_a
+          msg = decode_message(data, TypeStore["KRPC.List"])
+          msg.items.map{|x| decode(x, type.value_type, client)}.to_a
         elsif type.is_a?(Types::DictionaryType)
-          msg = decode_message(data, type_store.as_type("KRPC.Dictionary"))
-          msg.entries.map{|e| [decode(e.key,   type.key_type,   type_store),
-                               decode(e.value, type.value_type, type_store)]}.to_h
+          msg = decode_message(data, TypeStore["KRPC.Dictionary"])
+          msg.entries.map{|e| [decode(e.key,   type.key_type,   client),
+                               decode(e.value, type.value_type, client)]}.to_h
         elsif type.is_a?(Types::SetType)
-          msg = decode_message(data, type_store.as_type("KRPC.Set"))
-          Set.new(msg.items.map{|x| decode(x, type.value_type, type_store)}.to_a)
+          msg = decode_message(data, TypeStore["KRPC.Set"])
+          Set.new(msg.items.map{|x| decode(x, type.value_type, client)}.to_a)
         elsif type.is_a?(Types::TupleType)
-          msg = decode_message(data, type_store.as_type("KRPC.Tuple"))
-          msg.items.zip(type.value_types).map{|x,t| decode(x, t, type_store)}.to_a
+          msg = decode_message(data, TypeStore["KRPC.Tuple"])
+          msg.items.zip(type.value_types).map{|x,t| decode(x, t, client)}.to_a
         else raise RuntimeError.new("Cannot decode type #{type} from data: #{data}")
         end
       end
@@ -51,4 +51,3 @@ module KRPC
     end
   end
 end
-