collins_client 0.2.7

data/lib/collins/api/logging.rb

@@ -0,0 +1,137 @@
+require 'ostruct'
+
+module Collins; module Api
+
+  module Logging
+
+    include Collins::Util
+
+    # @see http://tumblr.github.com/platform/collinsTutorial/out/logapi.html
+    module Severity
+      extend self
+
+      EMERGENCY     = "EMERGENCY"
+      ALERT         = "ALERT"
+      CRITICAL      = "CRITICAL"
+      ERROR         = "ERROR"
+      WARNING       = "WARNING"
+      NOTICE        = "NOTICE"
+      INFORMATIONAL = "INFORMATIONAL"
+      DEBUG         = "DEBUG"
+      NOTE          = "NOTE"
+
+      # Given a severity level, give back the severity, or nil if not valid
+      # @param [String,Symbol] level Severity level
+      # @return [String] Severity level as string
+      def value_of level
+        level_s = normalize level
+        if valid? level_s then
+          level_s.to_s
+        else
+          nil
+        end
+      end
+
+      # Convert a level into one appropriate for validating
+      # @param [Symbol,String] level Severity level
+      # @return [Symbol] normalized (not neccesarily valid) severity level
+      def normalize level
+        level.to_s.upcase.to_sym
+      end
+
+      # Check is a level is valid or not
+      # @param [Symbol,String] level Severity level
+      # @return [Boolean] indicate whether valid or not
+      def valid? level
+        level_s = normalize level
+        Collins::Api::Logging::Severity.constants.include?(level_s)
+      end
+
+      #@return [Array<String>] severity levels
+      def to_a
+        s = Collins::Api::Logging::Severity
+        s.constants.map{|c| s.const_get(c)}
+      end
+    end # module Severity
+
+    # Log a message against an asset using the specified level
+    # @param [String,Collins::Asset] asset_or_tag
+    # @param [String] message
+    # @param [Severity] level severity level to use
+    # @return [Boolean] true if logged successfully
+    # @raise [Collins::ExpectationFailed] the specified level was invalid
+    # @raise [Collins::RequestError,Collins::UnexpectedResponseError] if the asset or message invalid
+    def log! asset_or_tag, message, level = nil
+      asset = get_asset_or_tag asset_or_tag
+      parameters = {
+        :message => message,
+        :type => log_level_from_string(level)
+      }
+      parameters = select_non_empty_parameters parameters
+      logger.debug("Logging to #{asset.tag} with parameters #{parameters.inspect}")
+      http_put("/api/asset/#{asset.tag}/log", parameters, asset.location) do |response|
+        parse_response response, :as => :status, :expects => 201
+      end
+    end
+
+    # Fetch logs for an asset according to the options specified
+    # @example
+    #   :filter => "EMERGENCY;ALERT" # Only retrieve emergency and alert messages
+    #   :filter => "!DEBUG;!NOTE"    # Only retrieve non-debug/non-notes
+    # @param [String,Collins::Asset] asset_or_tag
+    # @param [Hash] options query options
+    # @option options [Fixnum] :page (0) Page of results
+    # @option options [Fixnum] :size (25) Number of results to retrieve
+    # @option options [String] :sort (DESC) Sort ordering for results
+    # @option options [String] :filter Semicolon separated list of severity levels to include or exclude
+    # @option options [String] :all_tag If specified, an asset tag is this value, proxy to the all_logs method
+    # @note To exclude a level via a filter it must be prepended with a `!`
+    # @return [Array<OpenStruct>] Array of log objects
+    # @raise [Collins::UnexpectedResponseError] on a non-200 response
+    def logs asset_or_tag, options = {}
+      asset = get_asset_or_tag asset_or_tag
+      all_tag = options.delete(:all_tag)
+      if all_tag && all_tag.to_s.downcase == asset.tag.to_s.downcase then
+        return all_logs options
+      end
+      parameters = get_page_options(options).merge(
+        :filter => get_option(:filter, options, nil)
+      )
+      parameters = select_non_empty_parameters parameters
+      logger.debug("Fetching logs for #{asset.tag} with parameters #{parameters.inspect}")
+      http_get("/api/asset/#{asset.tag}/logs", parameters, asset.location) do |response|
+        parse_response response, :as => :paginated, :default => [], :raise => strict?, :expects => 200 do |json|
+          json.map{|j| OpenStruct.new(symbolize_hash(j))}
+        end
+      end
+    end
+
+    # Same as logs but for all assets
+    # @see #logs
+    def all_logs options = {}
+      parameters = get_page_options(options).merge(
+        :filter => get_option(:filter, options, nil)
+      )
+      parameters = select_non_empty_parameters parameters
+      logger.debug("Fetching logs for all assets with parameters #{parameters.inspect}")
+      http_get("/api/assets/logs", parameters) do |response|
+        parse_response response, :as => :paginated, :default => [], :raise => strict?, :expects => 200 do |json|
+          json.map{|j| OpenStruct.new(symbolize_hash(j))}
+        end
+      end
+    end
+
+    private
+    def log_level_from_string level
+      return nil if (level.nil? || level.empty?)
+      s = Collins::Api::Logging::Severity
+      if s.valid? level then
+        s.value_of level
+      else
+        raise Collins::ExpectationFailedError.new("#{level} is not a valid log level")
+      end
+    end
+
+  end # module Log
+
+end; end

data/lib/collins/api/management.rb

@@ -0,0 +1,84 @@
+require 'collins/power'
+require 'collins/profile'
+
+module Collins; module Api
+
+  module Management
+
+    def provisioning_profiles
+      logger.debug("Getting provisioning profiles from collins")
+      http_get("/api/provision/profiles") do |response|
+        parse_response response, :expects => 200, :as => :data do |json|
+          json["PROFILES"].map { |o| Collins::Profile.new(o) }
+        end
+      end
+    end
+
+    def provision asset_or_tag, profile, contact, options = {}
+      asset = get_asset_or_tag asset_or_tag
+      parameters = {
+        :profile => profile,
+        :contact => contact,
+        :suffix => options[:suffix],
+        :primary_role => options[:primary_role],
+        :secondary_role => options[:secondary_role],
+        :pool => options[:pool],
+        :activate => options[:activate]
+      }
+      parameters = select_non_empty_parameters parameters
+      if parameters.empty? then
+        raise CollinsError.new("provision requires at least a profile")
+      end
+      http_post("/api/provision/#{asset.tag}", parameters, asset.location) do |response|
+        parse_response response, :expects => 200, :as => :status
+      end
+    end
+
+    def power_status asset_or_tag
+      asset = get_asset_or_tag asset_or_tag
+      logger.debug("Checking power status of #{asset.tag}")
+      http_get("/api/asset/#{asset.tag}/power", {}, asset.location) do |response|
+        parse_response response, :expects => 200, :as => :message, :raise => strict?, :default => "Unknown"
+      end
+    end
+
+    def power! asset_or_tag, action
+      asset = get_asset_or_tag asset_or_tag
+      if action.to_s.downcase == "status" then
+        return power_status asset_or_tag
+      end
+      action = Collins::Power.normalize_action action
+      parameters = {
+        :action => action
+      }
+      logger.debug("Calling power action on #{asset.tag}, action #{action}")
+      http_post("/api/asset/#{asset.tag}/power", parameters, asset.location) do |response|
+        parse_response response, :expects => 200, :as => :status
+      end
+    end
+
+    def ipmi_create asset_or_tag, username, password, address, gateway, netmask
+      ipmi_update asset_or_tag, :username => username, :password => password, :address => address,
+                                :gateway => gateway, :netmask => netmask
+    end
+
+    def ipmi_update asset_or_tag, options = {}
+      asset = get_asset_or_tag asset_or_tag
+      parameters = {
+        :username => get_option(:username, options, nil),
+        :password => get_option(:password, options, nil),
+        :address => get_option(:address, options, nil),
+        :gateway => get_option(:gateway, options, nil),
+        :netmask => get_option(:netmask, options, nil)
+      }
+      parameters = select_non_empty_parameters parameters
+      return true if parameters.empty?
+      logger.debug("Updating asset #{asset.tag} IPMI info with parameters #{parameters.inspect}")
+      http_post("/api/asset/#{asset.tag}/ipmi", parameters, asset.location) do |response|
+        parse_response response, :expects => [200,201], :as => :status
+      end
+    end
+
+  end # module Management
+
+end; end

data/lib/collins/api/tag.rb

@@ -0,0 +1,46 @@
+require 'ostruct'
+
+module Collins; module Api
+
+  # @api collins
+  module Tag
+
+    include Collins::Util
+
+    # Get all collins tags
+    #
+    # Sample output
+    # @example
+    #  [
+    #    {:name => "", :label => "", :description => ""},
+    #  ]
+    #  
+    # @raise [UnexpectedResponseError] if strict is true and the response is not a 200
+    # @return [Array<OpenStruct>] Array of tags containing name, label and description keys
+    def get_all_tags
+      http_get("/api/tags") do |response|
+        parse_response response, :expects => 200, :default => [], :raise => strict? do |json|
+          json["data"]["tags"].map{|t| OpenStruct.new(symbolize_hash(t))}
+        end
+      end
+    end
+
+    # Get all values associated with the specified tag
+    # 
+    # @note You will get a 404 if the tag does not exist. Depending on strict mode, this will result in an empty array or an exception
+    # @param [String] tag The tag you would like values for
+    # @param [Boolean] strict Here for backwards API compatibility
+    # @raise [UnexpectedResponseError] if strict is true and the response is not a 200
+    # @return [Array<String>] values associated with this tag
+    def get_tag_values tag, strict = false
+      http_get("/api/tag/#{tag}") do |response|
+        parse_response response, :expects => 200, :default => [], :raise => strict?(strict) do |json|
+          json["data"]["values"]
+        end
+      end
+    end
+
+  end # module Tag
+
+end; end
+

data/lib/collins/api/util.rb

@@ -0,0 +1,28 @@
+require 'collins/api/util/parameters'
+require 'collins/api/util/requests'
+require 'collins/api/util/responses'
+
+module Collins; module Api
+
+  module Util
+
+    include Collins::Api::Util::Parameters
+    include Collins::Api::Util::Requests
+    include Collins::Api::Util::Responses
+
+
+    #returns true if successful ping to collins, false otherwise
+    def ping
+      begin
+        http_get("/api/ping") do |response|
+          parse_response response, :expects => 200
+        end
+        true
+      rescue
+        false
+      end
+    end
+
+  end # module Util
+
+end; end

data/lib/collins/api/util/errors.rb

@@ -0,0 +1,45 @@
+module Collins; module Api; module Util
+
+  module Errors
+
+    protected
+    def handle_error response
+      if response.code >= 400 && rich_error_response?(response) then
+        raise RichRequestError.new(
+          "Error processing request", response.code, error_response(response), error_details(response)
+        )
+      elsif response.code >= 400 && error_response?(response) then
+        raise RequestError.new("Error processing request: #{error_response(response)}", response.code)
+      elsif response.code == 401 then
+        raise AuthenticationError.new("Invalid username or password")
+      elsif response.code > 401 then
+        raise RequestError.new("Response code was #{response.code}, #{response.to_s}", response.code)
+      end
+    end
+    def rich_error_response? response
+      if error_response?(response) then
+        parsed = response.parsed_response
+        parsed.key?("data") && parsed["data"].key?("details")
+      else
+        false
+      end
+    end
+    def error_response? response
+      begin
+        parsed = response.parsed_response
+        parsed["status"] && parsed["status"].include?("error")
+      rescue Exception => e
+        logger.warn("Could not determine if response #{response} was an error. #{e}")
+        false
+      end
+    end
+    def error_details response
+      response.parsed_response["data"]["details"]
+    end
+    def error_response response
+      response.parsed_response["data"]["message"]
+    end
+
+  end
+
+end; end; end

data/lib/collins/api/util/parameters.rb

@@ -0,0 +1,44 @@
+module Collins; module Api; module Util
+
+  module Parameters
+    protected
+
+    # retrieve a key from a hash or use the default
+    def get_option key, hash, default
+      if hash.include?(key) then
+        hash[key]
+      elsif hash.include?(key.to_s) then
+        hash[key.to_s]
+      else
+        default
+      end
+    end
+
+    def get_page_options options = {}
+      {
+        :page => get_option(:page, options, 0),
+        :size => get_option(:size, options, 25),
+        :sort => get_option(:sort, options, "DESC")
+      }
+    end
+
+    # select parameters from a hash matching some options
+    def select_non_empty_parameters params
+      select_parameters params, :nil => false, :empty_string => false
+    end
+    def select_parameters params, options = {}
+      params.inject({}) do |result, (k,v)|
+        if v.nil? && options[:nil] == false then
+          # don't include
+        elsif v.is_a?(String) && v.empty? && options[:empty_string] == false then
+          # don't include
+        else
+          result[k] = v
+        end
+        result
+      end
+    end
+
+  end # Parameters module
+
+end; end; end

data/lib/collins/api/util/requests.rb

@@ -0,0 +1,136 @@
+require 'timeout'
+require 'uri'
+
+module Collins; module Api; module Util
+
+  module Requests
+
+    protected
+    def http_get uri, parameters = {}, remote = nil
+      http_call(uri) {
+        if parameters.is_a?(Array) then
+          params = {:query => parameters.join("&")}
+        else
+          params = {:query => parameters}
+        end
+        params = strip_request :query, params
+        result = self.class.get(uri, http_options(params, remote))
+        if block_given? then
+          yield(result)
+        else
+          result
+        end
+      }
+    end
+
+    def http_put uri, parameters = {}, remote = nil
+      http_call(uri) {
+        params = strip_request :body, :body => parameters
+        result = self.class.put(uri, http_options(params, remote))
+        if block_given? then
+          yield(result)
+        else
+          result
+        end
+      }
+    end
+
+    def http_post uri, parameters = {}, remote = nil
+      http_call(uri) {
+        params = strip_request :body, :body => parameters
+        result = self.class.post(uri, http_options(params, remote))
+        if block_given? then
+          yield(result)
+        else
+          result
+        end
+      }
+    end
+
+    def http_delete uri, parameters = {}, remote = nil
+      http_call(uri) {
+        params = strip_request :body, :body => parameters
+        result = self.class.delete(uri, http_options(params, remote))
+        if block_given? then
+          yield(result)
+        else
+          result
+        end
+      }
+    end
+
+    def http_options opts = {}, remote = nil
+      if remote then
+        host_info = get_location_information remote
+        auth = {:username => host_info.username, :password => host_info.password}
+        base_uri = host_info.host
+      else
+        auth = {:username => username, :password => password}
+        base_uri = host
+      end
+      http_opts = opts.merge!({:basic_auth => auth, :base_uri => base_uri, :timeout => timeout_i})
+      http_opts[:headers] = headers unless headers.empty?
+      http_opts[:debug_output] = $stderr if (logger.level < 0 and Module.const_defined?(:HTTP_DEBUG) and HTTP_DEBUG)
+      http_opts
+    end
+
+    def http_call uri, &block
+      trace("Calling uri #{uri}, waiting for #{timeout_i} seconds")
+      begin
+        timeout(timeout_i) {
+          block.call
+        }
+      rescue Timeout::Error => e
+        raise Timeout::Error.new("Timeout talking to #{uri}: #{e}")
+      rescue Collins::RequestError => e
+        e.uri = uri
+        raise e
+      rescue Exception => e
+        if e.class.to_s == "WebMock::NetConnectNotAllowedError" then
+          raise e
+        else
+          raise e.class.new("Exception talking to #{uri}: #{e}")
+        end
+      end
+    end
+
+    def strip_request key, options
+      if options[key] && options[key].empty? then
+        {}
+      else
+        options
+      end
+    end
+
+    def get_location_information location
+      location_s = location.downcase.to_sym
+      return locations[location_s] if locations[location_s]
+      logger.debug("Fetching credentials for location #{location_s}")
+      http_get("/api/asset/#{location}") do |response|
+        result = parse_response response, :expects => 200, :as => :asset, :raise => strict?, :default => nil
+        if result && result.get_attribute(:location) then
+          if result.get_attribute(:location).nil? then
+            raise AuthenticationError.new("Could not find LOCATION attribute on asset #{location}")
+          end
+          uri = URI(result.get_attribute(:location))
+          if uri.port then
+            port = ":#{uri.port}"
+          else
+            port = ""
+          end
+          locations[location_s] = OpenStruct.new Hash[
+            :username => uri.user,
+            :password => uri.password,
+            :host => "#{uri.scheme}://#{uri.host}#{port}"
+          ]
+        else
+          raise AuthenticationError.new("Could not find LOCATION attribute on asset #{location}")
+        end
+      end
+      locations[location_s]
+    end
+
+
+  end # module Requests
+
+end; end; end