You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Durable Object ID is a 64-digit hexadecimal number used to identify a Durable Object instance. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface.
12
+
A Durable Object ID is a 64-digit hexadecimal number used to identify a Durable Object. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface.
13
13
14
-
The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a [`DurableObjectStub`](/durable-objects/api/stub) for submitting requests to a Durable Object instance. Note that creating an ID for a Durable Object instance does not create the Durable Object. The Durable Object is created lazily after creating a stub from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
14
+
The `DurableObjectId` interface refers to a new or existing Durable Object. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a [`DurableObjectStub`](/durable-objects/api/stub) for submitting requests to a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after creating a stub from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
15
15
16
16
:::note[Logging]
17
17
18
-
If you are experiencing an issue with a particular Durable Object instance, you may wish to log the `DurableObjectId` from your Worker and include it in your Cloudflare support request.
18
+
If you are experiencing an issue with a particular Durable Object, you may wish to log the `DurableObjectId` from your Worker and include it in your Cloudflare support request.
A Durable Object namespace is a set of Durable Object instances that are backed by the same Durable Object class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Object instances.
12
+
A Durable Object namespace is a set of Durable Objects that are backed by the same Durable Object class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.
13
13
14
-
The `DurableObjectNamespace` interface is used to obtain a reference to new or existing Durable Object instances. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface when referencing bindings declared in `wrangler.toml`.
14
+
The `DurableObjectNamespace` interface is used to obtain a reference to new or existing Durable Objects. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface when referencing bindings declared in `wrangler.toml`.
15
15
16
-
This interface defines several [methods](/durable-objects/api/namespace/#methods) that can be used to create an ID for a Durable Object instance. Note that creating an ID for a Durable Object instance does not create the Durable Object. The Durable Object is created lazily after calling [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to create a [`DurableObjectStub`](/durable-objects/api/stub) from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
16
+
This interface defines several [methods](/durable-objects/api/namespace/#methods) that can be used to create an ID for a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after calling [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to create a [`DurableObjectStub`](/durable-objects/api/stub) from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
// Every unique ID refers to an individual instance of the Durable Object class
32
32
constid=env.MY_DURABLE_OBJECT.idFromName("foo");
33
33
34
-
// A stub is a client Object used to invoke methods defined by the Durable Object instance
34
+
// A stub is a client Object used to invoke methods defined by the Durable Object
35
35
conststub=env.MY_DURABLE_OBJECT.get(id);
36
36
...
37
37
}
@@ -58,7 +58,7 @@ export default {
58
58
// Every unique ID refers to an individual instance of the Durable Object class
59
59
const id =env.MY_DURABLE_OBJECT.idFromName("foo");
60
60
61
-
// A stub is a client Object used to invoke methods defined by the Durable Object instance
61
+
// A stub is a client Object used to invoke methods defined by the Durable Object
62
62
const stub =env.MY_DURABLE_OBJECT.get(id);
63
63
...
64
64
}
@@ -71,7 +71,7 @@ export default {
71
71
72
72
### `idFromName`
73
73
74
-
`idFromName` creates a unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. Named Durable Object instances are the most common method of referring to Durable Object instances.
74
+
`idFromName` creates a unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. Named Durable Objects are the most common method of referring to Durable Objects.
- A required string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object instance.
83
+
- A required string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object.
84
84
85
85
#### Return values
86
86
87
87
- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class.
88
88
89
89
### `newUniqueId`
90
90
91
-
`newUniqueId` creates a randomly generated and unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. IDs created using `newUniqueId`, will need to be stored as a string in order to refer to the same Durable Object again in the future. For example, the ID can be stored in Workers KV, another Durable Object instance, or in a cookie in the user's browser.
91
+
`newUniqueId` creates a randomly generated and unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. IDs created using `newUniqueId`, will need to be stored as a string in order to refer to the same Durable Object again in the future. For example, the ID can be stored in Workers KV, another Durable Object, or in a cookie in the user's browser.
The first time you get a Durable Object stub based on an ID derived from a name, the system has to take into account the possibility that a Worker on the opposite side of the world could have coincidentally accessed the same named Durable Object at the same time. To guarantee that only one instance of the Durable Object is created, the system must check that the Durable Object has not 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. `newUniqueId` can skip this check.
101
101
102
-
After this first use, the location of the Durable Object instance will be cached around the world so that subsequent lookups are faster.
102
+
After this first use, the location of the Durable Object will be cached around the world so that subsequent lookups are faster.
103
103
104
104
:::
105
105
@@ -127,9 +127,9 @@ After this first use, the location of the Durable Object instance will be cached
127
127
128
128
### `get`
129
129
130
-
`get` obtains a [`DurableObjectStub`](/durable-objects/api/stub) from a [`DurableObjectId`](/durable-objects/api/id) which can be used to invoke methods on a Durable Object instance.
130
+
`get` obtains a [`DurableObjectStub`](/durable-objects/api/stub) from a [`DurableObjectId`](/durable-objects/api/id) which can be used to invoke methods on a Durable Object.
131
131
132
-
This method returns the stub immediately, often before a connection has been established to the Durable Object instance. This allows requests to be sent to the instance right away, without waiting for a network round trip.
132
+
This method returns the stub immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip.
`jurisdiction` creates a subnamespace from a namespace where all Durable Object instance IDs and references created from that subnamespace will be restricted to the specified [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction).
150
+
`jurisdiction` creates a subnamespace from a namespace where all Durable Object IDs and references created from that subnamespace will be restricted to the specified [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction).
Copy file name to clipboardExpand all lines: src/content/docs/durable-objects/api/stub.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,11 +9,11 @@ import { Render } from "~/components";
9
9
10
10
## Description
11
11
12
-
The `DurableObjectStub` interface is a client used to invoke methods on a remote Durable Object instance. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub.
12
+
The `DurableObjectStub` interface is a client used to invoke methods on a remote Durable Object. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub.
13
13
14
14
Durable Objects implement E-order semantics, a concept deriving from the [E distributed programming language](<https://en.wikipedia.org/wiki/E_(programming_language)>). When you make multiple calls to the same Durable Object, it is guaranteed that the calls will be delivered to the remote Durable Object in the order in which you made them. E-order semantics makes many distributed programming problems easier. E-order is implemented by the [Cap'n Proto](https://capnproto.org) distributed object-capability RPC protocol, which Cloudflare Workers uses for internal communications.
15
15
16
-
If an exception is thrown by a Durable Object stub all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object instance a Worker must recreate the stub. There are no ordering guarantees between different stubs.
16
+
If an exception is thrown by a Durable Object stub all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs.
- Writing a Worker which invokes methods on a Durable Object instance.
13
+
- Writing a Worker which invokes methods on a Durable Object.
14
14
- Deploying a Durable Object.
15
15
16
16
## Prerequisites
@@ -139,7 +139,7 @@ export default {
139
139
// Every unique ID refers to an individual instance of the Durable Object class
140
140
constid=env.MY_DURABLE_OBJECT.idFromName("foo");
141
141
142
-
// A stub is a client used to invoke methods on the Durable Object instance
142
+
// A stub is a client used to invoke methods on the Durable Object
143
143
conststub=env.MY_DURABLE_OBJECT.get(id);
144
144
145
145
// Methods on the Durable Object are invoked via the stub
@@ -159,7 +159,7 @@ export default {
159
159
// Every unique ID refers to an individual instance of the Durable Object class
160
160
const id =env.MY_DURABLE_OBJECT.idFromName("foo");
161
161
162
-
// A stub is a client used to invoke methods on the Durable Object instance
162
+
// A stub is a client used to invoke methods on the Durable Object
163
163
const stub =env.MY_DURABLE_OBJECT.get(id);
164
164
165
165
// Methods on the Durable Object are invoked via the stub
@@ -174,7 +174,7 @@ export default {
174
174
175
175
## 5. Configure Durable Object bindings
176
176
177
-
To allow a Worker to invoke methods on a Durable Object instance, the Worker must have a [Durable Object binding](/workers/runtime-apis/bindings/) in the project's [`wrangler.toml`](/workers/wrangler/configuration/#durable-objects) file. The binding is configured to use a particular Durable Object class.
177
+
To allow a Worker to invoke methods on a Durable Object, the Worker must have a [Durable Object binding](/workers/runtime-apis/bindings/) in the project's [`wrangler.toml`](/workers/wrangler/configuration/#durable-objects) file. The binding is configured to use a particular Durable Object class.
0 commit comments