serf 0.9.0 → 0.10.0

data/lib/serf/builder.rb

@@ -1,6 +1,5 @@
-require 'serf/routing/endpoint'
-require 'serf/routing/registry'
-require 'serf/runners/direct'
+require 'serf/routing/route'
+require 'serf/routing/route_set'
 require 'serf/serfer'
 require 'serf/util/null_object'
 require 'serf/util/options_extraction'
@@ -9,7 +8,7 @@ module Serf
 
   ##
   # A Serf Builder that processes the SerfUp DSL to build a rack-like
-  # app to endpoint and process received messages. This builder is
+  # 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'
@@ -25,47 +24,80 @@ module Serf
   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}",
+      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
 
-      # Configuration about the endpoints and apps to run.
+      # 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)
       @use = []
-      @not_found = opts :not_found, lambda { |env|
-        raise ArgumentError, 'Endpoints Not Found'
-      }
 
-      # Utility and messaging channels that get passed as options
-      # when building our Runners and Handlers.
-      @response_channel = ::Serf::Util::NullObject.new
-      @error_channel = ::Serf::Util::NullObject.new
-      @logger = ::Serf::Util::NullObject.new
+      # 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 = []
 
-      # Set up the starting state for our DSL calls.
-      @runner_matcher_endpoint_map = {}
-      @runner_params = {}
-      runner :direct
+      # 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?
     end
 
-    def self.app(default_app=nil, &block)
-      self.new(default_app, &block).to_app
+    ##
+    # 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.
+    #
+    # @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) }
     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
 
-    def not_found(app); @not_found = app; 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) }
+    end
 
     def response_channel(channel); @response_channel = channel; end
     def error_channel(channel); @error_channel = channel; end
@@ -74,74 +106,34 @@ module Serf
     ##
     # DSL Method to change our current context to use the given matcher.
     #
-    def match(matcher); @matcher = matcher; end
-
-    ##
-    # Mount and endpoint to the current context's Runner and Matcher.
-    # Connected so the endpoint will pass serf_options to the handler's build.
-    def run(*args, &block); mount true, *args, &block; end
-
-    ##
-    # Mount and endpoint to the current context's Runner and Matcher.
-    # Unconnected so the endpoint will omit serf_options to the handler's build.
-    def run_unconnected(*args, &block); mount false, *args, &block; end
-
-    ##
-    # The generic mount method used by run & run_unconnected to create an
-    # endpoint to be associated with the current context's Runner and Matcher.
-    def mount(connected, handler_factory, *args, &block)
-      raise 'No matcher defined yet' unless @matcher
-      @runner_matcher_endpoint_map[@runner_factory] ||= {}
-      @runner_matcher_endpoint_map[@runner_factory][@matcher] ||= []
-      @runner_matcher_endpoint_map[@runner_factory][@matcher] <<
-        Serf::Routing::Endpoint.new(
-          connected,
-          handler_factory,
-          *args,
-          &block)
-    end
-
-    ##
-    # DSL Method to change our current context to use the given runner.
-    #
-    def runner(type)
-      @runner_factory = case type
-      when :direct
-        ::Serf::Runners::Direct
-      when :event_machine
-        begin
-          require 'serf/runners/event_machine'
-          Serf::Runners::EventMachine
-        rescue NameError => e
-          e.extend Serf::Error
-          raise e
-        end
-      when :girl_friday
-        begin
-          require 'serf/runners/girl_friday'
-          Serf::Runners::GirlFriday
-        rescue NameError => e
-          e.extend Serf::Error
-          raise e
-        end
-      else
-        raise 'No callable runner' unless type.respond_to? :build
-        type
-      end
-    end
-
-    def params(*args)
-      @runner_params[@runner_factory] = args
+    def match(matcher)
+      @matcher = matcher
+      @policies = []
     end
 
     ##
-    # Returns a hash of our current serf infrastructure options
-    # to be passed to Endpoint#build methods.
-    def serf_options
-      {
-        response_channel: @response_channel,
-        error_channel: @error_channel,
-        logger: @logger
+    # @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
 
@@ -149,54 +141,26 @@ module Serf
     # Create our app.
     #
     def to_app
-      # By default, we go to the not_found app.
-      app = @not_found
-
-      registries = {}
-
-      # Set additional options for all the mounts
-      @runner_matcher_endpoint_map.each do |runner_factory, matcher_endpoints|
-
-        # 1. Create a registry for our given hash of matchers to endpoints.
-        # 2. Convert the hash of matcher to endpoints into a useable registry
-        #   for lookups.
-        registry = ::Serf::Routing::Registry.new
-        matcher_endpoints.each do |matcher, endpoints|
-          registry.add matcher, endpoints
-        end
-
-        # Ok, we'll create the runner and add it to our registries hash
-        # if we actually have endpoints here.
-        if registry.size > 0
-          runner_params = @runner_params[runner_factory] ?
-            @runner_params[runner_factory] :
-            []
-          runner_params << (runner_params.last.is_a?(Hash) ?
-            runner_params.pop.merge(serf_options) :
-            serf_options)
-          runner = runner_factory.build *runner_params
-          registries[runner] = registry
-        end
-      end
-
-      if registries.size > 0
-        app = Serf::Serfer.build(
-          # The registries to match, and their runners to execute.
-          registries: registries,
-          # App if no endpoints were found.
-          not_found: app,
-          # Serf infrastructure options to pass to 'connected' Endpoints
-          # to build a handler instance for each env hash received.
-          serf_options: serf_options,
-          # Options to use by serfer because it includes ErrorHandling.
-          error_channel: @error_channel,
-          logger: @logger)
+      # 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
     end
+
   end
 end

data/lib/serf/command.rb

@@ -1,8 +1,10 @@
 require 'active_support/concern'
 require 'active_support/core_ext/class/attribute'
 
-require 'serf/util/mash_factory'
+require 'serf/util/error_handling'
 require 'serf/util/options_extraction'
+require 'serf/util/protected_call'
+require 'serf/util/uuidable'
 
 module Serf
 
@@ -12,103 +14,64 @@ module Serf
   #   class MyCommand
   #     include Serf::Command
   #
-  #     # Set a default Message Parser for the class.
-  #     self.request_factory = MySerfRequestMessage
-  #
-  #     # Validate the request, like using JSON-Schema for hash
-  #     # (or Hashie's Mash) requests.
-  #     self.request_validator = MySerfRequestValidator
-  #
-  #     def initialize(*args, &block)
+  #     def initialize(*contructor_params, &block)
   #       # Do some validation here, or extra parameter setting with the args
+  #       @model = opts :model, MyModel
   #     end
   #
-  #     def call
-  #       # Do something w/ @request and @opts
-  #       return nil # e.g. MySerfMessage
+  #     def call(request, context)
+  #       # Do something w/ request, opts and context.
+  #       item = @model.find request.model_id
+  #       # create a new hashie of UUIDs, which we will use as the base
+  #       # hash of our response
+  #       response = create_uuids request
+  #       response.kind = 'my_command/events/did_something'
+  #       response.item = item
+  #       return response
   #     end
   #   end
   #
-  #   MyCommand.call(REQUEST_ENV, some, extra, params, options_hash, &block)
-  #
-  #   # Built in lambda wrapping to use the MyCommand with GirlFriday.
-  #   worker = MyCommand.worker some, extra, params, options_hash, &block
-  #   work_queue = GirlFriday::WorkQueue.new &worker
-  #   work_queue.push REQUEST_ENV
+  #   constructor_params = [1, 2, 3, 4, etc]
+  #   block = Proc.new {}
+  #   request = ::Hashie::Mash.new
+  #   context = ::Hashie::Mash.new user: current_user
+  #   MyCommand.call(request, context, *contructor_params, &block)
   #
   module Command
     extend ActiveSupport::Concern
-    include Serf::Util::OptionsExtraction
 
-    included do
-      class_attribute :request_factory
-      __send__ 'request_factory=', Serf::Util::MashFactory
-      class_attribute :request_validator
-      attr_reader :request
-    end
+    # Including Serf::Util::*... Order matters, kind of, here.
+    include Serf::Util::Uuidable
+    include Serf::Util::OptionsExtraction
+    include Serf::Util::ProtectedCall
+    include Serf::Util::ErrorHandling
 
-    def call
+    def call(request, context=nil *args, &block)
       raise NotImplementedError
     end
 
-    def validate_request!
-      request_validator.validate! request if request_validator
-    end
-
     module ClassMethods
 
       ##
       # Class method that both builds then executes the unit of work.
       #
-      def call(*args, &block)
-        self.build(*args, &block).call
+      # @param request the request
+      # @param context the context about the request. Things like the
+      #   requesting :user for ACL.
+      # @param *args remaining contructor arguments
+      # @param &block the block to pass to constructor
+      #
+      def call(request, context=::Hashie::Mash.new, *args, &block)
+        self.build(*args, &block).call(request, context)
       end
 
       ##
       # Factory build method that creates an object of the implementing
-      # class' unit of work with the given parameters.
+      # class' unit of work with the given parameters. By default,
+      # This just calls the class new method.
       #
       def build(*args, &block)
-        # The very first argument is the Request, we shift it off the args var.
-        req = args.shift
-        req = {} if req.nil?
-
-        # Now we allocate the object, and do some options extraction that may
-        # modify the args array by popping off the last element if it is a hash.
-        obj = allocate
-        obj.__send__ :extract_options!, args
-
-        # If the request was a hash, we MAY be able to convert it into a
-        # request object. We only do this if a request_factory was set either
-        # in the options, or if the request_factory class attribute is set.
-        # Otherwise, just give the command the hash, and it is up to them
-        # to understand what was given to it.
-        factory = obj.opts :request_factory, self.request_factory
-        request = (req.is_a?(Hash) && factory ? factory.build(req) : req)
-
-        # Set the request instance variable to whatever type of request we got.
-        obj.instance_variable_set :@request, request
-
-        # Finalize the object's construction with the rest of the args & block.
-        obj.__send__ :initialize, *args, &block
-
-        # Now validate that the request is ok.
-        # Implementing classes MAY override this method to do different
-        # kind of request validation.
-        obj.validate_request!
-
-        return obj
-      end
-
-      ##
-      # Generates a curried function to execute a Command's call class method.
-      #
-      # @returns lambda block to execute a call.
-      #
-      def worker(*args, &block)
-        lambda { |message|
-          self.call message, *args, &block
-        }
+        new *args, &block
       end
 
     end

data/lib/serf/errors/not_found.rb

@@ -0,0 +1,8 @@
+module Serf
+module Errors
+
+  class NotFound < RuntimeError
+  end
+
+end
+end

data/lib/serf/middleware/girl_friday_async.rb

@@ -0,0 +1,39 @@
+require 'girl_friday'
+
+require 'serf/util/options_extraction'
+require 'serf/util/uuidable'
+
+module Serf
+module Middleware
+
+  class GirlFridayAsync
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :uuidable
+    attr_reader :queue
+
+    def initialize(app, *args)
+      extract_options! args
+
+      @uuidable = opts :uuidable, Serf::Util::Uuidable
+
+      @queue = ::GirlFriday::WorkQueue.new(
+          opts(:name, :serf_runner),
+          :size => opts(:workers, 1)) do |env|
+        app.call env
+      end
+    end
+
+    def call(env)
+      queue.push env
+      response = uuidable.create_uuids env.message
+      response.kind = 'serf/messages/message_accepted_event'
+      response.message = env.message
+      response.context = env.context
+      return response
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/masherize.rb

@@ -0,0 +1,25 @@
+require 'hashie'
+
+module Serf
+module Middleware
+
+  ##
+  # Middleware to turn an env into a Hashie::Mash.
+  #
+  class Masherize
+
+    ##
+    # @param app the app
+    #
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call Hashie::Mash.new(env)
+    end
+
+  end
+
+end
+end

data/lib/serf/middleware/uuid_tagger.rb

@@ -4,26 +4,32 @@ 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
+  # 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.
   #
   class UuidTagger
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :uuidable
 
     ##
     # @param app the app
     # @options opts [String] :field the ENV field to set with a UUID.
     #
-    def initialize(app, options={})
+    def initialize(app, *args)
+      extract_options! args
       @app = app
-      @field = options.fetch(:field) { 'uuid' }
+      @uuidable = opts :uuidable, Serf::Util::Uuidable
     end
 
     def call(env)
-      env = env.dup
-      unless env[@field.to_sym] || env[@field.to_s]
-        env[@field] = Serf::Util::Uuidable.create_coded_uuid
-      end
+      message = env[:message]
+      message[:uuid] = uuidable.create_coded_uuid if message && !message[:uuid]
+
+      context = env[:context]
+      context[:uuid] = uuidable.create_coded_uuid if context && !context[:uuid]
+
       @app.call env
     end
 

data/lib/serf/{util → routing}/regexp_matcher.rb

@@ -1,5 +1,7 @@
+require 'serf/util/options_extraction'
+
 module Serf
-module Util
+module Routing
 
   ##
   # A matcher that does a regexp match on a specific field
@@ -7,20 +9,24 @@ module Util
   # on message kinds for routing.
   #
   class RegexpMatcher
+    include Serf::Util::OptionsExtraction
+
     attr_reader :regexp
     attr_reader :field
 
-    def initialize(regexp, options={})
+    def initialize(regexp, *args)
+      extract_options! args
+
       @regexp = regexp
-      @field = options.fetch(:field) { :kind }
+      @field = opts :field, :kind
     end
 
     def ===(env)
-      return @regexp === env[@field]
+      return regexp === env[field]
     end
 
-    def self.build(regexp)
-      return self.new regexp
+    def self.build(*args, &block)
+      new *args, &block
     end
 
   end

data/lib/serf/routing/route.rb

@@ -0,0 +1,35 @@
+require 'serf/util/options_extraction'
+
+module Serf
+module Routing
+
+  class Route
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :policies
+    attr_reader :command
+
+    def initialize(*args, &block)
+      extract_options! args
+      @policies = opts :policies, []
+      @command = opts! :command
+    end
+
+    def check_policies!(request, context)
+      for policy in policies do
+        policy.check! request, context
+      end
+    end
+
+    def execute!(*args, &block)
+      command.call *args, &block
+    end
+
+    def self.build(*args, &block)
+      new *args, &block
+    end
+
+  end
+
+end
+end

data/lib/serf/routing/route_set.rb

@@ -0,0 +1,64 @@
+require 'serf/routing/regexp_matcher'
+require 'serf/util/options_extraction'
+
+module Serf
+module Routing
+
+  ##
+  # RouteSet resolves a list of matched routes to execute based on
+  # criteria from associated 'matcher' objects.
+  #
+  class RouteSet
+    include Serf::Util::OptionsExtraction
+
+    attr_reader :routes
+    attr_reader :matchers
+    attr_reader :regexp_matcher_factory
+
+    def initialize(*args, &block)
+      extract_options! args
+      @routes = {}
+      @matchers = []
+      @regexp_matcher_factory = opts(
+        :regexp_matcher_factory,
+        ::Serf::Routing::RegexpMatcher)
+    end
+
+    ##
+    # Connects a matcher (String or an Object implementing ===) to routes.
+    #
+    def add(matcher, route)
+      # 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 = regexp_matcher_factory.build matcher if matcher.kind_of? Regexp
+      matchers << matcher unless matcher.is_a? String
+
+      # We add the (matcher+routes) into our routes
+      routes[matcher] ||= []
+      routes[matcher].push route
+    end
+
+    ##
+    # @param [Hash] request The input message to match for routes.
+    # @return [Array] List of routes that matched.
+    #
+    def resolve(request, context)
+      resolved_routes = []
+      resolved_routes.concat routes.fetch(request[:kind]) { [] }
+      matchers.each do |matcher|
+        resolved_routes.concat routes[matcher] if matcher === request
+      end
+      return resolved_routes
+    end
+
+    ##
+    # Default factory method.
+    #
+    def self.build(*args, &block)
+      new *args, &block
+    end
+  end
+
+end
+end