emilio 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in emilio.gemspec
+gemspec

data/README.md

@@ -0,0 +1,123 @@
+Emilio
+======
+
+With Emilio you can parse external emails sent to your application using the
+IMAP protocol.
+
+
+Usage
+=====
+
+Once configured, you can do:
+
+    Emilio::Checker.check_emails
+
+To issue an IMAP connection to your server and fetch the new emails to be
+parsed.
+
+
+Configuration
+-------------
+
+You must setup Emilio in order to provide your IMAP server settings and your
+credentials, among other optional stuff:
+
+    Emilio.configure do |config|
+      config.host = "imap.gmail.com"
+      config.port = 993
+      config.username = "your@username.com"
+      config.password = "password"
+
+      config.add_label = "processed"
+      config.mailbox = "Inbox"
+      config.scheduler = :delayed_job
+      config.run_every = 10.minutes
+
+      config.parser = :my_parser
+    end
+
+This is recommended to be inside an initializer, something like
+`config/initializers/emilio.rb` will do the job. The first configuration
+options are very self explanatory, host and account credentials.
+
+- `add_label` is an optional label which you already must have in your GMail
+  account, that will be applied to each processed email. I'm talking here
+  about *labels* but this will apply to *folders* in other non-gmail providers
+  too.
+
+- `mailbox` is the name of the mailbox you want to parse emails from. By
+  default it's "Inbox", but it can be personalized to anything if you want to
+  choose which specific emails have to be parsed. This can be acomplished
+  simply by adding filters in your email account that moves the selected
+  emails into the *parsing* folder. In GMail this can be a label name too.
+
+- `scheduler` is the name of the scheduler you want to use to perform
+  recurring email checkings. By now Emilio ships with a :delayed_job
+  integration but more can be added in the future.
+
+- `run_every` is the amount of time between recurring checks, if you're using
+  a scheduler.
+
+- `parser` is the class name of your parser, and it's a requirment. More in
+  the next paragraph...
+
+
+Your parser class
+-----------------
+
+In order to do things with the emails your application receive, you must setup
+a class to do the parsing stuff, something like:
+
+    class MyParser < Emilio::Receiver
+      def parse
+        # Find a reference in the subject or sender
+        reference = find_a_reference_in(@subject, @sender)
+
+        # Do stuff
+        Message.create! :text => @body, :author => @sender
+      end
+    end
+
+Your class must inherit from `Emilio::Receiver` and implement a `parse`
+method, or if you like to do things the hard way you could also use a regular
+ActionMailer class:
+
+    class MyParser < ActionMailer::Base
+      def receive(email)
+        # email is a TMail object
+      end
+    end
+
+The `Emilio::Receiver` class will make things a little easier for you,
+providing the following instance variables you can use in `parse`:
+
+- @email: The TMail object representing the original email.
+- @html: true or false.
+- @attachments: Simply a shortcut to @email.attachments
+- @sender: The sender of the email, same as @email.from
+- @body: The body of the email correctly encoded as UTF-8.
+- @subject: Subject encoded as UTF-8.
+
+As you can see `Emilio::Receiver` doesn't make a lot of work, but it solves
+some encoding issues.
+
+
+Schedulers
+----------
+
+The schedulers are meant to cover the necessity of a recurring email checking
+system. You can run `Emilio::Checker.check_emails` to do the job, but you
+probably want to run it every 5 minutes or so, to keep you app up to date.
+
+If you want you can run your own solution, maybe with a Cron entry (the
+awesome gem [Whenever](https://github.com/javan/whenever) makes a great job
+dealing with cron) but I've found that loading the entire application stack
+every 5 minutes in my VPS shared host with 512 of RAM is overkilling.
+
+This is why I've come up with this solution taking advantage of the also
+excellent DelayedJob, using jobs that make the checking some time in the
+future (making use of the :run_at option) and then re-enqueuing themselves.
+
+While by now there is only delayed_job integration, the schedulers
+arquitecture is flexible enough to allow an easy implementation of another
+solutions like Resque, etc...

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/emilio.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "emilio/version"
+
+Gem::Specification.new do |s|
+  s.name        = "emilio"
+  s.version     = Emilio::VERSION
+  s.authors     = ["Roger Campos"]
+  s.email       = ["roger@itnig.net"]
+  s.homepage    = ""
+  s.summary     = %q{Parse incoming emails with IMAP}
+  s.description = %q{Parse incoming emails with IMAP}
+
+  s.rubyforge_project = "emilio"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'rails', '~> 3.0.0'
+end

data/lib/emilio/checker.rb

@@ -0,0 +1,50 @@
+module Emilio
+  class Checker
+    def self.check_emails
+      # Make sure we use a compatible Time format, otherwise TMail will
+      # not be able to parse the email timestamp.
+      old_time_format = Time::DATE_FORMATS[:default]
+      Time::DATE_FORMATS[:default] = '%m/%d/%Y %H:%M'
+
+
+      begin
+        # make a connection to imap account
+        imap = Net::IMAP.new(Emilio.host, Emilio.port, true)
+        imap.login(Emilio.username, Emilio.password)
+
+        # select which mailbox to process
+        imap.select(Emilio.mailbox)
+
+        # get all emails in that mailbox that have not been deleted
+        imap.uid_search(["NOT", "DELETED"]).each do |uid|
+          # fetches the straight up source of the email for tmail to parse
+          source = imap.uid_fetch(uid, ['RFC822']).first.attr['RFC822']
+
+          Emilio.parser.classify.constantize.receive(source)
+
+          # Optionally assign it some label
+          imap.uid_copy(uid, Emilio.add_label) if Emilio.add_label
+
+          # Delete it from Inbox (Gmail Archive)
+          imap.uid_store(uid, "+FLAGS", [:Deleted])
+        end
+
+        # expunge removes the deleted emails
+        imap.expunge
+        imap.logout
+        imap.disconnect
+
+      # NoResponseError and ByeResponseError happen often when imap'ing
+      rescue Net::IMAP::NoResponseError => e
+        Emilio.logger.error("No response: #{e}")
+      rescue Net::IMAP::ByeResponseError => e
+        Emilio.logger.error("Bye response: #{e}")
+      rescue => e
+        Emilio.logger.error("Error: #{e}")
+      end
+
+      Time::DATE_FORMATS[:default] = old_time_format
+      nil
+    end
+  end
+end

data/lib/emilio/logger.rb

@@ -0,0 +1,8 @@
+module Emilio
+  class EmilioLogger < Logger
+    def format_message(severity, timestamp, progname, msg)
+      "#{timestamp.to_formatted_s(:db)} #{msg}\n"
+    end
+  end
+end
+

data/lib/emilio/railtie.rb

@@ -0,0 +1,22 @@
+module Emilio
+  class Railtie < Rails::Railtie
+    initializer "emilio.setup_logger" do |app|
+      logfile = File.open("#{Rails.root}/log/emilio.log", 'a')
+      logfile.sync = true
+      Emilio.logger = EmilioLogger.new(logfile)
+    end
+
+    initializer "emilio.init_scheduler" do |app|
+      app.config.after_initialize do
+        if Emilio.scheduler
+          if Emilio.scheduler.respond_to?(:init)
+            Emilio.scheduler.init
+          else
+            raise LoadError, "It seems that #{Emilio.scheduler.inspect.split("::").last} was in your Gemfile but declared after Emilio. Please make sure you declare it before Emilio in order to avoid requiring order issues like this."
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/emilio/receiver.rb

@@ -0,0 +1,32 @@
+module Emilio
+  class Receiver < ActionMailer::Base
+    def receive(email)
+      @email = email
+      @html = false
+      @attachments = email.attachments
+      @sender = email.from.to_s
+
+      if email.multipart?
+        if email.html_part.present?
+          ic = Iconv.new('utf-8', email.html_part.charset)
+          @body = ic.iconv(email.html_part.body.to_s)
+          @html = true
+        else
+          ic = Iconv.new('utf-8', email.text_part.charset)
+          @body = ic.iconv(email.text_part.body.to_s)
+        end
+      else
+        ic = Iconv.new('utf-8', email.charset)
+        @body = ic.iconv(email.body.to_s)
+      end
+      @subject = ic.iconv(email.subject)
+      Emilio.logger.info("Parsed email [#{@subject}] from [#{@sender}]")
+
+      parse
+    end
+
+  protected
+    def parse
+    end
+  end
+end

data/lib/emilio/schedulers/base.rb

@@ -0,0 +1,15 @@
+module Emilio
+  module Schedulers
+    mattr_accessor :last_check_at
+    mattr_accessor :registered_schedulers
+    @@registered_schedulers = []
+  end
+
+  def self.scheduler=(type)
+    unless Schedulers.registered_schedulers.include?(type.to_sym)
+      raise NotImplementedError, "This scheduler is not supported."
+    end
+
+    @@scheduler = "Emilio::Schedulers::#{type.to_s.classify}".constantize.setup
+  end
+end

data/lib/emilio/schedulers/delayed_job/scheduler.rb

@@ -0,0 +1,29 @@
+module Emilio
+  module Schedulers
+    module DelayedJob
+      def self.init
+        # Ideally this should be a recurring Job and this implementation is a
+        # poor workaround. Must be refactored if DJ implements real recurring jobs:
+        # https://github.com/collectiveidea/delayed_job/wiki/FEATURE:-Adding-Recurring-Job-Support-to-Delayed_Job
+        Delayed::Job.enqueue ScheduleJob.new, :run_at => Time.now + Emilio.run_every
+      end
+
+      class ScheduleJob
+        def perform
+          unless Emilio::Schedulers.last_check_at.nil? || ( Time.now > Emilio::Schedulers.last_check_at + Emilio.run_every * 0.9 )
+            # Break here to avoid two chains of recurring jobs. Please
+            # refactor me! We need your recurring jobs DJ!
+            return
+          end
+
+          Emilio::Checker.check_emails
+          Emilio::Schedulers.last_check_at = Time.now
+
+          Delayed::Job.enqueue ScheduleJob.new, :run_at => Time.now + Emilio.run_every
+        end
+      end
+    end
+  end
+end
+
+

data/lib/emilio/schedulers/delayed_job.rb

@@ -0,0 +1,17 @@
+Emilio::Schedulers.registered_schedulers << :delayed_job
+
+module Emilio
+  module Schedulers
+    module DelayedJob
+      def self.setup
+        unless defined?(Delayed)
+          raise LoadError, "Please include 'delayed_job' in your Gemfile or require it manually before using this scheduler."
+        end
+
+        Emilio::Schedulers::DelayedJob
+      end
+    end
+  end
+end
+
+require 'emilio/schedulers/delayed_job/scheduler' if defined?(Delayed)

data/lib/emilio/version.rb

@@ -0,0 +1,3 @@
+module Emilio
+  VERSION = "0.1.0"
+end

data/lib/emilio.rb

@@ -0,0 +1,48 @@
+require 'emilio/version'
+
+require 'net/imap'
+require 'net/http'
+
+require 'emilio/logger'
+require 'emilio/railtie' if defined?(Rails)
+require 'emilio/checker'
+require 'emilio/receiver'
+
+module Emilio
+  mattr_accessor :logger
+
+  # Your parser class, must be defined
+  mattr_accessor :parser
+
+  # Optional label to be added to parsed emails
+  mattr_accessor :add_label
+
+  # In which mailbox look for new emails to be parsed. This is "Inbox" by
+  # default, but can be changed to anything if you want custom behaviour. For
+  # instance you can define a filter or a set of filters in your Gmail account to
+  # move emails to be parsed into a specific folder (assign a label) and only
+  # parse emails with that label (equivalent mailbox name).
+  mattr_accessor :mailbox
+
+  # Which sheduler use, if any
+  mattr_accessor :scheduler
+  # Amount of time between each run, when a scheduler is used. Accepts 1.hour
+  # and this kind of sugar syntax
+  mattr_accessor :run_every
+
+  # Settings of your IMAP account
+  mattr_accessor :host
+  mattr_accessor :port
+  mattr_accessor :username
+  mattr_accessor :password
+
+  @@mailbox = "Inbox"
+  @@run_every = 10.minutes
+
+  def self.configure
+    yield self
+  end
+end
+
+Dir["#{File.dirname(__FILE__)}/emilio/schedulers/*.rb"].each{|f| require f}
+

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: emilio
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Roger Campos
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-13 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+description: Parse incoming emails with IMAP
+email: 
+- roger@itnig.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- emilio.gemspec
+- lib/emilio.rb
+- lib/emilio/checker.rb
+- lib/emilio/logger.rb
+- lib/emilio/railtie.rb
+- lib/emilio/receiver.rb
+- lib/emilio/schedulers/base.rb
+- lib/emilio/schedulers/delayed_job.rb
+- lib/emilio/schedulers/delayed_job/scheduler.rb
+- lib/emilio/version.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: emilio
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Parse incoming emails with IMAP
+test_files: []
+