iron_admin 0.5.0 → 0.6.0

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Wraps Faraday for HTTP communication with REST APIs.
+      #
+      # Handles request building, response parsing, auth headers,
+      # and error mapping to IronAdmin exceptions.
+      class Connection
+        def initialize(config)
+          @config = config
+          @base_url = config.full_url
+        end
+
+        def get(params: {})
+          response = safe_request { faraday.get(@base_url, params) }
+          handle_errors(response)
+          parse_collection(response)
+        end
+
+        def get_one(id)
+          response = safe_request { faraday.get("#{@base_url}/#{id}") }
+          handle_errors(response)
+          parse_json(response.body)
+        end
+
+        def post(attrs)
+          response = safe_request do
+            faraday.post(@base_url) do |req|
+              req.headers["Content-Type"] = "application/json"
+              req.body = attrs.to_json
+            end
+          end
+          handle_errors(response)
+          parse_json(response.body)
+        end
+
+        def patch(id, attrs)
+          response = safe_request do
+            faraday.patch("#{@base_url}/#{id}") do |req|
+              req.headers["Content-Type"] = "application/json"
+              req.body = attrs.to_json
+            end
+          end
+          handle_errors(response)
+          parse_json(response.body)
+        end
+
+        def delete(id)
+          response = safe_request { faraday.delete("#{@base_url}/#{id}") }
+          handle_errors(response)
+        end
+
+        private
+
+        def faraday
+          @faraday ||= begin
+            require "faraday"
+            Faraday.new do |conn|
+              @config.headers.each { |key, value| conn.headers[key] = value }
+              conn.adapter Faraday.default_adapter
+            end
+          rescue LoadError
+            raise IronAdmin::AdapterError,
+                  "Faraday is required for the HTTP adapter. Add `gem 'faraday'` to your Gemfile."
+          end
+        end
+
+        def safe_request
+          yield
+        rescue StandardError => e
+          raise IronAdmin::AdapterError, "HTTP request failed: #{e.message}" if network_error?(e)
+
+          raise
+        end
+
+        def network_error?(error)
+          return true if defined?(Faraday::Error) && error.is_a?(Faraday::Error)
+
+          [Errno::ECONNREFUSED, SocketError, Timeout::Error, IOError].any? { |klass| error.is_a?(klass) }
+        end
+
+        def handle_errors(response)
+          case response.status
+          when 200..299, 422 then nil # 422 validation errors handled by caller
+          when 404 then raise IronAdmin::RecordNotFound, "Record not found (HTTP 404)"
+          else raise IronAdmin::AdapterError, "HTTP #{response.status}: #{response.body}"
+          end
+        end
+
+        def parse_collection(response)
+          body = parse_json(response.body)
+
+          case body
+          when Array
+            { data: body, total: nil }
+          when Hash
+            data = body["data"] || body
+            total = body.dig("meta", "total")
+            { data: data.is_a?(Array) ? data : [data], total: total }
+          else
+            { data: [], total: nil }
+          end
+        end
+
+        def parse_json(body)
+          return nil if body.blank?
+
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "active_model/naming"
+
+module IronAdmin
+  module Adapters
+    class Http < Base
+      # Lightweight stand-in for a Ruby model class when a Resource uses
+      # the HTTP adapter. The HTTP adapter pulls fields from the remote
+      # API at request time, so there's no Ruby model to introspect — but
+      # `Resource.adapter` still needs an object that responds to the
+      # minimal `ActiveModel::Naming` interface (`.model_name.plural`,
+      # `.model_name.human`) so URLs and labels work.
+      #
+      # The proxy is built from the resource class name:
+      # `IronAdmin::Resources::ExternalCustomerResource` →
+      # `model_name.plural = "external_customers"`,
+      # `model_name.human = "External customer"`.
+      #
+      # @example
+      #   IronAdmin::Adapters::Http::ModelProxy.new(MyResource).model_name.plural
+      #   #=> "my_resources"
+      class ModelProxy
+        # @return [Class] The Resource class this proxy stands in for.
+        attr_reader :resource_class
+
+        # @param resource_class [Class] The IronAdmin::Resource subclass.
+        def initialize(resource_class)
+          @resource_class = resource_class
+        end
+
+        # ActiveModel::Naming-compatible name object derived from the
+        # resource class name.
+        #
+        # @return [ActiveModel::Name]
+        def model_name
+          @model_name ||= ActiveModel::Name.new(self, nil, demodulized_name)
+        end
+
+        # HTTP resources have no Ruby-side schema; columns are discovered
+        # from the first API response. Return an empty list so any
+        # column-introspection checks (e.g. soft-delete detection) decide
+        # the column is absent rather than crashing.
+        #
+        # @return [Array<String>]
+        def column_names
+          []
+        end
+
+        # Mirror `Class#name` so anything logging the model class doesn't
+        # show `#<Adapters::Http::ModelProxy:0x...>`.
+        #
+        # @return [String]
+        def name
+          demodulized_name
+        end
+
+        alias to_s name
+
+        private
+
+        # Strips `IronAdmin::Resources::` and the trailing `Resource`
+        # suffix to mirror what `Resource.model` would return for an
+        # ActiveRecord-backed resource (e.g. `ExternalCustomer`).
+        #
+        # @return [String]
+        def demodulized_name
+          @demodulized_name ||= resource_class.name
+            .sub(/\AIronAdmin::Resources::/, "")
+            .sub(/Resource\z/, "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Chainable lazy query object for HTTP API resources.
+      #
+      # Accumulates filters, ordering, limit, and offset as parameters.
+      # Only fires an HTTP request when records are actually needed
+      # (via #each, #count, #first, #map, etc.).
+      #
+      # Implements the interface that IronAdmin controllers and Pagy expect:
+      # .count, .offset(n), .limit(n), .first, .map, .each, .merge
+      class Query
+        include Enumerable
+
+        def initialize(connection, params: {}, offset_value: nil, limit_value: nil, sort_params: {})
+          @connection = connection
+          @params = params.dup
+          @offset_value = offset_value
+          @limit_value = limit_value
+          @sort_params = sort_params.dup
+          @fetched = false
+          @records = nil
+          @total = nil
+        end
+
+        def each(&block)
+          return to_enum(:each) unless block
+
+          fetch!
+          @records.each(&block)
+        end
+
+        def count
+          fetch!
+          @total || @records.length
+        end
+
+        def first
+          fetch!
+          @records.first
+        end
+
+        def empty?
+          fetch!
+          @records.empty?
+        end
+
+        def where(conditions = {})
+          dup_with(params: @params.merge(conditions))
+        end
+
+        def offset(value)
+          dup_with(offset_value: value)
+        end
+
+        def limit(value)
+          dup_with(limit_value: value)
+        end
+
+        def order(sort_hash)
+          dup_with(sort_params: @sort_params.merge(sort_hash))
+        end
+
+        def merge(other)
+          return dup_with unless other.is_a?(Query)
+
+          dup_with(params: @params.merge(other.accumulated_params))
+        end
+
+        protected
+
+        def accumulated_params
+          @params
+        end
+
+        private
+
+        def dup_with(params: @params, offset_value: @offset_value, limit_value: @limit_value,
+                     sort_params: @sort_params)
+          self.class.new(
+            @connection,
+            params: params,
+            offset_value: offset_value,
+            limit_value: limit_value,
+            sort_params: sort_params
+          )
+        end
+
+        def fetch!
+          return if @fetched
+
+          request_params = build_request_params
+          response = @connection.get(params: request_params)
+          @records = response[:data].map { |attrs| Record.new(attrs) }
+          @total = response[:total]
+          @fetched = true
+        end
+
+        def build_request_params
+          result = @params.dup
+          result[:offset] = @offset_value if @offset_value
+          result[:limit] = @limit_value if @limit_value
+          result[:sort] = @sort_params.map { |col, dir| "#{col}:#{dir}" }.join(",") if @sort_params.any?
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Represents a single record from an HTTP API response.
+      #
+      # Provides dynamic attribute access, change tracking, and
+      # ActiveModel-compatible persistence state methods.
+      class Record
+        include ActiveModel::Validations
+
+        attr_reader :id
+
+        def initialize(attrs = {})
+          @force_new = true if attrs.delete(:_persisted) == false
+          @attributes = attrs.transform_keys(&:to_s)
+          @id = @attributes["id"]
+          @persisted = @force_new ? false : !@id.nil?
+          @changes = {}
+          @previous_changes = {}
+        end
+
+        def to_param
+          @id&.to_s
+        end
+
+        def persisted?
+          @persisted
+        end
+
+        def new_record?
+          !persisted?
+        end
+
+        def attributes
+          @attributes.dup
+        end
+
+        def [](key)
+          @attributes[key.to_s]
+        end
+
+        def assign_attributes(new_attrs)
+          new_attrs.each do |key, value|
+            key_s = key.to_s
+            old_value = @attributes[key_s]
+            next if old_value == value
+
+            @changes[key_s] = [old_value, value]
+            @attributes[key_s] = value
+          end
+        end
+
+        def changes
+          @changes.dup
+        end
+
+        def previous_changes
+          @previous_changes.dup
+        end
+
+        def mark_as_persisted
+          @previous_changes = @changes.dup
+          @changes = {}
+          @id = @attributes["id"]
+          @persisted = true
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          @attributes.key?(method_name.to_s) || super
+        end
+
+        def method_missing(method_name, *args)
+          key = method_name.to_s
+          return @attributes[key] if @attributes.key?(key)
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    class Http
+      # Infers IronAdmin field types from JSON values.
+      #
+      # Used for auto-discovery: the adapter fetches the first API response
+      # and uses this class to determine column types from the JSON data,
+      # matching IronAdmin's convention-over-configuration philosophy.
+      module TypeInferrer
+        ISO8601_DATETIME = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
+        ISO8601_DATE = /\A\d{4}-\d{2}-\d{2}\z/
+
+        # Infers the IronAdmin type symbol from a JSON value.
+        #
+        # @param value [Object] A value from a JSON response
+        # @return [Symbol] The inferred field type
+        def self.infer(value)
+          case value
+          when Integer, Float then :number
+          when TrueClass, FalseClass then :boolean
+          when Hash, Array then :json
+          when String then infer_string_type(value)
+          else :string
+          end
+        end
+
+        # Infers column descriptors from a JSON hash (one record).
+        #
+        # @param data [Hash] A single JSON record
+        # @return [Array<ColumnDescriptor>] Inferred column descriptors
+        def self.infer_columns(data)
+          data.map { |key, value| ColumnDescriptor.new(key.to_s, infer(value)) }
+        end
+
+        def self.infer_string_type(value)
+          if value.match?(ISO8601_DATETIME)
+            :datetime
+          elsif value.match?(ISO8601_DATE)
+            :date
+          else
+            :string
+          end
+        end
+
+        private_class_method :infer_string_type
+      end
+    end
+  end
+end

data/lib/iron_admin/adapters/http.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Adapters
+    # HTTP REST API adapter — enables IronAdmin to manage resources
+    # from external REST APIs with convention-over-configuration.
+    #
+    # Fields are auto-discovered from the first API response.
+    # Faraday is used as the HTTP transport (lazy loaded).
+    #
+    # @example Minimal resource configuration
+    #   class ProductResource < IronAdmin::Resource
+    #     self.adapter_class = :http
+    #     http_config do |c|
+    #       c.base_url = "https://api.example.com/v1"
+    #     end
+    #   end
+    class Http < Base
+      # --- Schema Introspection ---
+
+      def columns
+        discovered_columns
+      end
+
+      def column_names
+        discovered_columns.map(&:name)
+      end
+
+      def has_column?(name) # rubocop:disable Naming/PredicatePrefix
+        column_names.include?(name.to_s)
+      end
+
+      def enums
+        {}
+      end
+
+      def associations(_kind = nil)
+        []
+      end
+
+      def association(_name)
+        nil
+      end
+
+      def attachments
+        {}
+      end
+
+      def rich_text_attributes
+        []
+      end
+
+      # --- Naming ---
+
+      def table_name
+        nil
+      end
+
+      # --- Query Building ---
+
+      def all
+        Query.new(connection)
+      end
+
+      def find(id)
+        data = connection.get_one(id.to_s)
+        Record.new(data)
+      end
+
+      def find_by(attrs)
+        all.where(attrs).first
+      end
+
+      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
+      end
+
+      def distinct_values(column)
+        all.pluck(column).compact.uniq.sort_by(&:to_s)
+      end
+
+      def pluck(scope, column)
+        scope.pluck(column)
+      end
+
+      def count(scope = nil)
+        (scope || all).count
+      end
+
+      # --- Search ---
+
+      def search_column(scope, column, query)
+        scope.where("search[#{column}]" => query)
+      end
+
+      def search_columns(scope, columns, query)
+        scope.where(q: query, search_fields: columns.join(","))
+      end
+
+      # --- CRUD ---
+
+      def build(attrs = {})
+        Record.new(attrs.merge(_persisted: false))
+      end
+
+      def save(record)
+        if record.persisted?
+          data = connection.patch(record.id.to_s, record.attributes.except("id"))
+        else
+          data = connection.post(record.attributes.except("id"))
+          return add_api_errors(record, data) unless data.is_a?(Hash) && data["id"]
+        end
+
+        return add_api_errors(record, data) if data.is_a?(Hash) && data.key?("errors")
+
+        record.assign_attributes(data) if data.is_a?(Hash)
+        record.mark_as_persisted
+        true
+      rescue IronAdmin::AdapterError
+        false
+      end
+
+      def update(record, attrs)
+        data = connection.patch(record.id.to_s, attrs)
+        return add_api_errors(record, data) if data.is_a?(Hash) && data.key?("errors")
+
+        record.assign_attributes(attrs)
+        record.assign_attributes(data) if data.is_a?(Hash)
+        record.mark_as_persisted
+        true
+      rescue IronAdmin::AdapterError
+        false
+      end
+
+      def destroy!(record)
+        connection.delete(record.id.to_s)
+      end
+
+      # --- Transactions ---
+
+      def transaction
+        yield
+      end
+
+      # --- Scope Manipulation ---
+
+      def unscope_column(scope, _column)
+        scope
+      end
+
+      # --- Batch ---
+
+      def find_each(scope, &)
+        scope.each(&)
+      end
+
+      # --- Adapter-Agnostic Interface ---
+
+      def record_changes(record)
+        record.previous_changes
+      end
+
+      def wrap_rollback
+        yield
+      rescue IronAdmin::Rollback
+        nil
+      end
+
+      def query_builder_class
+        IronAdmin::Filters::HttpQueryBuilder
+      end
+
+      def pagy_method
+        :pagy
+      end
+
+      # Allows injecting a pre-built configuration (for testing or per-resource override).
+      attr_writer :http_config
+
+      private
+
+      def add_api_errors(record, data) # rubocop:disable Naming/PredicateMethod
+        return false unless data.is_a?(Hash) && data["errors"].is_a?(Hash)
+
+        data["errors"].each { |field, messages| Array(messages).each { |msg| record.errors.add(field, msg) } }
+        false
+      end
+
+      def connection
+        @connection ||= Connection.new(http_config)
+      end
+
+      def http_config
+        @http_config ||= build_config
+      end
+
+      def build_config
+        config = Configuration.new
+        global = IronAdmin.configuration
+        config.base_url = global.http_base_url
+        config.headers = global.http_headers || {}
+        config.resource_path = "/#{resource_name}"
+        config
+      end
+
+      def discovered_columns
+        @discovered_columns ||= discover_columns
+      end
+
+      def discover_columns
+        response = connection.get
+        return [] if response[:data].empty?
+
+        TypeInferrer.infer_columns(response[:data].first)
+      rescue IronAdmin::AdapterError, IronAdmin::RecordNotFound
+        []
+      end
+    end
+  end
+end
+
+require_relative "http/column_descriptor"
+require_relative "http/type_inferrer"
+require_relative "http/record"
+require_relative "http/configuration"
+require_relative "http/connection"
+require_relative "http/query"
+require_relative "http/model_proxy"
+require_relative "../filters/http_query_builder"