cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/request.rb

@@ -13,24 +13,29 @@ module Cuprum::Rails
       ].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.
+      # @param request [ActionDispatch::Request] The native request to build.
       #
       # @return [Cuprum::Rails::Request] the generated request.
-      def build(request:)
+      def build(request:, **options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        body_params  = request.request_parameters
+        query_params = request.query_parameters
+        path_params  = filter_path_parameters(request.path_parameters)
+
         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
+          action_name:     request.params['action']&.intern,
+          authorization:   request.authorization,
+          body_params:     body_params,
+          controller_name: request.params['controller'],
+          format:          request.format.symbol,
+          headers:         filter_headers(request.headers),
+          http_method:     request.request_method_symbol,
+          params:          body_params.merge(query_params).merge(path_params),
+          path:            request.fullpath,
+          path_params:     path_params,
+          query_params:    query_params,
+          **options
         )
       end
 
@@ -42,64 +47,148 @@ module Cuprum::Rails
         end
       end
 
-      def filter_params(params)
-        params.reject { |key, _| FILTERED_PARAMS.include?(key) }
+      def filter_path_parameters(path_parameters)
+        path_parameters.except('action', 'controller')
+      end
+
+      def property(property_name)
+        define_method(property_name) do
+          @properties[property_name]
+        end
+
+        define_method(:"#{property_name}=") do |value|
+          @properties[property_name] = value
+        end
       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
+    # @param context [Object] the controller or request context.
+    #
+    # @option properties [Symbol] :action_name the name of the called action.
+    # @option properties [String, nil] :authorization the authorization header,
+    #   if any.
+    # @option properties [Hash<String, Object>] :body_params the parameters from
+    #   the request body.
+    # @option properties [String] :controller_name the name of the controller.
+    # @option properties [Symbol] :format the request format, e.g. :html or
+    #   :json.
+    # @option properties [Hash<String, String>] :headers the request headers.
+    # @option properties [Boolean] :member_action true if the request is for a
+    #   resource member action; otherwise false.
+    # @option properties [Symbol] :method the HTTP method used for the request.
+    # @option properties [Hash<String, Object>] :params the merged GET and POST
+    #   parameters.
+    # @option properties [Hash<String, Object>] :query_params the query
+    #   parameters.
+    def initialize(context: nil, **properties)
+      @context    = context
+      @properties = properties
+    end
+
+    # @return [Object] the controller or request context.
+    attr_reader :context
+
+    # @return [Hash<Symbol, Object>] the properties of the request.
+    attr_reader :properties
+
+    # @!attribute action_name
+    #   @return [Symbol] the name of the called action.
+    property :action_name
+
+    # @!attribute authorization
+    #   @return [String, nil] the authorization header, if any.
+    property :authorization
+
+    # @!attribute body_params
+    #   @return [Hash<String, Object>] the parameters from the request body.
+    property :body_params
+    alias body_parameters  body_params
+    alias body_parameters= body_params=
+
+    # @!attribute controller_name
+    #   @return [String] the name of the controller.
+    property :controller_name
+
+    # @!attribute format [Symbol]
+    #   @return the request format, e.g. :html or :json.
+    property :format
+
+    # @!attribute headers
+    #   @return [Hash<String, String>] the request headers.
+    property :headers
+
+    # @!attribute method
+    #   @return [Symbol] the HTTP method used for the request.
+    property :http_method
+
+    # @!attribute params
+    #   @return [Hash<String, Object>] The merged GET and POST parameters.
+    property :params
+    alias parameters  params
+    alias parameters= params=
+
+    # @!attribute path
+    #   @return [String] the relative path of the request, including params.
+    property :path
+
+    # @!attribute path_params
+    #   @return [Hash<String, Object>] the path parameters.
+    property :path_params
+    alias path_parameters  path_params
+    alias path_parameters= path_params=
+
+    # @!attribute query_params
+    #   @return [Hash<String, Object>] the query parameters.
+    property :query_params
+    alias query_parameters  query_params
+    alias query_parameters= query_params=
+
+    # @param property_name [String, Symbol] the name of the property.
+    #
+    # @return [Object] the value of the property
+    def [](property_name)
+      validate_property_name!(property_name)
+
+      @properties[property_name.intern]
     end
 
-    # @return [String, nil] the authorization header, if any.
-    attr_reader :authorization
+    # @param property_name [String, Symbol] the name of the property.
+    # @param value [Object] the value to assign to the property.
+    def []=(property_name, value)
+      validate_property_name!(property_name)
+
+      @properties[property_name.intern] = value
+    end
 
-    # @return [Hash<String, Object>] The parameters from the request body.
-    attr_reader :body_params
-    alias body_parameters body_params
+    # @return [Boolean] true if the request is for a resource member action;
+    #   otherwise false.
+    def member_action?
+      !!@properties[:member_action]
+    end
 
-    # @return [Symbol] the request format, e.g. :html or :json.
-    attr_reader :format
+    # @return [ActionDispatch::Request::Session] the native session object.
+    def native_session
+      context&.session
+    end
 
-    # @return [Hash<String, String>] the request headers.
-    attr_reader :headers
+    private
 
-    # @return [Symbol] the HTTP method used for the request.
-    attr_reader :method
+    def validate_property_name!(name) # rubocop:disable Metrics/MethodLength
+      if name.nil?
+        raise ArgumentError,
+          "property name can't be blank",
+          caller(1..-1)
+      end
 
-    # @return [Hash<String, Object>] The merged GET and POST parameters.
-    attr_reader :params
-    alias parameters params
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError,
+          'property name must be a String or a Symbol',
+          caller(1..-1)
+      end
 
-    # @return [String] the relative path of the request, including params.
-    attr_reader :path
+      return unless name.empty?
 
-    # @return [Hash<String, Object>] the query parameters.
-    attr_reader :query_params
-    alias query_parameters query_params
+      raise ArgumentError, "property name can't be blank", caller(1..-1)
+    end
   end
 end

data/lib/cuprum/rails/resource.rb

@@ -1,67 +1,85 @@
 # frozen_string_literal: true
 
+require 'cuprum/collections/resource'
+
 require 'cuprum/rails'
+require 'cuprum/rails/collection'
 
 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.
+  class Resource < Cuprum::Collections::Resource
+    # Default actions for a plural resource.
+    PLURAL_ACTIONS = %w[create destroy edit index new show update].freeze
+
+    # Default actions for a singular resource.
+    SINGULAR_ACTIONS = %w[create destroy edit new show update].freeze
+
+    STRING_COLUMN_TYPES = Set.new(%i[string uuid]).freeze
+    private_constant :STRING_COLUMN_TYPES
+
+    # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
+    #   @param entity_class [Class, String] the class of entity represented by
+    #     the resource.
+    #   @param name [String] the name of the resource.
+    #   @param qualified_name [String] a scoped name for the resource.
+    #   @param routes [Cuprum::Rails::Routes] the routes defined for the
+    #     resource.
+    #   @param singular_name [String] the name of an entity in the resource.
+    #   @param options [Hash] additional options for the resource.
     #
-    # @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
+    #   @option options actions [Array, Set] the defined actions for the
+    #     resource.
+    #   @option options base_path [String] the base url for the resource.
+    #   @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_name [String] the name of the primary key
+    #     attribute. Defaults to 'id'.
+    #   @option primary_key_type [Class, Stannum::Constraint] the type of
+    #     the primary key attribute. Defaults to Integer.
+    #   @option options plural [Boolean] if true, the resource represents a
+    #     plural resource. Defaults to true. Can also be specified as :singular.
+    #   @option primary_key_type [Class, Stannum::Constraint] the type of
+    #     the primary key attribute. Defaults to Integer.
+    def initialize(routes: nil, **params)
+      validate_permitted_attributes(params[:permitted_attributes])
+
+      super(**params)
+
+      @routes = routes
+    end
+
+    # @return [Set] the defined actions for the resource.
+    def actions
+      @actions ||= Set.new(options.fetch(:actions, default_actions).map(&:to_s))
+    end
+
+    # @return [Array<Resource>] the resource's ancestors, starting with the
+    #   resource itself.
+    def ancestors
+      each_ancestor.to_a
+    end
 
     # @return [String] the base url for the resource.
     def base_path
       @base_path ||=
         options
-          .fetch(:base_path) { "/#{resource_name.underscore}" }
+          .fetch(:base_path) { default_base_path }
           .to_s
     end
 
+    # Enumerates the resource's ancestors, starting with the resource itself.
+    #
+    # @yield_param [Resource] the current ancestor.
+    def each_ancestor(&block)
+      return enum_for(:each_ancestor) unless block_given?
+
+      parent&.each_ancestor(&block)
+
+      yield self
+    end
+
     # @return [Hash] the default ordering for the resource items.
     def default_order
       @default_order ||= options.fetch(:default_order, {})
@@ -73,27 +91,32 @@ module Cuprum::Rails
       @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 ||=
+    # @return [String] the name of the primary key attribute. Defaults to 'id'.
+    def primary_key_name
+      @primary_key_name ||=
         options
-          .fetch(:primary_key) { resource_class&.primary_key }
-          .yield_self { |value| value.nil? ? nil : value.to_s }
+          .fetch(:primary_key_name) { entity_class.primary_key }
+          .to_s
     end
+    alias primary_key primary_key_name
 
-    # @return [String] the name of the resource.
-    def resource_name
-      return @resource_name if @resource_name
+    # @return [Cuprum::Rails::Resource] the parent resource, if any.
+    def parent
+      @parent ||= @options.fetch(:parent, nil)
+    end
 
-      name = resource_class.name.split('::').last.underscore
+    # @return [Class, Stannum::Constraint] the type of the primary key
+    #   attribute. Defaults to Integer.
+    def primary_key_type
+      @primary_key_type =
+        options
+          .fetch(:primary_key_type) do
+            key    = entity_class.primary_key
+            column = entity_class.columns.find { |col| col.name == key }
 
-      @resource_name = plural? ? name.pluralize : name
+            STRING_COLUMN_TYPES.include?(column.type) ? String : Integer
+          end # rubocop:disable Style/MultilineBlockChain
+          .then { |value| value.is_a?(String) ? value.constantize : value }
     end
 
     # Generates the routes for the resource and injects the given wildcards.
@@ -105,41 +128,52 @@ module Cuprum::Rails
       routes_without_wildcards.with_wildcards(wildcards)
     end
 
-    # @return [Boolean] true if the collection is a singular collection,
-    #   otherwise false.
-    def singular?
-      @singular
+    private
+
+    def default_actions
+      singular? ? SINGULAR_ACTIONS : PLURAL_ACTIONS
     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
+    def default_base_path
+      "#{parent_path}/#{(singular? ? name.singularize : name).underscore}"
     end
 
-    def validate_permitted_attributes(attributes)
-      return if attributes.nil? || attributes.is_a?(Array)
+    def default_parent_path
+      return unless parent
 
-      raise ArgumentError,
-        'keyword :permitted_attributes must be an Array or nil',
-        caller(1..-1)
+      return parent.base_path if parent.singular?
+
+      "#{parent.base_path}/:#{parent.singular_name}_id"
     end
 
-    private
+    def parent_path
+      @parent_path || default_parent_path
+    end
+
+    def routes_options
+      {
+        base_path:   base_path,
+        parent_path: parent_path
+      }
+    end
 
     def routes_without_wildcards
       return @routes if @routes
 
       @routes =
         if plural?
-          Cuprum::Rails::Routing::PluralRoutes.new(base_path: base_path)
+          Cuprum::Rails::Routing::PluralRoutes.new(**routes_options)
         else
-          Cuprum::Rails::Routing::SingularRoutes.new(base_path: base_path)
+          Cuprum::Rails::Routing::SingularRoutes.new(**routes_options)
         end
     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
   end
 end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/responders'
+
+module Cuprum::Rails::Responders
+  # Abstract base class for defining responders.
+  class BaseResponder
+    extend Forwardable
+
+    # @param action_name [String, Symbol] the name of the action to match.
+    # @param controller [Cuprum::Rails::Controller] the called controller.
+    # @param member_action [Boolean] true if the action acts on a collection
+    #   item, not on the collection as a whole.
+    # @param request [Cuprum::Rails::Request] the request to the controller.
+    def initialize(
+      action_name:,
+      controller:,
+      request:,
+      member_action: false,
+      **_options
+    )
+      @action_name     = action_name
+      @controller      = controller
+      @controller_name = controller.class.name
+      @member_action   = !!member_action # rubocop:disable Style/DoubleNegation
+      @request         = request
+      @resource        = controller.class.resource
+    end
+
+    # @return [String, Symbol] the name of the action to match.
+    attr_reader :action_name
+
+    # @return [Cuprum::Rails::Controller] the called controller.
+    attr_reader :controller
+
+    # @return [String] the name of the called controller.
+    attr_reader :controller_name
+
+    # @return [Cuprum::Rails::Request] the request to the controller.
+    attr_reader :request
+
+    # @return [Cuprum::Rails::Resource] the resource for the controller.
+    attr_reader :resource
+
+    # @return [Cuprum::Result] the result of calling the action.
+    attr_reader :result
+
+    # Generates the response object for the result.
+    #
+    # @param result [Cuprum::Result] the result of the action call.
+    #
+    # @return [#call] the response object from the matching response clause.
+    def call(result)
+      @result = result
+    end
+
+    # @return [true, false] true if the action is a member action, otherwise
+    #   false.
+    def member_action?
+      @member_action
+    end
+
+    # Helper for accessing the configured routes for the resource.
+    #
+    # Any wildcards from the path params will be applied to the routes.
+    #
+    # @return [Cuprum::Rails::Routes] the configured routes.
+    def routes
+      resource.routes.with_wildcards(routes_wildcards)
+    end
+
+    private
+
+    def routes_wildcards
+      request.path_params || {}
+    end
+  end
+end

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

@@ -3,6 +3,7 @@
 require 'cuprum/collections/errors/failed_validation'
 
 require 'cuprum/rails/responders/html'
+require 'cuprum/rails/responders/html/resource'
 
 module Cuprum::Rails::Responders::Html
   # Defines default responses for a plural RESTful resource.
@@ -18,45 +19,14 @@ module Cuprum::Rails::Responders::Html
   # 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
+  class PluralResource < Cuprum::Rails::Responders::Html::Resource
+    def initialize(**options)
+      super
+
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        'Cuprum::Rails::Responders::Html::PluralResource',
+        message: 'use Cuprum::Rails::Responders::Html::Resource'
+      )
     end
   end
 end