net-imap 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9a3148dcf057ea22dbb67a976576ca59060038a8352fc1a71f3ec4cd928289b
-  data.tar.gz: 38e9bbc72d9d90bad28b24f47305d6376c6b17e41233af747bfd3cae27cdfc2e
+  metadata.gz: b90ea893e6f831943d2d0412ff068c7a6603ce3bf723900ea7401a9e045f724b
+  data.tar.gz: '087c861278ce56a7369780aa27d77e56ed6d94907a4116a3a4fd9707f327d57a'
 SHA512:
-  metadata.gz: f5f9f4ade6c25741a402ea78c81928ab455c9b8c6bff5998ae884d567257cb823a16195aa148abc7d9215aa9d0bdce3632904e0f921f061174b04ccdfd4abf9c
-  data.tar.gz: 683fe61b95035387e6f651565174f6499a0f68e712287e904318f05e23fc24f195035a4c29eaeedbeb42a24401e7f2884f8e75af359d623daf098da402f8aaea
+  metadata.gz: 5fa157a8887d5ca2b97b75756b5414d5973667299ae3dbdb340b432eae05cfdb2994969ea2dab68b595f2eae66bd50d19fb814196fb991af1bfc285dfa5b3d6f
+  data.tar.gz: 7b173943ff66f97b5b22795752a34f7338228e6ef5a4dca43b293f5e3153f90d34b7039fd24c76399b1f460e77ffe422dd3691466b0952e3631f2406bab70854

data/.github/workflows/pages.yml

@@ -27,7 +27,7 @@ jobs:
           bundler-cache: true
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v4
       - name: Build with RDoc
         run: bundle exec rake rdoc
       - name: Upload artifact
@@ -43,4 +43,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v3

data/lib/net/imap/response_data.rb

@@ -3,6 +3,7 @@
 module Net
   class IMAP < Protocol
     autoload :FetchData,        "#{__dir__}/fetch_data"
+    autoload :SearchResult,     "#{__dir__}/search_result"
     autoload :SequenceSet,      "#{__dir__}/sequence_set"
 
     # Net::IMAP::ContinuationRequest represents command continuation requests.
@@ -205,6 +206,7 @@ module Net
     # defines them.  When unknown response code data is encountered, #data
     # will return an unparsed string.
     #
+    # ==== +IMAP4rev1+ Response Codes
     # See [IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501]] {§7.1, "Server
     # Responses - Status
     # Responses"}[https://www.rfc-editor.org/rfc/rfc3501#section-7.1] for full
@@ -228,13 +230,32 @@ module Net
     #   {§2.3.1.1, "Unique Identifier (UID) Message
     #   Attribute}[https://www.rfc-editor.org/rfc/rfc3501#section-2.3.1.1].
     # * +UIDVALIDITY+, #data is an Integer, the UID validity value of the
-    #   mailbox  See [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501]],
+    #   mailbox.  See [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501]],
     #   {§2.3.1.1, "Unique Identifier (UID) Message
     #   Attribute}[https://www.rfc-editor.org/rfc/rfc3501#section-2.3.1.1].
     # * +UNSEEN+, #data is an Integer, the number of messages which do not have
     #   the <tt>\Seen</tt> flag set.
-    #
-    # See RFC5530[https://www.rfc-editor.org/rfc/rfc5530], "IMAP Response
+    #   <em>DEPRECATED by IMAP4rev2.</em>
+    #
+    # ==== +BINARY+ extension
+    # See {[RFC3516]}[https://www.rfc-editor.org/rfc/rfc3516].
+    # * +UNKNOWN-CTE+, with a tagged +NO+ response, when the server does not
+    #   known how to decode a CTE (content-transfer-encoding).  #data is +nil+.
+    #   See IMAP#fetch.
+    #
+    # ==== +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.
+    # * +UIDNOTSTICKY+, #data is +nil+.  See IMAP#select.
+    #
+    # ==== +SEARCHRES+ extension
+    # See {[RFC5182]}[https://www.rfc-editor.org/rfc/rfc5182].
+    # * +NOTSAVED+, with a tagged +NO+ response, when the search result variable
+    #   is not saved.  #data is +nil+.
+    #
+    # ==== +RFC5530+ Response Codes
+    # See {[RFC5530]}[https://www.rfc-editor.org/rfc/rfc5530], "IMAP Response
     # Codes" for the definition of the following response codes, which are all
     # machine-readable annotations for the human-readable ResponseText#text, and
     # have +nil+ #data of their own:
@@ -256,9 +277,34 @@ module Net
     # * +ALREADYEXISTS+
     # * +NONEXISTENT+
     #
-    # Other supported \IMAP extension response codes:
-    # * +OBJECTID+ {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-7]
-    #   * +MAILBOXID+, #data will be a string
+    # ==== +QRESYNC+ extension
+    # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+    # * +CLOSED+, returned when the currently selected mailbox is closed
+    #   implicity by selecting or examining another mailbox.  #data is +nil+.
+    #
+    # ==== +IMAP4rev2+ Response Codes
+    # See {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051] {§7.1, "Server
+    # Responses - Status
+    # Responses"}[https://www.rfc-editor.org/rfc/rfc9051#section-7.1] for full
+    # descriptions of IMAP4rev2 response codes.  IMAP4rev2 includes all of the
+    # response codes listed above (except "UNSEEN") and adds the following:
+    # * +HASCHILDREN+, with a tagged +NO+ response, when a mailbox delete failed
+    #   because the server doesn't allow deletion of mailboxes with children.
+    #   #data is +nil+.
+    #
+    # ==== +CONDSTORE+ extension
+    # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+    # * +NOMODSEQ+, when selecting a mailbox that does not support
+    #   mod-sequences.  #data is +nil+.  See IMAP#select.
+    # * +HIGHESTMODSEQ+, #data is an Integer, the highest mod-sequence value of
+    #   all messages in the mailbox.  See IMAP#select.
+    # * +MODIFIED+, #data is a SequenceSet, the messages that have been modified
+    #   since the +UNCHANGEDSINCE+ mod-sequence given to +STORE+ or <tt>UID
+    #   STORE</tt>.
+    #
+    # ==== +OBJECTID+ extension
+    # See {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
+    # * +MAILBOXID+, #data is a string
     #
     class ResponseCode < Struct.new(:name, :data)
       ##
@@ -728,6 +774,19 @@ module Net
       #
       # An array of Net::IMAP::ThreadMember objects for mail items that are
       # children of this in the thread.
+
+      # Returns a SequenceSet containing #seqno and all #children's seqno,
+      # recursively.
+      def to_sequence_set
+        SequenceSet.new all_seqnos
+      end
+
+      protected
+
+      def all_seqnos(node = self)
+        [node.seqno].concat node.children.flat_map { _1.all_seqnos }
+      end
+
     end
 
     # Net::IMAP::BodyStructure is included by all of the structs that can be

data/lib/net/imap/response_parser.rb

@@ -231,6 +231,10 @@ module Net
         FLAG_PERM_LIST    = /\G\((#{FLAG_PERM}(?:#{SP}#{FLAG_PERM})*|)\)/ni
         MBX_LIST_FLAGS    = /\G  (#{MBX_FLAG }(?:#{SP}#{MBX_FLAG })*)   /nix
 
+        # Gmail allows SP and "]" in flags.......
+        QUIRKY_FLAG       = Regexp.union(/\\?#{ASTRING_CHARS}/n, "\\*")
+        QUIRKY_FLAGS_LIST = /\G\((   [^)]*   )\)/nx
+
         # RFC3501:
         #   QUOTED-CHAR   = <any TEXT-CHAR except quoted-specials> /
         #                   "\" quoted-specials
@@ -464,7 +468,7 @@ module Net
       def sequence_set
         str = combine_adjacent(*SEQUENCE_SET_TOKENS)
         if Patterns::SEQUENCE_SET_STR.match?(str)
-          SequenceSet.new(str)
+          SequenceSet[str]
         else
           parse_error("unexpected atom %p, expected sequence-set", str)
         end
@@ -978,7 +982,7 @@ module Net
       #   env-bcc         = "(" 1*address ")" / nil
       def nlist__address
         return if NIL?
-        lpar; list = [address]; list << address until rpar?
+        lpar; list = [address]; list << address until (quirky_SP?; rpar?)
         list
       end
 
@@ -989,6 +993,12 @@ module Net
       alias env_cc       nlist__address
       alias env_bcc      nlist__address
 
+      # Used when servers erroneously send an extra SP.
+      #
+      # As of 2023-11-28, Outlook.com (still) sends SP
+      #   between +address+ in <tt>env-*</tt> lists.
+      alias quirky_SP? SP?
+
       #   date-time       = DQUOTE date-day-fixed "-" date-month "-" date-year
       #                     SP time SP zone DQUOTE
       alias date_time quoted
@@ -1360,7 +1370,7 @@ module Net
         MailboxList.new(attr, delim, name)
       end
 
-      def getquota_response
+      def quota_response
         # If quota never established, get back
         # `NO Quota root does not exist'.
         # If quota removed, get `()' after the
@@ -1393,7 +1403,7 @@ module Net
         end
       end
 
-      def getquotaroot_response
+      def quotaroot_response
         # Similar to getquota, but only admin can use getquota.
         token = match(T_ATOM)
         name = token.value.upcase
@@ -1452,34 +1462,16 @@ module Net
       #   mailbox-data        = obsolete-search-response / ...
       #   obsolete-search-response = "SEARCH" *(SP nz-number)
       def mailbox_data__search
-        token = match(T_ATOM)
-        name = token.value.upcase
-        token = lookahead
-        if token.symbol == T_SPACE
-          shift_token
-          data = []
-          while true
-            token = lookahead
-            case token.symbol
-            when T_CRLF
-              break
-            when T_SPACE
-              shift_token
-            when T_NUMBER
-              data.push(number)
-            when T_LPAR
-              # TODO: include the MODSEQ value in a response
-              shift_token
-              match(T_ATOM)
-              match(T_SPACE)
-              match(T_NUMBER)
-              match(T_RPAR)
-            end
-          end
-        else
-          data = []
+        name = label_in("SEARCH", "SORT")
+        data = []
+        while _ = SP? && nz_number? do data << _ end
+        if lpar?
+          label("MODSEQ"); SP!
+          modseq = mod_sequence_value
+          rpar
         end
-        return UntaggedResponse.new(name, data, @str)
+        data = SearchResult.new(data, modseq: modseq)
+        UntaggedResponse.new(name, data, @str)
       end
       alias sort_data mailbox_data__search
 
@@ -1603,6 +1595,7 @@ module Net
           when "UIDVALIDITY"   then nz_number           # RFC3501, RFC9051
           when "RECENT"        then number              # RFC3501 (obsolete)
           when "SIZE"          then number64            # RFC8483, RFC9051
+          when "HIGHESTMODSEQ" then mod_sequence_valzer # RFC7162
           when "MAILBOXID"     then parens__objectid    # RFC8474
           else
             number? || ExtensionData.new(tagged_ext_val)
@@ -1809,6 +1802,8 @@ module Net
       #   resp-text-code   =/ "HIGHESTMODSEQ" SP mod-sequence-value /
       #                       "NOMODSEQ" /
       #                       "MODIFIED" SP sequence-set
+      # RFC7162 (QRESYNC):
+      #   resp-text-code   =/ "CLOSED"
       #
       # RFC8474: OBJECTID
       #   resp-text-code   =/ "MAILBOXID" SP "(" objectid ")"
@@ -1830,7 +1825,9 @@ module Net
             "EXPUNGEISSUED", "CORRUPTION", "SERVERBUG", "CLIENTBUG", "CANNOT",
             "LIMIT", "OVERQUOTA", "ALREADYEXISTS", "NONEXISTENT", "CLOSED",
             "NOTSAVED", "UIDNOTSTICKY", "UNKNOWN-CTE", "HASCHILDREN"
-          when "NOMODSEQ"           # CONDSTORE
+          when "NOMODSEQ"           then nil                       # CONDSTORE
+          when "HIGHESTMODSEQ"      then SP!; mod_sequence_value   # CONDSTORE
+          when "MODIFIED"           then SP!; sequence_set         # CONDSTORE
           when "MAILBOXID"          then SP!; parens__objectid     # RFC8474: OBJECTID
           else
             SP? and text_chars_except_rbra
@@ -1914,22 +1911,35 @@ module Net
 
       # flag-list       = "(" [flag *(SP flag)] ")"
       def flag_list
-        match_re(Patterns::FLAG_LIST, "flag-list")[1]
-          .split(nil)
-          .map! { _1.start_with?("\\") ? _1[1..].capitalize.to_sym : _1 }
+        if (match = accept_re(Patterns::FLAG_LIST))
+          match[1].split(nil)
+            .map! { _1.delete_prefix!("\\") ? _1.capitalize.to_sym : _1 }
+        else
+          quirky__flag_list "flags-list"
+        end
       end
 
       #   "(" [flag-perm *(SP flag-perm)] ")"
       def flag_perm__list
-        match_re(Patterns::FLAG_PERM_LIST, "PERMANENTFLAGS flag-perm list")[1]
-          .split(nil)
-          .map! { _1.start_with?("\\") ? _1[1..].capitalize.to_sym : _1 }
+        if (match = accept_re(Patterns::FLAG_PERM_LIST))
+          match[1].split(nil)
+            .map! { _1.delete_prefix!("\\") ? _1.capitalize.to_sym : _1 }
+        else
+          quirky__flag_list "PERMANENTFLAGS flag-perm list"
+        end
+      end
+
+      def quirky__flag_list(name)
+        match_re(Patterns::QUIRKY_FLAGS_LIST, "quirks mode #{name}")[1]
+          .scan(Patterns::QUIRKY_FLAG)
+          .map! { _1.delete_prefix!("\\") ? _1.capitalize.to_sym : _1 }
       end
 
       # See Patterns::MBX_LIST_FLAGS
       def mbx_list_flags
         match_re(Patterns::MBX_LIST_FLAGS, "mbx-list-flags")[1]
-          .split(nil).map! { _1[1..].capitalize.to_sym }
+          .split(nil)
+          .map! { _1.delete_prefix!("\\"); _1.capitalize.to_sym }
       end
 
       # See https://developers.google.com/gmail/imap/imap-extensions
@@ -1962,6 +1972,10 @@ module Net
       #                        ;; Per-message mod-sequence.
       alias permsg_modsequence mod_sequence_value
 
+      # RFC7162:
+      # mod-sequence-valzer = "0" / mod-sequence-value
+      alias mod_sequence_valzer number64
+
       def parens__modseq; lpar; _ = permsg_modsequence; rpar; _ end
 
       # RFC8474:

data/lib/net/imap/search_result.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    # An array of sequence numbers returned by Net::IMAP#search, or unique
+    # identifiers returned by Net::IMAP#uid_search.
+    #
+    # For backward compatibility, SearchResult inherits from Array.
+    class SearchResult < Array
+
+      # Returns a frozen SearchResult populated with the given +seq_nums+.
+      #
+      #     Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      #     # => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      def self.[](*seq_nums, modseq: nil)
+        new(seq_nums, modseq: modseq)
+      end
+
+      # A modification sequence number, as described by the +CONDSTORE+
+      # extension in {[RFC7162
+      # §3.1.6]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.6].
+      attr_reader :modseq
+
+      # Returns a frozen SearchResult populated with the given +seq_nums+.
+      #
+      #     Net::IMAP::SearchResult.new([1, 3, 5], modseq: 9)
+      #     # => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
+      def initialize(seq_nums, modseq: nil)
+        super(seq_nums.to_ary.map { Integer _1 })
+        @modseq = Integer modseq if modseq
+        freeze
+      end
+
+      # Returns a frozen copy of +other+.
+      def initialize_copy(other); super; freeze end
+
+      # Returns whether +other+ is a SearchResult with the same values and the
+      # same #modseq.  The order of numbers is irrelevant.
+      #
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[123, 456, modseq: 789]
+      #     # => true
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[456, 123, modseq: 789]
+      #     # => true
+      #
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[987, 654, modseq: 789]
+      #     # => false
+      #     Net::IMAP::SearchResult[123, 456, modseq: 789] ==
+      #       Net::IMAP::SearchResult[1, 2, 3, modseq: 9999]
+      #     # => false
+      #
+      # SearchResult can be compared directly with Array, if #modseq is nil and
+      # the array is sorted.
+      #
+      #     Net::IMAP::SearchResult[9, 8, 6, 4, 1] == [1, 4, 6, 8, 9] # => true
+      #     Net::IMAP::SearchResult[3, 5, 7, modseq: 99] == [3, 5, 7] # => false
+      #
+      # Note that Array#== does require matching order and ignores #modseq.
+      #
+      #     [9, 8, 6, 4, 1] == Net::IMAP::SearchResult[1, 4, 6, 8, 9] # => false
+      #     [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)) &&
+          size == other.size &&
+          sort == other.sort
+      end
+
+      # Hash equality.  Unlike #==, order will be taken into account.
+      def hash
+        return super if modseq.nil?
+        [super, self.class, modseq].hash
+      end
+
+      # Hash equality.  Unlike #==, order will be taken into account.
+      def eql?(other)
+        return super if modseq.nil?
+        self.class == other.class && hash == other.hash
+      end
+
+      # Returns a string that represents the SearchResult.
+      #
+      #    Net::IMAP::SearchResult[123, 456, 789].inspect
+      #    # => "[123, 456, 789]"
+      #
+      #    Net::IMAP::SearchResult[543, 210, 678, modseq: 2048].inspect
+      #    # => "Net::IMAP::SearchResult[543, 210, 678, modseq: 2048]"
+      #
+      def inspect
+        return super if modseq.nil?
+        "%s[%s, modseq: %p]" % [self.class, join(", "), modseq]
+      end
+
+      # Returns a string that follows the formal \IMAP syntax.
+      #
+      #    data = Net::IMAP::SearchResult[2, 8, 32, 128, 256, 512]
+      #    data.to_s           # => "* SEARCH 2 8 32 128 256 512"
+      #    data.to_s("SEARCH") # => "* SEARCH 2 8 32 128 256 512"
+      #    data.to_s("SORT")   # => "* SORT 2 8 32 128 256 512"
+      #    data.to_s(nil)      # => "2 8 32 128 256 512"
+      #
+      #    data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048].to_s
+      #    data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s           # => "1 3 16 1024 (MODSEQ 2048)"
+      #
+      def to_s(type = "SEARCH")
+        str = +""
+        str << "* %s " % [type.to_str] unless type.nil?
+        str << join(" ")
+        str << " (MODSEQ %d)" % [modseq] if modseq
+        -str
+      end
+
+      # Converts the SearchResult into a SequenceSet.
+      #
+      #     Net::IMAP::SearchResult[9, 1, 2, 4, 10, 12, 3, modseq: 123_456]
+      #       .to_sequence_set
+      #     # => Net::IMAP::SequenceSet["1:4,9:10,12"]
+      def to_sequence_set; SequenceSet[*self] end
+
+      def pretty_print(pp)
+        return super if modseq.nil?
+        pp.text self.class.name + "["
+        pp.group_sub do
+          pp.nest(2) do
+            pp.breakable ""
+            each do |num|
+              pp.pp num
+              pp.text ","
+              pp.fill_breakable
+            end
+            pp.breakable ""
+            pp.text "modseq: "
+            pp.pp modseq
+          end
+          pp.breakable ""
+          pp.text "]"
+        end
+      end
+
+    end
+
+  end
+end