rest_framework 1.1.0 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb2a69a51a24192200122bf40a9218e15e1f0d696bfdd63bb8f3aed9f43f82c
-  data.tar.gz: 3b630e5e5f8ec28096e245bc8ced22d5a63423d52799983543c1616b636999d8
+  metadata.gz: 6551a744b8574c83f8b5a482e32337e2ea554e4c572baf7c207af3bcda26fb38
+  data.tar.gz: d26a407bcf834d76a6f1d63e7ca22eafe05cd90197a50d53b016e178a2d92dd4
 SHA512:
-  metadata.gz: d0eae7105c8fe37a710ac56c9ba0c4df9b0f0663883d117123af6e778735c63117ca58d82e60e260e353aefcc9536e996848341a6537ca963d764b498dfba979
-  data.tar.gz: 72e217a7d2c9bed976d6801f333be3a97ebdedf1998b07fa4a4594c48256919dcd1cd4b48030582fc75bdd9e2e6d002dc29df931e217ab78cd97b87872f65c78
+  metadata.gz: b66138a6abd154cc8df980b6a533273dc5f6e5fd07bcb6d381e73254018cc065a1a2b01c6ae086f0eb6274a11501624a80f56ffd0f58657aa4f7c62145b74f7c
+  data.tar.gz: 8222dd29fb6de099e6f555438dcf1328a251a28f20076837176938ebc555a4c1f3d52df0acc77507150f6217058ce8f9dfa53f003641c1ab0e3914d515505348

data/README.md

@@ -3,7 +3,6 @@
 [![Gem Version](https://badge.fury.io/rb/rest_framework.svg)](https://badge.fury.io/rb/rest_framework)
 [![Pipeline](https://github.com/gregschmit/rails-rest-framework/actions/workflows/pipeline.yml/badge.svg)](https://github.com/gregschmit/rails-rest-framework/actions/workflows/pipeline.yml)
 [![Coverage](https://coveralls.io/repos/github/gregschmit/rails-rest-framework/badge.svg?branch=master)](https://coveralls.io/github/gregschmit/rails-rest-framework?branch=master)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ba5df7706cb544d78555/maintainability)](https://codeclimate.com/github/gregschmit/rails-rest-framework/maintainability)
 
 A framework for DRY RESTful APIs in Ruby on Rails.
 
@@ -44,49 +43,52 @@ To add REST framework features to a controller, include the `Controller` module:
 class ApiController < ApplicationController
   include RESTFramework::Controller
 
-  # Here is where you can set configuration class attributes that will propagate to child
-  # controllers.
-
-  # Setting up a paginator class here makes more sense than defining it on every child controller.
-  self.paginator_class = RESTFramework::PageNumberPaginator
-  self.page_size = 30
+  # Assignments are local by default; wrap shared config in `propagate` so child controllers inherit
+  # it. Settings you want every resource to share belong here rather than on each child controller.
+  propagate do
+    self.page_size = 30
+    self.max_page_size = 100
+  end
 end
 ```
 
+> **Note:** Configuration assignments are **local by default** — `self.x = value` sets `x` on that
+> controller alone and does not propagate to subclasses. To share a setting with every descendant
+> (pagination, filter backends, serializer config, and so on), wrap the assignment in a
+> `propagate` block on a base controller.
+
 Here is what the directory structure might look like for resource controllers:
 
 ```text
 controllers/
 ├─ api_controller.rb
 └─ api/
-   ├─ root_controller.rb
    ├─ movies_controller.rb
    └─ users_controller.rb
 ```
 
-### Root Controller
+### Serving the Root API Index
 
-It is typically a good pattern for the root of your API to have a dedicated `Api::RootController`
-outside the inheritance chain of your other API controllers, so that you can define actions on the
-root without them propagating to child controllers, and so you can set global configuration on the
-`ApiController`.
+A controller without a `model` renders its `index_content` at its index path, which serves as the
+API root. Because declared actions are local by default (they don't propagate to subclasses), you
+can serve the index — and any root-specific extra actions — straight from your API's base
+controller:
 
 ```ruby
-class Api::RootController < ApiController
-  self.extra_actions = {test: :get}
-
-  # The root action is routed by `rest_root`.
-  def root
-    render(
-      api: {
-        message: "Welcome to the API.",
-        how_to_authenticate: <<~END.lines.map(&:strip).join(" "),
-          You can use this API with your normal login session. Otherwise, you can insert your API
-          key into a Bearer Authorization header, or into the URL parameters with the name
-          `api_key`.
-        END
-      },
-    )
+class ApiController < ApplicationController
+  include RESTFramework::Controller
+
+  add_action(:test, :get)
+
+  # Rendered at the `/api` root. Defaults to the controller's `description`.
+  def index_content
+    {
+      message: "Welcome to the API.",
+      how_to_authenticate: <<~END.lines.map(&:strip).join(" "),
+        You can use this API with your normal login session. Otherwise, you can insert your API key
+        into a Bearer Authorization header, or into the URL parameters with the name `api_key`.
+      END
+    }
   end
 
   def test
@@ -97,14 +99,15 @@ end
 
 ### Resource Controllers
 
-Other API controllers can be associated to a resource/model by setting the `model` class attribute.
+Other API controllers can be associated to a resource/model by setting `model`, e.g.
+`self.model = Movie`.
 
 ```ruby
 class Api::MoviesController < ApiController
   self.model = Movie  # Automatically routes the standard CRUD actions for this controller.
   self.bulk = true  # Enables bulk create/update/destroy actions for this controller.
   self.fields = [:id, :name, :release_date, :enabled]
-  self.extra_member_actions = {first: :get}
+  add_action(:first, :get, type: :member)
 
   def first
     # Always use bang methods, since the framework will rescue `RecordNotFound` and return a
@@ -123,30 +126,29 @@ to include or exclude fields rather than defining them manually:
 
 ```ruby
 class Api::UsersController < ApiController
-  self.fields = {include: [:calculated_popularity], exclude: [:impersonation_token]}
+  # Include a method `popularity` and exclude the `impersonation_token` column.
+  self.fields = {include: [:popularity], exclude: [:impersonation_token]}
 
   # You can even disable some of the builtin actions. For example, this effectively makes the
   # resource read-only:
-  self.excluded_actions = [:create, :update, :destroy, :update_all, :destroy_all]
+  remove_actions(:create, :update, :destroy, :update_all, :destroy_all)
 end
 ```
 
 ### Routing
 
-Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful
-routers. These routers add some features to the Rails builtin `resource`/`resources` routers, such
-as automatically routing extra actions defined on the controller. To route the root, use
-`rest_root`.
+Use `rest_route` to route any controller. It wraps Rails' `resource` / `resources` routers, picking
+`resources` for a plural model controller and `resource` otherwise, and automatically routes the
+controller's built-in and extra actions. A controller with a `model` gets the full CRUD set; a
+modelless controller is routed at its root (its `index`, which renders `index_content`).
 
 ```ruby
 Rails.application.routes.draw do
-  # If you wanted to route actions from the `ApiController`, then you would use this:
-  # rest_root :api  # Will find `api_controller` and route the `root` action to '/api'.
+  rest_route :api  # `ApiController` serves the `/api` root.
 
   namespace :api do
-    rest_root  # Will route `Api::RootController#root` to '/' in this namespace ('/api').
-    rest_resources :movies
-    rest_resources :users
+    rest_route :movies
+    rest_route :users
   end
 end
 ```
@@ -163,3 +165,67 @@ web server and the job queue, which serves the test app and coverage/brakeman re
 - Test App: [http://127.0.0.1:3000](http://127.0.0.1:3000)
 - API: [http://127.0.0.1:3000/api](http://127.0.0.1:3000/api)
 - Reports: [http://127.0.0.1:3000/reports](http://127.0.0.1:3000/reports)
+
+## Version 2
+
+Version 2 is a substantial overhaul. The highlights below cover the major additions and behavior
+changes; the migration checklist that follows walks through updating an existing app.
+
+### New Features & Improvements
+
+- **Simpler setup** — a single `include RESTFramework::Controller` replaces the per-type `*Mixin`
+  modules.
+- **Local-by-default configuration** — assignments stay on the controller they're set on; wrap
+  shared settings in a `propagate` block to hand them down. Config no longer leaks silently onto
+  every resource.
+- **Declarative actions** — `add_action` / `remove_action` declare extra routes with an explicit
+  `member` / `collection` scope and per-declaration propagation, and can disable built-ins too,
+  replacing the `extra_actions` config hashes.
+- **Unified routing** — one `rest_route` (accepting several names) replaces `rest_resource` /
+  `rest_resources` / `rest_root`; a modelless controller serves the API root from its
+  `index_content`.
+- **Action delegation** — mark an action `metadata: { delegate: true }` to dispatch it to a model
+  class method (collection) or record method (member), passing query params through as args/kwargs.
+- **Consumer-driven association queries** (opt-in via `enable_association_queries`) — clients can
+  request extra fields for a serialized association (`?associations.<name>.fields=a,b,c`) and raise
+  its per-request record limit (`?associations.<name>.limit=N` or `all`), both bounded by a
+  per-association allowlist so an association never exposes more than its own endpoint would.
+- **`page_total_count`** — skip the `COUNT` query so pagination stays fast on very large tables.
+
+### Behavior Changes
+
+- **Pagination is on by default** (`PageNumberPaginator`, page size 20), so `index` responses are
+  bounded out of the box; opt out per controller with `paginator_class = nil`.
+- **Ordering and pagination read from the query string only**, never the request body.
+- **A `find_by` on a non-permitted field returns `404`** rather than matching a virtual or
+  serialized field.
+- **Delegated actions wrap their result under a `return` key**, and raise on a missing or non-public
+  target instead of silently 404-ing.
+- **Removed** `rrf_finalize` and the `auto_finalize` / `freeze_config` hooks.
+- **Security hardening** — per-element read-only stripping on bulk writes, an ordering-oracle fix,
+  sanitized `StatementInvalid` messages, and safer query-filter parsing.
+
+### Migrating from Older Versions
+
+See the guide for details on each item.
+
+- [ ] Replace the `*Mixin` modules with `include RESTFramework::Controller` on the core API
+      controller.
+- [ ] Set `self.model = ...` on every resource controller (it's no longer inferred from the name).
+- [ ] Wrap inherited config in a `propagate` block — assignments are now local by default.
+- [ ] Convert `extra_actions` / `extra_member_actions` hashes to `add_action` / `remove_action`.
+- [ ] Render custom actions with `render(api: ...)`, replacing the older `api_response(...)` /
+      `render_api(...)`.
+- [ ] Replace `rest_resource` / `rest_resources` / `rest_root` with `rest_route`.
+  - Fold any dedicated root controller into the namespace's base controller, which now serves the
+    root via `index_content` (the standalone `root` action and `rest_root` are gone).
+- [ ] Rename `singleton_controller` → `singular`.
+- [ ] Remove `rrf_finalize` calls and the `auto_finalize` / `freeze_config` config (all gone).
+- [ ] Expect paginated `index` responses by default (`self.paginator_class = nil` restores a bare
+      array).
+- [ ] Rename config: `sub_fields` → `fields`, `native_serializer_associations_limit[_max]` →
+      `association_limit[_max]`, `native_serializer_include_associations_count` →
+      `include_association_count`; the `?associations_limit=N` param is gone.
+- [ ] Note client-visible behavior changes: delegated actions wrap their result under a `return`
+      key; a non-permitted `find_by` returns `404`; `update_all` / `destroy_all` are plural-only;
+      ordering/pagination read from the query string only.

data/VERSION

@@ -1 +1 @@
-1.1.0
+2.0.0.beta1

data/app/views/rest_framework/routes_and_forms/_html_form.html.erb

@@ -18,7 +18,7 @@
     scope: "",
     local: true,
   }.compact) do |form| %>
-    <% controller.get_fields.map(&:to_s).each do |f| %>
+    <% controller.get_fields.each do |f| %>
       <%
         # Don't provide form fields for associations or read-only fields.
         cfg = controller.class.field_configuration[f]

data/lib/rest_framework/controller/actions.rb

@@ -0,0 +1,256 @@
+module RESTFramework::Controller
+  # Value object describing a routed action (builtin or user-declared).
+  ActionSpec = Struct.new(
+    :name, :type, :methods, :path, :metadata, :builtin, :kwargs, keyword_init: true
+  )
+
+  # Builtin actions keyed by name, each gated by a `condition` so only applicable ones surface in
+  # `actions` / `member_actions`. They route at the base path (`""`) of their scope.
+  RRF_BUILTIN_COLLECTION_ACTIONS = {
+    index: { methods: [ :get ], condition: ->(c) { !c.singular }, kwargs: { as: "" } },
+    create: { methods: [ :post ], condition: ->(c) { c.model } },
+    update_all: {
+      methods: [ :put, :patch ],
+      condition: ->(c) { c.model && c.bulk && !c.singular },
+      kwargs: { anchor: true },
+    },
+    destroy_all: {
+      methods: [ :delete ],
+      condition: ->(c) { c.model && c.bulk && !c.singular },
+      kwargs: { anchor: true },
+    },
+    options: { methods: [ :options ], condition: ->(_c) { true }, kwargs: { anchor: true } },
+  }.freeze
+  RRF_BUILTIN_MEMBER_ACTIONS = {
+    show: { methods: [ :get ], condition: ->(c) { c.model } },
+    update: { methods: [ :put, :patch ], condition: ->(c) { c.model } },
+    destroy: { methods: [ :delete ], condition: ->(c) { c.model } },
+  }.freeze
+
+  module ClassMethods
+    # Per-class action deltas (internal). Public because composition reads them off ancestors.
+    def _rrf_action_adds(type)
+      if type == :member
+        @_rrf_member_action_adds ||= {}
+      else
+        @_rrf_collection_action_adds ||= {}
+      end
+    end
+
+    def _rrf_action_removes(type)
+      if type == :member
+        @_rrf_member_action_removes ||= {}
+      else
+        @_rrf_collection_action_removes ||= {}
+      end
+    end
+
+    # Route an action, choosing the collection/member scope. Pass `type:` on a plural model
+    # controller, where the scopes differ; elsewhere the scope is implied — a singular controller's
+    # sole resource is a member (so `delegate` targets the record), a modelless one has only a
+    # collection — and `type:` warns as unnecessary (unless the action is delegated).
+    def add_action(name, methods, type: nil, **opts)
+      singular_model = self.model && self.singular
+
+      if self.model && !self.singular
+        _rrf_warn_action(name, methods, type, :ambiguous) if type.nil?
+      elsif singular_model && type && !opts[:metadata]&.[](:delegate)
+        _rrf_warn_action(name, methods, type, :redundant)
+      end
+
+      _rrf_add_action(type || (singular_model ? :member : :collection), name, methods, **opts)
+    end
+
+    # Remove an action from routing (including builtins). With no `type:`, both scopes are removed —
+    # keeping removal simple, and letting `propagate:` carry it to model descendants where member
+    # scope matters. Pass `type:` to target a single scope.
+    def remove_action(name, type: nil, propagate: false)
+      if type
+        _rrf_remove_action(type, name, propagate: propagate)
+      else
+        _rrf_remove_action(:collection, name, propagate: propagate)
+        _rrf_remove_action(:member, name, propagate: propagate)
+      end
+    end
+
+    def remove_actions(*names, type: nil, propagate: false)
+      names.each { |name| remove_action(name, type: type, propagate: propagate) }
+    end
+
+    # Source of truth: the effective collection / member actions (builtins + declared, composed
+    # across the inheritance chain), as an ordered `Hash{Symbol => ActionSpec}`.
+    def actions
+      _rrf_compose_actions(:collection)
+    end
+
+    def member_actions
+      _rrf_compose_actions(:member)
+    end
+
+    private
+
+    def _rrf_add_action(type, name, methods, path: nil, metadata: nil, propagate: false, **kwargs)
+      name = name.to_sym
+      spec = ActionSpec.new(
+        name: name,
+        type: type,
+        methods: Array(methods).map(&:to_sym),
+        path: (path || name).to_s,
+        metadata: metadata,
+        builtin: false,
+        kwargs: kwargs,
+      )
+      _rrf_action_removes(type).delete(name)
+      _rrf_action_adds(type)[name] = { spec: spec, propagate: _rrf_normalize_propagate(propagate) }
+    end
+
+    def _rrf_remove_action(type, name, propagate: false)
+      name = name.to_sym
+      _rrf_action_adds(type).delete(name)
+      _rrf_action_removes(type)[name] = { propagate: _rrf_normalize_propagate(propagate) }
+    end
+
+    # Normalize `propagate:` to `false` (local), `true` (self + descendants), or `:exclude_self`
+    # (descendants only). Non-standard values warn: `nil` becomes `false`, anything else truthy
+    # becomes `true`.
+    def _rrf_normalize_propagate(value)
+      case value
+      when false
+        false
+      when true, :exclude_self
+        value
+      when nil
+        Rails.logger.warn("RRF: `propagate: nil` is nonstandard; treating as `false`.")
+        false
+      else
+        Rails.logger.warn("RRF: invalid `propagate:` value #{value.inspect}; treating as `true`.")
+        true
+      end
+    end
+
+    # Whether an entry with the given `propagate`, declared on some class, reaches the controller
+    # we're composing for. `is_self` is true when that class is the controller itself.
+    def _rrf_reaches?(propagate, is_self)
+      case propagate
+      when :exclude_self
+        !is_self
+      when true
+        true
+      else # false
+        is_self
+      end
+    end
+
+    def _rrf_builtins(type)
+      type == :member ? RRF_BUILTIN_MEMBER_ACTIONS : RRF_BUILTIN_COLLECTION_ACTIONS
+    end
+
+    def _rrf_compose_actions(type)
+      effective = {}
+
+      # 1. Seed with the builtins whose condition holds for this controller.
+      _rrf_builtins(type).each do |name, cfg|
+        next unless cfg[:condition].call(self)
+
+        effective[name] = ActionSpec.new(
+          name: name,
+          type: type,
+          methods: cfg[:methods],
+          path: "",
+          metadata: nil,
+          builtin: true,
+          kwargs: cfg[:kwargs] || {},
+        )
+      end
+
+      # 2. Walk RRF ancestors from farthest to nearest (ending at self), applying each class's
+      #    removes then adds that reach us. Removes-before-adds lets a subclass re-add something an
+      #    ancestor removed; later (nearer) classes win.
+      _rrf_action_chain.each do |klass|
+        is_self = klass.equal?(self)
+
+        klass._rrf_action_removes(type).each do |name, remove|
+          effective.delete(name) if _rrf_reaches?(remove[:propagate], is_self)
+        end
+
+        klass._rrf_action_adds(type).each do |name, add|
+          effective[name] = add[:spec] if _rrf_reaches?(add[:propagate], is_self)
+        end
+      end
+
+      effective
+    end
+
+    def _rrf_action_chain
+      self.ancestors.select { |a| a.is_a?(Class) && a.respond_to?(:_rrf_action_adds) }.reverse
+    end
+
+    # Build the `type:` warning for `add_action`, echoing the call so its source is easy to find.
+    def _rrf_warn_action(name, methods, type, reason)
+      type_arg = type ? ", type: #{type.inspect}" : ""
+      sig = "add_action(#{name.inspect}, #{methods.inspect}#{type_arg})"
+
+      detail =
+        if reason == :ambiguous
+          "needs an explicit `type:` (`:collection` or `:member`); collection and member route " \
+            "differently on a plural model controller"
+        else
+          "has an unnecessary `type:`; member and collection route the same path on a singular " \
+            "model controller"
+        end
+
+      Rails.logger.warn("RRF: `#{sig}` #{detail}.")
+    end
+  end
+
+  # Delegated actions (`metadata: { delegate: true }`) dispatch through `rrf_delegate` while keeping
+  # their declared name for routing and introspection. The route marks itself delegated with the
+  # `rrf_delegate_scope` path parameter, so dispatch is route-based and never collides with a
+  # same-named method.
+  def method_for_action(action_name)
+    request&.path_parameters&.key?(:rrf_delegate_scope) ? "rrf_delegate" : super
+  end
+
+  # Dispatch a delegated action to the model class (collection) or the record (member). Its declared
+  # name is `action_name`; its scope comes from the route.
+  def rrf_delegate
+    target = self.action_name.to_sym
+    member = request.path_parameters[:rrf_delegate_scope].to_s == "member"
+    receiver = member ? self.get_record : self.class.model
+
+    # Delegation targets must be public methods. Anything else — a private/protected method, or a
+    # name that resolves to nothing — is developer misconfiguration (a typo, a missing method, or a
+    # method that should be public), so raise loudly rather than dispatch or mask it as a 404.
+    unless receiver.respond_to?(target)
+      raise RESTFramework::DelegatedMethodError.new(receiver, target)
+    end
+
+    parameters = receiver.method(target).parameters
+    query = request.query_parameters
+
+    # Positional arguments come from the reserved `args` param: a scalar becomes a single
+    # positional, an array is splatted as all of them.
+    args = query.key?("args") ? Array.wrap(query["args"]) : []
+
+    # Remaining query params splat as kwargs only when the method accepts arbitrary keywords
+    # (`**opts`); scan all params so a trailing block (`&blk`) doesn't hide the `:keyrest`.
+    kwargs = if parameters.any? { |type, _| type == :keyrest }
+      query.except("args").symbolize_keys
+    else
+      {}
+    end
+
+    result = receiver.public_send(target, *args, **kwargs)
+
+    # Serialize Active Record return values through the framework serializer (honoring field
+    # exclusions); `render_api` only does this for top-level payloads, and we nest under `return`.
+    if result.is_a?(ActiveRecord::Base) || result.is_a?(ActiveRecord::Relation)
+      result = self.serialize(result)
+    end
+
+    # Wrap the result under a `return` key rather than rendering it at the top level: the method may
+    # return `nil` (which `render_api` rejects) or a bare scalar/array that isn't a good serializer
+    # root, and this leaves room to attach metadata alongside it later.
+    render_api({ return: result })
+  end
+end