hanami-controller 2.3.0.beta1 → 2.3.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16424b402710c09cc6727cf6ab94c84469edaa5d8e93f12d18c1f058cb973f00
-  data.tar.gz: '0639c98ced9c6f1cca83891bd74650f8dc6856e64490aa3a3321069810cd86a7'
+  metadata.gz: 194fc2615c1034ce507513f72e4f218a45fafe60ad53823e0b04e07cae0469f6
+  data.tar.gz: fff5370bd197844f24e83d88490a950fac8cb44c1683c489da94cbb8b5d92402
 SHA512:
-  metadata.gz: e353e4df54518fcdc9fc2ae60262b839772fdcc180335d56c3f451a26766dcfb31567ca6a45b852ffabe92e40638cdb1f259d55bb1539ec315bc15c2bfe70de7
-  data.tar.gz: 0434befd1175d44411ad2aa5b315ba5c212c69d47dbb2c6c990733ca07f1c4c3d1954139f21c0cd6b35d236f5be9f4b9293e286f50f189a3eac24069435fca1a
+  metadata.gz: f61ceab1aba8a83b459e1c07698802f45fc27f5852454578a4cb135cf520bcf6c12a9a70ae90763dbdb0f1e0dde927da3eb67f071045344c44bb32bc86c8981a
+  data.tar.gz: f2d5905a9d93d09b4a328dbc27d564226293f89a54bb23155b5bd2ececfece6fe768a58d9e3473a228659e790c83018ee90b9f0b1ce1d783bba82679351abc1c

data/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 Complete, fast and testable actions for Rack
 
+## v2.3.0.beta2 - 2025-10-17
+
+### Added
+
+- [Tim Riley] Make format config more flexible. (#485)
+
+  **Use `config.formats.register` to register a new format and its media types.**
+
+  This replaces `config.formats.add`. Unlike `.add` it does _not_ set the format as being one of the accpeted formats at the same time.
+
+  This change makes it easier to `register` your custom formats in app config or a base action class, without inadvertently causing format restrictions in descendent action classes.
+
+  A simple registration looks like this:
+
+  ```ruby
+  config.formats.register(:json, "application/json")
+  ```
+
+  `.register` also allows you to register one or more media types for the distinct stages of request processing:
+
+  - If you want to accept requests based on different/additional media types in `Accept` request headers, provide them as `accept_types:`
+  - If you want to accept requests based on different/additional media types in `Content-Type` request headers, provide them as `content_types:`
+  - If you do not provide these options, then the _default_ media type (the required second argument, after the format name) is used for each of the above
+  - This default media type is also set as the default `Content-Type` _response_ header for requests that match the format
+
+  Together, these allow you to register a format like this:
+
+  ```ruby
+  config.formats.register(
+    :jsonapi,
+    "application/vnd.api+json",
+    accept_types: ["application/vnd.api+json", "application/json"],
+    content_types: ["application/vnd.api+json", "application/json"],
+  )
+  ```
+
+  **Use `config.formats.accept` to accept specific formats from an action.**
+
+  `formats.accept` replaces `Action.format` and `config.format`. You can access your accepted formats via `formats.accepted`, which replaces `config.formats.values`.
+
+  To accept a format:
+
+  ```ruby
+  config.formats.accept :html, :json
+  config.formats.accepted # => [:html, :json]
+
+  config.formats.accept :csv # it is additive
+  config.formats.accepted # => [:html, :json, :csv]
+  ```
+
+  The first format you give to `accept` will also become the _default format_ for responses from your action.
+
+  **Use config.formats.default=` to set an action's default format.**
+
+  This is a new capability. Assign an action's default format using `config.formats.default=`.
+
+  The default format is used to set the response `Content-Type` header when the request does not specify a format via `Accept`.
+
+  ```ruby
+  config.formats.accept :html, :json
+
+  # When no default is already set, the first accepted format becomes default
+  config.formats.default # => :html
+
+  # But you can now configure this directly
+  config.formats.default = :json
+  ```
+
+### Changed
+
+- [Tim Riley] `Action.format`, `config.format`, `config.formats.add`, `config.formats.values`, and `config.formats.values=` are deprecated and will be removed in Hanami 2.4. (#485)
+- [Tim Riley] Drop support for Ruby 3.1.
+
 ## v2.3.0.beta1 - 2025-10-03
 
 ### Fixed

data/README.md

@@ -135,10 +135,10 @@ action   = Show.new(configuration: configuration)
 response = action.call(id: 23, key: "value")
 ```
 
-#### Whitelisting
+#### Allowlisting
 
 Params represent an untrusted input.
-For security reasons it's recommended to whitelist them.
+For security reasons it's recommended to allowlist them.
 
 ```ruby
 require "hanami/validations"
@@ -162,11 +162,11 @@ class Signup < Hanami::Action
     puts request.params.class            # => Signup::Params
     puts request.params.class.superclass # => Hanami::Action::Params
 
-    # Whitelist :first_name, but not :admin
+    # Allowlist :first_name, but not :admin
     puts request.params[:first_name]     # => "Luca"
     puts request.params[:admin]          # => nil
 
-    # Whitelist nested params [:address][:line_one], not [:address][:line_two]
+    # Allowlist nested params [:address][:line_one], not [:address][:line_two]
     puts request.params[:address][:line_one] # => "69 Tender St"
     puts request.params[:address][:line_two] # => nil
   end

data/hanami-controller.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = []
   spec.require_paths = ["lib"]
   spec.metadata["rubygems_mfa_required"] = "true"
-  spec.required_ruby_version = ">= 3.1"
+  spec.required_ruby_version = ">= 3.2"
 
   spec.add_dependency "rack", ">= 2.1"
   spec.add_dependency "hanami-utils", "~> 2.3.0.beta1"

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

@@ -11,35 +11,57 @@ module Hanami
       # @since 2.0.0
       # @api private
       class Formats
-        include Dry.Equalizer(:values, :mapping)
+        include Dry.Equalizer(:accepted, :mapping)
 
-        # Default MIME type to format mapping
-        #
         # @since 2.0.0
         # @api private
-        DEFAULT_MAPPING = {
-          "application/octet-stream" => :all,
-          "*/*" => :all
-        }.freeze
+        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 private
-        attr_reader :mapping
+        # @api public
+        attr_reader :accepted
+
+        # @see #accepted
+        #
+        # @since 2.0.0
+        # @api public
+        def values
+          msg = <<~TEXT
+            Hanami::Action `config.formats.values` is deprecated and will be removed in Hanami 2.4.
+
+            Please use `config.formats.accepted` instead.
+
+            See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+          TEXT
+          warn(msg, category: :deprecated)
+
+          accepted
+        end
 
-        # The array of enabled formats.
+        # Returns the default format name.
+        #
+        # When a request is received that cannot
+        #
+        # @return [Symbol, nil] the default format name, if any
         #
         # @example
-        #   config.formats.values = [:html, :json]
-        #   config.formats.values # => [:html, :json]
+        #   @config.formats.default # => :json
         #
         # @since 2.0.0
         # @api public
-        attr_reader :values
+        attr_reader :default
 
         # @since 2.0.0
         # @api private
-        def initialize(values: [], mapping: DEFAULT_MAPPING.dup)
-          @values = values
+        def initialize(accepted: [], default: nil, mapping: {})
+          @accepted = accepted
+          @default = default
           @mapping = mapping
         end
 
@@ -47,15 +69,74 @@ module Hanami
         # @api private
         private def initialize_copy(original) # rubocop:disable Style/AccessModifierDeclarations
           super
-          @values = original.values.dup
+          @accepted = original.accepted.dup
+          @default = original.default
           @mapping = original.mapping.dup
         end
 
+        # !@attribute [w] accepted
+        #   @since 2.3.0
+        #   @api public
+        def accepted=(formats)
+          @accepted = formats.map { |f| Hanami::Utils::Kernel.Symbol(f) }
+        end
+
         # !@attribute [w] values
         #   @since 2.0.0
         #   @api public
-        def values=(formats)
-          @values = formats.map { |f| Utils::Kernel.Symbol(f) }
+        alias_method :values=, :accepted=
+
+        # @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])
+          mapping[format] = Mime::Format.new(
+            name: format.to_sym,
+            media_type: media_type,
+            accept_types: accept_types,
+            content_types: content_types
+          )
+
+          self
         end
 
         # @overload add(format)
@@ -83,20 +164,30 @@ module Hanami
         #   @param mime_types [Array<String>]
         #
         #   @example
-        #     config.formats.add(:json, ["application/json+scim", "application/json"])
+        #     config.formats.add(:json, ["application/json+scim"])
         #
         # @return [self]
         #
         # @since 2.0.0
         # @api public
-        def add(format, mime_types = [])
-          format = Utils::Kernel.Symbol(format)
+        def add(format, mime_types)
+          msg = <<~TEXT
+            Hanami::Action `config.formats.add` is deprecated and will be removed in Hanami 2.4.
+
+            Please use `config.formats.register` instead.
+
+            See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+          TEXT
+          warn(msg, category: :deprecated)
+
+          mime_type = Array(mime_types).first
 
-          Array(mime_types).each do |mime_type|
-            @mapping[Utils::Kernel.String(mime_type)] = format
-          end
+          # The old behaviour would have subsequent mime types _replacing_ previous ones
+          mapping.reject! { |_, format| format.media_type == mime_type }
 
-          @values << format unless @values.include?(format)
+          register(format, Array(mime_types).first, accept_types: mime_types)
+
+          accept(format) unless @accepted.include?(format)
 
           self
         end
@@ -104,31 +195,19 @@ module Hanami
         # @since 2.0.0
         # @api private
         def empty?
-          @values.empty?
+          accepted.empty?
         end
 
         # @since 2.0.0
         # @api private
         def any?
-          @values.any?
+          @accepted.any?
         end
 
         # @since 2.0.0
         # @api private
         def map(&blk)
-          @values.map(&blk)
-        end
-
-        # @since 2.0.0
-        # @api private
-        def mapping=(mappings)
-          @mapping = {}
-
-          mappings.each do |format_name, mime_types|
-            Array(mime_types).each do |mime_type|
-              add(format_name, mime_type)
-            end
-          end
+          @accepted.map(&blk)
         end
 
         # Clears any previously added mappings and format values.
@@ -138,15 +217,24 @@ module Hanami
         # @since 2.0.0
         # @api public
         def clear
-          @mapping = DEFAULT_MAPPING.dup
-          @values = []
+          @accepted = []
+          @default = nil
+          @mapping = {}
 
           self
         end
 
-        # Retrieve the format name associated with the given MIME Type
+        # 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 mime_type [String] the MIME Type
+        # @param media_type [String] the media Type
         #
         # @return [Symbol,NilClass] the associated format name, if any
         #
@@ -157,59 +245,46 @@ module Hanami
         #
         # @since 2.0.0
         # @api public
-        def format_for(mime_type)
-          @mapping[mime_type]
+        def format_for(media_type)
+          mapping.values.reverse.find { |format| format.media_type == media_type }&.name
         end
 
-        # Returns the primary MIME type associated with the given format.
+        # Returns the media type associated with the given format.
         #
         # @param format [Symbol] the format name
         #
-        # @return [String, nil] the associated MIME type, if any
+        # @return [String, nil] the associated media type, if any
         #
         # @example
-        #   @config.formats.mime_type_for(:json) # => "application/json"
+        #   @config.formats.media_type_for(:json) # => "application/json"
         #
         # @see #format_for
         #
-        # @since 2.0.0
+        # @since 2.3.0
         # @api public
-        def mime_type_for(format)
-          @mapping.key(format)
+        def media_type_for(format)
+          mapping[format]&.media_type
         end
 
-        # Returns an array of all MIME types associated with the given format.
-        #
-        # Returns an empty array if no such format is configured.
-        #
-        # @param format [Symbol] the format name
-        #
-        # @return [Array<String>] the associated MIME types
-        #
-        # @since 2.0.0
-        # @api public
-        def mime_types_for(format)
-          @mapping.each_with_object([]) { |(mime_type, f), arr| arr << mime_type if format == f }
+        # @api private
+        def accept_types_for(format)
+          mapping[format]&.accept_types || []
         end
 
-        # Returns the default format name
-        #
-        # @return [Symbol, nil] the default format name, if any
-        #
-        # @example
-        #   @config.formats.default # => :json
-        #
+        # @api private
+        def content_types_for(format)
+          mapping[format]&.content_types || []
+        end
+
+        # @see #media_type_for
         # @since 2.0.0
         # @api public
-        def default
-          @values.first
-        end
+        alias_method :mime_type_for, :media_type_for
 
+        # @see #media_type_for
         # @since 2.0.0
-        # @api private
-        def keys
-          @mapping.keys
-        end
+        # @api public
+        alias_method :mime_types_for, :accept_types_for
       end
     end
   end

data/lib/hanami/action/config.rb

@@ -68,7 +68,8 @@ module Hanami
 
       # Sets the format (or formats) for the action.
       #
-      # To configure custom formats and MIME type mappings, call {Formats#add formats.add} first.
+      # To configure custom formats and MIME type mappings, call {Formats#register formats.register}
+      # first.
       #
       # @example
       #   config.format :html, :json
@@ -82,10 +83,20 @@ module Hanami
       # @since 2.0.0
       # @api public
       def format(*formats)
+        msg = <<~TEXT
+          Hanami::Action `config.format` is deprecated and will be removed in Hanami 2.4.
+
+          Please use `config.formats.register` and/or `config.formats.accept` instead.
+
+          See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+        TEXT
+        warn(msg, category: :deprecated)
+
         if formats.empty?
           self.formats.values
         else
           self.formats.values = formats
+          self.formats.default = formats.first
         end
       end
 

data/lib/hanami/action/mime.rb

@@ -7,37 +7,39 @@ require_relative "errors"
 
 module Hanami
   class Action
+    # @api private
     module Mime # rubocop:disable Metrics/ModuleLength
-      # Most commom MIME Types used for responses
+      # Most commom media types used for responses
       #
       # @since 1.0.0
-      # @api private
+      # @api public
       TYPES = {
-        txt: "text/plain",
-        html: "text/html",
-        json: "application/json",
-        manifest: "text/cache-manifest",
         atom: "application/atom+xml",
         avi: "video/x-msvideo",
         bmp: "image/bmp",
-        bz: "application/x-bzip",
         bz2: "application/x-bzip2",
+        bz: "application/x-bzip",
         chm: "application/vnd.ms-htmlhelp",
         css: "text/css",
         csv: "text/csv",
         flv: "video/x-flv",
+        form: "application/x-www-form-urlencoded",
         gif: "image/gif",
         gz: "application/x-gzip",
         h264: "video/h264",
+        html: "text/html",
         ico: "image/vnd.microsoft.icon",
         ics: "text/calendar",
         jpg: "image/jpeg",
         js: "application/javascript",
-        mp4: "video/mp4",
+        json: "application/json",
+        manifest: "text/cache-manifest",
         mov: "video/quicktime",
         mp3: "audio/mpeg",
+        mp4: "video/mp4",
         mp4a: "audio/mp4",
         mpg: "video/mpeg",
+        multipart: "multipart/form-data",
         oga: "audio/ogg",
         ogg: "application/ogg",
         ogv: "video/ogg",
@@ -53,13 +55,14 @@ module Hanami
         tar: "application/x-tar",
         torrent: "application/x-bittorrent",
         tsv: "text/tab-separated-values",
+        txt: "text/plain",
         uri: "text/uri-list",
         vcs: "text/x-vcalendar",
         wav: "audio/x-wav",
         webm: "video/webm",
         wmv: "video/x-ms-wmv",
-        woff: "application/font-woff",
         woff2: "application/font-woff2",
+        woff: "application/font-woff",
         wsdl: "application/wsdl+xml",
         xhtml: "application/xhtml+xml",
         xml: "application/xml",
@@ -68,9 +71,109 @@ module Hanami
         zip: "application/zip"
       }.freeze
 
+      # @api private
       ANY_TYPE = "*/*"
 
+      # @api private
+      Format = Data.define(:name, :media_type, :accept_types, :content_types) do
+        def initialize(name:, media_type:, accept_types: [media_type], content_types: [media_type])
+          super
+        end
+      end
+
+      # @api private
+      FORMATS = TYPES
+        .to_h { |name, media_type| [name, Format.new(name:, media_type:)] }
+        .update(
+          all: Format.new(
+            name: :all,
+            media_type: "application/octet-stream",
+            accept_types: ["*/*"],
+            content_types: ["*/*"]
+          ),
+          html: Format.new(
+            name: :html,
+            media_type: "text/html",
+            content_types: ["application/x-www-form-urlencoded", "multipart/form-data"]
+          )
+        )
+        .freeze
+      private_constant :FORMATS
+
+      # @api private
+      MEDIA_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|
+        hsh[format.media_type] = format
+      }.freeze
+      private_constant :MEDIA_TYPES_TO_FORMATS
+
+      # @api private
+      ACCEPT_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|
+        format.accept_types.each { |type| hsh[type] = format }
+      }.freeze
+      private_constant :ACCEPT_TYPES_TO_FORMATS
+
       class << self
+        # Yields if an action is configured with `formats`, the request has an `Accept` header, and
+        # none of the Accept types matches the accepted formats. The given block is expected to halt
+        # the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_media_types
+        # @see Config#formats
+        #
+        # @api private
+        def enforce_accept(request, config)
+          return unless request.accept_header?
+
+          accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
+          return if accept_types.any? { |type| accepted_type?(type, config) }
+
+          yield
+        end
+
+        # Yields if an action is configured with `formats`, the request has a `Content-Type` header,
+        # and the content type does not match the accepted formats. The given block is expected to
+        # halt the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_media_types
+        # @see Config#formats
+        #
+        # @api private
+        def enforce_content_type(request, config)
+          # Compare media type (without parameters) instead of full Content-Type header to avoid
+          # false negatives (e.g., multipart/form-data; boundary=...)
+          media_type = request.media_type
+
+          return if media_type.nil?
+
+          return if accepted_content_type?(media_type, config)
+
+          yield
+        end
+
+        # Returns a string combining a media type and charset, intended for setting as the
+        # `Content-Type` header for the response to the given request.
+        #
+        # This uses the request's `Accept` header (if present) along with the configured formats to
+        # determine the best content type to return.
+        #
+        # @return [String]
+        #
+        # @see Action#call
+        #
+        # @api private
+        def response_content_type_with_charset(request, config)
+          content_type_with_charset(
+            response_content_type(request, config),
+            config.default_charset || Action::DEFAULT_CHARSET
+          )
+        end
+
         # Returns a format name for the given content type.
         #
         # The format name will come from the configured formats, if such a format is configured
@@ -81,52 +184,50 @@ module Hanami
         # This is used to return the format name a {Response}.
         #
         # @example
-        #   detect_format("application/jsonl charset=utf-8", config) # => :json
+        #   format_from_media_type("application/json;charset=utf-8", config) # => :json
         #
         # @return [Symbol, nil]
         #
         # @see Response#format
         # @see Action#finish
         #
-        # @since 2.0.0
         # @api private
-        def detect_format(content_type, config)
-          return if content_type.nil?
+        def format_from_media_type(media_type, config)
+          return if media_type.nil?
 
-          ct = content_type.split(";").first
-          config.formats.format_for(ct) || TYPES.key(ct)
+          mt = media_type.split(";").first
+          config.formats.format_for(mt) || MEDIA_TYPES_TO_FORMATS[mt]&.name
         end
 
         # Returns a format name and content type pair for a given format name or content type
         # string.
         #
         # @example
-        #   detect_format_and_content_type(:json, config)
+        #   format_and_media_type(:json, config)
         #   # => [:json, "application/json"]
         #
-        #   detect_format_and_content_type("application/json", config)
+        #   format_and_media_type("application/json", config)
         #   # => [:json, "application/json"]
         #
         # @example Unknown format name
-        #   detect_format_and_content_type(:unknown, config)
+        #   format_and_media_type(:unknown, config)
         #   # raises Hanami::Action::UnknownFormatError
         #
         # @example Unknown content type
-        #   detect_format_and_content_type("application/unknown", config)
+        #   format_and_media_type("application/unknown", config)
         #   # => [nil, "application/unknown"]
         #
         # @return [Array<(Symbol, String)>]
         #
         # @raise [Hanami::Action::UnknownFormatError] if an unknown format name is given
         #
-        # @since 2.0.0
         # @api private
-        def detect_format_and_content_type(value, config)
+        def format_and_media_type(value, config)
           case value
           when Symbol
-            [value, format_to_mime_type(value, config)]
+            [value, format_to_media_type(value, config)]
           when String
-            [detect_format(value, config), value]
+            [format_from_media_type(value, config), value]
           else
             raise UnknownFormatError.new(value)
           end
@@ -144,34 +245,13 @@ module Hanami
         #
         # @return [String]
         #
-        # @since 2.0.0
         # @api private
         def content_type_with_charset(content_type, charset)
           "#{content_type}; charset=#{charset}"
         end
 
-        # Returns a string combining a MIME type and charset, intended for setting as the
-        # `Content-Type` header for the response to the given request.
-        #
-        # This uses the request's `Accept` header (if present) along with the configured formats to
-        # determine the best content type to return.
-        #
-        # @return [String]
-        #
-        # @see Action#call
-        #
-        # @since 2.0.0
-        # @api private
-        def response_content_type_with_charset(request, config)
-          content_type_with_charset(
-            response_content_type(request, config),
-            config.default_charset || Action::DEFAULT_CHARSET
-          )
-        end
-
         # Patched version of <tt>Rack::Utils.best_q_match</tt>.
         #
-        # @since 2.0.0
         # @api private
         #
         # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
@@ -179,7 +259,7 @@ module Hanami
         # @see https://github.com/hanami/controller/issues/59
         # @see https://github.com/hanami/controller/issues/104
         # @see https://github.com/hanami/controller/issues/275
-        def best_q_match(q_value_header, available_mimes = TYPES.values)
+        def best_q_match(q_value_header, available_mimes)
           ::Rack::Utils.q_values(q_value_header).each_with_index.map { |(req_mime, quality), index|
             match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
             next unless match
@@ -188,99 +268,118 @@ module Hanami
           }.compact.max&.format
         end
 
-        # Yields if an action is configured with `formats`, the request has an `Accept` header, an
-        # none of the Accept types matches the accepted formats. The given block is expected to halt
-        # the request handling.
-        #
-        # If any of these conditions are not met, then the request is acceptable and the method
-        # returns without yielding.
-        #
-        # @see Action#enforce_accepted_mime_types
-        # @see Config#formats
-        #
-        # @since 2.0.0
-        # @api private
-        def enforce_accept(request, config)
-          return unless request.accept_header?
-
-          accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
-          return if accept_types.any? { |mime_type| accepted_mime_type?(mime_type, config) }
+        private
 
-          yield
+        # @api private
+        def accepted_type?(media_type, config)
+          accepted_types(config).any? { |accepted_type|
+            ::Rack::Mime.match?(media_type, accepted_type)
+          }
         end
 
-        # Yields if an action is configured with `formats`, the request has a `Content-Type` header
-        # (or a `default_requst_format` is configured), and the content type does not match the
-        # accepted formats. The given block is expected to halt the request handling.
-        #
-        # If any of these conditions are not met, then the request is acceptable and the method
-        # returns without yielding.
-        #
-        # @see Action#enforce_accepted_mime_types
-        # @see Config#formats
-        #
-        # @since 2.0.0
         # @api private
-        def enforce_content_type(request, config)
-          # Compare media type (without parameters) instead of full Content-Type header
-          # to avoid false negatives (e.g., multipart/form-data; boundary=...)
-          media_type = request.media_type
+        def accepted_types(config)
+          return [ANY_TYPE] if config.formats.empty?
 
-          return if media_type.nil?
+          config.formats.map { |format| format_to_accept_types(format, config) }.flatten(1)
+        end
 
-          return if accepted_mime_type?(media_type, config)
+        def format_to_accept_types(format, config)
+          configured_types = config.formats.accept_types_for(format)
+          return configured_types if configured_types.any?
 
-          yield
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .accept_types
         end
 
-        private
-
-        # @since 2.0.0
         # @api private
-        def accepted_mime_type?(mime_type, config)
-          accepted_mime_types(config).any? { |accepted_mime_type|
-            ::Rack::Mime.match?(mime_type, accepted_mime_type)
+        def accepted_content_type?(content_type, config)
+          accepted_content_types(config).any? { |accepted_content_type|
+            ::Rack::Mime.match?(content_type, accepted_content_type)
           }
         end
 
-        # @since 2.0.0
         # @api private
-        def accepted_mime_types(config)
+        def accepted_content_types(config)
           return [ANY_TYPE] if config.formats.empty?
 
-          config.formats.map { |format| format_to_mime_types(format, config) }.flatten(1)
+          config.formats.map { |format| format_to_content_types(format, config) }.flatten(1)
+        end
+
+        # @api private
+        def format_to_content_types(format, config)
+          configured_types = config.formats.content_types_for(format)
+          return configured_types if configured_types.any?
+
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .content_types
         end
 
-        # @since 2.0.0
         # @api private
         def response_content_type(request, config)
+          # This method prepares the default `Content-Type` for the response. Importantly, it only
+          # does this after `#enforce_accept` and `#enforce_content_type` have already passed the
+          # request. So by the time we get here, the request has been deemed acceptable to the
+          # action, so we can try to be as helpful as possible in setting an appropriate content
+          # type for the response.
+
           if request.accept_header?
-            all_mime_types = TYPES.values + config.formats.mapping.keys
-            content_type = best_q_match(request.accept, all_mime_types)
+            content_type =
+              if config.formats.empty? || config.formats.accepted.include?(:all)
+                permissive_response_content_type(request, config)
+              else
+                restrictive_response_content_type(request, config)
+              end
 
             return content_type if content_type
           end
 
           if config.formats.default
-            return format_to_mime_type(config.formats.default, config)
+            return format_to_media_type(config.formats.default, config)
           end
 
           Action::DEFAULT_CONTENT_TYPE
         end
 
-        # @since 2.0.0
         # @api private
-        def format_to_mime_type(format, config)
-          config.formats.mime_type_for(format) ||
-            TYPES.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+        def permissive_response_content_type(request, config)
+          # If no accepted formats are configured, or if the formats include :all, then we're
+          # working with a "permissive" action. In this case we simply want a response content type
+          # that corresponds to the request's accept header as closely as possible. This means we
+          # work from _all_ the media types we know of.
+
+          all_media_types =
+            (ACCEPT_TYPES_TO_FORMATS.keys | MEDIA_TYPES_TO_FORMATS.keys) +
+            config.formats.accept_types
+
+          best_q_match(request.accept, all_media_types)
         end
 
-        # @since 2.0.0
         # @api private
-        def format_to_mime_types(format, config)
-          config.formats.mime_types_for(format).tap { |types|
-            types << TYPES[format] if TYPES.key?(format)
-          }
+        def restrictive_response_content_type(request, config)
+          # When specific formats are configured, this is a "resitrctive" action. Here we want to
+          # match against the configured accept types only, and work back from those to the
+          # configured format, so we can use its canonical media type for the content type.
+
+          accept_types_to_formats = config.formats.accepted_formats(FORMATS)
+            .each_with_object({}) { |(_, format), hsh|
+              format.accept_types.each { hsh[_1] = format }
+            }
+
+          accept_type = best_q_match(request.accept, accept_types_to_formats.keys)
+          accept_types_to_formats[accept_type].media_type if accept_type
+        end
+
+        # @api private
+        def format_to_media_type(format, config)
+          configured_type = config.formats.media_type_for(format)
+          return configured_type if configured_type
+
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .media_type
         end
       end
     end

data/lib/hanami/action/response.rb

@@ -42,7 +42,7 @@ module Hanami
         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.detect_format(r.content_type), config)
+          r.set_format(Mime.format_from_media_type(r.content_type), config)
         end
       end
 
@@ -134,7 +134,7 @@ module Hanami
       # @since 2.0.0
       # @api public
       def format
-        @format ||= Mime.detect_format(content_type, @config)
+        @format ||= Mime.format_from_media_type(content_type, @config)
       end
 
       # Sets the format and associated content type for the response.
@@ -165,7 +165,7 @@ module Hanami
       # @since 2.0.0
       # @api public
       def format=(value)
-        format, content_type = Mime.detect_format_and_content_type(value, @config)
+        format, content_type = Mime.format_and_media_type(value, @config)
 
         self.content_type = Mime.content_type_with_charset(content_type, charset)
 

data/lib/hanami/action.rb

@@ -272,6 +272,15 @@ module Hanami
     # @since 2.0.0
     # @api public
     def self.format(...)
+      msg = <<~TEXT
+        Hanami::Action `format` is deprecated and will be removed in Hanami 2.4.
+
+        Please use `config.formats.accept` instead.
+
+        See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+      TEXT
+      warn(msg, category: :deprecated)
+
       config.format(...)
     end
 
@@ -326,7 +335,7 @@ module Hanami
           session_enabled: session_enabled?
         )
 
-        enforce_accepted_mime_types(request)
+        enforce_accepted_media_types(request)
 
         _run_before_callbacks(request, response)
         handle(request, response)
@@ -413,7 +422,7 @@ module Hanami
 
     # @since 2.0.0
     # @api private
-    def enforce_accepted_mime_types(request)
+    def enforce_accepted_media_types(request)
       return if config.formats.empty?
 
       Mime.enforce_accept(request, config) { return halt 406 }
@@ -596,7 +605,7 @@ module Hanami
       _empty_headers(res) if _requires_empty_headers?(res)
       _empty_body(res) if res.head?
 
-      res.set_format(Action::Mime.detect_format(res.content_type, config))
+      res.set_format(Mime.format_from_media_type(res.content_type, config))
       res[:params] = req.params
       res[:format] = res.format
       res

data/lib/hanami/controller/version.rb

@@ -8,6 +8,6 @@ module Hanami
     #
     # @since 0.1.0
     # @api public
-    VERSION = "2.3.0.beta1"
+    VERSION = "2.3.0.beta2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanami-controller
 version: !ruby/object:Gem::Version
-  version: 2.3.0.beta1
+  version: 2.3.0.beta2
 platform: ruby
 authors:
 - Luca Guidi
@@ -214,7 +214,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="