net-imap 0.4.12 → 0.5.5

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.

Potentially problematic release.


This version of net-imap might be problematic. Click here for more details.

Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile +7 -1
  3. data/README.md +10 -4
  4. data/docs/styles.css +75 -14
  5. data/lib/net/imap/authenticators.rb +2 -2
  6. data/lib/net/imap/command_data.rb +61 -48
  7. data/lib/net/imap/config/attr_accessors.rb +75 -0
  8. data/lib/net/imap/config/attr_inheritance.rb +90 -0
  9. data/lib/net/imap/config/attr_type_coercion.rb +61 -0
  10. data/lib/net/imap/config.rb +402 -0
  11. data/lib/net/imap/data_encoding.rb +3 -3
  12. data/lib/net/imap/data_lite.rb +226 -0
  13. data/lib/net/imap/deprecated_client_options.rb +8 -5
  14. data/lib/net/imap/errors.rb +6 -0
  15. data/lib/net/imap/esearch_result.rb +180 -0
  16. data/lib/net/imap/fetch_data.rb +126 -47
  17. data/lib/net/imap/response_data.rb +126 -193
  18. data/lib/net/imap/response_parser/parser_utils.rb +11 -6
  19. data/lib/net/imap/response_parser.rb +159 -21
  20. data/lib/net/imap/sasl/anonymous_authenticator.rb +3 -3
  21. data/lib/net/imap/sasl/authentication_exchange.rb +52 -20
  22. data/lib/net/imap/sasl/authenticators.rb +8 -4
  23. data/lib/net/imap/sasl/client_adapter.rb +77 -26
  24. data/lib/net/imap/sasl/cram_md5_authenticator.rb +4 -4
  25. data/lib/net/imap/sasl/digest_md5_authenticator.rb +218 -56
  26. data/lib/net/imap/sasl/external_authenticator.rb +2 -2
  27. data/lib/net/imap/sasl/gs2_header.rb +7 -7
  28. data/lib/net/imap/sasl/login_authenticator.rb +4 -3
  29. data/lib/net/imap/sasl/oauthbearer_authenticator.rb +6 -6
  30. data/lib/net/imap/sasl/plain_authenticator.rb +7 -7
  31. data/lib/net/imap/sasl/protocol_adapters.rb +60 -4
  32. data/lib/net/imap/sasl/scram_authenticator.rb +8 -8
  33. data/lib/net/imap/sasl.rb +7 -4
  34. data/lib/net/imap/sasl_adapter.rb +0 -1
  35. data/lib/net/imap/search_result.rb +2 -2
  36. data/lib/net/imap/sequence_set.rb +28 -24
  37. data/lib/net/imap/stringprep/nameprep.rb +1 -1
  38. data/lib/net/imap/stringprep/trace.rb +4 -4
  39. data/lib/net/imap/vanished_data.rb +56 -0
  40. data/lib/net/imap.rb +1001 -319
  41. data/net-imap.gemspec +3 -3
  42. data/rakelib/rfcs.rake +2 -0
  43. data/rakelib/string_prep_tables_generator.rb +2 -0
  44. metadata +11 -10
  45. data/.github/dependabot.yml +0 -6
  46. data/.github/workflows/pages.yml +0 -46
  47. data/.github/workflows/push_gem.yml +0 -48
  48. data/.github/workflows/test.yml +0 -31
  49. data/.gitignore +0 -12
  50. data/.mailmap +0 -13
@@ -2,9 +2,12 @@
2
2
 
3
3
  module Net
4
4
  class IMAP < Protocol
5
+ autoload :ESearchResult, "#{__dir__}/esearch_result"
5
6
  autoload :FetchData, "#{__dir__}/fetch_data"
7
+ autoload :UIDFetchData, "#{__dir__}/fetch_data"
6
8
  autoload :SearchResult, "#{__dir__}/search_result"
7
9
  autoload :SequenceSet, "#{__dir__}/sequence_set"
10
+ autoload :VanishedData, "#{__dir__}/vanished_data"
8
11
 
9
12
  # Net::IMAP::ContinuationRequest represents command continuation requests.
10
13
  #
@@ -157,13 +160,20 @@ module Net
157
160
  # The raw response data.
158
161
  end
159
162
 
160
- # Net::IMAP::ResponseText represents texts of responses.
163
+ # ResponseText represents texts of responses.
161
164
  #
162
165
  # The text may be prefixed by a ResponseCode.
163
166
  #
164
- # ResponseText is returned from TaggedResponse#data, or from
165
- # UntaggedResponse#data when the response type is a "condition" ("OK", "NO",
166
- # "BAD", "PREAUTH", or "BYE").
167
+ # ResponseText is returned from TaggedResponse#data or
168
+ # UntaggedResponse#data for
169
+ # {"status responses"}[https://www.rfc-editor.org/rfc/rfc3501#section-7.1]:
170
+ # * every TaggedResponse, name[rdoc-ref:TaggedResponse#name] is always
171
+ # "+OK+", "+NO+", or "+BAD+".
172
+ # * any UntaggedResponse when name[rdoc-ref:UntaggedResponse#name] is
173
+ # "+OK+", "+NO+", "+BAD+", "+PREAUTH+", or "+BYE+".
174
+ #
175
+ # Note that these "status responses" are confusingly _not_ the same as the
176
+ # +STATUS+ UntaggedResponse (see IMAP#status and StatusData).
167
177
  class ResponseText < Struct.new(:code, :text)
168
178
  # Used to avoid an allocation when ResponseText is empty
169
179
  EMPTY = new(nil, "").freeze
@@ -181,32 +191,35 @@ module Net
181
191
  # Returns the response text, not including any response code
182
192
  end
183
193
 
184
- # Net::IMAP::ResponseCode represents response codes. Response codes can be
185
- # retrieved from ResponseText#code and can be included in any "condition"
186
- # response: any TaggedResponse and UntaggedResponse when the response type
187
- # is a "condition" ("OK", "NO", "BAD", "PREAUTH", or "BYE").
194
+ # ResponseCode represents an \IMAP response code, which can be retrieved
195
+ # from ResponseText#code for
196
+ # {"status responses"}[https://www.rfc-editor.org/rfc/rfc3501#section-7.1]:
197
+ # * every TaggedResponse, name[rdoc-ref:TaggedResponse#name] is always
198
+ # "+OK+", "+NO+", or "+BAD+".
199
+ # * any UntaggedResponse when name[rdoc-ref:UntaggedResponse#name] is
200
+ # "+OK+", "+NO+", "+BAD+", "+PREAUTH+", or "+BYE+".
201
+ #
202
+ # Note that these "status responses" are confusingly _not_ the same as the
203
+ # +STATUS+ UntaggedResponse (see IMAP#status and StatusData).
188
204
  #
189
205
  # Some response codes come with additional data which will be parsed by
190
206
  # Net::IMAP. Others return +nil+ for #data, but are used as a
191
207
  # machine-readable annotation for the human-readable ResponseText#text in
192
- # the same response. When Net::IMAP does not know how to parse response
193
- # code text, #data returns the unparsed string.
208
+ # the same response.
194
209
  #
195
210
  # Untagged response code #data is pushed directly onto Net::IMAP#responses,
196
211
  # keyed by #name, unless it is removed by the command that generated it.
197
212
  # Use Net::IMAP#add_response_handler to view tagged response codes for
198
213
  # command methods that do not return their TaggedResponse.
199
214
  #
215
+ # == Standard response codes
216
+ #
200
217
  # \IMAP extensions may define new codes and the data that comes with them.
201
218
  # The IANA {IMAP Response
202
219
  # Codes}[https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml]
203
220
  # registry has links to specifications for all standard response codes.
204
- # Response codes are backwards compatible: Servers are allowed to send new
205
- # response codes even if the client has not enabled the extension that
206
- # defines them. When unknown response code data is encountered, #data
207
- # will return an unparsed string.
208
221
  #
209
- # ==== +IMAP4rev1+ Response Codes
222
+ # === +IMAP4rev1+ response codes
210
223
  # See [IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501]] {§7.1, "Server
211
224
  # Responses - Status
212
225
  # Responses"}[https://www.rfc-editor.org/rfc/rfc3501#section-7.1] for full
@@ -237,24 +250,24 @@ module Net
237
250
  # the <tt>\Seen</tt> flag set.
238
251
  # <em>DEPRECATED by IMAP4rev2.</em>
239
252
  #
240
- # ==== +BINARY+ extension
253
+ # === +BINARY+ extension
241
254
  # See {[RFC3516]}[https://www.rfc-editor.org/rfc/rfc3516].
242
255
  # * +UNKNOWN-CTE+, with a tagged +NO+ response, when the server does not
243
256
  # known how to decode a CTE (content-transfer-encoding). #data is +nil+.
244
257
  # See IMAP#fetch.
245
258
  #
246
- # ==== +UIDPLUS+ extension
259
+ # === +UIDPLUS+ extension
247
260
  # See {[RFC4315 §3]}[https://www.rfc-editor.org/rfc/rfc4315#section-3].
248
261
  # * +APPENDUID+, #data is UIDPlusData. See IMAP#append.
249
262
  # * +COPYUID+, #data is UIDPlusData. See IMAP#copy.
250
263
  # * +UIDNOTSTICKY+, #data is +nil+. See IMAP#select.
251
264
  #
252
- # ==== +SEARCHRES+ extension
265
+ # === +SEARCHRES+ extension
253
266
  # See {[RFC5182]}[https://www.rfc-editor.org/rfc/rfc5182].
254
267
  # * +NOTSAVED+, with a tagged +NO+ response, when the search result variable
255
268
  # is not saved. #data is +nil+.
256
269
  #
257
- # ==== +RFC5530+ Response Codes
270
+ # === +RFC5530+ response codes
258
271
  # See {[RFC5530]}[https://www.rfc-editor.org/rfc/rfc5530], "IMAP Response
259
272
  # Codes" for the definition of the following response codes, which are all
260
273
  # machine-readable annotations for the human-readable ResponseText#text, and
@@ -277,22 +290,22 @@ module Net
277
290
  # * +ALREADYEXISTS+
278
291
  # * +NONEXISTENT+
279
292
  #
280
- # ==== +QRESYNC+ extension
293
+ # === +QRESYNC+ extension
281
294
  # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
282
295
  # * +CLOSED+, returned when the currently selected mailbox is closed
283
296
  # implicitly by selecting or examining another mailbox. #data is +nil+.
284
297
  #
285
- # ==== +IMAP4rev2+ Response Codes
298
+ # === +IMAP4rev2+ response codes
286
299
  # See {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051] {§7.1, "Server
287
300
  # Responses - Status
288
301
  # Responses"}[https://www.rfc-editor.org/rfc/rfc9051#section-7.1] for full
289
302
  # descriptions of IMAP4rev2 response codes. IMAP4rev2 includes all of the
290
- # response codes listed above (except "UNSEEN") and adds the following:
303
+ # response codes listed above (except "+UNSEEN+") and adds the following:
291
304
  # * +HASCHILDREN+, with a tagged +NO+ response, when a mailbox delete failed
292
305
  # because the server doesn't allow deletion of mailboxes with children.
293
306
  # #data is +nil+.
294
307
  #
295
- # ==== +CONDSTORE+ extension
308
+ # === +CONDSTORE+ extension
296
309
  # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
297
310
  # * +NOMODSEQ+, when selecting a mailbox that does not support
298
311
  # mod-sequences. #data is +nil+. See IMAP#select.
@@ -302,10 +315,17 @@ module Net
302
315
  # since the +UNCHANGEDSINCE+ mod-sequence given to +STORE+ or <tt>UID
303
316
  # STORE</tt>.
304
317
  #
305
- # ==== +OBJECTID+ extension
318
+ # === +OBJECTID+ extension
306
319
  # See {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
307
320
  # * +MAILBOXID+, #data is a string
308
321
  #
322
+ # == Extension compatibility
323
+ #
324
+ # Response codes are backwards compatible: Servers are allowed to send new
325
+ # response codes even if the client has not enabled the extension that
326
+ # defines them. When Net::IMAP does not know how to parse response
327
+ # code text, #data returns the unparsed string.
328
+ #
309
329
  class ResponseCode < Struct.new(:name, :data)
310
330
  ##
311
331
  # method: name
@@ -324,14 +344,9 @@ module Net
324
344
  # code data can take.
325
345
  end
326
346
 
327
- # Net::IMAP::UIDPlusData represents the ResponseCode#data that accompanies
328
- # the +APPENDUID+ and +COPYUID+ response codes.
329
- #
330
- # See [[UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]].
331
- #
332
- # ==== Capability requirement
347
+ # UIDPlusData represents the ResponseCode#data that accompanies the
348
+ # +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode].
333
349
  #
334
- # The +UIDPLUS+ capability[rdoc-ref:Net::IMAP#capability] must be supported.
335
350
  # A server that supports +UIDPLUS+ should send a UIDPlusData object inside
336
351
  # every TaggedResponse returned by the append[rdoc-ref:Net::IMAP#append],
337
352
  # copy[rdoc-ref:Net::IMAP#copy], move[rdoc-ref:Net::IMAP#move], {uid
@@ -339,9 +354,9 @@ module Net
339
354
  # move}[rdoc-ref:Net::IMAP#uid_move] commands---unless the destination
340
355
  # mailbox reports +UIDNOTSTICKY+.
341
356
  #
342
- #--
343
- # TODO: support MULTIAPPEND
344
- #++
357
+ # == Required capability
358
+ # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
359
+ # or +IMAP4rev2+ capability.
345
360
  #
346
361
  class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids)
347
362
  ##
@@ -378,10 +393,8 @@ module Net
378
393
  end
379
394
  end
380
395
 
381
- # Net::IMAP::MailboxList represents contents of the LIST response,
382
- # representing a single mailbox path.
383
- #
384
- # Net::IMAP#list returns an array of MailboxList objects.
396
+ # MailboxList represents the data of an untagged +LIST+ response, for a
397
+ # _single_ mailbox path. IMAP#list returns an array of MailboxList objects.
385
398
  #
386
399
  class MailboxList < Struct.new(:attr, :delim, :name)
387
400
  ##
@@ -391,11 +404,11 @@ module Net
391
404
  # Returns the name attributes. Each name attribute is a symbol capitalized
392
405
  # by String#capitalize, such as :Noselect (not :NoSelect). For the
393
406
  # semantics of each attribute, see:
394
- # * rdoc-ref:Net::IMAP@Basic+Mailbox+Attributes
395
- # * rdoc-ref:Net::IMAP@Mailbox+role+Attributes
396
- # * Net::IMAP@SPECIAL-USE
407
+ # * Net::IMAP@Basic+Mailbox+Attributes
408
+ # * Net::IMAP@Mailbox+role+Attributes
397
409
  # * The IANA {IMAP Mailbox Name Attributes
398
410
  # registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml]
411
+ # has links to specifications for all standard mailbox attributes.
399
412
 
400
413
  ##
401
414
  # method: delim
@@ -410,16 +423,16 @@ module Net
410
423
  # Returns the mailbox name.
411
424
  end
412
425
 
413
- # Net::IMAP::MailboxQuota represents contents of GETQUOTA response.
414
- # This object can also be a response to GETQUOTAROOT. In the syntax
415
- # specification below, the delimiter used with the "#" construct is a
416
- # single space (SPACE).
426
+ # MailboxQuota represents the data of an untagged +QUOTA+ response.
417
427
  #
418
- # Net:IMAP#getquota returns an array of MailboxQuota objects.
428
+ # IMAP#getquota returns an array of MailboxQuota objects.
419
429
  #
420
430
  # Net::IMAP#getquotaroot returns an array containing both MailboxQuotaRoot
421
431
  # and MailboxQuota objects.
422
432
  #
433
+ # == Required capability
434
+ # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
435
+ # capability.
423
436
  class MailboxQuota < Struct.new(:mailbox, :usage, :quota)
424
437
  ##
425
438
  # method: mailbox
@@ -441,12 +454,14 @@ module Net
441
454
  #
442
455
  end
443
456
 
444
- # Net::IMAP::MailboxQuotaRoot represents part of the GETQUOTAROOT
445
- # response. (GETQUOTAROOT can also return Net::IMAP::MailboxQuota.)
457
+ # MailboxQuotaRoot represents the data of an untagged +QUOTAROOT+ response.
446
458
  #
447
- # Net::IMAP#getquotaroot returns an array containing both MailboxQuotaRoot
448
- # and MailboxQuota objects.
459
+ # IMAP#getquotaroot returns an array containing both MailboxQuotaRoot and
460
+ # MailboxQuota objects.
449
461
  #
462
+ # == Required capability
463
+ # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
464
+ # capability.
450
465
  class MailboxQuotaRoot < Struct.new(:mailbox, :quotaroots)
451
466
  ##
452
467
  # method: mailbox
@@ -461,12 +476,13 @@ module Net
461
476
  # Zero or more quotaroots that affect the quota on the specified mailbox.
462
477
  end
463
478
 
464
- # Net::IMAP::MailboxACLItem represents the response from GETACL.
479
+ # MailboxACLItem represents the data of an untagged +ACL+ response.
465
480
  #
466
- # Net::IMAP#getacl returns an array of MailboxACLItem objects.
481
+ # IMAP#getacl returns an array of MailboxACLItem objects.
467
482
  #
468
- # ==== Required capability
469
- # +ACL+ - described in [ACL[https://tools.ietf.org/html/rfc4314]]
483
+ # == Required capability
484
+ # Requires +ACL+ [RFC4314[https://www.rfc-editor.org/rfc/rfc4314]]
485
+ # capability.
470
486
  class MailboxACLItem < Struct.new(:user, :rights, :mailbox)
471
487
  ##
472
488
  # method: mailbox
@@ -488,11 +504,12 @@ module Net
488
504
  # The access rights the indicated #user has to the #mailbox.
489
505
  end
490
506
 
491
- # Net::IMAP::Namespace represents a single namespace contained inside a
492
- # NAMESPACE response.
493
- #
494
- # Returned by Net::IMAP#namespace, contained inside a Namespaces object.
507
+ # Namespace represents a _single_ namespace, contained inside a Namespaces
508
+ # object.
495
509
  #
510
+ # == Required capability
511
+ # Requires either +NAMESPACE+ [RFC2342[https://www.rfc-editor.org/rfc/rfc2342]]
512
+ # or +IMAP4rev2+ capability.
496
513
  class Namespace < Struct.new(:prefix, :delim, :extensions)
497
514
  ##
498
515
  # method: prefix
@@ -514,11 +531,14 @@ module Net
514
531
  # Extension parameter semantics would be defined by the extension.
515
532
  end
516
533
 
517
- # Net::IMAP::Namespaces represents a +NAMESPACE+ server response, which
518
- # contains lists of #personal, #shared, and #other namespaces.
534
+ # Namespaces represents the data of an untagged +NAMESPACE+ response,
535
+ # returned by IMAP#namespace.
519
536
  #
520
- # Net::IMAP#namespace returns a Namespaces object.
537
+ # Contains lists of #personal, #shared, and #other namespaces.
521
538
  #
539
+ # == Required capability
540
+ # Requires either +NAMESPACE+ [RFC2342[https://www.rfc-editor.org/rfc/rfc2342]]
541
+ # or +IMAP4rev2+ capability.
522
542
  class Namespaces < Struct.new(:personal, :other, :shared)
523
543
  ##
524
544
  # method: personal
@@ -539,9 +559,9 @@ module Net
539
559
  # Returns an array of Shared Namespace objects.
540
560
  end
541
561
 
542
- # Net::IMAP::StatusData represents the contents of the STATUS response.
562
+ # StatusData represents the contents of an untagged +STATUS+ response.
543
563
  #
544
- # Net::IMAP#status returns the contents of #attr.
564
+ # IMAP#status returns the contents of #attr.
545
565
  class StatusData < Struct.new(:mailbox, :attr)
546
566
  ##
547
567
  # method: mailbox
@@ -562,11 +582,11 @@ module Net
562
582
  # [Note]
563
583
  # When the #sender and #reply_to fields are absent or empty, they will
564
584
  # return the same value as #from. Also, fields may return values that are
565
- # invalid for well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
585
+ # invalid for well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
566
586
  # messages when the message is malformed or a draft message.
567
587
  #
568
- # See [{IMAP4rev1 §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2]]
569
- # and [{IMAP4rev2 §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2]]
588
+ # See [{IMAP4rev1 §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501#section-7.4.2]]
589
+ # and [{IMAP4rev2 §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051#section-7.5.2]]
570
590
  # for full description of the envelope fields, and
571
591
  # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs.
572
592
  #
@@ -580,7 +600,7 @@ module Net
580
600
  # Returns a string that represents the +Date+ header.
581
601
  #
582
602
  # [Note]
583
- # For a well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
603
+ # For a well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
584
604
  # message, the #date field must not be +nil+. However it can be +nil+
585
605
  # for a malformed or draft message.
586
606
 
@@ -606,7 +626,7 @@ module Net
606
626
  # returns +nil+ for this envelope field.
607
627
  #
608
628
  # [Note]
609
- # For a well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
629
+ # For a well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
610
630
  # message, the #from field must not be +nil+. However it can be +nil+
611
631
  # for a malformed or draft message.
612
632
 
@@ -619,7 +639,7 @@ module Net
619
639
  # [Note]
620
640
  # If the <tt>Sender</tt> header is absent, or is present but empty, the
621
641
  # server sets this field to be the same value as #from. Therefore, in a
622
- # well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]] message,
642
+ # well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] message,
623
643
  # the #sender envelope field must not be +nil+. However it can be
624
644
  # +nil+ for a malformed or draft message.
625
645
 
@@ -633,7 +653,7 @@ module Net
633
653
  # [Note]
634
654
  # If the <tt>Reply-To</tt> header is absent, or is present but empty,
635
655
  # the server sets this field to be the same value as #from. Therefore,
636
- # in a well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
656
+ # in a well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
637
657
  # message, the #reply_to envelope field must not be +nil+. However it
638
658
  # can be +nil+ for a malformed or draft message.
639
659
 
@@ -662,7 +682,7 @@ module Net
662
682
  # Returns a string that represents the <tt>In-Reply-To</tt> header.
663
683
  #
664
684
  # [Note]
665
- # For a well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
685
+ # For a well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
666
686
  # message, the #in_reply_to field, if present, must not be empty. But
667
687
  # it can still return an empty string for malformed messages.
668
688
  #
@@ -678,7 +698,7 @@ module Net
678
698
  # Returns a string that represents the <tt>Message-ID</tt>.
679
699
  #
680
700
  # [Note]
681
- # For a well-formed [RFC5322[https://tools.ietf.org/html/rfc5322]]
701
+ # For a well-formed [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
682
702
  # message, the #message_id field, if present, must not be empty. But it
683
703
  # can still return an empty string for malformed messages.
684
704
  #
@@ -692,10 +712,10 @@ module Net
692
712
  # parsed into its component parts by the server. Address objects are
693
713
  # returned within Envelope fields.
694
714
  #
695
- # === Group syntax
715
+ # == Group syntax
696
716
  #
697
717
  # When the #host field is +nil+, this is a special form of address structure
698
- # that indicates the [RFC5322[https://tools.ietf.org/html/rfc5322]] group
718
+ # that indicates the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] group
699
719
  # syntax. If the #mailbox name field is also +nil+, this is an end-of-group
700
720
  # marker (semicolon in RFC-822 syntax). If the #mailbox name field is
701
721
  # non-+NIL+, this is the start of a group marker, and the mailbox #name
@@ -705,7 +725,7 @@ module Net
705
725
  # method: name
706
726
  # :call-seq: name -> string or nil
707
727
  #
708
- # Returns the [RFC5322[https://tools.ietf.org/html/rfc5322]] address
728
+ # Returns the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] address
709
729
  # +display-name+ (or the mailbox +phrase+ in the RFC-822 grammar).
710
730
 
711
731
  ##
@@ -715,28 +735,28 @@ module Net
715
735
  # Returns the route from RFC-822 route-addr.
716
736
  #
717
737
  # Note:: Generating this obsolete route addressing syntax is not allowed
718
- # by [RFC5322[https://tools.ietf.org/html/rfc5322]]. However,
738
+ # by [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]. However,
719
739
  # addresses with this syntax must still be accepted and parsed.
720
740
 
721
741
  ##
722
742
  # method: mailbox
723
743
  # :call-seq: mailbox -> string or nil
724
744
  #
725
- # Returns the [RFC5322[https://tools.ietf.org/html/rfc5322]] address
745
+ # Returns the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] address
726
746
  # +local-part+, if #host is not +nil+.
727
747
  #
728
748
  # When #host is +nil+, this returns
729
- # an [RFC5322[https://tools.ietf.org/html/rfc5322]] group name and a +nil+
749
+ # an [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] group name and a +nil+
730
750
  # mailbox indicates the end of a group.
731
751
 
732
752
  ##
733
753
  # method: host
734
754
  # :call-seq: host -> string or nil
735
755
  #
736
- # Returns the [RFC5322[https://tools.ietf.org/html/rfc5322]] addr-spec
756
+ # Returns the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] addr-spec
737
757
  # +domain+ name.
738
758
  #
739
- # +nil+ indicates [RFC5322[https://tools.ietf.org/html/rfc5322]] group
759
+ # +nil+ indicates [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]] group
740
760
  # syntax.
741
761
  end
742
762
 
@@ -748,14 +768,14 @@ module Net
748
768
  # :call-seq: dsp_type -> string
749
769
  #
750
770
  # Returns the content disposition type, as defined by
751
- # [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
771
+ # [DISPOSITION[https://www.rfc-editor.org/rfc/rfc2183]].
752
772
 
753
773
  ##
754
774
  # method: param
755
775
  # :call-seq: param -> hash
756
776
  #
757
777
  # Returns a hash representing parameters of the Content-Disposition
758
- # field, as defined by [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
778
+ # field, as defined by [DISPOSITION[https://www.rfc-editor.org/rfc/rfc2183]].
759
779
  end
760
780
 
761
781
  # Net::IMAP::ThreadMember represents a thread-node returned
@@ -794,12 +814,12 @@ module Net
794
814
  # FetchData#attr value. Although these classes don't share a base class,
795
815
  # this module can be used to pattern match all of them.
796
816
  #
797
- # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2]
798
- # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2-4.9]
817
+ # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501#section-7.4.2]
818
+ # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051#section-7.5.2-4.9]
799
819
  # for full description of all +BODYSTRUCTURE+ fields, and also
800
820
  # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs.
801
821
  #
802
- # === Classes that include BodyStructure
822
+ # == Classes that include BodyStructure
803
823
  # BodyTypeBasic:: Represents any message parts that are not handled by
804
824
  # BodyTypeText, BodyTypeMessage, or BodyTypeMultipart.
805
825
  # BodyTypeText:: Used by <tt>text/*</tt> parts. Contains all of the
@@ -817,8 +837,8 @@ module Net
817
837
  # message parts, unless they have a <tt>Content-Type</tt> that is handled by
818
838
  # BodyTypeText, BodyTypeMessage, or BodyTypeMultipart.
819
839
  #
820
- # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2]
821
- # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2-4.9]
840
+ # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501#section-7.4.2]
841
+ # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051#section-7.5.2-4.9]
822
842
  # for full description of all +BODYSTRUCTURE+ fields, and also
823
843
  # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs.
824
844
  #
@@ -835,45 +855,45 @@ module Net
835
855
  # :call-seq: media_type -> string
836
856
  #
837
857
  # The top-level media type as defined in
838
- # [MIME-IMB[https://tools.ietf.org/html/rfc2045]].
858
+ # [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]].
839
859
 
840
860
  ##
841
861
  # method: subtype
842
862
  # :call-seq: subtype -> string
843
863
  #
844
864
  # The media subtype name as defined in
845
- # [MIME-IMB[https://tools.ietf.org/html/rfc2045]].
865
+ # [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]].
846
866
 
847
867
  ##
848
868
  # method: param
849
869
  # :call-seq: param -> string
850
870
  #
851
871
  # Returns a hash that represents parameters as defined in
852
- # [MIME-IMB[https://tools.ietf.org/html/rfc2045]].
872
+ # [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]].
853
873
 
854
874
  ##
855
875
  # method: content_id
856
876
  # :call-seq: content_id -> string
857
877
  #
858
878
  # Returns a string giving the content id as defined
859
- # in [MIME-IMB[https://tools.ietf.org/html/rfc2045]]
860
- # {§7}[https://tools.ietf.org/html/rfc2045#section-7].
879
+ # in [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]]
880
+ # {§7}[https://www.rfc-editor.org/rfc/rfc2045#section-7].
861
881
 
862
882
  ##
863
883
  # method: description
864
884
  # :call-seq: description -> string
865
885
  #
866
886
  # Returns a string giving the content description as defined
867
- # in [MIME-IMB[https://tools.ietf.org/html/rfc2045]]
868
- # {§8}[https://tools.ietf.org/html/rfc2045#section-8].
887
+ # in [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]]
888
+ # {§8}[https://www.rfc-editor.org/rfc/rfc2045#section-8].
869
889
 
870
890
  ##
871
891
  # method: encoding
872
892
  # :call-seq: encoding -> string
873
893
  #
874
894
  # Returns a string giving the content transfer encoding as defined
875
- # in [MIME-IMB[https://tools.ietf.org/html/rfc2045]]
876
- # {§6}[https://tools.ietf.org/html/rfc2045#section-6].
895
+ # in [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]]
896
+ # {§6}[https://www.rfc-editor.org/rfc/rfc2045#section-6].
877
897
 
878
898
  ##
879
899
  # method: size
@@ -886,7 +906,7 @@ module Net
886
906
  # :call-seq: md5 -> string
887
907
  #
888
908
  # Returns a string giving the body MD5 value as defined in
889
- # [MD5[https://tools.ietf.org/html/rfc1864]].
909
+ # [MD5[https://www.rfc-editor.org/rfc/rfc1864]].
890
910
 
891
911
  ##
892
912
  # method: disposition
@@ -894,7 +914,7 @@ module Net
894
914
  #
895
915
  # Returns a ContentDisposition object giving the content
896
916
  # disposition, as defined by
897
- # [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
917
+ # [DISPOSITION[https://www.rfc-editor.org/rfc/rfc2183]].
898
918
 
899
919
  ##
900
920
  # method: language
@@ -939,7 +959,8 @@ module Net
939
959
  # for something else?
940
960
  #++
941
961
  def media_subtype
942
- warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
962
+ warn("media_subtype is obsolete, use subtype instead.\n",
963
+ uplevel: 1, category: :deprecated)
943
964
  return subtype
944
965
  end
945
966
  end
@@ -984,7 +1005,8 @@ module Net
984
1005
  # generate a warning message to +stderr+, then return
985
1006
  # the value of +subtype+.
986
1007
  def media_subtype
987
- warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
1008
+ warn("media_subtype is obsolete, use subtype instead.\n",
1009
+ uplevel: 1, category: :deprecated)
988
1010
  return subtype
989
1011
  end
990
1012
  end
@@ -1040,77 +1062,6 @@ module Net
1040
1062
  end
1041
1063
  end
1042
1064
 
1043
- # BodyTypeAttachment is not used and will be removed in an upcoming release.
1044
- #
1045
- # === Bug Analysis
1046
- #
1047
- # \IMAP body structures are parenthesized lists and assign their fields
1048
- # positionally, so missing fields change the interpretation of all
1049
- # following fields. Additionally, different body types have a different
1050
- # number of required fields, followed by optional "extension" fields.
1051
- #
1052
- # BodyTypeAttachment was previously returned when a "message/rfc822" part,
1053
- # which should be sent as <tt>body-type-msg</tt> with ten required fields,
1054
- # was actually sent as a <tt>body-type-basic</tt> with _seven_ required
1055
- # fields.
1056
- #
1057
- # basic => type, subtype, param, id, desc, enc, octets, md5=nil, dsp=nil, lang=nil, loc=nil, *ext
1058
- # msg => type, subtype, param, id, desc, enc, octets, envelope, body, lines, md5=nil, ...
1059
- #
1060
- # Normally, +envelope+ and +md5+ are incompatible, but Net::IMAP leniently
1061
- # allowed buggy servers to send +NIL+ for +envelope+. As a result, when a
1062
- # server sent a <tt>message/rfc822</tt> part with +NIL+ for +md5+ and a
1063
- # non-<tt>NIL</tt> +dsp+, Net::IMAP misinterpreted the
1064
- # <tt>Content-Disposition</tt> as if it were a strange body type. In all
1065
- # reported cases, the <tt>Content-Disposition</tt> was "attachment", so
1066
- # BodyTypeAttachment was created as the workaround.
1067
- #
1068
- # === Current behavior
1069
- #
1070
- # When interpreted strictly, +envelope+ and +md5+ are incompatible. So the
1071
- # current parsing algorithm peeks ahead after it has received the seventh
1072
- # body field. If the next token is not the start of an +envelope+, we assume
1073
- # the server has incorrectly sent us a <tt>body-type-basic</tt> and return
1074
- # BodyTypeBasic. As a result, what was previously BodyTypeMessage#body =>
1075
- # BodyTypeAttachment is now BodyTypeBasic#disposition => ContentDisposition.
1076
- #
1077
- class BodyTypeAttachment < Struct.new(:dsp_type, :_unused_, :param)
1078
- # *invalid for BodyTypeAttachment*
1079
- def media_type
1080
- warn(<<~WARN, uplevel: 1)
1081
- BodyTypeAttachment#media_type is obsolete. Use dsp_type instead.
1082
- WARN
1083
- dsp_type
1084
- end
1085
-
1086
- # *invalid for BodyTypeAttachment*
1087
- def subtype
1088
- warn("BodyTypeAttachment#subtype is obsolete.\n", uplevel: 1)
1089
- nil
1090
- end
1091
-
1092
- ##
1093
- # method: dsp_type
1094
- # :call-seq: dsp_type -> string
1095
- #
1096
- # Returns the content disposition type, as defined by
1097
- # [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
1098
-
1099
- ##
1100
- # method: param
1101
- # :call-seq: param -> hash
1102
- #
1103
- # Returns a hash representing parameters of the Content-Disposition
1104
- # field, as defined by [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
1105
-
1106
- ##
1107
- def multipart?
1108
- return false
1109
- end
1110
- end
1111
-
1112
- deprecate_constant :BodyTypeAttachment
1113
-
1114
1065
  # Net::IMAP::BodyTypeMultipart represents body structures of messages and
1115
1066
  # message parts, when <tt>Content-Type</tt> is <tt>multipart/*</tt>.
1116
1067
  class BodyTypeMultipart < Struct.new(:media_type, :subtype,
@@ -1131,7 +1082,7 @@ module Net
1131
1082
  # call-seq: subtype -> string
1132
1083
  #
1133
1084
  # Returns the content subtype name
1134
- # as defined in [MIME-IMB[https://tools.ietf.org/html/rfc2045]].
1085
+ # as defined in [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]].
1135
1086
 
1136
1087
  ##
1137
1088
  # method: parts
@@ -1145,7 +1096,7 @@ module Net
1145
1096
  # call-seq: param -> hash
1146
1097
  #
1147
1098
  # Returns a hash that represents parameters
1148
- # as defined in [MIME-IMB[https://tools.ietf.org/html/rfc2045]].
1099
+ # as defined in [MIME-IMB[https://www.rfc-editor.org/rfc/rfc2045]].
1149
1100
 
1150
1101
  ##
1151
1102
  # method: disposition
@@ -1182,29 +1133,11 @@ module Net
1182
1133
  # generate a warning message to +stderr+, then return
1183
1134
  # the value of +subtype+.
1184
1135
  def media_subtype
1185
- warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
1136
+ warn("media_subtype is obsolete, use subtype instead.\n",
1137
+ uplevel: 1, category: :deprecated)
1186
1138
  return subtype
1187
1139
  end
1188
1140
  end
1189
1141
 
1190
- # === Obsolete
1191
- # BodyTypeExtension is not used and will be removed in an upcoming release.
1192
- #
1193
- # >>>
1194
- # BodyTypeExtension was (incorrectly) used for <tt>message/*</tt> parts
1195
- # (besides <tt>message/rfc822</tt>, which correctly uses BodyTypeMessage).
1196
- #
1197
- # Net::IMAP now (correctly) parses all message types (other than
1198
- # <tt>message/rfc822</tt> or <tt>message/global</tt>) as BodyTypeBasic.
1199
- class BodyTypeExtension < Struct.new(:media_type, :subtype,
1200
- :params, :content_id,
1201
- :description, :encoding, :size)
1202
- def multipart?
1203
- return false
1204
- end
1205
- end
1206
-
1207
- deprecate_constant :BodyTypeExtension
1208
-
1209
1142
  end
1210
1143
  end