hanami-controller 2.0.0.beta1 → 2.0.0.rc1

data/lib/hanami/action/flash.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
+# The Hanami::Action::Flash implementation is derived from Roda's FlashHash, also released under the
+# MIT Licence:
+#
+# Copyright (c) 2014-2020 Jeremy Evans
+# Copyright (c) 2010-2014 Michel Martens, Damian Janowski and Cyril David
+# Copyright (c) 2008-2009 Christian Neukirchen
+
 module Hanami
   class Action
-    # A container to transport data with the HTTP session, with a lifespan of
-    # just one HTTP request or redirect.
-    #
-    # Behaves like a hash, returning entries for the current request, except for
-    # {#[]=}, which updates the hash for the next request.
+    # A container to transport data with the HTTP session, with a lifespan of just one HTTP request
+    # or redirect.
     #
-    # This implementation is derived from Roda's FlashHash, also released under
-    # the MIT Licence:
-    #
-    # Copyright (c) 2014-2020 Jeremy Evans
-    # Copyright (c) 2010-2014 Michel Martens, Damian Janowski and Cyril David
-    # Copyright (c) 2008-2009 Christian Neukirchen
+    # Behaves like a hash, returning entries for the current request, except for {#[]=}, which
+    # updates the hash for the next request.
     #
     # @since 0.3.0
     # @api public
@@ -30,9 +30,9 @@ module Hanami
       # @api public
       attr_reader :next
 
-      # Initializes a new flash instance
+      # Returns a new flash object.
       #
-      # @param hash [Hash, nil] the flash hash for the current request. nil will become an empty hash.
+      # @param hash [Hash, nil] the flash hash for the current request; `nil` will become an empty hash.
       #
       # @since 0.3.0
       # @api public
@@ -41,7 +41,9 @@ module Hanami
         @next = {}
       end
 
-      # @return [Hash] The flash hash for the current request
+      # Returns the flash hash for the current request.
+      #
+      # @return [Hash] the flash hash for the current request
       #
       # @since 2.0.0
       # @api public
@@ -49,7 +51,7 @@ module Hanami
         @flash
       end
 
-      # Returns the value for the given key in the current hash
+      # Returns the value for the given key in the current hash.
       #
       # @param key [Object] the key
       #
@@ -61,7 +63,7 @@ module Hanami
         @flash[key]
       end
 
-      # Updates the next hash with the given key and value
+      # Updates the next hash with the given key and value.
       #
       # @param key [Object] the key
       # @param value [Object] the value
@@ -72,9 +74,12 @@ module Hanami
         @next[key] = value
       end
 
-      # Calls the given block once for each element in the current hash
+      # Calls the given block once for each element in the current hash.
       #
-      # @param block [Proc]
+      # @yieldparam element [Array<(Object, Object)>] array containing the key and value from the
+      #   hash
+      #
+      # @return [now]
       #
       # @since 1.2.0
       # @api public
@@ -82,10 +87,12 @@ module Hanami
         @flash.each(&block)
       end
 
-      # Returns a new array with the results of running block once for every
-      # element in the current hash
+      # Returns an array of objects returned by the block, called once for each element in the
+      # current hash.
+      #
+      # @yieldparam element [Array<(Object, Object)>] array containing the key and value from the
+      #   hash
       #
-      # @param block [Proc]
       # @return [Array]
       #
       # @since 1.2.0
@@ -114,7 +121,7 @@ module Hanami
         @flash.key?(key)
       end
 
-      # Removes entries from the next hash
+      # Removes entries from the next hash.
       #
       # @overload discard(key)
       #   Removes the given key from the next hash

data/lib/hanami/action/halt.rb

@@ -4,9 +4,11 @@ require "hanami/http/status"
 
 module Hanami
   class Action
+    # @api private
+    # @since 2.0.0
     module Halt
-      # @since 2.0.0
       # @api private
+      # @since 2.0.0
       def self.call(status, body = nil)
         body ||= Http::Status.message_for(status)
         throw :halt, [status, body]

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
@@ -84,13 +85,13 @@ module Hanami
       #
       # @since 2.0.0
       # @api private
-      def self.content_type(configuration, request, accepted_mime_types)
+      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
         end
 
-        default_response_type(configuration) || default_content_type(configuration) || Action::DEFAULT_CONTENT_TYPE
+        default_response_type(config) || default_content_type(config) || Action::DEFAULT_CONTENT_TYPE
       end
 
       # @since 2.0.0
@@ -101,23 +102,23 @@ module Hanami
 
       # @since 2.0.0
       # @api private
-      def self.default_response_type(configuration)
-        format_to_mime_type(configuration.default_response_format, configuration)
+      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(configuration)
-        format_to_mime_type(configuration.default_request_format, configuration)
+      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, configuration)
+      def self.format_to_mime_type(format, config)
         return if format.nil?
 
-        configuration.mime_type_for(format) ||
-          TYPES.fetch(format) { raise Hanami::Controller::UnknownFormatError.new(format) }
+        config.mime_type_for(format) ||
+          TYPES.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
       end
 
       # Transforms MIME Types to symbol
@@ -125,17 +126,17 @@ module Hanami
       #
       # @see Hanami::Action::Mime#finish
       # @example
-      #   detect_format("text/html; charset=utf-8", configuration)  #=> :html
+      #   detect_format("text/html; charset=utf-8", config)  #=> :html
       #
       # @return [Symbol, nil]
       #
       # @since 2.0.0
       # @api private
-      def self.detect_format(content_type, configuration)
+      def self.detect_format(content_type, config)
         return if content_type.nil?
 
         ct = content_type.split(";").first
-        configuration.format_for(ct) || format_for(ct)
+        config.format_for(ct) || format_for(ct)
       end
 
       # @since 2.0.0
@@ -144,63 +145,108 @@ module Hanami
         TYPES.key(content_type)
       end
 
+      # @since 2.0.0
+      # @api private
+      def self.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
+
       # Transforms symbols to MIME Types
       # @example
-      #   restrict_mime_types(configuration, [:json])  #=> ["application/json"]
+      #   restrict_mime_types(config, [:json])  #=> ["application/json"]
       #
       # @return [Array<String>, nil]
       #
-      # @raise [Hanami::Controller::UnknownFormatError] if the format is invalid
+      # @raise [Hanami::Action::UnknownFormatError] if the format is invalid
       #
       # @since 2.0.0
       # @api private
-      def self.restrict_mime_types(configuration, accepted_formats)
-        return if accepted_formats.empty?
+      def self.restrict_mime_types(config)
+        return if config.accepted_formats.empty?
 
-        mime_types = accepted_formats.map do |format|
-          format_to_mime_type(format, configuration)
+        mime_types = config.accepted_formats.map do |format|
+          format_to_mime_type(format, config)
         end
 
-        accepted_mime_types = mime_types & configuration.mime_types
+        accepted_mime_types = mime_types & config.mime_types
 
         return if accepted_mime_types.empty?
 
         accepted_mime_types
       end
 
-      # Use for checking the Content-Type header to make sure is valid based
-      # on the accepted_mime_types
+      # 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 no Content-Type is sent in the request it will check the default_request_format
+      # If any of these conditions are not met, then the request is acceptable and the method
+      # returns without yielding.
       #
-      # @return [TrueClass, FalseClass]
+      # @see Action#enforce_accepted_mime_types
+      # @see Action.accept
+      # @see Config#accepted_formats
       #
       # @since 2.0.0
       # @api private
-      def self.accepted_mime_type?(request, accepted_mime_types, configuration)
-        mime_type = request.env[Action::HTTP_CONTENT_TYPE] ||
-                    default_content_type(configuration) ||
-                    Action::DEFAULT_CONTENT_TYPE
+      def self.enforce_accept(request, config)
+        return unless request.accept_header?
+
+        accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
+        return if accept_types.any? { |mime_type| accepted_mime_type?(mime_type, config) }
 
-        !accepted_mime_types.find { |mt| ::Rack::Mime.match?(mt, mime_type) }.nil?
+        yield
       end
 
-      # Use for setting the content_type and charset if the response
+      # 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 Hanami::Action::Mime#call
+      # @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)
+
+        return if content_type.nil?
+
+        return if accepted_mime_type?(content_type, config)
+
+        yield
+      end
+
+      # @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
+
+      # Use for setting the content_type and charset if the response
       #
       # @return [String]
       #
       # @since 2.0.0
       # @api private
-      def self.calculate_content_type_with_charset(configuration, request, accepted_mime_types)
-        charset      = self.charset(configuration.default_charset)
-        content_type = self.content_type(configuration, request, accepted_mime_types)
+      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
 
-      # private
-
       # Patched version of <tt>Rack::Utils.best_q_match</tt>.
       #
       # @since 2.0.0

data/lib/hanami/action/params.rb

@@ -25,7 +25,7 @@ module Hanami
         # @since 1.1.0
         # @api private
         def initialize(errors = {})
-          super(errors)
+          super(errors.dup)
         end
 
         # Add an error to the param validations
@@ -160,9 +160,9 @@ module Hanami
       def initialize(env)
         @env = env
         super(_extract_params)
-        @result = validate
-        @params = _params
-        @errors = Errors.new(@result.messages)
+        validation = validate
+        @params = validation.to_h
+        @errors = Errors.new(validation.messages)
         freeze
       end
 
@@ -235,7 +235,7 @@ module Hanami
         errors.empty?
       end
 
-      # Serialize params to Hash
+      # Serialize validated params to Hash
       #
       # @return [::Hash]
       #
@@ -244,13 +244,6 @@ module Hanami
         @params
       end
       alias_method :to_hash, :to_h
-
-      private
-
-      # @api private
-      def _params
-        _router_params.merge(@result.output)
-      end
     end
   end
 end

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,37 +1,99 @@
 # frozen_string_literal: true
 
-require "rack/utils"
+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
 
-      def initialize(env, params)
+      # @since 2.0.0
+      # @api private
+      def initialize(env:, params:, sessions_enabled: false)
         super(env)
+
         @params = params
+        @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")
+        end
+
+        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")
+        end
+
+        @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