net-imap 0.2.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee45560f32705f69d591b21df3d54372e69b444e3cb40f540f44b299c24a1803
-  data.tar.gz: 2aa318c6367dee1ce530139e06c9b78b0cf7e8eeb9411ef873f290dda78b6273
+  metadata.gz: 7942e0dcda47ac417806fb03aec58b66b8bac3ccf51f53f2f7ac2c6a588e35af
+  data.tar.gz: 38530b6af862085a9d1ff3c59c6536152acc15bb7d925d8547cd4feebea42872
 SHA512:
-  metadata.gz: f98f22799e9e1bff9c8f191d510688f52b7a7737de7fce8b76e42da1cfe8672a94cbb6c3a1eb24d7fce3d1855e6d809dfda52d91f2a67a4d216f66ba015960a9
-  data.tar.gz: d51b6eb6901db8742ed404714cdd0f54c46cf965cbf2de0130cea863f41a84e0779aac631689c7b0913f77e0fecd2184a66054fc0699bde5d4825db7fb188829
+  metadata.gz: 5bd29fb28b2b3ed9b1a0589e38f8844c47e671006d50deb4462fe5e8cfd97ad923ef0af3114a094d31cbb5943ff0ac9a15e549e67ac08be68eb04a0915eae67f
+  data.tar.gz: 7562e44288caa3538203d415f4d0b1dc4a44a77428e40c4b44046b86fb26b1abc2a4226229f4f494e54f21240cc96dea9106afded971829ec5873f507adab7c9

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

data/.github/workflows/test.yml

@@ -7,7 +7,7 @@ jobs:
     name: build (${{ matrix.ruby }} / ${{ matrix.os }})
     strategy:
       matrix:
-        ruby: [ head, '3.0', '2.7' ]
+        ruby: [ head, '3.1', '3.0', '2.7' ]
         os: [ ubuntu-latest, macos-latest ]
         experimental: [false]
         include:
@@ -20,7 +20,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ matrix.experimental }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.gitignore

@@ -4,6 +4,7 @@
 /coverage/
 /doc/
 /pkg/
+/rfcs
 /spec/reports/
 /tmp/
 /Gemfile.lock

data/Gemfile

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gemspec
 
 gem "rake"
+gem "rdoc"
 gem "test-unit"

data/LICENSE.txt

@@ -20,3 +20,65 @@ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.
+
+-------------------------------------------------------------------------
+
+This software includes documentation which has been copied from the relevant
+RFCs.  The copied documentation is covered by the following licenses:
+
+RFC 3501 (Editor: M. Crispin)
+Full Copyright Statement
+
+   Copyright (C) The Internet Society (2003).  All Rights Reserved.
+
+   This document and translations of it may be copied and furnished to
+   others, and derivative works that comment on or otherwise explain it
+   or assist in its implementation may be prepared, copied, published
+   and distributed, in whole or in part, without restriction of any
+   kind, provided that the above copyright notice and this paragraph are
+   included on all such copies and derivative works.  However, this
+   document itself may not be modified in any way, such as by removing
+   the copyright notice or references to the Internet Society or other
+   Internet organizations, except as needed for the purpose of
+   developing Internet standards in which case the procedures for
+   copyrights defined in the Internet Standards process must be
+   followed, or as required to translate it into languages other than
+   English.
+
+   The limited permissions granted above are perpetual and will not be
+   revoked by the Internet Society or its successors or assigns.  v This
+   document and the information contained herein is provided on an "AS
+   IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
+   FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+   LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL
+   NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY
+   OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+RFC9051 (Editors: A. Melnikov, B. Leiba)
+Copyright Notice
+
+   Copyright (c) 2021 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+   This document may contain material from IETF Documents or IETF
+   Contributions published or made publicly available before November
+   10, 2008.  The person(s) controlling the copyright in some of this
+   material may not have granted the IETF Trust the right to allow
+   modifications of such material outside the IETF Standards Process.
+   Without obtaining an adequate license from the person(s) controlling
+   the copyright in such materials, this document may not be modified
+   outside the IETF Standards Process, and derivative works of it may
+   not be created outside the IETF Standards Process, except to format
+   it for publication as an RFC or to translate it into languages other
+   than English.

data/README.md

@@ -51,11 +51,10 @@ imap.expunge
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `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 `bundle exec rake 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).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/net-imap.
-

data/Rakefile

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rake/clean"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test/lib"

data/benchmarks/stringprep.yml

@@ -0,0 +1,65 @@
+---
+prelude: |
+  begin
+    require "mongo"  # gem install mongo
+    require "idn"    # gem install idn-ruby
+  rescue LoadError
+    warn "You must 'gem install mongo idn-ruby' for this benchmark."
+    raise
+  end
+
+  MStrPrep = Mongo::Auth::StringPrep
+
+  # this indirection will slow it down a little bit
+  def mongo_saslprep(string)
+    MStrPrep.prepare(string,
+                     MStrPrep::Profiles::SASL::MAPPINGS,
+                     MStrPrep::Profiles::SASL::PROHIBITED,
+                     normalize: true,
+                     bidi: true)
+  rescue Mongo::Error::FailedStringPrepValidation
+    nil
+  end
+
+  $LOAD_PATH.unshift "./lib"
+  require "net/imap"
+  def net_imap_saslprep(string)
+    Net::IMAP::SASL::SASLprep.saslprep string, exception: false
+  end
+
+  def libidn_saslprep(string)
+    IDN::Stringprep.with_profile(string, "SASLprep")
+  rescue IDN::Stringprep::StringprepError
+    nil
+  end
+
+benchmark:
+  - net_imap_saslprep "I\u00ADX"     # RFC example 1. IX
+  - net_imap_saslprep "user"         # RFC example 2. user
+  - net_imap_saslprep "USER"         # RFC example 3. user
+  - net_imap_saslprep "\u00aa"       # RFC example 4. a
+  - net_imap_saslprep "\u2168"       # RFC example 5. IX
+  - net_imap_saslprep "\u0007"       # RFC example 6. Error - prohibited character
+  - net_imap_saslprep "\u0627\u0031" # RFC example 7. Error - bidirectional check
+  - net_imap_saslprep "I\u2000X"     # map to space: I X
+  - net_imap_saslprep "a longer string, e.g. a password"
+
+  - libidn_saslprep "I\u00ADX"     # RFC example 1. IX
+  - libidn_saslprep "user"         # RFC example 2. user
+  - libidn_saslprep "USER"         # RFC example 3. user
+  - libidn_saslprep "\u00aa"       # RFC example 4. a
+  - libidn_saslprep "\u2168"       # RFC example 5. IX
+  - libidn_saslprep "\u0007"       # RFC example 6. Error - prohibited character
+  - libidn_saslprep "\u0627\u0031" # RFC example 7. Error - bidirectional check
+  - libidn_saslprep "I\u2000X"     # map to space: I X
+  - libidn_saslprep "a longer string, e.g. a password"
+
+  - mongo_saslprep "I\u00ADX"     # RFC example 1. IX
+  - mongo_saslprep "user"         # RFC example 2. user
+  - mongo_saslprep "USER"         # RFC example 3. user
+  - mongo_saslprep "\u00aa"       # RFC example 4. a
+  - mongo_saslprep "\u2168"       # RFC example 5. IX
+  - mongo_saslprep "\u0007"       # RFC example 6. Error - prohibited character
+  - mongo_saslprep "\u0627\u0031" # RFC example 7. Error - bidirectional check
+  - mongo_saslprep "I\u2000X"     # map to space: I X
+  - mongo_saslprep "a longer string, e.g. a password"

data/benchmarks/table-regexps.yml

@@ -0,0 +1,39 @@
+prelude: |
+  require "json"
+  require "set"
+
+  all_codepoints = (0..0x10ffff).map{_1.chr("UTF-8") rescue nil}.compact
+
+  rfc3454_tables = Dir["rfcs/rfc3454*.json"]
+    .first
+    .then{File.read _1}
+    .then{JSON.parse _1}
+  titles = rfc3454_tables.delete("titles")
+
+  sets = rfc3454_tables
+    .transform_values{|t|t.keys rescue t}
+    .transform_values{|table|
+      table
+        .map{_1.split(?-).map{|i|Integer i, 16}}
+        .flat_map{_2 ? (_1.._2).to_a : _1}
+        .to_set
+    }
+
+  TABLE_A1_SET   = sets.fetch "A.1"
+  ASSIGNED_3_2   = /\p{AGE=3.2}/
+  UNASSIGNED_3_2 = /\P{AGE=3.2}/
+  TABLE_A1_REGEX = /(?-mix:[\u{0000}-\u{001f}\u{007f}-\u{00a0}\u{0340}-\u{0341}\u{06dd}\u{070f}\u{1680}\u{180e}\u{2000}-\u{200f}\u{2028}-\u{202f}\u{205f}-\u{2063}\u{206a}-\u{206f}\u{2ff0}-\u{2ffb}\u{3000}\u{e000}-\u{f8ff}\u{fdd0}-\u{fdef}\u{feff}\u{fff9}-\u{ffff}\u{1d173}-\u{1d17a}\u{1fffe}-\u{1ffff}\u{2fffe}-\u{2ffff}\u{3fffe}-\u{3ffff}\u{4fffe}-\u{4ffff}\u{5fffe}-\u{5ffff}\u{6fffe}-\u{6ffff}\u{7fffe}-\u{7ffff}\u{8fffe}-\u{8ffff}\u{9fffe}-\u{9ffff}\u{afffe}-\u{affff}\u{bfffe}-\u{bffff}\u{cfffe}-\u{cffff}\u{dfffe}-\u{dffff}\u{e0001}\u{e0020}-\u{e007f}\u{efffe}-\u{10ffff}])|(?-mix:\p{Cs})/.freeze
+
+benchmark:
+
+  # matches A.1
+  - script: "all_codepoints.grep(TABLE_A1_SET)"
+  - script: "all_codepoints.grep(TABLE_A1_REGEX)"
+  - script: "all_codepoints.grep(UNASSIGNED_3_2)"
+  - script: "all_codepoints.grep_v(ASSIGNED_3_2)"
+
+  # doesn't match A.1
+  - script: "all_codepoints.grep_v(TABLE_A1_SET)"
+  - script: "all_codepoints.grep_v(TABLE_A1_REGEX)"
+  - script: "all_codepoints.grep_v(UNASSIGNED_3_2)"
+  - script: "all_codepoints.grep(ASSIGNED_3_2)"

data/docs/styles.css

@@ -0,0 +1,36 @@
+/* this is a work in progress. :) */
+
+main .method-header {
+  background: rgba(27,31,35,0.05);
+  border: 1px solid #6C8C22;
+  padding: 0.5em;
+  border-radius: 4px;
+  /* padding: 0 0.5em; */
+  /* border-width: 0 1px; */
+  /* border-color: #6C8C22; */
+  /* border-style: solid; */
+}
+
+main .method-description, main .aliases {
+  padding-left: 1em;
+}
+
+body {
+  /*
+   * The default (300) can be too low contrast.  Also, many fonts don't
+   * distinguish between 300->400, so <em>...</em> had no effect.
+   */
+  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/cram_md5.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "digest/md5"
-
 # Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
 # RFC2195[https://tools.ietf.org/html/rfc2195].  See Net::IMAP#authenticate.
 #
@@ -23,7 +21,11 @@ class Net::IMAP::CramMD5Authenticator
 
   private
 
-  def initialize(user, password)
+  def initialize(user, password, warn_deprecation: true, **_ignored)
+    if warn_deprecation
+      warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
+    end
+    require "digest/md5"
     @user = user
     @password = password
   end

data/lib/net/imap/authenticators/digest_md5.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "digest/md5"
-require "strscan"
-
 # Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type, specified
 # in RFC2831(https://tools.ietf.org/html/rfc2831).  See Net::IMAP#authenticate.
 #
@@ -29,8 +26,8 @@ class Net::IMAP::DigestMD5Authenticator
         sparams[k] = v
       end
 
-      raise DataFormatError, "Bad Challenge: '#{challenge}'" unless c.rest.size == 0
-      raise Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
+      raise Net::IMAP::DataFormatError, "Bad Challenge: '#{challenge}'" unless c.eos?
+      raise Net::IMAP::Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
 
       response = {
         :nonce => sparams['nonce'],
@@ -77,11 +74,18 @@ class Net::IMAP::DigestMD5Authenticator
     end
   end
 
-  def initialize(user, password, authname = nil)
+  def initialize(user, password, authname = nil, warn_deprecation: true)
+    if warn_deprecation
+      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
+      # TODO: recommend SCRAM instead.
+    end
+    require "digest/md5"
+    require "strscan"
     @user, @password, @authname = user, password, authname
     @nc, @stage = {}, STAGE_ONE
   end
 
+
   private
 
   STAGE_ONE = :stage_one
@@ -100,7 +104,7 @@ class Net::IMAP::DigestMD5Authenticator
   def qdval(k, v)
     return if k.nil? or v.nil?
     if %w"username authzid realm nonce cnonce digest-uri qop".include? k
-      v.gsub!(/([\\"])/, "\\\1")
+      v = v.gsub(/([\\"])/, "\\\1")
       return '%s="%s"' % [k, v]
     else
       return '%s=%s' % [k, v]

data/lib/net/imap/authenticators/login.rb

@@ -33,7 +33,10 @@ class Net::IMAP::LoginAuthenticator
   STATE_USER = :USER
   STATE_PASSWORD = :PASSWORD
 
-  def initialize(user, password)
+  def initialize(user, password, warn_deprecation: true, **_ignored)
+    if warn_deprecation
+      warn "WARNING: LOGIN SASL mechanism is deprecated. Use PLAIN instead."
+    end
     @user = user
     @password = password
     @state = STATE_USER

data/lib/net/imap/authenticators/xoauth2.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Net::IMAP::XOauth2Authenticator
+  def process(_data)
+    build_oauth2_string(@user, @oauth2_token)
+  end
+
+  private
+
+  def initialize(user, oauth2_token)
+    @user = user
+    @oauth2_token = oauth2_token
+  end
+
+  def build_oauth2_string(user, oauth2_token)
+    format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
+  end
+
+  Net::IMAP.add_authenticator 'XOAUTH2', self
+end

data/lib/net/imap/authenticators.rb

@@ -3,29 +3,51 @@
 # Registry for SASL authenticators used by Net::IMAP.
 module Net::IMAP::Authenticators
 
-  # Adds an authenticator for use with Net::IMAP#authenticate.  +auth_type+ is the
+  # Adds an authenticator for Net::IMAP#authenticate to use.  +mechanism+ is the
   # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  # supported by +authenticator+ (for instance, "+PLAIN+").  The +authenticator+
-  # is an object which defines a +#process+ method to handle authentication with
-  # the server.  See Net::IMAP::PlainAuthenticator, Net::IMAP::LoginAuthenticator,
-  # Net::IMAP::CramMD5Authenticator, and Net::IMAP::DigestMD5Authenticator for
-  # examples.
+  # 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.
   #
-  # If +auth_type+ refers to an existing authenticator, it will be
-  # replaced by the new one.
+  # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
+  # examples.
   def add_authenticator(auth_type, authenticator)
     authenticators[auth_type] = authenticator
   end
 
-  # Builds an authenticator for Net::IMAP#authenticate.  +args+ will be passed
-  # directly to the chosen authenticator's +#initialize+.
-  def authenticator(auth_type, *args)
-    auth_type = auth_type.upcase
-    unless authenticators.has_key?(auth_type)
-      raise ArgumentError,
-        format('unknown auth type - "%s"', auth_type)
+  # :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
-    authenticators[auth_type].new(*args)
   end
 
   private
@@ -38,7 +60,9 @@ end
 
 Net::IMAP.extend Net::IMAP::Authenticators
 
-require_relative "authenticators/login"
 require_relative "authenticators/plain"
+
+require_relative "authenticators/login"
 require_relative "authenticators/cram_md5"
 require_relative "authenticators/digest_md5"
+require_relative "authenticators/xoauth2"

data/lib/net/imap/command_data.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 require_relative "errors"
 
 module Net
@@ -21,7 +23,7 @@ module Net
             validate_data(i)
           end
         end
-      when Time
+      when Time, Date, DateTime
       when Symbol
       else
         data.validate
@@ -38,7 +40,9 @@ module Net
         send_number_data(data)
       when Array
         send_list_data(data, tag)
-      when Time
+      when Date
+        send_date_data(data)
+      when Time, DateTime
         send_time_data(data)
       when Symbol
         send_symbol_data(data)
@@ -101,15 +105,8 @@ module Net
       put_string(")")
     end
 
-    DATE_MONTH = %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
-
-    def send_time_data(time)
-      t = time.dup.gmtime
-      s = format('"%2d-%3s-%4d %02d:%02d:%02d +0000"',
-                 t.day, DATE_MONTH[t.month - 1], t.year,
-                 t.hour, t.min, t.sec)
-      put_string(s)
-    end
+    def send_date_data(date) put_string Net::IMAP.encode_date(date) end
+    def send_time_data(time) put_string Net::IMAP.encode_time(time) end
 
     def send_symbol_data(symbol)
       put_string("\\" + symbol.to_s)

data/lib/net/imap/data_encoding.rb

@@ -1,10 +1,50 @@
 # frozen_string_literal: true
 
+require "date"
+
 require_relative "errors"
 
 module Net
   class IMAP < Protocol
 
+    # strftime/strptime format for an IMAP4 +date+, excluding optional dquotes.
+    # Use via the encode_date and decode_date methods.
+    #
+    #   date            = date-text / DQUOTE date-text DQUOTE
+    #   date-text       = date-day "-" date-month "-" date-year
+    #
+    #   date-day        = 1*2DIGIT
+    #                       ; Day of month
+    #   date-month      = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
+    #                     "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
+    #   date-year       = 4DIGIT
+    STRFDATE = "%d-%b-%Y"
+
+    # strftime/strptime format for an IMAP4 +date-time+, including dquotes.
+    # See the encode_datetime and decode_datetime methods.
+    #
+    #   date-time       = DQUOTE date-day-fixed "-" date-month "-" date-year
+    #                     SP time SP zone DQUOTE
+    #
+    #   date-day-fixed  = (SP DIGIT) / 2DIGIT
+    #                       ; Fixed-format version of date-day
+    #   date-month      = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
+    #                     "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
+    #   date-year       = 4DIGIT
+    #   time            = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+    #                       ; Hours minutes seconds
+    #   zone            = ("+" / "-") 4DIGIT
+    #                       ; Signed four-digit value of hhmm representing
+    #                       ; hours and minutes east of Greenwich (that is,
+    #                       ; the amount that the given time differs from
+    #                       ; Universal Time).  Subtracting the timezone
+    #                       ; from the given time will give the UT form.
+    #                       ; The Universal Time zone is "+0000".
+    #
+    # Note that Time.strptime <tt>"%d"</tt> flexibly parses either space or zero
+    # padding.  However, the DQUOTEs are *not* optional.
+    STRFTIME = '"%d-%b-%Y %H:%M:%S %z"'
+
     # Decode a string from modified UTF-7 format to UTF-8.
     #
     # UTF-7 is a 7-bit encoding of Unicode [UTF7].  IMAP uses a
@@ -35,14 +75,70 @@ module Net
       }.force_encoding("ASCII-8BIT")
     end
 
-    # Formats +time+ as an IMAP-style date.
-    def self.format_date(time)
-      return time.strftime('%d-%b-%Y')
+    # Formats +time+ as an IMAP4 date.
+    def self.encode_date(date)
+      date.to_date.strftime STRFDATE
+    end
+
+    # :call-seq: decode_date(string) -> Date
+    #
+    # Decodes +string+ as an IMAP formatted "date".
+    #
+    # Double quotes are optional.  Day of month may be padded with zero or
+    # space.  See STRFDATE.
+    def self.decode_date(string)
+      string = string.delete_prefix('"').delete_suffix('"')
+      Date.strptime(string, STRFDATE)
+    end
+
+    # :call-seq: encode_datetime(time) -> string
+    #
+    # Formats +time+ as an IMAP4 date-time.
+    def self.encode_datetime(time)
+      time.to_datetime.strftime STRFTIME
     end
 
-    # Formats +time+ as an IMAP-style date-time.
+    # :call-seq: decode_datetime(string) -> DateTime
+    #
+    # Decodes +string+ as an IMAP4 formatted "date-time".
+    #
+    # Note that double quotes are not optional.  See STRFTIME.
+    def self.decode_datetime(string)
+      DateTime.strptime(string, STRFTIME)
+    end
+
+    # :call-seq: decode_time(string) -> Time
+    #
+    # Decodes +string+ as an IMAP4 formatted "date-time".
+    #
+    # Same as +decode_datetime+, but returning a Time instead.
+    def self.decode_time(string)
+      decode_datetime(string).to_time
+    end
+
+    class << self
+      alias encode_time     encode_datetime
+      alias format_date     encode_date
+      alias format_time     encode_time
+      alias parse_date      decode_date
+      alias parse_datetime  decode_datetime
+      alias parse_time      decode_time
+
+      # alias format_datetime encode_datetime  # n.b. this is overridden below...
+    end
+
+    # DEPRECATED:: The original version returned incorrectly formatted strings.
+    #              Strings returned by encode_datetime or format_time use the
+    #              correct IMAP4rev1 syntax for "date-time".
+    #
+    # This invalid format has been temporarily retained for backward
+    # compatibility.  A future release will change this method to return the
+    # correct format.
     def self.format_datetime(time)
-      return time.strftime('%d-%b-%Y %H:%M %z')
+      warn("#{self}.format_datetime incorrectly formats IMAP date-time. " \
+           "Convert to #{self}.encode_datetime or #{self}.format_time instead.",
+           uplevel: 1, category: :deprecated)
+      time.strftime("%d-%b-%Y %H:%M %z")
     end
 
     # Common validators of number and nz_number types

data/lib/net/imap/errors.rb

@@ -51,7 +51,7 @@ module Net
     class UnknownResponseError < ResponseError
     end
 
-    RESPONSE_ERRORS = Hash.new(ResponseError)
+    RESPONSE_ERRORS = Hash.new(ResponseError) # :nodoc:
     RESPONSE_ERRORS["NO"] = NoResponseError
     RESPONSE_ERRORS["BAD"] = BadResponseError