rest_framework 1.1.0 → 2.0.0.beta1

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,258 @@ 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
+
+  # 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
 
-  # Perform the `update` call and return the collection of (possibly) updated records.
-  def update_all!
+  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
+    pk_type = self.class.model.type_for_attribute(pk)
+    data = self._bulk_object_data(:update, :raw)
+
+    # Cast ids like `update_all_default!` so the existence check compares matching types.
+    data_ids = data.map { |r| pk_type.cast(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
+
+    self.get_recordset.upsert_all(data, unique_by: pk)
+  end
+
+  def update_all_default!
+    pk = self.class.model.primary_key
+    pk_type = self.class.model.type_for_attribute(pk)
+    data = self._bulk_object_data(:update, :default)
+
+    # Cast ids to the pk's type so they match records fetched from the DB; JSON clients often send
+    # ids as strings, which otherwise never match the type-cast keys of `existing` below.
+    data_ids = data.map { |r| pk_type.cast(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[pk_type.cast(attrs[pk])]
+      record.assign_attributes(attrs.except(pk))
+      record
+    }
 
-    # Perform bulk update in a transaction.
-    ActiveRecord::Base.transaction { self.get_recordset.update(data.keys, data.values) }
+    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,12 +1,11 @@
 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)
+    render_api(self.create!, status: :created)
   end
 
   # Perform the `create!` call and return the created record.
@@ -15,11 +14,11 @@ module RESTFramework::Controller
   end
 
   def index
-    render(api: self.get_index_records)
+    render_api(self.class.model ? self.index! : self.index_content)
   end
 
   # Get records with both filtering and pagination applied.
-  def get_index_records
+  def index!
     records = self.get_records
 
     # Handle pagination, if enabled.
@@ -39,12 +38,17 @@ module RESTFramework::Controller
     records
   end
 
+  # The payload rendered at a non-model controller's index (e.g. an API root). Override this.
+  def index_content
+    { message: self.class.description.presence || "This is the API root." }
+  end
+
   def show
-    render(api: self.get_record)
+    render_api(self.get_record)
   end
 
   def update
-    render(api: self.update!)
+    render_api(self.update!)
   end
 
   # Perform the `update!` call and return the updated record.
@@ -56,7 +60,7 @@ module RESTFramework::Controller
 
   def destroy
     self.destroy!
-    render(api: "")
+    render_api("")
   end
 
   # Perform the `destroy!` call and return the destroyed (and frozen) record.

data/lib/rest_framework/controller/openapi.rb

@@ -180,6 +180,7 @@ module RESTFramework::Controller
           end
 
           v[:readOnly] = true if cfg[:read_only]
+          v[:writeOnly] = true if cfg[:write_only]
           v[:default] = cfg[:default] if cfg.key?(:default)
 
           if enum_variants = cfg[:enum_variants]
@@ -194,17 +195,20 @@ 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]
-            v[:"x-rrf-sub_fields_metadata"] = cfg[:sub_fields_metadata]
+            v[:"x-rrf-association_fields"] = cfg[:fields]
+            v[:"x-rrf-association_fields_metadata"] = cfg[:association_fields_metadata]
             v[:"x-rrf-id_field"] = cfg[:id_field]
             v[:"x-rrf-nested_attributes_options"] = cfg[:nested_attributes_options]
           end