net-imap 0.5.14 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33bccbb75eba778cb42fc5340afc2f10a899ca671123e8b538a39acbdf16bd1b
-  data.tar.gz: c4252164f38a0f36b827fb32247500e95293880e2f8026f4b7ed04926614df41
+  metadata.gz: 561e6151a9540c8eaa6c12fd16d625061843a053fb0b0c8a2f215eb1a518ef70
+  data.tar.gz: 5be61c15097d2e0007822fc6c4825f59795d6078d6cf9b5cbe6ed4dd2bd1d22e
 SHA512:
-  metadata.gz: e682041f5c1f0e071578c0910f3eace9438064741cce16b148870c73137fd38926154269907f4948dec365e83b9115facff5ec21ac23072270ef39bab64cea10
-  data.tar.gz: 8a04cac2ad54cd0bc4b2e2f5855bac16f571c3ab6aa0183caa1427ad7c420f8c3920e74b85871c22454dbd827c7772b24cfe96bcaf262222664c05f7483f5dbd
+  metadata.gz: f84a8adf89f177e953fe57e390b027232bc4c7325ecb0049221a88db87fccc76a09281aea87c4f48de05bc547db1248b628b9c271134a466aedba953305001cc
+  data.tar.gz: 0b82898fb8581bab9a30c5b3edb96c89d81c4bddf197ade29a25ef166db827983a6c2c25d1eda9989a9f985cfcbec52f4bf484dbc1b57cfde32f432dcd0dfbc3

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 # gem "digest"  # not included as a workaround for #576
 gem "strscan"
 gem "base64"
+gem "psych", ">= 5.3.0" # 5.2.5 for Data serialization, 5.3.0 for TruffleRuby
 
 gem "irb"
 gem "rake"

data/lib/net/imap/command_data.rb

@@ -3,9 +3,6 @@
 require "date"
 
 require_relative "errors"
-require_relative "data_lite"
-
-# :enddoc:
 
 module Net
   class IMAP < Protocol
@@ -28,7 +25,6 @@ module Net
         end
       when Time, Date, DateTime
       when Symbol
-        Flag.validate(data)
       else
         data.validate
       end
@@ -49,7 +45,7 @@ module Net
       when Date
         send_date_data(data)
       when Symbol
-        Flag[data].send_data(self, tag)
+        send_symbol_data(data)
       else
         data.send_data(self, tag)
       end
@@ -81,23 +77,9 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    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)
+    def send_literal(str, tag = nil)
       synchronize do
-        prefix = "~" if binary
-        plus = "+" if non_sync
-        put_string("#{prefix}{#{str.bytesize}#{plus}}\r\n")
-        if non_sync
-          put_string(str)
-          return
-        end
+        put_string("{" + str.bytesize.to_s + "}" + CRLF)
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -133,13 +115,11 @@ 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
 
-    CommandData = Data.define(:data) do # :nodoc:
-      def self.validate(...)
-        data = new(...)
-        data.validate
-        data
-      end
+    def send_symbol_data(symbol)
+      put_string("\\" + symbol.to_s)
+    end
 
+    CommandData = Data.define(:data) do # :nodoc:
       def send_data(imap, tag)
         raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
@@ -148,109 +128,15 @@ module Net
       end
     end
 
-    # 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 data.encoding in Encoding::ASCII | Encoding::UTF_8
-          -data
-        elsif data.ascii_only?
-          -(data.dup.force_encoding("ASCII"))
-        else
-          -(data.dup.force_encoding("UTF-8"))
-        end
-        super
-        validate
-      end
-
-      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?
-
-      def send_data(imap, tag) = imap.__send__(:put_string, data)
-    end
-
     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
-
-      def validate
-        return unless data.last in RawText(data: text)
-        if text.rindex(/~?\{[1-9]\d*\+?\}\z/n)
-          raise DataFormatError, "RawData cannot end with literal continuation"
-        end
-      end
-
-      private
-
-      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:, bytesize:, 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:)
-      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)
+        imap.__send__(:put_string, data)
       end
     end
 
-    class Flag < Atom # :nodoc:
+    class Atom < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, "\\#{data}")
+        imap.__send__(:put_string, data)
       end
     end
 
@@ -260,39 +146,9 @@ module Net
       end
     end
 
-    class Literal < Data.define(:data, :non_sync) # :nodoc:
-      def self.validate(...)
-        data = new(...)
-        data.validate
-        data
-      end
-
-      def initialize(data:, non_sync: nil)
-        data = -String(data.to_str).b or
-          raise DataFormatError, "#{self.class} expects string input"
-        super
-        validate
-      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
-
-      def send_data(imap, tag)
-        imap.__send__(:send_literal, data, tag, non_sync:)
-      end
-    end
-
-    class Literal8 < Literal # :nodoc:
-      def validate; nil end # all bytes are okay
-
+    class Literal < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_binary_literal, data, tag, non_sync:)
+        imap.__send__(:send_literal, data, tag)
       end
     end
 
@@ -328,73 +184,6 @@ module Net
       end
     end
 
-    # *DEPRECATED*.  Replaced by SequenceSet.
-    class MessageSet < CommandData # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:put_string, format_internal(data))
-      end
-
-      def validate
-        validate_internal(data)
-      end
-
-      private
-
-      def initialize(data:)
-        super
-        warn("DEPRECATED: #{MessageSet} should be replaced with #{SequenceSet}.",
-             uplevel: 1, category: :deprecated)
-        begin
-          # to ensure the input works with SequenceSet, too
-          SequenceSet.new(data)
-        rescue
-          warn "MessageSet input is incompatible with SequenceSet: [%s] %s" % [
-            $!.class, $!.message
-          ]
-        end
-      end
-
-      def format_internal(data)
-        case data
-        when "*"
-          return data
-        when Integer
-          if data == -1
-            return "*"
-          else
-            return data.to_s
-          end
-        when Range
-          return format_internal(data.first) +
-            ":" + format_internal(data.last)
-        when Array
-          return data.collect {|i| format_internal(i)}.join(",")
-        when ThreadMember
-          return data.seqno.to_s +
-            ":" + data.children.collect {|i| format_internal(i).join(",")}
-        end
-      end
-
-      def validate_internal(data)
-        case data
-        when "*"
-        when Integer
-          NumValidator.ensure_nz_number(data)
-        when Range
-        when Array
-          data.each do |i|
-            validate_internal(i)
-          end
-        when ThreadMember
-          data.children.each do |i|
-            validate_internal(i)
-          end
-        else
-          raise DataFormatError, data.inspect
-        end
-      end
-    end
-
     class ClientID < CommandData # :nodoc:
 
       def send_data(imap, tag)

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

@@ -54,9 +54,22 @@ module Net
         # Creates a new config, which inherits from +self+.
         def new(**attrs) self.class.new(self, **attrs) end
 
+        # :call-seq:
+        #   inherited?(attr)   -> true or false
+        #   inherited?(*attrs) -> true or false
+        #   inherited?         -> true or false
+        #
         # Returns +true+ if +attr+ is inherited from #parent and not overridden
         # by this config.
-        def inherited?(attr) data[attr] == INHERITED end
+        #
+        # When multiple +attrs+ are given, returns +true+ if *all* of them are
+        # inherited, or +false+ if any of them are overriden.  When no +attrs+
+        # are given, returns +true+ if *all* attributes are inherited, or
+        # +false+ if any attribute is overriden.
+        def inherited?(*attrs)
+          attrs = data.members if attrs.empty?
+          attrs.all? { data[_1] == INHERITED }
+        end
 
         # :call-seq:
         #   reset -> self

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

@@ -24,7 +24,7 @@ module Net
         VERSIONS = ((0.0r..FUTURE_VERSION) % 0.1r).to_a.freeze
 
         # See Config.version_defaults.
-        singleton_class.attr_reader :version_defaults
+        singleton_class.attr_accessor :version_defaults
 
         @version_defaults = Hash.new {|h, k|
           # NOTE: String responds to both so the order is significant.

data/lib/net/imap/config.rb

@@ -234,13 +234,26 @@ module Net
       #   Do not use +SASL-IR+, even when it is supported by the server and the
       #   mechanism.
       #
+      # [+:when_capabilities_cached+]
+      #   Use +SASL-IR+ when Net::IMAP#capabilities_cached? is +true+ and it is
+      #   supported by the server and the mechanism, but do not send a
+      #   +CAPABILITY+ command to discover the server capabilities.
+      #
+      #   <em>(+:when_capabilities_cached+ option was added by +v0.6.0+)</em>
+      #
       # [+true+ <em>(default since +v0.4+)</em>]
       #   Use +SASL-IR+ when it is supported by the server and the mechanism.
-      attr_accessor :sasl_ir, type: :boolean, defaults: {
+      attr_accessor :sasl_ir, type: Enum[
+        false, :when_capabilities_cached, true
+      ], defaults: {
         0.0r => false,
         0.4r => true,
       }
 
+      # :stopdoc:
+      alias sasl_ir? sasl_ir
+      # :startdoc:
+
       # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
       # capability is present.  When enforced, Net::IMAP will raise a
       # LoginDisabledError when that capability is present.
@@ -347,39 +360,32 @@ module Net
       #
       # Alias for responses_without_block
 
-      # Whether ResponseParser should use the deprecated UIDPlusData or
-      # CopyUIDData for +COPYUID+ response codes, and UIDPlusData or
-      # AppendUIDData for +APPENDUID+ response codes.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option only affects deprecation warnings.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # UIDPlusData stores its data in arrays of numbers, which is vulnerable to
-      # a memory exhaustion denial of service attack from an untrusted or
-      # compromised server.  Set this option to +false+ to completely block this
-      # vulnerability.  Otherwise, parser_max_deprecated_uidplus_data_size
-      # mitigates this vulnerability.
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # AppendUIDData and CopyUIDData are _mostly_ backward-compatible with
-      # UIDPlusData.  Most applications should be able to upgrade with little
-      # or no changes.
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # Config option added in +v0.4.19+ and +v0.5.6+.
       #
-      # <em>(Config option added in +v0.4.19+ and +v0.5.6+.)</em>
+      # <em>UIDPlusData removed in +v0.6.0+.</em>
       #
-      # <em>UIDPlusData will be removed in +v0.6+ and this config setting will
-      # be ignored.</em>
-      #
-      # ==== Valid options
+      # ==== Options
       #
       # [+true+ <em>(original default)</em>]
-      #    ResponseParser only uses UIDPlusData.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
       # [+:up_to_max_size+ <em>(default since +v0.5.6+)</em>]
-      #    ResponseParser uses UIDPlusData when the +uid-set+ size is below
-      #    parser_max_deprecated_uidplus_data_size.  Above that size,
-      #    ResponseParser uses AppendUIDData or CopyUIDData.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
-      # [+false+ <em>(planned default for +v0.6+)</em>]
-      #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
+      # [+false+ <em>(default since +v0.6.0+)</em>]
+      #    This is the only supported option <em>(since v0.6.0)</em>.
       attr_accessor :parser_use_deprecated_uidplus_data, type: Enum[
         true, :up_to_max_size, false
       ], defaults: {
@@ -388,22 +394,22 @@ module Net
         0.6r => false,
       }
 
-      # The maximum +uid-set+ size that ResponseParser will parse into
-      # deprecated UIDPlusData.  This limit only applies when
-      # parser_use_deprecated_uidplus_data is not +false+.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option is ignored.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # <em>Support for limiting UIDPlusData to a maximum size was added in
-      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.</em>
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>UIDPlusData will be removed in +v0.6+.</em>
+      # Support for limiting UIDPlusData to a maximum size was added in
+      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.
       #
-      # ==== Versioned Defaults
+      # <em>UIDPlusData was removed in +v0.6.0+.</em>
       #
-      # Because this limit guards against a remote server causing catastrophic
-      # memory exhaustion, the versioned default (used by #load_defaults) also
-      # applies to versions without the feature.
+      # ==== Versioned Defaults
       #
       # * +0.3+ and prior: <tt>10,000</tt>
       # * +0.4+: <tt>1,000</tt>
@@ -485,8 +491,142 @@ module Net
       # Returns all config attributes in a hash.
       def to_h; data.members.to_h { [_1, send(_1)] } end
 
+      # Returns a string representation of overriden config attributes and the
+      # inheritance chain.
+      #
+      # Attributes overridden by ancestors are also inspected, recursively.
+      # Attributes that are inherited from default configs are not shown (see
+      # Config@Versioned+defaults and Config@Named+defaults).
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     Net::IMAP::Config.new(0.4)
+      #       .new(open_timeout: 10, enforce_logindisabled: true)
+      #       .inspect
+      #     #=> "#<Net::IMAP::Config:0x0000745871125410 open_timeout=10 enforce_logindisabled=true
+      #     #      inherits from Net::IMAP::Config[0.4]
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Non-default attributes are listed after the ancestor config from which
+      # they are inherited.
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     config = Net::IMAP::Config.global
+      #       .new(open_timeout: 10, idle_response_timeout: 2)
+      #       .new(enforce_logindisabled: :when_capabilities_cached, sasl_ir: false)
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      #     Net::IMAP.debug = true
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global debug=true
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Use +pp+ (see #pretty_print) to inspect _all_ config attributes,
+      # including default values.
+      #
+      # Use #to_h to inspect all config attributes ignoring inheritance.
+      def inspect;
+        "#<#{inspect_recursive}>"
+      end
+      alias to_s inspect
+
+      # Used by PP[https://docs.ruby-lang.org/en/master/PP.html] to create a
+      # string representation of all config attributes and the inheritance
+      # chain.  Inherited attributes are listed with the ancestor config from
+      # which they are inherited.
+      #
+      #     pp Config.new[0.4].new(open_timeout: 10, idle_response_timeout: 10)
+      #     # #<Net::IMAP::Config:0x0000745871125410
+      #     #   open_timeout=10
+      #     #   idle_response_timeout=10
+      #     #   inherits from Net::IMAP::Config[0.4]
+      #     #     responses_without_block=:silence_deprecation_warning
+      #     #     max_response_size=nil
+      #     #     sasl_ir=true
+      #     #     enforce_logindisabled=false
+      #     #     parser_use_deprecated_uidplus_data=true
+      #     #     parser_max_deprecated_uidplus_data_size=1000
+      #     #     inherits from Net::IMAP::Config.global
+      #     #       inherits from Net::IMAP::Config.default
+      #     #         debug=false>
+      #
+      # Related: #inspect, #to_h.
+      def pretty_print(pp)
+        pp.group(2, "#<", ">") do
+          pretty_print_recursive(pp)
+        end
+      end
+
+      # :stopdoc:
+
       protected
 
+      def named_default?
+        equal?(Config.default) ||
+          AttrVersionDefaults::VERSIONS.any? { equal? Config[_1] }
+      end
+
+      def name
+        if    equal? Config.default   then "#{Config}.default"
+        elsif equal? Config.global    then "#{Config}.global"
+        elsif equal? Config[0.0r]     then "#{Config}[:original]"
+        elsif equal? Config[:default] then "#{Config}[:default]"
+        elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
+          "%s[%0.1f]" % [Config, v]
+        else
+          Kernel.instance_method(:to_s).bind_call(self).delete("<#>")
+        end
+      end
+
+      def inspect_recursive(attrs = AttrAccessors.struct.members)
+        strings  = [name]
+        assigned = assigned_attrs_hash(attrs)
+        strings.concat assigned.map { "%s=%p" % _1 }
+        if parent
+          if parent.equal?(Config.default)
+            inherited_overrides = []
+          elsif parent
+            inherited_overrides = attrs - assigned.keys
+            inherited_overrides &= DEFAULT_TO_INHERIT if parent.named_default?
+          end
+          strings << "inherits from #{parent.inspect_recursive(inherited_overrides)}"
+        end
+        strings.join " "
+      end
+
+      def pretty_print_recursive(pp, attrs = AttrAccessors.struct.members)
+        pp.text name
+        assigned = assigned_attrs_hash(attrs)
+        pp.breakable
+        pp.seplist(assigned, ->{pp.breakable}) do |key, val|
+          pp.text key.to_s
+          pp.text "="
+          pp.pp val
+        end
+        if parent
+          pp.breakable if assigned.any?
+          pp.nest(2) do
+            pp.text "inherits from "
+            parent.pretty_print_recursive(pp, attrs - assigned.keys)
+          end
+        elsif assigned.empty?
+          pp.text "(overridden)"
+        end
+      end
+
+      def assigned_attrs_hash(attrs)
+        own_attrs = attrs.reject { inherited?(_1) }
+        own_attrs.to_h { [_1, data[_1]] }
+      end
+
       def defaults_hash
         to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end

data/lib/net/imap/connection_state.rb

@@ -2,7 +2,7 @@
 
 module Net
   class IMAP
-    class ConnectionState < Net::IMAP::Data # :nodoc:
+    class ConnectionState < Data # :nodoc:
       def self.define(symbol, *attrs)
         symbol => Symbol
         state = super(*attrs)