inbox-sync 0.2.1 → 0.3.0

data/README.md

@@ -1,6 +1,6 @@
 # InboxSync
 
-Move messages from one inbox to another.  Useful when server-side email forwarding is not an option.  (TODO) Can apply filters to messages as they are being moved.  Run on-demand, on a schedule, or as a daemon.
+Move messages from one inbox to another.  Useful when server-side email forwarding is not an option.  Can apply filters to messages as they are being moved.  Run on-demand, on a schedule, or as a daemon.
 
 ## Installation
 
@@ -20,7 +20,7 @@ Or install it yourself as:
 
 InboxSync uses IMAP to query a source inbox, process its messages, append them to a destination inbox, and archive them on the source.  It logs each step in the process and will send notification emails when something goes wrong.
 
-(TODO) InboxSync provides a framework for defining destination filters for post-sync mail processing (ie moving/archiving, copying/labeling, deletion, etc).
+InboxSync provides a framework for defining destination filters for post-sync mail processing (ie moving/archiving, copying/labeling, deletion, etc).
 
 InboxSync provides a basic ruby runner class to handle polling the source on an interval and running the configured sync(s).  You can call it in any number of ways: in a script, from a cron, as a daemon, or as part of a larger system.
 
@@ -158,7 +158,71 @@ The runner traps `SIGINT` and `SIGQUIT` and will shutdown nicely once any in-pro
 
 ## Filter Framework
 
-TODO
+You can configure filters for your syncs.  Filters are applied to destination messages after they have been appended to the inbox.
+
+```ruby
+sync = InboxSync.new.configure do
+
+  # conditions to match on
+  filter(:subject => contains('hi there')) do
+    # actions to perform
+    copy_to 'Some-Folder'
+  end
+
+end
+```
+
+### Conditions
+
+The first step in defining a filter is specifying the match conditions.  You can filter on any attribute of the message (`Mail::Message`).  The filter conditions are specified as a hash, where the keys are the attributes to match on and the values are what to match with.
+
+The default comparison is equals (`==`).  You have a few helpers for other comparisons at your disposal as well:
+
+* `contains`: converts to `/.*#{value}.*/` and matches.  aliased as `like` and `includes`.
+* `starts_with`: converts your value to `/\A#{value}.*/` and matches.  aliased as `sw`.
+* `ends_with`: converts your value to `/.*#{value}\Z/` and matches.  aliased as `ew`.
+* pass a custom regex: it will be matched
+
+```ruby
+sync = InboxSync.new.configure do
+
+  filter(:subject => 'hi there you')     { ... }
+  filter(:subject => contains('there'))  { ... }
+  filter(:subject => starts_with('hi')   { ... }
+  filter(:subject => ends_with('you'))   { ... }
+  filter(:subject => /\Ahi\s+.+\s+you\Z/ { ... }
+
+end
+```
+
+### Actions
+
+The second step in defining a filter is what to do with a message if it matches.  InboxSync provides a set of actions that can be performed on a message.
+
+* `copy_to`: copies the message to a given folder.  will create the folder if necessary.  aliased as `label`.
+* `move_to`: moves the message to a given folder.  will create the folder if necessary.  aliased as `archive_to`.
+* `mark_read`: marks the message as read (flag :Seen)
+* `delete`: deletes the message (flag :Deleted)
+* `flag`: apply a custom flag
+
+Actions are specified using a block.  If a message matches the filter conditions, the filters actions will be applied to the message on the destination.  In the case multiplie filters match the message, actions are aggregated and applied once after all filters have been processed.
+
+```ruby
+sync = InboxSync.new.configure do
+
+  filter(...) { copy_to 'Something' }
+  filter(...) { move_to 'Somewhere' }
+  filter(...) { mark_read; archive }
+
+end
+```
+
+Actions are applied according to precedence rules.  They go something like this:
+
+* flags first - they will carry over as messages are copied/moved.
+* copies/moves next - moves are just a macro for copy-then-delete
+
+This order ensures the message is available for all actions needed.
 
 ## Error Handling
 

data/lib/inbox-sync/config/filter.rb

@@ -0,0 +1,41 @@
+module InboxSync
+  class Config; end
+
+  class Config::Filter
+
+    attr_reader :conditions, :actions
+
+    def initialize(conditions, &actions)
+      @actions = actions
+
+      # make sure all match conditions are regexps
+      @conditions = conditions.keys.inject({}) do |processed, key|
+        val = conditions[key]
+        processed[key] = val.kind_of?(Regexp) ? val : /#{val.to_s}/
+        processed
+      end
+    end
+
+    def match?(message)
+      @conditions.keys.inject(true) do |result, key|
+        result && value_matches?(message.send(key), @conditions[key])
+      end
+    end
+
+    protected
+
+    def value_matches?(value, regexp)
+      if value.respond_to?(:inject)
+        # this is a collection, match if any one item matches
+        value.inject(false) do |result, item|
+          result || !!(item.to_s =~ regexp)
+        end
+      else
+        # single value match
+        !!(value.to_s =~ regexp)
+      end
+    end
+
+  end
+
+end

data/lib/inbox-sync/config.rb

@@ -2,6 +2,7 @@ require 'logger'
 require 'ns-options'
 require 'inbox-sync/config/imap_config'
 require 'inbox-sync/config/smtp_config'
+require 'inbox-sync/config/filter'
 
 module InboxSync
 
@@ -14,6 +15,11 @@ module InboxSync
 
     opt :archive_folder, :default => 'Archived'
     opt :logger, Logger, :required => true, :default => STDOUT
+    opt :filters, :default => [], :required => true
+
+    def filter(*args, &block)
+      filters << Filter.new(*args, &block)
+    end
 
     def validate!
       if !required_set?
@@ -25,6 +31,18 @@ module InboxSync
       notify.validate!
     end
 
+    protected
+
+    def contains(value);    /.*#{value}.*/; end
+    def starts_with(value); /\A#{value}.*/; end
+    def ends_with(value);   /.*#{value}\Z/; end
+
+    alias_method :like, :contains
+    alias_method :includes, :contains
+    alias_method :inc, :includes
+    alias_method :sw,  :starts_with
+    alias_method :ew,  :ends_with
+
   end
 
 end

data/lib/inbox-sync/filter_actions.rb

@@ -0,0 +1,86 @@
+module InboxSync
+
+  class FilterActions
+
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+      @copies  = @flags = []
+    end
+
+    def copies; @copies.uniq; end
+    def flags;  @flags.uniq;  end
+
+    def copy_to(*folders)
+      @copies += args_collection(folders)
+    end
+    alias_method :label, :copy_to
+
+    def move_to(*folders)
+      copy_to *folders
+      delete
+    end
+    alias_method :archive_to, :move_to
+
+    def flag(*flags)
+      @flags += args_collection(flags).map{|f| f.to_sym}
+    end
+
+    def mark_read
+      flag(:Seen)
+    end
+
+    def delete
+      flag(:Deleted)
+    end
+
+    def match!(filters)
+      filters.each do |filter|
+        instance_eval(&filter.actions) if filter.match?(@message)
+      end
+    end
+
+    def apply!(imap, uid)
+      apply_flags(imap, uid)
+      apply_copies(imap, uid)
+
+      # force make the dest message unread if not explicitly marked :Seen
+      if !flags.include?(:Seen)
+        imap.uid_store(uid, "-FLAGS", [:Seen])
+      end
+    end
+
+    protected
+
+    def apply_flags(imap, uid)
+      if !flags.empty?
+        imap.uid_store(uid, "+FLAGS", flags)
+      end
+    end
+
+    def apply_copies(imap, uid)
+      copies.each do |folder|
+        begin
+          imap.uid_copy(uid, folder)
+        rescue Net::IMAP::NoResponseError
+          imap.create(folder)
+          retry
+        end
+      end
+    end
+
+    private
+
+    def args_collection(args)
+      args.
+        flatten.
+        compact.
+        map {|f| f.to_s}.
+        reject {|f| f.empty?}.
+        uniq
+    end
+
+  end
+
+end

data/lib/inbox-sync/mail_item.rb

@@ -25,7 +25,13 @@ module InboxSync
     end
 
     def meta
-      @meta ||= @imap.uid_fetch(self.uid, ['RFC822', 'INTERNALDATE']).first
+      @meta ||= begin
+        fetch_data = @imap.uid_fetch(self.uid, ['RFC822', 'INTERNALDATE'])
+        if fetch_data.nil? || fetch_data.empty?
+          raise "error fetching data for uid '#{self.uid}'"
+        end
+        fetch_data.first
+      end
     end
 
     def rfc822
@@ -69,7 +75,11 @@ module InboxSync
     private
 
     def time_s(datetime)
-      datetime.strftime("%a %b %-d %Y, %I:%M %p")
+      if datetime && datetime.respond_to?(:strftime)
+        datetime.strftime("%a %b %-d %Y, %I:%M %p")
+      else
+        datetime
+      end
     end
 
     def copy_mail_item(item)

data/lib/inbox-sync/sync.rb

@@ -2,6 +2,7 @@ require 'net/imap'
 require 'net/smtp'
 
 require 'inbox-sync/config'
+require 'inbox-sync/filter_actions'
 require 'inbox-sync/notice/sync_mail_item_error'
 
 module InboxSync
@@ -56,9 +57,10 @@ module InboxSync
       return if runner && runner.shutdown?
       each_source_mail_item(runner) do |mail_item|
         begin
+          logger.debug "** #{mail_item.inspect}"
           response = send_to_dest(mail_item)
           dest_uid = parse_append_response_uid(response)
-          logger.debug "** dest uid: #{dest_uid.inspect}"
+          apply_dest_filters(dest_uid)
         rescue Exception => err
           log_error(err)
           notify(Notice::SyncMailItemError.new(@notify_smtp, @config.notify, {
@@ -106,7 +108,6 @@ module InboxSync
           logger.info "* the runner has been shutdown - aborting the sync"
           break
         end
-        logger.debug "** #{mail_item.inspect}"
         yield mail_item
       end
       items = nil
@@ -143,6 +144,21 @@ module InboxSync
       end
     end
 
+    def apply_dest_filters(dest_uid)
+      logger.info "** applying filters for dest uid: #{dest_uid.inspect}"
+      using_dest_imap do |imap|
+        dest_mail_item = MailItem.new(imap, dest_uid)
+        logger.debug "** #{dest_mail_item.inspect}"
+
+        actions = FilterActions.new(dest_mail_item.message)
+        actions.match!(@config.filters)
+        logger.debug "** flag as: #{actions.flags.inspect}"
+        logger.debug "** copy to: #{actions.copies.inspect}"
+
+        actions.apply!(imap, dest_uid)
+      end
+    end
+
     def archive_on_source(mail_item)
       folder = @config.archive_folder
       if !folder.nil? && !folder.empty?
@@ -164,10 +180,7 @@ module InboxSync
       end
 
       mark_as_deleted(@source_imap, mail_item.uid)
-
       expunge_imap(@source_imap, @config.source)
-
-      @source_imap.expunge
     end
 
     def using_dest_imap
@@ -237,7 +250,7 @@ module InboxSync
     # #<struct Net::IMAP::TaggedResponse tag="RUBY0012", name="OK", data=#<struct Net::IMAP::ResponseText code=#<struct Net::IMAP::ResponseCode name="APPENDUID", data="6 9">, text=" (Success)">, raw_data="RUBY0012 OK [APPENDUID 6 9] (Success)\r\n">
     # (here '9' is the UID)
     def parse_append_response_uid(response)
-      response.data.code.data.split(/\s+/).last
+      response.data.code.data.split(/\s+/).last.to_i
     end
 
     def mark_as_seen(imap, uid)

data/lib/inbox-sync/version.rb

@@ -1,3 +1,3 @@
 module InboxSync
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/test/config/filter_test.rb

@@ -0,0 +1,31 @@
+require 'assert'
+require 'inbox-sync/config/filter'
+
+module InboxSync
+
+  class ConfigFilterTests < Assert::Context
+    before do
+      @filter = InboxSync::Config::Filter.new({
+        :subject => 'test',
+        :from => /kellyredding.com\Z/
+      })
+    end
+    subject { @filter }
+
+    should have_reader :conditions, :actions
+    should have_instance_method :match?
+
+    should "convert condition values to regexs if not" do
+      assert_kind_of Hash, subject.conditions
+      subject.conditions.each do |k,v|
+        assert_kind_of Regexp, v
+      end
+    end
+
+    should "know if it matches a message" do
+      assert subject.match?(test_mail_item.message)
+    end
+
+  end
+
+end

data/test/config_test.rb

@@ -37,7 +37,14 @@ module InboxSync
       :default => STDOUT
     }
 
-    should have_instance_method  :validate!
+    should have_option :filters, {
+      :default => [],
+      :required => true
+    }
+
+    should have_instance_methods :validate!, :filter
+    should have_instance_methods :contains, :like, :includes, :inc
+    should have_instance_methods :starts_with, :ends_with, :sw, :ew
 
     should "complain if missing :source config" do
       assert_raises ArgumentError do

data/test/filter_actions_test.rb

@@ -0,0 +1,70 @@
+require 'assert'
+require 'inbox-sync/filter_actions'
+
+module InboxSync
+
+  class FilterActionsTests < Assert::Context
+    before do
+      @message = test_mail_item.message
+      @filter_actions = InboxSync::FilterActions.new(@message)
+    end
+    subject { @filter_actions }
+
+    should have_reader :message
+    should have_instance_methods :copies, :flags
+
+    should have_instance_methods :copy_to, :label
+    should have_instance_methods :move_to, :archive_to
+    should have_instance_methods :flag, :mark_read, :delete
+
+    should have_instance_methods :match!, :apply!
+
+    should "have no marks or copies and not be deleted by default" do
+      assert_empty subject.copies
+      assert_empty subject.flags
+    end
+
+    should "handle copy actions" do
+      subject.copy_to 'somewhere'
+      subject.label 'something'
+
+      assert_equal ['somewhere', 'something'], subject.copies
+    end
+
+    should "only show valid, uniq copies when reading" do
+      subject.copy_to 'valid'
+      subject.copy_to
+      subject.copy_to nil
+
+      assert_equal ['valid'], subject.copies
+    end
+
+    should "handle move actions as a copy and archive" do
+      subject.move_to 'somewhere'
+
+      assert_equal ['somewhere'], subject.copies
+      assert_equal [:Deleted], subject.flags
+    end
+
+    should "handle marking as read" do
+      subject.mark_read
+
+      assert_equal [:Seen], subject.flags
+    end
+
+    should "handle delete actions" do
+      subject.delete
+
+      assert_equal [:Deleted], subject.flags
+    end
+
+    should "handle flag actions" do
+      subject.flag :A
+      subject.flag :B, [:C]
+
+      assert_equal [:A, :B, :C], subject.flags
+    end
+
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: inbox-sync
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Kelly Redding
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-06-13 00:00:00 Z
+date: 2012-06-15 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   type: :development
@@ -81,8 +81,10 @@ files:
 - lib/inbox-sync.rb
 - lib/inbox-sync/config.rb
 - lib/inbox-sync/config/credentials.rb
+- lib/inbox-sync/config/filter.rb
 - lib/inbox-sync/config/imap_config.rb
 - lib/inbox-sync/config/smtp_config.rb
+- lib/inbox-sync/filter_actions.rb
 - lib/inbox-sync/mail_item.rb
 - lib/inbox-sync/notice/base.rb
 - lib/inbox-sync/notice/run_sync_error.rb
@@ -91,7 +93,9 @@ files:
 - lib/inbox-sync/sync.rb
 - lib/inbox-sync/version.rb
 - log/.gitkeep
+- test/config/filter_test.rb
 - test/config_test.rb
+- test/filter_actions_test.rb
 - test/helper.rb
 - test/irb.rb
 - test/mail_item_test.rb
@@ -132,7 +136,9 @@ signing_key:
 specification_version: 3
 summary: Move messages from one inbox to another
 test_files: 
+- test/config/filter_test.rb
 - test/config_test.rb
+- test/filter_actions_test.rb
 - test/helper.rb
 - test/irb.rb
 - test/mail_item_test.rb