light-service 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 41c85f3b70d95380e2e7aa2c289f089b5415c357
-  data.tar.gz: 66e9cb452320935e674a1f1250db139b8a7927ed
+  metadata.gz: 69a84cc464a38e385b929286e71879cfbd7c1a30
+  data.tar.gz: a5c1a3782056e3ef2bc1a2da4e6ab89fe2ef8487
 SHA512:
-  metadata.gz: 5783a1a16b678ad68c7352c74a75c506f8b1c3c41e25b43fa77e154f818a04bcff3a6adc641dd3bba779e6fd6cfe319916f4d1c4e3eacd8c06a192705b16a8ce
-  data.tar.gz: 0ce7a0c69be92173956db9280aac103654e961913242056c7a7a56264b6b2d22bf3322c764c5ea5d7188a09ebdac0b87de4100e62f0a35ba5508fd37ceffdb8a
+  metadata.gz: 8242553826eed7d16e4728dda02583b335bee7649749f18661fa5155748b21184523b20f7385ef6d5c4a3c2c644872c29d511ae54317d39974d1b4a8982e590f
+  data.tar.gz: 91dac04863bbff01761bda2f3ddbce112be0b36155c1a7e087b479dba9bce16547b661bc37ad3bbb6a8ea0ecd02034b9c8775b2f6361ef00d9706e7d030b62e2

data/README.md

@@ -218,12 +218,6 @@ You can turn off the logger by setting it to nil or `/dev/null`.
 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
@@ -290,18 +284,137 @@ class FooAction
 
   executed do |context|
     unless (service_call.success?)
-      context.fail!("Service call failed", 1001)
+      context.fail!("Service call failed", error_code: 1001)
     end
 
     # Do something else
 
     unless (entity.save)
-      context.fail!("Saving the entity failed", 2001)
+      context.fail!("Saving the entity failed", error_code: 2001)
     end
   end
 end
 ```
 
+## Action Rollback
+
+Sometimes your action has to undo what it did when an error occurs. Think about a chain of actions where you need
+to persist records in your data store in one action and you have to call an external service in the next. What happens if there
+is an error when you call the external service? You want to remove the records you previously saved. You can do it now with
+the `rolled_back` macro.
+
+```ruby
+class SaveEntities
+  include LightService::Action
+  expects :user
+
+  executed do |context|
+    context.user.save!
+  end
+
+  rolled_back do |context|
+    context.user.destroy
+  end
+end
+```
+
+You need to call the `fail_with_rollback!` method to initiate a rollback for actions starting with the action where the failure
+was triggered.
+
+```ruby
+class CallExternalApi
+  include LightService::Action
+
+  executed do |context|
+    api_call_result = SomeAPI.save_user(context.user)
+
+    context.fail_with_rollback!("Error when calling external API") if api_call_result.failure?
+  end
+end
+```
+
+Using the `rolled_back` macro is optional for the actions in the chain. You shouldn't care about undoing non-persisted changes.
+
+The actions are rolled back in reversed order from the point of failure starting with the action that triggered it.
+
+See [this](spec/acceptance/rollback_spec.rb) acceptance test to learn more about this functionality.
+
+## Localizing Messages
+
+By default LightService provides a mechanism for easily translating your error or success messages via I18n.  You can also provide your own custom localization adapter if your application's logic is more complex than what is shown here.
+
+```ruby
+class FooAction
+  include LightService::Action
+
+  executed do |context|
+    unless service_call.success?
+      context.fail!(:exceeded_api_limit)
+
+      # The failure message used here equates to:
+      # I18n.t(:exceeded_api_limit, scope: "foo_action.light_service.failures")
+    end
+  end
+end
+```
+
+This also works with nested classes via the ActiveSupport `#underscore` method, just as ActiveRecord performs localization lookups on models placed inside a module.
+
+```ruby
+module PaymentGateway
+  class CaptureFunds
+    include LightService::Action
+
+    executed do |context|
+      if api_service.failed?
+        context.fail!(:funds_not_available)
+      end
+
+      # this failure message equates to:
+      # I18n.t(:funds_not_available, scope: "payment_gateway/capture_funds.light_service.failures")
+    end
+  end
+end
+```
+
+If you need to provide custom variables for interpolation during localization, pass that along in a hash.
+
+```ruby
+module PaymentGateway
+  class CaptureFunds
+    include LightService::Action
+
+    executed do |context|
+      if api_service.failed?
+        context.fail!(:funds_not_available, last_four: "1234")
+      end
+
+      # this failure message equates to:
+      # I18n.t(:funds_not_available, last_four: "1234", scope: "payment_gateway/capture_funds.light_service.failures")
+
+      # the translation string itself being:
+      # => "Unable to process your payment for account ending in %{last_four}"
+    end
+  end
+end
+```
+
+To provide your own custom adapter, use the configuration setting and subclass the default adapter LightService provides.
+
+```ruby
+LightService::Configuration.localization_adapter = MyLocalizer.new
+
+# lib/my_localizer.rb
+class MyLocalizer < LightService::LocalizationAdapter
+  
+  # I just want to change the default lookup path
+  # => "light_service.failures.payment_gateway/capture_funds"
+  def i18n_scope_from_class(action_class, type)
+    "light_service.#{type.pluralize}.#{action_class.name.underscore}"
+  end
+end
+```
+
 ## Requirements
 
 This gem requires ruby 1.9.x

data/lib/light-service.rb

@@ -2,7 +2,9 @@ require 'logger'
 
 require "light-service/version"
 
+require 'light-service/errors'
 require 'light-service/configuration'
+require 'light-service/localization_adapter'
 require 'light-service/context'
 require 'light-service/context_key_verifier'
 require 'light-service/organizer/with_reducer'

data/lib/light-service/action.rb

@@ -17,34 +17,49 @@ module LightService
       end
 
       def expected_keys
-        @_expected_keys
+        @_expected_keys ||= []
       end
 
       def promised_keys
-        @_promised_keys
+        @_promised_keys ||= []
       end
 
       def executed
+        raise "`executed` macro can not be invoked again" if self.respond_to?(:execute)
+
         define_singleton_method "execute" do |context = {}|
           action_context = create_action_context(context)
           return action_context if action_context.stop_processing?
-          action = self
 
-          Context::KeyVerifier.verify_expected_keys_are_in_context(action_context, action)
+          # Store the action within the context
+          action_context.current_action = self
+
+          Context::KeyVerifier.verify_expected_keys_are_in_context(action_context)
 
           action_context.define_accessor_methods_for_keys(expected_keys)
           action_context.define_accessor_methods_for_keys(promised_keys)
 
           yield(action_context)
 
-          Context::KeyVerifier.verify_promised_keys_are_in_context(action_context, action)
+          Context::KeyVerifier.verify_promised_keys_are_in_context(action_context)
+        end
+      end
+
+      def rolled_back
+        raise "`rolled_back` macro can not be invoked again" if self.respond_to?(:rollback)
+
+        define_singleton_method "rollback" do |context = {}|
+          yield(context)
+
+          context
         end
+
       end
 
       private
 
       def create_action_context(context)
-        if context.is_a? ::LightService::Context
+        if context.is_a? LightService::Context
           return context
         end
 

data/lib/light-service/configuration.rb

@@ -2,17 +2,23 @@ module LightService
   class Configuration
 
     class << self
-      attr_writer :logger
-    end
+      attr_writer :logger, :localization_adapter
 
-    def self.logger
-      @logger ||= self._default_logger
-    end
+      def logger
+        @logger ||= _default_logger
+      end
+
+      def localization_adapter
+        @localization_adapter ||= LocalizationAdapter.new
+      end
+
+      private
 
-    def self._default_logger
-      logger = ::Logger.new("/dev/null")
-      logger.level = ::Logger::INFO
-      logger
+      def _default_logger
+        logger = Logger.new("/dev/null")
+        logger.level = Logger::INFO
+        logger
+      end
     end
 
   end

data/lib/light-service/context.rb

@@ -5,16 +5,17 @@ module LightService
   end
 
   class Context < Hash
-    attr_accessor :outcome, :message, :error_code
+    attr_accessor :outcome, :message, :error_code, :current_action
 
-    def initialize(context={}, outcome=::LightService::Outcomes::SUCCESS, message='', error_code=nil)
+    def initialize(context={}, outcome=Outcomes::SUCCESS, message='', error_code=nil)
       @outcome, @message, @error_code = outcome, message, error_code
+      @skip_all = false
       context.to_hash.each {|k,v| self[k] = v}
       self
     end
 
     def self.make(context={})
-      unless context.is_a? Hash or context.is_a? ::LightService::Context
+      unless context.is_a? Hash or context.is_a? LightService::Context
         raise ArgumentError, 'Argument must be Hash or LightService::Context'
       end
 
@@ -27,7 +28,7 @@ module LightService
     end
 
     def success?
-      @outcome == ::LightService::Outcomes::SUCCESS
+      @outcome == Outcomes::SUCCESS
     end
 
     def failure?
@@ -43,9 +44,9 @@ module LightService
       succeed!(message)
     end
 
-    def succeed!(message=nil)
-      @message = message
-      @outcome = ::LightService::Outcomes::SUCCESS
+    def succeed!(message=nil, options={})
+      @message = Configuration.localization_adapter.success(message, current_action, options)
+      @outcome = Outcomes::SUCCESS
     end
 
     def set_failure!(message)
@@ -53,10 +54,25 @@ module LightService
       fail!(message)
     end
 
-    def fail!(message=nil, error_code=nil)
-      @message = message
+    def fail!(message=nil, options_or_error_code={})
+      options_or_error_code ||= {}
+
+      if options_or_error_code.is_a?(Hash)
+        error_code = options_or_error_code.delete(:error_code)
+        options = options_or_error_code
+      else
+        error_code = options_or_error_code
+        options = {}
+      end
+
+      @message = Configuration.localization_adapter.failure(message, current_action, options)
       @error_code = error_code
-      @outcome = ::LightService::Outcomes::FAILURE
+      @outcome = Outcomes::FAILURE
+    end
+
+    def fail_with_rollback!(message=nil, error_code=nil)
+      fail!(message, error_code)
+      raise FailWithRollbackError.new
     end
 
     def skip_all!(message=nil)
@@ -71,6 +87,7 @@ module LightService
     def define_accessor_methods_for_keys(keys)
       return if keys.nil?
       keys.each do |key|
+        next if self.respond_to?(key.to_sym)
         define_singleton_method("#{key}") { self.fetch(key) }
         define_singleton_method("#{key}=") { |value| self[key] = value }
       end

data/lib/light-service/context_key_verifier.rb

@@ -1,11 +1,10 @@
 module LightService
-  class ExpectedKeysNotInContextError < StandardError; end
-  class PromisedKeysNotInContextError < StandardError; end
-
   class Context
     class KeyVerifier
       class << self
-        def verify_expected_keys_are_in_context(context, action)
+        def verify_expected_keys_are_in_context(context)
+          action = context.current_action
+
           verify_keys_are_in_context(context, action.expected_keys) do |not_found_keys|
             error_message = "expected #{format_keys(not_found_keys)} to be in the context during #{action}"
 
@@ -14,9 +13,11 @@ module LightService
           end
         end
 
-        def verify_promised_keys_are_in_context(context, action)
+        def verify_promised_keys_are_in_context(context)
           return context if context.failure?
 
+          action = context.current_action
+
           verify_keys_are_in_context(context, action.promised_keys) do |not_found_keys|
             error_message = "promised #{format_keys(not_found_keys)} to be in the context during #{action}"
 

data/lib/light-service/errors.rb

@@ -0,0 +1,5 @@
+module LightService
+  class FailWithRollbackError < StandardError; end
+  class ExpectedKeysNotInContextError < StandardError; end
+  class PromisedKeysNotInContextError < StandardError; end
+end

data/lib/light-service/localization_adapter.rb

@@ -0,0 +1,41 @@
+module LightService
+  class LocalizationAdapter
+    def failure(message_or_key, action_class, i18n_options={})
+      find_translated_message(message_or_key,
+                              action_class,
+                              i18n_options,
+                              {:type => :failure})
+    end
+
+    def success(message_or_key, action_class, i18n_options={})
+      find_translated_message(message_or_key,
+                              action_class,
+                              i18n_options,
+                              {:type => :success})
+    end
+
+    private
+
+    def find_translated_message(message_or_key, action_class, i18n_options, type)
+      if message_or_key.is_a?(Symbol)
+        i18n_options.merge!(type)
+        translate(message_or_key, action_class, i18n_options)
+      else
+        message_or_key
+      end
+    end
+
+    def translate(key, action_class, options={})
+      type = options.delete(:type)
+
+      scope = i18n_scope_from_class(action_class, type)
+      options.merge!(scope: scope)
+
+      I18n.t(key, options)
+    end
+
+    def i18n_scope_from_class(action_class, type)
+      "#{action_class.name.underscore}.light_service.#{type.to_s.pluralize}"
+    end
+  end
+end

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

@@ -12,10 +12,38 @@ module LightService; module Organizer
       actions.flatten!
 
       actions.reduce(context) do |context, action|
-        result = action.execute(context)
-        yield(context, action) if block_given?
+        begin
+          result = action.execute(context)
+        rescue FailWithRollbackError
+          result = reduce_rollback(actions)
+        ensure
+          # For logging
+          yield(context, action) if block_given?
+        end
+
         result
       end
     end
+
+    def reduce_rollback(actions)
+      reversable_actions(actions)
+        .reverse
+        .reduce(context) do |context, action|
+          if action.respond_to?(:rollback)
+            action.rollback(context)
+          else
+            context
+          end
+        end
+    end
+
+    private
+
+    def reversable_actions(actions)
+      index_of_current_action = actions.index(@context.current_action) || 0
+
+      # Reverse from the point where the fail was triggered
+      actions.take(index_of_current_action + 1)
+    end
   end
 end; end