net-imap 0.3.1 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a032f39f4325733e1c68595d730ae6eafe48702fd416480cfe37a0082f3ec340
-  data.tar.gz: e7f0d60f53ed135dea9f1262814902735c537adc97198c1284f32cf4e599da8b
+  metadata.gz: 30f6313663bc3f6e896e6166ad97a16296b52e59f9f2ef93f5b6ceb8a3031caa
+  data.tar.gz: e916c89df8b3d7bbf7c310c0299a6b7134caf71a0514091f4f87a171247750a2
 SHA512:
-  metadata.gz: 65d363c721fec3061313cdbe6a4746612699cf296a6434853b14c66d850cbd843389ccf8f88b77e658c966be1d9692324b03e0c4b0074acac8595795bda456ce
-  data.tar.gz: 03c8152b9fbd734ca4d5c1e6301a7d2c09bd3da1b5b5e937ce0b7c141ba7bce9f6ab3d4f291b6a4467dc88fdb02b1996579f9e404f3cd9f9d81b7eb69597609e
+  metadata.gz: f19ca9b2808b3d293b1a6ffef2c8b3287f1f69471c914bf775d51b3259d3dc837cee635d647c575dab70795b06b54c37214d2c51e9138a2093df5d3e20d5b478
+  data.tar.gz: d6c5b5c78de3f328486d4e107f1d6c336bb13be4738ad0d1b4e3b7b9b6af89f1a7bc77d09a7a27bd9f61160f38f4a5dc6c3a1ec5ae3f9f33705d6c52188e41f5

data/.github/workflows/test.yml

@@ -3,11 +3,18 @@ name: ubuntu
 on: [push, pull_request]
 
 jobs:
+  ruby-versions:
+    uses: ruby/actions/.github/workflows/ruby_versions.yml@master
+    with:
+      engine: cruby
+      min_version: 2.6
+
   build:
+    needs: ruby-versions
     name: build (${{ matrix.ruby }} / ${{ matrix.os }})
     strategy:
       matrix:
-        ruby: [ head, '3.1', '3.0', '2.7' ]
+        ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
         os: [ ubuntu-latest, macos-latest ]
         experimental: [false]
         include:

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/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/digest_md5.rb

@@ -15,7 +15,7 @@ class Net::IMAP::DigestMD5Authenticator
       @stage = STAGE_TWO
       sparams = {}
       c = StringScanner.new(challenge)
-      while c.scan(/(?:\s*,)?\s*(\w+)=("(?:[^\\"]+|\\.)*"|[^,]+)\s*/)
+      while c.scan(/(?:\s*,)?\s*(\w+)=("(?:[^\\"]|\\.)*"|[^,]+)\s*/)
         k, v = c[1], c[2]
         if v =~ /^"(.*)"$/
           v = $1
@@ -26,7 +26,7 @@ class Net::IMAP::DigestMD5Authenticator
         sparams[k] = v
       end
 
-      raise Net::IMAP::DataFormatError, "Bad Challenge: '#{challenge}'" unless c.eos?
+      raise Net::IMAP::DataFormatError, "Bad Challenge: '#{challenge}'" unless c.eos? and sparams['qop']
       raise Net::IMAP::Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
 
       response = {

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

@@ -7,7 +7,7 @@ class Net::IMAP::XOauth2Authenticator
 
   private
 
-  def initialize(user, oauth2_token)
+  def initialize(user, oauth2_token, **_)
     @user = user
     @oauth2_token = oauth2_token
   end

data/lib/net/imap/authenticators.rb

@@ -3,22 +3,42 @@
 # 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+.
+  # :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

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
@@ -14,9 +54,9 @@ module Net
     # Net::IMAP does _not_ automatically encode and decode
     # mailbox names to and from UTF-7.
     def self.decode_utf7(s)
-      return s.gsub(/&([^-]+)?-/n) {
-        if $1
-          ($1.tr(",", "/") + "===").unpack1("m").encode(Encoding::UTF_8, Encoding::UTF_16BE)
+      return s.gsub(/&([A-Za-z0-9+,]+)?-/n) {
+        if base64 = $1
+          (base64.tr(",", "/") + "===").unpack1("m").encode(Encoding::UTF_8, Encoding::UTF_16BE)
         else
           "&"
         end
@@ -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
 
-    # Formats +time+ as an IMAP-style date-time.
+    # :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
+
+    # :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