jpie 3.7.0 → 3.8.2

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

@@ -38,7 +38,8 @@ module JSONAPI
 
         related_model_class = type_value.constantize
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(related_model_class)
-        record = related_resource_class.records.find(id_value)
+        base = apply_relationship_authorization(related_resource_class.records, related_model_class)
+        record = base.find(id_value)
 
         association.collection? ? Array(record) : record
       end
@@ -52,17 +53,31 @@ module JSONAPI
       def fetch_polymorphic_has_many_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
-        related_resource_class.records.merge(association_instance.scope)
+        base = apply_relationship_authorization(related_resource_class.records, association.klass)
+        association_instance.scope.merge(base)
       end
 
       def fetch_non_polymorphic_related_through_resource_records(association)
         association_instance = @resource.association(@relationship_name)
         related_resource_class = JSONAPI::ResourceLoader.find_for_model(association.klass)
-        scope = related_resource_class.records.merge(association_instance.scope)
+        base = apply_relationship_authorization(related_resource_class.records, association.klass)
+        scope = association_instance.scope.merge(base)
 
         association.collection? ? scope : scope.first
       end
 
+      # A relationships response (`/:type/:id/relationships/:rel`) lists the related
+      # records identified by linkage. Route the related base scope through the
+      # configured authorization_scope hook, exactly as the primary collection and
+      # `?include=` sideloads already do, so linkage never names a record the reader
+      # cannot fetch. No configured hook leaves the scope untouched.
+      def apply_relationship_authorization(scope, model_class)
+        handler = JSONAPI.configuration.authorization_scope
+        return scope unless handler
+
+        handler.call(controller: self, scope:, action: :index, model_class:)
+      end
+
       def serialize_related(related, association)
         return serialize_collection_relationship(related, association) if association.collection?
 

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

@@ -8,10 +8,14 @@ module JSONAPI
       private
 
       def includes_to_hash(paths)
-        hash = paths.each_with_object({}) do |path, h|
-          path.split(".").reduce(h) { |cur, part| cur[part.to_sym] ||= {} }
+        filter_includable(includes_to_tree(paths), model_class)
+      end
+
+      # Nests dotted include paths into one tree, collapsing shared prefixes.
+      def includes_to_tree(paths)
+        paths.each_with_object({}) do |path, tree|
+          path.split(".").reduce(tree) { |node, part| node[part.to_sym] ||= {} }
         end
-        filter_includable(hash, model_class)
       end
 
       # Preloads associations from the include param so the serializer avoids N+1 queries
@@ -32,12 +36,27 @@ module JSONAPI
       def filter_includable(hash, klass)
         hash.each_with_object({}) do |(key, value), filtered|
           assoc = klass.reflect_on_association(key)
-          next unless assoc
-
-          filtered[key] = value.empty? || assoc.polymorphic? ? value : filter_includable(value, assoc.klass)
+          if assoc
+            filtered[key] = value.empty? || assoc.polymorphic? ? value : filter_includable(value, assoc.klass)
+          elsif (attachment_assoc = attachment_association_name(klass, key))
+            # An attachment include carries no AR reflection under its own name
+            # (has_many_attached :files defines files_attachments, not files).
+            # Preload the association pair ActiveStorage defines for it, so the
+            # serializer reads blobs without one probe query per record.
+            filtered[attachment_assoc] = { blob: {} }
+          end
         end
       end
 
+      def attachment_association_name(klass, key)
+        return nil unless defined?(::ActiveStorage) && klass.respond_to?(:reflect_on_attachment)
+
+        reflection = klass.reflect_on_attachment(key)
+        return nil unless reflection
+
+        reflection.macro == :has_one_attached ? :"#{key}_attachment" : :"#{key}_attachments"
+      end
+
       def preload_required?(hash, klass)
         hash.any? do |key, value|
           assoc = klass.reflect_on_association(key)
@@ -67,18 +86,45 @@ module JSONAPI
         assoc.polymorphic? || (value.present? && hash_contains_polymorphic?(value, assoc.klass))
       end
 
+      # Applies each included resource's own `records` preloads to the records
+      # of that resource's class. Walks the whole include tree: a resource
+      # reached at depth 3 gets its preloads just as one reached at depth 1.
+      #
+      # 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
+      # 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)
         return if includes.empty? || resources.empty?
 
-        includes.each do |include_path|
-          association_name = include_path.split(".").first.to_sym
-          assoc_reflection = model_class.reflect_on_association(association_name)
-          next unless assoc_reflection
+        preload_resource_tree(resources, model_class, includes_to_tree(includes))
+      end
+
+      def preload_resource_tree(records, klass, tree)
+        tree.each do |association_name, subtree|
+          reflection = klass.reflect_on_association(association_name)
+          next unless reflection
 
-          targets = collect_include_targets(resources, association_name)
+          targets = collect_include_targets(records, association_name)
           next if targets.empty?
 
-          apply_preloads_for_targets(targets, assoc_reflection.polymorphic?)
+          apply_preloads_for_targets(targets, reflection.polymorphic?)
+          next if subtree.empty?
+
+          descend_resource_tree(targets, reflection, subtree)
+        end
+      end
+
+      # A polymorphic hop has no single target class, so continue once per
+      # class actually present in the loaded targets.
+      def descend_resource_tree(targets, reflection, subtree)
+        if reflection.polymorphic?
+          targets.group_by(&:class).each do |target_class, records|
+            preload_resource_tree(records, target_class, subtree)
+          end
+        else
+          preload_resource_tree(targets, reflection.klass, subtree)
         end
       end
 

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

@@ -7,8 +7,10 @@ module JSONAPI
       include IncludePreloading
 
       def serialize_resource(resource)
-        JSONAPI::Serializer.new(resource, authorization_context: self).to_hash(
-          include: parse_include_param,
+        includes = parse_include_param
+        cache = build_include_filter_cache([resource], includes)
+        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache).to_hash(
+          include: includes,
           fields: parse_fields_param,
           document_meta: jsonapi_document_meta,
         )
@@ -28,28 +30,68 @@ module JSONAPI
 
       private
 
+      # One IncludeContext spans the whole page, so a record reached from
+      # several primaries serializes once, not once per primary. The final
+      # type-id pass keeps the response contract: it drops the rare collision
+      # where two model classes serialize to the same type and id.
       def serialize_resources_with_includes(resources, includes, fields)
-        all_included = []
-        processed = Set.new
+        shared_context = JSONAPI::Serialization::IncludeContext.new(
+          fields: fields, included_records: [], processed: Set.new, all_includes: nil,
+        )
+        cache = build_include_filter_cache(resources, includes)
 
         data = resources.map do |r|
-          result = serialize_single(r, includes, fields)
-          collect_included(result, all_included, processed)
-          result[:data]
+          serialize_single(r, includes, fields, shared_context, cache)[:data]
         end
 
-        [data, all_included]
+        [data, dedupe_included(shared_context.included_records)]
       end
 
-      def serialize_single(resource, includes, fields)
-        JSONAPI::Serializer.new(resource, authorization_context: self).to_hash(include: includes, fields:,
-                                                                               document_meta: nil,)
+      def serialize_single(resource, includes, fields, include_context = nil, cache = nil)
+        JSONAPI::Serializer.new(resource, authorization_context: self, include_filter_cache: cache)
+          .to_hash(include: includes, fields:, document_meta: nil, include_context:)
       end
 
-      def collect_included(result, all_included, processed)
-        (result[:included] || []).each do |inc|
+      # One filter cache per request, warmed from the loaded include tree:
+      # 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)
+        includes.each do |path|
+          current = resources
+          path.split(".").each do |part|
+            current = warm_include_level(cache, current, part.to_sym)
+            break if current.empty?
+          end
+        end
+        cache
+      end
+
+      def warm_include_level(cache, records, association_name)
+        targets = records.flat_map { |record| loaded_association_targets(record, association_name) }
+        targets.group_by(&:class).each { |klass, recs| cache.warm(klass, recs.filter_map(&:id)) }
+        targets
+      end
+
+      # Attachment names carry no AR reflection, and unloaded associations go
+      # through the scoped-relation fallback instead of filtering: both skip.
+      def loaded_association_targets(record, association_name)
+        return [] unless record.class.reflect_on_association(association_name)
+
+        association = record.association(association_name)
+        return [] unless association.loaded?
+
+        target = association.target
+        target.respond_to?(:to_a) ? target.to_a.compact : Array(target).compact
+      end
+
+      def dedupe_included(included_records)
+        all_included = []
+        processed = Set.new
+        included_records.each do |inc|
           add_unique_included(inc, all_included, processed)
         end
+        all_included
       end
 
       def add_unique_included(inc, all_included, processed)

data/lib/json_api/railtie.rb

@@ -100,8 +100,13 @@ module JSONAPI
     #    before app controllers are available, causing FrozenError or NameError
     # 3. We register with reloader.to_prepare for code reloading in development
     config.after_initialize do |app|
-      # Register for code reloading in development
+      # Register for code reloading in development. Clear the name-keyed
+      # resolution caches first so reloaded classes re-resolve; applications
+      # that pre-populate ResourceLoader caches in their own to_prepare blocks
+      # run after this and re-apply their entries.
       app.reloader.to_prepare do
+        JSONAPI::ResourceLoader.reset_cache!
+        JSONAPI::TypeConversion.reset_cache!
         Railtie.setup_base_controllers
       end
 

data/lib/json_api/resources/resource_loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "concurrent/map"
+
 module JSONAPI
   class ResourceLoader
     class MissingResourceClass < JSONAPI::Error
@@ -16,7 +18,30 @@ module JSONAPI
       end
     end
 
+    # Resolution runs the inflector and safe_constantize on every call, and the
+    # serializer calls it once per record, per identifier, and per include-hop
+    # visit. Cache by name, never by class object, so a reloaded class cannot be
+    # retained. Only successful resolutions are cached. The railtie clears both
+    # caches on code reload.
+    @find_cache = Concurrent::Map.new
+    @model_cache = Concurrent::Map.new
+
+    def self.reset_cache!
+      @find_cache.clear
+      @model_cache.clear
+    end
+
     def self.find(resource_type, namespace: nil)
+      key = "#{namespace}|#{resource_type}|#{JSONAPI.configuration.namespace_fallback ? 1 : 0}"
+      cached = @find_cache[key]
+      return cached if cached
+
+      klass = resolve(find_candidates(resource_type, namespace)) ||
+              raise(MissingResourceClass.new(resource_type, namespace:))
+      @find_cache[key] = klass
+    end
+
+    def self.find_candidates(resource_type, namespace)
       candidates = []
 
       # Namespaced resource, e.g. "widgets" with namespace "api/v1" → API::V1::WidgetResource
@@ -28,16 +53,24 @@ module JSONAPI
                                                 nil,)
       end
 
-      resolve(candidates) || raise(MissingResourceClass.new(resource_type, namespace:))
+      candidates
     end
 
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
+      # Key format "::ModelName" is public-ish: applications pre-populate
+      # @model_cache with these keys to pin STI subclass resources.
+      key = namespace ? "#{namespace}|::#{model_class.name}" : "::#{model_class.name}"
+      cached = @model_cache[key]
+      return cached if cached
+
       effective_namespace = namespace || extract_namespace_from_model(model_class)
       candidates = model_candidates(model_class, effective_namespace)
 
-      resolve(candidates) || raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      klass = resolve(candidates) ||
+              raise(MissingResourceClass.new(model_class.name, namespace: effective_namespace))
+      @model_cache[key] = klass
     end
 
     def self.build_resource_class_name(resource_type, namespace)

data/lib/json_api/routing.rb

@@ -8,6 +8,7 @@ module JSONAPI
       controller ||= detect_controller(resource_name, namespace)
       defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
       options[:only] = :index if sti
+      options = without_form_actions(options)
 
       JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
@@ -20,6 +21,15 @@ module JSONAPI
 
     private
 
+    # `new` and `edit` render the HTML forms of a scaffold. A JSON:API endpoint
+    # answers neither, so the routes only pad the route table and any document
+    # generated from it. A caller that names `only:` keeps full control.
+    def without_form_actions(options)
+      return options if options.key?(:only)
+
+      options.merge(except: Array(options[:except]) | %i[new edit])
+    end
+
     def extract_namespace_from_scope
       @scope[:module]&.to_s.presence
     end

data/lib/json_api/serialization/concerns/include_filtering.rb

@@ -3,51 +3,17 @@
 module JSONAPI
   module Serialization
     module IncludeFiltering
+      # When the authorization_scope hook or the resource's records scope
+      # narrows the relation, the eager-loaded set — preloaded through
+      # acts_as_tenant alone — must be re-checked against the narrowed scope,
+      # so a relationship never surfaces a record the related endpoint
+      # denies. The request-scoped cache memoizes the scopes and the per-id
+      # verdicts, so each record is vetted at most once per request.
       def filter_loaded_records(association, related_klass)
         loaded_array = association.target.respond_to?(:to_a) ? association.target.to_a : Array(association.target)
         return [] if loaded_array.empty?
 
-        base_scope = ResourceLoader.find_for_model(related_klass).records
-        authorized_scope = apply_include_authorization(base_scope, related_klass)
-
-        # When the authorization_scope hook narrows the relation (joins/subqueries a
-        # where-hash can't express), the eager-loaded set — preloaded through acts_as_tenant
-        # alone — must be re-checked against the authorized scope in the database, so a
-        # relationship never surfaces a record the related endpoint denies. An unchanged
-        # scope keeps the in-memory, query-free records-only filtering.
-        return filter_by_query(loaded_array, authorized_scope) if narrowed?(base_scope, authorized_scope)
-        return loaded_array if base_scope.where_clause.empty?
-
-        filter_by_where_hash(loaded_array, base_scope, related_klass)
-      end
-
-      def narrowed?(base_scope, authorized_scope)
-        authorized_scope.to_sql != base_scope.to_sql
-      end
-
-      def filter_by_where_hash(loaded_array, resource_scope, related_klass)
-        hash = where_values_hash_for_scope(resource_scope, related_klass)
-        return filter_by_query(loaded_array, resource_scope) if hash.blank?
-
-        loaded_array.select { |r| record_matches_where_hash?(r, hash) }
-      end
-
-      def where_values_hash_for_scope(resource_scope, related_klass)
-        resource_scope.where_values_hash(related_klass.table_name)
-      rescue StandardError
-        {}
-      end
-
-      def record_matches_where_hash?(record, hash)
-        hash.all? do |attr, val|
-          r_val = record.read_attribute(attr)
-          val.is_a?(Array) ? val.include?(r_val) : r_val == val
-        end
-      end
-
-      def filter_by_query(loaded_array, resource_scope)
-        valid_ids = resource_scope.where(id: loaded_array.filter_map(&:id)).pluck(:id).to_set
-        loaded_array.select { |r| valid_ids.include?(r.id) }
+        include_filter_cache.filter(loaded_array, related_klass)
       end
     end
   end

data/lib/json_api/serialization/concerns/includes_serialization.rb

@@ -13,22 +13,18 @@ module JSONAPI
       include IncludePathHelpers
       include IncludeFiltering
 
-      def serialize_included(includes, fields = {})
+      def serialize_included(includes, fields = {}, context: nil)
         all_includes = normalize_include_paths(includes)
-        return [] if all_includes.empty?
+        return context&.included_records || [] if all_includes.empty?
 
-        ctx = build_include_context(fields, all_includes)
+        ctx = context || build_include_context(fields, all_includes)
+        ctx.all_includes ||= all_includes
         all_includes.each { |path| serialize_include_path(record, path, ctx, path_from_root: "") }
         ctx.included_records
       end
 
       def build_include_context(fields, all_includes)
-        IncludeContext.new(
-          fields: fields,
-          included_records: [],
-          processed: Set.new,
-          all_includes: all_includes,
-        )
+        IncludeContext.new(fields:, included_records: [], processed: Set.new, all_includes:)
       end
 
       private
@@ -116,11 +112,7 @@ module JSONAPI
       end
 
       def get_active_storage_records(current_record, association_name)
-        attachment = current_record.public_send(association_name)
-        return [] unless attachment.respond_to?(:attached?) && attachment.attached?
-        return attachment.blobs.to_a if attachment.is_a?(::ActiveStorage::Attached::Many)
-
-        [attachment.blob].compact
+        JSONAPI::ActiveStorage::Serialization.blobs_for(association_name, current_record)
       end
 
       def serialize_and_process_record(related_record, path_to_record, ctx, parent_record: nil, association_name: nil)
@@ -128,7 +120,7 @@ module JSONAPI
 
         requested = include_paths_to_relationship_names(ctx.all_includes, path_to_record)
         serializer = self.class.new(related_record, parent_record:, association_name:,
-                                                    authorization_context:,)
+                                                    authorization_context:, include_filter_cache:,)
         ctx.included_records << serializer.serialize_record(ctx.fields, requested_relationships: requested)
         ctx.processed.add(build_record_key(related_record))
       end

data/lib/json_api/serialization/concerns/meta_serialization.rb

@@ -44,16 +44,19 @@ module JSONAPI
 
       def default_timestamp_meta
         {}.tap do |meta|
-          meta[:created_at] = format_timestamp(:created_at)
-          meta[:updated_at] = format_timestamp(:updated_at)
+          meta[:created_at] = timestamp(:created_at)
+          meta[:updated_at] = timestamp(:updated_at)
         end.compact
       end
 
-      def format_timestamp(attr)
+      # Returns the raw Time so the JSON encoder formats it. Formatting here with
+      # `iso8601` drops the sub-second digits the encoder keeps, which puts two
+      # spellings of one instant in a single document whenever a resource also
+      # exposes the timestamp as an attribute.
+      def timestamp(attr)
         return unless record.respond_to?(attr)
 
-        value = record.public_send(attr)
-        value&.iso8601
+        record.public_send(attr)
       end
     end
   end

data/lib/json_api/serialization/include_filter_cache.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    # Request-scoped memoization for include filtering.
+    #
+    # The include walk re-checks the related resource's scope (and the
+    # authorization hook) against the loaded records once per parent record,
+    # per hop, per include path. Within one request those verdicts cannot
+    # change: the scopes are functions of the related class and the
+    # controller. So compute each class's filter data once, and vet each
+    # record id at most once. Pure memoization — the allowed set is
+    # identical, id for id, to the per-visit filtering it replaces.
+    class IncludeFilterCache
+      Entry = Struct.new(:base_scope, :authorized_scope, :narrowed, :where_clause_empty, :where_hash,
+                         keyword_init: true,)
+
+      def initialize(authorization_context: nil)
+        @authorization_context = authorization_context
+        @entries = {}
+        @verdicts = {}
+      end
+
+      # Filters loaded records with the same rules as the per-visit filtering:
+      # a narrowed authorization scope vets ids in the database; a resource
+      # scope with no where clause keeps everything; a where-hash-expressible
+      # scope matches in memory; anything else vets ids in the database
+      # against the resource scope.
+      def filter(records, klass)
+        entry = entry_for(klass)
+        return filter_by_ids(records, klass, :authorized, entry.authorized_scope) if entry.narrowed
+        return records if entry.where_clause_empty
+        return filter_by_ids(records, klass, :base, entry.base_scope) if entry.where_hash.blank?
+
+        records.select { |record| matches_where_hash?(record, entry.where_hash) }
+      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)
+        entry = entry_for(klass)
+        if entry.narrowed
+          vet_ids(klass, :authorized, entry.authorized_scope, ids)
+        elsif !entry.where_clause_empty && entry.where_hash.blank?
+          vet_ids(klass, :base, entry.base_scope, ids)
+        end
+      end
+
+      private
+
+      def entry_for(klass)
+        @entries[klass] ||= build_entry(klass)
+      end
+
+      def build_entry(klass)
+        base_scope = ResourceLoader.find_for_model(klass).records
+        authorized_scope = apply_authorization(base_scope, klass)
+        Entry.new(
+          base_scope: base_scope,
+          authorized_scope: authorized_scope,
+          narrowed: authorized_scope.to_sql != base_scope.to_sql,
+          where_clause_empty: base_scope.where_clause.empty?,
+          where_hash: where_hash_for(base_scope, klass),
+        )
+      end
+
+      # Mirrors the serializer's include authorization: no context (serializer
+      # used outside a request) or no configured hook leaves the scope untouched.
+      def apply_authorization(scope, klass)
+        return scope unless @authorization_context
+
+        handler = JSONAPI.configuration.authorization_scope
+        return scope unless handler
+
+        handler.call(controller: @authorization_context, scope:, action: :index, model_class: klass)
+      end
+
+      def where_hash_for(scope, klass)
+        scope.where_values_hash(klass.table_name)
+      rescue StandardError
+        {}
+      end
+
+      def matches_where_hash?(record, hash)
+        hash.all? do |attr, val|
+          r_val = record.read_attribute(attr)
+          val.is_a?(Array) ? val.include?(r_val) : r_val == val
+        end
+      end
+
+      def filter_by_ids(records, klass, kind, scope)
+        allowed = vet_ids(klass, kind, scope, records.filter_map(&:id))
+        records.select { |record| allowed.include?(record.id) }
+      end
+
+      # One verdict per id per (class, scope kind). Queries only ids that have
+      # no verdict yet; repeats answer from memory.
+      def vet_ids(klass, kind, scope, ids)
+        verdicts = (@verdicts[[klass, kind]] ||= {})
+        record_new_verdicts(verdicts, scope, ids)
+        ids.each_with_object(Set.new) { |id, set| set << id if verdicts[id] }
+      end
+
+      def record_new_verdicts(verdicts, scope, ids)
+        unseen = ids.reject { |id| verdicts.key?(id) }
+        return if unseen.empty?
+
+        valid = scope.where(id: unseen).pluck(:id).to_set
+        unseen.each { |id| verdicts[id] = valid.include?(id) }
+      end
+    end
+  end
+end

data/lib/json_api/serialization/serializer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "include_filter_cache"
 require_relative "concerns/attributes_serialization"
 require_relative "concerns/relationships_serialization"
 require_relative "concerns/links_serialization"
@@ -35,23 +36,28 @@ module JSONAPI
     end
 
     def initialize(record, definition: nil, base_definition: nil, parent_record: nil, association_name: nil,
-                   authorization_context: nil)
+                   authorization_context: nil, include_filter_cache: nil)
       @record = record
       @definition = definition || ResourceLoader.find_for_model(record.class)
       @base_definition = base_definition
       @parent_record = parent_record
       @association_name = association_name
       @authorization_context = authorization_context
+      @include_filter_cache = include_filter_cache
       @sti_subclass = nil
     end
 
-    def to_hash(include: [], fields: {}, document_meta: nil)
+    # include_context shares one IncludeContext across a whole collection: a
+    # record reached from several primaries then serializes once instead of
+    # once per primary. Callers that pass it read the accumulated records from
+    # the context, not from each result's :included.
+    def to_hash(include: [], fields: {}, document_meta: nil, include_context: nil)
       include_paths = normalize_include_paths(include)
       top_level_relationships = include_paths_to_relationship_names(include_paths, "")
       {
         jsonapi: jsonapi_object,
         data: serialize_record(fields, requested_relationships: top_level_relationships),
-        included: serialize_included(include_paths, fields),
+        included: serialize_included(include_paths, fields, context: include_context),
         meta: document_meta,
       }.compact
     end
@@ -71,6 +77,12 @@ module JSONAPI
 
     attr_reader :record, :definition, :parent_record, :association_name, :authorization_context
 
+    # Shared per request when the controller passes one in; a standalone
+    # serializer builds its own, which still dedupes within its own walk.
+    def include_filter_cache
+      @include_filter_cache ||= Serialization::IncludeFilterCache.new(authorization_context: authorization_context)
+    end
+
     def base_definition
       @base_definition ||= definition
     end