imap.rb 0.4.9 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b062efdc696b59573e564f135485c3e987a8a8078b36e87783537cbcd040712a
-  data.tar.gz: 150f927c8023ed6cbbb1b58fa5b863620ba2043ec71058c52f36a75c817e9e0a
+  metadata.gz: db42d933da16aca65af3c854ea0f26da5ec173da7df4260e0bb2879476da0bbd
+  data.tar.gz: 1c751f2b12f3dcaa5cfa6035ead2c6b24ba81c3c866cd7bf454e56f67ada69ab
 SHA512:
-  metadata.gz: c979d4b09d86154e500454440396443d9db9ee8134603ea5d432ed093e46bc3a54fa33aaa24667302dc540566e8863c6d50c22c112c87ee91a1b224c7a4d567c
-  data.tar.gz: 4e91af7317d63811a9ec9dff17ff14130926bf101d4631e6fbfa5069501c12e90b1af0fa28efa315a6a1dc52b823b012e89f14e6d7dbdec3b8b7fe1fa44e3bff
+  metadata.gz: fea3b0f91b2813bc83be27ee944d2d34c4e7b7740b406349e85e5d24fbccc5b199a0b272e144bf8e3ea096a5a9dfa68760aef3c537cd6ddaf92f9533a9ee209c
+  data.tar.gz: 6e8c310a8660730d3c268f17f236ea92c7d33bd3de96edfb189acb4c0f34dfd6a7d9bc7037f8cb38486ac34836ba04c99df1960649f755a93c097cfb8ced3c00

data/CHANGELOG

@@ -2,6 +2,26 @@
 
 ## 20260917
 
+0.6.0: One fetch for a slice of messages rather than one per attribute per message.
+
+1. ~ Imap::Message.search: fetches the ENVELOPE for a slice of message ids and hands each Imap::Message its own, + SLICE = 200. A hundred messages cost a round trip apiece for the subject and another apiece for the from; they cost one for the hundred now, which at any real latency is the whole cost of a search.
+2. ~ Imap::Message#initialize: + attrs, which search() supplies and a caller need not. + Imap::Message#envelope, which reads what was prefetched or fetches where there is none, so a message built by hand behaves as before.
+3. ~ Imap::Message#subject, #from, #to: read from the envelope rather than fetching a header apiece. #from answers 'name <mailbox@host>' where the envelope names one, and the bare address where it does not, having answered the raw From header.
+4. ~ Imap::Message#body: unchanged and still lazy, a body being the one thing worth not fetching until it is wanted.
+5. ~ test/test_helper.rb: MockIMAP#fetch takes a list as a server does, answers with a seqno apiece, and counts its calls. Its envelope carries a subject and a from; the two BODY[HEADER.FIELDS] cases went with the code that asked for them.
+6. + tests: that a search of three fetches once, that the prefetched envelope is not fetched again, and that a message built by hand still fetches.
+7. ~ Imap::VERSION: /0.5.0/0.6.0/
+
+0.5.0: + OR and NOT to the criteria, and HEADER given its field
+
+1. + Imap::Search#any_of: or: [{from: 'a@x'}, {to: 'b@y'}]. OR takes two keys and no more, so three or more nest, OR OR a b c, as the server reads them. Each side is a criteria hash of its own and may nest further.
+2. + Imap::Search#none_of: not: {subject: 'Payday'}. NOT takes one key, so several are negated apiece, NOT a NOT b.
+3. ~ Imap::Search#to_imap_search_keys: OR and NOT read before the operator tests, being neither general nor boolean.
+4. HEADER wanted no change: an array value already flattens to ['HEADER', field, value], which nothing said and nothing tested. It is tested now.
+5. + tests for each, and for OR mixed with the plain keys.
+6. ~ Imap::VERSION: /0.4.9/0.5.0/
+
+
 0.4.9: + imap.rb.gemspec, so that the gem resolves under both names.
 
 1. + imap.rb.gemspec: the same code published as imap.rb, which is how gems are named here: 21 carry the suffix and imap is one of the few which do not. rubygems has no notion of an alias, so the two are separate gems which must be kept at the same version by hand.

data/lib/Imap/Message.rb

@@ -15,11 +15,20 @@ require_relative './Search'
 
 class Imap
   class Message
+
+    SLICE = 200
     class << self
 
+      # One fetch for a slice of messages rather than one per attribute per
+      # message.  A hundred messages cost a round trip apiece for the subject and
+      # another apiece for the from; they cost one for the hundred now.
       def search(imap_client, **search_criteria)
         message_ids = Imap::Search.new(imap_client, search_criteria).message_ids
-        message_ids.collect{|message_id| Imap::Message.new(message_id, imap_client)}
+        message_ids.each_slice(SLICE).flat_map do |slice|
+          imap_client.imap.fetch(slice, ['ENVELOPE']).collect do |data|
+            Imap::Message.new(data.seqno, imap_client, data.attr)
+          end
+        end
       end
       alias_method :find, :search
 
@@ -33,15 +42,15 @@ class Imap
     end
 
     def subject
-      @subject ||= fetch_data('BODY[HEADER.FIELDS (SUBJECT)]').first.attr['BODY[HEADER.FIELDS (SUBJECT)]'].sub(/^Subject: /, '').strip
+      @subject ||= envelope.subject.to_s.strip
     end
 
     def from
-      @from ||= fetch_data('BODY[HEADER.FIELDS (FROM)]').first.attr['BODY[HEADER.FIELDS (FROM)]'].sub(/^From: /, '').strip
+      @from ||= address_to_s(envelope.from && envelope.from.first)
     end
 
     def to
-      @to ||= (fetch_data('ENVELOPE').first.attr['ENVELOPE'].to || []).map{|addr| addr.mailbox + '@' + addr.host}
+      @to ||= (envelope.to || []).collect{|address| address_to_s(address)}
     end
 
     def urls
@@ -55,9 +64,21 @@ class Imap
 
     private
 
-    def initialize(message_id = nil, imap_client = nil)
+    def initialize(message_id = nil, imap_client = nil, attrs = nil)
       @message_id = message_id
       @imap_client = imap_client
+      @attrs = attrs
+    end
+
+    # Prefetched where search() built this, fetched where the caller built it.
+    def envelope
+      @envelope ||= (@attrs && @attrs['ENVELOPE']) || fetch_data('ENVELOPE').first.attr['ENVELOPE']
+    end
+
+    def address_to_s(address)
+      return nil unless address
+      email = [address.mailbox, address.host].compact.join('@')
+      address.name.to_s.empty? ? email : "#{address.name} <#{email}>"
     end
 
     def fetch_data(*attrs)

data/lib/Imap/Search.rb

@@ -123,6 +123,10 @@ class Imap
       criteria.inject([]) do |m, kv|
         key, value = kv.first.to_s.upcase, kv.last
         case
+        when key == 'OR'
+          m << any_of(value)
+        when key == 'NOT'
+          m << none_of(value)
         when general_operator?(key)
           m << general_to_imap_search_key(key, value)
         when boolean_operator?(key)
@@ -133,6 +137,17 @@ class Imap
       end.flatten
     end
 
+    # OR takes two keys and no more, so three criteria nest: OR OR a b c.  Each
+    # is a criteria hash of its own, so either side may nest further.
+    def any_of(criteria_hashes)
+      criteria_hashes.collect{|criteria_hash| Search.new(nil, criteria_hash).to_imap_search_keys}.inject{|m, keys| ['OR'] + m + keys}
+    end
+
+    # NOT takes one key, so each criterion is negated on its own: NOT a NOT b.
+    def none_of(criteria_hash)
+      criteria_hash.inject([]){|m, kv| m + ['NOT'] + Search.new(nil, Hash[*kv]).to_imap_search_keys}
+    end
+
     def general_to_imap_search_key(key, value)
       value.is_a?(Negated) ? ['NOT', key, value.value] : [key, value]
     end

data/lib/Imap/VERSION.rb

@@ -1,3 +1,3 @@
 class Imap
-  VERSION = '0.4.9'
+  VERSION = '0.6.0'
 end

data/test/Imap/Message_test.rb

@@ -30,6 +30,30 @@ describe Imap::Message do
     end
   end
 
+  describe 'the batched fetch' do
+    it 'fetches once for the whole slice rather than once per message' do
+      messages = Imap::Message.search(client, from: 'test@example.com')
+      _(messages.size).must_equal 3
+      _(client.imap.fetch_count).must_equal 1
+    end
+
+    it 'reads the prefetched envelope rather than fetching again' do
+      message = Imap::Message.search(client, from: 'test@example.com').first
+      before = client.imap.fetch_count
+      message.subject
+      message.from
+      message.to
+      _(client.imap.fetch_count).must_equal before
+    end
+
+    it 'still fetches for a message the caller built' do
+      message = Imap::Message.new(1, client)
+      before = client.imap.fetch_count.to_i
+      message.subject
+      _(client.imap.fetch_count).must_equal before + 1
+    end
+  end
+
   describe '#body' do
     it 'returns the message body' do
       _(imap_message.body).must_match(/Mock body/)

data/test/Imap/Search_test.rb

@@ -44,6 +44,34 @@ describe Imap::Search do
     end
   end
 
+  describe 'OR, NOT and HEADER' do
+    def keys(criteria) = Imap::Search.new(client, criteria).to_imap_search_keys
+
+    it 'takes two criteria hashes for OR' do
+      _(keys(or: [{from: 'a@x'}, {to: 'b@y'}])).must_equal ['OR', 'FROM', 'a@x', 'TO', 'b@y']
+    end
+
+    it 'nests OR where there are more than two, it taking only two' do
+      _(keys(or: [{from: 'a@x'}, {to: 'b@y'}, {cc: 'c@z'}])).must_equal ['OR', 'OR', 'FROM', 'a@x', 'TO', 'b@y', 'CC', 'c@z']
+    end
+
+    it 'negates a criterion for NOT' do
+      _(keys(not: {subject: 'Payday'})).must_equal ['NOT', 'SUBJECT', 'Payday']
+    end
+
+    it 'negates each on its own where NOT carries more than one, it taking only one' do
+      _(keys(not: {subject: 'Payday', seen: true})).must_equal ['NOT', 'SUBJECT', 'Payday', 'NOT', 'SEEN']
+    end
+
+    it 'takes a field and a value for HEADER' do
+      _(keys(header: ['List-Id', 'announce'])).must_equal ['HEADER', 'List-Id', 'announce']
+    end
+
+    it 'mixes with the plain keys' do
+      _(keys(since: '1-Sep-2026', or: [{from: 'a@x'}, {to: 'b@y'}])).must_equal ['SINCE', '1-Sep-2026', 'OR', 'FROM', 'a@x', 'TO', 'b@y']
+    end
+  end
+
   describe 'the chaining interface' do
     it 'names the keys in lower case' do
       _(Imap::Search.new(client).from('x@y.com').criteria).must_equal({FROM: 'x@y.com'})

data/test/test_helper.rb

@@ -32,10 +32,14 @@ class MockIMAP
   end
 
   attr_reader :fetched_attrs
+  attr_reader :fetch_count
 
-  def fetch(message_id, attrs)
+  def fetch(message_ids, attrs)
     @fetched_attrs = attrs
-    [OpenStruct.new(attr: mock_fetch_attrs(message_id, attrs))]
+    @fetch_count = (@fetch_count || 0) + 1
+    Array(message_ids).collect do |message_id|
+      OpenStruct.new(seqno: message_id, attr: mock_fetch_attrs(message_id, attrs))
+    end
   end
 
   def store(message_id, flags, values); end
@@ -63,12 +67,10 @@ class MockIMAP
       case attr
       when 'BODY[TEXT]', 'BODY.PEEK[TEXT]'
         result['BODY[TEXT]'] = "Mock body for message #{message_id}"
-      when 'BODY[HEADER.FIELDS (SUBJECT)]'
-        result['BODY[HEADER.FIELDS (SUBJECT)]'] = "Subject: Mock Subject #{message_id}\r\n"
-      when 'BODY[HEADER.FIELDS (FROM)]'
-        result['BODY[HEADER.FIELDS (FROM)]'] = "From: sender@example.com\r\n"
       when 'ENVELOPE'
         result['ENVELOPE'] = OpenStruct.new(
+          subject: "Mock Subject #{message_id}",
+          from: [OpenStruct.new(mailbox: 'sender', host: 'example.com')],
           to: message_id == 99 ? nil : [OpenStruct.new(mailbox: 'user', host: 'example.com')]
         )
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap.rb
 version: !ruby/object:Gem::Version
-  version: 0.4.9
+  version: 0.6.0
 platform: ruby
 authors:
 - thoran