rest_framework 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4f1c8277a69cc73b8683ac06a9a31c0706fa144d1e1d030eb0f97987da2429
-  data.tar.gz: 7f275441694689003a4f25df054c040a238a55ea63f331a77ff0fb370bff102b
+  metadata.gz: ebb2a69a51a24192200122bf40a9218e15e1f0d696bfdd63bb8f3aed9f43f82c
+  data.tar.gz: 3b630e5e5f8ec28096e245bc8ced22d5a63423d52799983543c1616b636999d8
 SHA512:
-  metadata.gz: 373581c9bb9eb2887bb0a66ed8013cbe2f595fa2f0ddb0e9e7180b89b9d81d02991556c14ade1dd2a9ac86844a76a3080daa41fb4d5debba8357959d2fe7ec52
-  data.tar.gz: f26c82b74d3cb344e65bc863a3718e152e4f107d7d709c64a7c47779c9ed60024e26c00709fd934177099b71cbdfdda37719f43e864a4aed907ca2676f31897f
+  metadata.gz: d0eae7105c8fe37a710ac56c9ba0c4df9b0f0663883d117123af6e778735c63117ca58d82e60e260e353aefcc9536e996848341a6537ca963d764b498dfba979
+  data.tar.gz: 72e217a7d2c9bed976d6801f333be3a97ebdedf1998b07fa4a4594c48256919dcd1cd4b48030582fc75bdd9e2e6d002dc29df931e217ab78cd97b87872f65c78

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.1.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/_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,62 @@
+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)
+    # 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
+
+  # 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]
+
+    # Perform bulk create in a transaction.
+    ActiveRecord::Base.transaction { self.create_from.create(create_data) }
+  end
+
+  def update_all
+    records = self.update_all!
+    serialized_records = self.bulk_serialize(records)
+    render(api: serialized_records)
+  end
+
+  # Perform the `update` call and return the collection of (possibly) updated records.
+  def update_all!
+    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] }
+    else
+      create_params = self.get_create_params
+      { create_params[pk] => create_params }
+    end
+
+    # Perform bulk update in a transaction.
+    ActiveRecord::Base.transaction { self.get_recordset.update(data.keys, data.values) }
+  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)
+    end
+
+    render(
+      api: { message: "Bulk destroy requires an array of primary keys as input." }, status: 400,
+    )
+  end
+
+  # Perform the `destroy!` call and return the destroyed (and frozen) record.
+  def destroy_all!
+    pk = self.class.model.primary_key
+    destroy_data = self.request.request_parameters[:_json]
+
+    # Perform bulk destroy in a transaction.
+    ActiveRecord::Base.transaction { self.get_recordset.where(pk => destroy_data).destroy_all }
+  end
+end

data/lib/rest_framework/controller/crud.rb

@@ -0,0 +1,66 @@
+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)
+      records = self.create_all!
+      return render(api: self.bulk_serialize(records))
+    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.get_index_records)
+  end
+
+  # Get records with both filtering and pagination applied.
+  def get_index_records
+    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

data/lib/rest_framework/controller/openapi.rb

@@ -0,0 +1,249 @@
+module RESTFramework::Controller
+  module ClassMethods
+    def openapi_response_content_types
+      @openapi_response_content_types ||= [
+        "text/html",
+        self.serialize_to_json ? "application/json" : nil,
+        self.serialize_to_xml ? "application/xml" : nil,
+      ].compact
+    end
+
+    def openapi_request_content_types
+      @openapi_request_content_types ||= [
+        "application/json",
+        "application/x-www-form-urlencoded",
+        "multipart/form-data",
+      ]
+    end
+
+    def openapi_paths(routes, tag)
+      resp_cts = self.openapi_response_content_types
+      req_cts = self.openapi_request_content_types
+      schema_name = self.openapi_schema_name if self.model
+
+      routes.group_by { |r| r[:concat_path] }.map { |concat_path, routes|
+        [
+          concat_path.gsub(/:([0-9A-Za-z_-]+)/, "{\\1}"),
+          routes.map { |route|
+            metadata = RESTFramework::ROUTE_METADATA[route[:path]] || {}
+            summary = metadata.delete(:label).presence || self.label_for(route[:action])
+            description = metadata.delete(:description).presence
+            extra_action = RESTFramework::EXTRA_ACTION_ROUTES.include?(route[:path])
+            error_response = { "$ref" => "#/components/responses/BadRequest" }
+            not_found_response = { "$ref" => "#/components/responses/NotFound" }
+            spec = { tags: [ tag ], summary: summary, description: description }.compact
+
+            # All routes should have a successful response.
+            success_code = if !extra_action
+              if route[:action] == "create"
+                201
+              elsif route[:action] == "destroy"
+                204
+              else
+                200
+              end
+            else
+              200
+            end
+            spec[:responses] = {
+              success_code => {
+                content: resp_cts.map { |ct|
+                  [
+                    ct,
+                    (self.model && !extra_action && route[:verb] != "OPTIONS") ? {
+                      schema: { "$ref" => "#/components/schemas/#{schema_name}" },
+                    } : {},
+                  ]
+                }.to_h,
+                description: "Success",
+              },
+            }
+
+            # Builtin POST, PUT, PATCH, and DELETE should have a 400 and 404 response.
+            if route[:verb].in?([ "POST", "PUT", "PATCH", "DELETE" ]) && !extra_action
+              spec[:responses][400] = error_response
+              spec[:responses][404] = not_found_response
+            end
+
+            # All POST, PUT, PATCH should have a request body.
+            if route[:verb].in?([ "POST", "PUT", "PATCH" ])
+              spec[:requestBody] ||= {
+                content: req_cts.map { |ct|
+                  [
+                    ct,
+                    (self.model && !extra_action) ? {
+                      schema: { "$ref" => "#/components/schemas/#{schema_name}" },
+                    } : {},
+                  ]
+                }.to_h,
+              }
+            end
+
+            # Add remaining metadata as an extension.
+            spec["x-rrf-metadata"] = metadata if metadata.present?
+
+            next route[:verb].downcase, spec
+          }.to_h.merge(
+            {
+              parameters: routes.first[:route].required_parts.map { |p|
+                {
+                  name: p,
+                  in: "path",
+                  required: true,
+                  schema: { type: "integer" },
+                }
+              },
+            },
+          ),
+        ]
+      }.to_h
+    end
+
+    def openapi_document(request, route_group_name, routes)
+      server = request.base_url + request.original_fullpath.gsub(/\?.*/, "")
+
+      {
+        openapi: "3.1.1",
+        info: {
+          title: self.get_title,
+          description: self.description,
+          version: self.version.to_s,
+        }.compact,
+        servers: [ { url: server } ],
+        paths: self.openapi_paths(routes, route_group_name),
+        tags: [ { name: route_group_name, description: self.description }.compact ],
+        components: {
+          schemas: {
+            "Error" => {
+              type: "object",
+              required: [ "message" ],
+              properties: {
+                message: { type: "string" },
+                errors: { type: "object" },
+                exception: { type: "string" },
+              },
+            },
+          }.merge(self.model ? { self.openapi_schema_name => self.openapi_schema } : {}),
+          responses: {
+            "BadRequest": {
+              description: "Bad Request",
+              content: self.openapi_response_content_types.map { |ct|
+                [
+                  ct,
+                  ct == "text/html" ? {} : { schema: { "$ref" => "#/components/schemas/Error" } },
+                ]
+              }.to_h,
+            },
+            "NotFound": {
+              description: "Not Found",
+              content: self.openapi_response_content_types.map { |ct|
+                [
+                  ct,
+                  ct == "text/html" ? {} : { schema: { "$ref" => "#/components/schemas/Error" } },
+                ]
+              }.to_h,
+            },
+          },
+        },
+      }.merge(self.model ? {
+        "x-rrf-primary_key" => self.model.primary_key,
+        "x-rrf-callbacks" => self._process_action_callbacks.as_json,
+
+        # While bulk update/destroy are obvious because they create new router endpoints, bulk
+        # create overloads the existing collection `POST` endpoint, so we add a special key to the
+        # OpenAPI metadata to indicate bulk create is supported.
+        "x-rrf-bulk-create": self.bulk,
+      } : {}).compact
+    end
+
+    # Only for model controllers.
+    def openapi_schema
+      return @openapi_schema if @openapi_schema
+
+      field_configuration = self.field_configuration
+      @openapi_schema = {
+        required: field_configuration.select { |_, cfg| cfg[:required] }.keys,
+        type: "object",
+        properties: field_configuration.map { |f, cfg|
+          v = { title: cfg[:label] }
+
+          if cfg[:kind] == "association"
+            v[:type] = cfg[:reflection].collection? ? "array" : "object"
+          elsif cfg[:kind] == "rich_text"
+            v[:type] = "string"
+            v[:"x-rrf-rich_text"] = true
+          elsif cfg[:kind] == "attachment"
+            v[:type] = "string"
+            v[:"x-rrf-attachment"] = cfg[:attachment_type]
+          else
+            v[:type] = cfg[:type]
+          end
+
+          v[:readOnly] = true if cfg[:read_only]
+          v[:default] = cfg[:default] if cfg.key?(:default)
+
+          if enum_variants = cfg[:enum_variants]
+            v[:enum] = enum_variants.keys
+            v[:"x-rrf-enum_variants"] = enum_variants
+          end
+
+          if validators = cfg[:validators]
+            v[:"x-rrf-validators"] = validators
+          end
+
+          v[:"x-rrf-kind"] = cfg[:kind] if cfg[:kind]
+
+          if 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,
+            }.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-id_field"] = cfg[:id_field]
+            v[:"x-rrf-nested_attributes_options"] = cfg[:nested_attributes_options]
+          end
+
+          next [ f, v ]
+        }.to_h,
+      }
+
+      @openapi_schema
+    end
+
+    # Only for model controllers.
+    def openapi_schema_name
+      @openapi_schema_name ||= self.name.chomp("Controller").gsub("::", ".")
+    end
+  end
+
+  def openapi_document
+    first, *rest = self.route_groups.to_a
+    document = self.class.openapi_document(request, *first)
+
+    if self.class.openapi_include_children
+      rest.each do |route_group_name, routes|
+        controller = "#{routes.first[:route].defaults[:controller]}_controller".camelize.constantize
+        child_document = controller.openapi_document(request, route_group_name, routes)
+
+        # Merge child paths and tags into the parent document.
+        document[:paths].merge!(child_document[:paths])
+        document[:tags] += child_document[:tags]
+
+        # If the child document has schemas, merge them into the parent document.
+        if schemas = child_document.dig(:components, :schemas)  # rubocop:disable Style/Next
+          document[:components] ||= {}
+          document[:components][:schemas] ||= {}
+          document[:components][:schemas].merge!(schemas)
+        end
+      end
+    end
+
+    document
+  end
+end