net-imap 0.6.4.1 → 0.6.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/net/imap.rb CHANGED
@@ -85,29 +85,100 @@ module Net
85
85
  #
86
86
  # === Examples of Usage
87
87
  #
88
- # ==== List sender and subject of all recent messages in the default mailbox
88
+ # ==== Connect with TLS to port 993
89
+ #
90
+ # Use Net::IMAP.new to open a new connection, with <tt>ssl: true</tt> for TLS.
91
+ # <br>
92
+ # Use #authenticate to log in.
93
+ #
94
+ # hostname = "mail.example.com"
95
+ # username = "user@example.com"
96
+ # password = "correct-horse-battery-staple"
97
+ #
98
+ # imap = Net::IMAP.new(hostname, ssl: true)
99
+ # imap.authenticate(:plain, username, password)
100
+ #
101
+ # To authenticate with an OAuth2 access token:
102
+ # if imap.auth_capable?(:OAUTHBEARER)
103
+ # imap.authenticate(:OAUTHBEARER, oauth2_token:)
104
+ # elsif imap.auth_capable?(:XOAUTH2)
105
+ # imap.authenticate(:XOAUTH2, oauth2_token:)
106
+ # else
107
+ # raise "OAuth2 not supported?"
108
+ # end
109
+ #
110
+ # See #authenticate for other supported authentication mechanisms.
111
+ #
112
+ # ==== List sender and subject of recent messages
113
+ #
114
+ # Use #examine to open a mailbox with read-only access.<br>
115
+ # Use #uid_search for a list of UIDs (or #search for sequence numbers).<br>
116
+ # Use #uid_fetch (or #fetch) to read message attributes, such as "envelope".
117
+ #
118
+ # Search returns a SearchResult or ESearchResult, which is coercible to
119
+ # SequenceSet so it can be used directly as a message set argument for other
120
+ # commands. The first #uid_fetch argument is the set of message UIDs
121
+ # (sequence numbers for #fetch). Fetch returns an array of FetchData (or
122
+ # UIDFetchData when +UIDONLY+ is enabled).
89
123
  #
90
- # imap = Net::IMAP.new('mail.example.com')
91
- # imap.authenticate('PLAIN', 'joe_user', 'joes_password')
92
124
  # imap.examine('INBOX')
93
- # imap.search(["RECENT"]).each do |message_id|
94
- # envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
95
- # puts "#{envelope.from[0].name}: \t#{envelope.subject}"
125
+ # search_result = imap.uid_search(["SINCE", Date.today - 7])
126
+ # imap.uid_fetch(search_result, "ENVELOPE").each do |fetch_data|
127
+ # envelope = fetch_data.envelope
128
+ # puts "#{envelope.from.first.name}: \t#{envelope.subject}"
96
129
  # end
97
130
  #
98
- # ==== Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
131
+ # ==== Move messages between two dates to another mailbox
132
+ #
133
+ # Use #list to check if the destination mailbox exists.<br>
134
+ # Use #create to create a missing destination mailbox.<br>
135
+ # Use #select to open the source mailbox with read-write access.<br>
136
+ # Use #uid_search (or #search) to search for messages within a date range.<br>
137
+ # Use #uid_move (or #move) to atomically move messages to another mailbox.
99
138
  #
100
- # imap = Net::IMAP.new('mail.example.com')
101
- # imap.authenticate('PLAIN', 'joe_user', 'joes_password')
102
- # imap.select('Mail/sent-mail')
103
- # if not imap.list('Mail/', 'sent-apr03')
104
- # imap.create('Mail/sent-apr03')
139
+ # *NOTE:* Most servers support atomic +MOVE+, but not all do.
140
+ # source = "Mail/sent-mail"
141
+ # destination = "Mail/sent-apr03"
142
+ #
143
+ # # The "BEFORE" and "AFTER" search criteria are not inclusive.
144
+ # since = Date.parse("2003-04-01").prev_day
145
+ # before = Date.parse("2003-05-01")
146
+ #
147
+ # if imap.list("", destination).empty?
148
+ # imap.create(destination)
105
149
  # end
106
- # imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id|
107
- # imap.copy(message_id, "Mail/sent-apr03")
108
- # imap.store(message_id, "+FLAGS", [:Deleted])
150
+ # imap.select(source)
151
+ # search_result = imap.uid_search(["SINCE", since, "BEFORE", before])
152
+ # imap.uid_move(search_result, destination)
153
+ #
154
+ # When atomic +MOVE+ is not supported, the messages can be copied and deleted.
155
+ # \IMAP message deletion requires two steps: set <tt>\Deleted</tt> flag to
156
+ # mark a message for deletion, then expunge the <tt>\Deleted</tt> messages.
157
+ #
158
+ # Use #uid_copy (or #copy) to copy messages to another mailbox.<br>
159
+ # Use #uid_store (or #store) to mark messages for deletion.<br>
160
+ # Use #uid_expunge (or #expunge) to remove deleted messages.
161
+ #
162
+ # *NOTE:* #uid_expunge is not supported by every server, and #expunge removes
163
+ # _all_ <tt>\Deleted</tt> messages in the mailbox, even if the
164
+ # <tt>\Deleted</tt> flag was added by another session.
165
+ #
166
+ # if imap.capable?(:MOVE) || imap.capable?(:IMAP4rev2)
167
+ # imap.uid_move(search_result, destination)
168
+ # else
169
+ # # Atomic MOVE is not supported. Copy, delete, and expunge.
170
+ # imap.uid_copy(search_result, destination)
171
+ # imap.uid_store(search_result, "+FLAGS", [:Deleted])
172
+ # if imap.capable?(:UIDPLUS) || imap.capable?(:IMAP4rev2)
173
+ # imap.uid_expunge(search_result)
174
+ # else
175
+ # # NOTE: This may expunge _other_ deleted messages, too.
176
+ # imap.expunge
177
+ # end
109
178
  # end
110
- # imap.expunge
179
+ #
180
+ # Additional error handling may be required for non-atomic moves. Smaller
181
+ # batch sizes are recommended.
111
182
  #
112
183
  # == Capabilities
113
184
  #
@@ -289,7 +360,9 @@ module Net
289
360
  #
290
361
  # == What's here?
291
362
  #
292
- # * {Connection control}[rdoc-ref:Net::IMAP@Connection+control+methods]
363
+ # * {Client configuration}[rdoc-ref:Net::IMAP@Client+configuration]
364
+ # * {Connection control}[rdoc-ref:Net::IMAP@Connection+control]
365
+ # * {Connection attributes}[rdoc-ref:Net::IMAP@Connection+attributes]
293
366
  # * {Server capabilities}[rdoc-ref:Net::IMAP@Server+capabilities]
294
367
  # * {Handling server responses}[rdoc-ref:Net::IMAP@Handling+server+responses]
295
368
  # * {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands]
@@ -300,35 +373,76 @@ module Net
300
373
  # * {for the "logout" state}[rdoc-ref:Net::IMAP@Logout+state]
301
374
  # * {IMAP extension support}[rdoc-ref:Net::IMAP@IMAP+extension+support]
302
375
  #
303
- # === Connection control methods
376
+ # === Client configuration
377
+ # - #host: The hostname this client connected to.
378
+ # - #port: The port this client connected to.
379
+ # - #config: The client configuration. See Net::IMAP::Config.
380
+ # - #open_timeout: Delegates to {config.open_timeout}[rdoc-ref:Config#open_timeout].
381
+ # - #idle_response_timeout: Delegates to {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout].
382
+ # - #max_response_size: Delegates to {config.max_response_size}[rdoc-ref:Config#max_response_size].
383
+ # - #ssl_ctx_params: Returns the params that were sent to {`ssl_ctx.set_params`}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params].
384
+ #
385
+ # <em>*NOTE:* Presence does _NOT_ indicate a secure TLS connection.</em>
386
+ #
387
+ # === Connection control
304
388
  #
305
389
  # - Net::IMAP.new: Creates a new \IMAP client which connects immediately and
306
390
  # waits for a successful server greeting before the method returns.
307
- # - #connection_state: Returns the connection state.
308
391
  # - #starttls: Asks the server to upgrade a clear-text connection to use TLS.
392
+ #
393
+ # <em>Requires the +STARTTLS+ capability.</em>
394
+ #
395
+ # <em>*NOTE:* Connecting to the implicit TLS port should be preferred.</em>
309
396
  # - #logout: Tells the server to end the session. Enters the +logout+ state.
397
+ # - #logout!: Calls #logout then #disconnect, converting most errors into
398
+ # warnings.
310
399
  # - #disconnect: Disconnects the connection (without sending #logout first).
400
+ #
401
+ # === Connection attributes
402
+ #
403
+ # - #greeting: The server's initial untagged response.
404
+ # - #connection_state: Returns the connection state.
311
405
  # - #disconnected?: True if the connection has been closed.
406
+ # - #tls_verified?: Returns whether TLS is used and #host has been verified.
407
+ # - #tls_connected?: Returns +true+ after TLS negotiation has completed.
408
+ #
409
+ # <em>*NOTE:* This does _NOT_ indicate a secure TLS connection.</em>
410
+ # - #tls_socket?: Returns +true+ after TLS negotiation has started.
411
+ #
412
+ # <em>*NOTE:* This does _NOT_ indicate a secure TLS connection.</em>
413
+ # - #ssl_ctx: Returns the {SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html]
414
+ # after attempting to start TLS.
415
+ #
416
+ # <em>*NOTE:* Presence does _NOT_ indicate a secure TLS connection.</em>
312
417
  #
313
418
  # === Server capabilities
314
419
  #
420
+ # ==== Cached capabilities
315
421
  # - #capable?: Returns whether the server supports a given capability.
316
422
  # - #capabilities: Returns the server's capabilities as an array of strings.
423
+ # - #capabilities_cached?: Returns whether capabilities are cached.
424
+ # - #clear_cached_capabilities: Clears cached capabilities.
425
+ #
426
+ # *NOTE:* The cache is automatically cleared when capabilities can change.
427
+ #
428
+ # ==== \SASL Auth mechanisms
429
+ #
317
430
  # - #auth_capable?: Returns whether the server advertises support for a given
318
431
  # SASL mechanism, for use with #authenticate.
319
432
  # - #auth_mechanisms: Returns the #authenticate SASL mechanisms which
320
433
  # the server claims to support as an array of strings.
321
- # - #clear_cached_capabilities: Clears cached capabilities.
322
434
  #
323
- # <em>The capabilities cache is automatically cleared after completing
324
- # #starttls, #login, or #authenticate.</em>
325
- # - #capability: Sends the +CAPABILITY+ command and returns the #capabilities.
435
+ # ==== Enabled capabilities
326
436
  #
327
- # <em>In general, #capable? should be used rather than explicitly sending a
328
- # +CAPABILITY+ command to the server.</em>
437
+ # *NOTE:* The following require the +ENABLE+ or +IMAP4rev2+ server capability.
438
+ # - #enable: Enables backwards incompatible server extensions.
439
+ # - #enabled: Returns a set of enabled server extensions.
440
+ # - #enabled?: Returns whether a server extension has been enabled.
441
+ # - #utf8_enabled?: Returns whether UTF-8 string encoding has been enabled.
329
442
  #
330
443
  # === Handling server responses
331
444
  #
445
+ # ==== Stored responses methods
332
446
  # - #greeting: The server's initial untagged response, which can indicate a
333
447
  # pre-authenticated connection.
334
448
  # - #responses: Yields unhandled UntaggedResponse#data and <em>non-+nil+</em>
@@ -336,6 +450,8 @@ module Net
336
450
  # - #extract_responses: Removes and returns the responses for which the block
337
451
  # returns a true value.
338
452
  # - #clear_responses: Deletes unhandled data from #responses and returns it.
453
+ #
454
+ # ==== Response handler methods
339
455
  # - #add_response_handler: Add a block to be called inside the receiver thread
340
456
  # with every server response.
341
457
  # - #response_handlers: Returns the list of response handlers.
@@ -359,8 +475,9 @@ module Net
359
475
  #
360
476
  # - #capability: Returns the server's capabilities as an array of strings.
361
477
  #
362
- # <em>In general,</em> #capable? <em>should be used rather than explicitly
363
- # sending a +CAPABILITY+ command to the server.</em>
478
+ # <em>*NOTE:* Use {cached capabilities
479
+ # methods}[rdoc-ref:Net::IMAP@Server+Capabilities] instead, to avoid sending
480
+ # unnecessary commands to the server.</em>
364
481
  # - #noop: Allows the server to send unsolicited untagged #responses.
365
482
  # - #logout: Tells the server to end the session. Enters the +logout+ state.
366
483
  #
@@ -372,6 +489,8 @@ module Net
372
489
  # - #starttls: Upgrades a clear-text connection to use TLS.
373
490
  #
374
491
  # <em>Requires the +STARTTLS+ capability.</em>
492
+ #
493
+ # <em>*NOTE:* Connecting to the implicit TLS port should be preferred.</em>
375
494
  # - #authenticate: Identifies the client to the server using the given
376
495
  # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
377
496
  # and credentials. Enters the +authenticated+ state.
@@ -448,10 +567,10 @@ module Net
448
567
  #
449
568
  # ==== RFC9051: +IMAP4rev2+
450
569
  #
451
- # Although IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] is not supported
452
- # yet, Net::IMAP supports several extensions that have been folded into it:
453
- # +ENABLE+, +IDLE+, +LITERAL-+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+,
454
- # +UNSELECT+, <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
570
+ # Although IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051] is not fully
571
+ # supported yet, Net::IMAP supports several extensions that have been folded
572
+ # into it: +ENABLE+, +IDLE+, +LITERAL-+, +MOVE+, +NAMESPACE+, +SASL-IR+,
573
+ # +UIDPLUS+, +UNSELECT+, <tt>STATUS=SIZE</tt>, and the fetch side of +BINARY+.
455
574
  # Commands for these extensions are listed with the {Core IMAP
456
575
  # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.
457
576
  #
@@ -552,6 +671,7 @@ module Net
552
671
  # ==== RFC6855: <tt>UTF8=ACCEPT</tt>, <tt>UTF8=ONLY</tt>
553
672
  #
554
673
  # - See #enable for information about support for UTF-8 string encoding.
674
+ # - #utf8_enabled?: Returns whether UTF-8 string encoding has been enabled.
555
675
  #
556
676
  # ==== RFC7162: +CONDSTORE+
557
677
  #
@@ -813,7 +933,7 @@ module Net
813
933
  # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
814
934
  #
815
935
  class IMAP < Protocol
816
- VERSION = "0.6.4.1"
936
+ VERSION = "0.6.8"
817
937
 
818
938
  # Aliases for supported capabilities, to be used with the #enable command.
819
939
  ENABLE_ALIASES = {
@@ -821,6 +941,11 @@ module Net
821
941
  "UTF8=ONLY" => "UTF8=ACCEPT",
822
942
  }.freeze
823
943
 
944
+ # Aliases for supported capabilities, to be used with #enabled?.
945
+ ENABLED_ALIASES = {
946
+ utf8: Set.new(%w[UTF8=ACCEPT IMAP4REV2]).freeze,
947
+ }.freeze
948
+
824
949
  dir = File.expand_path("imap", __dir__)
825
950
  autoload :ConnectionState, "#{dir}/connection_state"
826
951
  autoload :ResponseReader, "#{dir}/response_reader"
@@ -916,10 +1041,15 @@ module Net
916
1041
 
917
1042
  # Returns the
918
1043
  # {SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html]
919
- # used by the SSLSocket when TLS is attempted, even when the TLS handshake
920
- # is unsuccessful. The context object will be frozen.
1044
+ # used by the
1045
+ # {OpenSSL::SSL::SSLSocket}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLSocket.html].
1046
+ # when TLS is attempted, even when the TLS handshake is unsuccessful. The
1047
+ # context object will be frozen.
921
1048
  #
922
1049
  # Returns +nil+ for a plaintext connection.
1050
+ #
1051
+ # *NOTE:* The presence of this attribute does _NOT_ indicate that the
1052
+ # connection is using TLS.
923
1053
  attr_reader :ssl_ctx
924
1054
 
925
1055
  # Returns the parameters that were sent to #ssl_ctx
@@ -927,6 +1057,9 @@ module Net
927
1057
  # when the connection tries to use TLS (even when unsuccessful).
928
1058
  #
929
1059
  # Returns +false+ for a plaintext connection.
1060
+ #
1061
+ # *NOTE:* The presence of this attribute does _NOT_ indicate that the
1062
+ # connection is using TLS.
930
1063
  attr_reader :ssl_ctx_params
931
1064
 
932
1065
  # Returns the current connection state.
@@ -1110,12 +1243,12 @@ module Net
1110
1243
  @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(ssl)
1111
1244
 
1112
1245
  # Basic Client State
1113
- @utf8_strings = false
1114
1246
  @debug_output_bol = true
1115
1247
  @exception = nil
1116
1248
  @greeting = nil
1117
1249
  @capabilities = nil
1118
- @tls_verified = false
1250
+ @enabled = Set.new
1251
+ @tls_connected = @tls_verified = false
1119
1252
  @connection_state = ConnectionState::NotAuthenticated.new
1120
1253
 
1121
1254
  # Client Protocol Receiver
@@ -1174,12 +1307,11 @@ module Net
1174
1307
  end
1175
1308
 
1176
1309
  private def inspect_tls_state
1177
- if tls_verified?
1178
- "TLS"
1179
- elsif ssl_ctx && @sock.kind_of?(OpenSSL::SSL::SSLSocket)
1180
- "TLS (#{@sock.session ? "NOT VERIFIED" : "NOT ESTABLISHED"})"
1181
- else
1182
- "PLAINTEXT#{" (TLS NOT STARTED)" if ssl_ctx}"
1310
+ if tls_verified? then "TLS"
1311
+ elsif tls_connected? then "TLS (NOT VERIFIED)"
1312
+ elsif tls_socket? then "TLS (NOT ESTABLISHED)"
1313
+ elsif ssl_ctx then "PLAINTEXT (TLS NOT STARTED)"
1314
+ else "PLAINTEXT"
1183
1315
  end
1184
1316
  end
1185
1317
 
@@ -1188,14 +1320,39 @@ module Net
1188
1320
  # but peer verification was disabled.
1189
1321
  def tls_verified?; @tls_verified end
1190
1322
 
1323
+ # Returns +true+ after
1324
+ # {OpenSSL::SSL::SSLSocket#connect}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLSocket.html#method-i-connect]
1325
+ # completes successfully.
1326
+ #
1327
+ # <em>*NOTE:* This does _NOT_ indicate that the remote hostname has been
1328
+ # verified.</em>
1329
+ #
1330
+ # This does _not_ indicate current connection state. It will continue to
1331
+ # return +true+ even after a successful connection has disconnected.
1332
+ #
1333
+ # See #tls_verified?
1334
+ def tls_connected?; @tls_connected end
1335
+
1336
+ # Returns +true+ when the connection is a
1337
+ # {OpenSSL::SSL::SSLSocket}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLSocket.html]
1338
+ #
1339
+ # <em>*NOTE:* This does _NOT_ indicate that a TLS session has been
1340
+ # established or that remote hostname has been verified.</em>
1341
+ #
1342
+ # This only indicates that TLS negotiation has started.
1343
+ #
1344
+ # See #tls_verified?
1345
+ def tls_socket?; @sock.kind_of?(OpenSSL::SSL::SSLSocket) end
1346
+
1191
1347
  # Disconnects from the server.
1192
1348
  #
1193
1349
  # Waits for receiver thread to close before returning, except when called
1194
1350
  # from inside the connection mutex such as from a response handler. Slow or
1195
1351
  # stuck response handlers can cause #disconnect to hang until they complete.
1352
+ # Use +timeout+ to limit how long to wait for the receiver thread to exit.
1196
1353
  #
1197
1354
  # Related: #logout, #logout!
1198
- def disconnect
1355
+ def disconnect(timeout: nil)
1199
1356
  in_logout_state = try_state_logout?
1200
1357
  return if disconnected?
1201
1358
  in_receiver_thread = Thread.current == @receiver_thread
@@ -1207,7 +1364,7 @@ module Net
1207
1364
  @receiver_thread.raise(e) unless in_receiver_thread
1208
1365
  end
1209
1366
  @sock.close
1210
- @receiver_thread.join unless mon_owned? || in_receiver_thread
1367
+ @receiver_thread.join(timeout) unless mon_owned? || in_receiver_thread
1211
1368
  raise e if e
1212
1369
  ensure
1213
1370
  # Try again after shutting down the receiver thread. With no reciever
@@ -1469,7 +1626,7 @@ module Net
1469
1626
  end
1470
1627
  if error
1471
1628
  disconnect
1472
- raise error
1629
+ reraise error
1473
1630
  end
1474
1631
  unless handled
1475
1632
  disconnect
@@ -3160,12 +3317,48 @@ module Net
3160
3317
  synchronize do
3161
3318
  send_command("ENABLE", *capabilities)
3162
3319
  result = clear_responses("ENABLED").last || []
3163
- @utf8_strings ||= result.include? "UTF8=ACCEPT"
3164
- @utf8_strings ||= result.include? "IMAP4REV2"
3320
+ @enabled.merge(result.map(&:upcase))
3165
3321
  result
3166
3322
  end
3167
3323
  end
3168
3324
 
3325
+ # Returns whether UTF-8 string encoding has been enabled for the connection.
3326
+ #
3327
+ # This is currently identical to calling #enabled? with +:utf8+.
3328
+ #
3329
+ # See #enable and #enabled?.
3330
+ def utf8_enabled?; enabled?(:utf8) end
3331
+
3332
+ # Returns whether +capability+ is in the set of #enabled capabilities,
3333
+ # matched case-insensitively.
3334
+ #
3335
+ # When +capability+ is +:utf8+, it matches if _either_
3336
+ # <tt>"UTF8=ACCEPT"</tt> or <tt>"IMAP4REV2"</tt> is enabled.
3337
+ #
3338
+ # See #enable and #utf8_enabled?.
3339
+ def enabled?(capability)
3340
+ case capability
3341
+ in String
3342
+ capability = capability.upcase
3343
+ synchronize { @enabled.include?(capability) }
3344
+ in Symbol
3345
+ capabilities = ENABLED_ALIASES[capability] or
3346
+ raise ArgumentError, "unknown capability alias: #{capability}"
3347
+ synchronize { @enabled.intersect?(capabilities) }
3348
+ else
3349
+ raise TypeError, "expected capability to be String or Symbol, " \
3350
+ "got %s" % [capability.class]
3351
+ end
3352
+ end
3353
+
3354
+ # Returns a set of enabled capabilities for the connection, as upper-cased
3355
+ # strings.
3356
+ #
3357
+ # See #enable and #enabled?.
3358
+ def enabled
3359
+ synchronize { @enabled.dup }
3360
+ end
3361
+
3169
3362
  # Sends an {IDLE command [RFC2177 §3]}[https://www.rfc-editor.org/rfc/rfc6851#section-3]
3170
3363
  # {[IMAP4rev2 §6.3.13]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.13]
3171
3364
  # that waits for notifications of new or expunged messages. Yields
@@ -3202,8 +3395,9 @@ module Net
3202
3395
 
3203
3396
  synchronize do
3204
3397
  tag = Thread.current[:net_imap_tag] = generate_tag
3205
- guard_against_tagged_response_skipping_handler!(tag, "IDLE")
3398
+ command = Command[tag:, name: "IDLE"]
3206
3399
  put_string("#{tag} IDLE#{CRLF}")
3400
+ finish_sending_command(command)
3207
3401
 
3208
3402
  begin
3209
3403
  add_response_handler(&response_handler)
@@ -3211,7 +3405,7 @@ module Net
3211
3405
  @idle_done_cond.wait(timeout)
3212
3406
  @idle_done_cond = nil
3213
3407
  if @receiver_thread_terminating
3214
- raise @exception || Net::IMAP::Error.new("connection closed")
3408
+ reraise @exception || Net::IMAP::Error.new("connection closed")
3215
3409
  end
3216
3410
  ensure
3217
3411
  remove_response_handler(response_handler)
@@ -3220,6 +3414,9 @@ module Net
3220
3414
  response = get_tagged_response(tag, "IDLE", idle_response_timeout)
3221
3415
  end
3222
3416
  end
3417
+ rescue InvalidResponseError
3418
+ disconnect
3419
+ raise
3223
3420
  end
3224
3421
 
3225
3422
  return response
@@ -3279,7 +3476,7 @@ module Net
3279
3476
  # Prints a warning and returns the mutable responses hash.
3280
3477
  # <em>This is not thread-safe.</em>
3281
3478
  #
3282
- # [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
3479
+ # [+:frozen_dup+ <em>(default since +v0.6+)</em>]
3283
3480
  # Returns a frozen copy of the unhandled responses hash, with frozen
3284
3481
  # array values.
3285
3482
  #
@@ -3380,7 +3577,7 @@ module Net
3380
3577
  def clear_responses(type = nil)
3381
3578
  synchronize {
3382
3579
  if type
3383
- @responses.delete(type) || []
3580
+ @responses.delete(type.to_s.upcase) || []
3384
3581
  else
3385
3582
  @responses.dup.transform_values(&:freeze)
3386
3583
  .tap { _1.default = [].freeze }
@@ -3505,73 +3702,34 @@ module Net
3505
3702
  s = Socket.tcp(host, port, :connect_timeout => open_timeout)
3506
3703
  s.setsockopt(:SOL_SOCKET, :SO_KEEPALIVE, true)
3507
3704
  s
3508
- rescue Errno::ETIMEDOUT
3705
+ rescue Errno::ETIMEDOUT, IO::TimeoutError
3509
3706
  raise Net::OpenTimeout, "Timeout to open TCP connection to " +
3510
3707
  "#{host}:#{port} (exceeds #{open_timeout} seconds)"
3511
3708
  end
3512
3709
 
3513
3710
  def receive_responses
3514
- connection_closed = false
3515
- until connection_closed
3516
- synchronize do
3517
- @exception = nil
3518
- end
3519
- begin
3520
- resp = get_response
3521
- rescue Exception => e
3522
- synchronize do
3523
- state_logout!
3524
- @sock.close
3525
- @exception = e
3526
- end
3527
- break
3528
- end
3529
- unless resp
3530
- synchronize do
3531
- @exception = EOFError.new("end of file reached")
3532
- end
3533
- break
3534
- end
3535
- begin
3536
- synchronize do
3537
- case resp
3538
- when TaggedResponse
3539
- @tagged_responses[resp.tag] = resp
3540
- @tagged_response_arrival.broadcast
3541
- case resp.tag
3542
- when @logout_command_tag
3543
- state_logout!
3544
- return
3545
- when @continued_command_tag
3546
- @continuation_request_exception =
3547
- RESPONSE_ERRORS[resp.name].new(resp)
3548
- @continuation_request_arrival.signal
3549
- end
3550
- when UntaggedResponse
3551
- record_untagged_response(resp)
3552
- if resp.name == "BYE" && @logout_command_tag.nil?
3553
- state_logout!
3554
- @sock.close
3555
- @exception = ByeResponseError.new(resp)
3556
- connection_closed = true
3557
- end
3558
- when ContinuationRequest
3559
- @continuation_request_arrival.signal
3560
- end
3561
- state_unselected! if resp in {data: {code: {name: "CLOSED"}}}
3562
- @response_handlers.each do |handler|
3563
- handler.call(resp)
3564
- end
3565
- end
3566
- rescue Exception => e
3567
- @exception = e
3568
- synchronize do
3569
- @tagged_response_arrival.broadcast
3570
- @continuation_request_arrival.broadcast
3571
- end
3572
- end
3711
+ exception = nil
3712
+ loop do
3713
+ resp = get_response or raise EOFError, "end of file reached"
3714
+ handle_response(resp) or return
3573
3715
  end
3716
+ rescue Exception => exception
3717
+ # NOTE: this rescue clause is only capturing the exception for the ensure
3718
+ # clause. Using `$!` in the ensure clause seems to trigger a weird
3719
+ # TruffleRuby bug: https://github.com/truffleruby/truffleruby/issues/4308
3720
+ #
3721
+ # We don't assign @exception directly here, because we want that to be
3722
+ # atomically synchronized with all of the other changes in `ensure`.
3723
+ raise
3724
+ ensure
3574
3725
  synchronize do
3726
+ if exception
3727
+ # Handling exceptions here, not in a rescue clause, so the lock isn't
3728
+ # released and reacquired between rescue and ensure clauses.
3729
+ @exception ||= exception
3730
+ @sock.close
3731
+ end
3732
+ state_logout!
3575
3733
  @receiver_thread_terminating = true
3576
3734
  @tagged_response_arrival.broadcast
3577
3735
  @continuation_request_arrival.broadcast
@@ -3579,36 +3737,6 @@ module Net
3579
3737
  @idle_done_cond.signal
3580
3738
  end
3581
3739
  end
3582
- ensure
3583
- state_logout!
3584
- end
3585
-
3586
- def get_tagged_response(tag, cmd, timeout = nil)
3587
- if timeout
3588
- deadline = Time.now + timeout
3589
- end
3590
- until @tagged_responses.key?(tag)
3591
- raise @exception if @exception
3592
- if timeout
3593
- timeout = deadline - Time.now
3594
- if timeout <= 0
3595
- return nil
3596
- end
3597
- end
3598
- @tagged_response_arrival.wait(timeout)
3599
- end
3600
- resp = @tagged_responses.delete(tag)
3601
- case resp.name
3602
- when /\A(?:OK)\z/ni
3603
- return resp
3604
- when /\A(?:NO)\z/ni
3605
- raise NoResponseError, resp
3606
- when /\A(?:BAD)\z/ni
3607
- raise BadResponseError, resp
3608
- else
3609
- disconnect
3610
- raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw_data.chomp]
3611
- end
3612
3740
  end
3613
3741
 
3614
3742
  def get_response
@@ -3621,6 +3749,47 @@ module Net
3621
3749
  #############################
3622
3750
  # built-in response handlers
3623
3751
 
3752
+ def handle_response(resp)
3753
+ connection_closed = false
3754
+ synchronize do
3755
+ case resp
3756
+ when TaggedResponse
3757
+ @tagged_responses[resp.tag] = resp
3758
+ @tagged_response_arrival.broadcast
3759
+ case resp.tag
3760
+ when @logout_command_tag
3761
+ state_logout!
3762
+ return
3763
+ when @continued_command_tag
3764
+ @continuation_request_exception =
3765
+ RESPONSE_ERRORS[resp.name].new(resp)
3766
+ @continuation_request_arrival.signal
3767
+ end
3768
+ when UntaggedResponse
3769
+ record_untagged_response(resp)
3770
+ if resp.name == "BYE" && @logout_command_tag.nil?
3771
+ state_logout!
3772
+ @sock.close
3773
+ @exception = ByeResponseError.new(resp)
3774
+ connection_closed = true
3775
+ end
3776
+ when ContinuationRequest
3777
+ @continuation_request_arrival.signal
3778
+ end
3779
+ state_unselected! if resp in {data: {code: {name: "CLOSED"}}}
3780
+ @response_handlers.each do |handler|
3781
+ handler.call(resp)
3782
+ end
3783
+ rescue Exception => e
3784
+ @exception = e
3785
+ @tagged_response_arrival.broadcast
3786
+ @continuation_request_arrival.broadcast
3787
+ ensure
3788
+ @exception = nil unless connection_closed
3789
+ end
3790
+ !connection_closed
3791
+ end
3792
+
3624
3793
  # store name => [..., data]
3625
3794
  def record_untagged_response(resp)
3626
3795
  @responses[resp.name] << resp.data
@@ -3657,18 +3826,17 @@ module Net
3657
3826
  end
3658
3827
 
3659
3828
  def send_command(cmd, *args, &block)
3829
+ args.each do validate_data _1 end
3660
3830
  synchronize do
3661
- args.each do |i|
3662
- validate_data(i)
3663
- end
3664
3831
  tag = generate_tag
3832
+ command = Command[tag:, name: cmd]
3665
3833
  put_string(tag + " " + cmd)
3666
3834
  args.each do |i|
3667
3835
  put_string(" ")
3668
3836
  send_data(i, tag)
3669
3837
  end
3670
3838
  @logout_command_tag = tag if cmd == "LOGOUT"
3671
- guard_against_tagged_response_skipping_handler!(tag, cmd)
3839
+ finish_sending_command(command)
3672
3840
  add_response_handler(&block) if block
3673
3841
  begin
3674
3842
  put_string(CRLF)
@@ -3676,20 +3844,78 @@ module Net
3676
3844
  ensure
3677
3845
  remove_response_handler(block) if block
3678
3846
  end
3847
+ rescue InvalidResponseError
3848
+ disconnect
3849
+ raise
3679
3850
  end
3680
- rescue InvalidResponseError
3681
- disconnect
3682
- raise
3683
3851
  end
3684
3852
 
3685
- def guard_against_tagged_response_skipping_handler!(tag, cmd)
3686
- return unless (resp = @tagged_responses[tag])&.name&.upcase == "OK"
3687
- raise InvalidResponseError, format(
3688
- "Received tagged 'OK' to incomplete %s command (tag=%s). " \
3689
- "This could indicate a malicious server, a man-in-the-middle, or " \
3690
- "client-side command injection. Disconnecting.",
3691
- cmd, tag
3692
- )
3853
+ # NOTE: This must be synchronized with sending the command's final CRLF and
3854
+ # adding any command-related response handlers.
3855
+ def finish_sending_command(command)
3856
+ if (response = @tagged_responses[command.tag])&.name&.casecmp?("OK")
3857
+ raise InvalidTaggedResponseError.new(:incomplete, command:, response:)
3858
+ end
3859
+ end
3860
+
3861
+ def get_tagged_response(tag, cmd, timeout = nil)
3862
+ if timeout
3863
+ deadline = Time.now + timeout
3864
+ end
3865
+ until @tagged_responses.key?(tag)
3866
+ reraise @exception
3867
+ if timeout
3868
+ timeout = deadline - Time.now
3869
+ if timeout <= 0
3870
+ return nil
3871
+ end
3872
+ end
3873
+ @tagged_response_arrival.wait(timeout)
3874
+ end
3875
+ resp = @tagged_responses.delete(tag)
3876
+ case resp.name
3877
+ when /\A(?:OK)\z/ni
3878
+ return resp
3879
+ when /\A(?:NO)\z/ni
3880
+ raise NoResponseError, resp
3881
+ when /\A(?:BAD)\z/ni
3882
+ raise BadResponseError, resp
3883
+ else
3884
+ disconnect
3885
+ raise InvalidResponseError, "invalid tagged resp: %p" % [resp.raw_data.chomp]
3886
+ end
3887
+ end
3888
+
3889
+ # Raises a copy of +exception+ with an updated +backtrace+ and +cause+, or
3890
+ # returns +nil+ when +exception+ is falsey.
3891
+ #
3892
+ # +backtrace+ is set to reflect the current caller.
3893
+ #
3894
+ # +cause+ is set to the original exception, _if_ the original has its own
3895
+ # backtrace or cause. Otherwise, the original was never raised and the
3896
+ # default cause is used.
3897
+ #
3898
+ # This is meant for exceptions that may have been created by another thread.
3899
+ # Raising them directly gives a misleading backtrace, making it hard to
3900
+ # discover where the errors originate. Although it is sometimes more
3901
+ # appropriate to raise a wrapping exception, that changes the API and forces
3902
+ # updates to users' `rescue` pattern matching.
3903
+ def reraise(exception)
3904
+ return unless exception
3905
+ copy = exception.dup
3906
+ # NOTE: set_backtrace(caller_locations) doesn't work for CRuby <= 3.3.
3907
+ # and set_backtrace(nil) doesn't work for TruffleRuby 34.0.0:
3908
+ # https://github.com/truffleruby/truffleruby/issues/4296
3909
+ if RUBY_ENGINE == "truffleruby"
3910
+ copy.set_backtrace caller_locations
3911
+ else
3912
+ copy.set_backtrace nil
3913
+ end
3914
+ if exception.cause || exception.backtrace
3915
+ raise copy, cause: exception
3916
+ else
3917
+ raise copy
3918
+ end
3693
3919
  end
3694
3920
 
3695
3921
  def generate_tag
@@ -3820,6 +4046,9 @@ module Net
3820
4046
  raise ArgumentError, "partial can only be used with uid_fetch"
3821
4047
  end
3822
4048
  set = SequenceSet[set]
4049
+ mod in nil | Array or
4050
+ raise TypeError, "expected nil or array, got #{mod.class}"
4051
+ mod &&= mod.dup
3823
4052
  if partial
3824
4053
  mod ||= []
3825
4054
  mod << "PARTIAL" << PartialRange[partial]
@@ -3912,7 +4141,7 @@ module Net
3912
4141
 
3913
4142
  def build_ssl_ctx(ssl)
3914
4143
  if ssl
3915
- params = (Hash.try_convert(ssl) || {}).freeze
4144
+ params = (Hash.try_convert(ssl) || {}).clone(freeze: true)
3916
4145
  context = OpenSSL::SSL::SSLContext.new
3917
4146
  context.set_params(params)
3918
4147
  context.setup
@@ -3931,6 +4160,7 @@ module Net
3931
4160
  @sock.sync_close = true
3932
4161
  @sock.hostname = @host if @sock.respond_to? :hostname=
3933
4162
  ssl_socket_connect(@sock, open_timeout)
4163
+ @tls_connected = true
3934
4164
  if ssl_ctx.verify_mode != OpenSSL::SSL::VERIFY_NONE
3935
4165
  @sock.post_connection_check(@host)
3936
4166
  @tls_verified = true