Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ jobs:
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.0.3
ruby-version: '3.4'
bundler-cache: true

- name: Run tests
Expand All @@ -44,7 +44,7 @@ jobs:
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.0.3
ruby-version: '3.4'

- name: Bundle install
run: |
Expand Down
3 changes: 2 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ PROTO_DIRS = $(sort $(dir $(PROTO_FILES)))
PROTO_OUT := lib/gen

proto:
$(foreach PROTO_DIR,$(PROTO_DIRS),bundle exec grpc_tools_ruby_protoc -Iproto --ruby_out=$(PROTO_OUT) --grpc_out=$(PROTO_OUT) $(PROTO_DIR)*.proto;)
@set -e; $(foreach PROTO_DIR,$(PROTO_DIRS),bundle exec grpc_tools_ruby_protoc -Iproto --ruby_out=$(PROTO_OUT) --grpc_out=$(PROTO_OUT) $(PROTO_DIR)*.proto;)
@for script in scripts/backport_*.rb; do bundle exec ruby "$$script" || exit $$?; done

.PHONY: proto
24 changes: 24 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,30 @@ To achieve this there are two methods (returning a UUID token) available from yo

Both tokens will remain the same across multiple retry attempts of the activity.

When an Activity error carries a service-provided retry interval, include
`Temporal::RetryDelay` in that error class and set `next_retry_delay` in seconds
before raising it. The value must be positive, at least one nanosecond, and may be fractional. For example:

```ruby
class RateLimited < StandardError
include Temporal::RetryDelay

attr_reader :retry_after_seconds
end

def execute
ExternalService.call
rescue RateLimited => error
error.next_retry_delay = error.retry_after_seconds
raise
end
```

Only errors that include this module use the override. The retry policy's maximum attempts and
the Activity's timeouts still limit retries. Use `nil` for no override; zero and other invalid
delay values raise `ArgumentError` when set. The server versions used by this SDK can treat a zero
override as a retry timeout.

### Asynchronous completion

When dealing with asynchronous business logic in your activities, you might need to wait for an
Expand Down
18 changes: 18 additions & 0 deletions docs/retry-delay-parity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Per-failure retry delay parity

The first-party Ruby SDK reference is [`temporalio/sdk-ruby` at `2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e`](https://github.com/temporalio/sdk-ruby/tree/2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e). Its [Activity failure test](https://github.com/temporalio/sdk-ruby/blob/2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e/temporalio/test/worker_activity_test.rb#L200-L251) sets a fractional `next_retry_delay: 1.23` on a non-retryable `ApplicationError` and checks that the client receives its message, type, details, non-retryable flag, and retry delay. That test proves metadata round-trip; its non-retryable setting means it does not verify a scheduled retry. The [first-party failure converter](https://github.com/temporalio/sdk-ruby/blob/2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e/temporalio/lib/temporalio/converters/failure_converter.rb#L40-L54) writes the delay to `ApplicationFailureInfo`; [deserialization](https://github.com/temporalio/sdk-ruby/blob/2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e/temporalio/lib/temporalio/converters/failure_converter.rb#L140-L154) restores it. The [wire field](https://github.com/temporalio/api/blob/v1.44.0/temporal/api/failure/v1/message.proto) is field 4, a protobuf `Duration`.

| First-party behavior or boundary | This fork's coverage |
| --- | --- |
| Fractional delay survives serialization and deserialization | `failure_spec.rb`: `preserves a fractional retry delay...` runs for both legacy and v2 exception serialization, checks seconds/nanos, original class, message, and reconstructed delay. |
| Original error type, details, and stack trace survive as appropriate to converter mode | Existing `failure_spec.rb` full/legacy/fallback cases and `workflow/errors_spec.rb` reconstruction cases remain in the focused suite. New fractional cases assert class and message for both modes. |
| Retry-delay metadata remains available when the original class is not installed on the reader | `workflow/errors_spec.rb`: `retains a retry delay when the original error class is unavailable`. This is specific to the fork's class-based reconstruction. |
| Server schedules the next remote Activity attempt using the override, instead of the retry policy interval | `spec/integration/retry_delay_spec.rb` inspects `DescribeWorkflowExecution` pending failure for the fractional field and waits for the second actual Activity attempt; policy interval and maximum interval are 1 second, while the override is 2.3 seconds. Run with `TEMPORAL_TEST_PORT` against an isolated Temporal server. |
| Inbound delay `0` is distinct from an absent override | `failure_spec.rb`: `preserves an inbound zero delay without emitting one by default` also reserializes the restored error without an invalid override. The [first-party converter](https://github.com/temporalio/sdk-ruby/blob/2169e3e0dc2b4f59dbf9cc93205e19c2c01a037e/temporalio/lib/temporalio/internal/proto_utils.rb#L8-L20) preserves zero. This fork reads it for interoperability but does not emit it on re-raise because Temporal Server 1.32 treats a zero custom delay as a retry timeout. |
| Ordinary errors remain retryable without an opt-in delay | `failure_spec.rb`: `does not infer an override...`; existing ordinary error tests. Only exceptions including `Temporal::RetryDelay` emit the field. |
| Invalid inputs cannot create malformed duration or silently lose Activity failure reports | `failure_spec.rb`: `rejects invalid delay values before an error can be raised`. Setter rejects zero, sub-nanosecond, negative, non-finite, non-real, non-numeric, and out-of-range values; valid fractional values serialize at nanosecond precision. |
| Retry caps and total timeouts still apply | The [Temporal retry-policy contract](https://docs.temporal.io/encyclopedia/retry-policies#per-error-next-retry-delay) states the override replaces the interval while limits remain in force. The SDK sends an ordinary `ApplicationFailureInfo` with the additional duration; server owns enforcement. The integration test uses `max_attempts: 2` and checks exactly two attempts. |
| First-party non-retryable flag, arbitrary `ApplicationError` details, and cause chain | This fork keeps its existing class-based non-retriable policy and legacy/v2 exception payload behavior. Adding a separate ApplicationError wrapper or per-instance non-retryable API is outside this retry-delay change. The first-party test's non-retryable flag is used to terminate promptly, not to test retry scheduling. |
| First-party Go local Activity delay tests | [Go `ErrorWithNextDelay`](https://github.com/temporalio/sdk-go/blob/733b222690ef005e9cb09e684a11372fe7241a68/test/activity_test.go#L70) and [local Activity test](https://github.com/temporalio/sdk-go/blob/733b222690ef005e9cb09e684a11372fe7241a68/test/workflow_test.go#L90) exercise local Activities, which this fork does not implement. They are not a direct remote Activity parity test. |

This table maps behaviors, not raw test counts. The live integration assertion is required to claim server scheduling behavior; a skipped test only establishes that the test harness is present.
3 changes: 2 additions & 1 deletion lib/gen/temporal/api/failure/v1/message_pb.rb

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 14 additions & 1 deletion lib/temporal/connection/serializer/failure.rb
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
require 'temporal/connection/serializer/base'
require 'temporal/errors'
require 'google/protobuf/duration_pb'

module Temporal
module Connection
Expand Down Expand Up @@ -27,18 +29,29 @@ def to_proto
else
details = converter.to_details_payloads(object.message)
end
next_retry_delay = duration_from(object.next_retry_delay) if object.is_a?(Temporal::RetryDelay)
Temporalio::Api::Failure::V1::Failure.new(
message: object.message,
stack_trace: stack_trace_from(object.backtrace),
application_failure_info: Temporalio::Api::Failure::V1::ApplicationFailureInfo.new(
type: object.class.name,
details: details
details: details,
next_retry_delay: next_retry_delay
)
)
end

private

def duration_from(value)
# A failure read from history can carry a delay rejected by this server. Keep its error intact on re-raise.
return unless Temporal::RetryDelay.valid_seconds?(value)

nanoseconds = (value.to_r * 1_000_000_000).round
seconds, nanos = nanoseconds.divmod(1_000_000_000)
Google::Protobuf::Duration.new(seconds: seconds, nanos: nanos)
end

def stack_trace_from(backtrace)
return unless backtrace

Expand Down
25 changes: 25 additions & 0 deletions lib/temporal/errors.rb
Original file line number Diff line number Diff line change
@@ -1,4 +1,29 @@
module Temporal
# Include this in an exception class to opt in to a per-failure retry delay.
# The value is seconds and may be fractional. It only overrides the next
# interval; the retry policy's attempt limit and timeouts still apply.
module RetryDelay
attr_reader :next_retry_delay

def next_retry_delay=(seconds)
unless seconds.nil? || Temporal::RetryDelay.valid_seconds?(seconds)
raise ArgumentError, 'next_retry_delay must be a finite number of seconds between 1 nanosecond and 315576000000 seconds'
end

@next_retry_delay = seconds
end

def self.valid_seconds?(seconds)
seconds.is_a?(Numeric) && seconds.real? && seconds.finite? &&
seconds.to_r >= Rational(1, 1_000_000_000) && seconds <= 315_576_000_000
end

def self.restore(error, seconds)
error.extend(self) unless error.is_a?(self)
error.instance_variable_set(:@next_retry_delay, seconds)
end
end

# Superclass for all Temporal errors
class Error < StandardError; end

Expand Down
6 changes: 6 additions & 0 deletions lib/temporal/workflow/errors.rb
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ def self.generate_error(failure, converter, default_exception_class = StandardEr
)
end
exception.tap do |exception|
retry_delay = failure.application_failure_info.next_retry_delay
if retry_delay
# Older failures may carry zero; preserve their metadata without applying outbound validation.
Temporal::RetryDelay.restore(exception,
(retry_delay.seconds + retry_delay.nanos.quo(1_000_000_000)).to_f)
end
backtrace = failure.stack_trace.split("\n")
exception.set_backtrace(backtrace) if !backtrace.empty?
end
Expand Down
4 changes: 4 additions & 0 deletions rbi/temporal-ruby.rbi
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
module Temporal
module RetryDelay
def next_retry_delay; end
def next_retry_delay=(seconds); end
end
class Activity; end
class ActivityException; end
module Client
Expand Down
32 changes: 32 additions & 0 deletions scripts/backport_next_retry_delay.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
#!/usr/bin/env ruby
# Restore the additive next_retry_delay field after regenerating the pinned API proto.

require 'google/protobuf/descriptor_pb'

path = File.expand_path('../lib/gen/temporal/api/failure/v1/message_pb.rb', __dir__)
source = File.read(path)
match = source.match(/^descriptor_data = (".*")$/)
raise 'Unexpected generated failure descriptor' unless match

descriptor = Google::Protobuf::FileDescriptorProto.decode(match[1].undump)
raise 'Unexpected failure proto' unless descriptor.name == 'temporal/api/failure/v1/message.proto'
application = descriptor.message_type.find { |message| message.name == 'ApplicationFailureInfo' }
raise 'Missing ApplicationFailureInfo' unless application
field = application.field.find { |item| item.name == 'next_retry_delay' }
if field
raise 'Unexpected next_retry_delay field' unless field.number == 4 && field.type_name == '.google.protobuf.Duration'
exit 0
end
raise 'Field 4 is occupied' if application.field.any? { |item| item.number == 4 }
raise 'Duration already imported' if descriptor.dependency.include?('google/protobuf/duration.proto')

application.field << Google::Protobuf::FieldDescriptorProto.new(
name: 'next_retry_delay', number: 4,
label: :LABEL_OPTIONAL, type: :TYPE_MESSAGE, type_name: '.google.protobuf.Duration'
)
descriptor.dependency << 'google/protobuf/duration.proto'
source.sub!(match[0]) { "descriptor_data = #{Google::Protobuf::FileDescriptorProto.encode(descriptor).dump}" }
old_require = "require 'temporal/api/enums/v1/workflow_pb'"
raise 'Unexpected generated failure imports' unless source.scan(old_require).size == 1
source.sub!(old_require, "#{old_require}\nrequire 'google/protobuf/duration_pb'")
File.write(path, source)
1 change: 1 addition & 0 deletions spec/config/fabrication.rb
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
require 'ostruct'
require 'fabrication'

Fabrication.configure do |config|
Expand Down
Loading
Loading