cuprum-rails 0.1.0

data/lib/cuprum/rails/repository.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/repository'
+
+require 'cuprum/rails'
+require 'cuprum/rails/collection'
+
+module Cuprum::Rails
+  # A repository represents a group of Rails collections.
+  class Repository < Cuprum::Collections::Repository
+    # Adds a new collection with the given name to the repository.
+    #
+    # @param record_class [Class] The ActiveRecord class for the collection.
+    # @param options [Hash] Additional options to pass to Collection.new
+    #
+    # @return [Cuprum::Rails::Collection] the created collection.
+    #
+    # @see Cuprum::Rails::Collection#initialize.
+    def build(record_class:, **options)
+      validate_record_class!(record_class)
+
+      collection = Cuprum::Rails::Collection.new(
+        record_class: record_class,
+        **options
+      )
+
+      add(collection)
+
+      collection
+    end
+
+    private
+
+    def valid_collection?(collection)
+      collection.is_a?(Cuprum::Rails::Collection)
+    end
+
+    def validate_record_class!(record_class)
+      return if record_class.is_a?(Class) && record_class < ActiveRecord::Base
+
+      raise ArgumentError, 'record class must be an ActiveRecord model'
+    end
+  end
+end

data/lib/cuprum/rails/request.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Wraps a web request with a generic interface.
+  class Request
+    class << self
+      FILTERED_HEADER_PREFIXES = %w[
+        action_
+        puma
+        rack
+      ].freeze
+      private_constant :FILTERED_HEADER_PREFIXES
+
+      FILTERED_PARAMS = %w[controller action].freeze
+      private_constant :FILTERED_PARAMS
+
+      # Generates a Request from a native Rails request.
+      #
+      # @param request [] The native request to build.
+      #
+      # @return [Cuprum::Rails::Request] the generated request.
+      def build(request:)
+        new(
+          authorization: request.authorization,
+          body_params:   request.request_parameters,
+          format:        request.format.symbol,
+          headers:       filter_headers(request.headers),
+          method:        request.request_method_symbol,
+          params:        filter_params(request.params),
+          path:          request.fullpath,
+          query_params:  request.query_parameters
+        )
+      end
+
+      private
+
+      def filter_headers(headers)
+        headers.reject do |key, _|
+          FILTERED_HEADER_PREFIXES.any? { |prefix| key.start_with?(prefix) }
+        end
+      end
+
+      def filter_params(params)
+        params.reject { |key, _| FILTERED_PARAMS.include?(key) }
+      end
+    end
+
+    # @param authorization [String, nil] The authorization header, if any.
+    # @param body_params [Hash<String, Object>] The parameters from the request
+    #   body.
+    # @param format [Symbol] The request format, e.g. :html or :json.
+    # @param headers [Hash<String, String>] The request headers.
+    # @param method [Symbol] The HTTP method used for the request.
+    # @param params [Hash<String, Object>] The merged GET and POST parameters.
+    # @param query_params [Hash<String, Object>] The query parameters.
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      body_params:,
+      format:,
+      headers:,
+      method:,
+      params:,
+      path:,
+      query_params:,
+      authorization: nil
+    )
+      @authorization = authorization
+      @body_params   = body_params
+      @format        = format
+      @headers       = headers
+      @method        = method
+      @path          = path
+      @params        = params
+      @query_params  = query_params
+    end
+
+    # @return [String, nil] the authorization header, if any.
+    attr_reader :authorization
+
+    # @return [Hash<String, Object>] The parameters from the request body.
+    attr_reader :body_params
+    alias body_parameters body_params
+
+    # @return [Symbol] the request format, e.g. :html or :json.
+    attr_reader :format
+
+    # @return [Hash<String, String>] the request headers.
+    attr_reader :headers
+
+    # @return [Symbol] the HTTP method used for the request.
+    attr_reader :method
+
+    # @return [Hash<String, Object>] The merged GET and POST parameters.
+    attr_reader :params
+    alias parameters params
+
+    # @return [String] the relative path of the request, including params.
+    attr_reader :path
+
+    # @return [Hash<String, Object>] the query parameters.
+    attr_reader :query_params
+    alias query_parameters query_params
+  end
+end

data/lib/cuprum/rails/resource.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Value object representing a controller resource.
+  class Resource
+    # @param collection [Cuprum::Collections::Base] Collection representing the
+    #   resource data.
+    # @param options [Hash] Additional options for the resource.
+    # @param resource_class [Class] Class representing the resource items.
+    # @param resource_name [String] The name of the resource.
+    # @param routes [Cuprum::Rails::Routes] The routes defined for the resource.
+    # @param singular [Boolean] Indicates that the resource is a singular
+    #   collection, and has only one member.
+    #
+    # @option options default_order [Hash] The default ordering for the resource
+    #   items.
+    # @option options permitted_attributes [Array] List of attributes that can
+    #   be set or changed by resourceful actions.
+    # @option options primary_key [String, Symbol] The name of the primary key
+    #   for the resource, if any.
+    # @option options singular_resource_name [String] The singular form of the
+    #   resource name.
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      collection:     nil,
+      resource_class: nil,
+      resource_name:  nil,
+      routes:         nil,
+      singular:       false,
+      **options
+    )
+      unless resource_class || resource_name
+        raise ArgumentError, 'missing keyword :resource_class or :resource_name'
+      end
+
+      validate_permitted_attributes(options[:permitted_attributes])
+
+      @collection     = collection
+      @options        = options
+      @resource_class = resource_class
+      @resource_name  = resource_name.to_s unless resource_name.nil?
+      @routes         = routes
+      @singular       = !!singular
+    end
+
+    # @return [Cuprum::Collections::Base] collection representing the resource
+    #   data.
+    attr_reader :collection
+
+    # @return [Hash] additional options for the resource.
+    attr_reader :options
+
+    # @return [Class] class representing the resource items.
+    attr_reader :resource_class
+
+    # @return [String] the base url for the resource.
+    def base_path
+      @base_path ||=
+        options
+          .fetch(:base_path) { "/#{resource_name.underscore}" }
+          .to_s
+    end
+
+    # @return [Hash] the default ordering for the resource items.
+    def default_order
+      @default_order ||= options.fetch(:default_order, {})
+    end
+
+    # @return [Array] list of attributes that can be set or changed by
+    #   resourceful actions.
+    def permitted_attributes
+      @permitted_attributes ||= options.fetch(:permitted_attributes, nil)
+    end
+
+    # @return [Boolean] true if the collection is a plural collection, otherwise
+    #   false.
+    def plural?
+      !@singular
+    end
+
+    # @return [String] the name of the primary key for the resource, if any.
+    def primary_key
+      @primary_key ||=
+        options
+          .fetch(:primary_key) { resource_class&.primary_key }
+          .yield_self { |value| value.nil? ? nil : value.to_s }
+    end
+
+    # @return [String] the name of the resource.
+    def resource_name
+      return @resource_name if @resource_name
+
+      name = resource_class.name.split('::').last.underscore
+
+      @resource_name = plural? ? name.pluralize : name
+    end
+
+    # Generates the routes for the resource and injects the given wildcards.
+    #
+    # @param wildcards [Hash] The wildcard values to use in the routes.
+    #
+    # @return [Cuprum::Rails::Routes] the routes with injected wildcards.
+    def routes(wildcards: {})
+      routes_without_wildcards.with_wildcards(wildcards)
+    end
+
+    # @return [Boolean] true if the collection is a singular collection,
+    #   otherwise false.
+    def singular?
+      @singular
+    end
+
+    # @return [String] the singular form of the resource name.
+    def singular_resource_name
+      @singular_resource_name ||=
+        options
+          .fetch(:singular_resource_name) do
+            resource_name.singularize
+          end
+          .to_s
+    end
+
+    def validate_permitted_attributes(attributes)
+      return if attributes.nil? || attributes.is_a?(Array)
+
+      raise ArgumentError,
+        'keyword :permitted_attributes must be an Array or nil',
+        caller(1..-1)
+    end
+
+    private
+
+    def routes_without_wildcards
+      return @routes if @routes
+
+      @routes =
+        if plural?
+          Cuprum::Rails::Routing::PluralRoutes.new(base_path: base_path)
+        else
+          Cuprum::Rails::Routing::SingularRoutes.new(base_path: base_path)
+        end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'cuprum/matcher'
+
+require 'cuprum/rails/responders'
+
+module Cuprum::Rails::Responders
+  # Implements matching a result to action-specific response clauses.
+  module Actions
+    # Provides a DSL for generating action-specific response clauses.
+    module ClassMethods
+      # Creates a new response matcher specific to the specified action.
+      #
+      # @param action_name [String, Symbol] The name of the action.
+      #
+      # @yield The matcher definition.
+      def action(action_name, &block)
+        validate_action_name!(action_name)
+
+        actions[action_name.intern] = Cuprum::Matcher.new(&block)
+
+        nil
+      end
+
+      # @private
+      def actions
+        @actions ||= {}
+      end
+
+      # @private
+      def matchers(action_name: nil, **_keywords)
+        return super unless action_name
+
+        action = actions[action_name.intern]
+
+        action.nil? ? super : [action, *super]
+      end
+
+      private
+
+      def validate_action_name!(action_name)
+        if action_name.nil? || action_name.to_s.empty?
+          raise ArgumentError, "action name can't be blank", caller(1..-1)
+        end
+
+        return if action_name.is_a?(String) || action_name.is_a?(Symbol)
+
+        raise ArgumentError, 'action name must be a String or Symbol',
+          caller(1..-1)
+      end
+    end
+
+    # @!method call(result)
+    #   (see Cuprum::Rails::Responders::Matching#call)
+    #
+    #   If the responder defines an action matcher that matches the given action
+    #   name, that matcher is matched against the result before any match
+    #   clauses defined directly on the responder.
+
+    # @private
+    def self.included(other)
+      super
+
+      other.extend(ClassMethods)
+    end
+
+    private
+
+    def matcher_options
+      super().merge(action_name: action_name)
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/failed_validation'
+
+require 'cuprum/rails/responders/html'
+
+module Cuprum::Rails::Responders::Html
+  # Defines default responses for a plural RESTful resource.
+  #
+  # - #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.
+  #
+  # 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 either the show page or the index page for the
+  # resource, based on the resource's defined #routes.
+  class PluralResource < 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
+        entity = result.value[resource.singular_resource_name]
+
+        redirect_to resource.routes.show_path(entity)
+      end
+    end
+
+    action :destroy do
+      match :success do
+        redirect_to resource.routes.index_path
+      end
+    end
+
+    action :index do
+      match :failure do
+        redirect_to resource.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
+        entity = result.value[resource.singular_resource_name]
+
+        redirect_to resource.routes.show_path(entity)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# 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 singular RESTful resource.
+  #
+  # - #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.
+  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)
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders'
+
+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 :SingularResource, 'cuprum/rails/responders/html/singular_resource'
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responses/html/redirect_response'
+require 'cuprum/rails/responders'
+require 'cuprum/rails/responders/actions'
+require 'cuprum/rails/responders/matching'
+
+module Cuprum::Rails::Responders
+  # Provides a DSL for defining responses to HTML requests.
+  #
+  # By default, responds to any successful result by rendering the template for
+  # the action name and passing the result value as assigned variables. For a
+  # failing result, redirects to either the show page or the index page for the
+  # resource, based on the resource's defined #routes.
+  #
+  # @example Defining A Response
+  #   class CustomResponder < Cuprum::Rails::Responders::HtmlResponder
+  #     match :failure, error: Spec::AuthorizationError do
+  #       redirect_to('/login')
+  #     end
+  #   end
+  #
+  # @example Defining Responses For An Action
+  #   class ActionsResponder < Cuprum::Rails::Responders::HtmlResponder
+  #     action :publish do
+  #       match :failure do
+  #         redirect_to(resource.routes.index_path)
+  #       end
+  #
+  #       match :success do
+  #         redirect_to(resource.routes.show_path(@result.value))
+  #       end
+  #     end
+  #   end
+  #
+  # @see Cuprum::Rails::Responders::Actions::ClassMethods#action
+  # @see Cuprum::Rails::Responders::Matching::ClassMethods#match
+  class HtmlResponder
+    include Cuprum::Rails::Responders::Matching
+    include Cuprum::Rails::Responders::Actions
+
+    match :success do
+      render action_name
+    end
+
+    match :failure do
+      next redirect_to(resource.base_path) unless resource.routes
+
+      path = resource_path(result) || resource.routes.index_path
+
+      redirect_to(path)
+    end
+
+    # @!method call(result)
+    #   (see Cuprum::Rails::Responders::Actions#call)
+
+    # @return [Symbol] the format of the responder.
+    def format
+      :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]
+      else
+        result.value
+      end
+    end
+
+    def resource_path(result)
+      return resource.routes.index_path if result.value.nil?
+
+      entity = resource_entity
+
+      return resource.routes.show_path(entity) if entity
+
+      resource.routes.index_path
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/already_exists'
+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/responders/json'
+require 'cuprum/rails/responders/json_responder'
+
+module Cuprum::Rails::Responders::Json
+  # Defines default responses for a RESTful resource.
+  #
+  # - #create success: serializes the data with status 201 Created.
+  # - failure AlreadyExists: serializes the error with status 422 Unprocessable
+  #     Entity.
+  # - failure ExtraAttributes: serializes the error with status 422
+  #     Unprocessable Entity.
+  # - failure FailedValidation: serializes the error with status 422
+  #     Unprocessable Entity.
+  # - failure MissingParameters: serializes the error with status 400 Bad
+  #     Request.
+  # - failure NotFound: serializes the error with status 404 Not Found.
+  #
+  # Responds to any other successful result by serializing the result value with
+  # status 200. For a failing result, serializes a generic error with status
+  # 500 Internal Server Error.
+  class Resource < Cuprum::Rails::Responders::JsonResponder
+    action :create do
+      match :success do |result|
+        render_success(result.value, status: 201)
+      end
+    end
+
+    match :failure, error: Cuprum::Collections::Errors::AlreadyExists \
+    do |result|
+      render_failure(result.error, status: 422)
+    end
+
+    match :failure, error: Cuprum::Collections::Errors::ExtraAttributes \
+    do |result|
+      render_failure(result.error, status: 422)
+    end
+
+    match :failure, error: Cuprum::Collections::Errors::FailedValidation \
+    do |result|
+      render_failure(result.error, status: 422)
+    end
+
+    match :failure, error: Cuprum::Collections::Errors::NotFound \
+    do |result|
+      render_failure(result.error, status: 404)
+    end
+
+    match :failure, error: Cuprum::Rails::Errors::MissingParameters do |result|
+      render_failure(result.error, status: 400)
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders'
+
+module Cuprum::Rails::Responders
+  # Namespace for JSON responders, which process action results into responses.
+  module Json
+    autoload :Resource, 'cuprum/rails/responders/json/resource'
+  end
+end