cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/controllers/class_methods/actions.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'cuprum/rails/controller_action'
+require 'cuprum/rails/controllers/action'
 require 'cuprum/rails/controllers/class_methods'
 
 module Cuprum::Rails::Controllers::ClassMethods
@@ -18,8 +18,7 @@ module Cuprum::Rails::Controllers::ClassMethods
       validate_class(action_class, as: 'action class')
 
       action_name              = action_name.intern
-      own_actions[action_name] = Cuprum::Rails::ControllerAction.new(
-        configuration,
+      own_actions[action_name] = Cuprum::Rails::Controllers::Action.new(
         action_class:  action_class,
         action_name:   action_name,
         member_action: member
@@ -28,7 +27,7 @@ module Cuprum::Rails::Controllers::ClassMethods
       define_action(action_name)
     end
 
-    # @return [Hash<Symbol, Cuprum::Rails::ControllerAction>] the actions
+    # @return [Hash<Symbol, Cuprum::Rails::Controllers::Action>] the actions
     #   defined for the controller.
     def actions
       ancestors
@@ -38,18 +37,45 @@ module Cuprum::Rails::Controllers::ClassMethods
         .reduce(&:merge)
     end
 
+    # @private
+    def apply_request_defaults(request)
+      request.format ||= configuration.default_format
+    end
+
+    # Generates a Cuprum::Rails::Request from a native request.
+    #
+    # Override this method to generate a request subclass.
+    #
+    # @param context [#request] the controller or controller context.
+    # @param options [Hash{Symbol=>Object}] additional options for the request.
+    #
+    # @return [Cuprum::Rails::Request] the generated request.
+    def build_request(context, **options)
+      Cuprum::Rails::Request.build(
+        context: context,
+        request: context.request,
+        **options
+      )
+    end
+
     # @private
     def own_actions
+      # :nocov:
       @own_actions ||= {}
+      # :nocov:
     end
 
     private
 
     def define_action(action_name)
       define_method(action_name) do
-        request  = Cuprum::Rails::Request.build(request: self.request)
-        action   = self.class.actions[action_name]
-        response = action.call(request)
+        action  = self.class.actions[action_name]
+        request =
+          self
+            .class
+            .build_request(self, member_action: action.member_action?)
+            .tap { |req| self.class.apply_request_defaults(req) }
+        response = action.call(self, request)
         response.call(self)
       end
     end

data/lib/cuprum/rails/controllers/class_methods/configuration.rb

@@ -13,11 +13,40 @@ module Cuprum::Rails::Controllers::ClassMethods
       Cuprum::Rails::Controllers::Configuration.new(self)
     end
 
+    # @overload default_format
+    #   @return [Symbol] the default format for controller requests.
+    #
+    # @overload default_format(format)
+    #   Sets the default format for controller requests.
+    #
+    #   @param format [String, Symbol] The format to set as default.
+    def default_format(format = nil)
+      if format.nil?
+        return @default_format if @default_format
+
+        return superclass.default_format if controller_class?(superclass)
+
+        return nil
+      end
+
+      validate_name(format, as: 'format')
+
+      @default_format = format.intern
+    end
+
     # @private
     def own_responders
       @own_responders ||= {}
     end
 
+    # Returns the repository defined for the controller.
+    #
+    # @return [Cuprum::Collections::Repository] the repository containing the
+    #   data collections for the application or scope.
+    def repository
+      nil
+    end
+
     # Returns the resource defined for the controller.
     #
     # Controller subclasses must override this method.
@@ -60,5 +89,12 @@ module Cuprum::Rails::Controllers::ClassMethods
         json: Cuprum::Rails::Serializers::Json.default_serializers
       }
     end
+
+    private
+
+    def controller_class?(other)
+      other.singleton_class <
+        Cuprum::Rails::Controllers::ClassMethods::Configuration
+    end
   end
 end

data/lib/cuprum/rails/controllers/class_methods/middleware.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/controllers/class_methods'
+require 'cuprum/rails/controllers/middleware'
+
+module Cuprum::Rails::Controllers::ClassMethods
+  # Provides a DSL for defining controller middleware.
+  module Middleware
+    # @overload middleware
+    #   @return [Array<Cuprum::Rails::Controllers::Middleware>] the configured
+    #     middleware for the controller.
+    #
+    # @overload middleware(command, except: [], only: {]})
+    #   Defines middleware for the controller.
+    #
+    #   @param command [Class, Cuprum::Command] The middleware command.
+    #     Middleware commands must take two parameters: a next_command argument,
+    #     and a request: keyword.
+    #   @param except [Array<String, Symbol>] Action names to exclude. The
+    #     middleware will not be applied to actions on this list.
+    #   @param only [Array<String, Symbol>] Action names to include  If this is
+    #     not empty, the middleware will only be applied to actions on this
+    #     list.
+    #
+    #   @see Cuprum::Middleware
+    def middleware(command = nil, except: [], only: [])
+      unless command.nil?
+        own_middleware <<
+          build_middleware(command: command, except: except, only: only)
+      end
+
+      ancestors
+        .select { |ancestor| ancestor.respond_to?(:own_middleware) }
+        .reverse_each
+        .map(&:own_middleware)
+        .reduce(&:+)
+    end
+
+    # @private
+    def own_middleware
+      @own_middleware ||= []
+    end
+
+    private
+
+    def build_middleware(command:, except:, only:)
+      validate_command!(command)
+      validate_action_names!(except, as: 'except')
+      validate_action_names!(only,   as: 'only')
+
+      Cuprum::Rails::Controllers::Middleware.new(
+        command: command,
+        except:  except,
+        only:    only
+      )
+    end
+
+    def valid_action_names?(action_names)
+      return false unless action_names.is_a?(Array)
+
+      action_names.all? do |action_name|
+        next false unless action_name.is_a?(String) || action_name.is_a?(Symbol)
+
+        !action_name.empty?
+      end
+    end
+
+    def validate_action_names!(action_names, as:)
+      return if action_names.nil?
+
+      return if valid_action_names?(action_names)
+
+      raise ArgumentError,
+        "#{as} must be a list of action names",
+        caller(1..-1)
+    end
+
+    def validate_command!(command)
+      return if command.is_a?(Cuprum::Command)
+
+      return if command.is_a?(Class) && command < Cuprum::Command
+
+      raise ArgumentError,
+        'command must be an instance of or subclass of Cuprum::Command',
+        caller(1..-1)
+    end
+  end
+end

data/lib/cuprum/rails/controllers/class_methods/validations.rb

@@ -7,13 +7,13 @@ module Cuprum::Rails::Controllers::ClassMethods
   module Validations
     private
 
-    def validate_class(value, as:) # rubocop:disable Naming/MethodParameterName
+    def validate_class(value, as:)
       return if value.is_a?(Class)
 
       raise ArgumentError, "#{as} must be a Class", caller(1..-1)
     end
 
-    def validate_name(value, as:) # rubocop:disable Naming/MethodParameterName
+    def validate_name(value, as:)
       raise ArgumentError, "#{as} can't be blank", caller(1..-1) if value.nil?
 
       unless value.is_a?(String) || value.is_a?(Symbol)

data/lib/cuprum/rails/controllers/configuration.rb

@@ -18,6 +18,20 @@ module Cuprum::Rails::Controllers
     # @return [#resource, #responders] the controller to delegate configuration.
     attr_reader :controller
 
+    # @!method controller_name
+    #   @return [String] the name of the controller.
+
+    # @!method default_format
+    #   @return [Symbol] the default format for controller requests.
+
+    # @!method middleware
+    #   @return [Array<Cuprum::Rails::Controllers::Middleware>] the middleware
+    #     defined for the controller.
+
+    # @!method repository
+    #   @return [Cuprum::Collections::Repository] the repository containing the
+    #     data collections for the application or scope.
+
     # @!method resource
     #   @return [Cuprum::Rails::Resource] the resource defined for the
     #     controller.
@@ -31,13 +45,27 @@ module Cuprum::Rails::Controllers
     #     serializers for converting result values into serialized data.
 
     def_delegators :@controller,
+      :controller_name,
+      :default_format,
+      :middleware,
+      :repository,
       :resource,
       :responders,
       :serializers
 
+    # Finds the configured middleware for the requested action name.
+    #
+    # @param action_name [Symbol] The name of the action.
+    #
+    # @return [Array<Cuprum::Rails::Controllers::Middleware>] the configured
+    #   middleware for the action.
+    def middleware_for(action_name)
+      middleware.select { |item| item.matches?(action_name) }
+    end
+
     # Finds the configured responder for the requested format.
     #
-    # @param format [Symbol] The format to respond to.
+    # @param format [Symbol] the format to respond to.
     #
     # @return [Class] the responder class defined for the format.
     #
@@ -49,5 +77,17 @@ module Cuprum::Rails::Controllers
           "no responder registered for format #{format.inspect}"
       end
     end
+
+    # Finds the configured serializers for the requested format.
+    #
+    # @param format [Symbol] the format to respond to.
+    #
+    # @return [Hash<Class, Object>] the serializers for converting result values
+    #   into serialized data.
+    def serializers_for(format)
+      serializers
+        .select { |key, _| key.is_a?(Class) }
+        .merge(serializers.fetch(format, {}))
+    end
   end
 end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'cuprum/rails/controllers'
+
+module Cuprum::Rails::Controllers
+  # A configured middleware option for a controller.
+  class Middleware
+    # @param command [Cuprum::Command] The middleware command to wrap the
+    #   action or actions.
+    # @param except [Array<Symbol>] A list of action names; the middleware will
+    #   not be applied to actions on the list.
+    # @param only [Array<Symbol>] A list of action names; the middleware will
+    #   be applied only to actions on the list.
+    def initialize(command:, except: [], only: [])
+      @command = command
+      @except  = Set.new(except.map(&:intern))
+      @only    = Set.new(only.map(&:intern))
+    end
+
+    # @return [Cuprum::Middleware] the middleware command to wrap the action or
+    #   actions.
+    attr_reader :command
+
+    # @return [Array<Symbol>] a list of action names; the middleware will not be
+    #   applied to actions on the list.
+    attr_reader :except
+
+    # @return [Array<Symbol>] a list of action names; the middleware will be
+    #   applied only to actions on the list.
+    attr_reader :only
+
+    # @private
+    def ==(other)
+      other.is_a?(Cuprum::Rails::Controllers::Middleware) &&
+        other.command == command &&
+        other.except  == except &&
+        other.only    == only
+    end
+
+    # Checks if the middleware will be applied to the named action.
+    #
+    # If the middleware defines any :except actions, returns false if the action
+    # name is in the set. If the middleware defines any :only actions, returns
+    # false unless the action name is in the set. Otherwise, returns true.
+    #
+    # @param action_name [Symbol] The name of the action.
+    #
+    # @return [true, false] whether the middleware will be applied.
+    def matches?(action_name)
+      return false unless except.empty? || except.exclude?(action_name)
+      return false unless only.empty?   || only.include?(action_name)
+
+      true
+    end
+    alias match? matches?
+  end
+end

data/lib/cuprum/rails/controllers.rb

@@ -5,6 +5,8 @@ require 'cuprum/rails'
 module Cuprum::Rails
   # Namespace for controller-specific functionality.
   module Controllers
+    autoload :Action,        'cuprum/rails/controllers/action'
     autoload :Configuration, 'cuprum/rails/controllers/configuration'
+    autoload :Middleware,    'cuprum/rails/controllers/middleware'
   end
 end

data/lib/cuprum/rails/errors/invalid_parameters.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a parameters hash does not match the expected contract.
+  class InvalidParameters < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.invalid_parameters'
+
+    # @param errors [Stannum::Errors] the errors returned by the contract.
+    def initialize(errors:)
+      @errors = errors
+
+      super(message: default_message, errors: errors)
+    end
+
+    # @return [Stannum::Errors] the errors returned by the contract.
+    attr_reader :errors
+
+    private
+
+    def as_json_data
+      error_data =
+        errors
+          .group_by_path
+          .to_h do |path, errors|
+            [
+              join_path(path),
+              errors.map { |error| format_error(error) }
+            ]
+          end
+
+      { 'errors' => error_data }
+    end
+
+    def default_message
+      "invalid request parameters - #{errors.summary}"
+    end
+
+    def format_error(error)
+      tools.hash_tools.convert_keys_to_strings(error)
+    end
+
+    def join_path(path)
+      path.join('.')
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/rails/errors/invalid_statement.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a database execution error occurs.
+  class InvalidStatement < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.invalid_statement'
+  end
+end

data/lib/cuprum/rails/errors/missing_parameter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a parameters hash does not include the expected keys.
+  class MissingParameter < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.missing_parameter'
+
+    # @param parameter_name [String, Symbol] the name of the missing parameter.
+    # @param parameters [Hash] the received parameters.
+    def initialize(parameter_name:, parameters:)
+      @parameter_name = parameter_name
+      @parameters     = parameters
+
+      super(
+        message:        default_message,
+        parameter_name: parameter_name
+      )
+    end
+
+    # @return [String, Symbol] the name of the missing parameter.
+    attr_reader :parameter_name
+
+    # @return [Hash] the received parameters.
+    attr_reader :parameters
+
+    private
+
+    def as_json_data
+      {
+        'parameter_name' => parameter_name,
+        'parameters'     => parameters
+      }
+    end
+
+    def default_message
+      "missing parameter #{parameter_name.inspect}"
+    end
+  end
+end

data/lib/cuprum/rails/errors/resource_error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a resource is not correctly configured for an action.
+  class ResourceError < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.resource_error'
+
+    # @param resource [Cuprum::Rails::Resource] the errored resource.
+    # @param message [String] the message to display, if any.
+    def initialize(resource:, message: nil)
+      @resource = resource
+
+      super(message: generate_message(message), resource: resource)
+    end
+
+    # @return [Cuprum::Rails::Resource] the errored resource.
+    attr_reader :resource
+
+    private
+
+    def as_json_data
+      {
+        'resource' => {
+          'entity_class'   => resource.entity_class.to_s,
+          'name'           => resource.name.to_s,
+          'qualified_name' => resource.qualified_name.to_s,
+          'singular'       => resource.singular?,
+          'singular_name'  => resource.singular_name.to_s
+        }
+      }
+    end
+
+    def generate_message(message = nil)
+      prefix = "invalid resource #{resource.name}"
+
+      return prefix if message.blank?
+
+      "#{prefix} - #{message}"
+    end
+  end
+end

data/lib/cuprum/rails/errors.rb

@@ -4,5 +4,10 @@ require 'cuprum/rails'
 
 module Cuprum::Rails
   # Namespace for custom Cuprum::Rails error classes.
-  module Errors; end
+  module Errors
+    autoload :InvalidParameters, 'cuprum/rails/errors/invalid_parameters'
+    autoload :InvalidStatement,  'cuprum/rails/errors/invalid_statement'
+    autoload :MissingParameter,  'cuprum/rails/errors/missing_parameter'
+    autoload :ResourceError,     'cuprum/rails/errors/resource_error'
+  end
 end

data/lib/cuprum/rails/map_errors.rb

@@ -28,17 +28,45 @@ module Cuprum::Rails
 
     private
 
+    # :nocov:
     def map_errors(native_errors:)
+      if Rails.version < '6.1'
+        map_errors_hash(native_errors: native_errors)
+      else
+        map_errors_object(native_errors: native_errors)
+      end
+    end
+
+    def map_errors_hash(native_errors:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      errors   = Stannum::Errors.new
+      details  = native_errors.details
+      messages = native_errors.messages
+
+      native_errors.keys.each do |attribute| # rubocop:disable Style/HashEachMethods
+        scoped = attribute == :base ? errors : errors[attribute]
+
+        details[attribute].each.with_index do |hsh, index|
+          message = messages[attribute][index]
+
+          scoped.add(hsh[:error], **hsh.except(:error).merge(message: message))
+        end
+      end
+
+      errors
+    end
+
+    def map_errors_object(native_errors:)
       errors = Stannum::Errors.new
 
       native_errors.each do |error|
         attribute = error.attribute
         scoped    = attribute == :base ? errors : errors[attribute]
 
-        scoped.add(error.type, message: error.message, **error.options)
+        scoped.add(error.type, **error.options.merge(message: error.message))
       end
 
       errors
     end
   end
+  # :nocov:
 end

data/lib/cuprum/rails/query.rb

@@ -24,7 +24,7 @@ module Cuprum::Rails
       super()
 
       default_order = { record_class.primary_key => :asc }
-      @native_query = native_query || record_class.all.order(default_order)
+      @native_query = native_query || record_class.order(default_order)
       @record_class = record_class
       @limit        = nil
       @offset       = nil

data/lib/cuprum/rails/repository.rb

@@ -8,37 +8,24 @@ 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)
+    private
 
-      collection
+    def build_collection(**options)
+      Cuprum::Rails::Collection.new(**options)
     end
 
-    private
+    def qualified_name_for(**parameters)
+      Cuprum::Collections::Relation::Disambiguation
+        .resolve_parameters(
+          parameters,
+          entity_class: :record_class,
+          name:         :collection_name
+        )
+        .fetch(:qualified_name)
+    end
 
     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