net-imap 0.5.9 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a31378c34762136e5fc341801a0b4073157dc6c35df6aae3254d3f7b90a07b7
-  data.tar.gz: cbf787e39ecfde5a7af0061baba54eae3d7b12077679854ea62b335fc9b48798
+  metadata.gz: ffcec5e3cc42d7f72c63520110ec442f760c35472401de495001f420cfa059c5
+  data.tar.gz: aedd703997fc651cb6c67635a3d20a4159720c6e1bda41c07322f2bd67a627d6
 SHA512:
-  metadata.gz: fd0c8a34fa212bb42a55e943bf8184c614256b52da4ac13bdddb48f74c8517f5c7b72addb2153af42d76f2a8bcf42627ceb34e874b7842d8a6dfd542ba577578
-  data.tar.gz: 91dd4d1d35582abb9e4fd0df64c63ee5c9320f3404d548bff0a4023e32dc9a6ddd6b90cd1cc221e637a4719f3cc5699d57cc337ea17a6454b3aa7d7be9ffb423
+  metadata.gz: 1fa95302f29607d152b991535a9d14cda5dae1a1fce06b1d831dd2b09f69b2fd845367e0ebed73dd4e79d04c064a801e59865e76947060a4811304728458f3c7
+  data.tar.gz: 2dc9a56758d6f370affc9540a8ca26b8ad866ca5ef0e5b9bc2c30ff6257e3461e5ed23173e1c5e98a2e95c1e0f0a844c96f9e34d41151e9196ab513ac6987d33

data/.document

@@ -0,0 +1,3 @@
+*.rdoc
+*.md
+lib

data/.rdoc_options

@@ -0,0 +1,7 @@
+---
+charset: UTF-8
+main_page: README.md
+markup: rdoc
+title: net-imap # rake task override's title to add the version number
+op_dir: doc
+# vim:ft=yaml

data/Gemfile

@@ -4,21 +4,23 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "digest"
+# 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"
-gem "rdoc"
+gem "rdoc", ">= 7.2.0"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
 gem "benchmark", require: false
 gem "benchmark-driver", require: false
+gem "vernier", require: false, platform: :mri
 
 group :test do
-  gem "simplecov",        require: false
-  gem "simplecov-html",   require: false
-  gem "simplecov-json",   require: false
+  gem "simplecov",        require: false, platforms: %i[mri windows]
+  gem "simplecov-html",   require: false, platforms: %i[mri windows]
+  gem "simplecov-json",   require: false, platforms: %i[mri windows]
 end

data/README.md

@@ -61,9 +61,9 @@ imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_i
   else
     imap.copy(message_id, "Mail/sent-apr03")
     imap.store(message_id, "+FLAGS", [:Deleted])
+    imap.expunge
   end
 end
-imap.expunge
 ```
 
 ## Development

data/lib/net/imap/command_data.rb

@@ -3,7 +3,8 @@
 require "date"
 
 require_relative "errors"
-require_relative "data_lite"
+
+# :enddoc:
 
 module Net
   class IMAP < Protocol
@@ -26,6 +27,7 @@ module Net
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -46,7 +48,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
@@ -78,9 +80,23 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(*, **) = send_literal(*, **, binary: true)
+
+    # `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).
+    def send_literal(str, tag = nil, binary: false, non_sync: nil)
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        non_sync = non_sync_literal?(str.bytesize) if non_sync.nil?
+        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
@@ -95,6 +111,13 @@ module Net
       end
     end
 
+    def non_sync_literal?(bytesize)
+      capabilities_cached? &&
+        bytesize <= config.max_non_synchronizing_literal &&
+        (capable?("LITERAL+") ||
+         bytesize <= 4096 && (capable?("IMAP4rev2") || capable?("LITERAL-")))
+    end
+
     def send_number_data(num)
       put_string(num.to_s)
     end
@@ -116,11 +139,13 @@ 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
-
     CommandData = Data.define(:data) do # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
       def send_data(imap, tag)
         raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
@@ -129,15 +154,109 @@ 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 send_data(imap, tag)
-        imap.__send__(:put_string, data)
+      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 = NumValidator.coerce_number64 bytesize
+          parts << RawText[text] unless text.empty?
+          parts << extract_literal(data, binary:, bytesize:, non_sync:)
+          data.bytesplice(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)
+        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
 
@@ -147,9 +266,39 @@ module Net
       end
     end
 
-    class Literal < CommandData # :nodoc:
+    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
+
+      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 # all bytes are okay
+
       def send_data(imap, tag)
-        imap.__send__(:send_literal, data, tag)
+        imap.__send__(:send_binary_literal, data, tag, non_sync:)
       end
     end
 
@@ -185,73 +334,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)
@@ -289,6 +371,14 @@ module Net
 
       module_function
 
+      def literal_or_literal8(input, name: "argument")
+        return input if input in Literal | Literal8
+        data = String.try_convert(input) \
+          or raise TypeError, "expected #{name} to be String, got #{input.class}"
+        type = data.include?("\0") ? Literal8 : Literal
+        type.new(data:)
+      end
+
       # Allows symbols in addition to strings
       def valid_string?(str)
         str.is_a?(Symbol) || str.respond_to?(:to_str)

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

@@ -27,24 +27,23 @@ module Net
 
         def self.attr_accessor(name) # :nodoc: internal API
           name = name.to_sym
+          raise ArgumentError, "already defined #{name}" if attributes.include?(name)
+          attributes << name
           def_delegators :data, name, :"#{name}="
         end
 
-        def self.attributes
-          instance_methods.grep(/=\z/).map { _1.to_s.delete_suffix("=").to_sym }
-        end
-        private_class_method :attributes
+        # An array of Config attribute names
+        singleton_class.attr_reader :attributes
+        @attributes = []
 
         def self.struct # :nodoc: internal API
-          unless defined?(self::Struct)
-            const_set :Struct, Struct.new(*attributes)
-          end
-          self::Struct
+          attributes.freeze
+          Struct.new(*attributes)
         end
 
         def initialize # :notnew:
           super()
-          @data = AttrAccessors.struct.new
+          @data = Config::Struct.new
         end
 
         # Freezes the internal attributes struct, in addition to +self+.

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

@@ -54,9 +54,72 @@ 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.
+        #
+        # Related: #overrides?
+        def inherited?(*attrs)
+          attrs = data.members if attrs.empty?
+          attrs.all? { data[_1] == INHERITED }
+        end
+
+        # :call-seq:
+        #   inherits_defaults?(*attrs) -> true | Rational | nil | false
+        #
+        # Returns whether all +attrs+ are inherited from a default config.
+        # When no +attrs+ are given, returns whether *all* attributes are
+        # inherited from a default config.
+        #
+        # Returns +true+ when all attributes inherit from Config.default, the
+        # version number (as a Rational) when all attributes inherit from a
+        # versioned default (see Config@Versioned+defaults), +nil+ if any
+        # attributes inherit from Config.global overrides (but not from
+        # non-global ancestors), or +false+ when any attributes have been
+        # overridden by +self+ or an ancestor (besides global or default
+        # configs),
+        #
+        # Related: #overrides?
+        def inherits_defaults?(*attrs)
+          if equal?(Config.default)
+            true
+          elsif equal?(Config.global)
+            true if inherited?(*attrs)
+          elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
+            attrs  = DEFAULT_TO_INHERIT if attrs.empty?
+            attrs &= DEFAULT_TO_INHERIT
+            (attrs.empty? || parent.inherits_defaults?(*attrs)) && v
+          else
+            inherited?(*attrs) && parent.inherits_defaults?(*attrs)
+          end
+        end
+
+        # :call-seq:
+        #   overrides?(attr)   -> true or false
+        #   overrides?(*attrs) -> true or false
+        #   overrides?         -> true or false
+        #
+        # Returns +true+ if +attr+ is defined on this config and not inherited
+        # from #parent.
+        #
+        # When multiple +attrs+ are given, returns +true+ if
+        # *any* of them are defined on +self+.  When no +attrs+ are given,
+        # returns +true+ if *any* attribute is overriden.
+        #
+        # Related: #inherited?
+        def overrides?(*attrs)
+          attrs = data.members if attrs.empty?
+          attrs.any? { data[_1] != INHERITED }
+        end
 
         # :call-seq:
         #   reset -> self

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

@@ -28,10 +28,22 @@ module Net
         end
         private_class_method :included
 
-        if defined?(Ractor.make_shareable)
-          def self.safe(...) Ractor.make_shareable nil.instance_eval(...).freeze end
+        if defined?(Ractor.shareable_proc)
+          def self.safe(&b)
+            case obj = b.call
+            when Proc
+              Ractor.shareable_proc(&obj)
+            else
+              Ractor.make_shareable obj
+            end
+          end
+        elsif defined?(Ractor.make_shareable)
+          def self.safe(&b)
+            obj = nil.instance_eval(&b).freeze
+            Ractor.make_shareable obj
+          end
         else
-          def self.safe(...) nil.instance_eval(...).freeze end
+          def self.safe(&b) nil.instance_eval(&b).freeze end
         end
         private_class_method :safe
 
@@ -48,10 +60,10 @@ module Net
         NilOrInteger = safe{->val { Integer val unless val.nil? }}
 
         Enum = ->(*enum) {
-          enum     = safe{enum}
-          expected = -"one of #{enum.map(&:inspect).join(", ")}"
+          safe_enum = safe{enum}
+          expected = -"one of #{safe_enum.map(&:inspect).join(", ")}"
           safe{->val {
-            return val if enum.include?(val)
+            return val if safe_enum.include?(val)
             raise ArgumentError, "expected %s, got %p" % [expected, val]
           }}
         }

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +defaults+ parameter to +attr_accessor+, which is used to compile
+      # Config.version_defaults.
+      module AttrVersionDefaults
+        # The <tt>x.y</tt> part of Net::IMAP::VERSION, as a Rational number.
+        CURRENT_VERSION = VERSION.to_r
+
+        # The config version used for <tt>Config[:next]</tt>.
+        NEXT_VERSION    = CURRENT_VERSION + 0.1r
+
+        # The config version used for <tt>Config[:future]</tt>.
+        FUTURE_VERSION  = 1.0r
+
+        VERSIONS = ((0.0r..FUTURE_VERSION) % 0.1r).to_a.freeze
+
+        # See Config.version_defaults.
+        singleton_class.attr_reader :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)
+        }
+
+        # :stopdoc: internal APIs only
+
+        def attr_accessor(name, defaults: nil, default: (unset = true), **kw)
+          unless unset
+            version  = DEFAULT_TO_INHERIT.include?(name) ? nil : 0.0r
+            defaults = { version => default }
+          end
+          defaults&.each_pair do |version, default|
+            AttrVersionDefaults.version_defaults[version] ||= {}
+            AttrVersionDefaults.version_defaults[version][name] = default
+          end
+          super(name, **kw)
+        end
+
+        def self.compile_default!
+          raise "Config.default already compiled" if Config.default
+          default = VERSIONS.select { _1 <= CURRENT_VERSION }
+            .filter_map { version_defaults[_1] }
+            .prepend(version_defaults.delete(nil))
+            .inject(&:merge)
+          Config.new(**default).freeze
+        end
+
+        def self.compile_version_defaults!
+          version_defaults[0.0r]     = Config[version_defaults.fetch(0.0r)]
+
+          VERSIONS.each_cons(2) do |prior, version|
+            updates = version_defaults[version]
+            version_defaults[version] = version_defaults[prior]
+              .then { updates ? _1.dup.update(**updates).freeze : _1 }
+          end
+
+          # 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 in Rational
+            version_defaults[k.to_f] = v
+          end
+
+          version_defaults[:original] = Config[0.0r]
+          version_defaults[:current]  = Config[CURRENT_VERSION]
+          version_defaults[:default]  = Config[CURRENT_VERSION]
+          version_defaults[:next]     = Config[NEXT_VERSION]
+          version_defaults[:future]   = Config[FUTURE_VERSION]
+
+          version_defaults.freeze
+        end
+
+      end
+    end
+  end
+end