✨ Add support for the CONDSTORE extension (RFC7162)

lib/net/imap.rb

@@ -502,6 +502,22 @@ module Net
  #
  # - See #enable for information about support for UTF-8 string encoding.
  #
+ # ==== RFC7162: +CONDSTORE+
+ #
+ # - Updates #enable with +CONDSTORE+ parameter. +CONDSTORE+ will also be
+ # enabled by using any of the extension's command parameters, listed below.
+ # - Updates #status with the +HIGHESTMODSEQ+ status attribute.
+ # - Updates #select and #examine with the +condstore+ modifier, and adds
+ # either a +HIGHESTMODSEQ+ or +NOMODSEQ+ ResponseCode to the responses.
+ # - Updates #search, #uid_search, #sort, and #uid_sort with the +MODSEQ+
+ # search criterion, and adds SearchResult#modseq to the search response.
+ # - Updates #thread and #uid_thread with the +MODSEQ+ search criterion
+ # <em>(but thread responses are unchanged)</em>.
+ # - Updates #fetch and #uid_fetch with the +changedsince+ modifier and
+ # +MODSEQ+ FetchData attribute.
+ # - Updates #store and #uid_store with the +unchangedsince+ modifier and adds
+ # the +MODIFIED+ ResponseCode to the tagged response.
+ #
  # ==== RFC8438: <tt>STATUS=SIZE</tt>
  # - Updates #status with the +SIZE+ status attribute.
  #
@@ -669,6 +685,16 @@ module Net
  # Resnick, P., Ed., Newman, C., Ed., and S. Shen, Ed.,
  # "IMAP Support for UTF-8", RFC 6855, DOI 10.17487/RFC6855, March 2013,
  # <https://www.rfc-editor.org/info/rfc6855>.
+ # [CONDSTORE[https://tools.ietf.org/html/rfc7162]]::
+ # [QRESYNC[https://tools.ietf.org/html/rfc7162]]::
+ # Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag Changes
+ # Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization
+ # (QRESYNC)", RFC 7162, DOI 10.17487/RFC7162, May 2014,
+ # <https://www.rfc-editor.org/info/rfc7162>.
+ # [OBJECTID[https://tools.ietf.org/html/rfc8474]]::
+ # Gondwana, B., Ed., "IMAP Extension for Object Identifiers",
+ # RFC 8474, DOI 10.17487/RFC8474, September 2018,
+ # <https://www.rfc-editor.org/info/rfc8474>.
  #
  # === IANA registries
  # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities]
@@ -1345,6 +1371,12 @@ def login(user, password)
  # or when existing messages are expunged; see #add_response_handler for a
  # way to detect these events.
  #
+ # When the +condstore+ keyword argument is true, the server is told to
+ # enable the extension. If +mailbox+ supports persistence of mod-sequences,
+ # the +HIGHESTMODSEQ+ ResponseCode will be sent as an untagged response to
+ # #select and all `FETCH` responses will include FetchData#modseq.
+ # Otherwise, the +NOMODSEQ+ ResponseCode will be sent.
+ #
  # A Net::IMAP::NoResponseError is raised if the mailbox does not
  # exist or is for some reason non-selectable.
  #
@@ -1357,10 +1389,17 @@ def login(user, password)
  # response code indicating that the mailstore does not support persistent
  # UIDs:
  # imap.responses("NO", &:last)&.code&.name == "UIDNOTSTICKY"
- def select(mailbox)
+ #
+ # If [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html]] is supported,
+ # the +condstore+ keyword parameter may be used.
+ # imap.select("mbox", condstore: true)
+ # modseq = imap.responses("HIGHESTMODSEQ", &:last)
+ def select(mailbox, condstore: false)
+ args = ["SELECT", mailbox]
+ args << ["CONDSTORE"] if condstore
  synchronize do
  @responses.clear
- send_command("SELECT", mailbox)
+ send_command(*args)
  end
  end
 
@@ -1373,10 +1412,12 @@ def select(mailbox)
  # exist or is for some reason non-examinable.
  #
  # Related: #select
- def examine(mailbox)
+ def examine(mailbox, condstore: false)
+ args = ["EXAMINE", mailbox]
+ args << ["CONDSTORE"] if condstore
  synchronize do
  @responses.clear
- send_command("EXAMINE", mailbox)
+ send_command(*args)
  end
  end
 
@@ -1689,7 +1730,7 @@ def lsub(refname, mailbox)
  end
  end
 
- # Sends a {STATUS commands [IMAP4rev1 §6.3.10]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.10]
+ # Sends a {STATUS command [IMAP4rev1 §6.3.10]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.10]
  # and returns the status of the indicated +mailbox+. +attr+ is a list of one
  # or more attributes whose statuses are to be requested.
  #
@@ -1716,10 +1757,13 @@ def lsub(refname, mailbox)
  # The approximate size of the mailbox---must be greater than or equal to
  # the sum of all messages' +RFC822.SIZE+ fetch item values.
  #
+ # +HIGHESTMODSEQ+::
+ # The highest mod-sequence value of all messages in the mailbox. See
+ # +CONDSTORE+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+ #
  # +MAILBOXID+::
- # A server-allocated unique _string_ identifier for the mailbox.
- # See +OBJECTID+
- # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-4].
+ # A server-allocated unique _string_ identifier for the mailbox. See
+ # +OBJECTID+ {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
  #
  # +RECENT+::
  # The number of messages with the <tt>\Recent</tt> flag.
@@ -1741,6 +1785,9 @@ def lsub(refname, mailbox)
  #
  # +DELETED+ requires the server's capabilities to include +IMAP4rev2+.
  #
+ # +HIGHESTMODSEQ+ requires the server's capabilities to include +CONDSTORE+
+ # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+ #
  # +MAILBOXID+ requires the server's capabilities to include +OBJECTID+
  # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
  def status(mailbox, attr)
@@ -1877,6 +1924,10 @@ def uid_expunge(uid_set)
  # string holding the entire search string, or a single-dimension array of
  # search keywords and arguments.
  #
+ # Returns a SearchResult object. SearchResult inherits from Array (for
+ # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
+ # capability has been enabled.
+ #
  # Related: #uid_search
  #
  # ===== Search criteria
@@ -1925,6 +1976,15 @@ def uid_expunge(uid_set)
  # p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
  # #=> [1, 6, 7, 8]
  #
+ # ===== Capabilities
+ #
+ # If [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html]] is supported
+ # and enabled for the selected mailbox, a non-empty SearchResult will
+ # include a +MODSEQ+ value.
+ # imap.select("mbox", condstore: true)
+ # result = imap.search(["SUBJECT", "hi there", "not", "new")
+ # #=> Net::IMAP::SearchResult[1, 6, 7, 8, modseq: 5594]
+ # result.modseq # => 5594
  def search(keys, charset = nil)
  return search_internal("SEARCH", keys, charset)
  end
@@ -1933,11 +1993,18 @@ def search(keys, charset = nil)
  # to search the mailbox for messages that match the given searching
  # criteria, and returns unique identifiers (<tt>UID</tt>s).
  #
+ # Returns a SearchResult object. SearchResult inherits from Array (for
+ # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
+ # capability has been enabled.
+ #
  # See #search for documentation of search criteria.
  def uid_search(keys, charset = nil)
  return search_internal("UID SEARCH", keys, charset)
  end
 
+ # :call-seq:
+ # fetch(set, attr, changedsince: nil) -> array of FetchData
+ #
  # 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.
  #
@@ -1953,6 +2020,9 @@ def uid_search(keys, charset = nil)
  # +attr+ is a list of attributes to fetch; see the documentation
  # for FetchData for a list of valid attributes.
  #
+ # +changedsince+ is an optional integer mod-sequence. It limits results to
+ # messages with a mod-sequence greater than +changedsince+.
+ #
  # The return value is an array of FetchData.
  #
  # Related: #uid_search, FetchData
@@ -1974,10 +2044,23 @@ def uid_search(keys, charset = nil)
  # #=> "12-Oct-2000 22:40:59 +0900"
  # p data.attr["UID"]
  # #=> 98
- def fetch(set, attr, mod = nil)
- return fetch_internal("FETCH", set, attr, mod)
+ #
+ # ===== Capabilities
+ #
+ # Many extensions define new message +attr+ names. See FetchData for a list
+ # of supported extension fields.
+ #
+ # The server's capabilities must include +CONDSTORE+
+ # {[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)
  end
 
+ # :call-seq:
+ # uid_fetch(set, attr, changedsince: 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.
  #
@@ -1990,17 +2073,36 @@ def fetch(set, attr, mod = nil)
  # whether a +UID+ was specified as a message data item to the +FETCH+.
  #
  # Related: #fetch, FetchData
- def uid_fetch(set, attr, mod = nil)
- return fetch_internal("UID FETCH", set, attr, mod)
+ #
+ # ===== Capabilities
+ # Same as #fetch.
+ def uid_fetch(set, attr, mod = nil, changedsince: nil)
+ fetch_internal("UID FETCH", set, attr, mod, changedsince: changedsince)
  end
 
+ # :call-seq:
+ # store(set, attr, value, unchangedsince: nil) -> array of FetchData
+ #
  # Sends a {STORE command [IMAP4rev1 §6.4.6]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.6]
  # to alter data associated with messages in the mailbox, in particular their
- # flags. The +set+ parameter is a number, an array of numbers, or a Range
- # object. Each number is a message sequence number. +attr+ is the name of a
- # data item to store: <tt>"FLAGS"</tt> will replace the message's flag list
- # with the provided one, <tt>"+FLAGS"</tt> will add the provided flags, and
- # <tt>"-FLAGS"</tt> will remove them. +flags+ is a list of flags.
+ # flags.
+ #
+ # +set+ is a number, an array of numbers, or a Range object. Each number is
+ # a message sequence number.
+ #
+ # +attr+ is the name of a data item to store. The semantics of +value+
+ # varies based on +attr+:
+ # * When +attr+ is <tt>"FLAGS"</tt>, the flags in +value+ replace the
+ # message's flag list.
+ # * When +attr+ is <tt>"+FLAGS"</tt>, the flags in +value+ are added to
+ # the flags for the message.
+ # * When +attr+ is <tt>"-FLAGS"</tt>, the flags in +value+ are removed
+ # from the message.
+ #
+ # +unchangedsince+ is an optional integer mod-sequence. It prohibits any
+ # changes to messages with +mod-sequence+ greater than the specified
+ # +unchangedsince+ value. A SequenceSet of any messages that fail this
+ # check will be returned in a +MODIFIED+ ResponseCode.
  #
  # The return value is an array of FetchData.
  #
@@ -2009,13 +2111,25 @@ def uid_fetch(set, attr, mod = nil)
  # ===== For example:
  #
  # p imap.store(6..8, "+FLAGS", [:Deleted])
- # #=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
- # #<Net::IMAP::FetchData seqno=7, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
+ # #=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>,
+ # #<Net::IMAP::FetchData seqno=7, attr={"FLAGS"=>[:Seen, :Deleted]}>,
  # #<Net::IMAP::FetchData seqno=8, attr={"FLAGS"=>[:Seen, :Deleted]}>]
- def store(set, attr, flags)
- return store_internal("STORE", set, attr, flags)
+ #
+ # ===== Capabilities
+ #
+ # Extensions may define new data items to be used with #store.
+ #
+ # The server's capabilities must include +CONDSTORE+
+ # {[RFC7162]}[https://tools.ietf.org/html/rfc7162] in order to use the
+ # +unchangedsince+ argument. Using +unchangedsince+ implicitly enables the
+ # +CONDSTORE+ extension.
+ def store(set, attr, flags, unchangedsince: nil)
+ store_internal("STORE", set, attr, flags, unchangedsince: unchangedsince)
  end
 
+ # :call-seq:
+ # uid_store(set, attr, value, unchangedsince: nil) -> array of FetchData
+ #
  # Sends a {UID STORE command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
  # to alter data associated with messages in the mailbox, in particular their
  # flags.
@@ -2024,8 +2138,11 @@ def store(set, attr, flags)
  # message sequence numbers.
  #
  # Related: #store
- def uid_store(set, attr, flags)
- return store_internal("UID STORE", set, attr, flags)
+ #
+ # ===== Capabilities
+ # Same as #store.
+ def uid_store(set, attr, flags, unchangedsince: nil)
+ store_internal("UID STORE", set, attr, flags, unchangedsince: unchangedsince)
  end
 
  # Sends a {COPY command [IMAP4rev1 §6.4.7]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.7]
@@ -2201,6 +2318,13 @@ def uid_thread(algorithm, search_keys, charset)
  # each enabled extension (usually the same name as the enabled extension).
  # The following capabilities may be enabled:
  #
+ # [+CONDSTORE+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]]
+ #
+ # Updates various commands to return +CONDSTORE+ extension responses. It
+ # is not necessary to explicitly enable +CONDSTORE+—using any of the
+ # command parameters defined by the extension will implicitly enable it.
+ # See {[RFC7162 §3.1]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1].
+ #
  # [+:utf8+ --- an alias for <tt>"UTF8=ACCEPT"</tt>]
  #
  # In a future release, <tt>enable(:utf8)</tt> will enable either
@@ -2712,7 +2836,11 @@ def search_internal(cmd, keys, charset)
  end
  end
 
- def fetch_internal(cmd, set, attr, mod = nil)
+ def fetch_internal(cmd, set, attr, mod = nil, changedsince: nil)
+ if changedsince
+ mod ||= []
+ mod << "CHANGEDSINCE" << Integer(changedsince)
+ end
  case attr
  when String then
  attr = RawData.new(attr)
@@ -2733,13 +2861,14 @@ def fetch_internal(cmd, set, attr, mod = nil)
  end
  end
 
- def store_internal(cmd, set, attr, flags)
- if attr.instance_of?(String)
- attr = RawData.new(attr)
- end
+ def store_internal(cmd, set, attr, flags, unchangedsince: nil)
+ attr = RawData.new(attr) if attr.instance_of?(String)
+ args = [MessageSet.new(set)]
+ args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
+ args << attr << flags
  synchronize do
  clear_responses("FETCH")
- send_command(cmd, MessageSet.new(set), attr, flags)
+ send_command(cmd, *args)
  clear_responses("FETCH")
  end
  end

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.
@@ -291,6 +292,16 @@ class ResponseText < Struct.new(:code, :text)
  # 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