rest_framework 0.1.0 → 0.2.2

data/lib/rest_framework/errors.rb

@@ -0,0 +1,26 @@
+# Top-level class for all REST Framework errors.
+class RESTFramework::Error < StandardError
+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::UnserializableError < RESTFramework::Error
+  def initialize(object)
+    @object = object
+    return super
+  end
+
+  def message
+    return "Unable to serialize `#{@object.inspect}` (of type `#{@object.class}`)."
+  end
+end

data/lib/rest_framework/filters.rb

@@ -1,65 +1,68 @@
-module RESTFramework
-  class BaseFilter
-    def initialize(controller:)
-      @controller = controller
-    end
+class RESTFramework::BaseFilter
+  def initialize(controller:)
+    @controller = controller
+  end
 
-    def get_filtered_data(data)
-      raise NotImplementedError
-    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
+# A simple filtering backend that supports filtering a recordset based on fields defined on the
+# controller class.
+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)
+    return @controller.request.query_parameters.select { |p|
+      fields.include?(p)
+    }.to_h.symbolize_keys  # convert from HashWithIndifferentAccess to Hash w/keys
+  end
 
-      return data
+  # Filter data according to the request query parameters.
+  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
+# A filter backend which handles ordering of the recordset.
+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
+    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
 
-    def get_filtered_data(data)
-      ordering = self._get_ordering
-      if ordering && !ordering.empty?
-        return data.order(_get_ordering)
-      end
-      return data
-    end
+    return nil
   end
 
-  # TODO: implement searching within fields rather than exact match filtering (ModelFilter)
-  # class ModelSearchFilter < BaseFilter
-  # end
+  # Order data according to the request query parameters.
+  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 RESTFramework::ModelSearchFilter < RESTFramework::BaseFilter
+# end

data/lib/rest_framework/generators.rb

@@ -0,0 +1,5 @@
+module RESTFramework::Generators
+end
+
+
+require_relative 'generators/controller_generator'

data/lib/rest_framework/generators/controller_generator.rb

@@ -0,0 +1,26 @@
+require 'rails/generators'
+
+
+class RESTFramework::Generators::ControllerGenerator < Rails::Generators::Base
+  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
+  END
+
+  def create_controller_file
+    create_file "app/controllers/some_controller.rb", "# Add initialization content here"
+  end
+end

data/lib/rest_framework/paginators.rb

@@ -1,84 +1,95 @@
-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 != 0)
-    end
+class RESTFramework::BasePaginator
+  def initialize(data:, controller:, **kwargs)
+    @data = data
+    @controller = controller
+  end
 
-    def _page_size
-      page_size = nil
+  # Get the page and return it so the caller can serialize it.
+  def get_page
+    raise NotImplementedError
+  end
 
-      # 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
+  # Wrap the serialized page with appropriate metadata.
+  def get_paginated_response(serialized_page)
+    raise NotImplementedError
+  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
+# A simple paginator based on page numbers.
+#
+# Example: http://example.com/api/users/?page=3&page_size=50
+class RESTFramework::PageNumberPaginator < RESTFramework::BasePaginator
+  def initialize(**kwargs)
+    super
+    @count = @data.count
+    @page_size = self._page_size
+
+    @total_pages = @count / @page_size
+    @total_pages += 1 if (@count % @page_size != 0)
+  end
+
+  def _page_size
+    page_size = nil
 
-      # 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
+    # Get from context, if allowed.
+    if @controller.class.page_size_query_param
+      if page_size = @controller.params[@controller.class.page_size_query_param].presence
+        page_size = page_size.to_i
       end
+    end
 
-      # Ensure we return at least 1.
-      return page_size.zero? ? 1 : page_size
+    # Otherwise, get from config.
+    if !page_size && @controller.class.page_size
+      page_size = @controller.class.page_size
     end
 
-    def _page_query_param
-      return @controller.class.page_query_param&.to_sym
+    # 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
 
-    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?
+    # 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
+
+  # Get the page and return it so the caller can serialize it.
+  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
-        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
+    @page_number = page_number
 
-    # 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
+    # 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
 
-  # TODO: implement this
-  # class CountOffsetPaginator
-  # end
-
+  # Wrap the serialized page with appropriate metadata. TODO: include links.
+  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 RESTFramework::CountOffsetPaginator
+# end

data/lib/rest_framework/routers.rb

@@ -1,8 +1,9 @@
 require 'action_dispatch/routing/mapper'
 
+
 module ActionDispatch::Routing
   class Mapper
-    # Helper to take extra_actions hash and convert to a consistent format.
+    # 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 = {}
@@ -24,6 +25,11 @@ module ActionDispatch::Routing
             path = v.delete(:path)
           end
 
+          # Set the action to be the action key unless it's already defined.
+          if !kwargs[:action]
+            kwargs[:action] = k
+          end
+
           # Pass any further kwargs to the underlying Rails interface.
           kwargs = kwargs.merge(v)
         elsif v.is_a?(Symbol) || v.is_a?(String)
@@ -37,7 +43,7 @@ module ActionDispatch::Routing
       end
     end
 
-    # Private interface to get the controller class from the name and current scope.
+    # Internal interface to get the controller class from the name and current scope.
     protected def _get_controller_class(name, pluralize: true, fallback_reverse_pluralization: true)
       # get class name
       name = name.to_s.camelize  # camelize to leave plural names plural
@@ -71,7 +77,7 @@ module ActionDispatch::Routing
       return controller
     end
 
-    # Core implementation of the `rest_resource(s)` router, both singular and plural.
+    # 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
     # @param name [Symbol] the resource name, from which path and controller are deduced by default
@@ -166,7 +172,7 @@ module ActionDispatch::Routing
     end
 
     # Route a controller's `#root` to '/' in the current scope/namespace, along with other actions.
-    # @param label [Symbol] the snake_case name of the controller
+    # @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

data/lib/rest_framework/serializers.rb

@@ -1,116 +1,165 @@
-module RESTFramework
-  class BaseSerializer
-    attr_reader :errors
+class RESTFramework::BaseSerializer
+  def initialize(object: nil, controller: nil, **kwargs)
+    @object = object
+    @controller = controller
+  end
 
-    def initialize(object: nil, controller: nil, **kwargs)
-      @object = object
-      @controller = controller
-    end
+  def serialize
+    raise NotImplementedError
   end
+end
 
-  # This serializer uses `.as_json` to serialize objects. Despite the name, `.as_json` is an
-  # `ActiveModel` method which converts objects to Ruby primitives (with the top-level being either
-  # an array or a hash).
-  class NativeModelSerializer < BaseSerializer
-    class_attribute :config
-    class_attribute :singular_config
-    class_attribute :plural_config
-    class_attribute :action_config
 
-    def initialize(many: nil, model: nil, **kwargs)
-      super(**kwargs)
+# This serializer uses `.serializable_hash` to convert objects to Ruby primitives (with the
+# top-level being either an array or a hash).
+class RESTFramework::NativeSerializer < RESTFramework::BaseSerializer
+  class_attribute :config
+  class_attribute :singular_config
+  class_attribute :plural_config
+  class_attribute :action_config
 
-      if many.nil?
-        @many = @object.respond_to?(:count) ? @object.count : nil
-      else
-        @many = many
-      end
+  def initialize(many: nil, model: nil, **kwargs)
+    super(**kwargs)
 
-      @model = model || (@controller ? @controller.send(:get_model) : nil)
+    if many.nil?
+      # Determine if we are dealing with many objects or just one.
+      @many = @object.is_a?(Enumerable)
+    else
+      @many = many
     end
 
-    # Get controller action, if possible.
-    def get_action
-      return @controller&.action_name&.to_sym
-    end
+    # 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.is_a?(Enumerable) && @object.is_a?(ActiveRecord::Base)
+    )
+    @model ||= @controller.send(:get_model) if @controller
+  end
 
-    # Get a locally defined configuration, if one is defined.
-    def get_local_serializer_config
-      action = self.get_action
+  # Get controller action, if possible.
+  def get_action
+    return @controller&.action_name&.to_sym
+  end
 
-      if action && self.action_config
-        # Index action should use :list serializer config if :index is not provided.
-        action = :list if action == :index && !self.action_config.key?(:index)
+  # Get a locally defined native serializer configuration, if one is defined.
+  def get_local_native_serializer_config
+    action = self.get_action
 
-        return self.action_config[action] if self.action_config[action]
-      end
+    if action && self.action_config
+      # Index action should use :list serializer config if :index is not provided.
+      action = :list if action == :index && !self.action_config.key?(:index)
 
-      # 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
+      return self.action_config[action] if self.action_config[action]
+    end
+
+    # No action_config, so try singular/plural config if explicitly instructed to via @many.
+    return self.plural_config if @many == true && self.plural_config
+    return self.singular_config if @many == false && self.singular_config
+
+    # Lastly, try returning the default config, or singular/plural config in that order.
+    return self.config || self.singular_config || self.plural_config
+  end
+
+  # Helper to get a native serializer configuration from the controller.
+  def get_controller_native_serializer_config
+    return nil unless @controller
 
-      # Lastly, try returning the default config.
-      return self.config
+    if @many == true
+      controller_serializer = @controller.try(:native_serializer_plural_config)
+    elsif @many == false
+      controller_serializer = @controller.try(:native_serializer_singular_config)
     end
 
-    # Get a configuration passable to `as_json` for the object.
-    def get_serializer_config
-      # Return a locally defined serializer config if one is defined.
-      if local_config = self.get_local_serializer_config
-        return local_config
-      end
+    return controller_serializer || @controller.try(:native_serializer_config)
+  end
 
-      # Return a serializer config if one is defined.
-      if serializer_config = @controller.send(:get_native_serializer_config)
-        return serializer_config
-      end
+  # Get a configuration passable to `serializable_hash` for the object.
+  def get_serializer_config
+    # Return a locally defined serializer config if one is defined.
+    if local_config = self.get_local_native_serializer_config
+      return local_config
+    end
 
-      # 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}
+    # Return a serializer config if one is defined on the controller.
+    if serializer_config = get_controller_native_serializer_config
+      return serializer_config
+    end
+
+    # If the config wasn't determined, build a serializer config from model fields.
+    fields = @controller.send(:get_fields) if @controller
+    if fields
+      if @model
+        columns, methods = fields.partition { |f| f.in?(@model.column_names) }
+      else
+        columns = fields
+        methods = []
       end
 
-      return {}
+      return {only: columns, methods: methods}
     end
 
-    # Convert the object (record or recordset) to Ruby primitives.
-    def serialize
-      if @object
-        @many = @object.respond_to?(:each) if @many.nil?
-        return @object.as_json(self.get_serializer_config)
+    # By default, pass an empty configuration, allowing the serialization of all columns.
+    return {}
+  end
+
+  # Convert the object (record or recordset) to Ruby primitives.
+  def serialize
+    if @object
+      begin
+        if @object.is_a?(Enumerable)
+          return @object.map { |r| r.serializable_hash(self.get_serializer_config) }
+        end
+        return @object.serializable_hash(self.get_serializer_config)
+      rescue NoMethodError
       end
-      return nil
     end
 
-    # 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
-      return @_nested_config[key]
+    # Raise an error if we cannot serialize the object.
+    raise RESTFramework::UnserializableError.new(@object)
+  end
+
+  # 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
-    def []=(key, value)
-      unless instance_variable_defined?(:@_nested_config)
-        @_nested_config = self.get_serializer_config
-      end
-      return @_nested_config[key] = value
+    return @_nested_config[key]
+  end
+  def []=(key, value)
+    unless instance_variable_defined?(:@_nested_config)
+      @_nested_config = self.get_serializer_config
     end
+    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
-      return @_nested_config[key]
+  # 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
-    def self.[]=(key, value)
-      unless instance_variable_defined?(:@_nested_config)
-        @_nested_config = self.new.get_serializer_config
-      end
-      return @_nested_config[key] = value
+    return @_nested_config[key]
+  end
+  def self.[]=(key, value)
+    unless instance_variable_defined?(:@_nested_config)
+      @_nested_config = self.new.get_serializer_config
     end
+    return @_nested_config[key] = value
   end
+end
 
+
+# :nocov:
+# Alias NativeModelSerializer -> NativeSerializer.
+class RESTFramework::NativeModelSerializer < RESTFramework::NativeSerializer
+  def initialize(**kwargs)
+    super
+    ActiveSupport::Deprecation.warn(
+      <<~MSG.split("\n").join(' ')
+        RESTFramework::NativeModelSerializer is deprecated and will be removed in future versions of
+        REST Framework; you should use RESTFramework::NativeSerializer instead.
+      MSG
+    )
+  end
 end
+# :nocov: