hanami-controller 2.0.0.beta4 → 2.0.0

data/lib/hanami/action/mime.rb

@@ -3,6 +3,7 @@
 require "hanami/utils"
 require "rack/utils"
 require "rack/mime"
+require_relative "errors"
 
 module Hanami
   class Action
@@ -67,249 +68,217 @@ module Hanami
         zip: "application/zip"
       }.freeze
 
-      # @since 2.0.0
-      # @api private
-      def self.content_type_with_charset(content_type, charset)
-        "#{content_type}; charset=#{charset}"
-      end
+      ANY_TYPE = "*/*"
+
+      class << self
+        # Returns a format name for the given content type.
+        #
+        # The format name will come from the configured formats, if such a format is configured
+        # there, or instead from the default list of formats in `Mime::TYPES`.
+        #
+        # Returns nil if no matching format can be found.
+        #
+        # This is used to return the format name a {Response}.
+        #
+        # @example
+        #   detect_format("application/jsonl charset=utf-8", config) # => :json
+        #
+        # @return [Symbol, nil]
+        #
+        # @see Response#format
+        # @see Action#finish
+        #
+        # @since 2.0.0
+        # @api private
+        def detect_format(content_type, config)
+          return if content_type.nil?
 
-      # Use for setting Content-Type
-      # If the request has the ACCEPT header it will try to return the best Content-Type based
-      # on the content of the ACCEPT header taking in consideration the weights
-      #
-      # If no ACCEPT header it will check the default response_format, then the default request format and
-      # lastly it will fallback to DEFAULT_CONTENT_TYPE
-      #
-      # @return [String]
-      #
-      # @since 2.0.0
-      # @api private
-      def self.content_type(config, request, accepted_mime_types)
-        if request.accept_header?
-          type = best_q_match(request.accept, accepted_mime_types)
-          return type if type
+          ct = content_type.split(";").first
+          config.formats.format_for(ct) || TYPES.key(ct)
         end
 
-        default_response_type(config) || default_content_type(config) || Action::DEFAULT_CONTENT_TYPE
-      end
-
-      # @since 2.0.0
-      # @api private
-      def self.charset(default_charset)
-        default_charset || Action::DEFAULT_CHARSET
-      end
-
-      # @since 2.0.0
-      # @api private
-      def self.default_response_type(config)
-        format_to_mime_type(config.default_response_format, config)
-      end
-
-      # @since 2.0.0
-      # @api private
-      def self.default_content_type(config)
-        format_to_mime_type(config.default_request_format, config)
-      end
-
-      # @since 2.0.0
-      # @api private
-      def self.format_to_mime_type(format, config)
-        return if format.nil?
-
-        config.mime_type_for(format) ||
-          TYPES.fetch(format) { raise Hanami::Controller::UnknownFormatError.new(format) }
-      end
-
-      # Transforms MIME Types to symbol
-      # Used for setting the format of the response
-      #
-      # @see Hanami::Action::Mime#finish
-      # @example
-      #   detect_format("text/html; charset=utf-8", config)  #=> :html
-      #
-      # @return [Symbol, nil]
-      #
-      # @since 2.0.0
-      # @api private
-      def self.detect_format(content_type, config)
-        return if content_type.nil?
-
-        ct = content_type.split(";").first
-        config.format_for(ct) || format_for(ct)
-      end
-
-      # @since 2.0.0
-      # @api private
-      def self.format_for(content_type)
-        TYPES.key(content_type)
-      end
-
-      # Transforms symbols to MIME Types
-      # @example
-      #   restrict_mime_types(config, [:json])  #=> ["application/json"]
-      #
-      # @return [Array<String>, nil]
-      #
-      # @raise [Hanami::Controller::UnknownFormatError] if the format is invalid
-      #
-      # @since 2.0.0
-      # @api private
-      def self.restrict_mime_types(config)
-        return if config.accepted_formats.empty?
-
-        mime_types = config.accepted_formats.map do |format|
-          format_to_mime_type(format, config)
+        # Returns a format name and content type pair for a given format name or content type
+        # string.
+        #
+        # @example
+        #   detect_format_and_content_type(:json, config)
+        #   # => [:json, "application/json"]
+        #
+        #   detect_format_and_content_type("application/json", config)
+        #   # => [:json, "application/json"]
+        #
+        # @example Unknown format name
+        #   detect_format_and_content_type(:unknown, config)
+        #   # raises Hanami::Action::UnknownFormatError
+        #
+        # @example Unknown content type
+        #   detect_format_and_content_type("application/unknown", config)
+        #   # => [nil, "application/unknown"]
+        #
+        # @return [Array<(Symbol, String)>]
+        #
+        # @raise [Hanami::Action::UnknownFormatError] if an unknown format name is given
+        #
+        # @since 2.0.0
+        # @api private
+        def detect_format_and_content_type(value, config)
+          case value
+          when Symbol
+            [value, format_to_mime_type(value, config)]
+          when String
+            [detect_format(value, config), value]
+          else
+            raise UnknownFormatError.new(value)
+          end
         end
 
-        accepted_mime_types = mime_types & config.mime_types
-
-        return if accepted_mime_types.empty?
-
-        accepted_mime_types
-      end
-
-      # Yields if an action is configured with `accepted_formats`, the request has an `Accept`
-      # header, and none of the Accept types matches the accepted formats. The given block is
-      # expected to halt the request handling.
-      #
-      # If any of these conditions are not met, then the request is acceptable and the method
-      # returns without yielding.
-      #
-      # @see Action#enforce_accepted_mime_types
-      # @see Action.accept
-      # @see Config#accepted_formats
-      #
-      # @since 2.0.0
-      # @api private
-      def self.enforce_accept(request, config)
-        return unless request.accept_header?
+        # Returns a string combining the given content type and charset, intended for setting as a
+        # `Content-Type` header.
+        #
+        # @example
+        #   Mime.content_type_with_charset("application/json", "utf-8")
+        #   # => "application/json; charset=utf-8"
+        #
+        # @param content_type [String]
+        # @param charset [String]
+        #
+        # @return [String]
+        #
+        # @since 2.0.0
+        # @api private
+        def content_type_with_charset(content_type, charset)
+          "#{content_type}; charset=#{charset}"
+        end
 
-        accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
-        return if accept_types.any? { |mime_type| accepted_mime_type?(mime_type, config) }
+        # Returns a string combining a MIME type and charset, intended for setting as the
+        # `Content-Type` header for the response to the given request.
+        #
+        # This uses the request's `Accept` header (if present) along with the configured formats to
+        # determine the best content type to return.
+        #
+        # @return [String]
+        #
+        # @see Action#call
+        #
+        # @since 2.0.0
+        # @api private
+        def response_content_type_with_charset(request, config)
+          content_type_with_charset(
+            response_content_type(request, config),
+            config.default_charset || Action::DEFAULT_CHARSET
+          )
+        end
 
-        yield
-      end
+        # Patched version of <tt>Rack::Utils.best_q_match</tt>.
+        #
+        # @since 2.0.0
+        # @api private
+        #
+        # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
+        # @see https://github.com/rack/rack/pull/659
+        # @see https://github.com/hanami/controller/issues/59
+        # @see https://github.com/hanami/controller/issues/104
+        # @see https://github.com/hanami/controller/issues/275
+        def best_q_match(q_value_header, available_mimes = TYPES.values)
+          ::Rack::Utils.q_values(q_value_header).each_with_index.map { |(req_mime, quality), index|
+            match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
+            next unless match
+
+            RequestMimeWeight.new(req_mime, quality, index, match)
+          }.compact.max&.format
+        end
 
-      # Yields if an action is configured with `accepted_formats`, the request has a `Content-Type`
-      # header (or a `default_requst_format` is configured), and the content type does not match the
-      # accepted formats. The given block is expected to halt the request handling.
-      #
-      # If any of these conditions are not met, then the request is acceptable and the method
-      # returns without yielding.
-      #
-      # @see Action#enforce_accepted_mime_types
-      # @see Action.accept
-      # @see Config#accepted_formats
-      #
-      # @since 2.0.0
-      # @api private
-      def self.enforce_content_type(request, config)
-        content_type = request.content_type || default_content_type(config)
+        # Yields if an action is configured with `formats`, the request has an `Accept` header, an
+        # none of the Accept types matches the accepted formats. The given block is expected to halt
+        # the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_mime_types
+        # @see Config#formats
+        #
+        # @since 2.0.0
+        # @api private
+        def enforce_accept(request, config)
+          return unless request.accept_header?
 
-        return if content_type.nil?
+          accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
+          return if accept_types.any? { |mime_type| accepted_mime_type?(mime_type, config) }
 
-        return if accepted_mime_type?(content_type, config)
+          yield
+        end
 
-        yield
-      end
+        # Yields if an action is configured with `formats`, the request has a `Content-Type` header
+        # (or a `default_requst_format` is configured), and the content type does not match the
+        # accepted formats. The given block is expected to halt the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_mime_types
+        # @see Config#formats
+        #
+        # @since 2.0.0
+        # @api private
+        def enforce_content_type(request, config)
+          content_type = request.content_type
 
-      # @since 2.0.0
-      # @api private
-      def self.accepted_mime_type?(mime_type, config)
-        config.accepted_mime_types.any? { |accepted_mime_type|
-          ::Rack::Mime.match?(accepted_mime_type, mime_type)
-        }
-      end
+          return if content_type.nil?
 
-      # Use for setting the content_type and charset if the response
-      #
-      # @see Hanami::Action::Mime#call
-      #
-      # @return [String]
-      #
-      # @since 2.0.0
-      # @api private
-      def self.calculate_content_type_with_charset(config, request, accepted_mime_types)
-        charset = self.charset(config.default_charset)
-        content_type = self.content_type(config, request, accepted_mime_types)
-        content_type_with_charset(content_type, charset)
-      end
+          return if accepted_mime_type?(content_type, config)
 
-      # Patched version of <tt>Rack::Utils.best_q_match</tt>.
-      #
-      # @since 2.0.0
-      # @api private
-      #
-      # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
-      # @see https://github.com/rack/rack/pull/659
-      # @see https://github.com/hanami/controller/issues/59
-      # @see https://github.com/hanami/controller/issues/104
-      # @see https://github.com/hanami/controller/issues/275
-      def self.best_q_match(q_value_header, available_mimes = TYPES.values)
-        ::Rack::Utils.q_values(q_value_header).each_with_index.map do |(req_mime, quality), index|
-          match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
-          next unless match
+          yield
+        end
 
-          RequestMimeWeight.new(req_mime, quality, index, match)
-        end.compact.max&.format
-      end
+        private
 
-      # @since 1.0.1
-      # @api private
-      class RequestMimeWeight
         # @since 2.0.0
         # @api private
-        MIME_SEPARATOR = "/"
-        private_constant :MIME_SEPARATOR
+        def accepted_mime_type?(mime_type, config)
+          accepted_mime_types(config).any? { |accepted_mime_type|
+            ::Rack::Mime.match?(accepted_mime_type, mime_type)
+          }
+        end
 
         # @since 2.0.0
         # @api private
-        MIME_WILDCARD = "*"
-        private_constant :MIME_WILDCARD
-
-        include Comparable
-
-        # @since 1.0.1
-        # @api private
-        attr_reader :quality
+        def accepted_mime_types(config)
+          return [ANY_TYPE] if config.formats.empty?
 
-        # @since 1.0.1
-        # @api private
-        attr_reader :index
+          config.formats.map { |format| format_to_mime_types(format, config) }.flatten(1)
+        end
 
-        # @since 1.0.1
+        # @since 2.0.0
         # @api private
-        attr_reader :mime
+        def response_content_type(request, config)
+          if request.accept_header?
+            all_mime_types = TYPES.values + config.formats.mapping.keys
+            content_type = best_q_match(request.accept, all_mime_types)
 
-        # @since 1.0.1
-        # @api private
-        attr_reader :format
+            return content_type if content_type
+          end
 
-        # @since 1.0.1
-        # @api private
-        attr_reader :priority
+          if config.formats.default
+            return format_to_mime_type(config.formats.default, config)
+          end
 
-        # @since 1.0.1
-        # @api private
-        def initialize(mime, quality, index, format = mime)
-          @quality, @index, @format = quality, index, format
-          calculate_priority(mime)
+          Action::DEFAULT_CONTENT_TYPE
         end
 
-        # @since 1.0.1
+        # @since 2.0.0
         # @api private
-        def <=>(other)
-          return priority <=> other.priority unless priority == other.priority
-
-          other.index <=> index
+        def format_to_mime_type(format, config)
+          config.formats.mime_type_for(format) ||
+            TYPES.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
         end
 
-        private
-
-        # @since 1.0.1
+        # @since 2.0.0
         # @api private
-        def calculate_priority(mime)
-          @priority ||= (mime.split(MIME_SEPARATOR, 2).count(MIME_WILDCARD) * -10) + quality
+        def format_to_mime_types(format, config)
+          config.formats.mime_types_for(format).tap { |types|
+            types << TYPES[format] if TYPES.key?(format)
+          }
         end
       end
     end

data/lib/hanami/action/params.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "hanami/action/base_params"
 require "hanami/validations/form"
 
 module Hanami

data/lib/hanami/action/rack/file.rb

@@ -4,13 +4,17 @@ require "rack/file"
 
 module Hanami
   class Action
+    # Rack extensions for actions.
+    #
+    # @api private
+    # @since 0.4.3
     module Rack
       # File to be sent
       #
+      # @see Hanami::Action::Response#send_file
+      #
       # @since 0.4.3
       # @api private
-      #
-      # @see Hanami::Action::Rack#send_file
       class File
         # @param path [String,Pathname] file path
         #

data/lib/hanami/action/request.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 
-require "hanami/action/flash"
 require "rack/mime"
 require "rack/request"
 require "rack/utils"
 require "securerandom"
+require_relative "errors"
 
 module Hanami
   class Action
-    # An HTTP request based on top of Rack::Request.
-    # This guarantees backwards compatibility with with Rack.
+    # The HTTP request for an action, given to {Action#handle}.
     #
-    # @since 0.3.1
+    # Inherits from `Rack::Request`, providing compatibility with Rack functionality.
     #
     # @see http://www.rubydoc.info/gems/rack/Rack/Request
+    #
+    # @since 0.3.1
     class Request < ::Rack::Request
+      # Returns the request's params.
+      #
+      # For an action with {Validatable} included, this will be a {Params} instance, otherwise a
+      # {BaseParams}.
+      #
+      # @return [BaseParams,Params]
+      #
+      # @since 2.0.0
+      # @api public
       attr_reader :params
 
+      # @since 2.0.0
+      # @api private
       def initialize(env:, params:, sessions_enabled: false)
         super(env)
 
@@ -24,11 +36,27 @@ module Hanami
         @sessions_enabled = sessions_enabled
       end
 
+      # Returns the request's ID
+      #
+      # @return [String]
+      #
+      # @since 2.0.0
+      # @api public
       def id
         # FIXME: make this number configurable and document the probabilities of clashes
         @id ||= @env[Action::REQUEST_ID] = SecureRandom.hex(Action::DEFAULT_ID_LENGTH)
       end
 
+      # Returns the session for the request.
+      #
+      # @return [Hash] the session object
+      #
+      # @raise [MissingSessionError] if sessions are not enabled
+      #
+      # @see Response#session
+      #
+      # @since 2.0.0
+      # @api public
       def session
         unless @sessions_enabled
           raise Hanami::Action::MissingSessionError.new("Hanami::Action::Request#session")
@@ -37,6 +65,16 @@ module Hanami
         super
       end
 
+      # Returns the flash for the request.
+      #
+      # @return [Flash]
+      #
+      # @raise [MissingSessionError] if sessions are not enabled
+      #
+      # @see Response#flash
+      #
+      # @since 2.0.0
+      # @api public
       def flash
         unless @sessions_enabled
           raise Hanami::Action::MissingSessionError.new("Hanami::Action::Request#flash")
@@ -45,12 +83,16 @@ module Hanami
         @flash ||= Flash.new(session[Flash::KEY])
       end
 
+      # @since 2.0.0
+      # @api private
       def accept?(mime_type)
         !!::Rack::Utils.q_values(accept).find do |mime, _|
           ::Rack::Mime.match?(mime_type, mime)
         end
       end
 
+      # @since 2.0.0
+      # @api private
       def accept_header?
         accept != Action::DEFAULT_ACCEPT
       end