newman 0.1.1 → 0.2.0

data/lib/newman/controller.rb

@@ -1,30 +1,99 @@
+# `Newman::Controller` provides a context for application callbacks to run in,
+# and provides most of the core functionality for preparing a response email.
+#
+# For a full example of `Newman::Controller` in action, be sure to check out
+# [Jester](https://github.com/mendicant-university/jester).
+#
+# `Newman::Controller` is part of Newman's **external interface**.
+
 module Newman
   class Controller
+
+    #---
+    
+    # A `Newman::Controller` object is initialized with parameters that match
+    # what is provided by the low level `Newman::Server` object. Generally
+    # speaking, you won't instantiate controller objects yourself, but instead
+    # will rely on `Newman::Application` to instantiate them for you.
+
     def initialize(params)
       self.settings = params.fetch(:settings)
       self.request  = params.fetch(:request)
       self.response = params.fetch(:response)
+      self.logger   = params.fetch(:logger)
     end
 
-    attr_accessor :params
+    # ---
+
+    # All of the fields on `Newman::Controller` are public, so that they can
+    # freely be manipulated by callbacks. We may lock this down a bit more
+    # in a future version of Newman once we figure out what data actually needs
+    # to be exposed in callbacks, but for now you can feel free to depend on
+    # any of these fields.
+ 
+    attr_accessor :settings, :request, :response, :logger, :params
+
+
+    # ---
+    
+    # `Newman::Controller#respond` is used to modify the response email object,
+    # and is used in the manner shown below:
+    #
+    #     respond :subject => "Hello There", 
+    #             :body    => "It's nice to meet you, pal!"
+    # 
+    # Because this method simply provides syntactic sugar on top of the
+    # `Mail::Message` object's interface, you should be sure to take a look at
+    # the documentation for the [mail gem](http://github.com/mikel/mail) to
+    # discover what options are available.
 
     def respond(params)
       params.each { |k,v| response.send("#{k}=", v) }
     end
 
+    # ---
+    
+    # `Newman::Controller#template` is used to invoke a template file within the
+    # context of the current controller object using Tilt. A name for the template is
+    # provided and then looked up in the directory referenced by
+    # `settings.service.templates_dir`. While an example of using templates is 
+    # included in Newman's source, this feature hasn't really been tested 
+    # adequately. Please report any problems with this method in our 
+    # [issue tracker](https://github.com/mendicant-university/newman/issues).
+
     def template(name)
       Tilt.new(Dir.glob("#{settings.service.templates_dir}/#{name}.*").first)
           .render(self)
     end
 
-    def sender
-      request.from.first.to_s
-    end
+    # --- 
 
-    def domain
-      settings.service.domain 
+    # `Newman::Controller#skip_response` is used for disabling the delivery of
+    # the response email. Use this for situations where no response is required,
+    # such as when a spam email or a bounce has been detected, or if you are
+    # building an application which simply passively monitors incoming email
+    # rather than replying to it.
+
+    def skip_response
+      response.perform_deliveries = false
     end
 
+    # ---
+    
+    # `Newman::Controller#forward_message` works in a similar fashion to
+    # `Newman::Controller#response`, but copies the request FROM, SUBJECT
+    # and BODY fields and sets the REPLY TO field to be equal to
+    # `settings.service.default_sender`. This feature is convenient for
+    # implementing mailing-list style functionality, such as in the 
+    # following example:
+    #
+    #     if list.subscriber?(sender)
+    #       forward_message :bcc => list.subscribers.join(", ")
+    #     else
+    #       respond :subject => "You are not subscribed",
+    #               :body    => template("non-subscriber-error")
+    #     end
+
     def forward_message(params={})
       response.from      = request.from
       response.reply_to  = settings.service.default_sender 
@@ -42,8 +111,24 @@ module Newman
       end
     end
 
-    private
+    # ---
+    
+    # `Newman::Controller#sender` is used as a convenient shortcut for
+    # retrieving the sender's email address from the request object.
+
+    def sender
+      request.from.first.to_s
+    end
+
+    # ---
+    
+    # `Newman::Controller#domain` is used as a convenient shortcut for
+    # referencing `settings.service.domain`.
+
+    def domain
+      settings.service.domain 
+    end
+
 
-    attr_accessor :settings, :request, :response
   end
 end

data/lib/newman/email_logger.rb

@@ -0,0 +1,54 @@
+# `Newman::EmailLogger` provides rudimentary logging support for email objects,
+# and primarily exists to support the `Newman::RequestLogger` and
+# `Newman::ResponseLogger` objects.
+#
+# If you are only interested in making use of this logging functionality and not
+# extending it or changing it in some way, you do not need to be familiar with
+# the code in this file. Just be sure to note that if you add
+# `service.debug_mode = true` to your configuration file, or set the Ruby 
+# `$DEBUG` global variable, you will get much more verbose output from 
+# Newman's logging system.
+#
+# `Newman::EmailLogger` is part of Newman's **internal interface**.
+
+module Newman
+  module EmailLogger
+
+    # ---
+    
+    # `Newman::EmailLogger#log_email` takes a logger object, a prefix, and a `Mail` object and 
+    # then outputs relevant debugging details. 
+    #
+    # This method always at least provides a summary of the provided `email`
+    # at the `INFO` level When in debugging mode, the full contents of 
+    # the `email` will also gets logged.
+    #
+    # The main purpose of this method is to be used by `Newman::RequestLogger`
+    # and `Newman::ResponseLogger`, but may also optionally be used as a helper
+    # for those who are rolling their own logging functionality.
+
+    def log_email(logger, prefix, email)
+      logger.debug(prefix) { "\n#{email}" }
+      logger.info(prefix) { email_summary(email) }
+    end
+
+    # ---
+    
+    # **NOTE: Methods below this point in the file are implementation details, 
+    # and should not be depended upon**
+    
+    private
+
+    # ---
+    
+    # `Newman::EmailLogger#email_summary` returns a hash with a summary of the provided `email` object. 
+
+    def email_summary(email)
+      { :from     => email.from,
+        :to       => email.to,
+        :bcc      => email.bcc,
+        :subject  => email.subject,
+        :reply_to => email.reply_to }
+    end
+  end
+end

data/lib/newman/filters.rb

@@ -0,0 +1,123 @@
+# `Newman::Filters` provides the standard filtering mechanisms for 
+# Newman applications. 
+#
+# Unless you are building a server-side extension for
+# Newman, you probably only need to be familiar with how these filter methods
+# are used and can treat their implementation details as a black box.
+#
+# `Newman::Filters` is part of Newman's **external interface**.
+
+module Newman 
+  module Filters
+    
+    # ---
+    
+    # `Newman::Filters#to` takes a `filter_type`, a `pattern`, 
+    # and an `action` and then registers a callback which gets run for 
+    # each new request the application handles. If the filter matches the 
+    # incoming message, the `action` block gets run in the context of
+    # a `Newman::Controller` object. Otherwise, the `action` block 
+    # does not get run at all.
+    #
+    # Currently, the only supported `filter_type` is `:tag`, which leverages the
+    # `+` extension syntax for email addresses to filter out emails with certain
+    # tags in their TO field. For example, we could build a filter that responds
+    # to messages sent to `USERNAME+ping@HOST` using the following filter
+    # setup:
+    #
+    #     to(:tag, "ping") do
+    #       respond(:subject => "pong")
+    #     end
+    #
+    # Because this method runs the `pattern` through 
+    # `Newman::Application#compile_regex`, it can also be used in 
+    # combination with `Newman::Application#match` to do more
+    # complex matching. For example, the code below could be used to support
+    # complex TO field mappings, such as `USERNAME+somelist.subscribe@HOST`:
+    #
+    #     match :list_id, "[^.]+"
+    #
+    #     to(:tag, "{list_id}.subscribe") do
+    #       list = load_list(params[:list_id]) 
+    # 
+    #       if list.subscriber?(sender)
+    #         # send failure email, already subscribed
+    #       else
+    #         # add user to list and send success email
+    #       end
+    #     end
+    #
+    # Note that currently everything before the `+` in the email address is 
+    # ignored, and that the domain is hardcoded to match the
+    # `Controller#domain`, which currently directly references the
+    # `service.domain` setting. It'd be nice to make this a bit more 
+    # flexible and also support other filter types such as a match against the
+    # whole email address at some point in the future.
+
+    def to(filter_type, pattern, &action)
+      raise NotImplementedError unless filter_type == :tag
+
+      regex = compile_regex(pattern)
+
+      callback action, ->(controller) {
+        controller.request.to.each do |e| 
+          md = e.match(/\+#{regex}@#{Regexp.escape(controller.domain)}/)
+          return md if md
+        end
+
+        false
+      }
+    end
+
+    # ---
+
+    # `Newman::Filters#subject` takes a `filter_type`, 
+    # a `pattern`, and an `action` and
+    # then registers a callback which gets run for each new request the
+    # application handles. If the filter matches the incoming message, the
+    # `action` block gets run in the context of a `Newman::Controller` object.
+    # Otherwise, the `action` block does not get run at all.
+    #
+    # Currently, the only supported `filter_type` is `:match`, which matches the
+    # pattern against the full SUBJECT field. This can be used for simple
+    # subject based filtering, such as the code shown below:
+    #
+    #     subject(:match, "what stories do you know?") do
+    #       respond :subject => "All of Jester's stories",
+    #              :body => story_library.map { |e| e.title }.join("\n")
+    #     end
+    # 
+    # Because this method runs the `pattern` through 
+    # `Newman::Application#compile_regex`, it can also be used in 
+    # combination with `Newman::Application#match` to do more
+    # complex matching, such as in the following example:
+    #
+    #     match :genre, '\S+'
+    #     match :title, '.*'
+    #
+    #     subject(:match, "a {genre} story '{title}'") do
+    #       story_library.add_story(:genre => params[:genre],
+    #                               :title => params[:title],
+    #                               :body => request.body.to_s)
+    #
+    #       respond :subject => "Jester saved '#{params[:title]}'"
+    #     end
+    #
+    # It'd be nice to support more kinds of matching strategies at some point in
+    # the future, so be sure to let us know if you have ideas.
+
+    def subject(filter_type, pattern, &action)
+      raise NotImplementedError unless filter_type == :match
+
+      regex = compile_regex(pattern)
+
+      callback action, ->(controller) {
+        subject = controller.request.subject
+
+        return false unless subject
+
+        subject.match(/#{regex}/) || false
+      }
+    end
+  end
+end

data/lib/newman/mailer.rb

@@ -1,41 +1,107 @@
+# `Newman::Mailer` allows you to easily receive mail via IMAP and send mail via
+# SMTP, and is the default mailing strategy used by `Newman::Server.simple`.
+# This class mostly exists to serve as an adapter that bridges the gap between
+# the mail gem and Newman's configuration system. 
+#
+# `Newman::Mailer`'s interface is minimal by design so that other objects
+# can easily stand in for it as long as they respond to the same set of
+# messages. Be sure to see `Newman::TestMailer` for an example of how to build a
+# custom object that can be used in place of a `Newman::Mailer` object.
+#
+#
+# `Newman::Mailer` is part of Newman's **internal interface**.
+
 module Newman
-  Mailer = Object.new
+  class Mailer
+    
+    # ---
+    
+    # To initialize a `Newman::Mailer` object, a settings object must be
+    # provided, i.e:
+    #
+    #     settings = Newman::Settings.from_file('config/environment.rb')
+    #     mailer   = Newman::Mailer.new(settings)
+    #
+    # This is done automatically for you by `Newman::Server.simple`, but must be
+    # done manually if you are creating a `Newman::Server` instance from
+    # scratch.
+    #
+    # Currently, not all of the settings supported by the mail gem are mapped by
+    # Newman. This is by design, to limit the amount of configuration options
+    # need to think about. However, if this is causing you a problem, 
+    # please [file an issue](https://github.com/mendicant-university/newman/issues).
 
-  class << Mailer
-    def configure(settings)
+    def initialize(settings)
       imap = settings.imap
       smtp = settings.smtp
 
-      Mail.defaults do
-         retriever_method :imap, 
-           :address    => imap.address,
-           :user_name  => imap.user,
-           :password   => imap.password,
-           :enable_ssl => imap.ssl_enabled || false,
-           :port       => imap.port
-
-         delivery_method :smtp,
-           :address              => smtp.address,
-           :user_name            => smtp.user,
-           :password             => smtp.password,
-           :authentication       => :plain,
-           :enable_starttls_auto => smtp.starttls_enabled || false,
-           :port                 => smtp.port
-      end
-
-      def messages
-        Mail.all(:delete_after_find => true)
-      end
-
-      def new_message(*a, &b)
-        Mail.new(*a, &b)
-      end
-
-      def deliver_message(*a, &b)
-        new_message(*a, &b).deliver
-      end
+      self.retriever_settings = {
+         :address    => imap.address,
+         :user_name  => imap.user,
+         :password   => imap.password,
+         :enable_ssl => imap.ssl_enabled || false,
+         :port       => imap.port
+      }
+      
+      self.delivery_settings = {
+         :address              => smtp.address,
+         :user_name            => smtp.user,
+         :password             => smtp.password,
+         :authentication       => :plain,
+         :enable_starttls_auto => smtp.starttls_enabled || false,
+         :port                 => smtp.port
+      }
+    end
+
+    # ---
+
+    # `Newman::Mailer#messages` is used to retrieve all messages currently in the inbox
+    # and then delete them from the server. This method returns an array of
+    # `Mail::Message` objects if any messages were found, and returns
+    # an empty array otherwise.
+
+    def messages
+      Mail::IMAP.new(retriever_settings).all(:delete_after_find => true)
+    end
+
+    # ---
+    
+    # `Newman::Mailer#new_message` is used to construct a new `Mail::Message` object,
+    # with the delivery settings that were set up at initialization time. 
+    # This method passes all its arguments on to `Mail.new`, so be sure 
+    # to refer to the [mail gem's documentation](http://github.com/mikel/mail)
+    # for details.
+    #
+    def new_message(*a, &b)
+      msg = Mail.new(*a, &b)
+      msg.delivery_method(:smtp, delivery_settings)
+
+      msg
     end
 
-    attr_accessor :settings
+    # ---
+    
+    # `Newman::Mailer#deliver_message` is used to construct and immediately deliver a
+    # message using the delivery settings that were set up at initialization
+    # time.
+
+    def deliver_message(*a, &b)
+      new_message(*a, &b).deliver
+    end
+
+    # ---
+
+    # **NOTE: Methods below this point in the file are implementation 
+    # details, and should not be depended upon**
+
+    private
+
+    # ---
+
+    # These accessors have been made private to reflect the fact that
+    # `Newman::Mailer` objects are meant to be treated as immutable constructs
+    # once they are created.
+
+    attr_accessor :retriever_settings, :delivery_settings
   end
 end