light-service 0.11.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 591c6fcf80629485e608c41881fc41ebd8db307c
-  data.tar.gz: fdb6a27728e5201513be58cefd4b4335274509cd
+SHA256:
+  metadata.gz: d41ecb22a4b0d3cd9779c1e5726c8f34e6f186a34f04ec97ea5928f682f08fd8
+  data.tar.gz: 64f4d7f52607048313e9f39bea158899ef804deb32ae9744715e5969cc7b1567
 SHA512:
-  metadata.gz: a2ea84a98fb446cae6616d0c02b30d21e1f0c1a29dc5a5adb7692c4acc9be69a4769ec799c51e5c16ee4888a370d551e915e076b5e7ae9985b28ccac216ea46c
-  data.tar.gz: 3770373e92ac2498a72bb9833097541a3f35f44c5c383636e0920cd50eb53c4260abccc156772285da1411486ed8e309c10323602b282cab02ecfaf210549194
+  metadata.gz: 2345b72e3d9581aecaea2fe5eca1bd3c538cdb0cfcd2d943ac021ca4f3ef31913ac4b06011944c017df330f3ee8dc385793e8185f3e79cba6c51fbe6ee6acba6
+  data.tar.gz: 703b9608edfa42bf0d73135fa5b4eafa789e8a31c4239056fd8b7397d6f0a212f8c5c69d66834f1f5b9fe2431b234f8c0373ccaaa86f286d82671bfe8d8b705b

data/.github/workflows/project-build.yml

@@ -0,0 +1,28 @@
+name: CI Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu, macos]
+        ruby: [2.5.3, 2.6.6, 2.7.2]
+        gemfile: [activesupport_5, activesupport_6]
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
+      BUNDLE_GEMFILE: gemfiles/${{ matrix.gemfile }}.gemfile
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: bundle install
+      - run: bundle exec rspec spec
+      - run: bundle exec rubocop

data/.gitignore

@@ -17,3 +17,4 @@ test/version_tmp
 tmp
 vendor/bundle
 bin
+.idea

data/.rubocop.yml

@@ -1,4 +1,7 @@
+require: rubocop-performance
+
 AllCops:
+  TargetRubyVersion: 2.3
   Exclude:
     - 'lib/light-service.rb'
     - 'vendor/bundle/**/*'
@@ -46,3 +49,6 @@ Metrics/BlockLength:
 
 Layout/TrailingBlankLines:
   Enabled: false
+
+Layout/EndOfLine:
+  EnforcedStyle: lf

data/.travis.yml

@@ -4,16 +4,14 @@ env:
   - RUN_COVERAGE_REPORT=true
 
 rvm:
-  - 2.2.2
-  - 2.3.3
-  - 2.4.1
-  - 2.5.0
+  - 2.5.3
+  - 2.6.6
+  - 2.7.2
 
 before_install:
   - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'
   - gem install bundler
-  - bundle update simplecov
-  - bundle install --path vendor/bundle
+  - bundle install --clean --path vendor/bundle
 
 # uncomment this line if your project needs to run something other than `rake`:
 script:
@@ -21,13 +19,11 @@ script:
   - bundle exec rubocop
 
 gemfile:
-  - gemfiles/activesupport_3.gemfile
   - gemfiles/activesupport_4.gemfile
   - gemfiles/activesupport_5.gemfile
+  - gemfiles/activesupport_6.gemfile
 
 matrix:
   exclude:
-  - rvm: 2.1.8
-    gemfile: gemfiles/activesupport_5.gemfile
-  - rvm: 2.2.2
-    gemfile: gemfiles/activesupport_5.gemfile
+  - rvm: 2.7.2
+    gemfile: gemfiles/activesupport_4.gemfile

data/Appraisals

@@ -1,7 +1,3 @@
-appraise "activesupport-3" do
-  gem "activesupport", "~> 3.0"
-end
-
 appraise "activesupport-4" do
   gem "activesupport", "~> 4.0"
 end
@@ -9,3 +5,7 @@ end
 appraise "activesupport-5" do
   gem "activesupport", "~> 5.0"
 end
+
+appraise "activesupport-6" do
+  gem "activesupport", "~> 6.0"
+end

data/Gemfile

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

data/README.md

@@ -1,19 +1,21 @@
 ![LightService](https://raw.githubusercontent.com/adomokos/light-service/master/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)
-[![Code Climate](https://codeclimate.com/github/adomokos/light-service.png)](https://codeclimate.com/github/adomokos/light-service)
+[![CI Tests](https://github.com/adomokos/light-service/actions/workflows/project-build.yml/badge.svg)](https://github.com/adomokos/light-service/actions/workflows/project-build.yml)
+[![codecov](https://codecov.io/gh/adomokos/light-service/branch/master/graph/badge.svg)](https://codecov.io/gh/adomokos/light-service)
+[![Code Climate](https://codeclimate.com/github/adomokos/light-service.svg)](https://codeclimate.com/github/adomokos/light-service)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
+[![Download Count](https://ruby-gem-downloads-badge.herokuapp.com/light-service?type=total)](https://rubygems.org/gems/light-service)
 
-<br><br>
+LightService is a powerful and flexible service skeleton framework with an emphasis on simplicity
 
-![Orchestrators-Deprecated](resources/orchestrators_deprecated.svg)
-<br>Version 0.9.0 deprecates Orchestrators and moves all their functionalities into Organizers. Please check out [this PR](https://github.com/adomokos/light-service/pull/132) to see the changes.
-
-<br>
-
-## Table of Content
+## Table of Contents
 * [Why LightService?](#why-lightservice)
+* [Getting Started](#getting-started)
+    * [Requirements](#requirements)
+    * [Installation](#installation)
+    * [Your first action](#your-first-action)
+    * [Your first organizer](#your-first-organizer)
 * [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)
@@ -24,9 +26,11 @@
 * [Error Codes](#error-codes)
 * [Action Rollback](#action-rollback)
 * [Localizing Messages](#localizing-messages)
-* [Orchestrator Logic in Organizers](#orchestrator-logic-in-organizers)
+* [Orchestrating Logic in Organizers](#orchestrating-logic-in-organizers)
 * [ContextFactory for Faster Action Testing](#contextfactory-for-faster-action-testing)
-
+* [Rails support](#rails-support)
+* [Implementations in other languages](#other-implementations)
+* [Contributing](#contributing)
 
 ## Why LightService?
 
@@ -78,7 +82,7 @@ Wouldn't it be nice to see this instead?
 (
   LooksUpTaxPercentage,
   CalculatesOrderTax,
-  ChecksFreeShipping
+  ProvidesFreeShipping
 )
 ```
 
@@ -174,7 +178,143 @@ 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.
 
+## Getting started
+
+### Requirements
+
+This gem requires ruby 2.x. Use of [generators](#rails-support) requires Rails 5+ (tested on Rails 5.x & 6.x only. Will probably work on
+Rails versions as old as 3.2)
+
+### Installation
+
+In your Gemfile:
+
+```ruby
+gem 'light-service'
+```
+
+And then
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install light-service
+```
+
+### Your first action
+
+LightService's building blocks are actions that are normally composed within an organizer, but can be run independently.
+Let's make a simple greeter action. Each action can take an optional list of expected inputs and promised outputs. If
+these are specified and missing at action start and stop respectively, an exception will be thrown.
+
+```ruby
+class GreetsPerson
+  extend ::LightService::Action
+
+  expects :name
+  promises :greeting
+
+  executed do |context|
+    context.greeting = "Hey there, #{name}. You enjoying LightService so far?"
+  end
+end
+```
+
+When an action is run, you have access to its returned context, and the status of the action. You can invoke an
+action by calling `.execute` on its class with `key: value` arguments, and inspect its status and context like so:
+
+```ruby
+outcome = GreetsPerson.execute(name: "Han")
+
+if outcome.success?
+  puts outcome.greeting # which was a promised context value
+elsif outcome.failure?
+  puts "Rats... I can't say hello to you"
+end
+```
+
+You will notice that actions are set up to promote simplicity, i.e. they either succeed or fail, and they have
+very clear inputs and outputs. Ideally, they should do [exactly one thing](https://en.wikipedia.org/wiki/Single-responsibility_principle). This makes them as easy to test as unit tests.
+
+### Your first organizer
+
+LightService provides a facility to compose actions using organizers. This is great when you have a business process
+to execute that has multiple steps. By composing actions that do exactly one thing, you can sequence simple
+actions together to perform complex multi-step business processes in a clear manner that is very easy
+to reason about.
+
+There are advanced ways to sequence actions that can be found later in the README, but we'll keep this simple for now.
+First, let's add a second action that we can sequence to run after the `GreetsPerson` action from above:
+
+```ruby
+class RandomlyAwardsPrize
+  extend ::LightService::Action
+
+  expects :name, :greeting
+  promises :did_i_win
+
+  executed do |context|
+    prize_num  = "#{context.name}__#{context.greeting}".length
+    prizes     = ["jelly beans", "ice cream", "pie"]
+    did_i_win  = rand((1..prize_num)) % 7 == 0
+    did_i_lose = rand((1..prize_num)) % 13 == 0
+
+    if did_i_lose
+      # When failing, send a message as an argument, readable from the return context
+      context.fail!("you are exceptionally unlucky")
+    else
+      # You can specify 'optional' context items by treating context like a hash.
+      # Useful for when you may or may not be returning extra data. Ideally, selecting
+      # a prize should be a separate action that is only run if you win.
+      context[:prize]   = "lifetime supply of #{prizes.sample}" if did_i_win
+      context.did_i_win = did_i_win
+    end
+  end
+end
+```
+
+And here's the organizer that ties the two together. You implement a `call` class method that takes some arguments and
+from there sends them to `with` in `key: value` format which forms the initial state of the context. From there, chain
+`reduce` to `with` and send it a list of action class names in sequence. The organizer will call each action, one
+after the other, and build up the context as it goes along.
+
+```ruby
+class WelcomeAPotentiallyLuckyPerson
+  extend LightService::Organizer
+
+  def self.call(name)
+    with(:name => name).reduce(GreetsPerson, RandomlyAwardsPrize)
+  end
+end
+```
+
+When an organizer is run, you have access to the context as it passed through all actions, and the overall status
+of the organized execution. You can invoke an organizer by calling `.call` on the class with the expected arguments,
+and inspect its status and context just like you would an action:
+
+```ruby
+outcome = WelcomeAPotentiallyLuckyPerson.call("Han")
+
+if outcome.success?
+  puts outcome.greeting # which was a promised context value
+
+  if outcome.did_i_win
+    puts "And you've won a prize! Lucky you. Please see the front desk for your #{outcome.prize}."
+  end
+else # outcome.failure? is true, and we can pull the failure message out of the context for feedback to the user.
+  puts "Rats... I can't say hello to you, because #{outcome.message}."
+end
+```
+
+Because organizers generally run through complex business logic, and every action has the potential to cause a failure,
+testing an organizer is functionally equivalent to an integration test.
 
+For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki) and review
+the ["Why LightService" section](#why-lightservice) above.
 
 ## 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:
@@ -294,14 +434,16 @@ Consider this code:
 class SomeOrganizer
   extend LightService::Organizer
 
-  def call(ctx)
+  def self.call(ctx)
     with(ctx).reduce(actions)
   end
 
-  def actions
-    OneAction,
-    TwoAction,
-    ThreeAction
+  def self.actions
+    [
+      OneAction,
+      TwoAction,
+      ThreeAction
+    ]
   end
 end
 
@@ -345,14 +487,16 @@ class SomeOrganizer
                           end
                         end)
 
-  def call(ctx)
+  def self.call(ctx)
     with(ctx).reduce(actions)
   end
 
-  def actions
-    OneAction,
-    TwoAction,
-    ThreeAction
+  def self.actions
+    [
+      OneAction,
+      TwoAction,
+      ThreeAction
+    ]
   end
 end
 
@@ -451,9 +595,9 @@ class AnOrganizer
 
   def self.call(order)
     with(:order => order).reduce(
-        AnAction,
-        AnotherAction,
-      )
+      AnAction,
+      AnotherAction,
+    )
   end
 end
 
@@ -534,6 +678,15 @@ I, [DATE]  INFO -- : [LightService] - ;-) <TestDoubles::MakesLatteAction> has de
 I, [DATE]  INFO -- : [LightService] - context message: Can't make a latte with a fatty milk like that!
 ```
 
+You can specify the logger on the organizer level, so the organizer does not use the global logger.
+
+```ruby
+class FooOrganizer
+  extend LightService::Organizer
+  log_with Logger.new("/my/special.log")
+end
+```
+
 ## 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:
@@ -610,7 +763,28 @@ Using the `rolled_back` macro is optional for the actions in the chain. You shou
 
 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.
+See [this acceptance test](spec/acceptance/rollback_spec.rb) to learn more about this functionality.
+
+You may find yourself directly using an action that can roll back by calling `.execute` instead of using it from within an Organizer.
+If this action fails and attempts a rollback, a `FailWithRollbackError` exception will be raised. This is so that the organizer can
+rollback the actions one by one. If you don't want to wrap your call to the action with a `begin, rescue FailWithRollbackError`
+block, you can introspect the context like so, and keep your usage of the action clean:
+
+```ruby
+class FooAction
+  extend LightService::Action
+
+  executed do |context|
+    # context.organized_by will be nil if run from an action,
+    # or will be the class name if run from an organizer
+    if context.organized_by.nil?
+      context.fail!
+    else
+      context.fail_with_rollback!
+    end
+  end
+end
+```
 
 ## 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.
@@ -689,9 +863,13 @@ end
 
 To get the value of a `fail!` or `succeed!` message, simply call `#message` on the returned context.
 
-## Orchestrator Logic in Organizers
+## Orchestrating Logic in Organizers
 
-The Organizer - Action combination works really well for simple use cases. However, as business logic gets more complex, or when LightService is used in an ETL workflow, the code that routes the different organizers becomes very complex and imperative. Let's look at a piece of code that does basic data transformations:
+The Organizer - Action combination works really well for simple use cases. However, as business logic gets more complex, or when LightService is used in an ETL workflow, the code that routes the different organizers becomes very complex and imperative.
+
+In the past, this was solved using Orchestrators. As of [Version 0.9.0 Orchestrators have been deprecated](https://github.com/adomokos/light-service/pull/132). All their functionality is now usable directly within Organizers. Read on to understand how to orchestrate workflows from within a single Organizer.
+
+Let's look at a piece of code that does basic data transformations:
 
 ```ruby
 class ExtractsTransformsLoadsData
@@ -745,13 +923,15 @@ end
 
 This code is much easier to reason about, it's less noisy and it captures the goal of LightService well: simple, declarative code that's easy to understand.
 
-The 5 different orchestrator constructs an organizer can have:
+The 7 different orchestrator constructs an organizer can have:
 
 1. `reduce_until`
 2. `reduce_if`
 3. `iterate`
 4. `execute`
 5. `with_callback`
+6. `add_to_context`
+7. `add_aliases`
 
 `reduce_until` behaves like a while loop in imperative languages, it iterates until the provided predicate in the lambda evaluates to true. Take a look at [this acceptance test](spec/acceptance/organizer/reduce_until_spec.rb) to see how it's used.
 
@@ -763,6 +943,10 @@ To take advantage of another organizer or action, you might need to tweak the co
 
 Use `with_callback` when you want to execute actions with a deferred and controlled callback. It works similar to a Sax parser, I've used it for processing large files. The advantage of it is not having to keep large amount of data in memory. See [this acceptance test](spec/acceptance/organizer/with_callback_spec.rb) as a working example.
 
+`add_to_context` can add key-value pairs on the fly to the context. This functionality is useful when you need a value injected into the context under a specific key right before the subsequent actions are executed. Keys are also made available as accessors on the context object and can be used just like methods exposed via `expects` and `promises`. [This test](spec/acceptance/organizer/add_to_context_spec.rb) describes its functionality.
+
+Your action needs a certain key in the context but it's under a different one? Use the function `add_aliases` to alias an existing key in the context under the desired key. Take a look at [this test](spec/acceptance/organizer/add_aliases_spec.rb) to see an example.
+
 ## ContextFactory for Faster Action Testing
 
 As the complexity of your workflow increases, you will find yourself spending more and more time creating a context (LightService::Context it is) for your action tests. Some of this code can be reused by clever factories, but still, you are using a context that is artificial, and can be different from what the previous actions produced. This is especially true, when you use LightService in ETLs, where you start out with initial data and your actions are mutating its state.
@@ -816,28 +1000,59 @@ This context then can be passed to the action under test, freeing you up from th
 
 In case your organizer has more logic in its `call` method, you could create your own test organizer in your specs like you can see it in this [acceptance test](spec/acceptance/testing/context_factory_spec.rb#L4-L11). This is reusable in all your action tests.
 
-## Requirements
+## Rails support
+
+LightService includes Rails generators for creating both Organizers and Actions along with corresponding tests. Currently only RSpec is
+supported ([PR's for supporting MiniTest are welcome](https://github.com/adomokos/light-service/pulls))
 
-This gem requires ruby 2.x
+Note: Generators are namespaced to `light_service` not `light-service` due to Rake name constraints.
 
-## Installation
-Add this line to your application's Gemfile:
+### Organizer generation
 
-    gem 'light-service'
+```shell
+rails generate light_service:organizer My::SuperFancy::Organizer
+# -- or
+rails generate light_service:organizer my/super_fancy/organizer
+```
 
-And then execute:
+Options for this generator are:
 
-    $ bundle
+* `--dir=<SOME_DIR>`. `<SOME_DIR>` defaults to `organizers`. Will write organizers to `/app/organizers`, and specs to `/spec/organizers`
+* `--no-tests`. Default is `--tests`. Will generate a test file matching the namespace you've supplied.
 
-Or install it yourself as:
+### Action generation
+
+```shell
+rails generate light_service:action My::SuperFancy::Action
+# -- or
+rails generate light_service:action my/super_fancy/action
+```
+
+Options for this generator are:
+
+* `--dir=<SOME_DIR>`. `<SOME_DIR>` defaults to `actions`. Will write actions to `/app/actions`, and specs to `/spec/actions`
+* `--no-tests`. Defaults is `--tests`. Will generate a test file matching the namespace you've supplied.
+* `--no-roll-back`. Default is `--roll-back`. Will generate a `rolled_back` block for you to implement with [roll back functionality](#action-rollback).
+
+### Advanced action generation
+
+You are able to optionally specify `expects` and/or `promises` keys during generation
+
+```shell
+rails generate light_service:action CrankWidget expects:one_fish,two_fish promises:red_fish,blue_fish
+```
+
+When specifying `expects`, convenience variables will be initialized in the `executed` block so that you don't have to call
+them through the context. A stub context will be created in the test file using these keys too.
 
-    $ gem install light-service
+When specifying `promises`, specs will be created testing for their existence after executing the action.
 
-## 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.
+## Other implementations
 
-For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki).
+| Language | Repo                                                              | Author                                                 |
+| :------- |:------------------------------------------------------------------| :------------------------------------------------------|
+| Python   | [pyservice](https://github.com/adomokos/pyservice)                | [@adomokos](https://github.com/adomokos)               |
+| PHP      | [light-service](https://github.com/douglasgreyling/light-service) | [@douglasgreyling](https://github.com/douglasgreyling) |
 
 ## Contributing
 1. Fork it