flow_core 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8930957495dfe27e025aaebc7b0c88b665cd421ddcba835cc4680776279553d
+  data.tar.gz: 02d2f3166cde5e4d90226163d05ba8ffac13a26df81e1221040fbf8914933b5c
+SHA512:
+  metadata.gz: 96ce06af9cce87d138115bce55601dd0d3e278192c6052b82546ed1e2fad741876c5f0f01fbe71d37d01b04c60bf8d46e2a3c289f616d25bd5316cdff65a646a
+  data.tar.gz: 6fbc984298817220c0569484d40e7d8136013ad499d62d119fe43bfb6621a00a2056c59c07d1bf6bae6dfa82e91c06c1775a82a0d2f1e87ae093e540f43ec8fa

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 jasl
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,255 @@
+Flow Core
+===
+
+> FlowCore is ready for open reviewing, but it haven't tested in production yet,
+> any help are most welcome, breaking change is acceptable.
+
+A multi purpose, extendable, Workflow-net-based workflow engine for Rails applications.
+
+FlowCore is an open source Rails engine provides core workflow functionalities,
+including workflow definition and workflow instance scheduling.
+Easily making automation (including CI, CD, Data processing, etc.) and BPM applications or help you solve parts which changing frequently.
+
+## Features
+
+### Support all databases which based on ActiveRecord
+
+All persistent data are present as ActiveRecord model and not use any DB-specific feature.
+
+### Easy to extend & hack
+
+FlowCore basically followed best practice of Rails engine,
+you can extend as [Rails Guides](https://guides.rubyonrails.org/engines.html#improving-engine-functionality) suggests.
+
+Your app-specific workflow triggers, callbacks and guards can be extended via [Single Table Inheritance](https://guides.rubyonrails.org/association_basics.html#single-table-inheritance)
+
+FlowCore also provides callbacks for triggers (which control behavior of a transition) covered whole task lifecycle.
+
+### Petri-net based
+
+[Petri-net](https://en.wikipedia.org/wiki/Petri_net) is a technique for description and analysis of concurrent systems.
+
+FlowCore choose its special type called [Workflow-net](http://mlwiki.org/index.php/Workflow_Nets) to expressing workflow.
+
+Compared to more popular activity-based workflow definitions (e.g BPMN),
+Petri-net has only few rules but could express very complex case.
+
+Check [workflow patterns](http://workflowpatterns.com) to learn how to use Petri-net expressing workflows.
+
+### Basic workflow checking.
+
+A workflow should be verified first before running it.
+
+FlowCore provides the mechanism to help to prevent unexpected error on instance running
+
+> This is the hard work and help wanted
+> Workflow-net has [soundness](http://mlwiki.org/index.php/Workflow_Soundness) checking but I don't know how to implement it
+
+### Interfaces and abstractions to integrate your business
+
+FlowCore separate app-world and engine-world using interfaces and abstract classes,
+basically you no need to know Workflow-net internal works.
+
+### Runtime error and suspend support
+
+FlowCore provides necessary columns and event callbacks for runtime error and suspend.
+
+### A DSL to simplify workflow creation
+
+FlowCore provides a powerful DSL for creating workflow.
+
+## Demo
+
+**You need to install Graphviz first**
+
+Clone the repository.
+
+```sh
+$ git clone https://github.com/rails-engine/flow_core.git
+```
+
+Change directory
+
+```sh
+$ cd flow_core
+```
+
+Run bundler
+
+```sh
+$ bundle install
+```
+
+Preparing database
+
+```sh
+$ bin/rails db:migrate
+```
+
+Import sample workflow
+
+```sh
+$ bin/rails db:seed
+```
+
+Start the Rails server
+
+```sh
+$ bin/rails s
+```
+
+Open your browser, and visit `http://localhost:3000`
+
+## Design
+
+Architecture:
+
+![Architecture](doc/assets/architecture.png)
+
+Basic design based on [An activity based Workflow Engine for PHP By Tony Marston](https://www.tonymarston.net/php-mysql/workflow.html).
+
+Some notable:
+
+- Arc: The line to connecting a Place and a Transition
+- ArcGuard: The matcher to decide the arc is passable,
+            it's an base class that you can extend it for your own purpose.
+- Task: A stateful record to present current workflow instance work,
+        and can reference a `TaskExecutable` through Rails polymorphic-reference.
+        It finish means the transition is done and can moving on.
+- TaskExecutable: An interface for binding App task and FlowCore Task.
+- TransitionTrigger: It controls the behavior of a Transition,
+                     it's an base class that you can extend it for your own purpose,
+                     best place for implementing business.
+- TransitionCallback: It can be registered to a Transition, and be triggered on specified lifecycle(s) of Task
+
+### Lifecycle of Task
+
+- `created` Task created by a Petri-net Token
+- `enabled` Transit to this stage when next transition requirement fulfilled
+    - Best chance to create app task (your custom task for business) in `TransitionTrigger#on_task_enabled`
+- `finished` Normal ending
+    - Require app task finished first (if bind)
+- `terminated` Task killed by instance (e.g Instance cancelled) or other race condition task
+
+### FlowKit
+
+Because FlowCore only care about essentials of workflow engine,
+I'm planning a gem based on FlowCore to provides BPM-oriented features, including:
+
+- Dynamic form
+- Approval Task with assignment
+- ExpressionGuard
+
+### Why "core"
+
+Because it's not aim to "out-of-box",
+some gem like Devise giving developer an out-of-box experience, that's awesome,
+but on the other hand, it also introducing a very complex abstraction that may hard to understanding how it works,
+especially when you attempting to customize it.
+
+I believe that the gem is tightly coupled with features that face to end users directly,
+so having a good customizability and easy to understanding are of the most concern,
+so I just wanna give you a domain framework that you can build your own that just fitting your need,
+and you shall have fully control and without any unnecessary abstraction.
+
+## TODO / Help wanted
+
+- Document
+- Test
+- Activity-based to Petri-net mapping, see <https://www.researchgate.net/figure/The-mapping-between-BPMN-and-Petri-nets_tbl2_221250389> for example.
+- More efficient and powerful workflow definition checking
+- Grammar and naming correction (I'm not English native-speaker)
+
+## Usage
+
+> WIP
+
+### Deploy a workflow
+
+See [test/dummy/db/seeds.rb](test/dummy/db/seeds.rb) to learn the DSL, more complex sample see [test/dummy/app/models/internal_workflow.rb](test/dummy/app/models/internal_workflow.rb)
+
+### Running a workflow
+
+`workflow.create_instance!`
+
+### Implementing an ArcGuard
+
+[test/dummy/app/models/arc_guards/dentaku.rb](test/dummy/app/models/arc_guards/dentaku.rb) shows an expression guard which using [Dentaku](https://github.com/rubysolo/dentaku)
+
+### Implementing a TransitionTrigger
+
+[test/dummy/app/models/transition_triggers/timer.rb](test/dummy/app/models/transition_triggers/timer.rb) shows a delayed trigger which can be used for expires.
+
+[test/dummy/app/models/transition_triggers/user_task.rb](test/dummy/app/models/transition_triggers/user_task.rb) shows a simple user task with a simple assignment.
+
+### Implementing a TransitionCallback
+
+[test/dummy/app/models/transition_callbacks/notification.rb](test/dummy/app/models/transition_callbacks/notification.rb) shows a simple callback that notify the assignee when the task started
+
+### Implementing a TaskExecutable
+
+[test/dummy/app/models/user_task.rb](test/dummy/app/models/user_task.rb) shows a sample,
+[test/dummy/app/models/approval_task.rb](test/dummy/app/models/approval_task.rb) shows how to set payload to task that use for ArcGuard
+
+### Extending Workflow
+
+[test/dummy/app/models/internal_workflow.rb](test/dummy/app/models/internal_workflow.rb) shows how to use STI extending Workflow.
+
+[test/dummy/app/overrides/models/flow_core/workflow_override.rb](test/dummy/app/overrides/models/flow_core/workflow_override.rb) shows how to apply Rails override pattern to extend base model,
+here I add `to_graphviz` for dummy app visualize workflows.
+
+## Requirement
+
+- Rails 6.0+
+- Ruby 2.5+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "flow_core"
+```
+
+Or you may want to include the gem directly from GitHub:
+
+```ruby
+gem 'flow_core', github: 'rails-engine/flow_core'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install flow_core
+```
+
+## References
+
+- [hooopo/petri_flow](https://github.com/hooopo/petri_flow) (my partner's version, we share the same basis)
+- <http://mlwiki.org/index.php/Petri_Nets>
+- <https://www.tonymarston.net/php-mysql/workflow.html>
+- <http://workflowpatterns.com/>
+
+## Contributing
+
+Bug report or pull request are welcome.
+
+### Make a pull request
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+Please write unit test with your code if necessary.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "FlowCore"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/models/flow_core/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module FlowCore
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/flow_core/arc.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FlowCore
+  class Arc < FlowCore::ApplicationRecord
+    self.table_name = "flow_core_arcs"
+
+    belongs_to :workflow, class_name: "FlowCore::Workflow"
+    belongs_to :transition, class_name: "FlowCore::Transition"
+    belongs_to :place, class_name: "FlowCore::Place"
+
+    has_many :guards, class_name: "FlowCore::ArcGuard", dependent: :delete_all
+
+    enum direction: {
+      in: 0,
+      out: 1
+    }
+
+    validates :place,
+              uniqueness: {
+                scope: %i[workflow transition direction]
+              }
+
+    before_destroy :prevent_destroy
+    after_create :reset_workflow_verification
+    after_destroy :reset_workflow_verification
+
+    def can_destroy?
+      workflow.instances.empty?
+    end
+
+    private
+
+      def reset_workflow_verification
+        workflow.reset_workflow_verification!
+      end
+
+      def prevent_destroy
+        unless can_destroy?
+          raise FlowCore::ForbiddenOperation, "Found exists instance, destroy transition will lead serious corruption"
+        end
+      end
+  end
+end

data/app/models/flow_core/arc_guard.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FlowCore
+  class ArcGuard < FlowCore::ApplicationRecord
+    self.table_name = "flow_core_arc_guards"
+
+    belongs_to :workflow, class_name: "FlowCore::Workflow"
+    belongs_to :arc, class_name: "FlowCore::Arc"
+
+    has_one :transition, through: :arc, class_name: "FlowCore::Transition"
+
+    before_validation do
+      self.workflow ||= arc&.workflow
+    end
+
+    include FlowCore::ArcGuardable
+  end
+end

data/app/models/flow_core/end_place.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowCore
+  class EndPlace < FlowCore::Place
+    validates :type,
+              uniqueness: {
+                scope: :workflow
+              }
+
+    validates :output_arcs,
+              length: { is: 0 }
+
+    def end?
+      true
+    end
+  end
+end

data/app/models/flow_core/instance.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module FlowCore
+  class Instance < FlowCore::ApplicationRecord
+    self.table_name = "flow_core_instances"
+
+    FORBIDDEN_ATTRIBUTES = %i[
+      workflow_id stage activated_at finished_at canceled_at terminated_at terminated_reason
+      errored_at rescued_at suspended_at resumed_at created_at updated_at
+    ].freeze
+
+    belongs_to :workflow, class_name: "FlowCore::Workflow"
+
+    has_many :tokens, class_name: "FlowCore::Token", dependent: :delete_all
+    has_many :tasks, class_name: "FlowCore::Task", dependent: :delete_all
+
+    serialize :payload
+
+    enum stage: {
+      created: 0,
+      activated: 1,
+      canceled: 2,
+      finished: 11,
+      terminated: 12
+    }
+
+    scope :errored, -> { where.not(errored_at: nil) }
+    scope :suspended, -> { where.not(suspended_at: nil) }
+
+    after_initialize do
+      self.payload ||= {}
+    end
+
+    def errored?
+      errored_at.present?
+    end
+
+    def suspended?
+      suspended_at.present?
+    end
+
+    def can_active?
+      created?
+    end
+
+    def can_finish?
+      activated?
+    end
+
+    def active
+      return false unless can_active?
+
+      transaction do
+        tokens.create! place: workflow.start_place
+        update! stage: :activated, activated_at: Time.zone.now
+      end
+
+      true
+    end
+
+    def finish
+      return false unless can_finish?
+
+      transaction do
+        update! stage: :finished, finished_at: Time.zone.now
+
+        tasks.where(stage: %i[created enabled]).find_each do |task|
+          task.terminate! reason: "Instance finished"
+        end
+        tokens.where(stage: %i[free locked]).find_each(&:terminate!)
+      end
+
+      true
+    end
+
+    def active!
+      active || raise(FlowCore::InvalidTransition, "Can't active Instance##{id}")
+    end
+
+    def finish!
+      finish || raise(FlowCore::InvalidTransition, "Can't finish Instance##{id}")
+    end
+
+    def error!
+      return if errored?
+
+      update! errored_at: Time.zone.now
+    end
+
+    def rescue!
+      return unless errored?
+      return unless tasks.errored.any?
+
+      update! errored_at: nil, rescued_at: Time.zone.now
+    end
+
+    def suspend!
+      return if suspended?
+
+      transaction do
+        tasks.enabled.each(&:suspend!)
+        update! suspended_at: Time.zone.now
+      end
+    end
+
+    def resume!
+      return unless suspended?
+
+      transaction do
+        tasks.enabled.each(&:resume!)
+        update! suspended_at: nil, resumed_at: Time.zone.now
+      end
+    end
+  end
+end