Add Ruby SDK support by donald-pinckney · Pull Request #41 · temporalio/skill-temporal-developer

donald-pinckney · 2026-03-16T23:37:54Z

Summary

Add 11 Ruby reference files (~2100 lines) covering all major Temporal SDK features: workflows, activities, signals/queries/updates, child workflows, versioning, testing, error handling, data conversion, observability, determinism protection, and advanced features
Update SKILL.md to include Ruby in description, overview, and getting started guide
Add Ruby entry to core/determinism.md SDK Protection Mechanisms section

Details

The Ruby SDK (temporalio gem, GA) uses a fundamentally different determinism approach from Python (sandbox) and TypeScript (V8 isolate):

Illegal Call Tracing via Ruby's TracePoint to detect forbidden method calls at runtime
Durable Fiber Scheduler to make fiber operations deterministic

Ruby-specific sections added that don't exist in Python/TypeScript:

Cancellation (Token-based) — uses Temporalio::Cancellation objects
ActiveModel Integration — Ruby equivalent of Pydantic
Converter Hints — workflow_arg_hint/workflow_result_hint for type guidance
Illegal Call Tracing Gotchas — third-party gems triggering NondeterminismError
Activity Concurrency and Executors — ThreadPool configuration
Rails Integration — ActiveRecord, Zeitwerk, forking considerations

Test plan

Verify Ruby reference files are loaded correctly by the skill
Test with a sample Ruby Temporal project to validate code examples
Review alignment with Python/TypeScript content structure

🤖 Generated with Claude Code

Created complete Ruby reference documentation covering: - ruby.md: Overview, quick start, key concepts, file organization - patterns.md: Signals, queries, updates, child workflows, saga, cancellation, etc. - determinism.md: Illegal call tracing, safe alternatives table - determinism-protection.md: TracePoint, durable fiber scheduler, customization - versioning.md: Patching API, type versioning, worker versioning - testing.md: WorkflowEnvironment, mocking, replay, activity testing - error-handling.md: ApplicationError, retries, timeouts, workflow failure - data-handling.md: Data converter, ActiveModel, hints, search attributes - observability.md: Logging, metrics, best practices - gotchas.md: Common mistakes, illegal call tracing issues - advanced-features.md: Schedules, async completion, worker tuning, Rails Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Self-review fixes: - patterns.md: Remove non-existent `workflow_run` annotation; entry point is `def execute` (no annotation needed, unlike Python's @workflow.run) - patterns.md: Remove conflicting manual query methods that duplicated workflow_query_attr_reader - error-handling.md: Remove `await` keyword (doesn't exist in Ruby) - gotchas.md: Replace TS-style CancellationScope with Ruby's Temporalio::Cancellation token-based detached cancellation - data-handling.md: Replace homemade ActiveModel mixin with official SDK pattern using ActiveSupport::Concern + ActiveModel::Serializers::JSON - data-handling.md: Fix list_workflows call signature (positional, not kw) - ruby.md, gotchas.md: Fix require paths to use 'temporalio/activity' instead of 'temporalio/activity/definition' Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- patterns.md: Fix external workflow signal to use class method ref (TargetWorkflow.data_ready instead of TargetWorkflow, :data_ready) - patterns.md: Add ? suffix to all_handlers_finished (Ruby boolean convention) - ruby.md: Add 'default' namespace to Client.connect calls Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- SKILL.md: Add "Temporal Ruby" trigger phrase to description - SKILL.md: Update Overview to list Ruby as supported language - SKILL.md: Add Ruby entry to Getting Started guide - core/determinism.md: Add Ruby SDK Protection Mechanism entry (Illegal Call Tracing via TracePoint + Durable Fiber Scheduler) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jb08 · 2026-03-27T21:49:51Z

Thank you for doing this! As a ruby sdk user, very interested in this MR. Any update on ETA?

hughevans · 2026-04-17T06:51:26Z

Looks good!

chadxz · 2026-05-07T16:33:17Z

Yes please

chris-olszewski

Overall looks good. Just a few suggestions

chris-olszewski · 2026-05-11T13:27:17Z

+- Subclass `Temporalio::Workflow::Definition`
+- Define `def execute(args)` as the entry point
+- Use `Temporalio::Workflow.execute_activity` to call activities
+- Use signals, queries, and updates via class-level DSL methods


Suggested change

- Use signals, queries, and updates via class-level DSL methods

- Define signals, queries, and updates via class-level DSL methods

chris-olszewski · 2026-05-11T13:54:00Z

+
+class ReplayTest < Minitest::Test
+  def test_replay_from_json
+    json = File.read('test/fixtures/my_workflow_history.json')


Would showing how to construct this JSON file be helpful?

chris-olszewski · 2026-05-11T14:11:27Z

+
+## Cancellation (Token-based)
+
+Ruby uses `Temporalio::Cancellation` tokens instead of asyncio cancellation.


asyncio seems to be in reference to Python

Suggested change

Ruby uses `Temporalio::Cancellation` tokens instead of asyncio cancellation.

Ruby uses `Temporalio::Cancellation` tokens.

chris-olszewski · 2026-05-11T14:14:53Z

@@ -0,0 +1,62 @@
+# Ruby SDK Observability


Might be worth documenting the OTEL interceptor we provide: https://github.com/temporalio/samples-ruby/blob/fc306b7c72157169ba22112758d58c6becd59eec/open_telemetry/worker.rb#L27

chris-olszewski · 2026-05-11T14:23:37Z

+The SDK provides a custom `Fiber::Scheduler` implementation that makes fiber primitives deterministic within the workflow.
+
+- `Kernel.sleep` and `Mutex` technically work under the durable scheduler but are **disabled by default** via illegal call tracing to prevent accidental misuse.
+- `Temporalio::Workflow.sleep` and `Temporalio::Workflow.wait_condition` are the correct alternatives.


We do offer Temporalio::Workflow::Mutex which is perfectly safe to use if a user truly wants a mutex and not a wait_condition

chris-olszewski · 2026-05-11T14:29:03Z

+
+## Common Issues
+
+### Third-party gems triggering NondeterminismError


Should the first fix be to attempt to move the call into an activity? We should only be suggesting these escape hatches after there has been verification that the call will not introduce non-determinism.

bdewater-thatch

Saw this mentioned on the Slack. Long time Ruby/Rails user, still a bit new to Temporal, so reviewing through that lens :)

bdewater-thatch · 2026-05-05T14:42:43Z

+
+```ruby
+# In Puma config (puma.rb)
+on_worker_boot do


This has been renamed in Puma 7.

Suggested change

on_worker_boot do

before_worker_boot do

bdewater-thatch · 2026-05-05T15:02:20Z

+
+Rails uses Zeitwerk for autoloading. Workflow and activity classes must be loadable by Zeitwerk or explicitly required.
+
+```ruby


Between the line above and this example it's not clear if the example code is required or not? "Loadable by Zeitwerk" seems to imply it should be autoloadable/reloadable in development without additional work, assuming the conventions are followed. Is that right?

In my experience both humans and and LLMs will default to using the example if it's not clear it is not required.

bdewater-thatch · 2026-05-05T15:18:42Z

+## Heartbeating
+
+### Forgetting to Heartbeat Long Activities
+
+```ruby
+# BAD - No heartbeat, can't detect stuck activities
+class ProcessLargeFile < Temporalio::Activity::Definition
+  def execute(path)
+    File.readlines(path).each_slice(1000) do |chunk|
+      process(chunk)  # Takes hours, no heartbeat
+    end
+  end
+end
+```
+
+```ruby
+# GOOD - Regular heartbeats with progress
+class ProcessLargeFile < Temporalio::Activity::Definition
+  def execute(path)
+    File.readlines(path).each_slice(1000).with_index do |chunk, i|
+      Temporalio::Activity::Context.current.heartbeat("Processing chunk #{i}")
+      process(chunk)
+    end
+  end
+end
+```


This example seems a lot like the one above.

Personally I'd like to see an example that allows me to compare Temporal activities with solutions like job-iteration or Active Job Continuation. Claude came up with the following:

class ProcessAllUsers < Temporalio::Activity::Definition def execute context = Temporalio::Activity::Context.current cursor = context.info.heartbeat_details.first # nil on first attempt # `start` argument below is inclusive User.find_each(start: cursor) do |user| context.cancellation.check! process(user) context.heartbeat(user.id.succ) # next id to start from end end end

bdewater-thatch · 2026-05-05T16:00:50Z

+# BAD - No heartbeat, can't detect stuck activities
+class ProcessLargeFile < Temporalio::Activity::Definition
+  def execute(path)
+    File.readlines(path).each_slice(1000) do |chunk|


Suggested change

File.readlines(path).each_slice(1000) do |chunk|

File.foreach(path).each_slice(1000) do |chunk|

Same for the other example below. See https://felipeelias.github.io/ruby/2017/01/02/fast-file-processing-ruby.html

donald-pinckney and others added 4 commits March 16, 2026 18:23

donald-pinckney mentioned this pull request Mar 16, 2026

[Memory] Add Ruby temporalio/claude-temporal-plugin#13

Draft

donald-pinckney marked this pull request as draft March 16, 2026 23:40

donald-pinckney changed the base branch from dev to main April 17, 2026 19:07

chris-olszewski approved these changes May 11, 2026

View reviewed changes

bdewater-thatch reviewed May 13, 2026

View reviewed changes

	- Use signals, queries, and updates via class-level DSL methods
	- Define signals, queries, and updates via class-level DSL methods


		## Cancellation (Token-based)

		Ruby uses `Temporalio::Cancellation` tokens instead of asyncio cancellation.


		## Common Issues

		### Third-party gems triggering NondeterminismError


		Rails uses Zeitwerk for autoloading. Workflow and activity classes must be loadable by Zeitwerk or explicitly required.

		```ruby

	File.readlines(path).each_slice(1000) do \|chunk\|
	File.foreach(path).each_slice(1000) do \|chunk\|

Conversation

donald-pinckney commented Mar 16, 2026

Summary

Details

Test plan

Uh oh!

jb08 commented Mar 27, 2026

Uh oh!

hughevans commented Apr 17, 2026

Uh oh!

chadxz commented May 7, 2026

Uh oh!

chris-olszewski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdewater-thatch left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bdewater-thatch left a comment •

edited

Loading