Cloudflare Workers’a TypeScript Auth Kütüphanesi Taşıma Rehberi

Geçtiğimiz yıl açık kaynaklı bir kimlik doğrulama kütüphanesi olan KavachOS’u Node.js’den Cloudflare Workers’a taşımak, geliştiriciler için sadece teknik bir geçiş değil, aynı zamanda mimari bir dönüşüm anlamına geldi. Bu süreçte, birçok popüler kütüphanenin varsayılan olarak Node.js’e özgü API’lere (ör. crypto.randomBytes, Buffer, process.env) dayandığı ortaya çıktı. Workers’ın Web API’lerine dayalı çalışma modelinde, bu bağımlılıklar doğrudan performans kayıplarına ve uyumluluk sorunlarına yol açtı.

Cloudflare Workers’ın Edge’deki Farkı ve Uyumluluk Gereksinimleri

Cloudflare Workers, JavaScript kodunu kullanıcıya mümkün olan en yakın konumda çalıştırarak 5 milisaniyenin altında soğuk başlangıç süreleri sunuyor. Bu avantaj, Node.js benzeri ortamların taklit edildiği diğer sunucu dışı platformlardan farklı olarak, tamamen web standartlarına dayalı bir çalışma modeli gerektiriyor. Sonuç olarak, Buffer, process.env veya fs modülü gibi Node.js’e has bileşenler Workers ortamında doğal olarak bulunmuyor. Bu durum, her korumalı istekte kullanılan bir kimlik doğrulama katmanı için ciddi performans ve uyumluluk riskleri oluşturuyor.

Buffer Kullanımından Web API’lerine Geçiş

En yaygın karşılaşılan sorunlardan biri, Buffer kullanımının gerektirdiği Node.js’e özgü bağımlılıklardı. Örneğin, orijinal kodda yaklaşık 60 kez kullanılan Buffer.from() ifadeleri, Workers’ın Web API’lerine uygun şekilde yeniden yazılmak zorunda kaldı. Node.js’de basit bir şekilde gerçekleştirilen işlemler, artık Uint8Array ve manuel dönüşüm yardımcılarıyla yapılmaya başlandı.

Önceki yaklaşım:

const bytes = Buffer.from(secret, "utf-8");
const hex = bytes.toString("hex");

Yeni yaklaşım:

const bytes = new TextEncoder().encode(secret);
const hex = Array.from(bytes)
  .map((b) => b.toString(16).padStart(2, "0"))
  .join("");

Ayrıca, Buffer.toString("base64url") yerine elle yapılan base64 URL kodlaması için özel bir yardımcı fonksiyon geliştirildi:

function bytesToBase64Url(bytes: Uint8Array): string {
  let binary = "";
  for (const b of bytes) binary += String.fromCharCode(b);
  return btoa(binary)
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

Bu değişiklikler, Node.js’e özgü bağımlılıkları ortadan kaldırarak paket boyutunu küçültmenin yanı sıra, Web API standartlarına tam uyum sağladı.

Node.js Crypto’dan Web Crypto’ya Geçiş

Node.js’in crypto modülü, randomBytes() veya createHash() gibi senkron yöntemler sunarken, Workers’ın Web Crypto API’si tüm işlemleri asenkron olarak gerçekleştiriyor. Bu farklılık, kod tabanında köklü değişikliklere yol açtı. Örneğin, rastgele token üretmek için kullanılan randomBytes(32) yerine, artık aşağıdaki yaklaşım benimseniyor:

const bytes = new Uint8Array(32);
crypto.getRandomValues(bytes);
const token = bytesToHex(bytes);

Benzer şekilde, SHA-256 hash oluşturmak için kullanılan createHash("sha256").update(input).digest("hex") ifadesi de asenkron bir modele uygun şekilde yeniden yazıldı:

const data = new TextEncoder().encode(input);
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hash = bytesToHex(new Uint8Array(hashBuffer));

Bu değişiklikler, yaklaşık 20 yardımcı fonksiyonun await kullanacak şekilde güncellenmesini gerektirdi. JWT işlemleri içinse, jsonwebtoken yerine jose kütüphanesi tercih edildi. Bu kütüphane, Web Crypto desteğinin yanı sıra Workers, Bun ve Deno gibi ortamlarda da sorunsuz çalışıyor.

Cloudflare D1 Veritabanı Entegrasyonu ve API Farklılıkları

Cloudflare’ın D1 veritabanı, SQLite uyumlu olmasına rağmen API açısından Node.js’de kullanılan geleneksel kütüphanelerden önemli ölçüde farklılaşıyor. Örneğin, bağlantı dizgisiyle değil, çalışma zamanı tarafından enjekte edilen binding nesnesiyle tanımlanıyor:

const kavach = await createKavach({
  database: {
    provider: "d1",
    binding: env.DB, // Cloudflare Workers tarafından enjekte edilir
  },
});

Hazır ifadelerin kullanımı da değişiyor. Node.js’de better-sqlite3 ile yapılan:

db.prepare(sql).run(...)

yerine, D1’de aşağıdaki yaklaşım benimseniyor:

db.prepare(sql).bind(...).run()

Bu değişiklikler, şema dosyalarının Node.js’de diskten okunurken, Workers’da derleme sırasında bir dize olarak paketlenmesini gerektiren bir uyarlama sürecini beraberinde getirdi.

process.env’den Explicit Config’e Geçiş

Workers ortamında process.env bulunmadığından, gizli anahtarlar ve bağımlılıklar doğrudan env nesnesi üzerinden yönetiliyor. Örneğin, kimlik doğrulama gizli anahtarı şu şekilde ayarlanıyor:

export default {
  async fetch(request: Request, env: Env) {
    const kavach = await createKavach({
      secret: env.AUTH_SECRET,
      database: {
        provider: "d1",
        binding: env.DB,
      },
    });
    return kavach.handle(request);
  },
};

Bu yaklaşım, bağımlılıkların açıkça tanımlanmasını sağlayarak test edilebilirliği artırırken, farklı ortamlar arasındaki bağımlılık enjeksiyonunu da basitleştiriyor.

TypeScript 5.8 ile ArrayBuffer Tip Kontrolleri

TypeScript 5.8’in ArrayBuffer ve Uint8Array için getirdiği daha sıkı tip denetimleri, önceki kodların derlenmesini engelledi. Örneğin, crypto.subtle.digest() fonksiyonunun ArrayBuffer döndürmesi nedeniyle, aşağıdaki ifade artık hata veriyor:

const bytes: Uint8Array = await crypto.subtle.digest("SHA-256", data);

Bu sorunun çözümü için, açık bir şekilde Uint8Array dönüşümü yapılması gerekiyor:

const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", data));

Bu değişiklik, tip güvenliğini korumak için yaklaşık 30 konumda yeniden düzenleme yapılmasını gerektirdi.

Gelecekteki Taşımalar İçin Öğrenilen Dersler

Bu geçiş süreci, geliştiricilere gelecekteki projelerde dikkat edilmesi gereken önemli dersler de sundu. Örneğin, AES-GCM şifreleme için özel bir yardımcı fonksiyon geliştirmeye iki gün harcandıktan sonra, Web Crypto API’sinin bu işlemi zaten desteklediği fark edildi. Benzer şekilde, elle yapılan bytesToBase64 fonksiyonu yerine btoa() kullanımının yeterli olduğu görüldü.

Bu deneyim, Edge’de çalışacak uygulamalar geliştirirken, yerleşik API’lerin ve standartların önceden araştırılmasının ne kadar kritik olduğunu gösteriyor. Gelecekteki projelerde, bu tür uyumluluk sorunlarını en aza indirmek için ilk aşamalarda Web Crypto ve Workers API’lerinin detaylı bir şekilde incelenmesi gerekiyor.