rest_framework 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb2a69a51a24192200122bf40a9218e15e1f0d696bfdd63bb8f3aed9f43f82c
-  data.tar.gz: 3b630e5e5f8ec28096e245bc8ced22d5a63423d52799983543c1616b636999d8
+  metadata.gz: 8119cab13c69b27ebfa36906e6bcd577688f2ba63b136e0833f4cfdeae3ca5c3
+  data.tar.gz: 149343b13dfdf94b5804beb502d2296d95f487774d1cb3a1dd30dd63f4ab2afc
 SHA512:
-  metadata.gz: d0eae7105c8fe37a710ac56c9ba0c4df9b0f0663883d117123af6e778735c63117ca58d82e60e260e353aefcc9536e996848341a6537ca963d764b498dfba979
-  data.tar.gz: 72e217a7d2c9bed976d6801f333be3a97ebdedf1998b07fa4a4594c48256919dcd1cd4b48030582fc75bdd9e2e6d002dc29df931e217ab78cd97b87872f65c78
+  metadata.gz: 17d7143b9ac7a9a3f01fab29a369a083750d26f5923bea7d6b9b9dad407efe25bc30321de0024e1d1f3883aa86838bb250b2ee8c4c749e159386b42d5038f5c8
+  data.tar.gz: b1794ca103409bc69f235d72603bd8c9ecd91f674cf4e41c8072ec4c35b4e0d5ca26058f6903554df404183ee7c9624dac9b8f33b67fe212874e98bc4a600355

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

data/app/views/rest_framework/routes_and_forms/_html_form.html.erb

@@ -18,7 +18,7 @@
     scope: "",
     local: true,
   }.compact) do |form| %>
-    <% controller.get_fields.map(&:to_s).each do |f| %>
+    <% controller.get_fields.each do |f| %>
       <%
         # Don't provide form fields for associations or read-only fields.
         cfg = controller.class.field_configuration[f]

data/lib/rest_framework/controller/bulk.rb

@@ -1,7 +1,16 @@
 module RESTFramework::Controller
-  # Serialize the records, but also include any errors that might exist. This is used for bulk
-  # actions, however we include it here so the helper is available everywhere.
-  def bulk_serialize(records)
+  RRF_DEFAULT_BULK_MAX_SIZE = 1000
+  RRF_DEFAULT_BULK_MAX_RAW_SIZE = 10000
+
+  def _bulk_max_size
+    @_bulk_max_size ||= self.class.bulk_max_size || RRF_DEFAULT_BULK_MAX_SIZE
+  end
+
+  def _bulk_max_raw_size
+    @_bulk_max_raw_size ||= self.class.bulk_max_raw_size || RRF_DEFAULT_BULK_MAX_RAW_SIZE
+  end
+
+  def _bulk_serialize(records)
     # This is kinda slow, so perhaps we should eventually integrate `errors` serialization into
     # the serializer directly. This would fail for active model serializers, but maybe we don't
     # care?
@@ -11,52 +20,253 @@ module RESTFramework::Controller
     end
   end
 
-  # Perform the `create` call, and return the collection of (possibly) created records.
-  def create_all!
-    create_data = self.get_create_params(bulk_mode: true)[:_json]
+  def _bulk_mode
+    return @_bulk_mode if defined?(@_bulk_mode)
 
-    # Perform bulk create in a transaction.
-    ActiveRecord::Base.transaction { self.create_from.create(create_data) }
+    # If mode override is allowed, check the query param.
+    if self.class.bulk_allow_mode_override && (qp = self.class.bulk_mode_query_param)
+      if (requested = request.query_parameters[qp].presence)
+        requested = requested.to_sym
+        unless requested.in?([ :default, :raw ])
+          raise RESTFramework::InvalidBulkParametersError.new(
+            "Invalid bulk mode: #{requested}. Must be `default` or `raw`.",
+          )
+        end
+        return @_bulk_mode = requested
+      end
+    end
+
+    # Normalize: `true` and `:default` both mean per-record processing.
+    @_bulk_mode = self.class.bulk == :raw ? :raw : :default
   end
 
-  def update_all
-    records = self.update_all!
-    serialized_records = self.bulk_serialize(records)
-    render(api: serialized_records)
+  # Resolve whether partial fulfillment is enabled for this request.
+  def _bulk_partial
+    return @_bulk_partial if defined?(@_bulk_partial)
+
+    # Check the query param first if configured.
+    if (qp = self.class.bulk_partial_query_param)
+      if (requested = request.query_parameters[qp].presence)
+        return @_bulk_partial = ActiveModel::Type::Boolean.new.cast(requested)
+      end
+    end
+
+    @_bulk_partial = self.class.bulk_partial
+  end
+
+  # Validate and extract bulk object data from request parameters.
+  def _bulk_object_data(bulk_action, bulk_mode)
+    data = self.get_body_params(bulk_action: bulk_action)[:_json]
+
+    unless data&.is_a?(Array) && data.all? { |r| r.is_a?(ActionController::Parameters) }
+      raise RESTFramework::InvalidBulkParametersError.new("Expected an array of objects.")
+    end
+
+    # Enforce size limits.
+    max = bulk_mode == :raw ? self._bulk_max_raw_size : self._bulk_max_size
+    if max && data.length > max
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Too many records (#{data.length}) for #{bulk_mode} mode; maximum is #{max}.",
+      )
+    end
+
+    data
   end
 
-  # Perform the `update` call and return the collection of (possibly) updated records.
-  def update_all!
+  # Validate and extract bulk primary key data from request parameters.
+  def _bulk_pk_data
+    data = self.get_destroy_params(bulk_action: :destroy)[:_json]
+
+    unless data&.is_a?(Array) && data.all? { |r| r.is_a?(String) || r.is_a?(Numeric) }
+      raise RESTFramework::InvalidBulkParametersError.new("Expected an array of primary keys.")
+    end
+
+    # Enforce size limits.
+    max = self._bulk_mode == :raw ? self._bulk_max_raw_size : self._bulk_max_size
+    if max && data.length > max
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Too many records (#{data.length}) for #{self._bulk_mode} mode; maximum is #{max}.",
+      )
+    end
+
+    data
+  end
+
+  def create_all
+    if self._bulk_mode == :raw
+      result = self.create_all_raw!
+      return render(api: { message: "Bulk create successful.", result: result })
+    end
+
+    records = self.create_all_default!
+    render(
+      api: { message: "Bulk create successful.", records: self._bulk_serialize(records) },
+      status: :created,
+    )
+  end
+
+  def create_all_raw!
     pk = self.class.model.primary_key
-    data = if params[:_json].is_a?(Array)
-      self.get_create_params(bulk_mode: :update)[:_json].index_by { |r| r[pk] }
+    data = self._bulk_object_data(:create, :raw)
+
+    unless first_keys = data.first&.keys&.sort
+      raise RESTFramework::InvalidBulkParametersError.new("Expected objects with attrs.")
+    end
+    unless data.all? { |r| r.keys.sort == first_keys }
+      raise RESTFramework::InvalidBulkParametersError.new("All objects must have the same attrs.")
+    end
+
+    self.create_from.insert_all(data, unique_by: pk)
+  end
+
+  def create_all_default!
+    data = self._bulk_object_data(:create, :default)
+    collection = self.create_from
+
+    if self._bulk_partial
+      # Partial: save each record individually, return all (some may have errors).
+      data.map { |attrs| collection.create(attrs) }
     else
-      create_params = self.get_create_params
-      { create_params[pk] => create_params }
+      # Transactional: validate all first, then save in a transaction or raise.
+      records = data.map { |attrs| collection.new(attrs) }
+      failed = records.reject(&:valid?)
+
+      if failed.any?
+        raise RESTFramework::BulkRecordErrorsError.new(records)
+      end
+
+      self.class.model.transaction do
+        records.each(&:save!)
+      end
+
+      records
+    end
+  end
+
+  def update_all
+    if self._bulk_mode == :raw
+      result = self.update_all_raw!
+      return render(api: { message: "Bulk update successful.", result: result })
+    end
+
+    records = self.update_all_default!
+    render(api: { message: "Bulk update successful.", records: self._bulk_serialize(records) })
+  end
+
+  def update_all_raw!
+    pk = self.class.model.primary_key
+    data = self._bulk_object_data(:update, :raw)
+
+    data_ids = data.map { |r| r[pk] }.uniq
+    if data_ids.include?(nil)
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Bulk update requires the primary key (#{pk}) for all records.",
+      )
+    end
+    found_ids = self.get_recordset.where(pk => data_ids).pluck(pk)
+    if found_ids.length != data_ids.length
+      missing = data_ids - found_ids
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Records not found with #{pk}: #{missing.join(', ')}.",
+      )
+    end
+
+    unless first_keys = data.first&.keys&.sort
+      raise RESTFramework::InvalidBulkParametersError.new("Expected objects with attrs.")
+    end
+    unless data.all? { |r| r.keys.sort == first_keys }
+      raise RESTFramework::InvalidBulkParametersError.new("All objects must have the same attrs.")
     end
 
-    # Perform bulk update in a transaction.
-    ActiveRecord::Base.transaction { self.get_recordset.update(data.keys, data.values) }
+    self.get_recordset.upsert_all(data, unique_by: pk)
+  end
+
+  def update_all_default!
+    pk = self.class.model.primary_key
+    data = self._bulk_object_data(:update, :default)
+
+    data_ids = data.map { |r| r[pk] }.uniq
+    if data_ids.include?(nil)
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Bulk update requires the primary key (#{pk}) for all records.",
+      )
+    end
+    existing = self.get_recordset.where(pk => data_ids).index_by { |r| r.send(pk) }
+    if existing.length != data_ids.length
+      missing = data_ids - existing.keys
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Records not found with #{pk}: #{missing.join(', ')}.",
+      )
+    end
+
+    # Assign attributes to each record.
+    records = data.map { |attrs|
+      record = existing[attrs[pk]]
+      record.assign_attributes(attrs.except(pk))
+      record
+    }
+
+    if self._bulk_partial
+      # Partial: save each record individually.
+      records.each(&:save)
+      records
+    else
+      # Transactional: validate all first, then save in a transaction or raise.
+      failed = records.reject(&:valid?)
+
+      if failed.any?
+        raise RESTFramework::BulkRecordErrorsError.new(records)
+      end
+
+      self.class.model.transaction do
+        records.each(&:save!)
+      end
+
+      records
+    end
   end
 
   def destroy_all
-    if params[:_json].is_a?(Array)
-      records = self.destroy_all!
-      serialized_records = self.bulk_serialize(records)
-      return render(api: serialized_records)
+    if self._bulk_mode == :raw
+      deleted = self.destroy_all_raw!
+      return render(api: { message: "Bulk destroy successful.", result: deleted })
     end
 
-    render(
-      api: { message: "Bulk destroy requires an array of primary keys as input." }, status: 400,
-    )
+    records = self.destroy_all_default!
+    render(api: { message: "Bulk destroy successful.", records: self._bulk_serialize(records) })
   end
 
-  # Perform the `destroy!` call and return the destroyed (and frozen) record.
-  def destroy_all!
+  def destroy_all_raw!
+    data = self._bulk_pk_data
     pk = self.class.model.primary_key
-    destroy_data = self.request.request_parameters[:_json]
+    self.get_recordset.where(pk => data).delete_all
+  end
 
-    # Perform bulk destroy in a transaction.
-    ActiveRecord::Base.transaction { self.get_recordset.where(pk => destroy_data).destroy_all }
+  def destroy_all_default!
+    data = self._bulk_pk_data
+    pk = self.class.model.primary_key
+    records = self.get_recordset.where(pk => data).to_a
+
+    # In transactional mode, verify all requested records exist.
+    if !self._bulk_partial && records.length != data.uniq.length
+      found_ids = records.map { |r| r.send(pk) }
+      missing = data.uniq - found_ids
+      raise RESTFramework::InvalidBulkParametersError.new(
+        "Bulk destroy requires all records to exist. Missing #{pk}: #{missing.join(', ')}.",
+      )
+    end
+
+    if self._bulk_partial
+      # Partial: destroy each record individually.
+      records.each(&:destroy)
+      records
+    else
+      # Transactional: destroy all in a transaction, roll back on failure.
+      self.class.model.transaction do
+        records.each(&:destroy!)
+      end
+
+      records
+    end
   end
 end

data/lib/rest_framework/controller/crud.rb

@@ -1,9 +1,8 @@
 module RESTFramework::Controller
   def create
-    # Bulk create: if `bulk` is enabled and the request body is an array, delegate to `create_all!`.
+    # Bulk create: if `bulk` is enabled and the request body is an array, delegate to `create_all`.
     if self.class.bulk && params[:_json].is_a?(Array)
-      records = self.create_all!
-      return render(api: self.bulk_serialize(records))
+      return self.create_all
     end
 
     render(api: self.create!, status: :created)
@@ -15,11 +14,11 @@ module RESTFramework::Controller
   end
 
   def index
-    render(api: self.get_index_records)
+    render(api: self.index!)
   end
 
   # Get records with both filtering and pagination applied.
-  def get_index_records
+  def index!
     records = self.get_records
 
     # Handle pagination, if enabled.

data/lib/rest_framework/controller/openapi.rb

@@ -194,13 +194,16 @@ module RESTFramework::Controller
           v[:"x-rrf-kind"] = cfg[:kind] if cfg[:kind]
 
           if cfg[:reflection]
+            ref = cfg[:reflection]
             v[:"x-rrf-reflection"] = {
-              class_name: cfg[:reflection].class_name,
-              foreign_key: cfg[:reflection].foreign_key,
-              association_foreign_key: cfg[:reflection].association_foreign_key,
-              association_primary_key: cfg[:reflection].association_primary_key,
-              inverse_of: cfg[:reflection].inverse_of&.name,
-              join_table: cfg[:reflection].join_table,
+              class_name: ref.respond_to?(:class_name) ? ref.class_name : nil,
+              foreign_key: ref.respond_to?(:foreign_key) ? ref.foreign_key : nil,
+              association_foreign_key: ref.respond_to?(:association_foreign_key) ?
+                ref.association_foreign_key : nil,
+              association_primary_key: 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,
             }.compact
             v[:"x-rrf-association_pk"] = cfg[:association_pk]
             v[:"x-rrf-sub_fields"] = cfg[:sub_fields]

data/lib/rest_framework/controller.rb

@@ -14,30 +14,42 @@ module RESTFramework::Controller
     inflect_acronyms: RESTFramework.config.inflect_acronyms,
     openapi_include_children: false,
 
-    # Core attributes related to models.
+    # Options related to models.
     model: nil,
     recordset: nil,
     excluded_actions: nil,
-    bulk: false,
 
-    # Attributes for configuring record fields.
+    # Bulk configuration.
+    #
+    # When `bulk` is truthy, it enables the default bulk behavior (`:default`), which is per-record
+    # processing (e.g., `create` for each record). When `bulk` is set to `:raw`, it enables single
+    # SQL query behavior (e.g., `insert_all` for bulk create) which skips validations/callbacks.
+    bulk: false,
+    bulk_partial: false,
+    bulk_partial_query_param: "bulk_partial".freeze,
+    bulk_allow_mode_override: false,
+    bulk_mode_query_param: "bulk_mode".freeze,
+    bulk_max_size: nil,
+    bulk_max_raw_size: nil,
+
+    # Configuring record fields.
     fields: nil,
     field_config: nil,
     read_only_fields: RESTFramework.config.read_only_fields,
     write_only_fields: RESTFramework.config.write_only_fields,
     hidden_fields: nil,
 
-    # Attributes for finding records.
+    # Finding records.
     find_by_fields: nil,
     find_by_query_param: "find_by".freeze,
 
-    # Options for what should be included/excluded from default fields.
+    # What should be included/excluded from default fields.
     exclude_associations: false,
 
-    # Options for handling request body parameters.
+    # Handling request body parameters.
     allowed_parameters: nil,
 
-    # Attributes for the default native serializer.
+    # Options for the default native serializer.
     native_serializer_config: nil,
     native_serializer_singular_config: nil,
     native_serializer_plural_config: nil,
@@ -49,7 +61,7 @@ module RESTFramework::Controller
     native_serializer_associations_limit_query_param: "associations_limit".freeze,
     native_serializer_include_associations_count: false,
 
-    # Attributes for filtering, ordering, and searching.
+    # Options for filtering, ordering, and searching.
     filter_backends: [
       RESTFramework::QueryFilter,
       RESTFramework::OrderingFilter,
@@ -96,18 +108,39 @@ module RESTFramework::Controller
     enable_action_text: false,
     enable_active_storage: false,
   }
-  BASE64_REGEX = /data:(.*);base64,(.*)/
-  BASE64_TRANSLATE = ->(field, value) {
-    return value unless BASE64_REGEX.match?(value)
 
-    _, content_type, payload = value.match(BASE64_REGEX).to_a
+  # Exceptions to be rescued and handled by returning a reasonable error response.
+  RRF_RESCUED_EXCEPTIONS = [
+    RESTFramework::InvalidBulkParametersError,
+    RESTFramework::BulkRecordErrorsError,
+  ].freeze
+  RRF_RESCUED_RAILS_EXCEPTIONS = [
+    ActionController::ParameterMissing,
+    ActionController::UnpermittedParameters,
+    ActionDispatch::Http::Parameters::ParseError,
+    ActiveRecord::AssociationTypeMismatch,
+    ActiveRecord::NotNullViolation,
+    ActiveRecord::RecordNotFound,
+    ActiveRecord::RecordInvalid,
+    ActiveRecord::RecordNotSaved,
+    ActiveRecord::RecordNotDestroyed,
+    ActiveRecord::RecordNotUnique,
+    ActiveModel::UnknownAttributeError,
+  ].freeze
+
+  # Anchored regex with non-greedy content_type match to prevent over-matching on malicious input.
+  RRF_BASE64_REGEX = /\Adata:([^;]*);base64,(.*)\z/m
+  RRF_BASE64_TRANSLATE = ->(field, value) {
+    return value unless RRF_BASE64_REGEX.match?(value)
+
+    _, content_type, payload = value.match(RRF_BASE64_REGEX).to_a
     {
       io: StringIO.new(Base64.decode64(payload)),
       content_type: content_type,
       filename: "file_#{field}#{Rack::Mime::MIME_TYPES.invert[content_type]}",
     }
   }
-  ACTIVESTORAGE_KEYS = [ :io, :content_type, :filename, :identify, :key ]
+  RRF_ACTIVESTORAGE_KEYS = [ :io, :content_type, :filename, :identify, :key ]
 
   # Default action for API root.
   def root
@@ -366,10 +399,10 @@ module RESTFramework::Controller
         next unless self.model.respond_to?(action)
 
         self.define_method(action) do
-          if self.model.method(action).parameters.last&.first == :keyrest
-            render(api: self.model.send(action, **params))
+          if self.class.model.method(action).parameters.last&.first == :keyrest
+            render(api: self.class.model.send(action, **request.query_parameters.symbolize_keys))
           else
-            render(api: self.model.send(action))
+            render(api: self.class.model.send(action))
           end
         end
       end
@@ -383,7 +416,7 @@ module RESTFramework::Controller
           record = self.get_record
 
           if record.method(action).parameters.last&.first == :keyrest
-            render(api: record.send(action, **params))
+            render(api: record.send(action, **request.query_parameters.symbolize_keys))
           else
             render(api: record.send(action))
           end
@@ -417,27 +450,14 @@ module RESTFramework::Controller
     # Skip CSRF since this is an API.
     begin
       base.skip_before_action(:verify_authenticity_token)
-    rescue
+    rescue ArgumentError
+      # The callback may not exist if forgery protection isn't enabled; this is expected.
       nil
     end
 
-    # Handle some common exceptions.
-    unless RESTFramework.config.disable_rescue_from
-      base.rescue_from(
-        ActionController::ParameterMissing,
-        ActionController::UnpermittedParameters,
-        ActionDispatch::Http::Parameters::ParseError,
-        ActiveRecord::AssociationTypeMismatch,
-        ActiveRecord::NotNullViolation,
-        ActiveRecord::RecordNotFound,
-        ActiveRecord::RecordInvalid,
-        ActiveRecord::RecordNotSaved,
-        ActiveRecord::RecordNotDestroyed,
-        ActiveRecord::RecordNotUnique,
-        ActiveModel::UnknownAttributeError,
-        with: :rrf_error_handler,
-      )
-    end
+    # Handle exceptions.
+    base.rescue_from(*RRF_RESCUED_EXCEPTIONS, with: :rrf_error_handler)
+    base.rescue_from(*RRF_RESCUED_RAILS_EXCEPTIONS, with: :rrf_error_handler)
 
     # Use `TracePoint` hook to automatically call `rrf_finalize`.
     if RESTFramework.config.auto_finalize
@@ -470,6 +490,8 @@ module RESTFramework::Controller
     status = case e
     when ActiveRecord::RecordNotFound
       404
+    when RESTFramework::BulkRecordErrorsError
+      422
     else
       400
     end
@@ -561,8 +583,11 @@ module RESTFramework::Controller
     end
   end
 
-  # Compatibility alias for deprecated `api_response`.
-  alias_method :api_response, :render_api
+  # Deprecated alias for `render_api`.
+  def api_response(*args, **kwargs)
+    RESTFramework.deprecator.warn("`api_response` is deprecated; use `render_api` instead.")
+    render_api(*args, **kwargs)
+  end
 
   def options
     render(api: self.openapi_document)
@@ -594,13 +619,13 @@ module RESTFramework::Controller
 
       # ActiveStorage Integration: `has_one_attached`
       if self.class.enable_active_storage && reflections.key?("#{f}_attachment")
-        hash_variations[f] = ACTIVESTORAGE_KEYS
+        hash_variations[f] = RRF_ACTIVESTORAGE_KEYS
         next f
       end
 
       # ActiveStorage Integration: `has_many_attached`
       if self.class.enable_active_storage && reflections.key?("#{f}_attachments")
-        hash_variations[f] = ACTIVESTORAGE_KEYS
+        hash_variations[f] = RRF_ACTIVESTORAGE_KEYS
         next nil
       end
 
@@ -636,7 +661,7 @@ module RESTFramework::Controller
   end
 
   # Use strong parameters to filter the request body.
-  def get_body_params(bulk_mode: nil)
+  def get_body_params(bulk_action: nil)
     data = self.request.request_parameters
     pk = self.class.model&.primary_key
     allowed_params = self.get_allowed_parameters
@@ -645,15 +670,17 @@ module RESTFramework::Controller
     # assignment ActiveRecord API or the nested assignment ActiveRecord API. Note that there is no
     # need to check for `permit_id_assignment` or `permit_nested_attributes_assignment` here, since
     # that is enforced by strong parameters generated by `get_allowed_parameters`.
-    self.class.model.reflections.each do |name, ref|
-      if payload = data[name]
-        if payload.is_a?(Hash) || (payload.is_a?(Array) && payload.all? { |x| x.is_a?(Hash) })
-          # Assume nested attributes assignment.
-          attributes_key = "#{name}_attributes"
-          data[attributes_key] = data.delete(name) unless data[attributes_key]
-        elsif id_field = RESTFramework::Utils.id_field_for(name, ref)
-          # Assume id/ids assignment.
-          data[id_field] = data.delete(name) unless data[id_field]
+    if !bulk_action && self.class.model
+      self.class.model.reflections.each do |name, ref|
+        if payload = data[name]
+          if payload.is_a?(Hash) || (payload.is_a?(Array) && payload.all? { |x| x.is_a?(Hash) })
+            # Assume nested attributes assignment.
+            attributes_key = "#{name}_attributes"
+            data[attributes_key] = data.delete(name) unless data[attributes_key]
+          elsif id_field = RESTFramework::Utils.id_field_for(name, ref)
+            # Assume id/ids assignment.
+            data[id_field] = data.delete(name) unless data[id_field]
+          end
         end
       end
     end
@@ -669,12 +696,12 @@ module RESTFramework::Controller
     #
     # rubocop:enable Layout/LineLength
     has_many_attached_scalar_data = {}
-    if self.class.enable_active_storage
+    if !bulk_action && self.class.enable_active_storage && self.class.model
       self.class.model.attachment_reflections.keys.each do |k|
         if data[k].is_a?(Array)
           data[k] = data[k].map { |v|
             if v.is_a?(String)
-              v = BASE64_TRANSLATE.call(k, v)
+              v = RRF_BASE64_TRANSLATE.call(k, v)
 
               # Remember scalars because Rails strong params will remove it.
               if v.is_a?(String)
@@ -694,7 +721,7 @@ module RESTFramework::Controller
             data[k][:io] = StringIO.new(Base64.decode64(data[k][:io]))
           end
         elsif data[k].is_a?(String)
-          data[k] = BASE64_TRANSLATE.call(k, data[k])
+          data[k] = RRF_BASE64_TRANSLATE.call(k, data[k])
         end
       end
     end
@@ -703,9 +730,16 @@ module RESTFramework::Controller
     # parameters to the `_json` key of the request body.
     body_params = if allowed_params == true
       ActionController::Parameters.new(data).permit!
-    elsif bulk_mode
-      pk = bulk_mode == :update ? [ pk ] : []
-      ActionController::Parameters.new(data).permit({ _json: allowed_params + pk })
+    elsif bulk_action
+      if bulk_action == :create
+        ActionController::Parameters.new(data).permit({ _json: allowed_params })
+      elsif bulk_action == :update
+        ActionController::Parameters.new(data).permit({ _json: allowed_params + [ pk ] })
+      elsif bulk_action == :destroy
+        ActionController::Parameters.new(data).permit({ _json: [] })
+      else
+        raise ArgumentError, "Invalid bulk action: #{bulk_action}"
+      end
     else
       ActionController::Parameters.new(data).permit(*allowed_params)
     end
@@ -729,6 +763,7 @@ module RESTFramework::Controller
   end
   alias_method :get_create_params, :get_body_params
   alias_method :get_update_params, :get_body_params
+  alias_method :get_destroy_params, :get_body_params
 
   # Get the set of records this controller has access to.
   def get_recordset
@@ -760,10 +795,10 @@ module RESTFramework::Controller
 
     # Find by another column if it's permitted.
     if find_by_param = self.class.find_by_query_param.presence
-      if find_by = params[find_by_param].presence
-        find_by_fields = self.class.find_by_fields&.map(&:to_s)
+      if find_by = request.query_parameters[find_by_param].presence
+        find_by_fields = self.class.find_by_fields&.map(&:to_s) || self.get_fields
 
-        if !find_by_fields || find_by.in?(find_by_fields)
+        if find_by.in?(find_by_fields)
           is_pk = false unless find_by_key == find_by
           find_by_key = find_by
         end

data/lib/rest_framework/errors.rb

@@ -1,6 +1,56 @@
 module RESTFramework::Errors
-end
+  class BaseError < StandardError
+  end
+
+  class NilPassedToRenderAPIError < BaseError
+    def message
+      <<~MSG.split("\n").join(" ")
+        Payload of `nil` was passed to `render_api`; this is unsupported. If you want a blank
+        response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
+        (or similar Active Record method) not finding a record, you should use the bang version
+        (e.g., `find_by!`) to raise `ActiveRecord::RecordNotFound`, which the REST controller will
+        catch and return an appropriate error response.
+      MSG
+    end
+  end
+
+  class InvalidBulkParametersError < BaseError
+    def initialize(detail = nil)
+      @detail = detail
+    end
+
+    def message
+      msg = "Invalid request parameters for bulk action."
+      msg += " #{@detail}" if @detail
+      msg
+    end
+  end
 
-require_relative "errors/base_error"
+  class BulkRecordErrorsError < BaseError
+    attr_reader :errors
+
+    def initialize(records)
+      @errors = records.each_with_index.filter_map { |record, i|
+        next unless record.errors.any?
+        { index: i, errors: record.errors.messages }
+      }
+    end
+
+    # Allow `e.try(:record).try(:errors)` to chain through the standard error handler.
+    def record
+      self
+    end
+
+    def message
+      "Bulk operation failed due to validation errors on #{@errors.length} #{
+        'record'.pluralize(@errors.length)
+      }."
+    end
+  end
+end
 
-require_relative "errors/nil_passed_to_render_api_error"
+# Aliases for convenience.
+RESTFramework::BaseError = RESTFramework::Errors::BaseError
+RESTFramework::NilPassedToRenderAPIError = RESTFramework::Errors::NilPassedToRenderAPIError
+RESTFramework::InvalidBulkParametersError = RESTFramework::Errors::InvalidBulkParametersError
+RESTFramework::BulkRecordErrorsError = RESTFramework::Errors::BulkRecordErrorsError

data/lib/rest_framework/filters/ordering_filter.rb

@@ -1,6 +1,5 @@
 # A filter backend which handles ordering of the recordset.
 class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilter
-  # Get a list of ordering fields for the current action.
   def _get_fields
     @controller.class.ordering_fields&.map(&:to_s) || @controller.get_fields
   end

data/lib/rest_framework/filters/query_filter.rb

@@ -20,7 +20,13 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
     lte: ->(f, v) { { f => ..v } },
     gte: ->(f, v) { { f => v.. } },
     not: ->(f, v) { Not.new({ f => v }) },
-    cont: ->(f, v) { [ "#{f} LIKE ?", "%#{ActiveRecord::Base.sanitize_sql_like(v)}%" ] },
+    cont: ->(f, v) {
+      [
+        "#{ActiveRecord::Base.connection.quote_column_name(f)} LIKE ?", "%#{
+          ActiveRecord::Base.sanitize_sql_like(v)
+        }%"
+      ]
+    },
     in: ->(f, v) {
       if v.is_a?(Array)
         { f => v.map { |el| el == "null" ? nil : el } }
@@ -31,7 +37,6 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
   }.freeze
   PREDICATES_REGEX = /^(.*)_(#{PREDICATES.keys.join("|")})$/
 
-  # Get a list of filter fields for the current action.
   def _get_fields
     # Always return a list of strings; `@controller.get_fields` already does this.
     @controller.class.filter_fields&.map(&:to_s) || @controller.get_fields

data/lib/rest_framework/filters/search_filter.rb

@@ -1,5 +1,4 @@
 class RESTFramework::Filters::SearchFilter < RESTFramework::Filters::BaseFilter
-  # Get a list of search fields for the current action.
   def _get_fields
     if search_fields = @controller.class.search_fields
       return search_fields&.map(&:to_s)
@@ -25,12 +24,13 @@ class RESTFramework::Filters::SearchFilter < RESTFramework::Filters::BaseFilter
           "VARCHAR"
         end
 
-        # Ensure we pass user input as arguments to prevent SQL injection.
+        conn = data.connection
+        like_op = @controller.class.search_ilike ? "ILIKE" : "LIKE"
         return data.where(
           fields.map { |f|
-            "CAST(#{f} AS #{data_type}) #{@controller.class.search_ilike ? "ILIKE" : "LIKE"} ?"
+            "CAST(#{conn.quote_column_name(f)} AS #{data_type}) #{like_op} ?"
           }.join(" OR "),
-          *([ "%#{search}%" ] * fields.length),
+          *([ "%#{ActiveRecord::Base.sanitize_sql_like(search)}%" ] * fields.length),
         )
       end
     end

data/lib/rest_framework/paginators/page_number_paginator.rb

@@ -13,22 +13,21 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
   end
 
   def _page_size
-    page_size = 1
+    page_size = nil
 
-    # Get from context, if allowed.
+    # Get from query param, if allowed.
     if param = @controller.class.page_size_query_param
-      if page_size = @controller.params[param].presence
-        page_size = page_size.to_i
+      if raw = @controller.params[param].presence
+        parsed = raw.to_i
+        page_size = parsed if parsed > 0
       end
     end
 
-    # Otherwise, get from config.
-    if !page_size && @controller.class.page_size
-      page_size = @controller.class.page_size.to_i
-    end
+    # Fall back to the configured page size.
+    page_size ||= @controller.class.page_size&.to_i || 1
 
     # Ensure we don't exceed the max page size.
-    max_page_size = @controller.class.max_page_size&.to_i
+    max_page_size = @controller.class.max_page_size
     if max_page_size && page_size > max_page_size
       page_size = max_page_size
     end
@@ -46,7 +45,7 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
         page_number = 1
       else
         page_number = page_number.to_i
-        if page_number.zero?
+        if page_number < 1
           page_number = 1
         end
       end
@@ -61,7 +60,7 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
   # Wrap the serialized page with appropriate metadata.
   def get_paginated_response(serialized_page)
     page_query_param = @controller.class.page_query_param
-    base_params = @controller.params.to_unsafe_h
+    base_params = @controller.request.query_parameters.symbolize_keys
     next_url = if @page_number < @total_pages
       @controller.url_for({ **base_params, page_query_param => @page_number + 1 })
     end

data/lib/rest_framework/routers.rb

@@ -31,7 +31,7 @@ module ActionDispatch::Routing
 
           begin
             controller = mod.const_get(name_reverse)
-          rescue
+          rescue NameError
             reraise = true
           end
 
@@ -109,7 +109,9 @@ module ActionDispatch::Routing
             next unless controller_class.method_defined?(action)
 
             [ methods ].flatten.each do |m|
-              public_send(m, "", action: action) if self.respond_to?(m)
+              # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
+              # causes parent OPTIONS routes to greedily intercept sub-path requests.
+              public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
             end
           end
 
@@ -122,7 +124,9 @@ module ActionDispatch::Routing
               next if bulk_exclude.include?(action)
 
               [ methods ].flatten.each do |m|
-                public_send(m, "", action: action) if self.respond_to?(m)
+                # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
+                # causes parent OPTIONS routes to greedily intercept sub-path requests.
+                public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
               end
             end
           end
@@ -184,7 +188,9 @@ module ActionDispatch::Routing
             next unless controller_class.method_defined?(action)
 
             [ methods ].flatten.each do |m|
-              public_send(m, "", action: action) if self.respond_to?(m)
+              # Anchor the route since Rails 8.1 OPTIONS routes are non-anchored by default, which
+              # causes parent OPTIONS routes to greedily intercept sub-path requests.
+              public_send(m, "", action: action, anchor: true) if self.respond_to?(m)
             end
           end
         end

data/lib/rest_framework/serializers/native_serializer.rb

@@ -28,8 +28,10 @@ class RESTFramework::Serializers::NativeSerializer < RESTFramework::Serializers:
     # Determine model either explicitly, or by inspecting @object or @controller.
     @model = model
     @model ||= @object.class if @object.is_a?(ActiveRecord::Base)
-    @model ||= @object[0].class if
-      @many && @object.is_a?(Enumerable) && @object.is_a?(ActiveRecord::Base)
+    @model ||= @object.klass if @many && @object.is_a?(ActiveRecord::Relation)
+    @model ||= @object.first.class if @many &&
+      @object.is_a?(Enumerable) &&
+      @object.first.is_a?(ActiveRecord::Base)
 
     @model ||= @controller.class.model if @controller
   end

data/lib/rest_framework/utils.rb

@@ -56,6 +56,13 @@ module RESTFramework::Utils
 
   # Get the first route pattern which matches the given request.
   def self.get_request_route(application_routes, request)
+    # Prefer the route already resolved by the router to avoid an expensive `recognize` call. This
+    # is also required for Rails 8.1+ where OPTIONS routes are non-anchored, causing `path_info` to
+    # be modified during dispatch, which makes `recognize` fail from inside the controller action.
+    if route = request.env["action_dispatch.route"]
+      return route
+    end
+
     application_routes.router.recognize(request) { |route, _| return route }
   end
 

data/lib/rest_framework.rb

@@ -169,9 +169,6 @@ module RESTFramework
     # Whether the backtrace should be shown in rescued errors.
     attr_accessor :show_backtrace
 
-    # Disable `rescue_from` on the controller mixins.
-    attr_accessor :disable_rescue_from
-
     # The default label fields to use when generating labels for `has_many` associations.
     attr_accessor :label_fields
 
@@ -192,6 +189,7 @@ module RESTFramework
     def initialize
       self.register_api_renderer = true
       self.auto_finalize = true
+      self.freeze_config = true
 
       self.show_backtrace = Rails.env.development?
 
@@ -223,7 +221,6 @@ end
 require_relative "rest_framework/engine"
 require_relative "rest_framework/errors"
 require_relative "rest_framework/filters"
-require_relative "rest_framework/generators"
 require_relative "rest_framework/mixins"
 require_relative "rest_framework/paginators"
 require_relative "rest_framework/routers"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -60,16 +60,12 @@ files:
 - lib/rest_framework/controller/openapi.rb
 - lib/rest_framework/engine.rb
 - lib/rest_framework/errors.rb
-- lib/rest_framework/errors/base_error.rb
-- lib/rest_framework/errors/nil_passed_to_render_api_error.rb
 - lib/rest_framework/filters.rb
 - lib/rest_framework/filters/base_filter.rb
 - lib/rest_framework/filters/ordering_filter.rb
 - lib/rest_framework/filters/query_filter.rb
 - lib/rest_framework/filters/ransack_filter.rb
 - lib/rest_framework/filters/search_filter.rb
-- lib/rest_framework/generators.rb
-- lib/rest_framework/generators/controller_generator.rb
 - lib/rest_framework/mixins.rb
 - lib/rest_framework/mixins/base_controller_mixin.rb
 - lib/rest_framework/mixins/bulk_model_controller_mixin.rb

data/lib/rest_framework/errors/base_error.rb

@@ -1,5 +0,0 @@
-class RESTFramework::Errors::BaseError < StandardError
-end
-
-# Alias for convenience.
-RESTFramework::BaseError = RESTFramework::Errors::BaseError

data/lib/rest_framework/errors/nil_passed_to_render_api_error.rb

@@ -1,14 +0,0 @@
-class RESTFramework::Errors::NilPassedToRenderAPIError < RESTFramework::Errors::BaseError
-  def message
-    <<~MSG.split("\n").join(" ")
-      Payload of `nil` was passed to `render_api`; this is unsupported. If you want a blank
-      response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
-      (or similar Active Record method) not finding a record, you should use the bang version (e.g.,
-      `find_by!`) to raise `ActiveRecord::RecordNotFound`, which the REST controller will catch and
-      return an appropriate error response.
-    MSG
-  end
-end
-
-# Alias for convenience.
-RESTFramework::NilPassedToRenderAPIError = RESTFramework::Errors::NilPassedToRenderAPIError

data/lib/rest_framework/generators/controller_generator.rb

@@ -1,64 +0,0 @@
-require "rails/generators"
-
-# Most projects don't have the inflection "REST" as an acronym, so this is a helper class to prevent
-# this generator from being namespaced as `"r_e_s_t_framework"`.
-# :nocov:
-class RESTFrameworkCustomGeneratorControllerNamespace < String
-  def camelize
-    "RESTFramework"
-  end
-end
-# :nocov:
-
-class RESTFramework::Generators::ControllerGenerator < Rails::Generators::Base
-  PATH_REGEX = %r{^[a-z0-9][a-z0-9_/]+$}
-
-  desc <<~END
-    Description:
-      Generates a new REST Framework controller.
-
-      Specify the controller as a path, including the module, if needed, like:
-      'parent_module/controller_name'.
-
-    Example:
-      `rails generate rest_framework:controller user_api/groups`
-
-      Generates a controller at `app/controllers/user_api/groups_controller.rb` named
-      `UserApi::GroupsController`.
-  END
-
-  argument :path, type: :string
-  class_option(
-    :parent_class, type: :string, default: "ApplicationController", desc: "Inheritance parent"
-  )
-  class_option(
-    :include_base,
-    type: :boolean,
-    default: false,
-    desc: "Include `BaseControllerMixin`, not `ModelControllerMixin`",
-  )
-
-  # Some projects may not have the inflection "REST" as an acronym, which changes this generator to
-  # be namespaced in `r_e_s_t_framework`, which is weird.
-  def self.namespace
-    RESTFrameworkCustomGeneratorControllerNamespace.new("rest_framework:controller")
-  end
-
-  def create_rest_controller_file
-    unless PATH_REGEX.match?(self.path)
-      raise StandardError, "Path isn't valid."
-    end
-
-    # Remove '_controller' from end of path, if it exists.
-    cleaned_path = self.path.delete_suffix("_controller")
-
-    content = <<~END
-      class #{cleaned_path.camelize}Controller < #{options[:parent_class]}
-        include RESTFramework::#{
-          options[:include_base] ? "BaseControllerMixin" : "ModelControllerMixin"
-        }
-      end
-    END
-    create_file("app/controllers/#{cleaned_path}_controller.rb", content)
-  end
-end

data/lib/rest_framework/generators.rb

@@ -1,4 +0,0 @@
-module RESTFramework::Generators
-end
-
-require_relative "generators/controller_generator"