= Fetcher

Fetcher is a simple message fetcher perfect for using in a daemon or via cron.

It implements the following common pattern:

1. Connect to a server
2. Download available messages
3. Send each message to another object for further processing
4. Remove downloaded messages from the remote server

Install using:

script/plugin install git://github.com/look/fetcher.git

== Dependencies

If you are using a 1.8 series Ruby, this plugin depends on the SystemTimer gem to work reliably. Do not forget to add it to your Gemfile or environment.rb. As Ruby 1.9 onwards use native threads SystemTimer gem becomes redundant, and timeout.rb is used instead.

== Usage

Create a new fetcher object like the following:

@fetcher = Fetcher.create({:type => :pop, :receiver => IncomingMailHandler, :server => 'mail.example.com', :username => 'jim', :password => 'test'})

The receiver object is expected to have a receive method that takes a message as its only argument (e.g., the way ActionMailer::Base.recieve works; but you don't have to use ActionMailer.).

Call fetch to download messages and process them.

@fetcher.fetch

== Configuration

The following options can be passed to the Fetcher.create factory method:

[type] POP or IMAP [server] The IP address or domain name of the server [port] The port to connect to (defaults to the standard port for the type of server) [ssl] Set to any value to use SSL encryption [username] The username used to connect to the server [password] The password used to connect to the server [authentication] The authentication scheme to use (IMAP only). Supports LOGIN, CRAM-MD5, and PASSWORD (defaults to PLAIN) [use_login] Set to any value to use the LOGIN command instead of AUTHENTICATE. Some servers, like GMail, do not support AUTHENTICATE (IMAP only). [sleep_time] The number of seconds to sleep between fetches (defaults to 60 seconds; valid only for the generated daemon) [in_folder] The name of the folder from which to read incoming mail (IMAP only). Defaults to +INBOX+. [processed_folder] The name of a folder to move mail to after it has been processed (IMAP only). NOTE: If not specified, mail is deleted. [error_folder] The name a folder to move mail that causes an error during processing (IMAP only). Defaults to +bogus+.

== Daemon generator

The Fetcher plugin comes with a generator to create a daemon:

script/generate fetcher_daemon MailerDaemon

You should monitor the daemon using monit or god to ensure it does not crash.

== Running via cron

You can also run the Fetcher periodically via cron. It is important to ensure that only one instance is running at one time, and for that the {Lockfile gem}[http://codeforpeople.com/lib/ruby/lockfile/] is recommended.

Here is an example script to be with script/runner via cron:

begin Lockfile.new('cron_mail_fetcher.lock', :retries => 0) do config = YAML.load_file("#{RAILS_ROOT}/config/mail.yml") config = config[RAILS_ENV].to_options

  fetcher = Fetcher.create({:receiver => MailReceiver}.merge(config))
  fetcher.fetch
end

rescue Lockfile::MaxTriesLockError => e puts "Another fetcher is already running. Exiting." end

== Extending

You can subclass Fetcher::Base or one of the protocol-specific classed to override the standard behavior.

== Further documentation

== Credit & Copyright

Created by Dan Weinand and Luke Francl. Development supported by {Slantwise Design}[http://slantwisedesign.com].

Generators for Rails 3 compatibility added by Amol Hatwár, Exceed Consulting.

Licensed under the terms of the MIT License. Be excellent to each other.