huginn_datatable 0.1.0

data/lib/huginn/datatable/association_path.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+    # Resolves a multi-segment association chain ("company.people.name") into
+    # the concrete steps (tables, klasses and Arel link conditions) needed to
+    # build:
+    #
+    #   * a subquery for filtering/ranges
+    #     WHERE pk IN (SELECT DISTINCT pk FROM <chain> join ... WHERE ...)
+    #
+    #   * a correlated scalar subquery for ordering
+    #     ORDER BY (SELECT col FROM <chain> join ... WHERE <correlation> ...)
+    #
+    # The link conditions are direction aware: a `belongs_to` puts the FK on
+    # the owner table while `has_many`/`has_one` put it on the child table.
+    # Association scopes are folded in as Arel predicates (never parsed SQL).
+    class AssociationPath
+      Step = Struct.new(:reflection, :klass, :table, :link_to_previous, keyword_init: true)
+
+      attr_reader :segments, :column
+
+      def self.call(model, field)
+        new(model, field)
+      end
+
+      def initialize(model, field)
+        @model = model
+        @segments = field.to_s.split(".")
+        @column = segments.last
+      end
+
+      # The association steps of the chain ("company", "people").
+      def association_names
+        resolved_steps.map { |step| step.reflection.name.to_s }
+      end
+
+      def target_klass
+        resolved_steps.last.klass
+      end
+
+      def target_table
+        resolved_steps.last.table
+      end
+
+      def valid?
+        resolved_steps.present?
+      end
+
+      # The walkable Arel filter/order chain, or nil when invalid.
+      def resolved_steps
+        @steps ||= build_steps
+      end
+
+      # Correlated scalar subquery: ORDER BY (SELECT <col> FROM ... WHERE
+      # <correlation> [AND scope...] ORDER BY <col> ASC LIMIT 1).
+      # Deterministic: the smallest matching value per parent row.
+      def correlated_order_expression
+        steps = resolved_steps
+        return nil unless steps
+
+        manager = Arel::SelectManager.new
+        manager.from(steps.first.table)
+        steps.drop(1).each do |step|
+          manager.join(step.table).on(step.link_to_previous)
+        end
+
+        # The first step correlates the subquery to the outer (base) table.
+        manager.where(steps.first.link_to_previous)
+        scope_predicates.each { |predicate| manager.where(predicate) }
+        manager.project(target_table[column])
+        manager.order(target_table[column].asc)
+        manager.take(1)
+
+        Arel.sql("(#{manager.to_sql})")
+      rescue StandardError
+        nil
+      end
+
+      # Reverse engineers a join spec usable by `ActiveRecord::Relation#joins`
+      # for filter subqueries: `.joins(:people: { company: ... })`.
+      def self.join_spec_for(names)
+        names.reverse.reduce(nil) do |acc, name|
+          acc.nil? ? name.to_sym : { name.to_sym => acc }
+        end
+      end
+
+      private
+
+      attr_reader :model
+
+      def build_steps
+        chain = @segments[0..-2]
+        return nil if chain.empty?
+
+        klass = model
+        previous_table = model.arel_table
+        walked = []
+
+        chain.each do |name|
+          reflection = klass.reflect_on_association(name.to_sym) || table_reflection(klass, name)
+          return nil unless reflection
+
+          decomposed_reflections(reflection).each do |ref|
+            table = ref.klass.arel_table
+            link  = join_link(ref, previous_table)
+            return nil unless link
+
+            walked << Step.new(reflection: ref, klass: ref.klass, table: table, link_to_previous: link)
+            previous_table = table
+            klass = ref.klass
+          end
+        end
+
+        walked
+      end
+
+      # Flattens a through reflection into through + source reflections so the
+      # chain walk stays uniform.
+      def decomposed_reflections(reflection)
+        if reflection.is_a?(ActiveRecord::Reflection::ThroughReflection)
+          [reflection.through_reflection, reflection.source_reflection].compact
+        else
+          [reflection]
+        end
+      end
+
+      # Allows a scoped column to be addressed by its table name instead of
+      # the association name ("companies.name" vs "company.name"), matching
+      # the base model's first reflection that resolves to that table.
+      def table_reflection(klass, name)
+        target = begin
+          name.singularize.camelize.constantize
+        rescue NameError
+          nil
+        end
+        return nil unless target && target < ActiveRecord::Base
+
+        klass.reflect_on_all_associations.find { |ref| ref.klass == target }
+      end
+
+      # Direction aware join condition:
+      #   belongs_to ->   target_table[target_pk] = owner_table[fk]
+      #   has_one/many -> child_table[fk]        = parent_table[parent_pk]
+      def join_link(reflection, previous_table)
+        current = reflection.klass.arel_table
+
+        if reflection.belongs_to?
+          current[reflection.join_primary_key].eq(previous_table[reflection.foreign_key])
+        else
+          current[reflection.foreign_key].eq(previous_table[reflection.active_record_primary_key])
+        end
+      end
+
+      # Association scope (e.g. `has_many :people, -> { where(active: true) }`)
+      # folded into the subquery through its Arel constraints instead of a
+      # parsed WHERE string.
+      def scope_predicates
+        resolved_steps.flat_map do |step|
+          next [] unless step.reflection.scope.is_a?(Proc)
+
+          relation = step.klass.instance_exec(&step.reflection.scope)
+          relation.instance_of?(ActiveRecord::Relation) ? relation.arel.constraints : []
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/huginn/datatable/datatable.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :huginn_attribute_mapping, default: nil
+      class_attribute :huginn_strict_mapping, default: false
+    end
+
+    class_methods do
+      # Executes a datatable request in two phases:
+      #
+      #   phase 1  filtering & ordering built on join-subqueries and scalar
+      #            correlated subqueries (never joins/loads data on the
+      #            base relation)
+      #   phase 2  lean count, pagination and preload of the small subset
+      #
+      # Association scoped fields are resolved as subqueries against the
+      # primary key, so the base relation stays flat and the count is
+      # lightweight. `allowed_paths` is a strict allowlist of the association
+      # chains that may be filtered/ordered/ranged — anything else is
+      # silently ignored.
+      #
+      # @param params [ActionController::Parameters, Hash] keys: :page,
+      #   :per_page, :search, :filters, :range_data and :orders
+      # @option allowed_paths [Array<Symbol, String, Hash>] strict allowlist of
+      #   association chains for filtering/ordering/ranges (deny-all by default)
+      # @option includes [Array<Symbol, Hash>] associations preloaded only on
+      #   the final paginated subset (keeps queries lightweight)
+      #
+      # @return [Hash] { total_count: Integer, data: ActiveRecord::Relation }
+      def datatable(params, allowed_paths: [], includes: [])
+        relation = datatable_relation(params, allowed_paths: allowed_paths)
+        Paginator.call(relation, params, includes: includes)
+      end
+
+      # Builds the filtered/ordered relation. Kept public so callers can
+      # compose it with their own relation (e.g. tenant scoping) before
+      # pagination.
+      def datatable_relation(params, allowed_paths: [])
+        allowlist = effective_allowed_paths(allowed_paths)
+        relation = all
+
+        relation = apply_datatable_search(relation, params[:search])
+        relation = apply_datatable_filters(relation, params, allowlist)
+        relation = apply_datatable_order(relation, params[:orders], allowlist)
+
+        relation
+      end
+
+      # Declares the public API names that map to real columns (or
+      # association-scoped columns), hiding the database schema.
+      #
+      #   huginn_attributes name: "users.name",
+      #                     company_name: "companies.name"
+      #
+      # When `strict:` is true (default), fields not present in the mapping
+      # are rejected — API callers can only filter/order by the aliases.
+      # Without a mapping the model falls back to plain/reflected columns.
+      # Accepts a positional Hash or keyword arguments.
+      def huginn_attributes(mapping = nil, strict: true, **aliases)
+        merged = (mapping || {}).merge(aliases)
+        self.huginn_attribute_mapping = merged.map { |key, value| [key.to_s, value.to_s] }.to_h
+        self.huginn_strict_mapping = strict
+        huginn_attribute_mapping
+      end
+
+      private
+
+      def apply_datatable_search(relation, value)
+        return relation if value.blank? || !respond_to?(:search)
+
+        relation.merge(search(value, distinct: false))
+      end
+
+      def apply_datatable_filters(relation, params, allowed)
+        filters = FilterNormalizer.call(params[:filters])
+        filters.each do |field, values|
+          relation = apply_datatable_filter(relation, field, values, allowed)
+        end
+
+        each_range_data(params[:range_data]) do |field, value|
+          relation = apply_datatable_range(relation, field, value, allowed)
+        end
+
+        relation
+      end
+
+      def apply_datatable_filter(relation, field, values, allowed)
+        validator = Validator.call(self, field)
+        return relation unless authorized_validator?(validator, allowed)
+
+        if validator.plain?
+          apply_plain_filter(relation, validator, Array(values))
+        else
+          apply_scoped_filter(relation, validator, Array(values))
+        end
+      end
+
+      def apply_plain_filter(relation, validator, values)
+        attr = validator.arel_attribute
+        return relation if attr.nil?
+
+        if values.include?("null")
+          apply_nullable_predicate(relation, attr, values)
+        elsif values.size == 1
+          relation.where(attr.eq(values.first))
+        else
+          relation.where(attr.in(values))
+        end
+      end
+
+      # Scoped filters run as: WHERE <base PK> IN (
+      #   SELECT DISTINCT <base PK> FROM <chain> JOIN ... WHERE <target> IN ...)
+      def apply_scoped_filter(relation, validator, values)
+        subquery = association_ids_subquery(relation, validator)
+        return relation unless subquery
+
+        attr   = validator.arel_attribute
+        target = if values.include?("null")
+                   apply_nullable_predicate(subquery, attr, values)
+                 elsif values.size == 1
+                   subquery.where(attr.eq(values.first))
+                 else
+                   subquery.where(attr.in(values))
+                 end
+
+        relation.where(primary_key => target)
+      end
+
+      # A subquery over the same base relation (keeps tenant scoping) that
+      # selects DISTINCT pk while joining the association chain of the field.
+      def association_ids_subquery(relation, validator)
+        chain = validator.authorization_path
+        return nil if chain.empty?
+
+        spec = AssociationPath.join_spec_for(chain.map(&:to_sym))
+        base = relation.except(:select, :order, :offset, :limit)
+                        .select(arel_table[primary_key])
+                        .distinct
+        base.joins(spec)
+      end
+
+      def apply_datatable_range(relation, field, value, allowed)
+        values = Array(value)
+        return relation if field.blank? || values.size < 2
+
+        validator = Validator.call(self, field)
+        return relation unless authorized_validator?(validator, allowed) && validator.valid?
+
+        from, to = values[0], values[1]
+        return relation if from.blank? && to.blank?
+
+        if validator.plain?
+          attr = validator.arel_attribute
+          apply_range_predicate(relation, attr, from, to, validator.column_type)
+        else
+          apply_scoped_range(relation, validator, from, to)
+        end
+      end
+
+      def apply_scoped_range(relation, validator, from, to)
+        subquery = association_ids_subquery(relation, validator)
+        return relation unless subquery
+
+        attr = validator.arel_attribute
+        target = apply_range_predicate(subquery, attr, from, to, validator.column_type)
+        relation.where(primary_key => target)
+      end
+
+      def apply_range_predicate(relation, attr, from, to, type)
+        if numeric_column?(type)
+          from = to_numeric(from)
+          to   = to_numeric(to)
+          return relation if from.nil? && to.nil?
+
+          predicate = range_predicate(attr, from, to)
+          relation.where(predicate)
+        else
+          from = parse_datatable_date(from)
+          to   = parse_datatable_date(to)
+          return relation if from.blank? && to.blank?
+
+          relation.where(range_predicate(attr, from, to))
+        end
+      end
+
+      def range_predicate(attr, from, to)
+        if from && to
+          attr.between(from..to)
+        elsif from
+          attr.gteq(from)
+        else
+          attr.lteq(to)
+        end
+      end
+
+      def numeric_column?(type)
+        %i[integer decimal float].include?(type)
+      end
+
+      def to_numeric(value)
+        value.to_f if value.present?
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def apply_nullable_predicate(relation, attr, values)
+        non_null = values.reject { |value| value == "null" }
+        predicate = if non_null.empty?
+                      attr.eq(nil)
+                    elsif non_null.size == 1
+                      attr.eq(non_null.first).or(attr.eq(nil))
+                    else
+                      attr.in(non_null).or(attr.eq(nil))
+                    end
+        relation.where(predicate)
+      end
+
+      def apply_datatable_order(relation, orders, allowed)
+        return relation if orders.blank?
+
+        Array(orders).compact.each do |item|
+          next unless item.respond_to?(:each_pair)
+
+          item.each_pair do |field, direction|
+            validator = Validator.call(self, field)
+            next unless authorized_validator?(validator, allowed)
+
+            expression = if validator.plain?
+                           validator.arel_attribute
+                         else
+                           validator.correlated_order_expression
+                         end
+            next if expression.nil?
+
+            ordering = normalized_direction(direction) == "desc" ? expression.desc : expression.asc
+            relation = relation.order(ordering)
+          end
+        end
+
+        relation
+      end
+
+      def normalized_direction(direction)
+        %w[asc desc].include?(direction.to_s.downcase) ? direction.to_s.downcase : "asc"
+      end
+
+      def authorized_validator?(validator, allowed)
+        return false unless validator.valid?
+        return true if validator.plain?
+
+        chain = validator.authorization_path
+        !chain.empty? && allowed.include?(chain)
+      end
+
+      # The allowlist, merged with the association chains reached by the
+      # model's declared `huginn_attributes`, so declared aliases keep working
+      # under strict authorization.
+      def effective_allowed_paths(spec)
+        allowed = AllowedPaths.call(self, spec)
+        each_huginn_alias_path do |path|
+          allowed.include_path(path)
+        end
+        allowed
+      end
+
+      def each_huginn_alias_path
+        return unless respond_to?(:huginn_attribute_mapping) && huginn_attribute_mapping.present?
+
+        huginn_attribute_mapping.each_value do |target|
+          segments = target.to_s.split(".")
+          yield segments[0..-2] if segments.size >= 2
+        end
+      end
+
+      def each_range_data(range_data)
+        return if range_data.blank?
+
+        case range_data
+        when ActionController::Parameters, Hash
+          range_data.each_pair { |field, value| yield(field, value) }
+        when Array
+          range_data.each do |item|
+            case item
+            when ActionController::Parameters, Hash
+              item.each_pair { |field, value| yield(field, value) }
+            when Array
+              field, value = item
+              yield(field, value) if field
+            end
+          end
+        end
+      end
+
+      def parse_datatable_date(value)
+        return nil if value.blank?
+        return value.to_date if value.respond_to?(:to_date)
+
+        Date.parse(value.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/huginn/datatable/filter_normalizer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+    # Normalizes the heterogeneous filter payloads sent by frontends
+    # (ActionController::Parameters, Hash, Array of hashes, [key, value]
+    # pairs, ...) into a single Hash of { column => Array(values) }.
+    #
+    # Values are accumulated in arrays so that repeated keys produce an
+    # IN condition when applied as a datatable filter. Invalid payload
+    # shapes are simply ignored, and keys are normalized to strings.
+    class FilterNormalizer
+      def self.call(raw)
+        new(raw).call
+      end
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      def call
+        each_pair(@raw).each_with_object({}) do |(key, value), acc|
+          (acc[key.to_s] ||= []) << value
+        end
+      end
+
+      private
+
+      def each_pair(raw, &block)
+        return enum_for(:each_pair, raw) unless block
+
+        case raw
+        when ActionController::Parameters
+          raw.to_unsafe_h.each { |key, value| block.call(key, value) }
+        when Hash
+          raw.each { |key, value| block.call(key, value) }
+        when Array
+          if pair?(raw)
+            block.call(raw.first, raw.last)
+          else
+            raw.each { |item| each_pair(item) { |key, value| block.call(key, value) } }
+          end
+        end
+      end
+
+      # A two-element array whose first element is a key (String/Symbol)
+      # is treated as a single [key, value] pair rather than a list.
+      def pair?(array)
+        array.size == 2 && (array.first.is_a?(String) || array.first.is_a?(Symbol))
+      end
+    end
+  end
+end

data/lib/huginn/datatable/paginator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "pagy"
+
+module Huginn
+  module Datatable
+    # Splits datatable execution into two phases:
+    #
+    #   1. build the filtered/ordered relation
+    #   2. count lean, paginate with Pagy, then preload associations only
+    #      on the small paginated subset.
+    #
+    # The count runs against a stripped relation (no select/includes/order/
+    # offset/limit) selecting only the primary key with DISTINCT, so that
+    # PostgreSQL answers it through the PK index as a subquery instead of a
+    # massive COUNT(DISTINCT ...) over the joins.
+    class Paginator
+      attr_reader :relation, :params, :includes
+
+      def self.call(relation, params, includes: [])
+        new(relation, params, includes: includes).call
+      end
+
+      def initialize(relation, params, includes: [])
+        @relation = relation
+        @params = params
+        @includes = Array(includes).compact
+      end
+
+      def call
+        pagy = build_pagy
+        data = relation.offset(pagy.offset).limit(limit_for(pagy))
+        data = data.preload(*includes) if includes.any?
+
+        { total_count: pagy.count, data: data }
+      end
+
+      private
+
+      def build_pagy
+        page = params.fetch(:page, 1).to_i
+        items = params.fetch(:per_page, nil).presence || config.pagy_items
+        items = items.to_i
+        items = config.pagy_max_items if items > config.pagy_max_items
+        items = 1 if items < 1
+        page = 1 if page < 1
+
+        if offset_api?
+          ::Pagy::Offset.new(count: total_count, page: page, limit: items)
+        elsif items_keyword?
+          ::Pagy.new(count: total_count, page: page, items: items)
+        else
+          ::Pagy.new(count: total_count, page: page, limit: items)
+        end
+      end
+
+      # Pagy >= 43 exposes the dedicated `Pagy::Offset` class that speaks
+      # `limit:`. Releases 6..9 carry the legacy `Pagy.new(count:page:items:)`
+      # interface instead.
+      def offset_api?
+        defined?(::Pagy::Offset)
+      end
+
+      # Pagy 6..8 accept the page size through the `items:` constructor key and
+      # expose it through `#items`. Pagy 9 restructured the constructors, but
+      # the early 9.x releases keep `Pagy.new` keyed on `limit:`. Probe the
+      # live constructor instead of guessing by version number.
+      def items_keyword?
+        sample = ::Pagy.new(count: 100, page: 1, items: 7)
+        sample.respond_to?(:items) && sample.items == 7
+      rescue StandardError
+        false
+      end
+
+      def limit_for(pagy)
+        pagy.respond_to?(:limit) ? pagy.limit : pagy.items
+      end
+
+      def total_count
+        stripped = relation.except(:select, :includes, :order, :offset, :limit)
+        return stripped.count unless stripped.left_outer_joins_values.any? || stripped.joins_values.any?
+
+        stripped.select(stripped.arel_table[stripped.primary_key]).distinct.count
+      end
+
+      def config
+        Huginn.configuration
+      end
+    end
+  end
+end