hanami-controller 2.0.0.beta4 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a363029b7df3ddc560e2975862f72548788a2a2910c2d32519f073556b4bfbb2
-  data.tar.gz: e7d67505e3b0161a656d24e1ff634bd02c11d4fad1e217a1ee482271be6dbbd9
+  metadata.gz: 0a5d623c09e8ecb8c267de856196333c5da74e066b55501af2acc706349d0d73
+  data.tar.gz: '0786076a81b7a11ca79aedba2ff0318f207683e71ba931293dcc1f585a191e0b'
 SHA512:
-  metadata.gz: 0a9aeb4ea44db1fe6f137dee8f3e5e05bda318a8c53f1f57c30204a0077b5dcfd82aefab569fd7169c2c728de2331fcaa52f1fcdec2e3adb6d4679c38791edf6
-  data.tar.gz: 726de07b87cd8055da9973ea0365c00bde1f8808a1593ef3830051e196c722f001f6dc13615182f067542c605c9437259d1d36028031867edf3abd8d9612e817
+  metadata.gz: 81f1cddefe11892d05ccb63e8649bc9fb6e50f2258eb02503044577e9c0e445c57cbf2318046a4002e3c9b107f9df530463cbeb10460bb3339bb52b747deb0eb
+  data.tar.gz: eb26f557543e0d345580b9160ec4123def85b4a4ec5a1ad0a17f8a8d15d05dc34f12e13705082e21b95a5cc3095d36677b099a319a1c2472c7180e413f5c5faf

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Complete, fast and testable actions for Rack
 
+## v2.0.0.rc1 - 2022-11-08
+
+### Changed
+
+- [Tim Riley] Simplify assignment of response format: `response.format = :json` (was `response.format = format(:json)`)
+
 ## v2.0.0.beta4 - 2022-10-24
 
 ### Added

data/README.md

@@ -744,7 +744,7 @@ However, you can force this value:
 class Show < Hanami::Action
   def handle(*, res)
     # ...
-    res.format = format(:json)
+    res.format = :json
   end
 end
 
@@ -820,7 +820,7 @@ response.format                                                   # => :custom
 class Show < Hanami::Action
   def handle(*, res)
     # ...
-    res.format = format(:custom)
+    res.format = :custom
   end
 end
 
@@ -841,7 +841,7 @@ end
 
 class Csv < Hanami::Action
   def handle(*, res)
-    res.format = format(:csv)
+    res.format = :csv
     res.body = Enumerator.new do |yielder|
       yielder << csv_header
 

data/hanami-controller.gemspec

@@ -21,8 +21,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.0"
 
   spec.add_dependency "rack",         "~> 2.0"
-  spec.add_dependency "hanami-utils", "~> 2.0.beta"
-  spec.add_dependency "dry-configurable", "~> 0.13", ">= 0.13.0"
+  spec.add_dependency "hanami-utils", "~> 2.0.0.rc1"
+  spec.add_dependency "dry-configurable", "~> 1.0", "< 2"
 
   spec.add_development_dependency "bundler",   ">= 1.6", "< 3"
   spec.add_development_dependency "rack-test", "~> 2.0"

data/lib/hanami/action/base_params.rb

@@ -5,6 +5,19 @@ require "hanami/utils/hash"
 
 module Hanami
   class Action
+    # Provides access to params included in a Rack request.
+    #
+    # Offers useful access to params via methods like {#[]}, {#get} and {#to_h}.
+    #
+    # These params are available via {Request#params}.
+    #
+    # This class is used by default when {Hanami::Action::Validatable} is not included, or when no
+    # {Validatable::ClassMethods#params params} validation schema is defined.
+    #
+    # @see Hanami::Action::Request#params
+    #
+    # @api private
+    # @since 0.7.0
     class BaseParams
       # @attr_reader env [Hash] the Rack env
       #
@@ -18,12 +31,10 @@ module Hanami
       # @api private
       attr_reader :raw
 
-      # Initialize the params and freeze them.
+      # Returns a new frozen params object for the Rack env.
       #
       # @param env [Hash] a Rack env or an hash of params.
       #
-      # @return [Params]
-      #
       # @since 0.7.0
       # @api private
       def initialize(env)
@@ -33,26 +44,27 @@ module Hanami
         freeze
       end
 
-      # Returns the object associated with the given key
+      # Returns the value for the given params key.
       #
       # @param key [Symbol] the key
       #
-      # @return [Object,nil] return the associated object, if found
+      # @return [Object,nil] the associated value, if found
       #
       # @since 0.7.0
+      # @api public
       def [](key)
         @params[key]
       end
 
-      # Get an attribute value associated with the given key.
-      # Nested attributes are reached by listing all the keys to get to the value.
+      # Returns an value associated with the given params key.
+      #
+      # You can access nested attributes by listing all the keys in the path. This uses the same key
+      # path semantics as `Hash#dig`.
       #
       # @param keys [Array<Symbol,Integer>] the key
       #
       # @return [Object,NilClass] return the associated value, if found
       #
-      # @since 0.7.0
-      #
       # @example
       #   require "hanami/controller"
       #
@@ -73,6 +85,9 @@ module Hanami
       #       end
       #     end
       #   end
+      #
+      # @since 0.7.0
+      # @api public
       def get(*keys)
         @params.dig(*keys)
       end
@@ -83,32 +98,40 @@ module Hanami
       # @since 0.8.0
       alias_method :dig, :get
 
-      # Provide a common interface with Params
+      # Returns true at all times, providing a common interface with {Params}.
       #
       # @return [TrueClass] always returns true
       #
-      # @since 0.7.0
-      #
       # @see Hanami::Action::Params#valid?
+      #
+      # @api public
+      # @since 0.7.0
       def valid?
         true
       end
 
-      # Serialize params to Hash
+      # Returns a hash of the parsed request params.
       #
-      # @return [::Hash]
+      # @return [Hash]
       #
       # @since 0.7.0
+      # @api public
       def to_h
         @params
       end
       alias_method :to_hash, :to_h
 
-      # Iterates through params
+      # Iterates over the params.
+      #
+      # Calls the given block with each param key-value pair; returns the full hash of params.
+      #
+      # @yieldparam key [Symbol]
+      # @yieldparam value [Object]
       #
-      # @param blk [Proc]
+      # @return [to_h]
       #
       # @since 0.7.1
+      # @api public
       def each(&blk)
         to_h.each(&blk)
       end

data/lib/hanami/action/config.rb

@@ -5,6 +5,12 @@ require_relative "mime"
 
 module Hanami
   class Action
+    # Config for `Hanami::Action` classes.
+    #
+    # @see Hanami::Action.config
+    #
+    # @api public
+    # @since 2.0.0
     class Config < Dry::Configurable::Config
       # Default MIME type to format mapping
       #
@@ -151,7 +157,7 @@ module Hanami
       #
       #   The given format must be coercible to a symbol, and be a valid MIME
       #   type alias. If it isn't, at runtime the framework will raise an
-      #   `Hanami::Controller::UnknownFormatError`.
+      #   `Hanami::Action::UnknownFormatError`.
       #
       #   By default, this value is nil.
       #
@@ -168,7 +174,7 @@ module Hanami
       #
       #   The given format must be coercible to a symbol, and be a valid MIME
       #   type alias. If it isn't, at the runtime the framework will raise an
-      #   `Hanami::Controller::UnknownFormatError`.
+      #   `Hanami::Action::UnknownFormatError`.
       #
       #   By default, this value is nil.
       #

data/lib/hanami/action/constants.rb

@@ -116,12 +116,6 @@ module Hanami
     # @api private
     HTTP_ACCEPT = "HTTP_ACCEPT"
 
-    # The header key to set the mime type of the response
-    #
-    # @since 0.1.0
-    # @api private
-    CONTENT_TYPE = ::Rack::CONTENT_TYPE
-
     # The default mime type for an incoming HTTP request
     #
     # @since 0.1.0

data/lib/hanami/action/csrf_protection.rb

@@ -1,19 +1,13 @@
 # frozen_string_literal: true
 
 require "hanami/utils/blank"
-require "hanami/controller/error"
 require "rack/utils"
 require "securerandom"
+require_relative "errors"
 
 module Hanami
   # @api private
   class Action
-    # Invalid CSRF Token
-    #
-    # @since 0.4.0
-    class InvalidCSRFTokenError < Controller::Error
-    end
-
     # CSRF Protection
     #
     # This security mechanism is enabled automatically if sessions are turned on.

data/lib/hanami/action/{error.rb → errors.rb}

@@ -2,22 +2,44 @@
 
 module Hanami
   class Action
+    # Base class for all Action errors.
+    #
+    # @api public
     # @since 2.0.0
     class Error < ::StandardError
     end
 
-    # Missing session error
+    # Unknown format error
     #
-    # This error is raised when `session` or `flash` is accessed/set on request/response objects
-    # in actions which do not include `Hanami::Action::Session`.
+    # This error is raised when a action sets a format that it isn't recognized
+    # both by `Hanami::Action::Configuration` and the list of Rack mime types
     #
     # @since 2.0.0
     #
+    # @see Hanami::Action::Mime#format=
+    class UnknownFormatError < Error
+      # @since 2.0.0
+      # @api private
+      def initialize(format)
+        super("Cannot find a corresponding Mime type for '#{format}'. Please configure it with Hanami::Controller::Configuration#format.") # rubocop:disable Layout/LineLength
+      end
+    end
+
+    # Error raised when session is accessed but not enabled.
+    #
+    # This error is raised when `session` or `flash` is accessed/set on request/response objects
+    # in actions which do not include `Hanami::Action::Session`.
+    #
     # @see Hanami::Action::Session
     # @see Hanami::Action::Request#session
     # @see Hanami::Action::Response#session
     # @see Hanami::Action::Response#flash
+    #
+    # @api public
+    # @since 2.0.0
     class MissingSessionError < Error
+      # @api private
+      # @since 2.0.0
       def initialize(session_method)
         super(<<~TEXT)
           Sessions are not enabled. To use `#{session_method}`:
@@ -37,5 +59,11 @@ module Hanami
         TEXT
       end
     end
+
+    # Invalid CSRF Token
+    #
+    # @since 0.4.0
+    class InvalidCSRFTokenError < Error
+    end
   end
 end

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
@@ -117,7 +118,7 @@ module Hanami
         return if format.nil?
 
         config.mime_type_for(format) ||
-          TYPES.fetch(format) { raise Hanami::Controller::UnknownFormatError.new(format) }
+          TYPES.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
       end
 
       # Transforms MIME Types to symbol
@@ -144,13 +145,26 @@ 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(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
@@ -223,8 +237,6 @@ module Hanami
 
       # Use for setting the content_type and charset if the response
       #
-      # @see Hanami::Action::Mime#call
-      #
       # @return [String]
       #
       # @since 2.0.0

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

@@ -5,18 +5,31 @@ 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 +37,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 +66,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 +84,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