You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/durable-objects/reference/data-location.mdx
+40-75Lines changed: 40 additions & 75 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,85 +3,51 @@ title: Data location
3
3
pcx_content_type: concept
4
4
sidebar:
5
5
order: 8
6
-
7
6
---
8
7
9
-
You can restrict a Durable Object to a jurisdiction, or provide a location hint.
10
-
11
8
## Restrict Durable Objects to a jurisdiction
12
9
13
-
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/).
14
-
15
-
:::note
16
-
17
-
Jurisdictions are available to all Durable Objects users.
18
-
:::
19
-
20
-
To use a jurisdiction, first create a jurisidictional subnamespace in your Worker's code:
21
-
22
-
```js
23
-
let subnamespace =OBJECT_NAMESPACE.jurisdiction('eu');
24
-
```
25
-
26
-
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.
27
-
28
-
To create a new Durable Object ID that will only run and persist data within the jurisdiction:
29
-
30
-
```js
31
-
let id =subnamespace.newUniqueId();
32
-
```
33
-
34
-
To derive a unique Object ID from the given name string that will only run and persist data within the jurisdiction:
35
-
36
-
```js
37
-
let id =subnamespace.idFromName(name);
38
-
```
39
-
40
-
:::note[IDs derived from the same name but different jurisdictions will differ]
10
+
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/).
41
11
12
+
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.
42
13
43
-
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.
44
-
45
-
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.
14
+
:::note[logging]
46
15
16
+
A [`DurableObjectId`](../../api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes.
47
17
48
18
:::
49
19
50
-
To parse a previously-created ID from a string:
20
+
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:
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.
console.assert(!euId1.equal(euId2), "This should always be true");
60
35
```
61
36
62
-
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.
37
+
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.
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.
75
-
76
-
The currently supported jurisdictions are `eu` (the European Union) and `fedramp` (FedRAMP).
45
+
### Supported locations
77
46
78
-
:::note[ID logging]
79
-
80
-
81
-
Durable Object IDs will be logged outside of the specified jurisdiction for billing and debugging purposes.
82
-
83
-
84
-
:::
47
+
| Parameter | Location |
48
+
| --------- | ---------------------------- |
49
+
| eu | The European Union |
50
+
| fedramp | The United States of America |
85
51
86
52
## Provide a location hint
87
53
@@ -91,37 +57,36 @@ Durable Objects do not currently change locations after they are created<sup>1</
91
57
92
58
:::caution[Initial requests to Durable Objects]
93
59
94
-
95
60
It can negatively impact latency to pre-create Durable Objects prior to the first client request or when the first client request is not representative of where the majority of requests will come from. It is better for latency to create Durable Objects in response to actual production traffic or provide explicit location hints.
96
61
97
-
98
62
:::
99
63
100
64
Location hints are the mechanism provided to specify the location that a Durable Object should be located regardless of where the initial `get()` request comes from.
101
65
102
66
To manually create Durable Objects in another location, provide an optional `locationHint` parameter to `get()`. Only the first call to `get()` for a particular Object will respect the hint.
103
67
104
68
```js
105
-
let durableObjectStub =OBJECT_NAMESPACE.get(id, { locationHint:'enam' });
69
+
let durableObjectStub =OBJECT_NAMESPACE.get(id, { locationHint:"enam" });
106
70
```
107
71
108
72
:::caution
109
73
110
-
Hints are a best effort and not a guarantee. Unlike with jurisdictions, Durable Objects will not necessarily be instantiated in the hinted location, but instead instantiated in a data center selected to minimize latency from the hinted location.
74
+
Hints are a best effort and not a guarantee. Unlike with jurisdictions, Durable Objects will not necessarily be instantiated in the hinted location, but instead instantiated in a data center selected to minimize latency from the hinted location.
0 commit comments