hanami-controller 2.0.0.beta4 → 2.0.0.rc1

data/lib/hanami/action/response.rb

@@ -8,9 +8,18 @@ require "hanami/action/cookie_jar"
 require "hanami/action/cache/cache_control"
 require "hanami/action/cache/expires"
 require "hanami/action/cache/conditional_get"
+require_relative "errors"
 
 module Hanami
   class Action
+    # The HTTP response for an action, given to {Action#handle}.
+    #
+    # Inherits from `Rack::Response`, providing compatibility with Rack functionality.
+    #
+    # @see http://www.rubydoc.info/gems/rack/Rack/Response
+    #
+    # @since 2.0.0
+    # @api private
     class Response < ::Rack::Response
       # @since 2.0.0
       # @api private
@@ -26,7 +35,7 @@ module Hanami
 
       # @since 2.0.0
       # @api private
-      attr_reader :request, :exposures, :format, :env, :view_options
+      attr_reader :request, :exposures, :env, :view_options
 
       # @since 2.0.0
       # @api private
@@ -46,7 +55,7 @@ module Hanami
       # @api private
       def initialize(request:, config:, content_type: nil, env: {}, headers: {}, view_options: nil, sessions_enabled: false) # rubocop:disable Layout/LineLength, Metrics/ParameterLists
         super([], 200, headers.dup)
-        set_header(Action::CONTENT_TYPE, content_type)
+        self.content_type = content_type if content_type
 
         @request = request
         @config = config
@@ -59,6 +68,10 @@ module Hanami
         @sending_file = false
       end
 
+      # Sets the response body.
+      #
+      # @param str [String] the body string
+      #
       # @since 2.0.0
       # @api public
       def body=(str)
@@ -73,32 +86,96 @@ module Hanami
         end
       end
 
-      # @since 2.0.0
-      # @api public
+      # This is NOT RELEASED with 2.0.0
+      #
+      # @api private
       def render(view, **options)
         self.body = view.(**view_options.(request, self), **exposures.merge(options)).to_str
       end
 
+      # Returns the format for the response.
+      #
+      # Returns nil if a format has not been assigned and also cannot be determined from the
+      # response's `#content_type`.
+      #
+      # @example
+      #   response.format # => :json
+      #
+      # @return [Symbol, nil]
+      #
       # @since 2.0.0
       # @api public
-      def format=(args)
-        @format, content_type = *args
-        content_type = Action::Mime.content_type_with_charset(content_type, charset)
-        set_header("Content-Type", content_type)
+      def format
+        @format ||= Mime.detect_format(content_type, @config)
       end
 
+      # Sets the format and associated content type for the response.
+      #
+      # Either a format name (`:json`) or a content type string (`"application/json"`) may be given.
+      # In either case, the format or content type will be derived from the given value, and both
+      # will be set.
+      #
+      # @example Assigning via a format name symbol
+      #   response.format = :json
+      #   response.content_type # => "application/json"
+      #   response.headers["Content-Type"] # => "application/json"
+      #
+      # @example Assigning via a content type string
+      #   response.format = "application/json"
+      #   response.format # => :json
+      #   response.content_type # => "application/json"
+      #
+      # @param value [Symbol, String] the format name or content type
+      #
+      # @see Config#formats
+      #
+      # @since 2.0.0
+      # @api public
+      def format=(value)
+        format, content_type = Mime.detect_format_and_content_type(value, @config)
+
+        self.content_type = Mime.content_type_with_charset(content_type, charset)
+
+        @format = format
+      end
+
+      # Returns the exposure value for the given key.
+      #
+      # @param key [Object]
+      #
+      # @return [Object] the exposure value, if found
+      #
+      # @raise [KeyError] if the exposure was not found
+      #
       # @since 2.0.0
       # @api public
       def [](key)
         @exposures.fetch(key)
       end
 
+      # Sets an exposure value for the given key.
+      #
+      # @param key [Object]
+      # @param value [Object]
+      #
+      # @return [Object] the value
+      #
       # @since 2.0.0
       # @api public
       def []=(key, value)
         @exposures[key] = value
       end
 
+      # Returns the session for the response.
+      #
+      # This is the same session object as the {Request}.
+      #
+      # @return [Hash] the session object
+      #
+      # @raise [MissingSessionError] if sessions are not enabled
+      #
+      # @see Request#session
+      #
       # @since 2.0.0
       # @api public
       def session
@@ -109,6 +186,16 @@ module Hanami
         request.session
       end
 
+      # Returns the flash for the request.
+      #
+      # This is the same flash object as the {Request}.
+      #
+      # @return [Flash]
+      #
+      # @raise [MissingSessionError] if sessions are not enabled
+      #
+      # @see Request#flash
+      #
       # @since 2.0.0
       # @api public
       def flash
@@ -119,12 +206,21 @@ module Hanami
         request.flash
       end
 
+      # Returns the set of cookies to be included in the response.
+      #
+      # @return [CookieJar]
+      #
       # @since 2.0.0
       # @api public
       def cookies
         @cookies ||= CookieJar.new(env.dup, headers, @config.cookies)
       end
 
+      # Sets the response to redirect to the given URL and halts further handling.
+      #
+      # @param url [String]
+      # @param status [Integer] the HTTP status to use for the redirect
+      #
       # @since 2.0.0
       # @api public
       def redirect_to(url, status: 302)
@@ -134,6 +230,22 @@ module Hanami
         Halt.call(status)
       end
 
+      # Sends the file at the given path as the response, for any file within the configured
+      # `public_directory`.
+      #
+      # Handles the following aspects for file responses:
+      #
+      # - Setting `Content-Type` and `Content-Length` headers
+      # - File Not Found responses (returns a 404)
+      # - Conditional GET (via `If-Modified-Since` header)
+      # - Range requests (via `Range` header)
+      #
+      # @param path [String] the file path
+      #
+      # @return [void]
+      #
+      # @see Config#public_directory
+      #
       # @since 2.0.0
       # @api public
       def send_file(path)
@@ -142,6 +254,14 @@ module Hanami
         )
       end
 
+      # Send the file at the given path as the response, for a file anywhere in the file system.
+      #
+      # @see #send_file
+      #
+      # @param path [String, Pathname] path to the file to be sent
+      #
+      # @return [void]
+      #
       # @since 2.0.0
       # @api public
       def unsafe_send_file(path)
@@ -156,6 +276,37 @@ module Hanami
         )
       end
 
+      # Specifies the response freshness policy for HTTP caches using the `Cache-Control` header.
+      #
+      # Any number of non-value directives (`:public`, `:private`, `:no_cache`, `:no_store`,
+      # `:must_revalidate`, `:proxy_revalidate`) may be passed along with a Hash of value directives
+      # (`:max_age`, `:min_stale`, `:s_max_age`).
+      #
+      # See [RFC 2616 / 14.9](http://tools.ietf.org/html/rfc2616#section-14.9.1) for more on
+      # standard cache control directives.
+      #
+      # @example
+      #   # Set Cache-Control directives
+      #   response.cache_control :public, max_age: 900, s_maxage: 86400
+      #
+      #   # Overwrite previous Cache-Control directives
+      #   response.cache_control :private, :no_cache, :no_store
+      #
+      #   response.get_header("Cache-Control") # => "private, no-store, max-age=900"
+      #
+      # @param values [Array<Symbol, Hash>] values to map to `Cache-Control` directives
+      # @option values [Symbol] :public
+      # @option values [Symbol] :private
+      # @option values [Symbol] :no_cache
+      # @option values [Symbol] :no_store
+      # @option values [Symbol] :must_validate
+      # @option values [Symbol] :proxy_revalidate
+      # @option values [Hash] :max_age
+      # @option values [Hash] :min_stale
+      # @option values [Hash] :s_max_age
+      #
+      # @return void
+      #
       # @since 2.0.0
       # @api public
       def cache_control(*values)
@@ -163,6 +314,28 @@ module Hanami
         headers.merge!(directives.headers)
       end
 
+      # Sets the `Expires` header and `Cache-Control`/`max-age` directive for the response.
+      #
+      # You can provide an integer number of seconds in the future, or a Time object indicating when
+      # the response should be considered "stale". The remaining arguments are passed to
+      # {#cache_control}.
+      #
+      # @example
+      #   # Set Cache-Control directives and Expires
+      #   response.expires 900, :public
+      #
+      #   # Overwrite Cache-Control directives and Expires
+      #   response.expires 300, :private, :no_cache, :no_store
+      #
+      #   response.get_header("Expires") # => "Thu, 26 Jun 2014 12:00:00 GMT"
+      #   response.get_header("Cache-Control") # => "private, no-cache, no-store max-age=300"
+      #
+      # @param amount [Integer, Time] number of seconds or point in time
+      # @param values [Array<Symbols>] values to map to `Cache-Control` directives via
+      #   {#cache_control}
+      #
+      # @return void
+      #
       # @since 2.0.0
       # @api public
       def expires(amount, *values)
@@ -170,6 +343,26 @@ module Hanami
         headers.merge!(directives.headers)
       end
 
+      # Sets the `etag` and/or `last_modified` headers on the response and halts with a `304 Not
+      # Modified` response if the request is still fresh according to the `IfNoneMatch` and
+      # `IfModifiedSince` request headers.
+      #
+      # @example
+      #   # Set etag header and halt 304 if request matches IF_NONE_MATCH header
+      #   response.fresh etag: some_resource.updated_at.to_i
+      #
+      #   # Set last_modified header and halt 304 if request matches IF_MODIFIED_SINCE
+      #   response.fresh last_modified: some_resource.updated_at
+      #
+      #   # Set etag and last_modified header and halt 304 if request matches IF_MODIFIED_SINCE and IF_NONE_MATCH
+      #   response.fresh last_modified: some_resource.updated_at
+      #
+      # @param options [Hash]
+      # @option options [Integer] :etag for testing IfNoneMatch conditions
+      # @option options [Date] :last_modified for testing IfModifiedSince conditions
+      #
+      # @return void
+      #
       # @since 2.0.0
       # @api public
       def fresh(options)
@@ -183,7 +376,7 @@ module Hanami
       end
 
       # @since 2.0.0
-      # @api public
+      # @api private
       def set_format(value) # rubocop:disable Naming/AccessorMethodName
         @format = value
       end
@@ -209,7 +402,7 @@ module Hanami
       alias_method :to_ary, :to_a
 
       # @since 2.0.0
-      # @api public
+      # @api private
       def head?
         env[Action::REQUEST_METHOD] == Action::HEAD
       end

data/lib/hanami/action/session.rb

@@ -4,12 +4,17 @@ require "hanami/action/flash"
 
 module Hanami
   class Action
-    # Session API
+    # Session support for actions.
     #
-    # This module isn't included by default.
+    # Not included by default; you should include this module manually to enable session support.
+    # For actions within an Hanami app, this module will be included automatically if sessions are
+    # configured in the app config.
     #
+    # @api public
     # @since 0.1.0
     module Session
+      # @api private
+      # @since 0.1.0
       def self.included(base)
         base.class_eval do
           before { |req, _| req.id }

data/lib/hanami/action/validatable.rb

@@ -4,6 +4,12 @@ require "hanami/action/params"
 
 module Hanami
   class Action
+    # Support for validating params when calling actions.
+    #
+    # Included only when hanami-validations (and its dependencies) are bundled.
+    #
+    # @api private
+    # @since 0.1.0
     module Validatable
       # Defines the class name for anonymous params
       #
@@ -34,13 +40,10 @@ module Hanami
         # Once whitelisted, the params are available as an Hash with symbols
         # as keys.
         #
-        #
-        #
         # It accepts an anonymous block where all the params can be listed.
         # It internally creates an inner class which inherits from
         # Hanami::Action::Params.
         #
-        #
         # Alternatively, it accepts an concrete class that should inherit from
         # Hanami::Action::Params.
         #
@@ -49,8 +52,6 @@ module Hanami
         #
         # @return void
         #
-        # @since 0.3.0
-        #
         # @see Hanami::Action::Params
         # @see https://guides.hanamirb.org//validations/overview
         #
@@ -93,6 +94,9 @@ module Hanami
         #       req.params[:admin]               # => nil
         #     end
         #   end
+        #
+        # @since 0.3.0
+        # @api public
         def params(klass = nil, &blk)
           if klass.nil?
             klass = const_set(PARAMS_CLASS_NAME, Class.new(Params))

data/lib/hanami/action.rb

@@ -24,7 +24,7 @@ require_relative "action/mime"
 require_relative "action/rack/file"
 require_relative "action/request"
 require_relative "action/response"
-require_relative "action/error"
+require_relative "action/errors"
 
 module Hanami
   # An HTTP endpoint
@@ -126,71 +126,72 @@ module Hanami
     #
     # @raise [NoMethodError]
     #
-    # @api private
+    # @api public
     # @since 2.0.0
     def self.params(_klass = nil)
       raise NoMethodError,
             "To use `params`, please add 'hanami/validations' gem to your Gemfile"
     end
 
-    # Define a callback for an Action.
-    # The callback will be executed **before** the action is called, in the
-    # order they are added.
+    # @overload self.append_before(*callbacks, &block)
+    #   Define a callback for an Action.
+    #   The callback will be executed **before** the action is called, in the
+    #   order they are added.
     #
-    # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
-    #   each of them is representing a name of a method available in the
-    #   context of the Action.
+    #   @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+    #     each of them is representing a name of a method available in the
+    #     context of the Action.
     #
-    # @param blk [Proc] an anonymous function to be executed
+    #   @param blk [Proc] an anonymous function to be executed
     #
-    # @return [void]
+    #   @return [void]
     #
-    # @since 0.3.2
+    #   @since 0.3.2
     #
-    # @see Hanami::Action::Callbacks::ClassMethods#append_after
+    #   @see Hanami::Action::Callbacks::ClassMethods#append_after
     #
-    # @example Method names (symbols)
-    #   require "hanami/controller"
+    #   @example Method names (symbols)
+    #     require "hanami/controller"
     #
-    #   class Show < Hanami::Action
-    #     before :authenticate, :set_article
+    #     class Show < Hanami::Action
+    #       before :authenticate, :set_article
     #
-    #     def handle(req, res)
-    #     end
+    #       def handle(req, res)
+    #       end
     #
-    #     private
-    #     def authenticate
-    #       # ...
-    #     end
+    #       private
+    #       def authenticate
+    #         # ...
+    #       end
     #
-    #     # `params` in the method signature is optional
-    #     def set_article(params)
-    #       @article = Article.find params[:id]
+    #       # `params` in the method signature is optional
+    #       def set_article(params)
+    #         @article = Article.find params[:id]
+    #       end
     #     end
-    #   end
     #
-    #   # The order of execution will be:
-    #   #
-    #   # 1. #authenticate
-    #   # 2. #set_article
-    #   # 3. #call
+    #     # The order of execution will be:
+    #     #
+    #     # 1. #authenticate
+    #     # 2. #set_article
+    #     # 3. #call
     #
-    # @example Anonymous functions (Procs)
-    #   require "hanami/controller"
+    #   @example Anonymous functions (Procs)
+    #     require "hanami/controller"
     #
-    #   class Show < Hanami::Action
-    #     before { ... } # 1 do some authentication stuff
-    #     before {|req, res| @article = Article.find params[:id] } # 2
+    #     class Show < Hanami::Action
+    #       before { ... } # 1 do some authentication stuff
+    #       before {|req, res| @article = Article.find params[:id] } # 2
     #
-    #     def handle(req, res)
+    #       def handle(req, res)
+    #       end
     #     end
-    #   end
     #
-    #   # The order of execution will be:
-    #   #
-    #   # 1. authentication
-    #   # 2. set the article
-    #   # 3. `#handle`
+    #     # The order of execution will be:
+    #     #
+    #     # 1. authentication
+    #     # 2. set the article
+    #     # 3. `#handle`
     def self.append_before(...)
       config.before_callbacks.append(...)
     end
@@ -200,21 +201,22 @@ module Hanami
       alias_method :before, :append_before
     end
 
-    # Define a callback for an Action.
-    # The callback will be executed **after** the action is called, in the
-    # order they are added.
+    # @overload self.append_after(*callbacks, &block)
+    #   Define a callback for an Action.
+    #   The callback will be executed **after** the action is called, in the
+    #   order they are added.
     #
-    # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
-    #   each of them is representing a name of a method available in the
-    #   context of the Action.
+    #   @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+    #     each of them is representing a name of a method available in the
+    #     context of the Action.
     #
-    # @param blk [Proc] an anonymous function to be executed
+    #   @param blk [Proc] an anonymous function to be executed
     #
-    # @return [void]
+    #   @return [void]
     #
-    # @since 0.3.2
+    #   @since 0.3.2
     #
-    # @see Hanami::Action::Callbacks::ClassMethods#append_before
+    #   @see Hanami::Action::Callbacks::ClassMethods#append_before
     def self.append_after(...)
       config.after_callbacks.append(...)
     end
@@ -224,40 +226,42 @@ module Hanami
       alias_method :after, :append_after
     end
 
-    # Define a callback for an Action.
-    # The callback will be executed **before** the action is called.
-    # It will add the callback at the beginning of the callbacks' chain.
+    # @overload self.prepend_before(*callbacks, &block)
+    #   Define a callback for an Action.
+    #   The callback will be executed **before** the action is called.
+    #   It will add the callback at the beginning of the callbacks' chain.
     #
-    # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
-    #   each of them is representing a name of a method available in the
-    #   context of the Action.
+    #   @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+    #     each of them is representing a name of a method available in the
+    #     context of the Action.
     #
-    # @param blk [Proc] an anonymous function to be executed
+    #   @param blk [Proc] an anonymous function to be executed
     #
-    # @return [void]
+    #   @return [void]
     #
-    # @since 0.3.2
+    #   @since 0.3.2
     #
-    # @see Hanami::Action::Callbacks::ClassMethods#prepend_after
+    #   @see Hanami::Action::Callbacks::ClassMethods#prepend_after
     def self.prepend_before(...)
       config.before_callbacks.prepend(...)
     end
 
-    # Define a callback for an Action.
-    # The callback will be executed **after** the action is called.
-    # It will add the callback at the beginning of the callbacks' chain.
+    # @overload self.prepend_after(*callbacks, &block)
+    #   Define a callback for an Action.
+    #   The callback will be executed **after** the action is called.
+    #   It will add the callback at the beginning of the callbacks' chain.
     #
-    # @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
-    #   each of them is representing a name of a method available in the
-    #   context of the Action.
+    #   @param callbacks [Symbol, Array<Symbol>] a single or multiple symbol(s)
+    #     each of them is representing a name of a method available in the
+    #     context of the Action.
     #
-    # @param blk [Proc] an anonymous function to be executed
+    #   @param blk [Proc] an anonymous function to be executed
     #
-    # @return [void]
+    #   @return [void]
     #
-    # @since 0.3.2
+    #   @since 0.3.2
     #
-    # @see Hanami::Action::Callbacks::ClassMethods#prepend_before
+    #   @see Hanami::Action::Callbacks::ClassMethods#prepend_before
     def self.prepend_after(...)
       config.after_callbacks.prepend(...)
     end
@@ -266,7 +270,7 @@ module Hanami
     #
     # @param formats[Array<Symbol>] one or more symbols representing mime type(s)
     #
-    # @raise [Hanami::Controller::UnknownFormatError] if the symbol cannot
+    # @raise [Hanami::Action::UnknownFormatError] if the symbol cannot
     #   be converted into a mime type
     #
     # @since 0.1.0
@@ -586,20 +590,6 @@ module Hanami
       res.body = Response::EMPTY_BODY
     end
 
-    # @since 2.0.0
-    # @api private
-    def format(value)
-      case value
-      when Symbol
-        format = Utils::Kernel.Symbol(value)
-        [format, Action::Mime.format_to_mime_type(format, config)]
-      when String
-        [Action::Mime.detect_format(value, config), value]
-      else
-        raise Hanami::Controller::UnknownFormatError.new(value)
-      end
-    end
-
     # Finalize the response
     #
     # Prepare the data before the response will be returned to the webserver

data/lib/hanami/controller/version.rb

@@ -2,9 +2,7 @@
 
 module Hanami
   module Controller
-    # Defines the version
-    #
-    # @since 0.1.0
-    VERSION = "2.0.0.beta4"
+    # @api public
+    VERSION = "2.0.0.rc1"
   end
 end

data/lib/hanami/controller.rb

@@ -2,7 +2,6 @@
 
 require "hanami/action"
 require "hanami/controller/version"
-require "hanami/controller/error"
 
 # Hanami
 #
@@ -27,20 +26,5 @@ module Hanami
   #     end
   #   end
   module Controller
-    # Unknown format error
-    #
-    # 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 0.2.0
-    #
-    # @see Hanami::Action::Mime#format=
-    class UnknownFormatError < Hanami::Controller::Error
-      # @since 0.2.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
   end
 end