net-imap 0.6.6 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fc8fe0589b4b3cf22687ee9731136d4bb4fae32bceadffdad5cb4fdc225741b
-  data.tar.gz: 6c72c3817f3bd9c1ba7b6edbf01c5808e7d9c785effcc09294435944ccbdd33b
+  metadata.gz: 9405d034ddfa540378feffe20b4818437ca73913b1d82663cdd56d341ca71553
+  data.tar.gz: 2df46e36cdb6fc77aa6c88838ae684f7c800b5a643b985880e95d802e912a2fd
 SHA512:
-  metadata.gz: 2e24f88144b2329c18a03c9fcc5630ac6a6c50b88f14107c09abd29762eaa94467ab345fb356edf8d891b244b1c8d3dcc2a4033166ddc6bbde7131ffba3e0d59
-  data.tar.gz: bc71d03a81f9d268f0c3c359939150fd78c8fbe06dc5dba7e5de77d2f10d21f1155acafd8f670afae6aafea77e0fbd4f150f8cdcbf4e1301ba7a9695a1bba9d9
+  metadata.gz: 554739baaaaa8b0406f729d56447a13d4ced84f33feba90a350851424624483a36765c40f00e34737fe602bd0bd43555a2f480d4f7d9a0af034f791c0c9e0b8a
+  data.tar.gz: '06596b9d2da38bbd53dcc0fd990b66b1af5ffbd52af52370b8366188899043f129e63aae7090054090f8a1b29b8e89e7c96402ffc0aa48101d7f95bf09419a96'

data/.simplecov

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 SimpleCov.configure do
-  formatter SimpleCov::Formatter::HTMLFormatter
-
   enable_coverage  :branch
   enable_coverage  :method
   enable_coverage  :eval

data/Gemfile

@@ -13,12 +13,12 @@ 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
-  gem "simplecov", ">= 1.0.0", require: false, platforms: %i[mri windows]
+  gem "simplecov", ">= 1.2.0", require: false, platforms: %i[mri windows]
 end

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,63 @@ 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  98, per: group("Config")
+      minimum  97, per: group("StringPrep")
+      minimum  97, per: group("SASL")
+      minimum  95, per: group("Data Types")
+      minimum  94, per: group("Parser")
+      minimum  92, per: group("Client")
+
+      minimum  80, per: :file
+      minimum  55, per: "lib/net/imap/search_result.rb"
+    end
+
+    # NOTE: branch coverage varies more widely between ruby versions
+    coverage(:branch) do
+      # eval branch coverage varies too much between runtime environments
+      ignore :eval_generated
+
+      minimum  80
+
+      minimum  90, per: group("Data Types")
+      minimum  85, per: group("Config")
+      minimum  80, per: group("Client")
+      minimum  80, per: group("Parser")
+      minimum  70, per: group("SASL")
+      minimum  70, per: group("StringPrep")
+
+      minimum  60, per: :file
+      minimum  50, per: "lib/net/imap/sasl/authenticators.rb"
+      minimum  50, per: "lib/net/imap/config/attr_accessors.rb"
+    end
+
+    coverage(:method) do
+      minimum  88
+
+      minimum 100, per: group("Config")
+      minimum  90, per: group("Data Types")
+      minimum  90, per: group("StringPrep")
+      minimum  85, per: group("Client")
+      minimum  80, per: group("Parser")
+      minimum  80, per: group("SASL")
+
+      minimum  65, per: :file
+      minimum  60, per: "lib/net/imap/response_parser/parser_utils.rb"
+      minimum  55, per: "lib/net/imap/sasl/authenticators.rb"
+      minimum  50, per: "lib/net/imap/authenticators.rb"
+      minimum  50, per: "lib/net/imap/sasl/anonymous_authenticator.rb"
+      minimum  35, per: "lib/net/imap/sasl/protocol_adapters.rb"
+      minimum  20, per: "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/attr_type_coercion.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils"
+
 module Net
   class IMAP
     class Config
@@ -28,28 +30,14 @@ module Net
         end
         private_class_method :included
 
-        if defined?(Ractor.shareable_proc)
-          def self.safe(&b)
-            case obj = b.call
-            when Proc
-              Ractor.shareable_proc(&obj)
-            else
-              Ractor.make_shareable obj
-            end
-          end
-        elsif defined?(Ractor.make_shareable)
-          def self.safe(&b)
-            obj = nil.instance_eval(&b).freeze
-            Ractor.make_shareable obj
-          end
-        else
-          def self.safe(&b) nil.instance_eval(&b).freeze end
-        end
-        private_class_method :safe
+        extend Utils
 
-        Types = Hash.new do |h, type| type => Proc | nil; safe{type} end
-        Types[:boolean] = Boolean = safe{-> {!!_1}}
-        Types[Integer]  = safe{->{Integer(_1)}}
+        Types = Hash.new do |h, type|
+          type => Proc | nil
+          Utils.shareable{type}
+        end
+        Types[:boolean] = Boolean = shareable{-> {!!_1}}
+        Types[Integer]  = shareable{->{Integer(_1)}}
 
         def self.attr_accessor(attr, type: nil)
           type = Types[type] or return
@@ -57,16 +45,16 @@ module Net
           define_method :"#{attr}?" do send attr end if type == Boolean
         end
 
-        NilOrInteger = safe{->val { Integer val unless val.nil? }}
+        NilOrInteger = shareable{->val { Integer val unless val.nil? }}
 
-        Enum = ->(*enum) {
-          safe_enum = safe{enum}
+        Enum = shareable{->(*enum) {
+          safe_enum = Utils.shareable{enum}
           expected = -"one of #{safe_enum.map(&:inspect).join(", ")}"
-          safe{->val {
+          Utils.shareable{->val {
             return val if safe_enum.include?(val)
             raise ArgumentError, "expected %s, got %p" % [expected, val]
           }}
-        }
+        }}
 
       end
     end

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