Add extension on top of workflow binding by Caio-Nogueira · Pull Request #10919 · cloudflare/workers-sdk

Caio-Nogueira · 2025-10-08T09:31:01Z

Fixes WOR-926.

This PR migrates the workflow binding to use a wrapped binding that sits on top of the service binding. The goal is to avoid local dev errors due to engines not being disposed correctly.

Furthermore, this also mitigates the issue of Python Workflows not working correctly with default entrypoint classes. This happens because the runtime attempts to type translate the binding to a Python type - and fails because it doesn't really work properly when the JS object has RPC properties. Therefore, this is a backwards compatible way of fixing it.

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: the binding should work the same way for customers. All we did was change how its methods are handled internally
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: this is not a patch on wrangler or miniflare

changeset-bot · 2025-10-08T09:31:05Z

🦋 Changeset detected

Latest commit: 9380a3f

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-10-08T09:33:49Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@10919

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@10919

miniflare

npm i https://pkg.pr.new/miniflare@10919

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@10919

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@10919

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@10919

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@10919

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@10919

wrangler

npm i https://pkg.pr.new/wrangler@10919

commit: 9380a3f

jamesopstad · 2025-10-17T11:38:13Z

You'll need to update the Workflows tests for the Vite plugin here. These are currently failing for this PR.

It would also be good to understand why the changes in this PR change the outcome of the tests? Thanks.

Caio-Nogueira · 2025-10-20T10:41:36Z

It would also be good to understand why the changes in this PR change the outcome of the tests? Thanks.

I think that the architectural changes made here have consequences in the timing and execution model of workflows. They are still executed asynchronously (e.g.: some test workflows are still expecting to be returned on a running state back to the caller, when these workflows have step.sleep in them).

In other words, calling create directly to the binding via JSRPC would essentially evoke an immediate response to the caller, meaning that the workflow execution had only been initialized but the instance had not performed any work until that point in time. This may not hold true on the wrapped binding case, since besides initializing the instance, we're also constructing a new object that serves as the handle to that particular instance.

packages/vite-plugin-cloudflare/playground/external-workflows/__tests__/workflows.spec.ts

packages/vitest-pool-workers/src/worker/workflows.ts

packages/workflows-shared/src/binding.ts

packages/miniflare/src/workers/workflows/wrapped-binding.worker.ts

github-actions · 2025-10-21T15:03:35Z

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main caio/workflow-with-wrapped-binding might be a good starting point.

Notes:

your PR branch should be named v3-backport-10919
add the skip-v3-pr label to the current PR to stop this workflow from failing

…ine stubs

…ine stubs (#10919)

Caio-Nogueira requested review from a team as code owners October 8, 2025 09:31

workers-devprod added this to workers-sdk Oct 8, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Oct 8, 2025

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch from 06d541a to 9e575e4 Compare October 8, 2025 09:33

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch 2 times, most recently from 91e4a59 to 99af763 Compare October 9, 2025 11:16

Caio-Nogueira changed the title ~~Migrate from jsrpc to wrapped binding on the local workflow binding~~ Add extension on top of workflow binding Oct 9, 2025

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch 5 times, most recently from aeee441 to 06cad01 Compare October 9, 2025 14:21

Caio-Nogueira self-assigned this Oct 10, 2025

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch 7 times, most recently from f335e1d to f6fcbf7 Compare October 13, 2025 18:40

Caio-Nogueira requested a review from a team October 13, 2025 18:40

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch 3 times, most recently from 19bddc3 to de46599 Compare October 15, 2025 13:12

bruxodasilva approved these changes Oct 15, 2025

View reviewed changes

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch from de46599 to dbda86f Compare October 20, 2025 10:00

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch from dbda86f to 07e4e45 Compare October 20, 2025 10:24

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch 4 times, most recently from 537d54f to 7cff267 Compare October 20, 2025 15:59

jamesopstad approved these changes Oct 20, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Oct 20, 2025

Caio-Nogueira force-pushed the caio/workflow-with-wrapped-binding branch from 7cff267 to e22e2e2 Compare October 21, 2025 09:50