5 class SourceError < StandardError
7 raise "don't instantiate me!" if SourceError.is_a?(self.class)
11 class OutOfSyncSourceError < SourceError; end
12 class FatalSourceError < SourceError; end
15 ## Implementing a new source should be easy, because Sup only needs
17 ## 1. See how many messages it contains
18 ## 2. Get an arbitrary message
19 ## 3. (optional) see whether the source has marked it read or not
21 ## In particular, Sup doesn't need to move messages, mark them as
22 ## read, delete them, or anything else. (Well, it's nice to be able
23 ## to delete them, but that is optional.)
25 ## On the other hand, Sup assumes that you can assign each message a
26 ## unique integer id, such that newer messages have higher ids than
27 ## earlier ones, and that those ids stay constant across sessions
28 ## (in the absence of some other client going in and fucking
29 ## everything up). For example, for mboxes I use the file offset of
30 ## the start of the message. If a source does NOT have that
31 ## capability, e.g. IMAP, then you have to do a little more work to
34 ## To write a new source, subclass this class, and implement:
37 ## - end_offset (exclusive!) (or, #done?)
38 ## - load_header offset
39 ## - load_message offset
40 ## - raw_header offset
41 ## - raw_message offset
43 ## - next (or each, if you prefer): should return a message and an
46 ## ... where "offset" really means unique id. (You can tell I
47 ## started with mbox.)
49 ## All exceptions relating to accessing the source must be caught
50 ## and rethrown as FatalSourceErrors or OutOfSyncSourceErrors.
51 ## OutOfSyncSourceErrors should be used for problems that a call to
52 ## sup-sync will fix (namely someone's been playing with the source
53 ## from another client); FatalSourceErrors can be used for anything
54 ## else (e.g. the imap server is down or the maildir is missing.)
56 ## Finally, be sure the source is thread-safe, since it WILL be
57 ## pummelled from multiple threads at once.
59 ## Examples for you to look at: mbox/loader.rb, imap.rb, and
64 ## dirty? means cur_offset has changed, so the source info needs to
65 ## be re-saved to sources.yaml.
66 bool_reader :usual, :archived, :dirty
67 attr_reader :uri, :cur_offset
70 def initialize uri, initial_offset=nil, usual=true, archived=false, id=nil
71 raise ArgumentError, "id must be an integer: #{id.inspect}" unless id.is_a? Fixnum if id
74 @cur_offset = initial_offset
81 ## overwrite me if you have a disk incarnation (currently used only for sup-sync-back)
82 def file_path; nil end
84 def to_s; @uri.to_s; end
85 def seek_to! o; self.cur_offset = o; end
86 def reset!; seek_to! start_offset; end
87 def == o; o.uri == uri; end
88 def done?; start_offset.nil? || (self.cur_offset ||= start_offset) >= end_offset; end
89 def is_source_for? uri; uri == @uri; end
91 ## check should throw a FatalSourceError or an OutOfSyncSourcError
92 ## if it can detect a problem. it is called when the sup starts up
93 ## to proactively notify the user of any source problems.
96 ## yields successive offsets and labels, starting at #cur_offset.
98 ## when implementing a source, you can overwrite either #each or #next. the
99 ## default #each just calls next over and over.
101 self.cur_offset ||= start_offset
103 offset, labels = self.next
108 ## utility method to read a raw email header from an IO stream and turn it
109 ## into a hash of key-value pairs. minor special semantics for certain headers.
111 ## THIS IS A SPEED-CRITICAL SECTION. Everything you do here will have a
112 ## significant effect on Sup's processing speed of email from ALL sources.
113 ## Little things like string interpolation, regexp interpolation, += vs <<,
114 ## all have DRAMATIC effects. BE CAREFUL WHAT YOU DO!
115 def self.parse_raw_email_header f
121 ## these three can occur multiple times, and we want the first one
122 when /^(Delivered-To|X-Original-To|Envelope-To):\s*(.*?)\s*$/i; header[last = $1.downcase] ||= $2
123 ## regular header: overwrite (not that we should see more than one)
124 ## TODO: figure out whether just using the first occurrence changes
125 ## anything (which would simplify the logic slightly)
126 when /^([^:\s]+):\s*(.*?)\s*$/i; header[last = $1.downcase] = $2
127 when /^\r*$/; break # blank line signifies end of header
130 header[last] << " " unless header[last].empty?
131 header[last] << line.strip
136 %w(subject from to cc bcc).each do |k|
137 v = header[k] or next
138 next unless Rfc2047.is_encoded? v
140 Rfc2047.decode_to $encoding, v
141 rescue Errno::EINVAL, Iconv::InvalidEncoding, Iconv::IllegalSequence => e
142 #debug "warning: error decoding RFC 2047 header (#{e.class.name}): #{e.message}"
151 ## convenience function
152 def parse_raw_email_header f; self.class.parse_raw_email_header f end
154 def Source.expand_filesystem_uri uri
155 uri.gsub "~", File.expand_path("~")
164 ## if you have a @labels instance variable, include this
165 ## to serialize them nicely as an array, rather than as a
167 module SerializeLabelsNicely
168 def before_marshal # can return an object
170 c.instance_eval { @labels = @labels.to_a.map { |l| l.to_s } }
175 @labels = Set.new(@labels.map { |s| s.to_sym })
184 @sources_dirty = false
185 @source_mutex = Monitor.new
189 @source_mutex.synchronize { @sources[id] }
192 def add_source source
193 @source_mutex.synchronize do
194 raise "duplicate source!" if @sources.include? source
195 @sources_dirty = true
196 max = @sources.max_of { |id, s| s.is_a?(DraftLoader) || s.is_a?(SentLoader) ? 0 : id }
197 source.id ||= (max || 0) + 1
198 ##source.id += 1 while @sources.member? source.id
199 @sources[source.id] = source
204 ## favour the inbox by listing non-archived sources first
205 @source_mutex.synchronize { @sources.values }.sort_by { |s| s.id }.partition { |s| !s.archived? }.flatten
208 def source_for uri; sources.find { |s| s.is_source_for? uri }; end
209 def usual_sources; sources.find_all { |s| s.usual? }; end
211 def load_sources fn=Redwood::SOURCE_FN
212 source_array = (Redwood::load_yaml_obj(fn) || []).map { |o| Recoverable.new o }
213 @source_mutex.synchronize do
214 @sources = Hash[*(source_array).map { |s| [s.id, s] }.flatten]
215 @sources_dirty = false
219 def save_sources fn=Redwood::SOURCE_FN
220 @source_mutex.synchronize do
221 if @sources_dirty || @sources.any? { |id, s| s.dirty? }
225 FileUtils.mv fn, bakfn, :force => true unless File.exists?(bakfn) && File.size(fn) == 0
227 Redwood::save_yaml_obj sources, fn, true
230 @sources_dirty = false