cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/actions/middleware/log_request.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions/middleware'
+
+module Cuprum::Rails::Actions::Middleware
+  # Configurable middleware for logging controller requests.
+  class LogRequest < Cuprum::Command
+    include Cuprum::Middleware
+
+    DEFAULT_CONFIGURATION = {
+      authorization: false,
+      headers:       false,
+      repository:    false,
+      resource:      false
+    }.freeze
+    private_constant :DEFAULT_CONFIGURATION
+
+    REQUEST_PROPERTIES = %i[
+      action_name
+      authorization
+      body_params
+      controller_name
+      format
+      headers
+      http_method
+      params
+      path
+      path_params
+      query_params
+    ].freeze
+    private_constant :REQUEST_PROPERTIES
+
+    # @param config [Hash] request and environment properties to log. A value of
+    #   false will disable logging for that property.
+    #
+    # @option config action_name [Boolean] if true, logs the name of the action.
+    #   Defaults to true.
+    # @option config authorization [Boolean] if true, logs the value of the
+    #   authorization header. Defaults to false.
+    # @option config body_params [Boolean] if true, logs the parameters from the
+    #   request body. Defaults to true.
+    # @option config controller_name [Boolean] if true, logs the name of the
+    #   controller. Defaults to true.
+    # @option config format [Boolean] if true, logs the request format. Defaults
+    #   to true.
+    # @option config headers [Boolean] if true, logs the headers. Defaults to
+    #   false.
+    # @option config http_methopd [Boolean] if true, logs the request HTTP
+    #   method. Defaults to true.
+    # @option config params [Boolean] if true, logs the request parameters.
+    #   Defaults to true.
+    # @option config path [Boolean] if true, logs the request path. Defaults to
+    #   true.
+    # @option config path_params [Boolean] if true, logs the parameters from the
+    #   request path. Defaults to true.
+    # @option config query_params [Boolean] if true, logs the parameters from
+    #   the url query. Defaults to true.
+    # @option config repository [Boolean] if true, logs the repository used in
+    #   the request. Defaults to false.
+    # @option config resource [Boolean] if true, logs the resource used in the
+    #   request. Defaults to false.
+    def initialize(**config)
+      super()
+
+      @config = DEFAULT_CONFIGURATION.merge(config)
+    end
+
+    # @return [Hash] request and environment properties to log.
+    attr_reader :config
+
+    private
+
+    def format_log(request:, **options)
+      msg = +"  #{self.class.name}#process"
+
+      logged_properties(request: request, **options).each do |label, formatted|
+        msg << "\n    #{label}\n"
+        msg << tools.string_tools.indent(formatted, 6)
+      end
+
+      msg
+    end
+
+    def log_property?(name)
+      config.fetch(name.intern, true)
+    end
+
+    def logged_properties(request:, repository: nil, resource: nil, **options)
+      hsh = {}
+
+      if log_property?(:command_options) && options.present?
+        hsh['Command Options'] = options.pretty_inspect
+      end
+
+      if log_property?(:repository)
+        hsh['Repository'] = repository.pretty_inspect
+      end
+
+      hsh['Resource'] = resource.pretty_inspect if log_property?(:resource)
+
+      hsh.merge(request_properties(request: request))
+    end
+
+    def process(next_command, request:, **options)
+      Rails.logger.info format_log(request: request, **options)
+
+      next_command.call(request: request, **options)
+    end
+
+    def request_properties(request:)
+      hsh = {}
+
+      REQUEST_PROPERTIES.each do |key|
+        next unless log_property?(key)
+
+        hsh[key.to_s.titleize] = request.send(key).pretty_inspect
+      end
+
+      hsh
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/rails/actions/middleware/log_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions/middleware'
+
+module Cuprum::Rails::Actions::Middleware
+  # Middleware for logging controller action results.
+  class LogResult < Cuprum::Command
+    include Cuprum::Middleware
+
+    private
+
+    def format_log(result:)
+      msg = +"  #{self.class.name}#process"
+
+      logged_properties(result: result).each do |label, formatted|
+        msg << "\n    #{label}\n"
+        msg << tools.string_tools.indent(formatted, 6)
+      end
+
+      msg
+    end
+
+    def logged_properties(result:)
+      hsh = {
+        status: result.status,
+        value:  result.value,
+        error:  result.error
+      }
+
+      hsh
+        .merge(result.properties.except(:status, :value, :error))
+        .to_h { |key, value| [key.to_s.titleize, value.pretty_inspect] }
+    end
+
+    def process(next_command, **options)
+      result = next_command.call(**options)
+
+      if result.success?
+        Rails.logger.info format_log(result: result)
+      else
+        Rails.logger.error format_log(result: result)
+      end
+
+      result
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/rails/actions/middleware/resources/find.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions/middleware/resources'
+require 'cuprum/rails/actions/middleware/resources/query'
+
+module Cuprum::Rails::Actions::Middleware::Resources
+  # Middleware for querying a resource.
+  class Find < Cuprum::Rails::Actions::Middleware::Resources::Query
+    # @param only_form_actions [Boolean] if true, does not query the resource
+    #   for non-GET success results. Defaults to false.
+    # @param resource_params [Hash] parameters to pass to the resource.
+    def initialize(only_form_actions: false, **resource_params)
+      super(**resource_params)
+
+      @only_form_actions = !!only_form_actions
+    end
+
+    # @return [Boolean] if true, does not query the resource for non-GET success
+    #   results.
+    def only_form_actions?
+      @only_form_actions
+    end
+
+    private
+
+    def process(next_command, **)
+      super
+
+      return result if skip_query?
+
+      values = step { perform_query }
+
+      merge_result(result: result, values: values)
+    end
+
+    def skip_query?
+      return false unless only_form_actions?
+
+      return false if request.http_method.to_s.downcase == 'get'
+
+      result.success?
+    end
+  end
+end

data/lib/cuprum/rails/actions/middleware/resources/query.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands/associations/find_many'
+
+require 'cuprum/rails/actions/middleware/resources'
+require 'cuprum/rails/result'
+
+module Cuprum::Rails::Actions::Middleware::Resources
+  # Abstract middleware for performing a resource query.
+  class Query < Cuprum::Rails::Action
+    include Cuprum::Middleware
+
+    # @param resource_params [Hash] parameters to pass to the resource.
+    def initialize(**resource_params)
+      super()
+
+      @resource = build_resource(**resource_params)
+    end
+
+    # @return [Cuprum::Collections::Resource] the resource.
+    attr_reader :resource
+
+    private
+
+    attr_reader :repository
+
+    attr_reader :request
+
+    attr_reader :result
+
+    def build_resource(**params)
+      Cuprum::Collections::Resource.new(**params)
+    end
+
+    def collection
+      repository.find_or_create(
+        name:           resource.name,
+        qualified_name: resource.qualified_name
+      )
+    end
+
+    def merge_result(result:, values:)
+      return result unless result.value.is_a?(Hash)
+
+      Cuprum::Rails::Result.new(
+        **result.properties,
+        value: merge_values(
+          value:  result.value,
+          values: values
+        )
+      )
+    end
+
+    def merge_values(value:, values:)
+      key = pluralize_name(resource: resource, values: values)
+
+      value.merge(key => values)
+    end
+
+    def pluralize_name(resource:, values:)
+      values.is_a?(Array) ? resource.plural_name : resource.singular_name
+    end
+
+    def process(next_command, repository:, request:, **rest)
+      @repository = repository
+      @request    = request
+      @result     = next_command.call(
+        repository: repository,
+        request:    request,
+        resource:   resource,
+        **rest
+      )
+    end
+
+    def perform_query
+      if resource.singular?
+        values = step { query_command.call(limit: 1) }
+
+        success(values.first)
+      else
+        values = step { query_command.call }
+
+        success(values.to_a)
+      end
+    end
+
+    def query_command
+      collection.find_matching
+    end
+  end
+end

data/lib/cuprum/rails/actions/middleware/resources.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions/middleware'
+
+module Cuprum::Rails::Actions::Middleware
+  # Namespace for resource middleware.
+  module Resources
+    autoload :Find,  'cuprum/rails/actions/middleware/resources/find'
+    autoload :Query, 'cuprum/rails/actions/middleware/resources/query'
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+
+module Cuprum::Rails::Actions
+  # Namespace for action middleware, which wraps controller actions.
+  module Middleware
+    autoload :Associations, 'cuprum/rails/actions/middleware/associations'
+    autoload :LogRequest,   'cuprum/rails/actions/middleware/log_request'
+    autoload :LogResult,    'cuprum/rails/actions/middleware/log_result'
+    autoload :Resources,    'cuprum/rails/actions/middleware/resources'
+  end
+end

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

@@ -8,12 +8,24 @@ module Cuprum::Rails::Actions
   class New < Cuprum::Rails::Actions::ResourceAction
     private
 
-    def process(request:)
-      super
+    attr_reader :entity
+
+    def build_entity
+      collection.build_one.call(attributes: {})
+    end
+
+    def build_response
+      { resource.singular_name => entity }
+    end
+
+    def perform_action
+      @entity = step { build_entity }
+    end
 
-      instance = step { collection.build_one.call(attributes: {}) }
+    def process(**)
+      @entity = nil
 
-      { singular_resource_name => instance }
+      super
     end
   end
 end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/constraints/parameters_contract'
+
+module Cuprum::Rails::Actions
+  # Mixin for adding parameter validation to an Action.
+  module ParameterValidation
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to extend when including the mixin.
+    module ClassMethods
+      # @overload validate_parameters(contract)
+      #   Sets the contract to automatically validate the request parameters.
+      #
+      #   @param contract [Stannum::Contract] the contract used to validate the
+      #     request parameters.
+      #
+      # @overload validate_parameters(&block)
+      #   Defines a contract to automatically validate the request parameters.
+      #
+      #   @yield Used to create an indifferent hash contract to validate the
+      #     request parameters.
+      def validate_parameters(contract = nil, &block)
+        contract ||= Cuprum::Rails::Constraints::ParametersContract.new(&block)
+
+        define_method(:parameters_contract) { contract }
+      end
+    end
+
+    private
+
+    def parameters_contract
+      nil
+    end
+
+    def process(request:, **)
+      super
+
+      return unless validate_parameters?
+
+      step { validate_parameters(parameters_contract) }
+    end
+
+    def validate_parameters(contract)
+      match, errors = contract.match(params)
+
+      return success(nil) if match
+
+      error = Cuprum::Rails::Errors::InvalidParameters.new(errors: errors)
+      failure(error)
+    end
+
+    def validate_parameters?
+      !parameters_contract.nil?
+    end
+  end
+end

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

@@ -1,75 +1,152 @@
 # frozen_string_literal: true
 
-require 'forwardable'
+require 'cuprum/errors/uncaught_exception'
 
-require 'cuprum/rails/actions'
-require 'cuprum/rails/errors/missing_parameters'
-require 'cuprum/rails/errors/missing_primary_key'
-require 'cuprum/rails/errors/undefined_permitted_attributes'
+require 'cuprum/rails/action'
+require 'cuprum/rails/actions/parameter_validation'
+require 'cuprum/rails/errors/resource_error'
 
 module Cuprum::Rails::Actions
   # Abstract base class for resourceful actions.
+  #
+  # Each ResourceAction defines a series of steps used to validate and process
+  # the action. Each step is performed in order:
+  #
+  # - The #find_required_entities step locates any dependent entities and
+  #   ensures that the entities exist. For example, it may find the requested
+  #   entity for a show action, or the parent entity for a create action on a
+  #   nested resource.
+  # - The #perform_action step contains the core logic of the action. For
+  #   example, in a destroy action it would take the entity (located in the
+  #   previous step) and remove it from the collection.
+  # - The #build_response step generates the result returned by a successful
+  #   request. For example, for a show action on a nested resource, it might
+  #   build a passing result with both the requested and parent resources.
+  #
+  # If any of the steps fail, either by returning a failing result or by raising
+  # an exception, the action will immediately stop execution and return the
+  # result, or wrap the exception in a failing result with a
+  # Cuprum::Errors::UncaughtException error.
   class ResourceAction < Cuprum::Rails::Action
-    extend Forwardable
-
-    # @param resource [Cuprum::Rails::Resource] The controller resource.
-    def initialize(resource:)
-      if resource.collection.nil?
-        raise ArgumentError, 'resource must have a collection'
-      end
-
-      super
+    include Cuprum::Rails::Actions::ParameterValidation
+
+    # @!method call(request:, resource:, repository: nil, **options)
+    #   Performs the controller action.
+    #
+    #   Subclasses should implement a #process method with the :request keyword,
+    #   which accepts an ActionDispatch::Request instance.
+    #
+    #   @param request [ActionDispatch::Request] the Rails request.
+    #   @param resource [Cuprum::Rails::Resource] the controller resource.
+    #   @param repository [Cuprum::Collections::Repository] the repository
+    #     containing the data collections for the application or scope.
+    #   @param options [Hash<Symbol, Object>] additional options for the action.
+    #
+    #   @return [Cuprum::Result] the result of the action.
+
+    # @return [Cuprum::Rails::Collection] the collection for the resource class.
+    def collection
+      @collection ||= repository.find_or_create(
+        qualified_name: resource.qualified_name
+      )
     end
 
-    def_delegators :@resource,
-      :collection,
-      :resource_name,
-      :singular_resource_name
+    # @return [Cuprum::Rails::Resource] the controller resource.
+    attr_reader :resource
 
     # @return [Object] the primary key for the resource.
     def resource_id
-      return success(params[:id]) if params[:id].present?
-
-      failure(missing_primary_key_error)
+      @resource_id ||= params['id']
     end
 
     # @return [Hash] the permitted params for the resource.
     def resource_params
-      return failure(permitted_attributes_error) unless permitted_attributes?
+      return @resource_params if @resource_params
+
+      resource_params = params.fetch(resource.singular_name, {})
 
-      success(raw_resource_params)
-    rescue ActionController::ParameterMissing
-      failure(missing_parameters_error)
+      return resource_params unless resource_params.is_a?(Hash)
+
+      @resource_params =
+        resource_params
+          .select { |key, _| permitted_attributes.include?(key) }
+          .to_h
     end
 
     private
 
-    def missing_parameters_error
-      Cuprum::Rails::Errors::MissingParameters
-        .new(resource_name: singular_resource_name)
+    def build_response
+      Cuprum::Result.new(status: :success)
     end
 
-    def missing_primary_key_error
-      Cuprum::Rails::Errors::MissingPrimaryKey.new(
-        primary_key:   resource.primary_key,
-        resource_name: singular_resource_name
+    def find_required_entities; end
+
+    def handle_exceptions
+      yield
+    rescue StandardError => exception
+      error = Cuprum::Errors::UncaughtException.new(
+        exception: exception,
+        message:   "uncaught exception in #{self.class.name} -"
       )
+      failure(error)
+    end
+
+    def permitted_attributes
+      @permitted_attributes ||=
+        Set.new(resource.permitted_attributes.map(&:to_s))
+    end
+
+    def perform_action; end
+
+    def process(resource:, **rest)
+      @resource        = resource
+      @resource_id     = nil
+      @resource_params = nil
+
+      step { require_permitted_attributes }
+
+      super(**rest)
+
+      handle_exceptions do
+        step { find_required_entities }
+        step { perform_action }
+        step { build_response }
+      end
     end
 
-    def permitted_attributes?
-      !resource.permitted_attributes.nil?
+    def require_permitted_attributes
+      return unless require_permitted_attributes?
+
+      return if resource.permitted_attributes.present?
+
+      error = Cuprum::Rails::Errors::ResourceError.new(
+        message:  "permitted attributes can't be blank",
+        resource: resource
+      )
+      failure(error)
     end
 
-    def permitted_attributes_error
-      Cuprum::Rails::Errors::UndefinedPermittedAttributes
-        .new(resource_name: singular_resource_name)
+    def require_permitted_attributes?
+      false
     end
 
-    def raw_resource_params
-      params
-        .require(singular_resource_name)
-        .permit(*resource.permitted_attributes)
-        .to_hash
+    def transaction(&block) # rubocop:disable Metrics/MethodLength
+      result            = nil
+      entity_class      = resource.entity_class
+      transaction_class =
+        if entity_class.is_a?(Class) && entity_class < ActiveRecord::Base
+          entity_class
+        else
+          ActiveRecord::Base
+        end
+
+      transaction_class.transaction do
+        result = steps { block.call }
+
+        raise ActiveRecord::Rollback if result.failure?
+      end
+
+      result
     end
   end
 end

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

@@ -8,15 +8,31 @@ module Cuprum::Rails::Actions
   class Show < Cuprum::Rails::Actions::ResourceAction
     private
 
-    def process(request:)
-      super
+    attr_reader :entity
+
+    def build_response
+      { resource.singular_name => entity }
+    end
+
+    def find_entity(primary_key:)
+      collection.find_one.call(primary_key: primary_key)
+    end
 
-      primary_key = step { resource_id }
-      entity      = step do
-        collection.find_one.call(primary_key: primary_key)
-      end
+    def parameters_contract
+      @parameters_contract ||=
+        Cuprum::Rails::Constraints::ParametersContract.new do
+          key 'id', Stannum::Constraints::Presence.new
+        end
+    end
+
+    def perform_action
+      @entity = step { find_entity(primary_key: resource_id) }
+    end
 
-      { singular_resource_name => entity }
+    def process(**)
+      @entity = nil
+
+      super
     end
   end
 end