floe 0.11.3 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb1a786256a191ba7d1b3b08f6e3cd02fa778fcf28ab44a7353f36ae7979039b
-  data.tar.gz: ca5ab5d0b5ed1949945593bb1f07141e554fbbac4d825cbf6333bb92e5b17b6d
+  metadata.gz: 2eb195983f47d7cac44f18e962bf314c3ff4fefbdf3ac5cae32e960bfc2c0fb0
+  data.tar.gz: 6a0f8d91337297786c03e99fc96cb118ed8cb76244e52cf8253702d1517a6f5d
 SHA512:
-  metadata.gz: e96574a58740f8659f27947144bdc5067fbade1645a0b651e66607494fce5b0a16ef762bbba1638d54a8804425c2de2c3938884b4c18346be3623b4ffbdc821b
-  data.tar.gz: da673ecc866d1df2f6f75872df183beda957996fd54ff09177ebd84b27bc64fade88122eaaf34f7134e3a92d74b9d9f7a7322648042df444ad889de9a053d298
+  metadata.gz: 99f5a3c8e67a9f5c97b43795739c201a49a8f1195d40a1da38f2aa0e16d200266783336e4be9ada5d41b566c545144a4533db258546ebbf04a23c454a489e6a1
+  data.tar.gz: a77bfe436b37adf9dbdc2a279b9b1f70f48980062aaaec191a8e1fd57238e8b8b50b02828025e561c7ccb8429cb67fefb3f7ed044ed309d82eaae8dd8d9d407b

data/.yamllint

@@ -1,8 +1,6 @@
----
 extends: relaxed
-
 rules:
   indentation:
     indent-sequences: false
   line-length:
-    max: 120
+    max: 1000

data/CHANGELOG.md

@@ -4,6 +4,32 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2024-07-31
+### Added
+- Set Floe.logger.level if DEBUG env var set ([#234](https://github.com/ManageIQ/floe/pull/234))
+- Add InstrinsicFunction foundation + States.Array, States.UUID ([#194](https://github.com/ManageIQ/floe/pull/194))
+- Evaluate IntrinsicFunctions from PayloadTemplate ([#236](https://github.com/ManageIQ/floe/pull/236))
+- Add more intrinsic functions ([#242](https://github.com/ManageIQ/floe/pull/242))
+- Add State#cause_path, error_path ([#249](https://github.com/ManageIQ/floe/pull/249))
+- Validate Catcher Next ([#250](https://github.com/ManageIQ/floe/pull/250))
+- Add spec/supports ([#248](https://github.com/ManageIQ/floe/pull/248))
+
+### Fixed
+- Handle non-hash input/output values ([#214](https://github.com/ManageIQ/floe/pull/214))
+- Fix Input/Output handling for Pass, Choice, Succeed states ([#225](https://github.com/ManageIQ/floe/pull/225))
+- Wrap Parslet::ParseFailed errors as Floe::InvalidWorkflowError ([#235](https://github.com/ManageIQ/floe/pull/235))
+- Fix edge cases with States.Array ([#237](https://github.com/ManageIQ/floe/pull/237))
+- Fix sporadic test failure with Wait state ([#243](https://github.com/ManageIQ/floe/pull/243))
+- Fix invalid container names after normalizing ([#252](https://github.com/ManageIQ/floe/pull/252))
+
+### Changed
+- Extract ErrorMatcherMixin from Catch and Retry ([#186](https://github.com/ManageIQ/floe/pull/186))
+- Output should be JSON ([#230](https://github.com/ManageIQ/floe/pull/230))
+- Normalize functions to all take arguments ([#238](https://github.com/ManageIQ/floe/pull/238))
+- Pass full path name to State.new for better errors ([#229](https://github.com/ManageIQ/floe/pull/229))
+- Validate that state machine input is valid JSON ([#227](https://github.com/ManageIQ/floe/pull/227))
+- Move the Parslet parse into initialize so that invalid function definition will fail on workflow load ([#245](https://github.com/ManageIQ/floe/pull/245))
+
 ## [0.11.3] - 2024-06-20
 ### Fixed
 - ResultPath=$ replaces complete output ([#199](https://github.com/ManageIQ/floe/pull/199))
@@ -199,7 +225,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - Initial release
 
-[Unreleased]: https://github.com/ManageIQ/floe/compare/v0.11.3...HEAD
+[Unreleased]: https://github.com/ManageIQ/floe/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/ManageIQ/floe/compare/v0.11.3...v0.12.0
 [0.11.3]: https://github.com/ManageIQ/floe/compare/v0.11.2...v0.11.3
 [0.11.2]: https://github.com/ManageIQ/floe/compare/v0.11.1...v0.11.2
 [0.11.1]: https://github.com/ManageIQ/floe/compare/v0.11.0...v0.11.1

data/floe.gemspec

@@ -36,11 +36,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency "jsonpath", "~>1.1"
   spec.add_dependency "kubeclient", "~>4.7"
   spec.add_dependency "optimist", "~>3.0"
+  spec.add_dependency "parslet", "~>2.0"
 
-  spec.add_development_dependency "manageiq-style"
+  spec.add_development_dependency "manageiq-style", ">= 1.5.2"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec"
-  spec.add_development_dependency "rubocop"
   spec.add_development_dependency "simplecov", ">= 0.21.2"
   spec.add_development_dependency "timecop"
 end

data/lib/floe/cli.rb

@@ -7,6 +7,7 @@ module Floe
       require "logger"
 
       Floe.logger = Logger.new($stdout)
+      Floe.logger.level = 0 if ENV["DEBUG"]
     end
 
     def run(args = ARGV)
@@ -30,10 +31,12 @@ module Floe
       # Display status
       workflows.each do |workflow|
         puts "", "#{workflow.name}#{" (#{workflow.status})" unless workflow.context.success?}", "===" if workflows.size > 1
-        puts workflow.output.inspect
+        puts workflow.output
       end
 
       workflows.all? { |workflow| workflow.context.success? }
+    rescue Floe::Error => err
+      abort(err.message)
     end
 
     private

data/lib/floe/container_runner/docker_mixin.rb

@@ -24,6 +24,9 @@ module Floe
         # This does not follow the leading and trailing character restriction because we will embed it
         # below with a prefix and suffix that already conform to the RFC.
         normalized_name = name.downcase.gsub(/[^a-z0-9-]/, "-")[0, MAX_CONTAINER_NAME_SIZE]
+        # Ensure that the normalized_name doesn't end in any invalid characters after we
+        # limited the length to the MAX_CONTAINER_NAME_SIZE.
+        normalized_name.gsub!(/[^a-z0-9]+$/, "")
 
         "floe-#{normalized_name}-#{SecureRandom.hex(4)}"
       end

data/lib/floe/validation_mixin.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Floe
+  module ValidationMixin
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def parser_error!(comment)
+      self.class.parser_error!(name, comment)
+    end
+
+    def missing_field_error!(field_name)
+      self.class.missing_field_error!(name, field_name)
+    end
+
+    def invalid_field_error!(field_name, field_value = nil, comment = nil)
+      self.class.invalid_field_error!(name, field_name, field_value, comment)
+    end
+
+    def workflow_state?(field_value, workflow)
+      workflow.payload["States"] ? workflow.payload["States"].include?(field_value) : true
+    end
+
+    def wrap_parser_error(field_name, field_value)
+      yield
+    rescue ArgumentError, InvalidWorkflowError => error
+      invalid_field_error!(field_name, field_value, error.message)
+    end
+
+    module ClassMethods
+      def parser_error!(name, comment)
+        name = name.join(".") if name.kind_of?(Array)
+        raise Floe::InvalidWorkflowError, "#{name} #{comment}"
+      end
+
+      def missing_field_error!(name, field_name)
+        parser_error!(name, "does not have required field \"#{field_name}\"")
+      end
+
+      def invalid_field_error!(name, field_name, field_value, comment)
+        # instead of displaying a large hash or array, just displaying the word Hash or Array
+        field_value = field_value.class if field_value.kind_of?(Hash) || field_value.kind_of?(Array)
+
+        parser_error!(name, "field \"#{field_name}\"#{" value \"#{field_value}\"" unless field_value.nil?} #{comment}")
+      end
+    end
+  end
+end

data/lib/floe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Floe
-  VERSION = "0.11.3"
+  VERSION = "0.12.0"
 end

data/lib/floe/workflow/catcher.rb

@@ -3,14 +3,28 @@
 module Floe
   class Workflow
     class Catcher
-      attr_reader :error_equals, :next, :result_path
+      include ErrorMatcherMixin
+      include ValidationMixin
 
-      def initialize(payload)
-        @payload = payload
+      attr_reader :error_equals, :next, :result_path, :name
+
+      def initialize(workflow, name, payload)
+        @name         = name
+        @payload      = payload
 
         @error_equals = payload["ErrorEquals"]
         @next         = payload["Next"]
         @result_path  = ReferencePath.new(payload.fetch("ResultPath", "$"))
+
+        missing_field_error!("ErrorEquals") if !@error_equals.kind_of?(Array) || @error_equals.empty?
+        validate_state_next!(workflow)
+      end
+
+      private
+
+      def validate_state_next!(workflow)
+        missing_field_error!("Next") if @next.nil?
+        invalid_field_error!("Next", @next, "is not found in \"States\"") if @next && !workflow_state?(@next, workflow)
       end
     end
   end

data/lib/floe/workflow/choice_rule.rb

@@ -4,26 +4,31 @@ module Floe
   class Workflow
     class ChoiceRule
       class << self
-        def build(payload)
+        def build(workflow, name, payload)
           if (sub_payloads = payload["Not"])
-            Floe::Workflow::ChoiceRule::Not.new(payload, build_children([sub_payloads]))
+            name += ["Not"]
+            Floe::Workflow::ChoiceRule::Not.new(workflow, name, payload, build_children(workflow, name, [sub_payloads]))
           elsif (sub_payloads = payload["And"])
-            Floe::Workflow::ChoiceRule::And.new(payload, build_children(sub_payloads))
+            name += ["And"]
+            Floe::Workflow::ChoiceRule::And.new(workflow, name, payload, build_children(workflow, name, sub_payloads))
           elsif (sub_payloads = payload["Or"])
-            Floe::Workflow::ChoiceRule::Or.new(payload, build_children(sub_payloads))
+            name += ["Or"]
+            Floe::Workflow::ChoiceRule::Or.new(workflow, name, payload, build_children(workflow, name, sub_payloads))
           else
-            Floe::Workflow::ChoiceRule::Data.new(payload)
+            name += ["Data"]
+            Floe::Workflow::ChoiceRule::Data.new(workflow, name, payload)
           end
         end
 
-        def build_children(sub_payloads)
-          sub_payloads.map { |payload| build(payload) }
+        def build_children(workflow, name, sub_payloads)
+          sub_payloads.map.with_index { |payload, i| build(workflow, name + [i.to_s], payload) }
         end
       end
 
-      attr_reader :next, :payload, :variable, :children
+      attr_reader :next, :payload, :variable, :children, :name
 
-      def initialize(payload, children = nil)
+      def initialize(_workflow, name, payload, children = nil)
+        @name      = name
         @payload   = payload
         @children  = children
 

data/lib/floe/workflow/context.rb

@@ -9,9 +9,7 @@ module Floe
       # @param input [Hash] (default: {})
       def initialize(context = nil, input: nil, credentials: {})
         context = JSON.parse(context) if context.kind_of?(String)
-
-        input ||= {}
-        input = JSON.parse(input) if input.kind_of?(String)
+        input   = JSON.parse(input || "{}")
 
         @context = context || {}
         self["Execution"]          ||= {}
@@ -23,7 +21,7 @@ module Floe
 
         @credentials = credentials || {}
       rescue JSON::ParserError => err
-        raise Floe::InvalidWorkflowError, err.message
+        raise Floe::InvalidExecutionInput, "Invalid State Machine Execution Input: #{err}: was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')"
       end
 
       def execution
@@ -39,7 +37,7 @@ module Floe
       end
 
       def failed?
-        output&.key?("Error") || false
+        (output.kind_of?(Hash) && output.key?("Error")) || false
       end
 
       def ended?
@@ -54,10 +52,18 @@ module Floe
         state["Input"]
       end
 
+      def json_input
+        input.to_json
+      end
+
       def output
         state["Output"]
       end
 
+      def json_output
+        output.to_json
+      end
+
       def output=(val)
         state["Output"] = val
       end

data/lib/floe/workflow/error_matcher_mixin.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Floe
+  class Workflow
+    # Methods for common error handling
+    module ErrorMatcherMixin
+      # @param [String] error the error thrown
+      def match_error?(error)
+        return false if error == "States.Runtime"
+        return true if error_equals.include?("States.ALL")
+        return true if error_equals.include?("States.Timeout") && error == "States.HeartbeatTimeout"
+
+        error_equals.include?(error)
+      end
+    end
+  end
+end

data/lib/floe/workflow/intrinsic_function/parser.rb

@@ -0,0 +1,100 @@
+require "parslet"
+
+module Floe
+  class Workflow
+    class IntrinsicFunction
+      class Parser < Parslet::Parser
+        rule(:spaces)  { str(' ').repeat(1) }
+        rule(:spaces?) { spaces.maybe }
+        rule(:digit)   { match('[0-9]') }
+        rule(:quote)   { str('\'') }
+
+        rule(:comma_sep) { str(',') >> spaces? }
+
+        rule(:true_literal)  { str('true').as(:true_literal) }
+        rule(:false_literal) { str('false').as(:false_literal) }
+        rule(:null_literal)  { str('null').as(:null_literal) }
+
+        rule(:number) do
+          (
+            str('-').maybe >> (
+              str('0') | (match('[1-9]') >> digit.repeat)
+            ) >> (
+              str('.') >> digit.repeat(1)
+            ).maybe >> (
+              match('[eE]') >> (str('+') | str('-')).maybe >> digit.repeat(1)
+            ).maybe
+          ).as(:number)
+        end
+
+        rule(:string) do
+          (
+            quote >> (
+              (str('\\') >> any) | (quote.absent? >> any)
+            ).repeat >> quote
+          ).as(:string)
+        end
+
+        rule(:jsonpath) do
+          (
+            str('$') >> match('[^,)]').repeat(0)
+          ).as(:jsonpath)
+        end
+
+        rule(:arg) do
+          (
+            string | number | jsonpath | true_literal | false_literal | null_literal | expression
+          ).as(:arg)
+        end
+
+        rule(:args) do
+          (
+            arg >> (comma_sep >> arg).repeat
+          ).maybe.as(:args)
+        end
+
+        [
+          :states_array,           "States.Array",
+          :states_array_partition, "States.ArrayPartition",
+          :states_array_contains,  "States.ArrayContains",
+          :states_array_range,     "States.ArrayRange",
+          :states_array_get_item,  "States.ArrayGetItem",
+          :states_array_length,    "States.ArrayLength",
+          :states_array_unique,    "States.ArrayUnique",
+          :states_base64_encode,   "States.Base64Encode",
+          :states_base64_decode,   "States.Base64Decode",
+          :states_hash,            "States.Hash",
+          :states_math_random,     "States.MathRandom",
+          :states_math_add,        "States.MathAdd",
+          :states_string_split,    "States.StringSplit",
+          :states_uuid,            "States.UUID",
+        ].each_slice(2) do |function_symbol, function_name|
+          rule(function_symbol) do
+            (
+              str(function_name) >> str('(') >> args >> str(')')
+            ).as(function_symbol)
+          end
+        end
+
+        rule(:expression) do
+          states_array |
+            states_array_partition |
+            states_array_contains |
+            states_array_range |
+            states_array_get_item |
+            states_array_length |
+            states_array_unique |
+            states_base64_encode |
+            states_base64_decode |
+            states_hash |
+            states_math_random |
+            states_math_add |
+            states_string_split |
+            states_uuid
+        end
+
+        root(:expression)
+      end
+    end
+  end
+end

data/lib/floe/workflow/intrinsic_function/transformer.rb

@@ -0,0 +1,196 @@
+# Disable rubocops against the `match` method, since this is a Parslet specific
+#   match method and not the typical `Object#match`.
+# rubocop:disable Performance/RegexpMatch, Performance/RedundantMatch
+
+require "parslet"
+
+module Floe
+  class Workflow
+    class IntrinsicFunction
+      class Transformer < Parslet::Transform
+        OptionalArg = Struct.new(:type)
+
+        class << self
+          def process_args(args, function, signature = nil)
+            args = resolve_args(args)
+            if signature
+              check_arity(args, function, signature)
+              check_types(args, function, signature)
+            end
+            args
+          end
+
+          private
+
+          def resolve_args(args)
+            if args.nil?
+              # 0 args
+              []
+            elsif args.kind_of?(Array)
+              # >1 arg
+              args.map { |a| a[:arg] }
+            else
+              # 1 arg
+              [args[:arg]]
+            end
+          end
+
+          def check_arity(args, function, signature)
+            if signature.any?(OptionalArg)
+              signature_without_optional = signature.reject { |a| a.kind_of?(OptionalArg) }
+              signature_size = (signature_without_optional.size..signature.size)
+
+              raise ArgumentError, "wrong number of arguments to #{function} (given #{args.size}, expected #{signature_size})" unless signature_size.include?(args.size)
+            else
+              raise ArgumentError, "wrong number of arguments to #{function} (given #{args.size}, expected #{signature.size})" unless signature.size == args.size
+            end
+          end
+
+          def check_types(args, function, signature)
+            args.zip(signature).each_with_index do |(arg, type), index|
+              type = type.type if type.kind_of?(OptionalArg)
+
+              raise ArgumentError, "wrong type for argument #{index + 1} to #{function} (given #{arg.class}, expected #{type})" unless arg.kind_of?(type)
+            end
+          end
+        end
+
+        rule(:null_literal  => simple(:v)) { nil }
+        rule(:true_literal  => simple(:v)) { true }
+        rule(:false_literal => simple(:v)) { false }
+
+        rule(:string   => simple(:v)) { v.to_s[1..-2] }
+        rule(:number   => simple(:v)) { v.match(/[eE.]/) ? Float(v) : Integer(v) }
+        rule(:jsonpath => simple(:v)) { Floe::Workflow::Path.value(v.to_s, context, input) }
+
+        rule(:states_array => {:args => subtree(:args)}) do
+          Transformer.process_args(args, "States.Array")
+        end
+
+        rule(:states_array_partition => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayPartition", [Array, Integer])
+          array, chunk = *args
+          raise ArgumentError, "invalid value for argument 2 to States.ArrayPartition (given #{chunk}, expected a positive Integer)" unless chunk.positive?
+
+          array.each_slice(chunk).to_a
+        end
+
+        rule(:states_array_contains => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayContains", [Array, Object])
+          array, target = *args
+
+          array.include?(target)
+        end
+
+        rule(:states_array_range => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayRange", [Integer, Integer, Integer])
+          range_begin, range_end, increment = *args
+          raise ArgumentError, "invalid value for argument 3 to States.ArrayRange (given #{increment}, expected a non-zero Integer)" if increment.zero?
+
+          (range_begin..range_end).step(increment).to_a
+        end
+
+        rule(:states_array_get_item => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayGetItem", [Array, Integer])
+          array, index = *args
+          raise ArgumentError, "invalid value for argument 2 to States.ArrayGetItem (given #{index}, expected 0 or a positive Integer)" unless index >= 0
+
+          array[index]
+        end
+
+        rule(:states_array_length => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayLength", [Array])
+          array = args.first
+
+          array.size
+        end
+
+        rule(:states_array_unique => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.ArrayUnique", [Array])
+          array = args.first
+
+          array.uniq
+        end
+
+        rule(:states_base64_encode => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.Base64Encode", [String])
+          str = args.first
+
+          require "base64"
+          Base64.strict_encode64(str).force_encoding("UTF-8")
+        end
+
+        rule(:states_base64_decode => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.Base64Decode", [String])
+          str = args.first
+
+          require "base64"
+          begin
+            Base64.strict_decode64(str)
+          rescue ArgumentError => err
+            raise ArgumentError, "invalid value for argument 1 to States.Base64Decode (#{err})"
+          end
+        end
+
+        rule(:states_hash => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.Hash", [Object, String])
+          data, algorithm = *args
+          raise NotImplementedError if data.kind_of?(Hash)
+          if data.nil?
+            raise ArgumentError, "invalid value for argument 1 to States.Hash (given null, expected non-null)"
+          end
+
+          algorithms = %w[MD5 SHA-1 SHA-256 SHA-384 SHA-512]
+          unless algorithms.include?(algorithm)
+            raise ArgumentError, "invalid value for argument 2 to States.Hash (given #{algorithm.inspect}, expected one of #{algorithms.map(&:inspect).join(", ")})"
+          end
+
+          require "openssl"
+          algorithm = algorithm.sub("-", "")
+          data = data.to_json unless data.kind_of?(String)
+          OpenSSL::Digest.hexdigest(algorithm, data)
+        end
+
+        rule(:states_math_random => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.MathRandom", [Integer, Integer, OptionalArg[Integer]])
+          range_start, range_end, seed = *args
+          unless range_start < range_end
+            raise ArgumentError, "invalid values for arguments to States.MathRandom (start must be less than end)"
+          end
+
+          seed ||= Random.new_seed
+          Random.new(seed).rand(range_start..range_end)
+        end
+
+        rule(:states_math_add => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.MathAdd", [Integer, Integer])
+
+          args.sum
+        end
+
+        rule(:states_string_split => {:args => subtree(:args)}) do
+          args = Transformer.process_args(args(), "States.StringSplit", [String, String])
+          str, delimeter = *args
+
+          case delimeter.size
+          when 0
+            str.empty? ? [] : [str]
+          when 1
+            str.split(delimeter)
+          else
+            str.split(/[#{Regexp.escape(delimeter)}]+/)
+          end
+        end
+
+        rule(:states_uuid => {:args => subtree(:args)}) do
+          Transformer.process_args(args, "States.UUID", [])
+
+          require "securerandom"
+          SecureRandom.uuid
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Performance/RegexpMatch, Performance/RedundantMatch

data/lib/floe/workflow/intrinsic_function.rb

@@ -0,0 +1,34 @@
+require "parslet"
+
+module Floe
+  class Workflow
+    class IntrinsicFunction
+      def self.value(payload, context = {}, input = {})
+        new(payload).value(context, input)
+      end
+
+      def self.intrinsic_function?(payload)
+        payload.start_with?("States.")
+      end
+
+      attr_reader :payload
+
+      def initialize(payload)
+        @payload = payload
+        @tree    = Parser.new.parse(payload)
+
+        Floe.logger.debug { "Parsed intrinsic function: #{payload.inspect} => #{tree.inspect}" }
+      rescue Parslet::ParseFailed => err
+        raise Floe::InvalidWorkflowError, err.message
+      end
+
+      def value(context = {}, input = {})
+        Transformer.new.apply(tree, :context => context, :input => input)
+      end
+
+      private
+
+      attr_reader :tree
+    end
+  end
+end

data/lib/floe/workflow/path.rb

@@ -4,6 +4,10 @@ module Floe
   class Workflow
     class Path
       class << self
+        def path?(payload)
+          payload.start_with?("$")
+        end
+
         def value(payload, context, input = {})
           new(payload).value(context, input)
         end
@@ -26,8 +30,10 @@ module Floe
             [input, payload]
           end
 
-        results = JsonPath.on(obj, path)
+        # If path is $ then just return the entire input
+        return obj if path == "$"
 
+        results = JsonPath.on(obj, path)
         results.count < 2 ? results.first : results
       end
     end

data/lib/floe/workflow/payload_template.rb

@@ -42,14 +42,17 @@ module Floe
       end
 
       def parse_payload_string(value)
-        value.start_with?("$") ? Path.new(value) : value
+        return Path.new(value)              if Path.path?(value)
+        return IntrinsicFunction.new(value) if IntrinsicFunction.intrinsic_function?(value)
+
+        value
       end
 
       def interpolate_value(value, context, inputs)
         case value
-        when Array then interpolate_value_array(value, context, inputs)
-        when Hash  then interpolate_value_hash(value, context, inputs)
-        when Path  then value.value(context, inputs)
+        when Array                   then interpolate_value_array(value, context, inputs)
+        when Hash                    then interpolate_value_hash(value, context, inputs)
+        when Path, IntrinsicFunction then value.value(context, inputs)
         else
           value
         end

data/lib/floe/workflow/retrier.rb

@@ -3,15 +3,21 @@
 module Floe
   class Workflow
     class Retrier
-      attr_reader :error_equals, :interval_seconds, :max_attempts, :backoff_rate
+      include ErrorMatcherMixin
+      include ValidationMixin
 
-      def initialize(payload)
-        @payload = payload
+      attr_reader :error_equals, :interval_seconds, :max_attempts, :backoff_rate, :name
+
+      def initialize(_workflow, name, payload)
+        @name             = name
+        @payload          = payload
 
         @error_equals     = payload["ErrorEquals"]
         @interval_seconds = payload["IntervalSeconds"] || 1.0
         @max_attempts     = payload["MaxAttempts"] || 3
         @backoff_rate     = payload["BackoffRate"] || 2.0
+
+        missing_field_error!("ErrorEquals") if !@error_equals.kind_of?(Array) || @error_equals.empty?
       end
 
       # @param [Integer] attempt 1 for the first attempt

data/lib/floe/workflow/state.rb

@@ -4,16 +4,18 @@ module Floe
   class Workflow
     class State
       include Logging
+      include ValidationMixin
 
       class << self
         def build!(workflow, name, payload)
           state_type = payload["Type"]
-          raise Floe::InvalidWorkflowError, "Missing \"Type\" field in state [#{name}]" if payload["Type"].nil?
+          missing_field_error!(name, "Type") if payload["Type"].nil?
+          invalid_field_error!(name[0..-2], "Name", name.last, "must be less than or equal to 80 characters") if name.last.length > 80
 
           begin
             klass = Floe::Workflow::States.const_get(state_type)
           rescue NameError
-            raise Floe::InvalidWorkflowError, "Invalid state type: [#{state_type}]"
+            invalid_field_error!(name, "Type", state_type, "is not valid")
           end
 
           klass.new(workflow, name, payload)
@@ -22,14 +24,11 @@ module Floe
 
       attr_reader :comment, :name, :type, :payload
 
-      def initialize(workflow, name, payload)
+      def initialize(_workflow, name, payload)
         @name     = name
         @payload  = payload
         @type     = payload["Type"]
         @comment  = payload["Comment"]
-
-        raise Floe::InvalidWorkflowError, "Missing \"Type\" field in state [#{name}]" if payload["Type"].nil?
-        raise Floe::InvalidWorkflowError, "State name [#{name[..79]}...] must be less than or equal to 80 characters" if name.length > 80
       end
 
       def wait(context, timeout: nil)
@@ -54,7 +53,7 @@ module Floe
       def start(context)
         context.state["EnteredTime"] = Time.now.utc.iso8601
 
-        logger.info("Running state: [#{long_name}] with input [#{context.input}]...")
+        logger.info("Running state: [#{long_name}] with input [#{context.json_input}]...")
       end
 
       def finish(context)
@@ -64,8 +63,8 @@ module Floe
         context.state["FinishedTime"] ||= finished_time.iso8601
         context.state["Duration"]       = finished_time - entered_time
 
-        level = context.output&.[]("Error") ? :error : :info
-        logger.public_send(level, "Running state: [#{long_name}] with input [#{context.input}]...Complete #{context.next_state ? "- next state [#{context.next_state}]" : "workflow -"} output: [#{context.output}]")
+        level = context.failed? ? :error : :info
+        logger.public_send(level, "Running state: [#{long_name}] with input [#{context.json_input}]...Complete #{context.next_state ? "- next state [#{context.next_state}]" : "workflow -"} output: [#{context.json_output}]")
 
         0
       end
@@ -86,8 +85,12 @@ module Floe
         context.state["WaitUntil"] && Time.parse(context.state["WaitUntil"])
       end
 
+      def short_name
+        name.last
+      end
+
       def long_name
-        "#{@type}:#{name}"
+        "#{type}:#{short_name}"
       end
 
       private
@@ -95,7 +98,7 @@ module Floe
       def wait_until!(context, seconds: nil, time: nil)
         context.state["WaitUntil"] =
           if seconds
-            (Time.parse(context.state["EnteredTime"]) + seconds).iso8601
+            (Time.now + seconds).iso8601
           elsif time.kind_of?(String)
             time
           else

data/lib/floe/workflow/states/choice.rb

@@ -11,7 +11,7 @@ module Floe
 
           validate_state!(workflow)
 
-          @choices = payload["Choices"].map { |choice| ChoiceRule.build(choice) }
+          @choices = payload["Choices"].map.with_index { |choice, i| ChoiceRule.build(workflow, name + ["Choices", i.to_s], choice) }
           @default = payload["Default"]
 
           @input_path  = Path.new(payload.fetch("InputPath", "$"))
@@ -19,7 +19,8 @@ module Floe
         end
 
         def finish(context)
-          output     = output_path.value(context, context.input)
+          input      = input_path.value(context, context.input)
+          output     = output_path.value(context, input)
           next_state = choices.detect { |choice| choice.true?(context, output) }&.next || default
 
           context.next_state = next_state
@@ -43,12 +44,12 @@ module Floe
         end
 
         def validate_state_choices!
-          raise Floe::InvalidWorkflowError, "Choice state must have \"Choices\"" unless payload.key?("Choices")
-          raise Floe::InvalidWorkflowError, "\"Choices\" must be a non-empty array" unless payload["Choices"].kind_of?(Array) && !payload["Choices"].empty?
+          missing_field_error!("Choices") unless payload.key?("Choices")
+          invalid_field_error!("Choices", nil, "must be a non-empty array") unless payload["Choices"].kind_of?(Array) && !payload["Choices"].empty?
         end
 
         def validate_state_default!(workflow)
-          raise Floe::InvalidWorkflowError, "\"Default\" not in \"States\"" unless workflow.payload["States"].include?(payload["Default"])
+          invalid_field_error!("Default", payload["Default"], "is not found in \"States\"") if payload["Default"] && !workflow_state?(payload["Default"], workflow)
         end
       end
     end

data/lib/floe/workflow/states/fail.rb

@@ -4,7 +4,7 @@ module Floe
   class Workflow
     module States
       class Fail < Floe::Workflow::State
-        attr_reader :cause, :error
+        attr_reader :cause, :error, :cause_path, :error_path
 
         def initialize(workflow, name, payload)
           super

data/lib/floe/workflow/states/non_terminal_mixin.rb

@@ -12,8 +12,8 @@ module Floe
         end
 
         def validate_state_next!(workflow)
-          raise Floe::InvalidWorkflowError, "Missing \"Next\" field in state [#{name}]" if @next.nil? && !@end
-          raise Floe::InvalidWorkflowError, "\"Next\" [#{@next}] not in \"States\" for state [#{name}]" if @next && !workflow.payload["States"].key?(@next)
+          missing_field_error!("Next") if @next.nil? && !@end
+          invalid_field_error!("Next", @next, "is not found in \"States\"") if @next && !workflow_state?(@next, workflow)
         end
       end
     end

data/lib/floe/workflow/states/pass.rb

@@ -25,7 +25,8 @@ module Floe
         end
 
         def finish(context)
-          context.output = process_output(context, result)
+          input = result.nil? ? process_input(context) : result
+          context.output = process_output(context, input)
           super
         end
 

data/lib/floe/workflow/states/succeed.rb

@@ -6,9 +6,18 @@ module Floe
       class Succeed < Floe::Workflow::State
         attr_reader :input_path, :output_path
 
+        def initialize(workflow, name, payload)
+          super
+
+          @input_path  = Path.new(payload.fetch("InputPath", "$"))
+          @output_path = Path.new(payload.fetch("OutputPath", "$"))
+        end
+
         def finish(context)
+          input              = input_path.value(context, context.input)
+          context.output     = output_path.value(context, input)
           context.next_state = nil
-          context.output     = context.input
+
           super
         end
 

data/lib/floe/workflow/states/task.rb

@@ -18,10 +18,13 @@ module Floe
           @next              = payload["Next"]
           @end               = !!payload["End"]
           @resource          = payload["Resource"]
-          @runner            = Floe::Runner.for_resource(@resource)
+
+          missing_field_error!("Resource") unless @resource.kind_of?(String)
+          @runner = wrap_parser_error("Resource", @resource) { Floe::Runner.for_resource(@resource) }
+
           @timeout_seconds   = payload["TimeoutSeconds"]
-          @retry             = payload["Retry"].to_a.map { |retrier| Retrier.new(retrier) }
-          @catch             = payload["Catch"].to_a.map { |catcher| Catcher.new(catcher) }
+          @retry             = payload["Retry"].to_a.map.with_index { |retrier, i| Retrier.new(workflow, name + ["Retry", i.to_s], retrier) }
+          @catch             = payload["Catch"].to_a.map.with_index { |catcher, i| Catcher.new(workflow, name + ["Catch", i.to_s], catcher) }
           @input_path        = Path.new(payload.fetch("InputPath", "$"))
           @output_path       = Path.new(payload.fetch("OutputPath", "$"))
           @result_path       = ReferencePath.new(payload.fetch("ResultPath", "$"))
@@ -30,8 +33,6 @@ module Floe
           @credentials       = PayloadTemplate.new(payload["Credentials"])    if payload["Credentials"]
 
           validate_state!(workflow)
-        rescue ArgumentError => err
-          raise Floe::InvalidWorkflowError, err.message
         end
 
         def start(context)
@@ -82,11 +83,11 @@ module Floe
         end
 
         def find_retrier(error)
-          self.retry.detect { |r| (r.error_equals & [error, "States.ALL"]).any? }
+          self.retry.detect { |r| r.match_error?(error) }
         end
 
         def find_catcher(error)
-          self.catch.detect { |c| (c.error_equals & [error, "States.ALL"]).any? }
+          self.catch.detect { |c| c.match_error?(error) }
         end
 
         def retry_state!(context, error)
@@ -106,7 +107,7 @@ module Floe
           wait_until!(context, :seconds => retrier.sleep_duration(context["State"]["RetryCount"]))
           context.next_state = context.state_name
           context.output     = error
-          logger.info("Running state: [#{long_name}] with input [#{context.input}] got error[#{context.output}]...Retry - delay: #{wait_until(context)}")
+          logger.info("Running state: [#{long_name}] with input [#{context.json_input}] got error[#{context.json_output}]...Retry - delay: #{wait_until(context)}")
           true
         end
 
@@ -116,7 +117,7 @@ module Floe
 
           context.next_state = catcher.next
           context.output     = catcher.result_path.set(context.input, error)
-          logger.info("Running state: [#{long_name}] with input [#{context.input}]...CatchError - next state: [#{context.next_state}] output: [#{context.output}]")
+          logger.info("Running state: [#{long_name}] with input [#{context.json_input}]...CatchError - next state: [#{context.next_state}] output: [#{context.json_output}]")
 
           true
         end
@@ -126,7 +127,7 @@ module Floe
           # keeping in here for completeness
           context.next_state = nil
           context.output = error
-          logger.error("Running state: [#{long_name}] with input [#{context.input}]...Complete workflow - output: [#{context.output}]")
+          logger.error("Running state: [#{long_name}] with input [#{context.json_input}]...Complete workflow - output: [#{context.json_output}]")
         end
 
         def parse_error(output)

data/lib/floe/workflow.rb

@@ -6,6 +6,7 @@ require "json"
 module Floe
   class Workflow
     include Logging
+    include ValidationMixin
 
     class << self
       def load(path_or_io, context = nil, credentials = {}, name = nil)
@@ -96,19 +97,21 @@ module Floe
       # caller should really put credentials into context and not pass that variable
       context.credentials = credentials if credentials
 
-      raise Floe::InvalidWorkflowError, "Missing field \"States\""  if payload["States"].nil?
-      raise Floe::InvalidWorkflowError, "Missing field \"StartAt\"" if payload["StartAt"].nil?
-      raise Floe::InvalidWorkflowError, "\"StartAt\" not in the \"States\" field" unless payload["States"].key?(payload["StartAt"])
-
-      @name        = name
+      # NOTE: this is a string, and states use an array
+      @name        = name || "State Machine"
       @payload     = payload
       @context     = context
       @comment     = payload["Comment"]
       @start_at    = payload["StartAt"]
 
-      @states         = payload["States"].to_a.map { |state_name, state| State.build!(self, state_name, state) }
-      @states_by_name = @states.each_with_object({}) { |state, result| result[state.name] = state }
-    rescue Floe::InvalidWorkflowError
+      # NOTE: Everywhere else we include our name (i.e.: parent name) when building the child name.
+      #       When creating the states, we are dropping our name (i.e.: the workflow name)
+      @states      = payload["States"].to_a.map { |state_name, state| State.build!(self, ["States", state_name], state) }
+
+      validate_workflow
+
+      @states_by_name = @states.each_with_object({}) { |state, result| result[state.short_name] = state }
+    rescue Floe::Error
       raise
     rescue => err
       raise Floe::InvalidWorkflowError, err.message
@@ -157,7 +160,7 @@ module Floe
     end
 
     def output
-      context.output if end?
+      context.json_output if end?
     end
 
     def end?
@@ -187,8 +190,15 @@ module Floe
     def credentials
       @context.credentials
     end
+
     private
 
+    def validate_workflow
+      missing_field_error!("States") if @states.empty?
+      missing_field_error!("StartAt") if @start_at.nil?
+      invalid_field_error!("StartAt", @start_at, "is not found in \"States\"") unless workflow_state?(@start_at, self)
+    end
+
     def step!
       next_state = {"Name" => context.next_state, "Guid" => SecureRandom.uuid, "PreviousStateGuid" => context.state["Guid"]}
 

data/lib/floe.rb

@@ -7,7 +7,9 @@ require_relative "floe/logging"
 
 require_relative "floe/runner"
 
+require_relative "floe/validation_mixin"
 require_relative "floe/workflow"
+require_relative "floe/workflow/error_matcher_mixin"
 require_relative "floe/workflow/catcher"
 require_relative "floe/workflow/choice_rule"
 require_relative "floe/workflow/choice_rule/not"
@@ -15,6 +17,9 @@ require_relative "floe/workflow/choice_rule/or"
 require_relative "floe/workflow/choice_rule/and"
 require_relative "floe/workflow/choice_rule/data"
 require_relative "floe/workflow/context"
+require_relative "floe/workflow/intrinsic_function"
+require_relative "floe/workflow/intrinsic_function/parser"
+require_relative "floe/workflow/intrinsic_function/transformer"
 require_relative "floe/workflow/path"
 require_relative "floe/workflow/payload_template"
 require_relative "floe/workflow/reference_path"
@@ -37,6 +42,7 @@ require "time"
 module Floe
   class Error < StandardError; end
   class InvalidWorkflowError < Error; end
+  class InvalidExecutionInput < Error; end
 
   def self.logger
     @logger ||= NullLogger.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: floe
 version: !ruby/object:Gem::Version
-  version: 0.11.3
+  version: 0.12.0
 platform: ruby
 authors:
 - ManageIQ Developers
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-20 00:00:00.000000000 Z
+date: 2024-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_spawn
@@ -80,20 +80,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: parslet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: manageiq-style
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,20 +136,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -196,6 +196,7 @@ files:
 - lib/floe/logging.rb
 - lib/floe/null_logger.rb
 - lib/floe/runner.rb
+- lib/floe/validation_mixin.rb
 - lib/floe/version.rb
 - lib/floe/workflow.rb
 - lib/floe/workflow/catcher.rb
@@ -205,6 +206,10 @@ files:
 - lib/floe/workflow/choice_rule/not.rb
 - lib/floe/workflow/choice_rule/or.rb
 - lib/floe/workflow/context.rb
+- lib/floe/workflow/error_matcher_mixin.rb
+- lib/floe/workflow/intrinsic_function.rb
+- lib/floe/workflow/intrinsic_function/parser.rb
+- lib/floe/workflow/intrinsic_function/transformer.rb
 - lib/floe/workflow/path.rb
 - lib/floe/workflow/payload_template.rb
 - lib/floe/workflow/reference_path.rb