rest_framework 1.2.0 → 2.0.0.beta2

data/lib/rest_framework/filters/ordering_filter.rb

@@ -1,51 +1,71 @@
 # A filter backend which handles ordering of the recordset.
 class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilter
   def _get_fields
-    @controller.class.ordering_fields&.map(&:to_s) || @controller.get_fields
+    # Always return a list of strings; `@controller.readable_columns_or_associations` already does.
+    @controller.class.ordering_fields&.map(&:to_s) || @controller.readable_columns_or_associations
   end
 
-  # Convert ordering string to an ordering configuration.
+  # Convert the ordering param into an `[ordering, references]` pair: the ordering config for
+  # `order`/`reorder`, and the association names that must be joined for it to resolve.
   def _get_ordering
     return nil unless param = @controller.class.ordering_query_param.presence
 
     # Ensure ordering_fields are strings since the split param will be strings.
     fields = self._get_fields
-    order_string = @controller.params[param]
+    order_string = @controller.request.query_parameters[param]
 
-    if order_string.present?
-      ordering = {}.with_indifferent_access
+    # Reject nested-hash inputs like `?ordering[evil]=x` (Rack parses these into
+    # a Hash, which can't be split into ordering tokens).
+    return nil unless self.class._safe_query_value?(order_string)
+    return nil unless order_string.present?
 
-      order_string = order_string.join(",") if order_string.is_a?(Array)
-      order_string.split(",").map(&:strip).each do |field|
-        if field[0] == "-"
-          column = field[1..-1]
-          direction = :desc
-        else
-          column = field
-          direction = :asc
-        end
+    ordering = {}.with_indifferent_access
+    references = []
 
-        next if !column.in?(fields) && !column.split(".").first.in?(fields)
+    order_string = order_string.join(",") if order_string.is_a?(Array)
+    order_string.split(",").map(&:strip).each do |field|
+      if field[0] == "-"
+        column = field[1..-1]
+        direction = :desc
+      else
+        column = field
+        direction = :asc
+      end
 
+      # A plain, directly-allowlisted field.
+      if column.in?(fields)
         ordering[column] = direction
+        next
       end
 
-      return ordering
+      # A dotted `association.sub_field` token. The root must be an allowlisted association field,
+      # and the sub-field must be one of that association's allowlisted fields. Otherwise a client
+      # could order by (and infer, via an ordering oracle) a column that is never serialized.
+      root, sub = column.split(".", 2)
+      next unless sub && root.in?(fields)
+
+      cfg = @controller.class.field_configuration[root]
+      next unless cfg && sub.in?(cfg[:fields] || [])
+
+      ordering[column] = direction
+      references << root.to_sym
     end
 
-    nil
+    return nil if ordering.empty?
+
+    [ ordering, references ]
   end
 
   # Order data according to the request query parameters.
   def filter_data(data)
-    ordering = self._get_ordering
-    reorder = !@controller.class.ordering_no_reorder
+    ordering, references = self._get_ordering
+    return data unless ordering
 
-    if ordering && !ordering.empty?
-      return data.send(reorder ? :reorder : :order, ordering)
-    end
+    # Join any referenced associations so dotted ordering keys resolve instead of raising.
+    data = data.includes(*references).references(*references) if references.present?
 
-    data
+    reorder = !@controller.class.ordering_no_reorder
+    data.send(reorder ? :reorder : :order, ordering)
   end
 end
 

data/lib/rest_framework/filters/query_filter.rb

@@ -37,9 +37,14 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
   }.freeze
   PREDICATES_REGEX = /^(.*)_(#{PREDICATES.keys.join("|")})$/
 
+  # Predicates whose value may be an array (e.g. `?id_in[]=1&id_in[]=2`). Every other predicate
+  # operates on a single scalar and skips array input, which would otherwise raise: `cont` in
+  # `sanitize_sql_like`, the range predicates while casting the endpoint.
+  ARRAY_PREDICATES = %i[in not].freeze
+
   def _get_fields
-    # Always return a list of strings; `@controller.get_fields` already does this.
-    @controller.class.filter_fields&.map(&:to_s) || @controller.get_fields
+    # Always return a list of strings; `@controller.readable_columns_or_associations` already does.
+    @controller.class.filter_fields&.map(&:to_s) || @controller.readable_columns_or_associations
   end
 
   # Helper to find a variation of a field using a predicate. For example, there could be a field
@@ -66,6 +71,11 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
     pred_queries = []
 
     base_query = @controller.request.query_parameters.map { |field, v|
+      # Skip params whose values aren't bind-safe (e.g. a user submitted
+      # `?field[evil]=x`, which Rack parses into a Hash). AR can't quote
+      # those, and the predicate lambdas below would also blow up on them.
+      next nil unless self.class._safe_query_value?(v)
+
       # First, if field is a simple filterable field, return early.
       if field.in?(fields)
         next [ field, v ]
@@ -84,11 +94,11 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
         if sub_field
           next nil unless root_field.in?(fields)
 
-          sub_fields = @controller.class.field_configuration[root_field][:sub_fields] || []
-          if sub_field.in?(sub_fields)
+          association_fields = @controller.class.field_configuration[root_field][:fields] || []
+          if sub_field.in?(association_fields)
             includes << root_field.to_sym
             next [ field, v ]
-          elsif pred_sub_field && pred_sub_field.in?(sub_fields)
+          elsif pred_sub_field && pred_sub_field.in?(association_fields)
             includes << root_field.to_sym
             field = pred_field
           else
@@ -103,6 +113,10 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
       # value into a query that can be used in the ActiveRecord `where` API.
       cfg = PREDICATES[predicate.to_sym]
       if cfg.is_a?(Proc)
+        # Skip a scalar predicate given an array value (Rack parses `?field_cont[]=a&field_cont[]=b`
+        # into an array); only `in`/`not` accept arrays, the rest would raise.
+        next nil if v.is_a?(Array) && !predicate.to_sym.in?(ARRAY_PREDICATES)
+
         pred_queries << cfg.call(field, v)
       else
         pred_queries << { field => cfg }

data/lib/rest_framework/filters/search_filter.rb

@@ -1,19 +1,19 @@
 class RESTFramework::Filters::SearchFilter < RESTFramework::Filters::BaseFilter
   def _get_fields
-    if search_fields = @controller.class.search_fields
-      return search_fields&.map(&:to_s)
-    end
-
-    columns = @controller.class.model.column_names
-    @controller.get_fields.select { |f|
-      f.in?(RESTFramework.config.search_columns) && f.in?(columns)
-    }
+    # Always return a list of strings; `@controller.readable_columns` already does.
+    @controller.class.search_fields&.map(&:to_s) || (
+      @controller.readable_columns & RESTFramework.config.search_columns
+    )
   end
 
   # Filter data according to the request query parameters.
   def filter_data(data)
     search = @controller.request.query_parameters[@controller.class.search_query_param]
 
+    # Reject nested-hash inputs like `?search[evil]=x` (Rack parses these into a
+    # Hash, which `sanitize_sql_like` can't accept).
+    return data unless search.is_a?(String)
+
     if search.present?
       if fields = self._get_fields.presence
         # MySQL doesn't support casting to VARCHAR, so we need to use CHAR instead.

data/lib/rest_framework/paginators/page_number_paginator.rb

@@ -4,12 +4,19 @@
 class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators::BasePaginator
   def initialize(**kwargs)
     super
-    # Exclude any `select` clauses since that would cause `count` to fail with a SQL `SyntaxError`.
-    @count = @data.except(:select).count
     @page_size = self._page_size
+    @total_count = @controller.class.page_total_count
 
-    @total_pages = @count / @page_size
-    @total_pages += 1 if @count % @page_size != 0
+    # Compute the total count (and total pages) unless disabled. On large tables `page_total_count`
+    # can be set to `false` to skip this `COUNT(*)` over the whole filtered set; `next` is then
+    # derived by fetching one extra record in `get_page`.
+    if @total_count
+      # Exclude any `select` clauses, since that would cause `count` to fail with a SQL
+      # `SyntaxError`.
+      @count = @data.except(:select).count
+      @total_pages = @count / @page_size
+      @total_pages += 1 if @count % @page_size != 0
+    end
   end
 
   def _page_size
@@ -17,7 +24,7 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
 
     # Get from query param, if allowed.
     if param = @controller.class.page_size_query_param
-      if raw = @controller.params[param].presence
+      if raw = @controller.request.query_parameters[param].presence
         parsed = raw.to_i
         page_size = parsed if parsed > 0
       end
@@ -38,9 +45,9 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
 
   # Get the page and return it so the caller can serialize it.
   def get_page(page_number = nil)
-    # If page number isn't provided, infer from the params or use 1 as a fallback value.
+    # If page number isn't provided, infer from the query params or use 1 as a fallback value.
     unless page_number
-      page_number = @controller&.params&.[](@controller.class.page_query_param&.to_sym)
+      page_number = @controller&.request&.query_parameters&.[](@controller.class.page_query_param)
       if page_number.blank?
         page_number = 1
       else
@@ -54,14 +61,23 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
 
     # Get the data page and return it so the caller can serialize the data in the proper format.
     page_index = @page_number - 1
-    @data.limit(@page_size).offset(page_index * @page_size)
+    offset = page_index * @page_size
+
+    # Without a total count we can't derive `next` from `total_pages`, so detect whether a further
+    # page exists with a cheap existence check (a `LIMIT 1` past this page) instead of a full count.
+    unless @total_count
+      @has_next = @data.except(:select).offset(offset + @page_size).exists?
+    end
+
+    @data.limit(@page_size).offset(offset)
   end
 
   # Wrap the serialized page with appropriate metadata.
   def get_paginated_response(serialized_page)
     page_query_param = @controller.class.page_query_param
     base_params = @controller.request.query_parameters.symbolize_keys
-    next_url = if @page_number < @total_pages
+    has_next = @total_count ? @page_number < @total_pages : @has_next
+    next_url = if has_next
       @controller.url_for({ **base_params, page_query_param => @page_number + 1 })
     end
     previous_url = if @page_number > 1

data/lib/rest_framework/routers.rb

@@ -2,221 +2,85 @@ require "action_dispatch/routing/mapper"
 
 module ActionDispatch::Routing
   class Mapper
-    # Internal interface to get the controller class from the name and current scope.
-    def _get_controller_class(name, pluralize: true, fallback_reverse_pluralization: true)
-      # Get class name.
-      name = name.to_s.camelize  # Camelize to leave plural names plural.
-      name = name.pluralize if pluralize
-      if name == name.pluralize
-        name_reverse = name.singularize
-      else
-        name_reverse = name.pluralize
-      end
-      name += "Controller"
-      name_reverse += "Controller"
-
-      # Get scope for the class.
-      if @scope[:module]
-        mod = @scope[:module].to_s.camelize.constantize
-      else
-        mod = Object
-      end
-
-      # Convert class name to class.
-      begin
-        controller = mod.const_get(name)
-      rescue NameError
-        if fallback_reverse_pluralization
-          reraise = false
-
-          begin
-            controller = mod.const_get(name_reverse)
-          rescue NameError
-            reraise = true
-          end
-
-          if reraise
-            raise
-          end
-        else
-          raise
-        end
-      end
-
-      controller
+    # Resolve a controller class from a route name and the current scope. The name must match the
+    # controller exactly (camelized, plus `Controller`) — there is no pluralization fallback.
+    def _rrf_controller_class(name)
+      mod = @scope[:module] ? @scope[:module].to_s.camelize.constantize : Object
+      mod.const_get("#{name.to_s.camelize}Controller")
     end
 
-    # Internal interface for routing extra actions.
-    def _route_extra_actions(actions, &block)
-      parsed_actions = RESTFramework::Utils.parse_extra_actions(actions)
-
-      parsed_actions.each do |action, config|
-        config[:methods].each do |m|
-          public_send(m, config[:path], action: action, **config[:kwargs])
+    # Route each action from a controller's action store.
+    def _rrf_route_actions(actions)
+      actions.each_value do |spec|
+        # Delegated actions keep their declared action name (so routing and OpenAPI show the real
+        # name); `method_for_action` redirects dispatch to `rrf_delegate`, which needs the scope.
+        kwargs = spec.kwargs
+        if !spec.builtin && spec.metadata&.[](:delegate)
+          kwargs = kwargs.merge(rrf_delegate_scope: spec.type)
         end
 
-        # Record that this route is an extra action and any metadata associated with it.
-        metadata = config[:metadata]
-        key = "#{@scope[:path]}/#{config[:path]}"
-        RESTFramework::EXTRA_ACTION_ROUTES.add(key)
-        RESTFramework::ROUTE_METADATA[key] = metadata if metadata
-
-        yield if block_given?
-      end
-    end
-
-    # Internal core implementation of the `rest_resource(s)` router, both singular and plural.
-    # @param default_singular [Boolean] the default plurality of the resource if the plurality is
-    #   not otherwise defined by the controller
-    # @param name [Symbol] the resource name, from which path and controller are deduced by default
-    def _rest_resources(default_singular, name, **kwargs, &block)
-      controller = kwargs.delete(:controller) || name
-      if controller.is_a?(Class)
-        controller_class = controller
-      else
-        controller_class = self._get_controller_class(controller, pluralize: !default_singular)
-      end
-
-      # Set controller if it's not explicitly set.
-      kwargs[:controller] = name unless kwargs[:controller]
-
-      # Passing `unscoped: true` will prevent a nested resource from being scoped.
-      unscoped = kwargs.delete(:unscoped)
-
-      # Determine plural/singular resource.
-      if !controller_class.singleton_controller.nil?
-        singular = controller_class.singleton_controller
-      else
-        singular = default_singular
-      end
-      resource_method = singular ? :resource : :resources
-
-      # Call either `resource` or `resources`, passing appropriate modifiers.
-      skip = RESTFramework::Utils.get_skipped_builtin_actions(controller_class, singular)
-      public_send(resource_method, name, except: skip, **kwargs) do
-        if controller_class.respond_to?(:extra_member_actions)
-          member do
-            self._route_extra_actions(controller_class.extra_member_actions)
-          end
+        spec.methods.each do |m|
+          public_send(m, spec.path, action: spec.name, **kwargs)
         end
 
-        collection do
-          # Route extra controller-defined actions.
-          self._route_extra_actions(controller_class.extra_actions)
-
-          # Route extra RRF-defined actions.
-          RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|
-            next unless controller_class.method_defined?(action)
-
-            [ methods ].flatten.each do |m|
-              # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
-              # causes parent OPTIONS routes to greedily intercept sub-path requests.
-              public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
-            end
-          end
-
-          # Route bulk actions, if configured. These require a model and are gated by the `bulk`
-          # attribute, and may be individually excluded via `excluded_actions`.
-          if controller_class.model && controller_class.bulk
-            bulk_exclude = controller_class.excluded_actions&.to_set || Set.new
-            RESTFramework::RRF_BUILTIN_BULK_ACTIONS.each do |action, methods|
-              next unless controller_class.method_defined?(action)
-              next if bulk_exclude.include?(action)
+        # Record non-builtin (extra) actions and their metadata for the browsable API / OpenAPI.
+        next if spec.builtin
 
-              [ methods ].flatten.each do |m|
-                # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
-                # causes parent OPTIONS routes to greedily intercept sub-path requests.
-                public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
-              end
-            end
-          end
-        end
-
-        if unscoped
-          yield if block_given?
-        else
-          scope(module: name, as: name) do
-            yield if block_given?
-          end
-        end
+        key = "#{@scope[:path]}/#{spec.path}"
+        RESTFramework::EXTRA_ACTION_ROUTES.add(key)
+        RESTFramework::ROUTE_METADATA[key] = spec.metadata if spec.metadata
       end
     end
 
-    # Public interface for creating singular RESTful resource routes.
-    def rest_resource(*names, **kwargs, &block)
-      names.each do |n|
-        self._rest_resources(true, n, **kwargs, &block)
+    # Route one or more controllers from their action stores. Plural model controllers get
+    # collection/member scopes; singular and non-model controllers route everything at the root.
+    # Passing several names condenses simple routes into one call; per-name options (`path:`, `as:`,
+    # `controller:`, and a block) only apply to a single name.
+    def rest_route(*names, **kwargs, &block)
+      if names.size > 1 && (block || (kwargs.keys & [ :path, :as, :controller ]).any?)
+        raise ArgumentError, "rest_route: options and a block require a single name"
       end
-    end
 
-    # Public interface for creating plural RESTful resource routes.
-    def rest_resources(*names, **kwargs, &block)
-      names.each do |n|
-        self._rest_resources(false, n, **kwargs, &block)
-      end
+      names.each { |name| _rrf_rest_route(name, **kwargs, &block) }
     end
 
-    # Route a controller without the default resourceful paths.
-    def rest_route(name = nil, **kwargs, &block)
+    # Route a single controller from its action store.
+    def _rrf_rest_route(name, **kwargs)
       controller = kwargs.delete(:controller) || name
-      route_root_to = kwargs.delete(:route_root_to)
       if controller.is_a?(Class)
         controller_class = controller
       else
-        controller_class = self._get_controller_class(controller, pluralize: false)
+        controller_class = self._rrf_controller_class(controller)
       end
 
       # Set controller if it's not explicitly set.
       kwargs[:controller] = name unless kwargs[:controller]
 
-      # Passing `unscoped: true` will prevent a nested resource from being scoped.
-      unscoped = kwargs.delete(:unscoped)
-
-      # Route actions using the resourceful router, but skip all builtin actions.
-      public_send(:resource, name, only: [], **kwargs) do
-        # Route a root for this resource.
-        if route_root_to
-          get("", action: route_root_to, as: "")
-        end
-
-        collection do
-          # Route extra controller-defined actions.
-          self._route_extra_actions(controller_class.extra_actions)
-
-          # Route extra RRF-defined actions.
-          RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|
-            next unless controller_class.method_defined?(action)
-
-            [ methods ].flatten.each do |m|
-              # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
-              # causes parent OPTIONS routes to greedily intercept sub-path requests.
-              public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
-            end
+      has_model = !!controller_class.model
+      singular = controller_class.singular
+      actions = controller_class.actions
+      member_actions = controller_class.member_actions
+
+      # Use `resources` (plural) for plural model controllers to get the member `:id` scope; use
+      # `resource` (singular) for everything else.
+      resource_method = (has_model && !singular) ? :resources : :resource
+
+      public_send(resource_method, name, only: [], **kwargs) do
+        if has_model
+          if singular
+            # Singular model controller: actions and member actions are the same.
+            self._rrf_route_actions(actions)
+            self._rrf_route_actions(member_actions)
+          else
+            # Plural model controller: route collection/member actions separately.
+            collection { self._rrf_route_actions(actions) }
+            member { self._rrf_route_actions(member_actions) }
           end
-        end
-
-        if unscoped
-          yield if block_given?
         else
-          scope(module: name, as: name) do
-            yield if block_given?
-          end
+          # Non-model controller: only actions (there is no member `:id` scope).
+          self._rrf_route_actions(actions)
         end
-      end
-    end
-
-    # Route a controller's `#root` to '/' in the current scope/namespace, along with other actions.
-    def rest_root(name = nil, **kwargs, &block)
-      # By default, use RootController#root.
-      root_action = kwargs.delete(:action) || :root
-      controller = kwargs.delete(:controller) || name || :root
-
-      # Remove path if name is nil (routing to the root of current namespace).
-      unless name
-        kwargs[:path] = ""
-      end
 
-      rest_route(controller, route_root_to: root_action, **kwargs) do
         yield if block_given?
       end
     end

data/lib/rest_framework/serializers/active_model_serializer_adapter_factory.rb

@@ -1,6 +1,6 @@
 # This is a helper factory to wrap an ActiveModelSerializer to provide a `serialize` method which
 # accepts both collections and individual records. Use `.for` to build adapters.
-# :nocov:
+# simplecov:disable
 class RESTFramework::Serializers::ActiveModelSerializerAdapterFactory
   def self.for(active_model_serializer)
     Class.new(active_model_serializer) do
@@ -14,7 +14,7 @@ class RESTFramework::Serializers::ActiveModelSerializerAdapterFactory
     end
   end
 end
-# :nocov:
+# simplecov:enable
 
 # Alias for convenience.
 # rubocop:disable Layout/LineLength

data/lib/rest_framework/serializers/base_serializer.rb

@@ -16,7 +16,7 @@ class RESTFramework::Serializers::BaseSerializer
   end
 
   # Synonym for `serialize` for compatibility with `active_model_serializers`.
-  # :nocov:
+  # simplecov:disable
   def serializable_hash(*args)
     self.serialize(*args)
   end
@@ -35,7 +35,7 @@ class RESTFramework::Serializers::BaseSerializer
   def associations(*args, **kwargs)
     []
   end
-  # :nocov:
+  # simplecov:enable
 end
 
 # Alias for convenience.