serf 0.10.0 → 0.11.0

data/lib/serf/builder.rb

@@ -1,166 +1,61 @@
-require 'serf/routing/route'
-require 'serf/routing/route_set'
+require 'serf/middleware/error_handler'
+require 'serf/middleware/parcel_freezer'
+require 'serf/middleware/parcel_masher'
+require 'serf/middleware/policy_checker'
+require 'serf/middleware/uuid_tagger'
 require 'serf/serfer'
-require 'serf/util/null_object'
 require 'serf/util/options_extraction'
 
 module Serf
 
-  ##
-  # A Serf Builder that processes the SerfUp DSL to build a rack-like
-  # app to handlers that process received messages. This builder is
-  # implemented based on code from Rack::Builder.
-  #
-  #   builder = Serf::Builder.parse_file 'examples/config.su'
-  #   builder.to_app
-  #
-  # or
-  #
-  #   builder = Serf::Builder.new do
-  #     ... A SerfUp Config block here.
-  #   end
-  #   builder.to_app
-  #
   class Builder
     include Serf::Util::OptionsExtraction
 
-    attr_reader :serfer_factory
-    attr_reader :route_set_factory
-    attr_reader :route_factory
-
-    def self.parse_file(config)
-      cfgfile = ::File.read(config)
-      builder = eval "Serf::Builder.new {\n" + cfgfile + "\n}",
-        TOPLEVEL_BINDING, config
-      return builder
-    end
-
-    def self.app(*args, &block)
-      new(*args, &block).to_app
-    end
-
     def initialize(*args, &block)
       extract_options! args
 
-      # Our factories
-      @serfer_factory = opts :serfer_factory, Serf::Serfer
-      @route_set_factory = opts :route_set_factory, Serf::Routing::RouteSet
-      @route_factory = opts :route_factory, Serf::Routing::Route
-
-      # List of middleware to be executed (non-built form)
+      @run = opts :interactor
       @use = []
+      @policy_chain = opts :policy_chain, []
 
-      # A list of "mounted", non-built, command handlers with their
-      # matcher and policies.
-      @runs = []
-
-      # List of default policies to be run (non-built form)
-      @default_policies = []
-
-      # The current matcher
-      @matcher = nil
-
-      # Current policies to be run (PRE-built)
-      @policies = []
-
-      # configure based on a given block.
-      instance_eval(&block) if block_given?
+      if block_given?
+        instance_eval(&block)
+      else
+        use_defaults
+      end
     end
 
     ##
-    # Append a policy to default policy chain. The default
-    # policy chain is used by any route that does not define
-    # at least one of its own policies.
+    # Set a default chain of the following:
+    #
+    #   use Serf::Middleware::ParcelMasher
+    #   use Serf::Middleware::UuidTagger
+    #   use Serf::Middleware::ParcelFreezer
+    #   use Serf::Middleware::ErrorHandler
+    #   use Serf::Middleware::PolicyChecker, @policy_chain
+    #   use Serf::Serfer
     #
-    # @param policy the policy factory to append
-    # @param *args the arguments to pass to the factory
-    # @param &block the block to pass to the factory
-    def default_policy(policy, *args, &block)
-      @default_policies << proc { policy.build(*args, &block) }
+    def use_defaults
+      use Serf::Middleware::ParcelMasher
+      use Serf::Middleware::UuidTagger
+      use Serf::Middleware::ParcelFreezer
+      use Serf::Middleware::ErrorHandler
+      use Serf::Middleware::PolicyChecker, policy_chain: @policy_chain
+      use Serf::Serfer
     end
 
-    ##
-    # Append a rack-like middleware
-    #
-    # @param the middleware class
-    # @param *args the arguments to pass to middleware.new
-    # @param &block the block to pass to middleware.new
     def use(middleware, *args, &block)
       @use << proc { |app| middleware.new(app, *args, &block) }
     end
 
-    ##
-    # Append a policy to the current match's policy chain.
-    #
-    # @param policy the policy factory to append
-    # @param *args the arguments to pass to the factory
-    # @param &block the block to pass to the factory
-    def policy(policy, *args, &block)
-      @policies << proc { policy.build(*args, &block) }
+    def run(interactor)
+      @run = interactor
     end
 
-    def response_channel(channel); @response_channel = channel; end
-    def error_channel(channel); @error_channel = channel; end
-    def logger(logger); @logger = logger; end
-
-    ##
-    # DSL Method to change our current context to use the given matcher.
-    #
-    def match(matcher)
-      @matcher = matcher
-      @policies = []
-    end
-
-    ##
-    # @param command_factory the factory to invoke (in #to_app)
-    # @param *args the rest of the args to pass to command_factory#build method
-    # @param &block the block to pass to command_factory#build method
-    def run(command_factory, *args, &block)
-      raise 'No matcher defined yet' unless @matcher
-      # Create a local duplicate of the matcher and policies "snapshotted"
-      # at the time this method is called... so that snapshot is consistent
-      # for when the proc is called.
-      matcher = @matcher.dup
-      policies = @policies.dup
-
-      # This proc will be called in to_app when we actually go ahead and
-      # instantiate all the objects. By this point, route_set and
-      # default_policies passed to this proc will be ready, built.
-      @runs << proc { |route_set, default_policies|
-        route_set.add(
-          matcher,
-          route_factory.build(
-            command: command_factory.build(*args, &block),
-            policies: (policies.size > 0 ?
-              policies.map{ |p| p.call } :
-              default_policies)))
-      }
-    end
-
-    ##
-    # Create our app.
-    #
     def to_app
-      # Create the route_set to resolve routes
-      route_set = route_set_factory.build
-      # Build the default policies to be used if routes did not specify any.
-      default_policies = @default_policies.map{ |p| p.call }
-      # Add each route to the route_set
-      for run in @runs
-        run.call route_set, default_policies
-      end
-      # Create our serfer class
-      app = serfer_factory.build(
-        route_set: route_set,
-        response_channel: (@response_channel || Serf::Util::NullObject.new),
-        error_channel: (@error_channel || Serf::Util::NullObject.new),
-        logger: (@logger || Serf::Util::NullObject.new))
-
-      # We're going to inject middleware here.
-      app = @use.reverse.inject(app) { |a,e| e[a] } if @use.size > 0
-
-      return app
+      @use.reverse.inject(@run) { |a,e| e[a] }
     end
 
   end
+
 end

data/lib/serf/errors/policy_failure.rb

@@ -0,0 +1,10 @@
+module Serf
+module Errors
+
+  ##
+  # Common base error to raise for any policy failure.
+  class PolicyFailure < RuntimeError
+  end
+
+end
+end

data/lib/serf/middleware/error_handler.rb

@@ -0,0 +1,53 @@
+require 'hashie'
+
+require 'serf/parcel_builder'
+require 'serf/util/error_handling'
+require 'serf/util/uuidable'
+
+module Serf
+module Middleware
+
+  ##
+  # Middleware to catch raised exceptions and return an error parcel
+  # instead.
+  #
+  class ErrorHandler
+    include Serf::Util::ErrorHandling
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :app
+    attr_reader :parcel_builder
+    attr_reader :uuidable
+
+    ##
+    # @param app the app
+    #
+    def initialize(app, *args)
+      extract_options! args
+      @app = app
+
+      # Tunable knobs
+      @parcel_builder = opts(:parcel_builder) { Serf::ParcelBuilder.new }
+      @uuidable = opts(:uuidable) { Serf::Util::Uuidable.new }
+    end
+
+    def call(parcel)
+      # Attempt to execute the app, catching errors
+      response_parcel, error_message = with_error_handling do
+        app.call parcel
+      end
+
+      # Return on success
+      return response_parcel if response_parcel
+
+      # We got an error message instead, so build out the headers
+      # and return the parcel.
+      error_headers = uuidable.create_uuids parcel[:headers]
+      error_headers[:kind] = 'serf/events/caught_error'
+      return parcel_builder.build error_headers, error_message
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/parcel_freezer.rb

@@ -0,0 +1,36 @@
+require 'ice_nine'
+
+require 'serf/util/options_extraction'
+
+module Serf
+module Middleware
+
+  ##
+  # Middleware to add uuids to the headers of the parcel hash.
+  #
+  class ParcelFreezer
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :app
+    attr_reader :freezer
+
+    ##
+    # @param app the app
+    #
+    def initialize(app, *args)
+      extract_options! args
+      @app = app
+      @freezer = opts :freezer, IceNine
+    end
+
+    ##
+    # Chains the call, but deep freezes the parcel.
+    def call(parcel)
+      freezer.deep_freeze parcel
+      app.call parcel
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/parcel_masher.rb

@@ -0,0 +1,39 @@
+require 'hashie'
+
+require 'serf/util/options_extraction'
+
+module Serf
+module Middleware
+
+  ##
+  # Middleware to add uuids to the headers of the parcel hash.
+  #
+  class ParcelMasher
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :app
+    attr_reader :masher_class
+
+    ##
+    # @param app the app
+    #
+    def initialize(app, *args)
+      extract_options! args
+      @app = app
+      @masher_class = opts :masher_class, Hashie::Mash
+    end
+
+    ##
+    # Coerces the parcel into a Hashie::Mash, makes sure that
+    # the headers and message are set, and then passes it along the chain.
+    def call(parcel)
+      mashed_parcel = masher_class.new parcel
+      mashed_parcel[:headers] ||= {}
+      mashed_parcel[:message] ||= {}
+      app.call mashed_parcel
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/policy_checker.rb

@@ -0,0 +1,31 @@
+require 'serf/util/options_extraction'
+
+module Serf
+module Middleware
+
+  class PolicyChecker
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :app
+    attr_reader :policy_chain
+
+    def initialize(app, *args)
+      extract_options! args
+      @app = app
+      @policy_chain = opts :policy_chain, []
+    end
+
+    ##
+    # Iterates the policy chain and does a check for each policy.
+    # Assumes that policies will raise errors on any policy failure.
+    def call(parcel)
+      policy_chain.each do |policy|
+        policy.check! parcel
+      end
+      app.call parcel
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/uuid_tagger.rb

@@ -1,36 +1,38 @@
+require 'hashie'
+
+require 'serf/util/options_extraction'
 require 'serf/util/uuidable'
 
 module Serf
 module Middleware
 
   ##
-  # Middleware to add a request uuid to both the message and context
-  # of the env hash. But it won't overwrite the uuid field
-  # if the incoming request already has it.
+  # Middleware to add uuids to the headers of the parcel hash.
   #
   class UuidTagger
     include Serf::Util::OptionsExtraction
 
+    attr_reader :app
     attr_reader :uuidable
 
     ##
     # @param app the app
-    # @options opts [String] :field the ENV field to set with a UUID.
     #
     def initialize(app, *args)
       extract_options! args
       @app = app
-      @uuidable = opts :uuidable, Serf::Util::Uuidable
+      @uuidable = opts(:uuidable) { Serf::Util::Uuidable.new }
     end
 
-    def call(env)
-      message = env[:message]
-      message[:uuid] = uuidable.create_coded_uuid if message && !message[:uuid]
+    def call(parcel)
+      # Makes sure our parcel has headers
+      parcel[:headers] ||= {}
 
-      context = env[:context]
-      context[:uuid] = uuidable.create_coded_uuid if context && !context[:uuid]
+      # Tag headers with a UUID unless it already has one
+      parcel[:headers][:uuid] ||= uuidable.create_coded_uuid
 
-      @app.call env
+      # Pass on the given parcel with newly annotated headers
+      app.call parcel
     end
 
   end

data/lib/serf/parcel_builder.rb

@@ -0,0 +1,30 @@
+require 'hashie'
+
+require 'serf/util/options_extraction'
+
+module Serf
+
+  ##
+  # Builds Parcels as Hashie::Mash objects with headers and messages.
+  #
+  class ParcelBuilder
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :mash_class
+
+    def initialize(*args)
+      extract_options! args
+
+      @mash_class = opts :mash_class, Hashie::Mash
+    end
+
+    def build(headers=nil, message=nil)
+      # We want to make sure that our headers and message are Mashes.
+      headers = mash_class.new(headers) unless headers.kind_of? mash_class
+      message = mash_class.new(message) unless message.kind_of? mash_class
+      mash_class.new headers: headers, message: message
+    end
+
+  end
+
+end

data/lib/serf/serfer.rb

@@ -1,87 +1,48 @@
 require 'hashie'
 
-require 'serf/error'
-require 'serf/errors/not_found'
-require 'serf/util/error_handling'
-require 'serf/util/null_object'
+require 'serf/parcel_builder'
+require 'serf/util/options_extraction'
+require 'serf/util/uuidable'
 
 module Serf
 
   ##
-  # Class to drive the command handler execution, error handling, etc
-  # of received messages.
+  # Class to drive the Interactor execution.
+  #
   class Serfer
-    include Serf::Util::ErrorHandling
+    include Serf::Util::OptionsExtraction
 
-    attr_reader :route_set
-    attr_reader :response_channel
-    attr_reader :error_channel
-    attr_reader :logger
+    attr_reader :interactor
+    attr_reader :parcel_builder
+    attr_reader :uuidable
 
-    def initialize(*args)
+    def initialize(interactor, *args)
       extract_options! args
 
-      @route_set = opts! :route_set
-      @response_channel = opts(:response_channel) { Serf::Util::NullObject }
-      @error_channel = opts(:error_channel) { Serf::Util::NullObject }
-      @logger = opts(:logger) { Serf::Util::NullObject }
+      # How to and when to handle requests
+      @interactor = interactor
+
+      # Tunable knobs
+      @parcel_builder = opts(:parcel_builder) { Serf::ParcelBuilder.new }
+      @uuidable = opts(:uuidable) { Serf::Util::Uuidable.new }
     end
 
     ##
-    # Rack-like call to run a set of handlers for a message
+    # Rack-like call to run the Interactor's use-case.
     #
-    def call(env)
-      env = Hashie::Mash.new env unless env.is_a? Hashie::Mash
-
-      # We normalize by making the request a Hashie Mash
-      message = Hashie::Mash.new env.message
-      context = Hashie::Mash.new env.context
-
-      # Resolve the routes that we want to run
-      routes = route_set.resolve message, context
-
-      # We raise an error if no routes were found.
-      raise Serf::Errors::NotFound unless routes.size > 0
+    def call(parcel)
+      headers = parcel[:headers]
+      message = parcel[:message]
 
-      # For each route, we're going to execute
-      results = routes.map { |route|
-        # 1. Check request+context with the policies (RAISE)
-        # 2. Execute command (RETURNS Hash)
-        ok, res = with_error_handling(
-            message: message,
-            options: context) do
-          route.check_policies! message, context
-          route.execute! message, context
-        end
-        # Return the run_results as result of this block.
-        res
-      }.flatten.select { |r| r }
-      push_results results, context
-      return results
-    rescue => e
-      e.extend(Serf::Error)
-      raise e
-    end
-
-    def self.build(*args, &block)
-      new *args, &block
-    end
+      # 1. Execute interactor
+      response_message, response_kind = interactor.call message
 
-    private
+      # 2. Create the response headers
+      response_headers = uuidable.create_uuids headers
+      response_headers[:kind] = response_kind
 
-    ##
-    # Loop over the results and push them to the response channel.
-    # Any error in pushing individual messages will result in
-    # a log event and an error channel event.
-    def push_results(results, context)
-      results.each do |result|
-        with_error_handling(result) do
-          response_channel.push(
-            message: result,
-            context: context)
-        end
-      end
-      return nil
+      # 3. Return the response headers and message as a parcel
+      return parcel_builder.build response_headers, response_message
     end
 
   end

data/lib/serf/util/error_handling.rb

@@ -1,7 +1,3 @@
-require 'active_support/core_ext/string/inflections'
-
-require 'serf/util/null_object'
-require 'serf/util/options_extraction'
 require 'serf/util/protected_call'
 
 module Serf
@@ -9,53 +5,34 @@ module Util
 
   ##
   # Helper module to rescues exceptions from executing blocks of
-  # code, and then logs+pushes the error event.
+  # code, and then converts the exception to an "Error Message".
   #
-  # Including classes may have the following instance variables
-  # to override the default values:
-  # * @logger - ::Serf::Util::NullObject.new
-  # * @error_channel - ::Serf::Util::NullObject.new
   module ErrorHandling
-    include Serf::Util::OptionsExtraction
     include Serf::Util::ProtectedCall
 
     ##
     # A block wrapper to handle errors when executing a block.
     #
-    def with_error_handling(context=nil, *args, &block)
-      ok, results = pcall *args, &block
-      return ok, (ok ? results : handle_error(results, context))
+    def with_error_handling(*args, &block)
+      results, err = pcall *args, &block
+      return results, handle_error(err)
     end
 
     ##
     # Including classes may override this method to do alternate error
-    # handling. By default, this method will create a new caught exception
-    # event and publish it to the error channel. This method will also
-    # log the exception itself to the logger.
+    # handling. By default, this method will create a new error event message.
     #
-    def handle_error(e, context=nil)
-      logger = opts(:logger){ ::Serf::Util::NullObject.new }
-      error_channel = opts(:error_channel) { ::Serf::Util::NullObject.new }
-      error_event = {
-        kind: 'serf/messages/caught_exception_event',
-        context: context,
-        error: e.class.to_s.underscore,
+    def handle_error(e)
+      # no error was passed, so do nothing.
+      return nil unless e
+
+      # Return a simple error event message
+      return {
+        error: e.class.to_s,
         message: e.message,
+        process_env: ENV.to_hash,
         backtrace: e.backtrace.join("\n")
       }
-
-      # log the error to our logger
-      logger.error e
-
-      # log the error event to our error channel.
-      begin
-        error_channel.push error_event
-      rescue => e1
-        logger.error e1
-      end
-
-      # We're done, so just return this error.
-      return error_event
     end
 
   end

data/lib/serf/util/protected_call.rb

@@ -24,9 +24,9 @@ module Util
     # @return boolean success and the block's (or caught exception) results.
     #
     def pcall(*args)
-      return true, yield(*args)
+      return yield(*args), nil
     rescue => e
-      return false, e
+      return nil, e
     end
     alias_method :protected_call, :pcall