rhcp 0.1.3 → 0.1.4

data/lib/rhcp.rb

@@ -0,0 +1,47 @@
+require 'singleton'
+require 'logger'
+
+require 'rhcp/broker'
+require 'rhcp/command'
+require 'rhcp/command_param'
+require 'rhcp/dispatching_broker'
+require 'rhcp/http_exporter'
+require 'rhcp/request'
+require 'rhcp/response'
+require 'rhcp/rhcp_exception'
+require 'rhcp/client/http_broker'
+require 'rhcp/client/command_stub'
+require 'rhcp/client/command_param_stub'
+
+module RHCP #:nodoc:
+  
+  class Version
+    
+    include Singleton
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 4
+
+    def Version.to_s
+      [ MAJOR, MINOR, TINY ].join(".")
+    end
+    
+  end
+  
+  class ModuleHelper
+    
+    include Singleton
+    
+    attr_accessor :logger
+    
+    def initialize()
+      # TODO do we really want to log to STDOUT per default?
+      # TODO check the whole package for correct usage of loggers
+      @logger = Logger.new(STDOUT)
+    end
+    
+    
+  end
+  
+end

data/lib/rhcp/broker.rb

@@ -0,0 +1,40 @@
+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
+    
+    
+    # TODO add a getName() thingy?
+    
+    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,64 @@
+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)
+          if object.values_at('read_only')
+            instance.mark_as_read_only
+          end
+          instance.result_hints = {
+            :display_type => object['result_hints']['display_type'],
+            :overview_columns => object['result_hints']['overview_columns'],
+            :column_titles => object['result_hints']['column_titles']
+          }
+          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 descend 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,143 @@
+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 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
+    
+    # "true" if this command returns data, but does not modify anything.
+    attr_reader :is_read_only
+    
+    # hints about how the result of this command might be displayed
+    attr_accessor :result_hints
+
+    def initialize(name, description, block)
+      @logger = RHCP::ModuleHelper.instance().logger
+      
+      @name = name
+      @description = description
+      @block = block
+      @params = Hash.new()
+      @default_param = nil
+      @is_read_only = false
+      # TODO formalize this! (we need rules how clients should react, otherwise this will be a mess)
+      # TODO in some cases, the display_type could also be guessed from the response, I guess
+      @result_hints = {
+        :display_type => "unspecified",
+        :overview_columns => [],
+        :column_titles => []
+      }
+    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
+    
+    # marks this command as a read-only command, i.e. a command that returns data,
+    # but does not perform any action.
+    # this information might influence permissions and/or the way the command's
+    # result is displayed
+    def mark_as_read_only()
+      @is_read_only = true
+      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 by 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,
+        'read_only' => @is_read_only,
+        'result_hints' => @result_hints
+      }.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