rails-surrender 7.0.0 → 8.0.0

data/lib/rails/surrender/fields/node.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'asks'
+require_relative 'attribute'
+require_relative 'expand'
+require_relative 'id_list'
+
+module Rails
+  module Surrender
+    module Fields
+      # The fields one model renders at one place in the field tree, with a branch below each expand.
+      class Node
+        attr_reader :branches
+
+        # `above` holds the base class of every model from the top of the tree down to this one.
+        def initialize(model, asks, above)
+          @model = model
+          @asks = asks
+          @above = above
+          reject_unavailable_request_includes
+          @fields = ordered(rendered_fields)
+          @branches = @fields.to_h { |field| [field.name, field.branch(asks: asks, above: above)] }.compact
+          @variants = { model => self }
+        end
+
+        # An STI subclass renders its own fields. Its variant is built when one of its records first appears,
+        # because subclasses aren't known before they load in development.
+        def for(klass)
+          @variants[klass] ||= Node.new(klass, @asks, @above)
+        end
+
+        def preloads
+          @fields.filter_map(&:preload)
+        end
+
+        def render(record, ability)
+          @fields.each_with_object({}) do |field, rendered|
+            field.write(record, into: rendered, ability: ability, branch: @branches[field.name])
+          end
+        end
+
+        def to_h
+          @fields.to_h { |field| [field.name, field.describe(@branches[field.name])] }
+        end
+
+        # Nodes are equal when they render the same fields, so a level loads each association once for all of them.
+        def eql?(other)
+          other.is_a?(Node) && identity == other.identity
+        end
+
+        alias == eql?
+
+        def hash
+          identity.hash
+        end
+
+        protected
+
+        def identity
+          [@model, @asks, @above]
+        end
+
+        private
+
+        def reject_unavailable_request_includes
+          unavailable = @asks.request_includes.reject { |name| @model.surrenders?(name) }
+          return if unavailable.empty?
+
+          raise Error, I18n.t('surrender.error.query_string.include.not_available', param: unavailable)
+        end
+
+        def rendered_fields
+          (@model.surrender_fields + @asks.controller_includes + @asks.request_includes)
+            .uniq
+            .reject { |name| @asks.excludes?(name) }
+            .map { |name| @model.surrender_field(name) }
+            .reject { |field| field.circular?(@above) }
+        end
+
+        def ordered(fields)
+          fields.each_with_index.sort_by { |field, position| [field.rank, position] }.map(&:first)
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/menu/field.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Menu
+      # A field a request may ask a model for: its kind (:attribute, :id_list or :expand), whether it renders by
+      # default, and, for an expand, the menu of the model it leads to.
+      Field = Data.define(:name, :kind, :default, :menu) do
+        def default?
+          default
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/menu/filter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Menu
+      # A filter a request may name, and the column it compares, or nil for a filter the model defines under a name of
+      # its own.
+      Filter = Data.define(:name, :column)
+    end
+  end
+end

data/lib/rails/surrender/menu/menu.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'field'
+require_relative 'filter'
+
+module Rails
+  module Surrender
+    # Everything a request may ask of one model: its default and available fields, nested by expand, its filters and
+    # sorts, and the size of its pages. It is read from the same rules that check requests, so it lists exactly what a
+    # request may ask.
+    class Menu
+      # `above` holds the base class of every model from the top of the menu down to this one.
+      def initialize(model, above: [model.base_class])
+        @model = model
+        @above = above
+      end
+
+      # In the order fields render, with defaults before available fields within each kind. Expands back into a model
+      # above are left out, as they never render.
+      def fields
+        @fields ||= offered_fields.map do |field|
+          Field.new(name: field.name, kind: field.kind, default: default?(field), menu: field.menu(above: @above))
+        end
+      end
+
+      def filters
+        @model.surrender_filter_columns.map { |name, column| Filter.new(name: name, column: column) }
+      end
+
+      def sorts
+        @model.surrender_sort_names
+      end
+
+      def page_size
+        Surrender.page_size
+      end
+
+      private
+
+      def offered_fields
+        (@model.surrender_fields + @model.surrender_available_fields)
+          .uniq
+          .map { |name| @model.surrender_field(name) }
+          .reject { |field| field.circular?(@above) }
+          .each_with_index
+          .sort_by { |field, position| [field.rank, default?(field) ? 0 : 1, position] }
+          .map(&:first)
+      end
+
+      def default?(field)
+        @model.surrender_fields.include?(field.name)
+      end
+    end
+  end
+end

data/lib/rails/surrender/model_additions.rb

@@ -2,56 +2,71 @@
 
 module Rails
   module Surrender
-    # Aad methods to the model class to describe how the model renders.
+    # Adds methods to the model class to describe how the model renders.
     module ModelAdditions
       def self.included(base)
-        attr_accessor :surrender_attributes
-        attr_accessor :surrender_expands
-        attr_accessor :surrender_available_attributes
-        attr_accessor :surrender_available_expands
-
         base.extend(ClassMethods)
       end
 
+      # A model lists the fields it renders by default, and those a request may add with `include`. Fields that name
+      # an association expand into the associated resource; every other field is rendered as an attribute.
       module ClassMethods
-        def surrenders(*args)
-          directives = args.extract_options!
-
-          # Run through the various lists of attributes and assign them to the rendering context
-          # If the superclass has attributes then consume those as well.
-          %w[attributes expands available_attributes available_expands].each do |directive|
-            surrender_directive = "surrender_#{directive}"
-            list = []
-            if superclass.instance_variable_defined?("@#{surrender_directive}")
-              list << superclass.instance_variable_get("@#{surrender_directive}")
-            end
-            list << directives[directive.to_sym] if directives.key?(directive.to_sym)
-            instance_variable_set("@#{surrender_directive}", list.flatten.uniq)
-          end
+        DEFAULT_FIELDS = %i[id created_at].freeze
+
+        # Fields are sorted into attributes and associations when read, not here, because models often call
+        # `surrenders` before declaring the associations it names.
+        def surrenders(*fields, available: [])
+          @surrender_fields = (inherited_surrender(:@surrender_fields) + fields.map(&:to_sym)).uniq
+          @surrender_available_fields =
+            (inherited_surrender(:@surrender_available_fields) + Array(available).map(&:to_sym)).uniq
+        end
+
+        def surrender_fields
+          @surrender_fields || DEFAULT_FIELDS
         end
 
-        def surrender_attributes
-          @surrender_attributes ||= %i[id created_at]
+        def surrender_available_fields
+          @surrender_available_fields || []
         end
 
-        def surrender_available_attributes
-          @surrender_available_attributes ||= []
+        # Everything a request may ask of the model: its fields, filters and sorts.
+        def surrender_menu
+          Menu.new(self)
         end
 
-        def surrender_expands
-          @surrender_expands ||= []
+        # Whether a request may include the field: it renders by default or is available.
+        def surrenders?(name)
+          surrender_callable_fields.include?(name.to_sym)
         end
 
-        def surrender_available_expands
-          @surrender_available_expands ||= []
+        # An association expands, a *_ids name of an association is an id list, and anything else is an attribute.
+        def surrender_field(name)
+          name = name.to_sym
+          if (reflection = reflect_on_association(name))
+            Fields::Expand.new(name: name, reflection: reflection)
+          elsif (association = id_list_association(name))
+            Fields::IdList.new(name: name, association: association)
+          else
+            Fields::Attribute.new(name: name)
+          end
+        end
+
+        private
+
+        def id_list_association(name)
+          return unless name.end_with?('_ids')
+
+          association = name.to_s.delete_suffix('_ids').pluralize.to_sym
+          association if reflect_on_association(association)
         end
 
-        def surrender_callable_attributes
-          @surrender_callable_attributes ||= (surrender_attributes + surrender_available_attributes).flatten
+        # A subclass may make a default of a field its superclass only made available.
+        def surrender_callable_fields
+          (surrender_fields + surrender_available_fields).uniq
         end
 
-        def surrender_callable_expands
-          @surrender_callable_expands ||= (surrender_expands + surrender_available_expands).flatten
+        def inherited_surrender(variable)
+          superclass.instance_variable_defined?(variable) ? superclass.instance_variable_get(variable) : []
         end
       end
     end

data/lib/rails/surrender/params/list_param.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Params
+      # A query param that lists names, names with values, and nested lists, such as `genre:fantasy, author:[name]`.
+      # It is read as the YAML of a flow sequence, so values come back typed: `long:true` holds true, not 'true'.
+      class ListParam
+        # YAML needs a space after each comma and colon that separates entries, but not inside quoted values, where it
+        # would change the value: '13:30' must stay '13:30'.
+        SEPARATORS_OUTSIDE_QUOTES = /'[^']*'|"[^"]*"|[,:]/
+
+        # `param` names the query param in the error a malformed value raises.
+        def self.parse(text, param:)
+          spaced = text.to_s.gsub(SEPARATORS_OUTSIDE_QUOTES) { |match| match.length == 1 ? "#{match} " : match }
+          Psych.safe_load("[#{spaced}]")
+        rescue Psych::Exception
+          raise Error, I18n.t('surrender.error.query_string.incorrect_format', param: param)
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/railtie.rb

@@ -2,19 +2,33 @@
 
 module Rails
   module Surrender
+    # Hooks surrender into Rails as each framework loads. Using load hooks rather than after_initialize matters
+    # in eager loaded environments, where models call `surrenders` before after_initialize runs.
     class Railtie < ::Rails::Railtie
-      config.after_initialize do
-        ActionController::Base.class_eval do
-          include Rails::Surrender::ControllerAdditions
-        end
+      config.surrender = ActiveSupport::OrderedOptions.new
+      config.surrender.default_per_page = 50
+      config.surrender.max_per_page = 100
 
-        ActionController::API.class_eval do
-          include Rails::Surrender::ControllerAdditions
-        end
+      # Built once at boot, so a page size setting that makes no sense stops the app from starting.
+      initializer 'rails_surrender.page_size' do |app|
+        Rails::Surrender.page_size = Rails::Surrender::Selection::PageSize.new(
+          default: app.config.surrender.default_per_page, max: app.config.surrender.max_per_page
+        )
+      end
+
+      initializer 'rails_surrender.locales' do |app|
+        app.config.i18n.load_path += Dir[File.expand_path('config/locales/*.yml', __dir__)]
+      end
+
+      initializer 'rails_surrender.action_controller' do
+        ActiveSupport.on_load(:action_controller) { include Rails::Surrender::ControllerAdditions }
+      end
 
-        ActiveRecord::Base.class_eval do
+      initializer 'rails_surrender.active_record' do
+        ActiveSupport.on_load(:active_record) do
           include Rails::Surrender::ModelAdditions
-          include Rails::Surrender::ModelFilterScopes
+          include Rails::Surrender::Selection::Filtering
+          include Rails::Surrender::Selection::Sorting
         end
       end
     end

data/lib/rails/surrender/render/resource.rb

@@ -1,52 +1,33 @@
 # frozen_string_literal: true
 
-require_relative 'resource/inclusion_mapper'
-require_relative 'resource/collection'
-require_relative 'resource/instance'
-
 module Rails
   module Surrender
     module Render
-      # Rendering a resource, and it's various nested components, according to the given config params.
+      # Renders what a controller surrenders. Records and relations render through a field tree; nil, hashes and
+      # arrays have no model to shape them, so they render as given.
       class Resource
-        attr_reader :resource, :ability, :config
+        attr_reader :resource, :ability, :asks
 
-        def initialize(resource:, ability:, config:)
+        # `asks` holds the keyword arguments of FieldTree.new other than the model.
+        def initialize(resource:, ability:, asks: {})
           @resource = resource
           @ability = ability
-          @config  = config
+          @asks = asks
         end
 
         def parse
           data = case resource
-                 when nil? then {}
-                 when Hash || Array then resource
-                 when ActiveRecord::Relation then collection_data
-                 else instance_data
+                 when nil then {}
+                 when Hash, Array then resource
+                 else FieldTree.new(model, **asks).render(resource, ability: ability)
                  end
           Response.new(data: data)
         end
 
         private
 
-        def collection_data
-          includes = InclusionMapper.new(resource_class: resource.klass, config: config).parse
-          data = @resource.includes(includes)
-          Collection.new(resource: data, config: config, ability: ability).render
-        end
-
-        def instance_data
-          # Reloading the instance here allows us to take advantage of the eager loading
-          # capabilities of ActiveRecord with our 'includes' hash to prevent N+1 queries.
-          # This can save a TON of response time when the data sets begin to get large.
-          data = if config.reload_resource?
-                   includes = InclusionMapper.new(resource_class: resource.class, config: config).parse
-                   @resource = resource.class.includes(includes).find_by_id(resource.id)
-                 else
-                   resource
-                 end
-
-          Instance.new(resource: data, config: config, ability: ability).render
+        def model
+          resource.try(:klass) || resource.class
         end
       end
     end

data/lib/rails/surrender/selection/filtering.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Selection
+      # Adds a filter_by_<column> scope for every column, and filter_by_<name>_before/after scopes for date and
+      # time columns, where <name> drops any _at suffix. The before/after scopes take a Time or Date, or an ISO 8601
+      # string, and raise Rails::Surrender::Error for anything else.
+      #
+      # The scopes are defined the first time any filter_by_ method is looked up, rather than when the class is
+      # defined, so that loading a model never touches the database.
+      module Filtering
+        extend ActiveSupport::Concern
+
+        FILTER_PREFIX = 'filter_by_'
+
+        # Serializes first-time scope definition across threads, so a concurrent lookup waits for the scopes rather
+        # than reporting them missing. It is shared by all models because scopes are defined once per model.
+        SCOPES_LOCK = Monitor.new
+
+        # Applies a request's filters, and generates the filter scopes on first lookup.
+        module ClassMethods
+          # Applies the filter_by_ scope a request's filter names, trying an association's foreign key (`author` for
+          # filter_by_author_id) when the name alone has no scope. Only filter_by_ scopes are reachable this way.
+          def surrender_filter(name, value)
+            scope = surrender_filter_scopes_for(name).find { |candidate| respond_to?(candidate) }
+            raise Error, I18n.t('surrender.error.query_string.filter.not_available', param: name) unless scope
+
+            public_send(scope, value)
+          end
+
+          # The filters a request may name, each with the column it compares, or nil for a filter the model defines
+          # under a name of its own.
+          def surrender_filter_columns
+            generated = surrender_filterable? ? surrender_generated_filters : {}
+            defined = methods.grep(/\A#{FILTER_PREFIX}/o).map { |scope| scope.to_s.delete_prefix(FILTER_PREFIX) }.sort
+            generated.merge((defined - generated.keys).index_with(nil))
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            return super unless surrender_filter_name?(name) && surrender_filter_scopes_pending?
+
+            define_surrender_filter_scopes
+            surrender_filter_scopes_defined? ? respond_to?(name, include_private) : super
+          end
+
+          def method_missing(name, ...)
+            return super unless surrender_filter_name?(name) && surrender_filter_scopes_pending?
+
+            define_surrender_filter_scopes
+            surrender_filter_scopes_defined? ? public_send(name, ...) : super
+          end
+
+          private
+
+          def surrender_filter_scopes_for(name)
+            scope = :"#{FILTER_PREFIX}#{name.to_s.tr('.', '_')}"
+            [scope, :"#{scope}_id"]
+          end
+
+          def surrender_filter_name?(name)
+            name.start_with?(FILTER_PREFIX)
+          end
+
+          def surrender_filter_scopes_pending?
+            !surrender_filter_scopes_defined? && surrender_filterable?
+          end
+
+          def surrender_filter_scopes_defined?
+            @surrender_filter_scopes_defined == true
+          end
+
+          # A lookup made while this thread is already defining the scopes returns without them, rather than
+          # recursing. The flag is set only once every scope exists, so a failed attempt is retried next lookup.
+          def define_surrender_filter_scopes
+            SCOPES_LOCK.synchronize do
+              return if surrender_filter_scopes_defined? || @surrender_filter_scopes_defining
+
+              begin
+                @surrender_filter_scopes_defining = true
+                define_surrender_generated_scopes
+                @surrender_filter_scopes_defined = true
+              ensure
+                @surrender_filter_scopes_defining = false
+              end
+            end
+          end
+
+          # ActiveRecord::Base itself is asked whether it responds to scope names while scopes are being defined.
+          def surrender_filterable?
+            self != ActiveRecord::Base && !abstract_class? && table_exists?
+          end
+
+          # An equality filter for each column, and before and after filters for each date or time column, named
+          # without its _at suffix.
+          def surrender_generated_filters
+            columns.each_with_object({}) do |column, filters|
+              filters[column.name] = column
+              next unless column.type.in?(%i[date datetime])
+
+              stem = column.name.delete_suffix('_at')
+              filters["#{stem}_before"] = column
+              filters["#{stem}_after"] = column
+            end
+          end
+
+          def define_surrender_generated_scopes
+            surrender_generated_filters.each do |name, column|
+              define_surrender_filter_scope(name, surrender_filter_body(name, column.name))
+            end
+          end
+
+          # Scope bodies run against a relation, which can't call the model's private methods, so they close over it.
+          def surrender_filter_body(name, column)
+            return ->(value) { where(column => value) } if name == column
+
+            to_time = method(:surrender_filter_time)
+            attribute = arel_table[column]
+            comparison = name.end_with?('_before') ? :lt : :gt
+            ->(time) { where(attribute.public_send(comparison, to_time.call(name, time))) }
+          end
+
+          # Strict, so a value that is not a time is rejected rather than compared as NULL, which matches nothing.
+          # A time without an offset is in the app's time zone.
+          def surrender_filter_time(filter, value)
+            return value if value.is_a?(Date) || value.acts_like?(:time)
+
+            Time.zone.iso8601(value.to_s)
+          rescue ArgumentError
+            raise Error, I18n.t('surrender.error.query_string.filter.invalid_time', param: filter, value: value)
+          end
+
+          # Filters the application defines, on this model or a superclass, take precedence over generated ones.
+          def define_surrender_filter_scope(name, body)
+            scope_name = :"#{FILTER_PREFIX}#{name}"
+            return if singleton_class.method_defined?(scope_name) || singleton_class.private_method_defined?(scope_name)
+
+            scope scope_name, body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/selection/page_size.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Selection
+      # How many records one page holds: the size a request asks for, or the default when it asks for none, capped at
+      # the limit. A nil limit leaves pages uncapped.
+      PageSize = Data.define(:default, :max) do
+        def initialize(default: 50, max: 100)
+          check_positive_whole_number('default_per_page', default)
+          check_positive_whole_number('max_per_page', max) unless max.nil?
+          raise ArgumentError, "default_per_page (#{default}) is larger than max_per_page (#{max})" if max&.<(default)
+
+          super
+        end
+
+        def for(requested)
+          return default if requested.nil?
+
+          max ? [requested, max].min : requested
+        end
+
+        private
+
+        def check_positive_whole_number(setting, value)
+          return if value.is_a?(Integer) && value.positive?
+
+          raise ArgumentError, "#{setting} needs a positive whole number, not #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/selection/selected.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Selection
+      # The records a selection picked, and the headers that describe how.
+      class Selected
+        attr_reader :records
+
+        # `unpaged` holds the records before paging, which a count response counts. `sort` is the sort as requested,
+        # and `per` the page size used, each nil when that step didn't apply.
+        def initialize(records:, unpaged: records, sort: nil, per: nil)
+          @records = records
+          @unpaged = unpaged
+          @sort = sort
+          @per = per
+        end
+
+        # A single record, or anything else that can't count itself, counts as one.
+        def count
+          @unpaged.respond_to?(:count) ? @unpaged.count : 1
+        end
+
+        def headers
+          headers = {}
+          headers['X-Sort'] = @sort if @sort
+          headers['X-Pagination'] = pagination.to_json if @per
+          headers
+        end
+
+        private
+
+        # The size of the page follows from the total, so it doesn't need a query of its own.
+        def pagination
+          total = records.total_count
+          {
+            total: total,
+            page_total: (total - records.offset_value).clamp(0, records.limit_value),
+            page: records.current_page,
+            previous_page: records.prev_page,
+            next_page: records.next_page,
+            last_page: records.total_pages,
+            per_page: @per,
+            offset: records.offset_value
+          }
+        end
+      end
+    end
+  end
+end