rest_framework 2.0.0.beta6 → 2.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7be6812ae478ca58b5f352bf561a57384d309e2a91037d25cf1ad3dbe64ff09
-  data.tar.gz: a2295b59abd1f6e15fa0736b3e5255f00492a0cdc794583b87b85634533cb003
+  metadata.gz: 358f030b86e0232e68278653fae211e71cf1efe419c7050119118d36169b1e2b
+  data.tar.gz: 7b28aa42477c3a4eb9aad33dbdc78220e12fe5a4f359b701cee0dde999e1aa84
 SHA512:
-  metadata.gz: 6a92158c48314c5fb62470cde91d5b21d264e60b8d3d367315b20014965cceaee9bef5ff019c32cc3ef75fb9a45a410cc63373d2dc9c00fa295f6626ec279a6b
-  data.tar.gz: a332502f06c34126962890d6e4b395d5788c8dd1c07d5bd0cfbbcb33d49ec209efad4986d99f1f69ec0f86569b175bb902a11aee76cb21f4942546e256e0239b
+  metadata.gz: 69483cd5c46acd3e01e64af5336ce9e3b230448d66e159804fe3af706d1670d6ec32d60c03bf9dde682e846759aa0769898cb12e46b8b73e25167765fb739a80
+  data.tar.gz: fb65b66a849de488b55ea19e085cc33d7e06ca5bffc70c0cc24788970fbbe9921e017f1bd196bc374b51a904cf4df22b5ba3f4e9b97abb8a59010e401bf07b57

data/README.md

@@ -67,7 +67,7 @@ controllers/
    └─ users_controller.rb
 ```
 
-### Serving the Root API Index
+### Serving the Base API Index
 
 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
@@ -168,6 +168,29 @@ web server and the job queue, which serves the test app and coverage/brakeman re
 - 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)
 
+### Releasing
+
+The gem version is in `lib/rest_framework/version.rb`. Cutting a release means bumping that
+constant, tagging, and pushing; the pipeline builds the gem from the constant and pushes it to
+RubyGems when it sees the tag.
+
+Use `bin/release` with the exact version. It bumps the version constant, refreshes `Gemfile.lock`,
+folds both into a single commit, and creates the annotated tag `v<version>` (via the
+[gem-release](https://github.com/svenfuchs/gem-release) gem). The lock refresh matters because
+`rest_framework` is a path gem: if the tagged commit's lock doesn't match the bumped gemspec, CI's
+frozen `bundle install` fails with "the gemspecs for path gems changed". Run it from the `master`
+branch with a clean working tree:
+
+```shell
+bin/release 2.0.0.rc1   # cut a release candidate
+```
+
+Review, then push to publish:
+
+```shell
+git push origin master --follow-tags
+```
+
 ## Version 2
 
 Version 2 is a substantial overhaul. The highlights below cover the major additions and behavior
@@ -230,7 +253,16 @@ See the guide for details on each item.
       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.
+      `include_association_count`, `native_serializer_{only,except,include,exclude}_query_param` →
+      `{only,except,include,exclude}_query_param`; the `?associations_limit=N` param is gone.
+- [ ] Move `field_config` into `fields`: it's now the `config:` key of the `fields` hash
+      (`self.fields = { only: [...], config: { email: { label: "Email Address" } } }`). A field
+      named in `config:` is implicitly part of the set. An association's `fields:` takes the same
+      spec form (an array, or an `only:`/`include:`/`exclude:`/`config:` hash), replacing the old
+      nested `field_config:` key.
+- [ ] Replace the `native_serializer_config` / `native_serializer_singular_config` /
+      `native_serializer_plural_config` attributes with a custom `serializer_class` — a
+      `NativeSerializer` subclass carrying `config` / `singular_config` / `plural_config`.
 - [ ] 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/lib/rest_framework/controller/actions.rb

@@ -50,7 +50,10 @@ module RESTFramework::Controller
     # 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).
+    # collection — and `type:` warns as unnecessary (unless the action is delegated). `propagate:`
+    # also accepts a `->(controller) { ... }` predicate to gate the action: it applies to this
+    # controller and its descendants wherever the predicate holds — e.g. `->(c) { c.model }` routes
+    # it only on controllers with a model.
     def add_action(name, methods, type: nil, **opts)
       singular_model = self.model && self.singular
 
@@ -112,9 +115,10 @@ module RESTFramework::Controller
       _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`.
+    # Normalize `propagate:` to `false` (local), `true` (self + descendants), `:exclude_self`
+    # (descendants only), or a `->(controller) { ... }` predicate (self + descendants, wherever it
+    # returns truthy). Non-standard values warn: `nil` becomes `false`, anything else truthy becomes
+    # `true`.
     def _rrf_normalize_propagate(value)
       case value
       when false
@@ -125,21 +129,25 @@ module RESTFramework::Controller
         Rails.logger.warn("RRF: `propagate: nil` is nonstandard; treating as `false`.")
         false
       else
+        return value if value.respond_to?(:call)
+
         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)
+    # Whether an entry with the given `propagate`, declared on some class, reaches `controller` (the
+    # class we're composing for). `is_self` is true when the declaring class is `controller` itself.
+    def _rrf_reaches?(propagate, is_self, controller)
       case propagate
       when :exclude_self
         !is_self
       when true
         true
-      else # false
+      when false
         is_self
+      else # a `->(controller) { ... }` predicate: applies wherever it holds (self and descendants)
+        propagate.call(controller)
       end
     end
 
@@ -172,11 +180,11 @@ module RESTFramework::Controller
         is_self = klass.equal?(self)
 
         klass._rrf_action_removes(type).each do |name, remove|
-          effective.delete(name) if _rrf_reaches?(remove[:propagate], is_self)
+          effective.delete(name) if _rrf_reaches?(remove[:propagate], is_self, self)
         end
 
         klass._rrf_action_adds(type).each do |name, add|
-          effective[name] = add[:spec] if _rrf_reaches?(add[:propagate], is_self)
+          effective[name] = add[:spec] if _rrf_reaches?(add[:propagate], is_self, self)
         end
       end
 

data/lib/rest_framework/controller/openapi.rb

@@ -183,9 +183,11 @@ module RESTFramework::Controller
           v[:writeOnly] = true if cfg[:write_only]
           v[:default] = cfg[:default] if cfg.key?(:default)
 
-          if enum_variants = cfg[:enum_variants]
-            v[:enum] = enum_variants.keys
-            v[:"x-rrf-enum_variants"] = enum_variants
+          if (options = cfg[:options]).present?
+            # Emit `oneOf` for options, but also emit `enum` for true ActiveRecord enums, since some
+            # older tooling reads `enum` but not `oneOf`.
+            v[:oneOf] = options.map { |value, label| { const: value, title: label } }
+            v[:enum] = options.keys if cfg[:enum]
           end
 
           if validators = cfg[:validators]
@@ -196,15 +198,21 @@ module RESTFramework::Controller
 
           if cfg[:reflection]
             ref = cfg[:reflection]
+
+            # A polymorphic `belongs_to` has no single target class, so class-derived properties
+            # (`association_primary_key`, `join_table`) raise; expose the `*_type` column instead.
+            polymorphic = ref.respond_to?(:polymorphic?) && ref.polymorphic?
             v[:"x-rrf-reflection"] = {
+              polymorphic: polymorphic || nil,
               class_name: ref.respond_to?(:class_name) ? ref.class_name : nil,
               foreign_key: ref.respond_to?(:foreign_key) ? ref.foreign_key : nil,
+              foreign_type: polymorphic ? ref.foreign_type : nil,
               association_foreign_key: ref.respond_to?(:association_foreign_key) ?
                 ref.association_foreign_key : nil,
-              association_primary_key: ref.respond_to?(:association_primary_key) ?
+              association_primary_key: !polymorphic && ref.respond_to?(:association_primary_key) ?
                 ref.association_primary_key : nil,
               inverse_of: ref.respond_to?(:inverse_of) ? ref.inverse_of&.name : nil,
-              join_table: ref.respond_to?(:join_table) ? ref.join_table : nil,
+              join_table: !polymorphic && ref.respond_to?(:join_table) ? ref.join_table : nil,
             }.compact
             v[:"x-rrf-association_pk"] = cfg[:association_pk]
             v[:"x-rrf-association_fields"] = cfg[:fields]

data/lib/rest_framework/controller.rb

@@ -26,9 +26,10 @@ module RESTFramework::Controller
     bulk_max_size: nil,
     bulk_max_raw_size: nil,
 
-    # Configuring record fields.
+    # Configuring record fields. `fields` is the single source of truth: an Array (sugar for
+    # `only:`), or a Hash of `only:`/`include:`/`exclude:`/`except:` (set membership) plus `config:`
+    # (per-field configuration, keyed by field name).
     fields: nil,
-    field_config: nil,
     read_only_fields: RESTFramework.config.read_only_fields,
     write_only_fields: RESTFramework.config.write_only_fields,
     hidden_fields: nil,
@@ -40,32 +41,19 @@ module RESTFramework::Controller
     # Handling request body parameters.
     allowed_parameters: nil,
 
-    # Options for the default native serializer.
-    native_serializer_config: nil,
-    native_serializer_singular_config: nil,
-    native_serializer_plural_config: nil,
-    native_serializer_only_query_param: "only".freeze,
-    native_serializer_except_query_param: "except".freeze,
-    native_serializer_include_query_param: "include".freeze,
-    native_serializer_exclude_query_param: "exclude".freeze,
+    # Query params for the default native serializer's field selection.
+    only_query_param: "only".freeze,
+    except_query_param: "except".freeze,
+    include_query_param: "include".freeze,
+    exclude_query_param: "exclude".freeze,
 
     # 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.
+    # Options for association serialization.
     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,
 
@@ -95,10 +83,6 @@ 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,
@@ -283,7 +267,8 @@ module RESTFramework::Controller
     def field_configuration
       return @field_configuration if @field_configuration
 
-      field_config = self.field_config&.with_indifferent_access || {}
+      field_config = (self.fields.is_a?(Hash) ? self.fields[:config] : nil)
+        &.with_indifferent_access || {}
       columns = self.model.columns_hash
       column_defaults = self.model.column_defaults
       reflections = self.model.reflections
@@ -301,34 +286,23 @@ module RESTFramework::Controller
         cfg = field_config[f]&.dup || {}
         cfg[:label] ||= self.label_for(f)
 
+        # An explicit `read_only`/`write_only` in `field_config` wins over every framework default
+        # below (primary key, readonly attributes, the read/write-only config lists, and the
+        # method-field default), so those only apply when the developer set neither.
+        read_write_only_set = cfg.key?(:read_only) || cfg.key?(:write_only)
+
         # Annotate primary key.
         if self.model.primary_key == f
           cfg[:primary_key] = true
-
-          unless cfg.key?(:read_only)
-            cfg[:read_only] = true
-          end
+          cfg[:read_only] = true unless read_write_only_set
         end
 
         # Annotate field mutability and display properties.
-        cfg[:read_only] = true if f.in?(readonly_attributes) || f.in?(read_only_fields)
-        cfg[:write_only] = true if f.in?(write_only_fields)
-        cfg[:hidden] = true if f.in?(hidden_fields)
-
-        # Raise warnings on some bad combinations of properties.
-        if cfg[:write_only]
-          if cfg[:read_only]
-            Rails.logger.warn("RRF: `#{f}` write_only conflicts with read_only.")
-          end
-
-          if cfg[:hidden]
-            Rails.logger.warn("RRF: `#{f}` write_only implies hidden.")
-          end
-
-          if cfg[:hidden_from_index]
-            Rails.logger.warn("RRF: `#{f}` write_only implies hidden_from_index.")
-          end
+        unless read_write_only_set
+          cfg[:read_only] = true if f.in?(readonly_attributes) || f.in?(read_only_fields)
+          cfg[:write_only] = true if f.in?(write_only_fields)
         end
+        cfg[:hidden] = true if f.in?(hidden_fields)
 
         # Annotate column data.
         if column = columns[f]
@@ -353,9 +327,9 @@ module RESTFramework::Controller
           if type = attribute.type
             cfg[:type] ||= type.type if type.type
 
-            # Get enum variants.
             if type.is_a?(ActiveRecord::Enum::EnumType)
-              cfg[:enum_variants] = type.send(:mapping)
+              cfg[:enum] = true
+              cfg[:options] ||= type.send(:mapping).invert
 
               # TranslateEnum Integration:
               translate_method = "translated_#{f.pluralize}"
@@ -376,8 +350,15 @@ module RESTFramework::Controller
           else
             ref_columns = ref.klass.columns_hash
           end
-          cfg[:fields] ||= RESTFramework::Utils.association_fields_for(ref)
-          cfg[:fields] = cfg[:fields].map(&:to_s)
+          # The association's `fields` config is itself a spec (Array or `only:`/`include:`/
+          # `exclude:`/`config:` Hash). Resolve its membership to a name array (consumed by the
+          # serializer, filters, and OpenAPI) and stash any nested `config:` for the serializer's
+          # recursion.
+          spec = RESTFramework::Utils.normalize_field_spec(cfg[:fields])
+          cfg[:fields] = RESTFramework::Utils.resolve_field_names(
+            spec, RESTFramework::Utils.association_fields_for(ref)
+          )
+          cfg[:field_config] = spec[:config] if spec[:config]
 
           # Strings, to match `:fields` when intersecting requested fields against the allowlist.
           if cfg[:requestable_fields]
@@ -432,7 +413,8 @@ module RESTFramework::Controller
         # Determine if this is just a method.
         if !cfg[:kind] && self.model.method_defined?(f)
           cfg[:kind] = "method"
-          cfg[:read_only] = true if cfg[:read_only].nil?
+          # Methods are read-only by default, unless the field was marked read/write-only.
+          cfg[:read_only] = true unless read_write_only_set || cfg[:write_only]
         end
 
         # Collect validator options into a hash on their type, while also updating `required` based
@@ -453,6 +435,21 @@ module RESTFramework::Controller
           cfg[:validators][kind] << options
         end
 
+        # Warn on bad combinations, once every property has been resolved.
+        if cfg[:write_only]
+          if cfg[:read_only]
+            Rails.logger.warn("RRF: `#{f}` write_only conflicts with read_only.")
+          end
+
+          if cfg[:hidden]
+            Rails.logger.warn("RRF: `#{f}` write_only implies hidden.")
+          end
+
+          if cfg[:hidden_from_index]
+            Rails.logger.warn("RRF: `#{f}` write_only implies hidden_from_index.")
+          end
+        end
+
         next [ f, cfg ]
       }.to_h.compact.with_indifferent_access
 
@@ -474,17 +471,14 @@ module RESTFramework::Controller
     # 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.
+    # introspectable — a custom `serializer_class` makes its `get_fields` meaningless. Hidden fields
+    # are included (retrievable via `?only=` there); write-only 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
+      return [] if sibling.serializer_class
 
       cfg = sibling.field_configuration
       sibling.get_fields.reject { |sf|
@@ -648,8 +642,10 @@ module RESTFramework::Controller
   end
 
   def readable_fields
-    cfg = self.class.field_configuration
-    self.get_fields.reject { |f| cfg[f]&.[](:write_only) }
+    @_readable_fields ||= begin
+      cfg = self.class.field_configuration
+      self.get_fields.reject { |f| cfg[f]&.[](:write_only) }
+    end
   end
 
   # The fields a client may write (create/update): `get_fields` minus read_only fields. Excluding
@@ -657,23 +653,55 @@ module RESTFramework::Controller
   # 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) }
+    @_writable_fields ||= begin
+      cfg = self.class.field_configuration
+      self.get_fields.reject { |f| cfg[f]&.[](:read_only) }
+    end
   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
+    @_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" }
+    @_readable_columns_or_associations ||= begin
+      cfg = self.class.field_configuration
+      columns = self.class.model.column_names
+      self.readable_fields.select do |f|
+        next true if f.in?(columns)
+
+        # Skip polymorphic associations: they can't be JOINed, so filtering or ordering *through*
+        # them (e.g. `?favorite.name=x`) would raise. Their backing `*_id`/`*_type` columns are
+        # still filterable/orderable via `readable_polymorphic_columns`.
+        field = cfg[f]
+        field&.[](:kind) == "association" && !field[:reflection]&.polymorphic?
+      end
+    end
+  end
+
+  # Map each readable polymorphic `belongs_to`'s dotted `<name>.id`/`<name>.type` path to its
+  # backing `*_id`/`*_type` column. These columns live on the base table, so — unlike the
+  # association itself, which can't be JOINed — they filter and order like any other column. The
+  # dotted path mirrors the serialized shape, so clients filter with `?favorite.type=Genre`.
+  def readable_polymorphic_columns
+    @_readable_polymorphic_columns ||= begin
+      cfg = self.class.field_configuration
+      self.readable_fields.each_with_object({}) do |f, map|
+        field = cfg[f]
+        next unless field&.[](:kind) == "association"
+
+        ref = field[:reflection]
+        next unless ref&.polymorphic?
+
+        map["#{f}.id"] = ref.foreign_key
+        map["#{f}.type"] = ref.foreign_type
+      end
+    end
   end
 
   # Get a hash of strong parameters for the current action.
@@ -711,6 +739,14 @@ module RESTFramework::Controller
         next nil
       end
 
+      # JSON/JSONB columns hold opaque structured data, so permit hash (and nested) values here.
+      # Scalar and array values can't share this slot in strong params, so `get_body_params`
+      # re-injects them after filtering.
+      if config[:type].in?(%i[json jsonb])
+        hash_variations[f] = {}
+        next nil
+      end
+
       if config[:reflection]
         # Add `_id`/`_ids` variations for associations.
         if id_field = config[:id_field]
@@ -742,6 +778,15 @@ module RESTFramework::Controller
     @_get_allowed_parameters
   end
 
+  # Writable JSON/JSONB columns, whose values are opaque and may arrive as any JSON type.
+  def get_json_columns
+    return @_get_json_columns if defined?(@_get_json_columns)
+
+    @_get_json_columns = self.writable_fields.map(&:to_s).select { |f|
+      self.class.field_configuration[f]&.[](:type).in?(%i[json jsonb])
+    }
+  end
+
   # Use strong parameters to filter the request body.
   def get_body_params(bulk_action: nil)
     data = self.request.request_parameters
@@ -808,6 +853,16 @@ module RESTFramework::Controller
       end
     end
 
+    # JSON/JSONB columns accept any JSON value. Strong params permit a hash for such a key (via
+    # `key: {}`; see `get_allowed_parameters`), but can't also accept a scalar or array in that
+    # slot, so remember non-hash values now and re-inject them after filtering.
+    json_scalar_or_array_data = {}
+    if !bulk_action && self.class.model
+      self.get_json_columns.each do |f|
+        json_scalar_or_array_data[f] = data[f] if data.key?(f) && !data[f].is_a?(Hash)
+      end
+    end
+
     # Filter the request body with strong params. If `bulk` is true, then we apply allowed
     # parameters to the `_json` key of the request body.
     body_params = if allowed_params == true
@@ -835,6 +890,11 @@ module RESTFramework::Controller
       body_params[k].unshift(*v)
     end
 
+    # Re-inject scalar/array JSON column values that strong params dropped (see above).
+    json_scalar_or_array_data.each do |k, v|
+      body_params[k] = v
+    end
+
     body_params
   end
   alias_method :get_create_params, :get_body_params
@@ -855,13 +915,14 @@ module RESTFramework::Controller
   # `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.
+  # own controller's recordset, so per-level access scoping is enforced. Returns `nil` when there is
+  # no nested parent, or a `<name>_id` param can't connect. Override `get_recordset` to scope
+  # differently.
   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
+    return nil unless request
 
     # `<name>_id` path parameters that name a model, in route order (outermost parent first).
     parents = request.path_parameters.filter_map { |key, value|
@@ -899,11 +960,9 @@ module RESTFramework::Controller
   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.
+  # controller's access scoping is reused), or the bare model when 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
 

data/lib/rest_framework/filters/base_filter.rb

@@ -7,6 +7,16 @@ class RESTFramework::Filters::BaseFilter
     raise NotImplementedError
   end
 
+  # The controller's polymorphic `<assoc>.id`/`<assoc>.type` → backing-column map, gated by a custom
+  # field allowlist when the subclass defines one (`filter_fields`/`ordering_fields`). This keeps a
+  # restricted allowlist restrictive: a polymorphic path is honored only if it is also listed there.
+  def _polymorphic_columns(custom_fields)
+    map = @controller.readable_polymorphic_columns
+    return map unless custom_fields
+
+    map.slice(*custom_fields.map(&:to_s))
+  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

data/lib/rest_framework/filters/ordering_filter.rb

@@ -12,6 +12,7 @@ class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilte
 
     # Ensure ordering_fields are strings since the split param will be strings.
     fields = self._get_fields
+    poly_columns = self._polymorphic_columns(@controller.class.ordering_fields)
     order_string = @controller.request.query_parameters[param]
 
     # Reject nested-hash inputs like `?ordering[evil]=x` (Rack parses these into
@@ -38,6 +39,13 @@ class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilte
         next
       end
 
+      # A polymorphic association's `<name>.id`/`<name>.type` maps to a backing column on the base
+      # table, so it orders directly with no JOIN (unlike other sub-fields).
+      if real_column = poly_columns[column]
+        ordering[real_column] = direction
+        next
+      end
+
       # 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.

data/lib/rest_framework/filters/query_filter.rb

@@ -1,13 +1,7 @@
 # A simple filtering backend that supports filtering a recordset based on query parameters.
 class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
   # Wrapper to indicate a type of query that must be negated with `where.not(...)`.
-  class Not
-    attr_reader :q
-
-    def initialize(q)
-      @q = q
-    end
-  end
+  Not = Struct.new(:q)
 
   PREDICATES = {
     true: true,
@@ -63,6 +57,7 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
   # query config in the form of: `[base_query, pred_queries, includes]`.
   def _get_query_config
     fields = self._get_fields
+    poly_columns = self._polymorphic_columns(@controller.class.filter_fields)
     includes = []
 
     # Predicate queries must be added to a separate list because multiple predicates can be used.
@@ -81,10 +76,18 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
         next [ field, v ]
       end
 
+      # A polymorphic association's `<name>.id`/`<name>.type` maps to a backing column on the base
+      # table, so it filters directly with no JOIN (unlike other sub-fields).
+      if column = poly_columns[field]
+        next [ column, v ]
+      end
+
       # First, try to parse a simple predicate and check if it is filterable.
       pred_field, predicate = self.parse_predicate(field)
       if predicate && pred_field.in?(fields)
         field = pred_field
+      elsif predicate && (column = poly_columns[pred_field])
+        field = column
       else
         # Last, try to parse a sub-field or sub-field w/predicate.
         root_field, sub_field = field.split(".", 2)

data/lib/rest_framework/routers.rb

@@ -9,8 +9,9 @@ module ActionDispatch::Routing
       mod.const_get("#{name.to_s.camelize}Controller")
     end
 
-    # Route each action from a controller's action store.
-    def _rrf_route_actions(actions)
+    # Route each action from a controller's action store. `helpers: false` routes every action
+    # unnamed (`as: nil`), so the resource contributes no URL/path helpers.
+    def _rrf_route_actions(actions, helpers: true)
       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.
@@ -18,6 +19,7 @@ module ActionDispatch::Routing
         if !spec.builtin && spec.metadata&.[](:delegate)
           kwargs = kwargs.merge(rrf_delegate_scope: spec.type)
         end
+        kwargs = kwargs.merge(as: nil) unless helpers
 
         spec.methods.each do |m|
           public_send(m, spec.path, action: spec.name, **kwargs)
@@ -36,7 +38,9 @@ module ActionDispatch::Routing
     # 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).
+    # resources like Rails' `resources` (the nested controller resolves in the current scope). Pass
+    # `helpers: false` to route the resource without URL/path helpers — handy when a singular and a
+    # plural resource of the same model would otherwise claim the same helper name.
     def rest_resource(name, **kwargs)
       controller = kwargs.delete(:controller) || name
       if controller.is_a?(Class)
@@ -48,6 +52,9 @@ module ActionDispatch::Routing
       # Set controller if it's not explicitly set.
       kwargs[:controller] = name unless kwargs[:controller]
 
+      # `helpers:` is ours, not Rails' — pull it out before forwarding the rest to the router.
+      helpers = kwargs.delete(:helpers) != false
+
       has_model = !!controller_class.model
       singular = controller_class.singular
       actions = controller_class.actions
@@ -61,16 +68,16 @@ module ActionDispatch::Routing
         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)
+            self._rrf_route_actions(actions, helpers: helpers)
+            self._rrf_route_actions(member_actions, helpers: helpers)
           else
             # Plural model controller: route collection/member actions separately.
-            collection { self._rrf_route_actions(actions) }
-            member { self._rrf_route_actions(member_actions) }
+            collection { self._rrf_route_actions(actions, helpers: helpers) }
+            member { self._rrf_route_actions(member_actions, helpers: helpers) }
           end
         else
           # Non-model controller: only actions (there is no member `:id` scope).
-          self._rrf_route_actions(actions)
+          self._rrf_route_actions(actions, helpers: helpers)
         end
 
         yield if block_given?

data/lib/rest_framework/serializers/native_serializer.rb

@@ -44,10 +44,10 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
     return @fields if defined?(@fields)
     return nil unless base_fields = @controller&.get_fields
 
-    only_param = @controller.class.native_serializer_only_query_param
-    except_param = @controller.class.native_serializer_except_query_param
-    include_param = @controller.class.native_serializer_include_query_param
-    exclude_param = @controller.class.native_serializer_exclude_query_param
+    only_param = @controller.class.only_query_param
+    except_param = @controller.class.except_query_param
+    include_param = @controller.class.include_query_param
+    exclude_param = @controller.class.exclude_query_param
 
     only = EXTRACT_FROM_QUERY.call(only_param, @controller)
     except = EXTRACT_FROM_QUERY.call(except_param, @controller)
@@ -98,35 +98,20 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
     self.config
   end
 
-  # Get a native serializer configuration from the controller.
-  def get_controller_native_serializer_config
-    return nil unless @controller
-
-    if @many == true
-      controller_serializer = @controller.class.native_serializer_plural_config
-    elsif @many == false
-      controller_serializer = @controller.class.native_serializer_singular_config
-    end
-
-    controller_serializer || @controller.class.native_serializer_config
-  end
-
   # The record cap for a collection association (`nil` = unlimited). The default is applied even
   # when the feature is off, so responses are always bounded. `key?` (not `||`) reads the
   # `field_config` override so an explicit `nil` there means unlimited/uncapped rather than falling
   # back to the controller default.
   def _effective_association_limit(association_name, field_config)
-    controller = @controller&.class
+    klass = @controller&.class
 
-    default = field_config.key?(:limit) ?
-      field_config[:limit] : controller&.association_limit
-    return default unless controller&.enable_association_queries
+    default = field_config.key?(:limit) ? field_config[:limit] : klass&.association_limit
+    return default unless klass&.enable_association_queries
 
     requested = self._requested_association_limit(association_name)
     return default if requested.nil?
 
-    max = field_config.key?(:limit_max) ?
-      field_config[:limit_max] : controller.association_limit_max
+    max = field_config.key?(:limit_max) ? field_config[:limit_max] : klass.association_limit_max
 
     # `all` means "as many as allowed" — the cap, or unlimited when the cap is `nil`.
     return max if requested == :all
@@ -187,10 +172,10 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
   # Recursively translate an association's fields into a `serializable_hash` config
   # (`only`/`methods`/`include`). Columns go to `only` and plain methods to `methods`; a field that
   # is itself an association is recursed into (as a nested `include`) only when it has its own entry
-  # in `field_config[:field_config]`. Otherwise it falls through to a method and serializes as
-  # before (its full `as_json`), so deeper nesting is opt-in and never narrows the default output.
-  def _build_association_config(model, fields, field_config)
-    nested = field_config[:field_config] || {}
+  # in `nested` (the per-field `config:` map). Otherwise it falls through to a method and serializes
+  # as before (its full `as_json`), so deeper nesting is opt-in and never narrows the output.
+  def _build_association_config(model, fields, nested)
+    nested ||= {}
     only = []
     methods = []
     includes = {}
@@ -202,9 +187,11 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       if sf.in?(model.column_names)
         only << sf
       elsif sub_field_config && (ref = model.reflect_on_association(sf.to_sym)) && !ref.polymorphic?
-        sub_fields = sub_field_config[:fields]&.map(&:to_s) ||
-          RESTFramework::Utils.association_fields_for(ref)
-        includes[sf] = self._build_association_config(ref.klass, sub_fields, sub_field_config)
+        sub_spec = RESTFramework::Utils.normalize_field_spec(sub_field_config[:fields])
+        sub_fields = RESTFramework::Utils.resolve_field_names(
+          sub_spec, RESTFramework::Utils.association_fields_for(ref)
+        )
+        includes[sf] = self._build_association_config(ref.klass, sub_fields, sub_spec[:config])
       elsif model.method_defined?(sf)
         methods << sf
       else
@@ -241,14 +228,29 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       if f.in?(column_names)
         columns << f
       elsif ref = reflections[f]
-        effective_fields = self._effective_association_fields(f, ref, field_config)
-        sub_config = if ref.polymorphic?
-          # No single target class to introspect, so serialize every field as a method.
-          { only: [], methods: effective_fields }
-        else
-          self._build_association_config(ref.klass, effective_fields, field_config)
+        # A polymorphic `belongs_to` has no single target class to introspect, so serialize it via a
+        # method that emits the `type` (from the `*_type` column) and id, a label when the target
+        # has one, and any other configured `fields` the target responds to. Consumer-driven
+        # field/limit requests don't apply (they need one target class; see the serializer method).
+        if ref.polymorphic?
+          foreign_type = ref.foreign_type
+          fields = field_config[:fields]
+          serializer_methods[f] = f
+          includes_map[f] = f.to_sym
+          self.define_singleton_method(f) do |record|
+            next nil unless target = record.send(f)
+
+            RESTFramework::Utils.serialize_polymorphic(target, record.send(foreign_type), fields)
+          end
+
+          next
         end
 
+        effective_fields = self._effective_association_fields(f, ref, field_config)
+        sub_config = self._build_association_config(
+          ref.klass, effective_fields, field_config[:field_config]
+        )
+
         # Apply certain rules regarding collection associations.
         if ref.collection?
           # A finite limit needs a per-record `.limit` query, since eager `includes` can't cap rows
@@ -343,11 +345,6 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       return local_config.deep_dup
     end
 
-    # Return a serializer config if one is defined on the controller.
-    if serializer_config = self.get_controller_native_serializer_config
-      return serializer_config.deep_dup
-    end
-
     # If the config wasn't determined, build a serializer config from controller fields.
     if @model && self.fields
       return self._get_controller_serializer_config

data/lib/rest_framework/utils.rb

@@ -96,34 +96,63 @@ module RESTFramework::Utils
     s
   end
 
-  # Parse fields hashes.
+  # A `fields` spec's structural (non-`config`) keys, i.e. those that shape set membership.
+  FIELD_SPEC_KEYS = [ :only, :except, :include, :exclude, :config ].freeze
+
+  # Normalize a field spec — an Array, a Hash, or nil — into a canonical
+  # `{only:, include:, exclude:, config:}` Hash containing only the keys that are present. A plain
+  # Array is sugar for `only:`. `except:` is an alias of `exclude:`; the two are merged.
+  def self.normalize_field_spec(spec)
+    return {} if spec.nil?
+    return { only: spec } unless spec.is_a?(Hash)
+
+    exclude = (Array(spec[:exclude]) + Array(spec[:except])).presence
+    { only: spec[:only], include: spec[:include], exclude: exclude, config: spec[:config] }.compact
+  end
+
+  # Resolve a field spec (Array | Hash | nil) to an ordered array of string field names: start from
+  # `base` unless `only:` replaces it, then apply `include:`. Any field named in `config:` is
+  # implicitly part of the set (so a configured field never needs to be listed twice). `exclude:` is
+  # applied last, so it can still drop a field that `config:`/`include:` would otherwise add.
+  def self.resolve_field_names(spec, base)
+    spec = self.normalize_field_spec(spec)
+    names = (spec[:only] || base).map(&:to_s)
+    names += spec[:include].map(&:to_s) if spec[:include]
+    names |= spec[:config].keys.map(&:to_s) if spec[:config]
+    names -= spec[:exclude].map(&:to_s) if spec[:exclude]
+    names
+  end
+
+  # Resolve a top-level `fields` hash to an ordered array of string field names, using the model's
+  # default fields as the base. The `config:` key carries per-field configuration and is ignored for
+  # membership.
   def self.parse_fields_hash(h, model, exclude_associations:, action_text:, active_storage:)
-    parsed_fields = h[:only] || (
-      model ? self.fields_for(
-        model,
-        exclude_associations: exclude_associations,
-        action_text: action_text,
-        active_storage: active_storage,
-      ) : []
-    )
-    parsed_fields += h[:include].map(&:to_s) if h[:include]
-    parsed_fields -= h[:exclude].map(&:to_s) if h[:exclude]
-    parsed_fields -= h[:except].map(&:to_s) if h[:except]
+    base = model ? self.fields_for(
+      model,
+      exclude_associations: exclude_associations,
+      action_text: action_text,
+      active_storage: active_storage,
+    ) : []
 
     # Warn for any unknown keys.
-    (h.keys - [ :only, :except, :include, :exclude ]).each do |k|
+    (h.keys.map(&:to_sym) - FIELD_SPEC_KEYS).each do |k|
       Rails.logger.warn("RRF: Unknown key in fields hash: #{k}.")
     end
 
-    # We should always return strings, not symbols.
-    parsed_fields.map(&:to_s)
+    self.resolve_field_names(h, base)
   end
 
   # Get the fields for a given model, including not just columns (which includes foreign keys), but
   # also associations. Note that we always return an array of strings, not symbols.
   def self.fields_for(model, exclude_associations:, action_text:, active_storage:)
-    foreign_keys = model.reflect_on_all_associations(:belongs_to).map(&:foreign_key)
-    base_fields = model.column_names.reject { |c| c.in?(foreign_keys) }
+    belongs_to = model.reflect_on_all_associations(:belongs_to)
+
+    # A polymorphic `belongs_to` is backed by both a foreign key and a `*_type` column; the
+    # association represents both, so drop them from the plain column fields (as we already do for
+    # every foreign key).
+    excluded_columns = belongs_to.map(&:foreign_key)
+    excluded_columns += belongs_to.select(&:polymorphic?).map(&:foreign_type)
+    base_fields = model.column_names.reject { |c| c.in?(excluded_columns) }
 
     return base_fields if exclude_associations
 
@@ -173,7 +202,36 @@ module RESTFramework::Utils
       return fields
     end
 
-    [ "id", "name" ]
+    # A polymorphic association has no single target class, so we can't resolve a label column ahead
+    # of time. The id and type together identify the record; a per-record label is added at
+    # serialization time when the target has one (see `serialize_polymorphic`).
+    [ "id", "type" ]
+  end
+
+  # Serialize a polymorphic association's target as `{<pk> => id, "type" => type}`, plus a label
+  # entry when the target responds to one of the configured `label_fields`. The type comes from the
+  # parent's `*_type` column, so it matches exactly what is stored (and what a reverse lookup uses).
+  #
+  # `fields` are the association's configured fields. `id`/`type` are always emitted above; any
+  # other field is resolved against the target and included when it responds to it, so a field
+  # absent on a target class (e.g. `price` on a `Genre`) is omitted rather than serialized as nil.
+  def self.serialize_polymorphic(target, type, fields = nil)
+    result = {}
+    Array(target.class.primary_key).each { |pk| result[pk] = target.public_send(pk) }
+    result["type"] = type
+
+    if label = RESTFramework.config.label_fields.find { |f| target.respond_to?(f) }
+      result[label.to_s] = target.public_send(label)
+    end
+
+    Array(fields).each do |f|
+      f = f.to_s
+      next if f.in?(%w[id type]) || result.key?(f)
+
+      result[f] = target.public_send(f) if target.respond_to?(f)
+    end
+
+    result
   end
 
   # Get a field's id/ids variation.

data/lib/rest_framework/version.rb

@@ -1,41 +1,3 @@
 module RESTFramework
-  # Do not use Rails-specific helper methods here (e.g., `blank?`) so the module can run standalone.
-  module Version
-    VERSION_FILEPATH = File.expand_path("../../VERSION", __dir__)
-    UNKNOWN = "0-unknown"
-
-    def self.get_version(skip_git: false)
-      # First, attempt to get the version from git.
-      unless skip_git
-        version = `git describe --dirty 2>/dev/null`&.strip
-        return version unless !version || version.empty?
-      end
-
-      # Git failed or was skipped, so try to find a VERSION file.
-      begin
-        version = File.read(VERSION_FILEPATH)&.strip
-        return version unless !version || version.empty?
-      rescue SystemCallError
-      end
-
-      # No VERSION file, so version is unknown.
-      UNKNOWN
-    end
-
-    def self.stamp_version(version = nil)
-      # Stamp the given version into the VERSION file, deriving it from git when none is provided.
-      # Returns the stamped version so callers don't rely on the (require-time) `VERSION` constant.
-      version ||= self.get_version
-      if version != UNKNOWN
-        File.write(VERSION_FILEPATH, version)
-      end
-      version
-    end
-
-    def self.unstamp_version
-      File.delete(VERSION_FILEPATH) if File.exist?(VERSION_FILEPATH)
-    end
-  end
-
-  VERSION = Version.get_version(skip_git: true)
+  VERSION = "2.0.0.rc2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta6
+  version: 2.0.0.rc2
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -34,7 +34,6 @@ files:
 - ".yardopts"
 - LICENSE
 - README.md
-- VERSION
 - app/views/layouts/rest_framework.html.erb
 - app/views/rest_framework/_breadcrumbs.html.erb
 - app/views/rest_framework/_head.html.erb

data/VERSION

@@ -1 +0,0 @@
-2.0.0.beta6