Add specialized records methods, find_to_populate_by_keys

Specialized records methods allow the system to avoid duplicating
expensive permission checks for records that have already been found.
This is needed because of the new multiphase approach building up the
result set.

Closes gh-1228

Author: lgebhardt

lib/jsonapi/active_relation_resource_finder.rb

@@ -70,6 +70,16 @@ def find_by_keys(keys, options = {})
         resources_for(records, options[:context])
       end
 
+      # Returns an array of Resources identified by the `keys` array. The resources are not filtered as this
+      # will have been done in a prior step
+      #
+      # @param keys [Array<key>] Array of primary keys to find resources for
+      # @option options [Hash] :context The context of the request, set in the controller
+      def find_to_populate_by_keys(keys, options = {})
+        records = records_for_populate(options).where(_primary_key => keys)
+        resources_for(records, options[:context])
+      end
+
       # Finds Resource fragments using the `filters`. Pagination and sort options are used when provided.
       # Retrieving the ResourceIdentities and attributes does not instantiate a model instance.
       # Note: This is incompatible with Polymorphic resources (which are going to come from two separate tables)
@@ -242,10 +252,57 @@ def count_related(source_rid, relationship_name, options = {})
         count_records(records)
       end
 
-      def records(_options = {})
+      # This resource finder (ActiveRecordResourceFinder) uses an `ActiveRecord::Relation` as the starting point for
+      # retrieving models. From this relation filters, sorts and joins are applied as needed.
+      # Depending on which phase of the request processing different `records` methods will be called, giving the user
+      # the opportunity to override them differently for performance and security reasons.
+
+      # begin `records`methods
+
+      # Base for the `records` methods that follow and is not directly used for accessing model data by this class.
+      # Overriding this method gives a single place to affect the `ActiveRecord::Relation` used for the resource.
+      #
+      # @option options [Hash] :context The context of the request, set in the controller
+      #
+      # @return [ActiveRecord::Relation]
+      def records_base(_options = {})
         _model_class.all
       end
 
+      # The `ActiveRecord::Relation` used for finding user requested models. This may be overridden to enforce
+      # permissions checks on the request.
+      #
+      # @option options [Hash] :context The context of the request, set in the controller
+      #
+      # @return [ActiveRecord::Relation]
+      def records(options = {})
+        records_base(options)
+      end
+
+      # The `ActiveRecord::Relation` used for populating the ResourceSet. Only resources that have been previously
+      # identified through the `records` method will be accessed. Thus it should not be necessary to reapply permissions
+      # checks. However if the model needs to include other models adding `includes` is appropriate
+      #
+      # @option options [Hash] :context The context of the request, set in the controller
+      #
+      # @return [ActiveRecord::Relation]
+      def records_for_populate(options = {})
+        records_base(options)
+      end
+
+      # The `ActiveRecord::Relation` used for the finding related resources. Only resources that have been previously
+      # identified through the `records` method will be accessed and used as the basis to find related resources. Thus
+      # it should not be necessary to reapply permissions checks.
+      #
+      # @option options [Hash] :context The context of the request, set in the controller
+      #
+      # @return [ActiveRecord::Relation]
+      def records_for_source_to_related(options = {})
+        records_base(options)
+      end
+
+      # end `records` methods
+
       def apply_join(records:, relationship:, resource_type:, join_type:, options:)
         if relationship.polymorphic? && relationship.belongs_to?
           case join_type
@@ -267,7 +324,7 @@ def apply_join(records:, relationship:, resource_type:, join_type:, options:)
       end
 
       def relationship_records(relationship:, join_type: :inner, resource_type: nil, options: {})
-        records = relationship.parent_resource.records(options)
+        records = relationship.parent_resource.records_for_source_to_related(options)
         strategy = relationship.options[:apply_join]
 
         if strategy
@@ -336,7 +393,7 @@ def find_related_monomorphic_fragments(source_rids, relationship, options, conne
 
         paginator = options[:paginator] if source_rids.count == 1
 
-        records = apply_request_settings_to_records(records: records(options),
+        records = apply_request_settings_to_records(records: records_for_source_to_related(options),
                                resource_klass: resource_klass,
                                sort_criteria: sort_criteria,
                                primary_keys: source_ids,
@@ -463,7 +520,7 @@ def find_related_polymorphic_fragments(source_rids, relationship, options, conne
 
         # Note: We will sort by the source table. Without using unions we can't sort on a polymorphic relationship
         # in any manner that makes sense
-        records = apply_request_settings_to_records(records: records(options),
+        records = apply_request_settings_to_records(records: records_for_source_to_related(options),
                                resource_klass: resource_klass,
                                sort_primary: true,
                                primary_keys: source_ids,

lib/jsonapi/resource_set.rb

@@ -91,7 +91,7 @@ def populate!(serializer, context, find_options)
       # Step Four find any of the missing resources and join them into the result
       missed_resource_ids.each_pair do |resource_klass, ids|
         find_opts = {context: context, fields: find_options[:fields]}
-        found_resources = resource_klass.find_by_keys(ids, find_opts)
+        found_resources = resource_klass.find_to_populate_by_keys(ids, find_opts)
 
         found_resources.each do |resource|
           relationship_data = @resource_klasses[resource_klass][resource.id][:relationships]

test/fixtures/active_record.rb

@@ -1527,6 +1527,10 @@ def find_by_key(key, options = {})
       resource_for(record, options[:context])
     end
 
+    def find_to_populate_by_keys(keys, options = {})
+      find_by_keys(keys, options)
+    end
+
     def find_by_keys(keys, options = {})
       records = find_breeds_by_keys(keys, options)
       resources_for(records, options[:context])