v3: Support advanced filters on stacks, tasks, space quotas

Now, the list endpoints for these resources support filtering on
`created_ats` and `updated_ats`, including relational operators on these
filters.

[#173719526]

Authored-by: Reid Mitchell <rmitchell@pivotal.io>

Author: reidmit

app/controllers/v3/stacks_controller.rb

@@ -13,7 +13,7 @@ def index
     message = StacksListMessage.from_params(query_params)
     invalid_param!(message.errors.full_messages) unless message.valid?
 
-    dataset = StackListFetcher.new.fetch_all(message)
+    dataset = StackListFetcher.fetch_all(message)
 
     render status: :ok, json: Presenters::V3::PaginatedListPresenter.new(
       presenter: Presenters::V3::StackPresenter,

app/controllers/v3/tasks_controller.rb

@@ -21,14 +21,14 @@ def index
     show_secrets = false
 
     if app_nested?
-      app, dataset = TaskListFetcher.new.fetch_for_app(message: message)
+      app, dataset = TaskListFetcher.fetch_for_app(message: message)
       app_not_found! unless app && permission_queryer.can_read_from_space?(app.space.guid, app.organization.guid)
       show_secrets = can_read_secrets?(app.organization, app.space)
     else
       dataset = if permission_queryer.can_read_globally?
-                  TaskListFetcher.new.fetch_all(message: message)
+                  TaskListFetcher.fetch_all(message: message)
                 else
-                  TaskListFetcher.new.fetch_for_spaces(message: message, space_guids: readable_space_guids)
+                  TaskListFetcher.fetch_for_spaces(message: message, space_guids: readable_space_guids)
                 end
     end
 

app/fetchers/space_quota_list_fetcher.rb

@@ -1,8 +1,9 @@
 require 'cloud_controller/paging/sequel_paginator'
 require 'cloud_controller/paging/paginated_result'
+require 'fetchers/base_list_fetcher'
 
 module VCAP::CloudController
-  class SpaceQuotaListFetcher
+  class SpaceQuotaListFetcher < BaseListFetcher
     class << self
       def fetch(message:, readable_space_quota_guids:)
         dataset = SpaceQuotaDefinition.dataset
@@ -34,7 +35,7 @@ def filter(message, dataset, readable_space_quota_guids)
                     qualify(:space_quota_definitions)
         end
 
-        dataset
+        super(message, dataset, SpaceQuotaDefinition)
       end
     end
   end

app/fetchers/stack_list_fetcher.rb

@@ -1,27 +1,31 @@
 require 'cloud_controller/paging/sequel_paginator'
 require 'cloud_controller/paging/paginated_result'
+require 'fetchers/base_list_fetcher'
 
 module VCAP::CloudController
-  class StackListFetcher
-    def fetch_all(message)
-      dataset = Stack.dataset
-      filter(message, dataset)
-    end
-
-    def filter(message, dataset)
-      if message.requested?(:names)
-        dataset = dataset.where(name: message.names)
+  class StackListFetcher < BaseListFetcher
+    class << self
+      def fetch_all(message)
+        dataset = Stack.dataset
+        filter(message, dataset)
       end
 
-      if message.requested?(:label_selector)
-        dataset = LabelSelectorQueryGenerator.add_selector_queries(
-          label_klass: StackLabelModel,
-          resource_dataset: dataset,
-          requirements: message.requirements,
-          resource_klass: Stack,
-        )
+      def filter(message, dataset)
+        if message.requested?(:names)
+          dataset = dataset.where(name: message.names)
+        end
+
+        if message.requested?(:label_selector)
+          dataset = LabelSelectorQueryGenerator.add_selector_queries(
+            label_klass: StackLabelModel,
+            resource_dataset: dataset,
+            requirements: message.requirements,
+            resource_klass: Stack,
+          )
+        end
+
+        super(message, dataset, Stack)
       end
-      dataset
     end
   end
 end

app/fetchers/task_list_fetcher.rb

@@ -1,74 +1,80 @@
+require 'fetchers/base_list_fetcher'
+
 module VCAP::CloudController
-  class TaskListFetcher
-    def fetch_for_spaces(message:, space_guids:)
-      app_dataset = AppModel.select(:id).where(space_guid: space_guids)
-      filter(message, app_dataset)
-    end
+  class TaskListFetcher < BaseListFetcher
+    class << self
+      def fetch_for_spaces(message:, space_guids:)
+        app_dataset = AppModel.select(:id).where(space_guid: space_guids)
+        filter(message).where(app: filter_app_dataset(message, app_dataset))
+      end
 
-    def fetch_all(message:)
-      app_dataset = AppModel.select(:id)
-      filter(message, app_dataset)
-    end
+      def fetch_all(message:)
+        app_dataset = AppModel.select(:id)
+        filter(message).where(app: filter_app_dataset(message, app_dataset))
+      end
 
-    def fetch_for_app(message:)
-      app_dataset = AppModel.where(guid: message.app_guid).eager(:space, space: :organization)
-      app = app_dataset.first
-      return nil unless app
+      def fetch_for_app(message:)
+        app_dataset = AppModel.where(guid: message.app_guid).eager(:space, space: :organization)
+        app = app_dataset.first
+        return nil unless app
 
-      if message.requested?(:organization_guids) || message.requested?(:space_guids) || message.requested?(:app_guids)
-        [app, filter(message, app_dataset)]
-      else
-        [app, filter_task_dataset(message, TaskModel.dataset).where(app_guid: message.app_guid).qualify]
+        if message.requested?(:organization_guids) || message.requested?(:space_guids) || message.requested?(:app_guids)
+          [app, filter(message).where(app: filter_app_dataset(message, app_dataset))]
+        else
+          [app, filter_task_dataset(message, TaskModel.dataset).where(app_guid: message.app_guid).qualify]
+        end
       end
-    end
 
-    private
+      private
 
-    def filter(message, app_dataset)
-      task_dataset = TaskModel.dataset
-      filter_task_dataset(message, task_dataset).where(app: filter_app_dataset(message, app_dataset))
-    end
+      def filter(message)
+        task_dataset = TaskModel.dataset
+        task_dataset = filter_task_dataset(message, task_dataset)
 
-    def filter_app_dataset(message, app_dataset)
-      if message.requested?(:space_guids)
-        app_dataset = app_dataset.where(space_guid: message.space_guids)
-      end
-      if message.requested?(:organization_guids)
-        app_dataset = app_dataset.where(space_guid: Organization.where(guid: message.organization_guids).map(&:spaces).flatten.map(&:guid))
+        super(message, task_dataset, TaskModel)
       end
-      if message.requested?(:app_guids)
-        app_dataset = app_dataset.where(guid: message.app_guids)
-      end
-      app_dataset
-    end
 
-    def filter_task_dataset(message, task_dataset)
-      if message.requested?(:names)
-        task_dataset = task_dataset.where(name: message.names)
+      def filter_app_dataset(message, app_dataset)
+        if message.requested?(:space_guids)
+          app_dataset = app_dataset.where(space_guid: message.space_guids)
+        end
+        if message.requested?(:organization_guids)
+          app_dataset = app_dataset.where(space_guid: Organization.where(guid: message.organization_guids).map(&:spaces).flatten.map(&:guid))
+        end
+        if message.requested?(:app_guids)
+          app_dataset = app_dataset.where(guid: message.app_guids)
+        end
+        app_dataset
       end
 
-      if message.requested?(:states)
-        task_dataset = task_dataset.where(state: message.states)
-      end
+      def filter_task_dataset(message, task_dataset)
+        if message.requested?(:names)
+          task_dataset = task_dataset.where(name: message.names)
+        end
 
-      if message.requested?(:guids)
-        task_dataset = task_dataset.where(guid: message.guids)
-      end
+        if message.requested?(:states)
+          task_dataset = task_dataset.where(state: message.states)
+        end
 
-      if message.requested?(:sequence_ids)
-        task_dataset = task_dataset.where(sequence_id: message.sequence_ids)
-      end
+        if message.requested?(:guids)
+          task_dataset = task_dataset.where(guid: message.guids)
+        end
 
-      if message.requested?(:label_selector)
-        task_dataset = LabelSelectorQueryGenerator.add_selector_queries(
-          label_klass: TaskLabelModel,
-          resource_dataset: task_dataset,
-          requirements: message.requirements,
-          resource_klass: TaskModel
-        )
-      end
+        if message.requested?(:sequence_ids)
+          task_dataset = task_dataset.where(sequence_id: message.sequence_ids)
+        end
 
-      task_dataset
+        if message.requested?(:label_selector)
+          task_dataset = LabelSelectorQueryGenerator.add_selector_queries(
+            label_klass: TaskLabelModel,
+            resource_dataset: task_dataset,
+            requirements: message.requirements,
+            resource_klass: TaskModel
+          )
+        end
+
+        task_dataset
+      end
     end
   end
 end

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

@@ -48,7 +48,7 @@ This will return all routes with hostname `"hostname1"`, `""` OR `"hostname2"`.
 
 #### Relational Operators (Experimental)
 
-Fields can be filtered using relational operators when listing resources.
+Some fields (e.g. `created_at` and `updated_at`) can be filtered using relational operators when listing resources.
 
 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`.
@@ -67,9 +67,3 @@ Timestamps must be in [standard timestamp format](#timestamps).
 **lte**      | Return resources less than or equal to the given value for the filtered attribute
 **gt**       | Return resources strictly greater than the given value for the filtered attribute
 **gte**      | Return resources greater than or equal to the given value for the filtered attribute
-
-##### Resources with relational operators
-
-The following resources can filter using relational operators:
-
-- **[audit_events](#list-audit-events)**

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

@@ -37,6 +37,8 @@ Name | Type | Description
 **page** | _integer_ | Page to display; valid values are integers >= 1
 **per_page** | _integer_ | Number of results per page; <br>valid values are 1 through 5000
 **order_by** | _string_ | Value to sort by. Defaults to ascending; prepend with `-` to sort descending. <br>Valid values are `created_at`, `updated_at`
+**created_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
+**updated_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
 
 #### Permitted roles
 

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

@@ -35,6 +35,8 @@ Name | Type | Description
 **per_page** | _integer_ | Number of results per page; <br>valid values are 1 through 5000
 **order_by** | _string_ | Value to sort by. Defaults to ascending; prepend with `-` to sort descending<br>Valid values are `created_at`, `updated_at`, and `name`
 **label_selector** (*experimental*)| _string_ | A query string containing a list of [label selector](#labels-and-selectors) requirements
+**created_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
+**updated_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
 
 #### Permitted roles
  |

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

@@ -40,6 +40,8 @@ Name | Type | Description
 **per_page** | _integer_ | Number of results per page; <br>valid values are 1 through 5000
 **order_by** | _string_ | Value to sort by. Defaults to ascending; prepend with `-` to sort descending. <br>Valid values are `created_at`, `updated_at`
 **label_selector** (*experimental*)| _string_ | A query string containing a list of [label selector](#labels-and-selectors) requirements
+**created_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
+**updated_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
 
 #### Permitted roles
  |

docs/v3/source/includes/resources/tasks/_list_for_app.md.erb

@@ -39,6 +39,8 @@ Name | Type | Description
 **per_page** | _integer_ | Number of results per page; <br>valid values are 1 through 5000
 **order_by** | _string_ | Value to sort by. Defaults to ascending; prepend with `-` to sort descending. <br>Valid values are `created_at`, `updated_at`
 **label_selector** (*experimental*)| _string_ | A query string containing a list of [label selector](#labels-and-selectors) requirements
+**created_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
+**updated_ats** (*experimental*)| _[timestamp](#timestamps)_ | Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators-experimental)
 
 #### Permitted roles
  |