rest_framework 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e37d7baf0b2e805e4df451a8ef646e57ed078a7edd3f9d03b524198eef9fc83f
-  data.tar.gz: c6f5bf3f8f7bfa79566a1292f7634f94b29a09a934a0179adea6e3320291cb9e
+  metadata.gz: edeb7963dbca0185ff384e628a185c83341e3154d6414c9d8f70a05115abd23a
+  data.tar.gz: 8d6bc94fea07e57c20625c8aa192ced88789e078bf3a4b29b71e6c80099f2436
 SHA512:
-  metadata.gz: 13b7905e307bbc0f204d2570c05298cf9c4bcc025719210c3f496bac64a387f611ec4ab3772f8c268cc41b608973b7d3502cf5542d9fee0cce5587ef80a773cc
-  data.tar.gz: 49ef1e4a637fa2f3dee50f40042cdf50a28f68f632a0e5587a339e492954ef90c1f7cd8d80f4b0fb39668838ee020556b29dfd806377e82541b3c4a8940d6b55
+  metadata.gz: 68ecf8a8a045c3e217c597f86b46573dc80bb931e20be45af01b939079f8cf2dd27d68e8bebd8d458726b04b8b55fb2dd65a60bcf4c847c30feb1257f7cfb9ea
+  data.tar.gz: 388478f7c8f2c51a96740f25043aa7d188b5e59731478f4bca2ce6171fadc5ba1e201b12ee051859386ce151c1114b9b6f207dbe840e732dec652d9639323825

data/VERSION

@@ -1 +1 @@
-0.7.4
+0.7.6

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

@@ -3,8 +3,20 @@
 <%= csrf_meta_tags %>
 <%= csp_meta_tag rescue nil %>
 
+<!-- Bootstrap -->
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css" integrity="sha384-F3w7mX95PdgyTmZZMECAngseQB83DfGTowi0iMjiWaeVhAn4FJkqJByhZMI3AhiU" crossorigin="anonymous">
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.2.0/styles/vs.min.css" integrity="sha512-aWjgJTbdG4imzxTxistV5TVNffcYGtIQQm2NBNahV6LmX14Xq9WwZTL1wPjaSglUuVzYgwrq+0EuI4+vKvQHHw==" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/js/bootstrap.bundle.min.js" integrity="sha384-/bQdsTh/da6pkI1MST/rWKFNjaCP5gBSY4sEBT38Q/9RBh9AH40zEOg7Hlq2THRZ" crossorigin="anonymous"></script>
+
+<!-- Highlight.js -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/vs.min.css" integrity="sha512-AVoZ71dJLtHRlsgWwujPT1hk2zxtFWsPlpTPCc/1g0WgpbmlzkqlDFduAvnOV4JJWKUquPc1ZyMc5eq4fRnKOQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js" integrity="sha512-bgHRAiTjGrzHzLyKOnpFvaEpGzJet3z4tZnXGjpsCcqOnAH6VGUx9frc5bcIhKTVLEiCO6vEhNAgx5jtLUYrfA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/languages/json.min.js" integrity="sha512-0xYvyncS9OLE7GOpNBZFnwyh9+bq4HVgk4yVVYI678xRvE22ASicF1v6fZ1UiST+M6pn17MzFZdvVCI3jTHSyw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/languages/xml.min.js" integrity="sha512-5zBcw+OKRkaNyvUEPlTSfYylVzgpi7KpncY36b0gRudfxIYIH0q0kl2j26uCUB3YBRM6ytQQEZSgRg+ZlBTmdA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+
+<!-- NeatJSON -->
+<script src="https://cdn.jsdelivr.net/npm/neatjson@0.10.5/javascript/neatjson.min.js"></script>
+
+<!-- Custom Style -->
 <style>
 /* Adjust headers to always take up their entire row, and tweak the sizing. */
 h1,h2,h3,h4,h5,h6 { display: inline-block; font-weight: normal; margin-bottom: 0; }
@@ -17,7 +29,7 @@ h6 { font-size: 1rem; }
 
 /* Make code and code blocks a little nicer looking. */
 code {
-  padding: 0 .35em;
+  padding: .5em !important;
   background-color: #f3f3f3 !important;
   border: 1px solid #aaa;
   border-radius: 3px;
@@ -56,25 +68,22 @@ code {
 }
 </style>
 
-<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/js/bootstrap.bundle.min.js" integrity="sha384-/bQdsTh/da6pkI1MST/rWKFNjaCP5gBSY4sEBT38Q/9RBh9AH40zEOg7Hlq2THRZ" crossorigin="anonymous"></script>
-<script src="https://cdn.jsdelivr.net/npm/neatjson@0.10.5/javascript/neatjson.min.js"></script>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.2.0/highlight.min.js" integrity="sha512-TDKKr+IvoqZnPzc3l35hdjpHD0m+b2EC2SrLEgKDRWpxf2rFCxemkgvJ5kfU48ip+Y+m2XVKyOCD85ybtlZDmw==" crossorigin="anonymous"></script>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.2.0/languages/json.min.js" integrity="sha512-FoN8JE+WWCdIGXAIT8KQXwpiavz0Mvjtfk7Rku3MDUNO0BDCiRMXAsSX+e+COFyZTcDb9HDgP+pM2RX12d4j+A==" crossorigin="anonymous"></script>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.2.0/languages/xml.min.js" integrity="sha512-dICltIgnUP+QSJrnYGCV8943p3qSDgvcg2NU4W8IcOZP4tdrvxlXjbhIznhtVQEcXow0mOjLM0Q6/NvZsmUH4g==" crossorigin="anonymous"></script>
+<!-- Custom JavaScript -->
 <script>
-hljs.initHighlightingOnLoad()
-
 // What to do when document loads.
 document.addEventListener("DOMContentLoaded", (event) => {
   // Pretty-print JSON.
   [...document.getElementsByClassName("language-json")].forEach((element, index) => {
-    element.innerHTML = neatJSON(JSON.parse(element.innerHTML), {
+    element.innerHTML = neatJSON(JSON.parse(element.innerText), {
       wrap: 80,
       afterComma: 1,
       afterColon: 1,
     })
   });
 
+  // Then highlight it.
+  hljs.highlightAll();
+
   // Insert copy link and callback to copy contents of `<code>` element.
   [...document.getElementsByClassName("rrf-copy")].forEach((element, index) => {
     element.insertAdjacentHTML(

data/lib/rest_framework/controller_mixins/base.rb

@@ -12,16 +12,15 @@ module RESTFramework::BaseControllerMixin
       :created_at, :created_by, :created_by_id, :updated_at, :updated_by, :updated_by_id
     ].freeze,
     accept_generic_params_as_body_params: false,
-    show_backtrace: false,
     extra_actions: nil,
     extra_member_actions: nil,
     filter_backends: nil,
     singleton_controller: nil,
 
-    # Metadata and display options.
+    # Options related to metadata and display.
     title: nil,
     description: nil,
-    inflect_acronyms: ["ID", "REST", "API"].freeze,
+    inflect_acronyms: ["ID", "IDs", "REST", "API", "APIs"].freeze,
 
     # Options related to serialization.
     rescue_unknown_format_with: :json,
@@ -36,6 +35,10 @@ module RESTFramework::BaseControllerMixin
     page_size_query_param: "page_size",
     max_page_size: nil,
 
+    # Options related to bulk actions and batch processing.
+    bulk_guard_query_param: nil,
+    enable_batch_processing: nil,
+
     # Option to disable serializer adapters by default, mainly introduced because Active Model
     # Serializers will do things like serialize `[]` into `{"":[]}`.
     disable_adapters_by_default: true,
@@ -74,6 +77,13 @@ module RESTFramework::BaseControllerMixin
         end
       end
 
+      # Add builtin bulk actions.
+      RESTFramework::RRF_BUILTIN_BULK_ACTIONS.each do |action, methods|
+        if self.method_defined?(action)
+          actions[action] = {path: "", methods: methods, type: :builtin}
+        end
+      end
+
       # Add extra actions.
       if extra_actions = self.try(:extra_actions)
         actions.merge!(RESTFramework::Utils.parse_extra_actions(extra_actions, controller: self))
@@ -159,11 +169,17 @@ module RESTFramework::BaseControllerMixin
     end
 
     # Handle some common exceptions.
-    base.rescue_from(ActiveRecord::RecordNotFound, with: :record_not_found)
-    base.rescue_from(ActiveRecord::RecordInvalid, with: :record_invalid)
-    base.rescue_from(ActiveRecord::RecordNotSaved, with: :record_not_saved)
-    base.rescue_from(ActiveRecord::RecordNotDestroyed, with: :record_not_destroyed)
-    base.rescue_from(ActiveModel::UnknownAttributeError, with: :unknown_attribute_error)
+    unless RESTFramework.config.disable_rescue_from
+      base.rescue_from(
+        ActiveRecord::RecordNotFound,
+        ActiveRecord::RecordInvalid,
+        ActiveRecord::RecordNotSaved,
+        ActiveRecord::RecordNotDestroyed,
+        ActiveRecord::RecordNotUnique,
+        ActiveModel::UnknownAttributeError,
+        with: :rrf_error_handler,
+      )
+    end
 
     # Use `TracePoint` hook to automatically call `rrf_finalize`.
     unless RESTFramework.config.disable_auto_finalize
@@ -211,6 +227,7 @@ module RESTFramework::BaseControllerMixin
 
   # Filter an arbitrary data set over all configured filter backends.
   def get_filtered_data(data)
+    # Apply each filter sequentially.
     self.get_filter_backends.each do |filter_class|
       filter = filter_class.new(controller: self)
       data = filter.get_filtered_data(data)
@@ -223,53 +240,26 @@ module RESTFramework::BaseControllerMixin
     return self.class.get_options_metadata
   end
 
-  def record_invalid(e)
-    return api_response(
-      {
-        message: "Record invalid.", errors: e.record&.errors
-      }.merge(self.class.show_backtrace ? {exception: e.full_message} : {}),
-      status: 400,
-    )
-  end
-
-  def record_not_found(e)
-    return api_response(
-      {
-        message: "Record not found.",
-      }.merge(self.class.show_backtrace ? {exception: e.full_message} : {}),
-      status: 404,
-    )
-  end
-
-  def record_not_saved(e)
-    return api_response(
-      {
-        message: "Record not saved.", errors: e.record&.errors
-      }.merge(self.class.show_backtrace ? {exception: e.full_message} : {}),
-      status: 400,
-    )
-  end
-
-  def record_not_destroyed(e)
-    return api_response(
-      {
-        message: "Record not destroyed.", errors: e.record&.errors
-      }.merge(self.class.show_backtrace ? {exception: e.full_message} : {}),
-      status: 400,
-    )
-  end
+  def rrf_error_handler(e)
+    status = case e
+    when ActiveRecord::RecordNotFound
+      404
+    else
+      400
+    end
 
-  def unknown_attribute_error(e)
     return api_response(
       {
-        message: e.message.capitalize,
-      }.merge(self.class.show_backtrace ? {exception: e.full_message} : {}),
-      status: 400,
+        message: e.message,
+        errors: e.try(:record).try(:errors),
+        exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
+      }.compact,
+      status: status,
     )
   end
 
-  # Helper to render a browsable API for `html` format, along with basic `json`/`xml` formats, and
-  # with support or passing custom `kwargs` to the underlying `render` calls.
+  # Render a browsable API for `html` format, along with basic `json`/`xml` formats, and with
+  # support or passing custom `kwargs` to the underlying `render` calls.
   def api_response(payload, html_kwargs: nil, **kwargs)
     html_kwargs ||= {}
     json_kwargs = kwargs.delete(:json_kwargs) || {}

data/lib/rest_framework/controller_mixins/bulk.rb

@@ -0,0 +1,82 @@
+require_relative "models"
+
+# Mixin for creating records in bulk. This is unique compared to update/destroy because we overload
+# the existing `create` action to support bulk creation.
+# :nocov:
+module RESTFramework::BulkCreateModelMixin
+  def create
+    status, payload = self.create_all!
+    return api_response(payload, status: status)
+  end
+
+  # Perform the `create` or `insert_all` call and return the created records with any errors. The
+  # result should be of the form: `(status, payload)`, and `payload` should be of the form:
+  # `[{success:, record: | errors:}]`, unless batch mode is enabled, in which case `payload` is
+  # blank with a status of `202`.
+  def create_all!
+    if self.class.bulk_batch_mode
+      insert_from = if self.get_recordset.respond_to?(:insert_all) && self.create_from_recordset
+        # Create with any properties inherited from the recordset. We exclude any `select` clauses
+        # in case model callbacks need to call `count` on this collection, which typically raises a
+        # SQL `SyntaxError`.
+        self.get_recordset.except(:select)
+      else
+        # Otherwise, perform a "bare" insert_all.
+        self.class.get_model
+      end
+
+      insert_from
+    end
+
+    # Perform bulk creation, possibly in a transaction.
+    self.class._rrf_bulk_transaction do
+      if self.get_recordset.respond_to?(:insert_all) && self.create_from_recordset
+        # Create with any properties inherited from the recordset. We exclude any `select` clauses
+        # in case model callbacks need to call `count` on this collection, which typically raises a
+        # SQL `SyntaxError`.
+        return self.get_recordset.except(:select).create!(self.get_create_params)
+      else
+        # Otherwise, perform a "bare" insert_all.
+        return self.class.get_model.insert_all(self.get_create_params)
+      end
+    end
+  end
+end
+
+# Mixin for updating records in bulk.
+module RESTFramework::BulkUpdateModelMixin
+  def update_all
+    raise NotImplementedError, "TODO"
+  end
+
+  # Perform the `update!` call and return the updated record.
+  def update_all!
+    raise NotImplementedError, "TODO"
+  end
+end
+
+# Mixin for destroying records in bulk.
+module RESTFramework::BulkDestroyModelMixin
+  def destroy_all
+    raise NotImplementedError, "TODO"
+  end
+
+  # Perform the `destroy!` call and return the destroyed (and frozen) record.
+  def destroy_all!
+    raise NotImplementedError, "TODO"
+  end
+end
+
+# Mixin that includes all the CRUD bulk mixins.
+module RESTFramework::BulkModelControllerMixin
+  include RESTFramework::ModelControllerMixin
+
+  include RESTFramework::BulkCreateModelMixin
+  include RESTFramework::BulkUpdateModelMixin
+  include RESTFramework::BulkDestroyModelMixin
+
+  def self.included(base)
+    RESTFramework::ModelControllerMixin.included(base)
+  end
+end
+# :nocov:

data/lib/rest_framework/controller_mixins/models.rb

@@ -12,6 +12,7 @@ module RESTFramework::BaseModelControllerMixin
 
     # Attributes for configuring record fields.
     fields: nil,
+    field_config: nil,
     action_fields: nil,
 
     # Attributes for finding records.
@@ -38,9 +39,22 @@ module RESTFramework::BaseModelControllerMixin
     search_query_param: "search",
     search_ilike: false,
 
-    # Other misc attributes.
-    create_from_recordset: true,  # Option for `recordset.create` vs `Model.create` behavior.
-    filter_recordset_before_find: true,  # Control if filtering is done before find.
+    # Option for `recordset.create` vs `Model.create` behavior.
+    create_from_recordset: true,
+
+    # Control if filtering is done before find.
+    filter_recordset_before_find: true,
+
+    # Option to exclude associations from default fields.
+    exclude_associations: false,
+
+    # Control if bulk operations are done in a transaction and rolled back on error, or if all bulk
+    # operations are attempted and errors simply returned in the response.
+    bulk_transactional: false,
+
+    # Control if bulk operations should be done in "batch" mode, using efficient queries, but also
+    # skipping model validations/callbacks.
+    bulk_batch_mode: false,
   }
 
   module ClassMethods
@@ -77,14 +91,54 @@ module RESTFramework::BaseModelControllerMixin
       return self.get_model.human_attribute_name(s, default: super)
     end
 
+    # Get fields without any action context. Always fallback to columns at the class level.
+    def get_fields
+      if self.fields.is_a?(Hash)
+        return RESTFramework::Utils.parse_fields_hash(
+          self.fields, self.get_model, exclude_associations: self.exclude_associations
+        )
+      end
+
+      return self.fields || (
+        self.get_model ? RESTFramework::Utils.fields_for(
+          self.get_model, exclude_associations: self.exclude_associations
+        ) : []
+      )
+    end
+
+    # Get a field's config, including defaults.
+    def get_field_config(f)
+      config = self.field_config&.dig(f.to_sym) || {}
+
+      # Default sub-fields if field is an association.
+      if ref = self.get_model.reflections[f]
+        model = ref.klass
+        columns = model.columns_hash
+        config[:sub_fields] ||= RESTFramework::Utils.sub_fields_for(ref)
+
+        # Serialize very basic metadata about sub-fields.
+        config[:sub_fields_metadata] = config[:sub_fields].map { |sf|
+          v = {}
+
+          if columns[sf]
+            v[:kind] = "column"
+          end
+
+          next [sf, v]
+        }.to_h.compact.presence
+      end
+
+      return config.compact
+    end
+
     # Get metadata about the resource's fields.
-    def get_fields_metadata(fields: nil)
+    def get_fields_metadata
       # Get metadata sources.
       model = self.get_model
-      fields ||= self.get_fields
-      fields = fields.map(&:to_s)
+      fields = self.get_fields.map(&:to_s)
       columns = model.columns_hash
       column_defaults = model.column_defaults
+      reflections = model.reflections
       attributes = model._default_attributes
 
       return fields.map { |f|
@@ -105,9 +159,9 @@ module RESTFramework::BaseModelControllerMixin
 
         # Determine `type`, `required`, `label`, and `kind` based on schema.
         if column = columns[f]
+          metadata[:kind] = "column"
           metadata[:type] = column.type
           metadata[:required] = true unless column.null
-          metadata[:kind] = "column"
         end
 
         # Determine `default` based on schema; we use `column_defaults` rather than `columns_hash`
@@ -117,25 +171,46 @@ module RESTFramework::BaseModelControllerMixin
           metadata[:default] = column_default
         end
 
-        # Determine `default` and `kind` based on attribute only if not determined by the DB.
+        # Extract details from the model's attributes hash.
         if attributes.key?(f) && attribute = attributes[f]
           unless metadata.key?(:default)
             default = attribute.value_before_type_cast
             metadata[:default] = default unless default.nil?
           end
+          metadata[:kind] ||= "attribute"
+
+          # Get any type information from the attribute.
+          if type = attribute.type
+            metadata[:type] ||= type.type
 
-          unless metadata[:kind]
-            metadata[:kind] = "attribute"
+            # Get enum variants.
+            if type.is_a?(ActiveRecord::Enum::EnumType)
+              metadata[:enum_variants] = type.send(:mapping)
+            end
           end
         end
 
-        # Determine if `kind` is a association or method if not determined already.
-        unless metadata[:kind]
-          if association = model.reflections[f]
-            metadata[:kind] = "association.#{association.macro}"
-          elsif model.method_defined?(f)
-            metadata[:kind] = "method"
+        # Get association metadata.
+        if ref = reflections[f]
+          metadata[:kind] = "association"
+          begin
+            pk = ref.active_record_primary_key
+          rescue ActiveRecord::UnknownPrimaryKey
           end
+          metadata[:association] = {
+            macro: ref.macro,
+            class_name: ref.class_name,
+            foreign_key: ref.foreign_key,
+            primary_key: pk,
+            polymorphic: ref.polymorphic?,
+            table_name: ref.table_name,
+            options: ref.options.presence,
+          }.compact
+        end
+
+        # Determine if this is just a method.
+        if model.method_defined?(f)
+          metadata[:kind] ||= "method"
         end
 
         # Collect validator options into a hash on their type, while also updating `required` based
@@ -156,32 +231,18 @@ module RESTFramework::BaseModelControllerMixin
           metadata[:validators][kind] << options
         end
 
-        next [f, metadata.compact]
-      }.to_h
-    end
+        # Serialize any field config.
+        metadata[:config] = self.get_field_config(f).presence
 
-    # Get metadata about the resource's associations (reflections).
-    def get_associations_metadata
-      return self.get_model.reflections.map { |k, v|
-        next [k, {
-          macro: v.macro,
-          label: self.get_label(k),
-          class_name: v.class_name,
-          foreign_key: v.foreign_key,
-          primary_key: v.active_record_primary_key,
-          polymorphic: v.polymorphic?,
-          table_name: v.table_name,
-          options: v.options,
-        }.compact]
+        next [f, metadata.compact]
       }.to_h
     end
 
     # Get a hash of metadata to be rendered in the `OPTIONS` response. Cache the result.
-    def get_options_metadata(fields: nil)
+    def get_options_metadata
       return super().merge(
         {
-          fields: self.get_fields_metadata(fields: fields),
-          associations: self.get_associations_metadata,
+          fields: self.get_fields_metadata,
         },
       )
     end
@@ -238,9 +299,10 @@ module RESTFramework::BaseModelControllerMixin
   end
 
   def self.included(base)
+    RESTFramework::BaseControllerMixin.included(base)
+
     return unless base.is_a?(Class)
 
-    RESTFramework::BaseControllerMixin.included(base)
     base.extend(ClassMethods)
 
     # Add class attributes (with defaults) unless they already exist.
@@ -265,27 +327,23 @@ module RESTFramework::BaseModelControllerMixin
     return (action_config[action] if action) || self.class.send(generic_config_key)
   end
 
-  # Get fields without any action context. Always fallback to columns at the class level.
-  def self.get_fields
-    if self.fields.is_a?(Hash)
-      return RESTFramework::Utils.parse_fields_hash(self.fields, self.get_model)
-    end
-
-    return self.fields || self.get_model&.column_names || []
-  end
-
   # Get a list of fields for the current action. Returning `nil` indicates that anything should be
   # accepted unless `fallback` is true, in which case we should fallback to this controller's model
   # columns, or en empty array.
   def get_fields(fallback: false)
     fields = _get_specific_action_config(:action_fields, :fields)
 
-    # If fields is a hash, then parse using columns as a base, respecting `only` and `except`.
+    # If fields is a hash, then parse it.
     if fields.is_a?(Hash)
-      return RESTFramework::Utils.parse_fields_hash(fields, self.class.get_model)
+      return RESTFramework::Utils.parse_fields_hash(
+        fields, self.class.get_model, exclude_associations: self.class.exclude_associations
+      )
     elsif !fields && fallback
       # Otherwise, if fields is nil and fallback is true, then fallback to columns.
-      return self.class.get_model&.column_names || []
+      model = self.class.get_model
+      return model ? RESTFramework::Utils.fields_for(
+        model, exclude_associations: self.class.exclude_associations
+      ) : []
     end
 
     return fields
@@ -293,7 +351,7 @@ module RESTFramework::BaseModelControllerMixin
 
   # Pass fields to get dynamic metadata based on which fields are available.
   def get_options_metadata
-    return self.class.get_options_metadata(fields: self.get_fields(fallback: true))
+    return self.class.get_options_metadata
   end
 
   # Get a list of find_by fields for the current action. Do not fallback to columns in case the user
@@ -311,12 +369,12 @@ module RESTFramework::BaseModelControllerMixin
     ) || self.get_fields
   end
 
-  # Helper to get the configured serializer class, or `NativeSerializer` as a default.
+  # Get the configured serializer class, or `NativeSerializer` as a default.
   def get_serializer_class
     return super || RESTFramework::NativeSerializer
   end
 
-  # Helper to get filtering backends, defaulting to using `ModelFilter` and `ModelOrderingFilter`.
+  # Get filtering backends, defaulting to using `ModelFilter` and `ModelOrderingFilter`.
   def get_filter_backends
     return self.class.filter_backends || [
       RESTFramework::ModelFilter, RESTFramework::ModelOrderingFilter
@@ -324,14 +382,16 @@ module RESTFramework::BaseModelControllerMixin
   end
 
   # Filter the request body for keys in current action's allowed_parameters/fields config.
-  def get_body_params
+  def get_body_params(data: nil)
+    data ||= request.request_parameters
+
     # Filter the request body and map to strings. Return all params if we cannot resolve a list of
     # allowed parameters or fields.
     allowed_params = self.get_allowed_parameters&.map(&:to_s)
     body_params = if allowed_params
-      request.request_parameters.select { |p| allowed_params.include?(p) }
+      data.select { |p| allowed_params.include?(p) }
     else
-      request.request_parameters
+      data
     end
 
     # Add query params in place of missing body params, if configured.
@@ -370,7 +430,7 @@ module RESTFramework::BaseModelControllerMixin
     return @recordset = nil
   end
 
-  # Helper to get the records this controller has access to *after* any filtering is applied.
+  # Get the records this controller has access to *after* any filtering is applied.
   def get_records
     return @records if instance_variable_defined?(:@records)
 
@@ -403,7 +463,17 @@ module RESTFramework::BaseModelControllerMixin
     end
 
     # Return the record. Route key is always `:id` by Rails convention.
-    return @record = recordset.find_by!(find_by_key => params[:id])
+    return @record = recordset.find_by!(find_by_key => request.path_parameters[:id])
+  end
+
+  # Create a transaction around the passed block, if configured. This is used primarily for bulk
+  # actions, but we include it here so it's always available.
+  def self._rrf_bulk_transaction(&block)
+    if self.bulk_transactional
+      ActiveRecord::Base.transaction(&block)
+    else
+      yield
+    end
   end
 end
 
@@ -413,7 +483,7 @@ module RESTFramework::ListModelMixin
     return api_response(self.get_index_records)
   end
 
-  # Helper to get records with both filtering and pagination applied.
+  # Get records with both filtering and pagination applied.
   def get_index_records
     records = self.get_records
 
@@ -448,17 +518,19 @@ module RESTFramework::CreateModelMixin
     return api_response(self.create!, status: :created)
   end
 
-  # Helper to perform the `create!` call and return the created record.
+  # Perform the `create!` call and return the created record.
   def create!
-    if self.get_recordset.respond_to?(:create!) && self.create_from_recordset
+    create_from = if self.get_recordset.respond_to?(:create!) && self.create_from_recordset
       # Create with any properties inherited from the recordset. We exclude any `select` clauses in
       # case model callbacks need to call `count` on this collection, which typically raises a SQL
       # `SyntaxError`.
-      return self.get_recordset.except(:select).create!(self.get_create_params)
+      self.get_recordset.except(:select)
     else
       # Otherwise, perform a "bare" create.
-      return self.class.get_model.create!(self.get_create_params)
+      self.class.get_model
     end
+
+    return create_from.create!(self.get_create_params)
   end
 end
 
@@ -468,7 +540,7 @@ module RESTFramework::UpdateModelMixin
     return api_response(self.update!)
   end
 
-  # Helper to perform the `update!` call and return the updated record.
+  # Perform the `update!` call and return the updated record.
   def update!
     record = self.get_record
     record.update!(self.get_update_params)
@@ -483,7 +555,7 @@ module RESTFramework::DestroyModelMixin
     return api_response("")
   end
 
-  # Helper to perform the `destroy!` call and return the destroyed (and frozen) record.
+  # Perform the `destroy!` call and return the destroyed (and frozen) record.
   def destroy!
     return self.get_record.destroy!
   end
@@ -493,29 +565,25 @@ end
 module RESTFramework::ReadOnlyModelControllerMixin
   include RESTFramework::BaseModelControllerMixin
 
-  def self.included(base)
-    return unless base.is_a?(Class)
+  include RESTFramework::ListModelMixin
+  include RESTFramework::ShowModelMixin
 
+  def self.included(base)
     RESTFramework::BaseModelControllerMixin.included(base)
   end
-
-  include RESTFramework::ListModelMixin
-  include RESTFramework::ShowModelMixin
 end
 
 # Mixin that includes all the CRUD mixins.
 module RESTFramework::ModelControllerMixin
   include RESTFramework::BaseModelControllerMixin
 
-  def self.included(base)
-    return unless base.is_a?(Class)
-
-    RESTFramework::BaseModelControllerMixin.included(base)
-  end
-
   include RESTFramework::ListModelMixin
   include RESTFramework::ShowModelMixin
   include RESTFramework::CreateModelMixin
   include RESTFramework::UpdateModelMixin
   include RESTFramework::DestroyModelMixin
+
+  def self.included(base)
+    RESTFramework::BaseModelControllerMixin.included(base)
+  end
 end

data/lib/rest_framework/controller_mixins.rb

@@ -2,4 +2,5 @@ module RESTFramework::ControllerMixins
 end
 
 require_relative "controller_mixins/base"
+require_relative "controller_mixins/bulk"
 require_relative "controller_mixins/models"

data/lib/rest_framework/filters.rb

@@ -14,23 +14,59 @@ class RESTFramework::ModelFilter < RESTFramework::BaseFilter
   # Get a list of filterset fields for the current action. Fallback to columns because we don't want
   # to try filtering by any query parameter because that could clash with other query parameters.
   def _get_fields
-    return @controller.class.filterset_fields || @controller.get_fields(fallback: true)
+    return @_get_fields ||= (
+      @controller.class.filterset_fields || @controller.get_fields(fallback: true)
+    ).map(&:to_s)
   end
 
   # Filter params for keys allowed by the current action's filterset_fields/fields config.
   def _get_filter_params
     # Map filterset fields to strings because query parameter keys are strings.
-    if fields = self._get_fields.map(&:to_s)
-      return @controller.request.query_parameters.select { |p, _| fields.include?(p) }
-    end
+    fields = self._get_fields
+    @associations = []
+
+    return @controller.request.query_parameters.select { |p, _|
+      # Remove any trailing `__in` from the field name.
+      field = p.chomp("__in")
+
+      # Remove any associations whose sub-fields are not filterable. Also populate `@associations`
+      # so the caller can include them.
+      if match = /(.*)\.(.*)/.match(field)
+        field, sub_field = match[1..2]
+        next false unless field.in?(fields)
+
+        sub_fields = @controller.class.get_field_config(field)[:sub_fields]
+        if sub_field.in?(sub_fields)
+          @associations << field.to_sym
+          next true
+        end
+
+        next false
+      end
+
+      next field.in?(fields)
+    }.map { |p, v|
+      # Convert fields ending in `__in` to array values.
+      if p.end_with?("__in")
+        p = p.chomp("__in")
+        v = v.split(",")
+      end
+
+      # Convert "nil" and "null" to nil.
+      if v == "nil" || v == "null"
+        v = nil
+      end
 
-    return @controller.request.query_parameters.to_h
+      [p, v]
+    }.to_h.symbolize_keys
   end
 
   # Filter data according to the request query parameters.
   def get_filtered_data(data)
-    filter_params = self._get_filter_params.symbolize_keys
-    unless filter_params.blank?
+    if filter_params = self._get_filter_params.presence
+      # Include any associations.
+      data = data.includes(*@associations) unless @associations.empty?
+
       return data.where(**filter_params)
     end
 
@@ -43,18 +79,22 @@ class RESTFramework::ModelOrderingFilter < RESTFramework::BaseFilter
   # Get a list of ordering fields for the current action. Do not fallback to columns in case the
   # user wants to order by a virtual column.
   def _get_fields
-    return @controller.class.ordering_fields || @controller.get_fields
+    return @_get_fields ||= (
+      @controller.class.ordering_fields || @controller.get_fields
+    )&.map(&:to_s)
   end
 
   # Convert ordering string to an ordering configuration.
   def _get_ordering
     return nil if @controller.class.ordering_query_param.blank?
 
+    @associations = []
+
     # Ensure ordering_fields are strings since the split param will be strings.
-    fields = self._get_fields&.map(&:to_s)
+    fields = self._get_fields
     order_string = @controller.params[@controller.class.ordering_query_param]
 
-    if order_string.present? && fields
+    if order_string.present?
       ordering = {}.with_indifferent_access
       order_string.split(",").each do |field|
         if field[0] == "-"
@@ -64,9 +104,19 @@ class RESTFramework::ModelOrderingFilter < RESTFramework::BaseFilter
           column = field
           direction = :asc
         end
-        if !fields || column.in?(fields)
-          ordering[column] = direction
+        next unless !fields || column.in?(fields)
+
+        # Populate any `@associations` so the caller can include them.
+        if match = /(.*)\.(.*)/.match(column)
+          association, sub_field = match[1..2]
+          @associations << association.to_sym
+
+          # Also, due to Rails weirdness, we need to convert the association name to the table name.
+          table_name = @controller.class.get_model.reflections[association].table_name
+          column = "#{table_name}.#{sub_field}"
         end
+
+        ordering[column] = direction
       end
       return ordering
     end
@@ -80,7 +130,10 @@ class RESTFramework::ModelOrderingFilter < RESTFramework::BaseFilter
     reorder = !@controller.class.ordering_no_reorder
 
     if ordering && !ordering.empty?
-      return data.send(reorder ? :reorder : :order, _get_ordering)
+      # Include any associations.
+      data = data.includes(*@associations) unless @associations.empty?
+
+      return data.send(reorder ? :reorder : :order, ordering)
     end
 
     return data

data/lib/rest_framework/routers.rb

@@ -102,6 +102,15 @@ module ActionDispatch::Routing
               public_send(m, "", action: action) if self.respond_to?(m)
             end
           end
+
+          # Route bulk actions, if configured.
+          RESTFramework::RRF_BUILTIN_BULK_ACTIONS.each do |action, methods|
+            next unless controller_class.method_defined?(action)
+
+            [methods].flatten.each do |m|
+              public_send(m, "", action: action) if self.respond_to?(m)
+            end
+          end
         end
 
         if unscoped

data/lib/rest_framework/serializers.rb

@@ -88,7 +88,7 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
     return self.config || self.singular_config || self.plural_config
   end
 
-  # Helper to get a native serializer configuration from the controller.
+  # Get a native serializer configuration from the controller.
   def get_controller_native_serializer_config
     return nil unless @controller
 
@@ -101,9 +101,8 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
     return controller_serializer || @controller.class.try(:native_serializer_config)
   end
 
-  # Helper to filter a single subconfig for specific keys. By default, keys from `fields` are
-  # removed from the provided `subcfg`. There are two (mutually exclusive) options to adjust the
-  # behavior:
+  # Filter a single subconfig for specific keys. By default, keys from `fields` are removed from the
+  # provided `subcfg`. There are two (mutually exclusive) options to adjust the behavior:
   #
   #  `add`: Add any `fields` to the `subcfg` which aren't already in the `subcfg`.
   #  `only`: Remove any values found in the `subcfg` not in `fields`.
@@ -149,16 +148,14 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
     return subcfg
   end
 
-  # Helper to filter out configuration properties based on the :except query parameter.
-  def filter_except(cfg)
+  # Filter out configuration properties based on the :except/:only query parameters.
+  def filter_from_request(cfg)
     return cfg unless @controller
 
     except_param = @controller.class.try(:native_serializer_except_query_param)
     only_param = @controller.class.try(:native_serializer_only_query_param)
     if except_param && except = @controller.request.query_parameters[except_param].presence
-      except = except.split(",").map(&:strip).map(&:to_sym)
-
-      unless except.empty?
+      if except = except.split(",").map(&:strip).map(&:to_sym).presence
         # Filter `only`, `except` (additive), `include`, `methods`, and `serializer_methods`.
         if cfg[:only]
           cfg[:only] = self.class.filter_subcfg(cfg[:only], fields: except)
@@ -167,6 +164,7 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
         else
           cfg[:except] = except
         end
+
         cfg[:include] = self.class.filter_subcfg(cfg[:include], fields: except)
         cfg[:methods] = self.class.filter_subcfg(cfg[:methods], fields: except)
         cfg[:serializer_methods] = self.class.filter_subcfg(
@@ -174,20 +172,15 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
         )
       end
     elsif only_param && only = @controller.request.query_parameters[only_param].presence
-      only = only.split(",").map(&:strip).map(&:to_sym)
-
-      unless only.empty?
-        # Filter `only`, `except` (additive), `include`, and `methods`.
+      if only = only.split(",").map(&:strip).map(&:to_sym).presence
+        # Filter `only`, `include`, and `methods`. Adding anything to `except` is not needed,
+        # because any configuration there takes precedence over `only`.
         if cfg[:only]
           cfg[:only] = self.class.filter_subcfg(cfg[:only], fields: only, only: true)
-        elsif cfg[:except]
-          # For the `except` part of the serializer, we need to append any columns not in `only`.
-          model = @controller.class.get_model
-          except_cols = model&.column_names&.map(&:to_sym)&.reject { |c| c.in?(only) }
-          cfg[:except] = self.class.filter_subcfg(cfg[:except], fields: except_cols, add: true)
         else
           cfg[:only] = only
         end
+
         cfg[:include] = self.class.filter_subcfg(cfg[:include], fields: only, only: true)
         cfg[:methods] = self.class.filter_subcfg(cfg[:methods], fields: only, only: true)
         cfg[:serializer_methods] = self.class.filter_subcfg(
@@ -213,18 +206,28 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
     end
 
     # If the config wasn't determined, build a serializer config from controller fields.
-    if fields = @controller&.get_fields
+    if fields = @controller&.get_fields(fallback: true)
       fields = fields.deep_dup
 
       columns = []
-      includes = []
+      includes = {}
       methods = []
       if @model
         fields.each do |f|
           if f.in?(@model.column_names)
             columns << f
           elsif @model.reflections.key?(f)
-            includes << f
+            sub_columns = []
+            sub_methods = []
+            @controller.class.get_field_config(f)[:sub_fields].each do |sf|
+              sub_model = @model.reflections[f].klass
+              if sf.in?(sub_model.column_names)
+                sub_columns << sf
+              elsif sub_model.method_defined?(sf)
+                sub_methods << sf
+              end
+            end
+            includes[f] = {only: sub_columns, methods: sub_methods}
           elsif @model.method_defined?(f)
             methods << f
           end
@@ -242,10 +245,10 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
 
   # Get a configuration passable to `serializable_hash` for the object, filtered if required.
   def get_serializer_config
-    return filter_except(self._get_raw_serializer_config)
+    return filter_from_request(self._get_raw_serializer_config)
   end
 
-  # Internal helper to serialize a single record and merge results of `serializer_methods`.
+  # Serialize a single record and merge results of `serializer_methods`.
   def _serialize(record, config, serializer_methods)
     # Ensure serializer_methods is either falsy, or an array.
     if serializer_methods && !serializer_methods.respond_to?(:to_ary)

data/lib/rest_framework/utils.rb

@@ -1,5 +1,6 @@
 module RESTFramework::Utils
   HTTP_METHOD_ORDERING = %w(GET POST PUT PATCH DELETE OPTIONS HEAD)
+  LABEL_FIELDS = %w(name label login title email username)
 
   # Convert `extra_actions` hash to a consistent format: `{path:, methods:, kwargs:}`, and
   # additional metadata fields.
@@ -139,15 +140,63 @@ module RESTFramework::Utils
   end
 
   # Parse fields hashes.
-  def self.parse_fields_hash(fields_hash, model)
-    parsed_fields = fields_hash[:only] || model&.column_names || []
-    parsed_fields -= fields_hash[:except] if fields_hash[:except]
+  def self.parse_fields_hash(fields_hash, model, exclude_associations: nil)
+    parsed_fields = fields_hash[:only] || (
+      model ? self.fields_for(model, exclude_associations: exclude_associations) : []
+    )
+    parsed_fields += fields_hash[:include] if fields_hash[:include]
+    parsed_fields -= fields_hash[:exclude] if fields_hash[:exclude]
 
     # Warn for any unknown keys.
-    (fields_hash.keys - [:only, :except]).each do |k|
+    (fields_hash.keys - [:only, :include, :exclude]).each do |k|
       Rails.logger.warn("RRF: Unknown key in fields hash: #{k}")
     end
 
     return parsed_fields
   end
+
+  # Get the fields for a given model, including not just columns (which includes
+  # foreign keys), but also associations.
+  def self.fields_for(model, exclude_associations: nil)
+    foreign_keys = model.reflect_on_all_associations(:belongs_to).map(&:foreign_key)
+
+    if exclude_associations
+      return model.column_names.reject { |c| c.in?(foreign_keys) }
+    end
+
+    # Add associations in addition to normal columns.
+    return model.column_names.reject { |c|
+      c.in?(foreign_keys)
+    } + model.reflections.map { |association, ref|
+      if ref.macro.in?([:has_many, :has_and_belongs_to_many]) &&
+          RESTFramework.config.large_reverse_association_tables&.include?(ref.table_name)
+        next nil
+      end
+
+      next association
+    }.compact
+  end
+
+  # Get the sub-fields that may be serialized and filtered/ordered for a reflection.
+  def self.sub_fields_for(ref)
+    model = ref.klass
+
+    if model
+      sub_fields = [model.primary_key].flatten.compact
+
+      # Preferrably find a database column to use as label.
+      if match = LABEL_FIELDS.find { |f| f.in?(model.column_names) }
+        return sub_fields + [match]
+      end
+
+      # Otherwise, find a method.
+      if match = LABEL_FIELDS.find { |f| model.method_defined?(f) }
+        return sub_fields + [match]
+      end
+
+      return sub_fields
+    end
+
+    return ["id", "name"]
+  end
 end

data/lib/rest_framework.rb

@@ -13,6 +13,10 @@ module RESTFramework
   RRF_BUILTIN_ACTIONS = {
     options: :options,
   }.freeze
+  RRF_BUILTIN_BULK_ACTIONS = {
+    update_all: [:put, :patch].freeze,
+    destroy_all: :delete,
+  }.freeze
 
   # Global configuration should be kept minimal, as controller-level configurations allows multiple
   # APIs to be defined to behave differently.
@@ -24,11 +28,25 @@ module RESTFramework
     # in:
     #  - Model delegation, for the helper methods to be defined dynamically.
     #  - Websockets, for `::Channel` class to be defined dynamically.
-    #  - Controller configuration finalization.
+    #  - Controller configuration freezing.
     attr_accessor :disable_auto_finalize
 
     # Freeze configuration attributes during finalization to prevent accidental mutation.
     attr_accessor :freeze_config
+
+    # Specify reverse association tables that are typically very large, andd therefore should not be
+    # added to fields by default.
+    attr_accessor :large_reverse_association_tables
+
+    # Whether the backtrace should be shown in rescued errors.
+    attr_accessor :show_backtrace
+
+    # Option to disable `rescue_from` on the controller mixins.
+    attr_accessor :disable_rescue_from
+
+    def initialize
+      self.show_backtrace = Rails.env.development?
+    end
   end
 
   def self.config

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-10 00:00:00.000000000 Z
+date: 2023-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -42,6 +42,7 @@ files:
 - lib/rest_framework.rb
 - lib/rest_framework/controller_mixins.rb
 - lib/rest_framework/controller_mixins/base.rb
+- lib/rest_framework/controller_mixins/bulk.rb
 - lib/rest_framework/controller_mixins/models.rb
 - lib/rest_framework/engine.rb
 - lib/rest_framework/errors.rb