ntswf 1.0.8 → 2.0.0

data/README.md

@@ -15,54 +15,32 @@ Usage
 -----
 ### Gemfile
 
-    gem 'ntswf', '~> 1.0'
+    gem 'ntswf', '~> 2.0'
 
 ### Client
 ```
-class WorkflowClient
-  include Ntswf::Client
-
-  def enqueue!
-    start_execution(
-      execution_id: 'my_singleton_task',
-      name: 'my_worker_name',
-      params: {my: :param},
-      unit: 'my_worker',
-    )
-  end
-end
-
 config = {domain: 'my_domain', unit: 'my_app'} # ...
-WorkflowClient.new(config).enqueue!
+Ntswf.create(:client, config).start_execution(
+  execution_id: 'my_singleton_task',
+  name: 'my_worker_name',
+  params: {my_param: :param},
+  unit: 'my_worker',
+)
 ```
-See {Ntswf::Base#initialize} for configuration options.
+See {Ntswf::Base#configure} for configuration options.
 
 ### Decision worker
 ```
-class Decider
-  include Ntswf::DecisionWorker
-end
-
 config = {domain: 'my_domain', unit: 'my_app'} # ...
-Decider.new(config).process_decisions
+Ntswf.create(:decision_worker, config).process_decisions
 ```
 
 ### Activity worker
 ```
-class Worker
-  include Ntswf::ActivityWorker
-
-  def process_activity_task
-    super do |task|
-      options = parse_input(task.input)
-      # ...
-      task.complete!(result: 'OK')
-    end
-  end
-end
-
 config = {domain: 'my_domain', unit: 'my_worker'} # ...
-Worker.new(config).process_activities
+worker = Ntswf.create(:activity_worker, config)
+worker.on_task ->(task) { Ntswf.result task.params['my_param'] }
+worker.process_activities
 ```
 
 ### Setup helpers

data/lib/ntswf/activity_worker.rb

@@ -5,6 +5,29 @@ module Ntswf
   module ActivityWorker
     include Ntswf::Worker
 
+    # Configure a proc or block to be called on receiving an {AWS::SimpleWorkflow::ActivityTask}
+    # @yieldparam task [Hash]
+    #   Description of the task's properties:
+    #   :activity_task:: The {AWS::SimpleWorkflow::ActivityTask}
+    #   :name:: Kind of task
+    #   :params:: Custom parameters given to the execution (parsed back from JSON)
+    #   :version:: Client version
+    #
+    #   See {Ntswf::Client#start_execution}'s options for details
+    # @param proc [Proc] The callback
+    # @yieldreturn [Hash]
+    #   Processing result. The following keys are interpreted accordingly:
+    #   :error:: Fails the task with the given error details.
+    #   :outcome:: Completes the task, storing the outcome's value (as JSON).
+    #   :seconds_until_retry::
+    #     Re-schedules the task after the given delay.
+    #     In combination with an *:error*: Marks the task for immediate re-scheduling,
+    #     ignoring the value.
+    #     Please note that the behaviour is undefined if an *:interval* option has been set.
+    def on_activity(proc = nil, &block)
+      @task_callback = proc || block
+    end
+
     # Start the worker loop for activity tasks.
     def process_activities
       loop { in_subprocess :process_activity_task }
@@ -12,19 +35,41 @@ module Ntswf
 
     def process_activity_task
       announce("polling for activity task #{activity_task_list}")
-      domain.activity_tasks.poll_for_single_task(activity_task_list) do |task|
-        announce("got activity task #{task.activity_type.inspect} #{task.input}")
+      domain.activity_tasks.poll_for_single_task(activity_task_list) do |activity_task|
+        announce("got activity task #{activity_task.activity_type.inspect} #{activity_task.input}")
         begin
-          yield task
+          returned_hash = @task_callback.call(describe(activity_task)) if @task_callback
+          process_returned_hash(activity_task, returned_hash)
         rescue => e
-          notify(e, activity_type: task.activity_type.inspect, input: task.input)
+          notify(e, activity_type: activity_task.activity_type.inspect, input: activity_task.input)
           details = {
             error: e.message[0, 1000],
             exception: e.class.to_s[0, 1000],
           }
-          task.fail!(details: details.to_json, reason: 'Exception')
+          activity_task.fail!(details: details.to_json, reason: 'Exception')
         end
       end
     end
+
+    protected
+
+    def describe(activity_task)
+      options = parse_input(activity_task.input).merge(activity_task: activity_task)
+      options.map { |k, v| {k.to_sym => v} }.reduce(&:merge!)
+    end
+
+    KNOWN_RETURN_KEYS = [:error, :outcome, :seconds_until_retry]
+
+    def process_returned_hash(activity_task, returned_hash)
+      return unless returned_hash.kind_of? Hash
+      kind, value = returned_hash.detect { |k, v| KNOWN_RETURN_KEYS.include? k }
+      case kind
+      when :error
+        reason = returned_hash[:seconds_until_retry] ? "Retry" : "Error"
+        activity_task.fail!(details: {error: value.to_s[0, 1000]}.to_json, reason: reason)
+      when :outcome, :seconds_until_retry
+        activity_task.complete!(result: returned_hash.to_json)
+      end
+    end
   end
 end

data/lib/ntswf/base.rb

@@ -12,7 +12,8 @@ module Ntswf
     # @option config [Numeric] :subprocess_retries (0) see {Worker#in_subprocess}
     # @option config [String] :secret_access_key AWS credential
     # @option config [String] :unit This worker/client's activity task list key
-    def initialize(config)
+    # @raise If a task list name is invalid
+    def configure(config)
       @config = OpenStruct.new(config)
       raise_if_invalid_task_list
     end

data/lib/ntswf/client.rb

@@ -22,11 +22,11 @@ module Ntswf
     #   The executing unit's key, a corresponding activity task list must be configured
     # @option options [Numeric] :version
     #   Optional minimum version of the client. The task may be rescheduled by older clients.
-    # @return [AWS::SimpleWorkflow::WorkflowExecution]
+    # @return (see #find)
     # @raise [AWS::SimpleWorkflow::Errors::WorkflowExecutionAlreadyStartedFault]
     def start_execution(options)
       execution_id = options.delete(:execution_id)
-      workflow_type.start_execution(
+      workflow_execution = workflow_type.start_execution(
         child_policy: :terminate,
         execution_start_to_close_timeout: 48 * 3600,
         input: options.to_json,
@@ -35,10 +35,124 @@ module Ntswf
         task_start_to_close_timeout: 10 * 60,
         workflow_id: [activity_task_list, execution_id].join(separator),
       )
+      execution_details(workflow_execution).merge!(
+        name: options[:name].to_s,
+        params: options[:params],
+      )
+    end
+
+    # Get status and details of a workflow execution.
+    # @param ids [Hash] Identifies the queried execution
+    # @option ids [String] :workflow_id Workflow ID
+    # @option ids [String] :run_id Run ID
+    # @raise [AWS::SimpleWorkflow::Errors::UnknownResourceFault]
+    # @return [Hash]
+    #   Execution properties.
+    #   :exception:: Exception message for an unexpectedly failed execution
+    #   :error:: Error message returned from an execution
+    #   :outcome:: Result of a completed execution
+    #   :params:: Custom params from JSON
+    #   :run_id:: The workflow execution's run ID
+    #   :status:: Calculated workflow execution status (:completed, :open, others indicating failure)
+    #   :name:: Given task kind
+    #   :workflow_id:: The workflow execution's workflow ID
+    def find(ids)
+      workflow_execution = domain.workflow_executions.at(ids[:workflow_id], ids[:run_id])
+      history_details(workflow_execution)
     end
 
     protected
 
+    def execution_details(workflow_execution)
+      {
+        workflow_id: workflow_execution.workflow_id,
+        run_id: workflow_execution.run_id,
+        status: workflow_execution.status,
+      }
+    end
+
+    def history_details(workflow_execution)
+      result = execution_details(workflow_execution)
+      input = parse_input workflow_execution.history_events.first.attributes.input
+      result.merge!(name: input["name"].to_s, params: input["params"])
+
+      case result[:status]
+      when :open
+        # nothing
+      when :completed
+        result.merge!(completion_details workflow_execution)
+      else
+        result.merge!(failure_details workflow_execution)
+      end
+      result
+    end
+
+    def completion_details(workflow_execution)
+      completed_event = workflow_execution.history_events.reverse_order.detect do |e|
+        e.event_type == "WorkflowExecutionCompleted"
+      end
+      if completed_event
+        {outcome: parse_attribute(completed_event, :result)["outcome"]}
+      else
+        {status: :open}
+      end
+    end
+
+    TERMINAL_EVENT_TYPES_ON_FAILURE = %w(
+      WorkflowExecutionFailed
+      WorkflowExecutionTimedOut
+      WorkflowExecutionCanceled
+      WorkflowExecutionTerminated
+    )
+
+    def failure_details(workflow_execution)
+      terminal_event = workflow_execution.history_events.reverse_order.detect {|e|
+        TERMINAL_EVENT_TYPES_ON_FAILURE.include?(e.event_type)
+      }
+      if terminal_event
+        event_type = terminal_event.event_type
+        case event_type
+        when "WorkflowExecutionFailed"
+          details = parse_attribute(terminal_event, :details)
+          {
+            error: details["error"],
+            exception: details["exception"],
+          }
+        else
+          {
+            error: event_type,
+            exception: event_type,
+          }
+        end
+      else
+        log("No terminal event for execution"\
+            " #{workflow_execution.workflow_id} | #{workflow_execution.run_id}."\
+            " Event types: #{workflow_execution.history_events.map(&:event_type)}") rescue nil
+        {
+          error: "Execution has finished with status #{workflow_execution.status},"\
+              " but did not provide details."
+        }
+      end
+    end
+
+    def parse_attribute(event, key)
+      value = nil
+      begin
+        json_value = event.attributes[key]
+      rescue ArgumentError
+        # missing key in event attributes
+      end
+      if json_value
+        begin
+          value = JSON.parse json_value
+        rescue # JSON::ParserError, ...
+          # no JSON
+        end
+      end
+      value = nil unless value.kind_of? Hash
+      value || {}
+    end
+
     def workflow_type
       @workflow_type ||= domain.workflow_types[workflow_name, workflow_version]
     end

data/lib/ntswf/decision_worker.rb

@@ -16,9 +16,7 @@ module Ntswf
     # reason:: reschedule if {RETRY}
     # result:: Interpreted as {Hash}, see below for keys
     # Result keys
-    # :seconds_until_retry::
-    # Planned re-schedule after task completion. Please note that
-    # given an *:interval* option the behaviour of this key is undefined
+    # :seconds_until_retry:: See {ActivityWorker#on_activity}
     def process_decision_task
       announce("polling for decision task #{decision_task_list}")
       domain.decision_tasks.poll_for_single_task(decision_task_list) do |task|

data/lib/ntswf/instance.rb

@@ -0,0 +1,19 @@
+module Ntswf
+  class Instance
+    # @!method initialize(*modules, config)
+    # @param modules (DEFAULT_MODULES)
+    #   A list of module names to include
+    # @param config (see Base#configure)
+    # @option config (see Base#configure)
+    def initialize(*args)
+      symbols = args.grep Symbol
+      configs = args - symbols
+      instance_exec do
+        module_names = symbols.map(&:to_s).map { |s| s.gsub(/(^|_)(.)/) { $2.upcase } }
+        module_names = DEFAULT_MODULES if module_names.empty?
+        module_names.each { |module_name| extend Ntswf::const_get module_name }
+      end
+      configure(configs.last || {})
+    end
+  end
+end

data/lib/ntswf/worker.rb

@@ -7,7 +7,7 @@ module Ntswf
     # *reason* value to force task reschedule, may be set if the worker is unable process the task
     RETRY = "Retry"
 
-    # Run a method in a separate thread.
+    # Run a method in a separate process.
     # This will ensure the call lives on if the master process is terminated.
     # If the *:subprocess_retries* configuration is set {StandardError}s during the
     # method call will be retried accordingly.

data/lib/ntswf.rb

@@ -1,16 +1,25 @@
 module Ntswf
-  AUTOLOAD = %w(
+  # @!method self.create(*modules, config)
+  # Shortcut for creating an {Instance}
+  # @example
+  #     Ntswf.create(:client, :activity_worker, unit: "my_worker")
+  # @param modules (see Instance#initialize)
+  # @param config (see Instance#initialize)
+  # @option config (see Base#configure)
+  def self.create(*args)
+    Ntswf::Instance.new(*args)
+  end
+
+  DEFAULT_MODULES = %w(
     ActivityWorker
     Client
     DecisionWorker
     Utils
   )
 
-  AUTOLOAD.each { |c| autoload c.to_sym, "ntswf/#{c.gsub(/.(?=[A-Z])/, '\0_').downcase}.rb" }
+  AUTOLOAD = DEFAULT_MODULES + %w(
+    Instance
+  )
 
-  def self.included(base)
-    base.module_exec do
-      AUTOLOAD.each { |c| include const_get c }
-    end
-  end
+  AUTOLOAD.each { |c| autoload c.to_sym, "ntswf/#{c.gsub(/.(?=[A-Z])/, '\0_').downcase}.rb" }
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ntswf
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-28 00:00:00.000000000 Z
+date: 2014-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -54,6 +54,7 @@ files:
 - lib/ntswf/decision_worker.rb
 - lib/ntswf/utils.rb
 - lib/ntswf/activity_worker.rb
+- lib/ntswf/instance.rb
 - lib/ntswf/worker.rb
 - lib/ntswf/client.rb
 - lib/ntswf/base.rb