✨ Responses with no args can return frozen dup hash

This adds a new `:frozen_dup` option to `config.responses_without_block`
which allows it to return a frozen copy of the responses hash, with each
response type array also being a frozen copy.

Author: nevans

lib/net/imap.rb

@@ -2492,11 +2492,13 @@ def idle_done
 
     RESPONSES_DEPRECATION_MSG =
       "Pass a type or block to #responses, " \
-      "set config.responses_without_block to :silence_deprecation_warning, " \
+      "set config.responses_without_block to :frozen_dup " \
+      "or :silence_deprecation_warning, " \
       "or use #extract_responses or #clear_responses."
     private_constant :RESPONSES_DEPRECATION_MSG
 
     # :call-seq:
+    #   responses       -> hash of {String => Array} (see config.responses_without_block)
     #   responses(type) -> frozen array
     #   responses       {|hash|  ...} -> block result
     #   responses(type) {|array| ...} -> block result
@@ -2526,6 +2528,10 @@ def idle_done
     #       Prints a warning and returns the mutable responses hash.
     #       <em>This is not thread-safe.</em>
     #
+    #     [+:frozen_dup+</em>]
+    #       Returns a frozen copy of the unhandled responses hash, with frozen
+    #       array values.
+    #
     #     [+:raise+ <em>(planned future default)</em>]
     #       Raise an +ArgumentError+ with the deprecation warning.
     #
@@ -2597,6 +2603,13 @@ def responses(type = nil)
           raise ArgumentError, RESPONSES_DEPRECATION_MSG
         when :warn
           warn(RESPONSES_DEPRECATION_MSG, uplevel: 1, category: :deprecated)
+        when :frozen_dup
+          synchronize {
+            responses = @responses.transform_values(&:freeze)
+            responses.default_proc = nil
+            responses.default = [].freeze
+            return responses.freeze
+          }
         end
         @responses
       end

lib/net/imap/config.rb

@@ -260,6 +260,15 @@ def self.[](config)
       #   Prints a warning and returns the mutable responses hash.
       #   <em>This is not thread-safe.</em>
       #
+      # [+:frozen_dup+</em>]
+      #   Returns a frozen copy of the unhandled responses hash, with frozen
+      #   array values.
+      #
+      #   Note that calling IMAP#responses with a +type+ and without a block is
+      #   not configurable and always behaves like +:frozen_dup+.
+      #
+      #   <em>(+:frozen_dup+ config option was added in +v0.4.17+)</em>
+      #
       # [+:raise+ <em>(planned future default)</em>]
       #   Raise an ArgumentError with the deprecation warning.
       #

test/net/imap/test_imap_responses.rb

@@ -166,6 +166,15 @@ def assert_responses_warn
         assert_equal [], imap.responses["FAKE"]
       end
       assert_empty stderr
+      # opt-in to future behavior
+      imap.config.responses_without_block = :frozen_dup
+      stderr = EnvUtil.verbose_warning do
+        assert imap.responses.frozen?
+        assert imap.responses["CAPABILITY"].frozen?
+        assert_equal(%w[IMAP4REV1 NAMESPACE MOVE IDLE UTF8=ACCEPT],
+                     imap.responses["CAPABILITY"].last)
+      end
+      assert_empty stderr
     end
   end