Class: Temporalio::Workflow::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/temporalio/workflow/definition.rb

Overview

Base class for all workflows.

Workflows are instances of this class and must implement #execute. Inside the workflow code, class methods on Temporalio::Workflow can be used.

By default, the workflow is named as its unqualified class name. This can be customized with Definition.workflow_name.

Defined Under Namespace

Classes: Info, Query, Signal, Update

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.workflow_dynamic(value = true) ⇒ Object (protected)

Set a workflow as dynamic. Dynamic workflows do not have names and handle any workflow that is not otherwise registered. A worker can only have one dynamic workflow. It is often useful to use workflow_raw_args with this.

Parameters:

  • value (Boolean) (defaults to: true) —

    Whether the workflow is dynamic.



37
38
39
 
# File 'lib/temporalio/workflow/definition.rb', line 37

def workflow_dynamic(value = true) # rubocop:disable Style/OptionalBooleanParameter
  @workflow_dynamic = value
end

.workflow_dynamic_options ⇒ Object (protected)

Mark the next method as returning some dynamic configuraion.

Because dynamic workflows may conceptually represent more than one workflow type, it may be desirable to have different settings for fields that would normally be passed to ‘workflow_xxx` setters, but vary based on the workflow type name or other information available in the workflow’s context. This function will be called after the workflow’s ‘initialize`, if it has one, but before the workflow’s ‘execute` method.

The method must only take self as a parameter, and any values set in the class it returns will override those provided to other ‘workflow_xxx` setters.

Cannot be specified on non-dynamic workflows.



205
206
207
208
209
 
# File 'lib/temporalio/workflow/definition.rb', line 205

def workflow_dynamic_options
  raise 'Dynamic options method can only be set on workflows using `workflow_dynamic`' unless @workflow_dynamic

  self.pending_handler_details = { type: :dynamic_options }
end

.workflow_failure_exception_type(*types) ⇒ Object (protected)

Configure workflow failure exception types. This sets the types of exceptions that, if a workflow-thrown exception extends, will cause the workflow/update to fail instead of suspending the workflow via task failure. These are applied in addition to the worker option. If Exception is set, it effectively will fail a workflow/update in all user exception cases.

Parameters:

  • types (Array<Class<Exception>>) —

    Exception types to turn into workflow failures.



56
57
58
59
60
61
62
 
# File 'lib/temporalio/workflow/definition.rb', line 56

def workflow_failure_exception_type(*types)
  types.each do |t|
    raise ArgumentError, 'All types must classes inheriting Exception' unless t.is_a?(Class) && t < Exception
  end
  @workflow_failure_exception_types ||= []
  @workflow_failure_exception_types.concat(types)
end

.workflow_init(value = true) ⇒ Object (protected)

Mark an ‘initialize` as needing the workflow start arguments. Otherwise, `initialize` must accept no required arguments. This must be placed above the `initialize` method or it will fail.

Parameters:

  • value (Boolean) (defaults to: true) —

    Whether the start parameters will be passed to ‘initialize`.



107
108
109
 
# File 'lib/temporalio/workflow/definition.rb', line 107

def workflow_init(value = true) # rubocop:disable Style/OptionalBooleanParameter
  self.pending_handler_details = { type: :init, value: }
end

.workflow_name(workflow_name) ⇒ Object (protected)

Customize the workflow name. By default the workflow is named the unqualified class name of the class provided to the worker.

Parameters:

  • workflow_name (String, Symbol) —

    Name to use.



23
24
25
26
27
28
29
30
 
# File 'lib/temporalio/workflow/definition.rb', line 23

def workflow_name(workflow_name)
  if !workflow_name.is_a?(Symbol) && !workflow_name.is_a?(String)
    raise ArgumentError,
          'Workflow name must be a symbol or string'
  end

  @workflow_name = workflow_name.to_s
end

.workflow_query(name: nil, description: nil, dynamic: false, raw_args: false) ⇒ Object (protected)

Mark the next method as a workflow query with a default name as the name of the method. Queries can not have any side effects, meaning they should never mutate state or try to wait on anything.

Parameters:

  • name (String, Symbol, nil) (defaults to: nil) —

    Override the default name.

  • description (String, nil) (defaults to: nil) —

    Description for this handler that may appear in CLI/UI. This is currently experimental.

  • dynamic (Boolean) (defaults to: false) —

    If true, make the query dynamic. This means it receives all other queries without handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often it is useful to have the second parameter be ‘*args` and `raw_args` be true.

  • raw_args (Boolean) (defaults to: false) —

    If true, does not convert arguments, but instead provides each argument as Converters::RawValue which is a raw payload wrapper, convertible with Temporalio::Workflow.payload_converter.



147
148
149
150
151
152
153
154
155
156
 
# File 'lib/temporalio/workflow/definition.rb', line 147

def workflow_query(
  name: nil,
  description: nil,
  dynamic: false,
  raw_args: false
)
  raise 'Cannot provide name if dynamic is true' if name && dynamic

  self.pending_handler_details = { type: :query, name:, description:, dynamic:, raw_args: }
end

.workflow_query_attr_reader(*attr_names, description: nil) ⇒ Object (protected)

Expose an attribute as a method and as a query. A ‘workflow_query_attr_reader :foo` is the equivalent of: “` workflow_query def foo

@foo

end “‘ This means it is a superset of `attr_reader“ and will not work if also using `attr_reader` or `attr_accessor`. If a writer is needed alongside this, use `attr_writer`.

Parameters:

  • attr_names (Array<Symbol>) —

    Attributes to expose.

  • description (String, nil) (defaults to: nil) —

    Description that may appear in CLI/UI, applied to each query handler implicitly created. This is currently experimental.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/temporalio/workflow/definition.rb', line 77

def workflow_query_attr_reader(*attr_names, description: nil)
  @workflow_queries ||= {}
  attr_names.each do |attr_name|
    raise 'Expected attr to be a symbol' unless attr_name.is_a?(Symbol)

    if method_defined?(attr_name, false)
      raise 'Method already defined for this attr name. ' \
            'Note that a workflow_query_attr_reader includes attr_reader behavior. ' \
            'If you also want a writer for this attribute, use a separate attr_writer.'
    end

    # Just run this as if done manually
    workflow_query(description:)
    define_method(attr_name) { instance_variable_get("@#{attr_name}") }
  end
end

.workflow_raw_args(value = true) ⇒ Object (protected)

Have workflow arguments delivered to ‘execute` (and `initialize` if workflow_init in use) as Converters::RawValues. These are wrappers for the raw payloads that have not been converted to types (but they have been decoded by the codec if present). They can be converted with Temporalio::Workflow.payload_converter.

Parameters:

  • value (Boolean) (defaults to: true) —

    Whether the workflow accepts raw arguments.



46
47
48
 
# File 'lib/temporalio/workflow/definition.rb', line 46

def workflow_raw_args(value = true) # rubocop:disable Style/OptionalBooleanParameter
  @workflow_raw_args = value
end

.workflow_signal(name: nil, description: nil, dynamic: false, raw_args: false, unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON) ⇒ Object (protected)

Mark the next method as a workflow signal with a default name as the name of the method. Signals cannot return values.

Parameters:

  • name (String, Symbol, nil) (defaults to: nil) —

    Override the default name.

  • description (String, nil) (defaults to: nil) —

    Description for this handler that may appear in CLI/UI. This is currently experimental.

  • dynamic (Boolean) (defaults to: false) —

    If true, make the signal dynamic. This means it receives all other signals without handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often it is useful to have the second parameter be ‘*args` and `raw_args` be true.

  • raw_args (Boolean) (defaults to: false) —

    If true, does not convert arguments, but instead provides each argument as Converters::RawValue which is a raw payload wrapper, convertible with Temporalio::Workflow.payload_converter.

  • unfinished_policy (HandlerUnfinishedPolicy) (defaults to: HandlerUnfinishedPolicy::WARN_AND_ABANDON) —

    How to treat unfinished handlers if they are still running when the workflow ends. The default warns, but this can be disabled.



124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/temporalio/workflow/definition.rb', line 124

def workflow_signal(
  name: nil,
  description: nil,
  dynamic: false,
  raw_args: false,
  unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON
)
  raise 'Cannot provide name if dynamic is true' if name && dynamic

  self.pending_handler_details = { type: :signal, name:, description:, dynamic:, raw_args:, unfinished_policy: }
end

.workflow_update(name: nil, description: nil, dynamic: false, raw_args: false, unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON) ⇒ Object (protected)

Mark the next method as a workflow update with a default name as the name of the method. Updates can return values. Separate validation methods can be provided via workflow_update_validator.

Parameters:

  • name (String, Symbol, nil) (defaults to: nil) —

    Override the default name.

  • description (String, nil) (defaults to: nil) —

    Description for this handler that may appear in CLI/UI. This is currently experimental.

  • dynamic (Boolean) (defaults to: false) —

    If true, make the update dynamic. This means it receives all other updates without handlers. This cannot have a name override since it is nameless. The first parameter will be the name. Often it is useful to have the second parameter be ‘*args` and `raw_args` be true.

  • raw_args (Boolean) (defaults to: false) —

    If true, does not convert arguments, but instead provides each argument as Converters::RawValue which is a raw payload wrapper, convertible with Temporalio::Workflow.payload_converter.

  • unfinished_policy (HandlerUnfinishedPolicy) (defaults to: HandlerUnfinishedPolicy::WARN_AND_ABANDON) —

    How to treat unfinished handlers if they are still running when the workflow ends. The default warns, but this can be disabled.



171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/temporalio/workflow/definition.rb', line 171

def workflow_update(
  name: nil,
  description: nil,
  dynamic: false,
  raw_args: false,
  unfinished_policy: HandlerUnfinishedPolicy::WARN_AND_ABANDON
)
  raise 'Cannot provide name if dynamic is true' if name && dynamic

  self.pending_handler_details = { type: :update, name:, description:, dynamic:, raw_args:, unfinished_policy: }
end

.workflow_update_validator(update_method) ⇒ Object (protected)

Mark the next method as a workflow update validator to the given update method. The validator is expected to have the exact same parameter signature. It will run before an update and if it raises an exception, the update will be rejected, possibly before even reaching history. Validators cannot have any side effects or do any waiting, and they do not return values.

Parameters:

  • update_method (Symbol) —

    Name of the update method.



189
190
191
 
# File 'lib/temporalio/workflow/definition.rb', line 189

def workflow_update_validator(update_method)
  self.pending_handler_details = { type: :update_validator, update_method: }
end

.workflow_versioning_behavior(behavior) ⇒ Object (protected)

Set the versioning behavior of this workflow.

WARNING: This method is experimental and may change in future versions.

Parameters:



99
100
101
 
# File 'lib/temporalio/workflow/definition.rb', line 99

def workflow_versioning_behavior(behavior)
  @versioning_behavior = behavior
end

Instance Method Details

#execute(*args) ⇒ Object

Execute the workflow. This is the primary workflow method. The workflow is completed when this method completes. This must be implemented by all workflows.

Raises:

  • (NotImplementedError) 


457
458
459
 
# File 'lib/temporalio/workflow/definition.rb', line 457

def execute(*args)
  raise NotImplementedError, 'Workflow did not implement "execute"'
end