rest_framework 1.0.0.beta2 → 1.0.0

data/lib/rest_framework/serializers/native_serializer.rb

@@ -7,7 +7,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
   class_attribute :action_config
 
   # Accept/ignore `*args` to be compatible with the `ActiveModel::Serializer#initialize` signature.
-  def initialize(object=nil, *args, many: nil, model: nil, **kwargs)
+  def initialize(object = nil, *args, many: nil, model: nil, **kwargs)
     super(object, *args, **kwargs)
 
     if many.nil?
@@ -28,7 +28,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
 
   # Get controller action, if possible.
   def get_action
-    return @controller&.action_name&.to_sym
+    @controller&.action_name&.to_sym
   end
 
   # Get a locally defined native serializer configuration, if one is defined.
@@ -47,7 +47,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
     return self.singular_config if @many == false && self.singular_config
 
     # Lastly, try returning the default config, or singular/plural config in that order.
-    return self.config || self.singular_config || self.plural_config
+    self.config || self.singular_config || self.plural_config
   end
 
   # Get a native serializer configuration from the controller.
@@ -60,7 +60,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       controller_serializer = @controller.class.native_serializer_singular_config
     end
 
-    return controller_serializer || @controller.class.native_serializer_config
+    controller_serializer || @controller.class.native_serializer_config
   end
 
   # Filter a single subconfig for specific keys. By default, keys from `fields` are removed from the
@@ -99,7 +99,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       subcfg = subcfg.to_sym
 
       if add
-        subcfg = subcfg.in?(fields) ? fields : [subcfg, *fields]
+        subcfg = subcfg.in?(fields) ? fields : [ subcfg, *fields ]
       elsif only
         subcfg = subcfg.in?(fields) ? subcfg : []
       else
@@ -107,7 +107,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       end
     end
 
-    return subcfg
+    subcfg
   end
 
   # Filter out configuration properties based on the :except/:only query parameters.
@@ -153,7 +153,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       end
     end
 
-    return cfg
+    cfg
   end
 
   # Get the associations limit from the controller.
@@ -174,7 +174,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       end
     end
 
-    return @_get_associations_limit = limit
+    @_get_associations_limit = limit
   end
 
   # Get a serializer configuration from the controller. `@controller` and `@model` must be set.
@@ -210,7 +210,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
             sub_methods << sf
           end
         end
-        sub_config = {only: sub_columns, methods: sub_methods}
+        sub_config = { only: sub_columns, methods: sub_methods }
 
         # Apply certain rules regarding collection associations.
         if ref.collection?
@@ -257,7 +257,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
         # ActiveStorage Integration: Define attachment serializer method.
         if ref.macro == :has_one_attached
           serializer_methods[f] = f
-          includes_map[f] = {"#{f}_attachment": :blob}
+          includes_map[f] = { "#{f}_attachment": :blob }
           self.define_singleton_method(f) do |record|
             attached = record.send(f)
             next attached.attachment ? {
@@ -268,7 +268,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
           end
         elsif ref.macro == :has_many_attached
           serializer_methods[f] = f
-          includes_map[f] = {"#{f}_attachments": :blob}
+          includes_map[f] = { "#{f}_attachments": :blob }
           self.define_singleton_method(f) do |record|
             # Iterating the collection yields attachment objects.
             next record.send(f).map { |a|
@@ -288,7 +288,7 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       end
     end
 
-    return {
+    {
       only: columns,
       include: includes,
       methods: methods,
@@ -317,24 +317,24 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
     end
 
     # By default, pass an empty configuration, using the default Rails serializer.
-    return {}
+    {}
   end
 
   # Get a configuration passable to `serializable_hash` for the object, filtered if required.
   def get_serializer_config
-    return self.filter_from_request(self.get_raw_serializer_config)
+    self.filter_from_request(self.get_raw_serializer_config)
   end
 
   # Serialize a single record and merge results of `serializer_methods`.
   def _serialize(record, config, serializer_methods)
     # Ensure serializer_methods is either falsy, or a hash.
     if serializer_methods && !serializer_methods.is_a?(Hash)
-      serializer_methods = [serializer_methods].flatten.map { |m| [m, m] }.to_h
+      serializer_methods = [ serializer_methods ].flatten.map { |m| [ m, m ] }.to_h
     end
 
     # Merge serialized record with any serializer method results.
-    return record.serializable_hash(config).merge(
-      serializer_methods&.map { |m, k| [k.to_sym, self.send(m, record)] }.to_h,
+    record.serializable_hash(config).merge(
+      serializer_methods&.map { |m, k| [ k.to_sym, self.send(m, record) ] }.to_h,
     )
   end
 
@@ -352,29 +352,29 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
       return @object.map { |r| self._serialize(r, config, serializer_methods) }
     end
 
-    return self._serialize(@object, config, serializer_methods)
+    self._serialize(@object, config, serializer_methods)
   end
 
   # Allow a serializer instance to be used as a hash directly in a nested serializer config.
   def [](key)
     @_nested_config ||= self.get_serializer_config
-    return @_nested_config[key]
+    @_nested_config[key]
   end
 
   def []=(key, value)
     @_nested_config ||= self.get_serializer_config
-    return @_nested_config[key] = value
+    @_nested_config[key] = value
   end
 
   # Allow a serializer class to be used as a hash directly in a nested serializer config.
   def self.[](key)
     @_nested_config ||= self.new.get_serializer_config
-    return @_nested_config[key]
+    @_nested_config[key]
   end
 
   def self.[]=(key, value)
     @_nested_config ||= self.new.get_serializer_config
-    return @_nested_config[key] = value
+    @_nested_config[key] = value
   end
 end
 

data/lib/rest_framework/utils.rb

@@ -1,49 +1,32 @@
 module RESTFramework::Utils
-  HTTP_VERB_ORDERING = %w(GET POST PUT PATCH DELETE OPTIONS HEAD)
+  HTTP_VERB_ORDERING = %w[GET POST PUT PATCH DELETE OPTIONS HEAD]
 
-  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, kwargs:}`.
-  #
-  # If a controller is provided, labels will be added to any metadata fields.
-  def self.parse_extra_actions(extra_actions, controller: nil)
-    return (extra_actions || {}).map { |k, v|
+  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, metadata:, kwargs:}`.
+  def self.parse_extra_actions(extra_actions)
+    (extra_actions || {}).map { |k, v|
       path = k
+      kwargs = {}
 
       # Convert structure to path/methods/kwargs.
-      if v.is_a?(Hash)  # Allow kwargs to be used to define path differently from the key.
+      if v.is_a?(Hash)
         # Symbolize keys (which also makes a copy so we don't mutate the original).
         v = v.symbolize_keys
-        methods = v.delete(:methods)
-        if v.key?(:method)
-          methods = v.delete(:method)
-        end
 
-        # Add label to metadata fields, if any exist.
-        metadata = v[:metadata]
-        if controller && metadata&.key?(:fields)
-          metadata[:fields] = metadata[:fields].map { |f|
-            [f, {}]
-          }.to_h if metadata[:fields].is_a?(Array)
-          metadata[:fields]&.each do |field, cfg|
-            cfg[:label] = controller.label_for(field) unless cfg[:label]
-          end
-        end
+        # Cast method/methods to an array.
+        methods = [ v.delete(:methods), v.delete(:method) ].flatten.compact
 
         # Override path if it's provided.
         if v.key?(:path)
           path = v.delete(:path)
         end
 
+        # Extract metadata, if provided.
+        metadata = v.delete(:metadata).presence
+
         # Pass any further kwargs to the underlying Rails interface.
-        kwargs = v.presence
-      elsif v.is_a?(Array) && v.length == 1
-        methods = v[0]
+        kwargs = v
       else
-        methods = v
-      end
-
-      # Insert action label if it's not provided.
-      if controller
-        metadata[:label] ||= controller.label_for(k)
+        methods = [ v ].flatten
       end
 
       next [
@@ -51,6 +34,7 @@ module RESTFramework::Utils
         {
           path: path,
           methods: methods,
+          metadata: metadata,
           kwargs: kwargs,
         }.compact,
       ]
@@ -59,7 +43,7 @@ module RESTFramework::Utils
 
   # Get actions which should be skipped for a given controller.
   def self.get_skipped_builtin_actions(controller_class)
-    return (
+    (
       RESTFramework::BUILTIN_ACTIONS.keys + RESTFramework::BUILTIN_MEMBER_ACTIONS.keys
     ).reject do |action|
       controller_class.method_defined?(action)
@@ -74,7 +58,7 @@ module RESTFramework::Utils
   # Normalize a path pattern by replacing URL params with generic placeholder, and removing the
   # `(.:format)` at the end.
   def self.comparable_path(path)
-    return path.gsub("(.:format)", "").gsub(/:[0-9A-Za-z_-]+/, ":x")
+    path.gsub("(.:format)", "").gsub(/:[0-9A-Za-z_-]+/, ":x")
   end
 
   # Show routes under a controller action; used for the browsable API.
@@ -90,7 +74,7 @@ module RESTFramework::Utils
 
     # Return routes that match our current route subdomain/pattern, grouped by controller. We
     # precompute certain properties of the route for performance.
-    return application_routes.routes.select { |r|
+    application_routes.routes.select { |r|
       # We `select` first to avoid unnecessarily calculating metadata for routes we don't even want
       # to show.
       (r.defaults[:subdomain].blank? || r.defaults[:subdomain] == request.subdomain) &&
@@ -116,7 +100,7 @@ module RESTFramework::Utils
         verb: r.verb,
         path: path,
         path_with_params: r.format(
-          r.required_parts.each_with_index.map { |p, i| [p, path_params[i]] }.to_h,
+          r.required_parts.each_with_index.map { |p, i| [ p, path_params[i] ] }.to_h,
         ),
         relative_path: relative_path,
         concat_path: concat_path,
@@ -139,17 +123,19 @@ module RESTFramework::Utils
       ]
     }.group_by { |r| r[:controller] }.sort_by { |c, _r|
       # Sort the controller groups by current controller first, then alphanumerically.
-      [request.params[:controller] == c ? 0 : 1, c]
+      # Note: Use `controller_path` instead of `params[:controller]` to avoid re-raising a
+      # `ActionDispatch::Http::Parameters::ParseError` exception.
+      [ request.controller_class.controller_path == c ? 0 : 1, c ]
     }.to_h
   end
 
   # Custom inflector for RESTful controllers.
-  def self.inflect(s, acronyms=nil)
+  def self.inflect(s, acronyms = nil)
     acronyms&.each do |acronym|
       s = s.gsub(/\b#{acronym}\b/i, acronym)
     end
 
-    return s
+    s
   end
 
   # Parse fields hashes.
@@ -167,12 +153,12 @@ module RESTFramework::Utils
     parsed_fields -= h[:except].map(&:to_s) if h[:except]
 
     # Warn for any unknown keys.
-    (h.keys - [:only, :except, :include, :exclude]).each do |k|
+    (h.keys - [ :only, :except, :include, :exclude ]).each do |k|
       Rails.logger.warn("RRF: Unknown key in fields hash: #{k}")
     end
 
     # We should always return strings, not symbols.
-    return parsed_fields.map(&:to_s)
+    parsed_fields.map(&:to_s)
   end
 
   # Get the fields for a given model, including not just columns (which includes
@@ -195,7 +181,7 @@ module RESTFramework::Utils
     # Associations:
     associations = model.reflections.map { |association, ref|
       # Ignore associations for which we have custom integrations.
-      if ref.class_name.in?(%w(ActionText::RichText ActiveStorage::Attachment ActiveStorage::Blob))
+      if ref.class_name.in?(%w[ActionText::RichText ActiveStorage::Attachment ActiveStorage::Blob])
         next nil
       end
 
@@ -208,29 +194,29 @@ module RESTFramework::Utils
       next association
     }.compact
 
-    return base_fields + associations + atf + asf
+    base_fields + associations + atf + asf
   end
 
   # Get the sub-fields that may be serialized and filtered/ordered for a reflection.
   def self.sub_fields_for(ref)
     if !ref.polymorphic? && model = ref.klass
-      sub_fields = [model.primary_key].flatten.compact
+      sub_fields = [ model.primary_key ].flatten.compact
       label_fields = RESTFramework.config.label_fields
 
       # Preferrably find a database column to use as label.
       if match = label_fields.find { |f| f.in?(model.column_names) }
-        return sub_fields + [match]
+        return sub_fields + [ match ]
       end
 
       # Otherwise, find a method.
       if match = label_fields.find { |f| model.method_defined?(f) }
-        return sub_fields + [match]
+        return sub_fields + [ match ]
       end
 
       return sub_fields
     end
 
-    return ["id", "name"]
+    [ "id", "name" ]
   end
 
   # Get a field's id/ids variation.
@@ -243,7 +229,7 @@ module RESTFramework::Utils
       return reflection.foreign_key
     end
 
-    return nil
+    nil
   end
 
   # Wrap a serializer with an adapter if it is an ActiveModel::Serializer.
@@ -252,6 +238,6 @@ module RESTFramework::Utils
       return RESTFramework::ActiveModelSerializerAdapterFactory.for(s)
     end
 
-    return s
+    s
   end
 end

data/lib/rest_framework/version.rb

@@ -19,7 +19,7 @@ module RESTFramework
       end
 
       # No VERSION file, so version is unknown.
-      return UNKNOWN
+      UNKNOWN
     end
 
     def self.stamp_version

data/lib/rest_framework.rb

@@ -9,17 +9,21 @@ module RESTFramework
   BUILTIN_MEMBER_ACTIONS = {
     show: :get,
     edit: :get,
-    update: [:put, :patch].freeze,
+    update: [ :put, :patch ].freeze,
     destroy: :delete,
   }.freeze
   RRF_BUILTIN_ACTIONS = {
     options: :options,
   }.freeze
   RRF_BUILTIN_BULK_ACTIONS = {
-    update_all: [:put, :patch].freeze,
+    update_all: [ :put, :patch ].freeze,
     destroy_all: :delete,
   }.freeze
 
+  # Storage for extra routes and associated metadata.
+  EXTRA_ACTION_ROUTES = Set.new
+  ROUTE_METADATA = {}
+
   # We put most vendored external assets into these files to make precompilation and serving faster.
   EXTERNAL_CSS_NAME = "rest_framework/external.min.css"
   EXTERNAL_JS_NAME = "rest_framework/external.min.js"
@@ -61,12 +65,12 @@ module RESTFramework
     "highlight-a11y-dark.min.css" => {
       url: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-dark.min.css",
       sri: "sha512-Vj6gPCk8EZlqnoveEyuGyYaWZ1+jyjMPg8g4shwyyNlRQl6d3L9At02ZHQr5K6s5duZl/+YKMnM3/8pDhoUphg==",
-      extra_tag_attrs: {class: "rrf-dark-mode"},
+      extra_tag_attrs: { class: "rrf-dark-mode" },
     },
     "highlight-a11y-light.min.css" => {
       url: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/a11y-light.min.css",
       sri: "sha512-WDk6RzwygsN9KecRHAfm9HTN87LQjqdygDmkHSJxVkVI7ErCZ8ZWxP6T8RvBujY1n2/E4Ac+bn2ChXnp5rnnHA==",
-      extra_tag_attrs: {class: "rrf-light-mode"},
+      extra_tag_attrs: { class: "rrf-light-mode" },
     },
 
     # NeatJSON
@@ -113,7 +117,7 @@ module RESTFramework
       raise "Unknown asset extension: #{ext}."
     end
 
-    [name, cfg]
+    [ name, cfg ]
   }.to_h.freeze
   # rubocop:enable Layout/LineLength
 
@@ -122,8 +126,8 @@ module RESTFramework
   # Global configuration should be kept minimal, as controller-level configurations allows multiple
   # APIs to be defined to behave differently.
   class Config
-    DEFAULT_LABEL_FIELDS = %w(name label login title email username url).freeze
-    DEFAULT_SEARCH_COLUMNS = DEFAULT_LABEL_FIELDS + %w(description note).freeze
+    DEFAULT_LABEL_FIELDS = %w[name label login title email username url].freeze
+    DEFAULT_SEARCH_COLUMNS = DEFAULT_LABEL_FIELDS + %w[description note].freeze
     DEFAULT_EXCLUDE_BODY_FIELDS = %w[
       created_at
       created_by
@@ -136,15 +140,18 @@ module RESTFramework
       authenticity_token
     ].freeze
 
-    # Do not run `rrf_finalize` on controllers automatically using a `TracePoint` hook. This is a
-    # performance option and must be global because we have to determine this before any
-    # controller-specific configuration is set. If this is set to `true`, then you must manually
-    # call `rrf_finalize` after any configuration on each controller that needs to participate
-    # in:
+    # Permits use of `render(api: obj)` syntax over `render_api(obj)`; `true` by default.
+    attr_accessor :register_api_renderer
+
+    # Run `rrf_finalize` on controllers automatically using a `TracePoint` hook. This is `true` by
+    # default, and can be disabled for performance, and must be global because we have to determine
+    # this before any controller-specific configuration is set. If this is set to `false`, then you
+    # must manually call `rrf_finalize` after any configuration on each controller that needs to
+    # participate in:
     #  - Model delegation, for the helper methods to be defined dynamically.
     #  - Websockets, for `::Channel` class to be defined dynamically.
     #  - Controller configuration freezing.
-    attr_accessor :disable_auto_finalize
+    attr_accessor :auto_finalize
 
     # Freeze configuration attributes during finalization to prevent accidental mutation.
     attr_accessor :freeze_config
@@ -173,7 +180,11 @@ module RESTFramework
     attr_accessor :use_vendored_assets
 
     def initialize
+      self.register_api_renderer = true
+      self.auto_finalize = true
+
       self.show_backtrace = Rails.env.development?
+
       self.label_fields = DEFAULT_LABEL_FIELDS
       self.search_columns = DEFAULT_SEARCH_COLUMNS
       self.exclude_body_fields = DEFAULT_EXCLUDE_BODY_FIELDS
@@ -181,7 +192,7 @@ module RESTFramework
   end
 
   def self.config
-    return @config ||= Config.new
+    @config ||= Config.new
   end
 
   def self.configure
@@ -189,7 +200,7 @@ module RESTFramework
   end
 
   def self.features
-    return @features ||= {}
+    @features ||= {}
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-26 00:00:00.000000000 Z
+date: 2025-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -96,12 +96,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.7.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.10
 signing_key: