From 60f577690d80dd2593edaeb1d09b7681bedac368 Mon Sep 17 00:00:00 2001 From: nick evans Date: Wed, 5 Feb 2025 16:25:52 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=F0=9F=97=91=EF=B8=8F=20Deprecate?= =?UTF-8?q?=20UIDPlusData,=20with=20config=20to=20upgrade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This config attribute causes the parser to use the new AppendUIDData and CopyUIDData classes instead of CopyUIDData. AppendUIDData and CopyUIDData are _mostly_ backward-compatible with UIDPlusData. Most applications should be able to upgrade with no changes. UIDPlusData will be removed in +v0.6+. --- lib/net/imap/config.rb | 29 +++++++++++++++++ lib/net/imap/response_parser.rb | 12 ++++--- lib/net/imap/uidplus_data.rb | 14 ++++++++ test/net/imap/test_imap_response_parser.rb | 37 ++++++++++++++++++++++ 4 files changed, 88 insertions(+), 4 deletions(-) diff --git a/lib/net/imap/config.rb b/lib/net/imap/config.rb index edeea30e..d5b0975a 100644 --- a/lib/net/imap/config.rb +++ b/lib/net/imap/config.rb @@ -287,6 +287,32 @@ def self.[](config) # # Alias for responses_without_block + # Whether ResponseParser should use the deprecated UIDPlusData or + # CopyUIDData for +COPYUID+ response codes, and UIDPlusData or + # AppendUIDData for +APPENDUID+ response codes. + # + # AppendUIDData and CopyUIDData are _mostly_ backward-compatible with + # UIDPlusData. Most applications should be able to upgrade with little + # or no changes. + # + # (Parser support for +UIDPLUS+ added in +v0.3.2+.) + # + # (Config option added in +v0.4.19+ and +v0.5.6+.) + # + # UIDPlusData will be removed in +v0.6+ and this config setting will + # be ignored. + # + # ==== Valid options + # + # [+true+ (original default)] + # ResponseParser only uses UIDPlusData. + # + # [+false+ (planned default for +v0.6+)] + # ResponseParser _only_ uses AppendUIDData and CopyUIDData. + attr_accessor :parser_use_deprecated_uidplus_data, type: [ + true, false + ] + # Creates a new config object and initialize its attribute with +attrs+. # # If +parent+ is not given, the global config is used by default. @@ -367,6 +393,7 @@ def defaults_hash sasl_ir: true, enforce_logindisabled: true, responses_without_block: :warn, + parser_use_deprecated_uidplus_data: true, ).freeze @global = default.new @@ -378,6 +405,7 @@ def defaults_hash sasl_ir: false, responses_without_block: :silence_deprecation_warning, enforce_logindisabled: false, + parser_use_deprecated_uidplus_data: true, ).freeze version_defaults[0.0] = Config[0] version_defaults[0.1] = Config[0] @@ -392,6 +420,7 @@ def defaults_hash version_defaults[0.6] = Config[0.5].dup.update( responses_without_block: :frozen_dup, + parser_use_deprecated_uidplus_data: false, ).freeze version_defaults[:next] = Config[0.6] version_defaults[:future] = Config[:next] diff --git a/lib/net/imap/response_parser.rb b/lib/net/imap/response_parser.rb index 03f135ec..71c08e7b 100644 --- a/lib/net/imap/response_parser.rb +++ b/lib/net/imap/response_parser.rb @@ -2001,11 +2001,10 @@ def charset__list # # n.b, uniqueid ⊂ uid-set. To avoid inconsistent return types, we always # match uid_set even if that returns a single-member array. - # def resp_code_apnd__data validity = number; SP! dst_uids = uid_set # uniqueid ⊂ uid-set - UIDPlus(validity, nil, dst_uids) + AppendUID(validity, dst_uids) end # already matched: "COPYUID" @@ -2015,10 +2014,15 @@ def resp_code_copy__data validity = number; SP! src_uids = uid_set; SP! dst_uids = uid_set - UIDPlus(validity, src_uids, dst_uids) + CopyUID(validity, src_uids, dst_uids) end - def UIDPlus(validity, src_uids, dst_uids) + def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end + def CopyUID(...) DeprecatedUIDPlus(...) || CopyUIDData.new(...) end + + # TODO: remove this code in the v0.6.0 release + def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids) + return unless config.parser_use_deprecated_uidplus_data src_uids &&= src_uids.each_ordered_number.to_a dst_uids = dst_uids.each_ordered_number.to_a UIDPlusData.new(validity, src_uids, dst_uids) diff --git a/lib/net/imap/uidplus_data.rb b/lib/net/imap/uidplus_data.rb index f937d53d..0e593636 100644 --- a/lib/net/imap/uidplus_data.rb +++ b/lib/net/imap/uidplus_data.rb @@ -3,6 +3,10 @@ module Net class IMAP < Protocol + # *NOTE:* UIDPlusData is deprecated and will be removed in the +0.6.0+ + # release. To use AppendUIDData and CopyUIDData before +0.6.0+, set + # Config#parser_use_deprecated_uidplus_data to +false+. + # # UIDPlusData represents the ResponseCode#data that accompanies the # +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode]. # @@ -60,6 +64,11 @@ def uid_mapping end end + # >>> + # *NOTE:* AppendUIDData will replace UIDPlusData for +APPENDUID+ in the + # +0.6.0+ release. To use AppendUIDData before +0.6.0+, set + # Config#parser_use_deprecated_uidplus_data to +false+. + # # AppendUIDData represents the ResponseCode#data that accompanies the # +APPENDUID+ {response code}[rdoc-ref:ResponseCode]. # @@ -99,6 +108,11 @@ def size end end + # >>> + # *NOTE:* CopyUIDData will replace UIDPlusData for +COPYUID+ in the + # +0.6.0+ release. To use CopyUIDData before +0.6.0+, set + # Config#parser_use_deprecated_uidplus_data to +false+. + # # CopyUIDData represents the ResponseCode#data that accompanies the # +COPYUID+ {response code}[rdoc-ref:ResponseCode]. # diff --git a/test/net/imap/test_imap_response_parser.rb b/test/net/imap/test_imap_response_parser.rb index b24c63ff..7a70c02b 100644 --- a/test/net/imap/test_imap_response_parser.rb +++ b/test/net/imap/test_imap_response_parser.rb @@ -211,6 +211,24 @@ def test_fetch_binary_and_binary_size end end + test "APPENDUID with parser_use_deprecated_uidplus_data = true" do + parser = Net::IMAP::ResponseParser.new(config: { + parser_use_deprecated_uidplus_data: true, + }) + response = parser.parse("A004 OK [APPENDUID 1 101:200] Done\r\n") + uidplus = response.data.code.data + assert_instance_of Net::IMAP::UIDPlusData, uidplus + assert_equal 100, uidplus.assigned_uids.size + end + + test "APPENDUID with parser_use_deprecated_uidplus_data = false" do + parser = Net::IMAP::ResponseParser.new(config: { + parser_use_deprecated_uidplus_data: false, + }) + response = parser.parse("A004 OK [APPENDUID 1 10] Done\r\n") + assert_instance_of Net::IMAP::AppendUIDData, response.data.code.data + end + test "COPYUID with backwards ranges" do parser = Net::IMAP::ResponseParser.new response = parser.parse( @@ -241,4 +259,23 @@ def test_fetch_binary_and_binary_size end end + test "COPYUID with parser_use_deprecated_uidplus_data = true" do + parser = Net::IMAP::ResponseParser.new(config: { + parser_use_deprecated_uidplus_data: true, + }) + response = parser.parse("A004 OK [copyUID 1 101:200 1:100] Done\r\n") + uidplus = response.data.code.data + assert_instance_of Net::IMAP::UIDPlusData, uidplus + assert_equal 100, uidplus.assigned_uids.size + assert_equal 100, uidplus.source_uids.size + end + + test "COPYUID with parser_use_deprecated_uidplus_data = false" do + parser = Net::IMAP::ResponseParser.new(config: { + parser_use_deprecated_uidplus_data: false, + }) + response = parser.parse("A004 OK [COPYUID 1 101 1] Done\r\n") + assert_instance_of Net::IMAP::CopyUIDData, response.data.code.data + end + end