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 1 commit
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
32 changes: 32 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ opinions. Please communicate with us on [Slack](https://t.mp/slack) in the `#rub
- [Lazy/Eager Loading](#lazyeager-loading)
- [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 @@ -1238,6 +1239,37 @@ 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 a live workflow migration cannot occur, an alternative task queue would be
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.

I think more information could be helpful here. What does a closed workflow migration look like? Why is an alternative task queue needed?

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.

We don't have a specific answer here on how they migrate a workflow from one set of code to another (whether that's for code versioning reasons or SDK change reasons (be it this one or switching languages)). I think that's more of a whole-workflow-versioning problem I would rather not delve into here and leave that to whole-workflow-versioning docs. I will see if there are whole-workflow-versioning docs I can link to (probably https://docs.temporal.io/production-deployment/worker-deployments/worker-versioning).

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, maybe worth removing "an alternative task queue needed" bit? Not sure what value that adds, unless we dive further into what that statement means

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.

I think knowing that you can just put new stuff on an alternative task queue is plenty valuable on its own. But I may be able to add a bit more to the sentence.

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 some more detail here

needed. However, Coinbase Ruby clients, workflows, and activities can be used with Temporal Ruby clients, workflows, and
activities in either direction.

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