net-imap 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a032f39f4325733e1c68595d730ae6eafe48702fd416480cfe37a0082f3ec340
-  data.tar.gz: e7f0d60f53ed135dea9f1262814902735c537adc97198c1284f32cf4e599da8b
+  metadata.gz: 85c732bea9deedc8787a80daee38991be448a03e593f4653d91067f16d2ed699
+  data.tar.gz: 6a1880f7da062779af60bf190da72bc415b0f11ee5f04296a08d97bbf82233ba
 SHA512:
-  metadata.gz: 65d363c721fec3061313cdbe6a4746612699cf296a6434853b14c66d850cbd843389ccf8f88b77e658c966be1d9692324b03e0c4b0074acac8595795bda456ce
-  data.tar.gz: 03c8152b9fbd734ca4d5c1e6301a7d2c09bd3da1b5b5e937ce0b7c141ba7bce9f6ab3d4f291b6a4467dc88fdb02b1996579f9e404f3cd9f9d81b7eb69597609e
+  metadata.gz: '073296843ad22467cf1ab9e31adc6696f35a4fe8a81a3003e6ea0292a4fdb643f772355970d62531dae1bf53592ea1a99ae56e7ea0b4daf9c82719e6fefbf959'
+  data.tar.gz: c1aa2ed380ccf9adedca1bce427bc92629d2737f8439bccf697130460ef2b76e31ebf261563e505d0e206d075e6da52b278c772d3b768f12a14794b948a90667

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,9 +1,12 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rake/clean"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test/lib"
-  t.ruby_opts << "-rhelper"
+  t.ruby_opts << "-rbundler/setup -rhelper"
   t.test_files = FileList["test/**/test_*.rb"]
 end
 

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/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