git.cworth.org Git - sup/blob - lib/sup/source.rb

   1 module Redwood
   2
   3 class SourceError < StandardError
   4   def initialize *a
   5     raise "don't instantiate me!" if SourceError.is_a?(self.class)
   6     super
   7   end
   8 end
   9 class OutOfSyncSourceError < SourceError; end
  10 class FatalSourceError < SourceError; end
  11
  12 class Source
  13   ## Implementing a new source should be easy, because Sup only needs
  14   ## to be able to:
  15   ##  1. See how many messages it contains
  16   ##  2. Get an arbitrary message
  17   ##  3. (optional) see whether the source has marked it read or not
  18   ##
  19   ## In particular, Sup doesn't need to move messages, mark them as
  20   ## read, delete them, or anything else. (Well, it's nice to be able
  21   ## to delete them, but that is optional.)
  22   ##
  23   ## On the other hand, Sup assumes that you can assign each message a
  24   ## unique integer id, such that newer messages have higher ids than
  25   ## earlier ones, and that those ids stay constant across sessions
  26   ## (in the absence of some other client going in and fucking
  27   ## everything up). For example, for mboxes I use the file offset of
  28   ## the start of the message. If a source does NOT have that
  29   ## capability, e.g. IMAP, then you have to do a little more work to
  30   ## simulate it.
  31   ##
  32   ## To write a new source, subclass this class, and implement:
  33   ##
  34   ## - start_offset
  35   ## - end_offset (exclusive!)
  36   ## - load_header offset
  37   ## - load_message offset
  38   ## - raw_header offset
  39   ## - raw_message offset
  40   ## - check
  41   ## - next (or each, if you prefer): should return a message and an
  42   ##   array of labels.
  43   ##
  44   ## ... where "offset" really means unique id. (You can tell I
  45   ## started with mbox.)
  46   ##
  47   ## All exceptions relating to accessing the source must be caught
  48   ## and rethrown as FatalSourceErrors or OutOfSyncSourceErrors.
  49   ## OutOfSyncSourceErrors should be used for problems that a call to
  50   ## sup-sync will fix (namely someone's been playing with the source
  51   ## from another client); FatalSourceErrors can be used for anything
  52   ## else (e.g. the imap server is down or the maildir is missing.)
  53   ##
  54   ## Finally, be sure the source is thread-safe, since it WILL be
  55   ## pummelled from multiple threads at once.
  56   ##
  57   ## Examples for you to look at: mbox/loader.rb, imap.rb, and
  58   ## maildir.rb.
  59
  60   ## let's begin!
  61   ##
  62   ## dirty? means cur_offset has changed, so the source info needs to
  63   ## be re-saved to sources.yaml.
  64   bool_reader :usual, :archived, :dirty
  65   attr_reader :uri, :cur_offset
  66   attr_accessor :id
  67
  68   def initialize uri, initial_offset=nil, usual=true, archived=false, id=nil
  69     raise ArgumentError, "id must be an integer: #{id.inspect}" unless id.is_a? Fixnum if id
  70
  71     @uri = uri
  72     @cur_offset = initial_offset
  73     @usual = usual
  74     @archived = archived
  75     @id = id
  76     @dirty = false
  77   end
  78
  79   def file_path; nil end
  80
  81   def to_s; @uri.to_s; end
  82   def seek_to! o; self.cur_offset = o; end
  83   def reset!; seek_to! start_offset; end
  84   def == o; o.uri == uri; end
  85   def done?; start_offset.nil? || (self.cur_offset ||= start_offset) >= end_offset; end
  86   def is_source_for? uri; uri == @uri; end
  87
  88   ## check should throw a FatalSourceError or an OutOfSyncSourcError
  89   ## if it can detect a problem. it is called when the sup starts up
  90   ## to proactively notify the user of any source problems.
  91   def check; end
  92
  93   def each
  94     self.cur_offset ||= start_offset
  95     until done?
  96       n, labels = self.next
  97       raise "no message" unless n
  98       yield n, labels
  99     end
 100   end
 101
 102   ## read a raw email header from a filehandle (or anything that responds to
 103   ## #gets), and turn it into a hash of key-value pairs.
 104   ##
 105   ## WARNING! THIS IS A SPEED-CRITICAL SECTION. Everything you do here will have
 106   ## a significant effect on Sup's processing speed of email from ALL sources.
 107   ## Little things like string interpolation, regexp interpolation, += vs <<,
 108   ## all have DRAMATIC effects. BE CAREFUL WHAT YOU DO!
 109   def self.parse_raw_email_header f
 110     header = {}
 111     last = nil
 112
 113     while(line = f.gets)
 114       case line
 115       ## these three can occur multiple times, and we want the first one
 116       when /^(Delivered-To|X-Original-To|Envelope-To):\s*(.*?)\s*$/i; header[last = $1.downcase] ||= $2
 117       ## mark this guy specially. not sure why i care.
 118       when /^([^:\s]+):\s*(.*?)\s*$/i; header[last = $1.downcase] = $2
 119       when /^\r*$/; break
 120       else
 121         if last
 122           header[last] << " " unless header[last].empty?
 123           header[last] << line.strip
 124         end
 125       end
 126     end
 127
 128     %w(subject from to cc bcc).each do |k|
 129       v = header[k] or next
 130       next unless Rfc2047.is_encoded? v
 131       header[k] = begin
 132         Rfc2047.decode_to $encoding, v
 133       rescue Errno::EINVAL, Iconv::InvalidEncoding, Iconv::IllegalSequence => e
 134         #Redwood::log "warning: error decoding RFC 2047 header (#{e.class.name}): #{e.message}"
 135         v
 136       end
 137     end
 138     header
 139   end
 140
 141 protected
 142
 143   ## convenience function
 144   def parse_raw_email_header f; self.class.parse_raw_email_header f end
 145
 146   def Source.expand_filesystem_uri uri
 147     uri.gsub "~", File.expand_path("~")
 148   end
 149
 150   def cur_offset= o
 151     @cur_offset = o
 152     @dirty = true
 153   end
 154 end
 155
 156 end