jpie 4.1.1 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e43b1a16ff0ab1f8d1e2bed93eed667a7cdebbf83879dc7ba1da4cd4934eee
-  data.tar.gz: 3af66fff765a5f8b3efff0b4ca5866601c847e16c38492c08e6fd97b6eacbc95
+  metadata.gz: e210d214edcde88211f1fad82af9fa2dfcc2bb67053e8592d7a7d271995d99b3
+  data.tar.gz: e8e81eacff5269a4f66cadc93ee496b9b7746f7016f9a68a48cdffb21fc3d64e
 SHA512:
-  metadata.gz: d6d1da393d39f54ca154910a34b622bef89e8cf08aac4918fd9f796aeb38ba3e84b76afbf30b987fb7e85f7f7dfa53f0685fec274ce0bc9224ec52a7e0d4e42e
-  data.tar.gz: df49c567f4c64d98895ec528370591ff67760de7396a01dd15678af7a63d527d11e9bd11033ee90f76392dc48044749c8d6ec7c3019618f08b8ccdb06776dbd8
+  metadata.gz: 1725977eb3a852b9b131453bbca28d25ab5495faf06862b439bf65572455be2d1a97cbf8de18ad65e855d3e51c349e6ac06af3644201436fc7d00b52919ae6bd
+  data.tar.gz: f17962764401488d7986f9da451d26bc3a68a037135713169ad76b2b7be9ec86533b66e17c2d0c3e0fa36d290d67575b03818675fbb3e07f22ac89c8d2fc3916

data/CHANGELOG.md

@@ -7,6 +7,55 @@ at release time.
 
 ## [Unreleased]
 
+## [4.1.3] - 2026-10-10
+
+### Fixed
+
+- **Filter a polymorphic hop on the model that owns it.** A path such as
+  `filter[user.profile.id_eq]` on `/posts` passed validation and answered 500.
+  `PolymorphicFilters` read the foreign key and type columns from the root
+  table of the query, and `posts` holds no `profile_id`. A root table that
+  holds a column of the same name answered 200 with rows filtered on the wrong
+  table. The filter now joins the hops before the polymorphic one and reads
+  the columns of the owner's table. A polymorphic hop on the root model
+  behaves as before. Regression spec:
+  `nested_filter_polymorphic_hop_below_root_spec.rb`.
+- **Ignore an empty nested filter value.** `filter[comments.author.email_eq]=`
+  added the inner join before it checked the value, so the answer held only
+  the posts that have a comment. `filter[profile.type]=` matched the empty
+  string and answered no rows. An empty nested value now adds no join and no
+  condition, as an empty top-level filter does. A nested filter that adds no
+  condition adds no join either. Regression spec:
+  `nested_filter_empty_value_spec.rb`.
+
+## [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

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:

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

@@ -4,74 +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 = 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)
-      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/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"
@@ -30,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
@@ -51,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,61 +17,27 @@ 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 = parts[0..-2]
-        leaf_filter = parts.last
-
-        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?
-          attributes = { leaf_filter => filter_value }
-          return { scope: apply_polymorphic_nested_filters(scope, association, relationship_name, attributes),
-                   early_return: true, }
-        end
+        *relationship_chain, leaf_filter = filter_name.split(".")
+        return scope if relationship_chain.empty?
+        # An empty value filters nothing, so it adds no join. An inner join
+        # drops each row that has no related record.
+        return scope if empty_filter_value?(filter_value)
 
-        next_definition = hop_definition(association.klass)
-        return { scope:, early_return: true } unless next_definition
+        # The walk filter validation takes. A path it refuses filters nothing.
+        target = filter_path.resolve(filter_name)
+        return scope unless target
 
-        { model: association.klass, definition: next_definition, early_return: false }
+        # The foreign key and type columns of a polymorphic hop sit on the model
+        # that owns the association. Only the hops before it need a join.
+        joined = join_chain(scope, target.association ? relationship_chain[0..-2] : relationship_chain)
+        filtered = apply_filter_on_target(joined, target, leaf_filter, filter_value)
+        # A filter that adds no condition adds no join either.
+        filtered.equal?(joined) ? scope : filtered
       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?
-        apply_filter_on_model(scope, result[:model], result[:definition], leaf_filter, filter_value)
+      def join_chain(scope, chain)
+        join_hash = build_join_hash_for_chain(chain)
+        join_hash.present? ? scope.joins(join_hash) : scope
       end
 
       def build_join_hash_for_chain(chain)
@@ -86,15 +52,18 @@ module JSONAPI
         end
       end
 
-      def apply_filter_on_model(scope, target_model, target_resource, filter_name, filter_value)
-        return scope if empty_filter_value?(filter_value)
+      def apply_filter_on_target(scope, target, filter_name, filter_value)
+        if target.association
+          attributes = { filter_name => filter_value }
+          return apply_polymorphic_nested_filters(scope, target.association, target.model, attributes)
+        end
 
-        apply_column_filter(scope, target_model, filter_name, filter_value) ||
-          apply_scope_method_filter(scope, target_model, target_resource, filter_name, filter_value) ||
+        apply_column_filter(scope, target.model, 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/polymorphic_filters.rb

@@ -3,8 +3,10 @@
 module JSONAPI
   module Support
     module PolymorphicFilters
-      def apply_polymorphic_nested_filters(scope, association, _relationship_name, attributes)
-        context = build_polymorphic_filter_context(association, attributes)
+      # `owner` is the model that holds the association. Its table carries the
+      # foreign key and type columns, and the scope must already join it.
+      def apply_polymorphic_nested_filters(scope, association, owner, attributes)
+        context = build_polymorphic_filter_context(association, owner, attributes)
 
         attributes.each do |attr_name, attr_value|
           scope = apply_polymorphic_attribute_filter(scope, attr_name, attr_value, context)
@@ -15,18 +17,18 @@ module JSONAPI
 
       private
 
-      def build_polymorphic_filter_context(association, attributes)
+      def build_polymorphic_filter_context(association, owner, attributes)
         {
+          owner:,
           foreign_key: association.foreign_key,
           foreign_type: association.foreign_type,
-          fk_column: model_class.column_for_attribute(association.foreign_key),
+          fk_column: owner.column_for_attribute(association.foreign_key),
           type_value: attributes["type"] || attributes["type_eq"],
           class_name: association.options[:class_name],
         }
       end
 
       def apply_polymorphic_attribute_filter(scope, attr_name, attr_value, context)
-        return scope if empty_filter_value?(attr_value)
         return scope if attr_name == "type"
 
         scope = apply_polymorphic_id_filter(scope, attr_name, attr_value, context)
@@ -38,7 +40,7 @@ module JSONAPI
         return apply_polymorphic_fk_filter(scope, attr_value, column_filter, context) if polymorphic_fk_filter?(
           column_filter, context,
         )
-        return scope.where(context[:foreign_key] => attr_value) if attr_name == "id"
+        return where_owner_column(scope, context, :foreign_key, attr_value) if attr_name == "id"
 
         scope
       end
@@ -48,17 +50,17 @@ module JSONAPI
       end
 
       def apply_polymorphic_fk_filter(scope, attr_value, column_filter, context)
-        value = normalize_filter_value_for_model(model_class, context[:fk_column], attr_value)
+        value = normalize_filter_value_for_model(context[:owner], context[:fk_column], attr_value)
         return scope unless value
 
-        condition = build_condition(model_class, context[:fk_column], value, column_filter[:operator])
+        condition = build_condition(context[:owner], context[:fk_column], value, column_filter[:operator])
         condition ? apply_condition(scope, condition) : scope
       end
 
       def apply_polymorphic_type_filter(scope, context)
         return scope unless context[:foreign_type]
-        return scope.where(context[:foreign_type] => context[:class_name]) if context[:class_name]
-        return scope.where(context[:foreign_type] => context[:type_value]) if context[:type_value]
+        return where_owner_column(scope, context, :foreign_type, context[:class_name]) if context[:class_name]
+        return where_owner_column(scope, context, :foreign_type, context[:type_value]) if context[:type_value]
 
         scope
       end
@@ -68,7 +70,13 @@ module JSONAPI
         return scope if context[:class_name]
         return scope unless context[:type_value]
 
-        scope.where(context[:foreign_type] => context[:type_value])
+        where_owner_column(scope, context, :foreign_type, context[:type_value])
+      end
+
+      # Names the owner's table, so the condition reads the joined table when
+      # the owner sits below the root of the query.
+      def where_owner_column(scope, context, column_key, value)
+        scope.where(context[:owner].table_name => { context[column_key] => value })
       end
     end
   end

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"
+  VERSION = "4.1.3"
 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
+  version: 4.1.3
 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