cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/responders/html/rendering.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders/html'
+
+module Cuprum::Rails::Responders::Html
+  # Implements generating HTML response objects.
+  module Rendering
+    # Creates a HeadResponse based on the given HTTP status.
+    #
+    # @param status [Integer] the HTTP status of the response.
+    #
+    # @return [Cuprum::Rails::Responses::HeadResponse] the response.
+    def head(status:)
+      Cuprum::Rails::Responses::HeadResponse.new(status: status)
+    end
+
+    # Creates a RedirectBackResponse based on the given HTTP status.
+    #
+    # @param fallback_location [String] the path or url to redirect to if the
+    #   previous location cannot be determined.
+    # @param flash [Hash] the flash messages to set.
+    # @param status [Integer] the HTTP status of the response.
+    def redirect_back(fallback_location: '/', flash: {}, status: 302)
+      Cuprum::Rails::Responses::Html::RedirectBackResponse
+        .new(fallback_location: fallback_location, flash: flash, status: status)
+    end
+
+    # Creates a RedirectResponse based on the given path and HTTP status.
+    #
+    # @param flash [Hash] the flash messages to set.
+    # @param path [String] the path or url to redirect to.
+    # @param status [Integer] the HTTP status of the response.
+    #
+    # @return [Cuprum::Rails::Responses::Html::RedirectResponse] the response.
+    def redirect_to(path, flash: {}, status: 302)
+      Cuprum::Rails::Responses::Html::RedirectResponse
+        .new(path, flash: flash, status: status)
+    end
+
+    # Creates a RenderResponse based on the given template and parameters.
+    #
+    # @param assigns [Hash] variables to assign when rendering the template.
+    # @param flash [Hash] the flash messages to set.
+    # @param layout [String] the layout to render.
+    # @param status [Integer] the HTTP status of the response.
+    # @param template [String, Symbol] the template to render.
+    #
+    # @return [Cuprum::Rails::Responses::Html::RenderResponse] the response.
+    def render(template, assigns: nil, flash: {}, layout: nil, status: 200)
+      Cuprum::Rails::Responses::Html::RenderResponse.new(
+        template,
+        assigns: assigns || default_assigns,
+        flash:   flash,
+        layout:  layout,
+        status:  status
+      )
+    end
+
+    private
+
+    def default_assigns
+      return nil if result.nil?
+
+      assigns = default_value
+
+      assigns[:error] = result.error unless result.error.nil?
+
+      assigns
+    end
+
+    def default_value
+      if result.value.is_a?(Hash)
+        result.value
+      elsif !result.value.nil?
+        { value: result.value }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/cuprum/rails/responders/html/resource.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/failed_validation'
+
+require 'cuprum/rails/responders/html'
+require 'cuprum/rails/responders/html_responder'
+
+module Cuprum::Rails::Responders::Html
+  # Defines default responses for a RESTful resource.
+  #
+  # If the resource is plural:
+  #
+  # - #create failure: renders the :new template.
+  # - #create success: redirects to the resource #show page.
+  # - #destroy success: redirects to the resource #index page.
+  # - #index failure: redirects to the root path.
+  # - #update failure: renders the :edit template.
+  # - #update success: redirects to the resource #show page.
+  #
+  # If the resource is singular:
+  #
+  # - #create failure: renders the :new template.
+  # - #create success: redirects to the resource #show page.
+  # - #destroy success: redirects to the parent resource.
+  # - #update failure: renders the :edit template.
+  # - #update success: redirects to the resource #show page.
+  #
+  # Responds to any other successful result by rendering the template for the
+  # action name and passing the result value as assigned variables. For a
+  # failing result, redirects to the parent resource (for a singular resource),
+  # or redirects to either the show page or the index page for the resource.
+  class Resource < Cuprum::Rails::Responders::HtmlResponder
+    action :create do
+      match :failure, error: Cuprum::Collections::Errors::FailedValidation do
+        render :new,
+          assigns: result.value.merge(errors: result.error.errors),
+          status:  422 # rubocop:disable Rails/HttpStatus
+      end
+
+      match :success do
+        next redirect_to(routes.show_path) if resource.singular?
+
+        entity = result.value[resource.singular_name]
+
+        redirect_to routes.show_path(entity)
+      end
+    end
+
+    action :destroy do
+      match :success do
+        next redirect_to(routes.parent_path) if resource.singular?
+
+        redirect_to(routes.index_path)
+      end
+    end
+
+    action :index do
+      match :failure do
+        redirect_to routes.root_path
+      end
+    end
+
+    action :update do
+      match :failure, error: Cuprum::Collections::Errors::FailedValidation do
+        render :edit,
+          assigns: result.value.merge(errors: result.error.errors),
+          status:  422 # rubocop:disable Rails/HttpStatus
+      end
+
+      match :success do
+        next redirect_to(routes.show_path) if resource.singular?
+
+        entity = result.value[resource.singular_name]
+
+        redirect_to routes.show_path(entity)
+      end
+    end
+
+    match :failure, error: Cuprum::Collections::Errors::NotFound do |result|
+      handle_not_found_error(result)
+    end
+
+    match :failure do
+      next redirect_to(routes.show_path) if resource.singular?
+
+      redirect_to(routes.index_path)
+    end
+
+    private
+
+    def find_ancestor(&block)
+      resource.each_ancestor.find(&block)
+    end
+
+    def handle_not_found_error(result)
+      matching = find_ancestor do |ancestor|
+        ancestor.name == result.error.collection_name
+      end
+
+      return render(request.action_name, status: 404) unless matching # rubocop:disable Rails/HttpStatus
+
+      routes = matching.routes.with_wildcards(request.path_params || {})
+
+      redirect_to(matching.singular? ? routes.show_path : routes.index_path)
+    end
+  end
+end

data/lib/cuprum/rails/responders/html/singular_resource.rb

@@ -3,7 +3,7 @@
 require 'cuprum/collections/errors/failed_validation'
 
 require 'cuprum/rails/responders/html'
-require 'cuprum/rails/responders/html_responder'
+require 'cuprum/rails/responders/html/resource'
 
 module Cuprum::Rails::Responders::Html
   # Defines default responses for a singular RESTful resource.
@@ -17,43 +17,14 @@ module Cuprum::Rails::Responders::Html
   # Responds to any other successful result by rendering the template for the
   # action name and passing the result value as assigned variables. For a
   # failing result, redirects to the parent resource.
-  class SingularResource < Cuprum::Rails::Responders::HtmlResponder
-    action :create do
-      match :failure, error: Cuprum::Collections::Errors::FailedValidation do
-        render :new,
-          assigns: result.value.merge(errors: result.error.errors),
-          status:  422 # rubocop:disable Rails/HttpStatus
-      end
-
-      match :success do
-        redirect_to resource.routes.show_path
-      end
-    end
-
-    action :destroy do
-      match :success do
-        next redirect_to(resource.base_path) unless resource.routes
-
-        redirect_to(resource.routes.parent_path)
-      end
-    end
-
-    action :update do
-      match :failure, error: Cuprum::Collections::Errors::FailedValidation do
-        render :edit,
-          assigns: result.value.merge(errors: result.error.errors),
-          status:  422 # rubocop:disable Rails/HttpStatus
-      end
-
-      match :success do
-        redirect_to resource.routes.show_path
-      end
-    end
-
-    match :failure do
-      next redirect_to(resource.base_path) unless resource.routes
-
-      redirect_to(resource.routes.parent_path)
+  class SingularResource < Cuprum::Rails::Responders::Html::Resource
+    def initialize(**options)
+      super
+
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        'Cuprum::Rails::Responders::Html::SingularResource',
+        message: 'use Cuprum::Rails::Responders::Html::Resource'
+      )
     end
   end
 end

data/lib/cuprum/rails/responders/html.rb

@@ -6,6 +6,8 @@ module Cuprum::Rails::Responders
   # Namespace for HTML responders, which process action results into responses.
   module Html
     autoload :PluralResource,   'cuprum/rails/responders/html/plural_resource'
+    autoload :Rendering,        'cuprum/rails/responders/html/rendering'
+    autoload :Resource,         'cuprum/rails/responders/html/resource'
     autoload :SingularResource, 'cuprum/rails/responders/html/singular_resource'
   end
 end

data/lib/cuprum/rails/responders/html_responder.rb

@@ -3,6 +3,8 @@
 require 'cuprum/rails/responses/html/redirect_response'
 require 'cuprum/rails/responders'
 require 'cuprum/rails/responders/actions'
+require 'cuprum/rails/responders/base_responder'
+require 'cuprum/rails/responders/html/rendering'
 require 'cuprum/rails/responders/matching'
 
 module Cuprum::Rails::Responders
@@ -35,7 +37,8 @@ module Cuprum::Rails::Responders
   #
   # @see Cuprum::Rails::Responders::Actions::ClassMethods#action
   # @see Cuprum::Rails::Responders::Matching::ClassMethods#match
-  class HtmlResponder
+  class HtmlResponder < BaseResponder
+    include Cuprum::Rails::Responders::Html::Rendering
     include Cuprum::Rails::Responders::Matching
     include Cuprum::Rails::Responders::Actions
 
@@ -59,71 +62,24 @@ module Cuprum::Rails::Responders
       :html
     end
 
-    # Creates a RedirectResponse based on the given path and HTTP status.
-    #
-    # @param path [String] The path or url to redirect to.
-    # @param status [Integer] The HTTP status of the response.
-    #
-    # @return [Cuprum::Rails::Responses::Html::RedirectResponse] the response.
-    def redirect_to(path, status: 302)
-      Cuprum::Rails::Responses::Html::RedirectResponse.new(path, status: status)
-    end
-
-    # Creates a RenderResponse based on the given template and parameters.
-    #
-    # @param assigns [Hash] Variables to assign when rendering the template.
-    # @param layout [String] The layout to render.
-    # @param status [Integer] The HTTP status of the response.
-    # @param template [String, Symbol] The template to render.
-    #
-    # @return [Cuprum::Rails::Responses::Html::RenderResponse] the response.
-    def render(template, assigns: nil, layout: nil, status: 200)
-      Cuprum::Rails::Responses::Html::RenderResponse.new(
-        template,
-        assigns: assigns || default_assigns,
-        layout:  layout,
-        status:  status
-      )
-    end
-
     private
 
-    def default_assigns
-      return nil if result.nil?
-
-      assigns = default_value
-
-      assigns[:error] = result.error unless result.error.nil?
-
-      assigns
-    end
-
-    def default_value
-      if result.value.is_a?(Hash)
-        result.value
-      elsif !result.value.nil?
-        { value: result.value }
-      else
-        {}
-      end
-    end
-
     def resource_entity
       if result.value.is_a?(Hash)
-        result.value[resource.singular_resource_name]
+        result.value[resource.singular_name]
       else
         result.value
       end
     end
 
     def resource_path(result)
-      return resource.routes.index_path if result.value.nil?
+      return routes.index_path if result.value.nil?
 
       entity = resource_entity
 
-      return resource.routes.show_path(entity) if entity
+      return routes.show_path(entity) if entity
 
-      resource.routes.index_path
+      routes.index_path
     end
   end
 end

data/lib/cuprum/rails/responders/json/resource.rb

@@ -5,7 +5,7 @@ require 'cuprum/collections/errors/extra_attributes'
 require 'cuprum/collections/errors/failed_validation'
 require 'cuprum/collections/errors/not_found'
 
-require 'cuprum/rails/errors/missing_parameters'
+require 'cuprum/rails/errors/invalid_parameters'
 require 'cuprum/rails/responders/json'
 require 'cuprum/rails/responders/json_responder'
 
@@ -19,7 +19,7 @@ module Cuprum::Rails::Responders::Json
   #     Unprocessable Entity.
   # - failure FailedValidation: serializes the error with status 422
   #     Unprocessable Entity.
-  # - failure MissingParameters: serializes the error with status 400 Bad
+  # - failure InvalidParameters: serializes the error with status 400 Bad
   #     Request.
   # - failure NotFound: serializes the error with status 404 Not Found.
   #
@@ -53,7 +53,7 @@ module Cuprum::Rails::Responders::Json
       render_failure(result.error, status: 404)
     end
 
-    match :failure, error: Cuprum::Rails::Errors::MissingParameters do |result|
+    match :failure, error: Cuprum::Rails::Errors::InvalidParameters do |result|
       render_failure(result.error, status: 400)
     end
   end

data/lib/cuprum/rails/responders/json_responder.rb

@@ -2,9 +2,11 @@
 
 require 'cuprum/rails/responders'
 require 'cuprum/rails/responders/actions'
+require 'cuprum/rails/responders/base_responder'
 require 'cuprum/rails/responders/matching'
 require 'cuprum/rails/responders/serialization'
 require 'cuprum/rails/responses/json_response'
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
 
 module Cuprum::Rails::Responders
@@ -32,7 +34,7 @@ module Cuprum::Rails::Responders
   #       render_failure(error, status: 403)
   #     end
   #   end
-  class JsonResponder
+  class JsonResponder < BaseResponder
     include Cuprum::Rails::Responders::Matching
     include Cuprum::Rails::Responders::Actions
     include Cuprum::Rails::Responders::Serialization
@@ -46,31 +48,39 @@ module Cuprum::Rails::Responders
       render_success(result.value)
     end
 
-    match :failure do
-      render_failure(GENERIC_ERROR)
+    match :failure do |result|
+      render_failure(Rails.env.development? ? result.error : generic_error)
     end
 
-    # @param action_name [String, Symbol] The name of the action to match.
-    # @param matcher [Cuprum::Matcher] An optional matcher specific to the
+    # @param action_name [String, Symbol] the name of the action to match.
+    # @param controller [Cuprum::Rails::Controller] the called controller.
+    # @param controller_name [String] the name of the called controller.
+    #   Defaults to controller.class.name.
+    # @param matcher [Cuprum::Matcher] an optional matcher specific to the
     #   action. This will be matched before any of the generic matchers.
-    # @param member_action [Boolean] True if the action acts on a collection
+    # @param member_action [Boolean] true if the action acts on a collection
     #   item, not on the collection as a whole.
-    # @param resource [Cuprum::Rails::Resource] The resource for the controller.
+    # @param request [Cuprum::Rails::Request] the request to the controller.
+    # @param serializers [Hash<Class, Object>] the serializers for converting
+    #   result values into serialized data.
+    # @param options [Hash] additional parameters for the responder.
     def initialize( # rubocop:disable Metrics/ParameterLists
       action_name:,
-      resource:,
+      controller:,
+      request:,
       serializers:,
-      matcher:       nil,
       member_action: false,
-      **_options
+      **options
     )
       super(
-        action_name:     action_name,
-        matcher:         matcher,
-        member_action:   member_action,
-        resource:        resource,
-        root_serializer: Cuprum::Rails::Serializers::Json::Serializer.instance,
-        serializers:     serializers
+        action_name:   action_name,
+        controller:    controller,
+        matcher:       matcher,
+        member_action: member_action,
+        resource:      resource,
+        request:       request,
+        serializers:   serializers,
+        **options
       )
     end
 
@@ -82,6 +92,11 @@ module Cuprum::Rails::Responders
       :json
     end
 
+    # @return [Cuprum::Error] a generic error for generating failure responses.
+    def generic_error
+      GENERIC_ERROR
+    end
+
     # Creates a JsonResponse based on the given data and options.
     #
     # @param json [Object] The data to serialize.

data/lib/cuprum/rails/responders/matching.rb

@@ -46,44 +46,45 @@ module Cuprum::Rails::Responders
       attr_reader :matcher
     end
 
-    # @private
-    def self.included(other)
-      super
+    class << self
+      private
+
+      def included(other)
+        super
 
-      other.extend(ClassMethods)
+        other.extend(ClassMethods)
+      end
     end
 
-    # @param action_name [String, Symbol] The name of the action to match.
-    # @param matcher [Cuprum::Matcher] An optional matcher specific to the
+    # @param action_name [String, Symbol] the name of the action to match.
+    # @param controller [Cuprum::Rails::Controller] the called controller.
+    # @param matcher [Cuprum::Matcher] an optional matcher specific to the
     #   action. This will be matched before any of the generic matchers.
-    # @param member_action [Boolean] True if the action acts on a collection
+    # @param member_action [Boolean] true if the action acts on a collection
     #   item, not on the collection as a whole.
-    # @param resource [Cuprum::Rails::Resource] The resource for the controller.
-    def initialize(
+    # @param request [Cuprum::Rails::Request] the request to the controller.
+    def initialize( # rubocop:disable Metrics/ParameterLists
       action_name:,
-      resource:,
-      matcher: nil,
+      controller:,
+      request:,
+      matcher:       nil,
       member_action: false,
-      **_options
+      **options
     )
-      @action_name   = action_name
-      @matcher       = matcher
-      @member_action = !!member_action # rubocop:disable Style/DoubleNegation
-      @resource      = resource
+      super(
+        action_name:   action_name,
+        controller:    controller,
+        member_action: member_action,
+        request:       request,
+        **options
+      )
+
+      @matcher = matcher
     end
 
-    # @return [String, Symbol] the name of the action to match.
-    attr_reader :action_name
-
     # @return [Cuprum::Matcher] an optional matcher specific to the action.
     attr_reader :matcher
 
-    # @return [Cuprum::Rails::Resource] the resource for the controller.
-    attr_reader :resource
-
-    # @return [Cuprum::Result] the result of calling the action.
-    attr_reader :result
-
     # Finds and calls the response clause that matches the given result.
     #
     # 1.  Checks for an exact match (the result status, value, and error all
@@ -96,8 +97,9 @@ module Cuprum::Rails::Responders
     #     error or a value.
     # 4.  If there is no matching response clause, raises an exception.
     #
-    # @return [#call, #renderer] The response object from the matching response
-    #   clause.
+    # @param result [Cuprum::Result] the result of the action call.
+    #
+    # @return [#call] the response object from the matching response clause.
     #
     # @raise [Cuprum::Matching::NoMatchError] if none of the response clauses
     #   match the result.

data/lib/cuprum/rails/responders/serialization.rb

@@ -1,25 +1,21 @@
 # frozen_string_literal: true
 
 require 'cuprum/rails/responders'
+require 'cuprum/rails/serializers/base_serializer'
+require 'cuprum/rails/serializers/context'
 
 module Cuprum::Rails::Responders
   # Implements serializing a result value into response data.
   module Serialization
-    # @param root_serializer [Class] The root serializer for serializing the
-    #   result value.
     # @param serializers [Hash<Class, Object>] The serializers for converting
     #   result values into serialized data.
     # @param options [Hash] Additional parameters for the responder.
-    def initialize(root_serializer:, serializers:, **options)
+    def initialize(serializers:, **options)
       super(**options)
 
-      @root_serializer = root_serializer
-      @serializers     = serializers
+      @serializers = serializers
     end
 
-    # @return [Object] the root serializer for serializing the result value.
-    attr_reader :root_serializer
-
     # @return [Hash<Class, Object>] The serializers for converting result values
     #   into serialized data.
     attr_reader :serializers
@@ -30,7 +26,13 @@ module Cuprum::Rails::Responders
     #
     # @return [Object] the serialized data.
     def serialize(object)
-      root_serializer.call(object, serializers: serializers)
+      context = Cuprum::Rails::Serializers::Context.new(
+        serializers: serializers
+      )
+
+      Cuprum::Rails::Serializers::BaseSerializer
+        .instance
+        .call(object, context: context)
     end
   end
 end

data/lib/cuprum/rails/responders.rb

@@ -6,6 +6,7 @@ module Cuprum::Rails
   # Namespace for responders, which process action results into responses.
   module Responders
     autoload :Actions,       'cuprum/rails/responders/actions'
+    autoload :BaseResponder, 'cuprum/rails/responders/base_responder'
     autoload :Html,          'cuprum/rails/responders/html'
     autoload :HtmlResponder, 'cuprum/rails/responders/html_responder'
     autoload :Json,          'cuprum/rails/responders/json'

data/lib/cuprum/rails/responses/head_response.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses'
+
+module Cuprum::Rails::Responses
+  # Encapsulates a response without a response body.
+  class HeadResponse
+    # @param status [Integer] the HTTP status of the response.
+    def initialize(status:)
+      @status = status
+    end
+
+    # @return [Integer] the HTTP status of the response.
+    attr_reader :status
+
+    # Calls the renderer's #head method with the configured status.
+    #
+    # @param renderer [#render] The context for executing the response, such as
+    #   a Rails controller.
+    def call(renderer)
+      renderer.head(status)
+    end
+  end
+end

data/lib/cuprum/rails/responses/html/redirect_back_response.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses/html'
+
+module Cuprum::Rails::Responses::Html
+  # Encapsulates an HTML response that redirects to the previous path.
+  class RedirectBackResponse
+    # @param fallback_location [String] the path or url to redirect to if the
+    #   previous location cannot be determined.
+    # @param flash [Hash] the flash messages to set.
+    # @param status [Integer] the HTTP status of the response.
+    def initialize(fallback_location: '/', flash: {}, status: 302)
+      @fallback_location = fallback_location
+      @flash             = flash
+      @status            = status
+    end
+
+    # @return [String] the path or url to redirect to if the previous location
+    #   cannot be determined.
+    attr_reader :fallback_location
+
+    # @return [Hash] the flash messages to set.
+    attr_reader :flash
+
+    # @return [Integer] the HTTP status of the response.
+    attr_reader :status
+
+    # Calls the renderer's #redirect_back_or_to method with the status.
+    #
+    # @param renderer [#redirect_back_or_to] the context for executing the
+    #   response, such as a Rails controller.
+    def call(renderer)
+      assign_flash(renderer)
+
+      # :nocov:
+      if Rails.version >= '7.0' # @todo Rails 6
+        renderer.redirect_back_or_to(fallback_location, status: status)
+      else
+        renderer.redirect_back(
+          fallback_location: fallback_location,
+          status:            status
+        )
+      end
+      # :nocov:
+    end
+
+    private
+
+    def assign_flash(renderer)
+      flash.each do |key, value|
+        renderer.flash[key] = value
+      end
+    end
+  end
+end