iron_admin 0.5.0 → 0.6.0

data/lib/iron_admin/adapters/active_record.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    # ActiveRecord adapter — wraps AR's APIs behind the standard adapter interface.
+    #
+    # This is the default adapter used by all resources unless overridden.
+    # It delegates to ActiveRecord's column introspection, reflection system,
+    # query interface, and CRUD operations.
+    class ActiveRecord < Base
+      # --- Schema Introspection ---
+
+      delegate :columns, to: :model_class
+
+      delegate :column_names, to: :model_class
+
+      delegate :primary_key, to: :model_class
+
+      def has_column?(name) # rubocop:disable Naming/PredicatePrefix
+        model_class.column_names.include?(name.to_s)
+      end
+
+      def enums
+        return {} unless model_class.respond_to?(:defined_enums)
+
+        model_class.defined_enums
+      end
+
+      def associations(kind = nil)
+        if kind
+          model_class.reflect_on_all_associations(kind)
+        else
+          model_class.reflect_on_all_associations
+        end
+      end
+
+      def association(name)
+        model_class.reflect_on_association(name)
+      end
+
+      def attachments
+        return {} unless model_class.respond_to?(:attachment_reflections)
+
+        model_class.attachment_reflections
+      end
+
+      def rich_text_attributes
+        return [] unless model_class.respond_to?(:rich_text_association_names)
+
+        model_class.rich_text_association_names
+      end
+
+      def polymorphic_inverse_classes(polymorphic_name)
+        eager_load_model_paths
+
+        application_record_descendants.filter_map do |klass|
+          next if klass.abstract_class?
+          next unless klass.base_class == klass
+
+          klass if polymorphic_inverse?(klass, polymorphic_name)
+        end
+      end
+
+      # --- Naming ---
+
+      delegate :table_name, to: :model_class
+
+      # --- Query Building ---
+
+      delegate :all, to: :model_class
+
+      def find(id)
+        model_class.find(id)
+      rescue ::ActiveRecord::RecordNotFound => e
+        raise IronAdmin::RecordNotFound, e.message
+      end
+
+      delegate :find_by, to: :model_class
+
+      def filter(scope, column, value)
+        scope.where(column => value)
+      end
+
+      def order_by(scope, column, direction)
+        scope.order(column => direction)
+      end
+
+      def limit(scope, max)
+        scope.limit(max)
+      end
+
+      def preload(scope, association_names)
+        scope.includes(*association_names)
+      end
+
+      def distinct_values(column)
+        model_class.distinct.pluck(column).compact.sort
+      end
+
+      def pluck(scope, column)
+        scope.pluck(column)
+      end
+
+      def count(scope = nil)
+        scope ||= all
+        scope.count
+      end
+
+      # --- Search ---
+
+      def search_column(scope, column, query)
+        table = quoted_table_name
+        col = connection.quote_column_name(column)
+        scope.where("#{table}.#{col} #{like_operator} ? #{like_escape_clause}", "%#{sanitize_like(query)}%")
+      end
+
+      def search_columns(scope, columns, query)
+        table = quoted_table_name
+        conditions = columns.map do |col|
+          "#{table}.#{connection.quote_column_name(col)} #{like_operator} :q #{like_escape_clause}"
+        end
+        scope.where(conditions.join(" OR "), q: "%#{sanitize_like(query)}%")
+      end
+
+      # --- CRUD ---
+
+      def build(attrs = {})
+        model_class.new(attrs)
+      end
+
+      def save(record)
+        record.save
+      end
+
+      def update(record, attrs)
+        record.update(attrs)
+      end
+
+      def destroy!(record)
+        record.destroy!
+      end
+
+      # --- Scope Manipulation ---
+
+      def unscope_column(scope, column)
+        scope.unscope(where: column.to_sym)
+      end
+
+      # --- Transactions ---
+
+      def transaction(&)
+        ::ActiveRecord::Base.transaction(&)
+      end
+
+      # --- Batch ---
+
+      def find_each(scope, &)
+        scope.find_each(&)
+      end
+
+      # --- Adapter-Agnostic Interface ---
+
+      def record_changes(record)
+        record.saved_changes
+      end
+
+      def wrap_rollback
+        yield
+      rescue IronAdmin::Rollback
+        raise ::ActiveRecord::Rollback
+      end
+
+      def query_builder_class
+        IronAdmin::Filters::ActiveRecordQueryBuilder
+      end
+
+      def pagy_method
+        :pagy
+      end
+
+      def cast_boolean(value)
+        ::ActiveModel::Type::Boolean.new.cast(value)
+      end
+
+      private
+
+      def connection
+        model_class.connection
+      end
+
+      def quoted_table_name
+        connection.quote_table_name(model_class.table_name)
+      end
+
+      def postgresql?
+        connection.adapter_name.downcase.include?("postgresql")
+      end
+
+      def like_operator
+        postgresql? ? "ILIKE" : "LIKE"
+      end
+
+      def like_escape_clause
+        "ESCAPE '\\'"
+      end
+
+      def sanitize_like(value)
+        value.to_s.gsub(/[%_\\]/) { |match| "\\#{match}" }
+      end
+
+      def eager_load_model_paths
+        return unless defined?(::Rails) && ::Rails.respond_to?(:autoloaders)
+
+        Array(::Rails.application.config.eager_load_paths).each do |path|
+          next unless path.to_s.end_with?("/app/models")
+          next unless File.directory?(path)
+
+          ::Rails.autoloaders.main.eager_load_dir(path)
+        end
+      end
+
+      def application_record_descendants
+        return [] unless defined?(::ApplicationRecord)
+
+        ::ApplicationRecord.descendants
+      end
+
+      def polymorphic_inverse?(klass, polymorphic_name)
+        %i[has_many has_one].any? do |macro|
+          klass.reflect_on_all_associations(macro).any? do |reflection|
+            reflection.options[:as]&.to_sym == polymorphic_name.to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iron_admin/adapters/base.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    # Abstract base class defining the interface every data source adapter must implement.
+    #
+    # IronAdmin uses this interface to introspect schemas, build queries, perform CRUD
+    # operations, and search records. The default {ActiveRecord} adapter wraps Rails'
+    # ActiveRecord ORM. Future adapters (Mongoid, HTTP, etc.) implement this same interface.
+    #
+    # @abstract Subclass and implement all methods to create a custom adapter.
+    class Base
+      # @return [Class] The underlying model/data class this adapter wraps
+      attr_reader :model_class
+
+      # @param model_class [Class] The model class to wrap
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      # --- Schema Introspection ---
+
+      # Returns column descriptors for the model.
+      # @return [Array<#name, #type>] Objects responding to .name (String) and .type (Symbol)
+      def columns
+        raise NotImplementedError
+      end
+
+      # Returns column name strings.
+      # @return [Array<String>]
+      def column_names
+        raise NotImplementedError
+      end
+
+      # Checks if a column exists.
+      # @param name [Symbol, String] Column name
+      # @return [Boolean]
+      def has_column?(_name) # rubocop:disable Naming/PredicatePrefix
+        raise NotImplementedError
+      end
+
+      # Returns enum definitions.
+      # @return [Hash{String => Hash}] Enum name to values mapping
+      def enums
+        raise NotImplementedError
+      end
+
+      # Returns association descriptors.
+      # @param kind [Symbol, nil] Filter by :belongs_to, :has_many, :has_one, :has_and_belongs_to_many
+      # @return [Array<#name, #klass, #foreign_key, #polymorphic?>]
+      def associations(_kind = nil)
+        raise NotImplementedError
+      end
+
+      # Returns a single association descriptor by name.
+      # @param name [Symbol] Association name
+      # @return [#name, #klass, #foreign_key, nil]
+      def association(_name)
+        raise NotImplementedError
+      end
+
+      # Returns ActiveStorage attachment descriptors.
+      # @return [Hash] Attachment name to reflection mapping
+      def attachments
+        raise NotImplementedError
+      end
+
+      # Returns ActionText rich text attribute names.
+      # @return [Array<Symbol>]
+      def rich_text_attributes
+        raise NotImplementedError
+      end
+
+      # Returns model/document classes that declare an inverse association for
+      # a polymorphic belongs_to name.
+      # @param _polymorphic_name [Symbol]
+      # @return [Array<Class>]
+      def polymorphic_inverse_classes(_polymorphic_name)
+        []
+      end
+
+      # --- Naming ---
+
+      # URL-friendly plural resource name (e.g., "users").
+      # Uses ActiveModel::Naming (available on both AR and Mongoid models).
+      # @return [String]
+      def resource_name
+        model_class.model_name.plural
+      end
+
+      # Human-readable model name (e.g., "User").
+      # Uses ActiveModel::Naming (available on both AR and Mongoid models).
+      # @return [String]
+      def human_name
+        model_class.model_name.human
+      end
+
+      # Database table name (or nil for non-SQL backends).
+      # @return [String, nil]
+      def table_name
+        raise NotImplementedError
+      end
+
+      # Primary key column name(s) for the underlying model.
+      # Returns a String for single-column keys (e.g. `"id"`, `"slug"`) and an
+      # Array<String> for composite keys (e.g. `["account_id", "scope_id"]`).
+      # @return [String, Array<String>]
+      def primary_key
+        "id"
+      end
+
+      # --- Query Building ---
+
+      # Returns a base scope/collection of all records.
+      # @return [Object] A chainable query object
+      def all
+        raise NotImplementedError
+      end
+
+      # Finds a record by primary key.
+      # @param id [Integer, String] The record ID
+      # @return [Object] The record
+      def find(_id)
+        raise NotImplementedError
+      end
+
+      # Finds a record by attributes.
+      # @param attrs [Hash] Attribute conditions
+      # @return [Object, nil] The record or nil
+      def find_by(_attrs)
+        raise NotImplementedError
+      end
+
+      # Finds a record by a configured import key.
+      # @param attrs [Hash] Attribute conditions
+      # @return [Object, nil]
+      def find_by_keys(attrs)
+        find_by(attrs)
+      end
+
+      # Filters a scope by a column value.
+      # @param scope [Object] The current query scope
+      # @param column [Symbol] Column name
+      # @param value [Object] Filter value
+      # @return [Object] Filtered scope
+      def filter(_scope, _column, _value)
+        raise NotImplementedError
+      end
+
+      # Orders a scope by column and direction.
+      # @param scope [Object] The current query scope
+      # @param column [Symbol, String] Column name
+      # @param direction [Symbol] :asc or :desc
+      # @return [Object] Ordered scope
+      def order_by(_scope, _column, _direction)
+        raise NotImplementedError
+      end
+
+      # Limits a scope to N records.
+      # @param scope [Object] The current query scope
+      # @param max [Integer] Max records
+      # @return [Object] Limited scope
+      def limit(_scope, _max)
+        raise NotImplementedError
+      end
+
+      # Eager loads associations on a scope.
+      # @param scope [Object] The current query scope
+      # @param association_names [Array<Symbol>] Associations to preload
+      # @return [Object] Scope with preloading
+      def preload(_scope, _association_names)
+        raise NotImplementedError
+      end
+
+      # Returns distinct values for a column.
+      # @param column [Symbol, String] Column name
+      # @return [Array] Sorted unique values
+      def distinct_values(_column)
+        raise NotImplementedError
+      end
+
+      # Extracts a single column from a scope.
+      # @param scope [Object] The current query scope
+      # @param column [Symbol] Column name
+      # @return [Array] Column values
+      def pluck(_scope, _column)
+        raise NotImplementedError
+      end
+
+      # Returns record count for a scope.
+      # @return [Integer]
+      def count(_scope = nil)
+        raise NotImplementedError
+      end
+
+      # --- Search ---
+
+      # Searches a single column with LIKE/ILIKE.
+      # @param scope [Object] The current query scope
+      # @param column [Symbol, String] Column to search
+      # @param query [String] Search term
+      # @return [Object] Filtered scope
+      def search_column(_scope, _column, _query)
+        raise NotImplementedError
+      end
+
+      # Searches multiple columns with OR logic.
+      # @param scope [Object] The current query scope
+      # @param columns [Array<Symbol>] Columns to search
+      # @param query [String] Search term
+      # @return [Object] Filtered scope
+      def search_columns(_scope, _columns, _query)
+        raise NotImplementedError
+      end
+
+      # --- CRUD ---
+
+      # Builds a new unsaved record.
+      # @param attrs [Hash] Initial attributes
+      # @return [Object] New record
+      def build(_attrs = {})
+        raise NotImplementedError
+      end
+
+      # Persists a record.
+      # @param record [Object] The record to save
+      # @return [Boolean] Success
+      def save(_record)
+        raise NotImplementedError
+      end
+
+      # Updates a record's attributes.
+      # @param record [Object] The record
+      # @param attrs [Hash] New attributes
+      # @return [Boolean] Success
+      def update(_record, _attrs)
+        raise NotImplementedError
+      end
+
+      # Builds and persists a record, returning the record with validation errors if any.
+      # @param attrs [Hash] Attributes for the new record
+      # @return [Object]
+      def create_record(attrs)
+        record = build(attrs)
+        save(record)
+        record
+      end
+
+      # Updates a record and returns true when persistence succeeds.
+      # @param record [Object] The record
+      # @param attrs [Hash] New attributes
+      # @return [Boolean]
+      def update_record(record, attrs)
+        update(record, attrs)
+      end
+
+      # Destroys a record.
+      # @param record [Object] The record
+      # @return [void]
+      def destroy!(_record)
+        raise NotImplementedError
+      end
+
+      # --- Transactions ---
+
+      # Wraps a block in a transaction.
+      # @yield The block to run atomically
+      # @return [Object] Block return value
+      def transaction(&)
+        raise NotImplementedError
+      end
+
+      # --- Scope Manipulation ---
+
+      # Removes a WHERE condition on a specific column from a scope.
+      # @param scope [Object] The current query scope
+      # @param column [Symbol] Column to unscope
+      # @return [Object] Scope without the column condition
+      def unscope_column(_scope, _column)
+        raise NotImplementedError
+      end
+
+      # --- Batch ---
+
+      # Iterates records in memory-efficient batches.
+      # @param scope [Object] The current query scope
+      # @yield [record] Each record
+      # @return [void]
+      def find_each(_scope, &)
+        raise NotImplementedError
+      end
+
+      # --- Adapter-Agnostic Interface ---
+
+      # Returns the changes hash after a save/update.
+      # @param record [Object] The record
+      # @return [Hash] Changed attributes
+      def record_changes(_record)
+        raise NotImplementedError
+      end
+
+      # Executes a block, converting IronAdmin::Rollback to the adapter-native rollback.
+      # @yield The block to run
+      # @return [void]
+      def wrap_rollback(&)
+        raise NotImplementedError
+      end
+
+      # Returns the query builder class for operator-based filters.
+      # @return [Class] A QueryBuilder subclass
+      def query_builder_class
+        raise NotImplementedError
+      end
+
+      # Returns the Pagy backend method name for this adapter.
+      # @return [Symbol] :pagy or :pagy_mongoid
+      def pagy_method
+        raise NotImplementedError
+      end
+
+      # Casts a string value to a boolean.
+      # Default implementation for non-AR adapters.
+      # ActiveRecord overrides to use ActiveModel::Type::Boolean.
+      # @param value [String] The value to cast
+      # @return [Boolean]
+      TRUTHY_VALUES = %w[true 1 yes].freeze
+
+      def cast_boolean(value) # rubocop:disable Naming/PredicateMethod
+        TRUTHY_VALUES.include?(value.to_s.downcase)
+      end
+
+      # Shared column descriptor for non-AR adapters.
+      ColumnDescriptor = Struct.new(:name, :type) do
+        def to_s
+          name
+        end
+      end
+    end
+  end
+end

data/lib/iron_admin/adapters/http/column_descriptor.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Uses the shared ColumnDescriptor from Adapters::Base.
+      ColumnDescriptor = IronAdmin::Adapters::Base::ColumnDescriptor
+    end
+  end
+end

data/lib/iron_admin/adapters/http/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Configuration for an HTTP resource's API connection.
+      #
+      # Stores base URL, resource path, and headers.
+      # Each HTTP resource can override the global configuration.
+      class Configuration
+        attr_accessor :base_url, :resource_path, :headers
+
+        def initialize
+          @base_url = nil
+          @resource_path = nil
+          @headers = {}
+        end
+
+        def full_url
+          base = @base_url&.chomp("/") || ""
+          path = @resource_path&.start_with?("/") ? @resource_path : "/#{@resource_path}"
+          "#{base}#{path}"
+        end
+      end
+    end
+  end
+end