esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/tag.rb

@@ -1,28 +1,33 @@
 module ESP
   class Tag < ESP::Resource
     # Not Implemented. You cannot create or update a Tag.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Tag.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot search for a Tag.
+    #
+    # @return [void]
     def self.where(*)
       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.
+    # 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
+    # @param alert_id [Integer, Numeric] Required ID of the alert to list tags for.
+    # @return [ActiveResource::PaginatedCollection<ESP::Tag>]
+    # @raise [ArgumentError] if no +alert_id+ is supplied.
+    # @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?
@@ -32,12 +37,16 @@ module ESP
 
     # Find a Tag by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the tag to retrieve
+    # *call-seq* -> +super.find(id)+
     #
-    # :call-seq:
-    #  find(id)
+    # @overload find(id)
+    #   @param id [Integer, Numeric] Required ID of the tag to retrieve.
+    # @overload find(scope, options)
+    #   *call-seq* -> +super.all(options)+
+    #   @api private
+    #   @param scope [Object] *Example:* +:all+
+    #   @param options [Hash] +params: { alert_id: Integer }+
+    #   @raise [ArgumentError] if no +alert_id+ is supplied.
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access

data/lib/esp/resources/team.rb

@@ -1,23 +1,28 @@
 module ESP
   class Team < ESP::Resource
-    ##
     # The organization this team belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
-    ##
     # The sub organization this team belongs to.
+    #
+    # @return [ESP::SubOrganization]
     belongs_to :sub_organization, class_name: 'ESP::SubOrganization'
 
-    ##
     # The collection of external_accounts that belong to the team.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
     has_many :external_accounts, class_name: 'ESP::ExternalAccount'
 
-    ##
     # The collection of reports that belong to the team.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Report>]
     has_many :reports, class_name: 'ESP::Report'
 
-    ##
     # The collection of custom_signatures that belong to the team.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature>]
     def custom_signatures
       CustomSignature.where(teams_id_eq: id)
     end
@@ -28,82 +33,75 @@ module ESP
     #   ESP::Report.find(<id>)
     # until status is 'complete'.
     # If not successful, returns a Report object with the errors object populated.
+    #
+    # @return [ESP::Report]
     def create_report
       Report.create_for_team(id)
     end
 
-    # :singleton-method: where
-    # Return a paginated Team list filtered by search parameters
-    #
-    # ==== Parameters
+    # @!method self.where(clauses = {})
+    #   Return a paginated Team list filtered by search parameters
     #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # ===== Valid Clauses
+    #   @param clauses [Hash] A hash of attributes with appended predicates to search, sort and include.
+    #     ===== Valid Clauses
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#team-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#team-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Team>]
 
-    ##
-    # :singleton-method: find
-    # Find a Team by id
-    #
-    # ==== Parameter
+    # @!method self.find(id, options = {})
+    #   Find a Team by id
     #
-    # +id+ | Required | The ID of the team to retrieve
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # +options+ | Optional | A hash of options
+    #   @param id [Integer, Numeric, #to_i] Required ID of the team to retrieve.
+    #   @param options [Hash] Optional hash of options.
+    #     ===== Valid Options
     #
-    # ===== Valid Options
+    #     +include+ | The list of associated objects to return on the initial request.
     #
-    # +include+ | The list of associated objects to return on the initial request.
+    #     ===== Valid Includable Associations
     #
-    # ===== Valid Includable Associations
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#team-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
-
-    # :singleton-method: all
-    # Return a paginated Team list
+    #     See {API documentation}[http://api-docs.evident.io?ruby#team-attributes] for valid arguments
+    #   @return [ESP::Team]
 
-    # :singleton-method: create
-    # Create a Team.
-    # :call-seq:
-    #   create(attributes={})
-    #
-    # ==== Parameter
-    #
-    # +attributes+ | Required | A hash of team attributes
+    # @!method self.all
+    #   Return a paginated Team list
     #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#team-create] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Team>]
+
+    # @!method self.create(attributes = {})
+    #   Create a Team.
+    #   *call-seq* -> +super.create(attributes={})+
     #
-    # ==== Example
+    #   @param attributes [Hash] Required hash of team attributes.
+    #     ===== Valid Attributes
     #
-    #  team = ESP::Team.create(name: "Team Name", sub_organization_id: 9)
+    #     See {API documentation}[http://api-docs.evident.io?ruby#team-create] for valid arguments
+    #   @return [ESP::Team]
+    #   @example
+    #     team = ESP::Team.create(name: "Team Name", sub_organization_id: 9)
 
-    # :method: save
-    # Create and update a Team.
+    # @!method save
+    #   Create and update a Team.
     #
-    # ===== Valid Attributes when updating
+    #   ===== Valid Attributes when updating
     #
-    # +name+ | Required | The new name of the team
+    #   +name+ | Required | The new name of the team
     #
-    # ===== Valid Attributes when creating
+    #   ===== Valid Attributes when creating
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#team-create] for valid arguments
+    #   See {API documentation}[http://api-docs.evident.io?ruby#team-create] for valid arguments
     #
-    # ==== Example
-    #
-    #  team = ESP::Team.new(name: "Team Name", sub_organization_id: 9)
-    #  team.save
+    #   @return [Boolean]
+    #   @example
+    #     team = ESP::Team.new(name: "Team Name", sub_organization_id: 9)
+    #     team.save
 
-    # :method: destroy
-    # Delete a Team.
+    # @!method destroy
+    #   Delete a Team.
+    #
+    #   @return [self]
   end
 end

data/lib/esp/resources/user.rb

@@ -1,72 +1,75 @@
 module ESP
   class User < ESP::Resource
-    ##
     # The organization this user belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
     # Not Implemented. You cannot create or update a User.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a User.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    ##
     # The collection of sub organizations that belong to the user.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::SubOrganization>]
     def sub_organizations
       return attributes['sub_organizations'] if attributes['sub_organizations'].present?
       SubOrganization.where(id_in: sub_organization_ids)
     end
 
-    ##
     # The collection of teams that belong to the user.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Team>]
     def teams
       return attributes['teams'] if attributes['teams'].present?
       Team.where(id_in: team_ids)
     end
 
-    # :singleton-method: where
-    # Return a paginated User list filtered by search parameters
-    #
-    # ==== Parameters
+    # @!method self.where(clauses = {})
+    #   Return a paginated User list filtered by search parameters
     #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # ===== Valid Clauses
+    #   @param clauses [Hash] A hash of attributes with appended predicates to search, sort and include.
+    #     ===== Valid Clauses
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#user-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#user-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::User>]
 
-    ##
-    # :singleton-method: find
-    # Find a User by id
-    #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the user to retrieve
+    # @!method self.find(id, options = {})
+    #   Find a User by id
     #
-    # +options+ | Optional | A hash of options
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # ===== Valid Options
+    #   @param id [Integer, Numeric, #to_i] Required ID of the user to retrieve.
+    #   @param options [Hash] Optional hash of options.
+    #     ===== Valid Options
     #
-    # +include+ | The list of associated objects to return on the initial request.
+    #     +include+ | The list of associated objects to return on the initial request.
     #
-    # ===== Valid Includable Associations
+    #     ===== Valid Includable Associations
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#user-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#user-attributes] for valid arguments
+    #   @return [ESP::User]
 
-    # :singleton-method: all
-    # Return a paginated User list
+    # @!method self.all
+    #   Return a paginated User list
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::User>]
 
-    # :singleton-method: create
-    # Not Implemented. You cannot create a User.
+    # @!method self.create
+    #   Not Implemented. You cannot create a User.
+    #
+    #   @return [void]
   end
 end

data/lib/esp/version.rb

@@ -1,3 +1,3 @@
 module ESP
-  VERSION = '2.5.0'.freeze
+  VERSION = '2.6.0'.freeze
 end

data/lib/esp.rb

@@ -1,71 +1,92 @@
 module ESP
   # Manually set the access_key_id you created from https://esp.evident.io/settings/api_keys.
   #
-  # You can optionally set the `ESP_ACCESS_KEY_ID` environment variable.
+  # You can optionally set the +ESP_ACCESS_KEY_ID+ environment variable.
+  #
+  # @param access_key_id [String] Your access key ID.
+  # @return [void]
   def self.access_key_id=(access_key_id)
     @access_key_id               = access_key_id
     ESP::Resource.hmac_access_id = access_key_id
   end
 
-  # Reads the `ESP_ACCESS_KEY_ID` environment variable if ::access_key_id was not set manually.
+  # Reads the +ESP_ACCESS_KEY_ID+ environment variable if {.access_key_id=} was not set manually.
+  #
+  # Returns nil if no key or environment variable has been set.
+  #
+  # @return [String, nil]
   def self.access_key_id
     @access_key_id || ENV['ESP_ACCESS_KEY_ID']
   end
 
   # Manually set the secret_access_key you created from https://esp.evident.io/settings/api_keys.
   #
-  # You can optionally set the `ESP_SECRET_ACCESS_KEY` environment variable.
+  # You can optionally set the +ESP_SECRET_ACCESS_KEY+ environment variable.
+  #
+  # @param secret_access_key [String] Your secret access key.
+  # @return [void]
   def self.secret_access_key=(secret_access_key)
     @secret_access_key            = secret_access_key
     ESP::Resource.hmac_secret_key = secret_access_key
   end
 
-  # Reads the `ESP_SECRET_ACCESS_KEY` environment variable if ::secret_access_key was not set manually.
+  # Reads the +ESP_SECRET_ACCESS_KEY+ environment variable if {.secret_access_key=} was not set manually.
+  #
+  # Returns nil if no key or environment variable has been set.
+  #
+  # @return [String, nil]
   def self.secret_access_key
     @secret_access_key || ENV['ESP_SECRET_ACCESS_KEY']
   end
 
   PATH = '/api/v2'.freeze
 
+  # @private
   HOST = { development: "http://localhost:3000".freeze,
            test:        "http://localhost:3000".freeze,
-           production:  "https://api.evident.io".freeze }.freeze # :nodoc:
+           production:  "https://api.evident.io".freeze }.freeze
 
   # Users of the Evident.io marketplace appliance application will need to set the host for their instance.
   #
-  # ==== Attribute
-  #
-  # * +host+ - The host for the installed appliance instance.
+  # @param host [String] The host for the installed appliance instance.
+  # @return [void]
   def self.host=(host)
     @host              = host
     ESP::Resource.site = site
   end
 
   # The site the SDK will hit.
+  #
+  # @return [String]
   def self.site
     "#{(@host || HOST[ESP.env.to_sym] || ENV['ESP_HOST'])}#{PATH}"
   end
 
   # Manually set an http_proxy
   #
-  # You can optionally set the `HTTP_PROXY` environment variable.
-  #
-  # ==== Attribute
+  # You can optionally set the +HTTP_PROXY+ environment variable.
   #
-  # * +http_proxy+ - The URI of the http proxy
+  # @param proxy [String] The URI of the http proxy
+  # @return [void]
   def self.http_proxy=(proxy)
     @http_proxy         = proxy
     ESP::Resource.proxy = http_proxy
   end
 
-  # Reads the `HTTP_PROXY` environment variable if ::http_proxy was not set manually.
+  # Reads the +HTTP_PROXY+ environment variable if {.http_proxy=} was not set manually.
+  #
+  # Returns nil if no proxy or environment variable has been set.
+  #
+  # @return [String, nil]
   def self.http_proxy
     @http_proxy || ENV['http_proxy']
   end
 
-  # For use in a Rails initializer to set the ::access_key_id, ::secret_access_key and ::site.
+  # For use in a Rails initializer to set the {.access_key_id=}, {.secret_access_key=} and {.site}.
   #
-  # ==== Example
+  # @yield [self]
+  # @return [void]
+  # @example
   #
   #   ESP.configure do |config|
   #     config.access_key_id = <your key>
@@ -77,7 +98,9 @@ module ESP
     yield self
   end
 
-  # Default environment is production which will set ::site to "https://api.evident.io/api/v2".
+  # Default environment is production which will set {.site} to "https://api.evident.io/api/v2".
+  #
+  # @return [String]
   def self.env
     @env ||= ActiveSupport::StringInquirer.new(ENV['ESP_ENV'] || ENV['RAILS_ENV'] || 'production')
   end

data/lib/esp_sdk.rb

@@ -3,6 +3,7 @@ require 'active_resource'
 require 'api_auth'
 require_relative 'esp/extensions/active_resource/paginated_collection'
 require_relative 'esp/extensions/active_resource/validations'
+require_relative 'esp/extensions/active_resource/dirty'
 require_relative 'esp/extensions/active_resource/formats/json_api_format'
 require_relative 'esp/version'
 require_relative 'esp/exceptions'

data/test/esp/extensions/active_resource/dirty_test.rb

@@ -0,0 +1,81 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../test_helper')
+
+module ActiveResource
+  class DirtyTest < ActiveSupport::TestCase
+    context Dirty do
+      context 'changed_attributes' do
+        context 'for new record' do
+          context '#create' do
+            should 'pass all attributes to API and reset changed_attributes' do
+              stub_request(:post, /custom_signatures.json/).to_return(body: json(:custom_signature, name: 'abc', description: '123'))
+              custom_signature = ESP::CustomSignature.create(name: 'abc', description: '123')
+
+              assert_requested :post, /custom_signatures.json/ do |request|
+                json = JSON.parse(request.body)
+                json['data']['attributes']['name'] == 'abc' &&
+                json['data']['attributes']['description'] == '123'
+              end
+              assert_equal({}, custom_signature.changed_attributes)
+            end
+          end
+
+          context 'save' do
+            should 'pass all attributes to API and reset changed_attributes' do
+              custom_signature = ESP::CustomSignature.new
+              custom_signature.name = 'abc'
+              custom_signature.description = '123'
+              stub_request(:post, /custom_signatures\.json/).to_return(body: json(:custom_signature, name: 'abc', description: '123'))
+
+              custom_signature.save
+
+              assert_requested :post, /custom_signatures.json/ do |request|
+                json = JSON.parse(request.body)
+                json['data']['attributes']['name'] == 'abc' &&
+                json['data']['attributes']['description'] == '123'
+              end
+              assert_equal({}, custom_signature.changed_attributes)
+            end
+          end
+        end
+
+        context 'for record from api' do
+          context 'save' do
+            should 'pass only changed attributes to API and reset changed_attributes' do
+              stub_request(:get, %r{custom_signatures/1.json}).to_return(body: json(:custom_signature, name: 'abc', description: '123'))
+              custom_signature = ESP::CustomSignature.find(1)
+              custom_signature.name = 'def'
+              custom_signature.description = '123'
+              stub_request(:put, %r{custom_signatures/#{custom_signature.id}.json}).to_return(body: custom_signature.to_json)
+
+              custom_signature.save
+
+              assert_requested :put, %r{custom_signatures/#{custom_signature.id}.json} do |request|
+                json = JSON.parse(request.body)
+                json['data']['attributes']['name'] == 'def' &&
+                json['data']['attributes'].exclude?(:description)
+              end
+              assert_equal({}, custom_signature.changed_attributes)
+            end
+          end
+
+          context 'update_attributes' do
+            should 'pass only changed attributes to API and reset changed_attributes' do
+              stub_request(:get, %r{custom_signatures/1.json}).to_return(body: json(:custom_signature, name: 'abc', description: '123'))
+              custom_signature = ESP::CustomSignature.find(1)
+              stub_request(:put, %r{custom_signatures/#{custom_signature.id}.json}).to_return(body: custom_signature.to_json)
+
+              custom_signature.update_attributes(name: 'def', description: '123')
+
+              assert_requested :put, %r{custom_signatures/#{custom_signature.id}.json} do |request|
+                json = JSON.parse(request.body)
+                json['data']['attributes']['name'] == 'def' &&
+                json['data']['attributes'].exclude?(:description)
+              end
+              assert_equal({}, custom_signature.changed_attributes)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/test/esp/extensions/active_resource/formats/json_api_format_test.rb

@@ -49,6 +49,14 @@ module ActiveResource
               # nested objects too
               assert_equal parsed_json['included'].detect { |e| e['type'] == 'external_accounts' }['relationships']['organization']['data']['id'], alert.external_account.organization_id
             end
+
+            should 'not error with included nulls' do
+              manufactured_hash = JSON.parse(json_list(:alert, 1))
+              manufactured_hash['included'] << nil
+              stub_request(:put, %r{reports/1/alerts.json*}).to_return(body: manufactured_hash.to_json)
+
+              ESP::Alert.where(report_id: 1).first
+            end
           end
         end
       end

data/test/esp/extensions/active_resource/paginated_collection_test.rb

@@ -119,6 +119,13 @@ module ActiveResource
               assert_predicate req.uri.query, :blank? # It will only be called once to get the first page
             end
           end
+
+          should 'not error if no initial params were supplied' do
+            stub_request(:get, /reports.json*/).to_return(body: json_list(:report, 3, page: { number: 1, size: 2 }))
+            stub_request(:put, /reports.json*/).to_return(body: json_list(:report, 3, page: { number: 2, size: 2 }))
+            reports = ESP::Report.all
+            reports.next_page
+          end
         end
 
         context '#first_page!' do

data/test/esp/integration/json_api_format_integration_test.rb

@@ -11,12 +11,15 @@ module ESP::Integration
 
             assert_not_nil alert.attributes['external_account']
             assert_equal alert.external_account_id, alert.external_account.id
-            assert_not_nil alert.external_account.attributes['organization']
-            assert_equal alert.external_account.organization_id, alert.external_account.organization.id
+
+            assert_nil alert.attributes['team']
             assert_not_nil alert.external_account.attributes['team']
             assert_equal alert.external_account.team_id, alert.external_account.team.id
+
+            assert_nil alert.attributes['organization']
             assert_not_nil alert.external_account.team.attributes['organization']
             assert_equal alert.external_account.team.organization_id, alert.external_account.team.organization.id
+
             assert_not_nil alert.attributes['region']
             assert_equal alert.region_id, alert.region.id
             if alert.signature.present?

data/test/esp/integration/organization_integration_test.rb

@@ -67,7 +67,7 @@ module ESP::Integration
 
         context '#CRUD' do
           should 'be able to update' do
-            @organization.name = @organization.name
+            @organization.name = "New Name"
             @organization.save
 
             assert_nothing_raised do

data/test/esp/resources/custom_signature_test.rb

@@ -41,6 +41,21 @@ module ESP
         end
       end
 
+      context 'save' do
+        should 'should not send team_ids param if not changed' do
+          stub_request(:get, %r{custom_signatures/1.json}).to_return(body: json(:custom_signature))
+          custom_signature = ESP::CustomSignature.find(1)
+          stub_request(:put, %r{custom_signatures/#{custom_signature.id}.json})
+
+          custom_signature.save
+
+          assert_requested :put, %r{custom_signatures/#{custom_signature.id}.json} do |request|
+            json = JSON.parse(request.body)
+            json['data']['attributes'].exclude?('team_ids')
+          end
+        end
+      end
+
       context '#suppress' do
         should 'call the api' do
           stub_request(:post, %r{suppressions/signatures.json*}).to_return(body: json(:suppression_signature))

data/test/factories/custom_signatures.rb

@@ -11,25 +11,15 @@ FactoryGirl.define do
     name "Test"
     resolution "Test resolution"
     risk_level "Medium"
-    signature "Some javascript"
-    language "javascript"
     updated_at nil
     relationships do
       {
         organization: {
-          data: {
-            type: "organizations",
-            id: "1003"
-          },
           links: {
             related: "http://test.host/api/v2/organizations/1003.json"
           }
         },
         teams: {
-          data: {
-            type: "teams",
-            id: "1003"
-          },
           links: {
             related: "http://test.host/api/v2/teams?filter%5Bcustom_signatures_id_eq%5D=#{id}"
           }