right_agent 1.0.1 → 2.0.7

data/lib/right_agent/agent_config.rb

@@ -44,10 +44,11 @@ module RightScale
   #
   # The certs directory contains the x.509 public certificate and keys needed
   # to sign and encrypt all outgoing messages as well as to check the signature
-  # and decrypt any incoming messages. This directory should contain at least:
+  # and decrypt any incoming messages. If AMQP is being used as the RightNet
+  # protocol, this directory should contain at least:
   #   <agent name>.key  - agent's' private key
   #   <agent name>.cert - agent's' public certificate
-  #   mapper.cert       - mapper's' public certificate
+  #   router.cert       - router's' public certificate
   #
   # The scripts directory at a minimum contains the following:
   #   install.sh - script for installing standard and agent specific tools in /usr/bin
@@ -63,7 +64,7 @@ module RightScale
   module AgentConfig
 
     # Current agent protocol version
-    PROTOCOL_VERSION = 22
+    PROTOCOL_VERSION = 23
 
     # Current agent protocol version
     #
@@ -138,7 +139,7 @@ module RightScale
     # dir(String|Array):: Directory path or ordered list of directory paths to be searched
     #
     # === Return
-    # (String):: Ordered list of directory paths to be searched
+    # (Array):: Ordered list of directory paths to be searched
     def self.root_dir=(dir)
       @root_dirs = array(dir)
     end
@@ -456,7 +457,7 @@ module RightScale
     def self.all_dirs(type)
       dirs = []
       root_dirs.each do |d|
-        c = self.__send__(type, d)
+        c = self.send(type, d)
         dirs << c if File.directory?(c)
       end
       dirs
@@ -466,7 +467,7 @@ module RightScale
     def self.first_file(type, name)
       file = nil
       root_dirs.each do |d|
-        if File.exist?(f = File.join(self.__send__(type, d), name))
+        if File.exist?(f = File.join(self.send(type, d), name))
           file = f
           break
         end

data/lib/right_agent/agent_identity.rb

@@ -21,10 +21,12 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module RightScale
-  
+
   # Agent identity management
   class AgentIdentity
 
+    include ProtocolVersionMixin
+
     # Cutover time at which agents began using new separator
     SEPARATOR_EPOCH = Time.at(1256702400) unless defined?(SEPARATOR_EPOCH) # Tue Oct 27 21:00:00 -0700 2009
 
@@ -47,8 +49,8 @@ module RightScale
     # separator(String):: Character used to separate identity components, defaults to ID_SEPARATOR
     #
     # === Raise
-    # RightScale::Exceptions::Argument:: Invalid argument
-    def initialize(prefix, agent_type, base_id, token=nil, separator=nil)
+    # ArgumentError:: Invalid argument
+    def initialize(prefix, agent_type, base_id, token = nil, separator = nil)
       err = "Prefix cannot contain '#{ID_SEPARATOR}'" if prefix && prefix.include?(ID_SEPARATOR)
       err = "Prefix cannot contain '#{ID_SEPARATOR_OLD}'" if prefix && prefix.include?(ID_SEPARATOR_OLD)
       err = "Agent type cannot contain '#{ID_SEPARATOR}'" if agent_type.include?(ID_SEPARATOR)
@@ -58,7 +60,7 @@ module RightScale
       err = "Base ID must be a positive integer" unless base_id.kind_of?(Integer) && base_id >= 0
       err = "Token cannot contain '#{ID_SEPARATOR}'" if token && token.include?(ID_SEPARATOR)
       err = "Token cannot contain '#{ID_SEPARATOR_OLD}'" if token && token.include?(ID_SEPARATOR_OLD)
-      raise RightScale::Exceptions::Argument, err if err
+      raise ArgumentError, err if err
 
       @separator  = separator || ID_SEPARATOR
       @prefix     = prefix
@@ -97,12 +99,12 @@ module RightScale
     # (AgentIdentity):: Corresponding agent identity
     #
     # === Raise
-    # (RightScale::Exceptions::Argument):: Serialized agent identity is invalid
+    # (ArgumentError):: Serialized agent identity is invalid
     def self.parse(serialized_id)
       prefix, agent_type, token, bid, separator = parts(self.compatible_serialized(serialized_id))
-      raise RightScale::Exceptions::Argument, "Invalid agent identity: #{serialized_id.inspect}" unless prefix && agent_type && token && bid
+      raise ArgumentError, "Invalid agent identity: #{serialized_id.inspect}" unless prefix && agent_type && token && bid
       base_id = bid.to_i
-      raise RightScale::Exceptions::Argument, "Invalid agent identity base ID: #{bid ? bid : bid.inspect}" unless base_id.to_s == bid
+      raise ArgumentError, "Invalid agent identity base ID: #{bid ? bid : bid.inspect}" unless base_id.to_s == bid
 
       AgentIdentity.new(prefix, agent_type, base_id, token, separator)
     end
@@ -116,11 +118,11 @@ module RightScale
     #
     # === Return
     # serialized_id(String):: Compatible serialized agent identity
-    def self.compatible_serialized(serialized_id, version = 10)
-      if version < 10
-        serialized_id = "nanite-#{serialized_id}" if self.valid_parts?(serialized_id)
+    def self.compatible_serialized(serialized_id, version = nil)
+      if version.nil? || ProtocolVersionMixin.can_handle_non_nanite_ids?(version)
+        serialized_id = serialized_id[7..-1] if serialized_id =~ /^nanite-|^mapper-|^router-/
       else
-        serialized_id = serialized_id[7..-1] if serialized_id =~ /^nanite-|^mapper-/
+        serialized_id = "nanite-#{serialized_id}" if self.valid_parts?(serialized_id)
       end
       serialized_id
     end

data/lib/right_agent/agent_tag_manager.rb

@@ -24,6 +24,7 @@ module RightScale
 
   # Agent tags management
   class AgentTagManager
+
     include RightSupport::Ruby::EasySingleton
 
     # (Agent) Agent being managed
@@ -43,7 +44,8 @@ module RightScale
     # === Return
     # true:: Always return true
     def tags(options = {})
-      do_query(nil, @agent.identity, options) do |result|
+      # TODO remove use of agent identity when fully drop AMQP
+      do_query(nil, @agent.self_href || @agent.identity, options) do |result|
         if result.kind_of?(Hash)
           yield(result.size == 1 ? result.values.first['tags'] : [])
         else
@@ -77,7 +79,7 @@ module RightScale
     #
     # === Parameters
     # tags(String, Array):: Tag or tags to query or empty
-    # agent_ids(Array):: agent IDs to query or empty or nil
+    # hrefs(Array):: hrefs of resources to query with empty or nil meaning all instances in deployment
     # options(Hash):: Request options
     #   :timeout(Integer):: timeout in seconds before giving up and yielding an error message
     #
@@ -86,10 +88,10 @@ module RightScale
     #
     # === Return
     # true:: Always return true
-    def query_tags_raw(tags, agent_ids = nil, options = {})
+    def query_tags_raw(tags, hrefs = nil, options = {})
       tags = ensure_flat_array_value(tags) unless tags.nil? || tags.empty?
       options = options.merge(:raw => true)
-      do_query(tags, agent_ids, options) { |raw_response| yield raw_response }
+      do_query(tags, hrefs, options) { |raw_response| yield raw_response }
     end
 
     # Add given tags to agent
@@ -105,7 +107,7 @@ module RightScale
     # true always return true
     def add_tags(new_tags)
       new_tags = ensure_flat_array_value(new_tags) unless new_tags.nil? || new_tags.empty?
-      update_tags(new_tags, []) { |raw_response| yield raw_response if block_given? }
+      do_update(new_tags, []) { |raw_response| yield raw_response if block_given? }
     end
 
     # Remove given tags from agent
@@ -121,42 +123,7 @@ module RightScale
     # true always return true
     def remove_tags(old_tags)
       old_tags = ensure_flat_array_value(old_tags) unless old_tags.nil? || old_tags.empty?
-      update_tags([], old_tags) { |raw_response| yield raw_response if block_given? }
-    end
-
-    # Runs a tag update with a list of new and old tags.
-    #
-    # === Parameters
-    # new_tags(Array):: new tags to add or empty
-    # old_tags(Array):: old tags to remove or empty
-    # block(Block):: optional callback for update response
-    #
-    # === Block
-    # A block is optional. If provided, should take one argument which will be set with the
-    # raw response
-    #
-    # === Return
-    # true:: Always return true
-    def update_tags(new_tags, old_tags, &block)
-      agent_check
-      tags = @agent.tags
-      tags += (new_tags || [])
-      tags -= (old_tags || [])
-      tags.uniq!
-
-      payload = {:new_tags => new_tags, :obsolete_tags => old_tags}
-      request = RightScale::IdempotentRequest.new("/mapper/update_tags", payload)
-      if block
-        # always yield raw response
-        request.callback do |_|
-          # refresh agent's copy of tags on successful update
-          @agent.tags = tags
-          block.call(request.raw_response)
-        end
-        request.errback { |message| block.call(request.raw_response || message) }
-      end
-      request.run
-      true
+      do_update([], old_tags) { |raw_response| yield raw_response if block_given? }
     end
 
     # Clear all agent tags
@@ -167,20 +134,20 @@ module RightScale
     # === Return
     # true::Always return true
     def clear
-      update_tags([], @agent.tags) { |raw_response| yield raw_response }
+      do_update([], @agent.tags) { |raw_response| yield raw_response }
     end
 
     private
 
     def agent_check
-      raise ArgumentError, "Must set agent= before using tag manager" unless @agent
+      raise ArgumentError.new("Must set agent= before using tag manager") unless @agent
     end
 
     # Runs a tag query with an optional list of tags.
     #
     # === Parameters
     # tags(Array):: Tags to query or empty or nil
-    # agent_ids(Array):: IDs of agents to query with empty or nil meaning all agents in deployment
+    # hrefs(Array):: hrefs of resources to query with empty or nil meaning all instances in deployment
     # options(Hash):: Request options
     #   :raw(Boolean):: true to yield raw tag response instead of unserialized tags
     #   :timeout(Integer):: timeout in seconds before giving up and yielding an error message
@@ -191,8 +158,8 @@ module RightScale
     #
     # === Return
     # true:: Always return true
-    def do_query(tags = nil, agent_ids = nil, options = {})
-      raw = options[:raw] || false
+    def do_query(tags = nil, hrefs = nil, options = {})
+      raw = options[:raw]
       timeout = options[:timeout]
 
       request_options = {}
@@ -201,21 +168,60 @@ module RightScale
       agent_check
       payload = {:agent_identity => @agent.identity}
       payload[:tags] = ensure_flat_array_value(tags) unless tags.nil? || tags.empty?
-      payload[:agent_ids] = ensure_flat_array_value(agent_ids) unless agent_ids.nil? || agent_ids.empty?
-      request = RightScale::IdempotentRequest.new("/mapper/query_tags",
-                                                  payload,
-                                                  request_options)
+      payload[:hrefs] = ensure_flat_array_value(hrefs) unless hrefs.nil? || hrefs.empty?
+      request = RightScale::RetryableRequest.new("/router/query_tags", payload, request_options)
       request.callback { |result| yield raw ? request.raw_response : result }
       request.errback do |message|
-        Log.error("Failed to query tags: #{message}")
+        Log.error("Failed to query tags (#{message})")
         yield((raw ? request.raw_response : nil) || message)
       end
       request.run
       true
     end
 
-    # Ensures value is a flat array, making an array from the single value if
-    # necessary.
+    # Runs a tag update with a list of new or old tags
+    #
+    # === Parameters
+    # new_tags(Array):: new tags to add or empty
+    # old_tags(Array):: old tags to remove or empty
+    # block(Block):: optional callback for update response
+    #
+    # === Block
+    # A block is optional. If provided, should take one argument which will be set with the
+    # raw response
+    #
+    # === Return
+    # true:: Always return true
+    def do_update(new_tags, old_tags, &block)
+      agent_check
+      raise ArgumentError.new("Cannot add and remove tags in same update") if new_tags.any? && old_tags.any?
+      tags = @agent.tags
+      tags += new_tags
+      tags -= old_tags
+      tags.uniq!
+
+      if new_tags.any?
+        request = RightScale::RetryableRequest.new("/router/add_tags", {:tags => new_tags})
+      elsif old_tags.any?
+        request = RightScale::RetryableRequest.new("/router/delete_tags", {:tags => old_tags})
+      else
+        return
+      end
+
+      if block
+        # Always yield raw response
+        request.callback do |_|
+          # Refresh agent's copy of tags on successful update
+          @agent.tags = tags
+          block.call(request.raw_response)
+        end
+        request.errback { |message| block.call(request.raw_response || message) }
+      end
+      request.run
+      true
+    end
+
+    # Ensures value is a flat array, making an array from the single value if necessary
     #
     # === Parameters
     # value(Object):: any kind of value
@@ -223,19 +229,9 @@ module RightScale
     # === Return
     # result(Array):: flat array value
     def ensure_flat_array_value(value)
-      if value.kind_of?(Array)
-        value.flatten!
-      else
-        value = [value]
-      end
-      value
+      value = Array(value).flatten.compact
     end
 
   end # AgentTagManager
 
-  # This class has been renamed as of RightAgent 0.9.6; provide an alias
-  # to the old typename
-  # TODO remove this alias for RightAgent 1.0
-  AgentTagsManager = AgentTagManager
-
 end # RightScale

data/{spec/results_mock.rb → lib/right_agent/clients.rb}

@@ -1,5 +1,5 @@
-#
-# Copyright (c) 2009-2011 RightScale Inc
+#--
+# Copyright (c) 2013 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -19,27 +19,13 @@
 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
 
-# Mock for request results
-module RightScale
-
-  class ResultsMock
-
-    def initialize
-      @agent_id = AgentIdentity.generate
-    end
-
-    # Build a valid request results with given content
-    def success_results(content = nil, reply_to = '*test*1')
-      Result.new(AgentIdentity.generate, reply_to,
-        { @agent_id => OperationResult.success(content) }, @agent_id)
-    end
-
-    def error_results(content, reply_to = '*test*1')
-      Result.new(AgentIdentity.generate, reply_to,
-        { @agent_id => OperationResult.error(content) }, @agent_id)
-    end
+CLIENTS_BASE_DIR = File.join(File.dirname(__FILE__), 'clients')
 
-  end
-  
-end
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'balanced_http_client'))
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'base_retry_client'))
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'auth_client'))
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'api_client'))
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'router_client'))
+require File.normalize_path(File.join(CLIENTS_BASE_DIR, 'right_http_client'))

data/lib/right_agent/clients/api_client.rb

@@ -0,0 +1,383 @@
+#--
+# Copyright (c) 2013 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+module RightScale
+
+  # HTTP interface to RightApi for use when mapping actor-based requests to API requests
+  class ApiClient < BaseRetryClient
+
+    # RightApi API version for use in X-API-Version header
+    API_VERSION = "1.5"
+
+    # Maximum length of an audit summary as enforced by RightApi
+    MAX_AUDIT_SUMMARY_LENGTH = 255
+
+    # Default time to wait for HTTP connection to open
+    DEFAULT_OPEN_TIMEOUT = 2
+
+    # Default time to wait for response from request, which is chosen to be 5 seconds greater
+    # than the response timeout inside the RightNet router
+    DEFAULT_REQUEST_TIMEOUT = 35
+
+    # Map from actor-based request paths to RightApi HTTP verb and path; only requests whose type
+    # matches an entry in this hash will be routed to the RightApi; all others will be routed to RightNet
+    API_MAP = {
+      "/auditor/create_entry"              => [:post, "/audit_entries"],
+      "/auditor/update_entry"              => [:post, "/audit_entries/:id/append"],
+      "/booter/declare"                    => [:post, "/right_net/booter/declare"],
+      "/booter/get_repositories"           => [:get,  "/right_net/booter/get_repositories"],
+      "/booter/get_boot_bundle"            => [:get,  "/right_net/booter/get_boot_bundle"],
+      "/booter/get_decommission_bundle"    => [:get,  "/right_net/booter/get_decommission_bundle"],
+      "/booter/get_missing_attributes"     => [:get,  "/right_net/booter/get_missing_attributes"],
+      "/booter/get_login_policy"           => [:get,  "/right_net/booter/get_login_policy"],
+      "/forwarder/schedule_right_script"   => [:post, "/right_net/scheduler/bundle_right_script"],
+      "/forwarder/schedule_recipe"         => [:post, "/right_net/scheduler/bundle_recipe"],
+      "/forwarder/shutdown"                => [:post, "/right_net/scheduler/shutdown"],
+      "/key_server/retrieve_public_keys"   => [:get,  "/right_net/key_server/retrieve_public_keys"],
+      "/router/ping"                       => [:get,  "/health-check"],
+      "/router/query_tags"                 => [:post, "/tags/by_tag"],
+      "/router/add_tags"                   => [:post, "/tags/multi_add"],
+      "/router/delete_tags"                => [:post, "/tags/multi_delete"],
+      "/state_recorder/record"             => [:put,  "/right_net/state_recorder/record"],
+      "/storage_valet/get_planned_volumes" => [:get,  "/right_net/storage_valet/get_planned_volumes"],
+      "/storage_valet/attach_volume"       => [:post, "/right_net/storage_valet/attach_volume"],
+      "/storage_valet/detach_volume"       => [:post, "/right_net/storage_valet/detach_volume"],
+      "/updater/update_inputs"             => [:post, "/right_net/scheduler/update_inputs"],
+      "/vault/read_documents"              => [:get,  "/right_net/vault/read_documents"] }
+
+    # Symbols for audit request parameters whose values are to be hidden when logging
+    AUDIT_FILTER_PARAMS = ["detail", "text"]
+
+    # Resource href for this agent
+    attr_reader :self_href
+
+    # Create RightApi client of specified type
+    #
+    # @param [AuthClient] auth_client providing authorization session for HTTP requests
+    #
+    # @option options [Numeric] :open_timeout maximum wait for connection; defaults to DEFAULT_OPEN_TIMEOUT
+    # @option options [Numeric] :request_timeout maximum wait for response; defaults to DEFAULT_REQUEST_TIMEOUT
+    # @option options [Numeric] :retry_timeout maximum before stop retrying; defaults to DEFAULT_RETRY_TIMEOUT
+    # @option options [Array] :retry_intervals between successive retries; defaults to DEFAULT_RETRY_INTERVALS
+    # @option options [Boolean] :retry_enabled for requests that fail to connect or that return a retry result
+    # @option options [Numeric] :reconnect_interval for reconnect attempts after lose connectivity
+    # @option options [Proc] :exception_callback for unexpected exceptions
+    #
+    # @raise [ArgumentError] auth client does not support this client type
+    def initialize(auth_client, options)
+      init(:api, auth_client, options.merge(:server_name => "RightApi", :api_version => API_VERSION))
+    end
+
+    # Route a request to a single target or multiple targets with no response expected
+    # Persist the request en route to reduce the chance of it being lost at the expense of some
+    # additional network overhead
+    # Enqueue the request if the target is not currently available
+    # Never automatically retry the request if there is the possibility of it being duplicated
+    # Set time-to-live to be forever
+    #
+    # @param [String] type of request as path specifying actor and action
+    # @param [Hash, NilClass] payload for request
+    # @param [String, Hash, NilClass] target for request, which may be identity of specific
+    #   target, hash for selecting potentially multiple targets, or nil if routing solely
+    #   using type; hash may contain:
+    #   [Array] :tags that must all be associated with a target for it to be selected
+    #   [Hash] :scope for restricting routing which may contain:
+    #     [Integer] :account id that agents must be associated with to be included
+    #     [Integer] :shard id that agents must be in to be included, or if value is
+    #       Packet::GLOBAL, ones with no shard id
+    #   [Symbol] :selector for picking from qualified targets: :any or :all;
+    #     defaults to :any
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    #
+    # @return [NilClass] always nil since there is no expected response to the request
+    #
+    # @raise [Exceptions::Unauthorized] authorization failed
+    # @raise [Exceptions::ConnectivityFailure] cannot connect to server, lost connection
+    #   to it, or it is out of service or too busy to respond
+    # @raise [Exceptions::RetryableError] request failed but if retried may succeed
+    # @raise [Exceptions::Terminating] closing client and terminating service
+    # @raise [Exceptions::InternalServerError] internal error in server being accessed
+    def push(type, payload, target, token = nil)
+      map_request(type, payload, token)
+    end
+
+    # Route a request to a single target with a response expected
+    # Automatically retry the request if a response is not received in a reasonable amount of time
+    # or if there is a non-delivery response indicating the target is not currently available
+    # Timeout the request if a response is not received in time, typically configured to 30 sec
+    # Because of retries there is the possibility of duplicated requests, and these are detected and
+    # discarded automatically for non-idempotent actions
+    # Allow the request to expire per the agent's configured time-to-live, typically 1 minute
+    #
+    # @param [String] type of request as path specifying actor and action
+    # @param [Hash, NilClass] payload for request
+    # @param [String, Hash, NilClass] target for request, which may be identity of specific
+    #   target, hash for selecting targets of which one is picked randomly, or nil if routing solely
+    #   using type; hash may contain:
+    #   [Array] :tags that must all be associated with a target for it to be selected
+    #   [Hash] :scope for restricting routing which may contain:
+    #     [Integer] :account id that agents must be associated with to be included
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    #
+    # @return [Result, NilClass] response from request
+    #
+    # @raise [Exceptions::Unauthorized] authorization failed
+    # @raise [Exceptions::ConnectivityFailure] cannot connect to server, lost connection
+    #   to it, or it is out of service or too busy to respond
+    # @raise [Exceptions::RetryableError] request failed but if retried may succeed
+    # @raise [Exceptions::Terminating] closing client and terminating service
+    # @raise [Exceptions::InternalServerError] internal error in server being accessed
+    def request(type, payload, target, token = nil)
+      map_request(type, payload, token)
+    end
+
+    # Determine whether request supported by this client
+    #
+    # @param [String] type of request as path specifying actor and action
+    #
+    # @return [Array] HTTP verb and path
+    def support?(type)
+      API_MAP.has_key?(type)
+    end
+
+    protected
+
+    # Convert request to RightApi form and then make request via HTTP
+    #
+    # @param [String] type of request as path specifying actor and action
+    # @param [Hash, NilClass] payload for request
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    #
+    # @return [Object, NilClass] response from request
+    #
+    # @raise [Exceptions::Unauthorized] authorization failed
+    # @raise [Exceptions::ConnectivityFailure] cannot connect to server, lost connection
+    #   to it, or it is too busy to respond
+    # @raise [Exceptions::RetryableError] request failed but if retried may succeed
+    # @raise [Exceptions::Terminating] closing client and terminating service
+    # @raise [Exceptions::InternalServerError] internal error in server being accessed
+    def map_request(type, payload, token)
+      verb, path = API_MAP[type]
+      raise ArgumentError, "Unsupported request type: #{type}" if path.nil?
+      actor, action = type.split("/")[1..-1]
+      path, params, options = parameterize(actor, action, payload, path)
+      if action == "query_tags"
+        map_query_tags(verb, params, action, token, options)
+      else
+        map_response(make_request(verb, path, params, action, token, options), path)
+      end
+    end
+
+    # Convert response from request into required form where necessary
+    #
+    # @param [Object] response received
+    # @param [String] path in URI for desired resource
+    #
+    # @return [Object] converted response
+    def map_response(response, path)
+      case path
+      when "/audit_entries"
+        # Convert returned audit entry href to audit ID
+        response.sub!(/^.*\/api\/audit_entries\//, "") if response.is_a?(String)
+      when "/tags/by_resource", "/tags/by_tag"
+        # Extract tags for each instance resource from response array with members of form
+        # {"actions" => [], "links" => [{"rel" => "resource", "href" => <href>}, ...]}, "tags" => [{"name" => <tag>}, ...]
+        tags = {}
+        if response
+          response.each do |hash|
+            r = {}
+            hash["links"].each { |l| r[l["href"]] = {"tags" => []} if l["href"] =~ /instances/ }
+            hash["tags"].each { |t| r.each_key { |k| r[k]["tags"] << t["name"] } } if r.any?
+            tags.merge!(r)
+          end
+        end
+        response = tags
+      end
+      response
+    end
+
+    # Convert tag query request into one or more API requests and then convert responses
+    # Currently only retrieving "instances" resources
+    #
+    # @param [Symbol] verb for HTTP REST request
+    # @param [Hash] params for HTTP request
+    # @param [String] action from request type
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    # @param [Hash] options augmenting or overriding default options for HTTP request
+    #
+    # @return [Hash] tags retrieved with resource href as key and tags array as value
+    def map_query_tags(verb, params, action, token, options)
+      response = {}
+      hrefs = params[:resource_hrefs] || []
+      hrefs.concat(query_by_tag(verb, params[:tags], action, token, options)) if params[:tags]
+      response = query_by_resource(verb, hrefs, action, token, options) if hrefs.any?
+      response
+    end
+
+    # Query API for resources with specified tags
+    #
+    # @param [Symbol] verb for HTTP REST request
+    # @param [Array] tags that all resources retrieved must have
+    # @param [String] action from request type
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    # @param [Hash] options augmenting or overriding default options for HTTP request
+    #
+    # @return [Array] resource hrefs
+    def query_by_tag(verb, tags, action, token, options)
+      path = "/tags/by_tag"
+      params = {:tags => tags, :match_all => false, :resource_type => "instances"}
+      map_response(make_request(verb, path, params, action, token, options), path).keys
+    end
+
+    # Query API for tags associated with a set of resources
+    #
+    # @param [Symbol] verb for HTTP REST request
+    # @param [Array] hrefs for resources whose tags are to be retrieved
+    # @param [String] action from request type
+    # @param [String, NilClass] token uniquely identifying this request;
+    #   defaults to randomly generated ID
+    # @param [Hash] options augmenting or overriding default options for HTTP request
+    #
+    # @return [Hash] tags retrieved with resource href as key and tags array as value
+    def query_by_resource(verb, hrefs, action, token, options)
+      path = "/tags/by_resource"
+      params = {:resource_hrefs => hrefs}
+      map_response(make_request(verb, path, params, action, token, options), path)
+    end
+
+    # Convert payload to HTTP parameters
+    #
+    # @param [String] actor from request type
+    # @param [String] action from request type
+    # @param [Hash, NilClass] payload for request
+    # @param [String] path in URI for desired resource
+    #
+    # @return [Array] path string and parameters and options hashes
+    def parameterize(actor, action, payload, path)
+      options = {}
+      params = {}
+      if actor == "auditor"
+        path = path.sub(/:id/, payload[:audit_id].to_s || "")
+        params = parameterize_audit(action, payload)
+        options = {:filter_params => AUDIT_FILTER_PARAMS}
+      elsif actor == "router" && action =~ /_tags/
+        if action != "query_tags"
+          params[:resource_hrefs] = [@self_href]
+        else
+          params[:resource_hrefs] = Array(payload[:hrefs]).flatten.compact if payload[:hrefs]
+        end
+        params[:tags] = Array(payload[:tags]).flatten.compact if payload[:tags]
+      else
+        # Can remove :agent_identity here since now carried in the authorization as the :agent
+        payload.each { |k, v| params[k.to_sym] = v if k.to_sym != :agent_identity } if payload.is_a?(Hash)
+      end
+      [path, params, options]
+    end
+
+    # Translate audit request payload to HTTP parameters
+    # Truncate audit summary to MAX_AUDIT_SUMMARY_LENGTH, the limit imposed by RightApi
+    #
+    # @param [String] action requested: create_entry or update_entry
+    # @param [Hash] payload from submitted request
+    #
+    # @return [Hash] HTTP request parameters
+    #
+    # @raise [ArgumentError] unknown request action
+    def parameterize_audit(action, payload)
+      params = {}
+      summary = non_blank(payload[:summary])
+      detail = non_blank(payload[:detail])
+      case action
+      when "create_entry"
+        params[:audit_entry] = {:auditee_href => @self_href}
+        params[:audit_entry][:summary] = truncate(summary, MAX_AUDIT_SUMMARY_LENGTH) if summary
+        params[:audit_entry][:detail] = detail if detail
+        if (user_email = non_blank(payload[:user_email]))
+          params[:user_email] = user_email
+        end
+        params[:notify] = payload[:category] if payload[:category]
+      when "update_entry"
+        params[:offset] = payload[:offset] if payload[:offset]
+        if summary
+          params[:summary] = truncate(summary, MAX_AUDIT_SUMMARY_LENGTH)
+          params[:notify] = payload[:category] if payload[:category]
+        end
+        params[:detail] = detail if detail
+      else
+        raise ArgumentError, "Unknown audit request action: #{action}"
+      end
+      params
+    end
+
+    # Truncate string if it exceeds maximum length
+    # Do length check with bytesize rather than size since this code
+    # is running with ruby 1.9.2 while the API uses 1.8.7, otherwise
+    # multi-byte characters could cause this code to be too lenient
+    #
+    # @param [String, NilClass] value to be truncated
+    # @param [Integer] max_length allowed; must be greater than 3
+    #
+    # @return [String, NilClass] truncated string or original value if it is not a string
+    #
+    # @raise [ArgumentError] max_length too small
+    def truncate(value, max_length)
+      raise ArgumentError, "max_length must be greater than 3" if max_length <= 3
+      if value.is_a?(String) && value.bytesize > max_length
+        max_truncated = max_length - 3
+        truncated = value[0, max_truncated]
+        while truncated.bytesize > max_truncated do
+          truncated.chop!
+        end
+        truncated + "..."
+      else
+        value
+      end
+    end
+
+    # Determine whether value is non-blank
+    #
+    # @param [String, NilClass] value to be tested
+    #
+    # @return [String, NilClass] value if non-blank, otherwise nil
+    def non_blank(value)
+      value && !value.empty? ? value : nil
+    end
+
+    # Perform any other steps needed to make this client fully usable
+    # once HTTP client has been created and server known to be accessible
+    #
+    # @return [TrueClass] always true
+    def enable_use
+      result = make_request(:get, "/sessions/instance", {}, "instance")
+      @self_href = result["links"].select { |link| link["rel"] == "self" }.first["href"]
+      true
+    end
+
+  end # ApiClient
+
+end # RightScale