cuprum-rails 0.1.0

data/lib/cuprum/rails/controller_action.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # @api private
+  #
+  # Implements a controller action.
+  #
+  # @note This class should not be initialized directly. Instead, use the
+  #   Cuprum::Rails::Controller.action class method to define an action.
+  class ControllerAction
+    extend Forwardable
+
+    # @param configuration [Cuprum::Rails::Controllers::Configuration] the
+    #   configuration for the originating controller.
+    # @param action_class [Class] The class of the action command. Must be
+    #   constructible with keyword :resource.
+    # @param action_name [String, Symbol] The name of the action.
+    # @param member_action [Boolean] True if the action acts on a collection
+    #   item, not on the collection as a whole.
+    # @param serializers
+    #   [Hash<Class, Object>, Hash<Symbol, Hash<Class, Object>>] The serializers
+    #   for converting result values into serialized data.
+    def initialize(
+      configuration,
+      action_class:,
+      action_name:,
+      member_action: false,
+      serializers:   {}
+    )
+      @configuration = configuration
+      @action_class  = action_class
+      @action_name   = action_name
+      @member_action = !!member_action # rubocop:disable Style/DoubleNegation
+      @serializers   = serializers
+    end
+
+    # @return [Class] the class of the action command.
+    attr_reader :action_class
+
+    # @return [String, Symbol] the name of the action.
+    attr_reader :action_name
+
+    # @return [Cuprum::Rails::Controllers::Configuration] the configuration for
+    #   the originating controller.
+    attr_reader :configuration
+
+    # @return [Hash<Class, Object>, Hash<Symbol, Hash<Class, Object>>] the
+    #   serializers for converting result values into serialized data.
+    attr_reader :serializers
+
+    # @!method resource
+    #   @return [Cuprum::Rails::Resource] the resource defined for the
+    #     controller.
+
+    # @!method responder_for(format)
+    #   Finds the configured responder for the requested format.
+    #
+    #   @param format [Symbol] The format to respond to.
+    #
+    #   @return [Class] the responder class defined for the format.
+    #
+    #   @raise [Cuprum::Rails::Controller::UnknownFormatError] if the controller
+    #     does not define a responder for the given format.
+
+    def_delegators :@configuration,
+      :resource,
+      :responder_for
+
+    # Executes the controller action.
+    #
+    # 1. Initializes the action command with the resource.
+    # 2. Calls the command with the request.
+    # 3. Builds the responder with the resource and action metadata.
+    # 4. Calls the responder with the action result.
+    #
+    # @param request [ActionDispatch::Request] The request to process.
+    #
+    # @return [#call] The response object.
+    def call(request)
+      responder = build_responder(request)
+      action    = action_class.new(resource: resource)
+      result    = action.call(request: request)
+
+      responder.call(result)
+    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 build_responder(request)
+      responder_class = responder_for(request.format)
+
+      responder_class.new(
+        action_name:   action_name,
+        member_action: member_action?,
+        resource:      resource,
+        serializers:   merge_serializers_for(request.format)
+      )
+    end
+
+    def merge_serializers_for(format)
+      scoped_serializers(configuration.serializers, format: format)
+        .merge(scoped_serializers(serializers, format: format))
+    end
+
+    def scoped_serializers(serializers, format:)
+      serializers
+        .select { |key, _| key.is_a?(Class) }
+        .merge(serializers.fetch(format, {}))
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/controller_action'
+require 'cuprum/rails/controllers/class_methods'
+
+module Cuprum::Rails::Controllers::ClassMethods
+  # Provides a DSL for defining controller actions.
+  module Actions
+    # Defines a controller action.
+    #
+    # @param action_name [String, Symbol] The name of the action.
+    # @param action_class [Class] The class of the action command. Must be
+    #   constructible with keyword :resource.
+    # @param member [Boolean] True if the action acts on a collection item, not
+    #   on the collection as a whole.
+    def action(action_name, action_class, member: false)
+      validate_name(action_name, as: 'action name')
+      validate_class(action_class, as: 'action class')
+
+      action_name              = action_name.intern
+      own_actions[action_name] = Cuprum::Rails::ControllerAction.new(
+        configuration,
+        action_class:  action_class,
+        action_name:   action_name,
+        member_action: member
+      )
+
+      define_action(action_name)
+    end
+
+    # @return [Hash<Symbol, Cuprum::Rails::ControllerAction>] the actions
+    #   defined for the controller.
+    def actions
+      ancestors
+        .select { |ancestor| ancestor.respond_to?(:own_actions) }
+        .reverse_each
+        .map(&:own_actions)
+        .reduce(&:merge)
+    end
+
+    # @private
+    def own_actions
+      @own_actions ||= {}
+    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)
+        response.call(self)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/controllers/class_methods'
+require 'cuprum/rails/controllers/configuration'
+require 'cuprum/rails/serializers/json'
+
+module Cuprum::Rails::Controllers::ClassMethods
+  # Provides a DSL for defining controller configuration.
+  module Configuration
+    # @return [Cuprum::Rails::Controllers::Configuration] the configured options
+    #   for the controller.
+    def configuration
+      Cuprum::Rails::Controllers::Configuration.new(self)
+    end
+
+    # @private
+    def own_responders
+      @own_responders ||= {}
+    end
+
+    # Returns the resource defined for the controller.
+    #
+    # Controller subclasses must override this method.
+    #
+    # @return [Cuprum::Rails::Resource] the resource defined for the
+    #   controller.
+    #
+    # @raise [Cuprum::Rails::Controller::UndefinedResourceError] if the
+    #   controller does not define a resource.
+    def resource
+      raise Cuprum::Rails::Controller::UndefinedResourceError,
+        "no resource defined for #{name}"
+    end
+
+    # Assigns a responder class to handle requests of the specified format.
+    #
+    # @param format [String, Symbol] The request format to handle.
+    # @param responder_class [Class] The class of responder.
+    def responder(format, responder_class)
+      validate_name(format, as: 'format')
+      validate_class(responder_class, as: 'responder')
+
+      own_responders[format.intern] = responder_class
+    end
+
+    # @return [Hash<Symbol, Class>] the responder classes defined for the
+    #   controller, by format.
+    def responders
+      ancestors
+        .select { |ancestor| ancestor.respond_to?(:own_responders) }
+        .reverse_each
+        .map(&:own_responders)
+        .reduce(&:merge)
+    end
+
+    # @return [Hash<Class, Object>, Hash<Symbol, Hash<Class, Object>>] the
+    #   serializers for converting result values into serialized data.
+    def serializers
+      {
+        json: Cuprum::Rails::Serializers::Json.default_serializers
+      }
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/controllers/class_methods'
+
+module Cuprum::Rails::Controllers::ClassMethods
+  # @private
+  module Validations
+    private
+
+    def validate_class(value, as:) # rubocop:disable Naming/MethodParameterName
+      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
+      raise ArgumentError, "#{as} can't be blank", caller(1..-1) if value.nil?
+
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError,
+          "#{as} must be a String or Symbol",
+          caller(1..-1)
+      end
+
+      return unless value.to_s.empty?
+
+      raise ArgumentError, "#{as} can't be blank", caller(1..-1)
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/controllers'
+
+module Cuprum::Rails::Controllers
+  # Namespace for controller class-specific functionality.
+  module ClassMethods
+    autoload :Actions,
+      'cuprum/rails/controllers/class_methods/actions'
+    autoload :Configuration,
+      'cuprum/rails/controllers/class_methods/configuration'
+    autoload :Validations,
+      'cuprum/rails/controllers/class_methods/validations'
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/rails/controllers'
+
+module Cuprum::Rails::Controllers
+  # Data object that stores a controller's configuration.
+  class Configuration
+    extend Forwardable
+
+    # @param controller [#resource, #responders] The controller to delegate
+    #   configuration.
+    def initialize(controller)
+      @controller = controller
+    end
+
+    # @return [#resource, #responders] the controller to delegate configuration.
+    attr_reader :controller
+
+    # @!method resource
+    #   @return [Cuprum::Rails::Resource] the resource defined for the
+    #     controller.
+
+    # @!method responders
+    #   @return [Hash<Symbol, Class>] the responder classes defined for the
+    #     controller, by format.
+
+    # @!method serializers
+    #   @return [Hash<Class, Object>, Hash<Symbol, Hash<Class, Object>>] the
+    #     serializers for converting result values into serialized data.
+
+    def_delegators :@controller,
+      :resource,
+      :responders,
+      :serializers
+
+    # Finds the configured responder for the requested format.
+    #
+    # @param format [Symbol] The format to respond to.
+    #
+    # @return [Class] the responder class defined for the format.
+    #
+    # @raise [Cuprum::Rails::Controller::UnknownFormatError] if the controller
+    #   does not define a responder for the given format.
+    def responder_for(format)
+      responders.fetch(format) do
+        raise Cuprum::Rails::Controller::UnknownFormatError,
+          "no responder registered for format #{format.inspect}"
+      end
+    end
+  end
+end

data/lib/cuprum/rails/controllers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for controller-specific functionality.
+  module Controllers
+    autoload :Configuration, 'cuprum/rails/controllers/configuration'
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a parameters hash does not include a resource.
+  class MissingParameters < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.missing_parameters'
+
+    # @param resource_name [Cuprum::Rails::Resource] The name of the resource.
+    def initialize(resource_name:)
+      @resource_name = resource_name
+
+      super(message: default_message, resource_name: resource_name)
+    end
+
+    # @return [Cuprum::Rails::Resource] the name of the resource.
+    attr_reader :resource_name
+
+    private
+
+    def as_json_data
+      { 'resource_name' => resource_name }
+    end
+
+    def default_message
+      "The #{resource_name.inspect} parameter is missing or empty"
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a parameters hash does not include a primary key.
+  class MissingPrimaryKey < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.missing_primary_key'
+
+    # @param primary_key [String, Symbol] The name of the resource primary key.
+    # @param resource_name [Cuprum::Rails::Resource] The name of the resource.
+    def initialize(primary_key:, resource_name:)
+      @primary_key   = primary_key
+      @resource_name = resource_name
+
+      super(
+        message:       default_message,
+        primary_key:   primary_key,
+        resource_name: resource_name
+      )
+    end
+
+    # @return [String] the name of the resource primary key.
+    attr_reader :primary_key
+
+    # @return [Cuprum::Rails::Resource] the name of the resource.
+    attr_reader :resource_name
+
+    private
+
+    def as_json_data
+      {
+        'primary_key'   => primary_key,
+        'resource_name' => resource_name
+      }
+    end
+
+    def default_message
+      "Unable to find #{resource_name} because the #{primary_key.inspect}" \
+        ' parameter is missing or empty'
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/rails/errors'
+
+module Cuprum::Rails::Errors
+  # Error class when a resource does not define permitted attributes.
+  class UndefinedPermittedAttributes < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.rails.errors.undefined_permitted_attributes'
+
+    # @param resource_name [Cuprum::Rails::Resource] The name of the resource.
+    def initialize(resource_name:)
+      @resource_name = resource_name
+
+      super(message: default_message, resource_name: resource_name)
+    end
+
+    # @return [Cuprum::Rails::Resource] the name of the resource.
+    attr_reader :resource_name
+
+    private
+
+    def as_json_data
+      { 'resource_name' => resource_name }
+    end
+
+    def default_message
+      "Resource #{resource_name.inspect} does not define" \
+        ' permitted attributes'
+    end
+  end
+end

data/lib/cuprum/rails/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for custom Cuprum::Rails error classes.
+  module Errors; end
+end

data/lib/cuprum/rails/map_errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'stannum/errors'
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Maps errors from a validated Rails model to a Stannum::Errors object.
+  class MapErrors
+    # @return [MapErrors] a memoized instance of the class.
+    def self.instance
+      @instance ||= new
+    end
+
+    # Maps an ActiveModel::Errors object to a Stannum::Errors object.
+    #
+    # @param native_errors [ActiveModel::Errors] The Rails error object.
+    #
+    # @return [Stannum::Errors] the generated errors object.
+    def call(native_errors:)
+      unless native_errors.is_a?(ActiveModel::Errors)
+        raise ArgumentError,
+          'native_errors must be an instance of ActiveModel::Errors'
+      end
+
+      map_errors(native_errors: native_errors)
+    end
+
+    private
+
+    def map_errors(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)
+      end
+
+      errors
+    end
+  end
+end

data/lib/cuprum/rails/query.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/query'
+
+require 'cuprum/rails'
+require 'cuprum/rails/query_builder'
+
+module Cuprum::Rails
+  # Interface for performing query operations on a Rails collection.
+  class Query < Cuprum::Collections::Query
+    extend  Forwardable
+    include Enumerable
+
+    def_delegators :@native_query,
+      :each,
+      :exists?,
+      :to_a
+
+    # @param record_class [Class] The class of the collection items. Must be a
+    #   subclass of ActiveRecord::Base.
+    # @param native_query [ActiveRecord::Relation] A relation used to scope the
+    #   query.
+    def initialize(record_class, native_query: nil)
+      super()
+
+      default_order = { record_class.primary_key => :asc }
+      @native_query = native_query || record_class.all.order(default_order)
+      @record_class = record_class
+      @limit        = nil
+      @offset       = nil
+      @order        = default_order
+    end
+
+    # @return [Class] the class of the collection items.
+    attr_reader :record_class
+
+    protected
+
+    def query_builder
+      Cuprum::Rails::QueryBuilder.new(self)
+    end
+
+    def reset!
+      @native_query.reset
+
+      self
+    end
+
+    def with_limit(count)
+      @native_query = @native_query.limit(count)
+
+      super
+    end
+
+    def with_native_query(native_query)
+      @native_query = native_query
+
+      self
+    end
+
+    def with_offset(count)
+      @native_query = @native_query.offset(count)
+
+      super
+    end
+
+    def with_order(order)
+      @native_query = @native_query.reorder(order)
+
+      super
+    end
+
+    private
+
+    attr_reader :native_query
+  end
+end

data/lib/cuprum/rails/query_builder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/query_builder'
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Applies filter operations for a Rails collection query.
+  class QueryBuilder < Cuprum::Collections::QueryBuilder
+    # @param base_query [Cuprum::Rails::Query] The query to build.
+    def initialize(base_query)
+      super
+
+      @native_query = base_query.send(:native_query)
+    end
+
+    private
+
+    attr_reader :native_query
+
+    def build_native_query(criteria)
+      native_query.where(
+        criteria
+          .map do |(attribute, operator, value)|
+            send(operator, attribute, value)
+          end
+          .join(' AND ')
+      )
+    end
+
+    def build_query(criteria)
+      super.send(:with_native_query, build_native_query(criteria))
+    end
+
+    def equal(attribute, value)
+      return sanitize("#{attribute} IS NULL") if value.nil?
+
+      sanitize("#{attribute} = :value", value: value)
+    end
+
+    def greater_than(attribute, value)
+      sanitize("#{attribute} > :value", value: value)
+    end
+
+    def greater_than_or_equal_to(attribute, value)
+      sanitize("#{attribute} >= :value", value: value)
+    end
+
+    def less_than(attribute, value)
+      sanitize("#{attribute} < :value", value: value)
+    end
+
+    def less_than_or_equal_to(attribute, value)
+      sanitize("#{attribute} <= :value", value: value)
+    end
+
+    def not_equal(attribute, value)
+      return sanitize("#{attribute} IS NOT NULL") if value.nil?
+
+      sanitize("(#{attribute} != :value OR #{attribute} IS NULL)", value: value)
+    end
+
+    def not_one_of(attribute, value)
+      sanitize(
+        "(#{attribute} NOT IN (:value) OR #{attribute} IS NULL)",
+        value: value
+      )
+    end
+
+    def one_of(attribute, value)
+      sanitize("#{attribute} IN (:value)", value: value)
+    end
+
+    def sanitize(*conditions)
+      ActiveRecord::Base.sanitize_sql_for_conditions(conditions)
+    end
+  end
+end