rest_framework 2.0.0.beta3 → 2.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cedfa02dac90388b712f4e15e29d07a40e45df23847bebf5da02eea03862e75
-  data.tar.gz: 2de9c962810e9473dd5eb68c2ee42da764ed793e341049a49d9f4ca8d34fa48e
+  metadata.gz: e483f8e7b422c2a45545f8c6e5d6313cc8a3df9dc286e76d4a6f09b9c717d9bf
+  data.tar.gz: 16d95dda8928c50b01cbc9cc291778928c9023d77e05c35f51cc9c8411a4c7d0
 SHA512:
-  metadata.gz: f52b1b1075fef181d9e771df56f1c088c73601d600606411974febb1bb544facacc7d16d83c2b34929acc0d0f44a0e518098a3a121fcdf27f7e5f12be3a5d8ca
-  data.tar.gz: c08ffc3af87bb7d7337dd1a908c7c6199fa3e70328b06dbebd1a691a0c3f235224b0119026eda4274f555385254383d2a7a29719b339f5c487f0ee82a7b2bcd2
+  metadata.gz: 05ae9adf0e303bc8aa23acda8d33f8e2026de7e123ec57a1c51dc030b92b25caed62d872badf76b9c8e3c0f549c5899b59c3352b2620c767b61d4e1b1ac34672
+  data.tar.gz: ca6913825b5eaf6c6545359c494b8b38eae2deb87e285ed8d1e761ab38700f1f0e2be4469d3ab6c604bc98d30918b4c1c40ce0098d32027e0bed52db51c2b049

data/README.md

@@ -137,18 +137,20 @@ end
 
 ### Routing
 
-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`).
+Use `rest_resource` to route a controller (`rest_resources` routes several that share options). They
+wrap Rails' `resource` / `resources` routers, picking `resources` for a plural model controller and
+`resource` otherwise — so plurality follows the controller's config, not the helper name. Built-in
+and extra actions are routed automatically: a controller with a `model` gets the full CRUD set; a
+modelless controller is routed at its root (its `index`, which renders `index_content`). A block
+nests resources, and a nested recordset is auto-scoped to its parent (`/movies/:movie_id/genres` →
+`Movie.find(params[:movie_id]).genres`).
 
 ```ruby
 Rails.application.routes.draw do
-  rest_route :api  # `ApiController` serves the `/api` root.
+  rest_resource :api  # `ApiController` serves the `/api` root.
 
   namespace :api do
-    rest_route :movies
-    rest_route :users
+    rest_resources :movies, :users
   end
 end
 ```
@@ -181,9 +183,9 @@ changes; the migration checklist that follows walks through updating an existing
 - **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`.
+- **Simpler routing** — `rest_resource` routes one controller and `rest_resources` routes several
+  (plurality of the *routes* follows the controller's config, not the helper name); `rest_root` and
+  `rest_route` are gone, and nested resources are auto-scoped to their parent.
 - **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
@@ -218,7 +220,8 @@ See the guide for details on each item.
 - [ ] 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`.
+- [ ] Replace `rest_root` and `rest_route` with `rest_resource` (single controller) or
+      `rest_resources` (several) — plurality of the routes now comes from controller config.
 - [ ] 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`.

data/VERSION

@@ -1 +1 @@
-2.0.0.beta3
+2.0.0.beta5

data/lib/rest_framework/controller.rb

@@ -3,6 +3,7 @@
 # module rather than defining a separate submodule.
 module RESTFramework::Controller
   RRF_BASE_CONFIG = {
+    model: nil,
     singular: nil,
 
     # Options related to metadata and display.
@@ -12,10 +13,6 @@ module RESTFramework::Controller
     inflect_acronyms: RESTFramework.config.inflect_acronyms,
     openapi_include_children: false,
 
-    # Options related to models.
-    model: nil,
-    recordset: nil,
-
     # Bulk configuration.
     #
     # When `bulk` is truthy, it enables the default bulk behavior (`:default`), which is per-record
@@ -98,6 +95,10 @@ module RESTFramework::Controller
     # Option for `recordset.create` vs `Model.create` behavior.
     create_from_recordset: true,
 
+    # Options for scoped nested routing.
+    scope_nested_by_parent: true,
+    scope_nested_through_controllers: true,
+
     # Options related to serialization.
     rescue_unknown_format_with: :json,
     serializer_class: nil,
@@ -651,6 +652,15 @@ module RESTFramework::Controller
     self.get_fields.reject { |f| cfg[f]&.[](:write_only) }
   end
 
+  # The fields a client may write (create/update): `get_fields` minus read_only fields. Excluding
+  # them here — before strong parameters expand associations into `_id`/`_ids`/`_attributes` keys —
+  # keeps a read_only association from ever producing a permitted (and otherwise unstrippable, since
+  # those keys don't match a field name) assignment key.
+  def writable_fields
+    cfg = self.class.field_configuration
+    self.get_fields.reject { |f| cfg[f]&.[](:read_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
@@ -673,12 +683,14 @@ module RESTFramework::Controller
     @_get_allowed_parameters = self.class.allowed_parameters
     return @_get_allowed_parameters if @_get_allowed_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).
+    # Assemble strong parameters from writable fields only, so read-only fields never produce a
+    # permitted key — including the `_id`/`_ids`/`_attributes` variations an association expands
+    # into, which a later key-name-based filter couldn't catch. Bulk update re-permits the primary
+    # key (see `get_body_params`) since it needs it to locate each record.
     variations = []
     hash_variations = {}
     reflections = self.class.model.reflections
-    @_get_allowed_parameters = self.get_fields.map { |f|
+    @_get_allowed_parameters = self.writable_fields.map { |f|
       f = f.to_s
       config = self.class.field_configuration[f]
 
@@ -823,47 +835,90 @@ module RESTFramework::Controller
       body_params[k].unshift(*v)
     end
 
-    # 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
   end
   alias_method :get_create_params, :get_body_params
   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)
+  # Get the set of records this controller has access to. Override this to scope records (e.g. to
+  # the current user); the default scopes to a nested parent resource when one is present in the
+  # path, otherwise the model's default scope (all records).
+  def get_recordset
+    return nil unless self.class.model
 
-      cfg = self.class.field_configuration[f]
-      cfg && cfg[:read_only]
-    end
+    self._rrf_nested_parent_recordset || self.class.model.all
   end
 
-  # Get the set of records this controller has access to.
-  def get_recordset
-    return self.class.recordset if self.class.recordset
+  # For a nested route, walk the whole parent chain in path order and return the innermost
+  # collection of this controller's model — e.g. `/movies/:movie_id/genres/:genre_id/tracks` becomes
+  # `Movie.find(movie_id).genres.find(genre_id).tracks`. Every link is enforced (a broken one raises
+  # `RecordNotFound` -> 404), and each association is resolved from its parent, so `belongs_to`,
+  # `has_many`, and `has_and_belongs_to_many` children all work. Each parent is looked up via its
+  # own controller's recordset (see `scope_nested_through_controllers`), so per-level access scoping
+  # is enforced. Returns `nil` when there is no nested parent, or a `<name>_id` param can't connect.
+  def _rrf_nested_parent_recordset
+    # Set on an ad-hoc parent instance below, so evaluating a parent's `get_recordset` doesn't
+    # recurse back into nested scoping (we want the parent's own scope, not to re-nest it).
+    return nil if @_rrf_scoping_parent
+    return nil unless self.class.scope_nested_by_parent && request
+
+    # `<name>_id` path parameters that name a model, in route order (outermost parent first).
+    parents = request.path_parameters.filter_map { |key, value|
+      key = key.to_s
+      next unless key.end_with?("_id")
+
+      model = key.delete_suffix("_id").classify.safe_constantize
+      next unless model.is_a?(Class) && model < ActiveRecord::Base
+
+      [ model, value ]
+    }
+    return nil if parents.empty?
+
+    # Find the outermost parent within its controller's scope, then descend: each next parent is
+    # constrained both to the previous parent's association and to its own controller's scope.
+    record = nil
+    parents.each do |model, id|
+      scope = _rrf_parent_recordset(model)
+
+      unless record.nil?
+        assoc = _rrf_collection_association_name(record.class, model)
+        return nil unless assoc
 
-    # If there is a model, return that model's default scope (all records by default).
-    if self.class.model
-      return self.class.model.all
+        scope = record.public_send(assoc).merge(scope)
+      end
+
+      record = scope.find(id)
     end
 
-    nil
+    # Finally, the innermost parent's collection of this controller's model.
+    assoc = _rrf_collection_association_name(record.class, self.class.model)
+    return nil unless assoc
+
+    record.public_send(assoc)
+  end
+
+  # A parent's recordset for the nested-scope walk: its own controller's `get_recordset` (so that
+  # controller's access scoping is reused), or the bare model when the feature is off or no sibling
+  # controller is found. The ad-hoc instance shares this request and skips its own nested scoping.
+  def _rrf_parent_recordset(model)
+    return model.all unless self.class.scope_nested_through_controllers
+
+    controller = RESTFramework::Utils.controller_for_model(self.class, model)
+    return model.all unless controller
+
+    instance = controller.new
+    instance.request = request
+    instance.response = response
+    instance.instance_variable_set(:@_rrf_scoping_parent, true)
+    instance.get_recordset
+  end
+
+  # The name of `klass`'s collection association whose records are `target_model`, or `nil`.
+  def _rrf_collection_association_name(klass, target_model)
+    klass.reflect_on_all_associations.find { |ref|
+      ref.collection? && !ref.polymorphic? && ref.klass == target_model
+    }&.name
   end
 
   # Filter the recordset and return records this request has access to.

data/lib/rest_framework/routers.rb

@@ -32,20 +32,12 @@ module ActionDispatch::Routing
       end
     end
 
-    # 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
-
-      names.each { |name| _rrf_rest_route(name, **kwargs, &block) }
-    end
-
-    # Route a single controller from its action store.
-    def _rrf_rest_route(name, **kwargs)
+    # Route a single controller from its action store. Whether it routes as a singular `resource` or
+    # a plural `resources` is decided by the controller's own config (`singular`, and whether it has
+    # a `model`) — not by the method name: a plural model controller gets collection/member scopes,
+    # while singular and non-model controllers route everything at the root. Pass a block to nest
+    # resources like Rails' `resources` (the nested controller resolves in the current scope).
+    def rest_resource(name, **kwargs)
       controller = kwargs.delete(:controller) || name
       if controller.is_a?(Class)
         controller_class = controller
@@ -84,5 +76,17 @@ module ActionDispatch::Routing
         yield if block_given?
       end
     end
+
+    # Route several controllers that share the same options in one call — handy for condensing a
+    # namespace. Per-name options (`path:`, `as:`, `controller:`) and a block only make sense for a
+    # single controller, so they're rejected when several names are given. The `s` is about routing
+    # multiple controllers, not plural routes — a single plural controller is still `rest_resource`.
+    def rest_resources(*names, **kwargs, &block)
+      if names.size > 1 && (block || (kwargs.keys & [ :path, :as, :controller ]).any?)
+        raise ArgumentError, "rest_resources: per-name options and a block require a single name"
+      end
+
+      names.each { |name| rest_resource(name, **kwargs, &block) }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta3
+  version: 2.0.0.beta5
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails