Skip to content

Coinbase Ruby guide #304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 24, 2025
Merged

Coinbase Ruby guide #304

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d6d5175
Coinbase Ruby guide
cretz Jul 22, 2025
56e661b
PR suggestions
cretz Jul 24, 2025
c9cd0fe
Merge branch 'main' into coinbase-guide
cretz Jul 24, 2025
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
35 changes: 35 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#rub
- [Forking](#forking)
- [Ractors](#ractors)
- [Platform Support](#platform-support)
- [Migration from Coinbase Ruby SDK](#migration-from-coinbase-ruby-sdk)
- [Development](#development)
- [Build](#build)
- [Build Platform-specific Gem](#build-platform-specific-gem)
Expand Down Expand Up @@ -1249,6 +1250,40 @@ section for how to build a the repository.
The SDK works on Ruby 3.2+, but due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and
`async` gem) are only supported on Ruby versions 3.3 and newer.

### Migration from Coinbase Ruby SDK

The [Coinbase Ruby SDK](https://github.com/coinbase/temporal-ruby) predates this official Temporal SDK and has been a
popular approach to developing in Temporal with Ruby. While Temporal encourages users to use the official SDK to get new
features and support, this section covers differences from the Coinbase SDK to help those looking to migrate.

See [this Ruby sample](https://github.com/temporalio/samples-ruby/tree/main/coinbase_ruby) which demonstrates
interoperability between Coinbase Ruby and Temporal Ruby clients, workflows, and activities. Specifically, it discusses
how to disable API class loading on the Coinbase Ruby side if needing to use both dependencies in the same project,
since two sets of API classes cannot both be present.

Migration cannot be done on a live, running workflow. Overall, Coinbase Ruby workflow events are incompatible with
Copy link

@yuandrew yuandrew Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would our SDK be able to replay history from Coinbase's SDK? or are we just able to translate WF code from one SDK to another, as in our SDK can run Coinbase workflows and vise versa.

Copy link
Member Author

@cretz cretz Jul 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would our SDK be able to replay history from Coinbase's SDK?

No, Coinbase Ruby workflow events are incompatible with Temporal Ruby workflow events at runtime. Our SDK can start and interact with Coinbase workflows and vice-versa, yes.

Copy link
Member Author

@cretz cretz Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a bit of clarity here

Copy link

@yuandrew yuandrew Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it redundant to say "live" and "running"? Is there ever a running workflow that isn't "live"?

Copy link
Member Author

@cretz cretz Jul 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically yes, a workflow running on the server may never have reached worker code. Also there are "live" workflows that are not running (e.g. closed workflows that get queried). But in general, both adjectives are needed to clarify that you can't do the migration with live code.

Copy link

@yuandrew yuandrew Jul 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good, thanks

Temporal Ruby workflow events at runtime, so both SDK versions cannot have workers for the same task queue. A live
workflow migration cannot occur, an separate task queue would be needed. However, Coinbase Ruby clients, workflows, and
activities can be used with Temporal Ruby clients, workflows, and activities in either direction. Migrating from the
Coinbase Ruby SDK to the Temporal Ruby SDK would be similar to migrating from Temporal Go SDK to Temporal Java SDK. You
can interact across, but the workflow events are incompatible and therefore the task queues cannot be served by both at
the same time.

Here is an overview of the primary differences between the SDKs:

| Feature | Coinbase Ruby | Temporal Ruby |
| --- | --- | --- |
| Base module | `Temporal::` | `Temporalio::` |
| Client + start workflow | Global `Temporal.configure` + `Temporal.start_workflow` | `Temporalio::Client.connect` + `my_client.start_workflow` |
| Client implementation | Ruby gRPC | Rust gRPC |
| Activity definition | Extend `Temporal::Activity` + impl `execute` | Extend `Temporalio::Activity::Definition` + impl `execute` |
| Workflow definition | Extend `Temporal::Workflow` + impl `execute` | Extend `Temporalio::Workflow::Definition` + impl `execute` |
| Invoke activity from workflow | `MyActivity.execute!` or `workflow.execute_activity!(MyActivity)` | `Workflow.execute_activity(MyActivity)` |
| Handle signal/query/update in workflow | `workflow.on_signal`/`workflow.on_query`/update-unsupported | Decorate with `workflow_signal`/`workflow_query`/`workflow_update` |
| Run worker | `Temporal::Worker.new` + `start` | `Temporalio::Worker.new` + `run` |

This is just a high-level overview, there are many more differences on more specific Temporal components.
Copy link

@yuandrew yuandrew Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there already info on the more specific differences, or does that still need to be written

Copy link
Member Author

@cretz cretz Jul 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are thousands (...er...hundreds maybe heh) of differences from option names to method names to interceptor approaches, we don't want to write every difference. This is a small documentation section as a courtesy for a handful of non-Temporal-Ruby-SDK users. It'd be like documenting every difference between Go and Java SDKs just to help users do a Go-to-Java migration.


## Development

### Build
Expand Down
Loading