rest_framework 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ef7499f4d1e10af1f2520d3b9847dc7f711bd1c7f4377efe21bd5b60c0dd9a7
-  data.tar.gz: b15a9b0abee58e315fdc3a1157ca04d7051630821d3ed2ca691564966b5fefca
+  metadata.gz: 5a4c53fa557df9090c749745efce556214252b76e2115df09917970e9a9c8b5e
+  data.tar.gz: 5c33946ae697618f726532e9b45056f2e112d3f81f6efb5c9a37ab8d9b3b002e
 SHA512:
-  metadata.gz: fb586a083989a67f206d5b5d6c14eb546949569e384d3b44c870de5f49f610b5848d53da87e01234542705304dd7d49bcf6f0037f0b89331c7fa2a1b084422ce
-  data.tar.gz: fe4c960cda0d2a9ba43cb7d5b1cfa84963802800829323c26b350841bbd34290e68cbbc4f14a3138a1cb95a28aafff76b2d9a78a41772950e00ad80159c8f2f3
+  metadata.gz: ddfd6544b96284e871684d2f448e622631bd88631ea78ebe4170d2ff2fe4f1654901ef86a96584e3c5d0a2538bcef5d29f85152795aa689df58fc98cb05f7b3b
+  data.tar.gz: 1ab60515fcf543c0df574a6cf3913648736d19d559b1d9fbe55f891ce3e6926026357369580430ada33b6e294a081d8058b297bb3f146b3d17f4671b10683d55

data/README.md

@@ -3,6 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/rest_framework.svg)](https://badge.fury.io/rb/rest_framework)
 [![Build Status](https://travis-ci.org/gregschmit/rails-rest-framework.svg?branch=master)](https://travis-ci.org/gregschmit/rails-rest-framework)
 [![Coverage Status](https://coveralls.io/repos/github/gregschmit/rails-rest-framework/badge.svg?branch=master)](https://coveralls.io/github/gregschmit/rails-rest-framework?branch=master)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ba5df7706cb544d78555/maintainability)](https://codeclimate.com/github/gregschmit/rails-rest-framework/maintainability)
 
 A framework for DRY RESTful APIs in Ruby on Rails.
 

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/rest_framework/controller_mixins/base.rb

@@ -79,8 +79,12 @@ module RESTFramework::BaseControllerMixin
 
   protected
 
-  # Helper to get filtering backends with a sane default.
-  # @return [RESTFramework::BaseFilter]
+  # Helper to get the configured serializer class.
+  def get_serializer_class
+    return self.class.serializer_class
+  end
+
+  # Helper to get filtering backends, defaulting to no backends.
   def get_filter_backends
     return self.class.filter_backends || []
   end
@@ -95,16 +99,10 @@ module RESTFramework::BaseControllerMixin
     return data
   end
 
-  # Helper to get the configured serializer class.
-  # @return [RESTFramework::BaseSerializer]
-  def get_serializer_class
-    return self.class.serializer_class
-  end
-
   def record_invalid(e)
-    return api_response(
-      {message: "Record invalid.", exception: e, errors: e.record.errors}, status: 400
-    )
+    return api_response({
+      message: "Record invalid.", exception: e, errors: e.record&.errors
+    }, status: 400)
   end
 
   def record_not_found(e)
@@ -112,11 +110,15 @@ module RESTFramework::BaseControllerMixin
   end
 
   def record_not_saved(e)
-    return api_response({message: "Record not saved.", exception: e}, status: 406)
+    return api_response({
+      message: "Record not saved.", exception: e, errors: e.record&.errors
+    }, status: 406)
   end
 
   def record_not_destroyed(e)
-    return api_response({message: "Record not destroyed.", exception: e}, status: 406)
+    return api_response({
+      message: "Record not destroyed.", exception: e, errors: e.record&.errors
+    }, status: 406)
   end
 
   # Helper for showing routes under a controller action, used for the browsable API.
@@ -124,7 +126,9 @@ module RESTFramework::BaseControllerMixin
     begin
       formatter = ActionDispatch::Routing::ConsoleFormatter::Sheet
     rescue NameError
+      # :nocov:
       formatter = ActionDispatch::Routing::ConsoleFormatter
+      # :nocov:
     end
     return ActionDispatch::Routing::RoutesInspector.new(Rails.application.routes.routes).format(
       formatter.new

data/lib/rest_framework/controller_mixins/models.rb

@@ -20,6 +20,10 @@ module RESTFramework::BaseModelControllerMixin
         fields: nil,
         action_fields: nil,
 
+        # Attributes for finding records.
+        find_by_fields: nil,
+        find_by_query_param: 'find_by',
+
         # Attributes for create/update parameters.
         allowed_parameters: nil,
         allowed_action_parameters: nil,
@@ -35,7 +39,8 @@ module RESTFramework::BaseModelControllerMixin
         ordering_query_param: 'ordering',
 
         # Other misc attributes.
-        disable_creation_from_recordset: false,  # Option to disable `recordset.create` behavior.
+        create_from_recordset: true,  # Option for `recordset.create` vs `Model.create` behavior.
+        filter_recordset_before_find: true,  # Option to control if filtering is done before find.
       }.each do |a, default|
         unless base.respond_to?(a)
           base.class_attribute(a)
@@ -60,11 +65,6 @@ module RESTFramework::BaseModelControllerMixin
     return (action_config[action] if action) || self.class.send(generic_config_key)
   end
 
-  # Get a list of parameters allowed for the current action.
-  def get_allowed_parameters
-    return _get_specific_action_config(:allowed_action_parameters, :allowed_parameters)&.map(&:to_s)
-  end
-
   # Get a list of fields for the current action.
   def get_fields
     return (
@@ -74,14 +74,32 @@ module RESTFramework::BaseModelControllerMixin
     )
   end
 
+  # Get a list of find_by fields for the current action.
+  def get_find_by_fields
+    return self.class.find_by_fields&.map(&:to_s) || self.get_fields
+  end
+
+  # Get a list of find_by fields for the current action.
+  def get_filterset_fields
+    return self.class.filterset_fields&.map(&:to_s) || self.get_fields
+  end
+
+  # Get a list of ordering fields for the current action.
+  def get_ordering_fields
+    return self.class.ordering_fields&.map(&:to_s) || self.get_fields
+  end
+
+  # Get a list of parameters allowed for the current action.
+  def get_allowed_parameters
+    return _get_specific_action_config(:allowed_action_parameters, :allowed_parameters)&.map(&:to_s)
+  end
+
   # Helper to get the configured serializer class, or `NativeSerializer` as a default.
-  # @return [RESTFramework::BaseSerializer]
   def get_serializer_class
     return self.class.serializer_class || RESTFramework::NativeSerializer
   end
 
-  # Get the list of filtering backends to use.
-  # @return [RESTFramework::BaseFilter]
+  # Helper to get filtering backends, defaulting to using `ModelFilter` and `ModelOrderingFilter`.
   def get_filter_backends
     return self.class.filter_backends || [
       RESTFramework::ModelFilter, RESTFramework::ModelOrderingFilter
@@ -94,9 +112,7 @@ module RESTFramework::BaseModelControllerMixin
       fields = self.get_allowed_parameters || self.get_fields
 
       # Filter the request body.
-      body_params = request.request_parameters.select { |p|
-        fields.include?(p)
-      }
+      body_params = request.request_parameters.select { |p| fields.include?(p) }
 
       # Add query params in place of missing body params, if configured.
       if self.class.accept_generic_params_as_body_params
@@ -113,9 +129,7 @@ module RESTFramework::BaseModelControllerMixin
       end
 
       # Filter fields in exclude_body_fields.
-      (self.class.exclude_body_fields || []).each do |f|
-        body_params.delete(f.to_s)
-      end
+      (self.class.exclude_body_fields || []).each { |f| body_params.delete(f.to_s) }
 
       body_params
     end
@@ -123,14 +137,6 @@ module RESTFramework::BaseModelControllerMixin
   alias :get_create_params :get_body_params
   alias :get_update_params :get_body_params
 
-  # Get a record by the primary key from the (non-filtered) recordset.
-  def get_record
-    if pk = params[self.get_model.primary_key]
-      return self.get_recordset.find(pk)
-    end
-    return nil
-  end
-
   # Get the model for this controller.
   def get_model(from_get_recordset: false)
     return @model if instance_variable_defined?(:@model) && @model
@@ -164,6 +170,29 @@ module RESTFramework::BaseModelControllerMixin
 
     return nil
   end
+
+  # Get a single record by primary key or another column, if allowed.
+  def get_record
+    recordset = self.get_recordset
+    find_by_fields = self.get_find_by_fields
+    find_by_key = self.get_model.primary_key
+
+    # Find by another column if it's permitted.
+    if find_by_query_param && params[find_by_query_param].in?(find_by_fields)
+      find_by_key = params[find_by_query_param]
+    end
+
+    # Filter recordset, if configured.
+    if self.filter_recordset_before_find
+      recordset = self.get_filtered_data(recordset)
+    end
+
+    # Return the record.
+    if find_by_value = params[:id]  # Route key is always :id by Rails convention.
+      return self.get_recordset.find_by!(find_by_key => find_by_value)
+    end
+    return nil
+  end
 end
 
 
@@ -200,8 +229,8 @@ end
 # Mixin for creating records.
 module RESTFramework::CreateModelMixin
   def create
-    if self.get_recordset.respond_to?(:create!) && !self.disable_creation_from_recordset
-      # Create with any properties inherited from the recordset (like associations).
+    if self.get_recordset.respond_to?(:create!) && self.create_from_recordset
+      # Create with any properties inherited from the recordset.
       @record = self.get_recordset.create!(self.get_create_params)
     else
       # Otherwise, perform a "bare" create.

data/lib/rest_framework/errors.rb

@@ -2,6 +2,7 @@
 class RESTFramework::Error < StandardError
 end
 
+
 class RESTFramework::NilPassedToAPIResponseError < RESTFramework::Error
   def message
     return <<~MSG.split("\n").join(' ')
@@ -14,6 +15,7 @@ class RESTFramework::NilPassedToAPIResponseError < RESTFramework::Error
   end
 end
 
+
 class RESTFramework::UnserializableError < RESTFramework::Error
   def initialize(object)
     @object = object

data/lib/rest_framework/filters.rb

@@ -14,7 +14,7 @@ end
 class RESTFramework::ModelFilter < RESTFramework::BaseFilter
   # Filter params for keys allowed by the current action's filterset_fields/fields config.
   def _get_filter_params
-    fields = @controller.class.filterset_fields&.map(&:to_s) || @controller.send(:get_fields)
+    fields = @controller.send(:get_filterset_fields)
     return @controller.request.query_parameters.select { |p|
       fields.include?(p)
     }.to_h.symbolize_keys  # convert from HashWithIndifferentAccess to Hash w/keys
@@ -36,17 +36,25 @@ end
 class RESTFramework::ModelOrderingFilter < RESTFramework::BaseFilter
   # Convert ordering string to an ordering configuration.
   def _get_ordering
-    return nil unless @controller.class.ordering_query_param
+    return nil if @controller.class.ordering_query_param.blank?
+    ordering_fields = @controller.send(:get_ordering_fields)
 
     order_string = @controller.params[@controller.class.ordering_query_param]
     unless order_string.blank?
-      return order_string.split(',').map { |field|
+      ordering = {}
+      order_string.split(',').each do |field|
         if field[0] == '-'
-          [field[1..-1].to_sym, :desc]
+          column = field[1..-1]
+          direction = :desc
         else
-          [field.to_sym, :asc]
+          column = field
+          direction = :asc
         end
-      }.to_h
+        if column.in?(ordering_fields)
+          ordering[column.to_sym] = direction
+        end
+      end
+      return ordering
     end
 
     return nil

data/lib/rest_framework/generators/controller_generator.rb

@@ -1,26 +1,67 @@
 require 'rails/generators'
 
 
+# Some projects don't have the inflection "REST" as an acronym, so this is a helper class to prevent
+# this generator from being namespaced under `r_e_s_t_framework`.
+# :nocov:
+class RESTFrameworkCustomGeneratorControllerNamespace < String
+  def camelize
+    return "RESTFramework"
+  end
+end
+# :nocov:
+
+
 class RESTFramework::Generators::ControllerGenerator < Rails::Generators::Base
+  PATH_REGEX = /^\/*([a-z0-9_\/]*[a-z0-9_])(?:[\.a-z\/]*)$/
+
   desc <<~END
-    Description:
-      Stubs out a active_scaffolded controller. Pass the model name,
-      either CamelCased or under_scored.
-      The controller name is retrieved as a pluralized version of the model
-      name.
-      To create a controller within a module, specify the model name as a
-      path like 'parent_module/controller_name'.
-      This generates a controller class in app/controllers and invokes helper,
-      template engine and test framework generators.
-    Example:
-      `rails generate rest_framework:controller CreditCard`
-      Credit card controller with URLs like /credit_card/debit.
-          Controller:      app/controllers/credit_cards_controller.rb
-          Functional Test: test/functional/credit_cards_controller_test.rb
-          Helper:          app/helpers/credit_cards_helper.rb
+  Description:
+      Generates a new REST Framework controller.
+
+      Specify the controller as a path, including the module, if needed, like:
+      'parent_module/controller_name'.
+
+  Example:
+      `rails generate rest_framework:controller user_api/groups`
+
+      Generates a controller at `app/controllers/user_api/groups_controller.rb` named
+      `UserApi::GroupsController`.
   END
 
-  def create_controller_file
-    create_file "app/controllers/some_controller.rb", "# Add initialization content here"
+  argument :path, type: :string
+  class_option(
+    :parent_class,
+    type: :string,
+    default: 'ApplicationController',
+    desc: "Inheritance parent",
+  )
+  class_option(
+    :include_base,
+    type: :boolean,
+    default: false,
+    desc: "Include `BaseControllerMixin`, not `ModelControllerMixin`",
+  )
+
+  # 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")
+  end
+
+  def create_rest_controller_file
+    unless (path_match = PATH_REGEX.match(self.path))
+      raise StandardError.new("Path isn't correct.")
+    end
+
+    cleaned_path = path_match[1]
+    content = <<~END
+      class #{cleaned_path.camelize}Controller < #{options[:parent_class]}
+        include RESTFramework::#{
+          options[:include_base] ? "BaseControllerMixin" : "ModelControllerMixin"
+        }
+      end
+    END
+    create_file("app/controllers/#{path}_controller.rb", content)
   end
 end

data/lib/rest_framework/routers.rb

@@ -6,7 +6,7 @@ module ActionDispatch::Routing
     # Internal helper to take extra_actions hash and convert to a consistent format.
     protected def _parse_extra_actions(extra_actions)
       return (extra_actions || {}).map do |k,v|
-        kwargs = {}
+        kwargs = {action: k}
         path = k
 
         # Convert structure to path/methods/kwargs.
@@ -72,6 +72,16 @@ module ActionDispatch::Routing
       return controller
     end
 
+    # Interal interface for routing extra actions.
+    protected def _route_extra_actions(actions, &block)
+      actions.each do |action_config|
+        action_config[:methods].each do |m|
+          public_send(m, action_config[:path], **action_config[:kwargs])
+        end
+        yield if block_given?
+      end
+    end
+
     # Internal core implementation of the `rest_resource(s)` router, both singular and plural.
     # @param default_singular [Boolean] the default plurality of the resource if the plurality is
     #   not otherwise defined by the controller
@@ -89,9 +99,11 @@ module ActionDispatch::Routing
       kwargs[:controller] = name unless kwargs[:controller]
 
       # determine plural/singular resource
-      if kwargs.delete(:force_singular)
+      force_singular = kwargs.delete(:force_singular)
+      force_plural = kwargs.delete(:force_plural)
+      if force_singular
         singular = true
-      elsif kwargs.delete(:force_plural)
+      elsif force_plural
         singular = false
       elsif !controller_class.singleton_controller.nil?
         singular = controller_class.singleton_controller
@@ -100,28 +112,20 @@ module ActionDispatch::Routing
       end
       resource_method = singular ? :resource : :resources
 
-      # call either `resource` or `resources`, passing appropriate modifiers
+      # Call either `resource` or `resources`, passing appropriate modifiers.
       skip_undefined = kwargs.delete(:skip_undefined) || true
       skip = controller_class.get_skip_actions(skip_undefined: skip_undefined)
       public_send(resource_method, name, except: skip, **kwargs) do
         if controller_class.respond_to?(:extra_member_actions)
           member do
             actions = self._parse_extra_actions(controller_class.extra_member_actions)
-            actions.each do |action_config|
-              action_config[:methods].each do |m|
-                public_send(m, action_config[:path], **action_config[:kwargs])
-              end
-            end
+            _route_extra_actions(actions)
           end
         end
 
         collection do
           actions = self._parse_extra_actions(controller_class.extra_actions)
-          actions.each do |action_config|
-            action_config[:methods].each do |m|
-              public_send(m, action_config[:path], **action_config[:kwargs])
-            end
-          end
+          _route_extra_actions(actions)
         end
 
         yield if block_given?
@@ -145,6 +149,7 @@ module ActionDispatch::Routing
     # Route a controller without the default resourceful paths.
     def rest_route(name=nil, **kwargs, &block)
       controller = kwargs.delete(:controller) || name
+      route_root_to = kwargs.delete(:route_root_to)
       if controller.is_a?(Class)
         controller_class = controller
       else
@@ -157,42 +162,27 @@ module ActionDispatch::Routing
       # Route actions using the resourceful router, but skip all builtin actions.
       actions = self._parse_extra_actions(controller_class.extra_actions)
       public_send(:resource, name, only: [], **kwargs) do
-        actions.each do |action_config|
-          action_config[:methods].each do |m|
-            public_send(m, action_config[:path], **action_config[:kwargs])
-          end
-          yield if block_given?
+        # Route a root for this resource.
+        if route_root_to
+          get '', action: route_root_to
         end
+
+        _route_extra_actions(actions, &block)
       end
     end
 
     # Route a controller's `#root` to '/' in the current scope/namespace, along with other actions.
-    # @param name [Symbol] the snake_case name of the controller
     def rest_root(name=nil, **kwargs, &block)
       # By default, use RootController#root.
       root_action = kwargs.delete(:action) || :root
       controller = kwargs.delete(:controller) || name || :root
 
-      # Route the root.
-      get name.to_s, controller: controller, action: root_action
-
-      # Route any additional actions.
-      controller_class = self._get_controller_class(controller, pluralize: false)
-      actions = self._parse_extra_actions(controller_class.extra_actions)
-      actions.each do |action_config|
-        # Add :action unless kwargs defines it.
-        unless action_config[:kwargs].key?(:action)
-          action_config[:kwargs][:action] = action_config[:path]
-        end
+      # Remove path if name is nil (routing to the root of current namespace).
+      unless name
+        kwargs[:path] = ''
+      end
 
-        action_config[:methods].each do |m|
-          public_send(
-            m,
-            File.join(name.to_s, action_config[:path].to_s),
-            controller: controller,
-            **action_config[:kwargs],
-          )
-        end
+      return rest_route(controller, route_root_to: root_action, **kwargs) do
         yield if block_given?
       end
     end

data/lib/rest_framework/serializers.rb

@@ -3,6 +3,10 @@ class RESTFramework::BaseSerializer
     @object = object
     @controller = controller
   end
+
+  def serialize
+    raise NotImplementedError
+  end
 end
 
 
@@ -27,7 +31,9 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
     # Determine model either explicitly, or by inspecting @object or @controller.
     @model = model
     @model ||= @object.class if @object.is_a?(ActiveRecord::Base)
-    @model ||= @object[0].class if @many && @object[0].is_a?(ActiveRecord::Base)
+    @model ||= @object[0].class if (
+      @many && @object.is_a?(Enumerable) && @object.is_a?(ActiveRecord::Base)
+    )
     @model ||= @controller.send(:get_model) if @controller
   end
 
@@ -115,29 +121,21 @@ class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
 
   # Allow a serializer instance to be used as a hash directly in a nested serializer config.
   def [](key)
-    unless instance_variable_defined?(:@_nested_config)
-      @_nested_config = self.get_serializer_config
-    end
+    @_nested_config ||= self.get_serializer_config
     return @_nested_config[key]
   end
   def []=(key, value)
-    unless instance_variable_defined?(:@_nested_config)
-      @_nested_config = self.get_serializer_config
-    end
+    @_nested_config ||= self.get_serializer_config
     return @_nested_config[key] = value
   end
 
   # Allow a serializer class to be used as a hash directly in a nested serializer config.
   def self.[](key)
-    unless instance_variable_defined?(:@_nested_config)
-      @_nested_config = self.new.get_serializer_config
-    end
+    @_nested_config ||= self.new.get_serializer_config
     return @_nested_config[key]
   end
   def self.[]=(key, value)
-    unless instance_variable_defined?(:@_nested_config)
-      @_nested_config = self.new.get_serializer_config
-    end
+    @_nested_config ||= self.new.get_serializer_config
     return @_nested_config[key] = value
   end
 end

data/lib/rest_framework/version.rb

@@ -1,35 +1,32 @@
+# Do not use Rails-specific helper methods here (e.g., `blank?`) so the module can run standalone.
 module RESTFramework
   module Version
-    @_version = nil
+    VERSION_FILEPATH = File.expand_path("../../VERSION", __dir__)
 
     def self.get_version(skip_git: false)
-      # Return cached @_version, if available.
-      return @_version if @_version
-
       # First, attempt to get the version from git.
       unless skip_git
-        begin
-          version = `git describe 2>/dev/null`.strip
-          raise "blank version" if version.nil? || version.match(/^\w*$/)
-          # Check for local changes.
-          changes = `git status --porcelain 2>/dev/null`
-          version << '.localchanges' if changes.strip.length > 0
-          return version
-        rescue
-        end
+        version = `git describe --dirty --broken 2>/dev/null`&.strip
+        return version unless !version || version.empty?
       end
 
-      # Git failed, so try to find a VERSION_STAMP.
+      # Git failed or was skipped, so try to find a VERSION file.
       begin
-        version = File.read(File.expand_path("VERSION_STAMP", __dir__))
-        unless version.nil? || version.match(/^\w*$/)
-          return (@_version = version)  # cache VERSION_STAMP content
-        end
-      rescue
+        version = File.read(VERSION_FILEPATH)&.strip
+        return version unless !version || version.blank?
+      rescue SystemCallError
       end
 
-      # No VERSION_STAMP, so version is unknown.
-      return '0.unknown'
+      # No VERSION file, so version is unknown.
+      return 'unknown'
+    end
+
+    def self.stamp_version
+      File.write(VERSION_FILEPATH, RESTFramework::VERSION)
+    end
+
+    def self.unstamp_version
+      File.delete(VERSION_FILEPATH) if File.exist?(VERSION_FILEPATH)
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-28 00:00:00.000000000 Z
+date: 2021-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,12 +33,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- VERSION
 - app/views/layouts/rest_framework.html.erb
 - app/views/rest_framework/_head.html.erb
 - app/views/rest_framework/_routes.html.erb
 - app/views/rest_framework/default.html.erb
 - lib/rest_framework.rb
-- lib/rest_framework/VERSION_STAMP
 - lib/rest_framework/controller_mixins.rb
 - lib/rest_framework/controller_mixins/base.rb
 - lib/rest_framework/controller_mixins/models.rb

data/lib/rest_framework/VERSION_STAMP

@@ -1 +0,0 @@
-0.2.0