net-imap 0.5.10 → 0.6.3

data/lib/net/imap/errors.rb

@@ -51,7 +51,159 @@ module Net
     end
 
     # Error raised when a response from the server is non-parsable.
+    #
+    # NOTE: Parser attributes are provided for debugging and inspection only.
+    # Their names and semantics may change incompatibly in any release.
     class ResponseParseError < Error
+      # returns "" for all highlights
+      ESC_NO_HL = Hash.new("").freeze
+      private_constant :ESC_NO_HL
+
+      # Translates hash[:"/foo"] to hash[:reset] when hash.key?(:foo), else ""
+      #
+      # TODO: DRY this up with Config::AttrTypeCoercion.safe
+      if defined?(::Ractor.shareable_proc)
+        default_highlight = Ractor.shareable_proc {|hash, key|
+          %r{\A/(.+)} =~ key && hash.key?($1.to_sym) ? hash[:reset] : ""
+        }
+      else
+        default_highlight = nil.instance_eval { Proc.new {|hash, key|
+          %r{\A/(.+)} =~ key && hash.key?($1.to_sym) ? hash[:reset] : ""
+        } }
+        ::Ractor.make_shareable(default_highlight) if defined?(::Ractor)
+      end
+
+      # ANSI highlights, but no colors
+      ESC_NO_COLOR = Hash.new(&default_highlight).update(
+        reset: "\e[m",
+        val:   "\e[1m",   # bold
+        alt:   "\e[1;4m", # bold and underlined
+        sym:   "\e[1m",   # bold
+        label: "\e[1m",   # bold
+      ).freeze
+      private_constant :ESC_NO_COLOR
+
+      # ANSI highlights, with color
+      ESC_COLORS = Hash.new(&default_highlight).update(
+        reset: "\e[m",
+        key:   "\e[95m",      # bright magenta
+        idx:   "\e[34m",      # blue
+        val:   "\e[36;40m",   # cyan on black (to ensure contrast)
+        alt:   "\e[1;33;40m", # bold; yellow on black
+        sym:   "\e[33;40m",   # yellow on black
+        label: "\e[1m",       # bold
+        nil:   "\e[35m",      # magenta
+      ).freeze
+      private_constant :ESC_COLORS
+
+      # Net::IMAP::ResponseParser, unless a custom parser produced the error.
+      attr_reader :parser_class
+
+      # The full raw response string which was being parsed.
+      attr_reader :string
+
+      # The parser's byte position in #string when the error was raised.
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :pos
+
+      # The parser's lex state
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :lex_state
+
+      # The last lexed token
+      #
+      # May be +nil+ when the parser has accepted the last token and peeked at
+      # the next byte without generating a token.
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :token
+
+      def initialize(message = "unspecified parse error",
+                     parser_class: Net::IMAP::ResponseParser,
+                     parser_state: nil,
+                     string:    parser_state&.at(0), # see ParserUtils#parser_state
+                     lex_state: parser_state&.at(1), # see ParserUtils#parser_state
+                     pos:       parser_state&.at(2), # see ParserUtils#parser_state
+                     token:     parser_state&.at(3)) # see ParserUtils#parser_state
+        @parser_class = parser_class
+        @string    = string
+        @pos       = pos
+        @lex_state = lex_state
+        @token     = token
+        super(message)
+      end
+
+      # When +parser_state+ is true, debug info about the parser state is
+      # included.  Defaults to the value of Net::IMAP.debug.
+      #
+      # When +parser_backtrace+ is true, a simplified backtrace is included,
+      # containing only frames for methods in 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.
+      #
+      # When +highlight+ is not explicitly set, highlights may be enabled
+      # automatically, based on +TERM+ and +FORCE_COLOR+ environment variables.
+      #
+      # By default, +highlight+ uses colors from the basic ANSI palette.  When
+      # +highlight_no_color+ is true or the +NO_COLOR+ environment variable is
+      # not empty, only monochromatic highlights are used: bold, underline, etc.
+      def detailed_message(parser_state: Net::IMAP.debug,
+                           parser_backtrace: false,
+                           highlight: default_highlight_from_env,
+                           highlight_no_color: (ENV["NO_COLOR"] || "") != "",
+                           **)
+        return super unless parser_state || parser_backtrace
+        msg = super.dup
+        esc = !highlight ? ESC_NO_HL : highlight_no_color ? ESC_NO_COLOR : ESC_COLORS
+        hl  = ->str { str % esc }
+        val = ->str, val { hl[val.nil? ? "%{nil}%%p%{/nil}" : str] % val }
+        if parser_state && (string || pos || lex_state || token)
+          msg << hl["\n  %{key}processed %{/key}: "] << val["%{val}%%p%{/val}", processed_string]
+          msg << hl["\n  %{key}remaining %{/key}: "] << val["%{alt}%%p%{/alt}", remaining_string]
+          msg << hl["\n  %{key}pos       %{/key}: "] << val["%{val}%%p%{/val}", pos]
+          msg << hl["\n  %{key}lex_state %{/key}: "] << val["%{sym}%%p%{/sym}", lex_state]
+          msg << hl["\n  %{key}token     %{/key}: "] << val[
+            "%{sym}%%<symbol>p%{/sym} => %{val}%%<value>p%{/val}", token&.to_h
+          ]
+        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
+            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
+            ]
+          end
+        end
+        msg
+      rescue => error
+        msg ||= super.dup
+        msg << "\n  BUG in %s#%s: %s" % [self.class, __method__,
+                                         error.detailed_message]
+        msg
+      end
+
+      def processed_string = string && pos && string[...pos]
+      def remaining_string = string && pos && string[pos..]
+
+      private
+
+      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/esearch_result.rb

@@ -25,6 +25,12 @@ module Net
     # Some search extensions may result in the server sending ESearchResult
     # responses after the initiating command has completed.  Use
     # IMAP#add_response_handler to handle these responses.
+    #
+    # ==== Compatibility with SearchResult
+    #
+    # Note that both SearchResult and ESearchResult implement +each+, +to_a+,
+    # and +to_sequence_set+.  These methods can be used regardless of whether
+    # the server returns +SEARCH+ or +ESEARCH+ data (or no data).
     class ESearchResult < Data.define(:tag, :uid, :data)
       def initialize(tag: nil, uid: nil, data: nil)
         tag  => String       | nil; tag = -tag if tag
@@ -39,12 +45,49 @@ module Net
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
       # When both #all and #partial are +nil+, either because the server
-      # returned no results or because +ALL+ and +PARTIAL+ were not included in
-      # the IMAP#search +RETURN+ options, #to_a returns an empty array.
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_a returns an empty array.
       #
       # Note that SearchResult also implements +to_a+, so it can be used without
       # checking if the server returned +SEARCH+ or +ESEARCH+ data.
-      def to_a; all&.numbers || partial&.to_a || [] end
+      #
+      # Related: #each, #to_sequence_set, #all, #partial
+      def to_a; to_sequence_set.numbers end
+
+      # :call-seq: to_sequence_set -> SequenceSet or nil
+      #
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_sequence_set+ returns that sequence set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_sequence_set returns
+      # SequenceSet.empty.
+      #
+      # Note that SearchResult also implements +to_sequence_set+, so it can be
+      # used without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #each, #to_a, #all, #partial
+      def to_sequence_set
+        all || partial&.to_sequence_set || SequenceSet.empty
+      end
+
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +each+ yields each integer in the set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because +ALL+ and +PARTIAL+ were not included in
+      # the IMAP#search +RETURN+ options, #each does not yield.
+      #
+      # Note that SearchResult also implements +#each+, so it can be used
+      # without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #to_sequence_set, #to_a, #all, #partial
+      def each(&)
+        return to_enum(__callee__) unless block_given?
+        to_sequence_set.each_number(&)
+        self
+      end
 
       ##
       # attr_reader: tag
@@ -161,6 +204,8 @@ module Net
         #
         # See also: ESearchResult#to_a.
         def to_a; results&.numbers || [] end
+
+        alias to_sequence_set results
       end
 
       # :call-seq: partial -> PartialResult or nil

data/lib/net/imap/response_data.rb

@@ -6,7 +6,6 @@ module Net
     autoload :FetchData,        "#{__dir__}/fetch_data"
     autoload :UIDFetchData,     "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
-    autoload :UIDPlusData,      "#{__dir__}/uidplus_data"
     autoload :AppendUIDData,    "#{__dir__}/uidplus_data"
     autoload :CopyUIDData,      "#{__dir__}/uidplus_data"
     autoload :VanishedData,     "#{__dir__}/vanished_data"
@@ -260,8 +259,8 @@ module Net
     #
     # === +UIDPLUS+ extension
     # See {[RFC4315 §3]}[https://www.rfc-editor.org/rfc/rfc4315#section-3].
-    # * +APPENDUID+, #data is UIDPlusData.  See IMAP#append.
-    # * +COPYUID+, #data is UIDPlusData.  See IMAP#copy.
+    # * +APPENDUID+, #data is AppendUIDData.  See IMAP#append.
+    # * +COPYUID+, #data is CopyUIDData.  See IMAP#copy.
     # * +UIDNOTSTICKY+, #data is +nil+.  See IMAP#select.
     #
     # === +SEARCHRES+ extension

data/lib/net/imap/response_parser/parser_utils.rb

@@ -215,29 +215,20 @@ module Net
           @token = nil
         end
 
-        def parse_error(fmt, *args)
-          msg = format(fmt, *args)
-          if config.debug?
-            local_path = File.dirname(__dir__)
-            tok = @token ? "%s: %p" % [@token.symbol, @token.value] : "nil"
-            warn "%s %s: %s"        % [self.class, __method__, msg]
-            warn "  tokenized : %s" % [@str[...@pos].dump]
-            warn "  remaining : %s" % [@str[@pos..].dump]
-            warn "  @lex_state: %s" % [@lex_state]
-            warn "  @pos      : %d" % [@pos]
-            warn "  @token    : %s" % [tok]
-            caller_locations(1..20).each_with_index do |cloc, idx|
-              next unless cloc.path&.start_with?(local_path)
-              warn "  caller[%2d]: %-30s (%s:%d)" % [
-                idx,
-                cloc.base_label,
-                File.basename(cloc.path, ".rb"),
-                cloc.lineno
-              ]
-            end
-          end
-          raise ResponseParseError, msg
-        end
+        def parse_error(fmt, *args) = raise exception format(fmt, *args)
+
+        def exception(message) = ResponseParseError.new(
+          message, parser_state:, parser_class: self.class
+        )
+
+        # This can be used to backtrack after a parse error, and re-attempt to
+        # parse using a fallback.
+        #
+        # NOTE: Reckless backtracking could lead to O(n²) situations, so this
+        # should very rarely be used.  Ideally, fallbacks should not backtrack.
+        def restore_state(state) = (@lex_state, @pos, @token = state)
+        def current_state        = [@lex_state, @pos, @token]
+        def parser_state         = [@str, *current_state]
 
       end
     end

data/lib/net/imap/response_parser.rb

@@ -38,6 +38,11 @@ module Net
         @lex_state = EXPR_BEG
         @token = nil
         return response
+      rescue ResponseParseError => error
+        if config.debug?
+          warn error.detailed_message(parser_state: true, parser_backtrace: true)
+        end
+        raise
       end
 
       private
@@ -1883,12 +1888,17 @@ module Net
       # We leniently re-interpret this as
       #   resp-text       = ["[" resp-text-code "]" [SP [text]] / [text]
       def resp_text
-        if lbra?
-          code = resp_text_code; rbra
-          ResponseText.new(code, SP? && text? || "")
-        else
-          ResponseText.new(nil, text? || "")
+        begin
+          state = current_state
+          if lbra?
+            code = resp_text_code; rbra
+            return ResponseText.new(code, SP? && text? || "")
+          end
+        rescue ResponseParseError => error
+          raise if /\buid-set\b/i.match? error.message
+          restore_state state
         end
+        ResponseText.new(nil, text? || "")
       end
 
       # RFC3501 (See https://www.rfc-editor.org/errata/rfc3501):
@@ -2017,24 +2027,24 @@ module Net
         CopyUID(validity, src_uids, dst_uids)
       end
 
-      def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
-      def CopyUID(...)   DeprecatedUIDPlus(...) || CopyUIDData.new(...)   end
+      PARSER_PATH = File.expand_path(__FILE__).delete_suffix(".rb")
 
       # TODO: remove this code in the v0.6.0 release
       def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
         return unless config.parser_use_deprecated_uidplus_data
-        compact_uid_sets = [src_uids, dst_uids].compact
-        count = compact_uid_sets.map { _1.count_with_duplicates }.max
-        max   = config.parser_max_deprecated_uidplus_data_size
-        if count <= max
-          src_uids &&= src_uids.each_ordered_number.to_a
-          dst_uids   = dst_uids.each_ordered_number.to_a
-          UIDPlusData.new(validity, src_uids, dst_uids)
-        elsif config.parser_use_deprecated_uidplus_data != :up_to_max_size
-          parse_error("uid-set is too large: %d > %d", count, max)
-        end
+        uplevel = caller_locations
+          .find_index { !_1.path.start_with?(PARSER_PATH) }
+          &.succ
+        warn("#{Config}#parser_use_deprecated_uidplus_data is ignored " \
+             "since v0.6.0.  Disable this warning by setting " \
+             "config.parser_use_deprecated_uidplus_data = false.",
+             category: :deprecated, uplevel:)
+        nil
       end
 
+      def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
+      def CopyUID(...)   DeprecatedUIDPlus(...) || CopyUIDData.new(...)   end
+
       ADDRESS_REGEXP = /\G
         \( (?: NIL | #{Patterns::QUOTED_rev2} )  # 1: NAME
         \s (?: NIL | #{Patterns::QUOTED_rev2} )  # 2: ROUTE

data/lib/net/imap/search_result.rb

@@ -7,6 +7,12 @@ module Net
     # identifiers returned by Net::IMAP#uid_search.
     #
     # For backward compatibility, SearchResult inherits from Array.
+    #
+    # ==== Compatibility with ESearchResult
+    #
+    # Note that both SearchResult and ESearchResult implement +each+, +to_a+,
+    # and +to_sequence_set+.  These methods can be used regardless of whether
+    # the server returns +SEARCH+ or +ESEARCH+ data (or no data).
     class SearchResult < Array
 
       # Returns a SearchResult populated with the given +seq_nums+.
@@ -60,9 +66,8 @@ module Net
       #     [3, 5, 7] == Net::IMAP::SearchResult[3, 5, 7, modseq: 99] # => true
       #
       def ==(other)
-        (modseq ?
-         other.is_a?(self.class) && modseq == other.modseq :
-         other.is_a?(Array)) &&
+        other.is_a?(Array) &&
+          modseq == (other.modseq if other.respond_to?(:modseq)) &&
           size == other.size &&
           sort == other.sort
       end