newman 0.2.1 → 0.3.0

data/CHANGELOG.md

@@ -1,9 +1,40 @@
+### 0.3.0 (2012-03-08)
+
+**Improvements:**
+
+- Added documentation of all settings that can be modified via Newman configuration files.
+
+- Added `Newman::Server#simple!`, which combines some of the flexibility of
+  manually building a server object with sensible defaults. This method is
+  useful for building simple tick-based servers, or for tweaking small details
+  such as which logger you want to use.
+
+- Allow a locals hash to be passed to tilt via `Newman::Controller#template`,
+  and added some integration tests for template support.
+
+**Behavior Changes:**
+
+- Caching of logger object is less aggressive now, allowing 
+  `Newman::Server#logger=` to be called at any time to change the 
+  logger object used by the server.
+
+- `Newman::Server.new` no longer accepts a custom logger argument. 
+   Use `Newman::Server#logger=` instead.
+
+- Locked explicitly to mail v2.3.0, because we're being bit by an upstream
+  bug. We will try to lock more optimistically in a future release of
+  Newman.
+
+[Diff of all changes since 0.2.1](https://github.com/mendicant-university/newman/compare/v0.2.1...v0.3.0#diff-43)
+
 ### 0.2.1 (2012-02-11)
 
 - Fixed a bug with `Newman::Application#match`. It now normalizes keys to 
   strings for easy use with `Newman::Application#compile_regex`, which
   fixes our substitution logic in patterns.
 
+[Diff of all changes since 0.2.0](https://github.com/mendicant-university/newman/compare/v0.2.0...v0.2.1#diff-43)
+
 ### 0.2.0 (2012-02-08)
 
 - Internals mostly rewritten, changes too numerous to outline meaningfully. 
@@ -25,6 +56,8 @@
 - Add a generic callback method to Newman::Application which allows for arbitrary
   callbacks to be run based on filters against the Mail::Message object.
 
+[Diff of all changes since 0.1.1](https://github.com/mendicant-university/newman/compare/v0.1.1...v0.2.0#diff-43)
+
 ### 0.1.1 (2012-02-03)
 
 - First official release.

data/README.md

@@ -1,4 +1,4 @@
-![Newman](http://i.imgur.com/92bZB.jpg)
+![Newman](http://i.imgur.com/GCqaT.png)
 
 Newman is a microframework which aims to do for email-based 
 applications what Rack and Sinatra have done for web programming. **While our
@@ -45,6 +45,9 @@ simple examples in this repository.
 
 Check out [Newman's Rocco-based API documentation](http://mendicant-university.github.com/newman/lib/newman.html).
 
+We update this documentation on each gem release of newman, but to generate this documentation yourself, 
+you'll need to install the rocco gem.
+
 ### For general discussion, questions, and ideas about Newman:
 
 Find seacreature or ericgj in the #newman channel on Freenode or send an email to newman@librelist.org

data/examples/libre_list_clone.rb

@@ -1,8 +1,13 @@
-# This is a cheap and possibly buggy clone of librelist.org's automatic
-# mailing list creation
-
 require_relative "example_helper"
 
+# This is a cheap and possibly buggy clone of librelist.org's automatic
+# mailing list creation
+#
+# Settings:
+#
+# - `application.librelist_db`<br>
+#     path to mailing list pstore file, relative to application root
+#
 module Newman
   module Examples
     LibreList = Newman::Application.new do

data/examples/live_test.rb

@@ -1,11 +1,9 @@
 require_relative "ping_pong"
 
-
-settings = Newman::Settings.from_file("config/environment.rb")
-mailer = Newman::Mailer.new(settings)
-
-server = Newman::Server.new(settings, mailer)
-server.apps << Newman::Examples::PingPong
+server = Newman::Server.simple!(Newman::Examples::PingPong,
+                               "config/environment.rb")
+mailer   = server.mailer
+settings = server.settings
 
 mailer.deliver_message(:to   => settings.application.ping_email,
                        :from => settings.service.default_sender)

data/examples/simple_mailing_list.rb

@@ -1,5 +1,12 @@
 require_relative "example_helper"
 
+# The simplest possible mailing list app
+#
+# Settings:
+#
+# - `application.simplelist_db`<br>
+#     path to mailing list pstore file, relative to application root
+#
 module Newman
   module Examples
 

data/examples/views/test/_echo_body.erb

@@ -0,0 +1,3 @@
+The body of the request follows:
+
+<%= request.decoded %>

data/examples/views/test/_echo_date.erb

@@ -0,0 +1 @@
+It was sent <%= request.date %>.

data/examples/views/test/_echo_list.erb

@@ -0,0 +1 @@
+The list it was routed to was <%= params[:list_id] %>.

data/examples/views/test/_echo_sender.erb

@@ -0,0 +1 @@
+The sender of this email was <%= sender %>.

data/examples/views/test/echo.erb

@@ -0,0 +1,6 @@
+The sender of this email was <%= sender %>.
+It was sent <%= request.date %>.
+The list it was routed to was <%= params[:list_id] %>.
+The body of the request follows:
+
+<%= request.decoded %>

data/examples/views/test/echo_with_partials.erb

@@ -0,0 +1,4 @@
+<%= template('test/_echo_sender') %>
+<%= template('test/_echo_date') %>
+<%= template('test/_echo_list') %>
+<%= template('test/_echo_body') %>

data/examples/views/test/moneyball.erb

@@ -0,0 +1,3 @@
+Pick 4: <%= pick_4.map(&:to_s).join("") %>
+
+Your magic code is: <%= magic_code %>

data/lib/newman/application.rb

@@ -226,16 +226,13 @@ module Newman
     # 2) If the selection of `matched_callbacks` is empty, it executes the default
     # callback in the context of a controller object. Otherwise, it runs each 
     # callback in sequence, in the context of a controller object.
-    #
-    # This method may have some weird side effects because it relies on
-    # awkward state mutations that could be either done in a better way or 
-    # replaced with a mostly stateless approach. We will look at fixing 
-    # this in a future Newman release.
 
     def trigger_callbacks(controller)
+      match_data = {}
+
       matched_callbacks = callbacks.select do |e| 
         filter = e[:filter]
-        e[:match_data] = filter.call(controller)
+        match_data[e] = filter.call(controller)
       end
 
       if matched_callbacks.empty?
@@ -243,7 +240,7 @@ module Newman
       else
         matched_callbacks.each do |e|
           action = e[:action]
-          controller.params = e[:match_data] || {}
+          controller.params = match_data[e]
           controller.instance_exec(&action)
         end
       end

data/lib/newman/controller.rb

@@ -54,16 +54,18 @@ module Newman
     # ---
     
     # `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
+    # 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)
+    # `settings.service.templates_dir`.  If a `locals` hash is provided, these
+    # local variables will be made available in templates.
+    #
+    # **NOTE: This is feature is one we haven't adequately used in Newman,
+    # if you have trouble with it, please let us know via our [issue
+    # tracker](http://github.com/mendicant-university/newman/issues).**
+    #
+    def template(name,locals={})
       Tilt.new(Dir.glob("#{settings.service.templates_dir}/#{name}.*").first)
-          .render(self)
+          .render(self,locals)
     end
 
     # --- 

data/lib/newman/server.rb

@@ -2,34 +2,34 @@
 # to applications as a request, and then delivers a response email after the
 # applications have modified it.
 #
-# A `Newman::Server` object can be used in three distinct ways:
+# A `Newman::Server` object can be used in four distinct ways:
 #
 # 1) Instantiated via `Newman::Server.test_mode` and then run tick by tick
 # in integration tests.
 # 
 # 2) Instantiated via `Newman::Server.simple` which immediately executes
 # an infinite polling loop.
-# 
-# 3) Instantiated explicitly and manually configured, for maximum control.
+#
+# 3) Instantiated via `Newman::Server.simple!`, and then run manually (either
+# in a loop or by tick), using the same defaults used by `Newman::Server.simple`
+#
+# 4) Instantiated explicitly and manually configured, for maximum control.
 #
 # All of these different workflows are supported, but if you are simply looking
 # to build applications with `Newman`, you are most likely going to end up using
-# `Newman::Server.simple` because it takes care of most of the setup work for
-# you and is the easiest way to run a single Newman application.
+# either `simple()` or `simple!()` because they care of most of the setup work 
+# for you.
 #
 # `Newman::Server` is part of Newman's **external interface**.
 
 module Newman  
   class Server
     # ---
-    
-    # `Newman::Server.simple` automatically generates a `Newman::Mailer` object
-    # and `Newman::Settings` object from the privded `settings_file`. These
+     
+    # `Newman::Server.simple!` automatically generates a `Newman::Mailer` object
+    # and `Newman::Settings` object from the provided `settings_file`. These
     # objects are then passed on to `Newman::Server.new` and a server instance
-    # is created. The server object is set up to run the specified `app`, with
-    # request and response logging support enabled. Calling this method puts
-    # the server in an infinite polling loop, because its final action is to
-    # call `Newman::Server.run`.
+    # is created. 
     #
     # The following example demonstrates how to use this method:
     #
@@ -42,18 +42,29 @@ module Newman
     #         respond(:subject => "You missed the ball!")
     #       end
     #     end 
-    #
-    #     Newman::Server.simple(ping_pong, "config/environment.rb")
-    #
-    # Given a properly configured settings file, this code will launch a polling
-    # server and run the simple `ping_pong` application.
-
-    def self.simple(app, settings_file)
+    #     
+    #     s = Newman::Server.simple!(ping_pong, "config/environment.rb")
+    #     # call s.tick or s.run at some later point.
+    #
+    # Given a proper configuration file, this will make it possible to easily
+    # get your applications up and running with simple request and response
+    # logging enabled.
+    def self.simple!(app, settings_file)
       settings     = Settings.from_file(settings_file)
       mailer       = Mailer.new(settings)
       server       = new(settings, mailer)
-      server.apps = [RequestLogger, app, ResponseLogger]
+      server.apps  = [RequestLogger, app, ResponseLogger]
 
+      server
+    end
+    
+    # ---
+     
+    # `Newman::Server#simple` is the same as `Newman::Server#simple!`, but
+    # automatically starts an infinite polling loop.
+
+    def self.simple(app, settings_file)
+      server = simple!(app, settings_file)
       server.run
     end
 
@@ -64,7 +75,7 @@ module Newman
     # objects are then passed on to `Newman::Server.new` and a server instance
     # which is preconfigured for use in integration testing is returned.
     #
-    # Using the application from the `Newman::Server.simple` documentation
+    # Using the application from the `Newman::Server.simple!` documentation
     # above, it'd be possible to write a simple integration test using this
     # method in the following way:
     #
@@ -96,19 +107,17 @@ module Newman
     # ---
     
     # To initialize a `Newman::Server` object, a settings object and mailer object must
-    # be provided, and a logger object may also be provided. If a logger object
-    # is not provided, `Newman::Server#default_logger` is called to create one.
-    #
+    # be provided.
+    # 
     # Instantiating a server object directly can be useful for building live
     # integration tests, or for building cron jobs which process email
     # periodically rather than in a busy-wait loop. See one of Newman's [live
     # tests](https://github.com/mendicant-university/newman/blob/master/examples/live_test.rb)
     # for an example of how this approach works.
 
-    def initialize(settings, mailer, logger=nil)
+    def initialize(settings, mailer)
       self.settings = settings
       self.mailer   = mailer
-      self.logger   = logger || default_logger
       self.apps     = []
     end
 
@@ -120,7 +129,17 @@ module Newman
     # as an implementation detail; all important data will get passed down
     # into your apps on each `tick`.
 
-    attr_accessor :settings, :mailer, :apps,  :logger
+    attr_accessor :settings, :mailer, :apps
+    attr_writer   :logger
+
+    # ---
+
+    # Returns the logger object that was set via `Newman::Server#logger=`, 
+    # or delegates to `default_logger` if no custom logger was provided.
+    #
+    def logger
+      @logger || default_logger
+    end
 
     # ---
 
@@ -160,6 +179,12 @@ module Newman
     # exception is re-raised, typically taking the server down with it. This
     # setting is off by default.
     #
+    # 2b) If there are any server errors (such as an error retrieving messages
+    # via IMAP), those  errors are logged and re-raised, taking the server 
+    # down. Currently, you should use a process watcher to restart
+    # Newman to protect against such failures, but be careful about restarting
+    # without knowing what went wrong!
+    #
     # 3) Assuming an exception is not encountered, the response is delivered.
 
     def tick         
@@ -187,6 +212,9 @@ module Newman
 
         response.deliver
       end
+    rescue Exception => e
+      logger.fatal("Caught exception: #{e}\n\n#{e.backtrace.join("\n")}")
+      raise
     end
 
     # ---

data/lib/newman/settings.rb

@@ -13,6 +13,38 @@
 # `Newman::Settings`is part of Newman's **internal API**, but 
 # the setting file format and various settings that Newman depends
 # on should be considered part of the **external API**.
+#
+# The following settings are currently supported:
+#
+#     imap.address
+#     imap.user
+#     imap.password
+#     imap.ssl_enabled (default false)
+#     imap.port
+#
+#     smtp.address
+#     smtp.user
+#     smtp.password
+#     smtp.starttls_enabled  (default false)
+#     smtp.port
+#
+#     service.debug_mode
+#       log error backtraces and full request and response emails
+#
+#     service.default_sender
+#       default FROM field for responses
+#     
+#     service.domain
+#       mail domain, used by filters and in building email addresses
+#     
+#     service.polling_interval
+#       idle seconds between server ticks 
+#     
+#     service.raise_exceptions
+#       raise exceptions during server ticks, killing the server
+#       
+#     service.templates_dir
+#       directory of template files, relative to application root
 
 module Newman 
   class Settings

data/lib/newman/version.rb

@@ -4,8 +4,8 @@
 module Newman
   module Version
     MAJOR  = 0
-    MINOR  = 2
-    TINY   = 1
+    MINOR  = 3
+    TINY   = 0
     STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
   end
 end

data/test/helper.rb

@@ -7,12 +7,17 @@ require_relative "../lib/newman"
 module Newman
   TEST_DIR   =  File.dirname(__FILE__) 
 
-  def self.new_test_server(app)
+  def self.new_test_server(apps)
+    apps = Array(apps)  
     server = Newman::Server.test_mode(TEST_DIR + "/settings.rb")
-    server.apps << app
+    apps.each {|app| server.apps << app }
     server.settings.application.simplelist_db = TEST_DIR + "/test.store"
     server.settings.service.templates_dir = TEST_DIR + "/../examples/views"
 
+    logger = ::Logger.new( TEST_DIR + "/log/test.log" )
+    logger.level = ::Logger::DEBUG
+    server.logger = logger
+    
     server
   end
 end

data/test/integration/template_test.rb

@@ -0,0 +1,93 @@
+require 'digest/md5'
+require_relative "../helper"
+
+describe "template" do
+  let(:app) do
+    Newman::Application.new do
+      match :list_id, /[^\.]+/
+      
+      to :tag, "{list_id}.echo" do
+        respond(:subject => "RE: #{request.subject}",
+                :body    => template('test/echo')
+               )
+      end
+      
+      to :tag, "{list_id}.moneyball" do
+        pick_4 = [ rand(9), rand(9), rand(9), rand(9) ]
+        magic_code = Digest::MD5.hexdigest( 
+                      "#{sender}#{params[:list_id]}" 
+                     )
+        respond(:subject => "Today's Jackpots",
+                :body    => template('test/moneyball', :pick_4 => pick_4,
+                                                       :magic_code => magic_code)
+               )
+      end
+
+      to :tag, "{list_id}.partials" do
+        respond(:subject => "RE: #{request.subject}",
+                :body    => template('test/echo_with_partials')
+               )
+      end
+      
+    end
+  end
+
+  let(:server) { 
+    Newman.new_test_server([Newman::RequestLogger, app, Newman::ResponseLogger]) 
+  }
+  
+  let(:mailer) { server.mailer }
+
+  # -----
+  
+  it "renders simple template without passed locals hash" do
+    mailer.deliver_message(:from => "me@example.com",
+                           :to => "test+fizbiz.echo@test.com",
+                           :body => "Could you call me about fizbiz please?")
+    server.tick
+
+    msgs = mailer.messages
+    assert_equal 1, msgs.count
+    
+    actual = msgs.first.decoded
+    
+    # assert that list_id, sender, and body is rendered in view
+    assert_match /\bme\@example\.com\b/, actual
+    assert_match /\bfizbiz\b/, actual
+    assert_match /Could you call me about fizbiz please\?/, actual
+  end
+  
+  it "renders template with passed locals hash" do
+    mailer.deliver_message(:from => "me@example.com",
+                           :to => "test+fizbiz.moneyball@test.com")
+    server.tick
+
+    msgs = mailer.messages
+    assert_equal 1, msgs.count
+    
+    actual = msgs.first.decoded
+    expected_code = Digest::MD5.hexdigest("me@example.comfizbiz")
+    
+    # assert that pick_4 and magic_code locals are rendered in view
+    assert_match(/Pick 4\: \d\d\d\d/, actual)
+    assert_match(/Your magic code is\: #{expected_code}/, actual)
+  end
+  
+  it "renders template with partials" do
+    mailer.deliver_message(:from => "me@example.com",
+                           :to => "test+fizbiz.partials@test.com",
+                           :body => "Could you call me about fizbiz please?")
+    server.tick
+
+    msgs = mailer.messages
+    assert_equal 1, msgs.count
+    
+    actual = msgs.first.decoded
+    
+    # assert that list_id, sender, and body is rendered in view
+    assert_match /\bme\@example\.com\b/, actual
+    assert_match /\bfizbiz\b/, actual
+    assert_match /Could you call me about fizbiz please\?/, actual
+  end
+  
+end

data/test/suite.rb

@@ -4,4 +4,5 @@ SimpleCov.start
 require_relative "integration/acid_tests"
 require_relative "integration/skip_response_test"
 require_relative "integration/subject_filter_test"
+require_relative "integration/template_test"
 require_relative "integration/to_filter_test"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: newman
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,22 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-12 00:00:00.000000000 Z
+date: 2012-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mail
-  requirement: &2153405740 !ruby/object:Gem::Requirement
+  requirement: &2164929320 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - =
       - !ruby/object:Gem::Version
         version: 2.3.0
   type: :runtime
   prerelease: false
-  version_requirements: *2153405740
+  version_requirements: *2164929320
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &2153405240 !ruby/object:Gem::Requirement
+  requirement: &2164924480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.3.3
   type: :runtime
   prerelease: false
-  version_requirements: *2153405240
+  version_requirements: *2164924480
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &2153404780 !ruby/object:Gem::Requirement
+  requirement: &2164923220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 2.11.1
   type: :development
   prerelease: false
-  version_requirements: *2153404780
+  version_requirements: *2164923220
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2153404380 !ruby/object:Gem::Requirement
+  requirement: &2164956100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,21 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153404380
+  version_requirements: *2164956100
 - !ruby/object:Gem::Dependency
   name: purdytest
-  requirement: &2153403880 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: *2153403880
-- !ruby/object:Gem::Dependency
-  name: rocco
-  requirement: &2153403360 !ruby/object:Gem::Requirement
+  requirement: &2164954780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153403360
+  version_requirements: *2164954780
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2153402880 !ruby/object:Gem::Requirement
+  requirement: &2164953080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +76,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153402880
+  version_requirements: *2164953080
 description: A microframework for mail-centric applications
 email:
 - gregory.t.brown@gmail.com
@@ -121,12 +110,20 @@ files:
 - examples/views/non-subscriber-error.erb
 - examples/views/subscribe-error.erb
 - examples/views/subscribe-success.erb
+- examples/views/test/_echo_body.erb
+- examples/views/test/_echo_date.erb
+- examples/views/test/_echo_list.erb
+- examples/views/test/_echo_sender.erb
+- examples/views/test/echo.erb
+- examples/views/test/echo_with_partials.erb
+- examples/views/test/moneyball.erb
 - examples/views/unsubscribe-error.erb
 - examples/views/unsubscribe-success.erb
 - test/helper.rb
 - test/integration/acid_tests.rb
 - test/integration/skip_response_test.rb
 - test/integration/subject_filter_test.rb
+- test/integration/template_test.rb
 - test/integration/to_filter_test.rb
 - test/settings.rb
 - test/suite.rb