jskelet 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -31,23 +31,42 @@ one is listed under a **Breaking** heading.
   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) was reported during the same render. Those pages
-  now respond with an uncached `503` and `Retry-After`, so a temporary rate limit
-  is not frozen into "this page does not exist" for the whole TTL.
+  (`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 installed
-  package's `CHANGELOG.md` instead of a hand-written list, and shows the version
-  published on npm next to the installed one.
+- 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
 

package/docs/06-cache.md

@@ -5,8 +5,8 @@ Bu belge JSkelet'in ISR ikamesini bütün ayrıntılarıyla anlatır: HTML TTL
 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()`), veri önbelleği (`withDataCache`), upstream
-hatalarının önbelleği nasıl etkilediği (`reportUpstreamFailure`) ve sunucu
-açılışındaki ısıtma turu.
+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.
 
@@ -315,9 +315,34 @@ Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir.
 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
@@ -366,18 +391,44 @@ geçici bir kota sorunu TTL boyunca "bu sayfa yok" cevabına dönüşür. Arama
 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.
+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ı) | `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` |
+| 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ı:
 
-Log satırı:
-`[render] /haber/x returned notFound() while upstream is failing (429 /api/...), serving an uncached 503 instead`
+```
+[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 },
+}
+```
 
-Yani upstream'in kotası dolduğunda sayfa dinamik olarak, önbelleğe yazılmadan
-üretilir; hiçbir şey "yok" olarak dondurulmaz.
+`transientRetry: false` (ya da `attempts: 0`) tekrarı kapatır ve doğrudan 503'e
+düşer.
 
 ## Önbelleği yönetmek
 
@@ -612,8 +663,10 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
 - **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.
+  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

@@ -560,9 +560,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, prewarm?: object }` —
+`() => { 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 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -599,6 +599,24 @@ Upstream veri önbelleği (`withDataCache`). Ayrıntı: [06-cache.md](./06-cache
 | `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ı |

package/docs/en/06-caching.md

@@ -5,7 +5,7 @@ cache and its stale-while-revalidate behaviour, where `revalidate` comes from,
 how the cache key is built, the values of the `X-JSkelet-Cache` header, why the
 compressed body is kept in the cache, per-request memoization
 (`withRequestCache` / `cache()`), the data cache (`withDataCache`), how upstream
-failures affect the cache (`reportUpstreamFailure`) and the prewarm round at
+failures affect the cache (automatic tracking and `reportUpstreamFailure`) and the prewarm round at
 server startup. The
 measurement rationale behind the decisions is in
 [02-architecture.md](./02-architecture.md), and the full reference of config
@@ -324,9 +324,35 @@ If upstream went down during the render, the output contains missing data.
 Rather than serving such HTML for the whole TTL, the right behaviour is to
 **never write it** to the cache: the next request tries again.
 
-The dependency direction is deliberately inverted: the framework does not know
-about the data layer, the data layer notifies the framework. If nobody ever
-calls it, the cost is an empty array.
+This information arrives through two paths.
+
+### Automatic tracking (the default)
+
+At startup `createApp()` wraps `globalThis.fetch` and reports **transient**
+failures (`429`, `5xx`, network errors) from calls made during a render on its
+own. No application code is needed; if your API client talks over `fetch`, the
+rate limit protection is already in place.
+
+The details:
+
+- Only calls inside a render scope count. A `fetch` from a script, a cron job or
+  anywhere outside a request is left untouched.
+- Requests to our own server (`localhost`, `127.0.0.1`) are skipped: the warm-up
+  round and the health check are not upstream.
+- Deterministic answers such as `404`/`403` are **not** reported automatically.
+  In most APIs a `404` means "no such record"; treating it as missing data would
+  produce a false warning on every not-found page.
+- To turn it off: `cache().trackUpstream: false`. An application that wraps
+  `fetch` itself (metrics, retries, a circuit breaker) may prefer that.
+
+### Manual reporting
+
+For a client that does not use `fetch` (a database driver, gRPC, a vendor SDK),
+or for a layer that wants to flag permanent failures too, the contract is
+unchanged. The dependency direction is deliberately inverted: the framework does
+not know about the data layer, the data layer notifies the framework. If nobody
+ever calls it, the cost is an empty array. If the same failure arrives through
+both paths it is de-duplicated.
 
 ```js
 // lib/api/client.js
@@ -374,19 +400,45 @@ site into 404s when upstream is rate limited — and because those 404s enter th
 cache, a temporary quota problem becomes a "this page does not exist" answer for
 the whole TTL. For a search engine that is a permanent loss.
 
-The framework separates the two cases: if a **transient** upstream failure was
-reported during the render, `notFound()` is not served as a 404.
+The framework separates the two cases: if a **transient** upstream failure
+happened during the render, `notFound()` is not served as a 404. In order:
+
+1. The page is **retried** after a short delay (once by default, after 300 ms).
+   The retry runs in its own upstream and per-request cache scope, so neither
+   the first round's failure nor its memoized empty answers affect it.
+2. If the second round can produce the page, the visitor sees the **real
+   content** and the output is cached normally. Warm-up logs show this is
+   common: the same path returns 200 seconds later.
+3. If the retries are exhausted the response is a `503` — not cached, carrying
+   `Retry-After`, and the next request can still produce the real content.
 
 | During the render | Result of `notFound()` |
 | --- | --- |
-| A transient failure exists (`429`, `5xx`, network error) | `503`, `Retry-After: 30`, `no-store` — **not** written to the cache, the next request produces the real content |
-| A permanent failure (`404`, `403`…) or no failure | A normal `404` |
+| A transient failure exists (`429`, `5xx`, network error) | Retry → the page if it succeeds; otherwise `503`, `Retry-After: 30`, `no-store` |
+| The retry got a clean answer saying "not there" | A normal `404` |
+| A permanent failure (`404`, `403`…) or no failure | A normal `404`, no retry |
+
+The log lines:
 
-The log line:
-`[render] /news/x returned notFound() while upstream is failing (429 /api/...), serving an uncached 503 instead`
+```
+[render] /news/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /news/x could not be produced, upstream is still failing (429 /api/...), serving an uncached 503 instead of a 404
+```
+
+So **an existing page never turns into a 404**: either the real content arrives,
+or an uncached 503 does. Nothing is frozen as "missing".
+
+The cost of a retry is a second round of requests on upstream, which is why the
+default is a single attempt. The setting is `cache().transientRetry`:
+
+```js
+cache: {
+  transientRetry: { attempts: 2, delayMs: 500 },
+}
+```
 
-So when upstream runs out of quota the page is produced dynamically, without
-being written to the cache; nothing is frozen as "missing".
+`transientRetry: false` (or `attempts: 0`) disables the retry and falls straight
+through to the 503.
 
 ## Managing the cache
 
@@ -628,9 +680,12 @@ filled the cache.
   does not reach upstream.
 - **The warm-up list is longer than `max` and its tail never warms.** `rotate`
   may be `false`; the `over the limit` phrase in the log shows this.
-- **A whole section returns 404.** Upstream may be down. In that case a 503 that
-  does not enter the cache is now returned instead of a 404; look for the
-  `returned notFound() while upstream is failing` line in the log.
+- **A whole section returns 404.** Upstream may be down. The page is now retried
+  once and, failing that, a 503 that does not enter the cache is returned
+  instead of a 404; look for the `returned notFound() while upstream is failing`
+  line in the log. If you still see 404s, the failure may come from a non-`fetch`
+  client (which needs `reportUpstreamFailure()`) or `cache().trackUpstream` is
+  off.
 
 ## What's next
 

package/docs/en/07-configuration.md

@@ -572,9 +572,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -613,6 +613,25 @@ The upstream data cache (`withDataCache`). Details:
 | `maxEntries` | `number` | `10000` | The LRU entry limit. The limit is high because JSON is tens of times smaller than HTML. |
 | `staleFactor` | `number` | `10` | For how many TTLs an entry stays usable after the TTL expired. `0` → no stale serving. |
 
+### `cache().trackUpstream`
+
+**Type:** `boolean` — **Default:** `true`
+
+When on, `globalThis.fetch` is wrapped and transient upstream failures (`429`,
+`5xx`, network) during a render are reported automatically; calling
+`reportUpstreamFailure()` is not required. An application that wraps `fetch`
+itself can turn this off.
+
+### `cache().transientRetry`
+
+**Type:** `{ attempts?: number, delayMs?: number } | false` —
+**Default:** `{ attempts: 1, delayMs: 300 }`
+
+How many extra times a page is tried when `notFound()` was called because of a
+transient upstream failure. The point is that an existing page never turns into
+a 404; if the retries are exhausted the response is an uncached 503. `false` or
+`attempts: 0` disables the retry. Details: [06-caching.md](./06-caching.md).
+
 ### `cache().prewarm`
 
 | Field | Type | Default | Meaning |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/config/defaults.js

@@ -88,6 +88,20 @@ export const DEFAULT_PREWARM = {
  */
 export const DEFAULT_HTML_CACHE_MAX_ENTRIES = 500;
 
+/**
+ * `notFound()` geçici bir upstream hatasına denk geldiğinde sayfanın kaç kez
+ * daha denenmesi gerektiği.
+ *
+ * Varsayılan tek deneme: maliyeti upstream'e binen ikinci bir istek turu, ama
+ * alternatifi var olan bir sayfayı 404 olarak servis etmek — arama motoru için
+ * geçici bir rate limit'in kalıcı kayba dönüşmesi. `attempts: 0` tekrarı
+ * kapatır ve doğrudan önbelleğe girmeyen 503'e düşer.
+ */
+export const DEFAULT_TRANSIENT_RETRY = {
+  attempts: 1,
+  delayMs: 300,
+};
+
 /**
  * Upstream veri önbelleği.
  *

package/src/config/index.js

@@ -38,6 +38,7 @@ import {
   DEFAULT_PREWARM_SKIP,
   DEFAULT_SECURITY,
   DEFAULT_STATIC,
+  DEFAULT_TRANSIENT_RETRY,
 } from "./defaults.js";
 
 /** Framework paketinin kökü — kendi şablonlarına ve varlıklarına erişir. */
@@ -68,6 +69,8 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, seconds: number }[]} html
  * @property {number} htmlMaxEntries HTML önbelleğinin girdi sınırı.
  * @property {Record<string, unknown>} data Upstream veri önbelleği ayarları.
+ * @property {boolean} trackUpstream `fetch` sarılıp geçici hatalar otomatik bildirilsin mi.
+ * @property {{ attempts: number, delayMs: number }} transientRetry
  * @property {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
  * @property {Record<string, unknown>} brand
@@ -206,7 +209,9 @@ function normalizePriority(raw) {
 /**
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
- *   data: Record<string, unknown>, prewarm: Record<string, unknown>,
+ *   data: Record<string, unknown>, trackUpstream: boolean,
+ *   transientRetry: { attempts: number, delayMs: number },
+ *   prewarm: Record<string, unknown>,
  *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
  */
 function normalizeCache(raw) {
@@ -230,6 +235,13 @@ function normalizeCache(raw) {
         ? Math.floor(maxEntries)
         : DEFAULT_HTML_CACHE_MAX_ENTRIES,
     data: { ...DEFAULT_DATA_CACHE, ...(raw?.data ?? {}) },
+    // Otomatik upstream izleme kapatılabilir olmalı: `fetch`i kendisi saran
+    // bir uygulama (ölçüm, retry, circuit breaker) çakışma yaşayabilir.
+    trackUpstream: raw?.trackUpstream !== false,
+    transientRetry:
+      raw?.transientRetry === false
+        ? { attempts: 0, delayMs: 0 }
+        : { ...DEFAULT_TRANSIENT_RETRY, ...(raw?.transientRetry ?? {}) },
     // Desenler derlenmiş hâlde ayrı alanda tutulur: `prewarm` sayısal
     // ayarların düz torbası olarak kalsın, her turda yeniden derlenmesin.
     prewarm,
@@ -440,8 +452,15 @@ export async function loadConfig(options = {}) {
     section("cache"),
   ]);
 
-  const { html, htmlMaxEntries, data, prewarm, prewarmPriority } =
-    normalizeCache(cache);
+  const {
+    html,
+    htmlMaxEntries,
+    data,
+    trackUpstream,
+    transientRetry,
+    prewarm,
+    prewarmPriority,
+  } = normalizeCache(cache);
   const dirs = resolveDirs(root, source.paths);
   const brand = { ...DEFAULT_BRAND, ...(source.brand ?? {}) };
 
@@ -455,6 +474,8 @@ export async function loadConfig(options = {}) {
     html,
     htmlMaxEntries,
     data,
+    trackUpstream,
+    transientRetry,
     prewarm,
     prewarmPriority,
     brand,

package/src/server/create-app.js

@@ -34,6 +34,7 @@ import { registerRoutes } from "./router.js";
 import { renderNotFound } from "./render.js";
 import { renderStatusPage, statusFromError } from "./status-page.js";
 import { startPrewarm } from "./prewarm.js";
+import { trackUpstreamFetch } from "./upstream-tracking.js";
 import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
 
 /**
@@ -45,6 +46,11 @@ export async function createApp(options = {}) {
   await loadConfig(options);
   const config = getConfig();
 
+  // Upstream hatalarının izlenmesi route'lardan önce kurulmalı: sarmalayıcı
+  // yalnızca render bağlamı içindeki `fetch` çağrılarına bakar, ama bağlamın
+  // ilk kurulduğu istek de kapsanmalı.
+  if (config.trackUpstream) trackUpstreamFetch();
+
   const app = express();
 
   app.disable("x-powered-by");

package/src/server/render.js

@@ -27,7 +27,11 @@ import {
   guardRequest,
   withRequestContext,
 } from "../http/request-context.js";
-import { getUpstreamFailures, withUpstreamTracking } from "./upstream-tracking.js";
+import {
+  getUpstreamFailures,
+  isTransientStatus,
+  withUpstreamTracking,
+} from "./upstream-tracking.js";
 import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
 import { renderHeadMeta } from "./metadata.js";
 import { asset, hasAsset } from "./assets.js";
@@ -471,49 +475,100 @@ async function sendHtml(req, res, body, encoded, options = {}) {
 }
 
 /**
+ * @typedef {{ html: string, status: number, degraded?: boolean,
+ *   storable?: boolean, retryAfter?: number }} Produced
+ */
+
+/**
+ * Controller'ı bir kez çalıştırır. `notFound()` fırlatıldığında sonucu
+ * ayırt edilebilir biçimde döner: çağıran taraf bunun gerçek bir 404 mü,
+ * yoksa upstream düştüğü için verinin gelmemesi mi olduğuna karar verecek.
+ *
  * @param {Function} controller
  * @param {{ pathname: string }} ctx
- * @returns {Promise<{ html: string, status: number, degraded?: boolean,
- *   storable?: boolean, retryAfter?: number }>}
+ * @returns {Promise<{ page: Produced } | { notFound: true,
+ *   transient: import('./upstream-tracking.js').UpstreamFailure[] }>}
  */
-async function produce(controller, ctx) {
+async function attempt(controller, ctx) {
   try {
     const page = await controller(ctx);
     const rendered = await renderPage({ pathname: ctx.pathname, ...page });
     return {
-      html: rendered,
-      status: page.status ?? 200,
-      degraded: hasUpstreamFailures(ctx.pathname),
-      // Kimliğe bağlı çıktı önbelleğe yazılmaz. Karar burada verilmeli:
-      // `withHtmlCache` yazma anında controller'ın ne okuduğunu bilemez.
-      storable: getRequestContext()?.tainted !== true,
+      page: {
+        html: rendered,
+        status: page.status ?? 200,
+        degraded: hasUpstreamFailures(ctx.pathname),
+        // Kimliğe bağlı çıktı önbelleğe yazılmaz. Karar burada verilmeli:
+        // `withHtmlCache` yazma anında controller'ın ne okuduğunu bilemez.
+        storable: getRequestContext()?.tainted !== true,
+      },
     };
   } catch (error) {
     if (isNotFoundError(error)) {
-      // Veri gelmediği için `notFound()` çağrılmış olabilir: geçici bir
-      // upstream hatası (429, 5xx, ağ) varken bunu 404 olarak servis etmek iki
-      // kere yanlış. Önbelleğe girip TTL boyunca "bu sayfa yok" cevabını
-      // sabitler ve arama motoru geçici bir rate limit'i kalıcı 404 sanar.
-      // Doğrusu 503: cache'lenmez, `Retry-After` ile gider, sonraki istek
-      // gerçek içeriği üretir.
-      const transient = transientUpstreamFailures();
-      if (transient.length) {
-        console.warn(
-          `[render] ${ctx.pathname} returned notFound() while upstream is failing ` +
-            `(${summarizeFailures(transient)}), serving an uncached 503 instead`,
-        );
-        return {
-          html: await renderStatusPage(503),
-          status: 503,
-          degraded: true,
-          retryAfter: RETRY_AFTER_SECONDS,
-        };
-      }
+      return { notFound: true, transient: transientUpstreamFailures() };
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {Function} controller
+ * @param {{ pathname: string }} ctx
+ * @returns {Promise<Produced>}
+ */
+async function produce(controller, ctx) {
+  const first = await attempt(controller, ctx);
+  if ("page" in first) return first.page;
+  // Deterministik "böyle bir sayfa yok" cevabı: tekrar denemenin anlamı yok.
+  if (!first.transient.length) return { html: await renderNotFound(), status: 404 };
+
+  // Buraya gelindiyse `notFound()` veri gelmediği için çağrılmış. **Var olan
+  // bir sayfayı** 404 olarak servis etmek en kötü sonuç: arama motoru geçici
+  // bir rate limit'i kalıcı bir kayıp sanar. Bu yüzden sayfa yeniden denenir —
+  // ısıtma günlükleri gösteriyor ki aynı yol saniyeler sonra 200 dönüyor.
+  const { attempts, delayMs } = transientRetry();
+  let failures = first.transient;
+
+  for (let round = 1; round <= attempts; round += 1) {
+    console.warn(
+      `[render] ${ctx.pathname} returned notFound() while upstream is failing ` +
+        `(${summarizeFailures(failures)}), retrying (${round}/${attempts})`,
+    );
+
+    // Beklemeden tekrar denemek rate limit'e girmiş bir API'de aynı 429'u
+    // getirir; kısa bekleme hem pencerenin dönmesine şans verir hem de
+    // fırtınayı büyütmez.
+    await sleep(delayMs * round);
+
+    // Her deneme kendi upstream ve istek içi cache bağlamında çalışır: ilk
+    // turun hataları ikinci turun kararını kirletmesin ve memoize edilmiş
+    // boş cevaplar tekrar kullanılmasın.
+    const retried = await withUpstreamTracking(() =>
+      withRequestCache(() => attempt(controller, ctx)),
+    );
 
+    if ("page" in retried) return retried.page;
+    if (!retried.transient.length) {
+      // Bu kez upstream sağlam cevap verdi ve "yok" dedi: gerçek 404.
       return { html: await renderNotFound(), status: 404 };
     }
-    throw error;
+
+    failures = retried.transient;
   }
+
+  // Denemeler tükendi. 404 yerine 503: önbelleğe girmez, `Retry-After` taşır
+  // ve bir sonraki istek gerçek içeriği üretebilir.
+  console.warn(
+    `[render] ${ctx.pathname} could not be produced, upstream is still failing ` +
+      `(${summarizeFailures(failures)}), serving an uncached 503 instead of a 404`,
+  );
+
+  return {
+    html: await renderStatusPage(503),
+    status: 503,
+    degraded: true,
+    retryAfter: RETRY_AFTER_SECONDS,
+  };
 }
 
 /**
@@ -523,14 +578,32 @@ async function produce(controller, ctx) {
  */
 const RETRY_AFTER_SECONDS = 30;
 
-/** Ağ hatası (0) ve geçici olduğu varsayılan durumlar. */
-const TRANSIENT_STATUSES = new Set([0, 408, 425, 429]);
+/**
+ * Tekrar denemenin maliyeti upstream'e binen ikinci bir istek turu; bu yüzden
+ * varsayılan tek deneme ve kısa bekleme. Rate limit fırtınasında toplam yük
+ * iki katına çıkabilir, ama alternatifi var olan sayfaları 404'e düşürmek.
+ *
+ * @returns {{ attempts: number, delayMs: number }}
+ */
+function transientRetry() {
+  const raw = /** @type {any} */ (getConfig().transientRetry ?? {});
+  const attempts = Number(raw.attempts);
+  const delayMs = Number(raw.delayMs);
+
+  return {
+    attempts: Number.isFinite(attempts) && attempts >= 0 ? Math.floor(attempts) : 1,
+    delayMs: Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : 300,
+  };
+}
 
-/** @param {number} status */
-function isTransient(status) {
-  return TRANSIENT_STATUSES.has(status) || status >= 500;
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
 }
 
+
 /**
  * Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir.
  * Böyle bir HTML önbelleğe yazılmaz: sonraki istek yeniden dener.
@@ -548,8 +621,8 @@ function hasUpstreamFailures(pathname) {
   const failures = getUpstreamFailures();
   if (!failures.length) return false;
 
-  const transient = failures.filter((failure) => isTransient(failure.status));
-  const permanent = failures.filter((failure) => !isTransient(failure.status));
+  const transient = failures.filter((failure) => isTransientStatus(failure.status));
+  const permanent = failures.filter((failure) => !isTransientStatus(failure.status));
 
   if (permanent.length) {
     console.warn(
@@ -570,7 +643,7 @@ function hasUpstreamFailures(pathname) {
  * @returns {import('./upstream-tracking.js').UpstreamFailure[]}
  */
 function transientUpstreamFailures() {
-  return getUpstreamFailures().filter((failure) => isTransient(failure.status));
+  return getUpstreamFailures().filter((failure) => isTransientStatus(failure.status));
 }
 
 /**

package/src/server/upstream-tracking.js

@@ -1,22 +1,25 @@
 /**
  * Render başına upstream API hatalarını toplar.
  *
- * `render.js` her sayfayı bu bağlam içinde üretir; uygulamanın HTTP istemcisi
- * başarısız bir upstream yanıtında `reportUpstreamFailure()` çağırır. Böylece
- * HTML önbelleği "bu çıktı eksik veriyle üretildi" bilgisine sahip olur ve
- * bozuk sayfayı saklamaz.
+ * `render.js` her sayfayı bu bağlam içinde üretir. Böylece HTML önbelleği "bu
+ * çıktı eksik veriyle üretildi" bilgisine sahip olur ve bozuk sayfayı saklamaz;
+ * `notFound()` de geçici bir hataya denk geldiğinde 404 olmaktan çıkar.
  *
- * Bağımlılık yönü bilinçli olarak tersine çevrilmiş: framework veri katmanını
- * tanımaz, veri katmanı framework'e haber verir. Hiç çağıran olmazsa maliyet
- * boş bir dizidir.
+ * Bilgi iki yoldan gelir:
  *
- * Kullanım (uygulamanın `lib/api/client.js` içinde):
+ *   1. **Otomatik** — `trackUpstreamFetch()` `globalThis.fetch`i sarar ve
+ *      geçici hataları (429, 5xx, ağ) kendiliğinden bildirir. `createApp()`
+ *      bunu açılışta kurar, yani hiçbir uygulama kodu gerekmez.
+ *   2. **Elle** — `fetch` kullanmayan bir istemci (veritabanı sürücüsü, gRPC,
+ *      SDK) için:
  *
- *   import { reportUpstreamFailure } from "jskelet/server";
+ *        import { reportUpstreamFailure } from "jskelet";
  *
- *   if (!response.ok) {
- *     reportUpstreamFailure({ status: response.status, path: url });
- *   }
+ *        if (!response.ok) {
+ *          reportUpstreamFailure({ status: response.status, path: url });
+ *        }
+ *
+ * İki yol aynı hatayı bildirirse tekilleştirilir.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -33,7 +36,94 @@ const storage = new AsyncLocalStorage();
  * @returns {void}
  */
 export function reportUpstreamFailure(failure) {
-  storage.getStore()?.failures.push(failure);
+  const store = storage.getStore();
+  if (!store) return;
+
+  // Aynı hatayı hem otomatik sarmalayıcı hem uygulamanın istemcisi
+  // bildirebilir; aynı satırı iki kez loglamanın faydası yok.
+  const duplicate = store.failures.some(
+    (existing) => existing.status === failure.status && existing.path === failure.path,
+  );
+  if (!duplicate) store.failures.push(failure);
+}
+
+/**
+ * Geçici sayılan durumlar: tekrar denemekle düzelebilenler. Bu liste
+ * `render.js` ile paylaşılır — hangi hatanın önbelleği engellediği ve hangi
+ * hatanın `notFound()`u 404 olmaktan çıkardığı tek yerde tanımlı olsun.
+ */
+const TRANSIENT_STATUSES = new Set([0, 408, 425, 429]);
+
+/**
+ * @param {number} status
+ * @returns {boolean}
+ */
+export function isTransientStatus(status) {
+  return TRANSIENT_STATUSES.has(status) || status >= 500;
+}
+
+/**
+ * `globalThis.fetch`i sarıp **geçici** upstream hatalarını kendiliğinden
+ * bildirir.
+ *
+ * Gerekçesi pratik: `reportUpstreamFailure()` sözleşmesi uygulamanın HTTP
+ * istemcisine bir satır eklemeyi gerektiriyor ve o satır yazılmadığında
+ * framework rate limit'i hiç göremiyor — veri gelmediği için `notFound()`
+ * çağıran sayfa 404 olarak servis ediliyordu. Otomatik izleme bu bilgiyi
+ * varsayılan hâle getirir; elle çağrı hâlâ geçerli ve tekilleştirilir.
+ *
+ * Yalnızca geçici durumlar bildirilir. `404`/`403` gibi deterministik
+ * cevaplar birçok API'de "böyle bir kayıt yok" anlamına geliyor ve onları
+ * otomatik olarak "eksik veri" saymak her sayfada yanlış uyarı üretirdi.
+ *
+ * Kendi sunucumuza yapılan istekler atlanır: ısıtma turu ve sağlık kontrolü
+ * upstream değil.
+ *
+ * @returns {void}
+ */
+export function trackUpstreamFetch() {
+  const original = globalThis.fetch;
+  if (/** @type {any} */ (original).__jskeletUpstreamTracked) return;
+
+  /** @type {typeof fetch} */
+  const wrapped = async (input, init) => {
+    // İstek bir render bağlamı içinde değilse (script, zamanlayıcı) hiçbir
+    // şey yapılmaz: sarmalayıcının maliyeti bir `getStore()` çağrısı.
+    if (!storage.getStore()) return original(input, init);
+
+    const url = requestUrl(input);
+    if (isSelfRequest(url)) return original(input, init);
+
+    try {
+      const response = await original(input, init);
+      if (!response.ok && isTransientStatus(response.status)) {
+        reportUpstreamFailure({ status: response.status, path: url });
+      }
+      return response;
+    } catch (error) {
+      // Yanıt hiç gelmedi: ağ hatası her zaman geçicidir.
+      reportUpstreamFailure({ status: 0, path: url });
+      throw error;
+    }
+  };
+
+  /** @type {any} */ (wrapped).__jskeletUpstreamTracked = true;
+  globalThis.fetch = wrapped;
+}
+
+/**
+ * @param {RequestInfo | URL} input
+ * @returns {string}
+ */
+function requestUrl(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.href;
+  return /** @type {Request} */ (input)?.url ?? String(input);
+}
+
+/** @param {string} url */
+function isSelfRequest(url) {
+  return /^https?:\/\/(127\.0\.0\.1|\[::1\]|localhost)(:|\/|$)/i.test(url);
 }
 
 /**