esp_sdk 1.1.0 → 2.0.0.rc1

data/lib/esp/resources/resource.rb

@@ -0,0 +1,66 @@
+module ESP
+  class Resource < ActiveResource::Base # :nodoc:
+    self.site = ESP.site
+    self.format = ActiveResource::Formats::JsonAPIFormat
+    with_api_auth(ESP.access_key_id, ESP.secret_access_key)
+    headers["Content-Type"] = format.mime_type
+
+    self.collection_parser = ActiveResource::PaginatedCollection
+
+    def self.where(*)
+      fail ESP::NotImplementedError
+    end
+
+    # Pass a json api compliant hash to the api.
+    def serializable_hash(*)
+      h = attributes.extract!('included')
+      h['data'] = { 'type' => self.class.to_s.underscore.sub('esp/', '').pluralize,
+                    'attributes' => attributes.except('id', 'type', 'created_at', 'updated_at', 'relationships') }
+      h['data']['id'] = id if id.present?
+      h
+    end
+
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      arrange_options(options)
+      super(scope, options).tap do |object|
+        make_pageable object, options
+      end
+    end
+
+    def self.filters(params)
+      h = {}.tap do |filters|
+        params.each do |attr, value|
+          if value.is_a? Enumerable
+            filters["#{attr.sub(/_in$/, '')}_in"] = value
+          else
+            filters["#{attr.sub(/_eq$/, '')}_eq"] = value
+          end
+        end
+      end
+      { filter: h }
+    end
+
+    def self.make_pageable(object, options)
+      return object unless object.is_a? ActiveResource::PaginatedCollection
+      # Need to set from so paginated collection can use it for page calls.
+      object.tap do |collection|
+        collection.from = options['from']
+        collection.original_params = options['params']
+      end
+    end
+
+    def self.arrange_options(options)
+      if options[:params].present?
+        page = options[:params][:page] ? { page: options[:params].delete(:page) } : {}
+        options[:params].merge!(options[:params].delete(:filter)) if options[:params][:filter]
+        options[:params] = filters(options[:params]).merge!(page)
+      end
+      if options[:include].present?
+        options[:params] ||= {}
+        options[:params].merge!(options.extract!(:include))
+      end
+    end
+  end
+end

data/lib/esp/resources/service.rb

@@ -0,0 +1,31 @@
+module ESP
+  class Service < ESP::Resource
+    ##
+    # The collection of signatures associated with this service.
+    has_many :signatures, class_name: 'ESP::Signature'
+
+    # Not Implemented. You cannot create or update a Service.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a Service.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    ##
+    # :singleton-method: find
+    # Find a Service by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the service to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+
+    # :singleton-method: all
+    # Return a paginated Service list
+  end
+end

data/lib/esp/resources/signature.rb

@@ -0,0 +1,106 @@
+module ESP
+  class Signature < ESP::Resource
+    ##
+    # The service this signature belongs to.
+    belongs_to :service, class_name: 'ESP::Service'
+
+    # Not Implemented. You cannot create or update a Signature.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a Signature.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    # Run this signature.
+    # Returns a collection of alerts.
+    # Throws an error if not successful.
+    #
+    # ==== Parameters
+    #
+    # +arguments+ | Required | A hash of run arguments
+    #
+    # ===== Valid Arguments
+    #
+    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
+    #
+    # +regions+ | Required | Array of region names to run this custom signature against
+    #
+    # ==== Example
+    #   signature = ESP::Signature.find(3)
+    #   alerts = signature.run!(external_account_id: 3, regions: ['us_east_1'])
+    def run!(arguments = {})
+      result = run(arguments)
+      return result if result.is_a?(ActiveResource::Collection)
+      result.message = result.errors.full_messages.join(' ')
+      fail(ActiveResource::ResourceInvalid.new(result)) # rubocop:disable Style/RaiseArgs
+    end
+
+    # Run this signature.
+    # Returns a collection of alerts.
+    # If not successful, returns a Signature object with the errors object populated.
+    #
+    # ==== Parameters
+    #
+    # +arguments+ | Required | A hash of run arguments
+    #
+    # ===== Valid Arguments
+    #
+    # +external_account_id+ | Required | The ID of the external account to run this custom signature against
+    #
+    # +regions+ | Required | Array of region names to run this custom signature against
+    #
+    # ==== Example
+    #   signature = ESP::Signature.find(3)
+    #   alerts = signature.run(external_account_id: 3, regions: ['us_east_1'])
+    def run(arguments = {})
+      arguments = arguments.with_indifferent_access
+      attributes['external_account_id'] ||= arguments[:external_account_id]
+      attributes['regions'] ||= Array(arguments[:regions])
+
+      response = connection.post("#{self.class.prefix}signatures/#{id}/run.json", to_json)
+      ESP::Alert.send(:instantiate_collection, self.class.format.decode(response.body))
+    rescue ActiveResource::BadRequest, ActiveResource::ResourceInvalid, ActiveResource::ResourceNotFound => error
+      load_remote_errors(error, true)
+      self.code = error.response.code
+      self
+    end
+
+    # Create a suppression for this signature.
+    #
+    # ==== Parameter
+    #
+    # +arguments+ | Required | A hash of signature suppression attributes
+    #
+    # ===== Valid Arguments
+    #
+    # +regions+ | Required | An array of region names to suppress.
+    #
+    # +external_account_ids+ | Required | An Array of the external accounts identified by +external_account_id+ to suppress the signature or custom signature on.
+    #
+    # +reason+ | Required | The reason for creating the suppression.
+    #
+    # ==== Example
+    #   suppress(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+    def suppress(arguments = {})
+      arguments = arguments.with_indifferent_access
+      ESP::Suppression::Signature.create(signature_ids: [id], regions: Array(arguments[:regions]), external_account_ids: Array(arguments[:external_account_ids]), reason: arguments[:reason])
+    end
+
+    ##
+    # :singleton-method: find
+    # Find a Signature by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the signature to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+
+    # :singleton-method: all
+    # Return a paginated Signature list
+  end
+end

data/lib/esp/resources/stat.rb

@@ -0,0 +1,124 @@
+module ESP
+  class Stat < ESP::Resource
+    include ESP::StatTotals
+
+    ##
+    # The report these stats are for.
+    belongs_to :report, class_name: 'ESP::Report'
+
+    ##
+    # The stats for each region associated with this stat object.
+    has_many :regions, class_name: 'ESP::StatRegion'
+
+    ##
+    # The stats for each service associated with this stat object.
+    has_many :services, class_name: 'ESP::StatService'
+
+    ##
+    # The stats for each signature associated with this stat object.
+    has_many :signatures, class_name: 'ESP::StatSignature'
+
+    ##
+    # The stats for each custom signature associated with this stat object.
+    has_many :custom_signatures, class_name: 'ESP::StatCustomSignature'
+
+    # Not Implemented. You cannot search for a Stat.
+    def self.find(*)
+      fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use either the ESP::Stat.for_report or ESP::Stat.latest_for_teams method.'
+    end
+
+    # :singleton-method: create
+    # Not Implemented. You cannot create a Stat.
+
+    # :method: save
+    # Not Implemented. You cannot create or update a Stat.
+
+    # :method: destroy
+    # Not Implemented. You cannot delete a Stat.
+
+    # Returns all the stats of all the alerts for a report identified by the report_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.
+    def self.for_report(report_id = nil)
+      fail ArgumentError, "You must supply a report id." unless report_id.present?
+      # call find_one directly since find is overriden/not implemented
+      find_one(from: "#{prefix}reports/#{report_id}/stats.json")
+    end
+
+    # Returns all the stats for the most recent report of each team accessible by the given API key.
+    def self.latest_for_teams
+      # call find_every directly since find is overriden/not implemented
+      find_every(from: :latest_for_teams)
+    end
+
+    # :section: 'total' rollup methods
+
+    # :method: total
+
+    # :method: total_pass
+
+    # :method: total_fail
+
+    # :method: total_warn
+
+    # :method: total_error
+
+    # :method: total_info
+
+    # :method: total_new_1h_pass
+
+    # :method: total_new_1h_fail
+
+    # :method: total_new_1h_warn
+
+    # :method: total_new_1h_error
+
+    # :method: total_new_1h_info
+
+    # :method: total_new_1d_pass
+
+    # :method: total_new_1d_fail
+
+    # :method: total_new_1d_warn
+
+    # :method: total_new_1d_error
+
+    # :method: total_new_1d_info
+
+    # :method: total_new_1w_pass
+
+    # :method: total_new_1w_fail
+
+    # :method: total_new_1w_error
+
+    # :method: total_new_1w_info
+
+    # :method: total_new_1w_warn
+
+    # :method: total_old_fail
+
+    # :method: total_old_pass
+
+    # :method: total_old_warn
+
+    # :method: total_old_error
+
+    # :method: total_old_info
+
+    # :method: total_suppressed
+
+    # :method: total_suppressed_pass
+
+    # :method: total_suppressed_fail
+
+    # :method: total_suppressed_warn
+
+    # :method: total_suppressed_error
+
+    # :method: total_new_1h
+
+    # :method: total_new_1d
+
+    # :method: total_new_1w
+
+    # :method: total_old
+  end
+end

data/lib/esp/resources/stat_custom_signature.rb

@@ -0,0 +1,121 @@
+module ESP
+  class StatCustomSignature < ESP::Resource
+    include ESP::StatTotals
+
+    # The custom_signature these stats are for.
+    belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
+
+    # Returns a paginated collection of custom_signature stats for the given stat_id
+    # Convenience method to use instead of ::find since a stat_id is required to return custom_signature stats.
+    #
+    # ==== Parameter
+    #
+    # +stat_id+ | Required | The ID of the stat to list custom_signature stats for
+    #
+    # ==== Example
+    #   stats = ESP::StatCustomSignature.for_stat(1194)
+    def self.for_stat(stat_id = nil)
+      fail ArgumentError, "You must supply a stat id." unless stat_id.present?
+      from = "#{prefix}stats/#{stat_id}/custom_signatures.json"
+      find(:all, from: from)
+    end
+
+    # Find a StatRegion by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the custom_signature stat to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      return super(scope, options) if scope.is_a?(Numeric) || options[:from].present?
+      params = options.fetch(:params, {}).with_indifferent_access
+      stat_id = params.delete(:stat_id)
+      for_stat(stat_id)
+    end
+
+    # :singleton-method: create
+    # Not Implemented. You cannot create a Stat.
+
+    # :method: save
+    # Not Implemented. You cannot create or update a Stat.
+
+    # :method: destroy
+    # Not Implemented. You cannot delete a Stat.
+
+    # :section: 'total' rollup methods
+
+    # :method: total
+
+    # :method: total_pass
+
+    # :method: total_fail
+
+    # :method: total_warn
+
+    # :method: total_error
+
+    # :method: total_info
+
+    # :method: total_new_1h_pass
+
+    # :method: total_new_1h_fail
+
+    # :method: total_new_1h_warn
+
+    # :method: total_new_1h_error
+
+    # :method: total_new_1h_info
+
+    # :method: total_new_1d_pass
+
+    # :method: total_new_1d_fail
+
+    # :method: total_new_1d_warn
+
+    # :method: total_new_1d_error
+
+    # :method: total_new_1d_info
+
+    # :method: total_new_1w_pass
+
+    # :method: total_new_1w_fail
+
+    # :method: total_new_1w_error
+
+    # :method: total_new_1w_info
+
+    # :method: total_new_1w_warn
+
+    # :method: total_old_fail
+
+    # :method: total_old_pass
+
+    # :method: total_old_warn
+
+    # :method: total_old_error
+
+    # :method: total_old_info
+
+    # :method: total_suppressed
+
+    # :method: total_suppressed_pass
+
+    # :method: total_suppressed_fail
+
+    # :method: total_suppressed_warn
+
+    # :method: total_suppressed_error
+
+    # :method: total_new_1h
+
+    # :method: total_new_1d
+
+    # :method: total_new_1w
+
+    # :method: total_old
+  end
+end

data/lib/esp/resources/stat_region.rb

@@ -0,0 +1,121 @@
+module ESP
+  class StatRegion < ESP::Resource
+    include ESP::StatTotals
+
+    # The region these stats are for.
+    belongs_to :region, class_name: 'ESP::Region'
+
+    # Returns a paginated collection of region stats for the given stat_id
+    # Convenience method to use instead of ::find since a stat_id is required to return region stats.
+    #
+    # ==== Parameter
+    #
+    # +stat_id+ | Required | The ID of the stat to list region stats for
+    #
+    # ==== Example
+    #   stats = ESP::StatRegion.for_stat(1194)
+    def self.for_stat(stat_id = nil)
+      fail ArgumentError, "You must supply a stat id." unless stat_id.present?
+      from = "#{prefix}stats/#{stat_id}/regions.json"
+      find(:all, from: from)
+    end
+
+    # Find a StatRegion by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the region stat to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      return super(scope, options) if scope.is_a?(Numeric) || options[:from].present?
+      params = options.fetch(:params, {}).with_indifferent_access
+      stat_id = params.delete(:stat_id)
+      for_stat(stat_id)
+    end
+
+    # :singleton-method: create
+    # Not Implemented. You cannot create a Stat.
+
+    # :method: save
+    # Not Implemented. You cannot create or update a Stat.
+
+    # :method: destroy
+    # Not Implemented. You cannot delete a Stat.
+
+    # :section: 'total' rollup methods
+
+    # :method: total
+
+    # :method: total_pass
+
+    # :method: total_fail
+
+    # :method: total_warn
+
+    # :method: total_error
+
+    # :method: total_info
+
+    # :method: total_new_1h_pass
+
+    # :method: total_new_1h_fail
+
+    # :method: total_new_1h_warn
+
+    # :method: total_new_1h_error
+
+    # :method: total_new_1h_info
+
+    # :method: total_new_1d_pass
+
+    # :method: total_new_1d_fail
+
+    # :method: total_new_1d_warn
+
+    # :method: total_new_1d_error
+
+    # :method: total_new_1d_info
+
+    # :method: total_new_1w_pass
+
+    # :method: total_new_1w_fail
+
+    # :method: total_new_1w_error
+
+    # :method: total_new_1w_info
+
+    # :method: total_new_1w_warn
+
+    # :method: total_old_fail
+
+    # :method: total_old_pass
+
+    # :method: total_old_warn
+
+    # :method: total_old_error
+
+    # :method: total_old_info
+
+    # :method: total_suppressed
+
+    # :method: total_suppressed_pass
+
+    # :method: total_suppressed_fail
+
+    # :method: total_suppressed_warn
+
+    # :method: total_suppressed_error
+
+    # :method: total_new_1h
+
+    # :method: total_new_1d
+
+    # :method: total_new_1w
+
+    # :method: total_old
+  end
+end

data/lib/esp/resources/stat_service.rb

@@ -0,0 +1,121 @@
+module ESP
+  class StatService < ESP::Resource
+    include ESP::StatTotals
+
+    # The service these stats are for.
+    belongs_to :service, class_name: 'ESP::Service'
+
+    # Returns a paginated collection of service stats for the given stat_id
+    # Convenience method to use instead of ::find since a stat_id is required to return service stats.
+    #
+    # ==== Parameter
+    #
+    # +stat_id+ | Required | The ID of the stat to list service stats for
+    #
+    # ==== Example
+    #   stats = ESP::StatService.for_stat(1194)
+    def self.for_stat(stat_id = nil)
+      fail ArgumentError, "You must supply a stat id." unless stat_id.present?
+      from = "#{prefix}stats/#{stat_id}/services.json"
+      find(:all, from: from)
+    end
+
+    # Find a StatService by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the service stat to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+    def self.find(*arguments)
+      scope = arguments.slice!(0)
+      options = (arguments.slice!(0) || {}).with_indifferent_access
+      return super(scope, options) if scope.is_a?(Numeric) || options[:from].present?
+      params = options.fetch(:params, {}).with_indifferent_access
+      stat_id = params.delete(:stat_id)
+      for_stat(stat_id)
+    end
+
+    # :singleton-method: create
+    # Not Implemented. You cannot create a Stat.
+
+    # :method: save
+    # Not Implemented. You cannot create or update a Stat.
+
+    # :method: destroy
+    # Not Implemented. You cannot delete a Stat.
+
+    # :section: 'total' rollup methods
+
+    # :method: total
+
+    # :method: total_pass
+
+    # :method: total_fail
+
+    # :method: total_warn
+
+    # :method: total_error
+
+    # :method: total_info
+
+    # :method: total_new_1h_pass
+
+    # :method: total_new_1h_fail
+
+    # :method: total_new_1h_warn
+
+    # :method: total_new_1h_error
+
+    # :method: total_new_1h_info
+
+    # :method: total_new_1d_pass
+
+    # :method: total_new_1d_fail
+
+    # :method: total_new_1d_warn
+
+    # :method: total_new_1d_error
+
+    # :method: total_new_1d_info
+
+    # :method: total_new_1w_pass
+
+    # :method: total_new_1w_fail
+
+    # :method: total_new_1w_error
+
+    # :method: total_new_1w_info
+
+    # :method: total_new_1w_warn
+
+    # :method: total_old_fail
+
+    # :method: total_old_pass
+
+    # :method: total_old_warn
+
+    # :method: total_old_error
+
+    # :method: total_old_info
+
+    # :method: total_suppressed
+
+    # :method: total_suppressed_pass
+
+    # :method: total_suppressed_fail
+
+    # :method: total_suppressed_warn
+
+    # :method: total_suppressed_error
+
+    # :method: total_new_1h
+
+    # :method: total_new_1d
+
+    # :method: total_new_1w
+
+    # :method: total_old
+  end
+end