forest_liana 9.22.1 → 9.22.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be442492f5ecaafbff4d9d246c03634430ce0164159117f30a898cb730486090
-  data.tar.gz: 331dad7bbb30db9f6542adebf235ce1b8bf6e6f8abc96ef986b8fbb2c677aacd
+  metadata.gz: 2519878c68b98965bc3b8e31cf9ae9e8253f9d215cf724d99233e55cb37ab8c5
+  data.tar.gz: ae92f459f29ab022290ad09f33e9d1cec654d86fce2784cb425e8c8924b87e59
 SHA512:
-  metadata.gz: 8b01396fdeb47da3b36cba49666da16dd352ac8742a12cb83b84617b9c5e8529aaeaf500181c8b36cc4993aa090caaddf03e9c6b21ee3a17ddd47ab471b64e70
-  data.tar.gz: 707b4b922403fdefa05723d0fbdfadedc73bf7c73b59c1b7a9df6e8a55de61b6a43c2056ff50192063a385fc3e7a1202ac0770114c242409bf0a4499c84a46b0
+  metadata.gz: 6aaa74f4333c30a763077f5ef1e03247e9c42fd190608ef453263406485ecee48aae37fe8b8b927be1e5fadcf5eb12105c9ea9f5e1b43d7e6e66f78d6a1799af
+  data.tar.gz: 18e7851795ff42410beb2a87db9fb0cec346e4734cd04401461974529bf3d8e4a4ee61fca0e1d143428447f199b6c42cafe48f7c40a4e2d0c2841773e4bf254c

data/app/serializers/forest_liana/serializer_factory.rb

@@ -222,7 +222,20 @@ module ForestLiana
               if reflection_primary_key != klass_primary_key
                 data[attribute_name] = attr_data.merge({
                                                          attr_or_block: proc {
-                                                           relation.klass.find_by(reflection_primary_key => object.send(relation.foreign_key))
+                                                           # The find_by below reads once per row, undoing any preload, and
+                                                           # resolves less than ActiveRecord does: it drops the association's
+                                                           # own scope and matches a nil key against a target row whose key is
+                                                           # NULL too. Both branches answer the same record only once it is
+                                                           # aligned on the preloader, which is what scope_for does — and what
+                                                           # raises on a relation declaring no scope at all, the common case.
+                                                           association = object.association(attribute_name)
+                                                           next association.target if association.loaded? && !association.stale_target?
+
+                                                           key = object.send(relation.foreign_key)
+                                                           next nil if key.nil?
+
+                                                           scoped = relation.scope ? relation.scope_for(relation.klass.all, object) : relation.klass
+                                                           scoped.find_by(reflection_primary_key => key)
                                                          }
                                                        })
                 next

data/app/services/forest_liana/base_getter.rb

@@ -38,7 +38,9 @@ module ForestLiana
       polymorphic, preload_loads = analyze_associations(resource)
       result = records.eager_load(@includes.uniq - preload_loads - polymorphic - @optional_includes)
 
-      result = result.preload(preload_loads) if Rails::VERSION::MAJOR >= 7 && force_preload
+      if Rails::VERSION::MAJOR >= 7 && force_preload
+        result = result.preload(selectable_preloads(result, preload_loads))
+      end
 
       result
     end
@@ -48,6 +50,7 @@ module ForestLiana
     # instance_eval, once per record — loaded here in one query for the whole page instead.
     def apply_smart_field_preloads(records)
       preloads = smart_field_preloads
+      preloads = preloads.slice(*selectable_preloads(records, preloads.keys))
 
       preloads.empty? ? records : records.preload(preloads)
     end
@@ -192,6 +195,153 @@ module ForestLiana
       end
     end
 
+    # To-one only: a filter puts a to-many in @includes too, and preloading that would read every
+    # child row of a page that never displays them.
+    PRELOADABLE_CROSS_DATABASE_MACROS = [:belongs_to, :has_one].freeze
+
+    def cross_database_associations(resource)
+      @includes.uniq.select do |name|
+        association = resource.reflect_on_association(name)
+        next false if association.nil? || SchemaUtils.polymorphic?(association)
+        next false unless PRELOADABLE_CROSS_DATABASE_MACROS.include?(association.macro)
+
+        separate_database?(resource, association) && instance_dependent_hop(association).nil?
+      end
+    end
+
+    # Same version split as preload_polymorphic_associations. Nothing reads the loaders back here:
+    # a plain relation lands in the association cache, where the serializer finds it.
+    def preload_cross_database_associations(records, associations)
+      return if associations.empty? || records.empty?
+
+      associations = associations.reject { |name| missing_preload_key?(records, name) }
+      return if associations.empty?
+
+      if Rails::VERSION::MAJOR >= 7
+        ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
+      else
+        ActiveRecord::Associations::Preloader.new.preload(records, associations)
+      end
+    end
+
+    # A missing key raises while resolving the query, out of MissingAttributeValve's reach, and
+    # takes down the whole list rather than the one field (PRD-1316 from the other direction).
+    # Not only a belongs_to: a has_one reads its owner key off this row too when it declares a
+    # primary_key of its own. Per record class, not projected_resource, because that is how the
+    # Preloader resolves the reflection — one record per class is enough, the select being shared.
+    def missing_preload_key?(records, association_name)
+      records.group_by(&:class).any? do |klass, klass_records|
+        association = klass._reflect_on_association(association_name)
+        next false if association.nil?
+
+        missing = preload_owner_keys(association).reject { |key| klass_records.first.has_attribute?(key) }
+        next false if missing.empty?
+
+        warn_cross_database_preload_skipped(association_name, missing)
+        true
+      end
+    end
+
+    def warn_cross_database_preload_skipped(association_name, missing_keys)
+      reason = "its \"#{missing_keys.join('", "')}\" key is not in the projected select"
+      return unless PRELOAD_SKIPS_WARNED.add?([@collection&.name, association_name, reason])
+
+      FOREST_LOGGER.warn "The \"#{association_name}\" relation of the \"#{@collection&.name}\" " \
+        "collection lives in another database and cannot be preloaded (#{reason}) — it falls back " \
+        'to the lazy load, which cannot read that key either and resolves to a null relation.'
+    end
+
+    # The same question as missing_preload_key?, asked of a relation rather than of a page. A
+    # preload attached to a relation resolves after this method returns — per batch for an export,
+    # on #load for a list — so there is no record to test the key against, only the select the
+    # relation already carries. An empty one is SELECT *, which can never be missing anything; a
+    # narrowed one (a segment scope's .select, a default_scope's) can, and reading a key that is
+    # not there raises while resolving the query, out of MissingAttributeValve's reach, taking
+    # down the whole export where the lazy load it replaces degraded to a null relation.
+    def selectable_preloads(records, names)
+      return names if names.empty? || !records.respond_to?(:select_values)
+      return names if records.select_values.empty?
+
+      selected = selected_column_names(records)
+      return names if selected.include?('*')
+
+      names.reject do |name|
+        association = projected_resource.reflect_on_association(name)
+        next false if association.nil?
+
+        missing = preload_owner_keys(association).reject { |key| selected.include?(key.to_s) }
+        next false if missing.empty?
+
+        warn_unselected_preload_key(name, missing)
+        true
+      end
+    end
+
+    # Only a plain column reference can be read back off a select.
+    PLAIN_SELECT_REFERENCE = /\A(?:"?(?<table>\w+)"?\.)?"?(?<column>\w+|\*)"?\z/
+
+    def selected_column_names(records)
+      table = projected_resource.table_name
+
+      records.select_values.each_with_object(Set.new) do |value, names|
+        select_references(value).each do |reference|
+          match = PLAIN_SELECT_REFERENCE.match(reference)
+          next if match.nil? || (match[:table] && match[:table] != table)
+
+          names << match[:column]
+        end
+      end
+    end
+
+    # One select_value can name several columns, which splitting on commas recovers — but only
+    # while no parenthesis is in play: `COALESCE(uri, driver_id, name) AS x` would otherwise read
+    # as naming driver_id, and the preload that lets through raises on a column the row does not
+    # carry, which is the failure this guard exists to prevent. An expression names nothing here,
+    # so the preload is skipped and the relation left to the lazy load — the safe way to be wrong.
+    #
+    # SqlLiteral is a String, and is meant to be read like one. An Arel attribute is not, and
+    # carries its table and column apart, `products.*` included.
+    def select_references(value)
+      case value
+      when String, Symbol
+        text = value.to_s
+        text.include?('(') ? [] : text.split(',').map(&:strip)
+      when Arel::Attributes::Attribute
+        value.relation.respond_to?(:name) ? ["#{value.relation.name}.#{value.name}"] : []
+      else
+        []
+      end
+    end
+
+    # Re-checks the preloads a relation already carries, for the callers that attach them before
+    # the select is final — HasManyGetter builds its query in prepare_query and only projects in
+    # #perform. Judging the intermediate select drops preloads apply_projection was about to make
+    # safe: inherited_load_columns reads preload_values and selects their keys precisely because
+    # they are already attached. So the question is asked here, where the select is the one the
+    # query will run, and #preload only ever adds — removing one means rebuilding the relation.
+    def drop_unselected_preloads(records)
+      values = records.preload_values
+      return records if values.empty?
+
+      kept_names = selectable_preloads(records, association_names(values))
+      kept = values.select do |value|
+        names = value.is_a?(Hash) ? value.keys : [value]
+        names.all? { |name| kept_names.include?(name.to_sym) }
+      end
+
+      kept.size == values.size ? records : records.except(:preload).preload(kept)
+    end
+
+    def warn_unselected_preload_key(association_name, missing_keys)
+      reason = "its \"#{missing_keys.join('", "')}\" key is not in the query's select"
+      return unless PRELOAD_SKIPS_WARNED.add?([@collection&.name, association_name, reason])
+
+      FOREST_LOGGER.warn "The \"#{association_name}\" relation of the \"#{@collection&.name}\" " \
+        "collection cannot be preloaded (#{reason}) — it falls back to the lazy load, which reads " \
+        'it once per record where that key is on the row and resolves to a null relation where ' \
+        'it is not.'
+    end
+
     # records_by_owner's keys are the exact objects the Preloader was given, not copies — no need
     # to re-find them by id, which would also mis-assign on a nil or duplicate id (composite
     # primary keys are supported elsewhere in this gem).
@@ -364,6 +514,19 @@ module ForestLiana
         select_foreign_keys(select, projected_resource, association, joined?(association, joined_relations))
       end
 
+      # A cross-database to-one relation is never joined, so select_foreign_keys names nothing
+      # owner-side for the has_one half of it — and the preloader reads that key off this row.
+      # Without it here the guard in preload_cross_database_associations fires on every page and
+      # the relation keeps being read once per record, which is the N+1 this file removes. Off
+      # @includes for the same reason as the polymorphic loop above: the preload runs over all of
+      # it, not only the requested subset.
+      cross_database_associations(projected_resource).each do |name|
+        association = projected_resource.reflect_on_association(name)
+        preload_owner_keys(association).each do |key|
+          select << "#{projected_resource.table_name}.#{key}" if column?(projected_resource, key)
+        end
+      end
+
       @field_names_requested.each do |path|
         association = get_one_association(path)
         if association

data/app/services/forest_liana/has_many_getter.rb

@@ -85,11 +85,15 @@ module ForestLiana
     # batch never calls #perform and only reads ids, so it falls back to the plain
     # @base_records_for_batch, which needs no preload.
     def query_for_batch
-      @unprojected_records ? apply_smart_field_preloads(@unprojected_records) : @base_records_for_batch
+      return @base_records_for_batch unless @unprojected_records
+
+      drop_unselected_preloads(apply_smart_field_preloads(@unprojected_records))
     end
 
+    # The preloads were attached in prepare_query, before #perform projected: this is the first
+    # point where the select is the one the query will run.
     def records
-      records = @records.limit(limit).offset(offset)
+      records = drop_unselected_preloads(@records).limit(limit).offset(offset)
       polymorphic_associations, = analyze_associations(model_association)
 
       # Left a Relation (not resolved yet) when there is nothing to preload - some callers still
@@ -222,9 +226,10 @@ module ForestLiana
       # already routed those (and cross-DB ones) into `preload_loads`, so `move_to_preload` is
       # always safe to preload; only `preload_loads` needs the Rails 7+ gate.
       result = result.preload(move_to_preload)
-      result = result.preload(preload_loads) if Rails::VERSION::MAJOR >= 7
 
-      result
+      # Of the two shapes in preload_loads, 6.1's preloader only refuses the instance-dependent
+      # ones — gating both left it reading a cross-database relation once per row for nothing.
+      result.preload(Rails::VERSION::MAJOR >= 7 ? preload_loads : cross_database_associations(resource))
     end
 
     # Association names (symbols) whose JOIN the current request actually needs, so they must

data/app/services/forest_liana/resources_getter.rb

@@ -75,15 +75,25 @@ module ForestLiana
     # See HasManyGetter#query_for_batch: same dual-use split between a CSV export (which calls
     # #perform first, so this picks up its smart-field preload) and a bulk "select all" batch
     # (which never does, per initialize_resources_getter below, and only reads ids).
+    # On the relation, not a page: find_in_batches then resolves it per batch, so the key guard
+    # reads the select rather than a row. "Unprojected" only means this class did not narrow it —
+    # a segment whose scope calls .select narrows it before prepare_query ever returns.
     def query_for_batch
-      @unprojected_records ? apply_smart_field_preloads(@unprojected_records) : @base_records_for_batch
+      return @base_records_for_batch unless @unprojected_records
+
+      records = apply_smart_field_preloads(@unprojected_records)
+      cross_database = selectable_preloads(records, cross_database_associations(@resource))
+
+      cross_database.empty? ? records : records.preload(cross_database)
     end
 
     def records
       records = @records.offset(offset).limit(limit).to_a
-      polymorphic_association, preload_loads = analyze_associations(@resource)
+      polymorphic_association, = analyze_associations(@resource)
 
       preload_polymorphic_associations(records, polymorphic_association)
+      # On the page, not @records: count and query_for_batch build off the same relation.
+      preload_cross_database_associations(records, cross_database_associations(@resource))
 
       records
     end

data/app/services/forest_liana/schema_utils.rb

@@ -130,7 +130,7 @@ module ForestLiana
     def self.disable_filter_and_sort_if_cross_db!(opts, name, collection_name)
       return unless opts[:reference]
 
-      assoc_name = opts[:reference].split('.').first&.underscore&.to_sym || name
+      assoc_name = name.to_sym
       model = find_model_from_collection_name(collection_name)
       return unless model
 

data/lib/forest_liana/version.rb

@@ -1,3 +1,3 @@
 module ForestLiana
-  VERSION = "9.22.1"
+  VERSION = "9.22.2"
 end

data/spec/dummy/app/models/car.rb

@@ -1,3 +1,12 @@
 class Car < GarageRecord
   belongs_to :driver
-end
+
+  # Cross-database, keyed on a column that is not Driver's primary key.
+  belongs_to :pilot, class_name: 'Driver', primary_key: :firstname, foreign_key: :model,
+             optional: true
+
+  # The same, plus a scope: the preloader applies it and a bare find_by does not, so the
+  # serializer's two branches only agree once the fallback is aligned on the preloader.
+  belongs_to :active_pilot, -> { where.not(firstname: 'retired') }, class_name: 'Driver',
+             primary_key: :firstname, foreign_key: :model, optional: true
+end

data/spec/dummy/app/models/driver.rb

@@ -1,3 +1,6 @@
 class Driver < UserRecord
   has_one :car
-end
+
+  # The inverse of Car#pilot: the preload reads "firstname" off this row, and nothing projects it.
+  has_one :piloted_car, class_name: 'Car', primary_key: :firstname, foreign_key: :model
+end

data/spec/dummy/app/models/manufacturer.rb

@@ -1,3 +1,11 @@
 class Manufacturer < ApplicationRecord
   has_many :products
+
+  # A scope narrowing the select, which HasManyGetter attaches its preload to before
+  # apply_projection widens it — the select the guard must not judge.
+  has_many :narrowed_products, -> { select(:id, :name, :manufacturer_id) }, class_name: 'Product'
+
+  # Cross-database, and named after neither its target model nor anything else declared here.
+  belongs_to :chief, class_name: 'Driver', foreign_key: :name, primary_key: :firstname,
+             optional: true
 end

data/spec/dummy/app/models/product.rb

@@ -2,5 +2,16 @@ class Product < ApplicationRecord
   belongs_to :manufacturer
   belongs_to :driver, optional: true
 
+  # Same database, but the same shape the serializer intercepts: a primary_key that is not the
+  # target's, plus a scope. Joined rather than preloaded, so it pins that the intercept is about
+  # the declared key, not about crossing a database. On a column of its own: a foreign key is not
+  # a serialized attribute, so keying this on `name` would take `name` off every Product payload
+  # in the suite.
+  belongs_to :maker, -> { where.not(name: 'retired') }, class_name: 'Manufacturer',
+             primary_key: :name, foreign_key: :maker_name, optional: true
+
+  # What a segment scope calling .select does to a relation before any getter sees it.
+  scope :narrowed_select, -> { select(:id, :name) }
+
   validates :uri, presence: true, format: { with: URI::DEFAULT_PARSER.make_regexp }
 end

data/spec/dummy/db/migrate/20260924120000_add_maker_name_to_products.rb

@@ -0,0 +1,5 @@
+class AddMakerNameToProducts < ActiveRecord::Migration[6.0]
+  def change
+    add_column :products, :maker_name, :string
+  end
+end

data/spec/dummy/db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2026_09_22_120000) do
+ActiveRecord::Schema.define(version: 2026_09_24_120000) do
 
   create_table "addresses", force: :cascade do |t|
     t.string "line1"
@@ -75,6 +75,7 @@ ActiveRecord::Schema.define(version: 2026_09_22_120000) do
     t.string "name"
     t.integer "manufacturer_id"
     t.integer "driver_id"
+    t.string "maker_name"
     t.index ["driver_id"], name: "index_products_on_driver_id"
     t.index ["manufacturer_id"], name: "index_products_on_manufacturer_id"
   end