Access a Durable Object 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.

Durable Object namespace

A Durable Object namespace is a set of Durable Objects that can be addressed by name, backed by the same class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.

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.

Unique IDs perform best

When you construct a new unique ID, the system knows that the same ID will not be generated by another Worker running on the other side of the world at the same time. Therefore, you can instantiate the Durable Object nearby without waiting for any round-the-world synchronization. Whenever you have a convenient place to store the ID, it is recommended to use randomly-generated IDs for best performance.

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

• name string
  • The Object name, an arbitrary string from which the ID is derived.

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.

Name-derived IDs require global lookups at creation

The first time you access a Durable Object based on an ID derived from a name, the system does not know anything about the Durable Object. It is possible that a Worker on the opposite side of the world could have coincidentally decided to access the same Durable Object at the same time. To guarantee that only one instance of the Durable Object is created worldwide, the system must check whether the Durable Object has been created anywhere else. Due to the inherent limit of the speed of light, this round-the-world check can take up to a few hundred milliseconds. After this check, the Durable Object will be instantiated near where it was first requested.

After the Durable Object has been accessed the first time, location information will be cached around the world so that subsequent lookups can be faster.

Parse previously-created IDs from strings

let id = OBJECT_NAMESPACE.idFromString(hexId);

Parameters

• hexId string
  • An ID string constructed by calling the toString() method of an existing ID.

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);