newman 0.1.1 → 0.2.0

data/lib/newman/mailing_list.rb

@@ -1,29 +1,112 @@
+# `Newman::MailingList` implements a simple mechanism for storing lists of email
+# addresses keyed by a mailing list name. 
+#
+# This object is meant to be used in conjunction with a
+# `Newman::Store` object which is `PStore` backed, but would fairly easily map to
+# arbitrary data stores via adapter objects. 
+#
+# `Newman::MailingList` is part of Newman's **external interface**.
+
 module Newman
   class MailingList
+
+    # ---
+     
+    # To initialize a `Newman::MailingList` object, a list name and a store object must
+    # be provided, i.e:
+    #
+    #     store        = Newman::Store.new('simple.store')
+    #     mailing_list = Newman::MailingList.new("simple_list", store)
+
     def initialize(name, store)
       self.name  = name
       self.store = store
     end
 
+    # ---
+    
+    # `Newman::MailingList#subscribe` is used to add subscribers to 
+    # the mailing list, i.e.
+    #
+    #     mailing_list.subscribe('gregory.t.brown@gmail.com')
+    #
+    # If the provided email address is for a new subscriber, a new record gets
+    # created for that subscriber, adding them to the list. Otherwise, this 
+    # method does not modify the mailing list.
+    # 
+    # Returns true if list was modified, returns false otherwise.
+
     def subscribe(email)
+      return false if subscriber?(email)
+
       store[name].create(email)
+
+      true
     end
 
+    # ---
+    
+    # `Newman::MailingList#unsubscribe` is used to remove subscribers from 
+    # the mailing list, i.e.
+    #
+    #     mailing_list.unsubscribe('gregory.t.brown@gmail.com')
+    #
+    # If the provided email address is for an existing subscriber, the record
+    # for that subscriber is destroyed, removing them from the list. 
+    # Otherwise, this method does not modify the mailing list.
+    #
+    # Returns true if list was modified, returns false otherwise.
+
     def unsubscribe(email)
+      return false unless subscriber?(email)
+
       record = store[name].find { |e| e.contents == email } 
       store[name].destroy(record.id)
+
+      true
     end
 
+
+    # ---
+
+    # `Newman::MailingList#subscriber?` is used to check if a given email address 
+    # is on the list, i.e.
+    #
+    #     mailing_list.subscriber?('gregory.t.brown@gmail.com')
+    #
+    # Returns true if a record is found which matches the given email address,
+    # returns false otherwise.
+
     def subscriber?(email)
       store[name].any? { |r| r.contents == email }
     end
 
+    # ---
+
+    # `Newman::MailingList#subscribers` is used to access all email addresses for 
+    # the mailing list's subscribers, i.e:
+    #
+    #     members = mailing_list.subscribers
+    #
+    # Returns an array of email addresses.
+
     def subscribers
       store[name].map { |r| r.contents } 
     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::MailingList` objects are meant to point to a single
+    # named list within a single data store once they are created.
+    
     attr_accessor :name, :store
   end
 end

data/lib/newman/recorder.rb

@@ -0,0 +1,132 @@
+# `Newman::Recorder` provides a simple mechanism for storing non-relational
+# records within a `Newman::Store` with autoincrementing identifiers. It
+# supports basic CRUD operations, and also acts as an `Enumerable` object.
+#
+# For an example of how to make use of `Newman::Recorder` to implement arbitrary
+# persistent models, be sure to check out the implementation of the
+# `Newman::MailingList` object.
+#
+# `Newman::Recorder` is part of Newman's **external interface**.
+
+module Newman
+  Record = Struct.new(:column, :id, :contents)
+
+  class Recorder
+    include Enumerable
+
+    # ---
+    
+    # To initialize a `Newman::Recorder` object, a `column` key 
+    # and `store` object must be provided, i.e.
+    #
+    #     store     = Newman::Store.new("sample.store")
+    #     recorder  = Newman::Recorder.new(:subscribers, store)
+    #
+    # However, in most cases you should not instantiate a
+    # `Newman::Recorder` directly, and instead should make use of
+    # `Newman::Store#[]` which is syntactic sugar for the same operation.
+    #
+    # The first time a particular `column` key is referenced, two mapping
+    # is created for the column in the underlying data store: one which
+    # keeps track of the autoincrementing ids, and one that keeps track
+    # of the data stored within the column. It's fine to treat these
+    # mappings as implementation details, but we treat them as part of Newman's
+    # external interface because backwards-incompatible changes to them will
+    # result in possible data store corruption.
+
+    def initialize(column, store)
+      self.column = column
+      self.store  = store
+
+      store.write do |data|
+        data[:identifiers][column] ||= 0
+        data[:columns][column]     ||= {}
+      end
+    end
+
+    # ---
+    
+    # `Newman::Recorder#each` iterates over all records stored in the column,
+    # yielding a `Newman::Record` object for each one. Because `Enumerable` is
+    # mixed into `Newman::Recorder`, all enumerable methods that get called on a
+    # recorder object end up making calls to this method.
+    def each
+      store.read do |data|
+        data[:columns][column].each do |id, contents| 
+          yield(Record.new(column, id, contents)) 
+        end
+      end
+    end
+
+    # ---
+     
+    # `Newman::Recorder#create` store an arbitrary Ruby object in the data
+    # store and returns a `Newman::Record` object which has fields for the
+    # `column` key, record `id`, and record `contents`. This method
+    # automatically generates new ids, starting with `id=1` for the 
+    # first record and then incrementing sequentially.
+
+    def create(contents)
+      store.write do |data| 
+        id = (data[:identifiers][column] += 1)
+        
+        data[:columns][column][id] = contents 
+
+        Record.new(column, id, contents)
+      end
+    end
+
+    # ---
+     
+    # `Newman::Recorder#read` looks up a record by `id` and returns a
+    # `Newman::Record` object.
+
+    def read(id)
+      store.read do |data|
+        Record.new(column, id, data[:columns][column][id])
+      end
+    end
+
+    # ---
+
+    # `Newman::Recorder#update` looks up a record by `id` and yields its
+    # contents. The record contents are then replaced with the 
+    # return value of the provided block.
+
+    def update(id)
+      store.write do |data|
+        data[:columns][column][id] = yield(data[:columns][column][id])
+
+        Record.new(column, id, data[:columns][column][id])
+      end
+    end
+
+    # ---
+
+    # `Newman::Recorder#destroy` looks up a record by `id` and then removes it
+    # from the data store. This method returns `true` whether or not a record
+    # was actually destroyed, which is a somewhat useless behavior and may
+    # need to be fixed in a future version of Newman. Patches welcome!
+
+    def destroy(id)
+      store.write do |data|
+        data[:columns][column].delete(id)
+      end
+
+      true
+    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 fac that
+    # `Newman::Recorder` objects are meant to point to a single column within a
+    # single data store once created.
+    attr_accessor :column, :store
+  end
+end

data/lib/newman/request_logger.rb

@@ -0,0 +1,41 @@
+# `Newman::RequestLogger` implements rudimentary request logging functionality, 
+# which is enabled by default when `Newman::Server.simple` is used to execute 
+# your applications. 
+#
+# 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::RequestLogger` is part of Newman's **internal interface**.
+
+module Newman
+  RequestLogger = Object.new
+
+  # ---
+
+  # `Newman::RequestLogger` is implemented as a singleton object and is 
+  # completely stateless in nature. It can be added directly as an app to 
+  # any `Newman::Server` instance. The `Newman::Server.simple` helper method 
+  # automatically places a `Newman::RequestLogger` at the beginning of the call chain, 
+  # but  it can be inserted at any point and will output the request email 
+  # object at that point in the call chain.
+
+  class << RequestLogger
+    include EmailLogger
+
+    # ---
+
+    # `Newman::RequestLogger#call` simply delegates to
+    # `Newman::EmailLogger#log_email`, passing it a logger instance, the 
+    # `"REQUEST"` prefix for the log line, and an instance
+    # of an email object. See `Newman::Server.tick` and `Newman::EmailLogger#log_email`
+    # for details.
+
+    def call(params)
+      log_email(params[:logger], "REQUEST", params[:request])
+    end
+  end
+end

data/lib/newman/response_logger.rb

@@ -0,0 +1,41 @@
+# `Newman::ResponseLogger` supports rudimentary response logging functionality, which is
+# enabled by default when `Newman::Server.simple` is used to execute your
+# applications. 
+#
+# 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::ResponseLogger` is part of Newman's **internal interface**.
+
+module Newman  
+  ResponseLogger = Object.new
+
+  # ---
+
+  # `Newman::ResponseLogger` is implemented as a singleton object and is 
+  # completely stateless in nature. It can be added directly as an app to 
+  # any `Newman::Server` instance. The `Newman::Server.simple` helper method 
+  # automatically places a `ResponseLogger` at the end of the call chain, but 
+  # it can be inserted at any point and will output the response email object
+  # at that point in the call chain.
+
+  class << ResponseLogger
+    include EmailLogger
+
+    # ---
+
+    # `Newman::ResponseLogger#call` simply delegates to 
+    # `EmailLogger#log_email`, passing it a logger instance, the 
+    # `"RESPONSE"` prefix for the log line, and an instance of an email 
+    # object. See `Newman::Server.tick` and `Newman::EmailLogger#log_email`
+    # for details.
+
+    def call(params)
+      log_email(params[:logger], "RESPONSE", params[:response])
+    end
+  end
+end

data/lib/newman/server.rb

@@ -1,45 +1,219 @@
-module Newman
-  Server = Object.new  
-  
-  class << Server
-    attr_accessor :settings, :mailer
+# `Newman::Server` takes incoming mesages from a mailer object and passes them
+# 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:
+#
+# 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.
+#
+# 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.
+#
+# `Newman::Server` is part of Newman's **external interface**.
 
-    def test_mode(settings_file)
-      self.settings = Newman::Settings.from_file(settings_file)
-      self.mailer   = Newman::TestMailer
+module Newman  
+  class Server
+    # ---
+    
+    # `Newman::Server.simple` automatically generates a `Newman::Mailer` object
+    # and `Newman::Settings` object from the privded `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`.
+    #
+    # The following example demonstrates how to use this method:
+    #
+    #     ping_pong = Newman::Application.new do
+    #       subject(:match, "ping") do
+    #         respond(:subject => "pong")
+    #       end
+    #
+    #       default do
+    #         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.
 
-      mailer.configure(settings)
+    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.run
+    end
+
+    # ---
+     
+    # `Newman::Server.test_mode` automatically generates a `Newman::TestMailer` object
+    # and `Newman::Settings` object from the provided `settings_file`. These
+    # 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
+    # above, it'd be possible to write a simple integration test using this
+    # method in the following way:
+    #
+    #     server = Newman::Server.test_mode("config/environment.rb")
+    #     server.apps << ping_pong
+    #
+    #     mailer = server.mailer
+    #     mailer.deliver_message(:to      => "test@test.com",
+    #                            :subject => "ping)
+    #
+    #     server.tick
+    #
+    #     mailer.messages.first.subject.must_equal("pong")
+    #
+    # It's worth mentioning that although `Newman::Server.test_mode` is part of
+    # Newman's external interface, the `Newman::TestMailer` object is considered part
+    # of its internals. This is due to some ugly issues with global state and
+    # the overall brittleness of the current implementation. Expect a bit of
+    # weirdness if you plan to use this feature, at least until we improve upon
+    # it.
+
+    def self.test_mode(settings_file)
+      settings = Settings.from_file(settings_file)
+      mailer   = TestMailer.new(settings)
+
+      new(settings, mailer)
     end
 
-    def simple(apps, settings_file)
-      self.settings = Newman::Settings.from_file(settings_file)
-      self.mailer   = Newman::Mailer
-      
-      mailer.configure(settings)
+    # ---
+    
+    # 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.
+    #
+    # 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.
 
-      run(apps)
+    def initialize(settings, mailer, logger=nil)
+      self.settings = settings
+      self.mailer   = mailer
+      self.logger   = logger || default_logger
+      self.apps     = []
     end
 
-    def run(apps)
+    # ---
+    
+    # These accessors are mostly meant for use with server objects under test
+    # mode, or server objects that have been explicitly instantiated. If you are
+    # using `Newman::Server.simple` to run your apps, it's safe to treat these
+    # as an implementation detail; all important data will get passed down
+    # into your apps on each `tick`.
+
+    attr_accessor :settings, :mailer, :apps,  :logger
+
+    # ---
+
+    # `Newman::Server.run` kicks off a busy wait loop, alternating between
+    # calling `Newman::Server.tick` and sleeping for the amount of time
+    # specified by `settings.service.polling_interval`. We originally planned to
+    # use an EventMachine periodic timer here to potentially make running
+    # several servers within a single process easier, but had trouble coming up
+    # with a use case that made the extra dependency worth it.
+
+    def run
       loop do
-        tick(apps)
+        tick
         sleep settings.service.polling_interval
       end
     end
 
-    def tick(apps)           
-      mailer.messages.each do |request|
+    # ---
+    
+    # `Newman::Server.tick` runs the following sequence for each incoming
+    # request. 
+    #
+    # 1) A response is generated with the TO field set to the FROM field of the
+    # request, and the FROM field set to `settings.service.default_sender`.
+    # Applications can change these values later, but these are sensible
+    # defaults that work for most common needs.
+    #
+    # 2) The list of `apps` is iterated over sequentially, and each
+    # application's `call` method is invoked with a parameters hash which
+    # include the `request` email, the `response` email, the `settings` object
+    # being used by the server, and the `logger` object being used by the
+    # server.
+    #
+    # 2a) If any application raises an exception, that exception is caught and
+    # the processing of the current request is halted. Details about the failure
+    # are logged and if `settings.service.raise_exceptions` is enabled, the
+    # exception is re-raised, typically taking the server down with it. This
+    # setting is off by default.
+    #
+    # 3) Assuming an exception is not encountered, the response is delivered.
+
+    def tick         
+      mailer.messages.each do |request|        
         response = mailer.new_message(:to   => request.from, 
                                       :from => settings.service.default_sender)
+        
+        begin
+          apps.each do |app|
+            app.call(:request  => request, 
+                     :response => response, 
+                     :settings => settings,
+                     :logger   => logger)
+          end
+        rescue StandardError => e
+          logger.info("FAIL") { e.to_s }
+          logger.debug("FAIL") { "#{e.inspect}\n"+e.backtrace.join("\n  ") }
 
-        Array(apps).each do |a| 
-          a.call(:request  => request, 
-                 :response => response, 
-                 :settings => settings)
+          if settings.service.raise_exceptions
+            raise
+          else
+            next
+          end
         end
 
         response.deliver
       end
     end
+
+    # ---
+
+    # **NOTE: Methods below this point in the file are implementation 
+    # details, and should not be depended upon**
+
+    private
+
+    # ---
+    
+    # `Newman::Server#default_logger` generates a logger object using 
+    # Ruby's standard library. This object outputs to `STDERR`, and
+    # runs at info level by default, but will run at debug level if 
+    # either `settings.service.debug_mode` or the Ruby `$DEBUG`
+    # variable is set.
+
+    def default_logger
+      self.logger = Logger.new(STDERR)
+
+      if settings.service.debug_mode || $DEBUG
+        logger.level = Logger::DEBUG
+      else
+        logger.level = Logger::INFO
+      end
+
+      logger
+    end
   end
 end