rest_framework 1.2.0 → 2.0.0.beta2

data/lib/rest_framework/controller.rb

@@ -3,9 +3,7 @@
 # module rather than defining a separate submodule.
 module RESTFramework::Controller
   RRF_BASE_CONFIG = {
-    extra_actions: nil,
-    extra_member_actions: nil,
-    singleton_controller: nil,
+    singular: nil,
 
     # Options related to metadata and display.
     title: nil,
@@ -17,7 +15,6 @@ module RESTFramework::Controller
     # Options related to models.
     model: nil,
     recordset: nil,
-    excluded_actions: nil,
 
     # Bulk configuration.
     #
@@ -43,9 +40,6 @@ module RESTFramework::Controller
     find_by_fields: nil,
     find_by_query_param: "find_by".freeze,
 
-    # What should be included/excluded from default fields.
-    exclude_associations: false,
-
     # Handling request body parameters.
     allowed_parameters: nil,
 
@@ -57,9 +51,26 @@ module RESTFramework::Controller
     native_serializer_except_query_param: "except".freeze,
     native_serializer_include_query_param: "include".freeze,
     native_serializer_exclude_query_param: "exclude".freeze,
-    native_serializer_associations_limit: nil,
-    native_serializer_associations_limit_query_param: "associations_limit".freeze,
-    native_serializer_include_associations_count: false,
+
+    # Options for including associations and collection counts.
+    exclude_associations: false,
+    include_association_count: false,
+
+    # The number of records serialized per collection association, so responses are bounded out of
+    # the box (`nil` = unlimited). With `enable_association_queries`, a client can raise it for a
+    # given association via `?<prefix>.<name>.limit=N` or `limit=all` (`none`/`0` are aliases), both
+    # capped at `association_limit_max` (the "all" forms yield the cap). Set the max to `nil` to let
+    # a client request unlimited records.
+    association_limit: 10,
+    association_limit_max: 100,
+
+    # Let clients request extra fields for a serialized association via
+    # `?<prefix>.<association>.fields=a,b,c`. The allowlist keeps an association from ever exposing
+    # more than its own endpoint would: an explicit per-association `requestable_fields` in
+    # `field_config`, else the fields the associated model's sibling controller serializes.
+    # Off/secure by default.
+    enable_association_queries: false,
+    association_query_prefix: "associations".freeze,
 
     # Options for filtering, ordering, and searching.
     filter_backends: [
@@ -93,12 +104,16 @@ module RESTFramework::Controller
     serialize_to_json: true,
     serialize_to_xml: true,
 
-    # Options related to pagination.
-    paginator_class: nil,
+    # Options related to pagination. Pagination is on by default (page-number based) with a capped
+    # page size, so responses are bounded out of the box; set `paginator_class = nil` to disable.
+    paginator_class: RESTFramework::PageNumberPaginator,
     page_size: 20,
-    page_query_param: "page",
-    page_size_query_param: "page_size",
-    max_page_size: nil,
+    page_query_param: "page".freeze,
+    page_size_query_param: "page_size".freeze,
+    max_page_size: 40,
+    # Whether the page-number paginator computes the total record count to report `count` and
+    # `total_pages`. Set to `false` on large tables to skip that query.
+    page_total_count: true,
 
     # Option to disable serializer adapters by default, mainly introduced because Active Model
     # Serializers will do things like serialize `[]` into `{"":[]}`.
@@ -125,6 +140,7 @@ module RESTFramework::Controller
     ActiveRecord::RecordNotSaved,
     ActiveRecord::RecordNotDestroyed,
     ActiveRecord::RecordNotUnique,
+    ActiveRecord::StatementInvalid,
     ActiveModel::UnknownAttributeError,
   ].freeze
 
@@ -142,14 +158,84 @@ module RESTFramework::Controller
   }
   RRF_ACTIVESTORAGE_KEYS = [ :io, :content_type, :filename, :identify, :key ]
 
-  # Default action for API root.
-  def root
-    render(api: { message: "This is the API root." })
-  end
-
   module ClassMethods
     IGNORE_VALIDATORS_WITH_KEYS = [ :if, :unless ].freeze
 
+    # Thread-local key toggled by `propagate` while its block runs.
+    RRF_PROPAGATING_KEY = :rrf_propagating
+
+    # Define one or more class-level configuration attributes. Assignments are **local by default**:
+    #
+    #   self.x = value               # applies to this controller ONLY; descendants don't inherit it
+    #   propagate { self.x = value } # applies to this controller AND all descendants
+    #
+    # This gives a single, uniform rule (an assignment is local unless wrapped in `propagate`), so
+    # there's no per-attribute "does this inherit?" knowledge to carry around. Values are stored in
+    # closures on redefined singleton methods (the same mechanism as `class_attribute`), never in
+    # instance variables, so there is exactly one interface for configuration: the setter.
+    #
+    # Only singleton (class-level) methods are defined, so config never leaks to controller
+    # instances (which would risk colliding with action methods).
+    def rrf_class_attribute(*names, default: nil)
+      names.each do |name|
+        # Propagating baseline: every controller sees the default until it's overridden. This lives
+        # in the propagated module (see `rrf_propagated_module`) rather than directly on the
+        # singleton class, so a local assignment can coexist with it via `super`.
+        rrf_propagated_module.define_method(name) { default }
+
+        # Parity with `class_attribute`, which also defines a predicate.
+        singleton_class.define_method("#{name}?") { !!public_send(name) }
+
+        singleton_class.define_method("#{name}=") do |value|
+          if Thread.current[RRF_PROPAGATING_KEY]
+            # Propagate: descendants inherit this getter via the module in the singleton chain. It's
+            # kept separate from any local getter (defined directly on the singleton class) so a
+            # subsequent local assignment doesn't clobber the value propagated to descendants.
+            rrf_propagated_module.define_method(name) { value }
+          else
+            # Local: `value` for this class only; descendants fall back through `super` to the
+            # nearest propagated ancestor value, or the default.
+            klass = self
+            singleton_class.define_method(name) do
+              if equal?(klass)
+                value
+              elsif defined?(super)
+                super()
+              else
+                default
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # The per-class module holding this class's propagated attribute getters (and the default
+    # baseline). It's included into the singleton class so descendants inherit propagated values
+    # through the singleton-class chain, while local assignments—defined directly on the singleton
+    # class—take precedence for the class itself and can `super()` back into this module. Created
+    # lazily and memoized per class (instance variables aren't inherited, so each class gets its
+    # own).
+    def rrf_propagated_module
+      @rrf_propagated_module ||= Module.new.tap { |mod| singleton_class.include(mod) }
+    end
+
+    # Run a block in which configuration setters (`self.x = value`) propagate to descendant
+    # controllers instead of applying locally. Use this on a shared base controller for settings you
+    # want every subclass to inherit:
+    #
+    #   propagate do
+    #     self.paginator_class = RESTFramework::PageNumberPaginator
+    #     self.page_size = 30
+    #   end
+    def propagate
+      previous = Thread.current[RRF_PROPAGATING_KEY]
+      Thread.current[RRF_PROPAGATING_KEY] = true
+      yield
+    ensure
+      Thread.current[RRF_PROPAGATING_KEY] = previous
+    end
+
     # By default, this is the name of the controller class, titleized and with any custom inflection
     # acronyms applied.
     def get_title
@@ -167,48 +253,29 @@ module RESTFramework::Controller
       self.model&.human_attribute_name(s, default: default_title) || default_title
     end
 
-    # Define any behavior to execute at the end of controller definition.
-    # :nocov:
-    def rrf_finalize
-      if RESTFramework.config.freeze_config
-        self::RRF_BASE_CONFIG.keys.each { |k|
-          v = self.send(k)
-          v.freeze if v.is_a?(Hash) || v.is_a?(Array)
-        }
-      end
-
-      self.setup_delegation if self.model
-      # self.setup_channel if self.model
-    end
-    # :nocov:
-
-    # Get the available fields. Fallback to this controller's model columns, or an empty array. This
-    # should always return an array of strings.
-    def get_fields(input_fields: nil)
-      input_fields ||= self.fields
-
-      # If fields is a hash, then parse it.
-      if input_fields.is_a?(Hash)
-        return RESTFramework::Utils.parse_fields_hash(
-          input_fields,
+    # Resolve the `fields` config to an array of strings. Memoized, since `fields` and the flags it
+    # depends on are class-level config fixed at load time.
+    def get_fields
+      @get_fields ||= if self.fields.is_a?(Hash)
+        RESTFramework::Utils.parse_fields_hash(
+          self.fields,
           self.model,
           exclude_associations: self.exclude_associations,
           action_text: self.enable_action_text,
           active_storage: self.enable_active_storage,
         )
-      elsif !input_fields
-        # Otherwise, if fields is nil, then fallback to columns.
-        return self.model ? RESTFramework::Utils.fields_for(
+      elsif self.fields
+        self.fields.map(&:to_s)
+      elsif self.model
+        RESTFramework::Utils.fields_for(
           self.model,
           exclude_associations: self.exclude_associations,
           action_text: self.enable_action_text,
           active_storage: self.enable_active_storage,
-        ) : []
-      elsif input_fields
-        input_fields = input_fields.map(&:to_s)
+        )
+      else
+        []
       end
-
-      input_fields
     end
 
     # Get a full field configuration, including defaults and inferred values.
@@ -302,17 +369,22 @@ module RESTFramework::Controller
         if ref = reflections[f]
           cfg[:kind] = "association"
 
-          # Determine sub-fields for associations.
+          # Determine the association's fields.
           if ref.polymorphic?
             ref_columns = {}
           else
             ref_columns = ref.klass.columns_hash
           end
-          cfg[:sub_fields] ||= RESTFramework::Utils.sub_fields_for(ref)
-          cfg[:sub_fields] = cfg[:sub_fields].map(&:to_s)
+          cfg[:fields] ||= RESTFramework::Utils.association_fields_for(ref)
+          cfg[:fields] = cfg[:fields].map(&:to_s)
+
+          # Strings, to match `:fields` when intersecting requested fields against the allowlist.
+          if cfg[:requestable_fields]
+            cfg[:requestable_fields] = cfg[:requestable_fields].map(&:to_s)
+          end
 
-          # Very basic metadata about sub-fields.
-          cfg[:sub_fields_metadata] = cfg[:sub_fields].map { |sf|
+          # Very basic metadata about the association's fields.
+          cfg[:association_fields_metadata] = cfg[:fields].map { |sf|
             v = {}
 
             if ref_columns[sf]
@@ -375,13 +447,6 @@ module RESTFramework::Controller
           # Update `required` if we find a presence validator.
           cfg[:required] = true if kind == :presence
 
-          # Resolve procs (and lambdas), and symbols for certain arguments.
-          if options[:in].is_a?(Proc)
-            options = options.merge(in: options[:in].call)
-          elsif options[:in].is_a?(Symbol)
-            options = options.merge(in: self.model.send(options[:in]))
-          end
-
           cfg[:validators] ||= {}
           cfg[:validators][kind] ||= []
           cfg[:validators][kind] << options
@@ -389,39 +454,42 @@ module RESTFramework::Controller
 
         next [ f, cfg ]
       }.to_h.compact.with_indifferent_access
-    end
 
-    # Only for model controllers.
-    def setup_delegation
-      # Delegate extra actions.
-      self.extra_actions&.each do |action, config|
-        next unless config.is_a?(Hash) && config.dig(:metadata, :delegate)
-        next unless self.model.respond_to?(action)
+      # Compile each association's requestable-fields allowlist once (see
+      # `enable_association_queries`). This runs as a second pass, after `@field_configuration` is
+      # memoized, because resolving a sibling's fields reads its `field_configuration` — and a
+      # self-referential or mutual association would otherwise recurse into this build.
+      if self.enable_association_queries
+        @field_configuration.each do |_f, cfg|
+          next unless cfg[:kind] == "association"
 
-        self.define_method(action) do
-          if self.class.model.method(action).parameters.last&.first == :keyrest
-            render(api: self.class.model.send(action, **request.query_parameters.symbolize_keys))
-          else
-            render(api: self.class.model.send(action))
-          end
+          cfg[:requestable_fields] ||= self.association_requestable_fields(cfg[:reflection])
         end
       end
 
-      # Delegate extra member actions.
-      self.extra_member_actions&.each do |action, config|
-        next unless config.is_a?(Hash) && config.dig(:metadata, :delegate)
-        next unless self.model.method_defined?(action)
-
-        self.define_method(action) do
-          record = self.get_record
+      @field_configuration
+    end
 
-          if record.method(action).parameters.last&.first == :keyrest
-            render(api: record.send(action, **request.query_parameters.symbolize_keys))
-          else
-            render(api: record.send(action))
-          end
-        end
-      end
+    # The fields a consumer may request for an association beyond its defaults, derived from the
+    # associated model's sibling controller: what that controller serializes, so the association can
+    # never expose more than its own endpoint would. Empty unless the sibling is discoverable and
+    # introspectable — a custom serializer makes its `get_fields` meaningless. Hidden fields are
+    # included (retrievable via `?only=` there); write-only fields and nested associations aren't.
+    def association_requestable_fields(ref)
+      return [] if ref.polymorphic?
+
+      sibling = RESTFramework::Utils.controller_for_model(self, ref.klass)
+      return [] unless sibling
+      return [] if sibling.serializer_class ||
+        sibling.native_serializer_config ||
+        sibling.native_serializer_singular_config ||
+        sibling.native_serializer_plural_config
+
+      cfg = sibling.field_configuration
+      sibling.get_fields.reject { |sf|
+        c = cfg[sf]
+        c.nil? || c[:write_only] || c[:kind] == "association"
+      }
     end
   end
 
@@ -433,18 +501,12 @@ module RESTFramework::Controller
     # By default, the layout should be set to `rest_framework`.
     base.layout("rest_framework")
 
-    # Add class attributes unless they already exist.
+    # Materialize config with `rrf_class_attribute` (local by default) rather than `class_attribute`
+    # (always inherited).
     RRF_BASE_CONFIG.each do |a, default|
       next if base.respond_to?(a)
 
-      # Don't leak class attributes to the instance to avoid conflicting with action methods.
-      base.class_attribute(a, default: default, instance_accessor: false)
-    end
-
-    # Alias `extra_actions` to `extra_collection_actions`.
-    unless base.respond_to?(:extra_collection_actions)
-      base.singleton_class.alias_method(:extra_collection_actions, :extra_actions)
-      base.singleton_class.alias_method(:extra_collection_actions=, :extra_actions=)
+      base.rrf_class_attribute(a, default: default)
     end
 
     # Skip CSRF since this is an API.
@@ -458,21 +520,6 @@ module RESTFramework::Controller
     # Handle exceptions.
     base.rescue_from(*RRF_RESCUED_EXCEPTIONS, with: :rrf_error_handler)
     base.rescue_from(*RRF_RESCUED_RAILS_EXCEPTIONS, with: :rrf_error_handler)
-
-    # Use `TracePoint` hook to automatically call `rrf_finalize`.
-    if RESTFramework.config.auto_finalize
-      # :nocov:
-      TracePoint.trace(:end) do |t|
-        next if base != t.self
-
-        base.rrf_finalize
-
-        # It's important to disable the trace once we've found the end of the base class definition,
-        # for performance.
-        t.disable
-      end
-      # :nocov:
-    end
   end
 
   def get_serializer_class
@@ -496,9 +543,17 @@ module RESTFramework::Controller
       400
     end
 
-    render(
-      api: {
-        message: e.message,
+    # `StatementInvalid` messages commonly embed SQL fragments and schema details, so don't leak
+    # them to clients unless backtraces are explicitly enabled.
+    message = if e.is_a?(ActiveRecord::StatementInvalid) && !RESTFramework.config.show_backtrace
+      "Invalid query."
+    else
+      e.message
+    end
+
+    render_api(
+      {
+        message: message,
         errors: e.try(:record).try(:errors),
         exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
       }.compact,
@@ -583,18 +638,32 @@ module RESTFramework::Controller
     end
   end
 
-  # Deprecated alias for `render_api`.
-  def api_response(*args, **kwargs)
-    RESTFramework.deprecator.warn("`api_response` is deprecated; use `render_api` instead.")
-    render_api(*args, **kwargs)
-  end
-
   def options
-    render(api: self.openapi_document)
+    render_api(self.openapi_document)
   end
 
   def get_fields
-    self.class.get_fields(input_fields: self.class.fields)
+    self.class.get_fields
+  end
+
+  def readable_fields
+    cfg = self.class.field_configuration
+    self.get_fields.reject { |f| cfg[f]&.[](:write_only) }
+  end
+
+  # `readable_fields` restricted to real columns, for query surfaces that build SQL directly
+  # (find_by, search) and would raise on a virtual/method field.
+  def readable_columns
+    self.readable_fields & self.class.model.column_names
+  end
+
+  # `readable_fields` restricted to columns and associations, for surfaces that also resolve dotted
+  # `association.sub_field` paths (filtering, ordering). Excludes virtual/method fields, which have
+  # no column to order or filter by.
+  def readable_columns_or_associations
+    cfg = self.class.field_configuration
+    columns = self.class.model.column_names
+    self.readable_fields.select { |f| f.in?(columns) || cfg[f]&.[](:kind) == "association" }
   end
 
   # Get a hash of strong parameters for the current action.
@@ -604,7 +673,8 @@ module RESTFramework::Controller
     @_get_allowed_parameters = self.class.allowed_parameters
     return @_get_allowed_parameters if @_get_allowed_parameters
 
-    # Assemble strong parameters.
+    # Assemble strong parameters. Read-only fields are permitted here and stripped later per-action
+    # by `_rrf_strip_read_only_fields` (which keeps the primary key on bulk update to find records).
     variations = []
     hash_variations = {}
     reflections = self.class.model.reflections
@@ -643,7 +713,7 @@ module RESTFramework::Controller
         # TODO: Consider adjusting this based on `nested_attributes_options`.
         if self.class.permit_nested_attributes_assignment
           hash_variations["#{f}_attributes"] = (
-            config[:sub_fields] + [ "_destroy" ]
+            config[:fields] + [ "_destroy" ]
           )
         end
 
@@ -753,10 +823,18 @@ module RESTFramework::Controller
       body_params[k].unshift(*v)
     end
 
-    # Filter read-only fields.
-    body_params.delete_if do |f, _|
-      cfg = self.class.field_configuration[f]
-      cfg && cfg[:read_only]
+    # Filter read-only fields. For bulk actions the permitted structure is `{ _json: [...] }`, so we
+    # strip read-only keys from each element rather than the top-level hash (whose only key is
+    # `_json`). Bulk update keeps the primary key, which it needs to locate each record.
+    if bulk_action
+      keep = bulk_action == :update ? [ pk.to_s ] : []
+      body_params[:_json]&.each do |element|
+        next unless element.is_a?(ActionController::Parameters)
+
+        self._rrf_strip_read_only_fields(element, keep: keep)
+      end
+    else
+      self._rrf_strip_read_only_fields(body_params)
     end
 
     body_params
@@ -765,6 +843,17 @@ module RESTFramework::Controller
   alias_method :get_update_params, :get_body_params
   alias_method :get_destroy_params, :get_body_params
 
+  # Remove read-only fields from a permitted params hash in place. `keep` lists field names to
+  # preserve even when read-only (e.g. the primary key on bulk update, used to locate records).
+  def _rrf_strip_read_only_fields(params, keep: [])
+    params.delete_if do |f, _|
+      next false if f.in?(keep)
+
+      cfg = self.class.field_configuration[f]
+      cfg && cfg[:read_only]
+    end
+  end
+
   # Get the set of records this controller has access to.
   def get_recordset
     return self.class.recordset if self.class.recordset
@@ -796,12 +885,16 @@ module RESTFramework::Controller
     # Find by another column if it's permitted.
     if find_by_param = self.class.find_by_query_param.presence
       if find_by = request.query_parameters[find_by_param].presence
-        find_by_fields = self.class.find_by_fields&.map(&:to_s) || self.get_fields
+        # Default to readable columns: excluding write_only keeps hidden values from being used as
+        # lookup keys, and restricting to real columns keeps virtual/method fields from reaching a
+        # doomed `find_by(<not a column>)` (which would raise on the DB).
+        find_by_fields = self.class.find_by_fields&.map(&:to_s) || self.readable_columns
 
-        if find_by.in?(find_by_fields)
-          is_pk = false unless find_by_key == find_by
-          find_by_key = find_by
-        end
+        # A `find_by` was explicitly requested, so it must be a permitted field.
+        raise ActiveRecord::RecordNotFound unless find_by.in?(find_by_fields)
+
+        is_pk = false unless find_by_key == find_by
+        find_by_key = find_by
       end
     end
 
@@ -834,6 +927,7 @@ module RESTFramework::Controller
   end
 end
 
+require_relative "controller/actions"
 require_relative "controller/bulk"
 require_relative "controller/crud"
 require_relative "controller/openapi"

data/lib/rest_framework/errors.rb

@@ -4,7 +4,7 @@ module RESTFramework::Errors
 
   class NilPassedToRenderAPIError < BaseError
     def message
-      <<~MSG.split("\n").join(" ")
+      <<~MSG.squish
         Payload of `nil` was passed to `render_api`; this is unsupported. If you want a blank
         response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
         (or similar Active Record method) not finding a record, you should use the bang version
@@ -26,6 +26,22 @@ module RESTFramework::Errors
     end
   end
 
+  class DelegatedMethodError < BaseError
+    def initialize(receiver, target)
+      @receiver = receiver.is_a?(Class) ? receiver : receiver.class
+      @target = target
+    end
+
+    def message
+      <<~MSG.squish
+        Delegated action `#{@target}` does not resolve to a public method on `#{@receiver}`. This is
+        almost certainly a typo, a missing method, or a method that should be public. Define a
+        public class method (for a collection action) or instance method (for a member action), or
+        remove the action.
+      MSG
+    end
+  end
+
   class BulkRecordErrorsError < BaseError
     attr_reader :errors
 
@@ -53,4 +69,5 @@ end
 RESTFramework::BaseError = RESTFramework::Errors::BaseError
 RESTFramework::NilPassedToRenderAPIError = RESTFramework::Errors::NilPassedToRenderAPIError
 RESTFramework::InvalidBulkParametersError = RESTFramework::Errors::InvalidBulkParametersError
+RESTFramework::DelegatedMethodError = RESTFramework::Errors::DelegatedMethodError
 RESTFramework::BulkRecordErrorsError = RESTFramework::Errors::BulkRecordErrorsError

data/lib/rest_framework/filters/base_filter.rb

@@ -6,6 +6,16 @@ class RESTFramework::Filters::BaseFilter
   def filter_data(data)
     raise NotImplementedError
   end
+
+  # True when `v` is a query-parameter value safe to feed into `where`, string
+  # operations, or `split` — i.e. a String or an Array of Strings. Guards against
+  # nested-hash inputs like `?field[evil]=x`, which Rack parses into a Hash and
+  # which AR cannot quote as a bind.
+  def self._safe_query_value?(v)
+    return true if v.is_a?(String)
+    return v.all? { |el| el.is_a?(String) } if v.is_a?(Array)
+    false
+  end
 end
 
 # Alias for convenience.