Skip to content

Commit 28d4935

Browse files
dario-piotrowiczpenalosaOxyjun
authored andcommitted
Add DO and Workflow remote resources local usage instructions (#24023)
--------- Co-authored-by: Somhairle MacLeòid <[email protected]> Co-authored-by: Jun Lee <[email protected]>
1 parent 3f4a9f8 commit 28d4935

File tree

1 file changed

+30
-15
lines changed
  • src/content/docs/workers/development-testing

1 file changed

+30
-15
lines changed

src/content/docs/workers/development-testing/index.mdx

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -240,10 +240,8 @@ To verify that the certificate exchange and validation process work as expected.
240240
"binding": "MY_CLIENT_CERT_FETCHER",
241241
"certificate_id": "<YOUR_UPLOADED_CERT_ID>",
242242
"experimental_remote": true
243-
244-
}
245-
]
246-
243+
}
244+
]
247245
}
248246

249247
```
@@ -256,10 +254,10 @@ To connect to a high-fidelity version of the Images API, and verify that all tra
256254
<WranglerConfig>
257255
```jsonc title="wrangler.jsonc"
258256
{
259-
"images": {
260-
"binding": "IMAGES" ,
257+
"images": {
258+
"binding": "IMAGES" ,
261259
"experimental_remote": true
262-
}
260+
}
263261
}
264262
```
265263

@@ -278,13 +276,13 @@ Workers for Platforms users can configure `experimental_remote: true` in dispatc
278276
<WranglerConfig>
279277
```jsonc title="wrangler.jsonc"
280278
{
281-
"dispatch_namespaces": [
282-
{
283-
"binding": "DISPATCH_NAMESPACE",
284-
"namespace": "testing",
285-
"experimental_remote":true
279+
"dispatch_namespaces": [
280+
{
281+
"binding": "DISPATCH_NAMESPACE",
282+
"namespace": "testing",
283+
"experimental_remote":true
286284
}
287-
]
285+
]
288286
}
289287
```
290288
</WranglerConfig>
@@ -297,11 +295,11 @@ Certain bindings are not supported for remote connections during local developme
297295

298296
If `experimental_remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare **will issue an error**. See [all supported and unsupported bindings for remote bindings](/workers/development-testing/bindings-per-env/).
299297

300-
- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally.
298+
- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally. However, using Durable Objects in combination with remote bindings is possible. Refer to [Using remote resources with Durable Objects and Workflows](#using-remote-resources-with-durable-objects-and-workflows) below.
301299

302300
- [**RPC on service bindings**](/workers/runtime-apis/bindings/service-bindings/rpc/): While you can make `fetch()` calls on remote service bindings, you cannot currently call RPC methods on remote service bindings.
303301

304-
- [**Workflows**](/workflows/): Enabling remote connections for Workflows may be supported in the future, but currently will only run locally.
302+
- [**Workflows**](/workflows/): Enabling remote connections for Workflows may be supported in the future, but currently will only run locally. However, using Workflows in combination with remote bindings is possible. Refer to [Using remote resources with Durable Objects and Workflows](#using-remote-resources-with-durable-objects-and-workflows) below.
305303

306304
- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments. They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration).
307305

@@ -314,12 +312,29 @@ If `experimental_remote: true` is specified in Wrangler configuration for any of
314312
- [**Analytics Engine**](/analytics/analytics-engine/): Local development sessions typically don't contribute data directly to production Analytics Engine.
315313

316314
- [**Hyperdrive**](/workers/wrangler/configuration/#hyperdrive): This is being actively worked on, but is currently unsupported.
315+
317316
- [**Rate Limiting**](/workers/runtime-apis/bindings/rate-limit/#configuration): Local development sessions typically should not share or affect rate limits of your deployed Workers. Rate limiting logic should be tested against local simulations.
318317

319318
:::note
320319
If you have use-cases for connecting to any of the remote resources above, please [open a feature request](https://github.com/cloudflare/workers-sdk/issues) in our [`workers-sdk` repository](https://github.com/cloudflare/workers-sdk).
321320
:::
322321

322+
#### Using remote resources with Durable Objects and Workflows
323+
324+
While Durable Object and Workflow bindings cannot currently be remote, you can still use them during local development and have them interact with remote resources.
325+
326+
There are two recommended patterns for this:
327+
328+
- **Local Durable Objects/Workflows with remote bindings:**
329+
330+
When you enable remote bindings in your [Wrangler configuration](/workers/wrangler/configuration), your locally running Durable Objects and Workflows can access remote resources. This allows such bindings, although run locally, to interact with remote resources during local development.
331+
332+
- **Accessing remote Durable Objects/Workflows via service bindings:**
333+
334+
To interact with remote Durable Object or Workflow instances, deploy a Worker that defines those. Then, in your local Worker, configure a remote [service binding](/workers/runtime-apis/bindings/service-bindings/) pointing to the deployed Worker.
335+
Your local Worker will be then able to interact with the remote deployed Worker, which in turn can communicate with the remote Durable Objects/Workflows. Using this method, you can create a communication channel via the remote service binding, effectively using the deployed Worker as a proxy interface to the remote bindings during local development.
336+
337+
323338
### Important Considerations
324339

325340
- **Data modification**: Operations (writes, deletes, updates) on bindings connected remotely will affect your actual data in the targeted Cloudflare resource (be it preview or production).

0 commit comments

Comments
 (0)