diff --git a/src/content/docs/durable-objects/api/index.mdx b/src/content/docs/durable-objects/api/index.mdx index dfb5b4a5b60bb9..6308679d216ed9 100644 --- a/src/content/docs/durable-objects/api/index.mdx +++ b/src/content/docs/durable-objects/api/index.mdx @@ -2,7 +2,7 @@ title: Workers Binding API pcx_content_type: navigation sidebar: - order: 4 + order: 5 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/best-practices/index.mdx b/src/content/docs/durable-objects/best-practices/index.mdx index 57f21ba7643ffc..003f10c058d8e1 100644 --- a/src/content/docs/durable-objects/best-practices/index.mdx +++ b/src/content/docs/durable-objects/best-practices/index.mdx @@ -2,7 +2,7 @@ title: Best practices pcx_content_type: navigation sidebar: - order: 3 + order: 4 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/changelog.mdx b/src/content/docs/durable-objects/changelog.mdx index d0be4e937f0209..21f060a49073f9 100644 --- a/src/content/docs/durable-objects/changelog.mdx +++ b/src/content/docs/durable-objects/changelog.mdx @@ -4,7 +4,7 @@ title: Changelog changelog_file_name: - durable-objects sidebar: - order: 14 + order: 15 --- import { ProductChangelog } from "~/components"; diff --git a/src/content/docs/durable-objects/demos.mdx b/src/content/docs/durable-objects/demos.mdx index 66b63a35c2c45b..3471e8c472fc10 100644 --- a/src/content/docs/durable-objects/demos.mdx +++ b/src/content/docs/durable-objects/demos.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Demos and architectures sidebar: - order: 9 + order: 10 --- 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 bb31483101a657..0f2b349237a8ac 100644 --- a/src/content/docs/durable-objects/durable-objects-rest-api.mdx +++ b/src/content/docs/durable-objects/durable-objects-rest-api.mdx @@ -3,6 +3,6 @@ pcx_content_type: navigation title: REST API external_link: /api/resources/durable_objects/subresources/namespaces/methods/list/ sidebar: - order: 5 + order: 6 --- diff --git a/src/content/docs/durable-objects/examples/index.mdx b/src/content/docs/durable-objects/examples/index.mdx index 614db9572a3a54..5633c8a5350ed1 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: 7 + order: 8 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/get-started/index.mdx b/src/content/docs/durable-objects/get-started/index.mdx index d64864ac0a09c0..2fb8ad571f459c 100644 --- a/src/content/docs/durable-objects/get-started/index.mdx +++ b/src/content/docs/durable-objects/get-started/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Get started sidebar: - order: 2 + order: 3 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx index d4109b7f3967a8..4538c4c2fe25ce 100644 --- a/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx +++ b/src/content/docs/durable-objects/get-started/tutorial-with-sql-api.mdx @@ -14,6 +14,8 @@ This guide will instruct you through: - Instantiating and communicating with a Durable Object from another Worker. - Deploying a Durable Object and a Worker that communicates with a Durable Object. +If you wish to learn more about Durable Objects, refer to [What are Durable Objects?](/durable-objects/what-are-durable-objects/). + :::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/sql-storage/#exec), part of Durable Objects Storage API. diff --git a/src/content/docs/durable-objects/get-started/tutorial.mdx b/src/content/docs/durable-objects/get-started/tutorial.mdx index a8221ba79ffd3f..d45151975e4f62 100644 --- a/src/content/docs/durable-objects/get-started/tutorial.mdx +++ b/src/content/docs/durable-objects/get-started/tutorial.mdx @@ -13,6 +13,8 @@ This guide will instruct you through: - Writing a Worker which invokes methods on a Durable Object. - Deploying a Durable Object. +If you wish to learn more about Durable Objects, refer to [What are Durable Objects?](/durable-objects/what-are-durable-objects/). + ## Prerequisites diff --git a/src/content/docs/durable-objects/index.mdx b/src/content/docs/durable-objects/index.mdx index 31e68050326598..15be50ea880416 100644 --- a/src/content/docs/durable-objects/index.mdx +++ b/src/content/docs/durable-objects/index.mdx @@ -11,7 +11,7 @@ head: --- -import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, LinkButton } from "~/components" +import { Render, 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. @@ -21,16 +21,13 @@ Create collaborative applications, real-time chat, multiplayer games and more wi Durable Objects provide a building block for stateful applications and distributed systems. -Use Durable Objects to build applications that need cordination among multiple clients, like collaborative editing tools, interactive chat, multiplayer games, and deep distributed systems, without requiring you to build serialization and coordination primitives on your own. +Use Durable Objects to build applications that need coordination among multiple clients, like collaborative editing tools, interactive chat, multiplayer games, and deep distributed systems, without requiring you to build serialization and coordination primitives on your own. -### What is a Durable Object? +### What are Durable Objects? -A Durable Object is a special kind of [Worker](/workers/). Like a Worker, it is automatically provisioned geographically close to where it is requested, it starts up quickly when needed and shuts down when idle, and you can have millions of them around the world. However, unlike regular Workers: + -* Each object has a **globally-unique name**, allowing you to send requests to a specific object from anywhere in the world. Thus, a Durable Object can be used to coordinate between multiple clients who need to work together. -* Each object has some **durable storage** attached. Since this storage lives together with the object, it is strongly consistent yet fast to access. - -Thus, Durable Objects enable **stateful** serverless applications. +For more information, refer to the full [What are Durable Objects?](/durable-objects/what-are-durable-objects/) page. Get started diff --git a/src/content/docs/durable-objects/observability/index.mdx b/src/content/docs/durable-objects/observability/index.mdx index d9f4464f490331..b1c6ce8d4f82c4 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: 6 + order: 7 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/platform/index.mdx b/src/content/docs/durable-objects/platform/index.mdx index 8b14ea8352a012..7c3c97f7b5320e 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: 10 + order: 11 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/reference/index.mdx b/src/content/docs/durable-objects/reference/index.mdx index b007e3d2bb291a..9dafbc86d4897b 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: 11 + order: 12 group: hideIndex: true --- diff --git a/src/content/docs/durable-objects/tutorials/index.mdx b/src/content/docs/durable-objects/tutorials/index.mdx index 4b27c27c797379..86d95e33bd4444 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: 8 + order: 9 --- diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx new file mode 100644 index 00000000000000..c2318de1818eb8 --- /dev/null +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -0,0 +1,113 @@ +--- +title: What are Durable Objects? +pcx_content_type: concept +sidebar: + order: 2 + +--- + +import { Render } from "~/components"; + + + +## Durable Objects highlights + +Durable Objects have properties that make them a great fit for distributed stateful scalable applications. + +**Serverless compute, zero infrastructure management** + +- Durable Objects are built on-top of the Workers runtime, so they support exactly the same code (JavaScript and WASM), and similar memory and CPU limits. +- Each Durable Object is [implicitly created on first access](/durable-objects/api/namespace/#get). User applications are not concerned with their lifecycle, creating them or destroying them. Durable Objects migrate among healthy servers, and therefore applications never have to worry about managing them. +- Each Durable Object stays alive as long as requests are being processed, and remains alive for several seconds after being idle before hibernating, allowing applications to [exploit in-memory caching](/durable-objects/reference/in-memory-state/) while handling many consecutive requests and boosting their performance. + +**Storage colocated with compute** + +- Each Durable Object has its own [durable, transactional, and strongly consistent storage](/durable-objects/api/storage-api/) (up to 10 GB[^1]), persisted across requests, and accessible only within that object. + +**Single-threaded concurrency** + +- Each [Durable Object instance has an identifier](/durable-objects/api/id/), either randomly-generated or user-generated, which allows you to globally address which Durable Object should handle a specific action or request. +- Durable Objects are single-threaded and cooperatively multi-tasked, just like code running in a web browser. For more details on how safety and correctness are achieved, refer to the blog post ["Durable Objects: Easy, Fast, Correct — Choose three"](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). + +**Elastic horizontal scaling across Cloudflare's global network** + +- Durable Objects can be spread around the world, and you can [optionally influence where each instance should be located](/durable-objects/reference/data-location/#provide-a-location-hint). Durable Objects are not yet available in every Cloudflare data center; refer to the [where.durableobjects.live](https://where.durableobjects.live/) project for live locations. +- Each Durable Object type (or ["Namespace binding"](/durable-objects/api/namespace/) in Cloudflare terms) corresponds to a JavaScript class implementing the actual logic. There is no hard limit on how many Durable Objects can be created for each namespace. +- Durable Objects scale elastically as your application creates millions of objects. There is no need for applications to manage infrastructure or plan ahead for capacity. + +## Durable Objects features + +### In-memory state + +Each Durable Object has its own [in-memory state](/durable-objects/reference/in-memory-state/). Applications can use this in-memory state to optimize the performance of their applications by keeping important information in-memory, thereby avoiding the need to access the durable storage at all. + +Useful cases for in-memory state include batching and aggregating information before persisting it to storage, or for immediately rejecting/handling incoming requests meeting certain criteria, and more. + +In-memory state is reset when the Durable Object hibernates after being idle for some time. Therefore, it is important to persist any in-memory data to the durable storage if that data will be needed at a later time when the Durable Object receives another request. + +### Storage API + +The [Durable Object Storage API](/durable-objects/api/storage-api/) allows Durable Objects to access fast, transactional, and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects. + +There are two flavors of the storage API, a [key-value (KV) API](/durable-objects/api/storage-api/#methods) and an [SQL API](/durable-objects/api/sql-storage/). + +When using the [new SQLite in Durable Objects storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration), you have access to both the APIs. However, if you use the previous storage backend you only have access to the key-value API. + +### Alarms API + +Durable Objects provide an [Alarms API](/durable-objects/api/alarms/) which allows you to schedule the Durable Object to be woken up at a time in the future. This is useful when you want to do certain work periodically, or at some specific point in time, without having to manually manage infrastructure such as job scheduling runners on your own. + +You can combine Alarms with in-memory state and the durable storage API to build batch and aggregation applications such as queues, workflows, or advanced data pipelines. + +### WebSockets + +WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server. Because WebSocket sessions are long-lived, applications commonly use Durable Objects to accept either the client or server connection. + +Because Durable Objects provide a single-point-of-coordination between Cloudflare Workers, a single Durable Object instance can be used in parallel with WebSockets to coordinate between multiple clients, such as participants in a chat room or a multiplayer game. + +Durable Objects support the [WebSocket Standard API](/durable-objects/best-practices/websockets/#websocket-standard-api), as well as the [WebSockets Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api) which extends the Web Standard WebSocket API to reduce costs by not incurring billing charges during periods of inactivity. + +### RPC + +Durable Objects support Workers [Remote-Procedure-Call (RPC)](/workers/runtime-apis/rpc/) which allows applications to use JavaScript-native methods and objects to communicate between Workers and Durable Objects. + +Using RPC for communication makes application development easier and simpler to reason about, and more efficient. + +## Actor programming model + +Another way to describe and think about Durable Objects is through the lens of the [Actor programming model](https://en.wikipedia.org/wiki/Actor_model). There are several popular examples of the Actor model supported at the programming language level through runtimes or library frameworks, like [Erlang](https://www.erlang.org/), [Elixir](https://elixir-lang.org/), [Akka](https://akka.io/), or [Microsoft Orleans for .NET](https://learn.microsoft.com/en-us/dotnet/orleans/overview). + +The Actor model simplifies a lot of problems in distributed systems by abstracting away the communication between actors using RPC calls (or message sending) that could be implemented on-top of any transport protocol, and it avoids most of the concurrency pitfalls you get when doing concurrency through shared memory such as race conditions when multiple processes/threads access the same data in-memory. + +Each Durable Object instance can be seen as an Actor instance, receiving messages (incoming HTTP/RPC requests), executing some logic in its own single-threaded context using its attached durable storage or in-memory state, and finally sending messages to the outside world (outgoing HTTP/RPC requests or responses), even to another Durable Object instance. + +Each Durable Object has certain capabilities in terms of [how much work it can do](/durable-objects/platform/limits/#how-much-work-can-a-single-durable-object-do), which should influence the application's [architecture to fully take advantage of the platform](/reference-architecture/diagrams/storage/durable-object-control-data-plane-pattern/). + +Durable Objects are natively integrated into Cloudflare's infrastructure, giving you the ultimate serverless platform to build distributed stateful applications exploiting the entirety of Cloudflare's network. + +## Durable Objects in Cloudflare + +Many of Cloudflare's products use Durable Objects. Some of our technical blog posts showcase real-world applications and use-cases where Durable Objects make building applications easier and simpler. + +These blog posts may also server as inspiration on how to architect scalable applications using Durable Objects, and how to integrate them with the rest of Cloudflare Developer Platform. + +- [Durable Objects aren't just durable, they're fast: a 10x speedup for Cloudflare Queues](https://blog.cloudflare.com/how-we-built-cloudflare-queues/) +- [Behind the scenes with Stream Live, Cloudflare's live streaming service](https://blog.cloudflare.com/behind-the-scenes-with-stream-live-cloudflares-live-streaming-service/) +- [DO it again: how we used Durable Objects to add WebSockets support and authentication to AI Gateway](https://blog.cloudflare.com/do-it-again/) +- [Workers Builds: integrated CI/CD built on the Workers platform](https://blog.cloudflare.com/workers-builds-integrated-ci-cd-built-on-the-workers-platform/) +- [Build durable applications on Cloudflare Workers: you write the Workflows, we take care of the rest](https://blog.cloudflare.com/building-workflows-durable-execution-on-workers/) +- [Building D1: a Global Database](https://blog.cloudflare.com/building-d1-a-global-database/) +- [Billions and billions (of logs): scaling AI Gateway with the Cloudflare Developer Platform](https://blog.cloudflare.com/billions-and-billions-of-logs-scaling-ai-gateway-with-the-cloudflare/) +- [Indexing millions of HTTP requests using Durable Objects](https://blog.cloudflare.com/r2-rayid-retrieval/) + +Finally, the following blog posts may help you learn some of the technical implementation aspects of Durable Objects, and how they work. + +- [Durable Objects: Easy, Fast, Correct — Choose three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/) +- [Zero-latency SQLite storage in every Durable Object](https://blog.cloudflare.com/sqlite-in-durable-objects/) +- [Workers Durable Objects Beta: A New Approach to Stateful Serverless](https://blog.cloudflare.com/introducing-workers-durable-objects/) + +## Get started + +Get started now by following the ["Tutorial with SQL API"](/durable-objects/get-started/tutorial-with-sql-api/) to create your first application using Durable Objects. + +[^1]: Storage per Durable Object with SQLite is currently 1 GB. This will be raised to 10 GB for general availability. \ No newline at end of file diff --git a/src/content/partials/durable-objects/what-are-durable-objects.mdx b/src/content/partials/durable-objects/what-are-durable-objects.mdx new file mode 100644 index 00000000000000..15b96c85f0f37a --- /dev/null +++ b/src/content/partials/durable-objects/what-are-durable-objects.mdx @@ -0,0 +1,10 @@ +--- +{} +--- + +A Durable Object is a special kind of [Cloudflare Worker](/workers/) which uniquely combines compute with storage. Like a Worker, a Durable Object is automatically provisioned geographically close to where it is first requested, starts up quickly when needed, and shuts down when idle. You can have millions of them around the world. However, unlike regular Workers: + +- Each Durable Object has a **globally-unique name**, which allows you to send requests to a specific object from anywhere in the world. Thus, a Durable Object can be used to coordinate between multiple clients who need to work together. +- Each Durable Object has some **durable storage** attached. Since this storage lives together with the object, it is strongly consistent yet fast to access. + +Therefore, Durable Objects enable **stateful** serverless applications. \ No newline at end of file