light-service 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55ba3cb29c4ce4e3e59c3129bc8baf4287efe0c2
-  data.tar.gz: ba0a1fc827bee6a92346c886948c024753796880
+  metadata.gz: 25a715c986fab5133c64ef50160f93524bfdcca2
+  data.tar.gz: 1034f64ec7c50288024a15cce41b29082983941a
 SHA512:
-  metadata.gz: 64a014abda6e16cd5d1c4a62ea188b576a8878e46304f90d5768666f5e944869fc84814c250dfc986b7be67eb7c76fd736d74363171445f5401b5457704d36d4
-  data.tar.gz: 77d665f3fcd08eb79c598871fe1c97e6bba9e34b773fe2b083ed8001fa356c383a13fba2195157d187d84110c57fc929f0de81874de07207dfa529b821319ed2
+  metadata.gz: 1781b4242bb655bf55e257d65f97a4e4d6bf2d7eb0899bbfc509e10f62fce25d594de73bdcf426490052e3ca54a764c5ae1da049d107693c5a23d69dbe704867
+  data.tar.gz: 4009c8844215156df49a668a6c953cb60ae577438d35fb3452309fb005084d64b24317de65f4544a4a93af3ebc058edf9174adbbed58c5f227b791d99577bf5c

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  Exclude:
+    - 'lib/light-service.rb'
+    - 'vendor/bundle/**/*'
+    - 'gemfiles/vendor/bundle/**/*'
+    - 'bin/*'
+    - 'light-service.gemspec'
+
+Documentation:
+  Enabled: false
+
+Style/Encoding:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/TrailingBlankLines:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/HashSyntax:
+  EnforcedStyle: hash_rockets
+
+Style/PredicateName:
+  Enabled: false
+
+Style/TrivialAccessors:
+  AllowPredicates: true
+
+Metrics/MethodLength:
+  Max: 15

data/.travis.yml

@@ -1,7 +1,21 @@
 language: ruby
+
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1.2
+  - 2.2.0
+  - 2.3.0
+
+before_install:
+  - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'
+  - gem install bundler
+  - bundle install --path vendor/bundle
+
 # uncomment this line if your project needs to run something other than `rake`:
-script: bundle exec rspec spec
+script:
+  - bundle exec rspec spec
+  - bundle exec rubocop
+
+gemfile:
+  - gemfiles/activesupport_3.gemfile
+  - gemfiles/activesupport_4.gemfileset

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "activesupport-3" do
+  gem "activesupport", "~> 3.0"
+end
+
+appraise "activesupport-4" do
+  gem "activesupport", "~> 4.0"
+end

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in light_service.gemspec
 gemspec
+
+gem 'appraisal', '~> 2.0'

data/README.md

@@ -1,4 +1,4 @@
-![LightService](https://raw.github.com/adomokos/light-service/master/resources/light-service.png)
+![LightService](resources/light-service.png)
 
 [![Gem Version](https://img.shields.io/gem/v/light-service.svg)](https://rubygems.org/gems/light-service)
 [![Build Status](https://secure.travis-ci.org/adomokos/light-service.png)](http://travis-ci.org/adomokos/light-service)
@@ -62,7 +62,7 @@ and executes them one-by-one. Then you need to create the actions which will onl
 
 This is how the organizer and actions interact with eachother:
 
-![LightService](https://raw.github.com/adomokos/light-service/master/resources/organizer_and_actions.png)
+![LightService](resources/organizer_and_actions.png)
 
 ```ruby
 class CalculatesTax
@@ -146,6 +146,124 @@ end
 I gave a [talk at RailsConf 2013](http://www.adomokos.com/2013/06/simple-and-elegant-rails-code-with.html) on
 simple and elegant Rails code where I told the story of how LightService was extracted from the projects I had worked on.
 
+
+## Table of Content
+* [Stopping the Series of Actions](#stopping-the-series-of-actions)
+    * [Failing the Context](#failing-the-context)
+    * [Skipping the Rest of the Actions](#skipping-the-rest-of-the-actions)
+* [Benchmarking Actions with Around Advice](#benchmarking-actions-with-around-advice)
+* [Key Aliases](#key-aliases)
+* [Logging](#logging)
+* [Error Codes](#error-codes)
+* [Action Rollback](#action-rollback)
+* [Localizing Messages](#localizing-messages)
+
+## Stopping the Series of Actions
+When nothing unexpected happens during the organizer's call, the returned `context` will be successful. Here is how you can check for this:
+```ruby
+class SomeController < ApplicationController
+  def index
+    result_context = SomeOrganizer.call(current_user.id)
+
+    if result_context.success?
+      redirect_to foo_path, :notice => "Everything went OK! Thanks!"
+    else
+      flash[:error] = result_context.message
+      render :action => "new"
+    end
+  end
+end
+```
+However, sometimes not everything will play out as you expect it. An external API call might not be available or some complex business logic will need to stop the processing of the Series of Actions.
+You have two options to stop the call chain:
+
+1. Failing the context
+2. Skipping the rest of the actions
+
+### Failing the Context
+When something goes wrong in an action and you want to halt the chain, you need to call `fail!` on the context object. This will push the context in a failure state (`context.failure? # will evalute to true`).
+The context's `fail!` method can take an optional message argument, this message might help describing what went wrong.
+In case you need to return immediately from the point of failure, you have to do that by calling `next context`.
+
+Here is an example:
+```ruby
+class SubmitsOrderAction
+  extend LightService::Action
+  expects :order, :mailer
+
+  executed do |context|
+    unless context.order.submit_order_succeful?
+      context.fail!("Failed to submit the order")
+      next context
+    end
+
+    context.mailer.send_order_notification!
+  end
+end
+```
+![LightService](resources/fail_actions.png)
+
+In the example above the organizer called 4 actions. The first 2 actions got executed successfully. The 3rd had a failure, that pushed the context into a failure state and the 4th action was skipped.
+
+### Skipping the rest of the actions
+You can skip the rest of the actions by calling `context.skip_all!`. This behaves very similarly to the above-mentioned `fail!` mechanism, except this will not push the context into a failure state.
+A good use case for this is executing the first couple of action and based on a check you might not need to execute the rest.
+Here is an example of how you do it:
+```ruby
+class ChecksOrderStatusAction
+  extend LightService::Action
+  expects :order
+
+  executed do |context|
+    if context.order.send_notification?
+      context.skip_all!("Everything is good, no need to execute the rest of the actions")
+    end
+  end
+end
+```
+![LightService](resources/skip_actions.png)
+
+In the example above the organizer called 4 actions. The first 2 actions got executed successfully. The 3rd decided to skip the rest, the 4th action was not invoked. The context was successful.
+
+
+## Benchmarking Actions with Around Advice
+Benchmarking your action is needed when you profile the series of actions. You could add benchmarking logic to each and every action, however, that would blur the business logic you have in your actions.
+
+Take advantage of the organizer's `around_each` method, which wraps the action calls as its reducing them in order.
+
+Check out this example:
+
+```ruby
+class LogDuration
+  def self.call(action, context)
+    start_time = Time.now
+    result = yield
+    duration = Time.now - start_time
+    LightService::Configuration.logger.info(
+      :action   => action,
+      :duration => duration
+    )
+
+    result
+  end
+end
+
+class CalculatesTax
+  extend LightService::Organizer
+
+  def self.for_order(order)
+    with(:order => order).around_each(LogDuration).reduce(
+        LooksUpTaxPercentageAction,
+        CalculatesOrderTaxAction,
+        ProvidesFreeShippingAction
+      )
+  end
+end
+```
+
+Any object passed into `around_each` must respond to #call with two arguments: the action name and the context it will execute with. It is also passed a block, where LightService's action execution will be done in, so the result must be returned. While this is a little work, it also gives you before and after state access to the data for any auditing and/or checks you may need to accomplish.
+
+
 ## Expects and Promises
 The `expects` and `promises` macros are rules for the inputs/outputs of an action.
 `expects` describes what keys it needs to execute, and `promises` makes sure the keys are in the context after the
@@ -201,9 +319,9 @@ end
 Take a look at [this spec](spec/action_expects_and_promises_spec.rb) to see the refactoring in action.
 
 ## Key Aliases
-The `aliases` macro sets up pairs of keys and aliases in an Organizer.  Actions can access the context using the aliases.
+The `aliases` macro sets up pairs of keys and aliases in an organizer. Actions can access the context using the aliases.
 
-This allows you to put together existing Actions from different sources and have them work together without having to modify their code.  Aliases will work with or without Action `expects`.
+This allows you to put together existing actions from different sources and have them work together without having to modify their code. Aliases will work with or without action `expects`.
 
 Say for example you have actions `AnAction` and `AnotherAction` that you've used in previous projects.  `AnAction` provides `:my_key` but `AnotherAction` needs to use that value but expects `:key_alias`.  You can use them together in an organizer like so:
 
@@ -241,7 +359,6 @@ end
 ```
 
 ## 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.
 
@@ -300,7 +417,6 @@ I, [DATE]  INFO -- : [LightService] - context message: Can't make a latte with a
 ```
 
 ## Error Codes
-
 You can add some more structure to your error handling by taking advantage of error codes in the context.
 Normally, when something goes wrong in your actions, you fail the process by setting the context to failure:
 
@@ -337,7 +453,6 @@ 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
@@ -380,7 +495,6 @@ The actions are rolled back in reversed order from the point of failure starting
 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
@@ -446,7 +560,7 @@ 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)
@@ -455,12 +569,12 @@ class MyLocalizer < LightService::LocalizationAdapter
 end
 ```
 
-## Requirements
+To get the value of a `fail!` or `succeed!` message, simply call `#message` on the returned context.
 
-This gem requires ruby 1.9.x
+## Requirements
+This gem requires ruby 2.x
 
 ## Installation
-
 Add this line to your application's Gemfile:
 
     gem 'light-service'
@@ -474,14 +588,12 @@ Or install it yourself as:
     $ gem install light-service
 
 ## Usage
-
 Based on the refactoring example above, just create an organizer object that calls the
 actions in order and write code for the actions. That's it.
 
 For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki).
 
 ## Contributing
-
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
@@ -491,9 +603,7 @@ 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
-
 Follow the release notes in this [document](https://github.com/adomokos/light-service/blob/master/RELEASES.md).
 
 ## License
-
 LightService is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/RELEASES.md

@@ -1,5 +1,9 @@
 A brief list of new features and changes introduced with the specified version.
 
+### 0.6.1
+* Introducing [around_each](https://github.com/adomokos/light-service/pull/79) for AOP style logging and code execution
+* Introducing [Rubocop](https://github.com/adomokos/light-service/commit/39aa7ea39f69a16c2df66b213fb6d638796e25f2) to the project, forcing consistant style
+
 ### 0.6.0
 * Using [extend](https://github.com/adomokos/light-service/pull/64) for using class methods in Actions and Organizers
 * Setting [key aliases](https://github.com/adomokos/light-service/pull/69) for the Context from the Organizer

data/Rakefile

@@ -1,2 +1,5 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+
+require "rubygems"
+require "bundler/setup"

data/gemfiles/activesupport_3.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.0"
+gem "activesupport", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/activesupport_3.gemfile.lock

@@ -0,0 +1,63 @@
+PATH
+  remote: ../
+  specs:
+    light-service (0.6.0)
+      activesupport (>= 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (3.2.22)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    appraisal (2.0.2)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    coderay (1.0.9)
+    diff-lcs (1.2.5)
+    i18n (0.7.0)
+    method_source (0.8.2)
+    multi_json (1.11.2)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.6.0)
+    thor (0.19.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 3.0)
+  appraisal (~> 2.0)
+  light-service!
+  pry (= 0.9.12.2)
+  rspec (~> 3.0)
+  rspec-its (~> 1.0)
+  simplecov (~> 0.7.1)
+
+BUNDLED WITH
+   1.10.6

data/gemfiles/activesupport_4.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.0"
+gem "activesupport", "~> 4.0"
+
+gemspec :path => "../"

data/gemfiles/activesupport_4.gemfile.lock

@@ -0,0 +1,71 @@
+PATH
+  remote: ../
+  specs:
+    light-service (0.6.0)
+      activesupport (>= 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.3)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    appraisal (2.0.2)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    coderay (1.0.9)
+    diff-lcs (1.2.5)
+    i18n (0.7.0)
+    json (1.8.3)
+    method_source (0.8.2)
+    minitest (5.7.0)
+    multi_json (1.11.2)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.6.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 4.0)
+  appraisal (~> 2.0)
+  light-service!
+  pry (= 0.9.12.2)
+  rspec (~> 3.0)
+  rspec-its (~> 1.0)
+  simplecov (~> 0.7.1)
+
+BUNDLED WITH
+   1.10.6