rhcp 0.1.2

data/Rakefile

@@ -0,0 +1,116 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+$LOAD_PATH.push('lib')
+require File.join(File.dirname(__FILE__), 'lib', 'rhcp')
+
+PKG_NAME      = 'rhcp'
+PKG_VERSION   = RHCP::Version.to_s
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+desc "Default Task"
+task :default => [ :test ]
+
+###############################################
+### TESTS
+Rake::TestTask.new() { |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.libs << "test/rhcp"
+  t.test_files = FileList['test/rhcp/*_test.rb']
+  t.verbose = true
+}
+
+###############################################
+### RDOC
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "RHCP - really helpful command protocol"
+  rdoc.options << '--line-numbers' << '--inline-source' <<
+    '--accessor' << 'cattr_accessor=object'
+  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
+  #rdoc.rdoc_files.include('README', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+###############################################
+### METRICS
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/**/*.rb"]
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+    
+    total_lines     += lines
+    total_codelines += codelines
+    
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+
+# TODO add rcov
+# rcov -I lib/ -x rcov.rb -x rhcp.rb test/**/*.rb
+
+###############################################
+### GEM
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Library for exporting parts of your application using the rhcp protocol"
+  s.description = "The rhcp protocol allows you to register commands along with their parameter descriptions and some metadata that can then be executed by rhcp clients."
+
+  dist_dirs = [ "lib", "test" ]
+  # TODO add README and CHANGELOG
+  s.files = [ "Rakefile" ]
+  dist_dirs.each do |dir|
+    s.files = s.files + Dir.glob( "#{dir}/**/*" ).delete_if do |item|
+      item.include?( "\.svn" )
+    end
+  end
+  
+#  s.add_dependency('uuidtools', '>= 1.0.0')
+#  s.add_dependency('builder', '>= 1.2.4')
+
+  s.require_path = 'lib'
+  s.test_files = Dir.glob('test/**/*.rb')
+
+  
+  begin
+  s.post_install_message = <<-TEXT
+
+    This is the initial release of rhcp - hope you'll like it.
+    Feel free to send me feedback to rhcp at hitchhackers dot net.
+
+  TEXT
+  rescue Exception
+  end
+
+  s.has_rdoc = true
+  #s.extra_rdoc_files = %w( README )
+  #s.rdoc_options.concat ['--main',  'README']
+  
+  s.author = "Philipp Traeder"
+  s.email = "philipp@hitchhackers.net"
+  s.homepage = "http://hitchhackers.net/projects/rhcp"
+  s.rubyforge_project = "rhcp"
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end

data/lib/rhcp/broker.rb

@@ -0,0 +1,37 @@
+module RHCP
+
+  # Applications register the commands they are implementing at a broker.
+  # The broker holds the list of commands and is the central entry point for
+  # all code that wants to export/publish these commands  
+  class Broker
+    
+    def initialize
+      # command_name => command
+      @known_commands = Hash.new()
+    end  
+
+    # returns a list of all known commands
+    def get_command_list()
+      @known_commands
+    end  
+
+    # returns the specified command object
+    def get_command(command_name)
+      raise RHCP::RhcpException.new("no such command : #{command_name}") unless @known_commands.has_key?(command_name)
+      get_command_list[command_name]
+    end
+    
+    # registers a new command - this method should be called by the application
+    # providing the command
+    def register_command(command)
+      raise RHCP::RhcpException.new("duplicate command name : #{command.name}") if @known_commands.has_key?(command.name)
+      @known_commands[command.name] = command
+    end
+    
+    # removes all commands that have been registered previously
+    def clear
+      @known_commands = Hash.new()
+    end
+
+  end
+end

data/lib/rhcp/client/command_param_stub.rb

@@ -0,0 +1,51 @@
+require 'rhcp/command_param'
+
+module RHCP
+  
+  module Client
+    
+      # This is a proxy representing a remote CommandParam - see
+      # RHCP::CommandParam for details
+      class CommandParamStub < RHCP::CommandParam
+        
+        # the block that should be executed when +get_lookup_values()+ is called
+        # on this CommandParamStub
+        attr_accessor :get_lookup_values_block
+        
+        # when constructing a CommandParamStub, the +:lookup_method+ option is 
+        # set to +remote_get_lookup_values+ so that a method can be injected
+        # from outside that will retrieve the lookup values (using the
+        # +get_lookup_values_block+ property).
+        def initialize(name, description, options)
+          # we don't need to stub anything if the method does not have lookup values
+          if (options[:has_lookup_values])
+            options[:lookup_method] = self.method(:remote_get_lookup_values)
+          end
+          super(name, description, options)
+        end
+        
+        def self.reconstruct_from_json(json_data)
+          object = json_data.instance_of?(Hash) ? json_data : JSON.parse(json_data)
+          args = object.values_at('name', 'description')
+          args << {
+            :allows_multiple_values => object['allows_multiple_values'],
+            :has_lookup_values => object['has_lookup_values'],
+            :is_default_param => object['is_default_param'],
+            :mandatory => object['mandatory']
+          }
+          self.new(*args)
+        end
+        
+        def remote_get_lookup_values(partial_value = "")
+          @get_lookup_values_block.call(partial_value)
+        end
+        
+      end      
+
+  end
+  
+end
+
+ 
+
+

data/lib/rhcp/client/command_stub.rb

@@ -0,0 +1,56 @@
+require 'rhcp/command'
+require 'rhcp/client/command_param_stub'
+require 'rubygems'
+require 'json'
+
+
+module RHCP
+  
+  module Client
+    
+      # This is a stub that represents a remote RHCP::Command.
+      # Instances of this class will live in a client that uses one of the brokers
+      # from the RHCP::Client package. The interesting aspect about this stub is
+      # that the execute method is modified so that it does not execute the
+      # command directly, but can be modified from outside (by setting the
+      # +execute_block+ property) so that broker classes can inject their
+      # remote invocation logic.
+      class CommandStub < RHCP::Command
+        
+        attr_accessor :execute_block
+        
+        # constructs a new instance
+        # should not be invoked directly, but is called from +reconstruct_from_json+
+        def initialize(name, description)
+          super(name, description, lambda {})
+        end
+        
+        # builds a CommandStub out of some json data (either serialized as string
+        # or already unpacked into a ruby-hash)
+        # all nested params are unmarshalled as RHCP::CommandParamStub instances
+        # so that we are able to inject the logic for invoking get_lookup_values
+        # remotely
+        def self.reconstruct_from_json(json_data)
+          object = json_data.instance_of?(Hash) ? json_data : JSON.parse(json_data)
+          args = object.values_at('name', 'description')
+          instance = self.new(*args)
+          object['params'].each do |p|
+            param = RHCP::Client::CommandParamStub.reconstruct_from_json(p)
+            instance.add_param(param)
+          end
+          instance
+        end        
+        
+        # we don't want to execute the command block as the normal RHCP::Command
+        # does, but rather want to call the block injected by the registry that
+        # has created this stub.
+        def execute_request(request)
+          @execute_block.call(request)
+        end
+      end      
+      
+    end
+    
+end
+
+

data/lib/rhcp/client/http_broker.rb

@@ -0,0 +1,86 @@
+#require 'rhcp/rhcp'
+require 'rhcp/broker'
+require 'rhcp/rhcp_exception'
+require 'rhcp/client/command_stub'
+require 'net/http'
+require 'json'
+
+module RHCP
+  
+  module Client
+    
+      # This is an implementation of a RHCP broker that retrieves it's data via
+      # http from a remote broker. Since it implements the same interface as RHCP::Broker,
+      # clients can use it exactly as if they were talking with the broker itself.
+      # TODO shouldn't this descent from Broker?
+      class HttpBroker
+
+        def initialize(url)
+          # TODO should this really be an URL? or just a host name?
+          @url = url
+          @logger = RHCP::ModuleHelper.instance.logger
+          @logger.debug "connecting to #{@url}"
+          res = Net::HTTP.new(@url.host, @url.port).start { |http| http.get("/rhcp/") }
+          if (res.code == "200")
+            @logger.info "connected to '#{@url}' successfully."
+          else
+            @logger.error "cannot connect to '#{@url}' : got http status code #{res.code}"
+            raise RHCP::RhcpException.new("could not connect to '#{@url}' : got http status code #{res.code} (#{res.message})");
+          end
+        end
+
+        # returns a list of all known commands
+        # TODO add caching for commands
+        def get_command_list()
+          res = Net::HTTP.new(@url.host, @url.port).start { |http| http.get("/rhcp/get_commands") }   
+          if (res.code != "200")
+            raise RHCP::RhcpException.new("could not retrieve command list from remote server : http status #{res.code} (#{res.message})")
+          end
+          
+          @logger.debug "raw response : >>#{res.body}<<"
+
+          # the commands are transferred as array => convert into hash
+          command_array = JSON.parse(res.body)
+          commands = Hash.new()
+          command_array.each do |command_string|
+            command = RHCP::Client::CommandStub.reconstruct_from_json(command_string)
+            commands[command.name] = command
+            # and inject the block for executing over http
+            command.execute_block = lambda {
+              |req|
+              @logger.debug("executing command #{command.name} via http using #{@url}")
+              
+              res = Net::HTTP.new(@url.host, @url.port).start { |http| http.post("/rhcp/execute", req.to_json()) }
+              if (res.code != "200")
+                raise RHCP::RhcpException.new("could not execute command using remote server : http status #{res.code} (#{res.message})")
+              end
+              
+              json_response = RHCP::Response.reconstruct_from_json(res.body)
+              @logger.debug "json response : #{json_response}"
+              json_response
+            }
+            
+            # inject appropriate blocks for all params
+            command.params.each do |name, param|
+              param.get_lookup_values_block = lambda {
+                |partial_value|
+                @logger.debug("getting lookup values for param #{name} of command #{command.name} using #{@url}")
+                # TODO add caching for lookup values
+                res = Net::HTTP.new(@url.host, @url.port).start { |http| 
+                  http.get("/rhcp/get_lookup_values?command=#{command.name}&param=#{name}") 
+                }   
+                if (res.code != "200")
+                  raise RHCP::RhcpException.new("could not retrieve lookup values from remote server : http status #{res.code} (#{res.message})")
+                end
+                JSON.parse(res.body)
+              }
+            end
+          end
+          commands
+        end
+
+      end
+
+    end
+    
+end  

data/lib/rhcp/command.rb

@@ -0,0 +1,120 @@
+module RHCP
+
+  require 'rubygems'
+  require 'json'
+  
+  #require 'rhcp/rhcp'
+  require 'rhcp/response'
+  
+  # This class represents a single RHCP command, i.e. a functionality that
+  # should be exposed to clients.
+  class Command
+    
+    # TODO add read_write/read_only marker
+    
+    # TODO add metadata about the command's result (display type ("table"), column order etc.)
+    
+    # a unique name for this command
+    attr_reader :name
+
+    # textual description of what this command is doing
+    attr_reader :description
+
+    # the parameters supported by this command
+    attr_reader :params
+
+    # the block that should be executed if this command is invoked
+    attr_reader :block
+    
+    # the parameter that is the default param for this command; might be nil
+    attr_reader :default_param
+
+    def initialize(name, description, block)
+      @logger = RHCP::ModuleHelper.instance().logger
+      
+      @name = name
+      @description = description
+      @block = block
+      @params = Hash.new()
+      @default_param = nil
+    end
+
+    # adds a new parameter and returns the command
+    def add_param(new_param)
+      raise "duplicate parameter name '#{new_param.name}'" if @params.has_key?(new_param.name)
+      @params[new_param.name] = new_param
+      if new_param.is_default_param
+        if @default_param != nil
+          raise RHCP::RhcpException.new("there can be only one default parameter per command, and the parameter '#{@default_param.name}' has already been marked as default")
+        end
+        @default_param = new_param
+      end
+      self
+    end
+
+    # returns the specified CommandParam
+    # or throws an RhcpException if the parameter does not exist
+    def get_param(param_name)
+      raise RHCP::RhcpException.new("no such parameter : #{param_name}") unless @params.has_key?(param_name)
+      @params[param_name]
+    end
+
+    # invokes this command
+    def execute_request(request)
+      @logger.debug "gonna execute request >>#{request}<<"
+      response = RHCP::Response.new()      
+      begin
+        # TODO redirect the block's output (both Logger and STDOUT/STDERR) and send it back with the response
+        result = block.call(request, response)
+        response.set_payload(result)
+      rescue => ex
+        response.mark_as_error(ex.to_s, ex.backtrace.join("\n"))
+      end
+      
+      fire_post_exec_event(request, response)
+      
+      response
+    end
+    
+    def execute(param_values = {})
+      req = RHCP::Request.new(self, param_values)
+      execute_request(req)
+    end
+    
+    
+    # we do not serialize the block (no sense in this) nor the default param
+    # when the command is unmarshalled as stub, the default param will be set again
+    # automatically ba add_param(), and the block will be replaced by the block
+    # that does the remote invocation
+    def to_json(*args)
+      {
+        'name' => @name,
+        'description' => @description,
+        'params' => @params.values
+      }.to_json(*args)
+    end
+    
+    # TODO think about moving this and the whole command thing to the broker
+    def Command.register_post_exec_listener(block)        
+      @@listener = [] unless defined?(@@listener)
+      @@listener << block
+    end
+    
+    def Command.clear_post_exec_listeners()
+      @@listener = []
+    end
+    
+    def fire_post_exec_event(request, response)
+      return unless defined? @@listener
+      @@listener.each do |listener|
+        begin
+          listener.call(request, response)
+        rescue => ex
+          @logger.warn "a post-exec listener failed with the following message : #{ex}"
+        end
+      end
+    end
+
+  end
+
+end

data/lib/rhcp/command_param.rb

@@ -0,0 +1,93 @@
+require 'rubygems'
+require 'json'
+
+require 'rhcp/rhcp_exception'
+
+module RHCP
+
+  # This class represents a single parameter that can be specified for
+  # a certain command. It is used by the server side to define which
+  # commands are available for clients.
+  class CommandParam
+
+    # a unique name for this parameter
+    attr_reader :name
+    # a textual description of this parameter's meaning
+    attr_reader :description
+    # "true" if the command can not be invoked without this parameter
+    attr_reader :mandatory
+    # "true" if there are lookup values available for this parameter
+    attr_reader :has_lookup_values
+    # "true" if this parameter might be specified multiple times, resulting
+    # in a list of values for this parameter
+    attr_reader :allows_multiple_values    
+    # "true" if this parameter is the default parameter for the enclosing command
+    attr_reader :is_default_param
+
+    # creates a new command parameter
+    # options is a hash, possibly holding the following values (all optional)
+    #   :mandatory                true if the parameter is necessary for this command
+    #   :allows_multiple_values   true if this parameter might be specified multiple times
+    #   :lookup_method            a block that returns an array of lookup values valid for this param
+    #   :is_default_param         true if this parameter is the default param for the enclosing command
+    def initialize(name, description, options = Hash.new)
+      @name = name
+      @description = description
+
+      @mandatory = options[:mandatory] || false
+      @lookup_value_block = options[:lookup_method]     
+      @has_lookup_values = @lookup_value_block != nil
+      @allows_multiple_values = options[:allows_multiple_values] || false
+      @is_default_param = options[:is_default_param] || false
+    end
+
+    # returns lookup values for this parameter
+    # if "partial_value" is specified, only those values are returned that start
+    # with "partial_value"
+    def get_lookup_values(partial_value = "")
+      if @has_lookup_values
+        @lookup_value_block.call().grep(/^#{partial_value}/)
+      else
+        []
+      end
+    end
+
+    # throws an exception if +possible_value+ is not a valid value for this parameter
+    # returns true otherwise
+    # note that this methods expects +possible_value+ to be an array since all param values
+    # are specified as arrays
+    def check_param_is_valid(possible_value)
+
+      # formal check : single-value params against multi-value params
+      if ((! @allows_multiple_values) && (possible_value.size > 1))
+        raise RHCP::RhcpException.new("multiple values specified for single-value parameter '#{@name}'")
+      end
+
+      # check against lookup values
+      if @has_lookup_values
+        possible_value.each do |value|
+          if ! get_lookup_values().include?(value)
+            raise RHCP::RhcpException.new("invalid value '#{value}' for parameter '#{@name}'")
+          end
+        end
+      end
+
+      true
+    end
+    
+    # we do not serialize the lookup_method (it couldn't be invoked remotely
+    # anyway)
+    def to_json(*args)
+      {
+        'name' => @name,
+        'description' => @description,
+        'allows_multiple_values' => @allows_multiple_values,
+        'has_lookup_values' => @has_lookup_values,
+        'is_default_param' => @is_default_param,
+        'mandatory' => @mandatory
+      }.to_json(*args)
+    end        
+
+  end
+
+end  

data/lib/rhcp/dispatching_broker.rb

@@ -0,0 +1,25 @@
+require 'rhcp/rhcp_exception'
+require 'rhcp/broker'
+
+module RHCP
+
+  class DispatchingBroker < RHCP::Broker
+    def initialize
+      @known_commands = Hash.new()
+    end
+    
+    # returns a list of all known commands
+    def get_command_list()
+      @known_commands
+    end  
+
+    def add_broker(new_broker)
+      new_broker.get_command_list.each do |name, command|
+        raise RHCP::RhcpException.new("duplicate command: '#{name}' has already been defined.") if @known_commands.has_key?(name)
+        @known_commands[name] = command
+      end
+    end
+    
+  end
+  
+end