light-service 0.13.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e9dfb5cf61024afa28719b84e160c9580fa39c99eda19b73cdb0cced9017da2
-  data.tar.gz: 7f389c208b3b06000c84859d595d9b49acf8dfe8d370736ee564a1ae8ef8b5d1
+  metadata.gz: b37602f04d4539ba8d8622f9e226c916071760ee37e21c7add4e1972f9c5175f
+  data.tar.gz: f55175d1a477c78896522f4bdca07697ceb80c7b62fca80e4c6803ff06bb2ec7
 SHA512:
-  metadata.gz: b1b7792d344efe1aab4297f8774649590b8e0336a44082da31a167a62b75a039b7f89759923beb9a463f6c017b0387297efc815f357deae31270b54e2c1c1bcc
-  data.tar.gz: 0d1d339a23d2d7b39bd5403d81fe1e1519a89eec22fd64f00931d9dc49a81c5476f67e6dd28591e0e88c55b1378d1155ed0d1700100569aa9b43a1922c860f3e
+  metadata.gz: d087df4f8d16b2e4f2611ac9e026906d2c7bb40cbe19b31052a71ed87e7ed5d70016bfc6ccfff363a4a04df7e9ff676c495d5246a7f69a142897cede456e99f4
+  data.tar.gz: 2317cff4254ae4bb6a20f481f042e2e63785fa015f130e4d01acb799f65e1e1db5f1f8fe1ebe9fdc973617925c456f8e4d024fe20ba0af98204a65a0c0f81b78

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/.travis.yml

@@ -4,10 +4,9 @@ env:
   - RUN_COVERAGE_REPORT=true
 
 rvm:
-  - 2.4.2
   - 2.5.3
-  - 2.6.0
-  - 2.7.0
+  - 2.6.6
+  - 2.7.2
 
 before_install:
   - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'
@@ -20,16 +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.4.2
-    gemfile: gemfiles/activesupport_6.gemfile
-  - rvm: 2.7.0
-    gemfile: gemfiles/activesupport_3.gemfile
-  - rvm: 2.7.0
+  - 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

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,33 +1,38 @@
 ![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.svg)](http://travis-ci.org/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)
 * [Benchmarking Actions with Around Advice](#benchmarking-actions-with-around-advice)
 * [Before and After Action Hooks](#before-and-after-action-hooks)
+* [Expects and Promises](#expects-and-promises)
+    * [Default values for optional Expected keys](#default-values-for-optional-expected-keys)
 * [Key Aliases](#key-aliases)
 * [Logging](#logging)
 * [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?
 
@@ -175,7 +180,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:
@@ -390,9 +531,11 @@ These ideas are originally from Aspect Oriented Programming, read more about the
 ## 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
-action is reduced. If either of them are violated, a custom exception is thrown.
+action is reduced. If either of them are violated, a `LightService::ExpectedKeysNotInContextError` or
+`LightService::PromisedKeysNotInContextError` exception respectively will be thrown.
 
 This is how it's used:
+
 ```ruby
 class FooAction
   extend LightService::Action
@@ -400,46 +543,78 @@ class FooAction
   promises :bar
 
   executed do |context|
-    baz = context.fetch :baz
-
-    bar = baz + 2
-    context[:bar] = bar
+    context.bar = context.baz + 2
   end
 end
 ```
 
-The `expects` macro does a bit more for you: it pulls the value with the expected key from the context, and
-makes it available to you through a reader. You can refactor the action like this:
+The `expects` macro will pull the value with the expected key from the context, and
+makes it available to you through a reader.
+
+The `promises` macro will not only check if the context has the promised keys, it
+also sets them for you in the context if you use the accessor with the same name,
+much the same way as the expects macro works.
+
+The context object is essentially a smarter-than-normal Hash. Take a look at [this spec](spec/action_expects_and_promises_spec.rb)
+to see expects and promises used with and without accessors.
+
+### Default values for optional Expected keys
+
+When you have an expected key that has a sensible default which should be used everywhere and
+only overridden on an as-needed basis, you can specify a default value. An example use-case
+is a flag that allows a failure from a service under most circumstances to avoid failing an
+entire workflow because of a non-critical action.
+
+LightService provides two mechanisms for specifying default values:
+
+1. A static value that is used as-is
+2. A callable that takes the current context as a param
+
+Using the above use case, consider an action that sends a text message. In most cases,
+if there is a problem sending the text message, it might be OK for it to fail. We will
+`expect` an `allow_failure` key, but set it with a default, like so:
 
 ```ruby
-class FooAction
+class SendSMS
   extend LightService::Action
-  expects :baz
-  promises :bar
+  expects :message, :user
+  expects :allow_failure, default: true
 
   executed do |context|
-    bar = context.baz + 2
-    context[:bar] = bar
+    sms_api = SMSService.new(key: ENV["SMS_API_KEY"])
+    status  = sms_api.send(ctx.user.mobile_number, ctx.message)
+
+    if !status.sent_ok?
+      ctx.fail!(status.err_msg) unless ctx.allow_failure
+    end
   end
 end
 ```
 
-The `promises` macro will not only check if the context has the promised keys, it also sets it for you in the context if
-you use the accessor with the same name. The code above can be further simplified:
+Default values can also be processed dynamically by providing a callable. Any values already
+specified in the context are available to it via Hash key lookup syntax. e.g.
 
 ```ruby
-class FooAction
+class SendSMS
   extend LightService::Action
-  expects :baz
-  promises :bar
+  expects :message, :user
+  expects :allow_failure, default: ->(ctx) { !ctx[:user].admin? } # Admins must always get SMS'
 
   executed do |context|
-    context.bar = context.baz + 2
+    sms_api = SMSService.new(key: ENV["SMS_API_KEY"])
+    status  = sms_api.send(ctx.user.mobile_number, ctx.message)
+
+    if !status.sent_ok?
+      ctx.fail!(status.err_msg) unless ctx.allow_failure
+    end
   end
 end
 ```
 
-Take a look at [this spec](spec/action_expects_and_promises_spec.rb) to see the refactoring in action.
+**Note** that default values must be specified one at a time on their own line.
+
+You can then call an action or organizer that uses an action with defaults without specifying
+the expected key that has a default.
 
 ## Key Aliases
 The `aliases` macro sets up pairs of keys and aliases in an organizer. Actions can access the context using the aliases.
@@ -624,7 +799,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.
@@ -703,9 +899,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.
+
+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.
 
-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:
+Let's look at a piece of code that does basic data transformations:
 
 ```ruby
 class ExtractsTransformsLoadsData
@@ -763,23 +963,26 @@ 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`
+3. `reduce_if_else`
+4. `iterate`
+5. `execute`
+6. `with_callback`
+7. `add_to_context`
+8. `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.
 
 `reduce_if` will reduce the included organizers and/or actions if the predicate in the lambda evaluates to true. [This acceptance test](spec/acceptance/organizer/reduce_if_spec.rb) describes this functionality.
 
+`reduce_if_else` takes three arguments, a condition lambda, a first set of "if true" steps, and a second set of "if false" steps. If the lambda evaluates to true, the "if true" steps are executed, otherwise the "else steps" are executed. [This acceptance test](spec/acceptance/organizer/reduce_if_else_spec.rb) describes this functionality.
+
 `iterate` gives your iteration logic, the symbol you define there has to be in the context as a key. For example, to iterate over items you will use `iterate(:items)` in your steps, the context needs to have `items` as a key, otherwise it will fail. The organizer will singularize the collection name and will put the actual item into the context under that name. Remaining with the example above, each element will be accessible by the name `item` for the actions in the `iterate` steps. [This acceptance test](spec/acceptance/organizer/iterate_spec.rb) should provide you with an example.
 
 To take advantage of another organizer or action, you might need to tweak the context a bit. Let's say you have a hash, and you need to iterate over its values in a series of action. To alter the context and have the values assigned into a variable, you need to create a new action with 1 line of code in it. That seems a lot of ceremony for a simple change. You can do that in a `execute` method like this `execute(->(ctx) { ctx[:some_values] = ctx.some_hash.values })`. [This test](spec/acceptance/organizer/execute_spec.rb) describes how you can use it.
 
 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. [This test](spec/acceptance/organizer/add_to_context_spec.rb) describes its functionality.
+`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.
 
@@ -836,28 +1039,61 @@ 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.
+
+When specifying `promises`, specs will be created testing for their existence after executing the action.
 
-    $ gem install light-service
+## Other implementations
 
-## 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.
+| 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) |
+| JavaScript | [light-service.js](https://github.com/douglasgreyling/light-service.js) | [@douglasgreyling](https://github.com/douglasgreyling) |
 
-For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki).
 
 ## Contributing
 1. Fork it