jpie 4.1.1 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e43b1a16ff0ab1f8d1e2bed93eed667a7cdebbf83879dc7ba1da4cd4934eee
-  data.tar.gz: 3af66fff765a5f8b3efff0b4ca5866601c847e16c38492c08e6fd97b6eacbc95
+  metadata.gz: 7cb5c150e4da0f0608aa5b97534e2239b8b80900054c984ca2aed3c24e747198
+  data.tar.gz: 83558900f75be4e9a4b8ea5997f7551963ee1406359b9fd30903d39fe9ad78bb
 SHA512:
-  metadata.gz: d6d1da393d39f54ca154910a34b622bef89e8cf08aac4918fd9f796aeb38ba3e84b76afbf30b987fb7e85f7f7dfa53f0685fec274ce0bc9224ec52a7e0d4e42e
-  data.tar.gz: df49c567f4c64d98895ec528370591ff67760de7396a01dd15678af7a63d527d11e9bd11033ee90f76392dc48044749c8d6ec7c3019618f08b8ccdb06776dbd8
+  metadata.gz: 1fdbf06edc4419def82b3719d3cd419e84bc76f3ebb9af0e64650c8eea9856d0d0a20c688a8c291c491fddaed0f28a417b506391dc63e3987ab8594a34126f4f
+  data.tar.gz: cfa30d1e5be610419135bcd16b13752a9eab3792c8082fe95d4a8cc6272103c6ea62c6315bdfc3e46b68b2d7ffe8467b1231e37980e8872b0f3f3781ba71b3d0

data/CHANGELOG.md

@@ -7,6 +7,34 @@ 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

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,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 = 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
+        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)
@@ -86,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"
+  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
+  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