imap.rb 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be67e0de4db977ee6ba474e7355fadae929bd267132fd867d64f96caa3c7a19
-  data.tar.gz: e930fe80e9f8cffac1837670688e22f8826ce50391a36b5f5cc8474f0c89e9fb
+  metadata.gz: db42d933da16aca65af3c854ea0f26da5ec173da7df4260e0bb2879476da0bbd
+  data.tar.gz: 1c751f2b12f3dcaa5cfa6035ead2c6b24ba81c3c866cd7bf454e56f67ada69ab
 SHA512:
-  metadata.gz: 3b8f36bc1285a4f379624038e387cd70e825c07b617f07a60ebd5ba11ee62a775126eb1a0263107739bea073b44b2d2cc86c4c3f05a5533eb8ea848f5f11b0f0
-  data.tar.gz: 36f1969380582aef53570369140fdffddd920fabc04a157faca0accd49f38286f8563934b3db3c049e0769074d355339cc234ccfe65fa63f53d8a61eebc096fa
+  metadata.gz: fea3b0f91b2813bc83be27ee944d2d34c4e7b7740b406349e85e5d24fbccc5b199a0b272e144bf8e3ea096a5a9dfa68760aef3c537cd6ddaf92f9533a9ee209c
+  data.tar.gz: 6e8c310a8660730d3c268f17f236ea92c7d33bd3de96edfb189acb4c0f34dfd6a7d9bc7037f8cb38486ac34836ba04c99df1960649f755a93c097cfb8ced3c00

data/CHANGELOG

@@ -2,6 +2,16 @@
 
 ## 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.

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/VERSION.rb

@@ -1,3 +1,3 @@
 class Imap
-  VERSION = '0.5.0'
+  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/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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - thoran