net-imap 0.6.6 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fc8fe0589b4b3cf22687ee9731136d4bb4fae32bceadffdad5cb4fdc225741b
-  data.tar.gz: 6c72c3817f3bd9c1ba7b6edbf01c5808e7d9c785effcc09294435944ccbdd33b
+  metadata.gz: 5300636497a02d1c8bc10b528bf1d3fe8aad9898ba02ba3ab40f2329f9306baf
+  data.tar.gz: 449230117bc3289dc13cb1531d95a2ae530558a21a405d8f4effb958773da88d
 SHA512:
-  metadata.gz: 2e24f88144b2329c18a03c9fcc5630ac6a6c50b88f14107c09abd29762eaa94467ab345fb356edf8d891b244b1c8d3dcc2a4033166ddc6bbde7131ffba3e0d59
-  data.tar.gz: bc71d03a81f9d268f0c3c359939150fd78c8fbe06dc5dba7e5de77d2f10d21f1155acafd8f670afae6aafea77e0fbd4f150f8cdcbf4e1301ba7a9695a1bba9d9
+  metadata.gz: b034f4ab8fc449890b3eb29c2049c4af1ed5aac42e8943f0a5eb20d4f9eae910740e0c8d590590f3379121c30ac347ce49f5387dcd4985e2dd551292545bd2de
+  data.tar.gz: 996ab44d2c1f4bf6d5d2e3d141b1890d25a38cddf1e0032726257c63346fc7175bcdd05f3ed97cce3a3ce63d8939154c4d9c4b9e931b035a46d9c4fa1a518450

data/.simplecov

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 SimpleCov.configure do
-  formatter SimpleCov::Formatter::HTMLFormatter
-
   enable_coverage  :branch
   enable_coverage  :method
   enable_coverage  :eval
 
+  # eval branch coverage varies too much between runtime environments
+  ignore_branches :eval_generated
+
   skip "/test/"
   skip "/rakelib/"
   cover "lib/**/*.rb"

data/Gemfile

@@ -13,10 +13,10 @@ gem "irb"
 gem "rake"
 gem "rdoc", ">= 7.2.0"
 gem "test-unit"
-gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
+gem "test-unit-ruby-core"
 
 gem "benchmark", require: false
-gem "benchmark-driver", require: false
+gem "benchmark_driver", require: false
 gem "vernier", require: false, platform: :mri
 
 group :test do

data/README.md

@@ -26,41 +26,61 @@ Or install it yourself as:
 ### Connect with TLS to port 993
 
 ```ruby
-imap = Net::IMAP.new('mail.example.com', ssl: true)
-imap.port          => 993
-imap.tls_verified? => true
-case imap.greeting.name
-in /OK/i
-  # The client is connected in the "Not Authenticated" state.
-  imap.authenticate("PLAIN", "joe_user", "joes_password")
-in /PREAUTH/i
-  # The client is connected in the "Authenticated" state.
+hostname = "mail.example.com"
+username = "user@example.com"
+password = "correct-horse-battery-staple"
+
+imap = Net::IMAP.new(hostname, ssl: true)
+imap.authenticate(:plain, username, password)
+```
+
+To authenticate with an OAuth2 access token:
+```ruby
+if imap.auth_capable?(:OAUTHBEARER)
+  imap.authenticate(:OAUTHBEARER, username, oauth2_token)
+elsif imap.auth_capable?(:XOAUTH2)
+  imap.authenticate(:XOAUTH2, username, oauth2_token)
+else
+  raise "OAuth2 not supported?"
 end
 ```
 
-### List sender and subject of all recent messages in the default mailbox
+### List sender and subject of recent messages
 
 ```ruby
 imap.examine('INBOX')
-imap.search(["RECENT"]).each do |message_id|
-  envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
-  puts "#{envelope.from[0].name}: \t#{envelope.subject}"
+search_result = imap.uid_search(["SINCE", Date.today - 7])
+imap.uid_fetch(search_result, "ENVELOPE").each do |fetch_data|
+  envelope = fetch_data.envelope
+  puts "#{envelope.from.first.name}: \t#{envelope.subject}"
 end
 ```
 
-### Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
+### Move messages between two dates to another mailbox
 
 ```ruby
-imap.select('Mail/sent-mail')
-if imap.list('Mail/', 'sent-apr03').empty?
-  imap.create('Mail/sent-apr03')
+source      = "Mail/sent-mail"
+destination = "Mail/sent-apr03"
+
+# The "BEFORE" and "AFTER" search criteria are not inclusive.
+since  = Date.parse("2003-04-01").prev_day
+before = Date.parse("2003-05-01")
+
+if imap.list("", destination).empty?
+  imap.create(destination)
 end
-imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id|
-  if imap.capable?(:move) || imap.capable?(:IMAP4rev2)
-    imap.move(message_id, "Mail/sent-apr03")
+imap.select(source)
+search_result = imap.uid_search(["SINCE", since, "BEFORE", before])
+if imap.capable?(:MOVE) || imap.capable?(:IMAP4rev2)
+  imap.uid_move(search_result, destination)
+else
+  # Atomic MOVE is not supported.  Copy, delete, and expunge.
+  imap.uid_copy(search_result, destination)
+  imap.uid_store(search_result, "+FLAGS", [:Deleted])
+  if imap.capable?(:UIDPLUS) || imap.capable?(:IMAP4rev2)
+    imap.uid_expunge(search_result)
   else
-    imap.copy(message_id, "Mail/sent-apr03")
-    imap.store(message_id, "+FLAGS", [:Deleted])
+    # NOTE: This may expunge _other_ deleted messages, too.
     imap.expunge
   end
 end
@@ -68,9 +88,15 @@ end
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -12,13 +12,60 @@ end
 
 task :default => :test
 
-desc "Output coverage data report, and error when threshholds aren't met"
-task "coverage:report" do
+desc "Output HTML coverage data report, and error when threshholds aren't met"
+task "test:coverage:report" do
   require "simplecov"
+
   SimpleCov.collate "coverage/.resultset.json" do
+    formatter SimpleCov::Formatter::HTMLFormatter
+
     coverage(:line) do
-      minimum           90
-      minimum_per_file  40
+      minimum           95
+
+      minimum_per_group 98, only: "Config"
+      minimum_per_group 97, only: "StringPrep"
+      minimum_per_group 97, only: "SASL"
+      minimum_per_group 95, only: "Data Types"
+      minimum_per_group 94, only: "Parser"
+      minimum_per_group 92, only: "Client"
+
+      minimum_per_file  80
+      minimum_per_file  55, only: "lib/net/imap/search_result.rb"
+    end
+
+    # NOTE: branch coverage varies more widely between ruby versions
+    coverage(:branch) do
+      minimum           80
+
+      minimum_per_group 90, only: "Data Types"
+      minimum_per_group 85, only: "Config"
+      minimum_per_group 80, only: "Client"
+      minimum_per_group 80, only: "Parser"
+      minimum_per_group 70, only: "SASL"
+      minimum_per_group 70, only: "StringPrep"
+
+      minimum_per_file  60
+      minimum_per_file  50, only: "lib/net/imap/sasl/authenticators.rb"
+      minimum_per_file  50, only: "lib/net/imap/config/attr_accessors.rb"
+    end
+
+    coverage(:method) do
+      minimum            88
+
+      minimum_per_group 100, only: "Config"
+      minimum_per_group  90, only: "Data Types"
+      minimum_per_group  90, only: "StringPrep"
+      minimum_per_group  85, only: "Client"
+      minimum_per_group  80, only: "Parser"
+      minimum_per_group  80, only: "SASL"
+
+      minimum_per_file   65
+      minimum_per_file   60, only: "lib/net/imap/response_parser/parser_utils.rb"
+      minimum_per_file   55, only: "lib/net/imap/sasl/authenticators.rb"
+      minimum_per_file   50, only: "lib/net/imap/authenticators.rb"
+      minimum_per_file   50, only: "lib/net/imap/sasl/anonymous_authenticator.rb"
+      minimum_per_file   35, only: "lib/net/imap/sasl/protocol_adapters.rb"
+      minimum_per_file   20, only: "lib/net/imap/response_data.rb"
     end
   end
 end

data/lib/net/imap/command_data.rb

@@ -265,23 +265,26 @@ module Net
       def self.split(data)
         data = data.b # dups and ensures BINARY encoding
         parts = []
-        while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n)
-          text, binary, bytesize, non_sync, data = $`, !!$1, $2, !!$3, $'
+        text_start = 0
+        while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n, text_start)
+          text, binary, bytesize, non_sync, literal_start =
+            data.byteslice(text_start...$~.begin(0)), !!$1, $2, !!$3, $~.end(0)
           bytesize = NumValidator.coerce_number64 bytesize
+          text_start = literal_start + bytesize
           parts << RawText[text] unless text.empty?
-          parts << extract_literal(data, binary:, bytesize:, non_sync:)
-          data.bytesplice(0, bytesize, "")
+          parts << extract_literal(data, literal_start, bytesize, binary:, non_sync:)
         end
-        parts << RawText[data] unless data.empty?
+        parts << RawText[data.byteslice(text_start..)] if text_start < data.bytesize
         parts
       end
 
-      def self.extract_literal(data, binary:, bytesize:, non_sync:)
-        if data.bytesize < bytesize
+      def self.extract_literal(data, offset, bytesize, binary:, non_sync:)
+        remaining = data.bytesize - offset
+        if remaining < bytesize
           raise DataFormatError, "Too few bytes in string for literal, " \
-            "expected: %s, remaining: %s" % [bytesize, data.bytesize]
+            "expected: %s, remaining: %s" % [bytesize, remaining]
         end
-        literal = data.byteslice(0, bytesize)
+        literal = data.byteslice(offset, bytesize)
         (binary ? Literal8 : Literal).new(data: literal, non_sync:)
       end
       private_class_method :extract_literal
@@ -459,7 +462,7 @@ module Net
       # coerces using +to_s+
       def string(str)
         str = str.to_s
-        if str =~ LITERAL_REGEX
+        if str.b.match?(LITERAL_REGEX)
           Literal.new(str)
         else
           QuotedString.new(str)

data/lib/net/imap/config/attr_accessors.rb

@@ -58,9 +58,9 @@ module Net
 
         private
 
-        def initialize_clone(other)
+        def initialize_clone(other, **kwargs)
           super
-          @data = other.data.clone
+          @data = other.data.clone(**kwargs)
         end
 
         def initialize_dup(other)

data/lib/net/imap/config.rb

@@ -120,6 +120,66 @@ module Net
     #
     # *NOTE:* Updates to config objects are not synchronized for thread-safety.
     #
+    # == What's here?
+    #
+    # === \Config attributes
+    #
+    # ==== Timeouts and other limits
+    #
+    # * #open_timeout: seconds to wait for connection to open or start TLS
+    # * #idle_response_timeout: seconds to wait for +IDLE+ command to complete
+    # * max_response_size: Maximum allowed server response size.
+    #
+    # ==== Server capabilities
+    #
+    # * #sasl_ir: Controls +SASL-IR+ behavior for Net::IMAP#authenticate.
+    # * #enforce_logindisabled: Controls +LOGINDISABLED+ behavior in
+    #   Net::IMAP#login.
+    # * max_non_synchronizing_literal: maximum bytesize for <tt>LITERAL+</tt> /
+    #   <tt>LITERAL-</tt> non-synchronizing literals.
+    #
+    # ==== Inherited defaults
+    # {Versioned defaults}[rdoc-ref:Net::IMAP@Versioned+defaults] inherit these
+    # from ::global and #load_defaults doesn't update them.
+    #
+    # * #debug (aliased as #debug?): whether debug mode is enabled
+    #
+    # ==== Backward compatibility
+    # These attributes will be removed by some future release.
+    #
+    # * #responses_without_block: Controls the behavior of Net::IMAP#responses
+    #   when called without any arguments (+type+ or +block+).
+    # * #parser_use_deprecated_uidplus_data: <em>Ignored since +v0.6.0+.</em>
+    # * #parser_max_deprecated_uidplus_data_size: <em>Ignored since +v0.6.0+.</em>
+    #
+    # === Getting a new or existing config
+    # * ::global:  The global config, used as the default #parent.
+    # * ::default: The hardcoded frozen default config, and parent of ::global.
+    # * ::version_defaults: Hard-coded frozen default configurations, indexed
+    #   by version.
+    # * ::[]: Returns a config from ::version_defaults or created by ::new.
+    # * ::new: Return a new Config which inherits from a given +parent+.
+    # * #new: Return a new Config which inherits from +self+.
+    #
+    # === Updating multiple attributes
+    # * #load_defaults: Sets attributes to a given +version+'s default values.
+    # * #update: Assigns multiple attribute values to +self+.
+    # * #reset: Resets attributes to inherit from #parent.
+    #
+    # === Exporting multiple attributes
+    # * #to_h: Return a hash with all attributes.
+    # * #inspect (aliased as #to_s): Returns a string representation of
+    #   overriden config attributes and the config inheritance chain.
+    # * #pretty_print: Used by PP[https://docs.ruby-lang.org/en/master/PP.html]
+    #   to create a string representation of all config attributes and the
+    #   inheritance chain.
+    #
+    # === Inheritance inspection
+    # * #parent: Returns the parent config object.
+    # * #inherited?: Returns whether all attributes inherit from #parent.
+    # * #inherits_defaults?: Returns whether all attributes inherit from a default config.
+    # * #overrides?: Returns whether any attributes override the #parent value.
+    #
     class Config
       # Array of attribute names that are _not_ loaded by #load_defaults.
       DEFAULT_TO_INHERIT = %i[debug].freeze
@@ -196,7 +256,7 @@ module Net
       # #load_defaults will not override #debug.
       attr_accessor :debug, type: :boolean, default: false
 
-      # method: debug?
+      # :method: debug?
       # :call-seq: debug? -> boolean
       #
       # Alias for #debug
@@ -312,7 +372,7 @@ module Net
       # * +0.6+: 16 KiB
       attr_accessor :max_non_synchronizing_literal, type: Integer, defaults: {
         0.0r => -1,
-        0.6r => 16 << 16, # 16 KiB
+        0.6r => 16 << 10, # 16 KiB
       }
 
       # The maximum allowed server response size.  When +nil+, there is no limit
@@ -365,7 +425,7 @@ module Net
       #   Prints a warning and returns the mutable responses hash.
       #   <em>This is not thread-safe.</em>
       #
-      # [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+      # [+:frozen_dup+ <em>(default since +v0.6+)</em>]
       #   Returns a frozen copy of the unhandled responses hash, with frozen
       #   array values.
       #

data/lib/net/imap/esearch_result.rb

@@ -193,11 +193,11 @@ module Net
         end
 
         ##
-        # method: range
+        # :method: range
         # :call-seq: range -> range
 
         ##
-        # method: results
+        # :method: results
         # :call-seq: results -> sequence set or nil
 
         # Converts #results to an array of integers.

data/lib/net/imap/fetch_data.rb

@@ -104,7 +104,7 @@ module Net
     #
     class FetchStruct < Struct
       ##
-      # method: attr
+      # :method: attr
       # :call-seq: attr -> hash
       #
       # Each key specifies a message attribute, and the value is the
@@ -518,7 +518,7 @@ module Net
     # See FetchStruct documentation for a list of standard message attributes.
     class FetchData < FetchStruct.new(:seqno, :attr)
       ##
-      # method: seqno
+      # :method: seqno
       # :call-seq: seqno -> Integer
       #
       # The message sequence number.
@@ -532,7 +532,7 @@ module Net
       #   UIDFetchData will raise a NoMethodError.
 
       ##
-      # method: attr
+      # :method: attr
       # :call-seq: attr -> hash
       #
       # Each key specifies a message attribute, and the value is the
@@ -558,7 +558,7 @@ module Net
     # See FetchStruct documentation for a list of standard message attributes.
     class UIDFetchData < FetchStruct.new(:uid, :attr)
       ##
-      # method: uid
+      # :method: uid
       # call-seq: uid -> Integer
       #
       # A number expressing the unique identifier of the message.
@@ -568,7 +568,7 @@ module Net
       #   returns the uniqueid at the beginning of the +UIDFETCH+ response.
 
       ##
-      # method: attr
+      # :method: attr
       # call-seq: attr -> hash
       #
       # Each key specifies a message attribute, and the value is the