jskelet 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -10,6 +10,54 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- A cache admin panel at `/_jskelet/cache`, turned on with
+  `cache().panel: { enabled: true }` or `JSKELET_CACHE_PANEL=1`. It lists what
+  the in-process tier holds (key, size, status, remaining TTL, dependency count,
+  precompressed bodies for HTML; key and TTL for data), reports whether the
+  Redis tier is connected or bypassed, and runs the operations you would
+  otherwise hand-write an admin route for: targeted invalidation with an
+  optional hard mode, dropping a single entry, clearing either cache, unlinking
+  the shared keys and triggering a prewarm pass. Unlike the dev overlay it does
+  not look at `NODE_ENV`, because "why is this page stale" is a production
+  question — but nothing is mounted until it is explicitly enabled, so the path
+  does not exist by default. Access is a 32-character password regenerated on
+  every process start and printed once to the server log; there is no persistent
+  secret to leak and a deploy revokes old access on its own. The password is
+  never accepted in a query string, three failed attempts ban the IP for 24
+  hours, and every banned or unauthorised response is a `404` rather than a 401
+  that would confirm the panel exists. The panel is excluded from indexing,
+  prewarming and navigation speculation.
+- `dropHtmlCacheKey()` and `dropDataCacheKey()` drop one exact cache key.
+  `invalidateHtmlCache()` matches a path pattern and takes down every query
+  variant of a path, which is the right default for a webhook but wrong when you
+  want `/list?page=2` gone and `/list?page=3` left hot.
+
+- An adaptive per-host rate limit for upstream calls, `cache().upstream`. It sits
+  in the `fetch` wrapper rather than in the prewarm pass, because what spends the
+  quota is the API call, not the page: one render may make one call or twenty, so
+  `prewarm.rps` could never bound the real thing. A token bucket caps the average
+  rate, a concurrency limit caps the calls in flight, and `rate` is treated as a
+  ceiling that the limiter pulls down on its own — a 429 or 503 halves the rate,
+  `Retry-After` stops the bucket for exactly as long as the upstream asked, and
+  clean windows climb back one step at a time. A host that returns
+  `breakerFailures` rate limits in a row is bypassed for `breakerCooldownMs`,
+  which stops the worst waste: because a 429 counts as transient, the HTML
+  produced by a throttled call is never stored, so a pass in that state spends
+  quota and keeps nothing. Only 429 and 503 penalise the rate; a 400 or 500 is
+  not a quota problem. Off by default — set `rate` to turn it on.
+- `getUpstreamLimiterStatus()` reports the current rate, calls in flight, 429
+  count and breaker state per host. The dev panel's Server tab shows the same.
+- `getDataCacheStats()` counts how the data cache was used: fresh hits, stale
+  hits, misses, coalesced concurrent reads, values promoted from the shared tier
+  and — the only number that reaches the quota — real producer runs. A prewarm
+  pass now prints its own share of that (`12 upstream calls for 430 data reads
+  (97% from the data cache)`), which is what tells you whether the fix is a
+  longer TTL or a rate limit. The dev report has a Data cache card for it.
+
+- The dev overlay header now shows the installed JSkelet version next to the
+  title, labelled `latest` when it matches npm and `outdated` with the newer
+  version when it does not, so you can tell at a glance which version the
+  project runs without opening the Server tab.
 - An optional Redis tier behind both caches, turned on with
   `cache().redis: { enabled: true, url }` and `npm install ioredis`. The
   in-process cache stays primary and every request still reads it; Redis only
@@ -87,12 +135,20 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
-- Request errors raised during a prewarm pass are no longer logged one by one.
-  They are counted while the pass runs and printed as a single summary line
-  afterwards, grouped by status and message with the most frequent kinds first,
-  so a flaky upstream can no longer bury the "warmed N/M pages" line under
-  hundreds of stack traces. Errors from real traffic are logged as before, and
-  the dev tools panel still shows the per-path detail.
+- The prewarm retry pass no longer retries permanent failures. A `400`, `403` or
+  `404` does not get better on the second try, so those paths are dropped from
+  the retry round and counted as `N not retried (permanent)` in the summary. The
+  wait before the round now also honours the upstream rate limit: if a
+  `Retry-After` or an open circuit breaker is holding calls back, the pass waits
+  that out instead of retrying into the same 429.
+- Errors and warnings raised during a prewarm pass are no longer logged one per
+  page. Request errors and the per-page render warnings (`was produced with
+  missing data`, `returned notFound() while upstream is failing`, `could not be
+  produced`) are counted while the pass runs and printed as a single summary
+  block afterwards, grouped by message with the most frequent kinds first, so a
+  failing upstream can no longer bury the "warmed N/M pages" line under hundreds
+  of near-identical lines. Real traffic logs as before, and the dev tools panel
+  still shows the per-path detail.
 - The marketing example's changelog page is now a timeline: releases are laid out
   along a rail with a sticky version column, each change group gets its own card
   with a coloured rule and item count, and a row of version chips at the top

package/docs/06-cache.md

@@ -431,6 +431,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:
@@ -649,6 +740,90 @@ panelinin raporunda da var ([09-dev-araclari.md](./09-dev-araclari.md)).
 
 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 | 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 |
+| Girdi listesi | HTML: anahtar, taze/bayat, boyut, durum kodu, kalan TTL, bağımlılık sayısı, hazır sıkıştırılmış gövdeler. Veri: anahtar, 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 |
+| Prewarm | `prewarm()` — tur arkada koşar, ilerleme kartta görünür |
+
+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.
+
 ## Prewarm — açılışta ısıtma
 
 Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz: önbellek
@@ -700,19 +875,37 @@ 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)`
 
-Tur sırasında oluşan istek hataları tek tek loglanmaz; sayılır ve tur bitince
-özetin ardından tek bir satırda, en sık görülen türler başta olacak şekilde
-basılır:
+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
+özetin ardından, en sık görülen türler başta olacak şekilde basılır:
 
 ```text
-[prewarm] 37 request errors were not logged individually:
-  31× 502 upstream fetch failed: /api/quotes
+[prewarm] 137 problems were not logged individually:
+  94× missing data, upstream is failing permanently (403 /api/v1/polls)
+  37× missing data, upstream is failing permanently (400 /api/v1/posts)
   6× 500 Cannot read properties of undefined (reading 'title')
 ```
 

package/docs/07-yapilandirma.md

@@ -560,9 +560,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>, 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: {}, 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`
 
@@ -627,6 +627,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 +694,40 @@ 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).
+
+```js
+panel: {
+  enabled: process.env.CACHE_PANEL === "1",
+}
+```
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |
@@ -784,6 +851,7 @@ 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) |
 | `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/06-caching.md

@@ -441,6 +441,98 @@ cache: {
 `transientRetry: false` (or `attempts: 0`) disables the retry and falls straight
 through to the 503.
 
+## Upstream rate limit: `cache().upstream`
+
+Everything above describes what happens **after** a 429 arrives. This section is
+about not getting one in the first place.
+
+The brake sits inside the `trackUpstreamFetch()` wrapper, that is, where the
+real `fetch` call goes out. The prewarm pass's `prewarm.rps` cannot do this job:
+it counts **page** requests to our own server, but one page render may make one
+API call or twenty. What binds the quota is the number of calls, not the number
+of pages — and with the brake here, prewarming and real traffic spend the same
+budget.
+
+Off by default: unless `rate` is given, no request ever waits and the cost is a
+single branch.
+
+```js
+// jskelet.config.mjs
+cache: () => ({
+  upstream: {
+    rate: 10, // ceiling in calls per second, per host
+    burst: 20, // tolerance for short bursts
+    concurrency: 8, // calls in flight at once
+    hosts: {
+      // Endpoints with a different quota get their own settings.
+      "api.example.com": { rate: 3, concurrency: 2 },
+    },
+  },
+}),
+```
+
+### Three mechanisms, three different limits
+
+| Mechanism | What it bounds | Settings |
+| --- | --- | --- |
+| Token bucket | Average rate (calls per second) | `rate`, `burst` |
+| Concurrency | Instantaneous pressure (calls in flight) | `concurrency` |
+| AIMD | What the right rate actually is | `minRate`, `increaseStep`, `increaseIntervalMs`, `decreaseIntervalMs` |
+
+The third one is the real idea. A fixed rate is always either too slow or too
+fast: nobody can write the true quota limit into a config file, and it changes
+during the day anyway. So `rate` is treated as a **ceiling** and the actual rate
+moves with what the upstream says:
+
+- **429 or 503** → the rate is halved (multiplicative decrease). If the response
+  carries `Retry-After`, the bucket stops entirely for that long — the upstream
+  is already telling you how long to wait.
+- **Every clean window** → the rate climbs by `increaseStep` (additive
+  increase), up to the `rate` ceiling.
+
+Decreasing multiplicatively and increasing additively is deliberate. The other
+way round would earn a fresh 429 every window.
+
+### Circuit breaker
+
+A host that returns `breakerFailures` (default 5) rate limits in a row is
+bypassed entirely for `breakerCooldownMs`: the call is not made at all and is
+reported straight away as a transient failure.
+
+It looks harsh, but the asymmetry demands it: because a 429 counts as transient,
+the HTML produced by that call is **not stored**. So a pass that hit the rate
+limit spends quota and stores nothing in return — and the next pass finds the
+same page cold and tries again. The breaker stops that burn.
+
+```
+[upstream] api.example.com: 5 consecutive rate limits — bypassing for 10000ms (rate is now 1.2/s)
+```
+
+Only 429 and 503 count. A `400`/`404` is not a quota problem and neither is a
+`500`: slowing down does not fix them, it only makes the site slower.
+
+### Seeing the state
+
+`getUpstreamLimiterStatus()` returns the current rate, calls in flight and
+counters per host; the dev panel's **Server** tab prints the same thing. During
+a 429 storm, tuning without knowing "what rate is it down to right now" is
+guesswork.
+
+```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 }]
+```
+
+### Before turning it on
+
+The rate limit is a last resort. If hundreds of pages fetch the same upstream
+response, the real fix is keeping the
+[`withDataCache`](#cross-request-data-cache-withdatacache) TTL longer than the
+pass interval: a 400-page pass then makes one call for a shared endpoint. The
+brake slows those calls down, it does not reduce their number.
+
 ## Managing the cache
 
 `jskelet` exports these functions:
@@ -666,6 +758,95 @@ The same summary is in the dev panel report
 
 The full list of settings: [07-configuration.md](./07-configuration.md).
 
+## The admin panel
+
+Instead of hand-writing the `getHtmlCacheEntries()` / `getRedisStatus()`
+endpoints above, the framework ships a panel. It is deliberately separate from
+the dev overlay: the overlay only exists while `NODE_ENV=development`, while the
+panel does not look at the environment — "why is this page stale", "did the
+webhook purge land", "is Redis actually connected" are production questions.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/news/:slug": 300 },
+      panel: { enabled: process.env.CACHE_PANEL === "1" },
+    };
+  },
+};
+```
+
+Without `enabled` **nothing is mounted**: the path does not exist, the module is
+never loaded and it costs the production process nothing. The environment
+variable (`JSKELET_CACHE_PANEL=1`) overrides the config, because the panel is
+usually opened once during an incident and editing the config file and
+redeploying is the last thing you want at that moment.
+
+When the panel is on, the server log prints the password:
+
+```
+[cache-panel] http://localhost:3000/_jskelet/cache — password for this run: 3f9c…
+```
+
+### Access and hardening
+
+- **The password is regenerated on every process start** (32 hex characters) and
+  only ever appears in the log. There is no persistent secret to leak: leaking
+  one means handing out the right to flush the cache, and a deploy should revoke
+  old access on its own.
+- **The password is not accepted in the query string,** so access logs, browser
+  history and the `Referer` header never carry it. Sign-in goes through the form.
+- **Three failed attempts ban the IP for 24 hours** (`banAttempts`, `banHours`).
+  Requests without a session count just like a wrong password; a successful
+  sign-in resets the counter.
+- **Banned and unauthorised requests get a `404`.** A 401 or 403 confirms the
+  panel exists; a 404 behaves as if it never did. The rest of the site is
+  untouched.
+- **Nothing is indexable:** every response carries `X-Robots-Tag: noindex,
+  nofollow, noarchive, nosnippet`, `Cache-Control: no-store` and
+  `Referrer-Policy: no-referrer`. The path is also exempt from prewarming and
+  from navigation speculation.
+- Actions require an `X-JSkelet-Cache-Panel` header — a header a cross-site form
+  cannot send, which is the panel's own CSRF brake.
+- Sessions and ban counters live in process memory; persisting them to disk
+  would be the wrong trade for a panel whose password changes on every restart.
+
+### What the panel shows
+
+| Area | Contents |
+| --- | --- |
+| Top bar | Environment, pid, uptime, RSS |
+| Cards | HTML entry count and limit, HTML bytes in memory, stale entry count, data entry count, Redis state (`connected` / `bypassed` / `off`), prewarm progress |
+| Entry list | HTML: key, fresh/stale, size, status code, remaining TTL, dependency count, precompressed bodies. Data: key, fresh/stale, remaining TTL |
+
+The list is **filtered by key** and the filter runs on the server: a data cache
+can hold tens of thousands of keys. At most 500 rows come back per request and
+the counter in the heading says how many matches were cut. HTML bodies and
+cached values are **never returned** — the panel's job is to show state, not to
+export content.
+
+### What you can do from it
+
+| Action | Equivalent call |
+| --- | --- |
+| Invalidate (target + `hard`) | `invalidateHtmlCache(target, { hard })` |
+| `drop` a single row | `dropHtmlCacheKey(key)` / `dropDataCacheKey(key)` |
+| Clear HTML cache | `clearHtmlCache()` |
+| Clear data cache (optional prefix) | `clearDataCache(prefix)` |
+| Drop shared keys | Scans and unlinks the `html` or `data` namespace in Redis |
+| Prewarm | `prewarm()` — the pass runs in the background, progress shows in the card |
+
+Each one propagates to the shared tier as well: clearing a single replica's
+cache is what produces the "I cleared it and it is still old" question in a
+clustered setup.
+
+Dropping a single row is not the same as `invalidateHtmlCache()`: that one
+matches a path pattern and takes down **every** query variant of a path, while
+`dropHtmlCacheKey()` takes the exact key — `/list?page=2` goes and
+`/list?page=3` stays hot.
+
 ## Prewarm — warming up at startup
 
 The equivalent of Next's build-time prerender, except the output is not written
@@ -720,20 +901,38 @@ Rules:
    parallelism. In dev, 4 requests per second apply by default: rendering runs
    on a single event loop, so an unpaced round leaves page requests and the dev
    panel's live channel waiting behind it.
-4. **A single serial retry round** is performed for the failed paths after
-   waiting `retryDelayMs` (`concurrency: 1`). The wait is deliberate: rate limit
-   windows are on the order of seconds, so retrying immediately just earns the
-   same 429.
-5. A summary is logged:
+4. **A single serial retry round** is performed for the paths that hit a
+   **transient** failure (`concurrency: 1`). Permanent answers like `400`, `403`
+   or `404` are not retried: a deterministic error does not get better on the
+   second try and those calls spend quota for nothing. The summary shows them as
+   `N not retried (permanent)`.
+5. The wait before the retry is `retryDelayMs`, but when the rate limit is on and
+   something is holding it back, that wins: retrying 2 seconds into a 10 second
+   circuit breaker would just earn the same 429 up front.
+6. A summary is logged:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
-Request errors raised during the pass are not logged one by one. They are
-counted while the pass runs and printed after the summary as a single line,
-grouped by status and message with the most frequent kinds first:
+Then comes how much the pass actually touched the upstream:
+
+```text
+[prewarm] 12 upstream calls for 430 data reads (97% from the data cache, 38 coalesced)
+```
+
+This is the one line that tells you which way to turn the knob. If the ratio is
+low the fix is not the rate limit but a longer `withDataCache` TTL — the brake
+slows calls down, it does not reduce their number. The same counters are
+available through `getDataCacheStats()` and on the dev report's **Data cache**
+card.
+
+Request errors and the per-page render warnings (`was produced with missing
+data`, `returned notFound() while upstream is failing`, `could not be
+produced`) raised during the pass are not logged one by one. They are counted
+while the pass runs and printed after the summary, most frequent kinds first:
 
 ```text
-[prewarm] 37 request errors were not logged individually:
-  31× 502 upstream fetch failed: /api/quotes
+[prewarm] 137 problems were not logged individually:
+  94× missing data, upstream is failing permanently (403 /api/v1/polls)
+  37× missing data, upstream is failing permanently (400 /api/v1/posts)
   6× 500 Cannot read properties of undefined (reading 'title')
 ```