wavefront-sdk 1.6.2 → 2.0.0

data/lib/wavefront-sdk/cloudintegration.rb

@@ -1,11 +1,11 @@
-require_relative 'base'
+require_relative 'core/api'
 
 module Wavefront
   #
   # View and manage Cloud Integrations. These are identified by
   # a UUID.
   #
-  class CloudIntegration < Base
+  class CloudIntegration < CoreApi
     # GET /api/v2/cloudintegration
     # Get all cloud integrations for a customer
     #
@@ -14,7 +14,7 @@ module Wavefront
     # @return [Wavefront::Response]
     #
     def list(offset = 0, limit = 100)
-      api_get('', offset: offset, limit: limit)
+      api.get('', offset: offset, limit: limit)
     end
 
     # POST /api/v2/cloudintegration
@@ -26,7 +26,7 @@ module Wavefront
     #
     def create(body)
       raise ArgumentError unless body.is_a?(Hash)
-      api_post('', body, 'application/json')
+      api.post('', body, 'application/json')
     end
 
     # DELETE /api/v2/cloudintegration/id
@@ -41,7 +41,7 @@ module Wavefront
     #
     def delete(id)
       wf_cloudintegration_id?(id)
-      api_delete(id)
+      api.delete(id)
     end
 
     # GET /api/v2/cloudintegration/id
@@ -52,7 +52,7 @@ module Wavefront
     #
     def describe(id)
       wf_cloudintegration_id?(id)
-      api_get(id)
+      api.get(id)
     end
 
     # PUT /api/v2/cloudintegration/id
@@ -64,7 +64,7 @@ module Wavefront
     def update(id, body)
       wf_cloudintegration_id?(id)
       raise ArgumentError unless body.is_a?(Hash)
-      api_put(id, body)
+      api.put(id, body)
     end
 
     # POST /api/v2/cloudintegration/id/undelete
@@ -75,7 +75,7 @@ module Wavefront
     #
     def undelete(id)
       wf_cloudintegration_id?(id)
-      api_post([id, 'undelete'].uri_concat)
+      api.post([id, 'undelete'].uri_concat)
     end
   end
 end

data/lib/wavefront-sdk/core/api.rb

@@ -0,0 +1,99 @@
+require_relative 'logger'
+require_relative 'api_caller'
+require_relative 'exception'
+require_relative '../validators'
+require_relative '../support/mixins'
+
+module Wavefront
+  #
+  # Abstract class from which all API classes inherit. When you make
+  # any call to the Wavefront API from this SDK, you are returned an
+  # OpenStruct object.
+  #
+  # @return a Wavefront::Response object
+  #
+  class CoreApi
+    include Wavefront::Validators
+    include Wavefront::Mixins
+    attr_reader :api, :update_keys, :logger, :creds, :opts
+
+    # Create a new API object. This will always be called from a
+    # class which inherits this one. If the inheriting class defines
+    # #post_initialize, that method will be called afterwards, with
+    # the same arguments.
+    #
+    # @param creds [Hash] must contain the keys `endpoint` (the
+    #   Wavefront API server) and `token`, the user token with which
+    #   you wish to access the endpoint. Can optionally contain
+    #   `agent`, which will become the `user-agent` string sent with
+    #   all requests. Passed through to the ApiCaller class.
+    # @param opts [Hash] options governing class behaviour. Expected
+    #   keys are `debug`, `noop` and `verbose`, all boolean; and
+    #   `logger`, which must be a standard Ruby logger object. You
+    #   can also pass :response_only. If this is true, you will only
+    #   be returned a hash of the 'response' object returned by
+    #   Wavefront. Passed through to the ApiCaller class.
+    # @return [Nil]
+    #
+    def initialize(creds = {}, opts = {})
+      @creds   = creds
+      @opts    = opts
+      @api     = setup_api(creds, opts)
+      @s_api   = setup_api(creds, opts)
+      @logger  = Wavefront::Logger.new(opts)
+      post_initialize(creds, opts) if respond_to?(:post_initialize)
+    end
+
+    def setup_api(creds, opts)
+      Wavefront::ApiCaller.new(self, creds, opts)
+    end
+
+    # Derive the first part of the API path from the class name. You
+    # can override this in your class if you wish. This method is
+    # called by the ApiCaller class.
+    #
+    # @return [String] portion of API URI
+    #
+    def api_base
+      self.class.name.split('::').last.downcase
+    end
+
+    # The API path is normally /api/v2/something, but not always.
+    # Override this method if not
+    #
+    def api_path
+      ['', 'api', 'v2', api_base].uri_concat
+    end
+
+    # Convert an epoch timestamp into epoch milliseconds. If the
+    # timestamp looks like it's already epoch milliseconds, return
+    # it as-is.
+    #
+    # @param t [Integer] epoch timestamp
+    # @return [Ingeter] epoch millisecond timestamp
+    #
+    def time_to_ms(time)
+      return false unless time.is_a?(Integer)
+      return time if time.to_s.size == 13
+      (time.to_f * 1000).round
+    end
+
+    # doing a PUT to update an object requires only a certain subset of
+    # the keys returned by #describe(). This method takes the
+    # existing description of an object and turns it into a new has
+    # which can be PUT.
+    #
+    # @param old [Hash] a hash of the existing object
+    # @param new [Hash] the keys you wish to update
+    # @return [Hash] a hash containing only the keys which need to be
+    #   sent to the API. Keys will be symbolized.
+    #
+    def hash_for_update(old, new)
+      raise ArgumentError unless old.is_a?(Hash) && new.is_a?(Hash)
+
+      Hash[old.merge(new).map { |k, v| [k.to_sym, v] }].select do |k, _v|
+        update_keys.include?(k)
+      end
+    end
+  end
+end

data/lib/wavefront-sdk/core/api_caller.rb

@@ -0,0 +1,211 @@
+require 'json'
+require 'faraday'
+require 'addressable'
+require_relative 'response'
+require_relative '../defs/version'
+require_relative '../support/mixins'
+
+module Wavefront
+  #
+  # Constructs and makes API calls to Wavefront.
+  #
+  class ApiCaller
+    include Wavefront::Mixins
+
+    attr_reader :opts, :noop, :debug, :verbose, :net, :logger,
+                :calling_class
+
+    # @param calling_class [
+    # @param creds [Hash] Wavefront credentials
+    # @param opts [Hash]
+    # @return [Nil]
+    #
+    def initialize(calling_class, creds = {}, opts = {})
+      @calling_class = calling_class
+      @opts          = opts
+      setup_class_vars(opts)
+      setup_endpoint(creds)
+    end
+
+    def setup_class_vars(opts)
+      @logger    = Wavefront::Logger.new(opts)
+      @noop      = opts[:noop] || false
+      @verbose   = opts[:verbose] || false
+      @debug     = opts[:debug] || false
+    end
+
+    # Create a Faraday connection object. The server comes from the
+    # endpoint passed to the initializer in the 'creds' hash; the
+    # root of the URI is dynamically derived by the #setup_endpoint
+    # method.
+    #
+    # @param headers [Hash] additional headers
+    # @return [URI::HTTPS]
+    #
+    def mk_conn(path, headers = {})
+      url = format('%s://%s%s', net[:scheme], net[:endpoint],
+                   [net[:api_base], path].uri_concat)
+      Faraday.new(url:     Addressable::URI.encode(url),
+                  headers: net[:headers].merge(headers))
+    end
+
+    # Make a GET call to the Wavefront API and return the result as
+    # a Ruby hash.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param query [Hash] optional key-value pairs with will be made
+    #   into aquery string
+    # @return [Hash] API response
+    #
+    def get(path, query = {})
+      make_call(mk_conn(path), :get, nil, query)
+    end
+
+    # Make a POST call to the Wavefront API and return the result as
+    # a Ruby hash.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param body [String,Object] optional body text to post.
+    #   Objects will be converted to JSON
+    # @param ctype [String] the content type to use when posting
+    # @return [Hash] API response
+    #
+    def post(path, body = nil, ctype = 'text/plain')
+      body = body.to_json unless body.is_a?(String)
+      make_call(mk_conn(path,  'Content-Type': ctype,
+                               'Accept': 'application/json'),
+                :post, nil, body)
+    end
+
+    # Make a PUT call to the Wavefront API and return the result as
+    # a Ruby hash.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param body [String] optional body text to post
+    # @param ctype [String] the content type to use when putting
+    # @return [Hash] API response
+    #
+    def put(path, body = nil, ctype = 'application/json')
+      make_call(mk_conn(path,  'Content-Type': ctype,
+                               'Accept': 'application/json'),
+                :put, nil, body.to_json)
+    end
+
+    # Make a DELETE call to the Wavefront API and return the result
+    # as a Ruby hash.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @return [Hash] API response
+    #
+    def delete(path)
+      make_call(mk_conn(path), :delete)
+    end
+
+    # If we need to massage a raw response to fit what the
+    # Wavefront::Response class expects (I'm looking at you,
+    # 'User'), a class can provide a {#response_shim} method.
+    #
+    def respond(resp)
+      body = if calling_class.respond_to?(:response_shim)
+               calling_class.response_shim(resp.body, resp.status)
+             else
+               resp.body
+             end
+
+      Wavefront::Response.new(body, resp.status, @opts)
+    end
+
+    # Try to describe the actual HTTP calls we make. There's a bit
+    # of clumsy guesswork here
+    #
+    def verbosity(conn, method, *args)
+      return unless noop || verbose
+      log format('uri: %s %s', method.upcase, conn.url_prefix)
+
+      return unless args.last && !args.last.empty?
+
+      log method == :get ? "params: #{args.last}" : "body: #{args.last}"
+    end
+
+    private
+
+    def paginator_class(method)
+      require_relative File.join('..', 'paginator', method.to_s)
+      Object.const_get(format('Wavefront::Paginator::%s',
+                              method.to_s.capitalize))
+    end
+
+    # A dispatcher for making API calls. We now have three methods
+    # that do the real call, two of which live inside the requisite
+    # Wavefront::Paginator class
+    # @raise [Faraday::ConnectionFailed] if cannot connect to
+    #   endpoint
+    #
+    def make_call(conn, method, *args)
+      verbosity(conn, method, *args)
+      return if noop
+
+      paginator = paginator_class(method).new(self, conn, method, *args)
+
+      case paginator.initial_limit
+      when :all, 'all'
+        paginator.make_recursive_call
+      when :lazy, 'lazy'
+        paginator.make_lazy_call
+      else
+        make_single_call(conn, method, *args)
+      end
+    end
+
+    def make_single_call(conn, method, *args)
+      resp = conn.public_send(method, *args)
+
+      if debug
+        require 'pp'
+        pp resp
+      end
+
+      respond(resp)
+    end
+
+    def setup_endpoint(creds)
+      validate_credentials(creds)
+
+      unless creds.key?(:agent) && creds[:agent]
+        creds[:agent] = "wavefront-sdk #{WF_SDK_VERSION}"
+      end
+
+      @net = { headers:  headers(creds),
+               scheme:   opts[:scheme] || 'https',
+               endpoint: creds[:endpoint],
+               api_base: calling_class.api_path }
+    end
+
+    def headers(creds)
+      ret = { 'user-agent': creds[:agent] }
+      ret[:Authorization] = "Bearer #{creds[:token]}" if creds[:token]
+      ret
+    end
+
+    def validate_credentials(creds)
+      if calling_class.respond_to?(:validate_credentials)
+        calling_class.validate_credentials(creds)
+      else
+        _validate_credentials(creds)
+      end
+    end
+
+    def _validate_credentials(creds)
+      %w[endpoint token].each do |k|
+        unless creds.key?(k.to_sym)
+          raise(Wavefront::Exception::CredentialError,
+                format('credentials must contain %s', k))
+        end
+      end
+    end
+  end
+end

data/lib/wavefront-sdk/{exception.rb → core/exception.rb}

@@ -5,41 +5,46 @@ module Wavefront
   class Exception
     class CredentialError < RuntimeError; end
     class EmptyMetricName < RuntimeError; end
+    class EnumerableError < RuntimeError; end
     class InvalidAlertId < RuntimeError; end
     class InvalidAlertSeverity < RuntimeError; end
     class InvalidCloudIntegrationId < RuntimeError; end
     class InvalidDashboardId < RuntimeError; end
     class InvalidDerivedMetricId < RuntimeError; end
+    class InvalidDistribution < RuntimeError; end
+    class InvalidDistributionInterval < RuntimeError; end
+    class InvalidDistributionCount < RuntimeError; end
     class InvalidEndpoint < RuntimeError; end
     class InvalidEventId < RuntimeError; end
     class InvalidExternalLinkId < RuntimeError; end
     class InvalidGranularity < RuntimeError; end
     class InvalidHostname < RuntimeError; end
     class InvalidIntegrationId < RuntimeError; end
-    class InvalidRelativeTime < RuntimeError; end
-    class InvalidTimeUnit < RuntimeError; end
+    class InvalidLinkTemplate < RuntimeError; end
     class InvalidMaintenanceWindowId < RuntimeError; end
     class InvalidMessageId < RuntimeError; end
     class InvalidMetricName < RuntimeError; end
     class InvalidMetricValue < RuntimeError; end
-    class InvalidNotificantId < RuntimeError; end
     class InvalidName < RuntimeError; end
+    class InvalidNotificantId < RuntimeError; end
     class InvalidPoint < RuntimeError; end
     class InvalidPrefixLength < RuntimeError; end
     class InvalidProxyId < RuntimeError; end
-    class InvalidSavedSearchId < RuntimeError; end
+    class InvalidRelativeTime < RuntimeError; end
     class InvalidSavedSearchEntity < RuntimeError; end
+    class InvalidSavedSearchId < RuntimeError; end
     class InvalidSourceId < RuntimeError; end
     class InvalidString < RuntimeError; end
     class InvalidTag < RuntimeError; end
-    class InvalidLinkTemplate < RuntimeError; end
     class InvalidTimeFormat < RuntimeError; end
+    class InvalidTimeUnit < RuntimeError; end
     class InvalidTimestamp < RuntimeError; end
     class InvalidUserId < RuntimeError; end
-    class InvalidWebhookId < RuntimeError; end
     class InvalidVersion < RuntimeError; end
+    class InvalidWebhookId < RuntimeError; end
     class NotImplemented < RuntimeError; end
     class UnparseableResponse < RuntimeError; end
+    class UnsupportedWriter < RuntimeError; end
     class ValueOutOfRange < RuntimeError; end
   end
 end

data/lib/wavefront-sdk/{logger.rb → core/logger.rb}

@@ -46,12 +46,11 @@ module Wavefront
     end
 
     def print_debug_message(msg)
-      return unless debug
-      puts msg
+      puts msg if debug
     end
 
     def print_info_message(msg)
-      puts msg
+      puts msg if debug || verbose
     end
 
     def print_warn_message(msg)

data/lib/wavefront-sdk/{response.rb → core/response.rb}

@@ -1,7 +1,9 @@
 require 'json'
 require 'map'
+require_relative 'logger'
 require_relative 'exception'
-require_relative 'mixins'
+require_relative '../types/status'
+require_relative '../support/mixins'
 
 module Wavefront
   #
@@ -32,13 +34,10 @@ module Wavefront
     #   has changed underneath us.
     #
     def initialize(json, status, opts = {})
+      setup_vars(opts)
       raw       = raw_response(json, status)
       @status   = build_status(raw, status)
       @response = build_response(raw)
-      @opts     = opts
-
-      setup_opts
-
       logger.log(self, :debug)
     rescue StandardError => e
       logger.log(format("could not parse:\n%s", json), :debug)
@@ -46,69 +45,87 @@ module Wavefront
       raise Wavefront::Exception::UnparseableResponse
     end
 
-    def setup_opts
-      @logger = Wavefront::Logger.new(opts)
+    # Were there items in the response?
+    #
+    def empty?
+      response.items.size.zero?
+    rescue StandardError
+      false
     end
 
-    def raw_response(json, status)
-      json.empty? ? {} : JSON.parse(json, symbolize_names: true)
+    # Was the API's response positive?
+    # @return [Bool]
+    #
+    def ok?
+      respond_to?(:status) && status.result == 'OK'
+    end
+
+    # Are there more items in paginated output?
+    # @return [Bool]
+    #
+    def more_items?
+      return false unless response.key?(:moreItems)
+      !!response.moreItems
+    end
+
+    # On paginated output, the offset of the next item, or nil.
+    # @return [Integer, Nil]
+    #
+    def next_item
+      return nil unless more_items?
+      reponse.offset + response.limit
     rescue StandardError
-      { message: json, code: status }
+      nil
     end
 
-    def build_status(raw, status)
-      Wavefront::Type::Status.new(raw, status)
+    # A printable version of a Wavefront::Response object
+    # @return [String]
+    #
+    def to_s
+      inspect.to_s
     end
 
+    # We often want the IDs of all the objects we retrieved. This
+    # does it.
+
+    def ids
+      response.items.map(&:id)
+    end
+
+    # We often want the names of all the objects we retrieved.
+    #
+    def names
+      response.items.map(&:name)
+    end
+
+    private
+
+    def setup_vars(opts)
+      @opts   = opts
+      @logger = Wavefront::Logger.new(opts)
+    end
+
+    # @params raw [Hash] created by #raw_response
+    #
     def build_response(raw)
       return Map.new unless raw.is_a?(Hash)
       return Map.new(raw) unless raw.key?(:response)
       return raw[:response] unless raw[:response].is_a?(Hash)
       Map(raw[:response])
     end
-  end
 
-  # Status types are used by the Wavefront::Response class
-  #
-  class Type
-    #
-    # An object which provides information about whether the request
-    # was successful or not. Ordinarily this is easy to construct
-    # from the API's JSON response, but some classes, for instance
-    # Wavefront::Write fake it by constructing their own.
-    #
-    # @!attribute [r] result
-    #   @return [OK, ERROR] a string telling us how the request went
-    # @!attribute [r] message
-    #   @return [String] Any informational message from the API
-    # @!attribute [r] code
-    #   @return [Integer] the HTTP response code from the API
-    #     request
+    # Turn the API's JSON response and HTTP status code into a Ruby
+    # object.
+    # @return [Hash]
     #
-    class Status
-      attr_reader :obj, :status
-
-      # @param response [Hash] the API response, turned into a hash
-      # @param status [Integer] HTTP status code
-      #
-      def initialize(response, status)
-        @obj = response.fetch(:status, response)
-        @status = status
-      end
-
-      def message
-        obj[:message] || nil
-      end
-
-      def code
-        obj[:code] || status
-      end
+    def raw_response(json, status)
+      json.empty? ? {} : JSON.parse(json, symbolize_names: true)
+    rescue StandardError
+      { message: json, code: status }
+    end
 
-      def result
-        return obj[:result] if obj[:result]
-        return 'OK' if status.between?(200, 299)
-        'ERROR'
-      end
+    def build_status(raw, status)
+      Wavefront::Type::Status.new(raw, status)
     end
   end
 end