rest_framework 0.0.16 → 0.2.1

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
-    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,49 @@
 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
+
+          # 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)
+          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 +77,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 +111,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 +148,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