net-imap 0.4.4 → 0.4.6

data/lib/net/imap/sequence_set.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    ##
+    # An IMAP {sequence
+    # set}[https://www.rfc-editor.org/rfc/rfc9051.html#section-4.1.1],
+    # is a set of message sequence numbers or unique identifier numbers
+    # ("UIDs").  It contains numbers and ranges of numbers.  The numbers are all
+    # non-zero unsigned 32-bit integers and one special value, <tt>*</tt>, that
+    # represents the largest value in the mailbox.
+    #
+    # *NOTE:* This SequenceSet class is currently a placeholder for unhandled
+    # extension data.  All it does now is validate.  It will be expanded to a
+    # full API in a future release.
+    class SequenceSet
+
+      def self.[](str) new(str).freeze end
+
+      def initialize(input)
+        @atom = -String.try_convert(input)
+        validate
+      end
+
+      # Returns the IMAP string representation.  In the IMAP grammar,
+      # +sequence-set+ is a subset of +atom+ which is a subset of +astring+.
+      attr_accessor :atom
+
+      # Returns #atom.  In the IMAP grammar, +atom+ is a subset of +astring+.
+      alias astring atom
+
+      # Returns the value of #atom
+      alias to_s atom
+
+      # Hash equality requires the same encoded #atom representation.
+      #
+      #   Net::IMAP::SequenceSet["1:3"]  .eql? Net::IMAP::SequenceSet["1:3"]  # => true
+      #   Net::IMAP::SequenceSet["1,2,3"].eql? Net::IMAP::SequenceSet["1:3"]  # => false
+      #   Net::IMAP::SequenceSet["1,3"]  .eql? Net::IMAP::SequenceSet["3,1"]  # => false
+      #   Net::IMAP::SequenceSet["9,1:*"].eql? Net::IMAP::SequenceSet["1:*"]  # => false
+      #
+      def eql?(other) self.class == other.class && atom == other.atom end
+      alias == eql?
+
+      # See #eql?
+      def hash; [self.class. atom].hash end
+
+      def inspect
+        (frozen? ? "%s[%p]" : "#<%s %p>") % [self.class, to_s]
+      end
+
+      # Unstable API, for internal use only (Net::IMAP#validate_data)
+      def validate # :nodoc:
+        ResponseParser::Patterns::SEQUENCE_SET_STR.match?(@atom) or
+          raise ArgumentError, "invalid sequence-set: %p" % [input]
+        true
+      end
+
+      # Unstable API, for internal use only (Net::IMAP#send_data)
+      def send_data(imap, tag) # :nodoc:
+        imap.__send__(:put_string, atom)
+      end
+
+    end
+  end
+end

data/lib/net/imap.rb

@@ -404,18 +404,18 @@ module Net
   #
   # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is not supported
   # yet, Net::IMAP supports several extensions that have been folded into it:
-  # +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+, and +UNSELECT+.
+  # +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +SASL-IR+, +UIDPLUS+, +UNSELECT+, and
+  # the fetch side of +BINARY+.
   # Commands for these extensions are listed with the {Core IMAP
   # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above.
   #
   # >>>
   #   <em>The following are folded into +IMAP4rev2+ but are currently
   #   unsupported or incompletely supported by</em> Net::IMAP<em>: RFC4466
-  #   extensions, +ESEARCH+, +SEARCHRES+, +LIST-EXTENDED+,
-  #   +LIST-STATUS+, +LITERAL-+, +BINARY+ fetch, and +SPECIAL-USE+.  The
-  #   following extensions are implicitly supported, but will be updated with
-  #   more direct support: RFC5530 response codes, <tt>STATUS=SIZE</tt>, and
-  #   <tt>STATUS=DELETED</tt>.</em>
+  #   extensions, +ESEARCH+, +SEARCHRES+, +LIST-EXTENDED+, +LIST-STATUS+,
+  #   +LITERAL-+, and +SPECIAL-USE+.  The following extensions are implicitly
+  #   supported, but will be updated with more direct support: RFC5530 response
+  #   codes, <tt>STATUS=SIZE</tt>, and <tt>STATUS=DELETED</tt>.</em>
   #
   # ==== RFC2087: +QUOTA+
   # - #getquota: returns the resource usage and limits for a quota root
@@ -437,6 +437,15 @@ module Net
   # ==== RFC2971: +ID+
   # - #id: exchanges client and server implementation information.
   #
+  # ==== RFC3516: +BINARY+
+  # The fetch side of +BINARY+ has been folded into
+  # IMAP4rev2[https://tools.ietf.org/html/rfc9051].
+  # - Updates #fetch and #uid_fetch with the +BINARY+, +BINARY.PEEK+, and
+  #   +BINARY.SIZE+ items.  See FetchData#binary and FetchData#binary_size.
+  #
+  # >>>
+  #   *NOTE:* The binary extension the #append command is _not_ supported yet.
+  #
   # ==== RFC3691: +UNSELECT+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
@@ -474,9 +483,17 @@ module Net
   #   which arranges the results into ordered groups or threads according to a
   #   chosen algorithm.
   #
-  # ==== +XLIST+ (non-standard, deprecated)
+  # ==== +X-GM-EXT-1+
+  # +X-GM-EXT-1+ is a non-standard Gmail extension.  See {Google's
+  # documentation}[https://developers.google.com/gmail/imap/imap-extensions].
+  # - Updates #fetch and #uid_fetch with support for +X-GM-MSGID+ (unique
+  #   message ID), +X-GM-THRID+ (thread ID), and +X-GM-LABELS+ (Gmail labels).
+  # - Updates #search with the +X-GM-RAW+ search attribute.
   # - #xlist: replaced by +SPECIAL-USE+ attributes in #list responses.
   #
+  # *NOTE:* The +OBJECTID+ extension should replace +X-GM-MSGID+ and
+  # +X-GM-THRID+, but Gmail does not support it (as of 2023-11-10).
+  #
   # ==== RFC6851: +MOVE+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
@@ -487,6 +504,13 @@ module Net
   #
   # - See #enable for information about support for UTF-8 string encoding.
   #
+  # ==== RFC8474: +OBJECTID+
+  # - Adds +MAILBOXID+ ResponseCode to #create tagged response.
+  # - Adds +MAILBOXID+ ResponseCode to #select and #examine untagged response.
+  # - Updates #fetch and #uid_fetch with the +EMAILID+ and +THREADID+ items.
+  #   See FetchData#emailid and FetchData#emailid.
+  # - Updates #status with support for the +MAILBOXID+ status attribute.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -612,6 +636,10 @@ module Net
   # [ID[https://tools.ietf.org/html/rfc2971]]::
   #   Showalter, T., "IMAP4 ID extension", RFC 2971, DOI 10.17487/RFC2971,
   #   October 2000, <https://www.rfc-editor.org/info/rfc2971>.
+  # [BINARY[https://tools.ietf.org/html/rfc3516]]::
+  #   Nerenberg, L., "IMAP4 Binary Content Extension", RFC 3516,
+  #   DOI 10.17487/RFC3516, April 2003,
+  #   <https://www.rfc-editor.org/info/rfc3516>.
   # [ACL[https://tools.ietf.org/html/rfc4314]]::
   #   Melnikov, A., "IMAP4 Access Control List (ACL) Extension", RFC 4314,
   #   DOI 10.17487/RFC4314, December 2005,
@@ -662,7 +690,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.4"
+    VERSION = "0.4.6"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1662,21 +1690,58 @@ module Net
 
     # Sends a {STATUS commands [IMAP4rev1 §6.3.10]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.10]
     # and returns the status of the indicated +mailbox+. +attr+ is a list of one
-    # or more attributes whose statuses are to be requested.  Supported
-    # attributes include:
+    # or more attributes whose statuses are to be requested.
+    #
+    # The return value is a hash of attributes.  Most status attributes return
+    # integer values, but some return other value types (documented below).
+    #
+    # A Net::IMAP::NoResponseError is raised if status values
+    # for +mailbox+ cannot be returned; for instance, because it
+    # does not exist.
+    #
+    # ===== Supported attributes
+    #
+    # +MESSAGES+::    The number of messages in the mailbox.
+    #
+    # +UIDNEXT+::     The next unique identifier value of the mailbox.
+    #
+    # +UIDVALIDITY+:: The unique identifier validity value of the mailbox.
     #
-    # MESSAGES:: the number of messages in the mailbox.
-    # RECENT:: the number of recent messages in the mailbox.
-    # UNSEEN:: the number of unseen messages in the mailbox.
+    # +UNSEEN+::      The number of messages without the <tt>\Seen</tt> flag.
     #
-    # The return value is a hash of attributes. For example:
+    # +DELETED+::     The number of messages with the <tt>\Deleted</tt> flag.
+    #
+    # +SIZE+::
+    #     The approximate size of the mailbox---must be greater than or equal to
+    #     the sum of all messages' +RFC822.SIZE+ fetch item values.
+    #
+    # +MAILBOXID+::
+    #     A server-allocated unique _string_ identifier for the mailbox.
+    #     See +OBJECTID+
+    #     {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-4].
+    #
+    # +RECENT+::
+    #     The number of messages with the <tt>\Recent</tt> flag.
+    #     _NOTE:_ +RECENT+ was removed from IMAP4rev2.
+    #
+    # Unsupported attributes may be requested.  The attribute value will be
+    # either an Integer or an ExtensionData object.
+    #
+    # ===== For example:
     #
     #   p imap.status("inbox", ["MESSAGES", "RECENT"])
     #   #=> {"RECENT"=>0, "MESSAGES"=>44}
     #
-    # A Net::IMAP::NoResponseError is raised if status values
-    # for +mailbox+ cannot be returned; for instance, because it
-    # does not exist.
+    # ===== Capabilities
+    #
+    # +SIZE+ requires the server's capabilities to include either +IMAP4rev2+ or
+    # <tt>STATUS=SIZE</tt>
+    # {[RFC8483]}[https://www.rfc-editor.org/rfc/rfc8483.html].
+    #
+    # +DELETED+ requires the server's capabilities to include +IMAP4rev2+.
+    #
+    # +MAILBOXID+ requires the server's capabilities to include +OBJECTID+
+    # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
     def status(mailbox, attr)
       synchronize do
         send_command("STATUS", mailbox, attr)

data/rakelib/benchmarks.rake

@@ -17,11 +17,6 @@ BENCHMARK_INIT = <<RUBY
   parser   = Net::IMAP::ResponseParser.new
 RUBY
 
-PER_BENCHMARK_PRELUDE = <<RUBY
-  response = load_response(%p,
-                           %p)
-RUBY
-
 file "benchmarks/parser.yml" => PARSER_TEST_FIXTURES do |t|
   require "yaml"
   require "pathname"
@@ -31,7 +26,7 @@ file "benchmarks/parser.yml" => PARSER_TEST_FIXTURES do |t|
   files = path.glob("*.yml")
   tests = files.flat_map {|file|
     file.read
-      .gsub(%r{([-:]) !ruby/struct:\S+}) { $1 }
+      .gsub(%r{([-:]) !ruby/(object|struct):\S+}) { $1 }
       .then {
         YAML.safe_load(_1, filename: file,
                        permitted_classes: [Symbol, Regexp], aliases: true)
@@ -42,14 +37,12 @@ file "benchmarks/parser.yml" => PARSER_TEST_FIXTURES do |t|
           test.key?(:expected) ? :parser_assert_equal : :parser_pending
         }
       }
-      .map {|test_name, _|
-        [file.relative_path_from(__dir__).to_s, test_name.to_s]
-      }
+      .map {|test_name, test| [test_name.to_s, test.fetch(:response)] }
   }
 
-  benchmarks = tests.map {|file, fixture_name|
+  benchmarks = tests.map {|fixture_name, response|
     {"name"    => fixture_name.delete_prefix("test_"),
-     "prelude" => PER_BENCHMARK_PRELUDE % [file, fixture_name],
+     "prelude" => "response = -%s.b" % [response.dump],
      "script"  => "parser.parse(response)"}
   }
     .sort_by { _1["name"] }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.6
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-03 00:00:00.000000000 Z
+date: 2023-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -90,6 +90,7 @@ files:
 - lib/net/imap/data_encoding.rb
 - lib/net/imap/deprecated_client_options.rb
 - lib/net/imap/errors.rb
+- lib/net/imap/fetch_data.rb
 - lib/net/imap/flags.rb
 - lib/net/imap/response_data.rb
 - lib/net/imap/response_parser.rb
@@ -112,6 +113,7 @@ files:
 - lib/net/imap/sasl/stringprep.rb
 - lib/net/imap/sasl/xoauth2_authenticator.rb
 - lib/net/imap/sasl_adapter.rb
+- lib/net/imap/sequence_set.rb
 - lib/net/imap/stringprep.rb
 - lib/net/imap/stringprep/nameprep.rb
 - lib/net/imap/stringprep/saslprep.rb
@@ -146,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol