net-imap 0.3.4 → 0.5.6

data/lib/net/imap/stringprep.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # Regexps and utility methods for implementing stringprep profiles.  The
+    # \StringPrep algorithm is defined by
+    # {RFC-3454}[https://www.rfc-editor.org/rfc/rfc3454.html].  Each
+    # codepoint table defined in the RFC-3454 appendices is matched by a Regexp
+    # defined in this module.
+    module StringPrep
+      autoload :NamePrep, File.expand_path("stringprep/nameprep", __dir__)
+      autoload :SASLprep, File.expand_path("stringprep/saslprep", __dir__)
+      autoload :Tables,   File.expand_path("stringprep/tables",   __dir__)
+      autoload :Trace,    File.expand_path("stringprep/trace",    __dir__)
+
+      # ArgumentError raised when +string+ is invalid for the stringprep
+      # +profile+.
+      class StringPrepError < ArgumentError
+        attr_reader :string, :profile
+
+        def initialize(*args, string: nil, profile: nil)
+          @string  = -string.to_str  unless string.nil?
+          @profile = -profile.to_str unless profile.nil?
+          super(*args)
+        end
+      end
+
+      # StringPrepError raised when +string+ contains a codepoint prohibited by
+      # +table+.
+      class ProhibitedCodepoint < StringPrepError
+        attr_reader :table
+
+        def initialize(table, *args, **kwargs)
+          @table  = table
+          details = (title = Tables::TITLES[table]) ?
+            "%s [%s]" % [title, table] : table
+          message = "String contains a prohibited codepoint: %s" % [details]
+          super(message, *args, **kwargs)
+        end
+      end
+
+      # StringPrepError raised when +string+ contains bidirectional characters
+      # which violate the StringPrep requirements.
+      class BidiStringError < StringPrepError
+      end
+
+      # Returns a Regexp matching the given +table+ name.
+      def self.[](table)
+        Tables::REGEXPS.fetch(table)
+      end
+
+      module_function
+
+      # >>>
+      #   1. Map -- For each character in the input, check if it has a mapping
+      #      and, if so, replace it with its mapping.  This is described in
+      #      section 3.
+      #
+      #   2. Normalize -- Possibly normalize the result of step 1 using Unicode
+      #      normalization.  This is described in section 4.
+      #
+      #   3. Prohibit -- Check for any characters that are not allowed in the
+      #      output.  If any are found, return an error.  This is described in
+      #      section 5.
+      #
+      #   4. Check bidi -- Possibly check for right-to-left characters, and if
+      #      any are found, make sure that the whole string satisfies the
+      #      requirements for bidirectional strings.  If the string does not
+      #      satisfy the requirements for bidirectional strings, return an
+      #      error.  This is described in section 6.
+      #
+      #   The above steps MUST be performed in the order given to comply with
+      #   this specification.
+      #
+      def stringprep(string,
+                     maps:,
+                     normalization:,
+                     prohibited:,
+                     **opts)
+        string = string.encode("UTF-8") # also dups (and raises invalid encoding)
+        map_tables!(string, *maps)                     if maps
+        string.unicode_normalize!(normalization)       if normalization
+        check_prohibited!(string, *prohibited, **opts) if prohibited
+        string
+      end
+
+      def map_tables!(string, *tables)
+        tables.each do |table|
+          regexp, replacements = Tables::MAPPINGS.fetch(table)
+          string.gsub!(regexp, replacements)
+        end
+        string
+      end
+
+      # Checks +string+ for any codepoint in +tables+. Raises a
+      # ProhibitedCodepoint describing the first matching table.
+      #
+      # Also checks bidirectional characters, when <tt>bidi: true</tt>, which may
+      # raise a BidiStringError.
+      #
+      # +profile+ is an optional string which will be added to any exception that
+      # is raised (it does not affect behavior).
+      def check_prohibited!(string,
+                            *tables,
+                            bidi: false,
+                            unassigned: "A.1",
+                            stored: false,
+                            profile: nil)
+        tables  = Tables::TITLES.keys.grep(/^C/) if tables.empty?
+        tables |= [unassigned] if stored
+        tables |= %w[C.8] if bidi
+        table   = tables.find {|t|
+          case t
+          when String then Tables::REGEXPS.fetch(t).match?(string)
+          when Regexp then t.match?(string)
+          else raise ArgumentError, "only table names and regexps can be checked"
+          end
+        }
+        if table
+          raise ProhibitedCodepoint.new(
+            table, string: string, profile: profile
+          )
+        end
+        check_bidi!(string, profile: profile) if bidi
+      end
+
+      # Checks that +string+ obeys all of the "Bidirectional Characters"
+      # requirements in RFC-3454, §6:
+      #
+      # * The characters in \StringPrep\[\"C.8\"] MUST be prohibited
+      # * If a string contains any RandALCat character, the string MUST NOT
+      #   contain any LCat character.
+      # * If a string contains any RandALCat character, a RandALCat
+      #   character MUST be the first character of the string, and a
+      #   RandALCat character MUST be the last character of the string.
+      #
+      # This is usually combined with #check_prohibited!, so table "C.8" is only
+      # checked when <tt>c_8: true</tt>.
+      #
+      # Raises either ProhibitedCodepoint or BidiStringError unless all
+      # requirements are met.  +profile+ is an optional string which will be
+      # added to any exception that is raised (it does not affect behavior).
+      def check_bidi!(string, c_8: false, profile: nil)
+        check_prohibited!(string, "C.8", profile: profile) if c_8
+        if Tables::BIDI_FAILS_REQ2.match?(string)
+          raise BidiStringError.new(
+            Tables::BIDI_DESC_REQ2, string: string, profile: profile,
+          )
+        elsif Tables::BIDI_FAILS_REQ3.match?(string)
+          raise BidiStringError.new(
+            Tables::BIDI_DESC_REQ3, string: string, profile: profile,
+          )
+        end
+      end
+
+    end
+  end
+end

data/lib/net/imap/uidplus_data.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # *NOTE:* <em>UIDPlusData is deprecated and will be removed in the +0.6.0+
+    # release.</em>  To use AppendUIDData and CopyUIDData before +0.6.0+, set
+    # Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # UIDPlusData represents the ResponseCode#data that accompanies the
+    # +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ should send UIDPlusData in response to
+    # the append[rdoc-ref:Net::IMAP#append], copy[rdoc-ref:Net::IMAP#copy],
+    # move[rdoc-ref:Net::IMAP#move], {uid copy}[rdoc-ref:Net::IMAP#uid_copy],
+    # and {uid move}[rdoc-ref:Net::IMAP#uid_move] commands---unless the
+    # destination mailbox reports +UIDNOTSTICKY+.
+    #
+    # Note that append[rdoc-ref:Net::IMAP#append], copy[rdoc-ref:Net::IMAP#copy]
+    # and {uid_copy}[rdoc-ref:Net::IMAP#uid_copy] return UIDPlusData in their
+    # TaggedResponse.  But move[rdoc-ref:Net::IMAP#copy] and
+    # {uid_move}[rdoc-ref:Net::IMAP#uid_move] _should_ send UIDPlusData in an
+    # UntaggedResponse response before sending their TaggedResponse.  However
+    # some servers do send UIDPlusData in the TaggedResponse for +MOVE+
+    # commands---this complies with the older +UIDPLUS+ specification but is
+    # discouraged by the +MOVE+ extension and disallowed by +IMAP4rev2+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    #
+    class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids)
+      ##
+      # method: uidvalidity
+      # :call-seq: uidvalidity -> nonzero uint32
+      #
+      # The UIDVALIDITY of the destination mailbox.
+
+      ##
+      # method: source_uids
+      # :call-seq: source_uids -> nil or an array of nonzero uint32
+      #
+      # The UIDs of the copied or moved messages.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+
+      ##
+      # method: assigned_uids
+      # :call-seq: assigned_uids -> an array of nonzero uint32
+      #
+      # The newly assigned UIDs of the copied, moved, or appended messages.
+      #
+      # Note:: This always returns an array, even when it contains only one UID.
+
+      ##
+      # :call-seq: uid_mapping -> nil or a hash
+      #
+      # Returns a hash mapping each source UID to the newly assigned destination
+      # UID.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+      def uid_mapping
+        source_uids&.zip(assigned_uids)&.to_h
+      end
+    end
+
+    # >>>
+    #   *NOTE:* <em>AppendUIDData will replace UIDPlusData for +APPENDUID+ in the
+    #   +0.6.0+ release.</em>  To use AppendUIDData before +0.6.0+, set
+    #   Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # AppendUIDData represents the ResponseCode#data that accompanies the
+    # +APPENDUID+ {response code}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ (or +IMAP4rev2+) should send
+    # AppendUIDData inside every TaggedResponse returned by the
+    # append[rdoc-ref:Net::IMAP#append] command---unless the target mailbox
+    # reports +UIDNOTSTICKY+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    class AppendUIDData < Data.define(:uidvalidity, :assigned_uids)
+      def initialize(uidvalidity:, assigned_uids:)
+        uidvalidity   = Integer(uidvalidity)
+        assigned_uids = SequenceSet[assigned_uids]
+        NumValidator.ensure_nz_number(uidvalidity)
+        if assigned_uids.include_star?
+          raise DataFormatError, "uid-set cannot contain '*'"
+        end
+        super
+      end
+
+      ##
+      # attr_reader: uidvalidity
+      # :call-seq: uidvalidity -> nonzero uint32
+      #
+      # The UIDVALIDITY of the destination mailbox.
+
+      ##
+      # attr_reader: assigned_uids
+      #
+      # A SequenceSet with the newly assigned UIDs of the appended messages.
+
+      # Returns the number of messages that have been appended.
+      def size
+        assigned_uids.count_with_duplicates
+      end
+    end
+
+    # >>>
+    #   *NOTE:* <em>CopyUIDData will replace UIDPlusData for +COPYUID+ in the
+    #   +0.6.0+ release.</em>  To use CopyUIDData before +0.6.0+, set
+    #   Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # CopyUIDData represents the ResponseCode#data that accompanies the
+    # +COPYUID+ {response code}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ (or +IMAP4rev2+) should send CopyUIDData
+    # in response to
+    # copy[rdoc-ref:Net::IMAP#copy], {uid_copy}[rdoc-ref:Net::IMAP#uid_copy],
+    # move[rdoc-ref:Net::IMAP#copy], and {uid_move}[rdoc-ref:Net::IMAP#uid_move]
+    # commands---unless the destination mailbox reports +UIDNOTSTICKY+.
+    #
+    # Note that copy[rdoc-ref:Net::IMAP#copy] and
+    # {uid_copy}[rdoc-ref:Net::IMAP#uid_copy] return CopyUIDData in their
+    # TaggedResponse.  But move[rdoc-ref:Net::IMAP#copy] and
+    # {uid_move}[rdoc-ref:Net::IMAP#uid_move] _should_ send CopyUIDData in an
+    # UntaggedResponse response before sending their TaggedResponse.  However
+    # some servers do send CopyUIDData in the TaggedResponse for +MOVE+
+    # commands---this complies with the older +UIDPLUS+ specification but is
+    # discouraged by the +MOVE+ extension and disallowed by +IMAP4rev2+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    class CopyUIDData < Data.define(:uidvalidity, :source_uids, :assigned_uids)
+      def initialize(uidvalidity:, source_uids:, assigned_uids:)
+        uidvalidity   = Integer(uidvalidity)
+        source_uids   = SequenceSet[source_uids]
+        assigned_uids = SequenceSet[assigned_uids]
+        NumValidator.ensure_nz_number(uidvalidity)
+        if source_uids.include_star? || assigned_uids.include_star?
+          raise DataFormatError, "uid-set cannot contain '*'"
+        elsif source_uids.count_with_duplicates != assigned_uids.count_with_duplicates
+          raise DataFormatError, "mismatched uid-set sizes for %s and %s" % [
+            source_uids, assigned_uids
+          ]
+        end
+        super
+      end
+
+      ##
+      # attr_reader: uidvalidity
+      #
+      # The +UIDVALIDITY+ of the destination mailbox (a nonzero unsigned 32 bit
+      # integer).
+
+      ##
+      # attr_reader: source_uids
+      #
+      # A SequenceSet with the original UIDs of the copied or moved messages.
+
+      ##
+      # attr_reader: assigned_uids
+      #
+      # A SequenceSet with the newly assigned UIDs of the copied or moved
+      # messages.
+
+      # Returns the number of messages that have been copied or moved.
+      # source_uids and the assigned_uids will both the same number of UIDs.
+      def size
+        assigned_uids.count_with_duplicates
+      end
+
+      # :call-seq:
+      #   assigned_uid_for(source_uid) -> uid
+      #   self[source_uid] -> uid
+      #
+      # Returns the UID in the destination mailbox for the message that was
+      # copied from +source_uid+ in the source mailbox.
+      #
+      # This is the reverse of #source_uid_for.
+      #
+      # Related: source_uid_for, each_uid_pair, uid_mapping
+      def assigned_uid_for(source_uid)
+        idx = source_uids.find_ordered_index(source_uid) and
+          assigned_uids.ordered_at(idx)
+      end
+      alias :[] :assigned_uid_for
+
+      # :call-seq:
+      #   source_uid_for(assigned_uid) -> uid
+      #
+      # Returns the UID in the source mailbox for the message that was copied to
+      # +assigned_uid+ in the source mailbox.
+      #
+      # This is the reverse of #assigned_uid_for.
+      #
+      # Related: assigned_uid_for, each_uid_pair, uid_mapping
+      def source_uid_for(assigned_uid)
+        idx = assigned_uids.find_ordered_index(assigned_uid) and
+          source_uids.ordered_at(idx)
+      end
+
+      # Yields a pair of UIDs for each copied message.  The first is the
+      # message's UID in the source mailbox and the second is the UID in the
+      # destination mailbox.
+      #
+      # Returns an enumerator when no block is given.
+      #
+      # Please note the warning on uid_mapping before calling methods like
+      # +to_h+ or +to_a+ on the returned enumerator.
+      #
+      # Related: uid_mapping, assigned_uid_for, source_uid_for
+      def each_uid_pair
+        return enum_for(__method__) unless block_given?
+        source_uids.each_ordered_number.lazy
+          .zip(assigned_uids.each_ordered_number.lazy) do
+            |source_uid, assigned_uid|
+            yield source_uid, assigned_uid
+          end
+      end
+      alias each_pair each_uid_pair
+      alias each      each_uid_pair
+
+      # :call-seq: uid_mapping -> hash
+      #
+      # Returns a hash mapping each source UID to the newly assigned destination
+      # UID.
+      #
+      # <em>*Warning:*</em> The hash that is created may consume _much_ more
+      # memory than the data used to create it.  When handling responses from an
+      # untrusted server, check #size before calling this method.
+      #
+      # Related: each_uid_pair, assigned_uid_for, source_uid_for
+      def uid_mapping
+        each_uid_pair.to_h
+      end
+
+    end
+
+  end
+end

data/lib/net/imap/vanished_data.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # Net::IMAP::VanishedData represents the contents of a +VANISHED+ response,
+    # which is described by the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] extension.
+    # [{RFC7162 §3.2.10}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.2.10]].
+    #
+    # +VANISHED+ responses replace +EXPUNGE+ responses when either the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] or the
+    # {UIDONLY}[https://www.rfc-editor.org/rfc/rfc9586.html] extension has been
+    # enabled.
+    class VanishedData < Data.define(:uids, :earlier)
+
+      # Returns a new VanishedData object.
+      #
+      # * +uids+ will be converted by SequenceSet.[].
+      # * +earlier+ will be converted to +true+ or +false+
+      def initialize(uids:, earlier:)
+        uids    = SequenceSet[uids]
+        earlier = !!earlier
+        super
+      end
+
+      ##
+      # :attr_reader: uids
+      #
+      # SequenceSet of UIDs that have been permanently removed from the mailbox.
+
+      ##
+      # :attr_reader: earlier
+      #
+      # +true+ when the response was caused by Net::IMAP#uid_fetch with
+      # <tt>vanished: true</tt> or Net::IMAP#select/Net::IMAP#examine with
+      # <tt>qresync: true</tt>.
+      #
+      # +false+ when the response is used to announce message removals within an
+      # already selected mailbox.
+
+      # rdoc doesn't handle attr aliases nicely. :(
+      alias earlier? earlier # :nodoc:
+      ##
+      # :attr_reader: earlier?
+      #
+      # Alias for #earlier.
+
+      # Returns an Array of all of the UIDs in #uids.
+      #
+      # See SequenceSet#numbers.
+      def to_a; uids.numbers end
+
+    end
+  end
+end