rest_framework 2.0.0.beta4 → 2.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b09674d62848416f77b39e23bc7b586e105786c7605320ad61761fe76ebc033
-  data.tar.gz: d8242a8db125185c3b1d778f4b4f2697a174d0bf17f796329cc4a0dfa11be99e
+  metadata.gz: e483f8e7b422c2a45545f8c6e5d6313cc8a3df9dc286e76d4a6f09b9c717d9bf
+  data.tar.gz: 16d95dda8928c50b01cbc9cc291778928c9023d77e05c35f51cc9c8411a4c7d0
 SHA512:
-  metadata.gz: 8399d7751f5116a6196853e64c704f153c33e0a79923fa6fa0c12a3867f0669f3f7651f6ea4528b5bd976a76ea7e2e2604a87fcb1c39116d0148c79e34d36d30
-  data.tar.gz: f32a2db5595e8aee9dc069aa4fcaf6f96fffc35cb69b4ebc2d76589951a5dc1fdcdeae46631ad5af1506dbb365d07749461e12702ca8b36d7f1afa12e3922e83
+  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.beta4
+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,
@@ -840,16 +841,84 @@ module RESTFramework::Controller
   alias_method :get_update_params, :get_body_params
   alias_method :get_destroy_params, :get_body_params
 
-  # Get the set of records this controller has access to.
+  # 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 self.class.recordset if self.class.recordset
+    return nil unless self.class.model
+
+    self._rrf_nested_parent_recordset || self.class.model.all
+  end
+
+  # 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.beta4
+  version: 2.0.0.beta5
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails