jpie 4.1.1.pre.202609280317 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89f25c649293b22832412f92bcf29361b881deaf953d6b2db661736e226abd8d
-  data.tar.gz: 4256bc8778bf8968c852fb901f753fe433b3ed21776a02ea2445f86f179a05c2
+  metadata.gz: f0e43b1a16ff0ab1f8d1e2bed93eed667a7cdebbf83879dc7ba1da4cd4934eee
+  data.tar.gz: 3af66fff765a5f8b3efff0b4ca5866601c847e16c38492c08e6fd97b6eacbc95
 SHA512:
-  metadata.gz: 5384c6655800b556886f7ba54510c982fb2432fdcdde2439c1ce90f5d77bd10de6094973e0f6bed8c01f22a32c064de5c255b133c87c2395cbc4c12f9948e9b4
-  data.tar.gz: 9b72004eb39131a37d9e289e9c0103f88f17ebffd48df26a5ff0ee93337af855e7932c1965468a2d8ca0a4300180dba6e37897964cc124e26d2076cfe2aff536
+  metadata.gz: d6d1da393d39f54ca154910a34b622bef89e8cf08aac4918fd9f796aeb38ba3e84b76afbf30b987fb7e85f7f7dfa53f0685fec274ce0bc9224ec52a7e0d4e42e
+  data.tar.gz: df49c567f4c64d98895ec528370591ff67760de7396a01dd15678af7a63d527d11e9bd11033ee90f76392dc48044749c8d6ec7c3019618f08b8ccdb06776dbd8

data/CHANGELOG.md

@@ -7,8 +7,31 @@ at release time.
 
 ## [Unreleased]
 
+## [4.1.1] - 2026-10-10
+
 ### Fixed
 
+- **Resolve a nested filter hop in the request namespace.** Filter validation
+  and `CollectionQuery` resolved each hop of a path such as
+  `filter[comments.author.email_eq]` from the model name alone. A namespaced
+  request then judged the path against the flat resources. A public namespace
+  accepted every filter and relationship its flat counterparts declare, and
+  refused the filters its own resources declare. Each hop now resolves through
+  `ResourceLoader.find_for_model(model, namespace:)`, the lookup an `?include=`
+  hop takes. A hop the namespace cannot answer is a 400 "Invalid Filter". A
+  flat request takes the same lookup, so a hop to an STI subclass now reaches
+  its base class's resource. Regression spec:
+  `nested_filter_namespace_bypass_spec.rb`.
+
+- **Preload an `?include=` hop through the related resource's own scope.** The
+  tree preloaded through `acts_as_tenant` alone, so neither the related
+  resource's `records` scope nor the `authorization_scope` hook reached the
+  query, and `IncludeFilterCache` dropped the surplus rows afterwards. The gate
+  now sits in the query. A branch that narrows nowhere still reads in one call,
+  and every level it loads joins the set the branches after it match against, so
+  two include paths that converge on one association read it once. Specs:
+  `include_preload_applies_resource_scope_spec.rb` and
+  `include_converging_branches_spec.rb`.
 - **Vet a partial where hash in the database, not in memory.**
   `IncludeFilterCache#filter` matched sideloaded records against
   `where_values_hash`. That hash holds only the conditions ActiveRecord

data/README.md

@@ -930,7 +930,10 @@ model is flat.
 A namespace serves only what it declares. A namespaced request never resolves a
 flat resource: a route whose namespace carries no resource fails at draw time
 (the app does not boot), and an `?include=` hop the namespace cannot answer is
-a 400 at validation, before anything loads. For a namespaced model, both name
+a 400 at validation, before anything loads. A nested filter follows the same
+rule. Each hop of `filter[comments.body_match]` resolves the namespace's
+resource, and the filter passes only where that resource declares it. For a
+namespaced model, both name
 shapes answer — `Pub::ItemResource` and `Pub::DepotItemResource` for
 `Depot::Item` — so the class a `MissingResourceClass` message names is always
 a working declaration. To serve a flat resource inside a

data/lib/json_api/controllers/concerns/resource_actions/filter_validation.rb

@@ -45,12 +45,21 @@ module JSONAPI
 
       def check_related_filter(parts, assoc)
         rel_mod = assoc.klass
-        rel_res = JSONAPI::Resource.resource_for_model(rel_mod)
+        rel_res = filter_hop_resource(rel_mod)
         return false unless rel_res
 
         check_filter_parts(parts, rel_res, rel_mod)
       end
 
+      # The request namespace answers each hop, the lookup an include hop
+      # takes. A flat resource is another namespace's surface, with filters
+      # this one never declared.
+      def filter_hop_resource(model)
+        JSONAPI::ResourceLoader.find_for_model(model, namespace: jsonapi_namespace)
+      rescue JSONAPI::ResourceLoader::MissingResourceClass
+        nil
+      end
+
       def filter_rel_allowed?(res_cls, rel)
         permitted = res_cls.permitted_filters_through
         permitted.include?(rel.to_sym) || permitted.map(&:to_s).include?(rel.to_s)

data/lib/json_api/controllers/concerns/resource_actions/include_preloading.rb

@@ -4,6 +4,7 @@ module JSONAPI
   module ResourceActions
     module IncludePreloading
       extend ActiveSupport::Concern
+      include IncludeScopePreloading
 
       private
 
@@ -18,25 +19,6 @@ module JSONAPI
         end
       end
 
-      # Preloads associations from the include param so the serializer avoids N+1 queries
-      # when walking include paths (association.loaded? is true). Used by both show and index.
-      def scope_with_includes(scope)
-        includes = parse_include_param
-        return scope unless includes.any?
-        return scope if scope.is_a?(Array)
-
-        # `preload`, never `includes`. `includes` resolves to one LEFT OUTER JOIN
-        # across the whole tree whenever the scope already answers
-        # `eager_loading?` with true, which one condition on an unjoined table is
-        # enough to cause. Every collection path in the tree then multiplies row
-        # for row: a measured page of 25 records loaded 75,712 rows and allocated
-        # 800MB, against 18MB for the same document through `preload`.
-        # Serialization filters on none of the included tables, so the tree never
-        # needs the join. A scope's own `includes` is untouched and still supplies
-        # whatever join its own conditions need.
-        scope.preload(includes_to_hash(includes))
-      end
-
       def filter_includable(hash, klass)
         hash.each_with_object({}) do |(key, value), filtered|
           assoc = klass.reflect_on_association(key)
@@ -67,7 +49,7 @@ module JSONAPI
       #
       # The tree collapses shared prefixes, so a prefix is visited once however
       # many paths run through it. Walking costs no association queries — every
-      # hop reads targets that `scope_with_includes` already loaded. The only
+      # hop reads targets that `preload_include_tree` already loaded. The only
       # queries are the batched resource-default preloads themselves, each of
       # which replaces one query per record during serialization.
       def preload_included_resource_associations(resources, includes)

data/lib/json_api/controllers/concerns/resource_actions/include_scope_preloading.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module ResourceActions
+    # Reads an include tree one hop at a time, each hop through the scope its own
+    # resource answers with, so a record that resource hides never loads.
+    module IncludeScopePreloading
+      extend ActiveSupport::Concern
+
+      private
+
+      # Preloads the include tree so the serializer walks it without an N+1, one
+      # hop at a time, each hop through the scope its own resource answers with.
+      # Rails takes no per-association scope on a whole-tree preload, so a single
+      # call reads every row the foreign key matches and leaves the narrowing to
+      # the serializer. Reading through the scope puts that gate in the query,
+      # where the database applies it once.
+      #
+      # `preload`, never `includes`. `includes` resolves to one LEFT OUTER JOIN
+      # across the whole tree whenever the scope already answers
+      # `eager_loading?` with true, which one condition on an unjoined table is
+      # enough to cause. Every collection path in the tree then multiplies row
+      # for row: a measured page of 25 records loaded 75,712 rows and allocated
+      # 800MB, against 18MB for the same document through `preload`. A scope's
+      # own `includes` is untouched and still supplies whatever join its own
+      # conditions need. Each hop being its own query is also what lets a hop
+      # narrow without dropping a parent.
+      def preload_include_tree(records, includes)
+        return if records.empty? || includes.empty?
+
+        tree = includes_to_hash(includes)
+        # Nothing in this tree narrows, so nothing needs its own read. One call
+        # reads the whole tree, which is what Rails batches best: it gathers the
+        # owners of a level across every branch and reads each association once.
+        # The hop walk cannot, because it holds one branch at a time, and two
+        # paths that converge on one association then read it twice.
+        return preload_association(records, tree, nil) unless tree_narrows?(model_class, tree)
+
+        preload_include_level(records, model_class, tree)
+      end
+
+      # True when any class the tree reaches answers with a scope that selects
+      # fewer rows than the association would. Costs no query: each answer is the
+      # entry the filter cache already builds per class.
+      def tree_narrows?(klass, tree)
+        tree.any? do |association_name, subtree|
+          reflection = klass.reflect_on_association(association_name)
+          next false unless reflection
+          next false if attachment_hop?(reflection)
+
+          hop_reads_through_scope?(reflection, subtree)
+        end
+      end
+
+      # This hop needs its own read when its own class narrows, or when something
+      # under it does and the walk has to reach that far to find it.
+      #
+      # A polymorphic hop names no class until its rows load, so no scope can
+      # reach its read. The serializer vets those rows, as it always has.
+      def hop_reads_through_scope?(reflection, subtree)
+        return false if reflection.polymorphic?
+        return true if include_scope_for(reflection.klass)
+
+        tree_narrows?(reflection.klass, subtree)
+      end
+
+      def preload_include_level(records, klass, tree)
+        tree.each do |association_name, subtree|
+          reflection = klass.reflect_on_association(association_name)
+          next unless reflection
+
+          preload_include_hop(records, association_name, subtree, reflection)
+        end
+      end
+
+      # A branch that narrows nowhere reads whole, for the same reason the whole
+      # tree does when nothing in it narrows: one call batches the level and two
+      # paths that converge on one association read it once.
+      def preload_include_hop(records, association_name, subtree, reflection)
+        if attachment_hop?(reflection) || !hop_reads_through_scope?(reflection, subtree)
+          preload_association(records, { association_name => subtree }, nil)
+          return record_loaded_subtree(records, association_name, subtree)
+        end
+
+        preload_scoped_hop(records, association_name, reflection)
+        targets = collect_include_targets(records, association_name)
+        return if targets.empty?
+
+        loaded_include_records.concat(targets)
+        descend_include_level(targets, reflection, subtree) unless subtree.empty?
+      end
+
+      # One call read every level of this branch, so every level joins the set the
+      # branches after it match against. Recording the first hop alone left the
+      # levels below it out, and a branch that converged there read them again.
+      def record_loaded_subtree(records, association_name, subtree)
+        targets = collect_include_targets(records, association_name)
+        return if targets.empty?
+
+        loaded_include_records.concat(targets)
+        return if subtree.empty?
+
+        targets.group_by(&:class).each do |target_class, group|
+          subtree.each do |child_name, child_subtree|
+            next unless target_class.reflect_on_association(child_name)
+
+            record_loaded_subtree(group, child_name, child_subtree)
+          end
+        end
+      end
+
+      # A polymorphic hop has no single target class, so continue once per class
+      # actually present in the loaded targets.
+      def descend_include_level(targets, reflection, subtree)
+        if reflection.polymorphic?
+          targets.group_by(&:class).each { |target_class, recs| preload_include_level(recs, target_class, subtree) }
+        else
+          preload_include_level(targets, reflection.klass, subtree)
+        end
+      end
+
+      def preload_scoped_hop(records, association_name, reflection)
+        return preload_polymorphic_hop(records, association_name, reflection) if reflection.polymorphic?
+
+        preload_association(records, association_name, include_scope_for(reflection.klass))
+      end
+
+      # One Preloader call carries one scope, and a polymorphic hop spans
+      # classes, so group the parents by the type they name and read each group
+      # through that class's own scope.
+      def preload_polymorphic_hop(records, association_name, reflection)
+        groups = records.group_by { |record| record.read_attribute(reflection.foreign_type) }
+        groups.each do |type_name, group|
+          next if type_name.blank?
+
+          preload_association(group, association_name, include_scope_for(type_name.constantize))
+        end
+      end
+
+      def preload_association(records, associations, scope)
+        ActiveRecord::Associations::Preloader.new(
+          records:, associations:, scope:, available_records: loaded_include_records,
+        ).call
+      end
+
+      # Two include paths can converge on one association: `findings.samples.files`
+      # and `samples_direct.files` read the same files. Walking hop by hop, the
+      # second branch would read them again, because it holds its own instances of
+      # the rows the first branch already loaded. One whole-tree preload never did:
+      # it matched the rows it had. Hand the same set over and each row is read
+      # once, whichever branch reaches it first.
+      def loaded_include_records
+        @loaded_include_records ||= []
+      end
+
+      # `filter_includable` rewrites an attachment include into the pair
+      # ActiveStorage defines for it. Those rows are jpie's own and answer to no
+      # resource, so the pair preloads whole and unscoped, the way the whole tree
+      # once did.
+      def attachment_hop?(reflection)
+        !reflection.polymorphic? && reflection.klass.name.start_with?("ActiveStorage::")
+      end
+
+      # The resource's own scope, narrowed by the authorization hook. It comes
+      # from the request's filter cache, so the hook resolves once per class for
+      # the read and the vetting together.
+      def include_scope_for(klass)
+        include_filter_cache.authorized_scope_for(klass)
+      end
+
+      # One cache per request. The preloader reads each class's scope from it
+      # before the read, and the serializers read their verdicts from it after,
+      # so the authorization hook runs once for each included type.
+      def include_filter_cache
+        @include_filter_cache ||= JSONAPI::Serialization::IncludeFilterCache.new(
+          authorization_context: self, namespace: jsonapi_namespace,
+        )
+      end
+    end
+  end
+end

data/lib/json_api/controllers/concerns/resource_actions/resource_loading.rb

@@ -37,8 +37,8 @@ module JSONAPI
         return unless params[:id] && @resource_class
 
         authorized = apply_authorization_scope(@resource_class.records, action: action_name.to_sym)
-        scope = scope_with_includes(authorized)
-        @resource = scope.find(params[:id])
+        @resource = authorized.find(params[:id])
+        preload_include_tree([@resource], parse_include_param)
       end
 
       def render_record_not_found

data/lib/json_api/controllers/concerns/resource_actions/serialization.rb

@@ -9,7 +9,7 @@ module JSONAPI
       def serialize_resource(resource)
         includes = parse_include_param
         # On show and update the record arrives through `load_resource_record`, which loaded
-        # the include tree via `scope_with_includes`. Each included resource's own `records`
+        # the include tree via `preload_include_tree`. Each included resource's own `records`
         # preloads still have to be applied, or every included record pays them one query at
         # a time. On create the tree is unloaded, so this finds no targets and does nothing.
         preload_included_resource_associations([resource], includes)
@@ -22,9 +22,9 @@ module JSONAPI
       def serialize_collection(resources)
         includes = parse_include_param
         fields = parse_fields_param
-        resources = scope_with_includes(resources)
         resources_array = resources.to_a
 
+        preload_include_tree(resources_array, includes)
         preload_included_resource_associations(resources_array, includes)
 
         data, all_included = serialize_resources_with_includes(resources_array, includes, fields)
@@ -60,8 +60,7 @@ module JSONAPI
       # every included record gets its scope verdict in one query per class,
       # and the serializers answer their per-visit checks from memory.
       def build_include_filter_cache(resources, includes)
-        cache = JSONAPI::Serialization::IncludeFilterCache.new(authorization_context: self,
-                                                               namespace: jsonapi_namespace,)
+        cache = include_filter_cache
         includes.each do |path|
           current = resources
           path.split(".").each do |part|

data/lib/json_api/controllers/concerns/resource_actions.rb

@@ -3,6 +3,7 @@
 require_relative "resource_actions/filter_validation"
 require_relative "resource_actions/field_validation"
 require_relative "resource_actions/include_validation"
+require_relative "resource_actions/include_scope_preloading"
 require_relative "resource_actions/include_preloading"
 require_relative "resource_actions/serialization"
 require_relative "resource_actions/pagination"
@@ -104,6 +105,7 @@ module JSONAPI
         scope,
         definition: @resource_class,
         model_class: model_class,
+        namespace: jsonapi_namespace,
         filter_params: parse_filter_param,
         sort_params: parse_sort_param,
         page_params: parse_page_param,

data/lib/json_api/serialization/include_filter_cache.rb

@@ -36,6 +36,22 @@ module JSONAPI
         records.select { |record| matches_where_hash?(record, entry.where_hash) }
       end
 
+      # The scope an include hop reads through, and nil when that scope narrows
+      # nothing. The preloader reads it from here so the hook resolves once per
+      # class per request, for the read and the vetting together.
+      #
+      # nil is what tells the walk that a hop needs no read of its own. A class
+      # whose resource adds no condition asks for every row the foreign key
+      # matches, which is what a plain preload already reads. The branch that hop
+      # sits on can then read in one call and keep the batching a whole-tree
+      # preload gives, instead of walking a level at a time for no gain.
+      def authorized_scope_for(klass)
+        entry = entry_for(klass)
+        return nil unless entry.narrowed || !entry.where_clause_empty
+
+        entry.authorized_scope
+      end
+
       # Vets ids ahead of the walk, one query per class, so the per-visit
       # checks answer from memory. Safe to skip: #filter queries lazily.
       def warm(klass, ids)

data/lib/json_api/support/collection_query.rb

@@ -17,10 +17,11 @@ module JSONAPI
 
     attr_reader :scope, :total_count, :pagination_applied
 
-    def initialize(scope, definition:, model_class:, filter_params:, sort_params:, page_params:)
+    def initialize(scope, definition:, model_class:, filter_params:, sort_params:, page_params:, namespace: nil)
       @scope = scope
       @definition = definition
       @model_class = model_class
+      @namespace = namespace
       @filter_params = filter_params
       @sort_params = sort_params
       @page_params = page_params
@@ -38,7 +39,7 @@ module JSONAPI
 
     private
 
-    attr_reader :definition, :model_class, :filter_params, :sort_params, :page_params
+    attr_reader :definition, :model_class, :namespace, :filter_params, :sort_params, :page_params
 
     def compute_total_count_if_needed
       return unless pagination_applied

data/lib/json_api/support/concerns/nested_filters.rb

@@ -54,12 +54,20 @@ module JSONAPI
                    early_return: true, }
         end
 
-        next_definition = JSONAPI::Resource.resource_for_model(association.klass)
+        next_definition = hop_definition(association.klass)
         return { scope:, early_return: true } unless next_definition
 
         { model: association.klass, definition: next_definition, early_return: false }
       end
 
+      # The query's namespace answers each hop, as it does in filter
+      # validation. A hop it carries no resource for filters nothing.
+      def hop_definition(model)
+        JSONAPI::ResourceLoader.find_for_model(model, namespace:)
+      rescue JSONAPI::ResourceLoader::MissingResourceClass
+        nil
+      end
+
       def apply_joined_filter(scope, result, relationship_chain:, leaf_filter:, filter_value:)
         join_hash = build_join_hash_for_chain(relationship_chain)
         scope = scope.joins(join_hash) if join_hash.present?

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "4.1.1.pre.202609280317"
+  VERSION = "4.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 4.1.1.pre.202609280317
+  version: 4.1.1
 platform: ruby
 authors:
 - Emil Kampp
@@ -120,6 +120,7 @@ files:
 - lib/json_api/controllers/concerns/resource_actions/field_validation.rb
 - lib/json_api/controllers/concerns/resource_actions/filter_validation.rb
 - lib/json_api/controllers/concerns/resource_actions/include_preloading.rb
+- lib/json_api/controllers/concerns/resource_actions/include_scope_preloading.rb
 - lib/json_api/controllers/concerns/resource_actions/include_validation.rb
 - lib/json_api/controllers/concerns/resource_actions/pagination.rb
 - lib/json_api/controllers/concerns/resource_actions/resource_loading.rb