net-imap 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4249dc5d175bd3ae3a3b3b79e0f368e674ec96045510a8b504e829feefb54f3d
-  data.tar.gz: 6adbee15b0303b36ec1c574991d4bdbf518bcd5621c6b668f05df0bc201ba50a
+  metadata.gz: ffcec5e3cc42d7f72c63520110ec442f760c35472401de495001f420cfa059c5
+  data.tar.gz: aedd703997fc651cb6c67635a3d20a4159720c6e1bda41c07322f2bd67a627d6
 SHA512:
-  metadata.gz: a20c230ac3977d9acc09bc964badc60acbedaca84246d1ce67787c78443cdea350ade6907e58b61a5c9f09bf3b12e5e57cd319ef82a096c3780f97dc7017ed31
-  data.tar.gz: 68ab8b48664998bbf05d5367fea4e5b06e3ba3b2d4e48ba8ae026069060b23f7dafaf7ecf2681fc5aa4ff0f134e55d9399ca51456ff3a7ec718ba829629866b7
+  metadata.gz: 1fa95302f29607d152b991535a9d14cda5dae1a1fce06b1d831dd2b09f69b2fd845367e0ebed73dd4e79d04c064a801e59865e76947060a4811304728458f3c7
+  data.tar.gz: 2dc9a56758d6f370affc9540a8ca26b8ad866ca5ef0e5b9bc2c30ff6257e3461e5ed23173e1c5e98a2e95c1e0f0a844c96f9e34d41151e9196ab513ac6987d33

data/.document

@@ -0,0 +1,3 @@
+*.rdoc
+*.md
+lib

data/.rdoc_options

@@ -0,0 +1,7 @@
+---
+charset: UTF-8
+main_page: README.md
+markup: rdoc
+title: net-imap # rake task override's title to add the version number
+op_dir: doc
+# vim:ft=yaml

data/Gemfile

@@ -11,7 +11,7 @@ gem "psych", ">= 5.3.0" # 5.2.5 for Data serialization, 5.3.0 for TruffleRuby
 
 gem "irb"
 gem "rake"
-gem "rdoc"
+gem "rdoc", ">= 7.2.0"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 

data/README.md

@@ -61,9 +61,9 @@ imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_i
   else
     imap.copy(message_id, "Mail/sent-apr03")
     imap.store(message_id, "+FLAGS", [:Deleted])
+    imap.expunge
   end
 end
-imap.expunge
 ```
 
 ## Development

data/lib/net/imap/command_data.rb

@@ -4,6 +4,8 @@ require "date"
 
 require_relative "errors"
 
+# :enddoc:
+
 module Net
   class IMAP < Protocol
 
@@ -25,6 +27,7 @@ module Net
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -45,7 +48,7 @@ module Net
       when Date
         send_date_data(data)
       when Symbol
-        send_symbol_data(data)
+        Flag[data].send_data(self, tag)
       else
         data.send_data(self, tag)
       end
@@ -77,9 +80,23 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(*, **) = send_literal(*, **, binary: true)
+
+    # `non_sync` is an optional tri-state flag:
+    # * `true`  -> Force non-synchronizing `LITERAL+`/`LITERAL-` behavior.
+    #   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).
+    def send_literal(str, tag = nil, binary: false, non_sync: nil)
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        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")
+        if non_sync
+          put_string(str)
+          return
+        end
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -94,6 +111,13 @@ module Net
       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
@@ -115,11 +139,13 @@ module Net
     def send_date_data(date) put_string Net::IMAP.encode_date(date) end
     def send_time_data(time) put_string Net::IMAP.encode_time(time) end
 
-    def send_symbol_data(symbol)
-      put_string("\\" + symbol.to_s)
-    end
-
     CommandData = Data.define(:data) do # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
       def send_data(imap, tag)
         raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
@@ -128,15 +154,109 @@ module Net
       end
     end
 
+    # Represents IMAP +text+ data, which may contain any 7-bit ASCII character,
+    # except for +NULL+, +CR+, or +LF+.  +text+ is extended to allow any
+    # multibyte +UTF-8+ character when either +UTF8=ACCEPT+ or +IMAP4rev2+ have
+    # been enabled, or when the server supports only +IMAP4rev2+ and not earlier
+    # IMAP revisions, or when the server advertises +UTF8=ONLY+.
+    #
+    # NOTE: The current implementation does not validate whether the connection
+    # currently supports UTF-8.  Future versions may change.
+    #
+    # The string's bytes must be valid ASCII or valid UTF-8.  The string's
+    # reported encoding is ignored, but the string is _not_ transcoded.
+    class RawText < CommandData # :nodoc:
+      def initialize(data:)
+        data = String(data.to_str)
+        data = if data.encoding in Encoding::ASCII | Encoding::UTF_8
+          -data
+        elsif data.ascii_only?
+          -(data.dup.force_encoding("ASCII"))
+        else
+          -(data.dup.force_encoding("UTF-8"))
+        end
+        super
+        validate
+      end
+
+      def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte must be binary literal encoded"
+        elsif !data.valid_encoding?
+          raise DataFormatError, "invalid UTF-8 must be literal encoded"
+        elsif /[\r\n]/.match?(data)
+          raise DataFormatError, "CR and LF bytes must be literal encoded"
+        end
+      end
+
+      def ascii_only? = data.ascii_only?
+
+      def send_data(imap, tag) = imap.__send__(:put_string, data)
+    end
+
     class RawData < CommandData # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:put_string, data)
+      def initialize(data:)
+        data = split_parts(data)
+        super
+        validate
+      end
+
+      def send_data(imap, tag) = data.each do _1.send_data(imap, tag) end
+
+      def validate
+        return unless data.last in RawText(data: text)
+        if text.rindex(/~?\{[1-9]\d*\+?\}\z/n)
+          raise DataFormatError, "RawData cannot end with literal continuation"
+        end
+      end
+
+      private
+
+      def split_parts(data)
+        data = data.b # dups and ensures BINARY encoding
+        parts = []
+        while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n)
+          text, binary, bytesize, non_sync, data = $`, !!$1, $2, !!$3, $'
+          bytesize = NumValidator.coerce_number64 bytesize
+          parts << RawText[text] unless text.empty?
+          parts << extract_literal(data, binary:, bytesize:, non_sync:)
+          data.bytesplice(0, bytesize, "")
+        end
+        parts << RawText[data] unless data.empty?
+        parts
+      end
+
+      def extract_literal(data, binary:, bytesize:, non_sync:)
+        if data.bytesize < bytesize
+          raise DataFormatError, "Too few bytes in string for literal, " \
+            "expected: %s, remaining: %s" % [bytesize, data.bytesize]
+        end
+        literal = data.byteslice(0, bytesize)
+        (binary ? Literal8 : Literal).new(data: literal, non_sync:)
       end
     end
 
     class Atom < CommandData # :nodoc:
+      def initialize(**)
+        super
+        validate
+      end
+
+      def validate
+        data.to_s.ascii_only? \
+          or raise DataFormatError, "#{self.class} must be ASCII only"
+        data.match?(ResponseParser::Patterns::ATOM_SPECIALS) \
+          and raise DataFormatError, "#{self.class} must not contain atom-specials"
+      end
+
+      def send_data(imap, tag)
+        imap.__send__(:put_string, data.to_s)
+      end
+    end
+
+    class Flag < Atom # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, data)
+        imap.__send__(:put_string, "\\#{data}")
       end
     end
 
@@ -146,9 +266,39 @@ module Net
       end
     end
 
-    class Literal < CommandData # :nodoc:
+    class Literal < Data.define(:data, :non_sync) # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
+      def initialize(data:, non_sync: nil)
+        data = -String(data.to_str).b or
+          raise DataFormatError, "#{self.class} expects string input"
+        super
+        validate
+      end
+
+      def bytesize = data.bytesize
+
+      def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte not allowed in #{self.class}.  " \
+            "Use #{Literal8} or a null-safe encoding."
+        end
+      end
+
+      def send_data(imap, tag)
+        imap.__send__(:send_literal, data, tag, non_sync:)
+      end
+    end
+
+    class Literal8 < Literal # :nodoc:
+      def validate = nil # all bytes are okay
+
       def send_data(imap, tag)
-        imap.__send__(:send_literal, data, tag)
+        imap.__send__(:send_binary_literal, data, tag, non_sync:)
       end
     end
 
@@ -221,6 +371,14 @@ module Net
 
       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)

data/lib/net/imap/config.rb

@@ -281,6 +281,40 @@ module Net
         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.
       #

data/lib/net/imap/data_encoding.rb

@@ -174,6 +174,22 @@ module Net
         0 < num && num <= 0xffff_ffff
       end
 
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     number64        = 1*DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 <= n <= 9,223,372,036,854,775,807)
+      def valid_number64?(num)
+        0 <= num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     nz-number64     = digit-nz *DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 < n <= 9,223,372,036,854,775,807)
+      def valid_nz_number64?(num)
+        0 < num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
       # Check if argument is a valid 'mod-sequence-value' according to RFC 4551
       #     mod-sequence-value  = 1*DIGIT
       #                            ; Positive unsigned 64-bit integer
@@ -203,6 +219,20 @@ module Net
           "nz-number must be non-zero unsigned 32-bit integer: #{num}"
       end
 
+      # Ensure argument is 'number64' or raise DataFormatError
+      def ensure_number64(num)
+        return num if valid_number64?(num)
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
+      end
+
+      # Ensure argument is 'nz-number64' or raise DataFormatError
+      def ensure_nz_number64(num)
+        return num if valid_nz_number64?(num)
+        raise DataFormatError,
+          "nz-number64 must be non-zero unsigned 63-bit integer: #{num}"
+      end
+
       # Ensure argument is 'mod-sequence-value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
         return num if valid_mod_sequence_value?(num)
@@ -237,6 +267,26 @@ module Net
         end
       end
 
+      # Like #ensure_number64, but usable with numeric String input.
+      def coerce_number64(num)
+        case num
+        when Integer   then ensure_number64 num
+        when NUMBER_RE then ensure_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid number64" % [num]
+        end
+      end
+
+      # Like #ensure_nz_number64, but usable with numeric String input.
+      def coerce_nz_number64(num)
+        case num
+        when Integer   then ensure_nz_number64 num
+        when NUMBER_RE then ensure_nz_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid nz-number64" % [num]
+        end
+      end
+
       # Like #ensure_mod_sequence_value, but usable with numeric String input.
       def coerce_mod_sequence_value(num)
         case num

data/lib/net/imap/errors.rb

@@ -172,18 +172,11 @@ module Net
           ]
         end
         if parser_backtrace
-          backtrace_locations&.each_with_index do |loc, idx|
-            next  if    loc.base_label.include? "parse_error"
-            break if    loc.base_label == "parse"
-            if loc.label.include?("#") # => Class#method, since ruby 3.4
-              next unless loc.label&.include?(parser_class.name)
-            else
-              next unless loc.path&.include?("net/imap/response_parser")
-            end
+          normalized_parser_backtrace.each do |idx, path, lineno, label, base_label|
             msg << "\n  %s: %s (%s:%d)" % [
               hl["%{key}caller[%{/key}%{idx}%%2d%{/idx}%{key}]%{/key}"] % idx,
-              hl["%{label}%%-30s%{/label}"] % loc.base_label,
-              File.basename(loc.path, ".rb"), loc.lineno
+              hl["%{label}%%-30s%{/label}"] % base_label,
+              File.basename(path, ".rb"), lineno
             ]
           end
         end
@@ -198,12 +191,56 @@ module Net
       def processed_string = string && pos && string[...pos]
       def remaining_string = string && pos && string[pos..]
 
+      # Returns true when all attributes are equal, except for #backtrace and
+      # #backtrace_locations which are replaced with #parser_methods.  This
+      # allows deserialized errors to be compared.
+      def ==(other)
+        return false if self.class != other.class
+        methods       = parser_methods
+        other_methods = other.parser_methods
+        message     == other.message &&
+          methods   == other_methods &&
+          string    == other.string &&
+          pos       == other.pos &&
+          lex_state == other.lex_state &&
+          token     == other.token
+      end
+
+      # Lists the methods (from #backtrace_locations or #backtrace) called on
+      # parser_class (since ruby 3.4) or which have "net/imap/response_parser"
+      # in the path (before ruby 3.4).  Most parser method names are based on
+      # rules in the IMAP grammar.
+      def parser_methods = normalized_parser_backtrace.map(&:last)
+
       private
 
+      def normalized_parser_backtrace
+        normalize_backtrace
+          .take_while {|_, _, _, _, base_label| base_label != "parse" }
+          .reject {|_, _, _, _, base_label| base_label.nil? }
+          .reject {|_, _, _, _, base_label| base_label.include? "parse_error" }
+          .select {|_, path, _, label, _|
+            if label.include?("#") # => Class#method, since ruby 3.4
+              label.include?(parser_class.name)
+            else
+              path.include?("net/imap/response_parser")
+            end
+          }
+      end
+
+      def normalize_backtrace
+        (backtrace_locations&.each_with_index&.map {|loc, idx|
+          [idx, loc.path, loc.lineno, loc.label, loc.base_label]
+        } || backtrace&.each_with_index&.map {|bt, idx|
+          [idx, *bt.match(/\A(\S+):(\d+):in [`'](.*?([\w]+[?!]?))'\z/)&.captures]
+        } || [])
+      end
+
       def default_highlight_from_env
         (ENV["FORCE_COLOR"] || "") !~ /\A(?:0|)\z/ ||
           (ENV["TERM"] || "") !~ /\A(?:dumb|unknown|)\z/i
       end
+
     end
 
     # Superclass of all errors used to encapsulate "fail" responses

data/lib/net/imap/response_data.rb

@@ -75,9 +75,18 @@ module Net
     #
     # Net::IMAP::UnparsedData represents data for unknown response types or
     # unknown extensions to response types without a well-defined extension
-    # grammar.
+    # grammar.  UnparsedData represents the portion of the response which the
+    # parser has skipped over, without attempting to parse it.
     #
-    # See also: UnparsedNumericResponseData, ExtensionData, IgnoredResponse
+    #    parser = Net::IMAP::ResponseParser.new
+    #    response = parser.parse "* X-UNKNOWN-TYPE can't parse this\r\n"
+    #    response => Net::IMAP::UntaggedResponse(
+    #      name: "X-UNKNOWN-TYPE",
+    #      data: Net::IMAP::UnparsedData(unparsed_data: "can't parse this"),
+    #    )
+    #
+    # See also: UnparsedNumericResponseData, ExtensionData, IgnoredResponse,
+    # InvalidParseData.
     class UnparsedData < Struct.new(:unparsed_data)
       ##
       # method: unparsed_data
@@ -86,6 +95,61 @@ module Net
       # The unparsed data
     end
 
+    # **Note:** This represents an intentionally _unstable_ API.  Where
+    # instances of this class are returned, future releases may return a
+    # different (incompatible) object <em>without deprecation or warning</em>.
+    #
+    # When the response parser encounters a recoverable error,
+    # Net::IMAP::InvalidParseData represents that portion of the response which
+    # could not be parsed, allowing the parser to parse the remainder of the
+    # response.  InvalidParseData is always associated with a ResponseParseError
+    # which has been rescued.
+    #
+    # This could be caused by a malformed server response, by a bug in
+    # Net::IMAP::ResponseParser, or by an unsupported extension to the response
+    # syntax.  For example, if a server supports +UIDPLUS+, but sends an invalid
+    # +COPYUID+ response code:
+    #
+    #    parser = Net::IMAP::ResponseParser.new
+    #    parsed = parser.parse "* OK [COPYUID 701  ] copied one message\r\n"
+    #    parsed => {
+    #      data: Net::IMAP::ResponseText(
+    #        code: Net::IMAP::ResponseCode(
+    #          name: "COPYUID",
+    #          data: Net::IMAP::InvalidParseData(
+    #            parse_error: Net::IMAP::ResponseParseError,
+    #            unparsed_data: "701  ",
+    #            parsed_data: nil,
+    #          )
+    #        )
+    #      )
+    #    }
+    #
+    # In this example, although <tt>[COPYUID 701  ]</tt> uses valid syntax for a
+    # _generic_ ResponseCode, it is _invalid_ syntax for a +COPYUID+ response
+    # code.
+    #
+    # See also: UnparsedData, ExtensionData
+    class InvalidParseData < Data.define(:parse_error, :unparsed_data, :parsed_data)
+      ##
+      # method: parse_error
+      # :call-seq: parse_error -> ResponseParseError
+      #
+      # Returns the rescued ResponseParseError.
+
+      ##
+      # method: unparsed_data
+      # :call-seq: unparsed_data -> string
+      #
+      # Returns the raw string which was skipped over by the parser.
+
+      ##
+      # method: parsed_data
+      #
+      # May return a partial parse result for unparsed_data, which had already
+      # been parsed before the parse_error.
+    end
+
     # **Note:** This represents an intentionally _unstable_ API.  Where
     # instances of this class are returned, future releases may return a
     # different (incompatible) object <em>without deprecation or warning</em>.
@@ -93,7 +157,17 @@ module Net
     # Net::IMAP::UnparsedNumericResponseData represents data for unhandled
     # response types with a numeric prefix.  See the documentation for #number.
     #
-    # See also: UnparsedData, ExtensionData, IgnoredResponse
+    #    parser = Net::IMAP::ResponseParser.new
+    #    response = parser.parse "* 123 X-UNKNOWN-TYPE can't parse this\r\n"
+    #    response => Net::IMAP::UntaggedResponse(
+    #      name: "X-UNKNOWN-TYPE",
+    #      data: Net::IMAP::UnparsedNumericData(
+    #        number: 123,
+    #        unparsed_data: "can't parse this"
+    #      ),
+    #    )
+    #
+    # See also: UnparsedData, ExtensionData, IgnoredResponse, InvalidParseData
     class UnparsedNumericResponseData < Struct.new(:number, :unparsed_data)
       ##
       # method: number
@@ -306,6 +380,14 @@ module Net
     #   because the server doesn't allow deletion of mailboxes with children.
     #   #data is +nil+.
     #
+    # === <tt>QUOTA=RES-*</tt> response codes
+    # See {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html#section-4.3].
+    # * +OVERQUOTA+ (also in RFC5530[https://www.rfc-editor.org/rfc/rfc5530]),
+    #   with a tagged +NO+ response to an +APPEND+/+COPY+/+MOVE+ command when
+    #   the command would put the target mailbox over any quota, and with an
+    #   untagged +NO+ when a mailbox exceeds a soft quota (which may be caused
+    #   be external events).  #data is +nil+.
+    #
     # === +CONDSTORE+ extension
     # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
     # * +NOMODSEQ+, when selecting a mailbox that does not support
@@ -324,9 +406,10 @@ module Net
     #
     # Response codes are backwards compatible:  Servers are allowed to send new
     # response codes even if the client has not enabled the extension that
-    # defines them.  When Net::IMAP does not know how to parse response
-    # code text, #data returns the unparsed string.
-    #
+    # defines them.  When ResponseParser does not know how to parse the response
+    # code data, #data may return the unparsed string, ExtensionData, or
+    # UnparsedData.  When ResponseParser attempts but fails to parse the
+    # response code data, #data returns InvalidParseData.
     class ResponseCode < Struct.new(:name, :data)
       ##
       # method: name
@@ -341,8 +424,13 @@ module Net
       #
       # Returns the parsed response code data, e.g: an array of capabilities
       # strings, an array of character set strings, a list of permanent flags,
-      # an Integer, etc.  The response #code determines what form the response
-      # code data can take.
+      # an Integer, etc.  The response #name determines what form the response
+      # code #data can take.
+      #
+      # When ResponseParser does not know how to parse the response code data,
+      # #data may return the unparsed string, ExtensionData, or UnparsedData.
+      # When ResponseParser attempts but fails to parse the response code data,
+      # #data returns InvalidParseData.
     end
 
     # MailboxList represents the data of an untagged +LIST+ response, for a
@@ -383,14 +471,23 @@ module Net
     # and MailboxQuota objects.
     #
     # == Required capability
+    #
     # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
-    # capability.
+    # or <tt>QUOTA=RES-STORAGE</tt>
+    # [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]] capability.
     class MailboxQuota < Struct.new(:mailbox, :usage, :quota)
       ##
       # method: mailbox
       # :call-seq: mailbox -> string
       #
-      # The mailbox with the associated quota.
+      # The quota root with the associated quota.
+      #
+      # NOTE: this was mistakenly named "mailbox".  But the quota root's name may
+      # differ from the mailbox.  A single quota root may cover multiple
+      # mailboxes, and a single mailbox may be governed by multiple quota roots.
+
+      # The quota root with the associated quota.
+      alias quota_root mailbox
 
       ##
       # method: usage
@@ -402,7 +499,7 @@ module Net
       # method: quota
       # :call-seq: quota -> Integer
       #
-      # Quota limit imposed on the mailbox.
+      # Storage limit imposed on the mailbox.
       #
     end