From 10035950ffc66c01f3efe8c901aa2a02c5abb878 Mon Sep 17 00:00:00 2001 From: Joshua Howard Date: Tue, 8 Oct 2024 12:32:36 -0500 Subject: [PATCH 01/17] Add runtime API reference docs for Worker accessible interfaces --- .../docs/durable-objects/api/alarms.mdx | 106 +++++------ src/content/docs/durable-objects/api/id.mdx | 84 +++++++++ .../docs/durable-objects/api/index.mdx | 2 +- .../docs/durable-objects/api/namespace.mdx | 178 ++++++++++++++++++ src/content/docs/durable-objects/api/stub.mdx | 114 +++++++++++ 5 files changed, 422 insertions(+), 62 deletions(-) create mode 100644 src/content/docs/durable-objects/api/id.mdx create mode 100644 src/content/docs/durable-objects/api/namespace.mdx create mode 100644 src/content/docs/durable-objects/api/stub.mdx diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index fb16729633d8296..fa1ecf5aec54a0a 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -2,8 +2,7 @@ title: Alarms pcx_content_type: concept sidebar: - order: 1 - + order: 4 --- import { Type } from "~/components"; @@ -20,18 +19,16 @@ Durable Objects alarms allow you to schedule the Durable Object to be woken up a Notably: -* Each Durable Object instance is able to schedule a single alarm at a time by calling `setAlarm()`. -* Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws. -* Retries are performed using exponential backoff starting at a two second delay from the first failure with up to six retries allowed. +- Each Durable Object instance is able to schedule a single alarm at a time by calling `setAlarm()`. +- Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws. +- Retries are performed using exponential backoff starting at a two second delay from the first failure with up to six retries allowed. :::note[How are alarms different from Cron Triggers?] - Alarms are more fine grained than [Cron Triggers](/workers/configuration/cron-triggers/#cron-triggers). A Worker can have up to three Cron Triggers configured at once, but it can have an unlimited amount of Durable Objects, each of which can have an alarm set. Alarms are directly scheduled from within your Durable Object. Cron Triggers, on the other hand, are not programmatic. [Cron Triggers](/workers/configuration/cron-triggers/#cron-triggers) execute based on their schedules, which have to be configured through the Cloudflare dashboard or API. - ::: Alarms can be used to build distributed primitives, like queues or batching of work atop Durable Objects. Alarms also provide a mechanism to guarantee that operations within a Durable Object will complete without relying on incoming requests to keep the Durable Object alive. For a complete example, refer to [Use the Alarms API](/durable-objects/examples/alarms-api/). @@ -40,94 +37,81 @@ Alarms can be used to build distributed primitives, like queues or batching of w ### getAlarm +- `getAlarm()`: - -* `getAlarm()`: - - * If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. - - + - If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. ### setAlarm +- + setAlarm(scheduledTimeMs ) + + : - -* setAlarm(scheduledTimeMs ): - - * Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch. - - + - Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch. ### deleteAlarm +- `deleteAlarm()`: + - Unset the alarm if there is a currently set alarm. -* `deleteAlarm()`: - - * Unset the alarm if there is a currently set alarm. - - * Calling `deleteAlarm()` inside the `alarm()` handler may prevent retries on a best-effort basis, but is not guaranteed. - - + - Calling `deleteAlarm()` inside the `alarm()` handler may prevent retries on a best-effort basis, but is not guaranteed. ## Handler methods ### alarm +- `alarm()`: + - Called by the system when a scheduled alarm time is reached. -* `alarm()`: - - * Called by the system when a scheduled alarm time is reached. - - * The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception. - - * This method can be `async`. - + - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception. + - This method can be `async`. ## Example This example shows how to both set alarms with the `setAlarm(timestamp)` method and handle alarms with the `alarm()` handler within your Durable Object. -* The `alarm()` handler will be called once every time an alarm fires. -* If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine. -* Following a short delay, the `alarm()` handler will run from the beginning on the other machine. +- The `alarm()` handler will be called once every time an alarm fires. +- If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine. +- Following a short delay, the `alarm()` handler will run from the beginning on the other machine. ```js -import { DurableObject } from 'cloudflare:workers'; +import { DurableObject } from "cloudflare:workers"; export default { - async fetch(request, env) { - let id = env.ALARM_EXAMPLE.idFromName("foo"); - return await env.ALARM_EXAMPLE.get(id).fetch(request); - }, + async fetch(request, env) { + let id = env.ALARM_EXAMPLE.idFromName("foo"); + return await env.ALARM_EXAMPLE.get(id).fetch(request); + }, }; const SECONDS = 1000; export class AlarmExample extends DurableObject { - constructor(ctx, env) { - this.ctx = ctx; - this.storage = ctx.storage; - } - async fetch(request) { - // If there is no alarm currently set, set one for 10 seconds from now - let currentAlarm = await this.storage.getAlarm(); - if (currentAlarm == null) { - this.storage.setAlarm(Date.now() + 10 * SECONDS); - } - } - async alarm() { - // The alarm handler will be invoked whenever an alarm fires. - // You can use this to do work, read from the Storage API, make HTTP calls - // and set future alarms to run using this.storage.setAlarm() from within this handler. - } + constructor(ctx, env) { + this.ctx = ctx; + this.storage = ctx.storage; + } + async fetch(request) { + // If there is no alarm currently set, set one for 10 seconds from now + let currentAlarm = await this.storage.getAlarm(); + if (currentAlarm == null) { + this.storage.setAlarm(Date.now() + 10 * SECONDS); + } + } + async alarm() { + // The alarm handler will be invoked whenever an alarm fires. + // You can use this to do work, read from the Storage API, make HTTP calls + // and set future alarms to run using this.storage.setAlarm() from within this handler. + } } ``` ## Related resources -* Understand how to [use the Alarms API](/durable-objects/examples/alarms-api/) in an end-to-end example. -* Read the [Durable Objects alarms announcement blog post](https://blog.cloudflare.com/durable-objects-alarms/). -* Review the [Storage API](/durable-objects/api/storage-api/) documentation for Durable Objects. +- Understand how to [use the Alarms API](/durable-objects/examples/alarms-api/) in an end-to-end example. +- Read the [Durable Objects alarms announcement blog post](https://blog.cloudflare.com/durable-objects-alarms/). +- Review the [Storage API](/durable-objects/api/storage-api/) documentation for Durable Objects. diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx new file mode 100644 index 000000000000000..4be25aab5cbd46b --- /dev/null +++ b/src/content/docs/durable-objects/api/id.mdx @@ -0,0 +1,84 @@ +--- +title: Durable Object ID +pcx_content_type: concept +sidebar: + order: 2 +--- + +import { Tabs, TabItem } from "~/components"; + +## Description + +The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used to by [`DurableObjectNamespace::get`](./namespace.mdx) to obtain a stub for submitting requests to the Durable Object class. + +Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. + +:::note[`DurableObjectId`] + +If you are experiencing an issue with a particular Durable Object instance the `DurableObjectId` corresponding to this particular instance is very helpful for obtaining a resolution through Cloudflare support. It is advisable to log a `DurableObjectId` from a Worker and include it in support requests where applicable. + +::: + +## Methods + +### `toString` + +#### Description + +`toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, e.g. in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`. + +```js +// Create a new unique ID +const id = env.MY_DURABLE_OBJECT.newUniqueId(); +// Save the unique ID elsewhere, e.g. a session cookie via id.toString() +... +// Recreate the ID from the string +const id = env.MY_DURABLE_OBJECT.idFromString(session_id); +``` + +#### Parameters + +None. + +#### Return value + +A 64 digit hex string. + +### `equals` + +#### Description + +`equals` is used to compare equality between two instances of `DurableObjectId`. + +```js +const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); +const id2 = env.MY_DURABLE_OBJECT.newUniqueId(); +console.assert(!id1.equals(id2), "This should always be true"); +``` + +#### Parameters + +A required `DurableObjectId` to compare against. + +#### Return value + +A boolean. True if equal and false otherwise. + +## Properties + +### `name` + +#### Description + +`name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](../namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](../namespace/#newuniqueid). + +```js +const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); +const id2 = env.MY_DURABLE_OBJECT.idFromName("foo"); +console.assert(id1.name === undefined, "This should always be true"); +console.assert(id2.name === "foo", "This should always be true"); +``` + +## Related resources + +- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). diff --git a/src/content/docs/durable-objects/api/index.mdx b/src/content/docs/durable-objects/api/index.mdx index 83c3b69386459df..4eb2fd2d900a11c 100644 --- a/src/content/docs/durable-objects/api/index.mdx +++ b/src/content/docs/durable-objects/api/index.mdx @@ -1,5 +1,5 @@ --- -title: API +title: Runtime APIs pcx_content_type: navigation sidebar: order: 4 diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx new file mode 100644 index 000000000000000..1a616718f20acb4 --- /dev/null +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -0,0 +1,178 @@ +--- +title: Durable Object Namespace +pcx_content_type: concept +sidebar: + order: 1 +--- + +import { Tabs, TabItem } from "~/components"; + +## Description + +The `DurableObjectNamespace` interface is used to obtain a reference to a new or existing Durable Object instance. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface for reference bindings declared in `wrangler.toml`. + +There are several functions of this interface 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 invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. + + + +```js +import { DurableObject } from "cloudflare:workers"; + +// Durable Object +export class MyDurableObject extends DurableObject { + ... +} + +// Worker +export default { + async fetch(request, env) { + // Every unique ID refers to an individual instance of the Durable Object class + const id = env.MY_DURABLE_OBJECT.idFromName("foo"); + + // A stub is a client Object used to invoke methods on the Durable Object instance. + const stub = env.MY_DURABLE_OBJECT.get(id); + ... + } +} +``` + + + +```ts +import { DurableObject } from "cloudflare:workers"; + +export interface Env { + MY_DURABLE_OBJECT: DurableObjectNamespace; +} + +// Durable Object +export class MyDurableObject extends DurableObject { + ... +} + +// Worker +export default { + async fetch(request, env) { + // Every unique ID refers to an individual instance of the Durable Object class + const id = env.MY_DURABLE_OBJECT.idFromName("foo"); + + // A stub is a client used to invoke methods on the Durable Object instance. + const stub = env.MY_DURABLE_OBJECT.get(id); + ... + } +} satisfies ExportedHandler; +``` + + + +## Methods + +### `idFromName` + +#### Description + +`idFromName` creates a [`DurableObjectId`](../id) which refers to an individual instance of the Durable Object class from a particular name. + +```js +const fooId = env.MY_DURABLE_OBJECT.idFromName("foo"); +const barId = env.MY_DURABLE_OBJECT.idFromName("bar"); +``` + +#### Parameters + +The string to be used to generate a [`DurableObjectId`](../id) corresponding to the name of a Durable Object instance. + +#### Return value + +A [`DurableObjectId`](../id) refering to an instance of a Durable Object class. + +### `newUniqueId` + +#### Description + +creates a `DurableObjectId` which refers to an individual instance of the +Durable Object class. + +```js +const id = env.MY_DURABLE_OBJECT.newUniqueId(); +const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); +``` + +:::note[`newUniqueId`] + +IDs created by `newUniqueId` will result in lower latencies when getting a [`DurableObjectStub`](../stub) relative to [`idFromName`](../namespace/#idFromName). + +::: + +#### Parameters + +An optional object with the key `jurisdiction` and value of a [jurisdiction](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. + +#### Return value + +A [`DurableObjectId`](../id) refering to an instance of the Durable Object class. + +### `idFromString` + +#### Description + +`idFromString` creates a [`DurableObjectId`](../id) based on a previously generated ID which has been converted to a string. This method ensures the validity of the ID, e.g. that it is 64 hex digits. + +```js +// Create a new unique ID +const id = env.MY_DURABLE_OBJECT.newUniqueId(); +// Save the unique ID elsewhere, e.g. a session cookie via id.toString() +... +// Recreate the ID from the string +const id = env.MY_DURABLE_OBJECT.idFromString(session_id); +``` + +#### Parameters + +The string corresponding to a [`DurableObjectId`](../id) previously generated either by `newUniqueId` or `idFromName`. + +#### Return value + +A [`DurableObjectId`](../id) refering to an instance of a Durable Object class. + +### `get` + +#### Description + +`get` obtains a [`DurableObjectStub`](../stub) from a [`DurableObjectId`](../id) which can be used to invoke methods on a Durable Object instance. + +```js +const id = env.MY_DURABLE_OBJECT.newUniqueId(); +const stub = env.MY_DURABLE_OBJECT.get(id); +``` + +#### Parameters + +A required [`DurableObjectId`](../id) and an optional object with the key `locationHint` and value of a [locationHint](../../reference/data-location/#provide-a-location-hint) string. + +#### Return value + +A [`DurableObjectStub`](../stub) refering to an instance of a Durable Object class. + +### `jurisdiction` + +#### Description + +`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](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction). + +```js +const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("foo"); +const euId = subnamespace.idFromName("foo"); +``` + +#### Parameters + +A required [jurisdiction](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. + +#### Return value + +A `DurableObjectNamespace` scoped to a particular geographic jurisdiction. + +## Related resources + +- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). diff --git a/src/content/docs/durable-objects/api/stub.mdx b/src/content/docs/durable-objects/api/stub.mdx new file mode 100644 index 000000000000000..62168598b874dad --- /dev/null +++ b/src/content/docs/durable-objects/api/stub.mdx @@ -0,0 +1,114 @@ +--- +title: Durable Object Stub +pcx_content_type: concept +sidebar: + order: 3 +--- + +import { Tabs, TabItem } from "~/components"; + +## Description + +The `DurableObjectStub` interface is used to obtain a reference a Durable Object instance and invoke methods on that instance. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub. + + + +```js +import { DurableObject } from "cloudflare:workers"; + +// Durable Object +export class MyDurableObject extends DurableObject { + constructor(ctx, env) { + super(ctx, env); + } + + sayHello() { + return "Hello, World!"; + } +} + +// Worker +export default { + async fetch(request, env) { + // Every unique ID refers to an individual instance of the Durable Object class + const id = env.MY_DURABLE_OBJECT.idFromName("foo"); + + // A stub is a client used to invoke methods on the Durable Object instance + const stub = env.MY_DURABLE_OBJECT.get(id); + + // Methods on the Durable Object are invoked via the stub + const rpcResponse = stub.sayHello(); + + return new Response(rpcResponse); + }, +}; +``` + + + +```ts +import { DurableObject } from "cloudflare:workers"; + +export interface Env { + MY_DURABLE_OBJECT: DurableObjectNamespace; +} + +// Durable Object +export class MyDurableObject extends DurableObject { + constructor(ctx: DurableObjectState, env: Env) { + super(ctx, env); + } + + sayHello(): String { + return "Hello, World!"; + } +} + +// Worker +export default { + async fetch(request, env) { + // Every unique ID refers to an individual instance of the Durable Object class + const id = env.MY_DURABLE_OBJECT.idFromName("foo"); + + // A stub is a client used to invoke methods on the Durable Object instance + const stub = env.MY_DURABLE_OBJECT.get(id); + + // Methods on the Durable Object are invoked via the stub + const rpcResponse = stub.sayHello(); + + return new Response(rpcResponse); + }, +} satisfies ExportedHandler; +``` + + + +## Properties + +### `id` + +#### Description + +`id` is a property of the `DurableObjectStub` corresponding to the [`DurableObjectId`](../id) used to create the stub. + +```js +const id = env.MY_DURABLE_OBJECT.newUniqueId(); +const stub = env.MY_DURABLE_OBJECT.get(id); +console.assert(id.equals(stub.id), "This should always be true"); +``` + +### `name` + +#### Description + +`name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](../id) via [`DurableObjectNamespace::idFromName`](../namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](../id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](../namespace/#newuniqueid). + +```js +const id = env.MY_DURABLE_OBJECT.idFromName("foo"); +const stub = env.MY_DURABLE_OBJECT.get(id); +console.assert(stub.name === "foo", "This should always be true"); +``` + +## Related resources + +- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). From 8cfdcb5807997b34b81d9c655fec47ca3983f28f Mon Sep 17 00:00:00 2001 From: Joshua Howard Date: Tue, 8 Oct 2024 13:16:19 -0500 Subject: [PATCH 02/17] Update data location docs to account for docs for Worker accessible interfaces --- .../reference/data-location.mdx | 115 ++++++------------ 1 file changed, 40 insertions(+), 75 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 7feb6c3702196b4..c7721b9e2252985 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -3,85 +3,51 @@ title: Data location pcx_content_type: concept sidebar: order: 8 - --- -You can restrict a Durable Object to a jurisdiction, or provide a location hint. - ## Restrict Durable Objects to a jurisdiction -Durable Objects can be created so that they only run and store data within a specific jurisdiction to comply with local regulations such as the [GDPR](https://gdpr-info.eu/) or [FedRAMP](https://blog.cloudflare.com/cloudflare-achieves-fedramp-authorization/). - -:::note - -Jurisdictions are available to all Durable Objects users. -::: - -To use a jurisdiction, first create a jurisidictional subnamespace in your Worker's code: - -```js -let subnamespace = OBJECT_NAMESPACE.jurisdiction('eu'); -``` - -A jurisdictional subnamespace works like a normal Durable Object namespace (`OBJECT_NAMESPACE` above), except that IDs created within them permanently encode the jurisdiction that was used to create the subnamespace. Additionally, the `idFromString()` and `get()` methods will throw an exception if the IDs passed into them are not within the subnamespace's jurisdiction. Once you have a subnamespace, you can use all of the namespace methods documented above. - -To create a new Durable Object ID that will only run and persist data within the jurisdiction: - -```js -let id = subnamespace.newUniqueId(); -``` - -To derive a unique Object ID from the given name string that will only run and persist data within the jurisdiction: - -```js -let id = subnamespace.idFromName(name); -``` - -:::note[IDs derived from the same name but different jurisdictions will differ] +Jurisdictions are used to create Durable Object instances that only run and store data within a region to comply with local regulations such as the [GDPR](https://gdpr-info.eu/) or [FedRAMP](https://blog.cloudflare.com/cloudflare-achieves-fedramp-authorization/). +Workers may still access Durable Objects constrained to a jurisdiction from anywhere in the world. The jurisdiction constraint only controls where the Durable Object itself runs and persists data. Consider using [Regional Services](/data-localization/regional-services/) to control the regions from which Cloudflare responds to requests. -Because the jurisdiction is encoded permanently in the Durable Object ID, it is possible to have the same name represent different Durable Objects in different jurisdictions. For example: `OBJECT_NAMESPACE.idFromName('my-name')` and `OBJECT_NAMESPACE.jurisdiction('eu').idFromName('my-name')` represent different Durable Objects. They will have their own transient (in-memory) and persistent state, and will likely run in different geographical regions. - -This may be counterintuitive at first, but it would be impossible to enforce two different non-overlapping jurisdictions for a single name. The key insight to remember is that Durable Object namespaces operate on IDs, not names, and the jurisdiction is a permanent part of the ID. +:::note[logging] +A [`DurableObjectId`](../../api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes. ::: -To parse a previously-created ID from a string: +Durable Object instances can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](../../api/namespace/) restricted to a jurisdiction or by creating an individual [`DurableObjectId`](../../api/id) restricted to a jurisdiction: ```js -let id = subnamespace.idFromString(id); +const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); +const euId = euSubnamespace.newUniqueId(); +// or +const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); ``` -To obtain an Object: +Methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. To achieve this, a [`DurableObjectId`](../../api/id) encodes its jurisdiction. As a consequence, it is possible to have the same name represent different IDs in different jurisdictions. ```js -let durableObjectStub = subnamespace.get(id) +const euId1 = env.MY_DURABLE_OBJECT.idFromName("my-name"); +const euId2 = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("my-name"); +console.assert(!euId1.equal(euId2), "This should always be true"); ``` -While you cannot use an ID from a different jurisdiction in a subnamespace's `idFromString()` or `get()` methods, you can use any valid ID in the top-level namespace's methods. Object IDs created with a jurisdiction will still only run and persist data within the jurisdiction. +While methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction, these methods will not throw an exception if the [`DurableObjectNamespace`](../../api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](../../api/id) can be used in the top-level namespace's methods. ```js -let id = subnamespace.idFromName(name); - -// This is valid. -OBJECT_NAMESPACE.idFromString(id.toString()) - -// And so is this. -OBJECT_NAMESPACE.get(id) +const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); +const euId = euSubnamespace.idFromName(name); +const stub = env.MY_DURABLE_OBJECT.get(euId); ``` -Your Workers may still access Durable Objects constrained to a jurisdiction from anywhere in the world. The jurisdiction constraint only controls where the Durable Object itself runs and persists data. Consider using [Regional Services](/data-localization/regional-services/) to control the regions from which Cloudflare responds to requests. - -The currently supported jurisdictions are `eu` (the European Union) and `fedramp` (FedRAMP). +### Supported locations -:::note[ID logging] - - -Durable Object IDs will be logged outside of the specified jurisdiction for billing and debugging purposes. - - -::: +| Parameter | Location | +| --------- | ---------------------------- | +| eu | The European Union | +| fedramp | The United States of America | ## Provide a location hint @@ -91,10 +57,8 @@ Durable Objects do not currently change locations after they are created11 Dynamic relocation of existing Durable Objects is planned for the future. +### Supported locations + +| Parameter | Location | +| --------- | --------------------- | +| wnam | Western North America | +| enam | Eastern North America | +| sam | South America | +| weur | Western Europe | +| eeur | Eastern Europe | +| apac | Asia-Pacific | +| oc | Oceania | +| afr | Africa | +| me | Middle East | + +1 Dynamic relocation of existing Durable Objects is planned for the +future. From 0c41e9bc884e811288ce9e22c47ed71d70862d4d Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 09:12:46 +0100 Subject: [PATCH 03/17] Update src/content/docs/durable-objects/api/namespace.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/api/namespace.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 1a616718f20acb4..94a1460c59f6489 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -116,7 +116,7 @@ A [`DurableObjectId`](../id) refering to an instance of the Durable Object class #### Description -`idFromString` creates a [`DurableObjectId`](../id) based on a previously generated ID which has been converted to a string. This method ensures the validity of the ID, e.g. that it is 64 hex digits. +`idFromString` creates a [`DurableObjectId`](../id) from a previously generated ID that has been converted to a string. This method ensures the ID is valid, for example, it checks that the ID consists of 64 hex digits. ```js // Create a new unique ID From b92f7c8e6d73d6925ac07b3f16f079d934062ada Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 09:12:58 +0100 Subject: [PATCH 04/17] Update src/content/docs/durable-objects/api/id.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/api/id.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 4be25aab5cbd46b..f063bbe865940f0 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -25,7 +25,7 @@ If you are experiencing an issue with a particular Durable Object instance the ` #### Description -`toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, e.g. in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`. +`toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, for example, in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`. ```js // Create a new unique ID From f9296209ce7da83705402275e536c59aabbb5a92 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 10:02:24 +0100 Subject: [PATCH 05/17] Jun/PCX edits part 1 --- src/content/docs/durable-objects/api/alarms.mdx | 9 +++------ src/content/docs/durable-objects/api/id.mdx | 4 ++-- .../docs/durable-objects/api/namespace.mdx | 15 +++++++-------- .../docs/durable-objects/api/storage-api.mdx | 4 ++-- src/content/docs/durable-objects/api/webgpu.mdx | 2 +- .../docs/durable-objects/api/websockets.mdx | 2 +- .../docs/durable-objects/api/workers-rs.mdx | 2 +- .../durable-objects/reference/data-location.mdx | 6 +++--- 8 files changed, 20 insertions(+), 24 deletions(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index fa1ecf5aec54a0a..1f68b7ef1270690 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -2,7 +2,7 @@ title: Alarms pcx_content_type: concept sidebar: - order: 4 + order: 6 --- import { Type } from "~/components"; @@ -37,16 +37,13 @@ Alarms can be used to build distributed primitives, like queues or batching of w ### getAlarm -- `getAlarm()`: +- getAlarm(): - If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. ### setAlarm -- - setAlarm(scheduledTimeMs ) - - : +- setAlarm(scheduledTimeMs ): - Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch. diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index f063bbe865940f0..1d2e7fd4210f0d1 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -9,13 +9,13 @@ import { Tabs, TabItem } from "~/components"; ## Description -The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used to by [`DurableObjectNamespace::get`](./namespace.mdx) to obtain a stub for submitting requests to the Durable Object class. +The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used by [`DurableObjectNamespace::get`](./namespace.mdx) to obtain a stub for submitting requests to the Durable Object class. Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. :::note[`DurableObjectId`] -If you are experiencing an issue with a particular Durable Object instance the `DurableObjectId` corresponding to this particular instance is very helpful for obtaining a resolution through Cloudflare support. It is advisable to log a `DurableObjectId` from a Worker and include it in support requests where applicable. +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. ::: diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 94a1460c59f6489..65e71b55bca79b9 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -9,9 +9,9 @@ import { Tabs, TabItem } from "~/components"; ## Description -The `DurableObjectNamespace` interface is used to obtain a reference to a new or existing Durable Object instance. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface for reference bindings declared in `wrangler.toml`. +The `DurableObjectNamespace` interface is used to obtain a reference to a new or existing Durable Object instance. 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`. -There are several functions of this interface 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 invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. +This interface defines several [methods](../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 invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. @@ -84,14 +84,13 @@ The string to be used to generate a [`DurableObjectId`](../id) corresponding to #### Return value -A [`DurableObjectId`](../id) refering to an instance of a Durable Object class. +A [`DurableObjectId`](../id) referring to an instance of a Durable Object class. ### `newUniqueId` #### Description -creates a `DurableObjectId` which refers to an individual instance of the -Durable Object class. +`newUniqueId` creates a `DurableObjectId` which refers to an individual instance of the Durable Object class. ```js const id = env.MY_DURABLE_OBJECT.newUniqueId(); @@ -110,7 +109,7 @@ An optional object with the key `jurisdiction` and value of a [jurisdiction](../ #### Return value -A [`DurableObjectId`](../id) refering to an instance of the Durable Object class. +A [`DurableObjectId`](../id) referring to an instance of the Durable Object class. ### `idFromString` @@ -133,7 +132,7 @@ The string corresponding to a [`DurableObjectId`](../id) previously generated ei #### Return value -A [`DurableObjectId`](../id) refering to an instance of a Durable Object class. +A [`DurableObjectId`](../id) referring to an instance of a Durable Object class. ### `get` @@ -152,7 +151,7 @@ A required [`DurableObjectId`](../id) and an optional object with the key `locat #### Return value -A [`DurableObjectStub`](../stub) refering to an instance of a Durable Object class. +A [`DurableObjectStub`](../stub) referring to an instance of a Durable Object class. ### `jurisdiction` diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index e12eb9e89105bad..219db0d4deb7312 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -2,7 +2,7 @@ title: Storage API pcx_content_type: concept sidebar: - order: 2 + order: 4 --- @@ -100,7 +100,7 @@ Each method is implicitly wrapped inside a transaction, such that its results ar * deleteAll(options ): - * Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database. + * Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database. * For Durable Objects with a key-value storage backend, an in-progress `deleteAll()` operation can fail, which may leave a subset of data undeleted. Durable Objects with a SQLite storage backend do not have a partial `deleteAll()` issue because `deleteAll()` operations are atomic (all or nothing). * `deleteAll()` does not proactively delete [Alarms](/durable-objects/api/alarms/). Use [`deleteAlarm()`](/durable-objects/api/alarms/#deletealarm) to delete an alarm. diff --git a/src/content/docs/durable-objects/api/webgpu.mdx b/src/content/docs/durable-objects/api/webgpu.mdx index 326f69729fbf51e..008cf2f2a389737 100644 --- a/src/content/docs/durable-objects/api/webgpu.mdx +++ b/src/content/docs/durable-objects/api/webgpu.mdx @@ -2,7 +2,7 @@ pcx_content_type: configuration title: WebGPU sidebar: - order: 4 + order: 7 --- :::caution diff --git a/src/content/docs/durable-objects/api/websockets.mdx b/src/content/docs/durable-objects/api/websockets.mdx index d61920589345d84..cb9c2920f95ffac 100644 --- a/src/content/docs/durable-objects/api/websockets.mdx +++ b/src/content/docs/durable-objects/api/websockets.mdx @@ -2,7 +2,7 @@ title: WebSockets pcx_content_type: concept sidebar: - order: 3 + order: 5 --- diff --git a/src/content/docs/durable-objects/api/workers-rs.mdx b/src/content/docs/durable-objects/api/workers-rs.mdx index aa6ca1abed327c0..59416eac283e978 100644 --- a/src/content/docs/durable-objects/api/workers-rs.mdx +++ b/src/content/docs/durable-objects/api/workers-rs.mdx @@ -3,6 +3,6 @@ pcx_content_type: navigation title: Rust API external_link: https://github.com/cloudflare/workers-rs?tab=readme-ov-file#durable-objects sidebar: - order: 5 + order: 10 --- diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index c7721b9e2252985..f048a8c29e97284 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -11,13 +11,13 @@ Jurisdictions are used to create Durable Object instances that only run and stor Workers may still access Durable Objects constrained to a jurisdiction from anywhere in the world. The jurisdiction constraint only controls where the Durable Object itself runs and persists data. Consider using [Regional Services](/data-localization/regional-services/) to control the regions from which Cloudflare responds to requests. -:::note[logging] +:::note[Logging] A [`DurableObjectId`](../../api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes. ::: -Durable Object instances can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](../../api/namespace/) restricted to a jurisdiction or by creating an individual [`DurableObjectId`](../../api/id) restricted to a jurisdiction: +Durable Object instances can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](../../api/namespace/) restricted to a jurisdiction, or by creating an individual [`DurableObjectId`](../../api/id) restricted to a jurisdiction: ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); @@ -34,7 +34,7 @@ const euId2 = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("my-name"); console.assert(!euId1.equal(euId2), "This should always be true"); ``` -While methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction, these methods will not throw an exception if the [`DurableObjectNamespace`](../../api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](../../api/id) can be used in the top-level namespace's methods. +Methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. However, these methods will not throw an exception if the [`DurableObjectNamespace`](../../api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](../../api/id) can be used in the top-level namespace's methods. ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); From 279071dd7b8ffefa6e72b90d0ad1a0579503f2b7 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 11:37:42 +0100 Subject: [PATCH 06/17] Replacing relative paths to absolute paths. --- src/content/docs/durable-objects/api/id.mdx | 6 ++-- .../docs/durable-objects/api/namespace.mdx | 30 +++++++++---------- src/content/docs/durable-objects/api/stub.mdx | 4 +-- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 1d2e7fd4210f0d1..26c5900e6aabc9a 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -9,9 +9,9 @@ import { Tabs, TabItem } from "~/components"; ## Description -The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used by [`DurableObjectNamespace::get`](./namespace.mdx) to obtain a stub for submitting requests to the Durable Object class. +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 stub for submitting requests to the Durable Object class. -Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. +Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when 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 unless their methods can be directly invoked. :::note[`DurableObjectId`] @@ -70,7 +70,7 @@ A boolean. True if equal and false otherwise. #### Description -`name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](../namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](../namespace/#newuniqueid). +`name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid). ```js const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 65e71b55bca79b9..cc0ec291dbddd45 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -11,7 +11,7 @@ import { Tabs, TabItem } from "~/components"; The `DurableObjectNamespace` interface is used to obtain a reference to a new or existing Durable Object instance. 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`. -This interface defines several [methods](../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 invoke the constructor of the Durable Object. This is done lazily when calling [`DurableObjectNamespace::get`](../namespace/#get) to create a [`DurableObjectStub`](../stub) from a `DurableObjectId`. This ensures that objects are not constructed unless their methods can be directly invoked. +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 invoke the constructor of the Durable Object. This is done lazily when 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 unless their methods can be directly invoked. @@ -71,7 +71,7 @@ export default { #### Description -`idFromName` creates a [`DurableObjectId`](../id) which refers to an individual instance of the Durable Object class from a particular name. +`idFromName` creates a [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class from a particular name. ```js const fooId = env.MY_DURABLE_OBJECT.idFromName("foo"); @@ -80,11 +80,11 @@ const barId = env.MY_DURABLE_OBJECT.idFromName("bar"); #### Parameters -The string to be used to generate a [`DurableObjectId`](../id) corresponding to the name of a Durable Object instance. +The string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object instance. #### Return value -A [`DurableObjectId`](../id) referring to an instance of a Durable Object class. +A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. ### `newUniqueId` @@ -99,23 +99,23 @@ const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); :::note[`newUniqueId`] -IDs created by `newUniqueId` will result in lower latencies when getting a [`DurableObjectStub`](../stub) relative to [`idFromName`](../namespace/#idFromName). +IDs created by `newUniqueId` will result in lower latencies when getting a [`DurableObjectStub`](/durable-objects/api/stub) relative to [`idFromName`](/durable-objects/api/namespace/#idfromname). ::: #### Parameters -An optional object with the key `jurisdiction` and value of a [jurisdiction](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +An optional object with the key `jurisdiction` and value of a [jurisdiction](durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. #### Return value -A [`DurableObjectId`](../id) referring to an instance of the Durable Object class. +A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of the Durable Object class. ### `idFromString` #### Description -`idFromString` creates a [`DurableObjectId`](../id) from a previously generated ID that has been converted to a string. This method ensures the ID is valid, for example, it checks that the ID consists of 64 hex digits. +`idFromString` creates a [`DurableObjectId`](/durable-objects/api/id) from a previously generated ID that has been converted to a string. This method ensures the ID is valid, for example, it checks that the ID consists of 64 hex digits. ```js // Create a new unique ID @@ -128,17 +128,17 @@ const id = env.MY_DURABLE_OBJECT.idFromString(session_id); #### Parameters -The string corresponding to a [`DurableObjectId`](../id) previously generated either by `newUniqueId` or `idFromName`. +The string corresponding to a [`DurableObjectId`](/durable-objects/api/id) previously generated either by `newUniqueId` or `idFromName`. #### Return value -A [`DurableObjectId`](../id) referring to an instance of a Durable Object class. +A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. ### `get` #### Description -`get` obtains a [`DurableObjectStub`](../stub) from a [`DurableObjectId`](../id) which can be used to invoke methods on a Durable Object instance. +`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. ```js const id = env.MY_DURABLE_OBJECT.newUniqueId(); @@ -147,17 +147,17 @@ const stub = env.MY_DURABLE_OBJECT.get(id); #### Parameters -A required [`DurableObjectId`](../id) and an optional object with the key `locationHint` and value of a [locationHint](../../reference/data-location/#provide-a-location-hint) string. +A required [`DurableObjectId`](/durable-objects/api/id) and an optional object with the key `locationHint` and value of a [locationHint](durable-objects/reference/data-location/#provide-a-location-hint) string. #### Return value -A [`DurableObjectStub`](../stub) referring to an instance of a Durable Object class. +A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class. ### `jurisdiction` #### Description -`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](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction). +`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). ```js const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("foo"); @@ -166,7 +166,7 @@ const euId = subnamespace.idFromName("foo"); #### Parameters -A required [jurisdiction](../../reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +A required [jurisdiction](durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. #### Return value diff --git a/src/content/docs/durable-objects/api/stub.mdx b/src/content/docs/durable-objects/api/stub.mdx index 62168598b874dad..4f8452190975a38 100644 --- a/src/content/docs/durable-objects/api/stub.mdx +++ b/src/content/docs/durable-objects/api/stub.mdx @@ -89,7 +89,7 @@ export default { #### Description -`id` is a property of the `DurableObjectStub` corresponding to the [`DurableObjectId`](../id) used to create the stub. +`id` is a property of the `DurableObjectStub` corresponding to the [`DurableObjectId`](/durable-objects/api/id) used to create the stub. ```js const id = env.MY_DURABLE_OBJECT.newUniqueId(); @@ -101,7 +101,7 @@ console.assert(id.equals(stub.id), "This should always be true"); #### Description -`name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](../id) via [`DurableObjectNamespace::idFromName`](../namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](../id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](../namespace/#newuniqueid). +`name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](/durable-objects/api/id) via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](/durable-objects/api/id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid). ```js const id = env.MY_DURABLE_OBJECT.idFromName("foo"); From ad4b2be49c85b0391e4d4f779e490fece64274c8 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 11:58:12 +0100 Subject: [PATCH 07/17] Fixing more invalid relative paths. --- src/content/docs/durable-objects/api/namespace.mdx | 8 ++++---- .../docs/durable-objects/reference/data-location.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index cc0ec291dbddd45..4c00d87a01f60e7 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -105,7 +105,7 @@ IDs created by `newUniqueId` will result in lower latencies when getting a [`Dur #### Parameters -An optional object with the key `jurisdiction` and value of a [jurisdiction](durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +An optional object with the key `jurisdiction` and value of a [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. #### Return value @@ -147,7 +147,7 @@ const stub = env.MY_DURABLE_OBJECT.get(id); #### Parameters -A required [`DurableObjectId`](/durable-objects/api/id) and an optional object with the key `locationHint` and value of a [locationHint](durable-objects/reference/data-location/#provide-a-location-hint) string. +A required [`DurableObjectId`](/durable-objects/api/id) and an optional object with the key `locationHint` and value of a [locationHint](/durable-objects/reference/data-location/#provide-a-location-hint) string. #### Return value @@ -157,7 +157,7 @@ A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a #### Description -`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). +`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). ```js const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("foo"); @@ -166,7 +166,7 @@ const euId = subnamespace.idFromName("foo"); #### Parameters -A required [jurisdiction](durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +A required [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. #### Return value diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index f048a8c29e97284..df4a033e370fd9b 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -13,11 +13,11 @@ Workers may still access Durable Objects constrained to a jurisdiction from anyw :::note[Logging] -A [`DurableObjectId`](../../api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes. +A [`DurableObjectId`](/durable-objects/api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes. ::: -Durable Object instances can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](../../api/namespace/) restricted to a jurisdiction, or by creating an individual [`DurableObjectId`](../../api/id) restricted to a jurisdiction: +Durable Object instances can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction, or by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction: ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); @@ -26,7 +26,7 @@ const euId = euSubnamespace.newUniqueId(); const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); ``` -Methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. To achieve this, a [`DurableObjectId`](../../api/id) encodes its jurisdiction. As a consequence, it is possible to have the same name represent different IDs in different jurisdictions. +Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. To achieve this, a [`DurableObjectId`](/durable-objects/api/id) encodes its jurisdiction. As a consequence, it is possible to have the same name represent different IDs in different jurisdictions. ```js const euId1 = env.MY_DURABLE_OBJECT.idFromName("my-name"); @@ -34,7 +34,7 @@ const euId2 = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("my-name"); console.assert(!euId1.equal(euId2), "This should always be true"); ``` -Methods on a [`DurableObjectNamespace`](../../api/namespace/) that take a [`DurableObjectId`](../../api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. However, these methods will not throw an exception if the [`DurableObjectNamespace`](../../api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](../../api/id) can be used in the top-level namespace's methods. +Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. However, these methods will not throw an exception if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](/durable-objects/api/id) can be used in the top-level namespace's methods. ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); From 19136301cb26675f7df505c09aa9f75f5d3cc7c2 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 15:59:25 +0100 Subject: [PATCH 08/17] Apply suggestions from code review Adding immediately resolvable edits. Co-authored-by: justin-mp --- src/content/docs/durable-objects/api/id.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 26c5900e6aabc9a..681571fea36a457 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -11,7 +11,7 @@ import { Tabs, TabItem } from "~/components"; 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 stub for submitting requests to the Durable Object class. -Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when 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 unless their methods can be directly invoked. +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. :::note[`DurableObjectId`] @@ -53,7 +53,7 @@ A 64 digit hex string. ```js const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); const id2 = env.MY_DURABLE_OBJECT.newUniqueId(); -console.assert(!id1.equals(id2), "This should always be true"); +console.assert(!id1.equals(id2), "Different unique ids should never be equal."); ``` #### Parameters @@ -75,8 +75,8 @@ A boolean. True if equal and false otherwise. ```js const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); const id2 = env.MY_DURABLE_OBJECT.idFromName("foo"); -console.assert(id1.name === undefined, "This should always be true"); -console.assert(id2.name === "foo", "This should always be true"); +console.assert(id1.name === undefined, "unique ids have no name"); +console.assert(id2.name === "foo", "name matches parameter to idFromName"); ``` ## Related resources From afb20a22f52a3c9d682f83b9414bf54da7d26845 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:02:37 +0100 Subject: [PATCH 09/17] Adding suggestion. --- src/content/docs/durable-objects/api/id.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 26c5900e6aabc9a..cdcdabafbcd26fd 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -9,7 +9,7 @@ import { Tabs, TabItem } from "~/components"; ## Description -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 stub for submitting requests to the Durable Object class. +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 stub for submitting requests to a Durable Object instance. Note that creating an ID for a Durable Object instance does not invoke the constructor of the Durable Object. This is done lazily when 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 unless their methods can be directly invoked. From 0f815459d56b4864401174d86b2b2ddaf2e74c51 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:09:12 +0100 Subject: [PATCH 10/17] Apply suggestions from code review --- src/content/docs/durable-objects/api/id.mdx | 8 ++++---- .../docs/durable-objects/reference/data-location.mdx | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index a6ab41383d999e4..0ae080970119df1 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -73,10 +73,10 @@ A boolean. True if equal and false otherwise. `name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid). ```js -const id1 = env.MY_DURABLE_OBJECT.newUniqueId(); -const id2 = env.MY_DURABLE_OBJECT.idFromName("foo"); -console.assert(id1.name === undefined, "unique ids have no name"); -console.assert(id2.name === "foo", "name matches parameter to idFromName"); +const uniqueId = env.MY_DURABLE_OBJECT.newUniqueId(); +const fromNameId = env.MY_DURABLE_OBJECT.idFromName("foo"); +console.assert(uniqueId.name === undefined, "unique ids have no name"); +console.assert(fromNameId.name === "foo", "name matches parameter to idFromName"); ``` ## Related resources diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index df4a033e370fd9b..649c38dcb33daf0 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -47,7 +47,7 @@ const stub = env.MY_DURABLE_OBJECT.get(euId); | Parameter | Location | | --------- | ---------------------------- | | eu | The European Union | -| fedramp | The United States of America | +| fedramp | FedRAMP-compliant data centers | ## Provide a location hint From 9503ffe74e21604cde1ef1986cf8b22bbabd8e63 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:14:59 +0100 Subject: [PATCH 11/17] Ensuring consistent wording for description of DurableObjectNamespace. --- src/content/docs/durable-objects/api/namespace.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 4c00d87a01f60e7..56144477acc2c5f 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -11,7 +11,7 @@ import { Tabs, TabItem } from "~/components"; The `DurableObjectNamespace` interface is used to obtain a reference to a new or existing Durable Object instance. 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`. -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 invoke the constructor of the Durable Object. This is done lazily when 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 unless their methods can be directly invoked. +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. From d21b9fb1eb09e9a64c8800910d12df95a6779b38 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:21:32 +0100 Subject: [PATCH 12/17] Update src/content/docs/durable-objects/api/alarms.mdx Co-authored-by: justin-mp --- src/content/docs/durable-objects/api/alarms.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index 1f68b7ef1270690..60a80874f39992d 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -39,7 +39,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w - getAlarm(): - - If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. + - If there is an alarm set, then return the currently set alarm time as the number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. ### setAlarm From 84f382fe0c975333425e8110703834349308bc3e Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:21:42 +0100 Subject: [PATCH 13/17] Update src/content/docs/durable-objects/api/alarms.mdx Co-authored-by: justin-mp --- src/content/docs/durable-objects/api/alarms.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index 60a80874f39992d..69410185d45e708 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -45,7 +45,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w - setAlarm(scheduledTimeMs ): - - Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch. + - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch. ### deleteAlarm From 76f073c4d4424f2dc8076a8f21befe5cb6d08c2b Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:22:35 +0100 Subject: [PATCH 14/17] Update src/content/docs/durable-objects/api/storage-api.mdx Co-authored-by: justin-mp --- src/content/docs/durable-objects/api/storage-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index 219db0d4deb7312..66713d1d0b8d5b0 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -100,7 +100,7 @@ Each method is implicitly wrapped inside a transaction, such that its results ar * deleteAll(options ): - * Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database. + * Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database, including both SQL data and key-value data. * For Durable Objects with a key-value storage backend, an in-progress `deleteAll()` operation can fail, which may leave a subset of data undeleted. Durable Objects with a SQLite storage backend do not have a partial `deleteAll()` issue because `deleteAll()` operations are atomic (all or nothing). * `deleteAll()` does not proactively delete [Alarms](/durable-objects/api/alarms/). Use [`deleteAlarm()`](/durable-objects/api/alarms/#deletealarm) to delete an alarm. From a8cc3865a72a56062cac55fe0fd4579aefe47c28 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:25:46 +0100 Subject: [PATCH 15/17] "Two seconds" -> "2 seconds", "six seconds" -> "6 seconds" --- src/content/docs/durable-objects/api/alarms.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index 1f68b7ef1270690..6384c0aab3b80ef 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -21,7 +21,7 @@ Notably: - Each Durable Object instance is able to schedule a single alarm at a time by calling `setAlarm()`. - Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws. -- Retries are performed using exponential backoff starting at a two second delay from the first failure with up to six retries allowed. +- Retries are performed using exponential backoff starting at a 2 second delay from the first failure with up to 6 retries allowed. :::note[How are alarms different from Cron Triggers?] @@ -63,7 +63,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w - Called by the system when a scheduled alarm time is reached. - - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception. + - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. Retries will be performed if the method fails with an uncaught exception. - This method can be `async`. From c3ee93ba70cd63db8a32bd9a40128723e93613e3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 9 Oct 2024 16:32:26 +0100 Subject: [PATCH 16/17] Adding link to best practices section. --- src/content/docs/durable-objects/api/namespace.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 56144477acc2c5f..42ba3172ce3a28e 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -175,3 +175,4 @@ A `DurableObjectNamespace` scoped to a particular geographic jurisdiction. ## Related resources - [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). +- [Durable Objects best practices](/durable-objects/best-practices/access-durable-objects-from-a-worker/). \ No newline at end of file From 7ab17b26fe4f14aec989a52a72ba5ea029c786f6 Mon Sep 17 00:00:00 2001 From: Joshua Howard Date: Wed, 9 Oct 2024 12:15:43 -0500 Subject: [PATCH 17/17] Address remaining comments --- .../docs/durable-objects/api/alarms.mdx | 12 +++-- src/content/docs/durable-objects/api/id.mdx | 27 ++++++----- .../docs/durable-objects/api/namespace.mdx | 46 ++++++++----------- src/content/docs/durable-objects/api/stub.mdx | 8 +--- 4 files changed, 41 insertions(+), 52 deletions(-) diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index bb1a1c4dd3084d5..49498f31d0ff86f 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -37,15 +37,19 @@ Alarms can be used to build distributed primitives, like queues or batching of w ### getAlarm -- getAlarm(): +- getAlarm(): - If there is an alarm set, then return the currently set alarm time as the number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`. ### setAlarm -- setAlarm(scheduledTimeMs ): +- + {" "} + setAlarm(scheduledTimeMs ) + + : - - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch. + - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch. ### deleteAlarm @@ -72,7 +76,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w This example shows how to both set alarms with the `setAlarm(timestamp)` method and handle alarms with the `alarm()` handler within your Durable Object. - The `alarm()` handler will be called once every time an alarm fires. -- If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine. +- If an unexpected error terminates the Durable Object, the `alarm()` handler may be re-instantiated on another machine. - Following a short delay, the `alarm()` handler will run from the beginning on the other machine. ```js diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index 0ae080970119df1..97c339ff62fa022 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -23,14 +23,14 @@ If you are experiencing an issue with a particular Durable Object instance, you ### `toString` -#### Description - `toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, for example, in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`. ```js // Create a new unique ID const id = env.MY_DURABLE_OBJECT.newUniqueId(); -// Save the unique ID elsewhere, e.g. a session cookie via id.toString() +// Convert the ID to a string to be saved elsewhere, e.g. a session cookie +const session_id = id.toString(); + ... // Recreate the ID from the string const id = env.MY_DURABLE_OBJECT.idFromString(session_id); @@ -38,16 +38,14 @@ const id = env.MY_DURABLE_OBJECT.idFromString(session_id); #### Parameters -None. +- None. -#### Return value +#### Return values -A 64 digit hex string. +- A 64 digit hex string. ### `equals` -#### Description - `equals` is used to compare equality between two instances of `DurableObjectId`. ```js @@ -58,25 +56,26 @@ console.assert(!id1.equals(id2), "Different unique ids should never be equal."); #### Parameters -A required `DurableObjectId` to compare against. +- A required `DurableObjectId` to compare against. -#### Return value +#### Return values -A boolean. True if equal and false otherwise. +- A boolean. True if equal and false otherwise. ## Properties ### `name` -#### Description - `name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid). ```js const uniqueId = env.MY_DURABLE_OBJECT.newUniqueId(); const fromNameId = env.MY_DURABLE_OBJECT.idFromName("foo"); console.assert(uniqueId.name === undefined, "unique ids have no name"); -console.assert(fromNameId.name === "foo", "name matches parameter to idFromName"); +console.assert( + fromNameId.name === "foo", + "name matches parameter to idFromName", +); ``` ## Related resources diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 42ba3172ce3a28e..4e53d3398dc9131 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -29,7 +29,7 @@ export default { // Every unique ID refers to an individual instance of the Durable Object class const id = env.MY_DURABLE_OBJECT.idFromName("foo"); - // A stub is a client Object used to invoke methods on the Durable Object instance. + // A stub is a client Object used to invoke methods defined by the Durable Object instance const stub = env.MY_DURABLE_OBJECT.get(id); ... } @@ -56,7 +56,7 @@ export default { // Every unique ID refers to an individual instance of the Durable Object class const id = env.MY_DURABLE_OBJECT.idFromName("foo"); - // A stub is a client used to invoke methods on the Durable Object instance. + // A stub is a client Object used to invoke methods defined by the Durable Object instance const stub = env.MY_DURABLE_OBJECT.get(id); ... } @@ -69,8 +69,6 @@ export default { ### `idFromName` -#### Description - `idFromName` creates a [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class from a particular name. ```js @@ -80,16 +78,14 @@ const barId = env.MY_DURABLE_OBJECT.idFromName("bar"); #### Parameters -The string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object instance. +- A required string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object instance. -#### Return value +#### Return values -A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. +- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. ### `newUniqueId` -#### Description - `newUniqueId` creates a `DurableObjectId` which refers to an individual instance of the Durable Object class. ```js @@ -105,16 +101,14 @@ IDs created by `newUniqueId` will result in lower latencies when getting a [`Dur #### Parameters -An optional object with the key `jurisdiction` and value of a [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +- An optional object with the key `jurisdiction` and value of a [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. -#### Return value +#### Return values -A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of the Durable Object class. +- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of the Durable Object class. ### `idFromString` -#### Description - `idFromString` creates a [`DurableObjectId`](/durable-objects/api/id) from a previously generated ID that has been converted to a string. This method ensures the ID is valid, for example, it checks that the ID consists of 64 hex digits. ```js @@ -128,16 +122,14 @@ const id = env.MY_DURABLE_OBJECT.idFromString(session_id); #### Parameters -The string corresponding to a [`DurableObjectId`](/durable-objects/api/id) previously generated either by `newUniqueId` or `idFromName`. +- A required string corresponding to a [`DurableObjectId`](/durable-objects/api/id) previously generated either by `newUniqueId` or `idFromName`. -#### Return value +#### Return values -A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. +- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class. ### `get` -#### Description - `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. ```js @@ -147,16 +139,14 @@ const stub = env.MY_DURABLE_OBJECT.get(id); #### Parameters -A required [`DurableObjectId`](/durable-objects/api/id) and an optional object with the key `locationHint` and value of a [locationHint](/durable-objects/reference/data-location/#provide-a-location-hint) string. +- A required [`DurableObjectId`](/durable-objects/api/id) and an optional object with the key `locationHint` and value of a [locationHint](/durable-objects/reference/data-location/#provide-a-location-hint) string. -#### Return value +#### Return values -A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class. +- A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class. ### `jurisdiction` -#### Description - `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). ```js @@ -166,13 +156,13 @@ const euId = subnamespace.idFromName("foo"); #### Parameters -A required [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. +- A required [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string. -#### Return value +#### Return values -A `DurableObjectNamespace` scoped to a particular geographic jurisdiction. +- A `DurableObjectNamespace` scoped to a particular geographic jurisdiction. ## Related resources - [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). -- [Durable Objects best practices](/durable-objects/best-practices/access-durable-objects-from-a-worker/). \ No newline at end of file +- [Durable Objects best practices](/durable-objects/best-practices/access-durable-objects-from-a-worker/). diff --git a/src/content/docs/durable-objects/api/stub.mdx b/src/content/docs/durable-objects/api/stub.mdx index 4f8452190975a38..19dfbd9cc724082 100644 --- a/src/content/docs/durable-objects/api/stub.mdx +++ b/src/content/docs/durable-objects/api/stub.mdx @@ -59,7 +59,7 @@ export class MyDurableObject extends DurableObject { super(ctx, env); } - sayHello(): String { + async sayHello(): String { return "Hello, World!"; } } @@ -74,7 +74,7 @@ export default { const stub = env.MY_DURABLE_OBJECT.get(id); // Methods on the Durable Object are invoked via the stub - const rpcResponse = stub.sayHello(); + const rpcResponse = await stub.sayHello(); return new Response(rpcResponse); }, @@ -87,8 +87,6 @@ export default { ### `id` -#### Description - `id` is a property of the `DurableObjectStub` corresponding to the [`DurableObjectId`](/durable-objects/api/id) used to create the stub. ```js @@ -99,8 +97,6 @@ console.assert(id.equals(stub.id), "This should always be true"); ### `name` -#### Description - `name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](/durable-objects/api/id) via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](/durable-objects/api/id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid). ```js