hanami-action 3.0.0.rc1

data/lib/hanami/action/response.rb

@@ -0,0 +1,481 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/response"
+require "hanami/utils/kernel"
+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
+      DEFAULT_VIEW_OPTIONS = -> (*) { {} }.freeze
+
+      # @since 2.0.0
+      # @api private
+      EMPTY_BODY = [].freeze
+
+      # @since 2.0.0
+      # @api private
+      FILE_SYSTEM_ROOT = Pathname.new("/").freeze
+
+      # @since 2.0.0
+      # @api private
+      attr_reader :request, :exposures, :env, :view_options
+
+      # @since 2.0.0
+      # @api private
+      attr_accessor :charset
+
+      # @since 2.0.0
+      # @api private
+      def self.build(status, env)
+        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_from_media_type(r.content_type), config)
+        end
+      end
+
+      # @since 2.0.0
+      # @api private
+      def initialize(request:, config:, content_type: nil, charset: nil, env: {}, headers: {}, view_options: nil, session_enabled: false) # rubocop:disable Layout/LineLength
+        # `Rack::Response#initialize` copies the headers into its own internal store on both Rack
+        # 2.2+ (`Utils::HeaderHash[headers]`) and Rack 3.x (`Headers.new` + per-entry copy), so it
+        # never aliases the hash passed in. That means we can skip a defensive `headers.dup` here
+        # and avoid an allocation per request without risk of pollution. See the regression spec
+        # in `spec/unit/hanami/action/response_spec.rb` if you're tempted to add one back.
+        super([], 200, headers)
+        self.content_type = content_type if content_type
+
+        @request = request
+        @config = config
+        @charset = charset
+        @exposures = {}
+        @env = env
+        @view_options = view_options || DEFAULT_VIEW_OPTIONS
+
+        @session_enabled = session_enabled
+        @sending_file = false
+      end
+
+      # Sets the response body.
+      #
+      # @param str [String] the body string
+      #
+      # @since 2.0.0
+      # @api public
+      def body=(str)
+        @length = 0
+
+        if str.nil? || str == EMPTY_BODY
+          @body = EMPTY_BODY
+          return
+        end
+
+        @body = []
+
+        if str.is_a?(::Rack::Files::BaseIterator)
+          @body = str
+          buffered_body! # Ensure appropriate content-length is set
+        else
+          write(str)
+        end
+      end
+
+      # Sets the response status.
+      #
+      # @param code [Integer, Symbol] the status code
+      #
+      # @since 2.0.2
+      # @api public
+      #
+      # @raise [Hanami::Action::UnknownHttpStatusError] if the given code
+      #   cannot be associated to a known HTTP status
+      #
+      # @example
+      #   response.status = :unprocessable_entity
+      #
+      # @example
+      #   response.status = 422
+      #
+      # @see https://guides.hanamirb.org/v2.0/actions/status-codes/
+      def status=(code)
+        super(Http::Status.lookup(code))
+      end
+
+      # Sets the response body from the rendered view.
+      #
+      # @param view [Hanami::View] the view to render
+      # @param input [Hash] keyword arguments to pass to the view's `#call` method
+      #
+      # @api public
+      # @since 2.1.0
+      def render(view, **input)
+        view_input = {
+          **view_options.call(request, self),
+          **exposures,
+          **input
+        }
+
+        self.body = view.call(**view_input).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
+        @format ||= Mime.format_from_media_type(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.format_and_media_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 true if the session is enabled for the request.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      # @since 2.1.0
+      def session_enabled?
+        @session_enabled
+      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
+        unless session_enabled?
+          raise Hanami::Action::MissingSessionError.new("Hanami::Action::Response#session")
+        end
+
+        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
+        unless session_enabled?
+          raise Hanami::Action::MissingSessionError.new("Hanami::Action::Response#flash")
+        end
+
+        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)
+        return unless allow_redirect?
+
+        redirect(::String.new(url), status)
+        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 Hanami::Action::Config#public_directory
+      # @see Hanami::Action::Rack::File
+      #
+      # @since 2.0.0
+      # @api public
+      def send_file(path)
+        _send_file(
+          Action::Rack::File.new(path, @config.public_directory).call(env)
+        )
+      end
+
+      # Send the file at the given path as the response, for a file anywhere in the file system.
+      #
+      # @param path [String, Pathname] path to the file to be sent
+      #
+      # @return [void]
+      #
+      # @see #send_file
+      # @see Hanami::Action::Rack::File
+      #
+      # @since 2.0.0
+      # @api public
+      def unsafe_send_file(path)
+        directory = if Pathname.new(path).relative?
+                      @config.root_directory
+                    else
+                      FILE_SYSTEM_ROOT
+                    end
+
+        _send_file(
+          Action::Rack::File.new(path, directory).call(env)
+        )
+      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)
+        directives = Cache::CacheControl::Directives.new(*values)
+        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)
+        directives = Cache::Expires::Directives.new(amount, *values)
+        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)
+        conditional_get = Cache::ConditionalGet.new(env, options)
+
+        headers.merge!(conditional_get.headers)
+
+        conditional_get.fresh? do
+          Halt.call(304)
+        end
+      end
+
+      # @since 2.0.0
+      # @api private
+      def set_format(value) # rubocop:disable Naming/AccessorMethodName
+        @format = value
+      end
+
+      # @since 2.0.0
+      # @api private
+      def renderable?
+        return !head? && body.empty? if body.respond_to?(:empty?)
+
+        !@sending_file && !head?
+      end
+
+      # @since 2.0.0
+      # @api private
+      def allow_redirect?
+        return body.empty? if body.respond_to?(:empty?)
+
+        !@sending_file
+      end
+
+      # @since 2.0.0
+      # @api private
+      alias_method :to_ary, :to_a
+
+      # @since 2.0.0
+      # @api private
+      def head?
+        env[Action::REQUEST_METHOD] == Action::HEAD
+      end
+
+      # @since 2.0.0
+      # @api private
+      def _send_file(send_file_response)
+        headers.merge!(send_file_response[Action::RESPONSE_HEADERS])
+
+        if send_file_response[Action::RESPONSE_CODE] == Action::NOT_FOUND
+          headers.delete(Action::X_CASCADE)
+          headers.delete(Action::CONTENT_LENGTH)
+          Halt.call(Action::NOT_FOUND)
+        else
+          self.status = send_file_response[Action::RESPONSE_CODE]
+          self.body = send_file_response[Action::RESPONSE_BODY]
+          @sending_file = true
+        end
+      end
+    end
+  end
+end

data/lib/hanami/action/session.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Action
+    # Session support for actions.
+    #
+    # 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 }
+        end
+      end
+
+      private
+
+      def session_enabled?
+        true
+      end
+
+      # Finalize the response
+      #
+      # @return [void]
+      #
+      # @since 0.3.0
+      # @api private
+      #
+      # @see Hanami::Action#finish
+      def finish(req, res, *)
+        if (next_flash = res.flash.next).any?
+          res.session[Flash::KEY] = next_flash
+        else
+          res.session.delete(Flash::KEY)
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/hanami/action/validatable.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Action
+    # Support for validating params when calling actions.
+    #
+    # Included only when dry-validation is bundled.
+    #
+    # @api private
+    # @since 0.1.0
+    module Validatable
+      # @api private
+      # @since 0.1.0
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Validatable API class methods
+      #
+      # @since 0.1.0
+      # @api private
+      module ClassMethods
+        # Defines a validation schema for the params passed to {Hanami::Action#call}.
+        #
+        # This feature isn't mandatory, but is highly recommended for secure handling of params:
+        # because params come from an untrusted source, it's good practice to filter these to only
+        # the keys and types required for your action's use case.
+        #
+        # The given block is evaluated inside a `params` schema of a `Dry::Validation::Contract`
+        # class. This constrains the validation to simple structure and type rules only. If you want
+        # to use all the features of dry-validation contracts, use {#contract} instead.
+        #
+        # Instead of defining the params validation schema inline, you can alternatively provide a
+        # concrete `Dry::Validation::Contract` subclass.
+        #
+        # @param klass [Class,nil] a Dry::Validation::Contract subclass
+        # @param block [Proc] the params schema definition
+        #
+        # @return void
+        #
+        # @see #contract
+        # @see Hanami::Action::Params
+        # @see https://dry-rb.org/gems/dry-validation/
+        #
+        # @example Inline definition
+        #   require "hanami/action"
+        #
+        #   class Signup < Hanami::Action
+        #     params do
+        #       required(:first_name)
+        #       required(:last_name)
+        #       required(:email)
+        #     end
+        #
+        #     def handle(req, *)
+        #       puts req.params[:first_name]     # => "Luca"
+        #       puts req.params[:admin]          # => nil
+        #     end
+        #   end
+        #
+        # @example Concrete class
+        #   require "hanami/action"
+        #
+        #   class SignupContract < Dry::Validation::Contract
+        #     params do
+        #       required(:first_name)
+        #       required(:last_name)
+        #       required(:email)
+        #     end
+        #   end
+        #
+        #   class Signup < Hanami::Action
+        #     params SignupContract
+        #
+        #     def handle(req, *)
+        #       req.params[:first_name]          # => "Luca"
+        #       req.params[:admin]               # => nil
+        #     end
+        #   end
+        #
+        # @api public
+        # @since 0.3.0
+        def params(klass = nil, &block)
+          contract_class = klass || Class.new(Dry::Validation::Contract) { params(&block) }
+
+          config.contract_class = contract_class
+        end
+
+        # Defines a validation contract for the params passed to {Hanami::Action#call}.
+        #
+        # This feature isn't mandatory, but is highly recommended for secure handling of params:
+        # because params come from an untrusted source, it's good practice to filter these to only
+        # the keys and types required for your action's use case.
+        #
+        # The given block is evaluated inside a `Dry::Validation::Contract` class. This allows you
+        # to use all features of dry-validation contracts
+        #
+        # Instead of defining the contract inline, you can alternatively provide a concrete
+        # `Dry::Validation::Contract` subclass.
+        #
+        # @param klass [Class,nil] a Dry::Validation::Contract subclass
+        # @param block [Proc] the params schema definition
+        #
+        # @return void
+        #
+        # @see #params
+        # @see Hanami::Action::Params
+        # @see https://dry-rb.org/gems/dry-validation/
+        #
+        # @example Inline definition
+        #   require "hanami/action"
+        #
+        #   class Signup < Hanami::Action
+        #     contract do
+        #       params do
+        #         required(:first_name)
+        #         required(:last_name)
+        #         required(:email)
+        #       end
+        #
+        #       rule(:email) do
+        #         # custom rule logic here
+        #       end
+        #     end
+        #
+        #     def handle(req, *)
+        #       puts req.params[:first_name]     # => "Luca"
+        #       puts req.params[:admin]          # => nil
+        #     end
+        #   end
+        #
+        # @example Concrete class
+        #   require "hanami/action"
+        #
+        #   class SignupContract < Dry::Validation::Contract
+        #     params do
+        #       required(:first_name)
+        #       required(:last_name)
+        #       required(:email)
+        #     end
+        #
+        #     rule(:email) do
+        #       # custom rule logic here
+        #     end
+        #   end
+        #
+        #   class Signup < Hanami::Action
+        #     contract SignupContract
+        #
+        #     def handle(req, *)
+        #       req.params[:first_name]          # => "Luca"
+        #       req.params[:admin]               # => nil
+        #     end
+        #   end
+        #
+        # @api public
+        # @since 2.2.0
+        def contract(klass = nil, &block)
+          contract_class = klass || Class.new(Dry::Validation::Contract, &block)
+
+          config.contract_class = contract_class
+        end
+      end
+    end
+  end
+end

data/lib/hanami/action/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Action
+    # The current hanami-action version.
+    #
+    # @return [String]
+    #
+    # @since 3.0.0
+    # @api public
+    VERSION = "3.0.0.rc1"
+  end
+end