v3: replace created_at query param with created_ats on audit_events

[ finishes #173574658]

Co-authored-by: Reid Mitchell <rmitchell@pivotal.io>
Co-authored-by: Merric de Launey <mdelauney@pivotal.io>

Author: reidmit

app/fetchers/event_list_fetcher.rb

@@ -28,10 +28,10 @@ def filter(message, dataset)
           dataset = dataset.where(organization_guid: message.organization_guids)
         end
 
-        if message.requested?(:created_at)
-          if message.created_at.is_a?(Hash)
-            operator = message.created_at.keys[0]
-            given_timestamp = message.created_at.values[0]
+        if message.requested?(:created_ats)
+          if message.created_ats.is_a?(Hash)
+            operator = message.created_ats.keys[0]
+            given_timestamp = message.created_ats.values[0]
 
             if operator == Event::LESS_THAN_COMPARATOR
               normalized_timestamp = Time.parse(given_timestamp).utc
@@ -53,7 +53,7 @@ def filter(message, dataset)
             # Gotcha: the equals operator returns all resources occurring within
             # the span of the second (e.g. "12:34:56.00-12:34:56.9999999"), for databases store
             # timestamps in sub-second accuracy (PostgreSQL stores in microseconds, for example)
-            lower_bound = Time.parse(message.created_at).utc
+            lower_bound = Time.parse(message.created_ats).utc
             upper_bound = Time.at(lower_bound + 0.99999).utc
             dataset = dataset.where(Sequel.lit('created_at BETWEEN ? AND ?', lower_bound, upper_bound))
           end

app/messages/events_list_message.rb

@@ -4,34 +4,34 @@ module VCAP::CloudController
   class EventsListMessage < ListMessage
     class CreatedAtValidator < ActiveModel::Validator
       def validate(record)
-        if record.requested?(:created_at)
-          if record.created_at.is_a?(String)
-            timestamp = record.created_at
+        if record.requested?(:created_ats)
+          if record.created_ats.is_a?(String)
+            timestamp = record.created_ats
           else
-            unless record.created_at.is_a?(Hash)
-              record.errors[:created_at] << 'comparison operator and timestamp must be specified'
+            unless record.created_ats.is_a?(Hash)
+              record.errors[:created_ats] << 'comparison operator and timestamp must be specified'
               return
             end
 
-            comparison_operator = record.created_at.keys[0]
+            comparison_operator = record.created_ats.keys[0]
             valid_comparision_operators = [
               Event::LESS_THAN_COMPARATOR,
               Event::GREATER_THAN_COMPARATOR,
               Event::LESS_THAN_OR_EQUAL_COMPARATOR,
               Event::GREATER_THAN_OR_EQUAL_COMPARATOR,
             ]
             unless valid_comparision_operators.include?(comparison_operator)
-              record.errors[:created_at] << "Invalid comparison operator: '#{comparison_operator}'"
+              record.errors[:created_ats] << "Invalid comparison operator: '#{comparison_operator}'"
             end
 
-            timestamp = record.created_at.values[0]
+            timestamp = record.created_ats.values[0]
           end
           begin
             raise ArgumentError.new('invalid date') unless timestamp =~ /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\Z/
 
             Time.iso8601(timestamp)
           rescue
-            record.errors[:created_at] << "has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'"
+            record.errors[:created_ats] << "has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'"
             return
           end
         end
@@ -43,7 +43,7 @@ def validate(record)
       :target_guids,
       :space_guids,
       :organization_guids,
-      :created_at
+      :created_ats
     ]
 
     validates_with NoAdditionalParamsValidator

docs/v3/source/includes/concepts/_filters.md.erb

@@ -41,21 +41,13 @@ This will return all routes with hostname `"hostname1"`, `""` OR `"hostname2"`.
 
 #### Relational Operators (Experimental)
 
-##### Filtering on Equality
+Fields can be filtered using inequality when listing resources. Currently, this is supported only on
+the `created_at` field, using the `created_ats` filter.
 
-Fields can be filtered using equality when listing resources. Currently, only the `created_at` field
-is supported. The `created_at` field expects a timestamp filter, and timestamps must be in ISO 8601
-format, e.g. `2020-06-30T12:34:56Z`.
-
-##### Filtering on Inequality
-
-Fields can be filtered using inequality when listing resources. Currently, only the `created_at`
-field is supported.
-
-For example, a response to `/v3/audit_events?created_at[lt]=2020-06-30T12:34:56Z` will contain
+For example, a response to `/v3/audit_events?created_ats[lt]=2020-06-30T12:34:56Z` will contain
 audit events with a `created_at` timestamp strictly earlier than `2020-06-30T12:34:56Z`.
 
-Timestamps must be in ISO 8601 format.
+Timestamps must be in [standard timestamp format](#timestamps).
 
 ##### Valid inequality operators
 

docs/v3/source/includes/resources/audit_events/_list.md.erb

@@ -30,7 +30,7 @@ Retrieve all audit events the user has access to.
 
 Name | Type | Description
 ---- | ---- | ------------
-**created_at** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. Only supports relational operators, see [relational operators](#relational-operators-experimental)
+**created_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. Only supports relational operators, see [relational operators](#relational-operators-experimental)
 **types** | _list of strings_ | Comma-delimited list of event types to filter by
 **target_guids** | _list of strings_ | Comma-delimited list of target guids to filter by
 **space_guids** | _list of strings_ | Comma-delimited list of space guids to filter by

spec/request/events_spec.rb

@@ -169,7 +169,7 @@
         let!(:half_second_event) { VCAP::CloudController::Event.make(created_at: timestamp_half_second_later, organization_guid: org.guid, type: 'audit.organization.create') }
 
         it 'returns events earlier than the given timestamp' do
-          get "/v3/audit_events?created_at[lt]=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[lt]=#{timestamp}", nil, admin_header
 
           expect(
             resources: parsed_response['resources']
@@ -243,7 +243,7 @@
         end
 
         it 'returns events earlier than the given timestamp' do
-          get "/v3/audit_events?created_at[lte]=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[lte]=#{timestamp}", nil, admin_header
 
           expect(
             resources: parsed_response['resources']
@@ -286,7 +286,7 @@
         end
 
         it 'returns events at or after the given timestamp' do
-          get "/v3/audit_events?created_at[gte]=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[gte]=#{timestamp}", nil, admin_header
 
           expect(
             resources: parsed_response['resources']
@@ -298,7 +298,7 @@
 
       context 'using greater than' do
         it 'returns events after the given timestamp' do
-          get "/v3/audit_events?created_at[gt]=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[gt]=#{timestamp}", nil, admin_header
 
           expect(
             resources: parsed_response['resources']
@@ -341,7 +341,7 @@
         end
 
         it 'returns events at the given timestamp' do
-          get "/v3/audit_events?created_at=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats=#{timestamp}", nil, admin_header
 
           expect(
             resources: parsed_response['resources']
@@ -353,7 +353,7 @@
 
       context 'using an invalid operator' do
         it 'returns a useful error' do
-          get "/v3/audit_events?created_at[goat]=#{timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[goat]=#{timestamp}", nil, admin_header
 
           expect(last_response).to have_status_code(400)
           expect(last_response).to have_error_message("Invalid comparison operator: 'goat'")
@@ -363,22 +363,22 @@
       context 'using an invalid timestamp (with fractional seconds)' do
         let(:fractional_second_timestamp) { '2020-06-30T23:45:67.890Z' }
         it 'returns a useful error' do
-          get "/v3/audit_events?created_at[lt]=#{fractional_second_timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[lt]=#{fractional_second_timestamp}", nil, admin_header
 
           expect(last_response).to have_status_code(400)
           expect(last_response).to have_error_message(
-            "The query parameter is invalid: Created at has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
+            "The query parameter is invalid: Created ats has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
         end
       end
 
       context 'using an invalid timestamp (local time zone)' do
         let(:local_timezone_timestamp) { '2020-06-30T23:45:67-0700' }
         it 'returns a useful error' do
-          get "/v3/audit_events?created_at[lt]=#{local_timezone_timestamp}", nil, admin_header
+          get "/v3/audit_events?created_ats[lt]=#{local_timezone_timestamp}", nil, admin_header
 
           expect(last_response).to have_status_code(400)
           expect(last_response).to have_error_message(
-            "The query parameter is invalid: Created at has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
+            "The query parameter is invalid: Created ats has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
         end
       end
     end

spec/unit/fetchers/event_list_fetcher_spec.rb

@@ -76,7 +76,7 @@ module VCAP::CloudController
 
         context 'requesting events less than a timestamp' do
           let(:filters) do
-            { created_at: { lt: event_3.created_at.iso8601 } }
+            { created_ats: { lt: event_3.created_at.iso8601 } }
           end
 
           it 'returns events with a created_at timestamp less than the given timestamp' do
@@ -94,7 +94,7 @@ module VCAP::CloudController
 
         context 'requesting events less than or equal to a timestamp' do
           let(:filters) do
-            { created_at: { lte: event_3.created_at.iso8601 } }
+            { created_ats: { lte: event_3.created_at.iso8601 } }
           end
 
           it 'returns events with a created_at timestamp before or at a given timestamp' do
@@ -112,7 +112,7 @@ module VCAP::CloudController
 
         context 'requesting events greater than or equal to a timestamp' do
           let(:filters) do
-            { created_at: { gte: event_3.created_at.iso8601 } }
+            { created_ats: { gte: event_3.created_at.iso8601 } }
           end
 
           it 'returns events with a created_at timestamp at or after a given timestamp' do
@@ -130,7 +130,7 @@ module VCAP::CloudController
 
         context 'requesting events greater than a timestamp' do
           let(:filters) do
-            { created_at: { gt: event_3.created_at.iso8601 } }
+            { created_ats: { gt: event_3.created_at.iso8601 } }
           end
 
           it 'returns events with a created_at timestamp greater than the given timestamp' do
@@ -148,7 +148,7 @@ module VCAP::CloudController
 
         context 'requesting events equal to a timestamp' do
           let(:filters) do
-            { created_at: event_3.created_at.iso8601 }
+            { created_ats: event_3.created_at.iso8601 }
           end
 
           it 'returns events with a created_at timestamp at or after a given timestamp' do

spec/unit/messages/events_list_message_spec.rb

@@ -27,7 +27,7 @@ module VCAP::CloudController
           target_guids: ['guid1', 'guid2'],
           space_guids: ['guid3', 'guid4'],
           organization_guids: ['guid5', 'guid6'],
-          created_at: { lt: Time.now.utc.iso8601 },
+          created_ats: { lt: Time.now.utc.iso8601 },
         })
         expect(message).to be_valid
       end
@@ -64,65 +64,65 @@ module VCAP::CloudController
           expect(message.errors[:organization_guids]).to include('must be an array')
         end
 
-        context 'validates the created_at filter' do
+        context 'validates the created_ats filter' do
           it 'requires a hash or a timestamp' do
-            message = EventsListMessage.from_params({ created_at: [Time.now.utc.iso8601] })
+            message = EventsListMessage.from_params({ created_ats: [Time.now.utc.iso8601] })
             expect(message).not_to be_valid
-            expect(message.errors[:created_at]).to include('comparison operator and timestamp must be specified')
+            expect(message.errors[:created_ats]).to include('comparison operator and timestamp must be specified')
           end
 
           it 'requires a valid comparison operator' do
-            message = EventsListMessage.from_params({ created_at: { garbage: Time.now.utc.iso8601 } })
+            message = EventsListMessage.from_params({ created_ats: { garbage: Time.now.utc.iso8601 } })
             expect(message).not_to be_valid
-            expect(message.errors[:created_at]).to include("Invalid comparison operator: 'garbage'")
+            expect(message.errors[:created_ats]).to include("Invalid comparison operator: 'garbage'")
           end
 
           context 'requires a valid timestamp' do
             it "won't accept garbage" do
-              message = EventsListMessage.from_params({ created_at: { gt: 123 } })
+              message = EventsListMessage.from_params({ created_ats: { gt: 123 } })
               expect(message).not_to be_valid
-              expect(message.errors[:created_at]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
+              expect(message.errors[:created_ats]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
             end
             it "won't accept fractional seconds even though it's ISO 8601-compliant" do
-              message = EventsListMessage.from_params({ created_at: { gt: '2020-06-30T12:34:56.78Z' } })
+              message = EventsListMessage.from_params({ created_ats: { gt: '2020-06-30T12:34:56.78Z' } })
               expect(message).not_to be_valid
-              expect(message.errors[:created_at]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
+              expect(message.errors[:created_ats]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
             end
             it "won't accept local time zones even though it's ISO 8601-compliant" do
-              message = EventsListMessage.from_params({ created_at: { gt: '2020-06-30T12:34:56.78-0700' } })
+              message = EventsListMessage.from_params({ created_ats: { gt: '2020-06-30T12:34:56.78-0700' } })
               expect(message).not_to be_valid
-              expect(message.errors[:created_at]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
+              expect(message.errors[:created_ats]).to include("has an invalid timestamp format. Timestamps should be formatted as 'YYYY-MM-DDThh:mm:ssZ'")
             end
           end
 
           it 'allows the lt operator' do
-            message = EventsListMessage.from_params({ created_at: { lt: Time.now.utc.iso8601 } })
+            message = EventsListMessage.from_params({ created_ats: { lt: Time.now.utc.iso8601 } })
             expect(message).to be_valid
           end
 
           it 'allows the lte operator' do
-            message = EventsListMessage.from_params({ created_at: { lte: Time.now.utc.iso8601 } })
+            message = EventsListMessage.from_params({ created_ats: { lte: Time.now.utc.iso8601 } })
             expect(message).to be_valid
           end
 
           it 'allows the gt operator' do
-            message = EventsListMessage.from_params({ created_at: { gt: Time.now.utc.iso8601 } })
+            message = EventsListMessage.from_params({ created_ats: { gt: Time.now.utc.iso8601 } })
             expect(message).to be_valid
           end
 
           it 'allows the gte operator' do
-            message = EventsListMessage.from_params({ created_at: { gte: Time.now.utc.iso8601 } })
+            message = EventsListMessage.from_params({ created_ats: { gte: Time.now.utc.iso8601 } })
             expect(message).to be_valid
           end
 
           context 'when the operator is an equals operator' do
             it 'allows the equals operator' do
-              message = EventsListMessage.from_params({ created_at: Time.now.utc.iso8601 })
+              message = EventsListMessage.from_params({ created_ats: Time.now.utc.iso8601 })
               expect(message).to be_valid
             end
 
             it 'errors on invalid (non-ISO 8601) timestamps' do
-              message = EventsListMessage.from_params({ created_at: 'yesterday' })
+              message = EventsListMessage.from_params({ created_ats: 'yesterday' })
               expect(message).to be_invalid
             end
           end