What are Durable Objects? · Cloudflare Durable Objects docs (original) (raw)

A Durable Object is a special kind of Cloudflare Worker 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 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. 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 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 (up to 10 GB1), persisted across requests, and accessible only within that object.

Single-threaded concurrency

Each Durable Object instance has an identifier, 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" ↗.

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 are not yet available in every Cloudflare data center; refer to the where.durableobjects.live ↗ project for live locations.
Each Durable Object type (or "Namespace binding" 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. 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 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 and an SQL API.

When using the new SQLite in Durable Objects storage backend, 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 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, as well as the WebSockets 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) 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 ↗. There are several popular examples of the Actor model supported at the programming language level through runtimes or library frameworks, like Erlang ↗, Elixir ↗, Akka ↗, or Microsoft Orleans for .NET ↗.

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, which should influence the application's architecture to fully take advantage of the platform.

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 serve as inspiration on how to architect scalable applications using Durable Objects, and how to integrate them with the rest of Cloudflare Developer Platform.

Finally, the following blog posts may help you learn some of the technical implementation aspects of Durable Objects, and how they work.

Get started

Get started now by following the "Get started" guide to create your first application using Durable Objects.

Storage per Durable Object with SQLite is currently 1 GB. This will be raised to 10 GB for general availability. ↩