mailhopper 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 Cerebris Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,69 @@
+= Mailhopper
+
+Mailhopper provides an ActiveRecord based queue for email storage and delivery in Rails apps.
+
+Why use Mailhopper to queue your email?
+* Mailhopper captures the full content and headers of emails at their time of creation. It can handle multiple MIME types and attachments.
+* If email can't be delivered from your queue (e.g. your smtp server is down), you can retry delivery until successful.
+* Emails can be accessed at any time, even after they've been sent.
+
+Mailhopper is intended to be used along with a delivery agent such as DelayedMailhopper, which uses DelayedJob to deliver email from the Mailhopper queue. Without use of a delivery agent, emails will accumulate in the Mailhopper queue but won't be delivered.
+
+== Requirements
+
+Rails 3.1+
+
+== Installation
+
+Add to your project's Gemfile:
+
+  gem 'mailhopper'
+  
+Install with bundler:
+
+  bundle install
+  
+Generate default initializer and migration files:
+
+  rails generate mailhopper
+  
+Migrate your database:
+
+  rake db:migrate
+
+!!! Don't forget to also install a delivery agent, such as DelayedMailhopper, so that emails will be delivered from your queue !!!
+  
+== Configuration
+
+If you want all of your application's email to be queued in Mailhopper, configure mailers either in environment.rb or your application's environment-specific configuration files:
+
+  MyApp::Application.configure do
+    config.action_mailer.delivery_method = :mailhopper
+  end
+
+Alternatively, or additionally, configure individual mailers to use Mailhopper:
+
+  class MyMailer < ActionMailer::Base
+    ActionMailer::Base.delivery_method = :mailhopper
+  end
+
+== Options
+
+The following options can be configured in your initializer (config/initializers/mailhopper):
+
+  Mailhopper::Base.setup do |config|
+    # The base email class used by Mailhopper
+    config.email_class = Mailhopper::Email
+
+    # The base mailer class used by Mailhopper
+    config.mailer_class = Mailhopper::Mailer
+    
+    # The method used by the delivery agent to deliver emails from your queue
+    config.default_delivery_method = :smtp
+  end
+
+It's preferable to leave these options out of your initializer if the defaults, shown above, are acceptable. Delivery agents may override some defaults (e.g. DelayedMailhopper sets email_class = DelayedMailhopper::Email).
+
+== Copyright
+
+Copyright (c) 2011 Cerebris Corporation. This is free software released under the MIT License (see MIT-LICENSE for details).

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Mailhopper'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/mailers/mailhopper/mailer.rb

@@ -0,0 +1,4 @@
+module Mailhopper
+  class Mailer < ActionMailer::Base
+  end
+end

data/app/models/mailhopper/email.rb

@@ -0,0 +1,17 @@
+module Mailhopper
+  class Email < ActiveRecord::Base
+    default_scope :order => 'created_at DESC'
+    scope :unsent, :conditions => 'sent_at is null'
+
+    validates :from_address, :presence => true
+
+    def send!(delivery_method = nil)
+      mail = Mail.new(self.content)
+      mail[:bcc] = self.bcc_address unless self.bcc_address.blank?
+      Base.mailer_class.wrap_delivery_behavior(mail, delivery_method || Base.default_delivery_method)
+      mail.deliver
+      self.sent_at = Time.now
+      self.save!
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/generators/mailhopper/mailhopper_generator.rb

@@ -0,0 +1,36 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Mailhopper
+  module Generators
+    class MailhopperGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      desc 'Generates Mailhopper files.'
+
+      def self.source_root
+        File.join(File.dirname(__FILE__), 'templates')
+      end
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+
+      def create_migration_file
+        migration_template 'migrations/create_emails.rb', 'db/migrate/create_emails.rb'
+      end
+
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/mailhopper.rb'
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/mailhopper/templates/README

@@ -0,0 +1,28 @@
+
+===============================================================================
+Mailhopper has been installed.
+===============================================================================
+
+To configure your application to use Mailhopper:
+
+1) Migrate your database with "rake db:migrate".
+
+2) Configure mailers either in environment.rb or environment-specific config files:
+
+  MyApp::Application.configure do
+    config.action_mailer.delivery_method = :mailhopper
+  end
+
+Alternatively, or additionally, you can configure individual mailers:
+
+  class MyMailer < ActionMailer::Base
+    ActionMailer::Base.delivery_method = :mailhopper
+  end
+
+3) Install a delivery agent, such as DelayedMailhopper, so that emails will be delivered from your queue.
+
+4) Configure a delivery method in "config/initializers/mailhopper" for your delivery agent to use (the default is smtp).
+
+  Mailhopper::Base.setup do |config|
+    config.default_delivery_method = :smtp
+  end

data/lib/generators/mailhopper/templates/initializer.rb

@@ -0,0 +1,3 @@
+Mailhopper::Base.setup do |config|
+  config.default_delivery_method = :smtp
+end

data/lib/generators/mailhopper/templates/migrations/create_emails.rb

@@ -0,0 +1,21 @@
+# Everything listed in this migration will be added to a migration file
+# inside of your main app.
+class CreateEmails < ActiveRecord::Migration
+  def self.up
+    create_table :emails do |t|
+      t.string :from_address, :null => false
+      t.string :to_address,
+               :cc_address,
+               :bcc_address,
+               :reply_to_address,
+               :subject
+      t.text :content
+      t.datetime :sent_at
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :emails
+  end
+end

data/lib/mailhopper.rb

@@ -0,0 +1,13 @@
+require "mailhopper/engine"
+require 'mailhopper/queue'
+require 'mailhopper/base'
+
+module Mailhopper
+  class << self
+    def setup(&block)
+      Mailhopper::Base.setup(&block)
+    end
+  end
+end
+
+ActionMailer::Base.add_delivery_method :mailhopper, Mailhopper::Queue

data/lib/mailhopper/base.rb

@@ -0,0 +1,19 @@
+require File.expand_path('../../../app/models/mailhopper/email', __FILE__)
+require File.expand_path('../../../app/mailers/mailhopper/mailer', __FILE__)
+
+module Mailhopper
+  class Base
+    cattr_accessor :email_class
+    self.email_class = Mailhopper::Email
+
+    cattr_accessor :mailer_class
+    self.mailer_class = Mailhopper::Mailer
+
+    cattr_accessor :default_delivery_method
+    self.default_delivery_method = :smtp
+    
+    def self.setup
+      yield self
+    end
+  end
+end

data/lib/mailhopper/engine.rb

@@ -0,0 +1,4 @@
+module Mailhopper
+  class Engine < Rails::Engine
+  end
+end

data/lib/mailhopper/queue.rb

@@ -0,0 +1,18 @@
+module Mailhopper
+  class Queue
+    def initialize(options)
+    end
+
+    def deliver!(mail)
+      Base.email_class.create({
+        :to_address => mail.to.to_s,
+        :from_address => mail.from.to_s,
+        :cc_address => mail.cc.to_s,
+        :bcc_address => mail.bcc.to_s,
+        :reply_to_address => mail.reply_to.to_s,
+        :subject => mail.subject,
+        :content => mail.to_s
+      })
+    end
+  end
+end

data/lib/mailhopper/version.rb

@@ -0,0 +1,3 @@
+module Mailhopper
+  VERSION = "0.0.1"
+end

data/lib/tasks/mailhopper_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :mailhopper do
+#   # Task goes here
+# end

data/test/dummy/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,9 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,7 @@
+/*
+ * This is a manifest file that'll automatically include all the stylesheets available in this directory
+ * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
+ * the top of the compiled file, but it's generally better to create a new file per style scope.
+ *= require_self
+ *= require_tree . 
+*/

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/mailers/sample_mailer.rb

@@ -0,0 +1,8 @@
+class SampleMailer < ActionMailer::Base
+  ActionMailer::Base.delivery_method = :mailhopper
+
+  def hello(headers, content)
+    @content = content
+    mail(headers)
+  end
+end

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag    "application" %>
+  <%= javascript_include_tag "application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy/app/views/sample_mailer/hello.text.erb

@@ -0,0 +1 @@
+<%= @content %>

data/test/dummy/config.ru

@@ -0,0 +1,4 @@
+# This file is used by Rack-based servers to start the application.
+
+require ::File.expand_path('../config/environment',  __FILE__)
+run Dummy::Application

data/test/dummy/config/application.rb

@@ -0,0 +1,42 @@
+require File.expand_path('../boot', __FILE__)
+
+require 'rails/all'
+
+Bundler.require
+require "mailhopper"
+
+module Dummy
+  class Application < Rails::Application
+    # Settings in config/environments/* take precedence over those specified here.
+    # Application configuration should go into files in config/initializers
+    # -- all .rb files in that directory are automatically loaded.
+
+    # Custom directories with classes and modules you want to be autoloadable.
+    # config.autoload_paths += %W(#{config.root}/extras)
+
+    # Only load the plugins named here, in the order given (default is alphabetical).
+    # :all can be used as a placeholder for all plugins not explicitly named.
+    # config.plugins = [ :exception_notification, :ssl_requirement, :all ]
+
+    # Activate observers that should always be running.
+    # config.active_record.observers = :cacher, :garbage_collector, :forum_observer
+
+    # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone.
+    # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC.
+    # config.time_zone = 'Central Time (US & Canada)'
+
+    # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+    # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
+    # config.i18n.default_locale = :de
+
+    # Configure the default encoding used in templates for Ruby 1.9.
+    config.encoding = "utf-8"
+
+    # Configure sensitive parameters which will be filtered from the log file.
+    config.filter_parameters += [:password]
+
+    # Enable the asset pipeline
+    config.assets.enabled = true
+  end
+end
+