flow_core 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a450593fd3daee1db9bcb92693d4329b0f6153f4d4c09997a409742925e38df
-  data.tar.gz: 326838fdb6df30560b532e93cf65d67f7059599106aa47a9db46cb6859d6c7de
+  metadata.gz: d31b83d470547f95bbe973b6376c596a2d2ebe7c5d15efe569452a4342cfe5b8
+  data.tar.gz: 1b7ae085f8487d2d6765cb946435b5f83c1d32bbea26e625303ee8941ec2efa1
 SHA512:
-  metadata.gz: 454c961586288c08a59192a3c26bc393e58b11a20f5e91daf198e83222210b661dc4fb4c2ff6aa3679914778b45cf9ddfa292cfefed90e29b3037c1abf6e32db
-  data.tar.gz: 59a6189a9b1d787473d68f4e2bbcd38c7e40ec52ea336a8b6efc82899b7e9f6c271f0aeea076b22ff14d1d06114352d4d48e9d2193c6e805e29552bfadcfd6b3
+  metadata.gz: 1765159897d571c89c05b3cca8f3d30229a13e6511a3797f8bfda0620540ac97940132bcc019a80fd371b1db8680bba91cca27927c841a54e0c4f48f88ad80ca
+  data.tar.gz: c6d354ddecbdda0596132ad83d56fce39bcbb9ab05a7a642e4c20bfa557ef792a0932156d6be195d8a66ff7e6143fc076a46a166e62be6cc77e33152a888d1de

data/README.md

@@ -131,6 +131,8 @@ Some notable:
     - Require app task finished first (if bind)
 - `terminated` Task killed by instance (e.g Instance cancelled) or other race condition task
 
+![Life cycle of workflow instance](doc/assets/life_cycle_of_workflow_instance.png)
+
 ### FlowKit
 
 Because FlowCore only care about essentials of workflow engine,
@@ -156,7 +158,8 @@ and you shall have fully control and without any unnecessary abstraction.
 
 - 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.
+- Activity-based to Petri-net mapping that will possible to integrate to existing visual editors (with some modification),
+  see <https://www.researchgate.net/figure/The-mapping-between-BPMN-and-Petri-nets_tbl2_221250389> for understanding.
 - More efficient and powerful workflow definition checking
 - Grammar and naming correction (I'm not English native-speaker)
 

data/app/models/flow_core/instance.rb

@@ -5,8 +5,8 @@ module FlowCore
     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
+      workflow_id stage activated_at finished_at canceled_at terminated_at terminate_reason
+      created_at updated_at
     ].freeze
 
     belongs_to :workflow, class_name: "FlowCore::Workflow"
@@ -32,14 +32,14 @@ module FlowCore
     end
 
     def errored?
-      errored_at.present?
+      tasks.where.not(errored_at: nil).exists?
     end
 
-    def suspended?
-      suspended_at.present?
+    def can_cancel?
+      created?
     end
 
-    def can_active?
+    def can_activate?
       created?
     end
 
@@ -47,69 +47,75 @@ module FlowCore
       activated?
     end
 
-    def active
-      return false unless can_active?
+    def can_terminate?
+      true
+    end
+
+    def cancel
+      return false unless can_cancel?
+
+      with_transaction_returning_status do
+        update! stage: :canceled, canceled_at: Time.zone.now
+        workflow.on_instance_cancel(self)
+
+        true
+      end
+    end
+
+    def activate
+      return false unless can_activate?
 
-      transaction do
+      with_transaction_returning_status do
         tokens.create! place: workflow.start_place
         update! stage: :activated, activated_at: Time.zone.now
-      end
+        workflow.on_instance_activate(self)
 
-      true
+        true
+      end
     end
 
     def finish
       return false unless can_finish?
 
-      transaction do
+      with_transaction_returning_status 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
+        workflow.on_instance_finish(self)
 
-    def active!
-      active || raise(FlowCore::InvalidTransition, "Can't active Instance##{id}")
+        true
+      end
     end
 
-    def finish!
-      finish || raise(FlowCore::InvalidTransition, "Can't finish Instance##{id}")
-    end
+    def terminate(reason:)
+      return unless can_terminate?
 
-    def error!
-      return if errored?
+      with_transaction_returning_status do
+        tasks.enabled.each { |task| task.terminate! reason: "Instance terminated" }
+        update! stage: :terminated, terminated_at: Time.zone.now, terminate_reason: reason
+        workflow.on_instance_terminate(self)
 
-      update! errored_at: Time.zone.now
+        true
+      end
     end
 
-    def rescue!
-      return unless errored?
-      return unless tasks.errored.any?
-
-      update! errored_at: nil, rescued_at: Time.zone.now
+    def cancel!
+      cancel || raise(FlowCore::InvalidTransition, "Can't cancel Instance##{id}")
     end
 
-    def suspend!
-      return if suspended?
-
-      transaction do
-        tasks.enabled.each(&:suspend!)
-        update! suspended_at: Time.zone.now
-      end
+    def activate!
+      activate || raise(FlowCore::InvalidTransition, "Can't activate Instance##{id}")
     end
 
-    def resume!
-      return unless suspended?
+    def finish!
+      finish || raise(FlowCore::InvalidTransition, "Can't finish Instance##{id}")
+    end
 
-      transaction do
-        tasks.enabled.each(&:resume!)
-        update! suspended_at: nil, resumed_at: Time.zone.now
-      end
+    def terminate!(reason:)
+      terminate(reason: reason) || raise(FlowCore::InvalidTransition, "Can't terminate Instance##{id}")
     end
   end
 end

data/app/models/flow_core/task.rb

@@ -7,7 +7,7 @@ module FlowCore
     belongs_to :workflow, class_name: "FlowCore::Workflow"
     belongs_to :transition, class_name: "FlowCore::Transition"
 
-    belongs_to :instance, class_name: "FlowCore::Instance"
+    belongs_to :instance, class_name: "FlowCore::Instance", autosave: true
     belongs_to :created_by_token, class_name: "FlowCore::Token", optional: true
 
     belongs_to :executable, polymorphic: true, optional: true
@@ -80,20 +80,21 @@ module FlowCore
     def enable
       return false unless can_enable?
 
-      transaction do
+      with_transaction_returning_status do
         input_free_tokens.each(&:lock!)
         update! stage: :enabled, enabled_at: Time.zone.now
 
-        transition.on_task_enabled(self)
-      end
+        transition.on_task_enable(self)
+        workflow.on_instance_task_enable(self)
 
-      true
+        true
+      end
     end
 
     def finish
       return false unless can_finish?
 
-      transaction do
+      with_transaction_returning_status do
         # terminate other racing tasks
         instance.tasks.enabled.where(created_by_token: created_by_token).find_each do |task|
           task.terminate! reason: "Same origin task #{id} finished"
@@ -102,80 +103,106 @@ module FlowCore
         input_locked_tokens.each { |token| token.consume! by: self }
         update! stage: :finished, finished_at: Time.zone.now
 
-        transition.on_task_finished(self)
-      end
+        transition.on_task_finish(self)
+        workflow.on_instance_task_finish(self)
 
-      create_output_token!
+        true
+      end
 
-      true
+      create_output_token
     end
 
     def terminate(reason:)
       return false unless can_terminate?
 
-      transaction do
+      with_transaction_returning_status do
         update! stage: :terminated, terminated_at: Time.zone.now, terminate_reason: reason
-        transition.on_task_terminated(self)
-      end
-
-      true
-    end
+        transition.on_task_terminate(self)
+        workflow.on_instance_task_terminate(self)
 
-    def enable!
-      enable || raise(FlowCore::InvalidTransition, "Can't enable Task##{id}")
-    end
-
-    def finish!
-      finish || raise(FlowCore::InvalidTransition, "Can't finish Task##{id}")
-    end
-
-    def terminate!(reason:)
-      terminate(reason: reason) || raise(FlowCore::InvalidTransition, "Can't terminate Task##{id}")
+        true
+      end
     end
 
-    def error!(error)
-      transaction do
-        update! errored_at: Time.zone.now, error_reason: error.message
-        transition.on_task_errored(self, error)
+    def error(error)
+      update! errored_at: Time.zone.now, error_reason: error.message
+      instance.update! errored_at: Time.zone.now
+      transition.on_task_errored(self, error)
+      workflow.on_instance_task_errored(self, error)
 
-        instance.error!
-      end
+      true
     end
 
-    def rescue!
+    def rescue
       return unless errored?
 
-      transaction do
+      with_transaction_returning_status do
         update! errored_at: nil, rescued_at: Time.zone.now
-        transition.on_task_rescued(self)
+        instance.update! errored_at: nil, rescued_at: Time.zone.now
+        transition.on_task_rescue(self)
+        workflow.on_instance_task_rescue(self)
 
-        instance.rescue!
+        true
       end
     end
 
-    def suspend!
-      transaction do
+    def suspend
+      with_transaction_returning_status do
         update! suspended_at: Time.zone.now
-        transition.on_task_suspended(self)
+        transition.on_task_suspend(self)
+        workflow.on_instance_task_suspend(self)
+
+        true
       end
     end
 
-    def resume!
-      transaction do
+    def resume
+      with_transaction_returning_status do
         update! suspended_at: nil, resumed_at: Time.zone.now
-        transition.on_task_resumed(self)
+        transition.on_task_resume(self)
+        workflow.on_instance_task_resume(self)
+
+        true
       end
     end
 
-    def create_output_token!
+    def create_output_token
       return if output_token_created
 
-      transaction do
+      with_transaction_returning_status do
         transition.create_tokens_for_output(task: self)
         update! output_token_created: true
+
+        true
       end
     end
 
+    def enable!
+      enable || raise(FlowCore::InvalidTransition, "Can't enable Task##{id}")
+    end
+
+    def finish!
+      finish || raise(FlowCore::InvalidTransition, "Can't finish Task##{id}")
+    end
+
+    def terminate!(reason:)
+      terminate(reason: reason) || raise(FlowCore::InvalidTransition, "Can't terminate Task##{id}")
+    end
+
+    alias error! error
+
+    def rescue!
+      self.rescue || raise(FlowCore::InvalidTransition, "Can't rescue Task##{id}")
+    end
+
+    def suspend!
+      suspend || raise(FlowCore::InvalidTransition, "Can't suspend Task##{id}")
+    end
+
+    def resume!
+      resume || raise(FlowCore::InvalidTransition, "Can't resume Task##{id}")
+    end
+
     private
 
       def input_tokens

data/app/models/flow_core/transition.rb

@@ -76,7 +76,9 @@ module FlowCore
       end
 
       if candidate_arcs.empty?
-        trigger&.on_error(task, FlowCore::NoNewTokenCreated.new)
+        # TODO: find a better way
+        on_task_errored task, FlowCore::NoNewTokenCreated.new
+        return
       end
 
       candidate_arcs.each do |arc|
@@ -84,43 +86,38 @@ module FlowCore
       end
     end
 
-    def on_task_created(task)
-      trigger&.on_task_created(task)
+    def on_task_enable(task)
+      trigger&.on_task_enable(task)
       callbacks.each { |callback| callback.call task }
     end
 
-    def on_task_enabled(task)
-      trigger&.on_task_enabled(task)
+    def on_task_finish(task)
+      trigger&.on_task_finish(task)
       callbacks.each { |callback| callback.call task }
     end
 
-    def on_task_finished(task)
-      trigger&.on_task_finished(task)
-      callbacks.each { |callback| callback.call task }
-    end
-
-    def on_task_terminated(task)
-      trigger&.on_task_terminated(task)
+    def on_task_terminate(task)
+      trigger&.on_task_terminate(task)
       callbacks.each { |callback| callback.call task }
     end
 
     def on_task_errored(task, error)
       trigger&.on_task_errored(task, error)
-      callbacks.each { |callback| callback.call task }
+      callbacks.each { |callback| callback.call task, error }
     end
 
-    def on_task_rescued(task)
-      trigger&.on_task_rescued(task)
+    def on_task_rescue(task)
+      trigger&.on_task_rescue(task)
       callbacks.each { |callback| callback.call task }
     end
 
-    def on_task_suspended(task)
-      trigger&.on_task_suspended(task)
+    def on_task_suspend(task)
+      trigger&.on_task_suspend(task)
       callbacks.each { |callback| callback.call task }
     end
 
-    def on_task_resumed(task)
-      trigger&.on_task_resumed(task)
+    def on_task_resume(task)
+      trigger&.on_task_resume(task)
       callbacks.each { |callback| callback.call task }
     end
 

data/app/models/flow_core/workflow.rb

@@ -15,12 +15,34 @@ module FlowCore
     has_one :start_place, class_name: "FlowCore::StartPlace", dependent: :delete
     has_one :end_place, class_name: "FlowCore::EndPlace", dependent: :delete
 
-    def create_instance!(attributes = {})
-      unless verified?
+    class_attribute :force_workflow_verified_on_create_instance, default: false
+
+    include FlowCore::WorkflowCallbacks
+
+    def build_instance(attributes = {})
+      if force_workflow_verified_on_create_instance && invalid?
         raise FlowCore::UnverifiedWorkflow, "Workflow##{id} didn't do soundness check yet."
       end
 
-      instances.create! attributes.with_indifferent_access.except(FlowCore::Instance::FORBIDDEN_ATTRIBUTES)
+      instances.build attributes.with_indifferent_access.except(FlowCore::Instance::FORBIDDEN_ATTRIBUTES)
+    end
+
+    def create_instance(attributes = {})
+      instance = build_instance(attributes)
+      return unless instance
+
+      instance.save
+      instance
+    end
+
+    def create_instance!(attributes = {})
+      instance = build_instance(attributes)
+      unless instance
+        raise RecordNotSaved.new("Failed to create workflow instance", instance)
+      end
+
+      instance.save!
+      instance
     end
 
     def invalid?

data/db/migrate/20200130200532_create_flow_core_tables.rb

@@ -85,13 +85,7 @@ class CreateFlowCoreTables < ActiveRecord::Migration[6.0]
       t.datetime :canceled_at
       t.datetime :terminated_at
 
-      t.string :terminated_reason
-
-      t.datetime :errored_at
-      t.datetime :rescued_at
-
-      t.datetime :suspended_at
-      t.datetime :resumed_at
+      t.string :terminate_reason
 
       t.text :payload
 
@@ -128,8 +122,8 @@ class CreateFlowCoreTables < ActiveRecord::Migration[6.0]
       t.integer :stage, default: 0, comment: "0-created, 1-enabled, 11-finished, 12-terminated"
       t.datetime :enabled_at
       t.datetime :finished_at
-      t.datetime :terminated_at
 
+      t.datetime :terminated_at
       t.string :terminate_reason
 
       t.datetime :errored_at

data/lib/flow_core.rb

@@ -13,6 +13,7 @@ require "flow_core/arc_guardable"
 require "flow_core/transition_triggerable"
 require "flow_core/transition_callbackable"
 require "flow_core/task_executable"
+require "flow_core/workflow_callbacks"
 
 require "flow_core/definition"
 require "flow_core/violations"

data/lib/flow_core/task_executable.rb

@@ -5,8 +5,7 @@ module FlowCore
     extend ActiveSupport::Concern
 
     included do
-      has_one :task, as: :executable, required: true, class_name: "FlowCore::Task"
-      has_one :instance, through: :task, class_name: "FlowCore::Instance"
+      has_one :task, as: :executable, class_name: "FlowCore::Task", autosave: true, required: true
       has_one :transition, -> { readonly }, through: :task, class_name: "FlowCore::Transition"
 
       after_save :notify_workflow_task_finished!, if: :implicit_notify_workflow_task_finished

data/lib/flow_core/transition_callbackable.rb

@@ -19,15 +19,15 @@ module FlowCore
       true
     end
 
-    def _call(_task)
+    def _call(_task, *_args)
       raise NotImplementedError
     end
 
-    def call(task)
+    def call(task, *args)
       return unless on.include? task.stage.to_sym
       return unless callable? task
 
-      _call task
+      _call task, *args
     end
   end
 end

data/lib/flow_core/transition_triggerable.rb

@@ -6,22 +6,20 @@ module FlowCore
 
     def on_verify(_transition, _violations); end
 
-    def on_task_created(_task); end
+    def on_task_enable(_task); end
 
-    def on_task_enabled(_task); end
+    def on_task_finish(_task); end
 
-    def on_task_finished(_task); end
+    def on_task_terminate(_task); end
 
-    def on_task_terminated(_task); end
+    def on_task_suspend(_task); end
 
-    def on_task_suspended(_task); end
-
-    def on_task_resumed(_task); end
+    def on_task_resume(_task); end
 
     def on_task_errored(_task, error)
       raise error
     end
 
-    def on_task_rescued(_task); end
+    def on_task_rescue(_task); end
   end
 end

data/lib/flow_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FlowCore
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/flow_core/workflow_callbacks.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FlowCore
+  module WorkflowCallbacks
+    extend ActiveSupport::Concern
+
+    def on_instance_cancel(_instance); end
+
+    def on_instance_activate(_instance); end
+
+    def on_instance_finish(_instance); end
+
+    def on_instance_terminate(_instance); end
+
+    def on_instance_task_enable(_task); end
+
+    def on_instance_task_finish(_task); end
+
+    def on_instance_task_terminate(_task); end
+
+    def on_instance_task_errored(_task, _error); end
+
+    def on_instance_task_rescue(_task); end
+
+    def on_instance_task_suspend(_task); end
+
+    def on_instance_task_resume(_task); end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_core
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - jasl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-18 00:00:00.000000000 Z
+date: 2020-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -95,6 +95,7 @@ files:
 - lib/flow_core/transition_triggerable.rb
 - lib/flow_core/version.rb
 - lib/flow_core/violations.rb
+- lib/flow_core/workflow_callbacks.rb
 - lib/tasks/flow_core_tasks.rake
 homepage: https://github.com/rails-engine/flow_core
 licenses:
@@ -115,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: A multi purpose, extendable, Workflow-net-based workflow engine for Rails