From 9df57b7fe54d9581a33ec901f5109c6288bb90ef Mon Sep 17 00:00:00 2001 From: nick evans Date: Sat, 22 Mar 2025 14:31:32 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Add=20docs=20for=20receiver=20th?= =?UTF-8?q?read=20&=20server=20responses?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most importantly, this documents the scenarios that need extra care to avoid memory leaks: * 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. --- lib/net/imap.rb | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 50566d06..181fd4a0 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -207,6 +207,37 @@ 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 #add_response_handler to handle responses after each one is received. + # Use #extract_responses, #clear_responses, or #responses (with a block) to + # prune responses. + # # == Errors # # An \IMAP server can send three different types of responses to indicate