net-imap 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc6f6d65e2f5092b38316ed4d381551838dd412a5b376c06359225e8f53a020c
-  data.tar.gz: d5daf47c70a868650687f7db3d1a1e074555a634708c16792e19f1cb53f8cc83
+  metadata.gz: ffcec5e3cc42d7f72c63520110ec442f760c35472401de495001f420cfa059c5
+  data.tar.gz: aedd703997fc651cb6c67635a3d20a4159720c6e1bda41c07322f2bd67a627d6
 SHA512:
-  metadata.gz: 1aeb682e73a666591079aac75c4325f22079dfbf61dbe71df135059b9087890633c31fd036e61757a217f1b1ff3e1d3771801a7ec6f3817646a0f8d2c0896386
-  data.tar.gz: 8cd118d9943b83010dd2f4916ab7641e120743991d3bc06062c4eb286098d1af8af05d86854b3e44235a0b3263b801db1cf9a7d64ac3140d89eda1aca086e6cd
+  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

@@ -11,7 +11,7 @@ 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"
 

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

@@ -4,6 +4,8 @@ require "date"
 
 require_relative "errors"
 
+# :enddoc:
+
 module Net
   class IMAP < Protocol
 
@@ -25,6 +27,7 @@ module Net
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -45,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
@@ -77,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
@@ -94,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
@@ -115,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
@@ -128,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.to_s)
+      end
+    end
+
+    class Flag < Atom # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, data)
+        imap.__send__(:put_string, "\\#{data}")
       end
     end
 
@@ -146,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
 
@@ -221,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

@@ -66,11 +66,61 @@ module Net
         # 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
         #   reset(attr) -> attribute value

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_accessor :version_defaults
+        singleton_class.attr_reader :version_defaults
 
         @version_defaults = Hash.new {|h, k|
           # NOTE: String responds to both so the order is significant.
@@ -59,10 +59,6 @@ module Net
         end
 
         def self.compile_version_defaults!
-          # Temporarily assign Config.default, enabling #load_defaults(:default)
-          version_defaults[:default] = Config.default
-          # Use #load_defaults so some attributes are inherited from global.
-          version_defaults[:default] = Config.new.load_defaults(:default).freeze
           version_defaults[0.0r]     = Config[version_defaults.fetch(0.0r)]
 
           VERSIONS.each_cons(2) do |prior, version|
@@ -81,6 +77,7 @@ module Net
 
           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]
 

data/lib/net/imap/config.rb

@@ -281,6 +281,40 @@ module Net
         0.5r => true,
       }
 
+      # The maximum bytesize for sending non-synchronizing literals, when the
+      # server supports them.  To disable non-synchronizing literals, set the
+      # value to +-1+.
+      #
+      # Non-synchronizing literals are only sent when the server's
+      # capabilities[rdoc-ref:IMAP#capabilities] have been
+      # cached[rdoc-ref:IMAP#capabilities_cached?] and include either
+      # <tt>LITERAL+</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]],
+      # <tt>LITERAL-</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]], or
+      # +IMAP4rev2+ [RFC9051[https://www.rfc-editor.org/rfc/rfc9051]].
+      #
+      # For <tt>LITERAL+</tt>, this value is the only limit on whether a literal
+      # value is sent as non-synchronizing literals.  For <tt>LITERAL-</tt> and
+      # <tt>IMAP4rev2</tt>, non-synchronizing literals must also be smaller than
+      # +4096+ bytes.
+      #
+      # Non-synchronizing literals avoid the latency of waiting for the server
+      # to allow continuation.  However, if a client sends a non-synchronizing
+      # literal that is too large for the server, the server may need to close
+      # the connection.  Because <tt>LITERAL+</tt> does not directly indicate
+      # the server's limits, it's best to avoid sending very large
+      # non-synchronized literals.
+      #
+      # ==== Versioned Defaults
+      #
+      # max_non_synchronizing_literal <em>was added in +v0.6.4+.</em>
+      #
+      # * original: +-1+ (_never_ send non-synchronizing literals)
+      # * +0.6+: 16 KiB
+      attr_accessor :max_non_synchronizing_literal, type: Integer?, defaults: {
+        0.0r => -1,
+        0.6r => 16 << 16, # 16 KiB
+      }
+
       # The maximum allowed server response size.  When +nil+, there is no limit
       # on response size.
       #
@@ -578,7 +612,6 @@ module Net
         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
@@ -631,6 +664,7 @@ module Net
         to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end
 
+      Struct   = AttrAccessors.struct
       @default = AttrVersionDefaults.compile_default!
       @global  = default.new
       AttrVersionDefaults.compile_version_defaults!

data/lib/net/imap/data_encoding.rb

@@ -174,6 +174,22 @@ module Net
         0 < num && num <= 0xffff_ffff
       end
 
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     number64        = 1*DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 <= n <= 9,223,372,036,854,775,807)
+      def valid_number64?(num)
+        0 <= num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     nz-number64     = digit-nz *DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 < n <= 9,223,372,036,854,775,807)
+      def valid_nz_number64?(num)
+        0 < num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
       # Check if argument is a valid 'mod-sequence-value' according to RFC 4551
       #     mod-sequence-value  = 1*DIGIT
       #                            ; Positive unsigned 64-bit integer
@@ -203,6 +219,20 @@ module Net
           "nz-number must be non-zero unsigned 32-bit integer: #{num}"
       end
 
+      # Ensure argument is 'number64' or raise DataFormatError
+      def ensure_number64(num)
+        return num if valid_number64?(num)
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
+      end
+
+      # Ensure argument is 'nz-number64' or raise DataFormatError
+      def ensure_nz_number64(num)
+        return num if valid_nz_number64?(num)
+        raise DataFormatError,
+          "nz-number64 must be non-zero unsigned 63-bit integer: #{num}"
+      end
+
       # Ensure argument is 'mod-sequence-value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
         return num if valid_mod_sequence_value?(num)
@@ -237,6 +267,26 @@ module Net
         end
       end
 
+      # Like #ensure_number64, but usable with numeric String input.
+      def coerce_number64(num)
+        case num
+        when Integer   then ensure_number64 num
+        when NUMBER_RE then ensure_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid number64" % [num]
+        end
+      end
+
+      # Like #ensure_nz_number64, but usable with numeric String input.
+      def coerce_nz_number64(num)
+        case num
+        when Integer   then ensure_nz_number64 num
+        when NUMBER_RE then ensure_nz_number64 Integer num
+        else
+          raise DataFormatError, "%p is not a valid nz-number64" % [num]
+        end
+      end
+
       # Like #ensure_mod_sequence_value, but usable with numeric String input.
       def coerce_mod_sequence_value(num)
         case num