net-imap 0.6.4 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffcec5e3cc42d7f72c63520110ec442f760c35472401de495001f420cfa059c5
-  data.tar.gz: aedd703997fc651cb6c67635a3d20a4159720c6e1bda41c07322f2bd67a627d6
+  metadata.gz: cd2bbaf7d6564739894405f3066c772976b48062ea2c696b741d10aa34ebbed6
+  data.tar.gz: 1fa2b00d9869e60e44be3a3aea1e058f0974705aef5a41a62f4ea25ee4fda48d
 SHA512:
-  metadata.gz: 1fa95302f29607d152b991535a9d14cda5dae1a1fce06b1d831dd2b09f69b2fd845367e0ebed73dd4e79d04c064a801e59865e76947060a4811304728458f3c7
-  data.tar.gz: 2dc9a56758d6f370affc9540a8ca26b8ad866ca5ef0e5b9bc2c30ff6257e3461e5ed23173e1c5e98a2e95c1e0f0a844c96f9e34d41151e9196ab513ac6987d33
+  metadata.gz: dc1083920d0f196a21db61ef8282be1aa214e43b38ba18bf5ada58fa16d9b007f2169332fc0df2e5799e2ec1e76f15b1469d0c2401e851feb0409237b7f60ee2
+  data.tar.gz: 4b9c9ba8892b67ec86c39f4ad3f28c5dd91ad785def8b9324175a0f6bac6940dffde3499135f045a911dde98646afff687c2bd6381117f14bdf68de244f03dea

data/.simplecov

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+SimpleCov.configure do
+  formatter SimpleCov::Formatter::HTMLFormatter
+
+  enable_coverage  :branch
+  enable_coverage  :method
+  enable_coverage  :eval
+
+  skip "/test/"
+  skip "/rakelib/"
+  cover "lib/**/*.rb"
+
+  group "Parser",     %w[lib/net/imap/response_parser.rb
+                         lib/net/imap/response_parser]
+
+  group "Client",     %w[lib/net/imap.rb
+                         lib/net/imap/connection_state.rb
+                         lib/net/imap/deprecated_client_options.rb
+                         lib/net/imap/errors.rb
+                         lib/net/imap/response_reader.rb]
+
+  group "Config",     %w[lib/net/imap/config.rb
+                         lib/net/imap/config]
+
+  group "Data Types", %w[lib/net/imap/flags.rb
+                         lib/net/imap/sequence_set.rb] +
+                         [%r{lib/net/imap/\w*_data\.rb},
+                          %r{lib/net/imap/\w*_result.rb},
+                          %r{lib/net/imap/data_\w+\.rb}]
+
+  group "SASL",       %w[lib/net/imap/sasl.rb
+                         lib/net/imap/sasl
+                         lib/net/imap/sasl_adapter.rb
+                         lib/net/imap/authenticators.rb]
+
+  group "StringPrep", %w[lib/net/imap/stringprep.rb
+                         lib/net/imap/stringprep]
+end

data/Gemfile

@@ -20,7 +20,5 @@ gem "benchmark-driver", require: false
 gem "vernier", require: false, platform: :mri
 
 group :test do
-  gem "simplecov",        require: false, platforms: %i[mri windows]
-  gem "simplecov-html",   require: false, platforms: %i[mri windows]
-  gem "simplecov-json",   require: false, platforms: %i[mri windows]
+  gem "simplecov", ">= 1.0.0", require: false, platforms: %i[mri windows]
 end

data/Rakefile

@@ -11,3 +11,14 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task :default => :test
+
+desc "Output coverage data report, and error when threshholds aren't met"
+task "coverage:report" do
+  require "simplecov"
+  SimpleCov.collate "coverage/.resultset.json" do
+    coverage(:line) do
+      minimum           90
+      minimum_per_file  40
+    end
+  end
+end

data/lib/net/imap/command_data.rb

@@ -15,15 +15,19 @@ module Net
       case data
       when nil
       when String
+        if data.include?("\0")
+          raise DataFormatError, "String argument contains NULL byte"
+        end
       when Integer
-        NumValidator.ensure_number(data)
+        # Covers modseq-valzer, which is the largest valid IMAP integer
+        if data.negative?
+          raise DataFormatError, "Integer argument must be unsigned: #{data}"
+        elsif 0xffff_ffff_ffff_ffff < data
+          raise DataFormatError, "Integer argument must fit in 64 bits: #{data}"
+        end
       when Array
-        if data[0] == 'CHANGEDSINCE'
-          NumValidator.ensure_mod_sequence_value(data[1])
-        else
-          data.each do |i|
-            validate_data(i)
-          end
+        data.each do |i|
+          validate_data(i)
         end
       when Time, Date, DateTime
       when Symbol
@@ -54,45 +58,62 @@ module Net
       end
     end
 
+    UNQUOTABLE_CHARS = /\0\r\n/
+    ASTRING_SPECIALS = /[(){ \x00-\x1f\x7f%*"\\]/
+    private_constant :UNQUOTABLE_CHARS, :ASTRING_SPECIALS
+
+    # Sends generic strings formatted as +astring+:
+    # * as an atom (note: this is based on +ASTRING-CHAR+, not +ATOM-CHAR+)
+    # * as a quoted string
+    # * as a literal (may send non-synchronizing)
+    #
+    # NOTE: This does not validate that +str+ contains no +NULL+ bytes.
     def send_string_data(str, tag = nil)
       if str.empty?
+        # same as send_quoted_string(str), but incompatible encoding is allowed
         put_string('""')
-      elsif str.match?(/[\r\n]/n)
-        # literal, because multiline
-        send_literal(str, tag)
-      elsif !str.ascii_only?
-        if @utf8_strings
-          # quoted string
-          send_quoted_string(str)
-        else
-          # literal, because of non-ASCII bytes
-          send_literal(str, tag)
-        end
-      elsif str.match?(/[(){ \x00-\x1f\x7f%*"\\]/n)
-        # quoted string
+      elsif str.ascii_only? && !str.match?(ASTRING_SPECIALS)
+        # valid +astring+ atom: non-empty, ASCII only, no ASTRING_SPECIALS
+        put_string(str)
+      elsif text_encodable?(str) && !str.match?(UNQUOTABLE_CHARS)
         send_quoted_string(str)
       else
-        put_string(str)
+        send_literal(str, tag)
       end
     end
 
-    def send_quoted_string(str)
-      put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
+    # Encodable as +text+ (which is a superset of +quoted+):
+    # * ASCII only (for any ASCII compatible encoding)
+    # * or valid UTF-8 (when the connection supports it)
+    def text_encodable?(str)
+      str.ascii_only? || (utf8_enabled? &&
+                          str.encoding == Encoding::UTF_8 &&
+                          str.valid_encoding?)
     end
 
+    def send_quoted_string(str) = QuotedString.new(data: str).send_data(self)
+
     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.
+    #   NOTE: raises DataFormatError when server doesn't support
+    #   non-synchronizing literal, or literal is too large for LITERAL-.
     # * `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)
+      bytesize = str.bytesize
       synchronize do
-        non_sync = non_sync_literal?(str.bytesize) if non_sync.nil?
+        if non_sync && !non_sync_literal_allowed?(bytesize)
+          # TODO: check in Printer, so we don't need to close the connection.
+          @sock.close
+          raise DataFormatError, "Connection closed: " \
+            "Cannot send non-synchronizing literal without known server support"
+        end
+        non_sync = non_sync_literal?(bytesize) if non_sync.nil?
         prefix = "~" if binary
         plus = "+" if non_sync
-        put_string("#{prefix}{#{str.bytesize}#{plus}}\r\n")
+        put_string("#{prefix}{#{bytesize}#{plus}}\r\n")
         if non_sync
           put_string(str)
           return
@@ -101,8 +122,7 @@ module Net
         @continuation_request_exception = nil
         begin
           @continuation_request_arrival.wait
-          e = @continuation_request_exception || @exception
-          raise e if e
+          reraise @continuation_request_exception || @exception
           put_string(str)
         ensure
           @continued_command_tag = nil
@@ -112,14 +132,22 @@ module Net
     end
 
     def non_sync_literal?(bytesize)
-      capabilities_cached? &&
-        bytesize <= config.max_non_synchronizing_literal &&
-        (capable?("LITERAL+") ||
-         bytesize <= 4096 && (capable?("IMAP4rev2") || capable?("LITERAL-")))
+      bytesize <= config.max_non_synchronizing_literal \
+        && non_sync_literal_allowed?(bytesize)
+    end
+
+    def non_sync_literal_allowed?(bytesize)
+      return unless capabilities_cached?
+      return "+" if capable?("LITERAL+")
+      return "-" if capable_literal_minus? && bytesize <= 4096
+      false
     end
 
+    def capable_literal_minus? = capable?("LITERAL-") || capable?("IMAP4rev2")
+
+    # NOTE: +num+ should already be an Integer
     def send_number_data(num)
-      put_string(num.to_s)
+      put_string(Integer(num).to_s)
     end
 
     def send_list_data(list, tag = nil)
@@ -139,6 +167,9 @@ 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
 
+    # NOTE: Currently for internal use only.  The API is expected to change.
+    Command = Data.define(:tag, :name) # :nodoc:
+
     CommandData = Data.define(:data) do # :nodoc:
       def self.validate(...)
         data = new(...)
@@ -154,36 +185,38 @@ 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+.
+    # Represents IMAP +text+ or +quoted+ data, which share the same
+    # validations of decoded #data, and differ only in how they are formatted.
+    #
+    # +data+ may contain any 7-bit ASCII character except +NULL+, +CR+, or +LF+.
+    # Any multibyte +UTF-8+ character is also allowed when the connection
+    # supports UTF8: either +UTF8=ACCEPT+ or +IMAP4rev2+ have been enabled, or
+    # the server supports only +IMAP4rev2+ and not earlier IMAP revisions, or
+    # the server advertises +UTF8=ONLY+.
     #
-    # NOTE: The current implementation does not validate whether the connection
-    # currently supports UTF-8.  Future versions may change.
+    # NOTE: This does not verify whether the connection supports UTF-8, but that
+    # may change in future versions.
     #
     # 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:
+    class ValidNonLiteralData < CommandData
       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"))
+        unless data.encoding in Encoding::ASCII | Encoding::UTF_8
+          data = data.dup.force_encoding(data.ascii_only? ? "ASCII" : "UTF-8")
         end
+        data = -data
         super
         validate
       end
 
       def validate
-        if data.include?("\0")
-          raise DataFormatError, "NULL byte must be binary literal encoded"
+        if !(data.encoding in Encoding::ASCII | Encoding::UTF_8)
+          raise DataFormatError, "must use ASCII or UTF-8 encoding"
         elsif !data.valid_encoding?
           raise DataFormatError, "invalid UTF-8 must be literal encoded"
+        elsif data.include?("\0")
+          raise DataFormatError, "NULL byte must be binary literal encoded"
         elsif /[\r\n]/.match?(data)
           raise DataFormatError, "CR and LF bytes must be literal encoded"
         end
@@ -191,12 +224,27 @@ module Net
 
       def ascii_only? = data.ascii_only?
 
-      def send_data(imap, tag) = imap.__send__(:put_string, data)
+      def send_data(imap, tag = nil) = imap.__send__(:put_string, formatted)
+    end
+
+    # Represents IMAP +text+ data, which covers everything in the IMAP grammar,
+    # except for +literal+, +literal8+, and the concluding +CRLF+.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class RawText < ValidNonLiteralData # :nodoc:
+      # raw: no formatting necessary
+      alias formatted data
     end
 
     class RawData < CommandData # :nodoc:
       def initialize(data:)
-        data = split_parts(data)
+        case data
+        in String then data = self.class.split(data)
+        in Array  if   data.all? { _1 in RawText | Literal }
+        else
+          raise TypeError, "expected String or Array[#{RawText} | #{Literal}]"
+        end
         super
         validate
       end
@@ -205,14 +253,16 @@ module Net
 
       def validate
         return unless data.last in RawText(data: text)
-        if text.rindex(/~?\{[1-9]\d*\+?\}\z/n)
+        if text.rindex(/\{\d+\+?\}\z/n)
           raise DataFormatError, "RawData cannot end with literal continuation"
         end
       end
 
-      private
-
-      def split_parts(data)
+      # Splits an input +string+ into an array of RawText and Literal/Literal8.
+      #
+      # NOTE: unlike RawData#validate, this does not prevent the final RawText
+      # from ending with a literal prefix.
+      def self.split(data)
         data = data.b # dups and ensures BINARY encoding
         parts = []
         while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n)
@@ -226,7 +276,7 @@ module Net
         parts
       end
 
-      def extract_literal(data, binary:, bytesize:, non_sync:)
+      def self.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]
@@ -234,8 +284,20 @@ module Net
         literal = data.byteslice(0, bytesize)
         (binary ? Literal8 : Literal).new(data: literal, non_sync:)
       end
+      private_class_method :extract_literal
     end
 
+    # Please note that +ATOM-CHAR+ and +atom+ are not the same as +ASTRING-char+
+    # and the atom form of +astring+.  +astring+ allows <tt>]</tt>, but +atom+
+    # does not.
+    #
+    # Generic string arguments in Net::IMAP use +astring+, so they will send as
+    # atoms even if they contain <tt>]</tt>.
+    #
+    # This class is used by:
+    # * to validate generic symbol arguments, as the superclass of Flag
+    # * to validate #enable +capabilities+
+    # * to validate #store (and #uid_store) +attr+
     class Atom < CommandData # :nodoc:
       def initialize(**)
         super
@@ -247,6 +309,8 @@ module Net
           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"
+        data.empty? \
+          and raise DataFormatError, "#{self.class} must not be empty"
       end
 
       def send_data(imap, tag)
@@ -260,10 +324,13 @@ module Net
       end
     end
 
-    class QuotedString < CommandData # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:send_quoted_string, data)
-      end
+    # Represents a IMAP +quoted+ string, which can encode any valid ASCII or
+    # UTF-8 string, unless it contains any +CR+, +LF+, or +NULL+ bytes.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class QuotedString < ValidNonLiteralData # :nodoc:
+      def formatted = %("#{data.gsub(/["\\]/, "\\\\\\&")}")
     end
 
     class Literal < Data.define(:data, :non_sync) # :nodoc:

data/lib/net/imap/config.rb

@@ -310,7 +310,7 @@ module Net
       #
       # * original: +-1+ (_never_ send non-synchronizing literals)
       # * +0.6+: 16 KiB
-      attr_accessor :max_non_synchronizing_literal, type: Integer?, defaults: {
+      attr_accessor :max_non_synchronizing_literal, type: Integer, defaults: {
         0.0r => -1,
         0.6r => 16 << 16, # 16 KiB
       }

data/lib/net/imap/data_encoding.rb

@@ -155,7 +155,8 @@ module Net
 
     # Common validators of number and nz_number types
     module NumValidator # :nodoc
-      NUMBER_RE = /\A(?:0|[1-9]\d*)\z/
+      NUMBER_RE = /\A\d+\z/
+      NZ_NUMBER_RE = /\A[1-9]\d*\z/
       module_function
 
       # Check if argument is a valid 'number' according to RFC 3501
@@ -251,7 +252,7 @@ module Net
       def coerce_number(num)
         case num
         when Integer   then ensure_number num
-        when NUMBER_RE then ensure_number Integer num
+        when NUMBER_RE then ensure_number num.to_i
         else
           raise DataFormatError, "%p is not a valid number" % [num]
         end
@@ -260,8 +261,8 @@ module Net
       # Like #ensure_nz_number, but usable with numeric String input.
       def coerce_nz_number(num)
         case num
-        when Integer   then ensure_nz_number num
-        when NUMBER_RE then ensure_nz_number Integer num
+        when Integer      then ensure_nz_number num
+        when NZ_NUMBER_RE then ensure_nz_number num.to_i
         else
           raise DataFormatError, "%p is not a valid nz-number" % [num]
         end
@@ -271,7 +272,7 @@ module Net
       def coerce_number64(num)
         case num
         when Integer   then ensure_number64 num
-        when NUMBER_RE then ensure_number64 Integer num
+        when NUMBER_RE then ensure_number64 num.to_i
         else
           raise DataFormatError, "%p is not a valid number64" % [num]
         end
@@ -280,8 +281,8 @@ module Net
       # 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
+        when Integer      then ensure_nz_number64 num
+        when NZ_NUMBER_RE then ensure_nz_number64 num.to_i
         else
           raise DataFormatError, "%p is not a valid nz-number64" % [num]
         end
@@ -291,7 +292,7 @@ module Net
       def coerce_mod_sequence_value(num)
         case num
         when Integer   then ensure_mod_sequence_value num
-        when NUMBER_RE then ensure_mod_sequence_value Integer num
+        when NUMBER_RE then ensure_mod_sequence_value num.to_i
         else
           raise DataFormatError, "%p is not a valid mod-sequence-value" % [num]
         end
@@ -301,7 +302,7 @@ module Net
       def coerce_mod_sequence_valzer(num)
         case num
         when Integer   then ensure_mod_sequence_valzer num
-        when NUMBER_RE then ensure_mod_sequence_valzer Integer num
+        when NUMBER_RE then ensure_mod_sequence_valzer num.to_i
         else
           raise DataFormatError, "%p is not a valid mod-sequence-valzer" % [num]
         end

data/lib/net/imap/errors.rb

@@ -279,7 +279,11 @@ module Net
     #
     # This is different from UnknownResponseError: the response has been
     # rejected.  Although it may be parsable, the server is forbidden from
-    # sending it in the current context.  The client should automatically
+    # sending it in the current context.
+    #
+    # This could be caused by a bug in the server or in Net::IMAP.  Or it
+    # might indicate a malicious server, a man-in-the-middle attack, or
+    # client-side command injection.  So the client should automatically
     # disconnect, abruptly (without logout).
     #
     # Note that InvalidResponseError does not inherit from ResponseError: it
@@ -288,6 +292,67 @@ module Net
     class InvalidResponseError < Error
     end
 
+    # Error raised when the server sends a tagged #response that is invalid for
+    # the #command #state.
+    #
+    # This could be caused by a bug in the server or in Net::IMAP.  Or it
+    # might indicate a malicious server, a man-in-the-middle attack, or
+    # client-side command injection, so the client should disconnect
+    # automatically and abruptly (without logout).
+    class InvalidTaggedResponseError < InvalidResponseError
+      # A symbol representing the state of the matching tagged command.
+      #
+      # +:unknown+::
+      #   #response does not match any known command (#command will be +nil+).
+      # +:unstarted+::
+      #   Any tagged #response is invalid before #command starts sending.
+      # +:incomplete+::
+      #   A tagged +OK+ #response is invalid before #command is fully sent.
+      # +:completed+::
+      #   Multiple tagged responses were received for the same command.
+      #
+      # NOTE: Command state is neither anticipated nor remembered indefinitely.
+      # +:unknown+ is used before the matching command is called and after the
+      # it is forgotten.
+      #
+      # NOTE: This version of Net::IMAP does not detect or raise an exception
+      # for all of these states.
+      attr_reader :state
+
+      # Metadata about the matching IMAP command.
+      #
+      # Returns +nil+ when #state is +:unknown+.
+      #
+      # NOTE: The non-nil return type is an unstable API, for debug only.  It
+      # may be changed by any release, without warning or deprecation.
+      attr_reader :command
+
+      # The TaggedResponse which triggered this error
+      attr_reader :response
+
+      def initialize(state, response:, command: nil)
+        response => TaggedResponse[tag:, name: status]
+        case [state, status, command]
+        in :unknown,                _,    nil
+        in :incomplete,             "OK", {tag: ^tag, name:}
+        in :unstarted | :completed, _,    {tag: ^tag, name:}
+        end
+        @state, @command, @response = state, command, response
+        cmd_desc = name ? "#{state} #{name}" : state
+        super "Received tagged #{status} to #{cmd_desc} command (tag=#{tag})"
+      rescue NoMatchingPatternError => err
+        raise ArgumentError, err.message
+      end
+
+      def detailed_message(**)
+        "#{message}.\n" \
+          "Disconnecting: This could indicate a malicious server, a " \
+          "man-in-the-middle attack, a client-side command injection, or " \
+          "a bug in net-imap.\n" \
+          "response.data=#{response.data.inspect}"
+      end
+    end
+
     # Error raised upon an unknown response from the server.
     #
     # This is different from InvalidResponseError: the response may be a

data/lib/net/imap/response_parser.rb

@@ -2212,10 +2212,7 @@ module Net
             if $1
               return Token.new(T_SPACE, $+)
             elsif $2
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL8, val)
+              literal_token($+, T_LITERAL8)
             elsif $3 && $7
               # greedily match ATOM, prefixed with NUMBER, NIL, or PLUS.
               return Token.new(T_ATOM, $3)
@@ -2243,10 +2240,7 @@ module Net
             elsif $15
               return Token.new(T_RBRA, $+)
             elsif $16
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL, val)
+              literal_token($+)
             elsif $17
               return Token.new(T_PERCENT, $+)
             elsif $18
@@ -2272,10 +2266,7 @@ module Net
             elsif $4
               return Token.new(T_QUOTED, Patterns.unescape_quoted($+))
             elsif $5
-              len = $+.to_i
-              val = @str[@pos, len]
-              @pos += len
-              return Token.new(T_LITERAL, val)
+              literal_token($+)
             elsif $6
               return Token.new(T_LPAR, $+)
             elsif $7
@@ -2290,6 +2281,15 @@ module Net
         else
           parse_error("invalid @lex_state - %s", @lex_state.inspect)
         end
+      rescue DataFormatError => error
+        parse_error error.message
+      end
+
+      def literal_token(len, type = T_LITERAL)
+        len = NumValidator.coerce_number64 len
+        val = @str[@pos, len]
+        @pos += len
+        Token.new(type, val)
       end
 
     end

data/lib/net/imap/response_reader.rb

@@ -4,6 +4,8 @@ module Net
   class IMAP
     # See https://www.rfc-editor.org/rfc/rfc9051#section-2.2.2
     class ResponseReader # :nodoc:
+      include NumValidator
+
       attr_reader :client
 
       def initialize(client, sock)
@@ -46,7 +48,10 @@ module Net
       def line_done?          = buff.end_with?(CRLF)
 
       def get_literal_size(buff)
-        buff.end_with?("}\r\n") && buff.rindex(/\{(\d+)\}\r\n\z/n) && $1.to_i
+        buff.end_with?("}\r\n") && buff.rindex(/\{(\d+)\}\r\n\z/n) &&
+          coerce_number64($1)
+      rescue DataFormatError
+        raise DataFormatError, format("invalid response literal size (%s)", $1)
       end
 
       def read_line

data/lib/net/imap.rb

@@ -326,6 +326,11 @@ module Net
   #
   #   <em>In general, #capable? should be used rather than explicitly sending a
   #   +CAPABILITY+ command to the server.</em>
+  # - #enable: Enables backwards incompatible server extensions.
+  #   <em>Requires the +ENABLE+ or +IMAP4rev2+ capability.</em>
+  # - #enabled: Returns a set of enabled server extensions.
+  # - #enabled?: Returns whether a server extension has been enabled.
+  # - #utf8_enabled?: Returns whether UTF-8 string encoding has been enabled.
   #
   # === Handling server responses
   #
@@ -552,6 +557,7 @@ module Net
   # ==== RFC6855: <tt>UTF8=ACCEPT</tt>, <tt>UTF8=ONLY</tt>
   #
   # - See #enable for information about support for UTF-8 string encoding.
+  # - #utf8_enabled?: Returns whether UTF-8 string encoding has been enabled.
   #
   # ==== RFC7162: +CONDSTORE+
   #
@@ -813,7 +819,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.6.4"
+    VERSION = "0.6.5"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -821,6 +827,11 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
+    # Aliases for supported capabilities, to be used with #enabled?.
+    ENABLED_ALIASES = {
+      utf8: Set.new(%w[UTF8=ACCEPT IMAP4REV2]).freeze,
+    }.freeze
+
     dir = File.expand_path("imap", __dir__)
     autoload :ConnectionState,        "#{dir}/connection_state"
     autoload :ResponseReader,         "#{dir}/response_reader"
@@ -1110,11 +1121,11 @@ module Net
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(ssl)
 
       # Basic Client State
-      @utf8_strings = false
       @debug_output_bol = true
       @exception = nil
       @greeting = nil
       @capabilities = nil
+      @enabled = Set.new
       @tls_verified = false
       @connection_state = ConnectionState::NotAuthenticated.new
 
@@ -1160,16 +1171,29 @@ module Net
     #   imap.logout
     #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS logout>"
     #
+    #   imap = Net::IMAP.new(hostname, ssl: false)
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:143 PLAINTEXT not_authenticated>"
+    #
+    #   imap.starttls verify_mode: OpenSSL::SSL::VERIFY_NONE
+    #   imap.inspect #=> "#<Net::IMAP imap.example.net:993 TLS (NOT VERIFIED) not_authenticated>"
+    #
     def inspect
-      tls_state = tls_verified? ? "TLS" :
-        ssl_ctx ? "TLS (NOT VERIFIED)" :
-        "PLAINTEXT"
       conn_state = disconnected? ? "disconnected" : connection_state.to_sym
       "#<%s:0x%08x %s:%s %s %s>" % [
-        self.class.name, __id__, host, port, tls_state, conn_state
+        self.class.name, __id__, host, port, inspect_tls_state, conn_state
       ]
     end
 
+    private def inspect_tls_state
+      if tls_verified?
+        "TLS"
+      elsif ssl_ctx && @sock.kind_of?(OpenSSL::SSL::SSLSocket)
+        "TLS (#{@sock.session ? "NOT VERIFIED" : "NOT ESTABLISHED"})"
+      else
+        "PLAINTEXT#{" (TLS NOT STARTED)" if ssl_ctx}"
+      end
+    end
+
     # Returns true after the TLS negotiation has completed and the remote
     # hostname has been verified.  Returns false when TLS has been established
     # but peer verification was disabled.
@@ -1177,22 +1201,25 @@ module Net
 
     # Disconnects from the server.
     #
-    # Waits for receiver thread to close before returning.  Slow or stuck
-    # response handlers can cause #disconnect to hang until they complete.
+    # Waits for receiver thread to close before returning, except when called
+    # from inside the connection mutex such as from a response handler.  Slow or
+    # stuck response handlers can cause #disconnect to hang until they complete.
+    # Use +timeout+ to limit how long to wait for the receiver thread to exit.
     #
     # Related: #logout, #logout!
-    def disconnect
+    def disconnect(timeout: nil)
       in_logout_state = try_state_logout?
       return if disconnected?
+      in_receiver_thread = Thread.current == @receiver_thread
       begin
         @sock.to_io.shutdown
       rescue Errno::ENOTCONN
         # ignore `Errno::ENOTCONN: Socket is not connected' on some platforms.
       rescue Exception => e
-        @receiver_thread.raise(e)
+        @receiver_thread.raise(e) unless in_receiver_thread
       end
       @sock.close
-      @receiver_thread.join
+      @receiver_thread.join(timeout) unless mon_owned? || in_receiver_thread
       raise e if e
     ensure
       # Try again after shutting down the receiver thread.  With no reciever
@@ -1454,7 +1481,7 @@ module Net
       end
       if error
         disconnect
-        raise error
+        reraise error
       end
       unless handled
         disconnect
@@ -2242,6 +2269,7 @@ module Net
     # provided as an array or a string.
     # See {"Argument translation"}[rdoc-ref:#search@Argument+translation]
     # and {"Search criteria"}[rdoc-ref:#search@Search+criteria], below.
+    # <em>Please note</em> the warning for when +criteria+ is a String.
     #
     # +return+ options control what kind of information is returned about
     # messages matching the search +criteria+.  Specifying +return+ should force
@@ -2652,7 +2680,8 @@ module Net
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
-    # See #search for documentation of parameters.
+    # See #search for documentation of parameters.  <em>Please note</em> the
+    # warning for when +criteria+ is a String.
     #
     # ==== Capabilities
     #
@@ -2738,7 +2767,8 @@ module Net
     # {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets].
     # (For message sequence numbers, use #fetch instead.)
     #
-    # +attr+ behaves the same as with #fetch.
+    # +attr+ behaves the same as with #fetch.  <em>Please note</em> the #fetch
+    # warning on the +attr+ argument.
     # >>>
     #   *Note:* Servers _MUST_ implicitly include the +UID+ message data item as
     #   part of any +FETCH+ response caused by a +UID+ command, regardless of
@@ -2950,8 +2980,10 @@ module Net
 
     # Sends a {SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox for messages that match +search_keys+ and return an
-    # array of message sequence numbers, sorted by +sort_keys+.  +search_keys+
-    # are interpreted the same as for #search.
+    # array of message sequence numbers, sorted by +sort_keys+.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     #--
     # TODO: describe +sort_keys+
@@ -2976,8 +3008,10 @@ module Net
 
     # Sends a {UID SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox for messages that match +search_keys+ and return an
-    # array of unique identifiers, sorted by +sort_keys+.  +search_keys+ are
-    # interpreted the same as for #search.
+    # array of unique identifiers, sorted by +sort_keys+.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     # Related: #sort, #search, #uid_search, #thread, #uid_thread
     #
@@ -2991,8 +3025,10 @@ module Net
 
     # Sends a {THREAD command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
     # to search a mailbox and return message sequence numbers in threaded
-    # format, as a ThreadMember tree.  +search_keys+ are interpreted the same as
-    # for #search.
+    # format, as a ThreadMember tree.
+    #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
     #
     # The supported algorithms are:
     #
@@ -3018,6 +3054,9 @@ module Net
     # Similar to #thread, but returns unique identifiers instead of
     # message sequence numbers.
     #
+    # +search_keys+ are interpreted the same as the +criteria+ argument for
+    # #search.  <em>Please note</em> the #search warning for String +criteria+.
+    #
     # Related: #thread, #search, #uid_search, #sort, #uid_sort
     #
     # ==== Capabilities
@@ -3127,17 +3166,54 @@ module Net
       capabilities = capabilities
         .flatten
         .map {|e| ENABLE_ALIASES[e] || e }
+        .flat_map { _1.is_a?(String) && !_1.empty? ? _1.split(/ /, -1) : [_1] }
         .uniq
-        .join(' ')
+        .map { Atom[_1] }
       synchronize do
-        send_command("ENABLE #{capabilities}")
+        send_command("ENABLE", *capabilities)
         result = clear_responses("ENABLED").last || []
-        @utf8_strings ||= result.include? "UTF8=ACCEPT"
-        @utf8_strings ||= result.include? "IMAP4REV2"
+        @enabled.merge(result.map(&:upcase))
         result
       end
     end
 
+    # Returns whether UTF-8 string encoding has been enabled for the connection.
+    #
+    # This is currently identical to calling #enabled? with +:utf8+.
+    #
+    # See #enable and #enabled?.
+    def utf8_enabled?; enabled?(:utf8) end
+
+    # Returns whether +capability+ is in the set of #enabled capabilities,
+    # matched case-insensitively.
+    #
+    # When +capability+ is +:utf8+, it matches if _either_
+    # <tt>"UTF8=ACCEPT"</tt> or <tt>"IMAP4REV2"</tt> is enabled.
+    #
+    # See #enable and #utf8_enabled?.
+    def enabled?(capability)
+      case capability
+      in String
+        capability = capability.upcase
+        synchronize { @enabled.include?(capability) }
+      in Symbol
+        capabilities = ENABLED_ALIASES[capability] or
+          raise ArgumentError, "unknown capability alias: #{capability}"
+        synchronize { @enabled.intersect?(capabilities) }
+      else
+        raise TypeError, "expected capability to be String or Symbol, " \
+                         "got %s" % [capability.class]
+      end
+    end
+
+    # Returns a set of enabled capabilities for the connection, as upper-cased
+    # strings.
+    #
+    # See #enable and #enabled?.
+    def enabled
+      synchronize { @enabled.dup }
+    end
+
     # Sends an {IDLE command [RFC2177 §3]}[https://www.rfc-editor.org/rfc/rfc6851#section-3]
     # {[IMAP4rev2 §6.3.13]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.13]
     # that waits for notifications of new or expunged messages.  Yields
@@ -3174,8 +3250,9 @@ module Net
 
       synchronize do
         tag = Thread.current[:net_imap_tag] = generate_tag
-        guard_against_tagged_response_skipping_handler!(tag, "IDLE")
+        command = Command[tag:, name: "IDLE"]
         put_string("#{tag} IDLE#{CRLF}")
+        finish_sending_command(command)
 
         begin
           add_response_handler(&response_handler)
@@ -3183,7 +3260,7 @@ module Net
           @idle_done_cond.wait(timeout)
           @idle_done_cond = nil
           if @receiver_thread_terminating
-            raise @exception || Net::IMAP::Error.new("connection closed")
+            reraise @exception || Net::IMAP::Error.new("connection closed")
           end
         ensure
           remove_response_handler(response_handler)
@@ -3192,6 +3269,9 @@ module Net
             response = get_tagged_response(tag, "IDLE", idle_response_timeout)
           end
         end
+      rescue InvalidResponseError
+        disconnect
+        raise
       end
 
       return response
@@ -3483,67 +3563,28 @@ module Net
     end
 
     def receive_responses
-      connection_closed = false
-      until connection_closed
-        synchronize do
-          @exception = nil
-        end
-        begin
-          resp = get_response
-        rescue Exception => e
-          synchronize do
-            state_logout!
-            @sock.close
-            @exception = e
-          end
-          break
-        end
-        unless resp
-          synchronize do
-            @exception = EOFError.new("end of file reached")
-          end
-          break
-        end
-        begin
-          synchronize do
-            case resp
-            when TaggedResponse
-              @tagged_responses[resp.tag] = resp
-              @tagged_response_arrival.broadcast
-              case resp.tag
-              when @logout_command_tag
-                state_logout!
-                return
-              when @continued_command_tag
-                @continuation_request_exception =
-                  RESPONSE_ERRORS[resp.name].new(resp)
-                @continuation_request_arrival.signal
-              end
-            when UntaggedResponse
-              record_untagged_response(resp)
-              if resp.name == "BYE" && @logout_command_tag.nil?
-                state_logout!
-                @sock.close
-                @exception = ByeResponseError.new(resp)
-                connection_closed = true
-              end
-            when ContinuationRequest
-              @continuation_request_arrival.signal
-            end
-            state_unselected! if resp in {data: {code: {name: "CLOSED"}}}
-            @response_handlers.each do |handler|
-              handler.call(resp)
-            end
-          end
-        rescue Exception => e
-          @exception = e
-          synchronize do
-            @tagged_response_arrival.broadcast
-            @continuation_request_arrival.broadcast
-          end
-        end
+      exception = nil
+      loop do
+        resp = get_response or raise EOFError, "end of file reached"
+        handle_response(resp) or return
       end
+    rescue Exception => exception
+      # NOTE: this rescue clause is only capturing the exception for the ensure
+      # clause.  Using `$!` in the ensure clause seems to trigger a weird
+      # TruffleRuby bug: https://github.com/truffleruby/truffleruby/issues/4308
+      #
+      # We don't assign @exception directly here, because we want that to be
+      # atomically synchronized with all of the other changes in `ensure`.
+      raise
+    ensure
       synchronize do
+        if exception
+          # Handling exceptions here, not in a rescue clause, so the lock isn't
+          # released and reacquired between rescue and ensure clauses.
+          @exception ||= exception
+          @sock.close
+        end
+        state_logout!
         @receiver_thread_terminating = true
         @tagged_response_arrival.broadcast
         @continuation_request_arrival.broadcast
@@ -3551,36 +3592,6 @@ module Net
           @idle_done_cond.signal
         end
       end
-    ensure
-      state_logout!
-    end
-
-    def get_tagged_response(tag, cmd, timeout = nil)
-      if timeout
-        deadline = Time.now + timeout
-      end
-      until @tagged_responses.key?(tag)
-        raise @exception if @exception
-        if timeout
-          timeout = deadline - Time.now
-          if timeout <= 0
-            return nil
-          end
-        end
-        @tagged_response_arrival.wait(timeout)
-      end
-      resp = @tagged_responses.delete(tag)
-      case resp.name
-      when /\A(?:OK)\z/ni
-        return resp
-      when /\A(?:NO)\z/ni
-        raise NoResponseError, resp
-      when /\A(?:BAD)\z/ni
-        raise BadResponseError, resp
-      else
-        disconnect
-        raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw_data.chomp]
-      end
     end
 
     def get_response
@@ -3593,6 +3604,47 @@ module Net
     #############################
     # built-in response handlers
 
+    def handle_response(resp)
+      connection_closed = false
+      synchronize do
+        case resp
+        when TaggedResponse
+          @tagged_responses[resp.tag] = resp
+          @tagged_response_arrival.broadcast
+          case resp.tag
+          when @logout_command_tag
+            state_logout!
+            return
+          when @continued_command_tag
+            @continuation_request_exception =
+              RESPONSE_ERRORS[resp.name].new(resp)
+            @continuation_request_arrival.signal
+          end
+        when UntaggedResponse
+          record_untagged_response(resp)
+          if resp.name == "BYE" && @logout_command_tag.nil?
+            state_logout!
+            @sock.close
+            @exception = ByeResponseError.new(resp)
+            connection_closed = true
+          end
+        when ContinuationRequest
+          @continuation_request_arrival.signal
+        end
+        state_unselected! if resp in {data: {code: {name: "CLOSED"}}}
+        @response_handlers.each do |handler|
+          handler.call(resp)
+        end
+      rescue Exception => e
+        @exception = e
+        @tagged_response_arrival.broadcast
+        @continuation_request_arrival.broadcast
+      ensure
+        @exception = nil unless connection_closed
+      end
+      !connection_closed
+    end
+
     # store name => [..., data]
     def record_untagged_response(resp)
       @responses[resp.name] << resp.data
@@ -3629,18 +3681,17 @@ module Net
     end
 
     def send_command(cmd, *args, &block)
+      args.each do validate_data _1 end
       synchronize do
-        args.each do |i|
-          validate_data(i)
-        end
         tag = generate_tag
+        command = Command[tag:, name: cmd]
         put_string(tag + " " + cmd)
         args.each do |i|
           put_string(" ")
           send_data(i, tag)
         end
         @logout_command_tag = tag if cmd == "LOGOUT"
-        guard_against_tagged_response_skipping_handler!(tag, cmd)
+        finish_sending_command(command)
         add_response_handler(&block) if block
         begin
           put_string(CRLF)
@@ -3648,20 +3699,78 @@ module Net
         ensure
           remove_response_handler(block) if block
         end
+      rescue InvalidResponseError
+        disconnect
+        raise
+      end
+    end
+
+    # NOTE: This must be synchronized with sending the command's final CRLF and
+    # adding any command-related response handlers.
+    def finish_sending_command(command)
+      if (response = @tagged_responses[command.tag])&.name&.casecmp?("OK")
+        raise InvalidTaggedResponseError.new(:incomplete, command:, response:)
       end
-    rescue InvalidResponseError
-      disconnect
-      raise
     end
 
-    def guard_against_tagged_response_skipping_handler!(tag, cmd)
-      return unless (resp = @tagged_responses[tag])&.name&.upcase == "OK"
-      raise InvalidResponseError, format(
-        "Received tagged 'OK' to incomplete %s command (tag=%s).  " \
-        "This could indicate a malicious server, a man-in-the-middle, or " \
-        "client-side command injection.  Disconnecting.",
-        cmd, tag
-      )
+    def get_tagged_response(tag, cmd, timeout = nil)
+      if timeout
+        deadline = Time.now + timeout
+      end
+      until @tagged_responses.key?(tag)
+        reraise @exception
+        if timeout
+          timeout = deadline - Time.now
+          if timeout <= 0
+            return nil
+          end
+        end
+        @tagged_response_arrival.wait(timeout)
+      end
+      resp = @tagged_responses.delete(tag)
+      case resp.name
+      when /\A(?:OK)\z/ni
+        return resp
+      when /\A(?:NO)\z/ni
+        raise NoResponseError, resp
+      when /\A(?:BAD)\z/ni
+        raise BadResponseError, resp
+      else
+        disconnect
+        raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw_data.chomp]
+      end
+    end
+
+    # Raises a copy of +exception+ with an updated +backtrace+ and +cause+, or
+    # returns +nil+ when +exception+ is falsey.
+    #
+    # +backtrace+ is set to reflect the current caller.
+    #
+    # +cause+ is set to the original exception, _if_ the original has its own
+    # backtrace or cause.  Otherwise, the original was never raised and the
+    # default cause is used.
+    #
+    # This is meant for exceptions that may have been created by another thread.
+    # Raising them directly gives a misleading backtrace, making it hard to
+    # discover where the errors originate.  Although it is sometimes more
+    # appropriate to raise a wrapping exception, that changes the API and forces
+    # updates to users' `rescue` pattern matching.
+    def reraise(exception)
+      return unless exception
+      copy = exception.dup
+      # NOTE: set_backtrace(caller_locations) doesn't work for CRuby <= 3.3.
+      #   and set_backtrace(nil) doesn't work for TruffleRuby 34.0.0:
+      #   https://github.com/truffleruby/truffleruby/issues/4296
+      if RUBY_ENGINE == "truffleruby"
+        copy.set_backtrace caller_locations
+      else
+        copy.set_backtrace nil
+      end
+      if exception.cause || exception.backtrace
+        raise copy, cause: exception
+      else
+        raise copy
+      end
     end
 
     def generate_tag

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.5
 platform: ruby
 authors:
 - Shugo Maeda
@@ -48,6 +48,7 @@ extra_rdoc_files: []
 files:
 - ".document"
 - ".rdoc_options"
+- ".simplecov"
 - BSDL
 - COPYING
 - Gemfile
@@ -131,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []