Cloudflare D1 and Durable Objects: A Framework for Designing Strong Consistency Boundaries at the Edge with Distributed SQLite

// D1 basic query — reads from the nearest replica
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const products = await env.DB.prepare(
      "SELECT id, name, price FROM products WHERE active = 1"
    ).all();
 
    return Response.json(products.results);
  },
};

// When session consistency is needed — reading immediately after writing
const session = env.DB.withSession("first-primary");
 
await session
  .prepare("INSERT INTO cart_items (user_id, product_id) VALUES (?, ?)")
  .bind(userId, productId)
  .run();
 
// Same session → the data just written is guaranteed to be readable
const cart = await session
  .prepare("SELECT * FROM cart_items WHERE user_id = ?")
  .bind(userId)
  .all();

// src/routes/products.ts
import { Hono } from "hono";
import { drizzle } from "drizzle-orm/d1";
import { products, inventory, cartItems } from "../schema";
import { eq } from "drizzle-orm";
 
const app = new Hono<{ Bindings: Env }>();
 
// Product listing — read from nearest replica (fast)
app.get("/products", async (c) => {
  const db = drizzle(c.env.DB);
  const items = await db
    .select()
    .from(products)
    .where(eq(products.active, true));
  return c.json(items);
});
 
// Add to cart and immediately verify — session consistency required
app.post("/cart", async (c) => {
  const { productId, userId } = await c.req.json();
 
  // "first-primary": guarantees same read consistency as writes on Primary
  const session = c.env.DB.withSession("first-primary");
  const db = drizzle(session);
 
  // Check latest inventory (replica lag not acceptable here)
  const [item] = await db
    .select()
    .from(inventory)
    .where(eq(inventory.productId, productId));
 
  if (item.stock < 1) {
    return c.json({ error: "Out of stock" }, 409);
  }
 
  // Atomically decrement inventory + add to cart
  await db.batch([
    db
      .update(inventory)
      .set({ stock: item.stock - 1 })
      .where(eq(inventory.productId, productId)),
    db.insert(cartItems).values({ userId, productId }),
  ]);
 
  // Same session → the item just added is guaranteed to appear
  const cart = await db
    .select()
    .from(cartItems)
    .where(eq(cartItems.userId, userId));
 
  return c.json(cart);
});
 
export default app;

// src/durable-objects/document.ts
import { DurableObject } from "cloudflare:workers";
 
interface EditOperation {
  userId: string;
  position: number;
  text: string;
  type: "insert" | "delete";
  timestamp: number;
}
 
interface Operation {
  op_type: string;
  position: number;
  content: string | null;
}
 
export class DocumentDO extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
 
    this.ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS operations (
          id        INTEGER PRIMARY KEY AUTOINCREMENT,
          user_id   TEXT    NOT NULL,
          op_type   TEXT    NOT NULL,
          position  INTEGER NOT NULL,
          content   TEXT,
          applied_at INTEGER NOT NULL
        )
      `);
    });
  }
 
  async fetch(request: Request): Promise<Response> {
    if (request.headers.get("Upgrade") === "websocket") {
      const [client, server] = Object.values(new WebSocketPair());
      // acceptWebSocket + getWebSockets() → Hibernation API pattern
      this.ctx.acceptWebSocket(server);
      return new Response(null, { status: 101, webSocket: client });
    }
    return new Response("Not found", { status: 404 });
  }
 
  // Hibernation API: WebSocket messages are routed to this method
  async webSocketMessage(ws: WebSocket, message: string): Promise<void> {
    const op: EditOperation = JSON.parse(message);
 
    // Single-threaded — even concurrent edit requests are processed in order
    this.ctx.storage.sql.exec(
      `INSERT INTO operations (user_id, op_type, position, content, applied_at)
       VALUES (?, ?, ?, ?, ?)`,
      op.userId,
      op.type,
      op.position,
      op.text,
      op.timestamp
    );
 
    const ops = [
      ...this.ctx.storage.sql.exec<Operation>(
        `SELECT op_type, position, content FROM operations ORDER BY applied_at ASC`
      ),
    ];
 
    // ⚠️ Simplified demo implementation (O(n) reapplication)
    // Real production use requires OT (Operational Transformation) or CRDT
    const content = this.reconstructDocument(ops);
 
    for (const socket of this.ctx.getWebSockets()) {
      if (socket !== ws) {
        socket.send(JSON.stringify({ type: "op_applied", op, content }));
      }
    }
  }
 
  private reconstructDocument(ops: Operation[]): string {
    let doc = "";
    for (const op of ops) {
      if (op.op_type === "insert") {
        doc = doc.slice(0, op.position) + op.content + doc.slice(op.position);
      } else {
        doc =
          doc.slice(0, op.position) +
          doc.slice(op.position + (op.content?.length ?? 0));
      }
    }
    return doc;
  }
}
 
// src/index.ts — DO routing in the Worker
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const docId = url.searchParams.get("docId");
    if (!docId) return new Response("docId required", { status: 400 });
 
    // Same docId → always routed to the same DO instance
    const id = env.DOCUMENT_DO.idFromName(`doc:${docId}`);
    return env.DOCUMENT_DO.get(id).fetch(request);
  },
};

┌─────────────────────────────────────────────────────┐
│                  Cloudflare Workers                 │
│                                                     │
│   Request Routing                                   │
│      │                                              │
│      ├─── Shared Data ────────▶ D1 Global DB        │
│      │    (users, plans, billing)  (distributed replicas) │
│      │                                              │
│      ├─── Tenant-Isolated Data ▶ DO per Tenant      │
│      │    (per-tenant SQLite)    (independent instances) │
│      │                                              │
│      └─── API Rate Limiting ──▶ DO per API Key      │
│           (sliding window)    (single-threaded counter) │
└─────────────────────────────────────────────────────┘

// src/durable-objects/rate-limiter.ts
import { DurableObject } from "cloudflare:workers";
 
export class RateLimiterDO extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS requests (
          id        INTEGER PRIMARY KEY AUTOINCREMENT,
          timestamp INTEGER NOT NULL
        )
      `);
    });
  }
 
  // The DO instance is isolated per API key, so no need to receive it as a parameter
  async checkLimit(limit: number, windowMs: number): Promise<boolean> {
    const now = Date.now();
    const windowStart = now - windowMs;
 
    this.ctx.storage.sql.exec(
      `DELETE FROM requests WHERE timestamp < ?`,
      windowStart
    );
 
    const result = this.ctx.storage.sql
      .exec<{ cnt: number }>(`SELECT COUNT(*) as cnt FROM requests`)
      .one();
 
    if (result.cnt >= limit) return false;
 
    this.ctx.storage.sql.exec(
      `INSERT INTO requests (timestamp) VALUES (?)`,
      now
    );
 
    return true;
  }
}
 
// src/middleware/rate-limiter.ts
import { Hono } from "hono";
import { drizzle } from "drizzle-orm/d1";
import { tenants } from "../schema";
import { eq } from "drizzle-orm";
 
const app = new Hono<{ Bindings: Env }>();
 
app.use("*", async (c, next) => {
  const apiKey = c.req.header("X-API-Key");
  if (!apiKey) return c.json({ error: "API key required" }, 401);
 
  // One DO instance per API key — strong consistency for accurate counting
  const id = c.env.RATE_LIMITER.idFromName(`key:${apiKey}`);
  const limiter = c.env.RATE_LIMITER.get(id);
 
  const allowed = await limiter.checkLimit(100, 60_000);
  if (!allowed) return c.json({ error: "Rate limit exceeded" }, 429);
 
  // Tenant info read from D1 (replicas OK — no write contention)
  const db = drizzle(c.env.DB);
  const [tenant] = await db
    .select()
    .from(tenants)
    .where(eq(tenants.apiKey, apiKey));
 
  c.set("tenant", tenant);
  await next();
});
 
export default app;