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

   1 module Redwood
   2
   3 class SourceError < StandardError; end
   4
   5 class Source
   6   ## Implementing a new source is typically quite easy, because Sup
   7   ## only needs to be able to:
   8   ##  1. See how many messages it contains
   9   ##  2. Get an arbirtrary message
  10   ##  3. (optional) see whether the source has marked it read or not
  11   ##
  12   ## In particular, Sup doesn't need to move messages, mark them as
  13   ## read, delete them, or anything else. (Well, at some point it will
  14   ## need to delete them, but that will be an optional capability.)
  15   ##
  16   ## On the other hand, Sup assumes that you can assign each message a
  17   ## unique integer id, such that newer messages have higher ids than
  18   ## earlier ones, and that those ids stay constant across sessions
  19   ## (in the absence of some other client going in and fucking
  20   ## everything up). For example, for mboxes I use the file offset of
  21   ## the start of the message. If a source does NOT have that
  22   ## capability, e.g. IMAP, then you have to do a little more work to
  23   ## simulate it.
  24   ##
  25   ## To write a new source, subclass this class, and implement:
  26   ##
  27   ## - start_offset
  28   ## - end_offset (exclusive!)
  29   ## - pct_done (percent of the way cur_offset is to end_offset)
  30   ## - load_header offset
  31   ## - load_message offset
  32   ## - raw_header offset
  33   ## - raw_full_message offset
  34   ## - next (or each, if you prefer)
  35   ##
  36   ## ... where "offset" really means unique id. (You can tell I
  37   ## started with mbox.)
  38   ##
  39   ## You can throw SourceErrors from any of those, but we don't catch
  40   ## anything else, so make sure you catch *all* errors and reraise
  41   ## them as SourceErrors, and set broken_msg to something if the
  42   ## source needs to be rescanned.
  43   ##
  44   ## Also, be sure to make the source thread-safe, since it WILL be
  45   ## pummeled from multiple threads at once.
  46   ##
  47   ## Two examples for you to look at, though sadly neither of them is
  48   ## as simple as I'd like: mbox/loader.rb and imap.rb
  49
  50
  51
  52   ## dirty? described whether cur_offset has changed, which means the
  53   ## source info needs to be re-saved to sources.yaml.
  54   ##
  55   ## broken? means no message can be loaded, e.g. IMAP server is
  56   ## down, mbox file is corrupt and needs to be rescanned, etc.
  57   bool_reader :usual, :archived, :dirty
  58   attr_reader :uri, :cur_offset, :broken_msg
  59   attr_accessor :id
  60
  61   def initialize uri, initial_offset=nil, usual=true, archived=false, id=nil
  62     @uri = uri
  63     @cur_offset = initial_offset
  64     @usual = usual
  65     @archived = archived
  66     @id = id
  67     @dirty = false
  68     @broken_msg = nil
  69   end
  70
  71   def broken?; !@broken_msg.nil?; end
  72   def to_s; @uri.to_s; end
  73   def seek_to! o; self.cur_offset = o; end
  74   def reset!
  75     return if broken?
  76     begin
  77       seek_to! start_offset
  78     rescue SourceError
  79     end
  80   end
  81   def == o; o.to_s == to_s; end
  82   def done?;
  83     return true if broken?
  84     begin
  85       (self.cur_offset ||= start_offset) >= end_offset
  86     rescue SourceError => e
  87       true
  88     end
  89   end
  90   def is_source_for? uri; URI(self.uri) == URI(uri); end
  91
  92   def each
  93     return if broken?
  94     begin
  95       self.cur_offset ||= start_offset
  96       until done? || broken? # just like life!
  97         n, labels = self.next
  98         raise "no message" unless n
  99         yield n, labels
 100       end
 101     rescue SourceError => e
 102       self.broken_msg = e.message
 103     end
 104   end
 105
 106 protected
 107
 108   def cur_offset= o
 109     @cur_offset = o
 110     @dirty = true
 111   end
 112
 113   def broken_msg= m
 114     @broken_msg = m
 115 #    Redwood::log "#{to_s}: #{m}"
 116   end
 117 end
 118
 119 Redwood::register_yaml(Source, %w(uri cur_offset usual archived id))
 120
 121 end