rest_framework 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c2eb85612656cf6f1b3d34b97deb06ad01aa07459012b4254e543fc0bd5507
-  data.tar.gz: 76f44db8c396cfe5bb539faebb6f6031276d7133327b733cab4a645922176d95
+  metadata.gz: 825e7e7ac0e9c8ae57250288a54dc3ef6510665ce3d4fee23245c559aa8e8233
+  data.tar.gz: 2211c303d14708ef94a4cb35d6e3b25bf78b3b08645f2990ca5448354d8dd64e
 SHA512:
-  metadata.gz: 246bd5c3972c212c1d6fcf600da1c894fe05acaeda8596d432b6b360e265520b3e54f3b4842998c26868464c29bd79f3c164f51104145163c0a63ba9e94f06fb
-  data.tar.gz: 52af9985b986a167f70cd8def492a3ff2c7d61bafd48e120f49934cc3827f76a1e6dbc5c02651df6bba7fdd622be058f945534415d6cb74e3537c56f9c18c0e2
+  metadata.gz: 0ee2cf406f2b8d77d9ea63650b080d037a759143e0a3e19846585d493a386a4647db0fe59188aa0fd887257a18087aaca82b80d99dee962af1dfdb7eca66a07c
+  data.tar.gz: 6248caea5ad7f5a37a55f7da6aae55c70dc284b9f04d046fc6149a13dff4ae34410106c97f54274f59a8353c79fe97073b7dcba51d65d9c94eb0f9cff1a205ac

data/README.md

@@ -116,18 +116,5 @@ To run the full test suite:
 $ rake test
 ```
 
-To run unit tests:
-
-```shell
-$ rake test:unit
-```
-
-To run integration tests:
-
-```shell
-$ rake test:integration
-```
-
-To interact with the integration app, you can `cd test/integration` and operate it via the normal
-Rails interfaces. Ensure you run `rake db:schema:load` before running `rails server` or
-`rails console`.
+To interact with the test app, `cd test` and operate it via the normal Rails interfaces. Ensure you
+run `rake db:schema:load` before running `rails server` or `rails console`.

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

@@ -30,14 +30,14 @@
                 <% if @json_payload %>
                   <li class="nav-item">
                     <a class="nav-link active" href="#tab-json" data-toggle="tab" role="tab">
-                      JSON
+                      .json
                     </a>
                   </li>
                 <% end %>
                 <% if @xml_payload %>
                   <li class="nav-item">
                     <a class="nav-link" href="#tab-xml" data-toggle="tab" role="tab">
-                      XML
+                      .xml
                     </a>
                   </li>
                 <% end %>

data/lib/rest_framework.rb

@@ -3,5 +3,8 @@ end
 
 require_relative "rest_framework/controller_mixins"
 require_relative "rest_framework/engine"
+require_relative "rest_framework/filters"
+require_relative "rest_framework/paginators"
 require_relative "rest_framework/routers"
+require_relative "rest_framework/serializers"
 require_relative "rest_framework/version"

data/lib/rest_framework/VERSION_STAMP

@@ -1 +1 @@
-0.0.15
+0.0.16

data/lib/rest_framework/controller_mixins/base.rb

@@ -1,3 +1,5 @@
+require_relative '../serializers'
+
 module RESTFramework
 
   # This module provides the common functionality for any controller mixins, a `root` action, and
@@ -28,12 +30,37 @@ module RESTFramework
     def self.included(base)
       if base.is_a? Class
         base.extend ClassMethods
-        base.class_attribute(*[
-          :singleton_controller,
-          :extra_actions,
-          :skip_actions,
-          :paginator_class,
-        ])
+
+        # Add class attributes (with defaults) unless they already exist.
+        {
+          extra_actions: nil,
+          extra_member_actions: nil,
+          filter_backends: nil,
+          native_serializer_config: nil,
+          native_serializer_action_config: nil,
+          paginator_class: nil,
+          page_size: nil,
+          page_query_param: 'page',
+          page_size_query_param: 'page_size',
+          max_page_size: nil,
+          serializer_class: nil,
+          singleton_controller: nil,
+          skip_actions: nil,
+        }.each do |a, default|
+          unless base.respond_to?(a)
+            base.class_attribute(a)
+
+            # Set default manually so we can still support Rails 4. Maybe later we can use the
+            # default parameter on `class_attribute`.
+            base.send(:"#{a}=", default)
+          end
+        end
+
+        # Alias `extra_actions` to `extra_collection_actions`.
+        unless base.respond_to?(:extra_collection_actions)
+          base.alias_method(:extra_collection_actions, :extra_actions)
+          base.alias_method(:extra_collection_actions=, :extra_actions=)
+        end
 
         # skip csrf since this is an API
         base.skip_before_action(:verify_authenticity_token) rescue nil
@@ -48,6 +75,45 @@ module RESTFramework
 
     protected
 
+    # Helper to get filtering backends with a sane default.
+    def get_filter_backends
+      if self.class.filter_backends
+        return self.class.filter_backends
+      end
+
+      # By default, return nil.
+      return nil
+    end
+
+    # Filter the recordset over all configured filter backends.
+    def get_filtered_data(data)
+      (self.get_filter_backends || []).each do |filter_class|
+        filter = filter_class.new(controller: self)
+        data = filter.get_filtered_data(data)
+      end
+
+      return data
+    end
+
+    # Helper to get the configured serializer class, or `NativeModelSerializer` as a default.
+    def get_serializer_class
+      return self.class.serializer_class || NativeModelSerializer
+    end
+
+    # Get a native serializer config for the current action.
+    def get_native_serializer_config
+      action_serializer_config = self.class.native_serializer_action_config || {}
+      action = self.action_name.to_sym
+
+      # Handle case where :index action is not defined.
+      if action == :index && !action_serializer_config.key?(:index)
+        # Default is :show if `singleton_controller`, otherwise :list.
+        action = self.class.singleton_controller ? :show : :list
+      end
+
+      return (action_serializer_config[action] if action) || self.class.native_serializer_config
+    end
+
     def record_invalid(e)
       return api_response(
         {message: "Record invalid.", exception: e, errors: e.record.errors}, status: 400
@@ -66,6 +132,7 @@ module RESTFramework
       return api_response({message: "Record not destroyed.", exception: e}, status: 406)
     end
 
+    # Helper for showing routes under a controller action, used for the browsable API.
     def _get_routes
       begin
         formatter = ActionDispatch::Routing::ConsoleFormatter::Sheet
@@ -124,8 +191,8 @@ module RESTFramework
           rescue ActionView::MissingTemplate  # fallback to rest_framework layout/view
             kwargs[:layout] = "rest_framework"
             kwargs[:template] = "rest_framework/default"
+            render(**kwargs)
           end
-          render(**kwargs)
         }
       end
     end

data/lib/rest_framework/controller_mixins/models.rb

@@ -1,5 +1,5 @@
 require_relative 'base'
-require_relative '../serializers'
+require_relative '../filters'
 
 module RESTFramework
 
@@ -8,61 +8,71 @@ module RESTFramework
     def self.included(base)
       if base.is_a? Class
         BaseControllerMixin.included(base)
-        base.class_attribute(*[
-          :model,
-          :recordset,
-          :fields,
-          :action_fields,
-          :native_serializer_config,
-          :native_serializer_action_config,
-          :filterset_fields,
-          :allowed_parameters,
-          :allowed_action_parameters,
-          :serializer_class,
-          :extra_member_actions,
-          :disable_creation_from_recordset,
-        ])
-        base.alias_method(:extra_collection_actions=, :extra_actions=)
+
+        # Add class attributes (with defaults) unless they already exist.
+        {
+          # Core attributes related to models.
+          model: nil,
+          recordset: nil,
+
+          # Attributes for create/update parameters.
+          allowed_parameters: nil,
+          allowed_action_parameters: nil,
+
+          # Attributes for configuring record fields.
+          fields: nil,
+          action_fields: nil,
+
+          # Attributes for default model filtering (and ordering).
+          filterset_fields: nil,
+          ordering_fields: nil,
+          ordering_query_param: 'ordering',
+
+          # Other misc attributes.
+          disable_creation_from_recordset: nil,  # Option to disable `recordset.create` behavior.
+        }.each do |a, default|
+          unless base.respond_to?(a)
+            base.class_attribute(a)
+
+            # Set default manually so we can still support Rails 4. Maybe later we can use the
+            # default parameter on `class_attribute`.
+            base.send(:"#{a}=", default)
+          end
+        end
       end
     end
 
     protected
 
-    def get_serializer_class
-      return self.class.serializer_class || NativeModelSerializer
-    end
-
-    # Get a list of fields for the current action.
-    def get_fields
-      action_fields = self.class.action_fields || {}
+    # Get a list of parameters allowed for the current action.
+    def get_allowed_parameters
+      allowed_action_parameters = self.class.allowed_action_parameters || {}
       action = self.action_name.to_sym
 
-      # index action should use :list fields if :index is not provided
-      action = :list if action == :index && !action_fields.key?(:index)
+      # index action should use :list allowed parameters if :index is not provided
+      action = :list if action == :index && !allowed_action_parameters.key?(:index)
 
-      return (action_fields[action] if action) || self.class.fields || []
+      return (allowed_action_parameters[action] if action) || self.class.allowed_parameters
     end
 
-    # Get a native serializer config for the current action.
-    def get_native_serializer_config
-      action_serializer_config = self.class.native_serializer_action_config || {}
-      action = self.action_name.to_sym
-
-      # index action should use :list serializer config if :index is not provided
-      action = :list if action == :index && !action_serializer_config.key?(:index)
+    # Get the list of filtering backends to use.
+    def get_filter_backends
+      backends = super
+      return backends if backends
 
-      return (action_serializer_config[action] if action) || self.class.native_serializer_config
+      # By default, return the standard model filter backend.
+      return [RESTFramework::ModelFilter, RESTFramework::ModelOrderingFilter]
     end
 
-    # Get a list of parameters allowed for the current action.
-    def get_allowed_parameters
-      allowed_action_parameters = self.class.allowed_action_parameters || {}
+    # Get a list of fields for the current action.
+    def get_fields
+      action_fields = self.class.action_fields || {}
       action = self.action_name.to_sym
 
-      # index action should use :list allowed parameters if :index is not provided
-      action = :list if action == :index && !allowed_action_parameters.key?(:index)
+      # index action should use :list fields if :index is not provided
+      action = :list if action == :index && !action_fields.key?(:index)
 
-      return (allowed_action_parameters[action] if action) || self.class.allowed_parameters
+      return (action_fields[action] if action) || self.class.fields || []
     end
 
     # Filter the request body for keys in current action's allowed_parameters/fields config.
@@ -75,29 +85,10 @@ module RESTFramework
     alias :get_create_params :_get_parameter_values_from_request_body
     alias :get_update_params :_get_parameter_values_from_request_body
 
-    # Filter params for keys allowed by the current action's filterset_fields/fields config.
-    def _get_filterset_values_from_params
-      fields = self.filterset_fields || self.get_fields
-      return @_get_filterset_values_from_params ||= request.query_parameters.select { |p|
-        fields.include?(p.to_sym) || fields.include?(p.to_s)
-      }
-    end
-    alias :get_lookup_params :_get_filterset_values_from_params
-    alias :get_filter_params :_get_filterset_values_from_params
-
-    # Get the recordset, filtered by the filter params.
-    def get_filtered_recordset
-      filter_params = self.get_filter_params
-      unless filter_params.blank?
-        return self.get_recordset.where(**self.get_filter_params.to_hash.symbolize_keys)
-      end
-      return self.get_recordset
-    end
-
     # Get a record by `id` or return a single record if recordset is filtered down to a single
     # record.
     def get_record
-      records = self.get_filtered_recordset
+      records = self.get_filtered_data(self.get_recordset)
       if params['id']  # direct lookup
         return records.find(params['id'])
       elsif records.length == 1
@@ -144,23 +135,28 @@ module RESTFramework
   end
 
   module ListModelMixin
-    # TODO: pagination classes like Django
     def index
-      @records = self.get_filtered_recordset
-      @serialized_records = self.get_serializer_class.new(
-        object: @records, controller: self
-      ).serialize
-      return api_response(@serialized_records)
+      @records = self.get_filtered_data(self.get_recordset)
+
+      # Handle pagination, if enabled.
+      if self.class.paginator_class
+        paginator = self.class.paginator_class.new(data: @records, controller: self)
+        page = paginator.get_page
+        serialized_page = self.get_serializer_class.new(object: page, controller: self).serialize
+        data = paginator.get_paginated_response(serialized_page)
+      else
+        data = self.get_serializer_class.new(object: @records, controller: self).serialize
+      end
+
+      return api_response(data)
     end
   end
 
   module ShowModelMixin
     def show
       @record = self.get_record
-      @serialized_record = self.get_serializer_class.new(
-        object: @record, controller: self
-      ).serialize
-      return api_response(@serialized_record)
+      serialized_record = self.get_serializer_class.new(object: @record, controller: self).serialize
+      return api_response(serialized_record)
     end
   end
 
@@ -173,10 +169,8 @@ module RESTFramework
         # Otherwise, perform a "bare" create.
         @record = self.get_model.create!(self.get_create_params)
       end
-      @serialized_record = self.get_serializer_class.new(
-        object: @record, controller: self
-      ).serialize
-      return api_response(@serialized_record)
+      serialized_record = self.get_serializer_class.new(object: @record, controller: self).serialize
+      return api_response(serialized_record)
     end
   end
 
@@ -184,10 +178,8 @@ module RESTFramework
     def update
       @record = self.get_record
       @record.update!(self.get_update_params)
-      @serialized_record = self.get_serializer_class.new(
-        object: @record, controller: self
-      ).serialize
-      return api_response(@serialized_record)
+      serialized_record = self.get_serializer_class.new(object: @record, controller: self).serialize
+      return api_response(serialized_record)
     end
   end
 

data/lib/rest_framework/filters.rb

@@ -0,0 +1,65 @@
+module RESTFramework
+  class BaseFilter
+    def initialize(controller:)
+      @controller = controller
+    end
+
+    def get_filtered_data(data)
+      raise NotImplementedError
+    end
+  end
+
+  # A simple filtering backend that supports filtering a recordset based on fields defined on the
+  # controller class.
+  class ModelFilter < BaseFilter
+    # Filter params for keys allowed by the current action's filterset_fields/fields config.
+    def _get_filter_params
+      fields = @controller.class.filterset_fields || @controller.send(:get_fields)
+      return @controller.request.query_parameters.select { |p|
+        fields.include?(p.to_sym) || fields.include?(p.to_s)
+      }.to_hash.symbolize_keys
+    end
+
+    def get_filtered_data(data)
+      filter_params = self._get_filter_params
+      unless filter_params.blank?
+        return data.where(**filter_params)
+      end
+
+      return data
+    end
+  end
+
+  # A filter backend which handles ordering of the recordset.
+  class ModelOrderingFilter < BaseFilter
+    # Convert ordering string to an ordering configuration.
+    def _get_ordering
+      return nil unless @controller.class.ordering_query_param
+
+      order_string = @controller.params[@controller.class.ordering_query_param]
+      unless order_string.blank?
+        return order_string.split(',').map { |field|
+          if field[0] == '-'
+            [field[1..-1].to_sym, :desc]
+          else
+            [field.to_sym, :asc]
+          end
+        }.to_h
+      end
+
+      return nil
+    end
+
+    def get_filtered_data(data)
+      ordering = self._get_ordering
+      if ordering && !ordering.empty?
+        return data.order(_get_ordering)
+      end
+      return data
+    end
+  end
+
+  # TODO: implement searching within fields rather than exact match filtering (ModelFilter)
+  # class ModelSearchFilter < BaseFilter
+  # end
+end

data/lib/rest_framework/paginators.rb

@@ -0,0 +1,84 @@
+module RESTFramework
+
+  # A simple paginator based on page numbers.
+  #
+  # Example: http://example.com/api/users/?page=3&page_size=50
+  class PageNumberPaginator
+    def initialize(data:, controller:, **kwargs)
+      @data = data
+      @controller = controller
+      @count = data.count
+      @page_size = self._page_size
+
+      @total_pages = @count / @page_size
+      @total_pages += 1 if @count % @page_size
+    end
+
+    def _page_size
+      page_size = nil
+
+      # Get from context, if allowed.
+      if @controller.class.page_size_query_param
+        page_size = @controller.params[@controller.class.page_size_query_param].presence
+        if page_size
+          page_size = page_size.to_i
+        end
+      end
+
+      # Otherwise, get from config.
+      if !page_size && @controller.class.page_size
+        page_size = @controller.class.page_size
+      end
+
+      # Fallback to a page size of 15.
+      page_size = 15 unless page_size
+
+      # Ensure we don't exceed the max page size.
+      if @controller.class.max_page_size && page_size > @controller.class.max_page_size
+        page_size = @controller.class.max_page_size
+      end
+
+      # Ensure we return at least 1.
+      return page_size.zero? ? 1 : page_size
+    end
+
+    def _page_query_param
+      return @controller.class.page_query_param&.to_sym
+    end
+
+    def get_page(page_number=nil)
+      # If page number isn't provided, infer from the params or use 1 as a fallback value.
+      if !page_number
+        page_number = @controller&.params&.[](self._page_query_param)
+        if page_number.blank?
+          page_number = 1
+        else
+          page_number = page_number.to_i
+          if page_number.zero?
+            page_number = 1
+          end
+        end
+      end
+      @page_number = page_number
+
+      # Get the data page and return it so the caller can serialize the data in the proper format.
+      page_index = @page_number - 1
+      return @data.limit(@page_size).offset(page_index * @page_size)
+    end
+
+    # Wrap the serialized page with appripriate metadata.
+    def get_paginated_response(serialized_page)
+      return {
+        count: @count,
+        page: @page_number,
+        total_pages: @total_pages,
+        results: serialized_page,
+      }
+    end
+  end
+
+  # TODO: implement this
+  # class CountOffsetPaginator
+  # end
+
+end

data/lib/rest_framework/serializers.rb

@@ -2,9 +2,8 @@ module RESTFramework
   class BaseSerializer
     attr_reader :errors
 
-    def initialize(object: nil, data: nil, controller: nil, **kwargs)
+    def initialize(object: nil, controller: nil, **kwargs)
       @object = object
-      @data = data
       @controller = controller
     end
   end
@@ -12,16 +11,15 @@ module RESTFramework
   # This serializer uses `.as_json` to serialize objects. Despite the name, `.as_json` is a Rails
   # method which converts objects to Ruby primitives (with the top-level being either an array or a
   # hash).
-  class NativeModelSerializer < BaseSerializer
+  class NativeSerializer < BaseSerializer
     class_attribute :config
     class_attribute :singular_config
     class_attribute :plural_config
     class_attribute :action_config
 
-    def initialize(model: nil, many: nil, **kwargs)
+    def initialize(many: nil, **kwargs)
       super(**kwargs)
       @many = many
-      @model = model || (@controller ? @controller.send(:get_model) : nil)
     end
 
     # Get controller action, if possible.
@@ -34,41 +32,36 @@ module RESTFramework
       action = self.get_action
 
       if action && self.action_config
-        # index action should use :list serializer config if :index is not provided
+        # Index action should use :list serializer config if :index is not provided.
         action = :list if action == :index && !self.action_config.key?(:index)
 
         return self.action_config[action] if self.action_config[action]
       end
 
-      # no action_config, so try singular/plural config
+      # No action_config, so try singular/plural config.
       return self.plural_config if @many && self.plural_config
       return self.singular_config if !@many && self.singular_config
 
-      # lastly, try the default config
+      # Lastly, try returning the default config.
       return self.config
     end
 
-    # Get a configuration passable to `as_json` for the model.
+    # Get a configuration passable to `as_json` for the object.
     def get_serializer_config
-      # return a locally defined serializer config if one is defined
-      local_config = self.get_local_serializer_config
-      return local_config if local_config
-
-      # return a serializer config if one is defined
-      serializer_config = @controller.send(:get_native_serializer_config)
-      return serializer_config if serializer_config
+      # Return a locally defined serializer config if one is defined.
+      if local_config = self.get_local_serializer_config
+        return local_config
+      end
 
-      # otherwise, build a serializer config from fields
-      fields = @controller.send(:get_fields) if @controller
-      unless fields.blank?
-        columns, methods = fields.partition { |f| f.to_s.in?(@model.column_names) }
-        return {only: columns, methods: methods}
+      # Return a serializer config if one is defined.
+      if serializer_config = @controller.send(:get_native_serializer_config)
+        return serializer_config
       end
 
       return {}
     end
 
-    # Convert the object(s) to Ruby primitives.
+    # Convert the object (record or recordset) to Ruby primitives.
     def serialize
       if @object
         @many = @object.respond_to?(:each) if @many.nil?
@@ -105,4 +98,28 @@ module RESTFramework
       return @_nested_config[key] = value
     end
   end
+
+  # `NativeModelSerializer` is similar to `NativeSerializer` but with some customizations to work
+  # with `ActiveModel`.
+  class NativeModelSerializer < NativeSerializer
+    def initialize(model: nil, **kwargs)
+      super(**kwargs)
+      @model = model || (@controller ? @controller.send(:get_model) : nil)
+    end
+
+    # Get a configuration passable to `as_json` for the object.
+    def get_serializer_config
+      config = super
+      return config unless config.blank?
+
+      # If the config wasn't determined, build a serializer config from model fields.
+      fields = @controller.try(:get_fields) if @controller
+      unless fields.blank?
+        columns, methods = fields.partition { |f| f.to_s.in?(@model.column_names) }
+        return {only: columns, methods: methods}
+      end
+
+      return {}
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-12-09 00:00:00.000000000 Z
+date: 2021-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,6 +43,8 @@ files:
 - lib/rest_framework/controller_mixins/base.rb
 - lib/rest_framework/controller_mixins/models.rb
 - lib/rest_framework/engine.rb
+- lib/rest_framework/filters.rb
+- lib/rest_framework/paginators.rb
 - lib/rest_framework/routers.rb
 - lib/rest_framework/serializers.rb
 - lib/rest_framework/version.rb