net-imap 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49dc46f2744a04f6b151bc033176f2d59dabf04fb1996bba36a87b4b9f0f99b4
-  data.tar.gz: 411eac8fd696e619f0255d37a83b74b19b3290c68533fded627cd689d1afc57a
+  metadata.gz: a871e99f51067e3a509aa5a74fe2c49f4d79496bcec2f21ac50c3c5793d2cdbf
+  data.tar.gz: 302c03e65954f9a118d877f97ea2296f34a7f50c8b1299e3e4f8b589cb620880
 SHA512:
-  metadata.gz: 3049e6a03f6660c6e7c67c82a9fdb8994a2a0ec3777ca66a6e4941b1a08486e452eb17007e5c666e41a52e34c2c54d057e33aecd6a4b5bac9c522d5f20acfb43
-  data.tar.gz: 9c7f8e858614748c65a434900f8b6ddba04b9e31578aa9669987803153c31269888abe6baca8ae42c5ecc00287dab2f494de73ac89cf1fb81d44ebfa65d42c5d
+  metadata.gz: 85d97c9729220265da03588f175fea22bcdd27d40cd06910ad35bc01ed64bd0c27b2769790464712572166761f3e82fc4eb6330fef64f45cceb0b3e1007f7126
+  data.tar.gz: aa18d53b81e57ddfbdde2b8295ca7324f965fa744846fdd756ec4ca1c30e6e72092b106ff454d100f70d1078ee239f2b3e643bd4650606a2fc3b4ab5a2d0cc1f

data/lib/net/imap/command_data.rb

@@ -153,6 +153,38 @@ module Net
       end
     end
 
+    class PartialRange < CommandData # :nodoc:
+      uint32_max = 2**32 - 1
+      POS_RANGE = 1..uint32_max
+      NEG_RANGE = -uint32_max..-1
+      Positive = ->{ (_1 in Range) and POS_RANGE.cover?(_1) }
+      Negative = ->{ (_1 in Range) and NEG_RANGE.cover?(_1) }
+
+      def initialize(data:)
+        min, max = case data
+        in Range
+          data.minmax.map { Integer _1 }
+        in ResponseParser::Patterns::PARTIAL_RANGE
+          data.split(":").map { Integer _1 }.minmax
+        else
+          raise ArgumentError, "invalid partial range input: %p" % [data]
+        end
+        data = min..max
+        unless data in Positive | Negative
+          raise ArgumentError, "invalid partial-range: %p" % [data]
+        end
+        super
+      rescue TypeError, RangeError
+        raise ArgumentError, "expected range min/max to be Integers"
+      end
+
+      def formatted = "%d:%d" % data.minmax
+
+      def send_data(imap, tag)
+        imap.__send__(:put_string, formatted)
+      end
+    end
+
     # *DEPRECATED*.  Replaced by SequenceSet.
     class MessageSet < CommandData # :nodoc:
       def send_data(imap, tag)

data/lib/net/imap/esearch_result.rb

@@ -35,16 +35,16 @@ module Net
 
       # :call-seq: to_a -> Array of integers
       #
-      # When #all contains a SequenceSet of message sequence
+      # When either #all or #partial contains a SequenceSet of message sequence
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
-      # When #all is +nil+, either because the server
-      # returned no results or because +ALL+ was not included in
+      # 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.
       #
       # 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 || [] end
+      def to_a; all&.numbers || partial&.to_a || [] end
 
       ##
       # attr_reader: tag
@@ -135,6 +135,46 @@ module Net
       # and +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.2].
       def modseq;     data.assoc("MODSEQ")&.last     end
 
+      # Returned by ESearchResult#partial.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      class PartialResult < Data.define(:range, :results)
+        def initialize(range:, results:)
+          range   => Range
+          results = SequenceSet[results] unless results.nil?
+          super
+        end
+
+        ##
+        # method: range
+        # :call-seq: range -> range
+
+        ##
+        # method: results
+        # :call-seq: results -> sequence set or nil
+
+        # Converts #results to an array of integers.
+        #
+        # See also: ESearchResult#to_a.
+        def to_a; results&.numbers || [] end
+      end
+
+      # :call-seq: partial -> PartialResult or nil
+      #
+      # A PartialResult containing a subset of the message sequence numbers or
+      # UIDs that satisfy the SEARCH criteria.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      def partial;    data.assoc("PARTIAL")&.last    end
+
     end
   end
 end

data/lib/net/imap/response_parser.rb

@@ -321,6 +321,24 @@ module Net
         SEQUENCE_SET      = /#{SEQUENCE_SET_ITEM}(?:,#{SEQUENCE_SET_ITEM})*/n
         SEQUENCE_SET_STR  = /\A#{SEQUENCE_SET}\z/n
 
+        # partial-range-first = nz-number ":" nz-number
+        #     ;; Request to search from oldest (lowest UIDs) to
+        #     ;; more recent messages.
+        #     ;; A range 500:400 is the same as 400:500.
+        #     ;; This is similar to <seq-range> from [RFC3501]
+        #     ;; but cannot contain "*".
+        PARTIAL_RANGE_FIRST = /\A(#{NZ_NUMBER}):(#{NZ_NUMBER})\z/n
+
+        # partial-range-last  = MINUS nz-number ":" MINUS nz-number
+        #     ;; Request to search from newest (highest UIDs) to
+        #     ;; oldest messages.
+        #     ;; A range -500:-400 is the same as -400:-500.
+        PARTIAL_RANGE_LAST  = /\A(-#{NZ_NUMBER}):(-#{NZ_NUMBER})\z/n
+
+        # partial-range     = partial-range-first / partial-range-last
+        PARTIAL_RANGE       = Regexp.union(PARTIAL_RANGE_FIRST,
+                                           PARTIAL_RANGE_LAST)
+
         # RFC3501:
         #   literal          = "{" number "}" CRLF *CHAR8
         #                        ; Number represents the number of CHAR8s
@@ -1517,6 +1535,9 @@ module Net
       # From RFC4731 (ESEARCH):
       #   search-return-data    =/ "MODSEQ" SP mod-sequence-value
       #
+      # From RFC9394 (PARTIAL):
+      #   search-return-data  =/ ret-data-partial
+      #
       def search_return_data
         label = search_modifier_name; SP!
         value =
@@ -1526,11 +1547,41 @@ module Net
           when "ALL"        then sequence_set
           when "COUNT"      then number
           when "MODSEQ"     then mod_sequence_value         # RFC7162: CONDSTORE
+          when "PARTIAL"    then ret_data_partial__value    # RFC9394: PARTIAL
           else search_return_value
           end
         [label, value]
       end
 
+      # From RFC5267 (CONTEXT=SEARCH, CONTEXT=SORT) and RFC9394 (PARTIAL):
+      #   ret-data-partial    = "PARTIAL"
+      #                         SP "(" partial-range SP partial-results ")"
+      def ret_data_partial__value
+        lpar
+        range   = partial_range;   SP!
+        results = partial_results
+        rpar
+        ESearchResult::PartialResult.new(range, results)
+      end
+
+      # partial-range       = partial-range-first / partial-range-last
+      # tagged-ext-simple   =/ partial-range-last
+      def partial_range
+        case (str = atom)
+        when Patterns::PARTIAL_RANGE_FIRST, Patterns::PARTIAL_RANGE_LAST
+          min, max = [Integer($1), Integer($2)].minmax
+          min..max
+        else
+          parse_error("unexpected atom %p, expected partial-range", str)
+        end
+      end
+
+      # partial-results     = sequence-set / "NIL"
+      #     ;; <sequence-set> from [RFC3501].
+      #     ;; NIL indicates that no results correspond to
+      #     ;; the requested range.
+      def partial_results; NIL? ? nil : sequence_set end
+
       # search-modifier-name = tagged-ext-label
       alias search_modifier_name tagged_ext_label
 

data/lib/net/imap.rb

@@ -534,6 +534,11 @@ module Net
   #   See FetchData#emailid and FetchData#emailid.
   # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
+  # ==== RFC9394: +PARTIAL+
+  # - Updates #search, #uid_search with the +PARTIAL+ return option which adds
+  #   ESearchResult#partial return data.
+  # - Updates #uid_fetch with the +partial+ modifier.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -701,6 +706,11 @@ module Net
   #   Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
   #   RFC 8474, DOI 10.17487/RFC8474, September 2018,
   #   <https://www.rfc-editor.org/info/rfc8474>.
+  # [PARTIAL[https://www.rfc-editor.org/info/rfc9394]]::
+  #   Melnikov, A., Achuthan, A., Nagulakonda, V., and L. Alves,
+  #   "IMAP PARTIAL Extension for Paged SEARCH and FETCH", RFC 9394,
+  #   DOI 10.17487/RFC9394, June 2023,
+  #   <https://www.rfc-editor.org/info/rfc9394>.
   #
   # === IANA registries
   # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
@@ -723,7 +733,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.5.3"
+    VERSION = "0.5.4"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1971,8 +1981,9 @@ module Net
     # the server to return an ESearchResult instead of a SearchResult, but some
     # servers disobey this requirement.  <em>Requires an extended search
     # capability, such as +ESEARCH+ or +IMAP4rev2+.</em>
-    # See {"Argument translation"}[rdoc-ref:#search@Argument+translation]
-    # and {"Return options"}[rdoc-ref:#search@Return+options], below.
+    # See {"Argument translation"}[rdoc-ref:#search@Argument+translation] and
+    # {"Supported return options"}[rdoc-ref:#search@Supported+return+options],
+    # below.
     #
     # +charset+ is the name of the {registered character
     # set}[https://www.iana.org/assignments/character-sets/character-sets.xhtml]
@@ -2082,33 +2093,58 @@ module Net
     #   <em>*WARNING:* This is vulnerable to injection attacks when external
     #   inputs are used.</em>
     #
-    # ==== Return options
+    # ==== Supported return options
     #
     # For full definitions of the standard return options and return data, see
     # the relevant RFCs.
     #
-    # ===== +ESEARCH+ or +IMAP4rev2+
-    #
-    # The following return options require either +ESEARCH+ or +IMAP4rev2+.
-    # See [{RFC4731 §3.1}[https://rfc-editor.org/rfc/rfc4731#section-3.1]] or
-    # [{IMAP4rev2 §6.4.4}[https://www.rfc-editor.org/rfc/rfc9051.html#section-6.4.4]].
-    #
     # [+ALL+]
     #    Returns ESearchResult#all with a SequenceSet of all matching sequence
     #    numbers or UIDs.  This is the default, when return options are empty.
     #
     #    For compatibility with SearchResult, ESearchResult#to_a returns an
     #    Array of message sequence numbers or UIDs.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
     # [+COUNT+]
     #    Returns ESearchResult#count with the number of matching messages.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
     # [+MAX+]
     #    Returns ESearchResult#max with the highest matching sequence number or
     #    UID.
+    #
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
     # [+MIN+]
     #    Returns ESearchResult#min with the lowest matching sequence number or
     #    UID.
     #
-    # ===== +CONDSTORE+
+    #    <em>Requires either the +ESEARCH+ or +IMAP4rev2+ capabability.</em>
+    #    {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731]
+    #    {[RFC9051]}[https://rfc-editor.org/rfc/rfc9051]
+    #
+    # [+PARTIAL+ _range_]
+    #    Returns ESearchResult#partial with a SequenceSet of a subset of
+    #    matching sequence numbers or UIDs, as selected by _range_.  As with
+    #    sequence numbers, the first result is +1+: <tt>1..500</tt> selects the
+    #    first 500 search results (in mailbox order), <tt>501..1000</tt> the
+    #    second 500, and so on.  _range_ may also be negative: <tt>-500..-1</tt>
+    #    selects the last 500 search results.
+    #
+    #    <em>Requires either the <tt>CONTEXT=SEARCH</tt> or +PARTIAL+ capabability.</em>
+    #    {[RFC5267]}[https://rfc-editor.org/rfc/rfc5267]
+    #    {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394]
+    #
+    # ===== +MODSEQ+ return data
     #
     # ESearchResult#modseq return data does not have a corresponding return
     # option.  Instead, it is returned if the +MODSEQ+ search key is used or
@@ -2120,8 +2156,8 @@ module Net
     #
     # {RFC4466 §2.6}[https://www.rfc-editor.org/rfc/rfc4466.html#section-2.6]
     # defines standard syntax for search extensions.  Net::IMAP allows sending
-    # unknown search return options and will parse unknown search extensions'
-    # return values into ExtensionData.  Please note that this is an
+    # unsupported search return options and will parse unsupported search
+    # extensions' return values into ExtensionData.  Please note that this is an
     # intentionally _unstable_ API.  Future releases may return different
     # (incompatible) objects, <em>without deprecation or warning</em>.
     #
@@ -2357,14 +2393,9 @@ module Net
     # Sends a {FETCH command [IMAP4rev1 §6.4.5]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.5]
     # to retrieve data associated with a message in the mailbox.
     #
-    # The +set+ parameter is a number or a range between two numbers,
-    # or an array of those.  The number is a message sequence number,
-    # where -1 represents a '*' for use in range notation like 100..-1
-    # being interpreted as '100:*'.  Beware that the +exclude_end?+
-    # property of a Range object is ignored, and the contents of a
-    # range are independent of the order of the range endpoints as per
-    # the protocol specification, so 1...5, 5..1 and 5...1 are all
-    # equivalent to 1..5.
+    # +set+ is the message sequence numbers to fetch, and may be any valid input
+    # to {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets].
+    # (For UIDs, use #uid_fetch instead.)
     #
     # +attr+ is a list of attributes to fetch; see the documentation
     # for FetchData for a list of valid attributes.
@@ -2374,7 +2405,7 @@ module Net
     #
     # The return value is an array of FetchData.
     #
-    # Related: #uid_search, FetchData
+    # Related: #uid_fetch, FetchData
     #
     # ==== For example:
     #
@@ -2403,30 +2434,66 @@ module Net
     # {[RFC7162]}[https://tools.ietf.org/html/rfc7162] in order to use the
     # +changedsince+ argument.  Using +changedsince+ implicitly enables the
     # +CONDSTORE+ extension.
-    def fetch(set, attr, mod = nil, changedsince: nil)
-      fetch_internal("FETCH", set, attr, mod, changedsince: changedsince)
+    def fetch(...)
+      fetch_internal("FETCH", ...)
     end
 
     # :call-seq:
-    #   uid_fetch(set, attr, changedsince: nil) -> array of FetchData
+    #   uid_fetch(set, attr, changedsince: nil, partial: nil) -> array of FetchData
     #
     # Sends a {UID FETCH command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to retrieve data associated with a message in the mailbox.
     #
-    # Similar to #fetch, but the +set+ parameter contains unique identifiers
-    # instead of message sequence numbers.
+    # +set+ is the message UIDs to fetch, and may be any valid input to
+    # {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets].
+    # (For message sequence numbers, use #fetch instead.)
     #
+    # +attr+ behaves the same as with #fetch.
     # >>>
     #   *Note:* Servers _MUST_ implicitly include the +UID+ message data item as
     #   part of any +FETCH+ response caused by a +UID+ command, regardless of
     #   whether a +UID+ was specified as a message data item to the +FETCH+.
     #
+    # +changedsince+ (optional) behaves the same as with #fetch.
+    #
+    # +partial+ is an optional range to limit the number of results returned.
+    # It's useful when +set+ contains an unknown number of messages.
+    # <tt>1..500</tt> returns the first 500 messages in +set+ (in mailbox
+    # order), <tt>501..1000</tt> the second 500, and so on.  +partial+ may also
+    # be negative: <tt>-500..-1</tt> selects the last 500 messages in +set+.
+    # <em>Requires the +PARTIAL+ capabability.</em>
+    # {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394]
+    #
+    # For example:
+    #
+    #   # Without partial, the size of the results may be unknown beforehand:
+    #   results = imap.uid_fetch(next_uid_to_fetch.., %w(UID FLAGS))
+    #   # ... maybe wait for a long time ... and allocate a lot of memory ...
+    #   results.size # => 0..2**32-1
+    #   process results # may also take a long time and use a lot of memory...
+    #
+    #   # Using partial, the results may be paginated:
+    #   loop do
+    #     results = imap.uid_fetch(next_uid_to_fetch.., %w(UID FLAGS),
+    #                              partial: 1..500)
+    #     # fetch should return quickly and allocate little memory
+    #     results.size # => 0..500
+    #     break if results.empty?
+    #     next_uid_to_fetch = results.last.uid + 1
+    #     process results
+    #   end
+    #
     # Related: #fetch, FetchData
     #
     # ==== Capabilities
-    # Same as #fetch.
-    def uid_fetch(set, attr, mod = nil, changedsince: nil)
-      fetch_internal("UID FETCH", set, attr, mod, changedsince: changedsince)
+    #
+    # The server's capabilities must include +PARTIAL+
+    # {[RFC9394]}[https://rfc-editor.org/rfc/rfc9394] in order to use the
+    # +partial+ argument.
+    #
+    # Otherwise, the same as #fetch.
+    def uid_fetch(...)
+      fetch_internal("UID FETCH", ...)
     end
 
     # :call-seq:
@@ -3338,24 +3405,14 @@ module Net
         ]
       return_opts.map {|opt|
         case opt
-        when Symbol then opt.to_s
-        when Range  then partial_range_last_or_seqset(opt)
-        else             opt
+        when Symbol                 then opt.to_s
+        when PartialRange::Negative then PartialRange[opt]
+        when Range                  then SequenceSet[opt]
+        else                             opt
         end
       }
     end
 
-    def partial_range_last_or_seqset(range)
-      case [range.begin, range.end]
-      in [Integer => first, Integer => last] if first.negative? && last.negative?
-        # partial-range-last [RFC9394]
-        first <= last or raise DataFormatError, "empty range: %p" % [range]
-        "#{first}:#{last}"
-      else
-        SequenceSet[range]
-      end
-    end
-
     def search_internal(cmd, ...)
       args, esearch = search_args(...)
       synchronize do
@@ -3382,7 +3439,12 @@ module Net
       end
     end
 
-    def fetch_internal(cmd, set, attr, mod = nil, changedsince: nil)
+    def fetch_internal(cmd, set, attr, mod = nil, partial: nil, changedsince: nil)
+      set = SequenceSet[set]
+      if partial
+        mod ||= []
+        mod << "PARTIAL" << PartialRange[partial]
+      end
       if changedsince
         mod ||= []
         mod << "CHANGEDSINCE" << Integer(changedsince)
@@ -3399,9 +3461,9 @@ module Net
       synchronize do
         clear_responses("FETCH")
         if mod
-          send_command(cmd, SequenceSet.new(set), attr, mod)
+          send_command(cmd, set, attr, mod)
         else
-          send_command(cmd, SequenceSet.new(set), attr)
+          send_command(cmd, set, attr)
         end
         clear_responses("FETCH")
       end

data/rakelib/rfcs.rake

@@ -145,6 +145,7 @@ RFCS = {
   8514 => "IMAP SAVEDATE",
   8970 => "IMAP PREVIEW",
   9208 => "IMAP QUOTA, QUOTA=, QUOTASET",
+  9394 => "IMAP PARTIAL",
 
   # etc...
   3629 => "UTF8",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-20 00:00:00.000000000 Z
+date: 2024-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol