aws-flow 2.3.1 → 2.4.0

data/lib/aws/templates.rb

@@ -0,0 +1,4 @@
+require 'aws/templates/base'
+require 'aws/templates/activity'
+require 'aws/templates/default'
+require 'aws/templates/starter'

data/lib/aws/templates/activity.rb

@@ -0,0 +1,69 @@
+module AWS
+  module Flow
+    module Templates
+
+      # This template represents an Activity in SWF. It holds the name and
+      # scheduling options for the activity
+      class ActivityTemplate < TemplateBase
+        attr_reader :name, :options
+
+        def initialize(name, opts = {})
+          options = opts.dup
+          # Split the name into prefix name and activity method
+          prefix_name, @name = name.split(".")
+
+          # Raise if we don't have a fully qualified name for the activity
+          raise ArgumentError, "Activity name should be fully qualified: "\
+            "<prefix_name>.<activity_method>" unless @name
+
+          # Get all the property keys from the ActivityOptions class
+          keys = ActivityOptions.held_properties.push(:exponential_retry)
+
+          # Only select the options that are needed
+          options.select!{ |x| keys.include?(x) }
+
+          # Merge in default values for the activity in case they are not passed
+          # by the user
+          options = {
+            version: FlowConstants.defaults[:version],
+            prefix_name: "#{prefix_name}",
+            data_converter:  FlowConstants.defaults[:data_converter],
+            exponential_retry: FlowConstants.defaults[:retry_policy]
+          }.merge(options)
+
+          @options = options
+        end
+
+        # Uses the ActivityClient given in the context (workflow class) passed
+        # in by the calling template to schedule this activity
+        def run(input, context)
+          # Get a duplicate of the options hash so as not to change what's
+          # stored in this object
+          options = @options.dup
+          # If a :tasklist key is passed as input to this template, then schedule
+          # this activity on that tasklist
+          if input.is_a?(Hash) && input[:task_list]
+            options.merge!(task_list: input[:task_list])
+          end
+          # Schedule the activity using the ActivityClient in the context
+          context.act_client.send(@name, input) { options }
+        end
+      end
+
+      # Initializes an activity template
+      # @param {String} name
+      # @param {Hash} options
+      def activity(name, opts = {})
+        AWS::Flow::Templates.send(:activity, name, opts)
+      end
+
+      # Initializes an activity template
+      # @param {String} name
+      # @param {Hash} options
+      def self.activity(name, opts = {})
+        ActivityTemplate.new(name, opts)
+      end
+
+    end
+  end
+end

data/lib/aws/templates/base.rb

@@ -0,0 +1,87 @@
+module AWS
+  module Flow
+    module Templates
+
+      # A Template is a precanned workflow definition that can be combined with
+      # other templates to construct a workflow body. TemplateBase is a class
+      # that must be inherited by all templates. It provides the 'abstract'
+      # method #run that needs to be implemented by subclasses.
+      class TemplateBase
+
+        # This method needs to be implemented by the sub classes.
+        # @param {Hash} input
+        #   This is the input to the template
+        # @param {AWS::Flow::Workflows} context
+        #   A class that extends AWS::Flow::Workflows. The workflow that runs a
+        #   template passes itself as an argument to provide the template with
+        #   the right context to execute in.
+        def run(input, context)
+          raise NotImplementedError, "Please implement the #run method of your template."
+        end
+
+      end
+
+      # Root template is the top level template that is sent to a workflow to
+      # run. It contains a step (which is another template) that it passes the
+      # input and the context to. It also contains a result_step that it uses to
+      # report the result of the workflow.
+      class RootTemplate < TemplateBase
+        attr_reader :step, :input
+        attr_accessor :result_step
+
+        def initialize(step, result_step)
+          @step = step
+          @result_step = result_step
+        end
+
+        # Calls the run method on the step (top level template). Manages overall
+        # error handling and reporting of results for the workflow
+        def run(input, context)
+          result = nil
+          failure = nil
+          begin
+            result = @step.run(input, context)
+          rescue Exception => e
+            failure = e
+          ensure
+            if failure
+              # If there is a result_step, pass the failure as an input to it.
+              @result_step.run({failure: failure}, context) if @result_step
+              # Now fail the workflow
+              raise e
+            else
+              # Pass the result as an input to the result_step
+              @result_step.run(result, context) if @result_step
+              # Complete the workflow by returning the result
+              result
+            end
+          end
+        end
+      end
+
+      # Initializes a root template
+      # @param {TemplateBase} step
+      #   An AWS Flow Framework Template class that inherits TemplateBase. It
+      #   contains the actual orchestration of workflow logic inside it.
+      # @param {ActivityTemplate} result_step
+      #   An optional ActivityTemplate that can be used to report the result
+      #   of the 'step'
+      def root(step, result_step = nil)
+        AWS::Flow::Templates.send(:root, step, result_step)
+      end
+
+      # Initializes a root template
+      # @param {TemplateBase} step
+      #   An AWS Flow Framework Template class that inherits TemplateBase. It
+      #   contains the actual orchestration of workflow logic inside it.
+      # @param {ActivityTemplate} result_step
+      #   An optional ActivityTemplate that can be used to report the result
+      #   of the 'step'
+      def self.root(step, result_step = nil)
+        RootTemplate.new(step, result_step)
+      end
+
+
+    end
+  end
+end

data/lib/aws/templates/default.rb

@@ -0,0 +1,146 @@
+module AWS
+  module Flow
+    module Templates
+
+      # Default workflow class for the AWS Flow Framework for Ruby. It
+      # can run workflows defined by WorkflowTemplates.
+      class FlowDefaultWorkflowRuby
+        extend AWS::Flow::Workflows
+
+        # Create activity client and child workflow client
+        activity_client :act_client
+        child_workflow_client :child_client
+
+        # Create the workflow type with default options
+        workflow FlowConstants.defaults[:execution_method] do
+          {
+            version: FlowConstants.defaults[:version],
+            prefix_name: FlowConstants.defaults[:prefix_name],
+            default_task_list: FlowConstants.defaults[:task_list],
+            default_execution_start_to_close_timeout: FlowConstants.defaults[:execution_start_to_close_timeout]
+          }
+        end
+
+        # Define the workflow method :start. It will take in an input hash
+        # that contains the root template (:definition) and the arguments to the
+        # template (:args).
+        # @param input Hash
+        #   A hash containing the following keys -
+        #     definition: An object of type AWS::Flow::Templates::RootTemplate
+        #     args: Hash of arguments to be passed to the definition
+        #
+        def start(input)
+
+          raise ArgumentError, "Workflow input must be a Hash" unless input.is_a?(Hash)
+          raise ArgumentError, "Input hash must contain key :definition" if input[:definition].nil?
+          raise ArgumentError, "Input hash must contain key :args" if input[:args].nil?
+
+          definition = input[:definition]
+          args = input[:args]
+
+          unless definition.is_a?(AWS::Flow::Templates::RootTemplate)
+            raise "Workflow Definition must be a AWS::Flow::Templates::RootTemplate"
+          end
+          raise "Input must be a Hash" unless args.is_a?(Hash)
+
+          # Run the root workflow template
+          definition.run(args, self)
+
+        end
+
+      end
+
+      # Proxy classes for user activities are created in this module
+      module ActivityProxies; end
+
+      # Used to convert a regular ruby class into a Ruby Flow Activity class,
+      # i.e. extends the AWS::Flow::Activities module. It converts all user
+      # defined instance methods into activities and assigns the following
+      # defaults to the ActivityType - version: "1.0"
+      def self.make_activity_class(klass)
+        return klass if klass.nil?
+
+        name = klass.name.split(":").last
+
+        proxy_name = name + "Proxy"
+        # Create a proxy activity class that will define activities for all
+        # instance methods of the class.
+        new_klass = self::ActivityProxies.const_set(proxy_name.to_sym, Class.new(Object))
+
+        # Extend the AWS::Flow::Activities module and create activities for all
+        # instance methods
+        new_klass.class_exec do
+          extend AWS::Flow::Activities
+
+          attr_reader :instance
+
+          @@klass = klass
+
+          def initialize
+            @instance = @@klass.new
+          end
+
+          # Creates activities for all instance methods of the held klass
+          @@klass.instance_methods(false).each do |method|
+            activity(method) do
+              {
+                version: "1.0",
+                prefix_name: name
+              }
+            end
+          end
+
+          # Redirect all method calls to the held instance
+          def method_missing(method, *args, &block)
+            @instance.send(method, *args, &block)
+          end
+
+        end
+        new_klass
+      end
+
+      # Default result reporting activity class for the AWS Flow Framework for
+      # Ruby
+      class FlowDefaultResultActivityRuby
+        extend AWS::Flow::Activities
+
+        attr_reader :result
+
+        # Create the activity type with default options
+        activity FlowConstants.defaults[:result_activity_method] do
+          {
+            version: FlowConstants.defaults[:result_activity_version],
+            prefix_name: FlowConstants.defaults[:result_activity_prefix],
+            default_task_list: FlowConstants.defaults[:task_list],
+            exponential_retry: FlowConstants.defaults[:retry_policy]
+          }
+        end
+
+        # Initialize the future upon instantiation
+        def initialize
+          @result = Future.new
+        end
+
+        # Set the future when the activity is run
+        def run(input)
+          @result.set(input)
+          input
+        end
+
+      end
+
+      # Returns the default result activity class
+      # @api private
+      def self.result_activity
+        return AWS::Flow::Templates.const_get(FlowConstants.defaults[:result_activity_prefix])
+      end
+
+      # Returns the default workflow class
+      # @api private
+      def self.default_workflow
+        return AWS::Flow::Templates.const_get(FlowConstants.defaults[:prefix_name])
+      end
+
+    end
+  end
+end

data/lib/aws/templates/starter.rb

@@ -0,0 +1,256 @@
+module AWS
+  module Flow
+
+    # @api private
+    module Templates
+
+      # Starts an Activity or a Workflow Template execution using the default
+      # workflow class FlowDefaultWorkflowRuby
+      #
+      # @param [String or AWS::Flow::Templates::TemplateBase] name_or_klass
+      #   The Activity or the Workflow Template that needs to be scheduled via
+      #   the default workflow. This argument can either be a string that
+      #   represents a fully qualified activity name - <ActivityClass>.<method_name>
+      #   or it can be an instance of AWS::Flow::Templates::TemplateBase
+      #
+      # @param [Hash] input
+      #   Input hash for the workflow execution
+      #
+      # @param [Hash] opts
+      #   Additional options to configure the workflow or activity execution.
+      #
+      # @option opts [true, false] :wait
+      #   *Optional* This boolean flag can be set to true if the result of the
+      #   task is required. Default value is false.
+      #
+      # @option opts [Integer] :wait_timeout
+      #   *Optional* This sets the timeout value for :wait. Default value is
+      #   nil.
+      #
+      # @option opts [Hash] :exponential_retry
+      #   A hash of {AWS::Flow::ExponentialRetryOptions}. Default value is -
+      #   { maximum_attempts: 3 }
+      #
+      # @option opts [String] *Optional* :domain
+      #   Default value is FlowDefault
+      #
+      # @option opts [Integer] *Optional* :execution_start_to_close_timeout
+      #   Default value is 3600 seconds (1 hour)
+      #
+      # @option opts [Integer] *Optional* :retention_in_days
+      #   Default value is 7 days
+      #
+      # @option opts [String] *Optional* :workflow_id
+      #
+      # @option opts [Integer] *Optional* :task_priority
+      #   Default value is 0
+      #
+      # @option opts [String] *Optional* :tag_list
+      #   By default, the name of the activity task gets added to the workflow's
+      #   tag_list
+      #
+      # @option opts *Optional* :data_converter
+      #   Default value is {AWS::Flow::YAMLDataConverter}. To use the
+      #   {AWS::Flow::S3DataConverter}, set the AWS_SWF_BUCKET_NAME environment
+      #   variable name with a valid AWS S3 bucket name.
+      #
+      # @option opts *Optional* A hash of {AWS::Flow::ActivityOptions}
+      #
+      # Usage -
+      #
+      #    AWS::Flow::start("<ActivityClassName>.<method_name>", <input_hash>,
+      #    <options_hash> )
+      #
+      # Example -
+      #
+      # 1) Start an activity execution -
+      #    AWS::Flow::start("HelloWorldActivity.say_hello", { name: "World" })
+      #
+      # 2) Start an activity execution with overriden options -
+      #    AWS::Flow::start("HelloWorldActivity.say_hello", { name: "World" }, {
+      #      exponential_retry: { maximum_attempts: 10 } }
+      #    )
+      #
+      def self.start(name_or_klass, input, opts = {})
+
+        options = opts.dup
+
+        if name_or_klass.is_a?(String)
+          # Add activity name as a tag to the workflow execution
+          (options[:tag_list] ||= []) << name_or_klass
+
+          # If name_or_klass passed in is a string, we are assuming the user is
+          # trying to start a single activity task. Wrap the activity information
+          # in the activity template
+          name_or_klass = AWS::Flow::Templates.activity(name_or_klass, options)
+
+          # Keep only the required options in the hash
+          keys = [
+            :domain,
+            :retention_in_days,
+            :execution_start_to_close_timeout,
+            :task_priority,
+            :wait,
+            :wait_timeout,
+            :workflow_id,
+            :data_converter,
+            :tag_list
+          ]
+          options.select! { |x| keys.include?(x) }
+
+        end
+
+        # Wrap the template in a root template
+        root = AWS::Flow::Templates.root(name_or_klass)
+
+        # Get the default options and merge them with the options passed in. The
+        # order of the two hashes 'defaults' and 'options' is important here.
+        defaults = FlowConstants.defaults.select do |key|
+          [
+            :domain,
+            :prefix_name,
+            :execution_method,
+            :version,
+            :execution_start_to_close_timeout,
+            :data_converter,
+            :task_list
+          ].include?(key)
+        end
+        options = defaults.merge(options)
+
+        raise "input needs to be a Hash" unless input.is_a?(Hash)
+
+        # Set the input for the default workflow
+        workflow_input = {
+          definition: root,
+          args: input,
+        }
+
+        # Set the result_step for the root template if wait flag is
+        # set.
+        wait = options.delete(:wait)
+        wait_timeout = options.delete(:wait_timeout)
+        result_tasklist = set_result_activity(root) if wait
+
+        # Call #start_workflow with the correct options to start the workflow
+        # execution
+        begin
+          AWS::Flow::start_workflow(workflow_input, options)
+        rescue AWS::SimpleWorkflow::Errors::UnknownResourceFault => e
+          register_defaults(options[:domain])
+          AWS::Flow::start_workflow(workflow_input, options)
+        end
+
+        # Wait for result
+        get_result(result_tasklist, options[:domain], wait_timeout) if wait
+
+      end
+
+      # Sets the result activity with a unique tasklist name for the root template.
+      # @api private
+      def self.set_result_activity(root)
+        # We want the result to be sent to a specific tasklist so that no other
+        # worker gets the result of this workflow.
+        result_tasklist = "result_tasklist: #{SecureRandom.uuid}"
+
+        name = "#{FlowConstants.defaults[:result_activity_prefix]}."\
+          "#{FlowConstants.defaults[:result_activity_method]}"
+
+        # Set the result_step of the root template to the result activity and
+        # override the tasklist and timeouts.
+        root.result_step = activity(name, {
+            task_list: result_tasklist,
+            schedule_to_start_timeout: FlowConstants.defaults[:schedule_to_start_timeout],
+            start_to_close_timeout: FlowConstants.defaults[:start_to_close_timeout]
+          }
+        )
+        result_tasklist
+      end
+
+      # Gets the result of the workflow execution by starting an ActivityWorker
+      # on the FlowDefaultResultActivityRuby class. The result activity will set
+      # the instance variable future :result with the result of the template.
+      # It will block till either the result future is set or till the timeout
+      # expires - whichever comes first.
+      # @api private
+      def self.get_result(tasklist, domain, timeout=nil)
+
+        swf = AWS::SimpleWorkflow.new
+        domain = swf.domains[domain]
+
+        # Create a new instance of the FlowDefaultResultActivityRuby class and
+        # add it to the ActivityWorker. We pass in the instance instead of the
+        # class itself, so that we can locally access the instance variable set
+        # by the activity method.
+        activity = FlowDefaultResultActivityRuby.new
+
+        # Create the activity worker to poll on the result tasklist
+        worker = AWS::Flow::ActivityWorker.new(domain.client, domain, tasklist, activity) {{ use_forking: false }}
+
+        # Keep polling till we get the result or timeout. A 0 or nil timeout
+        # will let the loop run to completion.
+        begin
+          Timeout::timeout(timeout) do
+            until activity.result.set?
+              worker.run_once(false)
+            end
+          end
+        rescue Timeout::Error => e
+          activity.result.set
+          return
+        end
+
+        # Get the result from the future
+        result = activity.result.get
+        if result.is_a?(Hash) && result[:failure] && result[:failure].is_a?(Exception)
+          raise result[:failure]
+        end
+
+        result
+      end
+
+      # Registers the relevant defaults with the Simple Workflow Service
+      # @api private
+      def self.register_defaults(name=nil)
+        domain = name.nil? ? register_default_domain : AWS::SimpleWorkflow.new.domains[name]
+
+        register_default_workflow(domain)
+        register_default_result_activity(domain)
+      end
+
+      # Registers the default domain FlowDefault with the Simple Workflow
+      # Service
+      # @api private
+      def self.register_default_domain
+        AWS::Flow::Utilities.register_domain(FlowConstants.defaults[:domain])
+      end
+
+      # Registers the default workflow type FlowDefaultWorkflowRuby with the
+      # Simple Workflow Service
+      # @api private
+      def self.register_default_workflow(domain)
+        AWS::Flow::WorkflowWorker.new(
+          domain.client,
+          domain,
+          nil,
+          AWS::Flow::Templates.default_workflow
+        ).register
+      end
+
+      # Registers the default result activity type FlowDefaultResultActivityRuby
+      # with the Simple Workflow Service
+      # @api private
+      def self.register_default_result_activity(domain)
+        worker = AWS::Flow::ActivityWorker.new(
+          domain.client,
+          domain,
+          nil,
+          AWS::Flow::Templates.result_activity
+        ) {{ use_forking: false }}
+        worker.register
+      end
+
+    end
+
+  end
+end