Skip to content

Commit 55c1d24

Browse files
committed
✨ Support VANISHED response to #expunge
Both the `QRESYNC` and `UIDONLY` extensions replace `EXPUNGE` responses with `VANISHED` responses. This updates the #expunge and #uid_expunge commands to return VanishedData, rather than a (misleading) empty array.
1 parent a82c1d0 commit 55c1d24

File tree

2 files changed

+129
-20
lines changed

2 files changed

+129
-20
lines changed

lib/net/imap.rb

Lines changed: 51 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1889,48 +1889,64 @@ def unselect
18891889
send_command("UNSELECT")
18901890
end
18911891

1892+
# call-seq:
1893+
# expunge -> array of message sequence numbers
1894+
# expunge -> VanishedData of UIDs
1895+
#
18921896
# Sends an {EXPUNGE command [IMAP4rev1 §6.4.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.3]
1893-
# Sends a EXPUNGE command to permanently remove from the currently
1894-
# selected mailbox all messages that have the \Deleted flag set.
1897+
# to permanently remove all messages with the +\Deleted+ flag from the
1898+
# currently selected mailbox.
1899+
#
1900+
# Returns either an array of expunged message <em>sequence numbers</em> or
1901+
# (when the appropriate capability is enabled) VanishedData of expunged
1902+
# UIDs. Previously unhandled +EXPUNGE+ or +VANISHED+ responses are merged
1903+
# with the direct response to this command. <tt>VANISHED (EARLIER)</tt>
1904+
# responses will _not_ be merged.
1905+
#
1906+
# When no messages have been expunged, an empty array is returned,
1907+
# regardless of which extensions are enabled. In a future release, an empty
1908+
# VanishedData may be returned, based on the currently enabled extensions.
18951909
#
18961910
# Related: #uid_expunge
1911+
#
1912+
# ==== Capabilities
1913+
#
1914+
# When either QRESYNC[https://tools.ietf.org/html/rfc7162] or
1915+
# UIDONLY[https://tools.ietf.org/html/rfc9586] are enabled, #expunge
1916+
# returns VanishedData, which contains UIDs---<em>not message sequence
1917+
# numbers</em>.
18971918
def expunge
1898-
synchronize do
1899-
send_command("EXPUNGE")
1900-
clear_responses("EXPUNGE")
1901-
end
1919+
expunge_internal("EXPUNGE")
19021920
end
19031921

1922+
# call-seq:
1923+
# uid_expunge{uid_set) -> array of message sequence numbers
1924+
# uid_expunge{uid_set) -> VanishedData of UIDs
1925+
#
19041926
# Sends a {UID EXPUNGE command [RFC4315 §2.1]}[https://www.rfc-editor.org/rfc/rfc4315#section-2.1]
19051927
# {[IMAP4rev2 §6.4.9]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.4.9]
19061928
# to permanently remove all messages that have both the <tt>\\Deleted</tt>
19071929
# flag set and a UID that is included in +uid_set+.
19081930
#
1931+
# Returns the same result type as #expunge.
1932+
#
19091933
# By using #uid_expunge instead of #expunge when resynchronizing with
19101934
# the server, the client can ensure that it does not inadvertantly
19111935
# remove any messages that have been marked as <tt>\\Deleted</tt> by other
19121936
# clients between the time that the client was last connected and
19131937
# the time the client resynchronizes.
19141938
#
1915-
# *Note:*
1916-
# >>>
1917-
# Although the command takes a set of UIDs for its argument, the
1918-
# server still returns regular EXPUNGE responses, which contain
1919-
# a <em>sequence number</em>. These will be deleted from
1920-
# #responses and this method returns them as an array of
1921-
# <em>sequence number</em> integers.
1922-
#
19231939
# Related: #expunge
19241940
#
19251941
# ==== Capabilities
19261942
#
1927-
# The server's capabilities must include +UIDPLUS+
1943+
# The server's capabilities must include either +IMAP4rev2+ or +UIDPLUS+
19281944
# [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
1945+
#
1946+
# Otherwise, #uid_expunge is updated by extensions in the same way as
1947+
# #expunge.
19291948
def uid_expunge(uid_set)
1930-
synchronize do
1931-
send_command("UID EXPUNGE", SequenceSet.new(uid_set))
1932-
clear_responses("EXPUNGE")
1933-
end
1949+
expunge_internal("UID EXPUNGE", SequenceSet.new(uid_set))
19341950
end
19351951

19361952
# :call-seq:
@@ -3261,6 +3277,22 @@ def enforce_logindisabled?
32613277
end
32623278
end
32633279

3280+
def expunge_internal(...)
3281+
synchronize do
3282+
send_command(...)
3283+
expunged_array = clear_responses("EXPUNGE")
3284+
vanished_array = extract_responses("VANISHED") { !_1.earlier? }
3285+
if vanished_array.empty?
3286+
expunged_array
3287+
elsif vanished_array.length == 1
3288+
vanished_array.first
3289+
else
3290+
merged_uids = SequenceSet[*vanished_array.map(&:uids)]
3291+
VanishedData[uids: merged_uids, earlier: false]
3292+
end
3293+
end
3294+
end
3295+
32643296
RETURN_WHOLE = /\ARETURN\z/i
32653297
RETURN_START = /\ARETURN\b/i
32663298
private_constant :RETURN_WHOLE, :RETURN_START

test/net/imap/test_imap.rb

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1016,7 +1016,7 @@ def test_id
10161016
end
10171017
end
10181018

1019-
def test_uidplus_uid_expunge
1019+
test "#uid_expunge with EXPUNGE responses" do
10201020
with_fake_server(select: "INBOX",
10211021
extensions: %i[UIDPLUS]) do |server, imap|
10221022
server.on "UID EXPUNGE" do |resp|
@@ -1032,6 +1032,24 @@ def test_uidplus_uid_expunge
10321032
end
10331033
end
10341034

1035+
test "#uid_expunge with VANISHED response" do
1036+
with_fake_server(select: "INBOX",
1037+
extensions: %i[UIDPLUS]) do |server, imap|
1038+
server.on "UID EXPUNGE" do |resp|
1039+
resp.untagged("VANISHED 1001,1003")
1040+
resp.done_ok
1041+
end
1042+
response = imap.uid_expunge(1000..1003)
1043+
cmd = server.commands.pop
1044+
assert_equal ["UID EXPUNGE", "1000:1003"], [cmd.name, cmd.args]
1045+
assert_equal(
1046+
Net::IMAP::VanishedData[uids: [1001, 1003], earlier: false],
1047+
response
1048+
)
1049+
assert_equal([], imap.clear_responses("VANISHED"))
1050+
end
1051+
end
1052+
10351053
def test_uidplus_appenduid
10361054
with_fake_server(select: "INBOX",
10371055
extensions: %i[UIDPLUS]) do |server, imap|
@@ -1168,6 +1186,65 @@ def test_enable
11681186
end
11691187
end
11701188

1189+
test "#expunge with EXPUNGE responses" do
1190+
with_fake_server(select: "INBOX") do |server, imap|
1191+
server.on "EXPUNGE" do |resp|
1192+
resp.untagged("1 EXPUNGE")
1193+
resp.untagged("1 EXPUNGE")
1194+
resp.untagged("99 EXPUNGE")
1195+
resp.done_ok
1196+
end
1197+
response = imap.expunge
1198+
cmd = server.commands.pop
1199+
assert_equal ["EXPUNGE", nil], [cmd.name, cmd.args]
1200+
assert_equal [1, 1, 99], response
1201+
assert_equal [], imap.clear_responses("EXPUNGED")
1202+
end
1203+
end
1204+
1205+
test "#expunge with a VANISHED response" do
1206+
with_fake_server(select: "INBOX") do |server, imap|
1207+
server.on "EXPUNGE" do |resp|
1208+
resp.untagged("VANISHED 15:456")
1209+
resp.done_ok
1210+
end
1211+
response = imap.expunge
1212+
cmd = server.commands.pop
1213+
assert_equal ["EXPUNGE", nil], [cmd.name, cmd.args]
1214+
assert_equal(
1215+
Net::IMAP::VanishedData[uids: [15..456], earlier: false],
1216+
response
1217+
)
1218+
assert_equal([], imap.clear_responses("VANISHED"))
1219+
end
1220+
end
1221+
1222+
test "#expunge with multiple VANISHED responses" do
1223+
with_fake_server(select: "INBOX") do |server, imap|
1224+
server.unsolicited("VANISHED 86")
1225+
server.on "EXPUNGE" do |resp|
1226+
resp.untagged("VANISHED (EARLIER) 1:5,99,123")
1227+
resp.untagged("VANISHED 15,456")
1228+
resp.untagged("VANISHED (EARLIER) 987,1001")
1229+
resp.done_ok
1230+
end
1231+
response = imap.expunge
1232+
cmd = server.commands.pop
1233+
assert_equal ["EXPUNGE", nil], [cmd.name, cmd.args]
1234+
assert_equal(
1235+
Net::IMAP::VanishedData[uids: [15, 86, 456], earlier: false],
1236+
response
1237+
)
1238+
assert_equal(
1239+
[
1240+
Net::IMAP::VanishedData[uids: [1..5, 99, 123], earlier: true],
1241+
Net::IMAP::VanishedData[uids: [987, 1001], earlier: true],
1242+
],
1243+
imap.clear_responses("VANISHED")
1244+
)
1245+
end
1246+
end
1247+
11711248
def test_close
11721249
with_fake_server(select: "inbox") do |server, imap|
11731250
resp = imap.close

0 commit comments

Comments
 (0)