rest_framework 2.0.0.beta6 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7be6812ae478ca58b5f352bf561a57384d309e2a91037d25cf1ad3dbe64ff09
-  data.tar.gz: a2295b59abd1f6e15fa0736b3e5255f00492a0cdc794583b87b85634533cb003
+  metadata.gz: 827c588ec16bebf728f1bc186d0b716488be2a13d7d653fec82ff3c1bd3d7a75
+  data.tar.gz: f1447d4d393e9ab18fc82a2edeb1b366d7236ad46a00aa5e1adedb294262f3a9
 SHA512:
-  metadata.gz: 6a92158c48314c5fb62470cde91d5b21d264e60b8d3d367315b20014965cceaee9bef5ff019c32cc3ef75fb9a45a410cc63373d2dc9c00fa295f6626ec279a6b
-  data.tar.gz: a332502f06c34126962890d6e4b395d5788c8dd1c07d5bd0cfbbcb33d49ec209efad4986d99f1f69ec0f86569b175bb902a11aee76cb21f4942546e256e0239b
+  metadata.gz: 818d459d7b6897e777edb7d403e23087c19d2a18c8002cb8fc343381c514b7aa49da625f460d0fd06a181d76fe55308ec2642f493f4627aef82d98d341775014
+  data.tar.gz: 50226b18ddd51c61a88952c2637c3ea0c622ef59385ddcaff8b231dc0b2aabcacbe6fb5dd9a7db5d4d49bc67600c1d543781e9065cb37faa2344998186df3018

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

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

@@ -196,15 +196,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

@@ -301,34 +301,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]
@@ -432,7 +421,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 +443,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
 
@@ -648,8 +653,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 +664,35 @@ 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` or `?ordering=favorite.name`) would raise. This method is the
+        # safe field surface for those query features.
+        field = cfg[f]
+        field&.[](:kind) == "association" && !field[:reflection]&.polymorphic?
+      end
+    end
   end
 
   # Get a hash of strong parameters for the current action.
@@ -711,6 +730,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 +769,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 +844,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 +881,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

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,

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

@@ -241,14 +241,26 @@ 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 always emits the `type` (from the `*_type` column) alongside the id, plus a
+        # label when the target has one. Filtering/ordering skip polymorphic associations (see
+        # `readable_columns_or_associations`), so consumer-driven field/limit requests don't apply.
+        if ref.polymorphic?
+          foreign_type = ref.foreign_type
+          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))
+          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)
+
         # 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

data/lib/rest_framework/utils.rb

@@ -122,8 +122,14 @@ module RESTFramework::Utils
   # 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 +179,25 @@ 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).
+  def self.serialize_polymorphic(target, type)
+    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] = target.public_send(label)
+    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.rc1"
 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.rc1
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-12 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