hanami-action 3.0.0.rc1

data/lib/hanami/action/config/formats.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "hanami/utils/kernel"
+require "dry/core"
+
+module Hanami
+  class Action
+    class Config
+      # Action format configuration.
+      #
+      # @since 2.0.0
+      # @api private
+      class Formats
+        include Dry.Equalizer(:accepted, :mapping)
+
+        # @since 2.0.0
+        # @api private
+        attr_reader :mapping
+
+        # The array of formats to accept requests by.
+        #
+        # @example
+        #   config.formats.accepted = [:html, :json]
+        #   config.formats.accepted # => [:html, :json]
+        #
+        # @since 2.0.0
+        # @api public
+        attr_reader :accepted
+
+        # The registered body parsers, as a hash mapping content types to callable parsers.
+        #
+        # @return [Hash{String => #call}]
+        #
+        # @since x.x.x
+        # @api public
+        attr_reader :body_parsers
+
+        # Returns the default format name.
+        #
+        # When a request is received that cannot
+        #
+        # @return [Symbol, nil] the default format name, if any
+        #
+        # @example
+        #   @config.formats.default # => :json
+        #
+        # @since 2.0.0
+        # @api public
+        attr_reader :default
+
+        # @since 2.0.0
+        # @api private
+        def initialize(accepted: [], default: nil, mapping: {})
+          @accepted = accepted
+          @default = default
+          @mapping = mapping
+          @body_parsers = {}
+
+          register_default_body_parsers
+        end
+
+        # @since 2.0.0
+        # @api private
+        private def initialize_copy(original)
+          super
+          @accepted = original.accepted.dup
+          @default = original.default
+          @mapping = original.mapping.dup
+          @body_parsers = original.body_parsers.dup
+        end
+
+        # !@attribute [w] accepted
+        #   @since 2.3.0
+        #   @api public
+        def accepted=(formats)
+          @accepted = formats.map { |f| Hanami::Utils::Kernel.Symbol(f) }
+        end
+
+        # @since 2.3.0
+        def accept(*formats)
+          self.default = formats.first if default.nil?
+          self.accepted = accepted | formats
+        end
+
+        # @api private
+        def accepted_formats(standard_formats = {})
+          accepted.to_h { |format|
+            [
+              format,
+              mapping.fetch(format) { standard_formats[format] }
+            ]
+          }
+        end
+
+        # @since 2.3.0
+        def default=(format)
+          @default = format.to_sym
+        end
+
+        # Registers a format and its associated media types.
+        #
+        # @param format [Symbol] the format name
+        # @param media_type [String] the format's media type
+        # @param accept_types [Array<String>] media types to accept in request `Accept` headers
+        # @param content_types [Array<String>] media types to accept in request `Content-Type` headers
+        #
+        # @example
+        #   config.formats.register(:scim, media_type: "application/json+scim")
+        #
+        #   config.formats.register(
+        #     :jsonapi,
+        #     "application/vnd.api+json",
+        #     accept_types: ["application/vnd.api+json", "application/json"],
+        #     content_types: ["application/vnd.api+json", "application/json"]
+        #   )
+        #
+        # @return [self]
+        #
+        # @since 2.3.0
+        # @api public
+        def register(format, media_type, accept_types: [media_type], content_types: [media_type], parser: nil)
+          mapping[format] = Mime::Format.new(
+            name: format.to_sym,
+            media_type: media_type,
+            accept_types: accept_types,
+            content_types: content_types
+          )
+
+          if parser
+            Array(content_types).each do |ct|
+              @body_parsers[ct.downcase] = parser
+            end
+          end
+
+          self
+        end
+
+        # @since 2.0.0
+        # @api private
+        def empty?
+          accepted.empty?
+        end
+
+        # @since 2.0.0
+        # @api private
+        def any?
+          @accepted.any?
+        end
+
+        # @since 2.0.0
+        # @api private
+        def map(&blk)
+          @accepted.map(&blk)
+        end
+
+        # Clears any previously added mappings and format values.
+        #
+        # @return [self]
+        #
+        # @since 2.0.0
+        # @api public
+        def clear
+          @accepted = []
+          @default = nil
+          @mapping = {}
+
+          self
+        end
+
+        # Returns an array of all accepted media types.
+        #
+        # @since 2.3.0
+        # @api public
+        def accept_types
+          accepted.map { |format| mapping[format]&.accept_types }.flatten(1).compact
+        end
+
+        # Retrieve the format name associated with the given media type
+        #
+        # @param media_type [String] the media Type
+        #
+        # @return [Symbol,NilClass] the associated format name, if any
+        #
+        # @example
+        #   @config.formats.format_for("application/json") # => :json
+        #
+        # @see #mime_type_for
+        #
+        # @since 2.0.0
+        # @api public
+        def format_for(media_type)
+          mapping.values.reverse.find { |format| format.media_type == media_type }&.name
+        end
+
+        # Returns the media type associated with the given format.
+        #
+        # @param format [Symbol] the format name
+        #
+        # @return [String, nil] the associated media type, if any
+        #
+        # @example
+        #   @config.formats.media_type_for(:json) # => "application/json"
+        #
+        # @see #format_for
+        #
+        # @since 2.3.0
+        # @api public
+        def media_type_for(format)
+          mapping[format]&.media_type
+        end
+
+        # @api private
+        def accept_types_for(format)
+          mapping[format]&.accept_types || []
+        end
+
+        # @api private
+        def content_types_for(format)
+          mapping[format]&.content_types || []
+        end
+
+        # @see #media_type_for
+        # @since 2.0.0
+        # @api public
+        alias_method :mime_type_for, :media_type_for
+
+        # @see #media_type_for
+        # @since 2.0.0
+        # @api public
+        alias_method :mime_types_for, :accept_types_for
+
+        # Finds the parser for a content type.
+        #
+        # @param content_type [String] the content type
+        #
+        # @return [#call, nil] the parser callable, if registered
+        #
+        # @api private
+        def body_parser_for(content_type)
+          @body_parsers[content_type&.downcase]
+        end
+
+        private
+
+        def register_default_body_parsers
+          # Multipart forms (ordinary urlencoded forms are handled by Rack automatically)
+          @body_parsers["multipart/form-data"] = BodyParser::MultipartForm
+
+          # JSON
+          @body_parsers["application/json"] = BodyParser::JSON
+          @body_parsers["application/vnd.api+json"] = BodyParser::JSON
+        end
+      end
+    end
+  end
+end

data/lib/hanami/action/config.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+
+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 public directory
+      #
+      # This serves as the root directory for file downloads
+      #
+      # @since 1.0.0
+      #
+      # @api private
+      DEFAULT_PUBLIC_DIRECTORY = "public"
+
+      # @!attribute [rw] handled_exceptions
+      #
+      #   Specifies how to handle exceptions with an HTTP status.
+      #
+      #   Raised exceptions will return the corresponding HTTP status.
+      #
+      #   @return [Hash{Exception=>Integer}] exception classes as keys and HTTP statuses as values
+      #
+      #   @example
+      #     config.handled_exceptions = {ArgumentError => 400}
+      #
+      #   @since 0.2.0
+
+      # Specifies how to handle exceptions with an HTTP status
+      #
+      # Raised exceptions will return the corresponding HTTP status
+      #
+      # The specified exceptions will be merged with any previously configured
+      # exceptions
+      #
+      # @param exceptions [Hash{Exception=>Integer}] exception classes as keys
+      #   and HTTP statuses as values
+      #
+      # @return [void]
+      #
+      # @example
+      #   config.handle_exceptions(ArgumentError => 400}
+      #
+      # @see handled_exceptions
+      #
+      # @since 0.2.0
+      def handle_exception(exceptions)
+        self.handled_exceptions = handled_exceptions
+          .merge(exceptions)
+          .sort do |(ex1, _), (ex2, _)|
+            next 0 if [ex1, ex2].any?(String)
+
+            ex1.ancestors.include?(ex2) ? -1 : 1
+          end
+          .to_h
+      end
+
+      # @!attribute [r] formats
+      #   Returns the format config for the action.
+      #
+      #   @return [Config::Formats]
+      #
+      #   @since 2.0.0
+      #   @api public
+
+      # @!attribute [rw] default_charset
+      #
+      #   Sets a charset (character set) as default fallback for all the requests
+      #   without a strict requirement for the charset.
+      #
+      #   By default, this value is nil.
+      #
+      #   @return [String]
+      #
+      #   @see Hanami::Action::Mime
+      #
+      #   @since 0.3.0
+
+      # @!attribute [rw] default_headers
+      #
+      #   Sets default headers for all responses.
+      #
+      #   By default, this is an empty hash.
+      #
+      #   @return [Hash{String=>String}] the headers
+      #
+      #   @example
+      #     config.default_headers = {"X-Frame-Options" => "DENY"}
+      #
+      #   @see default_headers
+      #
+      #   @since 0.4.0
+
+      # @!attribute [rw] default_tld_length
+      #
+      #   Sets the default TLD length for host names. It is used to extract the
+      #   subdomain(s) in `Request#subdomains`.
+      #
+      #   Defaults to 1.
+      #
+      #   @example
+      #     # For *.example.com
+      #     config.default_tld_length = 1
+      #
+      #     # Or for *.example.co.uk
+      #     config.default_tld_length = 2
+      #
+      #   @return [Integer] the number of subdomains
+      #
+      #   @since 2.3.0
+
+      # @!attribute [rw] cookies
+      #
+      #   Sets default cookie options for all responses.
+      #
+      #   By default this, is an empty hash.
+      #
+      #   @return [Hash{Symbol=>String}] the cookie options
+      #
+      #   @example
+      #     config.cookies = {
+      #       domain: "hanamirb.org",
+      #       path: "/action",
+      #       secure: true,
+      #       httponly: true
+      #     }
+      #
+      #   @since 0.4.0
+
+      # @!attribute [rw] root_directory
+      #
+      #   Sets the the for the public directory, which is used for file downloads.
+      #   This must be an existent directory.
+      #
+      #   Defaults to the current working directory.
+      #
+      #   @return [String] the directory path
+      #
+      #   @api private
+      #
+      #   @since 1.0.0
+
+      # @!attribute [rw] public_directory
+      #
+      # Sets the path to public directory. This directory is used for file downloads.
+      #
+      # This given directory will be appended onto the root directory.
+      #
+      # By default, the public directory is `"public"`.
+      # @return [String] the public directory path
+      #
+      # @example
+      #   config.public_directory = "public"
+      #   config.public_directory # => "/path/to/root/public"
+      #
+      # @see root_directory
+      #
+      # @since 2.0.0
+      def public_directory
+        # This must be a string, for Rack compatibility
+        root_directory.join(super).to_s
+      end
+    end
+  end
+end

data/lib/hanami/action/constants.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module Hanami
+  class Action
+    # Rack SPEC response code
+    #
+    # @since 1.0.0
+    # @api private
+    RESPONSE_CODE = 0
+
+    # Rack SPEC response headers
+    #
+    # @since 1.0.0
+    # @api private
+    RESPONSE_HEADERS = 1
+
+    # Rack SPEC response body
+    #
+    # @since 1.0.0
+    # @api private
+    RESPONSE_BODY = 2
+
+    # @since 1.0.0
+    # @api private
+    DEFAULT_ERROR_CODE = 500
+
+    # Status codes that by RFC must not include a message body
+    #
+    # @since 0.3.2
+    # @api private
+    HTTP_STATUSES_WITHOUT_BODY = Set.new((100..199).to_a << 204 << 205 << 304).freeze
+
+    # Not Found
+    #
+    # @since 1.0.0
+    # @api private
+    NOT_FOUND = 404
+
+    # Entity headers allowed in blank body responses, according to
+    # RFC 2616 - Section 10 (HTTP 1.1).
+    #
+    # "The response MAY include new or updated metainformation in the form
+    #   of entity-headers".
+    #
+    # @since 0.4.0
+    # @api private
+    #
+    # @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5
+    # @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html
+    ENTITY_HEADERS = {
+      "allow" => true,
+      "content-encoding" => true,
+      "content-language" => true,
+      "content-location" => true,
+      "content-md5" => true,
+      "content-range" => true,
+      "expires" => true,
+      "last-modified" => true,
+      "extension-header" => true
+    }.freeze
+
+    # The request relative path
+    #
+    # @since 2.0.0
+    # @api private
+    PATH_INFO = ::Rack::PATH_INFO
+
+    # The request content type (env key, CGI-style uppercase). Rack exposes a `CONTENT_TYPE`
+    # constant but it refers to the response header (lowercase in Rack 3), not the env key.
+    #
+    # @api private
+    CONTENT_TYPE = "CONTENT_TYPE"
+
+    # The request method
+    #
+    # @since 0.3.2
+    # @api private
+    REQUEST_METHOD = ::Rack::REQUEST_METHOD
+
+    # The Content-Length HTTP header
+    #
+    # @since 1.0.0
+    # @api private
+    CONTENT_LENGTH = ::Rack::CONTENT_LENGTH
+
+    # The non-standard HTTP header to pass the control over when a resource
+    # cannot be found by the current endpoint
+    #
+    # @since 1.0.0
+    # @api private
+    X_CASCADE = "X-Cascade"
+
+    # HEAD request
+    #
+    # @since 0.3.2
+    # @api private
+    HEAD = ::Rack::HEAD
+
+    # GET request
+    #
+    # @since 2.0.0
+    # @api private
+    GET = ::Rack::GET
+
+    # TRACE request
+    #
+    # @since 2.0.0
+    # @api private
+    TRACE = ::Rack::TRACE
+
+    # OPTIONS request
+    #
+    # @since 2.0.0
+    # @api private
+    OPTIONS = ::Rack::OPTIONS
+
+    # The key that returns accepted mime types from the Rack env
+    #
+    # @since 0.1.0
+    # @api private
+    HTTP_ACCEPT = "HTTP_ACCEPT"
+
+    # The default mime type for an incoming HTTP request
+    #
+    # @since 0.1.0
+    # @api private
+    DEFAULT_ACCEPT       = "*/*"
+
+    # The default mime type that is returned in the response
+    #
+    # @since 0.1.0
+    # @api private
+    DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+    # @since 0.2.0
+    # @api private
+    RACK_ERRORS = ::Rack::RACK_ERRORS
+
+    # The HTTP header for Cache-Control
+    #
+    # @since 2.0.0
+    # @api private
+    CACHE_CONTROL = ::Rack::CACHE_CONTROL
+
+    # @since 2.0.0
+    # @api private
+    IF_NONE_MATCH = "HTTP_IF_NONE_MATCH"
+
+    # The HTTP header for ETag
+    #
+    # @since 2.0.0
+    # @api private
+    ETAG = ::Rack::ETAG
+
+    # @since 2.0.0
+    # @api private
+    IF_MODIFIED_SINCE = "HTTP_IF_MODIFIED_SINCE"
+
+    # The HTTP header for Expires
+    #
+    # @since 2.0.0
+    # @api private
+    EXPIRES = ::Rack::EXPIRES
+
+    # The HTTP header for Last-Modified
+    #
+    # @since 0.3.0
+    # @api private
+    LAST_MODIFIED = "Last-Modified"
+
+    # This isn't part of Rack SPEC
+    #
+    # Exception notifiers use <tt>rack.exception</tt> instead of
+    # <tt>rack.errors</tt>, so we need to support it.
+    #
+    # @since 0.5.0
+    # @api private
+    #
+    # @see Hanami::Action::Throwable::RACK_ERRORS
+    # @see http://www.rubydoc.info/github/rack/rack/file/SPEC#The_Error_Stream
+    # @see https://github.com/hanami/hanami-action/issues/133
+    RACK_EXCEPTION = "rack.exception"
+
+    # The HTTP header for redirects
+    #
+    # @since 0.2.0
+    # @api private
+    LOCATION = "Location"
+
+    # The key that returns Rack session params from the Rack env
+    # Please note that this is used only when an action is unit tested.
+    #
+    # @since 2.0.0
+    # @api private
+    #
+    # @example
+    #   # action unit test
+    #   action.call("rack.session" => { "foo" => "bar" })
+    #   action.session[:foo] # => "bar"
+    #
+    # @api private
+    RACK_SESSION = ::Rack::RACK_SESSION
+
+    # @since 2.0.0
+    # @api private
+    REQUEST_ID = "hanami.request_id"
+
+    # @since 2.0.0
+    # @api private
+    DEFAULT_ID_LENGTH = 16
+
+    # The key that returns raw cookies from the Rack env
+    #
+    # @since 2.0.0
+    # @api private
+    HTTP_COOKIE = ::Rack::HTTP_COOKIE
+
+    # The key used by Rack to set the cookies as an Hash in the env
+    #
+    # @since 2.0.0
+    # @api private
+    COOKIE_HASH_KEY = ::Rack::RACK_REQUEST_COOKIE_HASH
+
+    # The key used by Rack to set the cookies as a String in the env
+    #
+    # @since 2.0.0
+    # @api private
+    COOKIE_STRING_KEY = ::Rack::RACK_REQUEST_COOKIE_STRING
+
+    # The key that returns raw input from the Rack env
+    #
+    # @since 2.0.0
+    # @api private
+    RACK_INPUT = ::Rack::RACK_INPUT
+
+    # The key that returns a request body parsed by Hanami Action.
+    #
+    # This is the canonical key for body parsing.
+    #
+    # @since x.x.x
+    # @api private
+    ACTION_PARSED_BODY = "hanami.action.parsed_body"
+
+    # The key that returns params from a parsed body by Hanami Action.
+    #
+    # This is the canonical key for parsed body params.
+    #
+    # @since x.x.x
+    # @api private
+    ACTION_BODY_PARAMS = "hanami.action.body_params"
+
+    # The key that returns a request body parsed by Hanami Router.
+    #
+    # This is maintained for backward compatibility with Hanami Router.
+    #
+    # @api private
+    ROUTER_PARSED_BODY = "router.parsed_body"
+
+    # The key that returns router params from the Rack env.
+    #
+    # This is maintained for backward compatibility with Hanami Router.
+    #
+    # @since 2.0.0
+    # @api private
+    ROUTER_PARAMS = "router.params"
+
+    # Default HTTP request method for Rack env
+    #
+    # @since 2.0.0
+    # @api private
+    DEFAULT_REQUEST_METHOD = GET
+
+    # @since 2.0.0
+    # @api private
+    DEFAULT_CHARSET = "utf-8"
+
+    # @since 2.2.0
+    # @api private
+    ACTION_INSTANCE = "hanami.action_instance"
+  end
+end