rest_framework 0.0.15 → 0.2.0

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

@@ -0,0 +1,68 @@
+class RESTFramework::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 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
+
+  # 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 RESTFramework::ModelOrderingFilter < RESTFramework::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
+
+  # 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

@@ -0,0 +1,95 @@
+class RESTFramework::BasePaginator
+  def initialize(data:, controller:, **kwargs)
+    @data = data
+    @controller = controller
+  end
+
+  # Get the page and return it so the caller can serialize it.
+  def get_page
+    raise NotImplementedError
+  end
+
+  # Wrap the serialized page with appropriate metadata.
+  def get_paginated_response(serialized_page)
+    raise NotImplementedError
+  end
+end
+
+
+# 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
+
+    # 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
+
+    # Otherwise, get from config.
+    if !page_size && @controller.class.page_size
+      page_size = @controller.class.page_size
+    end
+
+    # 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
+
+  # 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
+        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 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,44 @@
 require 'action_dispatch/routing/mapper'
 
+
 module ActionDispatch::Routing
   class Mapper
-    # Private interface to get the controller class from the name and current scope.
+    # 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 = {}
+        path = k
+
+        # Convert structure to path/methods/kwargs.
+        if v.is_a?(Hash)  # allow kwargs
+          v = v.symbolize_keys
+
+          # Ensure methods is an array.
+          if v[:methods].is_a?(String) || v[:methods].is_a?(Symbol)
+            methods = [v.delete(:methods)]
+          else
+            methods = v.delete(:methods)
+          end
+
+          # Override path if it's provided.
+          if v.key?(:path)
+            path = v.delete(:path)
+          end
+
+          # Pass any further kwargs to the underlying Rails interface.
+          kwargs = kwargs.merge(v)
+        elsif v.is_a?(Symbol) || v.is_a?(String)
+          methods = [v]
+        else
+          methods = v
+        end
+
+        # Return a hash with keys: :path, :methods, :kwargs.
+        {path: path, methods: methods, kwargs: kwargs}
+      end
+    end
+
+    # 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
@@ -36,20 +72,20 @@ 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
-    # @param skip_undefined [Boolean] whether we should skip routing undefined actions
+    # @param skip_undefined [Boolean] whether we should skip routing undefined resourceful actions
     protected def _rest_resources(default_singular, name, skip_undefined: true, **kwargs, &block)
-      controller = kwargs[:controller] || name
+      controller = kwargs.delete(:controller) || name
       if controller.is_a?(Class)
         controller_class = controller
       else
         controller_class = _get_controller_class(controller, pluralize: !default_singular)
       end
 
-      # set controller if it's not explicitly set
+      # Set controller if it's not explicitly set.
       kwargs[:controller] = name unless kwargs[:controller]
 
       # determine plural/singular resource
@@ -70,25 +106,20 @@ module ActionDispatch::Routing
       public_send(resource_method, name, except: skip, **kwargs) do
         if controller_class.respond_to?(:extra_member_actions)
           member do
-            actions = controller_class.extra_member_actions || {}
-            actions = actions.select { |k,v| controller_class.method_defined?(k) } if skip_undefined
-            actions.each do |action, methods|
-              methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
-              methods.each do |m|
-                public_send(m, action)
+            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
           end
         end
 
         collection do
-          actions = controller_class.extra_actions || {}
-          actions = actions.select { |k,v| controller_class.method_defined?(k) } if skip_undefined
-          actions.reject! { |k,v| skip.include? k }
-          actions.each do |action, methods|
-            methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
-            methods.each do |m|
-              public_send(m, action)
+          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
         end
@@ -112,42 +143,55 @@ module ActionDispatch::Routing
     end
 
     # Route a controller without the default resourceful paths.
-    def rest_route(path=nil, skip_undefined: true, **kwargs, &block)
-      controller = kwargs.delete(:controller) || path
-      path = path.to_s
+    def rest_route(name=nil, **kwargs, &block)
+      controller = kwargs.delete(:controller) || name
+      if controller.is_a?(Class)
+        controller_class = controller
+      else
+        controller_class = self._get_controller_class(controller, pluralize: false)
+      end
 
-      # route actions
-      controller_class = self._get_controller_class(controller, pluralize: false)
-      skip = controller_class.get_skip_actions(skip_undefined: skip_undefined)
-      actions = controller_class.extra_actions || {}
-      actions = actions.select { |k,v| controller_class.method_defined?(k) } if skip_undefined
-      actions.reject! { |k,v| skip.include? k }
-      actions.each do |action, methods|
-        methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
-        methods.each do |m|
-          public_send(m, File.join(path, action.to_s), controller: controller, action: action)
+      # Set controller if it's not explicitly set.
+      kwargs[:controller] = name unless kwargs[:controller]
+
+      # 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?
         end
-        yield if block_given?
       end
     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
-    def rest_root(path=nil, **kwargs, &block)
-      # by default, use RootController#root
+    # @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) || path || :root
-      path = path.to_s
+      controller = kwargs.delete(:controller) || name || :root
 
-      # route the root
-      get path, controller: controller, action: root_action
+      # Route the root.
+      get name.to_s, controller: controller, action: root_action
 
-      # route any additional actions
+      # Route any additional actions.
       controller_class = self._get_controller_class(controller, pluralize: false)
-      (controller_class.extra_actions || {}).each do |action, methods|
-        methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
-        methods.each do |m|
-          public_send(m, File.join(path, action.to_s), controller: controller, action: action)
+      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
+
+        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
         yield if block_given?
       end

data/lib/rest_framework/serializers.rb

@@ -1,108 +1,159 @@
-module RESTFramework
-  class BaseSerializer
-    attr_reader :errors
-
-    def initialize(object: nil, data: nil, controller: nil, **kwargs)
-      @object = object
-      @data = data
-      @controller = controller
-    end
+class RESTFramework::BaseSerializer
+  def initialize(object: nil, controller: nil, **kwargs)
+    @object = object
+    @controller = controller
   end
+end
+
+
+# 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
+
+  def initialize(many: nil, model: nil, **kwargs)
+    super(**kwargs)
 
-  # 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_attribute :config
-    class_attribute :singular_config
-    class_attribute :plural_config
-    class_attribute :action_config
-
-    def initialize(model: nil, many: nil, **kwargs)
-      super(**kwargs)
+    if many.nil?
+      # Determine if we are dealing with many objects or just one.
+      @many = @object.is_a?(Enumerable)
+    else
       @many = many
-      @model = model || (@controller ? @controller.send(:get_model) : nil)
     end
 
-    # Get controller action, if possible.
-    def get_action
-      return @controller&.action_name&.to_sym
+    # 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 ||= @controller.send(:get_model) if @controller
+  end
+
+  # Get controller action, if possible.
+  def get_action
+    return @controller&.action_name&.to_sym
+  end
+
+  # Get a locally defined native serializer configuration, if one is defined.
+  def get_local_native_serializer_config
+    action = self.get_action
+
+    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)
+
+      return self.action_config[action] if self.action_config[action]
     end
 
-    # Get a locally defined configuration, if one is defined.
-    def get_local_serializer_config
-      action = self.get_action
+    # 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
 
-      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)
+    # Lastly, try returning the default config, or singular/plural config in that order.
+    return self.config || self.singular_config || self.plural_config
+  end
 
-        return self.action_config[action] if self.action_config[action]
-      end
+  # Helper to get a native serializer configuration from the controller.
+  def get_controller_native_serializer_config
+    return nil unless @controller
 
-      # 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
+    if @many == true
+      controller_serializer = @controller.try(:native_serializer_plural_config)
+    elsif @many == false
+      controller_serializer = @controller.try(:native_serializer_singular_config)
+    end
+
+    return controller_serializer || @controller.try(:native_serializer_config)
+  end
 
-      # lastly, try the default config
-      return self.config
+  # 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
 
-    # Get a configuration passable to `as_json` for the model.
-    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
-
-      # 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 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(s) 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: