rest_framework 0.9.7 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a9201bc66da6f1038a27aad8e0754d3b14973c20ca5bb3486b545c081e1cf31
-  data.tar.gz: af160d2b5f66a1d2ab4b40dcd366e5f10d46e5b4f075ac01926cfbcbc03a5c62
+  metadata.gz: 4b816fbe24e240ce66a74b2a3c18fd0a75a449c878c9a0126e4c14ddbaafe5b8
+  data.tar.gz: 383836204fd789afd4270794e0d7da57e05b8b8e8f537dd19c7fa2bf6ff1e2eb
 SHA512:
-  metadata.gz: 756aa93e81e2cd240a6d383df774c8003a4063e514bd19acce8857a36ae6844c4ee3dddafdd2c9a246ab4f213f9c9b01bd52bcf2758d84b6ec09b59f73ae3257
-  data.tar.gz: e7b9e1e1730604c3702e9e1c8b744c87ac6d474db8cb70f32457467ddbc25817bc94404b26560c4b19f3ac0ecdd4704ff9393cbd7a88216052ee13071a97a23a
+  metadata.gz: 0a845ce1b30eab8ad874e432268092e5e9117200a320d9446a3e333a88d202257987767fd6b9bad2b7b0768c52e564e1a0beede15408027c7c48c8b91beffcd4
+  data.tar.gz: a1ae6ccfd603c7759d5db717249790a7b124bc06b39ff3f88eba16527874ec8788e4fdcb149c4e96ca0a6a8dae1ea3361519acfb830e1dfda6bc5ea2b521177b

data/.yardopts

@@ -0,0 +1,5 @@
+--private
+--protected
+-
+LICENSE
+README.md

data/README.md

@@ -27,87 +27,122 @@ YARD Docs: [rubydoc.info/gems/rest_framework](https://rubydoc.info/gems/rest_fra
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'rest_framework'
+gem "rest_framework"
 ```
 
-And then execute:
+And then run:
 
 ```shell
-$ bundle install
+bundle install
 ```
 
-Or install it yourself with:
+## Quick Usage Tutorial
 
-```shell
-$ gem install rest_framework
-```
+This section provides some simple examples to quickly get you started using the framework.
 
-## Quick Usage Tutorial
+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:
+
+```text
+controllers/
+├─ api_controller.rb
+└─ api/
+   ├─ root_controller.rb
+   ├─ movies_controller.rb
+   └─ users_controller.rb
+```
 
 ### Controller Mixins
 
-To transform a controller into a RESTful controller, you can either include `BaseControllerMixin`,
-`ReadOnlyModelControllerMixin`, or `ModelControllerMixin`. `BaseControllerMixin` provides a `root`
-action and a simple interface for routing arbitrary additional actions:
+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
+
+  # The page_size attribute doesn't exist on the `BaseControllerMixin`, but for child controllers
+  # that include the `ModelControllerMixin`, they will inherit this attribute and will not overwrite
+  # it.
+  class_attribute(:page_size, default: 30)
+end
+```
+
+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:
+
+```ruby
+class Api::RootController < ApiController
   self.extra_actions = {test: :get}
 
+  def root
+    return api_response(
+      {
+        message: "Welcome to the API.",
+        how_to_authenticate: <<~END.lines.map(&:strip).join(" "),
+          You can use this API with your normal login session. Otherwise, you can insert your API
+          key into a Bearer Authorization header, or into the URL parameters with the name
+          `api_key`.
+        END
+      },
+    )
+  end
+
   def test
-    render api_response({message: "Test successful!"})
+    return api_response({message: "Hello, world!"})
   end
 end
 ```
 
-`ModelControllerMixin` assists with providing the standard model CRUD for your controller.
+And here is an example of a resource controller:
 
 ```ruby
 class Api::MoviesController < ApiController
   include RESTFramework::ModelControllerMixin
 
-  self.recordset = Movie.where(enabled: true)
+  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
+    # sensible error response.
+    return api_response(self.get_records.first!)
+  end
+
+  def get_recordset
+    return Movie.where(enabled: true)
+  end
 end
 ```
 
-`ReadOnlyModelControllerMixin` only enables list/show actions, but since we're naming this
-controller in a way that doesn't make the model obvious, we can set that explicitly:
+You can also configure a resource's fields dynamically using `include` and `exclude` keys:
 
 ```ruby
-class Api::ReadOnlyMoviesController < ApiController
-  include RESTFramework::ReadOnlyModelControllerMixin
+class Api::UsersController < ApiController
+  include RESTFramework::ModelControllerMixin
 
-  self.model = Movie
+  self.fields = {include: [:calculated_popularity], exclude: [:impersonation_token]}
 end
 ```
 
-Note that you can also override the `get_recordset` instance method to override the API behavior
-dynamically per-request.
-
 ### Routing
 
 You can use Rails' `resource`/`resources` routers to route your API, however if you want
 `extra_actions` / `extra_member_actions` to be routed automatically, then you can use `rest_route`
-for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers. You can
-also use `rest_root` to route the root of your API:
+for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers. To route
+the root, use `rest_root`.
 
 ```ruby
 Rails.application.routes.draw do
-  rest_root :api  # will find `api_controller` and route the `root` action to '/api'
-  namespace :api do
-    rest_resources :movies
-    rest_resources :users
-  end
-end
-```
-
-Or if you want the API root to be routed to `Api::RootController#root`:
+  # If you wanted to route actions from the `ApiController`, then you would use this:
+  # rest_root :api  # Will find `api_controller` and route the `root` action to '/api'.
 
-```ruby
-Rails.application.routes.draw do
   namespace :api do
-    rest_root  # will route `Api::RootController#root` to '/' in this namespace ('/api')
+    rest_root  # Will route `Api::RootController#root` to '/' in this namespace ('/api').
     rest_resources :movies
     rest_resources :users
   end
@@ -117,14 +152,7 @@ end
 ## Development/Testing
 
 After you clone the repository, cd'ing into the directory should create a new gemset if you are
-using RVM. Then run `bundle install` to install the appropriate gems.
-
-To run the test suite:
-
-```shell
-$ rails test
-```
+using RVM. Then run `bin/setup` to install the appropriate gems and set things up.
 
 The top-level `bin/rails` proxies all Rails commands to the test project, so you can operate it via
-the usual commands. Ensure you run `rails db:setup` before running `rails server` or
-`rails console`.
+the usual commands (e.g., `rails test`, `rails server` and `rails console`).

data/VERSION

@@ -1 +1 @@
-0.9.7
+0.9.9

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

@@ -1,5 +1,5 @@
 <!doctype html>
-<html class="rrf-mode">
+<html lang="en" class="rrf-mode">
   <head>
     <title><%= @title %></title>
 

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

@@ -29,7 +29,6 @@
   h1, h2, h3, h4, h5, h6 {
     color: var(--rrf-red);
     font-weight: normal;
-    margin-bottom: 0;
   }
   html[data-bs-theme="dark"] h1,
   html[data-bs-theme="dark"] h2,
@@ -290,7 +289,7 @@
 
   // Convert plain-text links to anchor tag links.
   function rrfLinkify(text) {
-    return text.replace(/(https?:\/\/[^\s<>"]+)/g, "<a href=\"$1\" target=\"_blank\">$1</a>")
+    return text.replace(/(https?:\/\/[^\s<>"]+)/g, "<a href=\"$1\">$1</a>")
   }
 
   // Replace the document when doing form submission (mainly to support PUT/PATCH/DELETE).

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

@@ -1,7 +1,7 @@
 <div class="row">
   <div>
     <%= render partial: "rest_framework/heading/actions" if @route_groups.present? %>
-    <h1 class="m-0"><%= @heading_title || @title %></h1>
+    <h1 style="margin: 0"><%= @heading_title || @title %></h1>
     <% if @description.present? %>
       <br><br><p style="display: inline-block; margin-bottom: 0"><%= @description %></p>
     <% end %>

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

@@ -17,7 +17,7 @@
       <% end %>
     </ul>
   </div>
-  <div class="tab-content pt-2">
+  <div class="tab-content">
     <div class="tab-pane fade show active" id="tab-json" role="tabpanel">
       <% if @json_payload.present? %>
         <div><pre class="rrf-copy"><code class="language-json"><%=

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

@@ -1,16 +1,14 @@
 <div class="row">
   <div>
-    <pre><code><%
+    <pre class="mb-2"><code class="language-plaintext"><%
       concat request.request_method
       if request.method != request.request_method
         concat " (via #{request.method})"
       end
       concat " #{request.path}"
     %></code></pre>
-    <pre><code><%
+    <pre><code class="language-plaintext"><%
       concat "HTTP #{response.status} #{response.message}"
-      concat "\n"
-      concat "Content-Type: #{response.content_type}"
     %></code></pre>
   </div>
 </div>

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

@@ -34,7 +34,7 @@
       <% end %>
     </ul>
   </div>
-  <div class="tab-content pt-2">
+  <div class="tab-content">
     <div class="tab-pane fade show active" id="tab-routes" role="tabpanel">
       <%= render partial: "rest_framework/routes_and_forms/routes" %>
     </div>
@@ -49,4 +49,4 @@
       </div>
     <% end %>
   </div>
-</div>
+</div>

data/lib/rest_framework/errors/base_error.rb

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

data/lib/rest_framework/errors/nil_passed_to_api_response_error.rb

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

data/lib/rest_framework/errors/unknown_model_error.rb

@@ -0,0 +1,18 @@
+class RESTFramework::Errors::UnknownModelError < RESTFramework::Errors::BaseError
+  def initialize(controller_class)
+    super()
+    @controller_class = controller_class
+  end
+
+  def message
+    return <<~MSG.split("\n").join(" ")
+      The model class for `#{@controller_class}` could not be determined. Any controller that
+      includes `RESTFramework::BaseModelControllerMixin` (directly or indirectly) must either set
+      the `model` attribute on the controller, or the model must be deducible from the controller
+      name (e.g., `UsersController` could resolve to the `User` model).
+    MSG
+  end
+end
+
+# Alias for convenience.
+RESTFramework::UnknownModelError = RESTFramework::Errors::UnknownModelError

data/lib/rest_framework/errors.rb

@@ -1,31 +1,7 @@
-# Top-level class for all REST Framework errors.
-class RESTFramework::Error < StandardError
+module RESTFramework::Errors
 end
 
-class RESTFramework::NilPassedToAPIResponseError < RESTFramework::Error
-  def message
-    return <<~MSG.split("\n").join(" ")
-      Payload of `nil` was passed to `api_response`; this is unsupported. If you want a blank
-      response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
-      (or similar Active Record method) not finding a record, you should use the bang version (e.g.,
-      `find_by!`) to raise `ActiveRecord::RecordNotFound`, which the REST controller will catch and
-      return an appropriate error response.
-    MSG
-  end
-end
-
-class RESTFramework::UnknownModelError < RESTFramework::Error
-  def initialize(controller_class)
-    super()
-    @controller_class = controller_class
-  end
+require_relative "errors/base_error"
 
-  def message
-    return <<~MSG.split("\n").join(" ")
-      The model class for `#{@controller_class}` could not be determined. Any controller that
-      includes `RESTFramework::BaseModelControllerMixin` (directly or indirectly) must either set
-      the `model` attribute on the controller, or the model must be deducible from the controller
-      name (e.g., `UsersController` could resolve to the `User` model).
-    MSG
-  end
-end
+require_relative "errors/nil_passed_to_api_response_error"
+require_relative "errors/unknown_model_error"

data/lib/rest_framework/filters/{base.rb → base_filter.rb}

@@ -1,4 +1,4 @@
-class RESTFramework::BaseFilter
+class RESTFramework::Filters::BaseFilter
   def initialize(controller:)
     @controller = controller
   end
@@ -7,3 +7,6 @@ class RESTFramework::BaseFilter
     raise NotImplementedError
   end
 end
+
+# Alias for convenience.
+RESTFramework::BaseFilter = RESTFramework::Filters::BaseFilter

data/lib/rest_framework/filters/{model_ordering.rb → model_ordering_filter.rb}

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

data/lib/rest_framework/filters/{model_query.rb → model_query_filter.rb}

@@ -1,5 +1,5 @@
 # A simple filtering backend that supports filtering a recordset based on query parameters.
-class RESTFramework::ModelQueryFilter < RESTFramework::BaseFilter
+class RESTFramework::Filters::ModelQueryFilter < RESTFramework::Filters::BaseFilter
   # Get a list of filterset fields for the current action.
   def _get_fields
     # Always return a list of strings; `@controller.get_fields` already does this.
@@ -49,3 +49,6 @@ class RESTFramework::ModelQueryFilter < RESTFramework::BaseFilter
     return data
   end
 end
+
+# Alias for convenience.
+RESTFramework::ModelQueryFilter = RESTFramework::Filters::ModelQueryFilter

data/lib/rest_framework/filters/{model_search.rb → model_search_filter.rb}

@@ -1,5 +1,5 @@
 # Multi-field text searching on models.
-class RESTFramework::ModelSearchFilter < RESTFramework::BaseFilter
+class RESTFramework::Filters::ModelSearchFilter < RESTFramework::Filters::BaseFilter
   # Get a list of search fields for the current action.
   def _get_fields
     if search_fields = @controller.search_fields
@@ -39,3 +39,6 @@ class RESTFramework::ModelSearchFilter < RESTFramework::BaseFilter
     return data
   end
 end
+
+# Alias for convenience.
+RESTFramework::ModelSearchFilter = RESTFramework::Filters::ModelSearchFilter

data/lib/rest_framework/filters/{ransack.rb → ransack_filter.rb}

@@ -1,5 +1,5 @@
 # Adapter for the `ransack` gem.
-class RESTFramework::RansackFilter < RESTFramework::BaseFilter
+class RESTFramework::Filters::RansackFilter < RESTFramework::Filters::BaseFilter
   # Filter data according to the request query parameters.
   def get_filtered_data(data)
     q = @controller.request.query_parameters[@controller.ransack_query_param]
@@ -23,3 +23,6 @@ class RESTFramework::RansackFilter < RESTFramework::BaseFilter
     return data
   end
 end
+
+# Alias for convenience.
+RESTFramework::RansackFilter = RESTFramework::Filters::RansackFilter

data/lib/rest_framework/filters.rb

@@ -1,9 +1,9 @@
 module RESTFramework::Filters
 end
 
-require_relative "filters/base"
+require_relative "filters/base_filter"
 
-require_relative "filters/model_ordering"
-require_relative "filters/model_query"
-require_relative "filters/model_search"
-require_relative "filters/ransack"
+require_relative "filters/model_ordering_filter"
+require_relative "filters/model_query_filter"
+require_relative "filters/model_search_filter"
+require_relative "filters/ransack_filter"

data/lib/rest_framework/{controller_mixins/base.rb → mixins/base_controller_mixin.rb}

@@ -1,11 +1,7 @@
-require_relative "../errors"
-require_relative "../serializers"
-require_relative "../utils"
-
 # This module provides the common functionality for any controller mixins, a `root` action, and
 # the ability to route arbitrary actions with `extra_actions`. This is also where `api_response`
 # is defined.
-module RESTFramework::BaseControllerMixin
+module RESTFramework::Mixins::BaseControllerMixin
   RRF_BASE_CONFIG = {
     extra_actions: nil,
     extra_member_actions: nil,
@@ -348,3 +344,6 @@ module RESTFramework::BaseControllerMixin
     return api_response(self.get_options_metadata)
   end
 end
+
+# Alias for convenience.
+RESTFramework::BaseControllerMixin = RESTFramework::Mixins::BaseControllerMixin

data/lib/rest_framework/{controller_mixins/bulk.rb → mixins/bulk_model_controller_mixin.rb}

@@ -1,8 +1,8 @@
-require_relative "models"
+require_relative "model_controller_mixin"
 
 # Mixin for creating records in bulk. This is unique compared to update/destroy because we overload
 # the existing `create` action to support bulk creation.
-module RESTFramework::BulkCreateModelMixin
+module RESTFramework::Mixins::BulkCreateModelMixin
   # 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 options
   # metadata to indicate bulk create is supported.
@@ -32,7 +32,7 @@ module RESTFramework::BulkCreateModelMixin
 end
 
 # Mixin for updating records in bulk.
-module RESTFramework::BulkUpdateModelMixin
+module RESTFramework::Mixins::BulkUpdateModelMixin
   def update_all
     records = self.update_all!
     serialized_records = self.bulk_serialize(records)
@@ -57,7 +57,7 @@ module RESTFramework::BulkUpdateModelMixin
 end
 
 # Mixin for destroying records in bulk.
-module RESTFramework::BulkDestroyModelMixin
+module RESTFramework::Mixins::BulkDestroyModelMixin
   def destroy_all
     if params[:_json].is_a?(Array)
       records = self.destroy_all!
@@ -84,14 +84,20 @@ module RESTFramework::BulkDestroyModelMixin
 end
 
 # Mixin that includes all the CRUD bulk mixins.
-module RESTFramework::BulkModelControllerMixin
-  include RESTFramework::ModelControllerMixin
+module RESTFramework::Mixins::BulkModelControllerMixin
+  include RESTFramework::Mixins::ModelControllerMixin
 
-  include RESTFramework::BulkCreateModelMixin
-  include RESTFramework::BulkUpdateModelMixin
-  include RESTFramework::BulkDestroyModelMixin
+  include RESTFramework::Mixins::BulkCreateModelMixin
+  include RESTFramework::Mixins::BulkUpdateModelMixin
+  include RESTFramework::Mixins::BulkDestroyModelMixin
 
   def self.included(base)
-    RESTFramework::ModelControllerMixin.included(base)
+    RESTFramework::Mixins::ModelControllerMixin.included(base)
   end
 end
+
+# Aliases for convenience.
+RESTFramework::BulkCreateModelMixin = RESTFramework::Mixins::BulkCreateModelMixin
+RESTFramework::BulkUpdateModelMixin = RESTFramework::Mixins::BulkUpdateModelMixin
+RESTFramework::BulkDestroyModelMixin = RESTFramework::Mixins::BulkDestroyModelMixin
+RESTFramework::BulkModelControllerMixin = RESTFramework::Mixins::BulkModelControllerMixin