Thoughts on Cloudflare Durable Objects

To begin, I’m a big fan of Cloudflare the company as well as the Workers platforms in general. They’ve been really busy improving the DX for working with Cloudflare, which had been by far the

hardest part of working with Cloudflare.

Now if you know Cloudflare, you know their Durable Objects product. It’s positioned to fill the “durable storage” problem with serverless. On its own, it’s an amazing technology and primitive to build on. But that’s just it — it’s something to build on top of. Think of it like an AWS EC2 instance: yes,

for certain markets they can’t use anything but that, but it’s also a primitive where other popular products like RDS and Fargate are built upon. A Durable Object is an amazing primitive — it can do a

lot of things: it can be a WebSocket server, high-speed consistent storage, or it can be a DB, a scheduler, and many other things. But that’s the problem — it can be used in a bunch of differentways which makes it harder to understand. Imagine a different timeline where these shipped as different products: “a fast highly consistent key-value storage,” “a WebSocket implementation,” “a fast DB (that supports transactions cough cough D1 cough),” etc… You see where I’m going with this, right? And this is not entirely new — a few projects have taken on some of these aspects https://starbasedb.com/, https://www.partykit.io/, and https://github.com/cloudflare/agents to name a few. These have grown in popularity mostly because of their ease of use, which is inherently because they have a specific target in mind.

But what we have currently looks something like this…

Oh, I want to implement a simple rate limiter or session storage. Okay, KV is eventually consistent so maybe no to that, but hey, Durable Objects seem to fit this profile… Okay, how do I use this again? I open up the docs for this, and ooh they have a handy example here, but what does all this other stuff mean? “I came here for a consistent fast KV.” Okay, maybe let me try a simpler example — a counter… Okay, this looks manageable. I have this.ctx.storage which exposes what I wanted in the first place…

import { DurableObject } from "cloudflare:workers";

// Worker
export default {
  async fetch(request, env) {
    let url = new URL(request.url);
    let name = url.searchParams.get("name");
    if (!name) {
      return new Response(
        "Select a Durable Object to contact by using" +
          " the `name` URL query string parameter, for example, ?name=A",
      );
    }

    // Every unique ID refers to an individual instance of the Counter class that
    // has its own state. `idFromName()` always returns the same ID when given the
    // same string as input (and called on the same class), but never the same
    // ID for two different strings (or for different classes).
    let id = env.COUNTERS.idFromName(name);

    // Construct the stub for the Durable Object using the ID.
    // A stub is a client Object used to send messages to the Durable Object.
    let stub = env.COUNTERS.get(id);

    // Send a request to the Durable Object using RPC methods, then await its response.
    let count = null;
    switch (url.pathname) {
      case "/increment":
        count = await stub.increment();
        break;
      case "/decrement":
        count = await stub.decrement();
        break;
      case "/":
        // Serves the current value.
        count = await stub.getCounterValue();
        break;
      default:
        return new Response("Not found", { status: 404 });
    }

    return new Response(`Durable Object '${name}' count: ${count}`);
  },
};

// Durable Object
export class Counter extends DurableObject {
  async getCounterValue() {
    let value = (await this.ctx.storage.get("value")) || 0;
    return value;
  }

  async increment(amount = 1) {
    let value = (await this.ctx.storage.get("value")) || 0;
    value += amount;
    // You do not have to worry about a concurrent request having modified the value in storage.
    // "input gates" will automatically protect against unwanted concurrency.
    // Read-modify-write is safe.
    await this.ctx.storage.put("value", value);
    return value;
  }

  async decrement(amount = 1) {
    let value = (await this.ctx.storage.get("value")) || 0;
    value -= amount;
    await this.ctx.storage.put("value", value);
    return value;
  }
}

okay now I have to introduce this to my existing app, would it be better to move the logic for adding the data into class itself maybe so seems to be the way it’s done on the docs

//kv.ts
export class KV extends DurableObject {

  async set(key,value) {
    try {
    await this.ctx.storage.put(key, value);
    return Result.ok(value);
    } catch(err){
     Result.err(err)
    }
  }
  async get(key){
  try {
    await this.ctx.storage.get(key);
    return Result.ok(value);
    } catch(err){
     Result.err(err)
    }
    }
}

// helper.ts
import type { DurableObject } from 'cloudflare:workers'

// Simple durable object accessor
export const durable = <T extends DurableObject>(
	namespace: DurableObjectNamespace,
) => {
	return {
		current: (id: string) => {
			const identifier = namespace.idFromName(id)
			return namespace.get(identifier) as DurableObjectStub<T>
		},
	}
}

// server.ts
// in the middleware somewhere 
 c.set("kv",durable(c.env.KV));

app.get("/customers/:cid", anyAuth(["read"]), async (c) => {
  const org= await kv.get(c.vars.organization_id)
  // this won't work
  const sessions= org.unwrap()
  const customer = await Customers.byId(c.req.param("cid"), c.var.db);
 
  return c.json(customer.unwrap());
});

This then doesn’t work. I missed the part of the docs that says these are actually RPC calls to another “DurableObject” instance, so they don’t exactly behave as you would expect…

So I came here for KV, and now I’m here figuring out RPC calls and that I had to export the Durable Object class in my worker entry point. And on top of this, I’m still not even sure if this is the “correct” way to do things. Now imagine an alternate dimension where all I had to do for this was

	"supa_fast_kv_namespaces": [
		{
			"binding": "SESSION",
			"id": "some_name"
		}
	],

(Obviously with a better name than this) but now all i have to do in my app is

app.get("/customers/:cid", anyAuth(["read"]), async (c) => {
  const org= await env.SESSION.get(c.vars.organization_id)
 
  const customer = await Customers.byId(c.req.param("cid"), c.var.db);
  return c.json(customer.unwrap());
});

or I can have my helper which would handle errors the way we already do

export const session= {
byOrganizationId:async (id:string)=>{
try{
    const org= await env.SESSION.get(c.vars.organization_id)
    return Result.ok(org)
    }catch(e){
    return Result.err(e)
    }
  }
}

This is much easier — I didn’t have to go through all of that other stuff just to get to what I actually needed. Now, this is just a grossly oversimplified example here, but hopefully you can see the pattern. I didn’t have to change my workflow, I didn’t have to figure anything else out besides what I really needed, and I didn’t have to get up close and personal with how Durable Objects work. But I could still do that if I have to, the same reason I would just scroll to the code sample and read the docs later when I run into something (be honest… you do it sometimes too). In some other dimension or maybe in the future who knows we might just get to see more improvements in this direction