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

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:

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 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

<shameless-plug>

You can read more about how to use the Fetcher in the PeepCode book Receiving Email with Ruby.

</shameless-plug>

Credit & Copyright

Created by Dan Weinand and Luke Francl. Development supported by Slantwise Design.

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