From 827a40d255e09aa84646ec238f850cc3c77c9f3f Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 16:40:13 +0000 Subject: [PATCH 01/11] Setting up new page. --- src/content/docs/durable-objects/api/index.mdx | 2 +- src/content/docs/durable-objects/best-practices/index.mdx | 2 +- src/content/docs/durable-objects/changelog.mdx | 2 +- src/content/docs/durable-objects/demos.mdx | 2 +- .../docs/durable-objects/durable-objects-rest-api.mdx | 2 +- src/content/docs/durable-objects/examples/index.mdx | 2 +- src/content/docs/durable-objects/get-started/index.mdx | 2 +- src/content/docs/durable-objects/index.mdx | 2 +- src/content/docs/durable-objects/observability/index.mdx | 2 +- src/content/docs/durable-objects/platform/index.mdx | 2 +- src/content/docs/durable-objects/reference/index.mdx | 2 +- src/content/docs/durable-objects/tutorials/index.mdx | 2 +- .../docs/durable-objects/what-are-durable-objects.mdx | 7 +++++++ 13 files changed, 19 insertions(+), 12 deletions(-) create mode 100644 src/content/docs/durable-objects/what-are-durable-objects.mdx 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/index.mdx b/src/content/docs/durable-objects/index.mdx index 31e68050326598..9618998a04d95f 100644 --- a/src/content/docs/durable-objects/index.mdx +++ b/src/content/docs/durable-objects/index.mdx @@ -21,7 +21,7 @@ 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? 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..681a34c6c78102 --- /dev/null +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -0,0 +1,7 @@ +--- +title: What are Durable Objects? +pcx_content_type: concept +sidebar: + order: 2 + +--- \ No newline at end of file From f8adaa2ebb9d3a536b4ed3dd8e9df58fa905b29b Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:25:41 +0000 Subject: [PATCH 02/11] Adding the bulk of the chapter. --- .../what-are-durable-objects.mdx | 109 +++++++++++++++++- 1 file changed, 108 insertions(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index 681a34c6c78102..dc4cc5473bab76 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -4,4 +4,111 @@ pcx_content_type: concept sidebar: order: 2 ---- \ No newline at end of file +--- + +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. + +## Durable Object highlights + +Durable Objects have properties and capabilities 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), 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 the 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 Object 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. \ No newline at end of file From 9f057b7d153a2ffa0a6b3cb812a77821f125effd Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:31:50 +0000 Subject: [PATCH 03/11] Update src/content/docs/durable-objects/what-are-durable-objects.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index dc4cc5473bab76..fbc918d374d8f7 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -19,7 +19,7 @@ Durable Objects have properties and capabilities that make them a great fit for **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. +- 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. From 0049194078c8652c38f2477be58b4b9c5c340f71 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:32:04 +0000 Subject: [PATCH 04/11] Update src/content/docs/durable-objects/what-are-durable-objects.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index fbc918d374d8f7..1ff3c17edc9bd1 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -30,7 +30,7 @@ Durable Objects have properties and capabilities that make them a great fit for **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 the 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/). +- Durable Objects are single-threaded and cooperatively multi-tasked, just like code running in the 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** From 4f9bec0f0a0e1c84ed3254674d5f72a011d38ea5 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:32:12 +0000 Subject: [PATCH 05/11] Update src/content/docs/durable-objects/what-are-durable-objects.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index 1ff3c17edc9bd1..dc5c0a66d4af37 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -35,7 +35,7 @@ Durable Objects have properties and capabilities that make them a great fit for **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. +- 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 Object features From 2b1f51ead74498998f51c8497f5b0ed53c056826 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:36:02 +0000 Subject: [PATCH 06/11] Adding links from other pages to the new chapter. --- .../docs/durable-objects/get-started/tutorial-with-sql-api.mdx | 2 ++ src/content/docs/durable-objects/get-started/tutorial.mdx | 2 ++ src/content/docs/durable-objects/index.mdx | 2 ++ 3 files changed, 6 insertions(+) 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 1527e77108a4ee..38b51c147a20ce 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 9618998a04d95f..e84d82274141da 100644 --- a/src/content/docs/durable-objects/index.mdx +++ b/src/content/docs/durable-objects/index.mdx @@ -32,6 +32,8 @@ A Durable Object is a special kind of [Worker](/workers/). Like a Worker, it is Thus, Durable Objects enable **stateful** serverless applications. +For more information, refer to [What are Durable Objects?](/durable-objects/what-are-durable-objects/) + Get started :::note[SQLite in Durable Objects Beta] From 59bc0fa3de6b648aa44998ee41a0dbd1e0eb63eb Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 30 Jan 2025 18:36:47 +0000 Subject: [PATCH 07/11] Update src/content/docs/durable-objects/what-are-durable-objects.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index dc5c0a66d4af37..cac22a1043fa5a 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -30,7 +30,7 @@ Durable Objects have properties and capabilities that make them a great fit for **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 the 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/). +- Durable Objects are single-threaded and cooperatively multi-tasked, just like code running in the 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** From f31c45bc608feac6f58b3bbfb241cb94cece97b0 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 31 Jan 2025 09:44:42 +0000 Subject: [PATCH 08/11] Implementing the feedback part 1. --- src/content/docs/durable-objects/index.mdx | 13 ++++--------- .../what-are-durable-objects.mdx | 17 +++++++---------- .../what-are-durable-objects.mdx | 10 ++++++++++ 3 files changed, 21 insertions(+), 19 deletions(-) create mode 100644 src/content/partials/durable-objects/what-are-durable-objects.mdx diff --git a/src/content/docs/durable-objects/index.mdx b/src/content/docs/durable-objects/index.mdx index e84d82274141da..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. @@ -23,16 +23,11 @@ Durable Objects provide a building block for stateful applications and distribut 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 [What are Durable Objects?](/durable-objects/what-are-durable-objects/) +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/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index cac22a1043fa5a..b366f86bbe4386 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -6,16 +6,13 @@ sidebar: --- -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: +import { Render } from "~/components"; -- 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. +## Durable Objects highlights -## Durable Object highlights - -Durable Objects have properties and capabilities that make them a great fit for distributed stateful scalable applications. +Durable Objects have properties that make them a great fit for distributed stateful scalable applications. **Serverless compute, zero infrastructure management** @@ -30,7 +27,7 @@ Durable Objects have properties and capabilities that make them a great fit for **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 the 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/). +- 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** @@ -38,7 +35,7 @@ Durable Objects have properties and capabilities that make them a great fit for - 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 Object features +## Durable Objects features ### In-memory state @@ -111,4 +108,4 @@ Finally, the following blog posts may help you learn some of the technical imple ## 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. \ No newline at end of file +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. \ 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 From 2936ad2a35ee2c67bc7c8c1f082aced91cfc49e7 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 31 Jan 2025 09:45:39 +0000 Subject: [PATCH 09/11] Removing unnecessary italics. --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index b366f86bbe4386..80d24222b372cb 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -27,7 +27,7 @@ Durable Objects have properties that make them a great fit for distributed state **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/). +- 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** From 2a84c23a883e492a0b663631e201217a262e45ce Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 31 Jan 2025 10:10:26 +0000 Subject: [PATCH 10/11] Making key-value consistent with rest of Docs. --- src/content/docs/durable-objects/what-are-durable-objects.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index 80d24222b372cb..8832a48c6b7d8a 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -49,9 +49,9 @@ In-memory state is reset when the Durable Object hibernates after being idle for 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/). +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. +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 From 7f509ed21bc8b89203589a5f5821706bc772450c Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Fri, 31 Jan 2025 10:39:17 +0000 Subject: [PATCH 11/11] Adding supplementary info on DO storage. --- .../docs/durable-objects/what-are-durable-objects.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/what-are-durable-objects.mdx b/src/content/docs/durable-objects/what-are-durable-objects.mdx index 8832a48c6b7d8a..c2318de1818eb8 100644 --- a/src/content/docs/durable-objects/what-are-durable-objects.mdx +++ b/src/content/docs/durable-objects/what-are-durable-objects.mdx @@ -22,7 +22,7 @@ Durable Objects have properties that make them a great fit for distributed state **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), persisted across requests, and accessible only within that object. +- 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** @@ -108,4 +108,6 @@ Finally, the following blog posts may help you learn some of the technical imple ## 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. \ No newline at end of file +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