mandrill_queue 0.1.1

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec', require: false
+  gem 'guard-rspec', require: false
+
+  gem 'rb-inotify', :require => false
+  gem 'rb-fsevent', :require => false
+  gem 'rb-fchange', :require => false
+
+  gem 'ruby_gntp' if RUBY_PLATFORM =~ /darwin/i
+  gem 'libnotify' if RUBY_PLATFORM =~ /linux/i
+end
+
+# group :development, :test do
+#   gem 'debugger', platform: :ruby
+# end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd: 'rspec --order rand:$RANDOM' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Stan
+
+MIT License
+
+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.md

@@ -0,0 +1,200 @@
+==========================
+  MandrillQueue::Mailer
+==========================
+[![Build Status](https://travis-ci.org/fixate/mandrill_queue.png)](https://travis-ci.org/fixate/mandrill_queue)
+
+DSL for sending mailers through Mailchimps Mandrill API. This gem enqueues the
+message on a background worker (`Resque` only for now, but I want to refactor
+so that it doesnt matter).
+
+The DSL is modelled on the JSON api [here](https://mandrillapp.com/api/docs/messages.ruby.html#method=send-template).
+
+## The DSL
+
+```ruby
+# app/mailers/my_mailer.rb
+class MyMailer < MandrillQueue::Mailer
+  # Template names are inferred from the class_name (without Mailer) + the method
+  # name. Spaces are `sluggified`. If you want to override the prefixes use:
+  # template_prefix 'my-project'
+  # now templates will be 'my-project' + sluggified method
+  #
+  # template_prefix '' means no prefix will be used
+
+  # Set defaults for all methods here.
+  # The full DSL is available here so feel free to include `merge_vars`,
+  # `preserve_recipients`, `to` etc.
+  # Settings here have a lower precedence than method settings.
+  #
+  defaults do
+    # Setting the default template will disable implicit template names
+    # template 'master_template'
+    message do
+      from_email 'no-reply@mysite.com'
+    end
+
+    content do ... end
+  end
+
+  def welcome_dave
+    template 'welcome'
+
+    message do
+      to 'dave@amazabal.ls', 'Dave' # Name optional
+      cc 'davesmom@yahoo.com'
+      bcc 'daves-sis@gmail.com'
+
+      to [{email: 'another@person.com', name: 'Another'}, ...]
+    end
+
+    # Template content
+    # e.g. <div mc:edit="my_tag"></div>
+    content do
+      my_tag '<p>Content!</p>'
+    end
+  end
+
+  def welcome_many(users)
+    message do
+      # If the given parameter is an array of objects or hashes
+      # that respond_to?/has_key? `email` then we're good to go.
+      # Same goes for `name`. Second and third parameters override this
+      # e.g. to users, :work_email, :fullname
+      to users
+
+      # You can also do your own mapping (to, cc and bcc have the same DSL):
+      cc users do |user|
+        email user.work_email
+        name "#{user.firstname} #{user.lastname}"
+      end
+    end
+  end
+
+  def message_with_merge_vars(vars) # Template slug: my-message-with-merge-vars
+    message do
+      to 'some@email.com'
+
+      global_merge_vars do ... end
+      global_merge_vars {vars: 'everywhere'}
+
+      # Substitute *|MERGE_VARS|* in your template for given recipients
+      merge_vars 'some@email.com' do
+        key 'value'
+        whatever 'you want'
+        this_will 'only apply to some@email.com'
+      end
+      # If an array of objects/hashes contains an email method or key
+      # that will be used as the recipient and the rest as normal vars.
+      merge_vars vars #, :other_email_field
+
+      track_clicks false
+  end
+
+  # Use send_at/send_in (no difference) to tell Mandrill to delay sending
+  send_in 2.days.from_now
+end
+
+def html_message(html)
+  message do
+    # (omitted)
+    html "<html><body>#{html}</html></body>"
+  end
+end
+
+# Meanwhile in another file...
+# maybe your controller...
+# Just like ActionMailer (note the class method calls are handed to instance methods)
+MyMailer.welcome_many(users).deliver
+```
+
+## Installation
+
+You probably already know this bit:
+
+    gem 'resque' # Support for Sidekiq and writing custom adapters coming soon...
+    gem 'mandrill-queue'
+
+but didn't know this (but it's optional):
+
+    rails g mandrill_queue:initializer
+
+Global configuration options are documented in the initializer
+but heres a taster:
+
+```ruby
+    MandrillQueue.configure do |config|
+      config.queue = :hipster_queue
+      # ...
+    end
+```
+
+## Setting up the worker
+
+Run it with a rake task like so:
+
+    rake resque:work QUEUES=mailer
+
+TODO: I still need to check that everything is OK when running the worker in Rails
+since I run mine outside Rails as a lightweight worker using:
+
+    rake resque:work -r ./worker.rb QUEUES=mailer
+
+
+## Devise mailer integration
+
+Since Mandrill_Queue quacks like ActionMailer where it counts, getting your Devise
+mailers on Mandrill infrastructure is pretty easy. Here is my implementation:
+
+```ruby
+class DeviseMailer < MandrillResque::Mailer
+  defaults do
+    message do
+      from_email Devise.mailer_sender
+      track_clicks false
+      track_opens false
+      view_content_link false
+    end
+  end
+
+  # Setup a template with the slug: devise-confirmation-instructions
+  def confirmation_instructions(record, token, opts = {})
+    confirm_url = user_confirmation_url(record, confirmation_token: token)
+    devise_mail(record, {name: record.fullname, confirmation_url: confirm_url})
+  end
+
+  # Slug: devise-reset-password-instructions
+  def reset_password_instructions(record, token, opts = {})
+    reset_url = edit_user_password_url(record, reset_password_token: token)
+    devise_mail(record, {name: record.fullname, reset_url: reset_url})
+  end
+
+  # Slug: devise-unlock-instructions
+  def unlock_instructions(record, token, opts = {})
+    unlock_url = user_unlock_url(record, unlock_token: token)
+    devise_mail(record, {name: record.fullname, unlock_url: unlock_url})
+  end
+
+  protected
+  def devise_mail(record, global_vars = {})
+    message do
+      to record, :email, :fullname
+
+      global_merge_vars global_vars
+    end
+  end
+end
+```
+
+## TODO
+
+1. Refactor so that it can work with `Sidekiq` or a custom adapter - coming soon...
+2. Allow synchonous sending.
+2. Render ActionView views to mailers.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+require "rspec/tasks"

data/lib/mandrill_queue/array_metadata.rb

@@ -0,0 +1,103 @@
+module MandrillQueue
+	class ArrayMetadata
+		class Var
+			Variables::DSL.include_as(self, :vars)
+
+			def initialize(recipient = nil, &block)
+				@_recipient = recipient
+				dsl(&block) if block_given?
+			end
+
+			def recipient=(value)
+				@_recipient = value
+			end
+
+			def recipient(value = nil)
+				@_recipient = value unless value.nil?
+				@_recipient
+			end
+
+			def to_hash(options = {})
+				hash = {}
+				hash[:rcpt] = recipient if options[:include_nils] || !recipient.nil?
+				hash[:vars] = vars.to_key_value_array(options) if options[:include_nils] || !@_vars.nil?
+				hash
+			end
+
+			def set!(hash)
+				@_recipient = hash[:rcpt]
+				@_vars = nil
+				vars.set!(hash[:vars]) unless hash[:vars].nil?
+				self
+			end
+
+			def dsl(&block)
+				vars.dsl(&block)
+			end
+
+			def validate(errors)
+				errors.push([:merge_vars, "Recipient cannot be empty for merge vars."]) if recipient.blank?
+			end
+		end
+
+		module DSL
+			def merge_vars(recipient = nil, &block)
+				@_merge_vars ||= MergeVars.new
+				@_merge_vars.dsl(recipient, &block) if !recipient.nil? || block_given?
+				block_given? ? self : @_merge_vars
+			end
+		end
+
+		def initialize
+			@_merge_vars = []
+		end
+
+		def add(*args, &block)
+			@_merge_vars << Var.new(*args, &block)
+		end
+
+		alias_method :dsl, :add
+
+		def to_a(options = {})
+			@_merge_vars.map do |v|
+				v.to_hash(options)
+			end
+		end
+
+		def first
+			@_merge_vars.first
+		end
+
+		def last
+			@_merge_vars.last
+		end
+
+		def [](index)
+			@_merge_vars[index]
+		end
+
+		def count
+			@_merge_vars.count
+		end
+
+		def merge_vars
+			@_merge_vars
+		end
+
+		def validate(errors)
+			@_merge_vars.each do |v|
+				v.validate(errors)
+			end
+		end
+
+		def set!(list)
+			@_merge_vars = list.map do |obj|
+				Var.new.set!(obj.symbolize_keys)
+			end
+
+			self
+		end
+	end
+
+	end
+end

data/lib/mandrill_queue/configuration.rb

@@ -0,0 +1,42 @@
+module MandrillQueue
+	class Configuration
+		ACCESSORS = [:message_defaults, :resque, :default_worker_class,
+							 :default_queue, :api_key, :logger]
+		attr_accessor(*ACCESSORS)
+
+		def initialize(defaults = {}, &block)
+			set(defaults)
+			instance_eval(&block) if block_given?
+		end
+
+		def []=(key, value)
+			send("#{key}=", value)
+		end
+
+		def [](key)
+			send(key)
+		end
+
+		def reset
+			ACCESSORS.each do |key|
+				send("#{key}=", nil)
+			end
+
+			yield self if block_given?
+		end
+
+		def each_key(&block)
+			ACCESSORS.each(&block)
+		end
+
+		def set(hash)
+			each_key do |k, v|
+				send("#{k}=", hash[k])
+			end
+		end
+
+		def self.accessors
+			ACCESSORS
+		end
+	end
+end

data/lib/mandrill_queue/core_ext.rb

@@ -0,0 +1,15 @@
+require 'active_support/core_ext/string'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/array'
+
+class String
+	def sluggify
+		value = self
+    value.gsub!(/[']+/, '')
+    value.gsub!(/\W+/, ' ')
+    value.strip!
+    value.downcase!
+		value.gsub!(/[^A-Za-z0-9]/, '-')
+    value
+	end
+end

data/lib/mandrill_queue/errors.rb

@@ -0,0 +1,24 @@
+module MandrillQueue
+	class Error < ::StandardError; end
+
+	class MandrillValidationError < Error
+		def initialize(errors)
+			@_errors = errors
+			super(message)
+		end
+
+		def message
+			<<-TXT
+			Validation Errors:
+			#{@_errors.inject(''){ |s, (name, e)| s += "\n- [#{name}]: #{e}" }}
+			TXT
+		end
+	end
+
+	class MessageError < Error; end
+
+	class VariableError < Error; end
+	class VariableNotSetError < VariableError; end
+
+	class RecipientDataError < Error; end
+end

data/lib/mandrill_queue/logging.rb

@@ -0,0 +1,51 @@
+require 'pp'
+require 'stringio'
+
+module MandrillQueue
+	module Logging
+		def logging
+			@_logger ||= MandrillQueue.configuration.logger || begin
+			MandrillQueue.resque.constants.include?(:Logging) ? MandrillQueue.resque::Logging : nil
+			end
+		end
+
+		def pretty(obj)
+			s = StringIO.new
+			PP.pp(obj, s)
+			s.rewind
+			s.read
+		end
+
+		def result_formatter(r)
+			<<-TXT
+				ID: #{r['_id']}
+				EMAIL: #{r['email']}
+				STATUS: #{r['status']}
+				---
+				TXT
+		end
+
+		def log_results(result)
+			errors = []
+			formatted = result.map do |r|
+				unless ['sent', 'queued'].include?(r['status'])
+					errors << result_formatter(r)
+				end
+
+				result_formatter(r)
+			end
+
+			logging.debug <<-TXT.tr("\t", '')
+				\n*******************************************
+			#{formatted.join("\n")}
+				*******************************************
+			TXT
+
+			if errors.empty?
+				logging.info("#{result.count} message(s) successfully sent.")
+			else
+				logging.error("The following messages were not sent:\n#{errors.join("\n")}")
+			end
+		end
+	end
+end

data/lib/mandrill_queue/mailer.rb

@@ -0,0 +1,184 @@
+require 'mandrill_queue'
+require 'mandrill_queue/errors'
+require 'mandrill_queue/message'
+require 'mandrill_queue/variables'
+
+module MandrillQueue
+	class Mailer
+		class << self
+			def respond_to?(method, include_private = false)
+				super || action_methods.include?(method)
+			end
+
+			def action_methods
+				klass = self
+				klass = klass.superclass until klass == MandrillQueue::Mailer
+				return [] if self == klass
+				self.public_instance_methods(true) -
+					klass.public_instance_methods(true)
+			end
+
+			def method_missing(method, *args)
+				if respond_to?(method)
+					mailer = new(defaults)
+					mailer.send(method, *args)
+					mailer.template(template_from_method(method)) if mailer.template.blank? &&
+						!mailer.message.content_message?
+					mailer
+				else
+					super
+				end
+			end
+
+			def configuration
+				MandrillQueue.configuration
+			end
+
+			def defaults(&block)
+				return @_defaults ||= {} unless block_given?
+
+				mailer = new
+				@_in_defaults = true
+				mailer.instance_eval(&block)
+				@_defaults = mailer.to_hash
+			ensure
+				@_in_defaults = false
+			end
+
+			def defaults=(hash)
+				@_defaults = hash
+			end
+
+			def message_defaults
+				md = configuration.message_defaults
+				md.merge!(defaults[:message]) unless @_in_defaults || defaults[:message].nil?
+				md
+			end
+
+			def template_prefix(*args)
+				@template_prefix = args.first unless args.count == 0
+				if @template_prefix.nil?
+					"#{self.name.chomp('Mailer').sluggify}-"
+				else
+					@template_prefix
+				end
+			end
+
+			def all_templates
+				action_methods.map do |method|
+					template_from_method(method)
+				end
+			end
+
+		private
+			def template_from_method(method)
+				template = defaults[:template].blank? ? method.to_s.sluggify : defaults[:template]
+				template_prefix + template
+			end
+		end # End Singleton
+
+		ACCESSORS = [:template, :send_at]
+
+		def initialize(values = nil)
+			set!(values) unless values.nil?
+		end
+
+		def reset!
+			ACCESSORS.each do |key|
+				instance_variable_set("@#{key}", nil)
+			end
+			@_message = nil
+			@_content = nil
+			self
+		end
+
+		def message(&block)
+			@_message ||= Message::Internal.new(self.class.message_defaults)
+			@_message.dsl(&block) if block_given?
+			block_given? ? self : @_message
+		end
+
+		# Define setters
+		ACCESSORS.each do |key|
+			define_method key do |value = nil|
+				var = "@#{key}".to_sym
+				if value.nil?
+					instance_variable_get(var)
+				else
+					instance_variable_set(var, value)
+					self
+				end
+			end
+		end
+
+		alias :send_in :send_at
+
+		def worker_class
+			self.class.configuration.default_worker_class || ::MandrillQueue::Worker
+		end
+
+		def queue
+			@_queue ||= \
+
+			if instance_variable_defined?(:@queue)
+				instance_variable_get(:@queue)
+			elsif worker_class.instance_variable_defined?(:@queue)
+				worker_class.instance_variable_get(:@queue)
+			elsif worker_class.respond_to?(:queue)
+				worker_class.queue
+			else
+				self.class.configuration.default_queue || :mailer
+			end
+		end
+
+		def deliver
+			validate!
+			MandrillQueue.resque.enqueue_to(queue, worker_class, to_hash)
+		end
+
+		def to_hash(options = {})
+			hash = {}
+			ACCESSORS.each do |key|
+				value = instance_variable_get("@#{key}".to_sym)
+				hash[key] = value if options[:include_nil] || !value.nil?
+			end
+
+			hash[:message] = message.to_hash(options) rescue nil if !@_message.nil? || options[:include_nils]
+			hash[:content] = content.to_key_value_array(options) rescue nil if !@_content.nil? || options[:include_nils]
+			hash
+		end
+
+		def set!(hash)
+			hash.symbolize_keys!
+			ACCESSORS.each do |key|
+				instance_variable_set("@#{key}", hash[key])
+			end
+
+			message.set!(hash[:message]) unless hash[:message].nil?
+			content.set!(hash[:content]) unless hash[:content].nil?
+			self
+		end
+
+		alias_method :dsl, :instance_eval
+
+		def use_defaults!
+			set!(self.class.defaults) unless self.class.defaults.nil?
+			self
+		end
+
+		def validate!
+			errors = []
+			message.validate(errors) unless @_message.nil?
+
+			raise MandrillValidationError.new(errors) unless errors.empty?
+			self
+		end
+
+		# Include variable DSL at end of class
+		Variables::DSL.include_as(self, :content)
+	end
+end
+
+if defined?(ActiveSupport)
+	ActiveSupport.run_load_hooks(:mandrill_queue, MandrillQueue::Mailer)
+end

data/lib/mandrill_queue/mandrill_api.rb

@@ -0,0 +1,25 @@
+require 'mandrill'
+require 'mandrill_queue'
+
+module MandrillQueue
+	module MandrillApi
+		class Error < ::StandardError; end
+
+		def configuration
+			MandrillQueue.configuration
+		end
+
+		def mandrill
+			@_api ||= begin
+				if configuration.api_key.nil?
+					raise MandrillQueue::Api::Error, <<-ERR
+					An Api key has not been configured. Please configure on as follows in an initializer:
+					MandrillQueue.configure do { |c| c.api_key = 'xxxxxxxxxxxxxx' }
+					ERR
+				end
+
+				Mandrill::API.new(configuration.api_key)
+			end
+		end
+	end
+end