mail_room 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5a6b5950db35515bea9f2f82bdde5e7dd1ff367
-  data.tar.gz: d051cde6554df19f74cea7054b94673c5fb0a718
+  metadata.gz: 645c66492e5e0a58d19940db070887bd42906d97
+  data.tar.gz: 083aab204d6d7263ffb05934cce8fc7d757f069c
 SHA512:
-  metadata.gz: 8aef87866ce7bdea33d3490adb6046e6eeea50fc07b46dd21924bec5e9ead803695eb901637f8c18448cd29d03208f0ca2f8fd47a3735153e08f4cc88e2647de
-  data.tar.gz: c0e0ed306a8b784234d8edf544133c3ee0382e647236a2f29f154e1284a1e627d0d9f0fafae09b61ff35f34b36aa69435027dea8e886e6465500dab5d8a4ba0e
+  metadata.gz: 3548362a217c606c6eab222b9c51ec396354834fed95fba57702ca87293bec36c2e2ab799cfcbd944e80f1fcfdeb1ea405c606a6367c4630e6ac35cec497b80a
+  data.tar.gz: 267df7e14dcab41af2da136c2045a86b755441cb8693ad189d9361fad520a95792229bde6dd6ed3473b3fe6ceee117745e9136b253567c83cd23769eddaf2767

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## mail_room 0.3.0 ##
+
+*   Reconnect and idle if disconnected during an existing idle.
+*   Set idling thread to abort on exception so any unhandled exceptions will stop mail_room running.
+
+    *Tony Pitale*

data/README.md

@@ -3,6 +3,7 @@
 mail_room is a configuration based process that will idle on IMAP connections and POST to a delivery URL whenever a new message is received on the configured mailbox and folder.
 
 [![Build Status](https://travis-ci.org/tpitale/mail_room.png?branch=master)](https://travis-ci.org/tpitale/mail_room)
+[![Code Climate](https://codeclimate.com/github/tpitale/mail_room.png)](https://codeclimate.com/github/tpitale/mail_room)
 
 ## Installation ##
 
@@ -26,33 +27,35 @@ You will also need to install `faraday` or `letter_opener` if you use the `postb
 
 ## Configuration ##
 
-    ---
-    :mailboxes:
-      -
-        :email: "user1@gmail.com"
-        :password: "password"
-        :name: "inbox"
-        :delivery_url: "http://localhost:3000/inbox"
-        :delivery_token: "abcdefg"
-      -
-        :email: "user2@gmail.com"
-        :password: "password"
-        :name: "inbox"
-        :delivery_method: postback
-        :delivery_url: "http://localhost:3000/inbox"
-        :delivery_token: "abcdefg"
-      -
-        :email: "user3@gmail.com"
-        :password: "password"
-        :name: "inbox"
-        :delivery_method: logger
-        :log_path: "/var/log/user3-email.log"
-      -
-        :email: "user4@gmail.com"
-        :password: "password"
-        :name: "inbox"
-        :delivery_method: letter_opener
-        :location: "/tmp/user4-email"
+```yaml
+---
+:mailboxes:
+  -
+    :email: "user1@gmail.com"
+    :password: "password"
+    :name: "inbox"
+    :delivery_url: "http://localhost:3000/inbox"
+    :delivery_token: "abcdefg"
+  -
+    :email: "user2@gmail.com"
+    :password: "password"
+    :name: "inbox"
+    :delivery_method: postback
+    :delivery_url: "http://localhost:3000/inbox"
+    :delivery_token: "abcdefg"
+  -
+    :email: "user3@gmail.com"
+    :password: "password"
+    :name: "inbox"
+    :delivery_method: logger
+    :log_path: "/var/log/user3-email.log"
+  -
+    :email: "user4@gmail.com"
+    :password: "password"
+    :name: "inbox"
+    :delivery_method: letter_opener
+    :location: "/tmp/user4-email"
+```
 
 ## delivery_method ##
 
@@ -60,9 +63,7 @@ You will also need to install `faraday` or `letter_opener` if you use the `postb
 
 Requires `faraday` gem be installed.
 
-*NOTE:* If you're using Ruby `>= 2.0`, you'll need
-to use Faraday from `master` for the time being. I will investigate any issues
-once version `0.9.0` final is released.
+*NOTE:* If you're using Ruby `>= 2.0`, you'll need to use Faraday from `>= 0.8.9`. Versions before this seem to have some weird behavior with `mail_room`.
 
 The default delivery method, requires `delivery_url` and `delivery_token` in 
 configuration.

data/lib/mail_room.rb

@@ -2,10 +2,16 @@ require 'net/imap'
 require 'optparse'
 require 'yaml'
 
+# The MailRoom namespace
 module MailRoom
-  # def self.logger
-  #   @logger ||= Logger.new(STDOUT)
-  # end
+  # The MailRoom Delivery namespace holds any defined delivery methods
+  #   including:
+  # 
+  #   * postback (default)
+  #   * letter_opener
+  #   * logger
+  #   * noop
+  module Delivery; end
 end
 
 require "mail_room/version"

data/lib/mail_room/cli.rb

@@ -1,7 +1,13 @@
 module MailRoom
+  # The CLI parses ARGV into configuration to start the coordinator with.
+  # @author Tony Pitale
   class CLI
     attr_accessor :configuration, :coordinator
 
+    # Initialize a new CLI instance to handle option parsing from arguments
+    #   into configuration to start the coordinator running on all mailboxes
+    #
+    # @param args [Array] `ARGV` passed from `bin/mail_room`
     def initialize(args)
       options = {}
 
@@ -29,6 +35,7 @@ module MailRoom
       self.coordinator = Coordinator.new(configuration.mailboxes)
     end
 
+    # Start the coordinator running, sets up signal traps
     def start
       Signal.trap(:INT) do
         coordinator.running = false

data/lib/mail_room/configuration.rb

@@ -1,7 +1,10 @@
 module MailRoom
+  # Wraps configuration for a set of individual mailboxes with global config
+  # @author Tony Pitale
   class Configuration
     attr_accessor :mailboxes, :daemonize, :log_path, :pid_path
 
+    # Initialize a new configuration of mailboxes
     def initialize(options={})
       self.mailboxes = []
 
@@ -12,6 +15,9 @@ module MailRoom
       end
     end
 
+    # Builds individual mailboxes from YAML configuration
+    # 
+    # @param mailboxes_config
     def set_mailboxes(mailboxes_config)
       mailboxes_config.each do |attributes|
         self.mailboxes << Mailbox.new(attributes)

data/lib/mail_room/coordinator.rb

@@ -1,7 +1,11 @@
 module MailRoom
+  # Coordinate the mailbox watchers
+  # @author Tony Pitale
   class Coordinator
     attr_accessor :watchers, :running
 
+    # build watchers for a set of mailboxes
+    # @params mailboxes [Array<MailRoom::Mailbox>] mailboxes to be watched
     def initialize(mailboxes)
       self.watchers = []
 
@@ -10,22 +14,26 @@ module MailRoom
 
     alias :running? :running
 
+    # start each of the watchers to running
     def run
       watchers.each(&:run)
       
       self.running = true
       
       sleep_while_running
-
+    ensure
       quit
     end
-    
-    def sleep_while_running
-      while(running?) do; sleep 1; end
-    end
 
+    # quit each of the watchers when we're done running
     def quit
       watchers.each(&:quit)
     end
+
+    private
+    # @private
+    def sleep_while_running
+      while(running?) do; sleep 1; end
+    end
   end
 end

data/lib/mail_room/delivery/letter_opener.rb

@@ -4,11 +4,17 @@ require 'letter_opener'
 
 module MailRoom
   module Delivery
+    # LetterOpener Delivery method
+    # @author Tony Pitale
     class LetterOpener
+      # Build a new delivery, hold the mailbox configuration
+      # @param [MailRoom::Mailbox]
       def initialize(mailbox)
         @mailbox = mailbox
       end
 
+      # Trigger `LetterOpener` to deliver our message
+      # @param message [String] the email message as a string, RFC822 format
       def deliver(message)
         method = ::LetterOpener::DeliveryMethod.new(:location => @mailbox.location)
         method.deliver!(Mail.read_from_string(message))

data/lib/mail_room/delivery/logger.rb

@@ -2,7 +2,12 @@ require 'logger'
 
 module MailRoom
   module Delivery
+    # File/STDOUT Logger Delivery method
+    # @author Tony Pitale
     class Logger
+      # Build a new delivery, hold the mailbox configuration
+      #   open a file or stdout for IO depending on the configuration
+      # @param [MailRoom::Mailbox]
       def initialize(mailbox)
         io = File.open(mailbox.log_path, 'a') if mailbox.log_path
         io ||= STDOUT
@@ -12,6 +17,8 @@ module MailRoom
         @logger = ::Logger.new(io)
       end
 
+      # Write the message to our logger
+      # @param message [String] the email message as a string, RFC822 format
       def deliver(message)
         @logger.info message
       end

data/lib/mail_room/delivery/noop.rb

@@ -1,9 +1,13 @@
 module MailRoom
   module Delivery
+    # Noop Delivery method
+    # @author Tony Pitale
     class Noop
+      # build a new delivery, do nothing
       def initialize(*)
       end
 
+      # accept the delivery, do nothing
       def deliver(*)
       end
     end

data/lib/mail_room/delivery/postback.rb

@@ -2,11 +2,17 @@ require 'faraday'
 
 module MailRoom
   module Delivery
+    # Postback Delivery method
+    # @author Tony Pitale
     class Postback
+      # Build a new delivery, hold the mailbox configuration
+      # @param [MailRoom::Mailbox]
       def initialize(mailbox)
         @mailbox = mailbox
       end
 
+      # deliver the message using Faraday to the configured mailbox url
+      # @param message [String] the email message as a string, RFC822 format
       def deliver(message)
         connection = Faraday.new
         connection.token_auth @mailbox.delivery_token

data/lib/mail_room/mailbox.rb

@@ -1,5 +1,6 @@
 module MailRoom
-  Mailbox = Struct.new(*[
+  # Mailbox Configuration fields
+  FIELDS = [
     :email,
     :password,
     :name,
@@ -8,9 +9,13 @@ module MailRoom
     :delivery_url, # for postback
     :delivery_token, # for postback
     :location # for letter_opener
-  ])
+  ]
 
-  class Mailbox
+  # Holds configuration for each of the email accounts we wish to monitor
+  #   and deliver email to when new emails arrive over imap
+  Mailbox = Struct.new(*FIELDS) do
+    # Store the configuration and require the appropriate delivery method
+    # @param attributes [Hash] configuration options
     def initialize(attributes={})
       super(*attributes.values_at(*members))
 
@@ -31,6 +36,8 @@ module MailRoom
       end
     end
 
+    # deliver the imap email message
+    # @param message [Net::IMAP::FetchData]
     def deliver(message)
       delivery_klass.new(self).deliver(message.attr['RFC822'])
     end

data/lib/mail_room/mailbox_handler.rb

@@ -1,10 +1,16 @@
 module MailRoom
+  # Fetches new email messages for delivery
+  # @author Tony Pitale
   class MailboxHandler
+    # build a handler for this mailbox and our imap connection
+    # @param mailbox [MailRoom::Mailbox] the mailbox configuration
+    # @param imap [Net::IMAP::Connection] the open connection to gmail
     def initialize(mailbox, imap)
       @mailbox = mailbox
       @imap = imap
     end
 
+    # deliver each of the new messages
     def process
       # return if idling? || !running?
 
@@ -16,17 +22,27 @@ module MailRoom
       end
     end
 
+    private
+    # @private
+    # fetch all messages for the new message ids
     def new_messages
       messages_for_ids(new_message_ids)
     end
 
-    # label messages?
-    # @imap.store(id, "+X-GM-LABELS", [label])
+    # TODO: label messages?
+    #   @imap.store(id, "+X-GM-LABELS", [label])
 
+    # @private
+    # search for all new (unseen) message ids
+    # @return [Array<Integer>] message ids
     def new_message_ids
       @imap.search('UNSEEN')
     end
 
+    # @private
+    # fetch the email for all given ids in RFC822 format
+    # @param ids [Array<Integer>] list of message ids
+    # @return [Array<Net::IMAP::FetchData>] the net/imap messages for the given ids
     def messages_for_ids(ids)
       return [] if ids.empty?
 

data/lib/mail_room/mailbox_watcher.rb

@@ -1,68 +1,105 @@
 module MailRoom
-  # split up between processing and idling?
+  # TODO: split up between processing and idling?
+
+  # Watch a Mailbox
+  # @author Tony Pitale
   class MailboxWatcher
     attr_accessor :idling_thread
 
+    # Watch a new mailbox
+    # @param mailbox [MailRoom::Mailbox] the mailbox to watch
     def initialize(mailbox)
       @mailbox = mailbox
 
+      reset
       @running = false
-      @logged_in = false
-      @idling = false
     end
 
+    # build a net/imap connection to google imap
     def imap
       @imap ||= Net::IMAP.new('imap.gmail.com', :port => 993, :ssl => true)
     end
 
+    # build a handler to process mailbox messages
     def handler
       @handler ||= MailboxHandler.new(@mailbox, imap)
     end
 
+    # are we running?
+    # @return [Boolean]
     def running?
       @running
     end
 
+    # is the connection logged in?
+    # @return [Boolean]
     def logged_in?
       @logged_in
     end
 
+    # is the connection blocked idling?
+    # @return [Boolean]
     def idling?
       @idling
     end
 
+    # is the imap connection closed?
+    # @return [Boolean]
+    def disconnected?
+      @imap.disconnected?
+    end
+
+    # is the connection ready to idle?
+    # @return [Boolean]
+    def ready_to_idle?
+      logged_in? && !idling?
+    end
+
+    # is the response for a new message?
+    # @param response [Net::IMAP::TaggedResponse] the imap response from idle
+    # @return [Boolean]
+    def message_exists?(response)
+      response.respond_to?(:name) && response.name == 'EXISTS'
+    end
+
+    # log in and set the mailbox
     def setup
+      reset
       log_in
       set_mailbox
     end
 
+    # clear disconnected imap
+    # reset imap state
+    def reset
+      @imap = nil
+      @logged_in = false
+      @idling = false
+    end
+
+    # send the imap login command to google
     def log_in
       imap.login(@mailbox.email, @mailbox.password)
       @logged_in = true
     end
 
+    # select the mailbox name we want to use
     def set_mailbox
       imap.select(@mailbox.name) if logged_in?
     end
 
+    # maintain an imap idle connection
     def idle
-      return unless logged_in?
+      return unless ready_to_idle?
 
       @idling = true
 
-      imap.idle do |response|
-        if response.respond_to?(:name) && response.name == 'EXISTS'
-          imap.idle_done
-        end
-      end
-
+      imap.idle(&idle_handler)
+    ensure
       @idling = false
     end
 
-    def process_mailbox
-      handler.process
-    end
-
+    # trigger the idle to finish and wait for the thread to finish
     def stop_idling
       return unless idling?
 
@@ -70,6 +107,7 @@ module MailRoom
       idling_thread.join
     end
 
+    # run the mailbox watcher
     def run
       setup
 
@@ -77,17 +115,38 @@ module MailRoom
 
       self.idling_thread = Thread.start do
         while(running?) do
-          # block until we stop idling
-          idle
-          # when new messages are ready
-          process_mailbox
+          begin
+            # block until we stop idling
+            idle
+
+            # when new messages are ready
+            process_mailbox
+          rescue Net::IMAP::Error => e
+            # we've been disconnected, so re-setup
+            setup
+          end
         end
       end
+
+      idling_thread.abort_on_exception = true
     end
 
+    # stop running
     def quit
       @running = false
       stop_idling
+      # disconnect
+    end
+
+    # trigger the handler to process this mailbox for new messages
+    def process_mailbox
+      handler.process
+    end
+
+    private
+    # @private
+    def idle_handler
+      lambda {|response| imap.idle_done if message_exists?(response)}
     end
   end
 end

data/lib/mail_room/version.rb

@@ -1,3 +1,4 @@
 module MailRoom
-  VERSION = "0.2.0"
+  # Current version of MailRoom gem
+  VERSION = "0.3.0"
 end

data/spec/lib/coordinator_spec.rb

@@ -34,9 +34,11 @@ describe MailRoom::Coordinator do
     
     it 'should go to sleep after running watchers' do
       coordinator = MailRoom::Coordinator.new([])
-      coordinator.stubs(:sleep_while_running)
+      coordinator.stubs(:running=)
+      coordinator.stubs(:running?).returns(false)
       coordinator.run
-      coordinator.should have_received(:sleep_while_running)
+      coordinator.should have_received(:running=).with(true)
+      coordinator.should have_received(:running?)
     end
 
     it 'should set attribute running to true' do
@@ -47,15 +49,6 @@ describe MailRoom::Coordinator do
     end
   end
 
-  describe '#sleep_while_running' do
-    it 'should check the running state' do
-      coordinator = MailRoom::Coordinator.new([])
-      coordinator.stubs(:running?).returns(false)
-      coordinator.sleep_while_running
-      coordinator.should have_received(:running?)
-    end
-  end
-
   describe '#quit' do
     it 'quits each watcher' do
       watcher = stub(:quit)

data/spec/lib/mailbox_watcher_spec.rb

@@ -118,7 +118,7 @@ describe MailRoom::MailboxWatcher do
 
   describe '#stop_idling' do
     let(:imap) {stub}
-    let(:idling_thread) {stub}
+    let(:idling_thread) {stub(:abort_on_exception=)}
     let(:watcher) {MailRoom::MailboxWatcher.new(nil)}
 
     before :each do
@@ -160,7 +160,7 @@ describe MailRoom::MailboxWatcher do
     let(:watcher) {MailRoom::MailboxWatcher.new(nil)}
 
     before :each do
-      Thread.stubs(:start).yields
+      Thread.stubs(:start).yields.returns(stub(:abort_on_exception=))
       watcher.stubs(:setup)
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mail_room
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Pitale
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-16 00:00:00.000000000 Z
+date: 2014-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -131,9 +131,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- .rspec
 - .ruby-version
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -182,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: mail_room will proxy email (gmail) from IMAP to a callback URL, logger, or
@@ -199,3 +199,4 @@ test_files:
 - spec/lib/mailbox_spec.rb
 - spec/lib/mailbox_watcher_spec.rb
 - spec/spec_helper.rb
+has_rdoc: 

data/.rspec

@@ -1,2 +0,0 @@
---color
---format nested