From d373342248288650ca8964218260e75bfeaf0aa3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 16 May 2025 14:51:43 +0100 Subject: [PATCH 1/5] Not recommending newUniqueId(jurisdiction) approach --- .../reference/data-location.mdx | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 57a260277b2b981..38aaac0a1ca82c6 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -19,15 +19,15 @@ A [`DurableObjectId`](/durable-objects/api/id) will be logged outside of the spe ::: -Durable Objects 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: +Durable Objects can be restricted to a specific jurisdiction by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction: ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); const euId = euSubnamespace.newUniqueId(); -// or -const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); ``` +This approach works with all of the [ID methods](/durable-objects/api/id/). + 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 @@ -35,8 +35,7 @@ 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"); ``` - -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. +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"); @@ -44,6 +43,16 @@ const euId = euSubnamespace.idFromName(name); const stub = env.MY_DURABLE_OBJECT.get(euId); ``` +:::caution[Do not use `newUniqueId(jurisdiction)`] +Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction: + +```sh +const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); +``` + +**However, we do not recommend this approach.** Instead, first create a namespace restricted to a jurisdiction, as explained above. +::: + ### Supported locations | Parameter | Location | @@ -96,4 +105,4 @@ future. 2 Durable Objects currently do not spawn in this location. Instead, the Durable Object will spawn in a nearby location which does support Durable Objects. For example, Durable Objects hinted to South America spawn in Eastern -North America instead. +North America instead. \ No newline at end of file From bae34cae0a249a1cfaa2b133fac6124d68be5b0d Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 20 May 2025 14:55:54 +0100 Subject: [PATCH 2/5] Iterating over the docs for clarity and better information segregation --- .../reference/data-location.mdx | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 38aaac0a1ca82c6..287b794315804c2 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -28,14 +28,32 @@ const euId = euSubnamespace.newUniqueId(); This approach works with all of the [ID methods](/durable-objects/api/id/). -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. +:::caution[Do not use `newUniqueId(jurisdiction)`] + +When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction, as explained above. + +Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction. + +**However, Cloudflare does not recommend this approach.** + +This approach is only documented for completeness. + +```sh +const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); +``` + +- As a consequence, it is possible to have the same name represent different IDs in different jurisdictions. +- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different. +- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. ```js 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"); ``` -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. +::: + +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"); @@ -43,16 +61,6 @@ const euId = euSubnamespace.idFromName(name); const stub = env.MY_DURABLE_OBJECT.get(euId); ``` -:::caution[Do not use `newUniqueId(jurisdiction)`] -Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction: - -```sh -const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); -``` - -**However, we do not recommend this approach.** Instead, first create a namespace restricted to a jurisdiction, as explained above. -::: - ### Supported locations | Parameter | Location | From d24b2abd3aa1624557a9a929095ce41b7146a1e3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 29 May 2025 11:55:43 +0100 Subject: [PATCH 3/5] Iterating on feedback --- .../reference/data-location.mdx | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 287b794315804c2..3a2f08b86858ab8 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -19,38 +19,41 @@ A [`DurableObjectId`](/durable-objects/api/id) will be logged outside of the spe ::: -Durable Objects can be restricted to a specific jurisdiction by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction: +Durable Objects can be restricted to a specific jurisdiction by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction. All [Durable Object ID methods](/durable-objects/api/id/) are valid on IDs within a namespace restricted to a jurisdiction. ```js const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); const euId = euSubnamespace.newUniqueId(); ``` -This approach works with all of the [ID methods](/durable-objects/api/id/). +- It is possible to have the same name represent different IDs in different jurisdictions. +- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different. +- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. + + ```js + 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"); + ``` + +:::caution[Use `DurableObjectNamespace.jurisdiction`] -:::caution[Do not use `newUniqueId(jurisdiction)`] +When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction. -When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction, as explained above. +```js +const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); +const euId = euSubnamespace.newUniqueId(); +``` Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction. **However, Cloudflare does not recommend this approach.** -This approach is only documented for completeness. +This approach is only shown below for completeness. ```sh const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); ``` - -- As a consequence, it is possible to have the same name represent different IDs in different jurisdictions. -- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different. -- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. - -```js -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"); -``` ::: The common case is that any valid [`DurableObjectId`](/durable-objects/api/id) can be used in the top-level namespace's methods. From 127d0ad6ad1c35f30cfabf4d043a05adce58e5f1 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 30 May 2025 16:45:31 +0100 Subject: [PATCH 4/5] Turning code blocks into in-line code, restructure --- .../reference/data-location.mdx | 35 +++++++------------ 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 3a2f08b86858ab8..14abf04dd4e4284 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -27,8 +27,6 @@ const euId = euSubnamespace.newUniqueId(); ``` - It is possible to have the same name represent different IDs in different jurisdictions. -- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different. -- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. ```js const euId1 = env.MY_DURABLE_OBJECT.idFromName("my-name"); @@ -36,34 +34,25 @@ const euId = euSubnamespace.newUniqueId(); console.assert(!euId1.equal(euId2), "This should always be true"); ``` -:::caution[Use `DurableObjectNamespace.jurisdiction`] - -When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction. +- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different. +- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. +- All [Durable Object ID methods](/durable-objects/api/id/) are valid on IDs within a namespace restricted to a jurisdiction. -```js -const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); -const euId = euSubnamespace.newUniqueId(); -``` + ```js + const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu"); + const euId = euSubnamespace.idFromName(name); + const stub = env.MY_DURABLE_OBJECT.get(euId); + ``` -Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction. +:::caution[Use `DurableObjectNamespace.jurisdiction`] -**However, Cloudflare does not recommend this approach.** +When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction, using `const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu")`. -This approach is only shown below for completeness. +Note that it is also possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction, using `const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" })`. -```sh -const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" }); -``` +**However, Cloudflare does not recommend this approach.** ::: -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"); -const euId = euSubnamespace.idFromName(name); -const stub = env.MY_DURABLE_OBJECT.get(euId); -``` - ### Supported locations | Parameter | Location | From 3fad9623ae2d859b0ddafdf4c246e32f4c78324c Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 30 May 2025 16:51:32 +0100 Subject: [PATCH 5/5] Cleaning up footnote lines --- .../docs/durable-objects/reference/data-location.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 5b9dc10cc39ebcd..2ee026d7ac5b6e0 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -99,13 +99,10 @@ Hints are a best effort and not a guarantee. Unlike with jurisdictions, Durable | afr | Africa 2 | | me | Middle East 2 | -1 Dynamic relocation of existing Durable Objects is planned for the -future. +1 Dynamic relocation of existing Durable Objects is planned for the future. + +2 Durable Objects currently do not spawn in this location. Instead, the Durable Object will spawn in a nearby location which does support Durable Objects. For example, Durable Objects hinted to South America spawn in Eastern North America instead. -2 Durable Objects currently do not spawn in this location. Instead, -the Durable Object will spawn in a nearby location which does support Durable -Objects. For example, Durable Objects hinted to South America spawn in Eastern -North America instead. ## Additional resources - You can find our more about where Durable Objects are located using the website: [Where Durable Objects Live](https://where.durableobjects.live/). \ No newline at end of file