✨ Add BINARY support to #append (RFC3516)

This adds the ability to send binary `literal8`, which were already
supported by the parser for `FETCH`, and automatically uses `literal8`
when the `#append` message includes `NULL` bytes.

Author: nevans

lib/net/imap.rb

@@ -486,9 +486,7 @@ module Net
   # IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].
   # - Updates #fetch and #uid_fetch with the +BINARY+, +BINARY.PEEK+, and
   #   +BINARY.SIZE+ items.  See FetchData#binary and FetchData#binary_size.
-  #
-  # >>>
-  #   *NOTE:* The binary extension the #append command is _not_ supported yet.
+  # - Updates #append to allow binary messages containing +NULL+ bytes.
   #
   # ==== RFC3691: +UNSELECT+
   # Folded into IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] and also included
@@ -2044,6 +2042,11 @@ def status(mailbox, attr)
     #
     # ==== Capabilities
     #
+    # If +BINARY+ [RFC3516[https://www.rfc-editor.org/rfc/rfc3516.html]] is
+    # supported by the server, +message+ may contain +NULL+ characters and
+    # be sent as a binary literal.  Otherwise, binary message parts must be
+    # encoded appropriately (for example, +base64+).
+    #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # supported and the destination supports persistent UIDs, the server's
     # response should include an +APPENDUID+ response code with AppendUIDData.
@@ -2054,12 +2057,11 @@ def status(mailbox, attr)
     # TODO: add MULTIAPPEND support
     #++
     def append(mailbox, message, flags = nil, date_time = nil)
+      message = StringFormatter.literal_or_literal8(message, name: "message")
       args = []
-      if flags
-        args.push(flags)
-      end
+      args.push(flags)     if flags
       args.push(date_time) if date_time
-      args.push(Literal.new(message))
+      args.push(message)
       send_command("APPEND", mailbox, *args)
     end
 

lib/net/imap/command_data.rb

@@ -77,9 +77,12 @@ def send_quoted_string(str)
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(str, tag) = send_literal(str, tag, binary: true)
+
+    def send_literal(str, tag = nil, binary: false)
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        prefix = "~" if binary
+        put_string("#{prefix}{#{str.bytesize}}\r\n")
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -158,7 +161,8 @@ def bytesize = data.bytesize
 
       def validate
         if data.include?("\0")
-          raise DataFormatError, "NULL byte not allowed in #{self.class}."
+          raise DataFormatError, "NULL byte not allowed in #{self.class}.  " \
+            "Use #{Literal8} or a null-safe encoding."
         end
       end
 
@@ -167,6 +171,14 @@ def send_data(imap, tag)
       end
     end
 
+    class Literal8 < Literal # :nodoc:
+      def validate = nil # all bytes are okay
+
+      def send_data(imap, tag)
+        imap.__send__(:send_binary_literal, data, tag)
+      end
+    end
+
     class PartialRange < CommandData # :nodoc:
       uint32_max = 2**32 - 1
       POS_RANGE = 1..uint32_max
@@ -236,6 +248,14 @@ module StringFormatter
 
       module_function
 
+      def literal_or_literal8(input, name: "argument")
+        return input if input in Literal | Literal8
+        data = String.try_convert(input) \
+          or raise TypeError, "expected #{name} to be String, got #{input.class}"
+        type = data.include?("\0") ? Literal8 : Literal
+        type.new(data:)
+      end
+
       # Allows symbols in addition to strings
       def valid_string?(str)
         str.is_a?(Symbol) || str.respond_to?(:to_str)

test/net/imap/test_command_data.rb

@@ -7,6 +7,8 @@ class CommandDataTest < Net::IMAP::TestCase
   DataFormatError = Net::IMAP::DataFormatError
 
   Literal = Net::IMAP::Literal
+  Literal8 = Net::IMAP::Literal8
+
   Output = Data.define(:name, :args)
   TAG = Module.new.freeze
 
@@ -45,6 +47,7 @@ def send_data(*data, tag: TAG)
     def_printer :send_date_data
     def_printer :send_quoted_string
     def_printer :send_literal
+    def_printer :send_binary_literal
   end
 
   test "Literal" do
@@ -61,4 +64,24 @@ def send_data(*data, tag: TAG)
     assert_empty imap.output
   end
 
+  test "Literal8" do
+    imap = FakeCommandWriter.new
+    imap.send_data Literal8["foo\r\nbar"], Literal8["foo\0bar"]
+    assert_equal [
+      Output.send_binary_literal("foo\r\nbar", TAG),
+      Output.send_binary_literal("foo\0bar", TAG),
+    ], imap.output
+  end
+
+  class StringFormatterTest < Net::IMAP::TestCase
+    include Net::IMAP::StringFormatter
+
+    test "literal_or_literal8" do
+      assert_kind_of Literal,  literal_or_literal8("simple\r\n")
+      assert_kind_of Literal8, literal_or_literal8("has NULL \0")
+      assert_kind_of Literal,  literal_or_literal8(Literal["foo"])
+      assert_kind_of Literal8, literal_or_literal8(Literal8["foo"])
+    end
+  end
+
 end

test/net/imap/test_imap_append.rb

@@ -5,6 +5,8 @@
 require_relative "fake_server"
 
 class IMAPAppendTest < Net::IMAP::TestCase
+  TEST_FIXTURE_PATH = File.join(__dir__, "fixtures/response_parser")
+
   include Net::IMAP::FakeServer::TestHelper
 
   test "#append" do
@@ -94,6 +96,30 @@ class IMAPAppendTest < Net::IMAP::TestCase
     end
   end
 
+  test "#append with binary data" do
+    png = File.binread(File.join(TEST_FIXTURE_PATH, "ruby.png"))
+    mail = <<~EOF.b.gsub(/\n/, "\r\n")
+      From: nick@example.com
+      To: shugo@example.com
+      Subject: Binary append support
+      MIME-Version: 1.0
+      Content-Transfer-Encoding: binary
+      Content-Type: image/png
+
+    EOF
+    mail << png
+    mail.freeze
+    with_fake_server do |server, imap|
+      server.on "APPEND", &:done_ok
+
+      time = Time.new(2026, 2, 20, 10, 00, in: "-0500")
+      imap.append "Drafts", mail, %i[Draft Seen], time
+      assert_equal 'Drafts (\\Draft \\Seen) "20-Feb-2026 10:00:00 -0500" ' \
+                   "~{#{mail.bytesize}}\r\n#{mail}",
+                   server.commands.pop.args
+    end
+  end
+
   private
 
   def start_server