jskelet 0.1.1 → 0.1.3

package/docs/06-cache.md

@@ -4,8 +4,9 @@ Bu belge JSkelet'in ISR ikamesini bütün ayrıntılarıyla anlatır: HTML TTL
 önbelleği ve stale-while-revalidate davranışı, `revalidate`'in nereden geldiği,
 cache anahtarının nasıl kurulduğu, `X-JSkelet-Cache` başlığının değerleri,
 sıkıştırılmış gövdenin neden önbellekte durduğu, istek içi memoizasyon
-(`withRequestCache` / `cache()`), upstream hatalarının önbelleği nasıl
-etkilediği (`reportUpstreamFailure`) ve sunucu açılışındaki ısıtma turu.
+(`withRequestCache` / `cache()`), veri önbelleği (`withDataCache`), upstream
+hatalarının önbelleği nasıl etkilediği (`reportUpstreamFailure`) ve sunucu
+açılışındaki ısıtma turu.
 Kararların arkasındaki ölçüm gerekçeleri [02-mimari.md](./02-mimari.md)'de,
 config alanlarının tam referansı [07-yapilandirma.md](./07-yapilandirma.md)'de.
 
@@ -17,12 +18,51 @@ route(controller, { revalidate })
      └─ withUpstreamTracking(...)              ← eksik veri tespiti
          └─ withRequestCache(...)              ← istek içi memoizasyon
              └─ produce() → controller + renderPage
+                              └─ withDataCache(...)  ← upstream veri önbelleği
 ```
 
 Sıra önemli: **istek içi cache en içte** olmalı ki aynı render'daki iki çağrı
 tek upstream isteğine düşsün; **upstream takibi HTML cache'in içinde** olmalı ki
 eksik veriyle üretilen çıktı önbelleğe yazılmasın.
 
+İki önbelleğin iş bölümü:
+
+| | HTML önbelleği | Veri önbelleği |
+| --- | --- | --- |
+| Ne tutar | Sayfanın tamamı (+ sıkıştırılmış gövdesi) | Upstream'den gelen JSON |
+| Girdi boyutu | ~100-200 kB | ~1-20 kB |
+| Girdi sınırı | 500 (`cache().maxEntries`) | 10.000 (`cache().data.maxEntries`) |
+| Kime yarar | Trafiği olan sayfalar: render bile edilmez | Uzun kuyruk: render edilir ama API'ye gidilmez |
+
+Bu ayrım pratikte şuna karşılık gelir: on binlerce yollu bir sitede sayfaların
+tamamını HTML olarak sıcak tutmak mümkün değil — 500 girdiyi aşan ısıtma kendi
+ısıttığını siler. Uzun kuyruk için hedef "HTML hazır olsun" değil, **"sayfayı
+üretecek veri API'ye gitmeden bulunsun"** olmalı. O zaman hiç ısıtılmamış bir
+sayfa da ilk ziyaretçide milisaniyeler içinde üretilir ve kota harcamaz.
+
+## Public ve kişiye özel ayrımı
+
+Bu belgedeki her şey **herkese aynı gidebilen** HTML için geçerli. Cache
+anahtarında kimlik yok (yalnızca yol + query), yani önbellekteki bir sayfa onu
+ilk isteyen kişinin değil, o yolun cevabıdır.
+
+Kullanıcıya bağlı bir sayfa bu yüzden ayrı bir yoldan geçer:
+
+```js
+app.get("/panel", route(async ({ req }) => { … }, { private: true }));
+```
+
+`private: true` üç şeyi birden yapar: önbellek devre dışı kalır, config'in
+`cache.html` deseni bu kararı **ezemez** ve yanıt `private, no-store`,
+`Vary: Cookie` ile, ETag'siz gider. Ayrıntılar ve oturum/CSRF tarafı
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de.
+
+Bayrağı unutursanız framework sessiz kalmaz: controller `Cookie`,
+`Authorization` ya da `req.session`/`req.user` okuduğu anda render işaretlenir
+ve önbelleğe **yazılmaz**. Dev'de istek bir hatayla düşer, üretimde `no-store`
+ile servis edilip loglanır. Koruma bir mazeret değil son savunma — doğru yer
+`private: true`.
+
 ## `revalidate` — TTL nereden gelir
 
 Bir route'un TTL'i iki kaynaktan gelebilir ve **config kazanır**:
@@ -31,6 +71,9 @@ Bir route'un TTL'i iki kaynaktan gelebilir ve **config kazanır**:
 2. `jskelet.config.mjs` → `cache().html` içindeki eşleşen desen. Varsa
    route'unkini ezer.
 
+Tek istisna `private: true`: desen eşleşse bile yok sayılır. Kilit tek yönlü,
+çünkü ters yönde bir hata sessiz veri sızıntısı anlamına geliyor.
+
 ```js
 // jskelet.config.mjs
 export default {
@@ -53,8 +96,14 @@ mümkün kılar; route dosyalarını dolaşmak gerekmez.
 yapılmaz. Hiç `cache().html` kuralı yoksa doğrudan route'un değeri kullanılır.
 
 `revalidate` verilmemişse ya da 0 ise sayfa **hiç önbelleklenmez**: her istek
-render edilir ve yanıta `Cache-Control` yazılmaz (yalnızca
-`X-JSkelet-Cache: MISS`).
+render edilir ve yanıt `Cache-Control: private, no-store` ile, ETag'siz gider.
+`X-JSkelet-Cache` başlığı da yazılmaz — önbellek yolu hiç çalışmadı, `MISS`
+demek yanıltıcı olurdu.
+
+Dinamik bir sayfaya `no-store` yazılması bilinçli. Hiç direktif taşımayan bir
+yanıtı HTTP "sezgisel olarak önbelleklenebilir" sayıyor; araya giren bir proxy
+ya da tarayıcının geri tuşu, tek bir ziyaretçi için üretilmiş HTML'i
+saklayabiliyordu.
 
 Önbellek ayrıca yalnızca `GET` istekleri için devreye girer.
 
@@ -70,8 +119,8 @@ ile `/liste?sayfa=3` ayrı girdilerdir.
 Bunun pratik sonucu: query string'e bağlı olmayan bir sayfa, farklı kampanya
 parametreleriyle (`?utm_source=…`) çağrıldığında her kombinasyon için ayrı bir
 girdi üretir. Bu tür parametreleri ters proxy katmanında temizlemek ya da
-önbelleği kapatmak (`revalidate` vermemek) makul bir önlemdir; store en fazla
-500 girdi tutar ve LRU ile en eskiyi düşürür.
+önbelleği kapatmak (`revalidate` vermemek) makul bir önlemdir; store varsayılan
+olarak en fazla 500 girdi tutar ve LRU ile en eskiyi düşürür.
 
 ## Stale-while-revalidate
 
@@ -92,7 +141,7 @@ Okuma davranışı:
 
 Stale penceresinde tazelemenin hatası isteği etkilemez: eski HTML pencere
 boyunca geçerli kalır ve hata yalnızca loglanır
-(`[html-cache] arka plan tazelemesi başarısız: …`).
+(`[html-cache] background refresh failed: …`).
 
 Aynı anahtar için eşzamanlı tazelemeler tek bir çalışmada birleştirilir
 (`inflight` haritası): yüz eşzamanlı istek tek render'a düşer.
@@ -102,8 +151,8 @@ veri en fazla `revalidate + bir tazeleme turu` kadar geride olabilir. Bu bedel
 kabul edilebilir, çünkü fiyat gibi canlı alanlar istemcide WebSocket'ten
 güncelleniyor.
 
-Store LRU'dur: erişilen girdi sona taşınır, `MAX_ENTRIES = 500` aşılınca en
-eski düşürülür.
+Store LRU'dur: erişilen girdi sona taşınır, sınır (`cache().maxEntries`,
+varsayılan 500) aşılınca en eski düşürülür.
 
 ## Ne önbelleğe yazılır
 
@@ -184,6 +233,82 @@ Ayrıntılar:
 - `withRequestCache(run)` dışa açıktır; `route()` dışında (ör. kendi yazdığınız
   bir Express handler'ında) aynı kapsamı kurmak için kullanılabilir.
 
+## İstekler arası veri önbelleği: `withDataCache`
+
+`cache()` yalnızca **tek bir istek** boyunca yaşar. Uzun kuyruğu API kotasından
+korumak için gereken şey istekler arasında yaşayan, TTL'li ve kendi kendini
+tazeleyen bir veri katmanı:
+
+```js
+// lib/api/articles.js
+import { withDataCache, reportUpstreamFailure } from "jskelet";
+
+export async function getArticle(slug) {
+  return withDataCache(`haber:${slug}`, 600, async () => {
+    const response = await fetch(`${process.env.API_ORIGIN}/articles/${slug}`);
+
+    if (!response.ok) {
+      reportUpstreamFailure({ status: response.status, path: `/articles/${slug}` });
+      return null;
+    }
+
+    return response.json();
+  });
+}
+```
+
+Aynı kalıbın sarmalayıcı biçimi — anahtar argümanlardan üretilir:
+
+```js
+import { dataCache } from "jskelet";
+
+export const getArticle = dataCache(
+  async (slug) => apiGet(`/articles/${slug}`),
+  { key: "haber", revalidate: 600 },
+);
+```
+
+Davranış:
+
+| Durum | Sonuç |
+| --- | --- |
+| Taze girdi | Anında döner, `producer` çalışmaz |
+| TTL geçmiş, bayat pencere sürüyor | Bayat değer **anında** döner, tazeleme arkada yürür |
+| Girdi yok | `producer` beklenir |
+| `producer` hata verdi, bayat girdi var | Bayat değer döner, uyarı: `[data-cache] producer failed, serving stale value: …` |
+| `producer` hata verdi, girdi yok | Hata çağırana gider |
+
+Ayrıntılar:
+
+- **Aynı anahtarı eşzamanlı isteyen çağrılar tek upstream isteğine düşer.**
+  Isıtma turlarında kotayı en çok kurtaran davranış bu: 50 sayfa aynı endeks
+  verisini istiyorsa API bir kez çağrılır.
+- **`null` ve `undefined` saklanmaz.** Uygulamaların HTTP istemcisi hatada
+  genellikle `null` döner; bunu saklamak geçici bir 429'u TTL boyunca "veri yok"
+  hâline dondurmak olurdu. Boş cevabı bilinçli olarak saklamak isteyen
+  `{ storeEmpty: true }` verir.
+- **Bayat pencere HTML'dekinden uzun**: `staleFactor` varsayılanı 10, yani girdi
+  TTL'inin 11 katı boyunca acil durum yedeği olarak kalır. Bayat veri, eksik
+  sayfadan iyidir. Anahtar başına `{ staleFactor: 0 }` ile kapatılabilir.
+- Anahtar tamamen uygulamanın: dil, sürüm, sayfa numarası gibi ayrımlar anahtara
+  yazılır (`haber:tr:v2:${slug}`).
+- TTL `0` verildiğinde önbellek devre dışı kalır ve `producer` her çağrıda
+  çalışır — bir ayarı geçici olarak kapatmak için yeterli.
+
+Yönetim yüzeyi:
+
+| Fonksiyon | Ne yapar |
+| --- | --- |
+| `withDataCache(key, ttlSeconds, producer, options?)` | Ana giriş noktası |
+| `dataCache(fn, { key, revalidate, … })` | Fonksiyon sarmalayıcısı |
+| `clearDataCache(prefix?)` | Önek eşleşen girdileri (ya da tümünü) düşürür, silinen sayısını döner |
+| `getDataCacheSize()` | Girdi sayısı |
+| `getDataCacheEntries()` | Döküm: `{ key, stale, expiresIn }`. Değerin kendisi dönmez. |
+
+`clearDataCache("haber:")`, "bu içerik güncellendi" webhook'unun karşılığıdır:
+tek bir bölümün verisini düşürüp HTML'in bir sonraki tazelemesinde yeni içeriği
+almasını sağlar.
+
 ## Degraded render: `reportUpstreamFailure`
 
 Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir. Böyle bir
@@ -220,14 +345,40 @@ export async function apiGet(path) {
 
 | Durum | Sayılır | Sonuç |
 | --- | --- | --- |
-| `0` (ağ hatası), `408`, `425`, `429`, `>= 500` | **Geçici** | Sayfa önbelleğe yazılmaz, uyarı: `[render] <yol> eksik veriyle üretildi, önbelleğe alınmıyor (…)` |
-| Diğerleri (`400`, `403`, `404`, …) | **Kalıcı** | Yalnızca uyarı: `[render] <yol> eksik veriyle üretildi, upstream kalıcı hata veriyor (…)`. Önbellek engellenmez. |
+| `0` (ağ hatası), `408`, `425`, `429`, `>= 500` | **Geçici** | Sayfa önbelleğe yazılmaz, uyarı: `[render] <path> was produced with missing data, not caching it (…)` |
+| Diğerleri (`400`, `403`, `404`, …) | **Kalıcı** | Yalnızca uyarı: `[render] <path> was produced with missing data, upstream is failing permanently (…)`. Önbellek engellenmez. |
 
 Kalıcı hataların önbelleği engellememesi bilinçli: deterministik cevaplar tekrar
 denemekle düzelmez. Onlar yüzünden önbelleği kapatmak sayfayı her ziyarette
 baştan render etmek olur — içerik yine aynı eksik hâliyle döner, ziyaretçi
 sadece render süresini öder.
 
+Eksik veriyle üretilen çıktı **paylaşılan önbelleklere de sunulmaz**: `degraded`
+bir yanıt `public, s-maxage=…` değil `private, no-store` alır. Süreç içi
+önbelleğe yazmama kararını CDN'de geri almak, aynı hatayı bir katman yukarıda
+tekrarlamak olurdu. Teşhis başlığı (`X-JSkelet-Cache: MISS`) yine yazılır.
+
+### `notFound()` geçici hataya denk gelirse
+
+Veri gelmediği için `notFound()` çağıran bir controller, upstream rate limit'e
+girdiğinde tüm siteyi 404'e çevirebilir — ve bu 404'ler önbelleğe girdiği için
+geçici bir kota sorunu TTL boyunca "bu sayfa yok" cevabına dönüşür. Arama motoru
+için bu kalıcı bir kayıp.
+
+Framework bu durumu ayırır: render sırasında **geçici** bir upstream hatası
+bildirilmişse `notFound()` 404 olarak servis edilmez.
+
+| Render sırasında | `notFound()` sonucu |
+| --- | --- |
+| Geçici hata var (`429`, `5xx`, ağ hatası) | `503`, `Retry-After: 30`, `no-store` — önbelleğe **girmez**, sonraki istek gerçek içeriği üretir |
+| Kalıcı hata var (`404`, `403`…) ya da hata yok | Normal `404` |
+
+Log satırı:
+`[render] /haber/x returned notFound() while upstream is failing (429 /api/...), serving an uncached 503 instead`
+
+Yani upstream'in kotası dolduğunda sayfa dinamik olarak, önbelleğe yazılmadan
+üretilir; hiçbir şey "yok" olarak dondurulmaz.
+
 ## Önbelleği yönetmek
 
 `jskelet` şu fonksiyonları dışa açar:
@@ -303,23 +454,74 @@ Kurallar:
 - Yalnızca `/` ile başlayan string'ler alınır.
 - `prewarmSkip` öneklerinden biriyle başlayanlar atlanır. Varsayılan liste:
   `/api/`, `/_fragment/`, `/__jskelet/`. Oturuma bağlı sayfalar ısıtılmamalı.
-- Tekilleştirme **sırayı korur**: liste `PREWARM_MAX` ile budandığı için
-  uygulamanın verdiği öncelik sırası anlamlıdır — en önemli sayfaları başa
-  koyun.
+- Tekilleştirme **sırayı korur**: `priority` verilmediğinde uygulamanın verdiği
+  sıra anlamlıdır — en önemli sayfaları başa koyun.
 - Bu hook tanımlı değilse ısıtma hiç kurulmaz; zamanlayıcı bile açılmaz.
 
 ### Tur mantığı
 
-1. Liste toplanır, `PREWARM_MAX` (varsayılan 400) ile budanır.
-2. `PREWARM_CONCURRENCY` işçi paralel olarak istek atar (prod'da 4, dev'de 2).
-   Dev'de daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın
-   render'ıyla CPU için yarışmasın.
-3. Başarısız yollar için **tek seri tekrar turu** yapılır (`concurrency: 1`).
-   Hatalar çoğunlukla upstream rate limit'i (429): ilk tur yüzlerce sayfayı aynı
-   anda çekerken API'yi zorluyor. Tekrar turu bu sayfaların önbelleğe girmesini
-   sağlıyor; aksi hâlde ziyaretçi soğuk render'ı öder.
-4. Özet loglanır:
-   `[prewarm] 128/130 sayfa ısıtıldı, 2 hata, 5 sayfa tekrar turunda kurtarıldı (12.4s)`
+1. Liste toplanır. `max`'tan (varsayılan 400) uzunsa bir dilim seçilir:
+   `priority` eşleşenler **her turda** başa alınır, kalan yerler kuyruktan
+   doldurulur.
+2. `concurrency` işçi paralel olarak istek atar (prod'da 4, dev'de 2). Dev'de
+   daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU
+   için yarışmasın.
+3. `rps` verilmişse tur bu hızın üstüne çıkmaz — paralellik ne olursa olsun.
+4. Başarısız yollar için, `retryDelayMs` bekledikten sonra **tek seri tekrar
+   turu** yapılır (`concurrency: 1`). Bekleme bilinçli: rate limit pencereleri
+   saniye mertebesinde, hemen tekrar denemek aynı 429'u almak demek.
+5. Özet loglanır:
+   `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
+
+### Isıtma sırası: `priority`
+
+```js
+// jskelet.config.mjs
+cache: () => ({
+  prewarm: {
+    priority: [
+      "/",
+      "/piyasalar/:path*",
+      /-yorumlar$/,
+    ],
+  },
+}),
+```
+
+Desen sözdizimi (`/haber/:slug`) ve doğrudan `RegExp` birlikte kullanılabilir;
+ikincisi "sonu `-yorumlar` ile bitenler" gibi desen sözdiziminin karşılamadığı
+kurallar için. Önce yazılan önce ısınır, hiçbirine uymayan yollar kuyruğa gider
+ve kendi aralarındaki sırayı korur.
+
+### Damla damla ısıtma: `rotate` + `rps` + `intervalSeconds`
+
+10.000 yolluk bir sitede tek turda her şeyi ısıtmak ne mümkün (HTML önbelleği
+500 girdi tutar) ne de doğru (API kotası dolar). Doğru davranış listeyi zamana
+yaymak:
+
+```js
+prewarm: {
+  max: 300,               // her turda 300 sayfa
+  rps: 4,                 // saniyede en fazla 4 istek
+  intervalSeconds: 300,   // 5 dakikada bir tur
+  rotate: true,           // kuyruk kaldığı yerden devam eder
+  priority: ["/", "/piyasalar/:path*"],
+}
+```
+
+Bu kurulumda öncelikli sayfalar her turda tazelenir, geri kalan kuyruk turlar
+boyunca baştan sona dolaşılır ve upstream saniyede dört isteğin üstünü hiç
+görmez. Veri önbelleği ile birlikte kullanıldığında ikinci turdan sonra ısıtma
+API'ye neredeyse hiç gitmez: veri katmanından okur.
+
+Rotasyon açıkken sınırın dışında kalan yollar kaybolmuyor, bir sonraki tura
+kalıyor; log bunu ayırt eder:
+`… , 700 deferred to the next pass`. `rotate: false` ile klasik davranışa
+dönülür — her tur listenin aynı ilk dilimini ısıtır ve gerisi hiç ısınmaz
+(`… , 700 over the limit`).
+
+Bir tur `intervalSeconds`'tan uzun sürerse yeni tur başlatılmaz; üst üste binen
+turlar upstream'e iki kat yük bindirirdi.
 
 İstekler `user-agent: jskelet-prewarm` (`brand.prewarmUserAgent`) ve
 `accept-encoding: br, gzip` başlıklarıyla gider; ikincisi sıkıştırılmış gövdenin
@@ -353,10 +555,14 @@ tek seferlik deneyler config'i düzenlemeden yapılabilsin.
 | Ayar | Env | `cache().prewarm` | Varsayılan |
 | --- | --- | --- | --- |
 | Açık/kapalı | `PREWARM=0` kapatır, `PREWARM=1` config'i ezip açar | `enabled` | `true` |
-| En fazla yol | `PREWARM_MAX` | `max` | `400` |
+| Tur başına en fazla yol | `PREWARM_MAX` | `max` | `400` |
 | Paralellik | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
+| Saniyedeki istek | `PREWARM_RPS` | `rps` | `0` (sınırsız) |
 | Başlangıç gecikmesi (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
+| Tekrar turu gecikmesi (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Periyot (saniye) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (kapalı) |
+| Kuyruk rotasyonu | — | `rotate` | `true` |
+| Isıtma sırası | — | `priority` | `[]` |
 
 Sayısal ayarlar yalnızca **pozitif ve sonlu** değer kabul eder; geçersiz bir
 değer sessizce bir sonraki katmana düşer.
@@ -392,7 +598,7 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   `cache().html` içindeki desen 0 saniye veriyor. Veya sayfa `status: 200`
   dışında bir kod dönüyor.
 - **Sayfa `MISS` dönüyor ama upstream sağlam.** Geçici bir upstream hatası
-  bildirilmiş olabilir; logda `eksik veriyle üretildi, önbelleğe alınmıyor`
+  bildirilmiş olabilir; logda `was produced with missing data, not caching it`
   satırını arayın.
 - **Sürekli eski veri.** `revalidate` çok yüksek; unutmayın ki gerçek gecikme en
   fazla `revalidate` + bir tazeleme turudur.
@@ -400,6 +606,14 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   parametreleri girdi çoğaltıyor olabilir.
 - **Isıtma hiç çalışmıyor.** `hooks.prewarmPaths` tanımlı değil, `PREWARM=0`
   ayarlı ya da `cache().prewarm.enabled === false`.
+- **Isıtma turu API'yi 429'a sokuyor.** `rps` verilmemiş. `concurrency`
+  düşürmek yeterli değil; kotayı koruyan ayar toplam hız. Kalıcı çözüm veri
+  önbelleği: ikinci turdan sonra ısıtma upstream'e gitmez.
+- **Isıtma listesi `max`'tan uzun ve sonu hiç ısınmıyor.** `rotate: false`
+  olabilir; logdaki `over the limit` ifadesi bunu gösterir.
+- **Bir bölümün tamamı 404 dönüyor.** Upstream düşmüş olabilir. Artık bu durumda
+  404 değil önbelleğe girmeyen 503 dönüyor; logda `returned notFound() while
+  upstream is failing` satırını arayın.
 
 ## Sırada ne var
 

package/docs/07-yapilandirma.md

@@ -25,7 +25,7 @@ düz değer** olabilir; fonksiyon olmaları hâlinde `async` olabilirler ve `thi
 config nesnesine bağlıdır. Bir bölüm hata verirse yalnızca o bölüm yok sayılır.
 
 Config başarıyla yüklendiğinde bir özet basılır:
-`[config] jskelet.config.mjs yüklendi — 3 header, 2 redirect, 1 cache kuralı`
+`[config] jskelet.config.mjs loaded — 3 headers, 2 redirects, 1 cache rule`
 
 ## Tam örnek
 
@@ -62,6 +62,20 @@ export default {
   devGateBypass: ["/api/healthcheck", "/robots.txt"],
   preconnect: ["https://cdn.ornek.com"],
 
+  security: {
+    trustProxy: true,
+    cookieSecret: process.env.JSKELET_SECRET,
+    csrf: {
+      enabled: true,
+      token: false,
+      allowedOrigins: [],
+      exclude: ["/webhook/:path*"],
+      cookieName: "csrf_token",
+      fieldName: "_csrf",
+      headerName: "x-csrf-token",
+    },
+  },
+
   navigation: {
     prefetch: "moderate",
     prerender: "conservative",
@@ -101,7 +115,17 @@ export default {
   async cache() {
     return {
       html: { "/": 60, "/haber/:slug": 300 },
-      prewarm: { enabled: true, max: 400, concurrency: 4, intervalSeconds: 0 },
+      maxEntries: 500,
+      data: { maxEntries: 10000, staleFactor: 10 },
+      prewarm: {
+        enabled: true,
+        max: 400,
+        concurrency: 4,
+        rps: 0,
+        intervalSeconds: 0,
+        rotate: true,
+        priority: ["/", "/haber/:slug"],
+      },
     };
   },
 
@@ -239,6 +263,37 @@ bir yapılandırmadır.
 preconnect: ["https://cdn.ornek.com", "https://api.ornek.com"]
 ```
 
+## `security`
+
+**Tip:** `object` — **Varsayılan:**
+`{ trustProxy: true, cookieSecret: null, csrf: { enabled: true, token: false, … } }`
+
+Kişiye özel sayfaların tamamı ve gerekçeleri
+[12-panel-ve-oturum.md](./12-panel-ve-oturum.md)'de; burada alanların referansı
+var.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `trustProxy` | `boolean` | `true` | Express'in `trust proxy` ayarı. Ters proxy arkasında doğru protokol ve istemci IP'si için gerekli. |
+| `cookieSecret` | `string \| null` | `null` | İmzalı cookie sırrı. Verilmezse `JSKELET_SECRET` okunur. |
+| `csrf.enabled` | `boolean` | `true` | Origin/`Sec-Fetch-Site` kontrolü. |
+| `csrf.token` | `boolean` | `false` | Çift gönderim token'ı katmanı. |
+| `csrf.allowedOrigins` | `string[]` | `[]` | Kendi host'umuzun yanında kabul edilen origin'ler. |
+| `csrf.exclude` | `string[]` | `[]` | Kontrolden muaf yollar; `source` desen sözdizimi. |
+| `csrf.cookieName` | `string` | `"csrf_token"` | Token cookie'sinin adı. |
+| `csrf.fieldName` | `string` | `"_csrf"` | `csrfField()`in bastığı alan adı. |
+| `csrf.headerName` | `string` | `"x-csrf-token"` | Token'ın kabul edildiği başlık. |
+
+`trustProxy` doğrudan internete açık bir sunucuda **kapatılmalı**: açıkken
+istemci kendi `X-Forwarded-For` başlığını uydurabilir ve rate limit ile audit
+log yanlış adresi görür.
+
+CSRF kontrolü yalnızca çapraz site olduğu **belli** olan istekleri reddeder —
+`Origin` uyuşmuyorsa ya da `Sec-Fetch-Site: cross-site` geldiyse. İkisi de yoksa
+istek geçer, çünkü tarayıcılar çapraz origin bir POST'ta `Origin`'i her zaman
+gönderirken webhook'lar hiç göndermez. Yine de tarayıcıdan gelmeyen uçları
+`csrf.exclude` listesine yazmak niyeti okunur kılıyor.
+
 ## `navigation`
 
 **Tip:** `object` — **Varsayılan:**
@@ -504,8 +559,10 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 
 ## `cache()`
 
-**Tip:** `() => { html?: Record<string, number>, prewarm?: object }` —
-**Varsayılan:** `{ html: {}, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+**Tip:**
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, prewarm?: object }` —
+**Varsayılan:**
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -521,18 +578,59 @@ html: {
 }
 ```
 
+Tek istisna `route(fn, { private: true })`: bu route'ta desen eşleşse bile yok
+sayılır. Kilidin tek yönlü olması bilinçli — ters yönde bir hata, bir
+kullanıcının HTML'inin bir başkasına servis edilmesi anlamına geliyor.
+
+### `cache().maxEntries`
+
+**Tip:** `number` — **Varsayılan:** `500`
+
+HTML önbelleğinin girdi sınırı. Girdi başına yüz kilobayt düştüğü için bu sayıyı
+yükseltmek belleği hızla tüketir; on binlerce yollu bir siteyi buradan çözmeye
+çalışmak yanlış katman, doğru yer `cache().data`.
+
+### `cache().data`
+
+Upstream veri önbelleği (`withDataCache`). Ayrıntı: [06-cache.md](./06-cache.md).
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `maxEntries` | `number` | `10000` | LRU girdi sınırı. JSON, HTML'e göre onlarca kat küçük olduğu için sınır yüksek. |
+| `staleFactor` | `number` | `10` | TTL dolduktan sonra girdinin kaç TTL boyunca daha kullanılabileceği. `0` → bayat servis yok. |
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
-| `max` | `number` | `400` | En fazla kaç yol ısıtılır |
+| `max` | `number` | `400` | Bir turda en fazla kaç yol ısıtılır |
 | `concurrency` | `number` | prod 4, dev 2 | Paralel işçi sayısı |
+| `rps` | `number` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. |
 | `delayMs` | `number` | prod 500, dev 3000 | Açılıştan sonra ilk turun gecikmesi |
+| `retryDelayMs` | `number` | `2000` | Tekrar turundan önce beklenen süre |
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
+| `rotate` | `boolean` | `true` | Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder |
+| `priority` | `(string \| RegExp)[]` | `[]` | Isıtma sırası; eşleşen yollar her turda başa alınır |
 
-Her biri aynı adı taşıyan ortam değişkeniyle ezilebilir; env önceliklidir.
-Ayrıntı: [06-cache.md](./06-cache.md).
+`priority` iki biçim kabul eder: config'in her yerinde geçerli olan desen
+sözdizimi ve doğrudan `RegExp`. Önce yazılan önce ısınır.
+
+```js
+prewarm: {
+  max: 500,
+  rps: 4,
+  intervalSeconds: 300,
+  priority: [
+    "/",                     // ana sayfa
+    "/piyasalar/:path*",      // tüm piyasa bölümü
+    /-yorumlar$/,             // desen sözdiziminin karşılamadığı kural
+  ],
+}
+```
+
+Sayısal alanların her biri aynı adı taşıyan ortam değişkeniyle ezilebilir; env
+önceliklidir. Ayrıntı: [06-cache.md](./06-cache.md).
 
 ## `hooks`
 
@@ -622,11 +720,14 @@ basılmaz.
 | `NODE_ENV` | her yer | `production` (start/build), `development` (dev) | Dev overlay, EJS cache, manifest yeniden okuma, route hata davranışı ve prewarm varsayılanlarını belirler. `jskelet dev` bunu kendisi ayarlar — `cross-env` gerekmez. |
 | `PORT` | `startServer` | `3000` | Dinlenecek port |
 | `HOST` | `startServer` | `0.0.0.0` | Bağlanılacak arayüz |
+| `JSKELET_SECRET` | `jskelet/cookies` | — | İmzalı cookie sırrı. `security.cookieSecret` verilmediğinde buradan okunur; ikisi de yoksa imzalı cookie API'si hata verir. [12](./12-panel-ve-oturum.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 2 | Paralel işçi sayısı |
+| `PREWARM_RPS` | `prewarm` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | İlk turun gecikmesi |
+| `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | Tekrar turundan önceki bekleme |
 | `PREWARM_INTERVAL_SECONDS` | `startPrewarm` | `0` | 0'dan büyükse periyodik tur |
 | `JSKELET_VERBOSE` | `jskelet dev` | — | `1` ise restart'ta değişen dosyaların tamamı listelenir |
 | `JSKELET_COLOR` | `jskelet/log` | — | `1` ise renk zorlanır. Alt süreçler boruya yazdığı için renk algılaması kapanır; `jskelet dev` bunu kendisi ayarlar. |

package/docs/08-build.md

@@ -69,7 +69,7 @@ dosya adlarını okunur tutuyor. Hash'li olmaları sayesinde bu dosyalara
 Build çalışmadıysa uygulama yine ayağa kalkar: `hasAsset()` false olur, layout
 stylesheet ve script etiketlerini hiç basmaz. `jskelet build` unutulduğunda hata
 yerine stilsiz ama çalışan bir sayfa görürsünüz. Manifest hiç yoksa bir kez uyarı
-basılır: `[assets] manifest yok — 'jskelet build' çalıştırın.`
+basılır: ``[assets] no manifest — run `jskelet build`.``
 
 Manifest **dev'de her istekte** yeniden okunur (watch build hash'leri
 değiştirir), prod'da bir kez.
@@ -244,8 +244,8 @@ Son satır için iki güvenlik ağı var: ad taşıyan yapılandırma alanları
 sembolleri okuyup eksik olan için tek seferlik uyarı basar:
 
 ```
-[icon] sprite'ta yok: x-logo-regular — adı sabit yazın ya da
-build/tasks/icons.mjs taramasına ekleyin.
+[icon] missing from sprite: x-logo-regular — write the name as a literal or add
+it to the build/tasks/icons.mjs scan.
 ```
 
 Bu uyarıyı görürseniz ya adı sabit yazın, ya `icons.scan` listesine ilgili
@@ -352,7 +352,7 @@ karşılaşmaması.
   kontrol edin.
 - **Bazı Tailwind sınıfları çalışmıyor.** `@source` direktifi eksik olan bir
   dizinde yazılmışlar.
-- **İkon boş görünüyor.** Sprite'ta o sembol yok; dev'de `[icon] sprite'ta yok`
+- **İkon boş görünüyor.** Sprite'ta o sembol yok; dev'de `[icon] missing from sprite`
   uyarısına bakın.
 - **Island'lar hiç açılmıyor.** `main.js` manifest'te yok (entry dizini boş ya
   da build atlanmış) veya bir build hatası var.

package/docs/09-dev-araclari.md

@@ -161,6 +161,11 @@ Gösterdikleri:
 - **Prewarm:** ısıtma turunun ilerlemesi; panelden elle tetiklenebilir, tek tek
   yollar tekrar denenebilir.
 - **Süreç:** pid, Node sürümü, uptime, RSS ve heap kullanımı.
+- **Sürüm:** kurulu JSkelet sürümü ve npm'deki `latest` ile karşılaştırması.
+  Yeni bir sürüm varsa **Server** sekmesinde `update` rozeti ve yükseltme
+  komutunu kopyalayan bir satır çıkar. Yoklama açılıştan 1,5 saniye sonra bir
+  kez yapılır, sonucu 6 saat boyunca `os.tmpdir()` içinde saklanır ve ağ yoksa
+  sessizce atlanır. `JSKELET_VERSION_CHECK=0` ile tamamen kapatılır.
 
 Isıtma istekleri (`user-agent: jskelet-prewarm`) hem terminalden hem istek
 listesinden filtrelenir: yüzlerce istek görünümü doldurmasın. İlerleme baloncuğun