serf 0.11.0 → 0.12.0

data/Gemfile

@@ -26,4 +26,5 @@ group :development, :test do
 
   # Required by our Specs
   gem 'json-schema'
+  gem 'yell'
 end

data/Guardfile

@@ -2,8 +2,7 @@ guard(
     :rspec,
     cli: '--format Fuubar --color',
     all_on_start: true,
-    all_after_pass: false,
-    :version => 2) do
+    all_after_pass: false) do
 
   # Watch our specs
   watch(%r{^spec/.+_spec\.rb$})

data/README.md

@@ -3,6 +3,14 @@ serf
 
 Code your Interactors with policy protection.
 
+Serf (a Serf App) -- an individual rack-like call chain.
+* Interactors define your business logic
+* Policies decide access
+* Middleware augment the request processing
+
+Serf Map -- a set of Serfs.
+* A registry of Serfs, mapped by the parcel kinds.
+
 Serf Links
 ----------
 
@@ -23,10 +31,18 @@ the Domain Layer's Entities (Value Objects and Entity Gateways).
 
 1. Include the "Serf::Interactor" module in your class.
 2. Implement the 'call(message)' method.
-3. Return the tuple: (message, kind)
-  a. Hashie::Mash is recommended for the message, nil is acceptable
-  b. The kind is the string representation of the message type,
-    It is optional.
+3. Return the tuple: (kind, message)
+  a. The kind is the string representation of the message type,
+    This field is RECOMMENDED.
+  b. The message field provides detailed return data about the
+    interactor's processing.
+    Hashie::Mash is suggested for the message, nil is acceptable.
+
+The reason that the interactor SHOULD return a kind is to properly
+identify the semantic meaning of the returned message, even if
+said returned message is empty. This also assists the handling
+of response parcels in other pipelines without the need to
+introspect the parcel's message.
 
 Example:
 
@@ -49,7 +65,7 @@ Example:
         response = Hashie::Mash.new
         response.item = item
         # Return the response 'kind' and the response data.
-        return response, 'my_app/events/did_something'
+        return 'my_app/events/did_something', response
       end
     end
 
@@ -127,6 +143,23 @@ Policies only need to implement a single method:
   RECOMMENDED: Use `Serf::Errors::PolicyFailure` error type.
 
 
+Thread Safety
+-------------
+
+Yes and No, it depends:
+* Serf Middleware and Serf Utils are all *Thread Safe* by default.
+  It may not be the case if thread unsafe options are passed in the
+  instantiation of these objects.
+* Built Serfs are *Thread Safe* **if** the developer took care
+  in the creation of the Interactors and in the dependency injection
+  wiring of the Serfs by the builder and loader.
+* The Builder and Loader are *Thread UNSAFE* because it just doesn't make
+  sense that multiple threads should compete/coordinate in the creation
+  and wiring of the created Serfs (Serf Apps) and Serf Maps.
+  This is usually done at start up by the main thread.
+  This includes the utility classes that the loader uses.
+
+
 References
 ==========
 
@@ -190,8 +223,8 @@ The Domain Layer (from DDD):
     and "Application Agnostic Logic" in Entities.
 
 
-Example
-=======
+Serf Builder Example
+====================
 
     # Require our libraries
     require 'json'
@@ -218,16 +251,16 @@ Example
         raise 'Error' if message.raise_an_error
 
         # And return a message as result. Nil is valid response.
-        return { success: true }, 'my_lib/events/success_event'
+        return 'my_lib/events/success_event', { success: true }
 
-        # Optionally just return the message w/o a tagged kind
-        #return { success: true }
+        # Optionally just return the kind
+        # return 'my_lib/events/success_event'
       end
 
     end
 
-    # Create a new builder for this serf app.
-    app = Serf::Builder.new(
+    # Create a new builder for this Serf (aka Serf App).
+    serf = Serf::Builder.new(
       interactor: MyInteractor.new,
       policy_chain: [
         MyPolicy.new
@@ -236,11 +269,11 @@ Example
     # This will submit a 'my_message' message (as a hash) to Serfer.
     # Missing data field will raise an error within the interactor, which
     # will be caught by the serfer.
-    results = app.call nil
+    results = serf.call nil
     my_logger.info "Call 1: #{results.to_json}"
 
     # Here is good result
-    results = app.call(
+    results = serf.call(
       headers: {
         user: 'user_info_1'
       },
@@ -249,7 +282,7 @@ Example
     my_logger.info "Call 2: #{results.to_json}"
 
     # Here get an error that was raised from the interactor
-    results = app.call(
+    results = serf.call(
       headers: {
         user: 'user_info_1'
       },
@@ -259,6 +292,89 @@ Example
     my_logger.info "Call 3: #{results.to_json}"
 
 
+Serf Loader Example
+===================
+
+Look inside the example subdirectory for the serf files in this example.
+
+
+    ####
+    ## File: example/serfs/create_widget.serf
+    ####
+
+    require 'json'
+    # require 'subsystem/commands/my_create_widget'
+    # Throwing in this class definition to make example work
+    class MyCreateWidget
+
+      def initialize(logger, success_message)
+        @logger = logger
+        @success_message = success_message
+      end
+
+      def call(parcel)
+        @logger.info "In My Create Widget, creating a widget: #{parcel.to_json}"
+        return 'subsystem/events/mywidget_created',
+          { success_message: @success_message }
+      end
+    end
+
+    ##
+    # Registers a serf that responds to a parcel with the given request "kind".
+    # The interactor is instantiated by asking for other components in the
+    # registry and for parameters set in the environment variable.
+    registry.add 'subsystem/requests/create_widget' do |r, env|
+      serf interactor: MyCreateWidget.new(r[:logger], env[:success_message])
+    end
+
+
+    ####
+    ## In another ruby script, where we may load and use serfs.
+    ####
+
+    require 'hashie'
+    require 'json'
+    require 'yell'
+
+    require 'serf/loader'
+
+    # Making a logger for the top level example
+    logger = Yell.new STDOUT
+
+    # Globs to search for serf files
+    globs = [
+      'example/**/*.serf'
+    ]
+    # The serf requests that the loaded Serf Map will handle.
+    serfs = [
+      'subsystem/requests/create_widget'
+    ]
+    # A simple environment variables hash, runtime configuration
+    env = Hashie::Mash.new(
+      success_message: 'Some environment variable like redis URL'
+    )
+
+    # Loading the configuration, creating the serfs.
+    serf_map = Serf::Loader.serfup globs: globs, serfs: serfs, env: env
+
+    # Make an example request parcel
+    request_parcel = {
+      headers: {
+        kind: 'subsystem/requests/create_widget'
+      },
+      message: {
+        name: 'some widget name'
+      }
+    }
+
+    #
+    # Look up the create widget serf by a request kind name,
+    # execute the serf, and log the results
+    serf = serf_map[request_parcel[:headers][:kind]]
+    results = serf.call request_parcel
+    logger.info results.to_json
+
+
 Contributing
 ============
 

data/example/components/logger.serf

@@ -0,0 +1,7 @@
+require 'yell'
+
+##
+# This is the registration of a component
+registry.add 'logger' do |r|
+  Yell.new STDOUT
+end

data/example/serfs/create_widget.serf

@@ -0,0 +1,24 @@
+require 'json'
+# require 'subsystem/commands/my_create_widget'
+# Throwing in this class definition to make example work
+class MyCreateWidget
+
+  def initialize(logger, success_message)
+    @logger = logger
+    @success_message = success_message
+  end
+
+  def call(parcel)
+    @logger.info "In My Create Widget, creating a widget: #{parcel.to_json}"
+    return 'subsystem/events/mywidget_created',
+      { success_message: @success_message }
+  end
+end
+
+##
+# Registers a serf that responds to a parcel with the given request "kind".
+# The interactor is instantiated by asking for other components in the
+# registry and for parameters set in the environment variable.
+registry.add 'subsystem/requests/create_widget' do |r, env|
+  serf interactor: MyCreateWidget.new(r[:logger], env[:success_message])
+end

data/lib/serf/builder.rb

@@ -1,22 +1,22 @@
+require 'optser'
+
 require 'serf/middleware/error_handler'
 require 'serf/middleware/parcel_freezer'
 require 'serf/middleware/parcel_masher'
 require 'serf/middleware/policy_checker'
+require 'serf/middleware/request_timer'
 require 'serf/middleware/uuid_tagger'
 require 'serf/serfer'
-require 'serf/util/options_extraction'
 
 module Serf
 
   class Builder
-    include Serf::Util::OptionsExtraction
-
     def initialize(*args, &block)
-      extract_options! args
+      opts = Optser.extract_options! args
 
-      @run = opts :interactor
+      @run = opts.get :interactor
       @use = []
-      @policy_chain = opts :policy_chain, []
+      @policy_chain = opts.get :policy_chain, []
 
       if block_given?
         instance_eval(&block)
@@ -36,6 +36,7 @@ module Serf
     #   use Serf::Serfer
     #
     def use_defaults
+      use Serf::Middleware::RequestTimer
       use Serf::Middleware::ParcelMasher
       use Serf::Middleware::UuidTagger
       use Serf::Middleware::ParcelFreezer

data/lib/serf/loader.rb

@@ -0,0 +1,16 @@
+require 'serf/loader/loader'
+
+module Serf
+
+  module Loader
+
+    ##
+    # @see Serf::Loader::Loader
+    #
+    def self.serfup(*args)
+      Serf::Loader::Loader.new.serfup *args
+    end
+
+  end
+
+end

data/lib/serf/loader/loader.rb

@@ -0,0 +1,103 @@
+require 'hashie'
+require 'optser'
+
+require 'serf/builder'
+require 'serf/loader/registry'
+
+module Serf
+module Loader
+
+  ##
+  # The main loader that takes a serfup configuration file and instance evals
+  # all the registered components and serfs, which populates the
+  # serfup loader registry; then returns a mapping of serf kind names to
+  # the instantiated serfs.
+  #
+  class Loader
+
+    def initialize(*args)
+      opts = Optser.extract_options! args
+      @registry_class = opts.get :registry_class, Serf::Loader::Registry
+      @builder_class = opts.get :builder_class, Serf::Builder
+    end
+
+    ##
+    # Loads up the components defined in a serfup configuration, wires up all
+    # the "exposed" serfs and returns them in a frozen map.
+    #
+    # Example Config:
+    #
+    #   # Config is a simple hash
+    #   config = Hashie::Mash.new
+    #   # List out the globbed filenames to load up.
+    #   config.globs = [
+    #     'example/**/*.serf'
+    #   ]
+    #   # List out the parcel kinds that we need to have serfs built up
+    #   # and exposed in the returned Serf Map.
+    #   config.serfs = [
+    #     'subsystem/requests/create_widget'
+    #   ]
+    #
+    # Example Env Hash:
+    #
+    #   env = Hashie::Mash.new
+    #   env.web_service = 'http://example.com/'
+    #
+    # @param [Hash] opts env and basepath options
+    # @option opts [Array] :globs list of file globs to load serf configs
+    # @option opts [Array] :serfs list of serfs to export in Serf Map.
+    # @option opts [String] :base_path root of where to run the config
+    # @option opts [Hash] :env environmental variables for runtime config
+    # @returns a frozen Serf Map of request parcel kind to serf.
+    #
+    def serfup(*args)
+      opts = Optser.extract_options! args
+      globs = opts.get! :globs
+      serfs = opts.get! :serfs
+      base_path = opts.get :base_path, '.'
+      env = opts.get(:env) { Hashie::Mash.new }
+      @registry = @registry_class.new env: env
+
+      # Load in all the components listed
+      globs.each do |glob_pattern|
+        globs = Dir.glob File.join(base_path, glob_pattern)
+        globs.each do |filename|
+          File.open filename do |file|
+            contents = file.read
+            instance_eval(contents)
+          end
+        end
+      end
+
+      # Construct all the "serfs"
+      map = Hashie::Mash.new
+      serfs.each do |serf|
+        map[serf] = @registry[serf]
+        raise "Missing Serf: #{serf}" if map[serf].nil?
+      end
+
+      # return a frozen registry, clear the registry
+      @registry = nil
+      map.freeze
+      return map
+    end
+
+    private
+
+    ##
+    # Registry attr_reader for serf files to access in the instance eval.
+    def registry
+      @registry
+    end
+
+    ##
+    # Registry attr_reader for serf files to define a builder's work.
+    def serf(*args, &block)
+      @builder_class.new(*args, &block).to_app
+    end
+
+  end
+
+end
+end

data/lib/serf/loader/registry.rb

@@ -0,0 +1,86 @@
+require 'hashie'
+
+module Serf
+module Loader
+
+  ##
+  # A Registry of components that can then be wired up
+  # dependency injection style using the Service Locator Pattern.
+  # Components are lazily evaluated and memoized. Thus all components
+  # are singletons.
+  #
+  #     # Create a new registry
+  #     registry = Registry.new
+  #
+  #     # Registers a component
+  #     registry.add 'a_comp' do |r|
+  #       12345
+  #     end
+  #
+  #     # Registers b component that uses a component
+  #     registry.add 'b_comp' do |r|
+  #       {
+  #         a_value: r['a_comp']
+  #       }
+  #     end
+  #
+  #     # Registers a Serf app (serf is helper to make and execute
+  #     # a Serf::Builder), using the long form builder DSL.
+  #     registry.add 'subsystem/request/my_request' do |r|
+  #       # Register a serf to handle this request
+  #       serf do
+  #         use_defaults
+  #         run MyInteractor.new(b_comp: r['b_comp'])
+  #       end
+  #     end
+  #
+  #     # Now obtain the build serf, all wired up, by the parcel kind
+  #     # and execute the found serf.
+  #     parcel = {
+  #       headers: { kind: 'subsystem/request/my_request' },
+  #       message: {}
+  #     }
+  #     serf = registry[parcel[:headers][:kind]]
+  #     puts serf.call(parcel)
+  #
+  class Registry
+    attr_reader :blocks
+    attr_reader :values
+
+    def initialize(*args)
+      opts = Optser.extract_options! args
+      @blocks = {}
+      @values = {}
+      @env = opts.get(:env) { Hashie::Mash.new }
+    end
+
+    ##
+    # Adds a component to the registry.
+    #
+    # @params name the registration name of the component.
+    # @params &block the proc that generates the component instance.
+    #
+    def add(name, &block)
+      @blocks[name.to_sym] = block
+    end
+
+    ##
+    # Looks up a component instance by name.
+    #
+    # @params name the name of the component.
+    # @returns the singleton instance of the component.
+    #
+    def [](name)
+      name = name.to_sym
+      return @values[name] if @values.has_key? name
+      # No memoized value, so grab the block, call it and memoize it
+      # return the block's return value, or nil.
+      if block = @blocks.delete(name)
+        @values[name] = block.call self, @env
+      end
+    end
+
+  end
+
+end
+end