Durable Objects

Durable Objects nedir?

Sunucusuz fonksiyonlar state tutmaz ve yatay olarak dağılır. İki eşzamanlı isteğin tek bir değer üzerinde anlaşması gerektiğinde — bir koltuk rezervasyonu, bir sayaç, bir sohbet odasının üye listesi, bir rate limit bütçesi — dışarıdan bir koordinasyon katmanı eklemek zorunda kalırsın: Redis ve kilitler, işlemsel bir veritabanı, bir kilit servisi.

Durable Objects bunu ortadan kaldırır. Platform, verilen bir kimlik için dünyada tek bir instance’ın çalıştığını garanti eder ve o instance’a kendi özel, yanı başında duran, güçlü tutarlı SQLite veritabanını verir.

Cloudflare’in kendi tanımı:

“Each Durable Object has a globally-unique name, which allows you to send requests to a specific object from anywhere in the world. […] Each Durable Object has some durable storage attached. Since this storage lives together with the object, it is strongly consistent yet fast to access.”

Nasıl çalışır?

Teklik garantisi ve eşzamanlılık

Bir Durable Object tek iş parçacıklıdır ve işbirlikçi çoklu görev kullanır — resmî benzetmeyle “tarayıcıda çalışan kod gibi”. Eşzamanlılık güvenliği input gate denen mekanizmayla sağlanır. Resmî ifade: “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.”

Yumuşak tavan: nesne başına saniyede 1.000 istek. Aşılınca overloaded hatası döner.

Adresleme

Nesne tembel oluşturulur: kimlik üretmek nesneyi yaratmaz, ilk get çağrısı yaratır.

// Güncel biçim
{
  "durable_objects": {
    "bindings": [{ "name": "SOHBET", "class_name": "SohbetOdasi" }]
  },
  "exports": {
    "SohbetOdasi": { "type": "durable-object", "storage": "sqlite" }
  }
}

// Eski biçim — hâlâ destekleniyor, yeni projelerde kullanma
{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SohbetOdasi"] }] }

Yaşam döngüsü değişikliklerinin üç katı kuralı var:

• “Lifecycle changes cannot be applied via wrangler versions upload”
• “Gradual deployments don’t support lifecycle changes”
• “Rollbacks cannot cross a lifecycle change”

Depolama

SQLite backend’inde iki API bir arada bulunur:

// SQL API — senkron, event loop'u bırakmaz, dolayısıyla atomik
const satirlar = ctx.storage.sql
  .exec("SELECT ad, puan FROM oyuncular ORDER BY puan DESC LIMIT ?", 10)
  .toArray();

// KV API — senkron veya asenkron
ctx.storage.kv.put("sayac", 42);
await ctx.storage.put("sayac", 42);

İki tuzak:

Cursor’ı await üzerinden taşıma. Resmî uyarı: “A cursor resumed after an await may observe rows inserted, updated, or deleted after the cursor was created.” Cursor’ı await öncesinde .toArray() ile tüket.

BEGIN TRANSACTION çalıştırma. sql.exec() işlem ifadelerini kabul etmez; transactionSync() veya transaction() kullan.

Alarmlar

Nesne başına tek alarm vardır; setAlarm() mevcut olanı ezer. Yeniden deneme davranışı: “Alarms have guaranteed at-least-once execution and are retried automatically when the alarm() handler throws. Retries are performed using exponential backoff starting at a 2 second delay from the first failure with up to 6 retries allowed.”

Alarm işleyicisinin duvar saati sınırı 15 dakika. Her setAlarm() bir satır yazma olarak faturalanır.

WebSocket hibernation

Bu, Durable Objects’te para kazandıran tek en önemli özelliktir.

ws.accept() çağırırsan nesne WebSocket açık kaldığı sürece ücretlendirilir. Resmî ifade: “Calling accept() on a WebSocket in an Object will incur duration charges for the entire time the WebSocket is connected.”

ctx.acceptWebSocket(ws) çağırırsan nesne mesajlar arasında hibernate olabilir ve yalnızca mesaj işlenirken ücretlendirilir.

İstemci heartbeat’i için setWebSocketAutoResponse kullan — resmî ifade: “the auto-response will be returned without waking WebSockets in hibernation and incurring billable duration charges.”

Mesaj gruplama önerisi resmî dokümanda net: “Batch every 50-100ms or every 50-100 messages, whichever comes first.”

Konum ipuçları ve yargı alanları

Yargı alanları — kesin garanti: eu, us, fedramp. Konum ipuçları — garanti değil: wnam, enam, sam, weur, eeur, apac, apac-ne, apac-se, oc, afr, me. Resmî uyarı: “Hints are a best effort and not a guarantee.”

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Sohbet odaları, işbirlikçi doküman düzenleme, çok oyunculu oyun oturumları
• Koltuk/stok rezervasyonu — tek iş parçacıklı olduğu için gerçek bir compare-and-set
• Kullanıcı veya kiracı başına rate limiting
• Her varlığın kendi küçük veri kümesine sahip olduğu çok kiracılı yapılar
• WebSocket sunucusu gerektiren her şey

Uygun olmadığı işler

• Tüm verin üzerinde toplu sorgu. Her nesnenin deposu kendine özeldir; nesneler arası SELECT yoktur. Fan-out/fan-in senin sorunun.
• Tek bir global sayaç veya singleton. Bir nesne = bir iş parçacığı = saniyede ~1.000 istek. Parçala.
• Okuma ağırlıklı, global dağıtık, bayatlığa toleranslı veri. KV bunun için var; nesnenin tek bir ev konumu vardır, uzaktaki okuyucular gidiş-dönüş maliyeti öder.
• Büyük ikili veriler. Nesne başına 10 GB, satır/BLOB başına 2 MB. R2 kullan.
• Hibernate edilemeyen uzun ömürlü bağlantılar. Giden bir WebSocket veya setInterval, nesneyi 7/24 ücretlendirilen durumda tutar.
• ORM’li klasik ilişkisel veritabanı. Hyperdrive + PostgreSQL veya D1 kullan.

Somut örnekler

1. Sayaç — oku-değiştir-yaz güvenli

import { DurableObject } from "cloudflare:workers";

export class Sayac extends DurableObject {
  async deger() {
    return (await this.ctx.storage.get("deger")) ?? 0;
  }

  async artir(miktar = 1) {
    let deger = (await this.ctx.storage.get("deger")) ?? 0;
    deger += miktar;
    // Input gate sayesinde bu oku-değiştir-yaz atomik. Kilit gerekmiyor.
    await this.ctx.storage.put("deger", deger);
    return deger;
  }
}

export default {
  async fetch(request, env) {
    const ad = new URL(request.url).searchParams.get("ad");
    if (!ad) return new Response("?ad= gerekli", { status: 400 });

    // get(ad) DEĞİL — get() bir DurableObjectId bekler, string değil.
    const stub = env.SAYACLAR.getByName(ad);
    return new Response(String(await stub.artir()));
  },
};

2. Sohbet odası — hibernation + SQL geçmişi

import { DurableObject } from "cloudflare:workers";

export class SohbetOdasi extends DurableObject {
  constructor(ctx, env) {
    super(ctx, env);
    // Şema kurulumu blockConcurrencyWhile'ın meşru kullanımıdır.
    ctx.blockConcurrencyWhile(async () => {
      ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS mesajlar (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          kullanici TEXT NOT NULL,
          govde TEXT NOT NULL,
          ts INTEGER NOT NULL
        )`);
    });
    // Heartbeat'e hibernate'ten uyanmadan cevap ver — ücretlendirilmez.
    ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
  }

  async fetch(request) {
    const kullanici = new URL(request.url).searchParams.get("kullanici") ?? "anonim";
    const [istemci, sunucu] = Object.values(new WebSocketPair());

    // ws.accept() DEĞİL — accept() bağlantı boyunca ücret yazdırır.
    this.ctx.acceptWebSocket(sunucu, [`kullanici:${kullanici}`]);
    sunucu.serializeAttachment({ kullanici });  // hibernation'ı atlatır, max 16 KB

    return new Response(null, { status: 101, webSocket: istemci });
  }

  async webSocketMessage(ws, mesaj) {
    if (typeof mesaj !== "string") return;
    const { kullanici } = ws.deserializeAttachment();
    const ts = Date.now();

    this.ctx.storage.sql.exec(
      "INSERT INTO mesajlar (kullanici, govde, ts) VALUES (?, ?, ?)",
      kullanici, mesaj, ts,
    );

    const paket = JSON.stringify({ kullanici, govde: mesaj, ts });
    for (const peer of this.ctx.getWebSockets()) peer.send(paket);
  }

  async gecmis(limit = 50) {
    return this.ctx.storage.sql
      .exec("SELECT kullanici, govde, ts FROM mesajlar ORDER BY id DESC LIMIT ?", limit)
      .toArray();   // await'ten önce senkron tüket
  }
}

3. Rate limiter — kendi kendini temizleyen

const PENCERE_MS = 60_000;
const LIMIT = 100;

export class RateLimiter extends DurableObject {
  async kontrol() {
    const simdi = Date.now();
    this.ctx.storage.sql.exec("DELETE FROM vurus WHERE ts < ?", simdi - PENCERE_MS);

    const { n } = this.ctx.storage.sql
      .exec("SELECT COUNT(*) AS n FROM vurus").one();

    if (n >= LIMIT) return { izin: false, kalan: 0 };

    this.ctx.storage.sql.exec("INSERT INTO vurus (ts) VALUES (?)", simdi);

    // Kimse dönmezse alarm tabloyu siler ve depolama ücreti ödemeyi bırakırız.
    if ((await this.ctx.storage.getAlarm()) === null) {
      await this.ctx.storage.setAlarm(simdi + PENCERE_MS * 2);
    }
    return { izin: true, kalan: LIMIT - n - 1 };
  }

  async alarm() {
    this.ctx.storage.sql.exec("DELETE FROM vurus WHERE ts < ?", Date.now() - PENCERE_MS);
    const { n } = this.ctx.storage.sql.exec("SELECT COUNT(*) AS n FROM vurus").one();
    if (n > 0) await this.ctx.storage.setAlarm(Date.now() + PENCERE_MS);
    else await this.ctx.storage.deleteAll();   // tüm faturalanabilir depolamayı boşaltır
  }
}

// Worker: her IP kendi nesnesine düşer — global darboğaz yok
// await env.RATE_LIMITER.getByName(`ip:${ip}`).kontrol()

4. Koltuk rezervasyonu — gerçek compare-and-set

export class KoltukHaritasi extends DurableObject {
  async tut(koltuk, tutan, ttlMs = 300_000) {
    const simdi = Date.now();
    const satir = this.ctx.storage.sql
      .exec("SELECT tutan, gecerli_son FROM koltuklar WHERE koltuk = ?", koltuk)
      .toArray()[0];

    if (satir?.tutan && satir.tutan !== tutan && satir.gecerli_son > simdi) {
      return { ok: false, sebep: "başkası tutuyor" };
    }

    this.ctx.storage.sql.exec(
      "INSERT OR REPLACE INTO koltuklar (koltuk, tutan, gecerli_son) VALUES (?,?,?)",
      koltuk, tutan, simdi + ttlMs,
    );
    return { ok: true, bitis: simdi + ttlMs };
  }
}

Bu kodda ne advisory lock var, ne SELECT ... FOR UPDATE. Nesne tek iş parçacıklı ve SQL senkron olduğu için bu zaten atomik.

Demo 1: Hibernation’lı sohbet odası

Adım 1 — Proje kurulumu

npm create cloudflare@latest -- sohbet
cd sohbet

C3 sihirbazının 'Worker + Durable Objects' şablonunu seçtiğimiz ekranı

Adım 2 — Yapılandırma

{
  "name": "sohbet",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-31",
  "observability": { "enabled": true },
  "durable_objects": {
    "bindings": [{ "name": "SOHBET", "class_name": "SohbetOdasi" }]
  },
  "exports": {
    "SohbetOdasi": { "type": "durable-object", "storage": "sqlite" }
  }
}

npx wrangler types    # wrangler.jsonc her değiştiğinde tekrar çalıştır
npx wrangler dev

Terminal çıktısı — Your Worker has access to the following bindings bölümünde SOHBET (SohbetOdasi) Durable Object satırı

Adım 3 — İki tarayıcıdan bağlan

Yan yana iki tarayıcı penceresi, aynı ?oda=lobi adresinde, birinden yazılan mesaj diğerinde anında görünüyor

Adım 4 — Yayına al ve gözlemle

npx wrangler deploy
npx wrangler tail

Deploy çıktısı — exports bloğundan namespace'in ilk kez provision edildiği satır

Workers & Pages → Durable Objects → namespace → Metrics: istek sayısı, süre (GB-s) ve aktif nesne sayısı

Demo 2: Hibernation’ın maliyet farkını ölçme

Bu demo sayfanın en önemli iddiasını doğrular: hibernation gerçekten ~7 kat fark yaratıyor mu?

Adım 1 — Hibernation’sız sürümü çalıştır

ctx.acceptWebSocket(sunucu) yerine geçici olarak:

sunucu.accept();
sunucu.addEventListener("message", (e) => { /* ... */ });

Durable Objects Metrics ekranında 'Duration (GB-s)' grafiği — bağlantı açık kaldığı sürece sürekli tüketim

Adım 2 — Hibernation’lı sürüme dön

Aynı Duration (GB-s) grafiği, hibernation açıkken — yalnızca mesaj anlarında sivrilen tüketim

Adım 3 — Otomatik yanıtı doğrula

ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));

DevTools → Network → WS → Messages sekmesinde ping gönderilip pong dönmesi; Worker log'unda bu mesajların görünmemesi

Terminal — mesaj geldiğinde nesnenin uyanıp webSocketMessage çalıştırdığı, ping'lerde ise hiç log düşmediği

Ölçüm: öncesi ve sonrası

Demo tamamlandığında gerçek değerlerle doldurulacak.

Fiyatlandırma

Rakamlar 31 Ağustos 2026’da resmî dokümandan doğrulanmıştır.

Hesaplama

Kritik ayrıntılar:

• Süre, nesnenin 128 MB belleği için ücretlendirilir — gerçek kullanımdan bağımsız.
• Gelen WebSocket mesajlarına faturalamada 20:1 oranı uygulanır: 100 mesaj 5 istek sayılır.
• Giden WebSocket mesajları ve gelen protokol ping’leri ücretsizdir.
• Bir RPC oturumu tek istek olarak faturalanır; aynı stub üzerindeki sonraki çağrılar ayrı istek değildir.
• setWebSocketAutoResponse ile yanıtlanan mesajlar duvar saati tüketmez, ücretlendirilmez.

SQLite depolama

Cloudflare’in kendi maliyet örnekleri

İkinci ile dördüncü satırı karşılaştır: aynı büyüklükteki iş yükü, 7 kat maliyet farkı.

Lisanslama ve hukuki çerçeve

Durable Objects tescilli bir hizmettir; kullanımı Cloudflare Hizmet Şartları ile düzenlenir.

Veri konumu açısından önemli: Bir Durable Object’in verisi tek bir fiziksel konumda durur ve o konum ilk erişimin geldiği yere göre belirlenir. Yargı alanı (jurisdiction) kesin bir kısıttır — eu seçilirse veri Avrupa Birliği içinde kalır. Konum ipucu (locationHint) ise garanti değildir.

Türkiye için tanımlı bir Durable Objects yargı alanı yoktur. Verinin Türkiye’de kalması gerekiyorsa Durable Objects uygun bir seçenek değildir.

Sık yapılan hatalar

ws.accept() kullanmak. Durable Objects’teki en pahalı hata. Bağlantı açık kaldığı sürece ücret yazar. Doğrusu ctx.acceptWebSocket(ws).

Tick için setInterval kullanmak. Hibernation’ı kalıcı olarak engeller ve 7/24 GB-s faturalar. Doğrusu setAlarm() — alarm hibernate olmuş nesneyi uyandırabilir.

Sınıf alanlarında gerçek state tutmak. Resmî ifade: “In-memory state is reset when the Durable Object hibernates.” Sınıf alanlarını yalnızca önbellek olarak gör; kaynak her zaman depo olmalı.

Constructor’da ağır iş yapmak. Hibernation altında constructor her uyanışta çalışır.

Cursor’ı await üzerinden taşımak. await öncesinde .toArray() ile tüket.

migrations ile exports’u karıştırmak. Aynı Worker’da ikisi birden kullanılamaz.

Kapanış kancası beklemek. Yoktur. Resmî öneri: “write your position to storage as you go rather than waiting to persist it at the end.”

Biten nesneleri temizlememek. Veri silinene kadar depolama ücreti işler. TTL alarmıyla deleteAll() çağır.

Tüm trafiği tek bir global nesneye yönlendirmek. Saniyede ~1.000 istek tavanına çarparsın. Varlık bazında parçala.