light-service 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc46d59ad8bc4839942dc2977961ce978bae275f
-  data.tar.gz: a2ca45e8cb9987ab44dfe5af7080dd45a943efc7
+  metadata.gz: 41c85f3b70d95380e2e7aa2c289f089b5415c357
+  data.tar.gz: 66e9cb452320935e674a1f1250db139b8a7927ed
 SHA512:
-  metadata.gz: 061d0554efd265aa95e83cd7197e24aa12207ea3c4119d297bbd036bc9ed15c5be44af52bcb9b00975b3d0a779f039a1008d6efae6d2ceffa562b65ce9f0cbf0
-  data.tar.gz: 66fe3f85032dc702b60edcb69cab36a2c6a6bd088f2f04a92a2554aff016d58889092f49baded959e6b161a3bd0490285ce0cc95de54647218cfb6d642ad7087
+  metadata.gz: 5783a1a16b678ad68c7352c74a75c506f8b1c3c41e25b43fa77e154f818a04bcff3a6adc641dd3bba779e6fd6cfe319916f4d1c4e3eacd8c06a192705b16a8ce
+  data.tar.gz: 0ce7a0c69be92173956db9280aac103654e961913242056c7a7a56264b6b2d22bf3322c764c5ea5d7188a09ebdac0b87de4100e62f0a35ba5508fd37ceffdb8a

data/README.md

@@ -200,6 +200,71 @@ end
 
 Take a look at [this spec](spec/action_expects_and_promises_spec.rb) to see the refactoring in action.
 
+## Logging
+
+Enable LightService's logging to better understand what goes on within the series of actions,
+what's in the context or when an action fails.
+
+Logging in LightService is turned off by default. However, turning it on is simple. Add this line to your
+project's config file:
+
+```ruby
+LightService::Configuration.logger = Logger.new(STDOUT)
+```
+
+You can turn off the logger by setting it to nil or `/dev/null`.
+
+```ruby
+LightService::Configuration.logger = Logger.new('/dev/null')
+```
+
+In case you're using LightService with Rails, feel free use Rails logger for LightService:
+
+```ruby
+LightService::Configuration.logger = Rails.logger # or config.logger in one of the config files
+```
+
+Watch the console while you are executing the workflow through the organizer. You should see something like this:
+
+```bash
+I, [DATE]  INFO -- : [LightService] - calling organizer <TestDoubles::MakesTeaAndCappuccino>
+I, [DATE]  INFO -- : [LightService] -     keys in context: :tea, :milk, :coffee
+I, [DATE]  INFO -- : [LightService] - executing <TestDoubles::MakesTeaWithMilkAction>
+I, [DATE]  INFO -- : [LightService] -   expects: :tea, :milk
+I, [DATE]  INFO -- : [LightService] -   promises: :milk_tea
+I, [DATE]  INFO -- : [LightService] -     keys in context: :tea, :milk, :coffee, :milk_tea
+I, [DATE]  INFO -- : [LightService] - executing <TestDoubles::MakesLatteAction>
+I, [DATE]  INFO -- : [LightService] -   expects: :coffee, :milk
+I, [DATE]  INFO -- : [LightService] -   promises: :latte
+I, [DATE]  INFO -- : [LightService] -     keys in context: :tea, :milk, :coffee, :milk_tea, :latte
+```
+
+The log provides a blueprint of the series of actions. You can see what organizer is invoked, what actions
+are called in what order, what do the expect and promise and most importantly what keys you have in the context
+after each action is executed.
+
+The logger logs its messages with "INFO" level. The exception to this is the event when an action fails the context.
+That message is logged with "WARN" level:
+
+```bash
+I, [DATE]  INFO -- : [LightService] - calling organizer <TestDoubles::MakesCappuccinoAddsTwoAndFails>
+I, [DATE]  INFO -- : [LightService] -     keys in context: :milk, :coffee
+W, [DATE]  WARN -- : [LightService] - :-((( <TestDoubles::MakesLatteAction> has failed...
+W, [DATE]  WARN -- : [LightService] - context message: Can't make a latte from a milk that's too hot!
+```
+
+The log message will show you what message was added to the context when the action pushed the
+context into a failure state.
+
+The event of skipping the rest of the actions is also captured by its logs:
+
+```bash
+I, [DATE]  INFO -- : [LightService] - calling organizer <TestDoubles::MakesCappuccinoSkipsAddsTwo>
+I, [DATE]  INFO -- : [LightService] -     keys in context: :milk, :coffee
+I, [DATE]  INFO -- : [LightService] - ;-) <TestDoubles::MakesLatteAction> has decided to skip the rest of the actions
+I, [DATE]  INFO -- : [LightService] - context message: Can't make a latte with a fatty milk like that!
+```
+
 ## Error Codes
 
 You can add some more structure to your error handling by taking advantage of error codes in the context.
@@ -273,40 +338,8 @@ For further examples, please visit the project's [Wiki](https://github.com/adomo
 Huge thanks to the [contributors](https://github.com/adomokos/light-service/graphs/contributors)!
 
 ## Release Notes
-### 0.3.6
-* [Collecting](https://github.com/adomokos/light-service/commit/29817de3ad589441788077368ad1d7e723286def) the `expects` and `promises` keys when they are called multiple times in an action
-
-### 0.3.5
-* remove previously deprecated method Context#context_hash
-* [Skipping](https://github.com/adomokos/light-service/commit/d2bd05455a7e4f78aa448db1ea1d692f7b8b67d3) the promised keys check in the context when the context is in failure state
-
-### 0.3.4
-* The method call `with` is [now optional](https://github.com/adomokos/light-service/blob/master/spec/organizer_spec.rb#L18) in case you have nothing to put into the context.
-* Action name is being displayed in the error message when the expected or promised key is not in the context.
-
-### 0.3.3
-* Switching the promises and expects key accessors from Action to Context
-
-### 0.3.2
-* Fixing documentation and using separate arguments instead of a hash when setting the context to failure with error code
-
-### 0.3.1
-* Adding [error codes](https://github.com/adomokos/light-service#error-codes) to the context
-
-### 0.3.0
-* Adding the `expects` and `promises` macros - Read more about it in [this blog post](http://www.adomokos.com/2014/05/expects-and-promises-in-lightservice.html)
-
-### 0.2.2
-* Adding the gem version icon to README
-* Actions can be invoked now [without arguments](https://github.com/adomokos/light-service/commit/244d5f03b9dbf61c97c1fdb865e6587f9aea177d), this makes it super easy to play with an action in the command line
-
-### 0.2.1
-* [Improving](https://github.com/adomokos/light-service/commit/fc7043241396b4a2556e9664c13c6929f8330025) deprecation warning for the renamed methods
-* Making the message an optional argument for `succeed!` and `fail!` methods
 
-### 0.2.0
-* [Renaming](https://github.com/adomokos/light-service/commit/8d40ff7d393a157a8a558f9e4e021b8731550834) the `set_success!` and `set_failure!` methods to `succeed!` and `fail!`
-* [Throwing](https://github.com/adomokos/light-service/commit/5ef315b8aeeafc99e38676adad3c11df5d93b0e3) an ArgumentError if the `make` method's argument is not Hash or LightService::Context
+Follow the release notes in this [document](https://github.com/adomokos/light-service/blob/master/RELEASES.md).
 
 ## License
 

data/RELEASES.md

@@ -0,0 +1,39 @@
+A brief list of new features and changes introduced with the specified version.
+
+### 0.4.0
+* Adding [logging](https://github.com/adomokos/light-service#logging) to LightService
+
+### 0.3.6
+* [Collecting](https://github.com/adomokos/light-service/commit/29817de3ad589441788077368ad1d7e723286def) the `expects` and `promises` keys when they are called multiple times in an action
+
+### 0.3.5
+* remove previously deprecated method Context#context_hash
+* [Skipping](https://github.com/adomokos/light-service/commit/d2bd05455a7e4f78aa448db1ea1d692f7b8b67d3) the promised keys check in the context when the context is in failure state
+
+### 0.3.4
+* The method call `with` is [now optional](https://github.com/adomokos/light-service/blob/master/spec/organizer_spec.rb#L18) in case you have nothing to put into the context.
+* Action name is being displayed in the error message when the expected or promised key is not in the context.
+
+### 0.3.3
+* Switching the promises and expects key accessors from Action to Context
+
+### 0.3.2
+* Fixing documentation and using separate arguments instead of a hash when setting the context to failure with error code
+
+### 0.3.1
+* Adding [error codes](https://github.com/adomokos/light-service#error-codes) to the context
+
+### 0.3.0
+* Adding the `expects` and `promises` macros - Read more about it in [this blog post](http://www.adomokos.com/2014/05/expects-and-promises-in-lightservice.html)
+
+### 0.2.2
+* Adding the gem version icon to README
+* Actions can be invoked now [without arguments](https://github.com/adomokos/light-service/commit/244d5f03b9dbf61c97c1fdb865e6587f9aea177d), this makes it super easy to play with an action in the command line
+
+### 0.2.1
+* [Improving](https://github.com/adomokos/light-service/commit/fc7043241396b4a2556e9664c13c6929f8330025) deprecation warning for the renamed methods
+* Making the message an optional argument for `succeed!` and `fail!` methods
+
+### 0.2.0
+* [Renaming](https://github.com/adomokos/light-service/commit/8d40ff7d393a157a8a558f9e4e021b8731550834) the `set_success!` and `set_failure!` methods to `succeed!` and `fail!`
+* [Throwing](https://github.com/adomokos/light-service/commit/5ef315b8aeeafc99e38676adad3c11df5d93b0e3) an ArgumentError if the `make` method's argument is not Hash or LightService::Context

data/lib/light-service.rb

@@ -1,6 +1,12 @@
+require 'logger'
+
 require "light-service/version"
 
+require 'light-service/configuration'
 require 'light-service/context'
 require 'light-service/context_key_verifier'
+require 'light-service/organizer/with_reducer'
+require 'light-service/organizer/with_reducer_log_decorator'
+require 'light-service/organizer/with_reducer_factory'
 require 'light-service/action'
 require 'light-service/organizer'

data/lib/light-service/configuration.rb

@@ -0,0 +1,19 @@
+module LightService
+  class Configuration
+
+    class << self
+      attr_writer :logger
+    end
+
+    def self.logger
+      @logger ||= self._default_logger
+    end
+
+    def self._default_logger
+      logger = ::Logger.new("/dev/null")
+      logger.level = ::Logger::INFO
+      logger
+    end
+
+  end
+end

data/lib/light-service/context_key_verifier.rb

@@ -7,7 +7,10 @@ module LightService
       class << self
         def verify_expected_keys_are_in_context(context, action)
           verify_keys_are_in_context(context, action.expected_keys) do |not_found_keys|
-            fail ExpectedKeysNotInContextError, "expected #{format_keys(not_found_keys)} to be in the context during #{action}"
+            error_message = "expected #{format_keys(not_found_keys)} to be in the context during #{action}"
+
+            Configuration.logger.error error_message
+            fail ExpectedKeysNotInContextError, error_message
           end
         end
 
@@ -15,7 +18,10 @@ module LightService
           return context if context.failure?
 
           verify_keys_are_in_context(context, action.promised_keys) do |not_found_keys|
-            fail PromisedKeysNotInContextError, "promised #{format_keys(not_found_keys)} to be in the context during #{action}"
+            error_message = "promised #{format_keys(not_found_keys)} to be in the context during #{action}"
+
+            Configuration.logger.error error_message
+            fail PromisedKeysNotInContextError, error_message
           end
         end
 

data/lib/light-service/organizer.rb

@@ -4,25 +4,25 @@ module LightService
       base_class.extend ClassMethods
     end
 
+    # In case this module is included
     module ClassMethods
       def with(data)
-        new.with(data)
+        WithReducerFactory.make(self).with(data)
       end
 
-      def reduce(actions)
-        new.with.reduce(actions)
+      def reduce(*actions)
+        WithReducerFactory.make(self).with.reduce(actions)
       end
     end
 
+    # Provide hooks for extending the class with these methods
     def with(data = {})
-      @context = LightService::Context.make(data)
-      self
+      WithReducerFactory.make(self).with(data)
     end
 
     def reduce(*actions)
-      raise "No action(s) were provided" if actions.empty?
-      actions.flatten!
-      actions.reduce(@context) { |context, action| action.execute(context) }
+      WithReducerFactory.make(self).with.reduce(actions)
     end
+
   end
 end

data/lib/light-service/organizer/with_reducer.rb

@@ -0,0 +1,21 @@
+module LightService; module Organizer
+  class WithReducer
+    attr_reader :context
+
+    def with(data = {})
+      @context = LightService::Context.make(data)
+      self
+    end
+
+    def reduce(*actions)
+      raise "No action(s) were provided" if actions.empty?
+      actions.flatten!
+
+      actions.reduce(context) do |context, action|
+        result = action.execute(context)
+        yield(context, action) if block_given?
+        result
+      end
+    end
+  end
+end; end

data/lib/light-service/organizer/with_reducer_factory.rb

@@ -0,0 +1,14 @@
+module LightService
+  module Organizer
+    class WithReducerFactory
+      def self.make(monitored_organizer)
+        if (LightService::Configuration.logger.nil?)
+          ::LightService::Organizer::WithReducer.new
+        else
+          ::LightService::Organizer::WithReducerLogDecorator.new(
+            ::LightService::Organizer::WithReducer.new, monitored_organizer)
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/with_reducer_log_decorator.rb

@@ -0,0 +1,65 @@
+module LightService; module Organizer
+  class WithReducerLogDecorator
+    attr_reader :logger, :decorated, :organizer
+
+    def initialize(decorated = WithReducer.new, organizer)
+      @decorated, @organizer = decorated, organizer
+      @logger = ::LightService::Configuration.logger
+      @logged = false
+    end
+
+    def with(data = {})
+      logger.info("[LightService] - calling organizer <#{organizer.to_s}>")
+
+      decorated.with(data)
+
+      logger.info("[LightService] -     keys in context: #{extract_keys(decorated.context.keys)}")
+      self
+    end
+
+    def reduce(*actions)
+      decorated.reduce(*actions) do |context, action|
+        next if has_failure?(context, action)
+        next if skip_all?(context, action)
+
+        logger.info("[LightService] - executing <#{action.to_s}>")
+        if defined? action.expects and action.expects.any?
+          logger.info("[LightService] -   expects: #{extract_keys(action.expects)}")
+        end
+        if defined? action.promises and action.promises.any?
+          logger.info("[LightService] -   promises: #{extract_keys(action.promises)}")
+        end
+        logger.info("[LightService] -     keys in context: #{extract_keys(context.keys)}")
+      end
+    end
+
+    private
+    def logged?
+      @logged
+    end
+
+    def extract_keys(keys)
+      keys.map {|key| ":#{key}" }.join(', ')
+    end
+
+    def has_failure?(context, action)
+      return false unless context.respond_to?(:failure?)
+      return false unless context.failure?
+      return true if logged?
+
+      logger.warn("[LightService] - :-((( <#{action.to_s}> has failed...")
+      logger.warn("[LightService] - context message: #{context.message}")
+      @logged = true
+    end
+
+    def skip_all?(context, action)
+      return false unless context.respond_to?(:skip_all?)
+      return false unless context.skip_all?
+      return true if logged?
+
+      logger.info("[LightService] - ;-) <#{action.to_s}> has decided to skip the rest of the actions")
+      logger.info("[LightService] - context message: #{context.message}")
+      @logged = true
+    end
+  end
+end; end

data/lib/light-service/version.rb

@@ -1,3 +1,3 @@
 module LightService
-  VERSION = "0.3.6"
+  VERSION = "0.4.0"
 end

data/spec/acceptance/add_numbers_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
-class Organizer
-  include LightService::Organizer
+class AdditionOrganizer
+  extend LightService::Organizer
 
   def self.add_numbers(number)
     with(:number => number).reduce(
@@ -25,7 +25,6 @@ end
 class AddsTwoAction
   include LightService::Action
   expects :number
-  promises :number
 
   executed do |context|
     context.number += 2
@@ -35,17 +34,17 @@ end
 class AddsThreeAction
   include LightService::Action
   expects :number
-  promises :number
+  promises :product
 
   executed do |context|
-    context.number += 3
+    context.product = context.number + 3
   end
 end
 
-describe Organizer do
+describe AdditionOrganizer do
   it "Adds 1 2 3 and through to 1" do
-    result = Organizer.add_numbers 1
-    number = result.fetch(:number)
+    result = AdditionOrganizer.add_numbers 1
+    number = result.fetch(:product)
 
     expect(number).to eq(7)
   end

data/spec/acceptance/log_from_organizer_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+require 'test_doubles'
+require 'stringio'
+
+describe "Logs from organizer" do
+  def collects_log
+    original_logger = LightService::Configuration.logger
+
+    strio = StringIO.new
+    LightService::Configuration.logger = Logger.new(strio)
+
+    result = yield
+
+    LightService::Configuration.logger = original_logger
+
+    strio.string
+  end
+
+  context "when every action has expects or promises" do
+    subject(:log_message) do
+      collects_log do
+        TestDoubles::MakesTeaAndCappuccino.call("black tea", "2% milk", "espresso coffee")
+      end
+    end
+
+    it "describes what organizer was invoked" do
+      organizer_log_message = "[LightService] - calling organizer <TestDoubles::MakesTeaAndCappuccino>"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "describes the actions invoked" do
+      organizer_log_message = "[LightService] - executing <TestDoubles::MakesTeaWithMilkAction>"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "[LightService] - executing <TestDoubles::MakesLatteAction>"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "lists the keys in context before the actions are executed" do
+      organizer_log_message = "[LightService] -     keys in context: :tea, :milk, :coffee"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "lists the expects actions are expecting" do
+      organizer_log_message = "[LightService] -   expects: :tea, :milk"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "[LightService] -   expects: :coffee, :milk"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "lists the promises actions are promising" do
+      organizer_log_message = "[LightService] -   promises: :milk_tea"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "[LightService] -   promises: :latte"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "lists the keys in contect after the actions are executed" do
+      organizer_log_message = "[LightService] -     keys in context: :tea, :milk, :coffee, :milk_tea, :latte"
+      expect(log_message).to include(organizer_log_message)
+    end
+  end
+
+  context "when NOT every action expects or promises" do
+    subject(:log_message) do
+      collects_log do
+        TestDoubles::MakesCappuccinoAddsTwo.call("2% milk", "espresso coffee")
+      end
+    end
+
+    it "describes what organizer was invoked" do
+      organizer_log_message = "[LightService] - calling organizer <TestDoubles::MakesCappuccinoAddsTwo>"
+      expect(log_message).to include(organizer_log_message)
+    end
+
+    it "does not list empty expects or promises" do
+      organizer_log_message = "[LightService] -   expects:\n"
+      expect(log_message).not_to include(organizer_log_message)
+      organizer_log_message = "[LightService] -   promises:\n"
+      expect(log_message).not_to include(organizer_log_message)
+    end
+  end
+
+  context "when the context has failed" do
+    subject(:log_message) do
+      collects_log do
+        TestDoubles::MakesCappuccinoAddsTwoAndFails.call("espresso coffee")
+      end
+    end
+
+    it "logs it with a warning" do
+      organizer_log_message = "WARN -- : [LightService] - :-((( <TestDoubles::MakesLatteAction> has failed..."
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "WARN -- : [LightService] - context message: Can't make a latte from a milk that's too hot!"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "[LightService] -  :-((( <TestDoubles::AddsTwoAction> has failed..."
+      expect(log_message).not_to include(organizer_log_message)
+    end
+  end
+
+  context "when the context is skipping the rest" do
+    subject(:log_message) do
+      collects_log do
+        TestDoubles::MakesCappuccinoSkipsAddsTwo.call("espresso coffee")
+      end
+    end
+
+    it "logs it with a warning" do
+      organizer_log_message = "INFO -- : [LightService] - ;-) <TestDoubles::MakesLatteAction> has decided to skip the rest of the actions"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "INFO -- : [LightService] - context message: Can't make a latte with a fatty milk like that!"
+      expect(log_message).to include(organizer_log_message)
+      organizer_log_message = "INFO -- : [LightService] - ;-) <TestDoubles::AddsTwoAction> has decided to skip the rest of the actions"
+      expect(log_message).not_to include(organizer_log_message)
+    end
+  end
+end