jskelet 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -10,6 +10,68 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- An upstream data cache: `withDataCache(key, ttlSeconds, producer)` and the
+  `dataCache(fn, { key, revalidate })` wrapper, with `clearDataCache(prefix?)`,
+  `getDataCacheSize()` and `getDataCacheEntries()` alongside them. It keeps JSON
+  rather than HTML, so its default limit is 10,000 entries: a long-tail page that
+  was never prewarmed still renders without touching the API. Concurrent reads of
+  the same key collapse into one upstream request, an expired entry is served
+  immediately while it refreshes in the background, a failing producer falls back
+  to the stale value, and empty answers (`null`/`undefined`) are not stored
+  unless `storeEmpty: true` is passed.
+- `cache().prewarm.priority` decides the warm-up order and accepts both the
+  config pattern syntax (`/news/:slug`) and plain regular expressions. Matching
+  paths are warmed on every pass.
+- Drip prewarming for large sites: `cache().prewarm.rps` (also `PREWARM_RPS`)
+  caps requests per second regardless of parallelism, and `rotate` (on by
+  default) makes periodic passes continue through the queue where the previous
+  one stopped instead of re-warming the same first slice. A pass is skipped while
+  the previous one is still running.
+- `cache().prewarm.retryDelayMs` (also `PREWARM_RETRY_DELAY_MS`) waits before the
+  retry pass, since rate limit windows are measured in seconds.
+- `cache().maxEntries` configures the HTML cache limit, which used to be a fixed
+  500.
+- Transient upstream failures are now detected without any application code:
+  `globalThis.fetch` is wrapped during startup and `429`, `5xx` and network
+  errors raised inside a render are reported on their own, so rate limits stop
+  turning existing pages into 404s even when the data layer never calls
+  `reportUpstreamFailure()`. Requests outside a render and requests to the
+  server itself are ignored, deterministic answers such as `404` are not
+  reported, and the wrapper can be turned off with `cache().trackUpstream:
+  false`.
+- `cache().transientRetry` (`{ attempts: 1, delayMs: 300 }` by default) retries a
+  page that called `notFound()` while upstream was failing. Each attempt runs in
+  a fresh upstream and per-request cache scope, so a page whose data arrives on
+  the second try is served and cached as usual instead of degrading to an error.
+- The dev report now includes the data cache entry count under `cache.data`.
+
+### Changed
+
+- `notFound()` is no longer served as a 404 when a transient upstream failure
+  (`429`, `5xx`, network error) happened during the same render. The page is
+  retried first and, if upstream is still failing, responds with an uncached
+  `503` and `Retry-After`. A temporary rate limit is no longer frozen into "this
+  page does not exist" for the whole TTL. A retry that gets a clean answer saying
+  the page is gone still returns a normal 404.
+- Responses produced with missing data are no longer offered to shared caches:
+  a `degraded` render is sent with `private, no-store` instead of
+  `public, s-maxage=…`. The `X-JSkelet-Cache` diagnostic header is still written.
+- The prewarm summary distinguishes paths left for the next pass
+  (`700 deferred to the next pass`) from paths dropped entirely
+  (`700 over the limit`).
+- The changelog page of the marketing example is generated from the project's
+  `CHANGELOG.md` instead of a hand-written list, and shows the version published
+  on npm next to the installed one.
+- The marketing example reads its markdown (documentation and changelog) from
+  the repository over GitHub's raw endpoint, falling back to the installed
+  package when the network is unavailable, so a deployment that ships without
+  `node_modules` can still serve the docs. In development the local file wins
+  and nothing is cached. The branch is overridable with `DOCS_REF`.
+
+## [0.1.2] - 2026-08-30
+
+### Added
+
 - `route(fn, { private: true })` for pages that depend on the visitor. The HTML
   cache is bypassed, `cache.html` patterns can no longer turn caching on for
   that route, and the response is sent with `private, no-store`, `Vary: Cookie`
@@ -42,8 +104,6 @@ one is listed under a **Breaking** heading.
   a private page, a paginated table fragment, a CSRF-protected mutation and an
   island with cleanup, covered by its own `smoke.mjs`.
 - An npm version badge in the `README`, linking to the package page.
-- English `README`, plus `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`,
-  a `LICENSE` file, issue and pull request templates, and a CI workflow.
 - An English edition of the documentation under `docs/en/`, mirroring every
   chapter of the Turkish `docs/`.
 - The dev overlay now compares the installed version against the `latest` tag on
@@ -76,7 +136,28 @@ one is listed under a **Breaking** heading.
   either; a stored "you need to sign in" redirect used to follow the visitor
   even after signing in.
 
-## [0.1.0]
+## [0.1.1] - 2026-08-30
+
+### Added
+
+- English `README`, plus `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`,
+  a `LICENSE` file, issue and pull request templates, and a CI workflow.
+- An English-first `examples/marketing` with a Turkish translation, serving the
+  package documentation under `/docs` and reading its version, dependencies and
+  bundle sizes from the installed package.
+
+### Changed
+
+- The install instructions point at the npm package instead of the git
+  repository.
+
+### Fixed
+
+- No more white flash between pages: the page background moved onto the root
+  element, so it applies before the body paints. Reduced-motion preferences now
+  switch off the decorative animations as well, not just page transitions.
+
+## [0.1.0] - 2026-08-30
 
 Initial release.
 
@@ -99,5 +180,7 @@ Initial release.
 - Documentation under `docs/` and three examples: `minimal`, `blog`,
   `marketing`.
 
-[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/ayberkenis/jskelet/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/ayberkenis/jskelet/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/ayberkenis/jskelet/releases/tag/v0.1.0

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 (otomatik izleme ve
+`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,28 @@ 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
@@ -102,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
 
@@ -134,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
 
@@ -216,15 +233,116 @@ 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
 HTML'i tüm TTL boyunca servis etmek yerine önbelleğe **hiç yazmamak** doğru
 davranış: sonraki istek yeniden dener.
 
+Bu bilgi iki yoldan gelir.
+
+### Otomatik izleme (varsayılan)
+
+`createApp()` açılışta `globalThis.fetch`i sarar ve render sırasında yapılan
+çağrılardaki **geçici** hataları (`429`, `5xx`, ağ hatası) kendiliğinden
+bildirir. Uygulama tarafında hiçbir satır gerekmez; `fetch` ile konuşan bir API
+istemcisi varsa rate limit koruması hazırdır.
+
+Ayrıntılar:
+
+- Yalnızca bir render bağlamı içindeki çağrılar sayılır. Script'ten, cron'dan
+  ya da istek dışı bir yerden yapılan `fetch` dokunulmaz kalır.
+- Kendi sunucumuza yapılan istekler (`localhost`, `127.0.0.1`) atlanır: ısıtma
+  turu ve sağlık kontrolü upstream değildir.
+- `404`/`403` gibi deterministik cevaplar **otomatik olarak bildirilmez**. Çoğu
+  API'de `404` "böyle bir kayıt yok" demektir; onu eksik veri saymak her yok
+  sayfasında yanlış uyarı üretirdi.
+- Kapatmak için `cache().trackUpstream: false`. `fetch`i kendisi saran bir
+  uygulama (ölçüm, retry, circuit breaker) bunu tercih edebilir.
+
+### Elle bildirim
+
+`fetch` kullanmayan bir istemci (veritabanı sürücüsü, gRPC, satıcı SDK'sı) ya da
+kalıcı hataları da işaretlemek isteyen bir katman için sözleşme aynı kaldı.
 Bağımlılık yönü bilinçli olarak tersine çevrilmiştir: framework veri katmanını
 tanımaz, veri katmanı framework'e haber verir. Hiç çağıran olmazsa maliyet boş
-bir dizidir.
+bir dizidir. Aynı hata her iki yoldan bildirilirse tekilleştirilir.
 
 ```js
 // lib/api/client.js
@@ -260,6 +378,58 @@ denemekle düzelmez. Onlar yüzünden önbelleği kapatmak sayfayı her ziyarett
 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ı
+varsa `notFound()` 404 olarak servis edilmez. Sırayla:
+
+1. Sayfa kısa bir beklemeden sonra **yeniden denenir** (varsayılan bir kez,
+   300 ms sonra). Deneme kendi upstream ve istek içi cache bağlamında koşar;
+   ilk turun hatası da memoize edilmiş boş cevabı da ikinci turu etkilemez.
+2. İkinci tur sayfayı üretebilirse ziyaretçi **gerçek içeriği** görür ve çıktı
+   normal şekilde önbelleğe girer. Isıtma günlükleri bunun sık olduğunu
+   gösteriyor: aynı yol saniyeler sonra 200 dönüyor.
+3. Denemeler tükendiyse yanıt `503` olur — önbelleğe girmez, `Retry-After`
+   taşır, sonraki istek yine gerçek içeriği üretebilir.
+
+| Render sırasında | `notFound()` sonucu |
+| --- | --- |
+| Geçici hata var (`429`, `5xx`, ağ hatası) | Tekrar dene → başarılıysa sayfa; hâlâ olmuyorsa `503`, `Retry-After: 30`, `no-store` |
+| Tekrar denemede upstream sağlam cevap verip "yok" dedi | Normal `404` |
+| Kalıcı hata var (`404`, `403`…) ya da hata yok | Normal `404`, tekrar denenmez |
+
+Log satırları:
+
+```
+[render] /haber/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /haber/x could not be produced, upstream is still failing (429 /api/...), serving an uncached 503 instead of a 404
+```
+
+Yani **var olan bir sayfa hiçbir koşulda 404'e dönüşmez**: ya gerçek içerik
+gelir, ya önbelleğe girmeyen bir 503. Hiçbir şey "yok" olarak dondurulmaz.
+
+Tekrar denemenin maliyeti upstream'e binen ikinci bir istek turudur; bu yüzden
+varsayılan tek deneme. Ayar `cache().transientRetry`:
+
+```js
+cache: {
+  transientRetry: { attempts: 2, delayMs: 500 },
+}
+```
+
+`transientRetry: false` (ya da `attempts: 0`) tekrarı kapatır ve doğrudan 503'e
+düşer.
+
 ## Önbelleği yönetmek
 
 `jskelet` şu fonksiyonları dışa açar:
@@ -335,24 +505,75 @@ 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:
+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
 de önbelleğe girmesi için.
@@ -385,10 +606,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.
@@ -432,6 +657,16 @@ 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
+  sayfa bir kez daha denenir, olmazsa 404 değil önbelleğe girmeyen 503 döner;
+  logda `returned notFound() while upstream is failing` satırını arayın. Hâlâ
+  404 görüyorsanız hata `fetch` dışı bir istemciden geliyor olabilir
+  (`reportUpstreamFailure()` gerekir) ya da `cache().trackUpstream` kapatılmış.
 
 ## Sırada ne var
 

package/docs/07-yapilandirma.md

@@ -115,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"],
+      },
     };
   },
 
@@ -549,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, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+**Varsayılan:**
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -570,18 +582,73 @@ 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().trackUpstream`
+
+**Tip:** `boolean` — **Varsayılan:** `true`
+
+Açıkken `globalThis.fetch` sarılır ve render sırasındaki geçici upstream
+hataları (`429`, `5xx`, ağ) kendiliğinden bildirilir; `reportUpstreamFailure()`
+çağırmak gerekmez. `fetch`i kendisi saran bir uygulama bunu kapatabilir.
+
+### `cache().transientRetry`
+
+**Tip:** `{ attempts?: number, delayMs?: number } | false` —
+**Varsayılan:** `{ attempts: 1, delayMs: 300 }`
+
+Geçici bir upstream hatası yüzünden `notFound()` çağrılan sayfa kaç kez daha
+denenir. Amaç var olan bir sayfanın 404'e dönüşmemesi; denemeler tükenirse yanıt
+önbelleğe girmeyen bir 503 olur. `false` ya da `attempts: 0` tekrarı kapatır.
+Ayrıntı: [06-cache.md](./06-cache.md).
+
 ### `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`
 
@@ -676,7 +743,9 @@ basılmaz.
 | `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. |