3 class SourceError < StandardError
5 raise "don't instantiate me!" if SourceError.is_a?(self.class)
9 class OutOfSyncSourceError < SourceError; end
10 class FatalSourceError < SourceError; end
13 ## Implementing a new source should be easy, because Sup only needs
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
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.)
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
32 ## To write a new source, subclass this class, and implement:
35 ## - end_offset (exclusive!)
36 ## - load_header offset
37 ## - load_message offset
38 ## - raw_header offset
39 ## - raw_message offset
41 ## - next (or each, if you prefer): should return a message and an
44 ## ... where "offset" really means unique id. (You can tell I
45 ## started with mbox.)
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.)
54 ## Finally, be sure the source is thread-safe, since it WILL be
55 ## pummelled from multiple threads at once.
57 ## Examples for you to look at: mbox/loader.rb, imap.rb, and
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
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
72 @cur_offset = initial_offset
79 def file_path; nil end
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
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.
94 self.cur_offset ||= start_offset
97 raise "no message" unless n
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.
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
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
122 header[last] << " " unless header[last].empty?
123 header[last] << line.strip
128 %w(subject from to cc bcc).each do |k|
129 v = header[k] or next
130 next unless Rfc2047.is_encoded? v
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}"
143 ## convenience function
144 def parse_raw_email_header f; self.class.parse_raw_email_header f end
146 def Source.expand_filesystem_uri uri
147 uri.gsub "~", File.expand_path("~")