jskelet 0.2.1 → 0.2.3

package/docs/03-routing.md

@@ -123,6 +123,10 @@ app.get(
 | `revalidate` | `number` (saniye) | HTML önbellek TTL'i. Verilmezse ya da 0 ise bu route önbelleklenmez. `jskelet.config.mjs` → `cache().html` içindeki eşleşen bir kural bu değeri **ezer**. |
 | `private` | `boolean` | Sayfa ziyaretçiye bağlı. Önbellek devre dışı kalır, `cache().html` deseni bunu **ezemez**, yanıt `private, no-store` ve `Vary: Cookie` ile ETag'siz gider. |
 
+`revalidate` verilse bile **query parametresi taşıyan istek varsayılan olarak
+dinamiktir**; o yol için `cache().query` altında bir izin listesi tanımlamak
+gerekir ([06-cache.md](./06-cache.md)).
+
 Oturuma bağlı her sayfa `private: true` almalı; önbellek anahtarında kimlik
 olmadığı için bayrak olmadan bir kullanıcının HTML'i bir başkasına servis
 edilir. Framework bu hatayı çalışma zamanında da yakalıyor (controller cookie

package/docs/06-cache.md

@@ -110,17 +110,30 @@ saklayabiliyordu.
 ## Cache anahtarı
 
 ```
-`${req.path}?${new URLSearchParams(query).toString()}`
+`${yol}?${izin verilen query parametreleri, sıralı}`
 ```
 
-Yani yol **ve tüm query parametreleri** anahtarın parçasıdır. `/liste?sayfa=2`
-ile `/liste?sayfa=3` ayrı girdilerdir.
+Query'siz bir istek için anahtar yalnızca yoldur. **Query parametresi taşıyan
+istek varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private,
+no-store` ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
+gibi sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
+sayfaları kampanya varyantları için dışarı atıyor.
 
-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 varsayılan
-olarak en fazla 500 girdi tutar ve LRU ile en eskiyi düşürür.
+Hangi parametrenin çıktıyı gerçekten değiştirdiğini uygulama bildirir —
+`jskelet.config.mjs` → `cache().query`:
+
+```js
+cache: () => ({
+  html: { "/liste": 60 },
+  query: { "/liste": ["sayfa"] },
+}),
+```
+
+Artık `/liste?sayfa=2` ile `/liste?sayfa=3` ayrı girdiler, `/liste?sayfa=2&utm_source=x`
+ise `?sayfa=2` kopyasını paylaşır: listede olmayan parametre anahtara girmez.
+Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (dikkat: girdi
+sayısını sınırlayan tek şey `maxEntries` olur), `[]` ile eşlenirse query tamamen
+yok sayılır. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ## Stale-while-revalidate
 
@@ -431,6 +444,97 @@ cache: {
 `transientRetry: false` (ya da `attempts: 0`) tekrarı kapatır ve doğrudan 503'e
 düşer.
 
+## Upstream hız freni: `cache().upstream`
+
+Buraya kadarki her şey 429 **geldikten sonra** ne olacağını anlatıyor. Bu bölüm
+429'u en baştan almamakla ilgili.
+
+Fren `trackUpstreamFetch()` sarmalayıcısının içinde, yani gerçek `fetch`
+çağrısının geçtiği yerde duruyor. Isıtma turundaki `prewarm.rps` bu işi
+yapamaz: o, kendi sunucumuza atılan **sayfa** isteklerini sayıyor, ama bir
+sayfa render'ı bir API çağrısı da yapabilir yirmi tane de. Kotayı bağlayan şey
+sayfa sayısı değil, çağrı sayısı — ve fren buraya konduğunda ısıtma da gerçek
+trafik de aynı bütçeden harcar.
+
+Varsayılan **kapalı**: `rate` verilmedikçe hiçbir istek beklemez ve maliyet bir
+daldan ibarettir.
+
+```js
+// jskelet.config.mjs
+cache: () => ({
+  upstream: {
+    rate: 10, // saniyedeki tavan (host başına)
+    burst: 20, // kısa patlama toleransı
+    concurrency: 8, // aynı anda uçan çağrı
+    hosts: {
+      // Kotası farklı olan uçlar ayrı ayarlanır.
+      "api.example.com": { rate: 3, concurrency: 2 },
+    },
+  },
+}),
+```
+
+### Üç mekanizma, üç farklı sınır
+
+| Mekanizma | Neyi sınırlar | Ayar |
+| --- | --- | --- |
+| Token bucket | Ortalama hız (çağrı/saniye) | `rate`, `burst` |
+| Eşzamanlılık | Anlık baskı (aynı anda uçan çağrı) | `concurrency` |
+| AIMD | Doğru hızın ne olduğu | `minRate`, `increaseStep`, `increaseIntervalMs`, `decreaseIntervalMs` |
+
+Üçüncüsü asıl fikir. Sabit bir hız her zaman ya çok yavaş ya çok hızlıdır:
+kotanın gerçek sınırını kimse config'e doğru yazamaz, üstelik gün içinde
+değişir. Bu yüzden `rate` bir **tavan** olarak alınır ve gerçek hız upstream'in
+cevabına göre oynar:
+
+- **429 ya da 503** → hız yarıya iner (çarpımsal azalma). Yanıt `Retry-After`
+  taşıyorsa kova o süre boyunca tamamen durur — upstream sana ne kadar
+  bekleyeceğini zaten söylüyor.
+- **Temiz geçen her pencere** → hız `increaseStep` kadar yukarı çıkar
+  (toplamsal artış), `rate` tavanına kadar.
+
+Azalmanın çarpımsal, artışın toplamsal olması bilinçli. Tersi olsaydı her
+pencerede yeniden 429 yenirdi.
+
+### Devre kesici
+
+Art arda `breakerFailures` (varsayılan 5) tane 429 alan bir host
+`breakerCooldownMs` süresince tamamen baypas edilir: çağrı hiç yapılmaz,
+doğrudan geçici hata olarak bildirilir.
+
+Sert görünüyor ama asimetri bunu gerektiriyor: 429 geçici sayıldığı için o
+çağrıyla üretilen HTML **önbelleğe yazılmaz**. Yani rate limit'e girmiş bir
+turda kota harcanır ve karşılığında hiçbir şey saklanmaz. Üstüne bir sonraki
+tur aynı sayfayı yine soğuk bulup yine dener. Kesici bu boşa yanmayı kesiyor.
+
+```
+[upstream] api.example.com: 5 consecutive rate limits — bypassing for 10000ms (rate is now 1.2/s)
+```
+
+Yalnızca 429 ve 503 sayılır. `400`/`404` bir kota sorunu değil, `500` de öyle:
+onlar için yavaşlamak arızayı düzeltmez, sadece siteyi yavaşlatır.
+
+### Durumu görmek
+
+`getUpstreamLimiterStatus()` host başına o anki hızı, uçuştaki çağrıyı ve
+sayaçları döner; dev panelinin **Server** sekmesi de aynı bilgiyi basıyor.
+429 fırtınasında "şu an saniyede kaça indi" bilgisi olmadan ayar yapmak
+körlemesine olur.
+
+```js
+import { getUpstreamLimiterStatus } from "jskelet";
+
+// [{ host: "api.example.com", rate: 2.5, maxRate: 10, concurrency: 8,
+//    active: 3, throttled: 12, rejected: 40, bypassed: false, blockedMs: 0 }]
+```
+
+### Freni açmadan önce
+
+Hız freni son çare. Aynı upstream yanıtını yüzlerce sayfa çekiyorsa asıl çözüm
+[`withDataCache`](#istekler-arası-veri-önbelleği-withdatacache) TTL'ini tur
+aralığından uzun tutmak: 400 sayfalık bir tur, ortak bir uç için tek çağrı
+yapar. Fren o çağrıları yavaşlatır, sayısını azaltmaz.
+
 ## Önbelleği yönetmek
 
 `jskelet` şu fonksiyonları dışa açar:
@@ -647,8 +751,216 @@ Bağlantı kurulmamışken de güvenle çağrılır. Dönen nesne
 kesicinin açık olduğunu, `errors` toplam komut hatasını gösterir. Aynı özet dev
 panelinin raporunda da var ([09-dev-araclari.md](./09-dev-araclari.md)).
 
+İki teşhis yüzeyi daha var:
+
+| Çağrı | Ne der |
+| --- | --- |
+| `getRedisDetails()` | Bağlantının **nereye** kurulduğu: adres, TLS, veritabanı, `namespace`, hangi türlerin paylaşıldığı, purge yayınına abone olunup olunmadığı. Şifre asla dönmez — bağlantı URL'i sır taşıyor olabilir. |
+| `inspectRedis()` | Paylaşımlı kademede gerçekten ne durduğu: tür başına anahtar sayısı, `DBSIZE` ve `used_memory`. Bir `SCAN` turu olduğu için **istek yolunda çağrılmaz**; yönetim panelinde de ayrı bir düğmeye bağlı. |
+
 Ayarların tam listesi: [07-yapilandirma.md](./07-yapilandirma.md).
 
+## Yönetim paneli
+
+Yukarıdaki `getHtmlCacheEntries()` / `getRedisStatus()` uçlarını elle yazmak
+yerine framework hazır bir panel taşıyor. Dev overlay'den ayrı bir şey: overlay
+yalnızca `NODE_ENV=development` iken var, panel ise ortama bakmaz — "bu sayfa
+neden bayat", "webhook purge'ü geçti mi", "Redis gerçekten bağlı mı" soruları
+üretimde soruluyor.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/haber/:slug": 300 },
+      panel: { enabled: process.env.CACHE_PANEL === "1" },
+    };
+  },
+};
+```
+
+`enabled` verilmedikçe **hiçbir şey mount edilmez**: yol yoktur, modül
+yüklenmez, üretim sürecinde hiçbir maliyeti olmaz. Ortam değişkeni
+(`JSKELET_CACHE_PANEL=1`) config'i ezer; panel genelde bir arıza sırasında tek
+seferlik açılıyor ve o an config dosyasını değiştirip yeniden dağıtmak
+istenmiyor.
+
+Panel açıldığında sunucu logu şifreyi basar:
+
+```
+[cache-panel] http://localhost:3000/_jskelet/cache — password for this run: 3f9c…
+```
+
+### Erişim ve güvenlik
+
+- **Şifre her süreç başlangıcında yeniden üretilir** (32 haneli, onaltılık) ve
+  yalnızca logda görünür. Kalıcı bir sır tutulmuyor: sızması önbelleği boşaltma
+  yetkisi demek ve bir deploy eski erişimi kendiliğinden iptal etmeli.
+- **Şifre query string ile kabul edilmez.** Erişim logları, tarayıcı geçmişi ve
+  `Referer` başlığı sırrı taşımasın; giriş yalnızca form üzerinden.
+- **Üç başarısız denemede IP 24 saat yasaklanır** (`banAttempts`, `banHours`).
+  Yanlış şifre kadar oturumsuz istek de sayılır; başarılı giriş sayacı sıfırlar.
+- **Yasaklı ve yetkisiz her cevap `404`.** 401/403 panelin var olduğunu
+  doğrular, 404 hiç yokmuş gibi davranır. Panelin dışındaki site etkilenmez.
+- **Hiçbir yeri indekslenmez:** her cevapta `X-Robots-Tag: noindex, nofollow,
+  noarchive, nosnippet`, `Cache-Control: no-store` ve `Referrer-Policy:
+  no-referrer`. Yol ayrıca ısıtma listesinden ve gezinme ipuçlarından muaftır.
+- Aksiyonlar `X-JSkelet-Cache-Panel` başlığı ister — çapraz siteden
+  gönderilemeyen bir başlık, yani panelin kendi CSRF freni.
+- Oturumlar ve yasak sayaçları süreç belleğinde durur; şifresi zaten her
+  restart'ta değişen bir panel için diske yazmak yanlış takas olurdu.
+
+### Panelde ne var
+
+| Bölüm | Gösterdiği |
+| --- | --- |
+| Üst satır | Sürüm, ortam, pid, uptime, RSS |
+| Kartlar | HTML girdi sayısı ve sınırı, bellekteki HTML boyutu, bayat girdi sayısı, veri girdisi sayısı, Redis durumu (`connected` / `bypassed` / `off`), ısıtma turunun ilerlemesi |
+| Paylaşımlı kademe | Bağlantının **nereye** kurulduğu (adres, TLS, veritabanı), anahtar öneki ve `namespace`, `buildId`, hangi türlerin paylaşıldığı, sıkıştırılmış gövde ve purge yayını durumu, komut zaman aşımı ve hata sayısı. Kapalıysa yerine Redis önerisi ve kurulum parçacığı çıkar. |
+| Cloudflare | Zone, plan, cache ile ilgili zone ayarları, development mode'un kalan süresi, Tiered Cache / Cache Reserve durumu ve cache isabet oranı. Bağlı değilse kurulum parçacığı çıkar. |
+| Host | Makinenin RAM kullanımı ve projenin bulunduğu diskin doluluğu |
+| Girdi listesi | HTML: yol (yeni sekmede açılır), taze/bayat, boyut, durum kodu, kalan TTL, bağımlılık sayısı, hazır sıkıştırılmış gövdeler. Veri: anahtar (tıklayınca panoya kopyalanır), taze/bayat, kalan TTL |
+
+Liste **anahtar bazında filtrelenir** ve filtre sunucuda uygulanır: veri
+önbelleğinde on binlerce anahtar olabiliyor. Her istekte en fazla 500 satır
+döner; başlıktaki sayaç kaç eşleşmenin kesildiğini söyler. HTML gövdesi ve veri
+değerleri **hiç dönmez** — panelin işi durumu göstermek, içeriği dışa vermek
+değil.
+
+### Panelden yapılabilenler
+
+| İşlem | Karşılığı |
+| --- | --- |
+| Invalidate (hedef + `hard`) | `invalidateHtmlCache(target, { hard })` |
+| Tek satırı `drop` | `dropHtmlCacheKey(key)` / `dropDataCacheKey(key)` |
+| Clear HTML cache | `clearHtmlCache()` |
+| Clear data cache (önek opsiyonel) | `clearDataCache(prefix)` |
+| Drop shared keys | Redis'teki `html` ya da `data` isim alanını tarar ve düşürür |
+| Count keys in Redis | `inspectRedis()` — tür başına anahtar sayısı, `DBSIZE` ve `used_memory` |
+| Prewarm | `prewarm()` — tur arkada koşar, ilerleme kartta görünür |
+| Cloudflare purge (her şey / bellekteki URL'ler / prefix / host / tag) | `purgeCloudflare()` |
+| Cloudflare ayarı ya da özelliği değiştirmek | Zone ayarları ve Tiered Cache / Cache Reserve |
+
+Hepsi paylaşımlı kademeye de yayılır: tek kopyanın önbelleğini boşaltmak,
+kümede çalışan bir kurulumda "temizledim ama hâlâ eski" sorusunu üretir.
+
+Listedeki tek satırı silmek `invalidateHtmlCache()`ten farklıdır: o yol
+desenine bakar ve bir yolun **bütün** query varyantlarını düşürür,
+`dropHtmlCacheKey()` ise tam anahtarı alır — `/liste?sayfa=2` düşerken
+`/liste?sayfa=3` sıcak kalır.
+
+## CDN kademesi: Cloudflare
+
+Buraya kadar anlatılan her şey **origin** önbelleği. Önünde Cloudflare varsa
+ziyaretçinin gördüğü HTML çoğu zaman hiç size ulaşmıyor: edge'deki kopya
+TTL'ini doldurana kadar servis edilir. Bu yüzden `invalidateHtmlCache()`
+tek başına "sayfayı güncelledim ama eski hâli görünüyor" sorununu çözmez —
+origin tazelenir, edge beklemeye devam eder.
+
+JSkelet iki kademeyi aynı yerden yönetilebilir kılar.
+
+### Kurulum
+
+Token bir sır; config dosyasına değil ortama yazılır:
+
+```bash
+JSKELET_CLOUDFLARE_KEY=... # API token
+JSKELET_CLOUDFLARE_ZONE_ID=... # zone kimliği
+JSKELET_CLOUDFLARE_HOSTNAME=example.com # opsiyonel
+```
+
+Token'a gereken izinler, yapmak istediğinize göre: purge için `Zone.Cache
+Purge`, ayarları değiştirmek için `Zone.Zone Settings`, isabet oranı ve edge
+kırılımı için `Zone.Analytics` (salt okunur). Yalnızca purge izni verilen bir
+token'la panel açılır, ayar bölümleri hata yazar.
+
+Zone kimliği ve site adı sır olmadığı için `jskelet.config.mjs` içinden de
+verilebilir; env her zaman önceliklidir:
+
+```js
+cache: {
+  cloudflare: {
+    zoneId: "…",
+    hostname: "example.com", // purge tam URL ister; yol → URL çevrimi için
+    analyticsHours: 24,
+  },
+}
+```
+
+`hostname` verilmezse purge URL'leri panelin açıldığı origin'den türetilir.
+Paneli iç bir adresten (`http://10.0.0.4:3000`) açıyorsanız bu adresin
+Cloudflare'de karşılığı yok; o kurulumda `hostname` zorunlu.
+
+### Ne yapılabilir
+
+Cloudflare'in cache yüzeyinde ne varsa panelde de var:
+
+| İşlem | Not |
+| --- | --- |
+| Purge everything | Zone'un tamamı. En kaba araç; ısınma maliyeti yüksek |
+| Purge by URL | Panelin o an bellekte tuttuğu sayfalar tek düğmeyle; ya da satır başına `cf purge` |
+| Purge by prefix / host / tag | Artık her planda çalışıyor; istek başına 100 anahtar |
+| Development mode | Üç saat boyunca edge önbelleğini baypas eder, sonra kendiliğinden kapanır |
+| Cache level, browser cache TTL, query string sıralaması, Always Online | Zone ayarları |
+| Tiered Cache, Regional Tiered Cache, Cache Reserve | Plana bağlı; kapalı planda "unavailable" görünür |
+| Clear Cache Reserve | Purge'den ayrı: `purge_everything` edge'i düşürür, R2'deki kalıcı kopya kalır |
+
+Uzun URL listeleri istek başına 100 anahtarlık partilere bölünür ve **sırayla**
+gönderilir. Paralel göndermek Free planda dakikada beş isteklik hız freni
+yüzünden yarısı reddedilen bir tur demek.
+
+Kod tarafında aynı yüzey:
+
+```js
+import { invalidateHtmlCache, purgeCloudflare, toCloudflareUrls } from "jskelet";
+
+export async function onPostPublished(slug) {
+  const paths = ["/", `/blog/${slug}`];
+
+  invalidateHtmlCache(paths); // origin
+  await purgeCloudflare({ files: toCloudflareUrls(paths) }); // edge
+}
+```
+
+Bu modüldeki hiçbir fonksiyon fırlatmaz: token yoksa, Cloudflare 403 dönerse
+ya da ağ düşerse sonuç `{ ok: false, error }` olur. Bir CDN arızası içerik
+yayınlama akışını kesmemeli.
+
+### "Bu sayfa kaç edge'de cache'li?" — sorulabilen ve sorulamayan
+
+Cloudflare API'sinde bir objenin **envanterini** veren uç yok. Yüzlerce şehirde
+birbirinden bağımsız önbellekler var ve hiçbiri "şu an bende bu URL'in kopyası
+var mı" sorusuna cevap vermiyor. Panel bu yüzden envanter değil **gözlem**
+gösterir: bir yol girip sorguladığınızda GraphQL analitiğinden son N saatte
+hangi kolonun (IST, FRA, AMS…) o yolu kaç kez cache'ten, kaç kez origin'den
+servis ettiği gelir.
+
+```js
+const report = await fetchPathEdges({ path: "/blog", hours: 24 });
+// → { colos: [{ colo: "IST", hits: 7, misses: 2 }, …], hits, misses }
+```
+
+Okurken iki sınırı akılda tutun: hiç istek almamış bir edge listede görünmez,
+kopyası olsa da; ve veri kümesi örneklemeli, yani oranlar güvenilir ama mutlak
+sayılar yaklaşıktır.
+
+Seçtiğiniz bir edge'i **ısıtmanın** da yolu yok. Bir obje ancak o koloya
+yönlenen gerçek bir istekle o edge'in önbelleğine giriyor; sunucudan
+"Frankfurt'a bunu cache'let" diyemezsiniz. Pratikte yapılabilen üç şey var:
+
+- **Origin'i ısıtmak** (`prewarm`): ilk isteği alan edge cevabı hazır bulur,
+  o istek yavaşlamaz.
+- **Tiered Cache**: edge'ler origin'e doğrudan gitmez, aradaki üst katmandan
+  besleniyor; bir şehirdeki ilk istek diğer şehirler için de ısıtma sayılır.
+- **Cache Reserve**: uzun kuyruklu içerik için R2'de kalıcı kopya; edge
+  düşünce istek origin'e kadar inmiyor.
+
+`hit` oranınız düşükse önce cevabın cache'lenebilir olup olmadığına bakın:
+`Cache-Control: private`, `Set-Cookie` ve query string ayarları edge'in
+cache'lememe kararının en sık sebepleri, ve bu panelde `dynamic` olarak
+görünür.
+
 ## Prewarm — açılışta ısıtma
 
 Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz: önbellek
@@ -700,12 +1012,28 @@ Kurallar:
    Dev'de varsayılan olarak saniyede 4 istek uygulanır: render tek bir olay
    döngüsünde çalıştığı için aralıksız bir tur, sayfa isteklerini ve dev
    panelinin canlı kanalını arkasında bekletiyor.
-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:
+4. **Geçici** hata alan yollar için **tek seri tekrar turu** yapılır
+   (`concurrency: 1`). `400`/`403`/`404` gibi kalıcı cevaplar tekrar turuna
+   girmez: deterministik bir hata tekrar denemekle düzelmez ve o çağrılar
+   kotadan karşılıksız yer. Özette `N not retried (permanent)` olarak görünür.
+5. Bekleme süresi `retryDelayMs`, ama hız freni açıkken **freni bekleten süre**
+   varsa o kazanır: 10 saniye kapalı kalacak bir devre kesiciden 2 saniye sonra
+   tekrar denemek, aynı 429'u peşin peşin almak olurdu.
+6. Özet loglanır:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
+Ardından turun upstream'e ne kadar dokunduğu basılır:
+
+```text
+[prewarm] 12 upstream calls for 430 data reads (97% from the data cache, 38 coalesced)
+```
+
+Bu satır ayarın hangi yönde değişmesi gerektiğini söyleyen tek satır. Oran
+düşükse çözüm hız freni değil, `withDataCache` TTL'ini tur aralığından uzun
+tutmak: fren çağrıları yavaşlatır, sayısını azaltmaz. Aynı sayaçlara
+`getDataCacheStats()` ile ya da dev raporundaki **Data cache** kartından da
+bakılabilir.
+
 Tur sırasında oluşan istek hataları ve sayfa başına basılan render uyarıları
 (`was produced with missing data`, `returned notFound() while upstream is
 failing`, `could not be produced`) tek tek loglanmaz; sayılır ve tur bitince

package/docs/07-yapilandirma.md

@@ -115,6 +115,7 @@ export default {
   async cache() {
     return {
       html: { "/": 60, "/haber/:slug": 300 },
+      query: { "/arama": ["q", "page"] },
       maxEntries: 500,
       data: { maxEntries: 10000, staleFactor: 10 },
       prewarm: {
@@ -560,9 +561,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, query: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -582,6 +583,39 @@ 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().query`
+
+Desen → cache anahtarına girmesine izin verilen query parametreleri.
+
+**Varsayılan olarak query parametresi taşıyan istek dinamiktir**: `cache().html`
+o yolu kapsıyor olsa bile HTML önbelleğine hiç girmez, `private, no-store` ile
+gider. Sebebi basit — bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
+gibi sonsuz sayıda anahtar üretiyor ve `maxEntries` sınırına dayandığında
+LRU'daki gerçek sayfaları dışarı atıyor. Hangi parametrenin çıktıyı gerçekten
+değiştirdiğini yalnızca uygulama bilir.
+
+```js
+query: {
+  "/arama": ["q", "page"], // yalnızca bu ikisi anahtara girer
+  "/urunler": ["kategori"],
+  "/rapor/:id": true, // bütün parametreler anahtara girer
+  "/kampanya": [], // query tamamen yok sayılır
+}
+```
+
+- **İzin listesi** (`string[]`): listedeki parametreler anahtara girer, her
+ farklı değer kendi girdisini alır. Listede olmayan parametreler **yok
+ sayılır** — sayfa yine cache'lenir ve bütün kampanya varyantları tek kopyayı
+ paylaşır.
+- **`true`**: bütün parametreler anahtara girer. Anahtar sayısını sınırlayan
+ tek şey `maxEntries` olur; yalnızca değer kümesi kapalı olan yollarda kullan.
+- **`[]`**: query hiç dikkate alınmaz, bütün varyantlar query'siz sürümün
+ HTML'ini alır.
+
+Parametreler anahtara **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı girdiyi
+paylaşır. `route(fn, { private: true })` bu bölümden etkilenmez; private route
+hiçbir koşulda cache'lenmez.
+
 ### `cache().maxEntries`
 
 **Tip:** `number` — **Varsayılan:** `500`
@@ -627,6 +661,39 @@ denenir. Amaç var olan bir sayfanın 404'e dönüşmemesi; denemeler tükenirse
 önbelleğe girmeyen bir 503 olur. `false` ya da `attempts: 0` tekrarı kapatır.
 Ayrıntı: [06-cache.md](./06-cache.md).
 
+### `cache().upstream`
+
+Upstream API'ye giden `fetch` çağrılarının host başına hız freni. Varsayılan
+**kapalı**: `rate` verilmedikçe hiçbir istek beklemez. `rate` bir tavandır;
+gerçek hız 429 cevaplarına göre kendini aşağı çeker ve temiz geçen pencerelerde
+kademe kademe geri çıkar.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `rate` | `number` | `0` | Saniyedeki en fazla çağrı. `0` → fren kapalı |
+| `burst` | `number` | `0` | Kova boyu; `0` → bir saniyelik bütçe kadar patlama |
+| `concurrency` | `number` | `8` | Aynı anda uçabilecek çağrı |
+| `minRate` | `number` | `0.5` | Azalmanın dibi; hız buranın altına inmez |
+| `increaseStep` | `number` | `1` | Toplamsal artışın adımı (çağrı/saniye) |
+| `increaseIntervalMs` | `number` | `5000` | Artış periyodu |
+| `decreaseIntervalMs` | `number` | `1000` | İki azalma arasındaki en kısa süre |
+| `breakerFailures` | `number` | `5` | Art arda kaç 429'dan sonra host baypas edilir |
+| `breakerCooldownMs` | `number` | `10000` | Baypasın süresi |
+| `hosts` | `Record<string, object>` | `{}` | Host bazlı override; aynı alanlar geçerli |
+
+Yalnızca `429` ve `503` hızı cezalandırır: `400`/`404`/`500` bir kota sorunu
+değil. Durumu `getUpstreamLimiterStatus()` ile ya da dev panelinin **Server**
+sekmesinden okuyabilirsin. Ayrıntı ve freni açmadan önce bakılacak yer:
+[06-cache.md](./06-cache.md).
+
+```js
+upstream: {
+  rate: 10,
+  concurrency: 4,
+  hosts: { "api.example.com": { rate: 3 } },
+}
+```
+
 ### `cache().redis`
 
 Opsiyonel Redis ikinci kademesi (L2). Bellek içi önbellek birincil kalır; Redis
@@ -661,6 +728,64 @@ redis: {
 }
 ```
 
+### `cache().panel`
+
+Önbellek yönetim paneli. Bellek içi kademenin ve Redis kademesinin durumunu
+gösterir; hedefli invalidation, tek girdi silme ve ısıtma tetikler.
+
+Ortama bakmaz: `enabled` verilmedikçe **hiç mount edilmez** ve yol da yoktur.
+Açıkken production'da da çalışır — asıl sorular ("bu sayfa neden bayat",
+"webhook purge'ü geçti mi") orada soruluyor.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Yalnızca açıkça `true` verildiğinde açılır (`JSKELET_CACHE_PANEL` ezer) |
+| `basePath` | `string` | `"/_jskelet/cache"` | Panelin kökü |
+| `banAttempts` | `number` | `3` | Kaç başarısız denemeden sonra IP yasaklanır |
+| `banHours` | `number` | `24` | Yasağın süresi |
+| `sessionHours` | `number` | `12` | Oturum çerezinin ömrü |
+
+Şifre **her süreç başlangıcında** üretilir ve yalnızca sunucu logunda görünür:
+
+```
+[cache-panel] http://localhost:3000/_jskelet/cache — password for this run: 3f9c…
+```
+
+Kalıcı bir sır (config alanı ya da env) tutulmaz; sızması önbelleği boşaltma
+yetkisi demek ve her deploy eski erişimi kendiliğinden iptal etmeli. Yasaklı ve
+yetkisiz her cevap `404`'tür. Kullanım ve ekran ayrıntıları:
+[06-cache.md](./06-cache.md).
+
+### `cache().cloudflare`
+
+CDN kademesi. JSkelet'in önbelleği origin önbelleği; ziyaretçinin gördüğü kopya
+edge'de duruyor. Bu bölüm bağlıysa panelden edge purge'ü, cache ile ilgili zone
+ayarları ve cache isabet oranı yönetilebilir.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | `false` verilirse env'de token olsa bile yüzey kapalı kalır |
+| `zoneId` | `string \| null` | `null` | Zone kimliği (`JSKELET_CLOUDFLARE_ZONE_ID` ezer) |
+| `apiToken` | `string \| null` | `null` | Token; **env tercih edilir**, config'e yazmak sırrı repoya sokar |
+| `hostname` | `string \| null` | `null` | Purge tam URL ister; yol → URL çevrimi bu ad üzerinden yapılır. Verilmezse panelin açıldığı origin kullanılır |
+| `analyticsHours` | `number` | `24` | Analitik penceresi, en çok `72` |
+
+Token yalnızca `JSKELET_CLOUDFLARE_KEY` ile verildiğinde config dosyası temiz
+kalır; izinler yapılacak işe göre: purge için `Zone.Cache Purge`, ayarlar için
+`Zone.Zone Settings`, isabet oranı için `Zone.Analytics` (salt okunur). Token
+hiçbir panel cevabında dönmez, yalnızca "env'den geldi" bilgisi görünür.
+
+Zone bağlı değilse panel bir uyarı değil kurulum önerisi gösterir; Cloudflare
+hata dönerse ilgili bölüm hatayı yazar ve panelin kalanı çalışmaya devam eder.
+Neyin sorulabildiği — özellikle "bu sayfa kaç edge'de cache'li" sorusunun neden
+tam cevabı olmadığı — [06-cache.md](./06-cache.md) içinde.
+
+```js
+panel: {
+  enabled: process.env.CACHE_PANEL === "1",
+}
+```
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |
@@ -784,6 +909,10 @@ basılmaz.
 | `HOST` | `startServer` | `::` | Bağlanılacak arayüz. Varsayılan çift yığın dinler (IPv6 + IPv4); IPv6 yoksa `0.0.0.0`'a düşer |
 | `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) |
+| `JSKELET_CACHE_PANEL` | `createApp` | — | Ayarlıysa önbellek panelini açar; `0` config'te açık olan paneli kapatır. Env config'i ezer, çünkü panel genelde bir arıza sırasında tek seferlik açılır. [06](./06-cache.md) |
+| `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache yüzeyi | — | API token. Verilene kadar CDN purge'ü ve edge analitiği kapalıdır; config'teki `apiToken`'ı ezer. Token hiçbir cevapta dönmez. [06](./06-cache.md) |
+| `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache yüzeyi | — | Zone kimliği. Token'la birlikte verilmedikçe hiçbir Cloudflare ucu çağrılmaz |
+| `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache yüzeyi | — | Purge URL'lerinin kökü. Panel iç bir adresten açılıyorsa gerekir |
 | `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 1 | Paralel işçi sayısı |

package/docs/en/03-routing.md

@@ -126,6 +126,10 @@ app.get(
 | `revalidate` | `number` (seconds) | The HTML cache TTL. If it is not given, or is 0, this route is not cached. A matching rule in `jskelet.config.mjs` → `cache().html` **overrides** this value. |
 | `private` | `boolean` | The page depends on the visitor. The cache is disabled, a `cache().html` pattern **cannot** override that, and the response is sent with `private, no-store` and `Vary: Cookie`, without an ETag. |
 
+Even with `revalidate` given, **a request that carries a query parameter is
+dynamic by default**; that path needs an allowlist under `cache().query`
+([06-caching.md](./06-caching.md)).
+
 Every session-dependent page needs `private: true`; because identity is not part
 of the cache key, without the flag one user's HTML is served to another. The
 framework also catches this at runtime (a render that reads cookies is never