cuprum-rails 0.1.0

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders'
+require 'cuprum/rails/responders/actions'
+require 'cuprum/rails/responders/matching'
+require 'cuprum/rails/responders/serialization'
+require 'cuprum/rails/responses/json_response'
+require 'cuprum/rails/serializers/json'
+
+module Cuprum::Rails::Responders
+  # Provides a DSL for defining responses to JSON requests.
+  #
+  # By default, responds to any successful result by serializing the result
+  # value and generating a JSON object of the form { 'ok' => true, 'data' =>
+  # serialized_value }.
+  #
+  # For a failing result, it generates and serializes a generic error and
+  # generates a JSON object of the form { 'ok' => false, 'data' =>
+  # serialized_error }. This is to prevent leaks of internal states that might
+  # help an adversary access your system. Use the .match class method to define
+  # more useful responses for whitelisted errors.
+  #
+  # @example Defining Error Responses
+  #   class CustomResponder < Cuprum::Rails::Responders::HtmlResponder
+  #     match :failure, error: Spec::NotFound do |result|
+  #       render_failure(result.error, status: 404)
+  #     end
+  #
+  #     match :failure, error: Spec::AuthorizationFailure do
+  #       error = Cuprum::Error.new(message: "I can't let you do that, Dave")
+  #
+  #       render_failure(error, status: 403)
+  #     end
+  #   end
+  class JsonResponder
+    include Cuprum::Rails::Responders::Matching
+    include Cuprum::Rails::Responders::Actions
+    include Cuprum::Rails::Responders::Serialization
+
+    GENERIC_ERROR = Cuprum::Error.new(
+      message: 'Something went wrong when processing the request'
+    ).freeze
+    private_constant :GENERIC_ERROR
+
+    match :success do |result|
+      render_success(result.value)
+    end
+
+    match :failure do
+      render_failure(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
+    #   action. This will be matched before any of the generic matchers.
+    # @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( # rubocop:disable Metrics/ParameterLists
+      action_name:,
+      resource:,
+      serializers:,
+      matcher:       nil,
+      member_action: false,
+      **_options
+    )
+      super(
+        action_name:     action_name,
+        matcher:         matcher,
+        member_action:   member_action,
+        resource:        resource,
+        root_serializer: Cuprum::Rails::Serializers::Json::Serializer.instance,
+        serializers:     serializers
+      )
+    end
+
+    # @!method call(result)
+    #   (see Cuprum::Rails::Responders::Actions#call)
+
+    # @return [Symbol] the format of the responder.
+    def format
+      :json
+    end
+
+    # Creates a JsonResponse based on the given data and options.
+    #
+    # @param json [Object] The data to serialize.
+    # @param status [Integer] The HTTP status of the response.
+    #
+    # @return [Cuprum::Rails::Responses::JsonResponse] the response.
+    def render(json, status: 200)
+      Cuprum::Rails::Responses::JsonResponse.new(
+        data:   serialize(json),
+        status: status
+      )
+    end
+
+    # Creates a JsonResponse for a failed result.
+    #
+    # @param error [Cuprum::Error] The error from the failed result.
+    # @param status [Integer] The HTTP status of the response.
+    #
+    # @return [Cuprum::Rails::Responses::JsonResponse] the response.
+    def render_failure(error, status: 500)
+      json = { 'ok' => false, 'error' => error }
+
+      render(json, status: status)
+    end
+
+    # Creates a JsonResponse for a successful result.
+    #
+    # @param value [Object] The value of the successful result.
+    # @param status [Integer] The HTTP status of the response.
+    #
+    # @return [Cuprum::Rails::Responses::JsonResponse] the response.
+    def render_success(value, status: 200)
+      json = { 'ok' => true, 'data' => value }
+
+      render(json, status: status)
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'cuprum/matcher'
+require 'cuprum/matcher_list'
+
+require 'cuprum/rails/responders'
+
+module Cuprum::Rails::Responders
+  # Implements matching an action result to a response clause.
+  module Matching
+    # Provides a DSL for generating response clauses for matching results.
+    module ClassMethods
+      # Creates a match clause that maps a result to a response.
+      #
+      # @param status [Symbol] The status of the result, either :success or
+      #   :failure.
+      # @param error [Class] The class of the result error. If given, the clause
+      #   will only match results with an error that is an instance of this
+      #   class or a subclass.
+      # @param value [Class] The class of the result value. If given, the clause
+      #   will only match results with a value that is an instance of this class
+      #   or a subclass.
+      #
+      # @yield The clause implementation. This block will be called in the
+      #   context of the matcher.
+      # @yieldreturn [#call, #renderer] the response for the action.
+      def match(status, error: nil, value: nil, &block)
+        matcher = @matcher || Cuprum::Matcher.new
+
+        matcher.singleton_class.match(
+          status, error: error, value: value, &block
+        )
+
+        @matcher = matcher
+      end
+
+      # @private
+      def matchers(**_keywords)
+        return [] unless @matcher
+
+        [@matcher]
+      end
+
+      private
+
+      attr_reader :matcher
+    end
+
+    # @private
+    def self.included(other)
+      super
+
+      other.extend(ClassMethods)
+    end
+
+    # @param action_name [String, Symbol] The name of the action to match.
+    # @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
+    #   item, not on the collection as a whole.
+    # @param resource [Cuprum::Rails::Resource] The resource for the controller.
+    def initialize(
+      action_name:,
+      resource:,
+      matcher: nil,
+      member_action: false,
+      **_options
+    )
+      @action_name   = action_name
+      @matcher       = matcher
+      @member_action = !!member_action # rubocop:disable Style/DoubleNegation
+      @resource      = resource
+    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
+    #     match) in the given matcher (if any), then the responder class, then
+    #     each ancestor of the responder class in ascending order.
+    # 2.  If a match is not found, checks for a partial match (the result
+    #     status, and either the value or the error match) in the same order.
+    # 3.  If there is still no match found, checks for a generic match (the
+    #     result status matches, and the match clause does not specify either an
+    #     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.
+    #
+    # @raise [Cuprum::Matching::NoMatchError] if none of the response clauses
+    #   match the result.
+    def call(result)
+      @result = result
+
+      Cuprum::MatcherList
+        .new(matchers.map { |matcher| matcher.with_context(self) })
+        .call(result)
+    end
+
+    # @return [Symbol, nil] the format of the responder.
+    def format
+      nil
+    end
+
+    # @return [Boolean] true if the action acts on a collection item, not on the
+    #   collection as a whole.
+    def member_action?
+      @member_action
+    end
+
+    private
+
+    def class_matchers
+      options = matcher_options
+
+      singleton_class
+        .ancestors
+        .select { |ancestor| ancestor < Cuprum::Rails::Responders::Matching }
+        .map { |ancestor| ancestor.matchers(**options) }
+        .flatten
+    end
+
+    def matcher_options
+      {}
+    end
+
+    def matchers
+      return class_matchers if matcher.nil?
+
+      [matcher, *class_matchers]
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders'
+
+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)
+      super(**options)
+
+      @root_serializer = root_serializer
+      @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
+
+    # Converts a result value into a serialized data structure.
+    #
+    # @param object [Object] The object to serialize.
+    #
+    # @return [Object] the serialized data.
+    def serialize(object)
+      root_serializer.call(object, serializers: serializers)
+    end
+  end
+end

data/lib/cuprum/rails/responders.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for responders, which process action results into responses.
+  module Responders
+    autoload :Actions,       'cuprum/rails/responders/actions'
+    autoload :Html,          'cuprum/rails/responders/html'
+    autoload :HtmlResponder, 'cuprum/rails/responders/html_responder'
+    autoload :Json,          'cuprum/rails/responders/json'
+    autoload :JsonResponder, 'cuprum/rails/responders/json_responder'
+    autoload :Matching,      'cuprum/rails/responders/matching'
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses/html'
+
+module Cuprum::Rails::Responses::Html
+  # Encapsulates an HTML response that redirects to a given path.
+  class RedirectResponse
+    # @param path [String] The path or url to redirect to.
+    # @param status [Integer] The HTTP status of the response.
+    def initialize(path, status: 302)
+      @path   = path
+      @status = status
+    end
+
+    # @return [String] the path or url to redirect to.
+    attr_reader :path
+
+    # @return [Integer] the HTTP status of the response.
+    attr_reader :status
+
+    # Calls the renderer's #redirect_to method with the path and status.
+    #
+    # @param renderer [#redirect_to] The context for executing the response,
+    #   such as a Rails controller.
+    def call(renderer)
+      renderer.redirect_to(path, status: status)
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses/html'
+
+module Cuprum::Rails::Responses::Html
+  # Encapsulates an HTML response that renders a given template.
+  class RenderResponse
+    # @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.
+    def initialize(template, assigns: {}, layout: nil, status: 200)
+      @assigns  = assigns
+      @layout   = layout
+      @status   = status
+      @template = template
+    end
+
+    # @return [Hash] variables to assign when rendering the template.
+    attr_reader :assigns
+
+    # @return [String] the layout to render.
+    attr_reader :layout
+
+    # @return [Integer] the HTTP status of the response.
+    attr_reader :status
+
+    # @return [String, Symbol] the template to render.
+    attr_reader :template
+
+    # Calls the renderer's #render method with the template and parameters.
+    #
+    # @param renderer [#render] The context for executing the response, such as
+    #   a Rails controller.
+    def call(renderer)
+      assign_variables(renderer)
+
+      options = { status: status }
+      options[:layout] = layout if layout
+
+      renderer.render(template, **options)
+    end
+
+    private
+
+    def assign_variables(renderer)
+      assigns.each do |key, value|
+        renderer.instance_variable_set("@#{key}", value)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses'
+
+module Cuprum::Rails::Responses
+  # Namespace for response objects, which encapsulate Html responses.
+  module Html
+    autoload :RedirectResponse, 'cuprum/rails/responses/html/redirect_response'
+    autoload :RenderResponse,   'cuprum/rails/responses/html/render_response'
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses'
+
+module Cuprum::Rails::Responses
+  # Encapsulates a JSON response that returns the given serialized data.
+  class JsonResponse
+    # @param data [Object] The JSON data to return.
+    # @param status [Integer] The HTTP status of the response.
+    def initialize(data:, status: 200)
+      @data   = data
+      @status = status
+    end
+
+    # @return [Object] the JSON data to return.
+    attr_reader :data
+
+    # @return [Integer] the HTTP status of the response.
+    attr_reader :status
+
+    # Calls the renderer's #render method with the serialized data and status.
+    #
+    # @param renderer [#render] The context for executing the response, such as
+    #   a Rails controller.
+    def call(renderer)
+      renderer.render(json: data, status: status)
+    end
+  end
+end

data/lib/cuprum/rails/responses.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for response objects, which encapsulate server responses.
+  module Responses
+    autoload :Html,         'cuprum/rails/responses/html'
+    autoload :JsonResponse, 'cuprum/rails/responses/json_response'
+  end
+end

data/lib/cuprum/rails/routes.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Represent the routes available for a given resource.
+  class Routes
+    # Error class when a wildcard value is missing for a route.
+    class MissingWildcardError < StandardError; end
+
+    class << self
+      # Defines a route for the resource routes.
+      #
+      # Each defined route creates a helper method on the routes, which returns
+      # the full path of the resource route. A member action helper (if the
+      # path ends in an :id wildcard) will require passing in either the primary
+      # key of the member or the member entity.
+      #
+      # If the base path includes wildcards, then the wildcards must be set
+      # (using #with_wildcards) before calling a route helper.
+      #
+      # @param action_name [String, Symbol] The name of the action.
+      # @param path [String] The path of the action relative to the resource
+      #   root. If the path has a leading slash, the path is treated as an
+      #   absolute path and does not include the routes base path.
+      def route(action_name, path)
+        validate_action_name!(action_name)
+        validate_path!(path)
+
+        if member_route?(path)
+          define_member_route(action_name, path)
+        else
+          define_collection_route(action_name, path)
+        end
+      end
+
+      private
+
+      def define_collection_route(action_name, original_path)
+        define_method :"#{action_name}_path" do
+          path = resolve_base_path(original_path)
+
+          insert_wildcards(path)
+        end
+      end
+
+      def define_member_route(action_name, original_path)
+        define_method :"#{action_name}_path" do |entity|
+          path = resolve_base_path(original_path)
+
+          insert_wildcards(path, entity)
+        end
+      end
+
+      def member_route?(path)
+        path.split('/').include?(':id')
+      end
+
+      def validate_action_name!(action_name)
+        unless action_name.is_a?(String) || action_name.is_a?(Symbol)
+          raise ArgumentError,
+            'action_name must be a String or Symbol',
+            caller(1..-1)
+        end
+
+        return unless action_name.to_s.empty?
+
+        raise ArgumentError, "action_name can't be blank", caller(1..-1)
+      end
+
+      def validate_path!(path)
+        return if path.is_a?(String) || path.is_a?(Symbol)
+
+        raise ArgumentError, 'path must be a String or Symbol', caller(1..-1)
+      end
+    end
+
+    # @param base_path [String] The relative path of the resource.
+    def initialize(base_path:, &block)
+      @base_path = base_path
+      @wildcards = {}
+
+      singleton_class.instance_exec(&block) if block_given?
+    end
+
+    # @return [String] the relative path of the resource.
+    attr_reader :base_path
+
+    # @return [String] the url wildcards for the resource.
+    attr_reader :wildcards
+
+    # @return [String] the path to the parent resource index.
+    def parent_path
+      root_path
+    end
+
+    # @return [String] the root path for the application.
+    def root_path
+      '/'
+    end
+
+    # @param wildcards [Hash] The wildcards to use with the routes.
+    #
+    # @return [Cuprum::Rails::Routes] a copy of the routes with the wildcards.
+    def with_wildcards(wildcards)
+      unless wildcards.is_a?(Hash)
+        raise ArgumentError, 'wildcards must be a Hash'
+      end
+
+      clone.apply_wildcards(wildcards)
+    end
+
+    protected
+
+    def apply_wildcards(wildcards)
+      @wildcards = wildcards.stringify_keys
+
+      self
+    end
+
+    private
+
+    def insert_wildcards(path, entity = nil)
+      path
+        .split('/')
+        .map do |segment|
+          next segment unless segment.start_with?(':')
+
+          next resolve_primary_key(entity) if segment == ':id'
+
+          resolve_wildcard(segment)
+        end
+        .join('/')
+    end
+
+    def resolve_base_path(path)
+      return path if path.start_with?('/')
+
+      return base_path if path.empty?
+
+      "#{base_path}/#{path}"
+    end
+
+    def resolve_primary_key(entity)
+      raise MissingWildcardError, 'missing wildcard :id' if entity.nil?
+
+      primary_key = entity.class.primary_key
+
+      entity[primary_key]
+    end
+
+    def resolve_wildcard(segment)
+      wildcard = segment[1..] # :something_id to something_id
+
+      return wildcards[wildcard] if wildcards.include?(wildcard)
+
+      wildcard = segment[1...-3] # :something_id to something
+
+      if wildcards.include?(wildcard)
+        return resolve_primary_key(wildcards[wildcard])
+      end
+
+      raise MissingWildcardError, "missing wildcard #{segment}"
+    end
+  end
+end

data/lib/cuprum/rails/routing/plural_routes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/routing'
+
+module Cuprum::Rails::Routing
+  # Routes object with predefined routes for a RESTful resource.
+  #
+  # The following route helpers are defined:
+  #
+  # - #create_path  => '/' or '/path/to/resource/'
+  # - #destroy_path => '/:id' or '/path/to/resource/:id'
+  # - #edit_path    => '/:id/edit' or '/path/to/resource/:id/edit'
+  # - #index_path   => '/' or '/path/to/resource/'
+  # - #new_path     => '/new' or '/path/to/resource/new'
+  # - #show_path    => '/:id/edit' or '/path/to/resource/:id/edit'
+  # - #update_path  => '/:id/edit' or '/path/to/resource/:id/edit'
+  class PluralRoutes < Cuprum::Rails::Routes
+    route :create,  ''
+    route :destroy, ':id'
+    route :edit,    ':id/edit'
+    route :index,   ''
+    route :new,     'new'
+    route :show,    ':id'
+    route :update,  ':id'
+  end
+end

data/lib/cuprum/rails/routing/singular_routes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/routing'
+
+module Cuprum::Rails::Routing
+  # Routes object with predefined routes for a singular RESTful resource.
+  #
+  # The following route helpers are defined:
+  #
+  # - #create_path  => '/' or '/path/to/resource/'
+  # - #destroy_path => '/' or '/path/to/resource/'
+  # - #edit_path    => '/edit' or '/path/to/resource/edit'
+  # - #new_path     => '/new' or '/path/to/resource/new'
+  # - #show_path    => '/' or '/path/to/resource/'
+  # - #update_path  => '/' or '/path/to/resource/'
+  class SingularRoutes < Cuprum::Rails::Routes
+    route :create,  ''
+    route :destroy, ''
+    route :edit,    'edit'
+    route :new,     'new'
+    route :show,    ''
+    route :update,  ''
+  end
+end

data/lib/cuprum/rails/routing.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for routing-specific functionality.
+  module Routing
+    autoload :PluralRoutes,   'cuprum/rails/routing/plural_routes'
+    autoload :SingularRoutes, 'cuprum/rails/routing/singular_routes'
+  end
+end