serf 0.14.0 → 0.15.0

data/.gitignore

@@ -1,10 +1,18 @@
-# Gemfile.lock because this is a library, not a deployable application.
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
 Gemfile.lock
+InstalledFiles
+_yardoc
 coverage
-rdoc
-doc
-.yardoc
-.bundle
-vendor
+doc/
+lib/bundler/man
 pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
 tmp
+vendor

data/.travis.yml

@@ -2,6 +2,8 @@ language: ruby
 rvm:
   - "1.9.2"
   - "1.9.3"
-  - jruby-19mode # JRuby in 1.9 mode
-  - rbx-19mode
+  - "jruby-19mode"
+  - "rbx-19mode"
+  - "ruby-head"
+  - "jruby-head"
 script: bundle exec rake spec

data/README.md

@@ -31,13 +31,20 @@ the Domain Layer's Model (Entities, Value Objects and Entity Gateways).
 
 1. Include the "Serf::Interactor" module in your class.
 2. Implement the 'call(parcel)' method.
-3. Return the tuple: (kind, message)
+3. Return the tuple: (kind, message, headers)
   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.
+    interactor's processing. The main meat of the Domain Object.
     Hashie::Mash is suggested for the message, nil is acceptable.
-  c. By default, returning nil for both kind and message will still
+  c. The headers are OPTIONAL. The headers are there primarily to return
+    out of band data about the processing of the request. For example,
+    the Interactor can return debug tags about connections to external
+    databases.
+    The *ONE* semantic relevant piece of information is that the
+    Interactor may specify the version the domain object, as represented
+    by the message of type 'kind', in the 'version' header field.
+  d. By default, returning nil for both kind and message will still
     result in a response parcel signifying that some Interactor received
     the inbound parcel. But that is just a almost worthless piece of
     information for the observer.
@@ -106,6 +113,7 @@ For example,
 Serf *RESERVES* the following set of header names:
 
 * kind
+* version
 * message
 * uuid
 * parent_uuid
@@ -134,6 +142,13 @@ may be used to route messages over messaging channels to Interactors.
 The convention is 'mymodule/requests/my_business_request' for Requests,
 and 'mymodule/events/my_business_event' for Events.
 
+*version* field MAY be used to identify the semantic version of the
+  message of the given 'kind'. The triplet of (kind, version, message)
+  constitutes the prime parts of domain object as represented by the
+  parcel. All other header fields are incidental data that pertain to
+  the processing. This field is optional, and is returned in the
+  headers portion of the interactor's return results.
+
 *UUIDs* are used to track request and events, providing a sequential
 order of execution of commands. Already Implemented by Serf middleware.
 
@@ -320,7 +335,9 @@ Serf Builder Example
         raise 'Error' if parcel.message.raise_an_error
 
         # And return a message as result. Nil is valid response.
-        return 'my_lib/events/success_event', { success: true }
+        return 'my_lib/events/success_event',
+          { success: true },
+          { version: "1.2.3" }
 
         # Optionally just return the kind
         # return 'my_lib/events/success_event'

data/lib/serf/builder.rb

@@ -28,19 +28,38 @@ module Serf
     ##
     # Set a default chain of the following:
     #
+    #   use_default_middleware
+    #   use_default_serfer_stage
+    #
+    def use_defaults
+      use_default_middleware
+      use_default_serfer_stage
+    end
+
+    ##
+    # Add the following middleware to the chain:
+    #
+    #   use Serf::Middleware::RequestTimer
     #   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
     #
-    def use_defaults
+    def use_default_middleware
       use Serf::Middleware::RequestTimer
       use Serf::Middleware::ParcelMasher
       use Serf::Middleware::UuidTagger
-      use Serf::Middleware::ParcelFreezer
       use Serf::Middleware::ErrorHandler
+    end
+
+    ##
+    # Add the following middleware to the chain:
+    #
+    #   use Serf::Middleware::ParcelFreezer
+    #   use Serf::Middleware::PolicyChecker, @policy_chain
+    #   use Serf::Serfer
+    #
+    def use_default_serfer_stage
+      use Serf::Middleware::ParcelFreezer
       use Serf::Middleware::PolicyChecker, policy_chain: @policy_chain
       use Serf::Serfer
     end

data/lib/serf/errors/load_failure.rb

@@ -0,0 +1,17 @@
+module Serf
+module Errors
+
+  ##
+  # An error occurred while loading serfs.
+  #
+  class LoadFailure < RuntimeError
+    attr_accessor :cause
+
+    def initialize(message=nil, cause=nil)
+      @cause = cause
+      super(message)
+    end
+  end
+
+end
+end

data/lib/serf/loader/loader.rb

@@ -2,6 +2,7 @@ require 'hashie'
 require 'optser'
 
 require 'serf/builder'
+require 'serf/errors/load_failure'
 require 'serf/loader/registry'
 
 module Serf
@@ -63,9 +64,13 @@ module Loader
       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)
+          begin
+            File.open filename do |file|
+              contents = file.read
+              instance_eval(contents)
+            end
+          rescue => e
+            raise Serf::Errors::LoadFailure.new "File: #{filename}", e
           end
         end
       end
@@ -73,7 +78,11 @@ module Loader
       # Construct all the "serfs"
       map = Hashie::Mash.new
       serfs.each do |serf|
-        map[serf] = @registry[serf]
+        begin
+          map[serf] = @registry[serf]
+        rescue => e
+          raise Serf::Errors::LoadFailure.new "Kind: #{serf}", e
+        end
         raise "Missing Serf: #{serf}" if map[serf].nil?
       end
 

data/lib/serf/loader/registry.rb

@@ -1,6 +1,8 @@
 require 'hashie'
 require 'optser'
 
+require 'serf/errors/load_failure'
+
 module Serf
 module Loader
 
@@ -47,6 +49,7 @@ module Loader
   class Registry
     attr_reader :blocks
     attr_reader :values
+    attr_reader :env
 
     def initialize(*args)
       opts = Optser.extract_options! args
@@ -62,7 +65,7 @@ module Loader
     # @params &block the proc that generates the component instance.
     #
     def add(name, &block)
-      @blocks[name.to_sym] = block
+      blocks[name.to_sym] = block
     end
 
     ##
@@ -73,11 +76,18 @@ module Loader
     #
     def [](name)
       name = name.to_sym
-      return @values[name] if @values.has_key? name
+      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
+      if block = blocks[name]
+        begin
+          value = block.call self, env
+          values[name] = value
+          blocks.delete name
+          return value
+        rescue => e
+          raise Serf::Errors::LoadFailure.new("Name: #{name}", e)
+        end
       end
     end
 

data/lib/serf/serfer.rb

@@ -26,16 +26,29 @@ module Serf
     #
     def call(parcel)
       # 1. Execute interactor
-      response_kind, response_message = interactor.call parcel
-
-      # 2. Return a new response parcel with:
+      response_kind, response_message, response_headers = interactor.call parcel
+
+      # 2. Extract a possible version embedded in the response_kind.
+      #   This is sugar syntax for kind and version.
+      if response_kind
+        kind_part, version_part = response_kind.split '#', 2
+        response_kind = kind_part if version_part
+        if version_part
+          response_headers ||= {}
+          response_headers[:version] = version_part
+        end
+      end
+
+      # 3. Return a new response parcel with:
       #   a. uuids set from parent parcel
       #   b. kind set to response kind
       #   c. the message set to response_message
+      #   d. add extra headers to the parcel
       return parcel_factory.create(
         parent: parcel,
         kind: response_kind,
-        message: response_message)
+        message: response_message,
+        headers: response_headers)
     end
 
   end

data/lib/serf/util/error_handling.rb

@@ -1,3 +1,5 @@
+require 'socket'
+
 require 'serf/util/protected_call'
 
 module Serf
@@ -31,6 +33,7 @@ module Util
         error: e.class.to_s,
         message: e.message,
         process_env: ENV.to_hash,
+        hostname: Socket.gethostname,
         backtrace: e.backtrace.join("\n")
       }
     end

data/lib/serf/util/uuidable.rb

@@ -42,6 +42,18 @@ module Util
       uuid_tool.parse_raw Base64.urlsafe_decode64("#{coded_uuid}==")
     end
 
+    ##
+    # Parses a coded_uuid and returns a time object for the Timestamped UUID.
+    #
+    # @param coded_uuid the coded uuid from which to get a time.
+    #
+    # @return ruby time object for which the coded_uuid was timestamped.
+    #
+    def coded_uuid_time(coded_uuid)
+      uuid = parse_coded_uuid coded_uuid
+      uuid.timestamp.utc
+    end
+
     ##
     # Create a new set of uuids.
     #

data/lib/serf/version.rb

@@ -1,11 +1,3 @@
 module Serf
-
-  module Version
-    MAJOR = 0
-    MINOR = 14
-    PATCH = 0
-    BUILD = nil
-    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join '.'
-  end
-
+  VERSION = '0.15.0'
 end

data/schemas/serf/events/caught_error.json

@@ -3,16 +3,29 @@
   "type": "object",
   "properties": {
     "error": {
-      "type": "string"
+      "description": "The error class",
+      "type": "string",
+      "required": true
     },
     "message": {
-      "type": "string"
+      "description": "The description of the error",
+      "type": "string",
+      "required": true
     },
     "process_env": {
-      "type": "object"
+      "description": "The ENV context of the error",
+      "type": "object",
+      "required": true
+    },
+    "hostname": {
+      "description": "The hostname of the process of the error",
+      "type": "string",
+      "required": true
     },
     "backtrace": {
-      "type": "string"
+      "description": "The backtrace of the error",
+      "type": "string",
+      "required": true
     }
   }
 }

data/serf.gemspec

@@ -1,9 +1,11 @@
 # -*- encoding: utf-8 -*-
-require File.expand_path('../lib/serf/version', __FILE__)
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'serf/version'
 
 Gem::Specification.new do |gem|
   gem.name        = 'serf'
-  gem.version     = Serf::Version::STRING
+  gem.version     = Serf::VERSION
   gem.authors     = ['Benjamin Yu']
   gem.email       = 'benjaminlyu@gmail.com'
   gem.description = 'Interactors with policy protection'

data/spec/data/construction_error.serf

@@ -0,0 +1,3 @@
+registry.add 'spec/data/bad_construction' do |r, env|
+  raise 'Intentional Construction Error'
+end

data/spec/data/raises_error.serf

@@ -0,0 +1 @@
+raise 'Intentional Error'

data/spec/serf/loader/loader_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 
+require 'serf/errors/load_failure'
 require 'serf/loader/loader'
 
 describe Serf::Loader::Loader do
@@ -14,7 +15,8 @@ describe Serf::Loader::Loader do
     subject {
       Serf::Loader::Loader.new.serfup(
         globs: [
-          'example/**/*.serf'
+          'example/components/**/*.serf',
+          'example/serfs/**/*.serf'
         ],
         serfs: [
           'subsystem/requests/create_widget'
@@ -70,4 +72,44 @@ describe Serf::Loader::Loader do
     end
   end
 
+  context '#serfup with construction error' do
+    let(:serfup_config) {
+      Hashie::Mash.new(
+        globs: [
+          'spec/data/construction_error.serf'
+        ],
+        serfs: [
+          'spec/data/bad_construction'
+        ])
+    }
+
+    it 'raises an error' do
+      expect {
+        Serf::Loader::Loader.new.serfup serfup_config
+      }.to raise_error { |error|
+        expect(error).to be_a(Serf::Errors::LoadFailure)
+        expect(error.message).to match(/Kind: .+$/)
+      }
+    end
+  end
+
+  context '#serfup Serf Map bad serf file' do
+    let(:serfup_config) {
+      Hashie::Mash.new(
+        globs: [
+          'spec/data/raises_error.serf'
+        ],
+        serfs: [])
+    }
+
+    it 'raises an error' do
+      expect {
+        Serf::Loader::Loader.new.serfup serfup_config
+      }.to raise_error { |error|
+        expect(error).to be_a(Serf::Errors::LoadFailure)
+        expect(error.message).to match(/^File: .+$/)
+      }
+    end
+  end
+
 end

data/spec/serf/loader/registry_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 
+require 'serf/errors/load_failure'
 require 'serf/loader/registry'
 
 describe Serf::Loader::Registry do
@@ -59,4 +60,18 @@ describe Serf::Loader::Registry do
     end
   end
 
+  context '#[] with error' do
+    it 'raises LoadFailure on error' do
+      subject.add 'component_name' do
+        raise 'Intentional Error'
+      end
+      expect {
+        subject['component_name']
+      }.to raise_error { |error|
+        expect(error).to be_a(Serf::Errors::LoadFailure)
+        expect(error.message).to match(/^Name: .+$/)
+      }
+    end
+  end
+
 end

data/spec/serf/loader_spec.rb

@@ -14,7 +14,8 @@ describe Serf::Loader do
     subject {
       Serf::Loader.serfup(
         globs: [
-          'example/**/*.serf'
+          'example/components/**/*.serf',
+          'example/serfs/**/*.serf'
         ],
         serfs: [
           'subsystem/requests/create_widget'

data/spec/serf/serfer_spec.rb

@@ -11,12 +11,21 @@ describe Serf::Serfer do
     let(:request_parcel) {
       FactoryGirl.create :random_parcel
     }
+    let(:versioned_response_kind_version) {
+      SecureRandom.hex
+    }
+    let(:versioned_response_kind) {
+      "#{response_kind}\##{versioned_response_kind_version}"
+    }
     let(:response_kind) {
       SecureRandom.hex
     }
     let(:response_message) {
       FactoryGirl.create :random_hash
     }
+    let(:response_headers) {
+      FactoryGirl.create :random_hash
+    }
     let(:disconnected_response_parcel) {
       FactoryGirl.create :random_parcel
     }
@@ -49,14 +58,55 @@ describe Serf::Serfer do
       expect(parcel.message).to eq(response_message)
     end
 
-    it 'uses parcel factory w/ kind, parent and message' do
+    it 'uses parcel factory w/ parent (w/ nil kind+message+headers)' do
+      mock_parcel_factory = double 'parcel_factory'
+      mock_parcel_factory.
+        should_receive(:create).
+        with({
+          parent: request_parcel,
+          kind: nil,
+          message: nil,
+          headers: nil
+        }).
+        and_return(disconnected_response_parcel)
+
+      serfer = described_class.new(
+        lambda { |obj| },
+        parcel_factory: mock_parcel_factory)
+      parcel = serfer.call request_parcel
+
+      expect(parcel).to eq(disconnected_response_parcel)
+    end
+
+    it 'uses parcel factory w/ kind, parent (w/ nil message+headers)' do
+      mock_parcel_factory = double 'parcel_factory'
+      mock_parcel_factory.
+        should_receive(:create).
+        with({
+          parent: request_parcel,
+          kind: response_kind,
+          message: nil,
+          headers: nil
+        }).
+        and_return(disconnected_response_parcel)
+
+      serfer = described_class.new(
+        lambda { |obj| return response_kind },
+        parcel_factory: mock_parcel_factory)
+      parcel = serfer.call request_parcel
+
+      expect(parcel).to eq(disconnected_response_parcel)
+    end
+
+    it 'uses parcel factory w/ kind, parent and message (w/ nil headers)' do
       mock_parcel_factory = double 'parcel_factory'
       mock_parcel_factory.
         should_receive(:create).
         with({
           parent: request_parcel,
           kind: response_kind,
-          message: response_message
+          message: response_message,
+          headers: nil
         }).
         and_return(disconnected_response_parcel)
 
@@ -68,6 +118,52 @@ describe Serf::Serfer do
       expect(parcel).to eq(disconnected_response_parcel)
     end
 
+    it 'uses parcel factory w/ kind, parent, message and headers' do
+      mock_parcel_factory = double 'parcel_factory'
+      mock_parcel_factory.
+        should_receive(:create).
+        with({
+          parent: request_parcel,
+          kind: response_kind,
+          message: response_message,
+          headers: response_headers
+        }).
+        and_return(disconnected_response_parcel)
+
+      serfer = described_class.new(
+        lambda { |obj|
+          return response_kind, response_message, response_headers
+        },
+        parcel_factory: mock_parcel_factory)
+      parcel = serfer.call request_parcel
+
+      expect(parcel).to eq(disconnected_response_parcel)
+    end
+
+    it 'moves version info from a versioned kind to the headers' do
+      mock_parcel_factory = double 'parcel_factory'
+      mock_parcel_factory.
+        should_receive(:create).
+        with({
+          parent: request_parcel,
+          kind: response_kind,
+          message: response_message,
+          headers: {
+            version: versioned_response_kind_version
+          }
+        }).
+        and_return(disconnected_response_parcel)
+
+      serfer = described_class.new(
+        lambda { |obj|
+          return versioned_response_kind, response_message
+        },
+        parcel_factory: mock_parcel_factory)
+      parcel = serfer.call request_parcel
+
+      expect(parcel).to eq(disconnected_response_parcel)
+    end
+
   end
 
 end

data/spec/serf/util/error_handling_spec.rb

@@ -12,7 +12,12 @@ describe Serf::Util::ErrorHandling do
       expect(result).to be_nil
       JsonSchemaTester.new.validate_for!(
         'serf/events/caught_error',
-        error)
+        Hashie::Mash.new(error))
+      expect(error[:error]).to be_kind_of(String)
+      expect(error[:message]).to be_kind_of(String)
+      expect(error[:process_env]).to be_kind_of(Hash)
+      expect(error[:hostname]).to be_kind_of(String)
+      expect(error[:backtrace]).to be_kind_of(String)
     end
 
   end

data/spec/serf/util/uuidable_spec.rb

@@ -21,6 +21,26 @@ describe Serf::Util::Uuidable do
 
   end
 
+  describe '#coded_uuid_time' do
+    let(:coded_uuid) {
+      'RIEHuF5-EeKLPQQMzuOZ7g'
+    }
+    let(:time_seconds) {
+      1358190718
+    }
+    let(:time_usec) {
+      273324
+    }
+
+    it 'returns a valid time object' do
+      time = subject.coded_uuid_time coded_uuid
+      # Check that we have a good timestamp in seconds and nanoseconds
+      expect(time.to_i).to eq(time_seconds)
+      expect(time.tv_usec).to eq(time_usec)
+    end
+
+  end
+
   describe '#create_uuids' do
 
     it 'works with no parent' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serf
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-03 00:00:00.000000000 Z
+date: 2013-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -96,6 +96,7 @@ files:
 - example/serfs/create_widget.serf
 - lib/serf.rb
 - lib/serf/builder.rb
+- lib/serf/errors/load_failure.rb
 - lib/serf/errors/policy_failure.rb
 - lib/serf/loader.rb
 - lib/serf/loader/loader.rb
@@ -115,6 +116,8 @@ files:
 - lib/serf/version.rb
 - schemas/serf/events/caught_error.json
 - serf.gemspec
+- spec/data/construction_error.serf
+- spec/data/raises_error.serf
 - spec/serf/builder_spec.rb
 - spec/serf/errors/policy_failure_spec.rb
 - spec/serf/loader/loader_spec.rb
@@ -155,7 +158,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3964117889067138578
+      hash: 526665702158101187
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -164,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3964117889067138578
+      hash: 526665702158101187
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -172,6 +175,8 @@ signing_key:
 specification_version: 3
 summary: Interactors with policy protection
 test_files:
+- spec/data/construction_error.serf
+- spec/data/raises_error.serf
 - spec/serf/builder_spec.rb
 - spec/serf/errors/policy_failure_spec.rb
 - spec/serf/loader/loader_spec.rb