rest_framework 1.0.0.beta2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acc3d4ff5a9d7669942f21eb7f3ecec06417c83322be936e1b862b1346e9bb14
-  data.tar.gz: 53ddfa6b5a46338b174ec67742d6019d5d005231eb492b0af30ed7232a2d22ce
+  metadata.gz: 90b0053684520db23e669f2badfea90f4bc138106f79cfece16e17fc4ef449f0
+  data.tar.gz: 03a2d6ec4d1178fca154641ca6522df27592fa2b32b7024de76ceec827d23a8f
 SHA512:
-  metadata.gz: a93ccb739766ae11c9b0be6b52e60c698c72793cd109c1efbaf89eaac3f10b56a7bf11fd9e90b77ccc7c148aaa8436e51f73530f3ed3442f58ee93934fa37494
-  data.tar.gz: 616ebaac8b55a68a38fc8d29f6cedf764403990bc057bf9f6d8c92e672764a4f23189a3acca1e803b1d34df70731d28729744380cc90e9b7ec49f133c258d0de
+  metadata.gz: bb23fb3f071a17bbc1aaf2f8c5b8571e47a46a8faeeeb43f851dc64d60d422b7a12ba924200e5ec4124b5b75fe06f868a8ee623c97345753f7d1dc3d5244c16d
+  data.tar.gz: 2828fe0ca8cf5415c781f09da370dc1e92e5408b21e0d77650151aa1d9234e0a31e1e4fb8db2737166acdeba4166b79f42659086fdbd0dcf6bd80150cfb73f11

data/README.md

@@ -7,10 +7,12 @@
 
 A framework for DRY RESTful APIs in Ruby on Rails.
 
-**The Problem**: Building controllers for APIs usually involves writing a lot of redundant CRUD logic, and routing them can be obnoxious.
-Building and maintaining features like ordering, filtering, and pagination can be tedious.
+**The Problem**: Building controllers for APIs usually involves writing a lot of redundant CRUD
+logic, and routing them can be obnoxious. Building and maintaining features like ordering,
+filtering, and pagination can be tedious.
 
-**The Solution**: This framework implements browsable API responses, CRUD actions for your models, and features like ordering/filtering/pagination, so you can focus on building awesome APIs.
+**The Solution**: This framework implements browsable API responses, CRUD actions for your models,
+and features like ordering/filtering/pagination, so you can focus on your application logic.
 
 Website/Guide: [rails-rest-framework.com](https://rails-rest-framework.com)
 
@@ -38,7 +40,8 @@ bundle install
 
 This section provides some simple examples to quickly get you started using the framework.
 
-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:
+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/
@@ -51,7 +54,8 @@ controllers/
 
 ### Controller Mixins
 
-The root `ApiController` can include any common behavior you want to share across all your API controllers:
+The root `ApiController` can include any common behavior you want to share across all your API
+controllers:
 
 ```ruby
 class ApiController < ApplicationController
@@ -59,24 +63,21 @@ class ApiController < ApplicationController
 
   # 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)
+  self.page_size = 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:
+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
-    render_api(
-      {
+    render(
+      api: {
         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
@@ -88,7 +89,7 @@ class Api::RootController < ApiController
   end
 
   def test
-    render_api({message: "Hello, world!"})
+    render(api: {message: "Hello, world!"})
   end
 end
 ```
@@ -105,7 +106,7 @@ class Api::MoviesController < ApiController
   def first
     # Always use the bang method, since the framework will rescue `RecordNotFound` and return a
     # sensible error response.
-    render_api(self.get_records.first!)
+    render(api: self.get_records.first!)
   end
 
   def get_recordset
@@ -114,8 +115,8 @@ class Api::MoviesController < ApiController
 end
 ```
 
-When `fields` is nil, then it will default to all columns.
-The `fields` attribute can also be a hash to include or exclude fields rather than defining them manually:
+When `fields` is nil, then it will default to all columns. The `fields` attribute can also be a hash
+to include or exclude fields rather than defining them manually:
 
 ```ruby
 class Api::UsersController < ApiController
@@ -127,9 +128,10 @@ end
 
 ### Routing
 
-Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers.
-These routers add some features to the Rails builtin `resource`/`resources` routers, such as automatically routing extra actions defined on the controller.
-To route the root, use `rest_root`.
+Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful
+routers. These routers add some features to the Rails builtin `resource`/`resources` routers, such
+as automatically routing extra actions defined on the controller. To route the root, use
+`rest_root`.
 
 ```ruby
 Rails.application.routes.draw do
@@ -146,7 +148,13 @@ 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 `bin/setup` to install the appropriate gems and set things up.
+After you clone the repository, cd'ing into the directory should create a new gemset if you are
+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 (e.g., `rails test`, `rails console`). For development, use `bin/dev` to run the
+web server and the job queue, which serves the test app and coverage/brakeman reports:
 
-The top-level `bin/rails` proxies all Rails commands to the test project, so you can operate it via the usual commands (e.g., `rails test`, `rails server` and `rails console`). For development, use `foreman start` to run the web server and the job queue.
+- Test App: [http://127.0.0.1:3000](http://127.0.0.1:3000)
+- API: [http://127.0.0.1:3000/api](http://127.0.0.1:3000/api)
+- Reports: [http://127.0.0.1:3000/reports](http://127.0.0.1:3000/reports)

data/VERSION

@@ -1 +1 @@
-1.0.0.beta2
+1.0.0

data/lib/rest_framework/engine.rb

@@ -8,6 +8,12 @@ class RESTFramework::Engine < Rails::Engine
           *RESTFramework::EXTERNAL_UNSUMMARIZED_ASSETS.keys.map { |name| "rest_framework/#{name}" },
         ]
       end
+
+      if RESTFramework.config.register_api_renderer
+        ActionController::Renderers.add(:api) do |data, kwargs|
+          render_api(data, **kwargs)
+        end
+      end
     end
   end
 end

data/lib/rest_framework/errors/nil_passed_to_render_api_error.rb

@@ -1,6 +1,6 @@
 class RESTFramework::Errors::NilPassedToRenderAPIError < RESTFramework::Errors::BaseError
   def message
-    return <<~MSG.split("\n").join(" ")
+    <<~MSG.split("\n").join(" ")
       Payload of `nil` was passed to `render_api`; 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.,

data/lib/rest_framework/errors/unknown_model_error.rb

@@ -5,7 +5,7 @@ class RESTFramework::Errors::UnknownModelError < RESTFramework::Errors::BaseErro
   end
 
   def message
-    return <<~MSG.split("\n").join(" ")
+    <<~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

data/lib/rest_framework/filters/ordering_filter.rb

@@ -2,7 +2,7 @@
 class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilter
   # Get a list of ordering fields for the current action.
   def _get_fields
-    return @controller.class.ordering_fields&.map(&:to_s) || @controller.get_fields
+    @controller.class.ordering_fields&.map(&:to_s) || @controller.get_fields
   end
 
   # Convert ordering string to an ordering configuration.
@@ -34,7 +34,7 @@ class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilte
       return ordering
     end
 
-    return nil
+    nil
   end
 
   # Order data according to the request query parameters.
@@ -46,7 +46,7 @@ class RESTFramework::Filters::OrderingFilter < RESTFramework::Filters::BaseFilte
       return data.send(reorder ? :reorder : :order, ordering)
     end
 
-    return data
+    data
   end
 end
 

data/lib/rest_framework/filters/query_filter.rb

@@ -1,66 +1,134 @@
 # A simple filtering backend that supports filtering a recordset based on query parameters.
 class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
-  NIL_VALUES = ["nil", "null"].freeze
+  # Wrapper to indicate a type of query that must be negated with `where.not(...)`.
+  class Not
+    attr_reader :q
+
+    def initialize(q)
+      @q = q
+    end
+  end
+
+  PREDICATES = {
+    true: true,
+    false: false,
+    null: nil,
+    lt: ->(f, v) { { f => ...v } },
+    # `gt` must negate `lte` because Rails doesn't support `>` with endless ranges.
+    gt: ->(f, v) { Not.new({ f => ..v }) },
+    lte: ->(f, v) { { f => ..v } },
+    gte: ->(f, v) { { f => v.. } },
+    not: ->(f, v) { Not.new({ f => v }) },
+    cont: ->(f, v) { [ "#{f} LIKE ?", "%#{ActiveRecord::Base.sanitize_sql_like(v)}%" ] },
+    in: ->(f, v) {
+      if v.is_a?(Array)
+        { f => v.map { |v| v == "null" ? nil : v } }
+      elsif v.is_a?(String)
+        { f => v.split(",").map { |v| v == "null" ? nil : v } }
+      end
+    },
+  }.freeze
+  PREDICATES_REGEX = /^(.*)_(#{PREDICATES.keys.join("|")})$/
 
   # Get a list of filter fields for the current action.
   def _get_fields
     # Always return a list of strings; `@controller.get_fields` already does this.
-    return @controller.class.filter_fields&.map(&:to_s) || @controller.get_fields
+    @controller.class.filter_fields&.map(&:to_s) || @controller.get_fields
+  end
+
+  # Helper to find a variation of a field using a predicate. For example, there could be a field
+  # called `age`, and if `age_lt` it passed, we should return `["age", "lt"]`. Otherwise, if
+  # something like `age` is passed, then we should return `["age", nil]`.
+  def parse_predicate(field)
+    if match = PREDICATES_REGEX.match(field)
+      field = match[1]
+      predicate = match[2]
+    end
+
+    return field, predicate
   end
 
-  # Filter params for keys allowed by the current action's filter_fields/fields config.
-  def _get_filter_params
+  # Filter params for keys allowed by the current action's filter_fields/fields config and return a
+  # query config in the form of: `[base_query, pred_queries, includes]`.
+  def _get_query_config
     fields = self._get_fields
     includes = []
 
-    filter_params = @controller.request.query_parameters.select { |p, _|
-      # Remove any trailing `__in` from the field name.
-      field = p.chomp("__in")
+    # Predicate queries must be added to a separate list because multiple predicates can be used.
+    # E.g., `age_lt=10&age_gte=5` would transform to `[{age: ...10}, {age: 5..}]` to avoid conflict
+    # on the `age` key.
+    pred_queries = []
 
-      # Remove any associations whose sub-fields are not filterable.
-      if match = /(.*)\.(.*)/.match(field)
-        field, sub_field = match[1..2]
-        next false unless field.in?(fields)
+    base_query = @controller.request.query_parameters.map { |field, v|
+      # First, if field is a simple filterable field, return early.
+      if field.in?(fields)
+        next [ field, v ]
+      end
 
-        sub_fields = @controller.class.field_configuration[field][:sub_fields] || []
-        if sub_field.in?(sub_fields)
-          includes << field.to_sym
-          next true
-        end
+      # First, try to parse a simple predicate and check if it is filterable.
+      pred_field, predicate = self.parse_predicate(field)
+      if predicate && pred_field.in?(fields)
+        field = pred_field
+      else
+        # Last, try to parse a sub-field or sub-field w/predicate.
+        root_field, sub_field = field.split(".", 2)
+        _, pred_sub_field = pred_field.split(".", 2) if predicate
 
-        next false
-      end
+        # Check if sub-field or sub-field w/predicate is filterable.
+        if sub_field
+          next nil unless root_field.in?(fields)
 
-      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(",").map { |v| v.in?(NIL_VALUES) ? nil : v }
+          sub_fields = @controller.class.field_configuration[root_field][:sub_fields] || []
+          if sub_field.in?(sub_fields)
+            includes << root_field.to_sym
+            next [ field, v ]
+          elsif pred_sub_field && pred_sub_field.in?(sub_fields)
+            includes << root_field.to_sym
+            field = pred_field
+          else
+            next nil
+          end
+        else
+          next nil
+        end
       end
 
-      # Convert "nil" and "null" to nil.
-      v = nil if v.in?(NIL_VALUES)
+      # If we get here, we must have a predicate, either from a field or a sub-field. Transform the
+      # value into a query that can be used in the ActiveRecord `where` API.
+      cfg = PREDICATES[predicate.to_sym]
+      if cfg.is_a?(Proc)
+        pred_queries << cfg.call(field, v)
+      else
+        pred_queries << { field => cfg }
+      end
 
-      [p, v]
-    }.to_h.symbolize_keys
+      next nil
+    }.compact.to_h.symbolize_keys
 
-    return filter_params, includes
+    return base_query, pred_queries, includes
   end
 
   # Filter data according to the request query parameters.
   def filter_data(data)
-    filter_params, includes = self._get_filter_params
+    base_query, pred_queries, includes = self._get_query_config
 
-    if filter_params.any?
+    if base_query.any? || pred_queries.any?
       if includes.any?
         data = data.includes(*includes)
       end
 
-      return data.where(**filter_params)
+      data = data.where(**base_query) if base_query.any?
+
+      pred_queries.each do |q|
+        if q.is_a?(Not)
+          data = data.where.not(q.q)
+        else
+          data = data.where(q)
+        end
+      end
     end
 
-    return data
+    data
   end
 end
 

data/lib/rest_framework/filters/ransack_filter.rb

@@ -20,7 +20,7 @@ class RESTFramework::Filters::RansackFilter < RESTFramework::Filters::BaseFilter
       return data.ransack(q, @controller.class.ransack_options || {}).result(distinct: distinct)
     end
 
-    return data
+    data
   end
 end
 

data/lib/rest_framework/filters/search_filter.rb

@@ -6,7 +6,7 @@ class RESTFramework::Filters::SearchFilter < RESTFramework::Filters::BaseFilter
     end
 
     columns = @controller.class.get_model.column_names
-    return @controller.get_fields.select { |f|
+    @controller.get_fields.select { |f|
       f.in?(RESTFramework.config.search_columns) && f.in?(columns)
     }
   end
@@ -30,12 +30,12 @@ class RESTFramework::Filters::SearchFilter < RESTFramework::Filters::BaseFilter
           fields.map { |f|
             "CAST(#{f} AS #{data_type}) #{@controller.class.search_ilike ? "ILIKE" : "LIKE"} ?"
           }.join(" OR "),
-          *(["%#{search}%"] * fields.length),
+          *([ "%#{search}%" ] * fields.length),
         )
       end
     end
 
-    return data
+    data
   end
 end
 

data/lib/rest_framework/generators/controller_generator.rb

@@ -5,7 +5,7 @@ require "rails/generators"
 # :nocov:
 class RESTFrameworkCustomGeneratorControllerNamespace < String
   def camelize
-    return "RESTFramework"
+    "RESTFramework"
   end
 end
 # :nocov:
@@ -41,7 +41,7 @@ class RESTFramework::Generators::ControllerGenerator < Rails::Generators::Base
   # Some projects may not have the inflection "REST" as an acronym, which changes this generator to
   # be namespaced in `r_e_s_t_framework`, which is weird.
   def self.namespace
-    return RESTFrameworkCustomGeneratorControllerNamespace.new("rest_framework:controller")
+    RESTFrameworkCustomGeneratorControllerNamespace.new("rest_framework:controller")
   end
 
   def create_rest_controller_file