Access Durable Objects from a Worker

To access a Durable Object from a Worker, you must first create a Durable Object binding in your Worker project’s wrangler.toml file. The binding is configured to use a particular class and controls access to instances of that class.

Durable Object bindings allow for communication between a Worker and a Durable Object.

If you are using Wrangler environments, you must specify any Durable Object bindings you wish to use on a per-environment basis.

​​ 1. Create Durable Object IDs

A Durable Object ID is a 64-digit hexadecimal number used to identify the Durable Object you are sending the request to. Not all 64-digit hex numbers are valid IDs. The Durable Object ID is tied to a class.

To create a Durable Object ID, you can choose to:

• Generate IDs randomly.
• Derive IDs from names (these names are string data types).
• Parse previously-created IDs from strings.

All three methods will allow you to create Durable Object IDs.

​​ Generate IDs randomly

The following code gives you a new Durable Object ID. Add the following to your Worker code.

let id = OBJECT_NAMESPACE.newUniqueId();

The newUniqueId() method on a Durable Object namespace creates a new Durable Object ID randomly. newUniqueId() will never return the same ID twice. Thus, it is guaranteed that the Durable Object does not yet exist and has never existed at the time the method returns.

When generating an ID randomly, you need to store the ID somewhere to reach the same Durable Object again in the future. For example, you can store the ID in Workers KV, in an external database, or in a cookie in the user’s browser.

Unique IDs are unguessable. You can use unique IDs in URL-based access control.

To store the ID in external storage, use its toString() method to convert it into a hexadecimal string, and OBJECT_NAMESPACE.idFromString() to convert the string back into an ID later.

​​ Derive IDs from names

The following code allows you to use a name (which is a String) to extract the ID of your Durable Object.

let id = OBJECT_NAMESPACE.idFromName(name);

​​ Parameters

This method derives a unique Durable Object ID from the given name string. It will always return the same ID when given the same name as input.

​​ Parse previously-created IDs from strings

let id = OBJECT_NAMESPACE.idFromString(hexId);

​​ Parameters

This method parses an ID that was previously stringified. This is useful with IDs created using newUniqueId(), as these IDs need to be stored somewhere as a string.

This method will throw an exception if it is passed an ID that was not originally created by newUniqueId() or idFromName(). It will also throw an exception if the ID was originally created for a different Durable Object namespace.

​​ 2. Construct the stub using the ID

Construct the stub for the Durable Object using the ID. A stub is a client Durable Object used to send messages to the Durable Object.

let stub = env.EXAMPLE_CLASS.get(id);

​​ 3. Use fetch() handler method

The system calls the fetch() method of a Durable Object namespace when an HTTP request is sent to the Durable Object. These requests are not sent from the public Internet, but from other Workers using a Durable Object binding.

The fetch() method takes a Request as the parameter and returns a Response (or a Promise for a Response).

If the method fails with an uncaught exception, the exception will be thrown into the calling Worker that made the fetch() request.

let response = await stub.fetch(request);