esp_sdk 1.1.0 → 2.0.0.rc1

data/lib/esp/resources/stat_signature.rb

@@ -0,0 +1,121 @@
+module ESP
+  class StatSignature < ESP::Resource
+    include ESP::StatTotals
+
+    # The signature these stats are for.
+    belongs_to :signature, class_name: 'ESP::Signature'
+
+    # Returns a paginated collection of signature stats for the given stat_id
+    # Convenience method to use instead of ::find since a stat_id is required to return signature stats.
+    #
+    # ==== Parameter
+    #
+    # +stat_id+ | Required | The ID of the stat to list signature stats for
+    #
+    # ==== Example
+    #   stats = ESP::StatSignature.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}/signatures.json"
+      find(:all, from: from)
+    end
+
+    # Find a StatRegion by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the 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/sub_organization.rb

@@ -0,0 +1,69 @@
+module ESP
+  class SubOrganization < ESP::Resource
+    ##
+    # The organization this sub organization belongs to.
+    belongs_to :organization, class_name: 'ESP::Organization'
+
+    ##
+    # The collection of teams that belong to the sub organization.
+    has_many :teams, class_name: 'ESP::Team'
+
+    ##
+    # The collection of external_accounts that belong to the sub organization.
+    has_many :external_accounts, class_name: 'ESP::ExternalAccount'
+
+    ##
+    # The collection of reports that belong to the sub organization.
+    has_many :reports, class_name: 'ESP::Report'
+
+    ##
+    # :singleton-method: find
+    # Find a SubOrganization by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the sub organization to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+
+    # :singleton-method: all
+    # Return a paginated SubOrganization list
+
+    # :singleton-method: create
+    # Create a SubOrganization.
+    # :call-seq:
+    #   create(attributes={})
+    #
+    # ==== Parameters
+    #
+    # +attributes+ | Required | A hash of run arguments
+    #
+    # ===== Valid Attributes
+    #
+    # +name+ | Required | The name of the sub organization
+    #
+    # ==== Example
+    #
+    #  sub_organization = ESP::SubOrganization.create(name: "Sub Organization Name")
+
+    # :method: save
+    # Create and update a SubOrganization.
+    #
+    # ==== Parameters
+    #
+    # +attributes+ | Required | A hash of run arguments
+    #
+    # ===== Valid Attributes
+    #
+    # +name+ | Required | The name of the sub organization
+    #
+    # ==== Example
+    #
+    #  sub_organization = ESP::SubOrganization.new(name: "Sub Organization Name")
+    #  sub_organization.save
+
+    # :method: destroy
+    # Delete a SubOrganization.
+  end
+end

data/lib/esp/resources/suppression/region.rb

@@ -0,0 +1,99 @@
+module ESP
+  class Suppression
+    class Region < ESP::Resource
+      self.prefix += "suppressions/"
+
+      # Not Implemented. You cannot search for Suppression::Region.
+      #
+      # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      def self.find(*)
+        fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
+      end
+
+      # Not Implemented. You cannot update a Suppression::Region.
+      def update
+        fail ESP::NotImplementedError
+      end
+
+      # Not Implemented. You cannot destroy a Suppression::Region.
+      def destroy
+        fail ESP::NotImplementedError
+      end
+
+      # This instance method is called by the #save method when new? is true.
+      def create # :nodoc:
+        original_prefix = self.class.prefix
+        if attributes[:alert_id]
+          self.class.prefix += "alert/:alert_id/"
+          prefix_options[:alert_id] = alert_id
+        end
+        super
+      ensure
+        self.class.prefix = original_prefix
+      end
+
+      # :singleton-method: create
+      # Create a suppression for a region.
+      #
+      # If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #
+      # :call-seq:
+      #   create(attributes={})
+      #
+      # ==== Parameter
+      #
+      # +attributes+ | Required | A hash of region suppression attributes
+      #
+      # ===== Valid Attributes When Not Creating for Alert
+      #
+      # +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.
+      #
+      # +resource+ | Not Required | The resource string this suppression will suppress alerts for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   create(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #
+      # ===== Valid Attributes When Creating for Alert
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+
+      # :method: save
+      # Create a suppression for a region.
+      #
+      # If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #
+      # ===== Valid Attributes When Not Creating for Alert
+      #
+      # +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.
+      #
+      # +resource+ | Not Required | The resource string this suppression will suppress alerts for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   suppression = new(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #   suppression.save
+      #
+      # ===== Valid Attributes When Creating for Alert
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #   suppression.save
+    end
+  end
+end

data/lib/esp/resources/suppression/signature.rb

@@ -0,0 +1,107 @@
+module ESP
+  class Suppression
+    class Signature < ESP::Resource
+      self.prefix += "suppressions/"
+
+      # Not Implemented. You cannot search for Suppression::Signature.
+      #
+      # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      def self.find(*)
+        fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
+      end
+
+      # Not Implemented. You cannot update a Suppression::Signature.
+      def update
+        fail ESP::NotImplementedError
+      end
+
+      # Not Implemented. You cannot destroy a Suppression::Signature.
+      def destroy
+        fail ESP::NotImplementedError
+      end
+
+      # This instance method is called by the #save method when new? is true.
+      def create # :nodoc:
+        original_prefix = self.class.prefix
+        if attributes[:alert_id]
+          self.class.prefix += "alert/:alert_id/"
+          prefix_options[:alert_id] = alert_id
+        end
+        super
+      ensure
+        self.class.prefix = original_prefix
+      end
+
+      # :singleton-method: create
+      # Create a suppression for a signature or custom signature.
+      #
+      # If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #
+      # :call-seq:
+      #   create(attributes={})
+      #
+      # ==== Parameter
+      #
+      # +attributes+ | Required | A hash of signature suppression attributes
+      #
+      # ===== Valid Attributes When Not Creating for Alert
+      #
+      # +signature_ids+ | Conditionally Required | An array of signatures identified by +signature_id+ to suppress.  Required if +custom_signature_ids+ is blank.
+      #
+      # +custom_signature_ids+ | Conditionally Required | An array of custom signatures identified by +custom_signature_id+ to suppress.  Required if +signature_ids+ is blank.
+      #
+      # +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.
+      #
+      # +resource+ | Not Required | The resource string this suppression will suppress alerts for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   create(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #
+      # ===== Valid Attributes When Creating for Alert
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+
+      # :method: save
+      # Create a suppression for a signature or custom signature.
+      #
+      # If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #
+      # ===== Valid Attributes When Not Creating for Alert
+      #
+      # +signature_ids+ | Conditionally Required | An array of signatures identified by +signature_id+ to suppress.  Required if +custom_signature_ids+ is blank.
+      #
+      # +custom_signature_ids+ | Conditionally Required | An array of custom signatures identified by +custom_signature_id+ to suppress.  Required if +signature_ids+ is blank.
+      #
+      # +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.
+      #
+      # +resource+ | Not Required | The resource string this suppression will suppress alerts for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   suppression = new(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #   suppression.save
+      #
+      # ===== Valid Attributes When Creating for Alert
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #   suppression.save
+    end
+  end
+end

data/lib/esp/resources/suppression/unique_identifier.rb

@@ -0,0 +1,60 @@
+module ESP
+  class Suppression
+    class UniqueIdentifier < ESP::Resource
+      self.prefix += "suppressions/alert/:alert_id/"
+
+      # Not Implemented. You cannot search for Suppression::UniqueIdentifier.
+      #
+      # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      def self.find(*)
+        fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
+      end
+
+      # Not Implemented. You cannot update a Suppression::UniqueIdentifier.
+      def update
+        fail ESP::NotImplementedError
+      end
+
+      # Not Implemented. You cannot destroy a Suppression::UniqueIdentifier.
+      def destroy
+        fail ESP::NotImplementedError
+      end
+
+      # :singleton-method: create
+      # Create a suppression for a unique identifier.
+      #
+      # Pass an +alert_id+, the suppression will be created based on that alert.
+      #
+      # :call-seq:
+      #   create(attributes={})
+      #
+      # ==== Parameter
+      #
+      # +attributes+ | Required | A hash of unique identifier suppression attributes
+      #
+      # ==== Attributes
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+
+      # :method: save
+      # Create a suppression for a unique identifier.
+      #
+      # Set an +alert_id+, the suppression will be created based on that alert.
+      #
+      # ==== Attributes
+      #
+      # +alert_id+ | Required | The id for the alert you want to create a suppression for.
+      #
+      # +reason+ | Required | The reason for creating the suppression.
+      #
+      # ==== Example
+      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #   suppression.save
+    end
+  end
+end

data/lib/esp/resources/suppression.rb

@@ -0,0 +1,86 @@
+module ESP
+  class Suppression < ESP::Resource
+    ##
+    # The organization this sub organization belongs to.
+    belongs_to :organization, class_name: 'ESP::Organization'
+
+    ##
+    # The user who created the suppression.
+    belongs_to :created_by, class_name: 'ESP::User'
+
+    ##
+    # The regions affected by this suppression.
+    has_many :regions, class_name: 'ESP::Region'
+
+    ##
+    # The external accounts affected by this suppression.
+    has_many :external_accounts, class_name: 'ESP::ExternalAccount'
+
+    ##
+    # The signatures being suppressed.
+    def signatures
+      return [] unless respond_to? :signature_ids
+      ESP::Signature.find(:all, params: { id: signature_ids })
+    end
+
+    ##
+    # The custom signatures being suppressed.
+    def custom_signatures
+      return [] unless respond_to? :custom_signature_ids
+      ESP::CustomSignature.find(:all, params: { id: custom_signature_ids })
+    end
+
+    # Overriden so the correct param is sent on the has_many relationships.  API needs this one to be plural.
+    def self.element_name # :nodoc:
+      'suppressions'
+    end
+
+    # Not Implemented. You cannot create or update a Suppression.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a Suppression.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    # Deactivate the current suppression instance.
+    # The current object will be updated with the new status if successful.
+    # Throws an error if not successful.
+    # === Once deactivated the suppression cannot be reactivated.
+    def deactivate!
+      return self if deactivate
+      self.message = errors.full_messages.join(' ')
+      fail(ActiveResource::ResourceInvalid.new(self)) # rubocop:disable Style/RaiseArgs
+    end
+
+    # Deactivate the current suppression instance.
+    # The current object will be updated with the new status if successful.
+    # If not successful, populates its errors object.
+    # === Once deactivated the suppression cannot be reactivated.
+    def deactivate
+      patch(:deactivate).tap do |response|
+        load_attributes_from_response(response)
+      end
+    rescue ActiveResource::BadRequest, ActiveResource::ResourceInvalid, ActiveResource::UnauthorizedAccess => error
+      load_remote_errors(error, true)
+      self.code = error.response.code
+      false
+    end
+
+    ##
+    # :singleton-method: find
+    # Find a Suppression by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the suppression to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+
+    # :singleton-method: all
+    # Return a paginated Suppression list
+  end
+end

data/lib/esp/resources/tag.rb

@@ -0,0 +1,45 @@
+module ESP
+  class Tag < ESP::Resource
+    # Not Implemented. You cannot create or update a Tag.
+    def save
+      fail ESP::NotImplementedError
+    end
+
+    # Not Implemented. You cannot destroy a Tag.
+    def destroy
+      fail ESP::NotImplementedError
+    end
+
+    # Returns a paginated collection of tags for the given alert_id
+    # Convenience method to use instead of ::find since an alert_id is required to return tags.
+    #
+    # ==== Parameter
+    #
+    # +alert_id+ | Required | The ID of the alert to list tags for
+    #
+    # ==== Example
+    #   alerts = ESP::Tag.for_alert(1194)
+    def self.for_alert(alert_id = nil)
+      fail ArgumentError, "You must supply an alert id." unless alert_id.present?
+      from = "#{prefix}alerts/#{alert_id}/tags.json"
+      find(:all, from: from)
+    end
+
+    # Find a Tag by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the tag 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
+      alert_id = params.delete(:alert_id)
+      for_alert(alert_id)
+    end
+  end
+end

data/lib/esp/resources/team.rb

@@ -0,0 +1,79 @@
+module ESP
+  class Team < ESP::Resource
+    ##
+    # The organization this team belongs to.
+    belongs_to :organization, class_name: 'ESP::Organization'
+
+    ##
+    # The sub organization this team belongs to.
+    belongs_to :sub_organization, class_name: 'ESP::SubOrganization'
+
+    ##
+    # The collection of external_accounts that belong to the team.
+    has_many :external_accounts, class_name: 'ESP::ExternalAccount'
+
+    ##
+    # The collection of reports that belong to the team.
+    has_many :reports, class_name: 'ESP::Report'
+
+    # Enqueue a report to be run for this team.
+    # Returns a Report object with a status of 'queued' and an id
+    # Periodically check the API
+    #   ESP::Report.find(<id>)
+    # until status is 'complete'.
+    # If not successful, returns a Report object with the errors object populated.
+    def create_report
+      Report.create_for_team(id)
+    end
+
+    ##
+    # :singleton-method: find
+    # Find a Team by id
+    #
+    # ==== Parameter
+    #
+    # +id+ | Required | The ID of the team to retrieve
+    #
+    # :call-seq:
+    #  find(id)
+
+    # :singleton-method: all
+    # Return a paginated Team list
+
+    # :singleton-method: create
+    # Create a Team.
+    # :call-seq:
+    #   create(attributes={})
+    #
+    # ==== Parameter
+    #
+    # +attributes+ | Required | A hash of team attributes
+    #
+    # ==== Valid Attributes
+    #
+    # +sub_organization_id+ | Required | The ID of the sub organization to attach this team to
+    #
+    # +name+ | Required | The name of the team
+
+    # :method: save
+    # Create and update a Team.
+    #
+    # ==== Valid Attributes when updating
+    #
+    # +name+ | Required | The new name of the team
+    #
+    # ==== Valid Attributes when creating
+    #
+    # +sub_organization_id+ | Required | The ID of the sub organization to attach this team to
+    #
+    # +name+ | Required | The name of the team
+    #
+    # ==== Example
+    #
+    #  team = ESP::Team.new(name: "Team Name", sub_organization_id: 9)
+    #  team.save
+
+    # :method: destroy
+    # Delete a Team.
+  end
+end