Upgrade to v9.22

• Role permissions are enforced on related data: fields, filters, sorts and searches that reach a collection a role cannot read are refused or redacted, the same way they are on Node.js agents.
• Lists select only the columns the page actually displays, instead of SELECT *.
• Smart fields can declare the columns and relations they need with a new dependencies: option, removing N+1 queries on lists, related lists and CSV exports.
• A collection can disable its record count with countable: false, without overriding a controller.
• belongs_to and has_one relations to another database are preloaded once per page on lists and CSV exports (and on related lists under Rails 6.1), instead of once per row.
• The agent announces its capabilities to the Forest Admin interface, which enables the projection features above and lets the interface adapt to what your agent supports.

​

Upgrading to v9.22

gem 'forest_liana', '~> 9.22.2'

bundle install

​

Deployment order with the Forest Admin interface

• Agent upgraded first: everything described in this note applies immediately on the agent side (permission refusals, redaction, column selection, count deactivation). The interface simply does not use the capabilities yet.
• Interface updated first: your current agent does not serve the capabilities route, so the interface keeps its current behavior until you upgrade.

​

Before you upgrade

​

1. Review the read permissions of your roles

• Listing or counting related records requires the browse permission on the related collection itself, and exporting a related list to CSV requires export on it. A role that could open a parent record and see or export a related list without those permissions will now get a 403 there.
• Associating or updating related records requires edit; dissociating or replacing records that get destroyed requires delete.

​

2. Temporary opt-out: skip_relation_read_permissions

# config/initializers/forest_liana.rb
ForestLiana.skip_relation_read_permissions = true

• Collection-level permissions (browse, read, edit, delete, add, export), including the new browse check on related lists.
• The refusal of paths reaching a collection that is not exposed to Forest Admin.
• Scopes, segments, and smart action permissions.

​

3. Check the read_only: and is_searchable: options of your collections

grep -rn "read_only:\|is_searchable:" lib/forest_liana/collections/

​

4. Check model code that reads columns the page does not display

• after_find and after_initialize callbacks
• to_s or name overrides used as record labels
• default_scope blocks and decorators reading attributes
• Smart actions and route overrides that reuse the records of a list

​

5. Check your search configuration

• A search whose term matches no real column now returns no records instead of the whole table. You are affected if a collection’s search_fields names only smart fields without a search: lambda, or only dotted relation entries used on a plain (non-extended) search. Previously the search silently returned every record.
• A plain search (the default, without “extended search”) no longer joins the related tables to count the results: the count matches what the list actually searches. Collections that keep a smart field search: lambda keep their joins.

​

6. Check the associations you will preload

has_many :notes, -> { select(:content) }
belongs_to :company, -> { select(:name) }

​

7. Check your route and controller overrides

• Permission refusals raise ForestLiana::Ability::Exceptions::UnauthorizedFieldsError, UnauthorizedQueryFieldError and UnexposedQueryCollectionError, rendered as 403. Overrides that rescue only the previous error classes should be extended.
• The record view, bulk delete and the related-data actions now render every other ForestLiana::Errors::ExpectedError themselves, with the error’s own status — as the list and the count already did before this release. A rescue_from ForestLiana::Errors::HTTP422Error (or similar) you added in an override no longer fires for an error raised inside those three — rescue it inside your override, or rely on the status the agent already returns. The three permission classes above are the exception: they are re-raised on purpose, so that their name and data reach the response.
• A filter, sort or projection whose prefix names no relation now answers 422 Relation not found: '<Collection>.<relation>' instead of resolving to the root collection.
• A malformed filter (a raw value instead of a condition tree) answers 422 Filters cannot be a raw value instead of a 500.
• Count overrides that call deactivate_count_response keep working. For a whole collection, countable: false is now simpler (see below).

​

New options you can adopt

​

Disable the count of a collection

class Forest::Order
  include ForestLiana::Collection

  collection :Order, countable: false
end

​

Declare what a smart field needs with dependencies:

class Forest::Customer
  include ForestLiana::Collection

  collection :Customer

  # Bare names are columns of the collection: they are selected with the list.
  field :full_name, type: 'String', dependencies: ['firstname', 'lastname'] do
    "#{object.firstname} #{object.lastname}"
  end

  # `relation:column` paths are preloaded once for the page, whatever the depth.
  field :company_name, type: 'String', dependencies: ['company:name'] do
    object.company.name
  end

  field :city, type: 'String', dependencies: ['address:city:name'] do
    object.address.city.name
  end

  # A to-many relation is preloaded the same way.
  field :order_count, type: 'Number', dependencies: ['orders:id'] do
    object.orders.size
  end

  # An empty list declares a getter that reads nothing from the record.
  field :kind, type: 'String', dependencies: [] do
    'customer'
  end
end

• A list, related list or CSV export that displays the field runs one query per relation of the path instead of one per row.
• The columns named are selected with the list, so the getter reads them without an extra query.

• The field keeps working exactly as before. A request that displays a smart field with no dependencies: keeps the previous SELECT * behavior for that request, and a getter reaching a relation keeps its one-query-per-row cost.
• You can therefore declare your smart fields one at a time, starting with the ones on your largest lists.

• An entry that does not resolve to a real column or relation, or that crosses a polymorphic relation, is ignored with a warning, and the field behaves as if it declared nothing.
• On Rails 6.1, a path crossing an association with an instance-dependent scope cannot be preloaded: it is logged once and loaded per record as before.

​

Projection on records and related data

​

Adapt your code to get the full benefit

class Forest::Customer
  include ForestLiana::Collection

  collection :Customer

  field :company_name, type: 'String' do
    object.company.name
  end
end

class Forest::Customer
  include ForestLiana::Collection

  collection :Customer

  field :company_name, type: 'String', dependencies: ['company:name'] do
    object.company.name
  end
end

class Forest::Customer
  include ForestLiana::Collection

  collection :Customer

  belongs_to :account_manager, reference: 'Employee.id' do
    Employee.find_by(id: object.account_manager_id)
  end
end

class Forest::Customer
  include ForestLiana::Collection

  collection :Customer
end

class Customer < ApplicationRecord
  belongs_to :account_manager, class_name: 'Employee', optional: true
end

class Customer < ApplicationRecord
  belongs_to :account_manager, class_name: 'Employee',
             primary_key: :email, foreign_key: :manager_email,
             optional: true
end

class Customer < ApplicationRecord
  has_many :notes, -> { select(:content) }
  belongs_to :company, -> { select(:name) }
end

class Customer < ApplicationRecord
  has_many :notes, -> { select(:content, :customer_id) }
  belongs_to :company, -> { select(:id, :name) }
end

class Forest::OrdersController < ForestLiana::ResourcesController
  def count
    deactivate_count_response
  end
end

# config/routes.rb, before `mount ForestLiana::Engine => '/forest'`
namespace :forest do
  get '/Order/count', to: 'orders#count'
end

class Forest::Order
  include ForestLiana::Collection

  collection :Order, countable: false
end

​

If you plan to migrate to a v2 agent later

​

Invalid or empty dependencies: fail the agent boot on v2

• an unknown column or relation, or a path crossing a polymorphic relation, raises a schema error and stops the agent;
• an empty list raises Computed field '<Collection>.<field>' must have at least one dependency.

​

A smart field search: lambda is not exempted from permission checks on v2

​

Behavior changes at a glance

​

Logs to watch after deploying

• ForestLiana.skip_relation_read_permissions is true: ... — the opt-out is active. Plan its removal.
• Invalid dependency '...' declared on smart field '...' of the '...' collection: it does not resolve to a real column, or crosses a polymorphic relation. Ignored ... — fix the declaration.
• Invalid dependencies declared on field "...": expected a String, Symbol, or Array of them. Ignored ... — fix the declaration.
• Field "..." of the "..." collection read the "..." column without declaring it in dependencies: — reloaded the record to serve it, at the cost of an extra query. Add it to the field's dependencies: to avoid this. — add the column to dependencies:.
• Cannot retrieve the "..." value of the "..." collection because of an internal error in the getter implementation: ... — the getter could not be served (it raised again after a reload, or read a column of a relation that a reload cannot restore); its value is served as nil.
• The "..." dependency of the "..." collection cannot be preloaded ("..." has an instance-dependent scope, which Rails 6.1.x cannot preload) — the relation is loaded once per record instead ... — expected on Rails 6.1; upgrade Rails to benefit from the preload.
• The "..." relation of the "..." collection lives in another database and cannot be preloaded (its "..." key is not in the projected select) — ... — the cross-database relation shows as empty. Report it to Forest support with the collection and relation names.
• The "..." relation of the "..." collection cannot be preloaded (its "..." key is not in the query's select) — ... — a segment or scope narrows the select of the collection and drops the key the relation reads. Add that key to the select.

​

Rollout recommendation

1. Upgrade in development. Restart the agent and read the startup logs.
2. Go through the Before you upgrade checklist with each role your teams use.
3. Decide whether you set skip_relation_read_permissions for the transition, and record when you will remove it.
4. Deploy to staging, then production, following Push your new version to production.
5. Watch the logs above and the 403/422/500/503 rate of your agent for a few days.
6. Once the upgrade is stable, adapt your code on your heaviest collections.