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_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`.



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

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.



138
139
140
141
142
143
144
145
146
147
 
# File 'lib/temporalio/workflow/definition.rb', line 138

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.



115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/temporalio/workflow/definition.rb', line 115

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.



162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/temporalio/workflow/definition.rb', line 162

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.



180
181
182
 
# File 'lib/temporalio/workflow/definition.rb', line 180

def workflow_update_validator(update_method)
  self.pending_handler_details = { type: :update_validator, update_method: }
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) 


405
406
407
 
# File 'lib/temporalio/workflow/definition.rb', line 405

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