Workers

Workers nedir?

Bir web isteği normalde şu yolu izler: kullanıcının tarayıcısı → DNS → (varsa CDN) → senin sunucun. Uygulama kodun o sunucuda, tek bir yerde çalışır. İstanbul’daki kullanıcı da, Berlin’deki kullanıcı da aynı makineye ulaşmak zorundadır.

Workers bu şemayı değiştirir: kodunu bir sunucuya değil, Cloudflare’in ağının kendisine yüklersin. Kod, isteği ilk karşılayan şehirde çalışır. İstanbul’dan gelen istek İstanbul’da, Frankfurt’tan gelen istek Frankfurt’ta işlenir. Ortada yönetmen gereken bir makine, kurman gereken bir işletim sistemi, yamalaman gereken bir çekirdek yoktur.

Pratikte bu üç şey demektir:

• Sunucu yönetimi ortadan kalkar. Kapasite planlaması, otomatik ölçekleme grubu, yük dengeleyici yapılandırması, güvenlik yaması yoktur. Kodu yayına alırsın, gerisi Cloudflare’in sorumluluğundadır.
• Gecikme düşer. Kod kullanıcıya coğrafi olarak yakın çalıştığı için, origin sunucuna gitmeyen istekler tek haneli milisaniyelerde yanıtlanır.
• Boşta durmak bedava olur. Fatura, çalışan koda göre kesilir. Gece hiç istek gelmeyen bir servis için ödeme yapmazsın.

Nasıl çalışır?

Workers’ın diğer sunucusuz platformlardan (AWS Lambda, Google Cloud Functions) ayrıldığı temel nokta, konteyner değil izolat (isolate) kullanmasıdır.

Klasik sunucusuz platformlar her fonksiyon için bir konteyner veya mikro-sanal makine başlatır. Bu birkaç yüz milisaniyeden birkaç saniyeye kadar süren bir soğuk başlangıç (cold start) demektir. Workers ise Chrome’un JavaScript motoru olan V8’in “isolate” mekanizmasını kullanır. Bir isolate, aynı süreç içinde çalışan ama belleği tamamen ayrılmış hafif bir bağlamdır; kurulumu milisaniyenin altında sürer.

Bir isteğin ömrü şöyledir:

1. İstek, kullanıcıya en yakın Cloudflare şehrine ulaşır.
2. Cloudflare, o alan adına bağlı Worker’ı bulur ve bir isolate içinde fetch fonksiyonunu çağırır.
3. Kod çalışır: gelen isteği okur, gerekirse KV’den veri okur, gerekirse origin sunucuna fetch atar, yanıtı oluşturur.
4. Yanıt kullanıcıya döner. Worker isterse arka planda iş yapmaya devam eder (waitUntil).

En basit haliyle bir Worker şudur:

export default {
  async fetch(request, env, ctx) {
    return new Response("Merhaba İstanbul", {
      headers: { "content-type": "text/plain; charset=utf-8" },
    });
  },
};

Bağlantılar (bindings)

Worker’ın dış dünyaya erişimi env nesnesi üzerinden, binding denen tanımlarla olur. Kodun içine bağlantı dizesi veya API anahtarı gömmezsin: wrangler.jsonc dosyasında hangi kaynağa erişeceğini bildirirsin, Cloudflare o kaynağı çalışma anında env içine koyar.

export default {
  async fetch(request, env) {
    // Durable Object — adı verilen tek bir nesneye bağlan
    const id = env.GAME_ROOM.idFromName("oda-42");
    const oda = env.GAME_ROOM.get(id);

    // D1 — sunucusuz SQL
    const { results } = await env.DB.prepare(
      "select ad, puan from oyuncular order by puan desc limit 10",
    ).all();

    // R2 — nesne depolama
    const logo = await env.BRAND.get("logo.svg");

    return Response.json({ liderler: results });
  },
};

Yayına alırken wrangler, Worker’ın hangi kaynaklara bağlı olduğunu listeler. Aşağıdaki demo bölümünde bunun gerçek çıktısı var: solda kodun gördüğü ad (env.DB), sağda arkasındaki kaynak (D1 Database).

Hata ayıklarken ilk bakılacak yer burasıdır: beklediğin bağlantı listede görünmüyorsa wrangler.jsonc düzenlenmiş ama yayına alınmamış demektir.

CPU süresi ile bekleme süresi farkı

Bu ayrım, Workers’ın faturasını anlamanın anahtarıdır ve yeni başlayanların en sık yanlış hesapladığı yerdir.

• CPU süresi: İşlemcinin gerçekten senin kodunu çalıştırdığı süre. JSON ayrıştırma, imza doğrulama, şablon işleme.
• Bekleme süresi (duration / wall-clock): Kodun bir yanıt beklediği süre. Origin sunucundan cevap beklemek, veritabanı sorgusunun dönmesini beklemek.

Cloudflare yalnızca CPU süresini ücretlendirir. Origin sunucun 3 saniyede cevap veriyorsa, Worker o 3 saniye boyunca bekler ama sen o beklemeye para ödemezsin. Ödediğin, isteği hazırlamak ve yanıtı işlemek için harcanan birkaç milisaniyedir.

Cloudflare paneli bu iki değeri yan yana gösterir. Demo bölümündeki metrik ekranında gerçek bir ölçüm var: CPU Time 865 µs, Wall Time 19 ms — yaklaşık 22 kat fark. Faturaya giren yalnızca soldaki.

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

Bir referans kaynağının işi, ürünü satmak değil sınırlarını göstermektir. Workers her iş için doğru araç değildir.

Uygun olduğu işler

• Origin’in önünde kimlik doğrulama, yetkilendirme, token doğrulama
• A/B testi, kademeli yayın (canary), bakım modu, coğrafi yönlendirme
• İstek/yanıt dönüştürme: başlık ekleme, HTML enjeksiyonu, eski API’yi yeni şemaya çevirme
• Webhook karşılama ve kuyruğa yazma
• API birleştirme (birden çok iç servisi tek yanıtta toplama)
• Statik site + hafif API (Pages ile birlikte)
• Bot filtreleme, hız sınırlama, imzalı URL üretme

Uygun olmadığı işler

• Uzun süren, CPU yoğun hesaplama. Video kodlama, büyük veri işleme, makine öğrenmesi eğitimi. Çağrı başına CPU süresi üst sınırı vardır (ücretsizde 10 ms, ücretlide varsayılan 30 sn, en fazla 5 dk).
• 128 MB’dan fazla bellek isteyen işler. İzolat başına bellek sınırı sabittir ve ücretli planda da artmaz.
• Native ikili bağımlılık gerektiren kod. ImageMagick, ffmpeg, kendi derlediğin C kütüphanesi. Bunlar için Containers vardır.
• Uzun ömürlü, havuzlanmış veritabanı bağlantıları. Ham TCP mümkündür (cloudflare:sockets) ama her çağrıda yeniden kurulum turu ödersin; PostgreSQL/MySQL için Hyperdrive kullan.
• Disk üzerinde dosya sistemi bekleyen kod. Worker’ın yazılabilir bir diski yoktur; kalıcı veri için R2, KV, D1 veya Durable Objects kullanılır.

Somut örnekler

1. Şirket içi API’nin önüne kimlik katmanı

Kendi veri merkezindeki bir API’yi internete açtın. Her isteğin geçerli bir imza taşımasını istiyorsun ve geçersiz isteklerin hiç iç ağa girmemesini tercih ediyorsun.

export default {
  async fetch(request, env) {
    const imza = request.headers.get("x-imza");
    const zaman = request.headers.get("x-zaman");

    if (!imza || !zaman) {
      return yanit(401, "İmza başlıkları eksik");
    }

    // 5 dakikadan eski istekleri tekrar oynatma saldırısına karşı reddet
    const yas = Math.abs(Date.now() - Number(zaman));
    if (!Number.isFinite(yas) || yas > 5 * 60 * 1000) {
      return yanit(401, "İstek zaman aşımına uğradı");
    }

    const govde = await request.clone().text();
    if (!(await imzaDogru(env.PAYLASILAN_SIR, zaman + govde, imza))) {
      return yanit(403, "İmza geçersiz");
    }

    // Doğrulandı: isteği Cloudflare Tunnel üzerinden iç API'ye ilet
    return fetch(request);
  },
};

async function imzaDogru(sir, veri, beklenenHex) {
  const enc = new TextEncoder();
  const anahtar = await crypto.subtle.importKey(
    "raw",
    enc.encode(sir),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  const bayt = Uint8Array.from(
    beklenenHex.match(/.{1,2}/g) ?? [],
    (b) => parseInt(b, 16),
  );
  return crypto.subtle.verify("HMAC", anahtar, bayt, enc.encode(veri));
}

function yanit(kod, mesaj) {
  return new Response(JSON.stringify({ hata: mesaj }), {
    status: kod,
    headers: { "content-type": "application/json; charset=utf-8" },
  });
}

Kazanç: geçersiz istekler İstanbul’daki Cloudflare sunucusunda ölür, senin hattını ve sunucunu hiç meşgul etmez.

2. Bakım modu — origin’e dokunmadan

Sunucuda planlı bakım var. Uygulamayı durdurmadan, kullanıcıya düzgün bir sayfa göstermek istiyorsun.

export default {
  async fetch(request, env) {
    // BAKIM değişkeni Cloudflare panelinden anında açılıp kapanır
    if (env.BAKIM === "acik") {
      const ip = request.headers.get("cf-connecting-ip");
      const ofisIp = ["203.0.113.10"]; // ofis çıkışı bakımda da erişebilsin

      if (!ofisIp.includes(ip)) {
        return new Response(BAKIM_HTML, {
          status: 503,
          headers: {
            "content-type": "text/html; charset=utf-8",
            "retry-after": "1800",
            "cache-control": "no-store",
          },
        });
      }
    }
    return fetch(request);
  },
};

const BAKIM_HTML = `<!doctype html><html lang="tr"><meta charset="utf-8">
<title>Bakım çalışması</title>
<h1>Kısa bir bakım çalışması yapıyoruz</h1>
<p>Yaklaşık 30 dakika içinde geri döneceğiz.</p>`;

503 ve retry-after başlığı önemlidir: arama motorları bunu geçici durum olarak okur, sıralamanı düşürmez.

3. Coğrafi yönlendirme

Cloudflare her isteğe request.cf nesnesiyle ülke, şehir ve veri merkezi bilgisi ekler. Ek bir GeoIP veritabanı kurmana gerek yoktur.

export default {
  async fetch(request) {
    const ulke = request.cf?.country ?? "XX";
    const url = new URL(request.url);

    // Türkiye'den gelen ve dil seçmemiş kullanıcıyı /tr/ altına al
    if (ulke === "TR" && url.pathname === "/") {
      return Response.redirect(new URL("/tr/", url), 302);
    }
    return fetch(request);
  },
};

4. Yanıtı kenarda önbellekleme

Origin’in ürettiği pahalı bir yanıtı Cloudflare’in kendi önbelleğinde tutarsın.

export default {
  async fetch(request, env, ctx) {
    const onbellek = caches.default;
    const vurus = await onbellek.match(request);
    if (vurus) return vurus;

    const yanit = await fetch(request);
    const kopya = new Response(yanit.body, yanit);
    kopya.headers.set("cache-control", "public, max-age=300");

    // Yanıtı kullanıcıya hemen gönder, önbelleğe yazmayı arka planda bitir
    ctx.waitUntil(onbellek.put(request, kopya.clone()));
    return kopya;
  },
};

ctx.waitUntil burada kritiktir: yanıt kullanıcıya gecikmeden gider, önbelleğe yazma işlemi arka planda tamamlanır.

Demo 1: on-prem API’nin önüne Workers katmanı

Bu demoyu birlikte kuracağız. Hedef mimari:

Kullanıcı  →  Cloudflare Edge (Worker: imza + hız sınırı)
                    ↓  Cloudflare Tunnel
              On-prem sunucu (iç API, internete kapalı)

Kurulum adımları:

# 1) Proje oluştur
npm create cloudflare@latest -- onprem-kapi
cd onprem-kapi

# 2) Paylaşılan sırrı gizli değişken olarak yaz (kod deposuna girmez)
npx wrangler secret put PAYLASILAN_SIR

# 3) Yerelde çalıştır — gerçek workerd çalışma zamanıyla
npx wrangler dev

# 4) Yayına al
npx wrangler deploy

Demo 2: Statik site + API tek Worker’da

Bu demo, Cloudflare’in yeni projeler için Pages yerine Workers önermesinin somut karşılığını gösterir: aynı Worker hem statik dosyaları sunar hem API’yi çalıştırır.

Adım 1 — Projeyi oluştur

npm create cloudflare@latest -- uygulamam --framework=react

pnpm create cloudflare@latest uygulamam --framework=react

yarn create cloudflare uygulamam --framework=react

{
  "name": "uygulamam",
  "main": "src/worker.js",
  "compatibility_date": "2026-08-31",
  "observability": { "enabled": true },
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application"
  }
}

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api/")) {
      return Response.json({ saat: new Date().toISOString() });
    }
    // Statik dosya bulunamazsa index.html dönsün (SPA)
    return env.ASSETS.fetch(request);
  },
};

Adım 2 — Yönlendirme sırasını doğrula

curl -s http://localhost:8787/api/saat        # Worker çalışır
curl -sI http://localhost:8787/               # statik dosya döner
curl -sI http://localhost:8787/derin/yol      # SPA: index.html döner

Adım 3 — Middleware davranışını test et

run_worker_first kapalıyken Worker’ın statik dosya isteklerini görmediğini kanıtla.

Adım 4 — Yayına al ve önbellek başlıklarını incele

npx wrangler deploy
curl -sI https://<worker>/ | grep -iE 'cache-control|etag|cf-cache-status'

Ölçüm

Fiyatlandırma

Aşağıdaki rakamlar 31 Ağustos 2026 tarihinde Cloudflare’in resmî fiyatlandırma sayfasından doğrulanmıştır.

İki gerçek hesap

Örnek A — orta ölçekli haber sitesi

• Günde 300.000 istek → ayda 9 milyon istek (10 milyon dahil sınırının altında)
• İstek başına ortalama 3 ms CPU → ayda 27 milyon CPU ms (30 milyon dahil sınırının altında)
• Aylık toplam: 5 USD

Örnek B — yoğun bir API ağ geçidi

• Günde 2 milyon istek → ayda 60 milyon istek
• İstek başına ortalama 5 ms CPU → ayda 300 milyon CPU ms

Aynı yükü kendi sunucunda karşılamak, yedekli iki sanal makine, bir yük dengeleyici ve bunların bakımı demektir. Karşılaştırmayı yaparken sadece sunucu kirasını değil, işletim maliyetini de hesaba kat.

Lisanslama ve hukuki çerçeve

Bu bölüm, kurumsal satın alma ve hukuk birimlerinin en çok sorduğu noktaları toplar.

Hizmetin lisansı. Cloudflare Workers tescilli bir hizmettir. Kullanımı Cloudflare Hizmet Şartları ve Kabul Edilebilir Kullanım Politikası ile düzenlenir. Kaynak kodu size lisanslanmaz; hizmete abone olursunuz.

Çalışma zamanı açık kaynaktır. Workers’ı çalıştıran motor olan workerd, Apache 2.0 lisansıyla GitHub’da yayımlanır. Bu pratikte şu anlama gelir: kodunu yerelde wrangler dev ile üretimdekiyle aynı çalışma zamanında test edebilirsin ve teorik olarak workerd’i kendi altyapında çalıştırabilirsin. Ancak KV, R2, D1 gibi bağlı servisler ve global ağın kendisi açık kaynak değildir — tam bir kendi kendine barındırma seçeneği yoktur.

Yazdığın kod sana aittir. Worker’ına yüklediğin kodun mülkiyeti sende kalır. Cloudflare, hizmeti sunmak için gerekli olan işleme hakkını alır.

Veri işleme ve KVKK. Kurumsal kullanımda ilgili belgeler Cloudflare’in Veri İşleme Ek Sözleşmesi ve alt işleyici listesidir. Trafiğin hangi coğrafyada işleneceğini kısıtlamak isteyen kurumlar için Data Localization Suite adında ayrı ücretlendirilen bir eklenti bulunur; standart Workers kullanımında kod, isteği karşılayan herhangi bir şehirde çalışabilir.

Sık yapılan hatalar

await edilmeyen sözler (floating promise). Yanıtı döndürdükten sonra biten bir iş varsa mutlaka ctx.waitUntil() içine alın. Aksi halde Worker yanıtı gönderdiği anda kapanır ve iş yarım kalır.

Genel (global) kapsamda durum tutmak. İzolatlar isteğe göre oluşturulup yok edilir ve farklı kullanıcılar aynı izolatı paylaşabilir. Genel değişkende kullanıcıya özel veri tutmak, veriyi başka kullanıcıya sızdırır. Kullanıcı durumu için Durable Objects veya KV kullanın.

Sırları kodun içine yazmak. API anahtarları wrangler secret put ile saklanır, wrangler.jsonc içindeki vars alanına değil. vars içeriği yayına alınan pakette açık metin olarak durur.

Gövdeyi iki kez okumak. request.body tek kullanımlık bir akıştır. Hem imza doğrulaması hem de iletme için gerekiyorsa request.clone() kullanın.

Yanıtı tamamen belleğe almak. Büyük yanıtları await response.text() ile toplamak yerine akış olarak geçirin; 128 MB bellek sınırına takılmadan ve ilk baytı geciktirmeden çalışır.