net-imap 0.4.19 → 0.4.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d13d2ec5aeab6f5fce9d77841e77c690a2849d2d6393d4bac0847fcec6dcf2b
-  data.tar.gz: 2821ba41ca70465fdfc38005908ae2fa2828ecd5c3425bf407df27f2e949ea2b
+  metadata.gz: 9419630b908b12c7f89846682dae953e50376d89ebb3b7391b3426bb34480991
+  data.tar.gz: 4558a77d38a4def28af960c201ca9359fcc828d5a316f76f95cf3c0e575702b6
 SHA512:
-  metadata.gz: 45bb4a741d80d2097e487b3d1ca31196f97322d6104967c6cad6410d65321e372667a6ff5bbb5bf9aafbdddc7906c7fc05b88c2fff06984dc9efd8a309802ecc
-  data.tar.gz: '08acdba3fdc323f01bc593ac7fde03ed5e06f1265be821263213fd53714b647e81305713d6829b67adba55dfb541a231e8c0a2303ad83e3efada4088e10c8419'
+  metadata.gz: 5f4baf570c8ed5732493ba801121ae092177fca3ab5f9162ef66f0db2a23e91c09fe740d8ddba52977e65737906a6735a8405bb94e923111970621e79b813141
+  data.tar.gz: 624e1b8a76630bffa007391b303eab5729b20665d9a5242f58749e0127340ddd1a842eb94ca46da085ccfa91cc093367348586cde705b51fe3eff25882f8f096

data/Gemfile

@@ -4,7 +4,7 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "digest"
+# gem "digest"  # not included as a workaround for #576
 gem "strscan"
 gem "base64"
 

data/lib/net/imap/command_data.rb

@@ -25,6 +25,7 @@ module Net
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -45,7 +46,7 @@ module Net
       when Date
         send_date_data(data)
       when Symbol
-        send_symbol_data(data)
+        Flag[data].send_data(self, tag)
       else
         data.send_data(self, tag)
       end
@@ -77,9 +78,23 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(*a, **kw) send_literal(*a, **kw, binary: true) end
+
+    # `non_sync` is an optional tri-state flag:
+    # * `true`  -> Force non-synchronizing `LITERAL+`/`LITERAL-` behavior.
+    #   TODO: raise or warn when capabilities don't allow non_sync.
+    # * `false` -> Force normal synchronizing literal behavior.
+    # * `nil`   -> (default) Currently behaves like `false` (will be dynamic).
+    #   TODO: Dynamic, based on capabilities and bytesize.
+    def send_literal(str, tag = nil, binary: false, non_sync: nil)
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        prefix = "~" if binary
+        plus = "+" if non_sync
+        put_string("#{prefix}{#{str.bytesize}#{plus}}\r\n")
+        if non_sync
+          put_string(str)
+          return
+        end
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -115,37 +130,148 @@ module Net
     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)
-    end
+    # simplistic emulation of CommandData = Data.define(:data)
+    class CommandData # :nodoc:
+      class << self
+        def new(arg = nil, data: arg) super(data: data) end
+        alias :[] :new
+      end
+
+      def initialize(data:)
+        @data = data
+        freeze
+      end
+
+      attr_reader :data
+
+      def to_h(&block) block ? to_h.to_h(&block) : { data: data } end
+      def ==(other)   self.class === other && to_h  ==  other.to_h  end
+      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
+
+      # following class definition goes beyond the basic Data.define(:data)
+      ##
+
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
 
-    class RawData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+        raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
 
       def validate
       end
+    end
 
-      private
+    # Represents IMAP +text+ data, which may contain any 7-bit ASCII character,
+    # except for +NULL+, +CR+, or +LF+.  +text+ is extended to allow any
+    # multibyte +UTF-8+ character when either +UTF8=ACCEPT+ or +IMAP4rev2+ have
+    # been enabled, or when the server supports only +IMAP4rev2+ and not earlier
+    # IMAP revisions, or when the server advertises +UTF8=ONLY+.
+    #
+    # NOTE: The current implementation does not validate whether the connection
+    # currently supports UTF-8.  Future versions may change.
+    #
+    # The string's bytes must be valid ASCII or valid UTF-8.  The string's
+    # reported encoding is ignored, but the string is _not_ transcoded.
+    class RawText < CommandData # :nodoc:
+      def initialize(data:)
+        data = String(data.to_str)
+        data = if [Encoding::ASCII, Encoding::UTF_8].include?(data.encoding)
+          -data
+        elsif data.ascii_only?
+          -(data.dup.force_encoding("ASCII"))
+        else
+          -(data.dup.force_encoding("UTF-8"))
+        end
+        super
+        validate
+      end
 
-      def initialize(data)
-        @data = data
+      def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte must be binary literal encoded"
+        elsif !data.valid_encoding?
+          raise DataFormatError, "invalid UTF-8 must be literal encoded"
+        elsif /[\r\n]/.match?(data)
+          raise DataFormatError, "CR and LF bytes must be literal encoded"
+        end
       end
+
+      def ascii_only?; data.ascii_only? end
+
+      def send_data(imap, tag) imap.__send__(:put_string, data) end
     end
 
-    class Atom # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+    class RawData < CommandData # :nodoc:
+      def initialize(data:)
+        data = split_parts(data)
+        super
+        validate
       end
 
+      def send_data(imap, tag) data.each do _1.send_data(imap, tag) end end
+
       def validate
+        return unless RawText === data.last
+        text = data.last.data
+        if text.rindex(/~?\{[1-9]\d*\+?\}\z/n)
+          raise DataFormatError, "RawData cannot end with literal continuation"
+        end
       end
 
       private
 
-      def initialize(data)
-        @data = data
+      def split_parts(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, $'
+          bytesize = Integer bytesize, 10
+          parts << RawText[text] unless text.empty?
+          parts << extract_literal(data,
+                                   binary: binary,
+                                   bytesize: bytesize,
+                                   non_sync: non_sync)
+          data[0, bytesize] = ""
+        end
+        parts << RawText[data] unless data.empty?
+        parts
+      end
+
+      def extract_literal(data, binary:, bytesize:, non_sync:)
+        if data.bytesize < bytesize
+          raise DataFormatError, "Too few bytes in string for literal, " \
+            "expected: %s, remaining: %s" % [bytesize, data.bytesize]
+        end
+        literal = data.byteslice(0, bytesize)
+        (binary ? Literal8 : Literal).new(data: literal, non_sync: non_sync)
+      end
+    end
+
+    class Atom < CommandData # :nodoc:
+      def initialize(**)
+        super
+        validate
+      end
+
+      def validate
+        data.to_s.ascii_only? \
+          or raise DataFormatError, "#{self.class} must be ASCII only"
+        data.match?(ResponseParser::Patterns::ATOM_SPECIALS) \
+          and raise DataFormatError, "#{self.class} must not contain atom-specials"
+      end
+
+      def send_data(imap, tag)
+        imap.__send__(:put_string, data.to_s)
+      end
+    end
+
+    class Flag < Atom # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:put_string, "\\#{data}")
       end
     end
 
@@ -165,17 +291,52 @@ module Net
     end
 
     class Literal # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:send_literal, @data, tag)
+      class << self
+        def new(_data = nil, _non_sync = nil, data: _data, non_sync: _non_sync)
+          super(data: data, non_sync: non_sync)
+        end
+        alias :[] :new
       end
 
+      attr_reader :data, :non_sync
+
+      def to_h(&block) block ? to_h.to_h(&block) : { data: data, non_sync: non_sync } end
+      def ==(other)   self.class === other && to_h  ==  other.to_h  end
+      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
+
+      def initialize(data:, non_sync: nil)
+        data = -String(data.to_str).b or
+          raise DataFormatError, "#{self.class} expects string input"
+        @data, @non_sync = data, non_sync
+        validate
+        freeze
+      end
+
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
+      def bytesize; data.bytesize end
+
       def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte not allowed in #{self.class}.  " \
+            "Use #{Literal8} or a null-safe encoding."
+        end
       end
 
-      private
+      def send_data(imap, tag)
+        imap.__send__(:send_literal, data, tag, non_sync: non_sync)
+      end
+    end
 
-      def initialize(data)
-        @data = data
+    class Literal8 < Literal # :nodoc:
+      def validate; nil end # all bytes are okay
+
+      def send_data(imap, tag)
+        imap.__send__(:send_binary_literal, data, tag, non_sync: non_sync)
       end
     end
 

data/lib/net/imap/config/attr_type_coercion.rb

@@ -18,6 +18,8 @@ module Net
             super(attr)
             AttrTypeCoercion.attr_accessor(attr, type: type)
           end
+
+          module_function def Integer?; NilOrInteger end
         end
         private_constant :Macros
 
@@ -26,34 +28,33 @@ module Net
         end
         private_class_method :included
 
-        def self.attr_accessor(attr, type: nil)
-          return unless type
-          if    :boolean == type then boolean attr
-          elsif Integer  == type then integer attr
-          elsif Array   === type then enum    attr, type
-          else raise ArgumentError, "unknown type coercion %p" % [type]
-          end
-        end
+        # Used in v0.5.8+ for Ractor sharability.
+        def self.safe(...) nil.instance_eval(...).freeze end
+        private_class_method :safe
 
-        def self.boolean(attr)
-          define_method :"#{attr}=" do |val| super !!val end
-          define_method :"#{attr}?" do send attr end
+        Types = Hash.new do |h, type|
+          type.nil? || Proc === type or raise TypeError, "type not nil or Proc"
+          safe{type}
         end
+        Types[:boolean] = Boolean = safe{-> {!!_1}}
+        Types[Integer]  = safe{->{Integer(_1)}}
 
-        def self.integer(attr)
-          define_method :"#{attr}=" do |val| super Integer val end
+        def self.attr_accessor(attr, type: nil)
+          type = Types[type] or return
+          define_method :"#{attr}=" do |val| super type[val] end
+          define_method :"#{attr}?" do send attr end if type == Boolean
         end
 
-        def self.enum(attr, enum)
-          enum = enum.dup.freeze
+        NilOrInteger = safe{->val { Integer val unless val.nil? }}
+
+        Enum = ->(*enum) {
+          enum     = safe{enum}
           expected = -"one of #{enum.map(&:inspect).join(", ")}"
-          define_method :"#{attr}=" do |val|
-            unless enum.include?(val)
-              raise ArgumentError, "expected %s, got %p" % [expected, val]
-            end
-            super val
-          end
-        end
+          safe{->val {
+            return val if enum.include?(val)
+            raise ArgumentError, "expected %s, got %p" % [expected, val]
+          }}
+        }
 
       end
     end

data/lib/net/imap/config.rb

@@ -129,8 +129,25 @@ module Net
       def self.global; @global if defined?(@global) end
 
       # A hash of hard-coded configurations, indexed by version number or name.
+      # Values can be accessed with any object that responds to +to_sym+ or
+      # +to_r+/+to_f+ with a non-zero number.
+      #
+      # Config::[] gets named or numbered versions from this hash.
+      #
+      # For example:
+      #     Net::IMAP::Config.version_defaults[0.5] == Net::IMAP::Config[0.5]
+      #     Net::IMAP::Config[0.5]       == Net::IMAP::Config[0.5r]     # => true
+      #     Net::IMAP::Config["current"] == Net::IMAP::Config[:current] # => true
+      #     Net::IMAP::Config["0.5.6"]   == Net::IMAP::Config[0.5r]     # => true
       def self.version_defaults; @version_defaults end
-      @version_defaults = {}
+      @version_defaults = Hash.new {|h, k|
+        # NOTE: String responds to both so the order is significant.
+        # And ignore non-numeric conversion to zero, because: "wat!?".to_r == 0
+        (h.fetch(k.to_r, nil) || h.fetch(k.to_f, nil) if k.is_a?(Numeric)) ||
+          (h.fetch(k.to_sym, nil) if k.respond_to?(:to_sym)) ||
+          (h.fetch(k.to_r,   nil) if k.respond_to?(:to_r) && k.to_r != 0r) ||
+          (h.fetch(k.to_f,   nil) if k.respond_to?(:to_f) && k.to_f != 0.0)
+      }
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -153,18 +170,17 @@ module Net
         elsif config.nil? && global.nil?   then nil
         elsif config.respond_to?(:to_hash) then new(global, **config).freeze
         else
-          version_defaults.fetch(config) do
+          version_defaults[config] or
             case config
             when Numeric
               raise RangeError, "unknown config version: %p" % [config]
-            when Symbol
+            when String, Symbol
               raise KeyError, "unknown config name: %p" % [config]
             else
               raise TypeError, "no implicit conversion of %s to %s" % [
                 config.class, Config
               ]
             end
-          end
         end
       end
 
@@ -191,10 +207,13 @@ module Net
 
       # Seconds to wait until a connection is opened.
       #
+      # Applied separately for establishing TCP connection and starting a TLS
+      # connection.
+      #
       # If the IMAP object cannot open a connection within this time,
       # it raises a Net::OpenTimeout exception.
       #
-      # See Net::IMAP.new.
+      # See Net::IMAP.new and Net::IMAP#starttls.
       #
       # The default value is +30+ seconds.
       attr_accessor :open_timeout, type: Integer
@@ -223,6 +242,40 @@ module Net
       #   Use +SASL-IR+ when it is supported by the server and the mechanism.
       attr_accessor :sasl_ir, type: :boolean
 
+      # The maximum allowed server response size.  When +nil+, there is no limit
+      # on response size.
+      #
+      # The default value (512 MiB, since +v0.5.7+) is <em>very high</em> and
+      # unlikely to be reached.  To use a lower limit, fetch message bodies in
+      # chunks rather than all at once.  A _much_ lower value should be used
+      # with untrusted servers (for example, when connecting to a user-provided
+      # hostname).
+      #
+      # <em>Please Note:</em> this only limits the size per response.  It does
+      # not prevent a flood of individual responses and it does not limit how
+      # many unhandled responses may be stored on the responses hash.  See
+      # Net::IMAP@Unbounded+memory+use.
+      #
+      # Socket reads are limited to the maximum remaining bytes for the current
+      # response: max_response_size minus the bytes that have already been read.
+      # When the limit is reached, or reading a +literal+ _would_ go over the
+      # limit, ResponseTooLargeError is raised and the connection is closed.
+      # See also #socket_read_limit.
+      #
+      # Note that changes will not take effect immediately, because the receiver
+      # thread may already be waiting for the next response using the previous
+      # value.  Net::IMAP#noop can force a response and enforce the new setting
+      # immediately.
+      #
+      # ==== Versioned Defaults
+      #
+      # Net::IMAP#max_response_size <em>was added in +v0.2.5+ and +v0.3.9+ as an
+      # attr_accessor, and in +v0.4.20+ and +v0.5.7+ as a delegator to this
+      # config attribute.</em>
+      #
+      # * original: +nil+ <em>(no limit)</em>
+      # * +0.5+: 512 MiB
+      attr_accessor :max_response_size, type: Integer?
 
       # Controls the behavior of Net::IMAP#responses when called without any
       # arguments (+type+ or +block+).
@@ -250,7 +303,7 @@ module Net
       #   Raise an ArgumentError with the deprecation warning.
       #
       # Note: #responses_without_args is an alias for #responses_without_block.
-      attr_accessor :responses_without_block, type: [
+      attr_accessor :responses_without_block, type: Enum[
         :silence_deprecation_warning, :warn, :frozen_dup, :raise,
       ]
 
@@ -295,7 +348,7 @@ module Net
       #
       # [+false+ <em>(planned default for +v0.6+)</em>]
       #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
-      attr_accessor :parser_use_deprecated_uidplus_data, type: [
+      attr_accessor :parser_use_deprecated_uidplus_data, type: Enum[
         true, :up_to_max_size, false
       ]
 
@@ -401,6 +454,7 @@ module Net
         open_timeout: 30,
         idle_response_timeout: 5,
         sasl_ir: true,
+        max_response_size: nil,
         responses_without_block: :silence_deprecation_warning,
         parser_use_deprecated_uidplus_data: true,
         parser_max_deprecated_uidplus_data_size: 1000,
@@ -408,36 +462,63 @@ module Net
 
       @global = default.new
 
-      version_defaults[0.4] = Config[default.send(:defaults_hash)]
+      version_defaults[:default] = Config[default.send(:defaults_hash)]
 
-      version_defaults[0] = Config[0.4].dup.update(
+      version_defaults[0r] = Config[:default].dup.update(
         sasl_ir: false,
+        max_response_size: nil,
         parser_use_deprecated_uidplus_data: true,
         parser_max_deprecated_uidplus_data_size: 10_000,
       ).freeze
-      version_defaults[0.0] = Config[0]
-      version_defaults[0.1] = Config[0]
-      version_defaults[0.2] = Config[0]
-      version_defaults[0.3] = Config[0]
+      version_defaults[0.0r] = Config[0r]
+      version_defaults[0.1r] = Config[0r]
+      version_defaults[0.2r] = Config[0r]
+      version_defaults[0.3r] = Config[0r]
 
-      version_defaults[0.5] = Config[0.4].dup.update(
+      version_defaults[0.4r] = Config[0.3r].dup.update(
+        sasl_ir: true,
+        parser_max_deprecated_uidplus_data_size: 1000,
+      ).freeze
+
+      version_defaults[0.5r] = Config[0.4r].dup.update(
+        max_response_size: 512 << 20, # 512 MiB
         responses_without_block: :warn,
         parser_use_deprecated_uidplus_data: :up_to_max_size,
         parser_max_deprecated_uidplus_data_size: 100,
       ).freeze
 
-      version_defaults[:default] = Config[0.4]
-      version_defaults[:current] = Config[0.4]
-      version_defaults[:next]    = Config[0.5]
-
-      version_defaults[0.6]      = Config[0.5].dup.update(
+      version_defaults[0.6r] = Config[0.5r].dup.update(
         responses_without_block: :frozen_dup,
         parser_use_deprecated_uidplus_data: false,
         parser_max_deprecated_uidplus_data_size: 0,
       ).freeze
-      version_defaults[:future]  = Config[0.6]
+
+      version_defaults[0.7r] = Config[0.6r].dup.update(
+      ).freeze
+
+      # Safe conversions one way only:
+      #   0.6r.to_f == 0.6  # => true
+      #   0.6 .to_r == 0.6r # => false
+      version_defaults.to_a.each do |k, v|
+        next unless k.is_a? Rational
+        version_defaults[k.to_f] = v
+      end
+
+      current = VERSION.to_r
+      version_defaults[:original] = Config[0]
+      version_defaults[:current]  = Config[current]
+      version_defaults[:next]     = Config[current + 0.1r]
+
+      version_defaults[:future]   = Config[0.7r]
 
       version_defaults.freeze
+
+      if ($VERBOSE || $DEBUG) && self[:current].to_h != self[:default].to_h
+        warn "Misconfigured Net::IMAP::Config[:current] => %p,\n" \
+             " not equal to Net::IMAP::Config[:default] => %p" % [
+                self[:current].to_h, self[:default].to_h
+              ]
+      end
     end
   end
 end

data/lib/net/imap/errors.rb

@@ -11,6 +11,39 @@ module Net
     class DataFormatError < Error
     end
 
+    # Error raised when the socket cannot be read, due to a Config limit.
+    class ResponseReadError < Error
+    end
+
+    # Error raised when a response is larger than IMAP#max_response_size.
+    class ResponseTooLargeError < ResponseReadError
+      attr_reader :bytes_read, :literal_size
+      attr_reader :max_response_size
+
+      def initialize(msg = nil, *args,
+                     bytes_read:        nil,
+                     literal_size:      nil,
+                     max_response_size: nil,
+                     **kwargs)
+        @bytes_read        = bytes_read
+        @literal_size      = literal_size
+        @max_response_size = max_response_size
+        msg ||= [
+          "Response size", response_size_msg, "exceeds max_response_size",
+          max_response_size && "(#{max_response_size}B)",
+        ].compact.join(" ")
+        super(msg, *args, **kwargs)
+      end
+
+      private
+
+      def response_size_msg
+        if bytes_read && literal_size
+          "(#{bytes_read}B read + #{literal_size}B literal)"
+        end
+      end
+    end
+
     # Error raised when a response from the server is non-parsable.
     class ResponseParseError < Error
     end

data/lib/net/imap/response_data.rb

@@ -295,6 +295,14 @@ module Net
     #   because the server doesn't allow deletion of mailboxes with children.
     #   #data is +nil+.
     #
+    # ==== <tt>QUOTA=RES-*</tt> response codes
+    # See {[RFC9208]}[https://www.rfc-editor.org/rfc/rfc9208.html#section-4.3].
+    # * +OVERQUOTA+ (also in RFC5530[https://www.rfc-editor.org/rfc/rfc5530]),
+    #   with a tagged +NO+ response to an +APPEND+/+COPY+/+MOVE+ command when
+    #   the command would put the target mailbox over any quota, and with an
+    #   untagged +NO+ when a mailbox exceeds a soft quota (which may be caused
+    #   be external events).  #data is +nil+.
+    #
     # ==== +CONDSTORE+ extension
     # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
     # * +NOMODSEQ+, when selecting a mailbox that does not support
@@ -369,12 +377,24 @@ module Net
     # Net::IMAP#getquotaroot returns an array containing both MailboxQuotaRoot
     # and MailboxQuota objects.
     #
+    # ==== Required capability
+    #
+    # Requires +QUOTA+ [RFC2087[https://www.rfc-editor.org/rfc/rfc2087]]
+    # or <tt>QUOTA=RES-STORAGE</tt>
+    # [RFC9208[https://www.rfc-editor.org/rfc/rfc9208]] capability.
     class MailboxQuota < Struct.new(:mailbox, :usage, :quota)
       ##
       # method: mailbox
       # :call-seq: mailbox -> string
       #
-      # The mailbox with the associated quota.
+      # The quota root with the associated quota.
+      #
+      # NOTE: this was mistakenly named "mailbox".  But the quota root's name may
+      # differ from the mailbox.  A single quota root may cover multiple
+      # mailboxes, and a single mailbox may be governed by multiple quota roots.
+
+      # The quota root with the associated quota.
+      alias quota_root mailbox
 
       ##
       # method: usage
@@ -386,7 +406,7 @@ module Net
       # method: quota
       # :call-seq: quota -> Integer
       #
-      # Quota limit imposed on the mailbox.
+      # Storage limit imposed on the mailbox.
       #
     end