✨ Support LITERAL+ and LITERAL- extensions

This also adds a new config attribute: `max_non_synchronizing_literal`.
By default, it is set rather conservatively to 16 KiB.  But servers are
much more likely to support `LITERAL-` than `LITERAL+`, so the practical
limit will be 4096.

Author: nevans

lib/net/imap.rb

@@ -450,16 +450,16 @@ module Net
   #
   # Although IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] is not supported
   # yet, Net::IMAP supports several extensions that have been folded into it:
-  # +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+, +UNSELECT+,
-  # <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
+  # +ENABLE+, +IDLE+, +LITERAL-+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+,
+  # +UNSELECT+, <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
   # Commands for these extensions are listed with the {Core IMAP
   # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.
   #
   # >>>
   #   <em>The following are folded into +IMAP4rev2+ but are currently
   #   unsupported or incompletely supported by</em> Net::IMAP<em>: RFC4466
   #   extensions, +SEARCHRES+, +LIST-EXTENDED+, +LIST-STATUS+,
-  #   +LITERAL-+, and +SPECIAL-USE+.</em>
+  #   and +SPECIAL-USE+.</em>
   #
   # ==== RFC2087: +QUOTA+
   # +NOTE:+ Only the +STORAGE+ quota resource type is currently supported.
@@ -569,6 +569,15 @@ module Net
   # - Updates #store and #uid_store with the +unchangedsince+ modifier and adds
   #   the +MODIFIED+ ResponseCode to the tagged response.
   #
+  # ==== RFC7888: <tt>LITERAL+</tt>
+  # - Literal strings smaller than Config#max_non_synchronizing_literal bytes
+  #   are sent without waiting for the server's continuation request.
+  #
+  # ==== RFC7888: +LITERAL-+
+  # - Literal strings smaller than 4096 bytes or
+  #   Config#max_non_synchronizing_literal (whichever is smaller)
+  #   are sent without waiting for the server's continuation request.
+  #
   # ==== RFC8438: <tt>STATUS=SIZE</tt>
   # - Updates #status with the +SIZE+ status attribute.
   #

lib/net/imap/command_data.rb

@@ -86,9 +86,9 @@ def send_binary_literal(*, **) = send_literal(*, **, binary: true)
     #   TODO: raise or warn when capabilities don't allow non_sync.
     # * `false` -> Force normal synchronizing literal behavior.
     # * `nil`   -> (default) Currently behaves like `false` (will be dynamic).
-    #   TODO: Dynamic, based on capabilities and bytesize.
     def send_literal(str, tag = nil, binary: false, non_sync: nil)
       synchronize do
+        non_sync = non_sync_literal?(str.bytesize) if non_sync.nil?
         prefix = "~" if binary
         plus = "+" if non_sync
         put_string("#{prefix}{#{str.bytesize}#{plus}}\r\n")
@@ -110,6 +110,13 @@ def send_literal(str, tag = nil, binary: false, non_sync: nil)
       end
     end
 
+    def non_sync_literal?(bytesize)
+      capabilities_cached? &&
+        bytesize <= config.max_non_synchronizing_literal &&
+        (capable?("LITERAL+") ||
+         bytesize <= 4096 && (capable?("IMAP4rev2") || capable?("LITERAL-")))
+    end
+
     def send_number_data(num)
       put_string(num.to_s)
     end

lib/net/imap/config.rb

@@ -281,6 +281,40 @@ def self.[](config)
         0.5r => true,
       }
 
+      # The maximum bytesize for sending non-synchronizing literals, when the
+      # server supports them.  To disable non-synchronizing literals, set the
+      # value to +-1+.
+      #
+      # Non-synchronizing literals are only sent when the server's
+      # capabilities[rdoc-ref:IMAP#capabilities] have been
+      # cached[rdoc-ref:IMAP#capabilities_cached?] and include either
+      # <tt>LITERAL+</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]],
+      # <tt>LITERAL-</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]], or
+      # +IMAP4rev2+ [RFC9051[https://www.rfc-editor.org/rfc/rfc9051]].
+      #
+      # For <tt>LITERAL+</tt>, this value is the only limit on whether a literal
+      # value is sent as non-synchronizing literals.  For <tt>LITERAL-</tt> and
+      # <tt>IMAP4rev2</tt>, non-synchronizing literals must also be smaller than
+      # +4096+ bytes.
+      #
+      # Non-synchronizing literals avoid the latency of waiting for the server
+      # to allow continuation.  However, if a client sends a non-synchronizing
+      # literal that is too large for the server, the server may need to close
+      # the connection.  Because <tt>LITERAL+</tt> does not directly indicate
+      # the server's limits, it's best to avoid sending very large
+      # non-synchronized literals.
+      #
+      # ==== Versioned Defaults
+      #
+      # max_non_synchronizing_literal <em>was added in +v0.6.4+.</em>
+      #
+      # * original: +-1+ (_never_ send non-synchronizing literals)
+      # * +0.6+: 16 KiB
+      attr_accessor :max_non_synchronizing_literal, type: Integer?, defaults: {
+        0.0r => -1,
+        0.6r => 16 << 16, # 16 KiB
+      }
+
       # The maximum allowed server response size.  When +nil+, there is no limit
       # on response size.
       #

test/net/imap/test_imap.rb

@@ -673,20 +673,38 @@ def test_send_invalid_number
   end
 
   test("send literal args") do
-    with_fake_server do |server, imap|
+    with_fake_server(with_extensions: %w[LITERAL-]) do |server, imap|
+      # disable automatic non-synchronizing literals
+      imap.config.max_non_synchronizing_literal = -1
       server.on "TEST", &:done_ok
       send_args = ->(*args) do
         imap.__send__(:send_command, "TEST", *args)
       end
       send_args.call ["\xDE\xAD\xBE\xEF".b]
       assert_equal "({4}\r\n\xDE\xAD\xBE\xEF)".b, server.commands.pop.args
 
+      # enable automatic non-synchronizing literals
+      imap.config.max_non_synchronizing_literal = 1024
       buff = bytes = nil
       server.literal_acceptor = proc { buff, bytes = _1, _2; false }
+      server.on "TEST", &:done_ok
+      send_args = ->(*args) do
+        imap.__send__(:send_command, "TEST", *args)
+      end
+      send_args.call ["\xDE\xAD\xBE\xEF".b]
+      assert_equal "({4+}\r\n\xDE\xAD\xBE\xEF)".b, server.commands.pop.args
+      assert_nil buff
+      assert_nil bytes
+
+      # limited automatic non-synchronizing literals
+      imap.config.max_non_synchronizing_literal = 5
       assert_raise(Net::IMAP::NoResponseError) do
-        send_args.call Net::IMAP::Literal["\x01" * 10]
+        send_args.call [
+          Net::IMAP::Literal["\rhi\r"],
+          Net::IMAP::Literal["\x01" * 10],
+        ]
       end
-      assert_match(/TEST \{10\}\r\n\z/, buff)
+      assert_match(/TEST \(\{4\+\}\r\n\rhi\r \{10\}\r\n\z/, buff)
       assert_equal 10, bytes
       assert_empty server.commands
 
@@ -703,18 +721,23 @@ def test_send_invalid_number
       assert_nil buff
       assert_nil bytes
 
+      imap.config.max_non_synchronizing_literal = 5
       server.literal_acceptor = proc { true }
       send_args.call("literal",   Net::IMAP::Literal["\r",       false],
+                     "literal",   Net::IMAP::Literal["αβ",         nil],
                      "literal",   Net::IMAP::Literal["αβγδε",      nil],
                      "literal+",  Net::IMAP::Literal["αβγδε",     true],
                      "literal8",  Net::IMAP::Literal8["\0",      false],
+                     "literal8+", Net::IMAP::Literal8["\0" * 2,    nil],
                      "literal8",  Net::IMAP::Literal8["\0" * 6,    nil],
                      "literal8+", Net::IMAP::Literal8["\0" * 8,   true],
                      "done")
       assert_equal("literal"   " {1}\r\n\r "                 \
+                   "literal"   " {4+}\r\nαβ "                \
                    "literal"   " {10}\r\nαβγδε "             \
                    "literal+"  " {10+}\r\nαβγδε "            \
                    "literal8"  " ~{1}\r\n\0 "                \
+                   "literal8+" " ~{2+}\r\n\0\0 "             \
                    "literal8"  " ~{6}\r\n\0\0\0\0\0\0 "      \
                    "literal8+" " ~{8+}\r\n\0\0\0\0\0\0\0\0 " \
                    "done".b,