Bir İsteğin Yolculuğunu Çözdüm — Vitrin mi, Açık Mutfak mı?

4. Günün sonunda şöyle demiştim: “Sıradaki adım, blogun ön yüzünü bu API’ye bağlamak.” Bugün o adımı atmadan önce durdum, çünkü kendime şunu sorduğumda cevabı tam veremedim: “Birisi idrishanlabs.com’u açtığında, arka planda tam olarak hangi sırayla ne çalışıyor?” Bu yazı, kod yazmadan önce kafamdaki resmi düzelttiğim bir gün.

Bugün kod yazmadım, bir yanlış anlamayı düzelttim

Şu ana kadar kullandığım her parçayı (Cloudflare, Astro, Hono, Drizzle, Neon) tek tek anlatabiliyordum ama onları art arda, bir isteğin yolculuğu olarak anlatmaya çalışınca takıldım. İki yanlış varsayımım vardı: birincisi, sitenin her ziyaretinde Astro’nun bir şekilde devreye girdiğini sanıyordum. İkincisi, API’mi sadece “isteği taşıyan bir aracı” (bir komi) gibi görüyordum, oysa içinde gerçek bir karar verme işi var. İkisini de bir restoran benzetmesiyle düzelttim.

Restoranı iki ayrı tezgaha ayırmak gerekiyor

idrishanlabs.com bir restoran zinciri olsun. Bu zincirin, benim kafamda birbirine karışmış iki ayrı bölümü var.

Vitrin — blog sayfalarım. Önceden hazırlanmış, soğuk vitrinde duran pastaların olduğu kısım. Her git push yaptığımda (yani her deploy’da), fırıncı — Astro — elindeki tarifleri (benim yazdığım .md dosyalarını) alır, hepsini pişirir, tepsilere koyar. Bu pişirme işi bir kere olur, sabah erkenden, müşteri daha ortalıkta yokken. Pişen pastalar sonra zincirin her şubesine (Cloudflare’in dünya genelindeki veri merkezleri) aynı anda dağıtılır, vitrine dizilir.

Açık mutfak — API’m. Buradaki fark, siparişe göre o anda pişirilen şeylerin olması. Aşçı (API kodum) her zaman ayakta, sipariş bekliyor.

İkisi aynı zincire ait ama fiziksel olarak iki ayrı tezgah: biri idrishanlabs.com, diğeri blog-api.idrishanndemirdag.workers.dev — iki farklı adres, iki ayrı Cloudflare Workers projesi.

Soru: Vitrindeki pasta her seferinde yeniden mi pişiyor?

Hayır — ve bu, bugünün beni takılı bıraktığı asıl kavramdı. Bir müşteri idrishanlabs.com’u açtığında, fırıncı o an orada bile değil. Fırıncı işini sabah bitirip gitti. Müşteri geldiğinde olan tek şey: Cloudflare, en yakın şubenin vitrininden, zaten hazır duran pastayı (HTML dosyasını) uzatıyor. Hiçbir pişirme o an gerçekleşmiyor.

Buna build time (pişirme zamanı — deploy anı) ile request time (müşterinin geldiği an) arasındaki fark deniyor. Astro sadece build time’da çalışıyor. Bir müşteri geldiğinde onu asla göremezsin, çünkü işi çoktan bitmiş oluyor. Ben bu ikisini aynı an sanıyordum — asıl kafa karışıklığım buradan geliyormuş.

Açık mutfağa sipariş nasıl gidiyor

Diyelim müşteri vitrindeki pastayı değil, o anda kendisine özel bir şey istiyor (ileride: bir yazıya yorum bırakmak gibi). Vitrinden bu karşılanamaz, çünkü vitrindeki her şey önceden, herkese aynı şekilde hazırlanmış. Bunun için müşterinin açık mutfağa gitmesi lazım — tarayıcı, idrishanlabs.com yerine blog-api...workers.dev adresine ayrı bir istek atıyor.

Açık mutfak da Cloudflare’in aynı dünya çapındaki ağında duruyor (yine en yakın şube seçiliyor), ama farkı şu: orada bir aşçı o an, canlı olarak çalışıyor. Her istek geldiğinde kod gerçekten o anda çalışıyor, önceden hazırlanmış bir şey yok.

Hono: Siparişi doğru aşçıya yönlendiren kişi

“API bir komi gibi” diye düşünüyordum, ama bu eksikti. API, açık mutfağın kendisi — Hono ise o mutfağın kapısında duran, gelen her siparişi okuyup hangi tarife göndereceğine karar veren kişi. Bir komi sadece taşır; Hono ise karar verir.

Bir sipariş fişinde (gelen istekte) iki bilgi yazar: ne tür bir işlem isteniyor (GET = “bana bir şey göster”, POST = “benden bir şey al ve kaydet”) ve hangi ürün isteniyor (/api/posts mi, /api/posts/merhaba-dunya mı). Hono elindeki listeye bakıyor: “GET isteği /api/posts’a geldiyse, şu tarife git” diye önceden yazılmış kurallar var — bunları src/index.ts içine biz yazdık. Fiş listedeki bir şeyle eşleşirse, Hono o tarifi çalıştırıyor. Eşleşmezse “böyle bir sipariş yok” diyor (404).

Tarif çalışınca: Drizzle ve Neon

Eşleşen tarif (route) çalıştığında, aşçının depoya gitmesi gerekiyor — ama depoyla kendi dilinde değil, deponun anladığı dilde (SQL) konuşması lazım. Drizzle, aşçının “bana yayınlanmış tüm yazıları getir” demesini alıp deponun anladığı dile çeviriyor, cevabı da geri aşçının anlayacağı şekle çeviriyor. Neon ise bu malzemenin gerçekten durduğu depo. Aşçı eline geçeni bir tabağa (JSON) koyuyor, Hono bunu isteği atan tarafa geri gönderiyor.

Bugünden çıkardığım ders

Önceki günlerde hatalarım hep “yanlış komut yazdım” ya da “yanlış klasördeydim” gibi somuttu. Bugünkü hata farklıydı: elimde doğru parçalar vardı (Cloudflare, Astro, Hono, Drizzle, Neon), ama onları ne zaman çalıştıklarına göre değil, ne yaptıklarına göre sıralamıştım kafamda. Bir şeyin “ne işe yaradığını” bilmek yetmiyor; “ne zaman, kimin isteğiyle çalıştığını” bilmek gerekiyormuş. Vitrin ile açık mutfağı birbirinden ayırabilmek, bundan sonra frontend’i API’ye bağlarken hangi parçaya dokunduğumu net görmemi sağlayacak.

Baştan sona, adım adım

Bütün bu hikayeyi, hiç atlamadan, tam sırasıyla böyle özetledim:

Önce, müşteri daha ortalıkta yokken (hazırlık aşaması)

1. Ben yeni bir blog yazısı yazıp git push yapıyorum.
2. Astro dayı bunu görüyor, kendi merkez fırınında ekmeği (HTML’i) pişiriyor — bu tek seferlik bir pişirme, çıkan ürüne dist deniyor.
3. Cloudflare’in dağıtım ekibi bu pişmiş ekmek yığınını alıp dünya genelindeki bütün tekerlekli tezgahlara (veri merkezlerine) dağıtıyor. Astro dayı burada işini bitiriyor, eve gidiyor — artık hiçbir müşteri isteğinde onu bir daha görmüyoruz.

Sonra, bir müşteri geliyor — ihtimal 1: sıradan bir ziyaret

4. Müşteri idrishanlabs.com’u açıyor.
5. En yakın tezgah bulunuyor, orada zaten hazır duran ekmek (HTML sayfası) doğrudan müşteriye veriliyor. Astro dayı’nın bundan haberi bile yok, çağrılmadı.

İhtimal 2: Müşteri özel bir sipariş istiyor

6. Müşterinin isteği vitrindekilerle karşılanamıyor — tarayıcı bu sefer farklı bir adrese, açık mutfağın kapısına (blog-api...) gidiyor.
7. Hono dayı kapıda bu siparişi karşılıyor, elindeki tarif defterine bakıyor.
8. Defterde eşleşen bir tarif varsa, Hono dayı o tarifi o anda uygulamaya başlıyor. Yoksa “böyle bir siparişimiz yok” diyor.
9. Tarif diyor ki: “depoya git, şu malzemeyi getir.” Ama depo (Neon) farklı bir dil konuşuyor, Hono dayı tek başına anlaşamıyor — yanına tercümanı (Drizzle) alıyor.
10. Drizzle, Hono dayı’nın isteğini depo diline çevirip depoya gidiyor, malzemeyi (veriyi) alıp Hono dayı’nın anlayacağı dile geri çeviriyor.
11. Hono dayı eline geçen malzemeyi bir tabağa diziyor (JSON), kapıdan doğrudan siparişi veren müşteriye uzatıyor.

Sırada ne var?

Artık resim netleşti: vitrin (blog sayfaları) hâlâ .md dosyalarından besleniyor, açık mutfak (API) ise Neon’dan. Sıradaki adım tam olarak bu ikisini birleştirmek — Astro’nun, pasta pişirirken artık .md dosyaları yerine açık mutfaktaki (API’deki) gerçek veriyi okumasını sağlamak.