net-imap 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee45560f32705f69d591b21df3d54372e69b444e3cb40f540f44b299c24a1803
-  data.tar.gz: 2aa318c6367dee1ce530139e06c9b78b0cf7e8eeb9411ef873f290dda78b6273
+  metadata.gz: 9c96e58708687b3fb8ded9def89a66e3ca9d1d83717c76c1579928ed60fb2b52
+  data.tar.gz: 56c64b20eab875d49b03e7a18f46988850e38865fbd756b0e6db3d7ecaec5975
 SHA512:
-  metadata.gz: f98f22799e9e1bff9c8f191d510688f52b7a7737de7fce8b76e42da1cfe8672a94cbb6c3a1eb24d7fce3d1855e6d809dfda52d91f2a67a4d216f66ba015960a9
-  data.tar.gz: d51b6eb6901db8742ed404714cdd0f54c46cf965cbf2de0130cea863f41a84e0779aac631689c7b0913f77e0fecd2184a66054fc0699bde5d4825db7fb188829
+  metadata.gz: 6dc72eab65ac59b09328cad6d1ad9bcc86e4565f05416b6b7de952d2d9d4634f8f272b6e2bf36a0f386ae0acb46de506d28c3856e1a53058fa83f30edfd7275c
+  data.tar.gz: 6deb8133dd67519bd082ba287db7eda44500048ef30f6e25f43e6955ed4b82f96c690633375dad56af8590b578ea6df846422a8ae54d40e359bfd2795f2d4125

data/.github/workflows/test.yml

@@ -7,7 +7,7 @@ jobs:
     name: build (${{ matrix.ruby }} / ${{ matrix.os }})
     strategy:
       matrix:
-        ruby: [ head, '3.0', '2.7' ]
+        ruby: [ head, '3.3', '3.2', '3.1', '3.0', '2.7' ]
         os: [ ubuntu-latest, macos-latest ]
         experimental: [false]
         include:

data/lib/net/imap/errors.rb

@@ -11,6 +11,40 @@ module Net
     class DataFormatError < Error
     end
 
+    # Error raised when the socket cannot be read, due to a configured 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(" ")
+        return super(msg, *args) if kwargs.empty? # ruby 2.6 compatibility
+        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-parseable.
     class ResponseParseError < Error
     end

data/lib/net/imap/response_reader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    # See https://www.rfc-editor.org/rfc/rfc9051#section-2.2.2
+    class ResponseReader # :nodoc:
+      attr_reader :client
+
+      def initialize(client, sock)
+        @client, @sock = client, sock
+      end
+
+      def read_response_buffer
+        @buff = String.new
+        catch :eof do
+          while true
+            read_line
+            break unless (@literal_size = get_literal_size)
+            read_literal
+          end
+        end
+        buff
+      ensure
+        @buff = nil
+      end
+
+      private
+
+      attr_reader :buff, :literal_size
+
+      def bytes_read;       buff.bytesize                         end
+      def empty?;           buff.empty?                           end
+      def done?;            line_done? && !get_literal_size       end
+      def line_done?;       buff.end_with?(CRLF)                  end
+      def get_literal_size; /\{(\d+)\}\r\n\z/n =~ buff && $1.to_i end
+
+      def read_line
+        buff << (@sock.gets(CRLF, read_limit) or throw :eof)
+        max_response_remaining! unless line_done?
+      end
+
+      def read_literal
+        # check before allocating memory for literal
+        max_response_remaining!
+        literal = String.new(capacity: literal_size)
+        buff << (@sock.read(read_limit(literal_size), literal) or throw :eof)
+      ensure
+        @literal_size = nil
+      end
+
+      def read_limit(limit = nil)
+        [limit, max_response_remaining!].compact.min
+      end
+
+      def max_response_size;      client.max_response_size                end
+      def max_response_remaining; max_response_size &.- bytes_read        end
+      def response_too_large?;    max_response_size &.< min_response_size end
+      def min_response_size;      bytes_read + min_response_remaining     end
+
+      def min_response_remaining
+        empty? ? 3 : done? ? 0 : (literal_size || 0) + 2
+      end
+
+      def max_response_remaining!
+        return max_response_remaining unless response_too_large?
+        raise ResponseTooLargeError.new(
+          max_response_size: max_response_size,
+          bytes_read:        bytes_read,
+          literal_size:      literal_size,
+        )
+      end
+
+    end
+  end
+end

data/lib/net/imap.rb

@@ -106,6 +106,41 @@ module Net
   #
   # This script invokes the FETCH command and the SEARCH command concurrently.
   #
+  # When running multiple commands, care must be taken to avoid ambiguity.  For
+  # example, SEARCH responses are ambiguous about which command they are
+  # responding to, so search commands should not run simultaneously, unless the
+  # server supports +ESEARCH+ {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731] or
+  # IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].  See {RFC9051
+  # §5.5}[https://www.rfc-editor.org/rfc/rfc9051.html#section-5.5] for
+  # other examples of command sequences which should not be pipelined.
+  #
+  # == Unbounded memory use
+  #
+  # Net::IMAP reads server responses in a separate receiver thread per client.
+  # Unhandled response data is saved to #responses, and response_handlers run
+  # inside the receiver thread.  See the list of methods for {handling server
+  # responses}[rdoc-ref:Net::IMAP@Handling+server+responses], below.
+  #
+  # Because the receiver thread continuously reads and saves new responses, some
+  # scenarios must be careful to avoid unbounded memory use:
+  #
+  # * Commands such as #list or #fetch can have an enormous number of responses.
+  # * Commands such as #fetch can result in an enormous size per response.
+  # * Long-lived connections will gradually accumulate unsolicited server
+  #   responses, especially +EXISTS+, +FETCH+, and +EXPUNGE+ responses.
+  # * A buggy or untrusted server could send inappropriate responses, which
+  #   could be very numerous, very large, and very rapid.
+  #
+  # Use paginated or limited versions of commands whenever possible.
+  #
+  # Use #max_response_size to impose a limit on incoming server responses
+  # as they are being read.  <em>This is especially important for untrusted
+  # servers.</em>
+  #
+  # Use #add_response_handler to handle responses after each one is received.
+  # Use the +response_handlers+ argument to ::new to assign response handlers
+  # before the receiver thread is started.
+  #
   # == Errors
   #
   # An IMAP server can send three different types of responses to indicate
@@ -220,7 +255,9 @@ module Net
   #    Unicode", RFC-2152[https://tools.ietf.org/html/rfc2152], May 1997.
   #
   class IMAP < Protocol
-    VERSION = "0.2.3"
+    VERSION = "0.2.5"
+
+    autoload :ResponseReader, File.expand_path("imap/response_reader", __dir__)
 
     include MonitorMixin
     if defined?(OpenSSL::SSL)
@@ -251,6 +288,40 @@ module Net
     # Seconds to wait until an IDLE response is received.
     attr_reader :idle_response_timeout
 
+    # The maximum allowed server response size.  When +nil+, there is no limit
+    # on response size.
+    #
+    # The default value is _unlimited_ (after +v0.5.8+, the default is 512 MiB).
+    # A _much_ lower value should be used with untrusted servers (for example,
+    # when connecting to a user-provided hostname).  When using a lower limit,
+    # message bodies should be fetched in chunks rather than all at once.
+    #
+    # <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 a config
+    # attribute.</em>
+    #
+    # * original: +nil+ <em>(no limit)</em>
+    # * +0.5+: 512 MiB
+    attr_accessor :max_response_size
+
     # The thread to receive exceptions.
     attr_accessor :client_thread
 
@@ -955,6 +1026,11 @@ module Net
     #     end
     #   }
     #
+    # Response handlers can also be added when the client is created before the
+    # receiver thread is started, by the +response_handlers+ argument to ::new.
+    # This ensures every server response is handled, including the #greeting.
+    #
+    # Related: #remove_response_handler, #response_handlers
     def add_response_handler(handler = nil, &block)
       raise ArgumentError, "two Procs are passed" if handler && block
       @response_handlers.push(block || handler)
@@ -1070,6 +1146,13 @@ module Net
     #         OpenSSL::SSL::SSLContext#set_params as parameters.
     # open_timeout:: Seconds to wait until a connection is opened
     # idle_response_timeout:: Seconds to wait until an IDLE response is received
+    # response_handlers:: A list of response handlers to be added before the
+    #                     receiver thread is started.  This ensures every server
+    #                     response is handled, including the #greeting.  Note
+    #                     that the greeting is handled in the current thread,
+    #                     but all other responses are handled in the receiver
+    #                     thread.
+    # max_response_size:: See #max_response_size.
     #
     # The most common errors are:
     #
@@ -1100,8 +1183,10 @@ module Net
       @tagno = 0
       @open_timeout = options[:open_timeout] || 30
       @idle_response_timeout = options[:idle_response_timeout] || 5
+      @max_response_size     = options[:max_response_size]
       @parser = ResponseParser.new
       @sock = tcp_socket(@host, @port)
+      @reader = ResponseReader.new(self, @sock)
       begin
         if options[:ssl]
           start_tls_session(options[:ssl])
@@ -1112,6 +1197,7 @@ module Net
         @responses = Hash.new([].freeze)
         @tagged_responses = {}
         @response_handlers = []
+        options[:response_handlers]&.each do |h| add_response_handler(h) end
         @tagged_response_arrival = new_cond
         @continued_command_tag = nil
         @continuation_request_arrival = new_cond
@@ -1128,6 +1214,7 @@ module Net
         if @greeting.name == "BYE"
           raise ByeResponseError, @greeting
         end
+        @response_handlers.each do |handler| handler.call(@greeting) end
 
         @client_thread = Thread.current
         @receiver_thread = Thread.start {
@@ -1251,25 +1338,14 @@ module Net
     end
 
     def get_response
-      buff = String.new
-      while true
-        s = @sock.gets(CRLF)
-        break unless s
-        buff.concat(s)
-        if /\{(\d+)\}\r\n/n =~ s
-          s = @sock.read($1.to_i)
-          buff.concat(s)
-        else
-          break
-        end
-      end
+      buff = @reader.read_response_buffer
       return nil if buff.length == 0
-      if @@debug
-        $stderr.print(buff.gsub(/^/n, "S: "))
-      end
-      return @parser.parse(buff)
+      $stderr.print(buff.gsub(/^/n, "S: ")) if @@debug
+      @parser.parse(buff)
     end
 
+    #############################
+
     def record_response(name, data)
       unless @responses.has_key?(name)
         @responses[name] = []
@@ -1447,6 +1523,7 @@ module Net
         context.verify_callback = VerifyCallbackProc
       end
       @sock = SSLSocket.new(@sock, context)
+      @reader = ResponseReader.new(self, @sock)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
       ssl_socket_connect(@sock, @open_timeout)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Shugo Maeda
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -77,6 +76,7 @@ files:
 - lib/net/imap/flags.rb
 - lib/net/imap/response_data.rb
 - lib/net/imap/response_parser.rb
+- lib/net/imap/response_reader.rb
 - net-imap.gemspec
 homepage: https://github.com/ruby/net-imap
 licenses:
@@ -85,7 +85,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/ruby/net-imap
   source_code_uri: https://github.com/ruby/net-imap
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -100,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []