rest_framework 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4f1c8277a69cc73b8683ac06a9a31c0706fa144d1e1d030eb0f97987da2429
-  data.tar.gz: 7f275441694689003a4f25df054c040a238a55ea63f331a77ff0fb370bff102b
+  metadata.gz: 8119cab13c69b27ebfa36906e6bcd577688f2ba63b136e0833f4cfdeae3ca5c3
+  data.tar.gz: 149343b13dfdf94b5804beb502d2296d95f487774d1cb3a1dd30dd63f4ab2afc
 SHA512:
-  metadata.gz: 373581c9bb9eb2887bb0a66ed8013cbe2f595fa2f0ddb0e9e7180b89b9d81d02991556c14ade1dd2a9ac86844a76a3080daa41fb4d5debba8357959d2fe7ec52
-  data.tar.gz: f26c82b74d3cb344e65bc863a3718e152e4f107d7d709c64a7c47779c9ed60024e26c00709fd934177099b71cbdfdda37719f43e864a4aed907ca2676f31897f
+  metadata.gz: 17d7143b9ac7a9a3f01fab29a369a083750d26f5923bea7d6b9b9dad407efe25bc30321de0024e1d1f3883aa86838bb250b2ee8c4c749e159386b42d5038f5c8
+  data.tar.gz: b1794ca103409bc69f235d72603bd8c9ecd91f674cf4e41c8072ec4c35b4e0d5ca26058f6903554df404183ee7c9624dac9b8f33b67fe212874e98bc4a600355

data/README.md

@@ -38,10 +38,22 @@ bundle install
 
 ## Quick Usage Tutorial
 
-This section provides some simple examples to quickly get you started using the framework.
+To add REST framework features to a controller, include the `Controller` module:
 
-For the purpose of this example, you'll want to add an `api_controller.rb` to your controllers, as
-well as a directory for the resources:
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::Controller
+
+  # Here is where you can set configuration class attributes that will propagate to child
+  # controllers.
+
+  # Setting up a paginator class here makes more sense than defining it on every child controller.
+  self.paginator_class = RESTFramework::PageNumberPaginator
+  self.page_size = 30
+end
+```
+
+Here is what the directory structure might look like for resource controllers:
 
 ```text
 controllers/
@@ -52,29 +64,18 @@ controllers/
    └─ users_controller.rb
 ```
 
-### Controller Mixins
-
-The root `ApiController` can include any common behavior you want to share across all your API
-controllers:
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-
-  # Setting up a paginator class here makes more sense than defining it on every child controller.
-  self.paginator_class = RESTFramework::PageNumberPaginator
-  self.page_size = 30
-end
-```
+### Root Controller
 
-A root controller can provide actions that exist on the root of your API. It's best to define a
-dedicated root controller, rather than using the `ApiController` for this purpose, so that actions
-don't propagate to child controllers:
+It is typically a good pattern for the root of your API to have a dedicated `Api::RootController`
+outside the inheritance chain of your other API controllers, so that you can define actions on the
+root without them propagating to child controllers, and so you can set global configuration on the
+`ApiController`.
 
 ```ruby
 class Api::RootController < ApiController
   self.extra_actions = {test: :get}
 
+  # The root action is routed by `rest_root`.
   def root
     render(
       api: {
@@ -94,17 +95,19 @@ class Api::RootController < ApiController
 end
 ```
 
-And here is an example of a resource controller:
+### Resource Controllers
+
+Other API controllers can be associated to a resource/model by setting the `model` class attribute.
 
 ```ruby
 class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
+  self.model = Movie  # Automatically routes the standard CRUD actions for this controller.
+  self.bulk = true  # Enables bulk create/update/destroy actions for this controller.
   self.fields = [:id, :name, :release_date, :enabled]
   self.extra_member_actions = {first: :get}
 
   def first
-    # Always use the bang method, since the framework will rescue `RecordNotFound` and return a
+    # Always use bang methods, since the framework will rescue `RecordNotFound` and return a
     # sensible error response.
     render(api: self.get_records.first!)
   end
@@ -120,9 +123,11 @@ to include or exclude fields rather than defining them manually:
 
 ```ruby
 class Api::UsersController < ApiController
-  include RESTFramework::ModelControllerMixin
-
   self.fields = {include: [:calculated_popularity], exclude: [:impersonation_token]}
+
+  # You can even disable some of the builtin actions. For example, this effectively makes the
+  # resource read-only:
+  self.excluded_actions = [:create, :update, :destroy, :update_all, :destroy_all]
 end
 ```
 

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.2.0

data/app/views/rest_framework/_routes_and_forms.html.erb

@@ -1,6 +1,3 @@
-<%
-  @is_model_controller = controller.class.included_modules.include?(RESTFramework::ModelControllerMixin)
-%>
 <div class="row">
   <div>
     <ul class="nav nav-tabs">
@@ -25,7 +22,7 @@
           </a>
         </li>
       <% end %>
-      <% if @_rrf_form_routes_html.present? && @is_model_controller %>
+      <% if @_rrf_form_routes_html.present? && controller.class.model %>
         <li class="nav-item">
           <a class="nav-link" href="#tabHtmlForm" data-bs-toggle="tab" role="tab">
             HTML Form
@@ -43,7 +40,7 @@
         <%= render partial: "rest_framework/routes_and_forms/raw_form" %>
       </div>
     <% end %>
-    <% if @_rrf_form_routes_html.present? && @is_model_controller %>
+    <% if @_rrf_form_routes_html.present? && controller.class.model %>
       <div class="tab-pane fade" id="tabHtmlForm" role="tabpanel">
         <%= render partial: "rest_framework/routes_and_forms/html_form" %>
       </div>

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/app/views/rest_framework/routes_and_forms/_raw_form.html.erb

@@ -29,7 +29,7 @@
     </label>
   </div>
 
-  <% if @is_model_controller && model = controller.class.get_model %>
+  <% if model = controller.class.model %>
     <% if attachment_reflections = model.attachment_reflections.presence %>
       <div class="mb-2" style="display: none" id="rawFilesFormWrapper">
         <%= form_with(**{

data/lib/rest_framework/controller/bulk.rb

@@ -0,0 +1,272 @@
+module RESTFramework::Controller
+  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?
+    s = RESTFramework::Utils.wrap_ams(self.get_serializer_class)
+    records.map do |record|
+      s.new(record, controller: self).serialize.merge!({ errors: record.errors.presence }.compact)
+    end
+  end
+
+  def _bulk_mode
+    return @_bulk_mode if defined?(@_bulk_mode)
+
+    # 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
+
+  # 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
+
+  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 = 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
+      # 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
+
+    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 self._bulk_mode == :raw
+      deleted = self.destroy_all_raw!
+      return render(api: { message: "Bulk destroy successful.", result: deleted })
+    end
+
+    records = self.destroy_all_default!
+    render(api: { message: "Bulk destroy successful.", records: self._bulk_serialize(records) })
+  end
+
+  def destroy_all_raw!
+    data = self._bulk_pk_data
+    pk = self.class.model.primary_key
+    self.get_recordset.where(pk => data).delete_all
+  end
+
+  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

@@ -0,0 +1,65 @@
+module RESTFramework::Controller
+  def create
+    # 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)
+      return self.create_all
+    end
+
+    render(api: self.create!, status: :created)
+  end
+
+  # Perform the `create!` call and return the created record.
+  def create!
+    self.create_from.create!(self.get_create_params)
+  end
+
+  def index
+    render(api: self.index!)
+  end
+
+  # Get records with both filtering and pagination applied.
+  def index!
+    records = self.get_records
+
+    # Handle pagination, if enabled.
+    if paginator_class = self.class.paginator_class
+      # Paginate if there is a `max_page_size`, or if there is no `page_size_query_param`, or if the
+      # page size is not set to "0".
+      max_page_size = self.class.max_page_size
+      page_size_query_param = self.class.page_size_query_param
+      if max_page_size || !page_size_query_param || params[page_size_query_param] != "0"
+        paginator = paginator_class.new(data: records, controller: self)
+        page = paginator.get_page
+        serialized_page = self.serialize(page)
+        return paginator.get_paginated_response(serialized_page)
+      end
+    end
+
+    records
+  end
+
+  def show
+    render(api: self.get_record)
+  end
+
+  def update
+    render(api: self.update!)
+  end
+
+  # Perform the `update!` call and return the updated record.
+  def update!
+    record = self.get_record
+    record.update!(self.get_update_params)
+    record
+  end
+
+  def destroy
+    self.destroy!
+    render(api: "")
+  end
+
+  # Perform the `destroy!` call and return the destroyed (and frozen) record.
+  def destroy!
+    self.get_record.destroy!
+  end
+end