net-imap 0.3.7 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f6313663bc3f6e896e6166ad97a16296b52e59f9f2ef93f5b6ceb8a3031caa
-  data.tar.gz: e916c89df8b3d7bbf7c310c0299a6b7134caf71a0514091f4f87a171247750a2
+  metadata.gz: e4e6a6afb6888a5be474a97195f41e06a2e1706d9f65a0700f17bce7f6dd82af
+  data.tar.gz: 3dd62a4e251d29e9e72e5538f548623662ed2ff16da46deadf8843585f8db658
 SHA512:
-  metadata.gz: f19ca9b2808b3d293b1a6ffef2c8b3287f1f69471c914bf775d51b3259d3dc837cee635d647c575dab70795b06b54c37214d2c51e9138a2093df5d3e20d5b478
-  data.tar.gz: d6c5b5c78de3f328486d4e107f1d6c336bb13be4738ad0d1b4e3b7b9b6af89f1a7bc77d09a7a27bd9f61160f38f4a5dc6c3a1ec5ae3f9f33705d6c52188e41f5
+  metadata.gz: bc73faf474cb22965f3ec95bdae48d13514505d4072f0fe3ca47f1dbccc8b04aad404e90ecd2b04afa7dc401dc2f66d087fea316b26e46edf1403945e7e3c305
+  data.tar.gz: 9c10a3b062c88f6145deb1adbbe3e8a2574e9f4dac39c2b7706fbc84643ee031891dae270197f910ceda3e5d0513f0929d574889e506c53a6f5048cb9be36dfa

data/.github/workflows/pages.yml

@@ -0,0 +1,46 @@
+name: Deploy RDoc site to Pages
+
+on:
+  push:
+    branches: [ 'master' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@250fcd6a742febb1123a77a841497ccaa8b9e939 # v1.152.0
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build with RDoc
+        run: bundle exec rake rdoc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with: { path: 'doc' }
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

data/.github/workflows/test.yml

@@ -7,7 +7,7 @@ jobs:
     uses: ruby/actions/.github/workflows/ruby_versions.yml@master
     with:
       engine: cruby
-      min_version: 2.6
+      min_version: 2.7
 
   build:
     needs: ruby-versions
@@ -17,22 +17,15 @@ jobs:
         ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
         os: [ ubuntu-latest, macos-latest ]
         experimental: [false]
-        include:
-#          - ruby: 2.6
-#            os: ubuntu-latest
-#            experimental: true
-          - ruby: 2.6
-            os: macos-latest
-            experimental: false
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ matrix.experimental }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
-    - name: Install dependencies
-      run: bundle install
+        bundler-cache: true
+        rubygems: latest
     - name: Run test
-      run: rake test
+      run: bundle exec rake test

data/.gitignore

@@ -8,3 +8,5 @@
 /spec/reports/
 /tmp/
 /Gemfile.lock
+/benchmarks/Gemfile*
+/benchmarks/parser.yml

data/Gemfile

@@ -7,3 +7,6 @@ gemspec
 gem "rake"
 gem "rdoc"
 gem "test-unit"
+gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
+
+gem "benchmark-driver"

data/README.md

@@ -21,11 +21,24 @@ Or install it yourself as:
 
 ## Usage
 
+### 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.
+end
+```
+
 ### List sender and subject of all recent messages in the default mailbox
 
 ```ruby
-imap = Net::IMAP.new('mail.example.com')
-imap.authenticate('LOGIN', 'joe_user', 'joes_password')
 imap.examine('INBOX')
 imap.search(["RECENT"]).each do |message_id|
   envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
@@ -36,8 +49,6 @@ end
 ### Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
 
 ```ruby
-imap = Net::IMAP.new('mail.example.com')
-imap.authenticate('LOGIN', 'joe_user', 'joes_password')
 imap.select('Mail/sent-mail')
 if not imap.list('Mail/', 'sent-apr03')
   imap.create('Mail/sent-apr03')

data/Rakefile

@@ -10,11 +10,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-task :sync_tool do
-  require 'fileutils'
-  FileUtils.cp "../ruby/tool/lib/core_assertions.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/envutil.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/find_executable.rb", "./test/lib"
-end
-
 task :default => :test

data/docs/styles.css

@@ -22,15 +22,3 @@ body {
    */
   font-weight: 400;
 }
-
-@media only screen and (min-width: 600px) {
-  nav {
-    height: 100%;
-    position: fixed;
-    overflow-y: scroll;
-  }
-
-  nav #class-metadata {
-    margin-bottom: 5em;
-  }
-}

data/lib/net/imap/authenticators.rb

@@ -1,68 +1,37 @@
 # frozen_string_literal: true
 
-# Registry for SASL authenticators used by Net::IMAP.
+# Backward compatible delegators from Net::IMAP to Net::IMAP::SASL.
 module Net::IMAP::Authenticators
 
-  # Adds an authenticator for Net::IMAP#authenticate to use.  +mechanism+ is the
-  # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  # implemented by +authenticator+ (for instance, <tt>"PLAIN"</tt>).
-  #
-  # The +authenticator+ must respond to +#new+ (or #call), receiving the
-  # authenticator configuration and return a configured authentication session.
-  # The authenticator session must respond to +#process+, receiving the server's
-  # challenge and returning the client's response.
-  #
-  # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
-  # examples.
-  def add_authenticator(auth_type, authenticator)
-    authenticators[auth_type] = authenticator
+  # Deprecated.  Use Net::IMAP::SASL.add_authenticator instead.
+  def add_authenticator(...)
+    warn(
+      "%s.%s is deprecated.  Use %s.%s instead." % [
+        Net::IMAP, __method__, Net::IMAP::SASL, __method__
+      ],
+      uplevel: 1
+    )
+    Net::IMAP::SASL.add_authenticator(...)
   end
 
-  # :call-seq:
-  #   authenticator(mechanism, ...)                            -> authenticator
-  #   authenticator(mech, *creds, **props) {|prop, auth| val } -> authenticator
-  #   authenticator(mechanism, authnid, creds, authzid=nil)    -> authenticator
-  #   authenticator(mechanism, **properties)                   -> authenticator
-  #   authenticator(mechanism) {|propname, authctx| value }    -> authenticator
-  #
-  # Builds a new authentication session context for +mechanism+.
-  #
-  # [Note]
-  #   This method is intended for internal use by connection protocol code only.
-  #   Protocol client users should see refer to their client's documentation,
-  #   e.g. Net::IMAP#authenticate for Net::IMAP.
-  #
-  # The call signatures documented for this method are recommendations for
-  # authenticator implementors.  All arguments (other than +mechanism+) are
-  # forwarded to the registered authenticator's +#new+ (or +#call+) method, and
-  # each authenticator must document its own arguments.
-  #
-  # The returned object represents a single authentication exchange and <em>must
-  # not</em> be reused for multiple authentication attempts.
-  def authenticator(mechanism, *authargs, **properties, &callback)
-    authenticator = authenticators.fetch(mechanism.upcase) do
-      raise ArgumentError, 'unknown auth type - "%s"' % mechanism
-    end
-    if authenticator.respond_to?(:new)
-      authenticator.new(*authargs, **properties, &callback)
-    else
-      authenticator.call(*authargs, **properties, &callback)
-    end
-  end
-
-  private
-
-  def authenticators
-    @authenticators ||= {}
+  # Deprecated.  Use Net::IMAP::SASL.authenticator instead.
+  def authenticator(...)
+    warn(
+      "%s.%s is deprecated.  Use %s.%s instead." % [
+        Net::IMAP, __method__, Net::IMAP::SASL, __method__
+      ],
+      uplevel: 1
+    )
+    Net::IMAP::SASL.authenticator(...)
   end
 
+  Net::IMAP.extend self
 end
 
-Net::IMAP.extend Net::IMAP::Authenticators
+class Net::IMAP
+  PlainAuthenticator = SASL::PlainAuthenticator # :nodoc:
+  deprecate_constant :PlainAuthenticator
 
-require_relative "authenticators/plain"
-
-require_relative "authenticators/login"
-require_relative "authenticators/cram_md5"
-require_relative "authenticators/digest_md5"
-require_relative "authenticators/xoauth2"
+  XOauth2Authenticator = SASL::XOAuth2Authenticator # :nodoc:
+  deprecate_constant :XOauth2Authenticator
+end

data/lib/net/imap/command_data.rb

@@ -52,13 +52,20 @@ module Net
     end
 
     def send_string_data(str, tag = nil)
-      case str
-      when ""
+      if str.empty?
         put_string('""')
-      when /[\x80-\xff\r\n]/n
-        # literal
+      elsif str.match?(/[\r\n]/n)
+        # literal, because multiline
         send_literal(str, tag)
-      when /[(){ \x00-\x1f\x7f%*"\\]/n
+      elsif !str.ascii_only?
+        if @utf8_strings
+          # quoted string
+          send_quoted_string(str)
+        else
+          # literal, because of non-ASCII bytes
+          send_literal(str, tag)
+        end
+      elsif str.match?(/[(){ \x00-\x1f\x7f%*"\\]/n)
         # quoted string
         send_quoted_string(str)
       else
@@ -67,7 +74,7 @@ module Net
     end
 
     def send_quoted_string(str)
-      put_string('"' + str.gsub(/["\\]/n, "\\\\\\&") + '"')
+      put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
     def send_literal(str, tag = nil)

data/lib/net/imap/data_encoding.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
+require "time"
 
 require_relative "errors"
 
@@ -102,8 +103,16 @@ module Net
     #
     # Decodes +string+ as an IMAP4 formatted "date-time".
     #
-    # Note that double quotes are not optional.  See STRFTIME.
+    # NOTE: Although double-quotes are not optional in the IMAP grammar,
+    # Net::IMAP currently parses "date-time" values as "quoted" strings and this
+    # removes the quotation marks.  To be useful for strings which have already
+    # been parsed as a quoted string, this method makes double-quotes optional.
+    #
+    # See STRFTIME.
     def self.decode_datetime(string)
+      unless string.start_with?(?") && string.end_with?(?")
+        string = '"%s"' % [string]
+      end
       DateTime.strptime(string, STRFTIME)
     end
 
@@ -113,7 +122,10 @@ module Net
     #
     # Same as +decode_datetime+, but returning a Time instead.
     def self.decode_time(string)
-      decode_datetime(string).to_time
+      unless string.start_with?(?") && string.end_with?(?")
+        string = '"%s"' % [string]
+      end
+      Time.strptime(string, STRFTIME)
     end
 
     class << self

data/lib/net/imap/deprecated_client_options.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # This module handles deprecated arguments to various Net::IMAP methods.
+    module DeprecatedClientOptions
+
+      # :call-seq:
+      #   Net::IMAP.new(host, **options) # standard keyword options
+      #   Net::IMAP.new(host, options)   # obsolete hash options
+      #   Net::IMAP.new(host, port)      # obsolete port argument
+      #   Net::IMAP.new(host, port, usessl, certs = nil, verify = true) # deprecated SSL arguments
+      #
+      # Translates Net::IMAP.new arguments for backward compatibility.
+      #
+      # ==== Obsolete arguments
+      #
+      # Using obsolete arguments does not a warning.  Obsolete arguments will be
+      # deprecated by a future release.
+      #
+      # If a second positional argument is given and it is a hash (or is
+      # convertable via +#to_hash+), it is converted to keyword arguments.
+      #
+      #     # Obsolete:
+      #     Net::IMAP.new("imap.example.com", options_hash)
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", **options_hash)
+      #
+      # If a second positional argument is given and it is not a hash, it is
+      # converted to the +port+ keyword argument.
+      #     # Obsolete:
+      #     Net::IMAP.new("imap.example.com", 114433)
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", port: 114433)
+      #
+      # ==== Deprecated arguments
+      #
+      # Using deprecated arguments prints a warning.  Convert to keyword
+      # arguments to avoid the warning.  Deprecated arguments will be removed in
+      # a future release.
+      #
+      # If +usessl+ is false, +certs+, and +verify+ are ignored.  When it true,
+      # all three arguments are converted to the +ssl+ keyword argument.
+      # Without +certs+ or +verify+, it is converted to <tt>ssl: true</tt>.
+      #     # DEPRECATED:
+      #     Net::IMAP.new("imap.example.com", nil, true) # => prints a warning
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", ssl: true)
+      #
+      # When +certs+ is a path to a directory, it is converted to <tt>ca_path:
+      # certs</tt>.
+      #     # DEPRECATED:
+      #     Net::IMAP.new("imap.example.com", nil, true, "/path/to/certs") # => prints a warning
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", ssl: {ca_path: "/path/to/certs"})
+      #
+      # When +certs+ is a path to a file, it is converted to <tt>ca_file:
+      # certs</tt>.
+      #     # DEPRECATED:
+      #     Net::IMAP.new("imap.example.com", nil, true, "/path/to/cert.pem") # => prints a warning
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", ssl: {ca_file: "/path/to/cert.pem"})
+      #
+      # When +verify+ is +false+, it is converted to <tt>verify_mode:
+      # OpenSSL::SSL::VERIFY_NONE</tt>.
+      #     # DEPRECATED:
+      #     Net::IMAP.new("imap.example.com", nil, true, nil, false) # => prints a warning
+      #     # Use instead:
+      #     Net::IMAP.new("imap.example.com", ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE})
+      #
+      def initialize(host, port_or_options = nil, *deprecated, **options)
+        if port_or_options.nil? && deprecated.empty?
+          super host, **options
+        elsif options.any?
+          # Net::IMAP.new(host, *__invalid__, **options)
+          raise ArgumentError, "Do not combine deprecated and keyword arguments"
+        elsif port_or_options.respond_to?(:to_hash) and deprecated.any?
+          # Net::IMAP.new(host, options, *__invalid__)
+          raise ArgumentError, "Do not use deprecated SSL params with options hash"
+        elsif port_or_options.respond_to?(:to_hash)
+          super host, **Hash.try_convert(port_or_options)
+        elsif deprecated.empty?
+          super host, port: port_or_options
+        elsif deprecated.shift
+          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          super host, port: port_or_options, ssl: create_ssl_params(*deprecated)
+        else
+          warn "DEPRECATED: Call Net::IMAP.new with keyword options", uplevel: 1
+          super host, port: port_or_options, ssl: false
+        end
+      end
+
+      # :call-seq:
+      #   starttls(**options) # standard
+      #   starttls(options = {}) # obsolete
+      #   starttls(certs = nil, verify = true) # deprecated
+      #
+      # Translates Net::IMAP#starttls arguments for backward compatibility.
+      #
+      # Support for +certs+ and +verify+ will be dropped in a future release.
+      #
+      # See ::new for interpretation of +certs+ and +verify+.
+      def starttls(*deprecated, **options)
+        if deprecated.empty?
+          super(**options)
+        elsif options.any?
+          # starttls(*__invalid__, **options)
+          raise ArgumentError, "Do not combine deprecated and keyword options"
+        elsif deprecated.first.respond_to?(:to_hash) && deprecated.length > 1
+          # starttls(*__invalid__, **options)
+          raise ArgumentError, "Do not use deprecated verify param with options hash"
+        elsif deprecated.first.respond_to?(:to_hash)
+          super(**Hash.try_convert(deprecated.first))
+        else
+          warn "DEPRECATED: Call Net::IMAP#starttls with keyword options", uplevel: 1
+          super(**create_ssl_params(*deprecated))
+        end
+      end
+
+      private
+
+      def create_ssl_params(certs = nil, verify = true)
+        params = {}
+        if certs
+          if File.file?(certs)
+            params[:ca_file] = certs
+          elsif File.directory?(certs)
+            params[:ca_path] = certs
+          end
+        end
+        params[:verify_mode] =
+          verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+        params
+      end
+
+    end
+  end
+end

data/lib/net/imap/errors.rb

@@ -47,7 +47,27 @@ module Net
     class ByeResponseError < ResponseError
     end
 
+    # Error raised when the server sends an invalid response.
+    #
+    # This is different from UnknownResponseError: the response has been
+    # rejected.  Although it may be parsable, the server is forbidden from
+    # sending it in the current context.  The client should automatically
+    # disconnect, abruptly (without logout).
+    #
+    # Note that InvalidResponseError does not inherit from ResponseError: it
+    # can be raised before the response is fully parsed.  A related
+    # ResponseParseError or ResponseError may be the #cause.
+    class InvalidResponseError < Error
+    end
+
     # Error raised upon an unknown response from the server.
+    #
+    # This is different from InvalidResponseError: the response may be a
+    # valid extension response and the server may be allowed to send it in
+    # this context, but Net::IMAP either does not know how to parse it or
+    # how to handle it.  This could result from enabling unknown or
+    # unhandled extensions.  The connection may still be usable,
+    # but—depending on context—it may be prudent to disconnect.
     class UnknownResponseError < ResponseError
     end