saga_orchestrator 0.15

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f2d80f2049b75b37a4a7bba59a62f4044e520c8e8ef6e883d37c6f25b83370b
+  data.tar.gz: 70ca29bd90e75a3528b30e3a7cfbc74960aabc2fff1ec27514e8dd81f5a51019
+SHA512:
+  metadata.gz: e80266e57ca6d8800e2b75c9035259f8f7c246e389646cab07ae925f3e509b97b3c035ec34201bbda37052caa7d5dbc89b5ecb0a692d6064fb04d032fcbcd42a
+  data.tar.gz: 81b6e4d48f690b5eb8d21e9070dc02c9afafe71f757e926f2c25ab3cc0bebb2fe1992cd56517bea03c893eef99442ace1a967c9acbe46397b8d6fc31f75ada9c

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Jayanth Ravindran
+
+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,195 @@
+# Saga Orchestration - define and run your desired workflows
+
+Saga Orchestration gem is inspired by Microservice Patterns by Chris Richardson. 
+
+It provides a framework to employ the Saga Orchestration patterns described in detail in his books and articles. Secondly, it makes it easier for firms to visualize the entire flow as a set of steps.
+
+## Description
+
+The key goals this gem seeks to address are -
+1. Enable transactions spanning singular or multiple servies to be addressed as a single, atomic operation?
+2. Depict flowchart of states be depicted using a simple DSL
+3. Branch to states based on conditions akin to flow charts
+4. Rollback compensatory transactions in case of errors and failures. These can be mandated and hooks provided for the same
+5. Visualize the sequence of steps executed as set of states ordered by sequence of operation and results at each stage
+
+## Getting Started
+
+### Dependencies
+
+* Ruby 2.7 or higher
+
+### Installing
+
+```
+gem install saga_orchestrator
+```
+
+### Executing program
+
+#### Basic Terminology
+
+Saga::StateEngine: Parent Class that can be inherited from to define the states within the work flow and sequence the same. 
+
+Saga::Orchestrator - Class responsible for running the StateEngine instance and produce end result of all states.   
+
+States - In system parlance terms, this could be a specific event like Payment Processing, New user assignment, create transaction etc. Each state can be hooked to a function with guidance on nature of function input.
+
+Sequence - The order in which states should be executed
+
+### How to build a workflow
+
+To build workflows, the first step is to design the workflow. Let us take an example of a workflow as in the image below.
+
+![workflow](images/flow_chart.png)
+
+1. Create a child class inheriting from Saga::StateEngine
+2. Add a function register_states within the child class to setup all the states as below.
+
+'''
+def state_registration
+
+      register_states do |add_state|
+
+        add_state.standard :state_01 do |state|
+          state.call Functions::Test.method(:test_func)
+          state.params do |p|
+            p.set_type :input_params
+          end
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.standard :state_02 do |state|
+          state.call Functions::Test.method(:test_func2)
+          state.params do |p|
+            p.set_type :last_result
+          end
+          state.process_input Processors::Test.method(:input_processor)
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.compensatory :state_03 do |state|
+          state.call Functions::Test.method(:test_func3)
+          state.params do |p|
+            p.set_type :last_result
+          end
+          state.rollback_method do |rollback|
+            rollback.call Rollback::Test.method(:rollback2)
+            rollback.params do |p|
+              p.set_type :last_result
+            end
+          end
+          state.process_input Processors::Test.method(:input_processor)
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.standard :state_04 do |state|
+          state.call Functions::Test.method(:test_func4)
+          state.params do |p|
+            p.set_type :last_result
+          end
+          state.process_input Processors::Test.method(:input_processor)
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.standard :cond01 do |state|
+          state.call Functions::Test.method(:conditional_test)
+          state.params do |p|
+            p.set_type :last_result
+          end
+        end
+
+      end
+
+    end
+'''
+
+### How to define a state
+
+States can be of two types:
+1. Standard - Can be hooked to a function and operates in the mode of retriable or pivot transactions
+2. Compensatory - Similar to standard function. But requires an additional input of a rollback function. In the event of an error, the rollback function is called
+
+Key parameters to define a function:
+1. .call: <mandatory> -> provide the hook to any function in your project using method() as in the example above
+2. .params: <mandatory> -> defines the parameter to be provided as input. Define a p.type within the block against state.params. Inputs may be of four types:
+> 1. input_params: The parameters provided at the time the state engine is invoked. This is explained in the sections ahead
+> 2. last_result: The result from the last state
+> 3. direct: Direct inputs where an absolute set of values may be provided. 
+    p.type :direct
+    p.input ##input value## // can be anything example [1,2,3] or {x: 3,y: 6} etc
+> 4. none: No input
+3. .process_input: In case one wishes to process the input prior to passing to function, this may be added and a function hooked
+4. .process_output: In case one wishes to process the output post passing to function, this may be added and a function hooked
+5. .rollback_method: only available and mandatory for compensatory states. You may hook a function to perform rollback and define the parameters to pass to the function. This usually becomes the end of the workflow as a rollback is considered a fail and closure.
+
+#### How to sequence states
+One simple way to sequence states is to do nothing. If you have defined the states in the order in which they should execute and there are no conditionals, this would work well.
+
+But if you have defined the states in any order and wish to put conditionals in the flow sequence, you can follow the steps below.
+The following is an example of a function that is added to the child class to provide your own sequence
+
+'''
+def sequence_states
+      describe_flows do |seqs|
+
+        #this creates the first sequence with name :seq_a
+        seqs.start :seq_a do |seq|
+          seq.init state_name :state_01 #always add an init to start the sequence. Use state_name to invoke a particular registered state
+          seq.then state_name :state_02 #to define the next state.
+          seq.then_conditional state_name :cond01 do |t| #the state defined here has to provide a true or false result
+            t.on_true state_name :state_03
+            t.on_false state_name :state_04
+          end
+          seq.end #closes the sequence
+        end
+      end
+    end
+'''
+
+In addition to the above, you can also define a sub sequence using seqs.sub instead of seqs.start. There should be only one seqs.start as this is taken as the the point to start execution of the state engine. 
+To invoke a sub sequence, replace the state_name with > sequence_name :seq_name
+
+### How to run the state engine
+If lets say, our child class is defined as Workflows::Test, you can initiate the state engine as follows:
+'''
+
+    obj = Saga::Orchestrator::new(Workflows::Test, 30, 40) #class followed by any number of input parameters. This will be referred as :input_params as explained above under definition
+
+    obj.run() #to run the state engine. This will return result with two keys: status and result
+
+    obj.execution_sequence # you can use this to get a hash contains each node that was run and results at each node level
+
+'''
+
+state can be:
+1. :success - completely ran all the way to end
+2. :error - in case of error in between that halted execution
+3. :rollback - in case of rollback 
+
+And that is it. You are good to go.
+
+
+## Tests
+
+I will be adding some tests soon to the same.
+
+## Authors
+
+Contributors names and contact info
+
+Jayanth Ravindran
+email: jayanth.ravindran@gmail.com
+
+## Version History
+
+* 0.1
+    * Initial Release
+
+## License
+
+This project is licensed under the MIT License - see the MIT-LICENSE file for details
+
+## Acknowledgments
+
+Inspired from Chris Richardson's articles on managing transactions across services

data/examples/main.rb

@@ -0,0 +1,6 @@
+require 'saga_orchestrator'
+require_relative 'workflow_models/definitions/test'
+
+obj = Saga::Orchestrator::new(Workflows::Test, 30)
+puts obj.run()
+puts obj.execution_sequence

data/examples/workflow_models/definitions/test.rb

@@ -0,0 +1,72 @@
+require 'saga_orchestrator'
+require_relative '../processors/test'
+require_relative '../functions/test'
+require_relative '../rollback/test'
+
+module Workflows
+  class Test < Saga::StateEngine
+
+    def state_registration
+
+      register_states do |add_state|
+
+        add_state.standard :sample do |state|
+          state.call Functions::Test.method(:test_func)
+          state.params do |p|
+            p.set_type :input_params
+          end
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.standard :sample2 do |state|
+          state.call Functions::Test.method(:test_func2)
+          state.params do |p|
+            p.set_type :last_result
+          end
+          state.process_input Processors::Test.method(:input_processor)
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.compensatory :sample3 do |state|
+          state.call Functions::Test.method(:test_func3)
+          state.params do |p|
+            p.set_type :last_result
+          end
+          state.rollback_method do |rollback|
+            rollback.call Rollback::Test.method(:rollback2)
+            rollback.params do |p|
+              p.set_type :last_result
+            end
+          end
+          state.process_input Processors::Test.method(:input_processor)
+          state.process_output Processors::Test.method(:processor)
+        end
+
+        add_state.standard :cond01 do |state|
+          state.call Functions::Test.method(:conditional_test)
+          state.params do |p|
+            p.set_type :last_result
+          end
+        end
+
+      end
+
+    end
+
+    def sequence_states
+      describe_flows do |seqs|
+        seqs.start :seq_a do |seq|
+          seq.init state_name :sample
+          seq.then state_name :sample2
+          seq.then_conditional state_name :cond01 do |t|
+            t.on_true state_name :sample
+            t.on_false state_name :sample2
+          end
+          seq.then state_name :sample3
+          seq.end
+        end
+      end
+    end
+
+  end
+end

data/examples/workflow_models/functions/test.rb

@@ -0,0 +1,28 @@
+module Functions
+  class Test
+    def self.test_func input
+      puts "in test_func: input - #{input}"
+      res = input + 2
+      puts "result = #{res}"
+      res
+    end
+
+    def self.test_func2 input
+      puts "in test_func2: input - #{input}"
+      res = input - 10
+      puts "result = #{res}"
+      res
+    end
+
+    def self.test_func3 input
+      raise StandardError, "An error occurred"
+    end
+
+    def self.conditional_test input
+      res = input > 0
+      puts "result = #{res}"
+      res
+    end
+
+  end
+end

data/examples/workflow_models/processors/test.rb

@@ -0,0 +1,11 @@
+module Processors
+  class Test
+    def self.processor input
+      input * 2
+    end
+
+    def self.input_processor input
+      input / 4
+    end
+  end
+end

data/examples/workflow_models/rollback/test.rb

@@ -0,0 +1,12 @@
+module Rollback
+  class Test
+    def self.rollback input
+      input * 100000
+    end
+
+    def self.rollback2 input
+      raise StandardError, "Rollback error occurred"
+    end
+
+  end
+end

data/lib/helpers/enum_helper.rb

@@ -0,0 +1,17 @@
+module EnumHelper
+  def enum(name, values)
+    # Define instance variable
+    attr_reader name
+
+    define_method("#{name}=") do |arg1|
+      instance_variable_set("@#{name}",arg1)
+    end
+
+    # Define supporting methods
+    values.each_key do |key|
+      define_method("#{key}?") do
+        instance_variable_get("@#{name}") == key
+      end
+    end
+  end
+end

data/lib/saga_orchestrator.rb

@@ -0,0 +1,38 @@
+require_relative 'state_management/state_manager'
+require_relative 'state_management/state_engine'
+ module Saga
+  class Orchestrator
+
+    def initialize(cls_state_engine, *args)
+      @args = args
+      obj = cls_state_engine.new(*@args)
+      @state_manager = StateManager::new(obj)
+    end
+
+    def run()
+      @state_manager.run()
+
+      res = {}
+
+      if @state_manager.success?
+        res[:status] = :success
+        res[:result] = @state_manager.result
+      elsif @state_manager.rollback?
+        res[:status] = :rollback
+        res[:result] = @state_manager.result
+      else
+        res[:status] = :error
+        res[:result] = @state_manager.error
+      end
+
+      return res
+
+    end
+
+    def execution_sequence()
+      @state_manager.execution_sequence
+    end
+
+  end
+
+end

data/lib/state_management/custom_exceptions/exceptions.rb

@@ -0,0 +1,35 @@
+class NodeNotRunError < StandardError
+  attr_reader :details
+
+  def initialize(message, details = nil)
+    super(message)
+    @details = details
+  end
+end
+
+class NodeTargetFunctionMissingError < StandardError
+  attr_reader :details
+
+  def initialize(message, details = nil)
+    super(message)
+    @details = details
+  end
+end
+
+class NullStateError < StandardError
+  attr_reader :details
+
+  def initialize(message, details = nil)
+    super(message)
+    @details = details
+  end
+end
+
+class RollbackMethodMissing < StandardError
+  attr_reader :details
+
+  def initialize(message, details = nil)
+    super(message)
+    @details = details
+  end
+end

data/lib/state_management/run_states.rb

@@ -0,0 +1,84 @@
+module Saga
+
+  class RunState
+
+    def initialize state_name
+      @state_name = state_name
+      @status = nil
+      @time_of_run = Time.now.gmtime
+      @input = nil
+      @result = nil
+      @error = nil
+    end
+
+    def initialize state_name, result
+      @state_name = state_name
+      @status = nil
+      @time_of_run = Time.now.gmtime
+      @result = nil
+      @error = nil
+
+      update(result)
+    end
+
+    def update result
+      @status = result&.[](:status)
+
+      case @status
+      when :success
+        @result = result[:result]
+      when :error
+        @error = result[:message]
+      when :rollback
+        @result = result[:result]
+      end
+    end
+
+    def outcome
+      outcome = ''
+
+      case @status
+      when :success
+        outcome = @result
+      when :error
+        outcome = @error
+      when :rollback
+        outcome = @result
+      end
+
+      outcome
+    end
+
+    def unwrap
+      {
+        state_name: @state_name,
+        status: @status,
+        time_of_run: @time_of_run,
+        outcome: outcome()
+      }
+    end
+
+  end
+
+  class RunStates
+    def initialize
+      @run_states = []
+    end
+
+    def push state_name, result
+      @run_states.push(RunState::new(state_name,result))
+    end
+
+    def dump
+      results = {}
+      ctr = 0
+      @run_states.each do |rs|
+        results[ctr] = rs.unwrap()
+        ctr += 1
+      end
+
+      results
+    end
+  end
+
+end

data/lib/state_management/sequences.rb

@@ -0,0 +1,253 @@
+require_relative './custom_exceptions/exceptions'
+require_relative '../transactions/transaction'
+require_relative '../helpers/enum_helper'
+
+module Saga
+
+  class SequenceNode
+    extend EnumHelper
+
+    enum :type, { process: 0, conditional: 1, stop: 2 }
+    enum :action_type, {transaction:0, sequence:1}
+
+    def initialize
+      @name = nil
+      self.type = :process
+      self.action_type = :transaction
+      @do = nil
+      @parent_node = nil
+      @on_success_go = nil
+      @on_false_go = nil
+      @run_state = nil
+    end
+
+    def run params = nil, last_state_result=nil
+
+      if self.type == :stop
+        return {status: :close}
+      end
+
+      if @do.nil?
+        raise NodeTargetFunctionMissingError.new("Node has no target task.", { reason: "State node has no transaction task.", code: 1001 })
+      end
+
+      if @do.is_a?(Transactions::Transaction)
+        res = @do.execute(params, last_state_result)
+        @run_state = true
+        @run_state   = false if !res&.[](:result) && self.type == :conditional
+        return res
+      end
+
+      return nil
+    end
+
+    def next
+
+      if @run_state.nil?
+        raise NodeNotRunError.new("Node has not been run yet.", { reason: "Next can only be decided after node has been run.", code: 1001 })
+      end
+
+      if @run_state == true
+        return @on_success_go
+      else
+        return @on_false_go
+      end
+    end
+
+    def set_parent_node node
+      @parent_node = node
+    end
+
+    def set_do task
+
+      if task.nil?
+        raise NullStateError.new("State not defined.", { reason: "State has not been defined or registered.", code: 1001 })
+      end
+
+      if task.is_a?(Sequence)
+        @action_type = :sequence
+      end
+      @do = task
+      @name = task.state_name
+    end
+
+    def name
+      @name
+    end
+
+    def set_type sym_type
+      self.type = sym_type
+    end
+
+    def point_to node
+      if node.is_a?(Sequence)
+        @on_success_go = node.first
+      else
+        @on_success_go = node
+      end
+    end
+
+    def set_parent node
+      @parent_node = node
+    end
+
+    def has_on_fail_pointer?
+      !@on_false_go.nil?
+    end
+
+    def has_on_success_pointer?
+      !@on_success_go.nil?
+    end
+
+    def on_fail_point_to node
+      if node.is_a?(Sequence)
+        @on_false_go = node.first
+      else
+        @on_false_go = node
+      end
+    end
+
+    def activity
+      @do
+    end
+
+    def on_true activity
+
+      seq_node = SequenceNode::new()
+      seq_node.set_do activity
+
+      self.point_to seq_node
+
+      seq_node.set_parent_node self
+
+    end
+
+    def on_false activity
+
+      seq_node = SequenceNode::new()
+      seq_node.set_do activity
+
+      self.on_fail_point_to seq_node
+
+      seq_node.set_parent_node self
+
+    end
+
+    def on_conditional &block
+      block.call(self) if block_given?
+
+      return_nodes = []
+      return_nodes.push(@on_success_go) if !@on_success_go.nil?
+      return_nodes.push(@on_false_go) if !@on_false_go.nil?
+      return_nodes
+    end
+
+  end
+
+  class Sequence
+
+    def initialize name
+      @name = name
+      @prev_node = []
+      @initial_node = nil
+    end
+
+    def first
+      @initial_node
+    end
+
+    def init task
+      seq_node = SequenceNode::new()
+      seq_node.set_do task
+      @prev_node.push(seq_node)
+      @initial_node = seq_node
+    end
+
+    def end
+      seq_node = SequenceNode::new()
+      seq_node.set_type :stop
+
+      begin
+        @prev_node.each do |nd|
+          nd.point_to seq_node
+        end
+        seq_node.set_parent_node @prev_node
+        @prev_node.clear
+        @prev_node.push(seq_node)
+      rescue NoMethodError => e
+        puts "Within End Error : #{e.message}"
+      end
+
+    end
+
+    def then task
+      seq_node = SequenceNode::new()
+      seq_node.set_do task
+
+      begin
+        @prev_node.each do |nd|
+          nd.point_to seq_node
+        end
+        seq_node.set_parent_node @prev_node
+        @prev_node.clear
+        @prev_node.push(seq_node)
+      rescue NoMethodError => e
+        puts "Within Then Error : #{e.message}"
+      end
+    end
+
+    def then_conditional task, &block
+      seq_node = SequenceNode::new()
+      seq_node.set_do task
+      seq_node.set_type :conditional
+
+      begin
+        @prev_node.each do |nd|
+          nd.point_to seq_node
+        end
+        seq_node.set_parent_node @prev_node
+
+        @prev_node = seq_node.on_conditional(&block)
+
+      rescue NoMethodError => e
+        puts "Within Then Conditional Error : #{e.message}"
+      end
+    end
+
+  end
+
+  class Sequences
+
+    def initialize
+      @sequences = {}
+      @active_sequence = nil
+      @start = nil
+    end
+
+    def get_sequence_by_name name
+      @sequences[name]
+    end
+
+    def first_node
+      @start.first
+    end
+
+    def start name, &block
+      seq = Sequence::new(name)
+      @sequences[name] = seq
+      @active_sequence = seq
+      @start = seq
+      block.call(seq) if block_given?
+    end
+
+    #sub sequence of a sequence
+    def sub name, &block
+      seq = Sequence::new(name)
+      @sequences[name] = seq
+      @active_sequence = seq
+      block.call(seq) if block_given?
+    end
+
+  end
+
+end

data/lib/state_management/state_engine.rb

@@ -0,0 +1,122 @@
+require_relative './custom_exceptions/exceptions'
+require_relative './states'
+require_relative './sequences'
+require_relative './run_states'
+require_relative '../helpers/enum_helper'
+
+module Saga
+
+  class StateEngine
+    extend EnumHelper
+
+    enum :run_status, { success: 0, fail: 1, rollback: 2 }
+
+    def initialize(*args)
+      @params = args
+      @states = States::new()
+      @sequences = Sequences::new()
+      @last_result = nil
+      @complete = false
+      self.run_status = :success
+      @error = nil
+      @executing_node = nil
+      @run_states = RunStates::new()
+    end
+
+    def register_states(&block)
+      block.call(@states) if block_given?
+    end
+
+    def describe_flows(&block)
+      @sequences = Sequences::new()
+      block.call(@sequences) if block_given?
+    end
+
+    def state_name name
+      @states.get_state_by_name name
+    end
+
+    def sequence_name name
+      @sequences.get_sequence_by_name name
+    end
+
+    def sequence_states
+      keys = @states.keys
+      return if keys.size == 0
+
+      describe_flows do |seqs|
+        seqs.start :base do |seq|
+          keys.each_with_index do |state_name, index|
+            if index ==0
+              seq.init state_name state_name
+            else
+              seq.then state_name state_name
+            end
+          end
+          seq.end
+        end
+      end
+    end
+
+    def run
+
+      @executing_node = @sequences.first_node
+
+      if @executing_node.nil?
+        raise NullStateError.new("Current sequence has no start node.", { reason: "Sequence not initialised before run.", code: 1001 })
+      else
+        conduct_sequence @executing_node
+      end
+
+    end
+
+    def result
+      @last_result
+    end
+
+    def error
+      @error
+    end
+
+    def execution_sequence
+      @run_states.dump
+    end
+
+    def conduct_sequence active_node
+      current_node = active_node
+
+      begin
+        if current_node.is_a?(Sequence)
+          conduct_sequence current_node.activity.first
+        else
+          @executing_node = current_node
+          res = current_node.run @params, @last_result
+
+          @run_states.push(@executing_node.name, res)
+
+          execution_status = res&.[](:status)
+          if execution_status == :close
+            @complete = true
+            return
+          elsif execution_status == :rollback
+            self.run_status = :rollback
+            @complete = true
+          elsif execution_status == :error
+            @complete = true
+            self.run_status = :fail
+            @error = res&.[](:message)
+            return
+          end
+          @last_result = res&.[](:result) if !current_node.conditional? #conditional nodes gives true / false responses which will not be considered as results
+        end
+
+        current_node = current_node.next
+
+        if current_node.nil?
+          @complete = true
+        end
+
+      end while !current_node.nil? && !@complete
+    end
+  end
+end

data/lib/state_management/state_manager.rb

@@ -0,0 +1,37 @@
+module Saga
+
+  class StateManager
+
+    def initialize obj_state_engine
+      @state_engine = obj_state_engine
+    end
+
+    def run
+      @state_engine.state_registration
+      @state_engine.sequence_states
+      @state_engine.run
+    end
+
+    def success?
+      @state_engine.success?
+    end
+
+    def rollback?
+      @state_engine.rollback?
+    end
+
+    def result
+      @state_engine.result
+    end
+
+    def error
+      @state_engine.error
+    end
+
+    def execution_sequence
+      @state_engine.execution_sequence
+    end
+
+  end
+
+end

data/lib/state_management/states.rb

@@ -0,0 +1,42 @@
+require_relative '../transactions/retriable'
+require_relative '../transactions/compensatory'
+require_relative './custom_exceptions/exceptions'
+
+module Saga
+
+  class States
+
+    def initialize
+      @states = {}
+    end
+
+    def standard name, &block
+      transac = Transactions::RetriableTransaction::new(name)
+      block.call(transac) if block_given?
+      @states[name] = transac
+    end
+
+    def compensatory name, &block
+      transac = Transactions::CompensatoryTransaction::new(name)
+      block.call(transac) if block_given?
+      if !transac.valid?
+        raise RollbackMethodMissing.new("Rollback method missing for compensatory state", { reason: "Add rollback method for compensatory state", code: 1001 })
+      end
+      @states[name] = transac
+    end
+
+    def sequence_states(&block)
+      block.call(@sequences) if block_given?
+    end
+
+    def get_state_by_name name
+      @states[name]
+    end
+
+    def keys
+      @states.keys
+    end
+
+  end
+
+end

data/lib/transactions/compensatory.rb

@@ -0,0 +1,55 @@
+require_relative './rollback_method'
+require_relative './transaction'
+
+module Transactions
+
+  class CompensatoryTransaction < Transaction
+
+    def initialize name
+      super(name)
+      @rollback = nil
+    end
+
+    def valid?
+      !(
+        @rollback.nil?
+      )
+    end
+
+    def rollback_method &block
+      @rollback = Transactions::RollbackMethod::new()
+      block.call(@rollback) if block_given?
+    end
+
+    def on_error_action e
+      begin
+        case @parameters.type
+        when :direct
+          input = @parameters.input
+          res = @rollback.method.call(input)
+        when :last_result
+          input =  @last_result
+          res = @rollback.method.call(input)
+        else
+            res = @rollback.method.call(*@input_params)
+        end
+
+        @result = {
+          status: :rollback,
+          result: res
+        }
+
+        return @result
+      rescue Exception => e
+        error_message = "Error in rollback at state (#{@name}) : #{e.message}"
+        @error = {
+          status: :error,
+          message: error_message
+        }
+        return @error
+      end
+    end
+
+  end
+
+end

data/lib/transactions/parameters.rb

@@ -0,0 +1,27 @@
+require_relative '../helpers/enum_helper'
+
+
+module Transactions
+
+  class Parameters
+    extend EnumHelper
+
+    enum :type, { input_params: 0, last_result: 1, direct:2, none: 3}
+
+    def initialize
+      self.type = :input_params
+      @params = nil
+    end
+
+    def set_type val
+      self.type = val
+    end
+
+    def input val
+      @params = val
+    end
+
+
+  end
+
+end

data/lib/transactions/retriable.rb

@@ -0,0 +1,11 @@
+# require_relative './parameters'
+require_relative './transaction'
+
+module Transactions
+
+  class RetriableTransaction < Transaction
+
+
+  end
+
+end

data/lib/transactions/rollback_method.rb

@@ -0,0 +1,25 @@
+require_relative './parameters'
+module Transactions
+
+  class RollbackMethod
+
+    def initialize
+      @method_to_call = nil
+      @params = Parameters::new()
+    end
+
+    def call func_name
+      @method_to_call = func_name
+    end
+
+    def method
+      @method_to_call
+    end
+
+    def params &block
+      block.call(@params) if block_given?
+    end
+
+  end
+
+end

data/lib/transactions/transaction.rb

@@ -0,0 +1,99 @@
+require_relative './parameters'
+require_relative './transaction'
+
+module Transactions
+  class Transaction
+
+    def initialize name
+      @name = name
+      @method_to_call = nil
+      @parameters = nil
+      @input_processing_function = nil
+      @output_processing_function = nil
+      @input_params = nil
+      @last_result = nil
+      @result = nil
+      @error = nil
+    end
+
+    def call func_name
+      @method_to_call = func_name
+    end
+
+    def state_name
+      @name
+    end
+
+    def params &block
+      obj_param = Parameters::new()
+      block.call(obj_param) if block_given?
+      @parameters = obj_param
+    end
+
+    def process_input process_func
+      @input_processing_function = process_func
+    end
+
+    def process_output process_func
+      @output_processing_function = process_func
+    end
+
+    def param_type
+      @parameters.type
+    end
+
+    def on_error_action e
+
+      @error =  {
+        status: :error,
+        message: "Error in processing at state (#{@name}): #{e.message}"
+      }
+
+      @error
+
+    end
+
+    def execute input_params, last_state_result
+
+      res = nil
+      input = nil
+
+      @input_params = input_params
+      @last_result = last_state_result
+
+      begin
+        case @parameters.type
+        when :direct
+          input = @input_processing_function.nil? ? @parameters.input : @input_processing_function.call(@parameters.input)
+          res = @method_to_call.call(input)
+        when :last_result
+          input = @input_processing_function.nil? ? @last_result : @input_processing_function.call(@last_result)
+          res = @method_to_call.call(input)
+        when :none
+          res = @method_to_call.call()
+        else
+          if @input_processing_function.nil?
+            res = @method_to_call.call(*@input_params)
+          else
+            res = @method_to_call.call(@input_processing_function.call(*@input_params))
+          end
+        end
+
+        if !@output_processing_function.nil?
+          res = @output_processing_function.call(res)
+        end
+
+        @result = {
+          status: :success,
+          result: res
+        }
+
+        return @result
+      rescue Exception => e
+        return on_error_action(e)
+      end
+
+    end
+
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: saga_orchestrator
+version: !ruby/object:Gem::Version
+  version: '0.15'
+platform: ruby
+authors:
+- Jayanth Ravindran
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-05-01 00:00:00.000000000 Z
+dependencies: []
+description: Framework to help employ the Saga Orchestration patterns in ruby or rails
+  applications. Secondly, it makes it easier for firms to visualize the entire flow
+  as a set of steps.
+email: jayanth.ravindran@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- Readme.md
+- examples/main.rb
+- examples/workflow_models/definitions/test.rb
+- examples/workflow_models/functions/test.rb
+- examples/workflow_models/processors/test.rb
+- examples/workflow_models/rollback/test.rb
+- images/flow_chart.png
+- lib/helpers/enum_helper.rb
+- lib/saga_orchestrator.rb
+- lib/state_management/custom_exceptions/exceptions.rb
+- lib/state_management/run_states.rb
+- lib/state_management/sequences.rb
+- lib/state_management/state_engine.rb
+- lib/state_management/state_manager.rb
+- lib/state_management/states.rb
+- lib/transactions/compensatory.rb
+- lib/transactions/parameters.rb
+- lib/transactions/retriable.rb
+- lib/transactions/rollback_method.rb
+- lib/transactions/transaction.rb
+homepage: https://rubygems.org/gems/saga_orchestrator
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Describe orchestration workflow as definitions and run within a state engine
+test_files: []