net-imap 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d271261a2609a31b8c84ae74913bf57d5046e95318db7660b3230940bdbff447
-  data.tar.gz: 771baa4b8a6c3f83f6ef4f320dda8dc5ea9f2fa2ace15fd9b0c1c1b3a594363a
+  metadata.gz: 49dc46f2744a04f6b151bc033176f2d59dabf04fb1996bba36a87b4b9f0f99b4
+  data.tar.gz: 411eac8fd696e619f0255d37a83b74b19b3290c68533fded627cd689d1afc57a
 SHA512:
-  metadata.gz: 230d40d8d183b1c69f63050990df140b49aa5731d0868713e44d2da68c2713ede4fd8d4b1aff60103c25ac6586076e220973b774a43cd5a7b3eaad4e49e7bf3b
-  data.tar.gz: 156e6c86f6fe39a76de89275bfcd3c57b5adcd375de6add45cd00a30bf92bbf04a2b475702db33cae0509fc0b7b3e015518d4991cd5c467f833cacb0f75d3ca6
+  metadata.gz: 3049e6a03f6660c6e7c67c82a9fdb8994a2a0ec3777ca66a6e4941b1a08486e452eb17007e5c666e41a52e34c2c54d057e33aecd6a4b5bac9c522d5f20acfb43
+  data.tar.gz: 9c7f8e858614748c65a434900f8b6ddba04b9e31578aa9669987803153c31269888abe6baca8ae42c5ecc00287dab2f494de73ac89cf1fb81d44ebfa65d42c5d

data/docs/styles.css

@@ -6,9 +6,7 @@
 
 main .method-detail {
   display: grid;
-  grid-template-areas:   "header         controls"
-                         "description description";
-  grid-template-columns: 1fr           min-content;
+  grid-template-columns: 1fr auto;
   justify-content: space-between;
 }
 
@@ -20,19 +18,16 @@ main .method-header, main .method-controls {
 }
 
 main .method-header {
-  grid-area: "header";
   border-right: none;
   border-radius: 4px 0 0 4px;
 }
 
 main .method-controls {
-  grid-area: "controls";
   border-left: none;
   border-radius: 0 4px 4px 0;
 }
 
 main .method-description, main .aliases {
-  grid-area: "description";
   grid-column: 1 / span 2;
   padding-left: 1em;
 }

data/lib/net/imap/response_data.rb

@@ -6,6 +6,7 @@ module Net
     autoload :FetchData,        "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
     autoload :SequenceSet,      "#{__dir__}/sequence_set"
+    autoload :VanishedData,     "#{__dir__}/vanished_data"
 
     # Net::IMAP::ContinuationRequest represents command continuation requests.
     #

data/lib/net/imap/response_parser.rb

@@ -769,7 +769,6 @@ module Net
       def response_data__ignored; response_data__unhandled(IgnoredResponse) end
       alias response_data__noop     response_data__ignored
 
-      alias expunged_resp           response_data__unhandled
       alias uidfetch_resp           response_data__unhandled
       alias listrights_data         response_data__unhandled
       alias myrights_data           response_data__unhandled
@@ -841,6 +840,20 @@ module Net
       alias mailbox_data__exists  response_data__simple_numeric
       alias mailbox_data__recent  response_data__simple_numeric
 
+      # The name for this is confusing, because it *replaces* EXPUNGE
+      # >>>
+      #   expunged-resp       =  "VANISHED" [SP "(EARLIER)"] SP known-uids
+      def expunged_resp
+        name    = label "VANISHED"; SP!
+        earlier = if lpar? then label("EARLIER"); rpar; SP!; true else false end
+        uids    = known_uids
+        data    = VanishedData[uids, earlier]
+        UntaggedResponse.new name, data, @str
+      end
+
+      # TODO: replace with uid_set
+      alias known_uids sequence_set
+
       # RFC3501 & RFC9051:
       #   msg-att         = "(" (msg-att-dynamic / msg-att-static)
       #                      *(SP (msg-att-dynamic / msg-att-static)) ")"

data/lib/net/imap/vanished_data.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # Net::IMAP::VanishedData represents the contents of a +VANISHED+ response,
+    # which is described by the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] extension.
+    # [{RFC7162 §3.2.10}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.2.10]].
+    #
+    # +VANISHED+ responses replace +EXPUNGE+ responses when either the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] or the
+    # {UIDONLY}[https://www.rfc-editor.org/rfc/rfc9586.html] extension has been
+    # enabled.
+    class VanishedData < Data.define(:uids, :earlier)
+
+      # Returns a new VanishedData object.
+      #
+      # * +uids+ will be converted by SequenceSet.[].
+      # * +earlier+ will be converted to +true+ or +false+
+      def initialize(uids:, earlier:)
+        uids    = SequenceSet[uids]
+        earlier = !!earlier
+        super
+      end
+
+      ##
+      # :attr_reader: uids
+      #
+      # SequenceSet of UIDs that have been permanently removed from the mailbox.
+
+      ##
+      # :attr_reader: earlier
+      #
+      # +true+ when the response was caused by Net::IMAP#uid_fetch with
+      # <tt>vanished: true</tt> or Net::IMAP#select/Net::IMAP#examine with
+      # <tt>qresync: true</tt>.
+      #
+      # +false+ when the response is used to announce message removals within an
+      # already selected mailbox.
+
+      # rdoc doesn't handle attr aliases nicely. :(
+      alias earlier? earlier # :nodoc:
+      ##
+      # :attr_reader: earlier?
+      #
+      # Alias for #earlier.
+
+      # Returns an Array of all of the UIDs in #uids.
+      #
+      # See SequenceSet#numbers.
+      def to_a; uids.numbers end
+
+    end
+  end
+end

data/lib/net/imap.rb

@@ -723,7 +723,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.2"
+    VERSION = "0.5.3"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1889,48 +1889,64 @@ module Net
       send_command("UNSELECT")
     end
 
+    # call-seq:
+    #   expunge -> array of message sequence numbers
+    #   expunge -> VanishedData of UIDs
+    #
     # Sends an {EXPUNGE command [IMAP4rev1 §6.4.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.3]
-    # Sends a EXPUNGE command to permanently remove from the currently
-    # selected mailbox all messages that have the \Deleted flag set.
+    # to permanently remove all messages with the +\Deleted+ flag from the
+    # currently selected mailbox.
+    #
+    # Returns either an array of expunged message <em>sequence numbers</em> or
+    # (when the appropriate capability is enabled) VanishedData of expunged
+    # UIDs.  Previously unhandled +EXPUNGE+ or +VANISHED+ responses are merged
+    # with the direct response to this command.  <tt>VANISHED (EARLIER)</tt>
+    # responses will _not_ be merged.
+    #
+    # When no messages have been expunged, an empty array is returned,
+    # regardless of which extensions are enabled.  In a future release, an empty
+    # VanishedData may be returned, based on the currently enabled extensions.
     #
     # Related: #uid_expunge
+    #
+    # ==== Capabilities
+    #
+    # When either QRESYNC[https://tools.ietf.org/html/rfc7162] or
+    # UIDONLY[https://tools.ietf.org/html/rfc9586] are enabled, #expunge
+    # returns VanishedData, which contains UIDs---<em>not message sequence
+    # numbers</em>.
     def expunge
-      synchronize do
-        send_command("EXPUNGE")
-        clear_responses("EXPUNGE")
-      end
+      expunge_internal("EXPUNGE")
     end
 
+    # call-seq:
+    #   uid_expunge{uid_set) -> array of message sequence numbers
+    #   uid_expunge{uid_set) -> VanishedData of UIDs
+    #
     # Sends a {UID EXPUNGE command [RFC4315 §2.1]}[https://www.rfc-editor.org/rfc/rfc4315#section-2.1]
     # {[IMAP4rev2 §6.4.9]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.4.9]
     # to permanently remove all messages that have both the <tt>\\Deleted</tt>
     # flag set and a UID that is included in +uid_set+.
     #
+    # Returns the same result type as #expunge.
+    #
     # By using #uid_expunge instead of #expunge when resynchronizing with
     # the server, the client can ensure that it does not inadvertantly
     # remove any messages that have been marked as <tt>\\Deleted</tt> by other
     # clients between the time that the client was last connected and
     # the time the client resynchronizes.
     #
-    # *Note:*
-    # >>>
-    #        Although the command takes a set of UIDs for its argument, the
-    #        server still returns regular EXPUNGE responses, which contain
-    #        a <em>sequence number</em>. These will be deleted from
-    #        #responses and this method returns them as an array of
-    #        <em>sequence number</em> integers.
-    #
     # Related: #expunge
     #
     # ==== Capabilities
     #
-    # The server's capabilities must include +UIDPLUS+
+    # The server's capabilities must include either +IMAP4rev2+ or +UIDPLUS+
     # [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
+    #
+    # Otherwise, #uid_expunge is updated by extensions in the same way as
+    # #expunge.
     def uid_expunge(uid_set)
-      synchronize do
-        send_command("UID EXPUNGE", SequenceSet.new(uid_set))
-        clear_responses("EXPUNGE")
-      end
+      expunge_internal("UID EXPUNGE", SequenceSet.new(uid_set))
     end
 
     # :call-seq:
@@ -1942,7 +1958,7 @@ module Net
     # and returns either a SearchResult or an ESearchResult.  SearchResult
     # inherits from Array (for backward compatibility) but adds
     # SearchResult#modseq when the +CONDSTORE+ capability has been enabled.
-    # ESearchResult also implements to_a{rdoc-ref:ESearchResult#to_a}, for
+    # ESearchResult also implements {#to_a}[rdoc-ref:ESearchResult#to_a], for
     # compatibility with SearchResult.
     #
     # +criteria+ is one or more search keys and their arguments, which may be
@@ -3261,6 +3277,22 @@ module Net
       end
     end
 
+    def expunge_internal(...)
+      synchronize do
+        send_command(...)
+        expunged_array = clear_responses("EXPUNGE")
+        vanished_array = extract_responses("VANISHED") { !_1.earlier? }
+        if vanished_array.empty?
+          expunged_array
+        elsif vanished_array.length == 1
+          vanished_array.first
+        else
+          merged_uids = SequenceSet[*vanished_array.map(&:uids)]
+          VanishedData[uids: merged_uids, earlier: false]
+        end
+      end
+    end
+
     RETURN_WHOLE = /\ARETURN\z/i
     RETURN_START = /\ARETURN\b/i
     private_constant :RETURN_WHOLE, :RETURN_START

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-16 00:00:00.000000000 Z
+date: 2024-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -97,6 +97,7 @@ files:
 - lib/net/imap/stringprep/saslprep_tables.rb
 - lib/net/imap/stringprep/tables.rb
 - lib/net/imap/stringprep/trace.rb
+- lib/net/imap/vanished_data.rb
 - net-imap.gemspec
 - rakelib/benchmarks.rake
 - rakelib/rdoc.rake