hanami-controller 2.0.0.beta4 → 2.0.0

data/lib/hanami/action/response.rb

@@ -3,14 +3,18 @@
 require "rack"
 require "rack/response"
 require "hanami/utils/kernel"
-require "hanami/action/halt"
-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 +30,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
@@ -35,10 +39,10 @@ module Hanami
       # @since 2.0.0
       # @api private
       def self.build(status, env)
-        new(config: nil, content_type: Mime.best_q_match(env[Action::HTTP_ACCEPT]), env: env).tap do |r|
+        new(config: Action.config.dup, content_type: Mime.best_q_match(env[Action::HTTP_ACCEPT]), env: env).tap do |r|
           r.status = status
           r.body   = Http::Status.message_for(status)
-          r.set_format(Mime.format_for(r.content_type))
+          r.set_format(Mime.detect_format(r.content_type), config)
         end
       end
 
@@ -46,7 +50,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 +63,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 +81,101 @@ 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 MIME type (`"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.
+      #
+      # Providing an unknown format name will raise an {Hanami::Action::UnknownFormatError}.
+      #
+      # Providing an unknown MIME type will set the content type and set the format as nil.
+      #
+      # @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
+      #
+      # @raise [Hanami::Action::UnknownFormatError] if an unknown format name is given
+      #
+      # @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

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
-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

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
-require "hanami/action/params"
+require_relative "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))