jpie 4.1.1.pre.202609300315 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdb7cd53b04d123a7fbcefd2e1cde0809eaa0289dfe1731cf283302db3ad260f
-  data.tar.gz: 8685564a715a8cb677b73a4d55b3762d94fadccbac03adbd28d9166943c98df2
+  metadata.gz: 7cb5c150e4da0f0608aa5b97534e2239b8b80900054c984ca2aed3c24e747198
+  data.tar.gz: 83558900f75be4e9a4b8ea5997f7551963ee1406359b9fd30903d39fe9ad78bb
 SHA512:
-  metadata.gz: 9c47e7c40d0ddcfecb1c8ed69ab089e16445e87a5a2a1c838d9ad041a9f21067ddbfd1bb55ca382ff1e933b03e325f66cc07a3e3d69cec191caca058324d77ea
-  data.tar.gz: 8ab015ac55076351ac1a02510a6f3c9ad60ed9fd48de5f7261c2f3280ef97218ff9a872a1662d2d4fae542f7dc1d174c88be0bb2dde1d4604b6e032a66f468c7
+  metadata.gz: 1fdbf06edc4419def82b3719d3cd419e84bc76f3ebb9af0e64650c8eea9856d0d0a20c688a8c291c491fddaed0f28a417b506391dc63e3987ab8594a34126f4f
+  data.tar.gz: cfa30d1e5be610419135bcd16b13752a9eab3792c8082fe95d4a8cc6272103c6ea62c6315bdfc3e46b68b2d7ffe8467b1231e37980e8872b0f3f3781ba71b3d0

data/CHANGELOG.md

@@ -7,8 +7,50 @@ at release time.
 
 ## [Unreleased]
 
+## [4.1.2] - 2026-10-10
+
 ### Fixed
 
+- **Check each filter in the query, not only in the controller.**
+  `CollectionQuery` applied each filter name it received. Only
+  `validate_filter_param`, a controller `before_action`, refused a filter no
+  resource declares. A caller that built the query without that validation
+  reached the public class methods of a model through `public_send`. A spec
+  shows `where` take a raw SQL string that way. The query now takes the walk
+  filter validation takes, in the new `JSONAPI::Support::FilterPath`. A
+  resource declares each hop in `permitted_filters_through`, and the last
+  resource declares the leaf in `permitted_filters`. The query ignores a filter
+  that fails the walk: it adds no join, no condition and no model call. A
+  request that passes filter validation gets the same rows as before. Specs:
+  `collection_query_spec.rb`.
+- **End the order of every paged read with the primary key.** A paged
+  collection read carried no `ORDER BY` unless the request named a sort, and a
+  sort carried no tie-break. A database promises no order beyond the one it is
+  given, so a write between two page reads moved a row to another page: the
+  walk returned one row twice and never returned another. `Support::Sort` now
+  appends the model's primary key to the order of a paged read, and the
+  in-memory sort for virtual fields keeps the database order for rows that tie.
+  A read with no `page` parameter is unchanged. A paged scope must keep the
+  primary key in its select list: PostgreSQL refuses the order on a scope that
+  selects `DISTINCT` columns without the key, or groups by another column.
+  Regression spec: `paged_read_unstable_order_spec.rb`.
+
+## [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

data/README.md

@@ -256,6 +256,10 @@ Paginated responses include a `links` object with `self`, `first`, `last`, and c
 
 Default page size is 25, maximum is 100 (configurable).
 
+A paged read always has one total order. JPie ends the `ORDER BY` of every paged query with the model's primary key: an unsorted page orders by the key, and a sorted page uses the key for rows that tie on the sort. A client that reads page after page then gets each row once, even when a row changes between two reads. A read with no `page` parameter gets no order of its own.
+
+The key cannot help when a row is created or deleted between two page reads. Every later offset then moves by one row.
+
 ## Includes
 
 Include related resources with the `include` parameter:
@@ -930,7 +934,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

@@ -4,65 +4,20 @@ module JSONAPI
   module ResourceActions
     module FilterValidation
       extend ActiveSupport::Concern
-      include JSONAPI::Support::FilterParsing
 
       def validate_filter_param
         filters = parse_filter_param
         return if filters.empty?
 
-        invalid = filters.keys.reject { |n| filter_path_valid?(n.to_s) }
+        path = JSONAPI::Support::FilterPath.new(
+          definition: @resource_class, model_class:, namespace: jsonapi_namespace,
+        )
+        invalid = filters.keys.reject { |name| path.declared?(name) }
         render_filter_errors(invalid) if invalid.any?
       end
 
       private
 
-      def filter_path_valid?(name)
-        parts = name.split(".")
-        check_filter_parts(parts, @resource_class, model_class)
-      end
-
-      def check_filter_parts(parts, res_cls, mod_cls)
-        return false if parts.empty?
-        return single_filter_valid?(parts.first, res_cls) if parts.length == 1
-
-        check_nested_filter(parts, res_cls, mod_cls)
-      end
-
-      def single_filter_valid?(name, res_cls)
-        res_cls.permitted_filters.map(&:to_s).include?(name)
-      end
-
-      def check_nested_filter(parts, res_cls, mod_cls)
-        rel, *rest = parts
-        return false unless filter_rel_allowed?(res_cls, rel)
-
-        assoc = mod_cls.reflect_on_association(rel.to_sym)
-        return false unless assoc
-        return polymorphic_filter_valid?(rest) if assoc.polymorphic?
-
-        check_related_filter(rest, assoc)
-      end
-
-      def check_related_filter(parts, assoc)
-        rel_mod = assoc.klass
-        rel_res = JSONAPI::Resource.resource_for_model(rel_mod)
-        return false unless rel_res
-
-        check_filter_parts(parts, rel_res, rel_mod)
-      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)
-      end
-
-      def polymorphic_filter_valid?(parts)
-        return false if parts.empty? || parts.length > 1
-
-        col_filter = parse_column_filter(parts.first)
-        %w[id type].include?(col_filter ? col_filter[:column] : parts.first)
-      end
-
       def render_filter_errors(invalid)
         render_parameter_errors(
           invalid,

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

@@ -105,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/support/collection_query.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "sort"
+require_relative "filter_path"
 require_relative "concerns/regular_filters"
 require_relative "concerns/nested_filters"
 require_relative "concerns/polymorphic_filters"
@@ -17,10 +18,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
@@ -29,7 +31,7 @@ module JSONAPI
 
     def execute
       @scope = apply_filtering
-      @sort = Support::Sort.new(sort_params:, resource_class: definition)
+      @sort = Support::Sort.new(sort_params:, resource_class: definition, tie_break: pagination_applied)
       compute_total_count_if_needed
       @scope = @sort.apply(@scope)
       @scope = apply_pagination
@@ -38,7 +40,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
@@ -50,5 +52,11 @@ module JSONAPI
       scope = apply_nested_relationship_filters(@scope)
       apply_regular_filters(scope)
     end
+
+    # The query trusts no caller to validate first. It applies a filter only
+    # when the resources on its path declare it.
+    def filter_path
+      @filter_path ||= Support::FilterPath.new(definition:, model_class:, namespace:)
+    end
   end
 end

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

@@ -17,53 +17,25 @@ module JSONAPI
       private
 
       def apply_filter_for_path(scope, filter_name, filter_value)
-        parts = filter_name.split(".")
-        return scope if parts.length < 2
+        *relationship_chain, leaf_filter = filter_name.split(".")
+        return scope if relationship_chain.empty?
 
-        relationship_chain = parts[0..-2]
-        leaf_filter = parts.last
+        # The walk filter validation takes. A path it refuses filters nothing.
+        target = filter_path.resolve(filter_name)
+        return scope unless target
 
-        result = traverse_relationship_chain(scope, relationship_chain, leaf_filter, filter_value)
-        return result[:scope] if result[:early_return]
-
-        apply_joined_filter(scope, result, relationship_chain:, leaf_filter:, filter_value:)
-      end
-
-      def traverse_relationship_chain(scope, relationship_chain, leaf_filter, filter_value)
-        current_model = model_class
-        current_definition = definition
-
-        relationship_chain.each do |relationship_name|
-          result = process_chain_step(scope, current_model, relationship_name, leaf_filter, filter_value)
-          return result if result[:early_return]
-
-          current_model = result[:model]
-          current_definition = result[:definition]
-        end
-
-        { model: current_model, definition: current_definition, early_return: false }
-      end
-
-      def process_chain_step(scope, current_model, relationship_name, leaf_filter, filter_value)
-        association = current_model.reflect_on_association(relationship_name.to_sym)
-        return { scope:, early_return: true } unless association
-
-        if association.polymorphic?
+        if target.association
           attributes = { leaf_filter => filter_value }
-          return { scope: apply_polymorphic_nested_filters(scope, association, relationship_name, attributes),
-                   early_return: true, }
+          return apply_polymorphic_nested_filters(scope, target.association, relationship_chain.last, attributes)
         end
 
-        next_definition = JSONAPI::Resource.resource_for_model(association.klass)
-        return { scope:, early_return: true } unless next_definition
-
-        { model: association.klass, definition: next_definition, early_return: false }
+        apply_joined_filter(scope, target.model, relationship_chain:, leaf_filter:, filter_value:)
       end
 
-      def apply_joined_filter(scope, result, relationship_chain:, leaf_filter:, filter_value:)
+      def apply_joined_filter(scope, target_model, relationship_chain:, leaf_filter:, filter_value:)
         join_hash = build_join_hash_for_chain(relationship_chain)
         scope = scope.joins(join_hash) if join_hash.present?
-        apply_filter_on_model(scope, result[:model], result[:definition], leaf_filter, filter_value)
+        apply_filter_on_model(scope, target_model, leaf_filter, filter_value)
       end
 
       def build_join_hash_for_chain(chain)
@@ -78,15 +50,15 @@ module JSONAPI
         end
       end
 
-      def apply_filter_on_model(scope, target_model, target_resource, filter_name, filter_value)
+      def apply_filter_on_model(scope, target_model, filter_name, filter_value)
         return scope if empty_filter_value?(filter_value)
 
         apply_column_filter(scope, target_model, filter_name, filter_value) ||
-          apply_scope_method_filter(scope, target_model, target_resource, filter_name, filter_value) ||
+          apply_scope_method_filter(scope, target_model, filter_name, filter_value) ||
           scope
       end
 
-      def apply_scope_method_filter(scope, target_model, _target_resource, filter_name, filter_value)
+      def apply_scope_method_filter(scope, target_model, filter_name, filter_value)
         return nil unless target_model.respond_to?(filter_name.to_sym)
 
         try_scope_method(scope, target_model, filter_name, filter_value)

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

@@ -18,6 +18,7 @@ module JSONAPI
 
       def apply_regular_filter(scope, filter_name, filter_value)
         return scope if empty_filter_value?(filter_value)
+        return scope unless filter_path.declared?(filter_name)
 
         apply_column_filter(scope, model_class, filter_name, filter_value) ||
           apply_scope_fallback(scope, filter_name, filter_value)

data/lib/json_api/support/filter_path.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "filter_parsing"
+
+module JSONAPI
+  module Support
+    # Walks a filter path such as `comments.author.email_eq`, for filter
+    # validation and for the query. A resource declares each hop as a
+    # relationship, and the last resource declares the leaf as a filter. A path
+    # that fails either test resolves to nothing.
+    class FilterPath
+      include FilterParsing
+
+      # Where a declared path ends. `association` is the polymorphic hop that
+      # ends the walk, and nil on every other path.
+      Target = Struct.new(:model, :definition, :association)
+
+      def initialize(definition:, model_class:, namespace:)
+        @definition = definition
+        @model_class = model_class
+        @namespace = namespace
+      end
+
+      def declared?(name)
+        !resolve(name).nil?
+      end
+
+      def resolve(name)
+        *relationships, filter = name.to_s.split(".")
+        return nil unless filter
+
+        target = walk(relationships)
+        target if target && filter_declared?(target, filter)
+      end
+
+      private
+
+      def walk(relationships)
+        target = Target.new(@model_class, @definition)
+        relationships.each do |relationship|
+          # A polymorphic hop names no one resource, so no hop follows it.
+          target = target.association ? nil : hop(target, relationship)
+          return nil unless target
+        end
+        target
+      end
+
+      def hop(target, relationship)
+        return nil unless listed?(target.definition.permitted_filters_through, relationship)
+
+        association = target.model.reflect_on_association(relationship.to_sym)
+        return nil unless association
+        return Target.new(target.model, target.definition, association) if association.polymorphic?
+
+        definition = hop_definition(association.klass)
+        definition && Target.new(association.klass, definition)
+      end
+
+      # The 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 hop_definition(model)
+        JSONAPI::ResourceLoader.find_for_model(model, namespace: @namespace)
+      rescue JSONAPI::ResourceLoader::MissingResourceClass
+        nil
+      end
+
+      def filter_declared?(target, filter)
+        return polymorphic_filter?(filter) if target.association
+
+        listed?(target.definition.permitted_filters, filter)
+      end
+
+      def polymorphic_filter?(filter)
+        column_filter = parse_column_filter(filter)
+        %w[id type].include?(column_filter ? column_filter[:column] : filter)
+      end
+
+      def listed?(names, name)
+        names.map(&:to_s).include?(name)
+      end
+    end
+  end
+end

data/lib/json_api/support/sort.rb

@@ -17,6 +17,10 @@ module JSONAPI
     # sort over the materialised result set. This means virtual sorts always
     # take precedence over column/scope sorts regardless of the order the
     # user specified them in.
+    #
+    # With tie_break, the order ends with the primary key. A paged read needs
+    # that: its pages are separate queries, and only a total order makes them
+    # agree on which row comes where.
     class Sort
       class InvalidFieldError < JSONAPI::Error
         attr_reader :invalid_fields
@@ -27,15 +31,15 @@ module JSONAPI
         end
       end
 
-      def initialize(sort_params:, resource_class:)
+      def initialize(sort_params:, resource_class:, tie_break: false)
         @fields = build_fields(sort_params, resource_class)
+        @tie_break = tie_break
       end
 
       def apply(scope)
-        return scope if @fields.empty?
-
         virtual, db = @fields.partition(&:virtual?)
         scope = db.reduce(scope) { |acc, field| field.apply(acc) }
+        scope = break_ties(scope) if @tie_break
         virtual.any? ? apply_virtual_sorting(scope, virtual) : scope
       end
 
@@ -64,8 +68,21 @@ module JSONAPI
         raise InvalidFieldError, invalid if invalid.any?
       end
 
+      # A database places tied rows as it finds them, and an update moves a row.
+      # The primary key gives every row one place, so two queries agree on the order.
+      def break_ties(scope)
+        return scope unless scope.is_a?(ActiveRecord::Relation)
+
+        scope.order(Array(scope.primary_key).index_with(:asc))
+      end
+
+      # Array#sort does not keep tied items in place, so the position the scope gave breaks the tie.
       def apply_virtual_sorting(scope, virtual_fields)
-        scope.to_a.sort { |a, b| compare_by_fields(a, b, virtual_fields) }
+        ranked = scope.to_a.each_with_index.sort do |(record_a, position_a), (record_b, position_b)|
+          comparison = compare_by_fields(record_a, record_b, virtual_fields)
+          comparison.zero? ? position_a <=> position_b : comparison
+        end
+        ranked.map(&:first)
       end
 
       def compare_by_fields(record_a, record_b, fields)

data/lib/json_api/version.rb

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

data/lib/json_api.rb

@@ -37,6 +37,7 @@ require "json_api/active_storage/serialization"
 require "json_api/active_storage/deserialization"
 require "json_api/support/active_storage_support"
 require "json_api/support/filter_parsing"
+require "json_api/support/filter_path"
 require "json_api/support/collection_query"
 require "json_api/support/prosopite_instrumentation_logger"
 require "json_api/support/n1_log_subscriber"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 4.1.1.pre.202609300315
+  version: 4.1.2
 platform: ruby
 authors:
 - Emil Kampp
@@ -166,6 +166,7 @@ files:
 - lib/json_api/support/concerns/regular_filters.rb
 - lib/json_api/support/correlation_id.rb
 - lib/json_api/support/filter_parsing.rb
+- lib/json_api/support/filter_path.rb
 - lib/json_api/support/header_warning_subscriber.rb
 - lib/json_api/support/instrumentation.rb
 - lib/json_api/support/n1_log_subscriber.rb