workflow 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60901ed58fefbe1ef7c4e6b4ec5f06c307c3b6c1669f6838d9990bd15ef452ad
-  data.tar.gz: d4f5f51c86f382b65ae4850ede4a7749f9dcc2153e544cdf3c068a0af7561799
+  metadata.gz: a90286a0749bd94cabc4fab8cc89dc5c9fc7b05d60ea5cf58cd6493852159206
+  data.tar.gz: 8c4015a8ba91be4c4fc37bd5e8004534146d1daedfd290d32538edec33ac02a3
 SHA512:
-  metadata.gz: dd5fc9eeb0062c0dd432406be66c47bf64530c5f89b95364af6cc92821199c821e895ad16eab361939f02c6ccbbf21bcba33048e2014f56dd920a7bb22219382
-  data.tar.gz: 7d9ca2e0b4e8873bb3802944f29879f0606ccf14adc392cb6a63e5ba2fe2a5c70245fc78e4a4026b374f9b39b4d3330630df2398f22187c86ae2be32da17d78d
+  metadata.gz: b72b7e1d8de350a9e5478d291d7ff6a1e0f6f192bff31eac6951f9f5e8fbf4941597e84e990838402902fb65fa79acabfffdfc5fd168d937967e5d63239dc7f1
+  data.tar.gz: 9aaea40918c7f2b55b9e51a8ae881708869af77e22995545a5e5017731b19575d7f0ed0a6ffbd5343a6c8883854d81e83749e7447abedd796d6c2d77345bebf8

data/README.adoc

@@ -0,0 +1,564 @@
+:doctype: book
+:toc: macro
+:toclevels: 1
+:sectlinks:
+:idprefix:
+
+# Workflow
+
+image:https://img.shields.io/gem/v/workflow.svg[link=https://rubygems.org/gems/workflow]
+image:https://github.com/geekq/workflow/actions/workflows/test.yml/badge.svg[link=https://github.com/geekq/workflow/actions/workflows/test.yml]
+image:https://codeclimate.com/github/geekq/workflow/badges/gpa.svg[link=https://codeclimate.com/github/geekq/workflow]
+image:https://codeclimate.com/github/geekq/workflow/badges/coverage.svg[link=https://codeclimate.com/github/geekq/workflow/coverage]
+
+Note: you can find documentation for specific workflow rubygem versions
+at http://rubygems.org/gems/workflow : select a version (optional,
+default is latest release), click "Documentation" link. When reading on
+github.com, the README refers to the upcoming release.
+
+toc::[]
+
+What is workflow?
+-----------------
+
+Workflow is a finite-state-machine-inspired API for modeling and
+interacting with what we tend to refer to as 'workflow'.
+
+A lot of business modeling tends to involve workflow-like concepts, and
+the aim of this library is to make the expression of these concepts as
+clear as possible, using similar terminology as found in state machine
+theory.
+
+So, a workflow has a state. It can only be in one state at a time. When
+a workflow changes state, we call that a transition. Transitions occur
+on an event, so events cause transitions to occur. Additionally, when an
+event fires, other arbitrary code can be executed, we call those actions.
+So any given state has a bunch of events, any event in a state causes a
+transition to another state and potentially causes code to be executed
+(an action). We can hook into states when they are entered, and exited
+from, and we can cause transitions to fail (guards), and we can hook in
+to every transition that occurs ever for whatever reason we can come up
+with.
+
+Now, all that's a mouthful, but we'll demonstrate the API bit by bit
+with a real-ish world example.
+
+Let's say we're modeling article submission from journalists. An article
+is written, then submitted. When it's submitted, it's awaiting review.
+Someone reviews the article, and then either accepts or rejects it.
+Here is the expression of this workflow using the API:
+
+```rb
+class Article
+  include Workflow
+  workflow do
+    state :new do
+      event :submit, :transitions_to => :awaiting_review
+    end
+    state :awaiting_review do
+      event :review, :transitions_to => :being_reviewed
+    end
+    state :being_reviewed do
+      event :accept, :transitions_to => :accepted
+      event :reject, :transitions_to => :rejected
+    end
+    state :accepted
+    state :rejected
+  end
+end
+```
+
+Nice, isn't it!
+
+Note: the first state in the definition (`:new` in the example, but you
+can name it as you wish) is used as the initial state - newly created
+objects start their life cycle in that state.
+
+Let's create an article instance and check in which state it is:
+
+```rb
+article = Article.new
+article.accepted? # => false
+article.new? # => true
+```
+
+You can also access the whole `current_state` object including the list
+of possible events and other meta information:
+
+    article.current_state
+    => #<Workflow::State:0x7f1e3d6731f0 @events={
+      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
+        @transitions_to=:awaiting_review, @name=:submit, @meta={}>},
+      name:new, meta{}
+
+You can also check, whether a state comes before or after another state (by the
+order they were defined):
+
+```rb
+article.current_state # => being_reviewed
+article.current_state < :accepted # => true
+article.current_state >= :accepted # => false
+article.current_state.between? :awaiting_review, :rejected # => true
+```
+
+Now we can call the submit event, which transitions to the
+<tt>:awaiting_review</tt> state:
+
+```rb
+article.submit!
+article.awaiting_review? # => true
+```
+
+Events are actually instance methods on a workflow, and depending on the
+state you're in, you'll have a different set of events used to
+transition to other states.
+
+It is also easy to check, if a certain transition is possible from the
+current state . `article.can_submit?` checks if there is a `:submit`
+event (transition) defined for the current state.
+
+
+Getting started
+---------------
+
+=== Installation
+
+```sh
+gem install workflow
+```
+
+**Important**: If you're interested in graphing your workflow state machine, you will also need to
+install the `activesupport` and `ruby-graphviz` gems.
+
+Versions up to and including 1.0.0 are also available as a single file download -
+[lib/workflow.rb file](https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb).
+
+
+=== Examples
+
+After installation or downloading the library you can easily try out
+all the example code from this README in irb.
+
+    $ irb
+    require 'rubygems'
+    require 'workflow'
+
+Now just copy and paste the source code from the beginning of this README
+file snippet by snippet and observe the output.
+
+
+### Transition event handler
+
+The best way is to use convention over configuration and to define a
+method with the same name as the event. Then it is automatically invoked
+when event is raised. For the Article workflow defined earlier it would
+be:
+
+```rb
+class Article
+  def reject
+    puts 'sending email to the author explaining the reason...'
+  end
+end
+```
+
+`article.review!; article.reject!` will cause state transition to
+`being_reviewed` state, persist the new state (if integrated with
+ActiveRecord), invoke this user defined `reject` method and finally
+persist the `rejected` state.
+
+Note: on successful transition from one state to another the workflow
+gem immediately persists the new workflow state with `update_column()`,
+bypassing any ActiveRecord callbacks including `updated_at` update.
+This way it is possible to deal with the validation and to save the
+pending changes to a record at some later point instead of the moment
+when transition occurs.
+
+You can also define event handler accepting/requiring additional
+arguments:
+
+```rb
+class Article
+  def review(reviewer = '')
+    puts "[#{reviewer}] is now reviewing the article"
+  end
+end
+
+article2 = Article.new
+article2.submit!
+article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
+```
+
+Alternative way is to use a block (only recommended for short event
+implementation without further code nesting):
+
+```rb
+event :review, :transitions_to => :being_reviewed do |reviewer|
+  # store the reviewer
+end
+```
+
+We've noticed, that mixing the list of events and states with the blocks
+invoked for particular transitions leads to a bumpy and poorly readable code
+due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually
+we decided to invoke an optional user defined callback method with the same
+name as the event (convention over configuration) as explained before.
+
+State persistence
+-----------------
+
+=== ActiveRecord
+
+Note: Workflow 2.0 is a major refactoring for the `worklow` library.
+If your application suddenly breaks after the workflow 2.0 release, you've
+probably got your Gemfile wrong ;-). workflow uses
+https://guides.rubygems.org/patterns/#semantic-versioning[semantic versioning].
+For highest compatibility please reference the desired major+minor version.
+
+Note on ActiveRecord/Rails 4.\*, 5.\* Support:
+
+Since integration with ActiveRecord makes over 90% of the issues and
+maintenance effort, and also to allow for an independent (faster) release cycle
+for Rails support, starting with workflow **version 2.0** in January 2019 the
+support for ActiveRecord (4.\*, 5.\* and newer) has been extracted into a separate
+gem. Read at
+https://github.com/geekq/workflow-activerecord[workflow-activerecord], how to
+include the right gem.
+
+To use legacy built-in ActiveRecord 2.3 - 4.* support, reference Workflow 1.2 in
+your Gemfile:
+
+    gem 'workflow', '~> 1.2'
+
+
+=== Custom workflow state persistence
+
+If you do not use a relational database and ActiveRecord, you can still
+integrate the workflow very easily. To implement persistence you just
+need to override `load_workflow_state` and
+`persist_workflow_state(new_value)` methods. Next section contains an example for
+using CouchDB, a document oriented database.
+
+http://tim.lossen.de/[Tim Lossen] implemented support
+for http://github.com/tlossen/remodel[remodel] / http://github.com/antirez/redis[redis]
+key-value store.
+
+=== Integration with CouchDB
+
+We are using the compact http://github.com/geekq/couchtiny[couchtiny library]
+here. But the implementation would look similar for the popular
+couchrest library.
+
+```rb
+require 'couchtiny'
+require 'couchtiny/document'
+require 'workflow'
+
+class User < CouchTiny::Document
+  include Workflow
+  workflow do
+    state :submitted do
+      event :activate_via_link, :transitions_to => :proved_email
+    end
+    state :proved_email
+  end
+
+  def load_workflow_state
+    self[:workflow_state]
+  end
+
+  def persist_workflow_state(new_value)
+    self[:workflow_state] = new_value
+    save!
+  end
+end
+```
+
+Please also have a look at
+http://github.com/geekq/workflow/blob/develop/test/couchtiny_example.rb[the full source code].
+
+
+=== Adapters to support other databases
+
+I get a lot of requests to integrate persistence support for different
+databases, object-relational adapters, column stores, document
+databases.
+
+To enable highest possible quality, avoid too many dependencies and to
+avoid unneeded maintenance burden on the `workflow` core it is best to
+implement such support as a separate gem.
+
+Only support for the ActiveRecord will remain for the foreseeable
+future. So Rails beginners can expect `workflow` to work with Rails out
+of the box. Other already included adapters stay for a while but should
+be extracted to separate gems.
+
+If you want to implement support for your favorite ORM mapper or your
+favorite NoSQL database, you just need to implement a module which
+overrides the persistence methods `load_workflow_state` and
+`persist_workflow_state`. Example:
+
+```rb
+module Workflow
+  module SuperCoolDb
+    module InstanceMethods
+      def load_workflow_state
+        # Load and return the workflow_state from some storage.
+        # You can use self.class.workflow_column configuration.
+      end
+
+      def persist_workflow_state(new_value)
+        # save the new_value workflow state
+      end
+    end
+
+    module ClassMethods
+      # class methods of your adapter go here
+    end
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+  end
+end
+```
+
+The user of the adapter can use it then as:
+
+```rb
+class Article
+  include Workflow
+  include Workflow:SuperCoolDb
+  workflow do
+    state :submitted
+    # ...
+  end
+end
+```
+
+I can then link to your implementation from this README. Please let me
+also know, if you need any interface beyond `load_workflow_state` and
+`persist_workflow_state` methods to implement an adapter for your
+favorite database.
+
+Advanced usage
+--------------
+
+### Accessing your workflow specification
+
+You can easily reflect on workflow specification programmatically - for
+the whole class or for the current object. Examples:
+
+```rb
+article2.current_state.events # lists possible events from here
+article2.current_state.events[:reject].transitions_to # => :rejected
+
+Article.workflow_spec.states.keys
+#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
+
+Article.workflow_spec.state_names
+#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
+
+# list all events for all states
+Article.workflow_spec.states.values.collect &:events
+```
+
+You can also store and later retrieve additional meta data for every
+state and every event:
+
+```rb
+class MyProcess
+  include Workflow
+  workflow do
+    state :main, :meta => {:importance => 8}
+    state :supplemental, :meta => {:importance => 1}
+  end
+end
+puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1
+```
+
+The workflow library itself uses this feature to tweak the graphical
+representation of the workflow. See below.
+
+
+### Conditional event transitions
+
+Conditions can be a "method name symbol" with a corresponding instance method, a `proc` or `lambda` which are added to events, like so:
+
+```rb
+state :off
+  event :turn_on, :transition_to => :on,
+                  :if => :sufficient_battery_level?
+
+  event :turn_on, :transition_to => :low_battery,
+                  :if => proc { |device| device.battery_level > 0 }
+end
+
+# corresponding instance method
+def sufficient_battery_level?
+  battery_level > 10
+end
+```
+
+When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>!`, each event is checked in turn:
+
+* With no `:if` check, proceed as usual.
+* If an `:if` check is present, proceed if it evaluates to true, or drop to the next event.
+* If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible.
+
+
+### Advanced transition hooks
+
+#### on_entry/on_exit
+
+We already had a look at the declaring callbacks for particular workflow
+events. If you would like to react to all transitions to/from the same state
+in the same way you can use the on_entry/on_exit hooks. You can either define it
+with a block inside the workflow definition or through naming
+convention, e.g. for the state :pending just define the method
+`on_pending_exit(new_state, event, *args)` somewhere in your class.
+
+#### on_transition
+
+If you want to be informed about everything happening everywhere, e.g. for
+logging then you can use the universal `on_transition` hook:
+
+```rb
+workflow do
+  state :one do
+    event :increment, :transitions_to => :two
+  end
+  state :two
+  on_transition do |from, to, triggering_event, *event_args|
+    Log.info "#{from} -> #{to}"
+  end
+end
+```
+
+#### on_error
+
+If you want to do custom exception handling internal to workflow, you can define an `on_error` hook in your workflow.
+For example:
+
+```rb
+workflow do
+  state :first do
+    event :forward, :transitions_to => :second
+  end
+  state :second
+
+  on_error do |error, from, to, event, *args|
+    Log.info "Exception(#{error.class}) on #{from} -> #{to}"
+  end
+end
+```
+
+If forward! results in an exception, `on_error` is invoked and the workflow stays in a 'first' state.  This capability
+is particularly useful if your errors are transient and you want to queue up a job to retry in the future without
+affecting the existing workflow state.
+
+### Guards
+
+If you want to halt the transition conditionally, you can just raise an
+exception in your [transition event handler](#transition_event_handler).
+There is a helper called `halt!`, which raises the
+Workflow::TransitionHalted exception. You can provide an additional
+`halted_because` parameter.
+
+```rb
+def reject(reason)
+  halt! 'We do not reject articles unless the reason is important' \
+    unless reason =~ /important/i
+end
+```
+
+The traditional `halt` (without the exclamation mark) is still supported
+too. This just prevents the state change without raising an
+exception.
+
+You can check `halted?` and `halted_because` values later.
+
+### Hook order
+
+The whole event sequence is as follows:
+
+    * before_transition
+    * event specific action
+    * on_transition (if action did not halt)
+    * on_exit
+    * PERSIST WORKFLOW STATE, i.e. transition
+    * on_entry
+    * after_transition
+
+
+Documenting with diagrams
+-------------------------
+
+You can generate a graphical representation of the workflow for
+a particular class for documentation purposes.
+Use `Workflow::create_workflow_diagram(class)` in your rake task like:
+
+```rb
+namespace :doc do
+  desc "Generate a workflow graph for a model passed e.g. as 'MODEL=Order'."
+  task :workflow => :environment do
+    require 'workflow/draw'
+    Workflow::Draw::workflow_diagram(ENV['MODEL'].constantize)
+  end
+end
+```
+
+
+Changelog
+---------
+
+=== New in the version 3.0.0
+
+* gh-228 Support for Ruby 3 keyword args, provided by @agirling
+* retire Ruby 2.6 since it has reached end of live; please use workflow 2.x, if you still depend on that Ruby version
+* gh-229 Switch from travis CI to GihHub actions for continuous integration
+
+### New in the versions 2.x
+
+* extract persistence adapters, Rails/ActiveRecord integration is now a separate gem
+  workflow-activerecord
+
+Support, Participation
+----------------------
+
+### Reporting bugs
+
+<http://github.com/geekq/workflow/issues>
+
+### Development Setup
+
+```sh
+sudo apt-get install graphviz # Linux
+brew install graphviz # Mac OS
+cd workflow
+gem install bundler
+bundle install
+# run all the tests
+bundle exec rake test
+```
+
+### Other 3rd party libraries
+
+https://github.com/kwent/active_admin-workflow[ActiveAdmin-Workflow] - is an
+integration with https://github.com/activeadmin/activeadmin[ActiveAdmin].
+
+### About
+
+Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
+
+Copyright (c) 2010-2022 Vladimir Dobriakov and Contributors
+
+Copyright (c) 2008-2009 Vodafone
+
+Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
+
+Based on the work of Ryan Allen and Scott Barron
+
+Licensed under MIT license, see the MIT-LICENSE file.
+

data/lib/workflow/draw.rb

@@ -41,6 +41,7 @@ module Workflow
         :font => 'Helvetica'
       }.merge options
 
+      require 'ruby-graphviz'
       graph = ::GraphViz.new('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB', :ratio => options[:ratio])
 
       # Add nodes

data/lib/workflow/version.rb

@@ -1,3 +1,3 @@
 module Workflow
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end