Queues

Queues nedir?

Bir isteği yanıtlarken yapılması gereken her iş, o isteğin içinde yapılmak zorunda değildir. Fatura e-postası göndermek, görüntü işlemek, dış bir API’ye bildirim atmak — bunlar kullanıcıyı bekletmeden arka planda yapılabilir.

Cloudflare Queues bu ayrımı sağlar. Resmî tanım:

“Send and receive messages with guaranteed delivery and no charges for egress bandwidth.”

Kullanım amaçları resmî dokümanda dört başlıkta toplanıyor: teslimi garanti etmek, işi istekten ayırmak, Worker’dan Worker’a veri göndermek, ve veriyi tamponlayıp gruplamak.

Nasıl çalışır?

Dört kavram: kuyruk, üretici (producer), tüketici (consumer) ve mesaj.

Üretici bir Worker’a kuyruk binding’i tanımlanarak kurulur. Bir kuyruğa yazan üretici sayısında sınır yoktur. Tüketici tarafında ise durum farklı:

Teslim garantisi: en az bir kez

Bu, Queues hakkında bilinmesi gereken en önemli şeydir.

Cloudflare’in önerdiği çözüm: mesajı yazarken benzersiz bir kimlik üret ve bunu veritabanı eklemelerinde birincil anahtar veya idempotency anahtarı olarak kullan.

Gruplama (batching)

İkisi birlikte çalışır; hangisi önce dolarsa batch o an teslim edilir.

Kuyruk boşken push tüketicisi hiç çağrılmaz — maliyet doğmaz. Ama pull tüketicisi için durum farklı: “Pull-based consumers that attempt to pull from a queue, even when empty, will incur a read operation.”

Onaylama ve yeniden deneme

Varsayılan davranış batch’i bir bütün olarak ele alır:

“if a batch of 10 messages is delivered, but the 8th message fails to be processed, all 10 messages will be retried and thus redelivered to your consumer in full.”

Bu hem gereksiz iş hem gereksiz fatura demektir. Çözüm mesajları tek tek onaylamak.

Öncelik kuralları nettir: “The first method call wins in all cases.” Bir mesaj için ack() çağırdıysan sonraki ack() veya retry() sessizce yok sayılır; tek mesaj çağrıları ackAll()/retryAll()’u ezer.

Dead letter queue

Varsayılan retry sayısı 3, en fazla 100. Hak bitince:

• DLQ tanımlıysa mesaj oraya yazılır
• Tanımlı değilse kalıcı olarak silinir

DLQ önceden var olmak zorunda değil — belirtilen adda kuyruk yoksa otomatik oluşturulur. Tüketicisi olmayan bir DLQ’daki mesajlar 4 gün sonra silinir.

Eşzamanlılık

Varsayılan olarak açıktır. Cloudflare’in kendi örneği ölçeklenmeyi somutlaştırıyor: saniyede 100 mesaj yazılıyorsa ve tek tüketici 100 mesajlık batch’i 5 saniyede işliyorsa, Queues eşzamanlı çağrı sayısını yaklaşık 5’e çıkarır.

Ölçeklenmeme sebepleri: max_concurrency 1 yapılmış, tüketici hata döndürüyor, veya bir batch hâlâ işleniyor (“Queues checks if it should autoscale consumers only after processing an entire batch”).

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

Uygun olduğu işler

• İstekten iş ayırma: e-posta, bildirim, dış API çağrısı
• Yük tepesini yayma — üretici hızlı yazar, tüketici sabit hızda işler
• Hız sınırlı bir API’ye karşı geri baskı (backpressure)
• Yazmaları gruplayarak R2 veya dış servise toplu yazma
• Worker’dan Worker’a veri taşıma

Uygun olmadığı işler

• Sıralama gerekiyorsa. Resmî olarak garanti edilmiyor, iki ayrı yerde yazıyor.
• Exactly-once gerekiyorsa. En az bir kez teslim var; tekrarı sen engellersin.
• Uzun, çok adımlı, kısmi ilerlemesi korunması gereken iş. Tüketici çağrısı 15 dakikayla sınırlı ve adım bazlı kontrol noktası yok. Workflows kullan.
• Varlık bazında sıralama veya koordinasyon gerekiyorsa. Kuyruk başına tek tüketici var, partition anahtarı yok. Durable Objects kullan.
• 24 saatten uzun gecikme gerekiyorsa. delaySeconds tavanı 24 saat.
• Saniyede 5.000 mesajı aşan tek kuyruk. Üretici Too Many Requests alır; resmî çözüm birden çok kuyruğa yatay bölmek.
• 25 GB’ı aşan birikme. Storage Limit Exceeded döner.

Somut örnekler

1. Üretici ve tüketici

{
  "queues": {
    "producers": [{ "queue": "isler", "binding": "ISLER" }],
    "consumers": [{
      "queue": "isler",
      "max_batch_size": 10,
      "max_batch_timeout": 30,
      "max_retries": 5,
      "dead_letter_queue": "isler-dlq"
    }]
  }
}

export default {
  // Üretici: isteği hemen yanıtla, işi kuyruğa at
  async fetch(request, env) {
    const { siparisId } = await request.json();
    await env.ISLER.send({
      tip: "siparis-onay",
      siparisId,
      // Tekrar teslimde çift işlem yapmamak için benzersiz kimlik
      islemId: crypto.randomUUID(),
    });
    return Response.json({ alindi: true });
  },

  // Tüketici
  async queue(batch, env) {
    for (const mesaj of batch.messages) {
      try {
        await isle(mesaj.body, env);
        mesaj.ack();      // tek tek onayla — batch'in tamamı retry edilmesin
      } catch (h) {
        mesaj.retry();
      }
    }
  },
};

2. Hız sınırlı API’ye geri baskı

Dış API 429 döndüğünde tüm batch’i geciktirerek yavaşla.

export default {
  async queue(batch, env) {
    for (const mesaj of batch.messages) {
      const yanit = await fetch("https://api.ornek.com/gonder", {
        method: "POST",
        body: JSON.stringify(mesaj.body),
      });

      if (yanit.status === 429) {
        // Tüm batch'i 10 dakika geciktir — bu başarısız çağrı sayılmaz,
        // dolayısıyla otomatik ölçeklenme cezalandırılmaz
        batch.retryAll({ delaySeconds: 600 });
        return;
      }
      if (!yanit.ok) {
        mesaj.retry();
        continue;
      }
      mesaj.ack();
    }
  },
};

3. Üstel geri çekilme

const TABAN_SANIYE = 30;

export default {
  async queue(batch, env) {
    for (const mesaj of batch.messages) {
      try {
        await isle(mesaj.body, env);
        mesaj.ack();
      } catch {
        // attempts 1-indexlidir: 30, 900, 27000 saniye…
        mesaj.retry({ delaySeconds: TABAN_SANIYE ** mesaj.attempts });
      }
    }
  },
};

4. Tek tüketici, çok kuyruk

export default {
  async queue(batch, env) {
    switch (batch.queue) {
      case "log-kuyrugu":
        await env.LOGLAR.put(`log/${Date.now()}.ndjson`,
          batch.messages.map(m => JSON.stringify(m.body)).join("\n"));
        break;
      case "eposta-kuyrugu":
        for (const m of batch.messages) await epostaGonder(m.body, env);
        break;
      default:
        console.log("bilinmeyen kuyruk", batch.queue);
    }
  },
};

5. Birikmeyi izleme

const sonuc = await env.ISLER.send({ tip: "is" });
const { backlogCount, backlogBytes, oldestMessageTimestamp } = sonuc.metadata.metrics;

if (backlogCount > 100_000) {
  console.log(JSON.stringify({
    olay: "kuyruk_birikiyor",
    backlogCount,
    enEskiMesajYasiSn: (Date.now() - oldestMessageTimestamp) / 1000,
  }));
}

Demo 1: Batch, retry ve dead letter queue

Adım 1 — Kuyrukları oluştur

npx wrangler queues create isler
npx wrangler queues create isler-dlq
npx wrangler queues list

Terminal — iki kuyruğun oluşturulması ve list çıktısında görünmesi

Adım 2 — Üretici ve tüketiciyi yayına al

npx wrangler deploy
npx wrangler queues consumer add isler <WORKER_ADI> --dead-letter-queue=isler-dlq

consumer add çıktısı ve panelde kuyruğun tüketici bilgisi

Adım 3 — Batch davranışını gözle

50 mesaj gönder, max_batch_size: 10 ile kaç çağrıda işlendiğini izle.

Terminal — her tüketici çağrısında kaç mesaj geldiği; batch boyutunun 10'da toplandığı

Adım 4 — Kasten hata üret

Bir mesajı sürekli hata verecek şekilde ayarla ve retry’ları izle.

wrangler tail — aynı mesajın attempts değeri artarak tekrar gelmesi

Adım 5 — DLQ’ya düşüşü doğrula

Panel veya CLI — isler-dlq kuyruğunda biriken mesaj sayısı

Adım 6 — Tek tek onaylamanın farkı

msg.ack() olmadan ve varken aynı testi çalıştır.

İki wrangler tail çıktısı yan yana — ack'siz sürümde 10 mesajın tamamının tekrar geldiği, ack'li sürümde yalnızca hatalı olanın geldiği

Demo 2: Hız sınırlı API’ye karşı geri baskı

Adım 1 — Hız sınırlı bir test API’si kur

Basit bir Worker veya yerel servis — belirli bir hızın üstünde 429 döndürüyor

Adım 2 — Geri baskısız hâli çalıştır

Log çıktısı — çok sayıda 429 yanıtı ve boşa harcanan retry'lar

Adım 3 — retryAll ile geri çekil

Log çıktısı — 429 alındığında batch'in geciktirilmesi ve 429 sayısının düşmesi

Adım 4 — Eşzamanlılığın davranışını gözle

Queues metrik ekranı — eşzamanlı tüketici çağrısı sayısının yük altında artması

Adım 5 — Kuyruğu duraklat

npx wrangler queues pause-delivery isler
npx wrangler queues resume-delivery isler

Metrik ekranı — teslim durdurulduğunda backlog'un artışı, devam ettirildiğinde erimesi

Ölçüm

Fiyatlandırma

Rakamlar 1 Eylül 2026’da resmî dokümandan doğrulanmıştır.

İşlem nasıl sayılır:

• Yazılan, okunan veya silinen her 64 KB bir işlemdir
• 127 KB’lık bir mesaj yazılırken, okunurken ve silinirken ikişer işlem sayar
• İşlemler batch başına değil mesaj başına sayılır — 10 mesajlık bir batch 10 yazma, 10 okuma, 10 silme işlemi doğurur
• Normalde bir mesaj 3 işlem eder: yazma + okuma + silme
• Her retry ek bir okuma yazar
• Egress veya bant genişliği ücreti yoktur

Resmî formül:

((mesaj sayısı × 3) − 1.000.000) / 1.000.000 × 0,40 USD

Cloudflare’in kendi örnekleri

İkinci satır 64 KB kuralının etkisini gösteriyor: mesaj boyutu iki katına çıkınca işlem sayısı da ikiye katlanıyor.

Kuyruğu boşaltmak (purge) kaç mesaj silinirse silinsin tek işlem sayılır.

Tüketicinin harcadığı CPU ve istek ayrıca Workers fiyatlandırmasına tabidir.

Limitler

Aşım davranışları: throughput aşılınca send() ve sendBatch() Too Many Requests fırlatır; birikme sınırı aşılınca Storage Limit Exceeded döner.

Lisanslama ve hukuki çerçeve

Queues tescilli bir hizmettir; Cloudflare Hizmet Şartları kapsamındadır.

Mesaj içeriği Cloudflare’de saklanır — varsayılan 4 gün, en fazla 14 gün. Kuyruğa yazdığın her şey bu süre boyunca Cloudflare’in altyapısında durur. Kişisel veri taşıyorsan:

• Mesaj gövdesine ham kişisel veri yerine referans (kimlik) yazmayı değerlendir
• Saklama süresini ihtiyacın kadar kısalt
• DLQ’daki mesajları da veri envanterine dahil et — orada 4 gün daha durabilirler

Yargı bölgesi kısıtı Queues için tanımlı değildir.

Sık yapılan hatalar

Sıralama varsaymak. Dokümanda iki kez garanti edilmediği yazıyor.

Exactly-once varsaymak. Tekrar teslim olabilir; idempotency anahtarı kullan.

batch.messages.forEach() içinde asenkron iş yapmak. Beklemez. for...of veya Promise.all(map(...)) kullan.

Tek tek onaylamamak. Batch’in 8. mesajı hata verirse 10’u birden tekrar teslim edilir ve retry başına 10 okuma işlemi faturalanır.

Kritik yazmayı ctx.waitUntil() içine koymak. Resmî uyarı: “because waitUntil() is non-blocking, any errors raised from the send() or sendBatch() methods on a queue will be implicitly ignored.”

max_concurrency: 1 verip ölçeklenmemesine şaşırmak. Cloudflare’in kendi “neden ölçeklenmiyor” listesinin ilk maddesi.

Mesaj başına 1 işlem bütçelemek. Normalde 3’tür, her retry bir okuma daha ekler.

Pull tüketicisiyle boş kuyruğu yoklamak. Boş çekim bile okuma işlemi maliyeti doğurur.

CLI ile tüketiciyi kaldırıp yapılandırmayı silmemek. Resmî uyarı: sonraki deploy’lar çakışan tüketici yapılandırması yüzünden başarısız olur.

Pull tüketicisine v8 içerik tipi göndermek. “Pull-based consumers cannot decode the v8 content type as it is specific to the Workers runtime.”