diff --git a/public/_redirects b/public/_redirects index 81e69ff47b819f..76bfdc55c9015e 100644 --- a/public/_redirects +++ b/public/_redirects @@ -368,6 +368,8 @@ /durable-objects/reference/troubleshooting/ /durable-objects/observability/troubleshooting/ 301 /durable-objects/reference/graphql-analytics/ /durable-objects/observability/graphql-analytics/ 301 /durable-objects/api/transactional-storage-api/ /durable-objects/api/storage-api/ 301 +/durable-objects/platform/changelog/ /durable-objects/changelog/ 301 +/durable-objects/glossary/ /durable-objects/reference/glossary/ 301 # email-routing /email-routing/enable-email-routing/ /email-routing/get-started/enable-email-routing/ 301 @@ -379,7 +381,7 @@ /email-security/setup/api-deployment/ /email-security/setup/post-delivery-deployment/api/ 301 /email-security/setup/api-deployment/office365-api/ /email-security/setup/post-delivery-deployment/api/office365-api/ 301 /email-security/email-configuration/retract-settings/gmail-retraction/ /email-security/deployment/api/setup/gsuite-bcc-setup/add-retraction/ 301 - + # firewall /firewall/api/cf-lists/ /waf/tools/lists/lists-api/ 301 diff --git a/src/content/changelogs/durable-objects.yaml b/src/content/changelogs/durable-objects.yaml index d8d20dadd17bc6..85377c3470c86c 100644 --- a/src/content/changelogs/durable-objects.yaml +++ b/src/content/changelogs/durable-objects.yaml @@ -1,5 +1,5 @@ --- -link: "/durable-objects/platform/changelog/" +link: "/durable-objects/changelog/" productName: Durable Objects productLink: "/durable-objects/" productArea: Developer platform diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx index db3a94f565ec92..e121811a13dead 100644 --- a/src/content/docs/durable-objects/api/alarms.mdx +++ b/src/content/docs/durable-objects/api/alarms.mdx @@ -5,11 +5,11 @@ sidebar: order: 6 --- -import { Type } from "~/components"; +import { Type, GlossaryTooltip } from "~/components"; ## Background -Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm's scheduled time comes, the `alarm()` handler method will be called. Alarms are modified using the [Storage API](/durable-objects/api/storage-api/), and alarm operations follow the same rules as other storage operations. +Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm's scheduled time comes, the `alarm()` handler method will be called. Alarms are modified using the Storage API, and alarm operations follow the same rules as other storage operations. Notably: @@ -37,10 +37,7 @@ Alarms can be used to build distributed primitives, like queues or batching of w ### 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. diff --git a/src/content/docs/durable-objects/api/id.mdx b/src/content/docs/durable-objects/api/id.mdx index f3cfb0fa6eacd3..246de21c9e6188 100644 --- a/src/content/docs/durable-objects/api/id.mdx +++ b/src/content/docs/durable-objects/api/id.mdx @@ -5,11 +5,11 @@ sidebar: order: 2 --- -import { Render, Tabs, TabItem } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; ## Description -A Durable Object ID is a 64-digit hexadecimal number used to identify a Durable Object. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface. +A Durable Object ID is a 64-digit hexadecimal number used to identify a Durable Object. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface. The `DurableObjectId` interface refers to a new or existing Durable Object. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a [`DurableObjectStub`](/durable-objects/api/stub) for submitting requests to a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after creating a stub from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed. diff --git a/src/content/docs/durable-objects/api/namespace.mdx b/src/content/docs/durable-objects/api/namespace.mdx index 1f94375a4a34a4..ba5f2ce58d15a5 100644 --- a/src/content/docs/durable-objects/api/namespace.mdx +++ b/src/content/docs/durable-objects/api/namespace.mdx @@ -5,11 +5,11 @@ sidebar: order: 1 --- -import { Render, Tabs, TabItem } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; ## Description -A Durable Object namespace is a set of Durable Objects that are backed by the same Durable Object class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects. +A Durable Object namespace is a set of Durable Objects that are backed by the same Durable Object class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects. The `DurableObjectNamespace` interface is used to obtain a reference to new or existing Durable Objects. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface when referencing bindings declared in `wrangler.toml`. @@ -129,7 +129,7 @@ After this first use, the location of the Durable Object will be cached around t `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. -This method returns the stub immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip. +This method returns the stub immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip. ```js const id = env.MY_DURABLE_OBJECT.newUniqueId(); diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index 568bed9da99e2c..de46162e1948e6 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -9,9 +9,9 @@ import { Tabs, TabItem, GlossaryTooltip } from "~/components"; ## Description -The `DurableObjectState` interface is accessible as an instance property on the Durable Objects class. This interface encapsulates methods that modify the state of a Durable Object, for example which WebSockets are attached to a Durable Object or how the runtime should handle concurrent Durable Object requests. +The `DurableObjectState` interface is accessible as an instance property on the Durable Object class. This interface encapsulates methods that modify the state of a Durable Object, for example which WebSockets are attached to a Durable Object or how the runtime should handle concurrent Durable Object requests. -The `DurableObjectState` interface is different from the [Storage API](/durable-objects/api/storage-api) in that it does not have top-level methods which manipulate persistent application data. These methods are instead encapsulated in the [`DurableObjectStorage`](/durable-objects/api/storage-api) interface and accessed by [`DurableObjectState::storage`](/durable-objects/api/state/#storage). +The `DurableObjectState` interface is different from the Storage API in that it does not have top-level methods which manipulate persistent application data. These methods are instead encapsulated in the [`DurableObjectStorage`](/durable-objects/api/storage-api) interface and accessed by [`DurableObjectState::storage`](/durable-objects/api/state/#storage). diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index c87773f37d091c..6b080ccab3c392 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -6,9 +6,9 @@ sidebar: --- -import { Render, Type, MetaInfo } from "~/components"; +import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components"; -The Storage API allows Durable Objects to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects. +The Storage API allows Durable Objects to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects. Durable Objects gain access to a persistent Storage API via `ctx.storage`, on the `ctx` parameter passed to the Durable Object constructor. diff --git a/src/content/docs/durable-objects/api/stub.mdx b/src/content/docs/durable-objects/api/stub.mdx index 0e5c306b4fe9c2..1a277e4c0bb932 100644 --- a/src/content/docs/durable-objects/api/stub.mdx +++ b/src/content/docs/durable-objects/api/stub.mdx @@ -5,15 +5,15 @@ sidebar: order: 3 --- -import { Render } from "~/components"; +import { Render, GlossaryTooltip } from "~/components"; ## Description -The `DurableObjectStub` interface is a client used to invoke methods on a remote Durable Object. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub. +The `DurableObjectStub` interface is a client used to invoke methods on a remote Durable Object. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub. Durable Objects implement E-order semantics, a concept deriving from the [E distributed programming language](). When you make multiple calls to the same Durable Object, it is guaranteed that the calls will be delivered to the remote Durable Object in the order in which you made them. E-order semantics makes many distributed programming problems easier. E-order is implemented by the [Cap'n Proto](https://capnproto.org) distributed object-capability RPC protocol, which Cloudflare Workers uses for internal communications. -If an exception is thrown by a Durable Object stub all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs. +If an exception is thrown by a Durable Object stub all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs. diff --git a/src/content/docs/durable-objects/api/websockets.mdx b/src/content/docs/durable-objects/api/websockets.mdx index 3504ebf3211c2f..c1fc60478dd091 100644 --- a/src/content/docs/durable-objects/api/websockets.mdx +++ b/src/content/docs/durable-objects/api/websockets.mdx @@ -5,13 +5,13 @@ sidebar: order: 5 --- -import { Render, Type, MetaInfo } from "~/components"; +import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components"; ## Background WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server. -Durable Objects support the Workers Runtime [WebSocket API](/workers/runtime-apis/websockets/). Your Durable Object can act as a single point-of-coordination for WebSocket sessions, giving you full control over messages sent to and from clients, allowing you to build applications like chat rooms and multiplayer games. +Durable Objects support the Workers Runtime [WebSocket API](/workers/runtime-apis/websockets/). Your Durable Object can act as a single point-of-coordination for WebSocket sessions, giving you full control over messages sent to and from clients, allowing you to build applications like chat rooms and multiplayer games. For more information beyond the API reference, refer to the [Build a WebSocket server](/durable-objects/examples/websocket-server/) example. diff --git a/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx b/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx index 7f76695ccb348e..c6705730d02a5c 100644 --- a/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx +++ b/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx @@ -6,17 +6,17 @@ sidebar: --- -import { Render } from "~/components"; +import { Render, GlossaryTooltip } from "~/components"; -Durable Objects are a powerful compute API that provides a compute with storage building block. Each Durable Object has its own private, transactional and strongly consistent storage. Durable Objects [Storage API](/durable-objects/api/storage-api/#methods) provides access to a Durable Object's attached storage. +Durable Objects are a powerful compute API that provides a compute with storage building block. Each Durable Object has its own private, transactional and strongly consistent storage. Durable Objects Storage API provides access to a Durable Object's attached storage. A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/configuration/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects. ## Access storage -By default, a Durable Object class leverages a key-value storage backend. New Durable Object classes can opt-in to using a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend). +By default, a Durable Object class leverages a key-value storage backend. New Durable Object classes can opt-in to using a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend). -[Storage API](/durable-objects/api/storage-api/#methods) methods are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API. +[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API. A common pattern is to initialize a Durable Object from [persistent storage](/durable-objects/api/storage-api/) and set instance variables the first time it is accessed. Since future accesses are routed to the same Durable Object, it is then possible to return any initialized values without making further calls to persistent storage. @@ -44,7 +44,7 @@ export class Counter extends DurableObject { ``` ### Removing a Durable Object's storage -A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting alarms), then storage remains empty, and so the Durable Object will no longer exist once it shuts down. +A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting alarms), then storage remains empty, and so the Durable Object will no longer exist once it shuts down. However if you ever write using [Storage API](/durable-objects/api/storage-api/), including setting alarms, then you must explicitly call [`storage.deleteAll()`](/durable-objects/api/storage-api/#deleteall) to empty storage. It is not sufficient to simply delete the specific data that you wrote, such as deleting a key or dropping a table, as some metadata may remain. The only way to remove all storage is to call `deleteAll()`. Calling `deleteAll()` ensures that a Durable Object will not be billed for storage. diff --git a/src/content/docs/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.mdx b/src/content/docs/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.mdx index 271c8ba61030a3..bdf8bb6e9e9930 100644 --- a/src/content/docs/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.mdx +++ b/src/content/docs/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.mdx @@ -5,11 +5,11 @@ sidebar: order: 2 --- -import { Render, Tabs, TabItem } from "~/components"; +import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; ## Invoking methods on a Durable Object -All new projects and existing projects with a compatibility date greater than or equal to [`2024-04-03`](/workers/configuration/compatibility-dates/#durable-object-stubs-and-service-bindings-support-rpc) should prefer to invoke [Remote Procedure Call (RPC)](/workers/runtime-apis/rpc/) methods defined on a Durable Object class. Legacy projects can continue to invoke the `fetch` handler on the Durable Object class indefinitely. +All new projects and existing projects with a compatibility date greater than or equal to [`2024-04-03`](/workers/configuration/compatibility-dates/#durable-object-stubs-and-service-bindings-support-rpc) should prefer to invoke [Remote Procedure Call (RPC)](/workers/runtime-apis/rpc/) methods defined on a Durable Object class. Legacy projects can continue to invoke the `fetch` handler on the Durable Object class indefinitely. ### Invoke RPC methods diff --git a/src/content/docs/durable-objects/best-practices/error-handling.mdx b/src/content/docs/durable-objects/best-practices/error-handling.mdx index 18c2a222b61a07..abcbaf755dc3d1 100644 --- a/src/content/docs/durable-objects/best-practices/error-handling.mdx +++ b/src/content/docs/durable-objects/best-practices/error-handling.mdx @@ -5,7 +5,10 @@ sidebar: order: 4 --- -Any uncaught exceptions thrown by a Durable Object or thrown by Durable Objects' infrastructure (such as overloads or network errors) will be propagated to the callsite of the client. Catching these exceptions allows you to retry creating the [`DurableObjectStub`](/durable-objects/api/stub) and sending requests. +import { GlossaryTooltip } from "~/components"; + + +Any uncaught exceptions thrown by a Durable Object or thrown by Durable Objects' infrastructure (such as overloads or network errors) will be propagated to the callsite of the client. Catching these exceptions allows you to retry creating the [`DurableObjectStub`](/durable-objects/api/stub) and sending requests. JavaScript Errors with the property `.retryable` set to True are suggested to be retried if requests to the Durable Object are idempotent, or can be applied multiple times without changing the response. If requests are not idempotent, then you will need to decide what is best for your application. @@ -17,7 +20,7 @@ It is strongly recommended to retry requests following the exponential backoff a Durable Objects can throw exceptions in one of two ways: -- An exception can be thrown within the user code which implements a Durable Object class. The resulting exception will have a `.remote` property set to `True` in this case. +- An exception can be thrown within the user code which implements a Durable Object class. The resulting exception will have a `.remote` property set to `True` in this case. - An exception can be generated by Durable Object's infrastructure. Some sources of infrastructure exceptions include: transient internal errors, sending too many requests to a single Durable Object, and too many requests being queued due to slow or excessive I/O (external API calls or storage operations) within an individual Durable Object. Some infrastructure exceptions may also have the `.remote` property set to `True` -- for example, when the Durable Object exceeds its memory or CPU limits. Refer to [Troubleshooting](/durable-objects/observability/troubleshooting/) to review the types of errors returned by a Durable Object and/or Durable Objects infrastructure and how to prevent them. diff --git a/src/content/docs/durable-objects/platform/changelog.mdx b/src/content/docs/durable-objects/changelog.mdx similarity index 97% rename from src/content/docs/durable-objects/platform/changelog.mdx rename to src/content/docs/durable-objects/changelog.mdx index 240a143a81c5ec..d0be4e937f0209 100644 --- a/src/content/docs/durable-objects/platform/changelog.mdx +++ b/src/content/docs/durable-objects/changelog.mdx @@ -4,7 +4,7 @@ title: Changelog changelog_file_name: - durable-objects sidebar: - order: 4 + order: 14 --- import { ProductChangelog } from "~/components"; diff --git a/src/content/docs/durable-objects/demos.mdx b/src/content/docs/durable-objects/demos.mdx index e309bb515264f5..66b63a35c2c45b 100644 --- a/src/content/docs/durable-objects/demos.mdx +++ b/src/content/docs/durable-objects/demos.mdx @@ -2,13 +2,13 @@ pcx_content_type: navigation title: Demos and architectures sidebar: - order: 8 + order: 9 --- import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components" -Learn how you can use Durable Objects within your existing application and architecture. +Learn how you can use a Durable Object within your existing application and architecture. ## Demos diff --git a/src/content/docs/durable-objects/durable-objects-rest-api.mdx b/src/content/docs/durable-objects/durable-objects-rest-api.mdx index 3cf48e5eb4dd81..dc4a4b92ec3ec6 100644 --- a/src/content/docs/durable-objects/durable-objects-rest-api.mdx +++ b/src/content/docs/durable-objects/durable-objects-rest-api.mdx @@ -1,8 +1,8 @@ --- pcx_content_type: navigation -title: Durable Objects REST API +title: REST API external_link: /api/operations/durable-objects-namespace-list-namespaces sidebar: - order: 11 + order: 5 --- diff --git a/src/content/docs/durable-objects/examples/alarms-api.mdx b/src/content/docs/durable-objects/examples/alarms-api.mdx index 0abb98b3347f63..d9d24eeaf63d37 100644 --- a/src/content/docs/durable-objects/examples/alarms-api.mdx +++ b/src/content/docs/durable-objects/examples/alarms-api.mdx @@ -13,7 +13,9 @@ description: Use the Durable Objects Alarms API to batch requests to a Durable O --- -This example implements an `alarm()` handler that wakes the Durable Object once every 10 seconds to batch requests to a single Durable Object. The `alarm()` handler will delay processing until there is enough work in the queue. +import { GlossaryTooltip } from "~/components"; + +This example implements an `alarm()` handler that wakes the Durable Object once every 10 seconds to batch requests to a single Durable Object. The `alarm()` handler will delay processing until there is enough work in the queue. ```js import { DurableObject } from 'cloudflare:workers'; diff --git a/src/content/docs/durable-objects/examples/build-a-rate-limiter.mdx b/src/content/docs/durable-objects/examples/build-a-rate-limiter.mdx index 7aec3637e7e500..563686e7484a53 100644 --- a/src/content/docs/durable-objects/examples/build-a-rate-limiter.mdx +++ b/src/content/docs/durable-objects/examples/build-a-rate-limiter.mdx @@ -11,9 +11,9 @@ description: Build a rate limiter using Durable Objects and Workers. --- -import { TabItem, Tabs } from "~/components" +import { TabItem, Tabs, GlossaryTooltip } from "~/components" -This example shows how to build a rate limiter using Durable Objects and Workers that can be used to protect upstream resources, including third-party APIs that your application relies on and/or services that may be costly for you to invoke. +This example shows how to build a rate limiter using Durable Objects and Workers that can be used to protect upstream resources, including third-party APIs that your application relies on and/or services that may be costly for you to invoke. This example also discusses some decisions that need to be made when designing a system, such as a rate limiter, with Durable Objects. @@ -35,7 +35,7 @@ The Durable Object uses a token bucket algorithm to implement rate limiting. The This example uses Durable Object's [Alarms API](/durable-objects/api/alarms) to schedule the Durable Object to be woken up at a time in the future. -* When the alarm's scheduled time comes, the `alarm()` handler method is called, and in this case, the alarm will add a token to the "Bucket". +* When the alarm's scheduled time comes, the `alarm()` handler method is called, and in this case, the alarm will add a token to the "Bucket". * The implementation is made more efficient by adding tokens in bulk (as specified by milliseconds\_for\_updates) and preventing the alarm handler from being invoked every millisecond. More frequent invocations of Durable Objects will lead to higher invocation and duration charges. The first implementation of a rate limiter is below: diff --git a/src/content/docs/durable-objects/examples/durable-object-in-memory-state.mdx b/src/content/docs/durable-objects/examples/durable-object-in-memory-state.mdx index c3ea4eac51806c..3b6ab5309a7519 100644 --- a/src/content/docs/durable-objects/examples/durable-object-in-memory-state.mdx +++ b/src/content/docs/durable-objects/examples/durable-object-in-memory-state.mdx @@ -13,7 +13,7 @@ description: Create a Durable Object that stores the last location it was --- -This example shows you how Durable Objects are stateful, meaning in-memory state can be retained between requests. After a brief period of inactivity, the Durable Object will be evicted, and all in-memory state will be lost. The next request will reconstruct the object, but instead of showing the city of the previous request, it will display a message indicating that the object has been reinitialized. If you need your applications state to survive eviction, write the state to storage by using the [storage API](/durable-objects/api/storage-api/), or by storing your data elsewhere. +This example shows you how Durable Objects are stateful, meaning in-memory state can be retained between requests. After a brief period of inactivity, the Durable Object will be evicted, and all in-memory state will be lost. The next request will reconstruct the object, but instead of showing the city of the previous request, it will display a message indicating that the object has been reinitialized. If you need your applications state to survive eviction, write the state to storage by using the [Storage API](/durable-objects/api/storage-api/), or by storing your data elsewhere. ```js import { DurableObject } from 'cloudflare:workers'; diff --git a/src/content/docs/durable-objects/examples/index.mdx b/src/content/docs/durable-objects/examples/index.mdx index f8539190182b77..614db9572a3a54 100644 --- a/src/content/docs/durable-objects/examples/index.mdx +++ b/src/content/docs/durable-objects/examples/index.mdx @@ -2,7 +2,7 @@ title: Examples pcx_content_type: navigation sidebar: - order: 6 + order: 7 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/examples/use-kv-from-durable-objects.mdx b/src/content/docs/durable-objects/examples/use-kv-from-durable-objects.mdx index 33ad1474e76ea3..7fbf364ed9b541 100644 --- a/src/content/docs/durable-objects/examples/use-kv-from-durable-objects.mdx +++ b/src/content/docs/durable-objects/examples/use-kv-from-durable-objects.mdx @@ -11,7 +11,9 @@ description: Read and write to/from KV within a Durable Object --- -The following Worker script shows you how to configure a [Durable Object](/durable-objects/) to read from and/or write to a [Workers KV namespace](/kv/concepts/how-kv-works/). This is useful when using a Durable Object to coordinate between multiple clients, and allows you to serialize writes to KV and/or broadcast a single read from KV to hundreds or thousands of clients connected to a single Durable Object [using WebSockets](/durable-objects/api/websockets/). +import { GlossaryTooltip } from "~/components"; + +The following Worker script shows you how to configure a Durable Object to read from and/or write to a [Workers KV namespace](/kv/concepts/how-kv-works/). This is useful when using a Durable Object to coordinate between multiple clients, and allows you to serialize writes to KV and/or broadcast a single read from KV to hundreds or thousands of clients connected to a single Durable Object [using WebSockets](/durable-objects/api/websockets/). Prerequisites: diff --git a/src/content/docs/durable-objects/examples/websocket-server.mdx b/src/content/docs/durable-objects/examples/websocket-server.mdx index a03748a687d22d..363229dd1859ee 100644 --- a/src/content/docs/durable-objects/examples/websocket-server.mdx +++ b/src/content/docs/durable-objects/examples/websocket-server.mdx @@ -11,9 +11,9 @@ description: Build a WebSocket server using Durable Objects and Workers. --- -import { TabItem, Tabs } from "~/components" +import { TabItem, Tabs, GlossaryTooltip } from "~/components" -This example shows how to build a WebSocket server using Durable Objects and Workers. The example exposes an endpoint to create a new WebSocket connection. This WebSocket connection echos any message while including the total number of WebSocket connections currently established. For more information, refer to [Use Durable Objects with WebSockets](/durable-objects/reference/websockets/). +This example shows how to build a WebSocket server using Durable Objects and Workers. The example exposes an endpoint to create a new WebSocket connection. This WebSocket connection echos any message while including the total number of WebSocket connections currently established. For more information, refer to [Use Durable Objects with WebSockets](/durable-objects/reference/websockets/). :::caution @@ -187,7 +187,7 @@ export class WebSocketServer extends DurableObject { -Finally, configure your `wrangler.toml` file to include a Durable Object [binding](/durable-objects/get-started/#5-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously. +Finally, configure your `wrangler.toml` file to include a Durable Object [binding](/durable-objects/get-started/#5-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously. ```toml title="wrangler.toml" name = "websocket-server" diff --git a/src/content/docs/durable-objects/index.mdx b/src/content/docs/durable-objects/index.mdx index d75f9e0600e505..f088cb127b6edb 100644 --- a/src/content/docs/durable-objects/index.mdx +++ b/src/content/docs/durable-objects/index.mdx @@ -11,14 +11,10 @@ head: --- -import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components" +import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, LinkButton } from "~/components" - - Create collaborative applications, real-time chat, multiplayer games and more without needing to coordinate state or manage infrastructure. - - @@ -27,6 +23,8 @@ Durable Objects provide a powerful compute API for coordinating multiple clients Use Durable Objects to build collaborative editing tools, interactive chat, multiplayer games and applications that need coordination among multiple clients, without requiring you to build serialization and coordination primitives on your own. +Get started + :::note[SQLite in Durable Objects Beta] The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can [opt-in to a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) in order to access new [SQL API](/durable-objects/api/storage-api/#sqlexec) and [point-in-time-recovery API](/durable-objects/api/storage-api/#point-in-time-recovery), part of Durable Objects Storage API. diff --git a/src/content/docs/durable-objects/observability/graphql-analytics.mdx b/src/content/docs/durable-objects/observability/graphql-analytics.mdx index 1ba39c324ebf6d..1fbe1eba544bb9 100644 --- a/src/content/docs/durable-objects/observability/graphql-analytics.mdx +++ b/src/content/docs/durable-objects/observability/graphql-analytics.mdx @@ -6,13 +6,15 @@ sidebar: --- -Durable Objects expose analytics for Durable Object namespace-level and request-level metrics. +import { GlossaryTooltip } from "~/components"; + +Durable Objects expose analytics for Durable Object namespace-level and request-level metrics. The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically via GraphQL](#query-via-the-graphql-api) or HTTP client. :::note[Durable Object namespace] -A Durable Object namespace is a set of Durable Objects that can be addressed by name, backed by the same class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects. +A Durable Object namespace is a set of Durable Objects that can be addressed by name, backed by the same class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects. ::: ## View metrics and analytics via the dashboard @@ -51,10 +53,10 @@ Durable Objects using [WebSockets](/durable-objects/reference/websockets/) will ```js viewer { - /* + /* Replace with your account tag, the 32 hex character id visible at the beginning of any url - when logged in to dash.cloudflare.com or under "Account ID" on the sidebar of the Workers & Pages Overview - */ + when logged in to dash.cloudflare.com or under "Account ID" on the sidebar of the Workers & Pages Overview + */ accounts(filter: {accountTag: "your account tag here"}) { // Replace dates with a recent date durableObjectsInvocationsAdaptiveGroups(filter: {date_gt: "2023-05-23"}, limit: 1000) { diff --git a/src/content/docs/durable-objects/observability/index.mdx b/src/content/docs/durable-objects/observability/index.mdx index 0a019bda97134b..d9f4464f490331 100644 --- a/src/content/docs/durable-objects/observability/index.mdx +++ b/src/content/docs/durable-objects/observability/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Observability sidebar: - order: 5 + order: 6 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/platform/index.mdx b/src/content/docs/durable-objects/platform/index.mdx index fe7a16eca104db..8b14ea8352a012 100644 --- a/src/content/docs/durable-objects/platform/index.mdx +++ b/src/content/docs/durable-objects/platform/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Platform sidebar: - order: 8 + order: 10 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/platform/known-issues.mdx b/src/content/docs/durable-objects/platform/known-issues.mdx index 7fe2020e3ac498..6e2ff0d3af7067 100644 --- a/src/content/docs/durable-objects/platform/known-issues.mdx +++ b/src/content/docs/durable-objects/platform/known-issues.mdx @@ -4,11 +4,13 @@ title: Known issues --- +import { GlossaryTooltip } from "~/components"; + Durable Objects is generally available. However, there are some known issues. ## Global uniqueness -Global uniqueness guarantees there is only a single instance of a Durable Object class with a given ID running at once, across the world. +Global uniqueness guarantees there is only a single instance of a Durable Object class with a given ID running at once, across the world. Uniqueness is enforced upon starting a new event (such as receiving an HTTP request), and upon accessing storage. diff --git a/src/content/docs/durable-objects/platform/limits.mdx b/src/content/docs/durable-objects/platform/limits.mdx index 1b2c053ef6c93b..36e3110b1d10a7 100644 --- a/src/content/docs/durable-objects/platform/limits.mdx +++ b/src/content/docs/durable-objects/platform/limits.mdx @@ -6,7 +6,7 @@ sidebar: --- -import { Render } from "~/components"; +import { Render, GlossaryTooltip } from "~/components"; Durable Objects are only available on the [Workers Paid plan](/workers/platform/pricing/#workers). Durable Objects limits are the same as [Workers Limits](/workers/platform/limits/), as well as the following limits that are specific to Durable Objects: @@ -58,6 +58,6 @@ A Durable Object that receives too many requests will, after attempting to queue Durable Objects are designed such that the number of individual objects in the system do not need to be limited, and can scale horizontally. -- You can create and run as many separate Durable Objects as you want within a given Durable Object namespace. +- You can create and run as many separate Durable Objects as you want within a given Durable Object namespace. - The main limit to your usage of Durable Objects is the total storage limit per account. - If you need more storage, contact your account team or complete the [Limit Increase Request Form](https://forms.gle/ukpeZVLWLnKeixDu7) and we will contact you with next steps. diff --git a/src/content/docs/durable-objects/reference/data-location.mdx b/src/content/docs/durable-objects/reference/data-location.mdx index 60f1ce63c86689..176475c99cdba5 100644 --- a/src/content/docs/durable-objects/reference/data-location.mdx +++ b/src/content/docs/durable-objects/reference/data-location.mdx @@ -5,9 +5,11 @@ sidebar: order: 8 --- +import { GlossaryTooltip } from "~/components"; + ## Restrict Durable Objects to a jurisdiction -Jurisdictions are used to create Durable Objects 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/). +Jurisdictions are used to create Durable Objects 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. diff --git a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx index 30124ba3e634c1..3ee8256da8bade 100644 --- a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx +++ b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx @@ -6,11 +6,13 @@ sidebar: --- +import { GlossaryTooltip } from "~/components"; + A migration is a mapping process from a class name to a runtime state. You must initiate a migration process when you: -* Create a new Durable Object class. +* Create a new Durable Object class. * Rename a Durable Object class. * Delete a Durable Object class. * Transfer an existing Durable Objects class. diff --git a/src/content/docs/durable-objects/glossary.mdx b/src/content/docs/durable-objects/reference/glossary.mdx similarity index 95% rename from src/content/docs/durable-objects/glossary.mdx rename to src/content/docs/durable-objects/reference/glossary.mdx index 311ad3571b9c01..e45c9a0059abdf 100644 --- a/src/content/docs/durable-objects/glossary.mdx +++ b/src/content/docs/durable-objects/reference/glossary.mdx @@ -2,7 +2,7 @@ title: Glossary pcx_content_type: glossary sidebar: - order: 10 + order: 12 --- diff --git a/src/content/docs/durable-objects/reference/in-memory-state.mdx b/src/content/docs/durable-objects/reference/in-memory-state.mdx index d862330caa245b..c34016efc3f5e8 100644 --- a/src/content/docs/durable-objects/reference/in-memory-state.mdx +++ b/src/content/docs/durable-objects/reference/in-memory-state.mdx @@ -5,7 +5,9 @@ sidebar: order: 1 --- -In-memory state means that each Durable Object has one active instance at any particular time. All requests sent to that Durable Object are handled by that same instance. You can store some state in memory. +import { GlossaryTooltip } from "~/components"; + +In-memory state means that each Durable Object has one active instance at any particular time. All requests sent to that Durable Object are handled by that same instance. You can store some state in memory. Variables in a Durable Object will maintain state as long as your Durable Object is not evicted from memory. diff --git a/src/content/docs/durable-objects/reference/index.mdx b/src/content/docs/durable-objects/reference/index.mdx index 3daad7052a171b..b007e3d2bb291a 100644 --- a/src/content/docs/durable-objects/reference/index.mdx +++ b/src/content/docs/durable-objects/reference/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Reference sidebar: - order: 9 + order: 11 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/tutorials/index.mdx b/src/content/docs/durable-objects/tutorials/index.mdx index df38d89638d4d9..4b27c27c797379 100644 --- a/src/content/docs/durable-objects/tutorials/index.mdx +++ b/src/content/docs/durable-objects/tutorials/index.mdx @@ -4,7 +4,7 @@ pcx_content_type: navigation title: Tutorials hideChildren: true sidebar: - order: 7 + order: 8 --- diff --git a/src/content/glossary/durable-objects.yaml b/src/content/glossary/durable-objects.yaml index 60843c60f27a83..301dd452fe6a61 100644 --- a/src/content/glossary/durable-objects.yaml +++ b/src/content/glossary/durable-objects.yaml @@ -11,7 +11,7 @@ entries: - term: "Durable Object" general_definition: |- - An individual instance of a Durable Object class. A Durable Object is globally unique (referenced by ID), provides a global point of coordination for all methods/requests sent to it, and has private, persistent storage that is not shared with other Durable Objects within a namespace. + A Durable Object is an individual instance of a Durable Object class. A Durable Object is globally unique (referenced by ID), provides a global point of coordination for all methods/requests sent to it, and has private, persistent storage that is not shared with other Durable Objects within a namespace. - term: "stub" general_definition: |-