serf 0.4.1 → 0.5.0

data/README.md

@@ -65,12 +65,10 @@ Service Libraries
     hashes that define at least one attribute: 'kind'.
 2. Serialization of the messages SHOULD BE Json or MessagePack (I hate XML).
   a. `to_hash` is also included.
-3. Service Libraries SHOULD implement handler classes that include the
-  ::Serf::Handler helper module.
-4. Handler methods MUST receive a message as either as an options hash
+3. Handler methods MUST receive a message as either as an options hash
   (with symbolized keys) or an instance of a declared Message.
-5. Handler methods MUST return zero or more messages.
-6. Handler methods SHOULD handle catch their business logic exceptions and
+4. Handler methods MUST return zero or more messages.
+5. Handler methods SHOULD handle catch their business logic exceptions and
   return them as specialized messages that can be forwarded down error channels.
   Uncaught exceptions that are then caught by Serf are published as
   generic Serf::CaughtExceptionEvents, and are harder to deal with.
@@ -105,7 +103,7 @@ aware that:
 1. Message classes MUST implement `Message.parse(env={})` class method
   if said message class is to be used as the target object representation
   of a received message (from ENV hash).
-    a. Serf::Handler code makes this assumption when it finds an ENV
+    a. Serf code makes this assumption when it finds an ENV
     hash that is to be parsed into a message object.
 
 
@@ -115,15 +113,35 @@ Example
     # Require our libraries
     require 'active_model'
     require 'log4r'
-    require 'serf/handler'
-    require 'serf/message'
+    require 'json'
+
     require 'serf/builder'
+    require 'serf/message'
+    require 'serf/middleware/uuid_tagger'
 
     # create a simple logger for this example
-    logger = Log4r::Logger.new 'my_logger'
-    logger.outputters = Log4r::FileOutputter.new(
+    outputter = Log4r::FileOutputter.new(
       'fileOutputter',
       filename: 'log.txt')
+    ['top_level',
+      'serf',
+      'handler',
+      'results_channel',
+      'error_channel'].each do |name|
+      logger = Log4r::Logger.new name
+      logger.outputters = outputter
+    end
+
+    # Helper class for this example to receive result or error messages
+    # and pipe it into our logger.
+    class MyChannel
+      def initialize(logger)
+        @logger = logger
+      end
+      def publish(message)
+        @logger.info "#{message}"
+      end
+    end
 
     # my_lib/my_message.rb
     class MyMessage
@@ -135,92 +153,107 @@ Example
       validates_presence_of :data
 
       def initialize(options={})
-        @hi = options[:data] || 'some data here'
+        @data = options[:data]
+      end
+
+      # We define this for Serf::Message serialization.
+      def attributes
+        { 'data' => data }
       end
 
     end
 
     # my_lib/my_handler.rb
     class MyHandler
-      include Serf::Handler
-
-      # Declare handlers for a 'my_message' message kind with a Message class.
-      receives(
-        'my_message',
-        as: MyMessage,
-        with: :submit_my_message)
-
-      # This handler of 'other_message' doesn't need a Message class,
-      # and will just work off the ENV hash.
-      receives(
-        'other_message',
-        with: :submit_other_message)
 
       def initialize(options={})
         @logger = options[:logger]
       end
 
       def submit_my_message(message)
-        @logger.info "In Submit My Message: #{message.inspect.to_s}"
+        @logger.info "In Submit My Message: #{message.to_json}"
         # Validate message because we have implement my_message with it.
         unless message.valid?
           raise ArgumentError, message.errors.full_messages.join(',')
         end
         # Do work Here...
-        # And return other messages as results of work, or nil for nothing.
-        return nil
+        # And return 0 or more messages as result. Nil is valid response.
+        return { kind: 'my_message_results' }
       end
 
       def submit_other_message(message={})
         # The message here is the ENV hash because we didn't declare
         # an :as option with `receives`.
-        @logger.info "In Submit Other Result: #{message.inspect.to_s}"
-        return nil
+        @logger.info "In Submit OtherMessage: #{message.inspect.to_s}"
+        return [
+          { kind: 'other_message_result1' },
+          { kind: 'other_message_result2' }
+        ]
       end
 
+      def raises_error(message={})
+        @logger.info 'In Raises Error, about to raise error'
+        raise 'My Handler Runtime Error'
+      end
+
+      def regexp_matched(message={})
+        @logger.info "RegExp Matched #{message.inspect}"
+        nil
+      end
     end
 
-    # my_lib/manifest.rb
-    MANIFEST = {
-      'my_message' => {
+    # my_lib/routes.rb
+    ROUTES = {
+      # Declare a matcher and a list of routes to endpoints.
+      'my_message' => [{
         # Declares which handler to use. This is the tableized
         # name of the class. It will be constantized by the serf code.
         handler: 'my_handler',
-        # Default is true to process in background.
-        async: true
-      },
-      'other_message' => {
+        action: :submit_my_message,
+
+        # Define a parser that will build up a message object.
+        # Default: nil, no parsing done.
+        # Or name of registered parser to use.
+        message_parser: 'my_parser',
+
+        # Default is process in foreground.
+        #background: false
+      }],
+      'other_message' => [{
+        handler: 'my_handler',
+        action: :submit_other_message,
+        background: true
+      }, {
+        handler: 'my_handler',
+        action: :raises_error,
+        background: true
+      }],
+      /^events\/.*$/ => [{
         handler: 'my_handler',
-        async: false
-      }
+        action: :regexp_matched,
+        background: true
+      }]
     }
 
-    # Helper class for this example to receive result or error messages
-    # and pipe it into our logger.
-    class MyChannel
-      def initialize(name, logger)
-        @name = name
-        @logger = logger
-      end
-      def publish(message)
-        @logger.info "#{@name} #{message}"
-        #@logger.info message
-      end
-    end
-
     # Create a new builder for this serf app.
     builder = Serf::Builder.new do
-      # Registers different service libary manifests.
-      register MANIFEST
+      # Include some middleware
+      use Serf::Middleware::UuidTagger
+
+      # Registers routes from different service libary manifests.
+      routes ROUTES
+
       # Can define arguments to pass to the 'my_handler' initialize method.
-      config(
-        'my_handler',
-        logger: logger)
+      handler 'my_handler', MyHandler.new(logger: ::Log4r::Logger['handler'])
+      message_parser 'my_parser', MyMessage
+
       # Create result and error channels for the handler result messages.
-      error_channel MyChannel.new('errorchannel: ', logger)
-      results_channel MyChannel.new('resultschannel: ', logger)
+      error_channel MyChannel.new(::Log4r::Logger['error_channel'])
+      results_channel MyChannel.new(::Log4r::Logger['results_channel'])
+
       # We pass in a logger to our Serf code: Serfer and Runners.
-      logger logger
+      logger ::Log4r::Logger['serf']
+
       # Optionally define a not found handler...
       # Defaults to raising an ArgumentError, 'Not Found'.
       #not_found lambda {|x| puts x}
@@ -228,21 +261,39 @@ Example
     app = builder.to_app
 
     # Start event machine loop.
+    logger = ::Log4r::Logger['top_level']
     EM.run do
       # On the next tick
       EM.next_tick do
         logger.info "Start Tick #{Thread.current.object_id}"
+
         # This will submit a 'my_message' message (as a hash) to the Serf App.
+        # NOTE: We should get an error message pushed to the error channel
+        #  because no 'data' field was put in my_message as required
+        #  And the Result should have a CaughtExceptionEvent.
         results = app.call('kind' => 'my_message')
-        # Because we declared the 'my_message' kind to be handled async, we
+        logger.info "In Tick, MyMessage Results: #{results.inspect}"
+
+        # Here is good result
+        results = app.call('kind' => 'my_message', 'data' => '1234')
+        logger.info "In Tick, MyMessage Results: #{results.inspect}"
+
+        # This will submit 'other_message' to be handled in foreground
+        # Because we declared the 'other_message' kind to be handled async, we
         # should get a MessageAcceptedEvent as the results.
-        logger.info "In Tick Results: #{results.inspect}"
+        results = app.call('kind' => 'other_message')
+        logger.info "In Tick, OtherMessage Results: #{results.inspect}"
+
+        # This will match a regexp
+        results = app.call('kind' => 'events/my_event')
+        logger.info "In Tick, Regexp Results: #{results.inspect}"
+
         begin
           # Here, we're going to submit a message that we don't handle.
           # By default, an exception will be raised.
           app.call('kind' => 'unhandled_message_kind')
         rescue => e
-          puts "Caught in Tick: #{e.inspect}"
+          logger.warn "Caught in Tick: #{e.inspect}"
         end
         logger.info "End Tick #{Thread.current.object_id}"
       end
@@ -251,7 +302,6 @@ Example
       end
     end
 
-
 Contributing to serf
 ====================
 

data/lib/serf/builder.rb

@@ -2,13 +2,14 @@ require 'serf/serfer'
 require 'serf/runners/direct_runner'
 require 'serf/runners/em_runner'
 require 'serf/util/null_object'
+require 'serf/util/route_set'
 
 module Serf
 
   ##
   # A Serf Builder that processes the SerfUp DSL to build a rack-like
   # app to route and process received messages. This builder is
-  # implemented with lots of code from Rack::Builder.
+  # implemented based on code from Rack::Builder.
   #
   #   builder = Serf::Builder.parse_file 'examples/config.su'
   #   builder.to_app
@@ -16,7 +17,7 @@ module Serf
   # or
   #
   #   builder = Serf::Builder.new do
-  #     ... A SerfUp Config block here. See the examples/config.su
+  #     ... A SerfUp Config block here.
   #   end
   #   builder.to_app
   #
@@ -30,17 +31,19 @@ module Serf
 
     def initialize(app=nil, &block)
       # Configuration about the routes and apps to run.
-      @manifest = {}
-      @config = {}
+      @use = []
+      @route_maps = []
+      @handlers = {}
+      @message_parsers = {}
       @not_found = app
 
-      # Implementing classes of our app
-      # NOTE: runner_class and async_runner_class are only used if actual
-      #   runner instances are omitted in the configuration.
-      @serfer_class = ::Serf::Serfer
-      @serfer_options = {}
-      @runner_class = ::Serf::Runners::DirectRunner
-      @async_runner_class = ::Serf::Runners::EmRunner
+      # Factories to build objects that wire our Serf App together.
+      # Note that these default implementing classes are also factories
+      # of their own objects (i.e. - define a 'build' class method).
+      @serfer_factory = ::Serf::Serfer
+      @foreground_runner_factory = ::Serf::Runners::DirectRunner
+      @background_runner_factory = ::Serf::Runners::EmRunner
+      @route_set_factory = ::Serf::Util::RouteSet
 
       # Utility and messaging channels for our Runners
       # NOTE: these are only used if the builder needs to instantiage runners.
@@ -56,32 +59,40 @@ module Serf
       self.new(default_app, &block).to_app
     end
 
-    def register(manifest)
-      @manifest.merge! manifest
+    def use(middleware, *args, &block)
+      @use << proc { |app| middleware.new(app, *args, &block) }
     end
 
-    def config(handler, *args, &block)
-      @config[handler] = [args, block]
+    def routes(route_map)
+      @route_maps << route_map
+    end
+
+    def handler(handler_name, handler)
+      @handlers[handler_name] = handler
+    end
+
+    def message_parser(message_parser_name, message_parser)
+      @message_parsers[message_parser_name] = message_parser
     end
 
     def not_found(app)
       @not_found = app
     end
 
-    def serfer_class(serfer_class)
-      @serfer_class = serfer_class
+    def serfer_factory(serfer_factory)
+      @serfer_factory = serfer_factory
     end
 
-    def serfer_class(serfer_options)
-      @serfer_options = serfer_options
+    def foreground_runner_factory(foreground_runner_factory)
+      @foreground_runner_factory = foreground_runner_factory
     end
 
-    def runner(runner)
-      @runner = runner
+    def background_runner_factory(background_runner_factory)
+      @background_runner_factory = background_runner_factory
     end
 
-    def async_runner(runner)
-      @async_runner = runner
+    def route_set_factory(route_set_factory)
+      @route_set_factory = route_set_factory
     end
 
     def results_channel(results_channel)
@@ -97,61 +108,79 @@ module Serf
     end
 
     def to_app
-      # Our async and sync messages & handlers.
-      handlers = {}
-      async_handlers = {}
-
-      # Iterate our manifests to build out handlers and message classes
-      @manifest.each do |kind, options|
-        # Instantiate our handler with any possible configuration.
-        handler_str = options.fetch(:handler)
-        handler_class = handler_str.camelize.constantize
-        args, block = @config.fetch(handler_str) { [[], nil] }
-        handler = handler_class.new *args, &block
-
-        # Put handlers and kinds into the proper map of handlers for either
-        # synchronous or asynchronous processing.
-        async = options.fetch(:async) { true }
-        if async
-          async_handlers[kind] = handler
-        else
-          handlers[kind] = handler
+      bg_route_set = @route_set_factory.build
+      fg_route_set = @route_set_factory.build
+
+      @route_maps.each do |route_map|
+        route_map.each do |matcher, route_configs|
+          route_configs.each do |route_config|
+            # Get the required handler.
+            # Raises error if handler wasn't declared in config.
+            # Raises error if handler wasn't registered with builder.
+            handler_name = route_config.fetch :handler
+            handler = @handlers.fetch handler_name
+
+            # Get the required action/method of the handler.
+            # Raises error if route_config doesn't have it.
+            action = route_config.fetch :action
+
+            # Lookup the parser if it was defined.
+            # The Parser MAY be either an object or string.
+            # If String, then we're going to look up in parser map.
+            # Raises an error if a parser (string) was declared, but not
+            # registered with the builder.
+            parser = route_config[:message_parser]
+            parser = @message_parsers.fetch(parser) if parser.is_a?(String)
+
+            # We have the handler, action and parser.
+            # Now we're going to add that route to either the background
+            # or foreground route_set.
+            background = route_config.fetch(:background) { false }
+            (background ? bg_route_set : fg_route_set).add_route(
+              matcher: matcher,
+              handler: handler,
+              action: action,
+              message_parser: parser)
+          end
         end
       end
 
-      # Get or make our runner
-      runner = @runner || @runner_class.new(
+      # Get or make our foreground runner
+      fg_runner = @foreground_runner_factory.build(
         results_channel: @results_channel,
         error_channel: @error_channel,
         logger: @logger)
 
-      # By default, we go to the not_found app.
-      app = @not_found
+      # Get or make our background runner
+      bg_runner = @background_runner_factory.build(
+        results_channel: @results_channel,
+        error_channel: @error_channel,
+        logger: @logger)
 
-      # If we have synchronous handlers, insert before not_found app.
-      if handlers.size > 0
-        # create the serfer class to run synchronous handlers
-        app = @serfer_class.new(
-          @serfer_options.merge(
-            handlers: handlers,
-            runner: runner,
-            not_found: app))
+      # We create the route_sets dependent on built routes.
+      route_sets = {}
+      if fg_route_set.size > 0
+        route_sets[fg_route_set] = fg_runner
+      end
+      if bg_route_set.size > 0
+        route_sets[bg_route_set] = bg_runner
       end
 
-      # If we have async handlers, insert before current app stack.
-      if async_handlers.size > 0
-        # Get or make our async wrapper
-        async_runner = @async_runner || @async_runner_class.new(
-          runner: runner,
+      # By default, we go to the not_found app.
+      app = @not_found
+
+      # But if we have routes, then we'll build a serfer to handle it.
+      if route_sets.size > 0
+        app = @serfer_factory.build(
+          route_sets: route_sets,
+          not_found: app,
+          error_channel: @error_channel,
           logger: @logger)
-        # create the serfer class to run async handlers
-        app = @serfer_class.new(
-          @serfer_options.merge(
-            handlers: async_handlers,
-            runner: async_runner,
-            not_found: app))
       end
 
+      # We're going to inject middleware here.
+      app = @use.reverse.inject(app) { |a,e| e[a] } if @use.size > 0
+
       return app
     end
   end

data/lib/serf/message.rb

@@ -17,24 +17,20 @@ module Serf
       send 'kind=', self.to_s.tableize.singularize
     end
 
-    module InstanceMethods
-
-      def kind
-        self.class.kind
-      end
-
-      def to_hash
-        attributes.merge kind: kind
-      end
+    def kind
+      self.class.kind
+    end
 
-      def to_msgpack
-        to_hash.to_msgpack
-      end
+    def to_hash
+      attributes.merge kind: kind
+    end
 
-      def to_json(*args)
-        to_hash.to_json *args
-      end
+    def to_msgpack
+      to_hash.to_msgpack
+    end
 
+    def to_json(*args)
+      to_hash.to_json *args
     end
 
     module ClassMethods

data/lib/serf/middleware/uuid_tagger.rb

@@ -0,0 +1,31 @@
+require 'uuidtools'
+
+module Serf
+module Middleware
+
+  ##
+  # Middleware to add a request uuid the ENV Hash to uniquely identify
+  # the handling of this input. But it won't overwrite the uuid field
+  # if the incoming request already has it.
+  #
+  class UuidTagger
+
+    ##
+    # @param app the app
+    # @options opts [String] :field the ENV field to set with a UUID.
+    #
+    def initialize(app, options={})
+      @app = app
+      @field = options.fetch(:field) { 'serf.request_uuid' }
+    end
+
+    def call(env)
+      env = env.dup
+      env[@field] ||= UUIDTools::UUID.random_create.to_s
+      @app.call env
+    end
+
+  end
+
+end
+end

data/lib/serf/runners/direct_runner.rb

@@ -1,5 +1,4 @@
-require 'serf/messages/caught_exception_event'
-require 'serf/util/null_object'
+require 'serf/util/with_error_handling'
 
 module Serf
 module Runners
@@ -10,28 +9,33 @@ module Runners
   # to proper error or results channels.
   #
   class DirectRunner
+    include ::Serf::Util::WithErrorHandling
 
     def initialize(options={})
       # Mandatory, we want both results and error channels.
       @results_channel = options.fetch(:results_channel)
       @error_channel = options.fetch(:error_channel)
 
-      # For caught exceptions, we're going to publish an error event
-      # over our error channel. This defines our error event message class.
-      @error_event_class = options.fetch(:error_event_class) {
-        ::Serf::Messages::CaughtExceptionEvent
-      }
-
-      # Our default logger
-      @logger = options.fetch(:logger) { ::Serf::Util::NullObject.new }
+      # Optional overrides for error handling
+      @error_event_class = options[:error_event_class]
+      @logger = options[:logger]
     end
 
-    def run(handler, params)
-      with_error_handling(params) do
-        results = handler.call params
-        publish_results results
-        return results
+    def run(endpoints, env)
+      results = []
+      endpoints.each do |ep|
+        run_results = with_error_handling(env) do
+          params = ep.message_parser ? ep.message_parser.parse(env) : env
+          ep.handler.send(ep.action, params)
+        end
+        results.concat Array(run_results)
+        publish_results run_results
       end
+      return results
+    end
+
+    def self.build(options={})
+      self.new options
     end
 
     protected
@@ -50,24 +54,6 @@ module Runners
       return nil
     end
 
-    ##
-    # A block wrapper to handle errors when executing a block.
-    #
-    def with_error_handling(context=nil)
-      yield
-    rescue => e
-      error_event = @error_event_class.new(
-        context: context,
-        error_message: e.inspect,
-        error_backtrace: e.backtrace.join("\n"))
-
-      # log the error to our logger, and to our error channel.
-      @logger.error error_event
-      @error_channel.publish error_event
-
-      # We're done, so just return this error.
-      return error_event
-    end
   end
 
 end

data/lib/serf/runners/em_runner.rb

@@ -1,6 +1,7 @@
 require 'eventmachine'
 
 require 'serf/messages/message_accepted_event'
+require 'serf/runners/direct_runner'
 
 module Serf
 module Runners
@@ -34,15 +35,25 @@ module Runners
       @logger = options.fetch(:logger) { ::Serf::Util::NullObject.new }
     end
 
-    def run(handler, params)
+    def run(endpoints, env)
+      endpoints = endpoints.dup
+      env = env.dup
       @evm.defer(proc do
         begin
-          @runner.run handler, params
+          @runner.run endpoints, env
         rescue => e
           @logger.error "#{e.inspect}\n\n#{e.backtrace.join("\n")}"
         end
       end)
-      return @mae_class.new message: params
+      return @mae_class.new message: env
+    end
+
+    def self.build(options={})
+      options[:runner] = options.fetch(:runner) {
+        factory = options[:runner_factory] || ::Serf::Runners::DirectRunner
+        factory.build options
+      }
+      self.new options
     end
 
   end

data/lib/serf/serfer.rb

@@ -1,41 +1,60 @@
 require 'serf/error'
+require 'serf/util/with_error_handling'
 
 module Serf
 
   class Serfer
+    include ::Serf::Util::WithErrorHandling
 
     def initialize(options={})
-      # Manditory, needs a runner.
-      @runner = options.fetch(:runner)
+      # Each route_set has a runner.
+      @route_sets = options[:route_sets] || {}
+
+      # Optional overrides for WithErrorHandling
+      @error_channel = options[:error_channel]
+      @error_event_class = options[:error_event_class]
+      @logger = options[:logger]
 
       # Options for handling the requests
-      @handlers = options[:handlers] || {}
       @not_found = options[:not_found] || proc do
         raise ArgumentError, 'Handler Not Found'
       end
     end
 
     ##
-    # Rack-like call to handle a message
+    # Rack-like call to run set of handlers for a message
     #
     def call(env)
       # We normalize by symbolizing the env keys
-      params = env.symbolize_keys
-
-      # Pull the kind out of the env.
-      kind = params[:kind]
-      handler = @handlers[kind]
-      if handler
-        # Let's run the handler
-        return @runner.run(handler, params) if handler
-      else
-        # we can't handle this kind.
-        return @not_found.call env
+      env = env.symbolize_keys
+
+      # We're going to concat all the results
+      matched_routes = false
+      results = []
+      @route_sets.each do |route_set, runner|
+        with_error_handling(env) do
+          endpoints = route_set.match_routes env
+          if endpoints.size > 0
+            matched_routes = true
+            results.concat Array(runner.run(endpoints, env))
+          end
+        end
       end
+
+      # If we don't have any handlers, do the not_found call.
+      # NOTE: Purposefully not wrapping this in exception handling.
+      return @not_found.call env unless matched_routes
+
+      return results
     rescue => e
       e.extend(::Serf::Error)
       raise e
     end
+
+    def self.build(options={})
+      self.new options
+    end
+
   end
 
 end

data/lib/serf/util/regexp_matcher.rb

@@ -0,0 +1,29 @@
+module Serf
+module Util
+
+  ##
+  # A matcher that does a regexp match on a specific field
+  # in the given Env. By default, we use this to do regexp matching
+  # on message kinds for routing.
+  #
+  class RegexpMatcher
+    attr_reader :regexp
+    attr_reader :field
+
+    def initialize(regexp, options={})
+      @regexp = regexp
+      @field = options.fetch(:field) { :kind }
+    end
+
+    def ===(env)
+      return @regexp === env[@field]
+    end
+
+    def self.build(regexp)
+      return self.new regexp
+    end
+
+  end
+
+end
+end

data/lib/serf/util/route_endpoint.rb

@@ -0,0 +1,37 @@
+module Serf
+module Util
+
+  ##
+  # A simple class to represent route endpoints. RouteSets
+  # store a list of endpoints per matcher, and Runners use endpoints
+  # to then execute the handlers.
+  #
+  class RouteEndpoint
+    # Actual handler object that defines the action method.
+    attr_accessor :handler
+    # The method to call.
+    attr_accessor :action
+    # A parser that turns the message ENV hash into a Message object
+    # that the handler#action uses.
+    attr_accessor :message_parser
+
+    def initialize(options={})
+      # Mandatory parameters
+      @handler = options.fetch :handler
+      @action = options.fetch :action
+
+      # Optional parameters
+      @message_parser = options[:message_parser]
+    end
+
+    ##
+    # Default factory method.
+    #
+    def self.build(options={})
+      return self.new options
+    end
+
+  end
+
+end
+end

data/lib/serf/util/route_set.rb

@@ -0,0 +1,82 @@
+require 'serf/util/route_endpoint'
+require 'serf/util/regexp_matcher'
+
+module Serf
+module Util
+
+  ##
+  # RouteSets hold routing information for ENV hashes to matched endpoints.
+  #
+  class RouteSet
+
+    def initialize(options={})
+      @routes = {}
+      @matchers = []
+      @regexp_matcher_factory = options.fetch(:regexp_matcher_factory) {
+        ::Serf::Util::RegexpMatcher
+      }
+      @route_endpoint_factory = options.fetch(:route_endpoint_factory) {
+        ::Serf::Util::RouteEndpoint
+      }
+    end
+
+    ##
+    # Connects a matcher (String or an Object implementing ===) to an endpoint.
+    #
+    # @option opts [Obj, String] :matcher Matches ENV Hashes to endpoints.
+    #   Note that String and Regexp values are set up to match the
+    #   :kind key from ENV Hashes.
+    # @option opts [Obj] :handler Receiver of the action.
+    # @option opts [Symbol, String] :action Method to call on handler.
+    # @option opts [#parse] :message_parser Translates ENV Hash to Message Obj.
+    #
+    def add_route(options={})
+      # We create our endpoint representation.
+      endpoint = @route_endpoint_factory.build(
+        handler: options.fetch(:handler),
+        action: options.fetch(:action),
+        message_parser: options[:message_parser])
+
+      # Maybe we have an non-String matcher. Handle the Regexp case.
+      # We only keep track of matchers if it isn't a string because
+      # string matchers are just pulled out of routes by key lookup.
+      matcher = options.fetch :matcher
+      matcher = @regexp_matcher_factory.build matcher if matcher.kind_of? Regexp
+      @matchers << matcher unless matcher.is_a? String
+
+      # We add the route (matcher+endpoint) into our routes
+      @routes[matcher] ||= []
+      @routes[matcher] << endpoint
+    end
+
+    ##
+    # @param [Hash] env The input message environment to match for routes.
+    # @return [Array] List of endpoints that matched.
+    #
+    def match_routes(env={})
+      kind = env[:kind]
+      routes = []
+      routes.concat Array(@routes[kind])
+      @matchers.each do |matcher|
+        routes.concat Array(@routes[matcher]) if matcher === env
+      end
+      return routes
+    end
+
+    ##
+    # @return [Integer] Number of routes this RouteSet tracks.
+    #
+    def size
+      return @routes.size
+    end
+
+    ##
+    # Default factory method.
+    #
+    def self.build(options={})
+      self.new options
+    end
+  end
+
+end
+end

data/lib/serf/util/with_error_handling.rb

@@ -0,0 +1,44 @@
+require 'serf/messages/caught_exception_event'
+require 'serf/util/null_object'
+
+module Serf
+module Util
+
+  ##
+  # Helper module to rescues exceptions from executing blocks of
+  # code, and then logs+publishes the error event.
+  #
+  module WithErrorHandling
+
+    ##
+    # A block wrapper to handle errors when executing a block.
+    #
+    # Including classes may have the following instance variables
+    # to override the default values:
+    # * @error_event_class - ::Serf::Messages::CaughtExceptionEvent
+    # * @logger - ::Serf::Util::NullObject.new
+    # * @error_channel - ::Serf::Util::NullObject.new
+    #
+    def with_error_handling(context=nil)
+      yield
+    rescue => e
+      eec = @error_event_class || ::Serf::Messages::CaughtExceptionEvent
+      logger = @logger || ::Serf::Util::NullObject.new
+      error_channel = @error_channel || ::Serf::Util::NullObject.new
+      error_event = eec.new(
+        context: context,
+        error_message: e.inspect,
+        error_backtrace: e.backtrace.join("\n"))
+
+      # log the error to our logger, and to our error channel.
+      logger.error error_event
+      error_channel.publish error_event
+
+      # We're done, so just return this error.
+      return error_event
+    end
+
+  end
+
+end
+end

data/lib/serf/version.rb

@@ -2,8 +2,8 @@ module Serf
 
   module Version
     MAJOR = 0
-    MINOR = 4
-    PATCH = 1
+    MINOR = 5
+    PATCH = 0
     BUILD = nil
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join '.'
   end

data/serf.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "serf"
-  s.version = "0.4.1"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Benjamin Yu"]
-  s.date = "2012-01-22"
+  s.date = "2012-01-26"
   s.description = "Event-Driven SOA with CQRS"
   s.email = "benjaminlyu@gmail.com"
   s.extra_rdoc_files = [
@@ -28,15 +28,19 @@ Gem::Specification.new do |s|
     "lib/serf.rb",
     "lib/serf/builder.rb",
     "lib/serf/error.rb",
-    "lib/serf/handler.rb",
     "lib/serf/message.rb",
     "lib/serf/messages/caught_exception_event.rb",
     "lib/serf/messages/message_accepted_event.rb",
+    "lib/serf/middleware/uuid_tagger.rb",
     "lib/serf/runners/direct_runner.rb",
     "lib/serf/runners/em_runner.rb",
     "lib/serf/serfer.rb",
     "lib/serf/util/null_object.rb",
+    "lib/serf/util/regexp_matcher.rb",
+    "lib/serf/util/route_endpoint.rb",
+    "lib/serf/util/route_set.rb",
     "lib/serf/util/uuidable.rb",
+    "lib/serf/util/with_error_handling.rb",
     "lib/serf/version.rb",
     "serf.gemspec",
     "spec/serf_spec.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serf
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-22 00:00:00.000000000Z
+date: 2012-01-26 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70284496039920 !ruby/object:Gem::Requirement
+  requirement: &70145106081500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.2.0
   type: :runtime
   prerelease: false
-  version_requirements: *70284496039920
+  version_requirements: *70145106081500
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &70284496037020 !ruby/object:Gem::Requirement
+  requirement: &70145106073960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 0.6.0
   type: :runtime
   prerelease: false
-  version_requirements: *70284496037020
+  version_requirements: *70145106073960
 - !ruby/object:Gem::Dependency
   name: uuidtools
-  requirement: &70284496034860 !ruby/object:Gem::Requirement
+  requirement: &70145106072920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: 2.1.2
   type: :runtime
   prerelease: false
-  version_requirements: *70284496034860
+  version_requirements: *70145106072920
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70284496020980 !ruby/object:Gem::Requirement
+  requirement: &70145106071740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 2.3.0
   type: :development
   prerelease: false
-  version_requirements: *70284496020980
+  version_requirements: *70145106071740
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70284496019460 !ruby/object:Gem::Requirement
+  requirement: &70145106070620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 0.6.0
   type: :development
   prerelease: false
-  version_requirements: *70284496019460
+  version_requirements: *70145106070620
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70284496018360 !ruby/object:Gem::Requirement
+  requirement: &70145106069640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70284496018360
+  version_requirements: *70145106069640
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70284496017420 !ruby/object:Gem::Requirement
+  requirement: &70145106068740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +87,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70284496017420
+  version_requirements: *70145106068740
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70284496015800 !ruby/object:Gem::Requirement
+  requirement: &70145106067300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70284496015800
+  version_requirements: *70145106067300
 - !ruby/object:Gem::Dependency
   name: msgpack
-  requirement: &70284496014740 !ruby/object:Gem::Requirement
+  requirement: &70145106053600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: 0.4.6
   type: :development
   prerelease: false
-  version_requirements: *70284496014740
+  version_requirements: *70145106053600
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &70284496013960 !ruby/object:Gem::Requirement
+  requirement: &70145106052540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +120,7 @@ dependencies:
         version: 0.12.10
   type: :development
   prerelease: false
-  version_requirements: *70284496013960
+  version_requirements: *70145106052540
 description: Event-Driven SOA with CQRS
 email: benjaminlyu@gmail.com
 executables: []
@@ -140,15 +140,19 @@ files:
 - lib/serf.rb
 - lib/serf/builder.rb
 - lib/serf/error.rb
-- lib/serf/handler.rb
 - lib/serf/message.rb
 - lib/serf/messages/caught_exception_event.rb
 - lib/serf/messages/message_accepted_event.rb
+- lib/serf/middleware/uuid_tagger.rb
 - lib/serf/runners/direct_runner.rb
 - lib/serf/runners/em_runner.rb
 - lib/serf/serfer.rb
 - lib/serf/util/null_object.rb
+- lib/serf/util/regexp_matcher.rb
+- lib/serf/util/route_endpoint.rb
+- lib/serf/util/route_set.rb
 - lib/serf/util/uuidable.rb
+- lib/serf/util/with_error_handling.rb
 - lib/serf/version.rb
 - serf.gemspec
 - spec/serf_spec.rb
@@ -168,7 +172,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -616776169548584213
+      hash: -650473328553199241
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/lib/serf/handler.rb

@@ -1,91 +0,0 @@
-require 'active_support/concern'
-require 'active_support/core_ext/class/attribute'
-require 'active_support/core_ext/hash/keys'
-require 'active_support/core_ext/object/blank'
-require 'active_support/ordered_options'
-
-require 'serf/error'
-
-module Serf
-
-  module Handler
-    extend ActiveSupport::Concern
-
-    included do
-      # In the class that includes this module, we're going to
-      # create an inheritable class attribute that will store
-      # our mappings between messages and the methods to call.
-      class_attribute :serf_actions
-      class_attribute :serf_message_classes
-      send(
-        'serf_actions=',
-        ActiveSupport::InheritableOptions.new)
-      send(
-        'serf_message_classes=',
-        ActiveSupport::InheritableOptions.new)
-
-      def self.inherited(kls) #:nodoc:
-        super
-        # Sets the current subclass class attribute to be an
-        # inheritable copy of the superclass options.
-        kls.send(
-          'serf_actions=',
-          self.serf_actions.inheritable_copy)
-        kls.send(
-          'serf_message_classes=',
-          self.serf_message_classes.inheritable_copy)
-      end
-
-    end
-
-    module InstanceMethods
-
-      ##
-      # Rack-like call. It receives an environment hash, which we
-      # assume is a message.
-      #
-      def call(env={})
-        # Just to stringify the environment keys
-        env = env.symbolize_keys
-        # Make sure a kind was set, and that we can handle it.
-        message_kind = env[:kind]
-        raise ArgumentError, 'No "kind" in call env' if message_kind.blank?
-        method = self.class.serf_actions[message_kind]
-        raise ArgumentError, "#{message_kind} not found" if method.blank?
-        # Optionally convert the env into a Message class.
-        # Let the actual handler method validate if they want.
-        message_class = self.class.serf_message_classes[message_kind]
-        env = message_class.parse env if message_class
-        # Now execute the method with the environment parameters
-        self.send method, env
-      rescue => e
-        e.extend ::Serf::Error
-        raise e
-      end
-    end
-
-    module ClassMethods
-
-      ##
-      # registers a method to handle the receipt of a message type.
-      # @param *args splat list of message kinds
-      # @options opts [Symbol] :with The method to call.
-      # @options opts [Object] :as The Message class to call `parse`.
-      #
-      def receives(*args)
-        options = args.last.kind_of?(Hash) ? args.pop : {}
-        exposed_method = options[:with]
-        raise ArgumentError, 'Missing "with" option' if exposed_method.blank?
-        message_class = options[:as]
-        args.each do |kind|
-          raise ArgumentError, 'Blank kind' if kind.blank?
-          self.serf_actions[kind] = exposed_method
-          self.serf_message_classes[kind] = message_class if message_class
-        end
-      end
-
-    end
-
-  end
-
-end