jskelet 0.1.2 → 0.1.3

package/src/server/data-cache.js

@@ -0,0 +1,244 @@
+/**
+ * Upstream veri için TTL + stale-while-revalidate LRU önbelleği.
+ *
+ * HTML önbelleği (`html-cache.js`) yalnızca **trafiği olan** sayfaları tutar:
+ * girdi başına yüz kilobayt düştüğü için sınırı 500 civarındadır ve on binlerce
+ * yolluk bir site onu ısıtmaya çalıştığında kendi ısıttığını siler. Uzun kuyruk
+ * için doğru katman bu modül: aynı sayfanın JSON'u HTML'inden onlarca kat
+ * küçük olduğu için on binlerce girdi bellekte durur.
+ *
+ * Kazanç iki taraflı:
+ *   - Hiç ısıtılmamış bir uzun kuyruk sayfası ilk ziyaretçide render edilir ama
+ *     upstream'e gitmez; gecikme yüzlerce ms değil, şablon render'ı kadardır.
+ *   - Periyodik ısıtma turları API kotası harcamaz, veri katmanından okur.
+ *
+ * `null`/`undefined` **saklanmaz**: uygulamaların HTTP istemcisi hatada
+ * genellikle `null` döner ve 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.
+ */
+import { getConfig } from "../config/index.js";
+import { DEFAULT_DATA_CACHE } from "../config/defaults.js";
+
+/**
+ * @typedef {{ value: unknown, expiresAt: number, staleUntil: number }} DataEntry
+ */
+
+/** @type {Map<string, DataEntry>} */
+const store = new Map();
+
+/** @type {Map<string, Promise<unknown>>} */
+const inflight = new Map();
+
+/**
+ * Ayarlar config'ten okunur ama config yüklenmemiş olabilir: bu modül
+ * script'lerden ve testlerden de çağrılabiliyor. `getConfig()` fırlatırsa
+ * kod varsayılanına düşülür.
+ *
+ * @returns {{ maxEntries: number, staleFactor: number }}
+ */
+function settings() {
+  try {
+    const { data } = getConfig();
+    return {
+      maxEntries: Number(data?.maxEntries) || DEFAULT_DATA_CACHE.maxEntries,
+      staleFactor: Number.isFinite(Number(data?.staleFactor))
+        ? Number(data.staleFactor)
+        : DEFAULT_DATA_CACHE.staleFactor,
+    };
+  } catch {
+    return { ...DEFAULT_DATA_CACHE };
+  }
+}
+
+/**
+ * @param {string} key
+ * @returns {{ value: unknown, stale: boolean } | null}
+ */
+function read(key) {
+  const entry = store.get(key);
+  if (!entry) return null;
+
+  const now = Date.now();
+  if (now >= entry.staleUntil) {
+    store.delete(key);
+    return null;
+  }
+
+  // LRU: erişilen girdiyi sona taşı.
+  store.delete(key);
+  store.set(key, entry);
+
+  return { value: entry.value, stale: now >= entry.expiresAt };
+}
+
+/**
+ * @param {string} key
+ * @param {unknown} value
+ * @param {number} ttlSeconds
+ * @param {number} staleFactor
+ */
+function write(key, value, ttlSeconds, staleFactor) {
+  const now = Date.now();
+  const ttl = ttlSeconds * 1000;
+
+  store.set(key, {
+    value,
+    expiresAt: now + ttl,
+    staleUntil: now + ttl + ttl * staleFactor,
+  });
+
+  const { maxEntries } = settings();
+  while (store.size > maxEntries) {
+    const oldest = store.keys().next().value;
+    if (oldest === undefined) break;
+    store.delete(oldest);
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {number} ttlSeconds
+ * @param {() => Promise<unknown>} producer
+ * @param {{ storeEmpty?: boolean, staleFactor?: number }} options
+ * @returns {Promise<unknown>}
+ */
+function refresh(key, ttlSeconds, producer, options) {
+  // Aynı anahtarı eşzamanlı isteyen yüz sayfa tek upstream isteğine düşer.
+  // Isıtma turlarında bu tek başına kotanın büyük kısmını kurtarıyor.
+  const pending = inflight.get(key);
+  if (pending) return pending;
+
+  const staleFactor = options.staleFactor ?? settings().staleFactor;
+
+  const task = Promise.resolve()
+    .then(producer)
+    .then((value) => {
+      const empty = value === undefined || value === null;
+      if (!empty || options.storeEmpty === true) {
+        write(key, value, ttlSeconds, staleFactor);
+      }
+      return value;
+    })
+    .finally(() => {
+      inflight.delete(key);
+    });
+
+  inflight.set(key, task);
+  return task;
+}
+
+/**
+ * Veriyi önbellekten döner, gerekiyorsa `producer` ile üretir.
+ *
+ * @param {string} key Anahtar tamamen uygulamanın; sürüm/dil gibi ayrımlar
+ *   anahtara yazılır (`quote:v2:${symbol}`).
+ * @param {number} ttlSeconds 0 → önbellek yok, `producer` her çağrıda çalışır.
+ * @param {() => Promise<T>} producer
+ * @param {{ storeEmpty?: boolean, staleFactor?: number }} [options]
+ *   `storeEmpty` boş cevabı da saklar, `staleFactor` bu anahtar için bayat
+ *   penceresini ayarlar (0 → bayat servis yok).
+ * @returns {Promise<T>}
+ * @template T
+ */
+export async function withDataCache(key, ttlSeconds, producer, options = {}) {
+  if (!ttlSeconds) return producer();
+
+  const hit = read(key);
+
+  if (hit) {
+    // Bayat girdi anında döner; tazeleme arkada yürür ve hatası bu isteği
+    // etkilemez — çağıran taraf bir şey beklemediği için upstream'in yavaş
+    // olması sayfaya yansımaz.
+    if (hit.stale) {
+      void refresh(key, ttlSeconds, producer, options).catch((error) => {
+        console.error(`[data-cache] background refresh failed: ${key}`, error);
+      });
+    }
+    return /** @type {T} */ (hit.value);
+  }
+
+  try {
+    return /** @type {T} */ (await refresh(key, ttlSeconds, producer, options));
+  } catch (error) {
+    // Girdi yoksa hata çağırana gider; asıl kazanç bayat girdinin olduğu
+    // durumda: upstream düşmüşken sayfayı eski veriyle ayakta tutmak,
+    // ziyaretçiye hata sayfası göstermekten iyidir.
+    const stale = read(key);
+    if (!stale) throw error;
+
+    console.warn(
+      `[data-cache] producer failed, serving stale value: ${key}`,
+      error instanceof Error ? error.message : error,
+    );
+    return /** @type {T} */ (stale.value);
+  }
+}
+
+/**
+ * `withDataCache`'in fonksiyon sarmalayıcısı: argümanlardan anahtar üretir.
+ * `cache()` (istek içi memoizasyon) ile aynı kullanım biçimi, ama istekler
+ * arasında ve TTL'li.
+ *
+ * @param {F} fn
+ * @param {{ key: string, revalidate: number, storeEmpty?: boolean,
+ *   staleFactor?: number }} options `key` önektir; argümanlar sonuna eklenir.
+ * @returns {F}
+ * @template {(...args: any[]) => Promise<any>} F
+ */
+export function dataCache(fn, options) {
+  const wrapped = (...args) =>
+    withDataCache(
+      args.length ? `${options.key}:${JSON.stringify(args)}` : options.key,
+      options.revalidate,
+      () => fn(...args),
+      options,
+    );
+
+  return /** @type {F} */ (wrapped);
+}
+
+/**
+ * Bir anahtarı ya da önek eşleşen tüm anahtarları düşürür. Webhook ile
+ * "bu haber güncellendi" bilgisi geldiğinde kullanılır.
+ *
+ * @param {string} [prefix] Verilmezse tüm önbellek boşaltılır.
+ * @returns {number} Silinen girdi sayısı.
+ */
+export function clearDataCache(prefix) {
+  if (prefix === undefined) {
+    const size = store.size;
+    store.clear();
+    return size;
+  }
+
+  let removed = 0;
+  for (const key of store.keys()) {
+    if (key.startsWith(prefix)) {
+      store.delete(key);
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+/** @returns {number} */
+export function getDataCacheSize() {
+  return store.size;
+}
+
+/**
+ * Dev raporu ve yönetim uçları için döküm. Değerin kendisi dönmez: JSON'un
+ * tamamını bir teşhis ucundan dışa vermek istenmez.
+ *
+ * @returns {{ key: string, stale: boolean, expiresIn: number }[]}
+ */
+export function getDataCacheEntries() {
+  const now = Date.now();
+
+  return [...store.entries()].map(([key, entry]) => ({
+    key,
+    stale: now >= entry.expiresAt,
+    expiresIn: Math.round((entry.expiresAt - now) / 1000),
+  }));
+}

package/src/server/dev/report.js

@@ -13,6 +13,7 @@ import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 import { getHtmlCacheEntries, getHtmlCacheSize } from "../html-cache.js";
+import { getDataCacheSize } from "../data-cache.js";
 import { prewarmProgress } from "../prewarm.js";
 import { getConfig } from "../../config/index.js";
 
@@ -343,7 +344,13 @@ export function buildReport(devtools) {
     pages: pageList.sort((a, b) => (b.visits - a.visits) || b.at - a.at),
     serverApi: serverApiCalls.slice().reverse(),
     build: { assets: assets(), ...chunks() },
-    cache: { size: getHtmlCacheSize(), entries: getHtmlCacheEntries() },
+    cache: {
+      size: getHtmlCacheSize(),
+      entries: getHtmlCacheEntries(),
+      // Veri önbelleğinden yalnızca sayaç: uzun kuyruklu bir sitede on
+      // binlerce anahtar oluyor ve dökümü rapora koymak faydasız bir yük.
+      data: getDataCacheSize(),
+    },
     prewarm: { ...prewarmProgress },
     requests: devtools.requests,
     errors: devtools.errors,

package/src/server/html-cache.js

@@ -8,12 +8,31 @@
  * WebSocket'ten güncellendiği için bu gecikme ekranda görünmez.
  */
 
+import { getConfig } from "../config/index.js";
+import { DEFAULT_HTML_CACHE_MAX_ENTRIES } from "../config/defaults.js";
+
 /**
  * @typedef {{ html: string, status: number, expiresAt: number,
  *   staleUntil: number, encoded: Map<string, Buffer> }} HtmlEntry
  */
 
-const MAX_ENTRIES = 500;
+/**
+ * Girdi sınırı `cache().maxEntries` ile yükseltilebilir ama uzun kuyruklu bir
+ * siteyi buradan çözmeye çalışmak yanlış katman: girdi başına yüz kilobayt
+ * düşüyor. On binlerce yol için `withDataCache` kullanılır.
+ *
+ * Config yüklenmemiş olabilir (testler bu modülü doğrudan çağırıyor); o
+ * durumda kod varsayılanı geçerli.
+ *
+ * @returns {number}
+ */
+function maxEntries() {
+  try {
+    return getConfig().htmlMaxEntries;
+  } catch {
+    return DEFAULT_HTML_CACHE_MAX_ENTRIES;
+  }
+}
 
 /**
  * TTL dolduktan sonra eski HTML'in kaç TTL boyunca daha servis edilebileceği.
@@ -73,7 +92,8 @@ function write(key, value, ttlSeconds) {
     staleUntil: now + ttlSeconds * 1000 * (1 + STALE_FACTOR),
   });
 
-  while (store.size > MAX_ENTRIES) {
+  const limit = maxEntries();
+  while (store.size > limit) {
     const oldest = store.keys().next().value;
     if (oldest === undefined) break;
     store.delete(oldest);

package/src/server/prewarm.js

@@ -11,6 +11,12 @@
  * middleware zinciri normal trafikle bire bir aynı olsun. Hangi yolların
  * ısıtılacağını uygulama `hooks.prewarmPaths()` ile bildirir; genelde
  * sitemap üreten fonksiyonun aynısıdır.
+ *
+ * On binlerce yolluk bir sitede tur bir "damla damla" tarayıcıya dönüşür:
+ * `priority` desenleri her turda başa alınır, geri kalan kuyruk turlar
+ * arasında kaldığı yerden devam eder (`rotate`) ve `rps` toplam hızı upstream
+ * kotasının altında tutar. Amaç, kimse gelmese bile hiçbir sayfanın soğuk
+ * kalmaması — ama bunu API'yi düşürmeden yapmak.
  */
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
@@ -78,6 +84,100 @@ async function collectPaths() {
   );
 }
 
+/**
+ * `cache().prewarm.priority` desenlerine göre sıralar. Eşleşmeyen yollar
+ * listenin sonuna, kendi aralarındaki sırayı koruyarak gider — uygulamanın
+ * verdiği sıra hâlâ anlamlı olsun.
+ *
+ * @param {string[]} paths
+ * @returns {{ head: string[], tail: string[] }}
+ *   `head` öncelikli yollar (her turda ısıtılır), `tail` geri kalan kuyruk
+ *   (turlar arasında dolaşılır).
+ */
+function byPriority(paths) {
+  const rules = getConfig().prewarmPriority;
+  if (!rules.length) return { head: [], tail: paths };
+
+  /** @type {string[][]} */
+  const buckets = rules.map(() => []);
+  /** @type {string[]} */
+  const tail = [];
+
+  for (const candidate of paths) {
+    const rank = rules.findIndex((rule) => rule.test(candidate));
+    if (rank === -1) tail.push(candidate);
+    else buckets[rank].push(candidate);
+  }
+
+  return { head: buckets.flat(), tail };
+}
+
+/**
+ * Kuyruğun kaldığı yer. Periyodik turlar listeyi baştan ısıtıp aynı ilk
+ * `max` yolu tekrar tekrar tazelemesin: her tur bir sonraki dilimi alır ve
+ * yeterli tur sonunda liste baştan sona ısınır.
+ */
+let queueCursor = 0;
+
+/**
+ * Bir turda ısıtılacak dilimi seçer: önce `priority` eşleşenler, sonra
+ * kuyruğun sırası gelen parçası. Dışa açık olması bilinçli — sıralama ve
+ * rotasyon, tur çalışmadan doğrulanabilen tek davranış.
+ *
+ * @param {string[]} all
+ * @param {number} limit
+ * @param {boolean} rotate
+ * @returns {string[]}
+ */
+export function selectPrewarmPaths(all, limit, rotate = true) {
+  if (all.length <= limit) return all;
+
+  const { head, tail } = byPriority(all);
+  const selected = head.slice(0, limit);
+  const room = limit - selected.length;
+  if (room <= 0 || !tail.length) return selected;
+
+  if (!rotate) return [...selected, ...tail.slice(0, room)];
+
+  // Dilim listenin sonunu aşarsa başa sarar: kuyruk halkasal dolaşılır.
+  const start = queueCursor % tail.length;
+  const slice = tail.slice(start, start + room);
+  if (slice.length < room) slice.push(...tail.slice(0, room - slice.length));
+  queueCursor = (start + room) % tail.length;
+
+  return [...selected, ...slice];
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
+}
+
+/**
+ * Saniyedeki istek sayısını sınırlar. Fren `concurrency`'den bağımsız
+ * olmalı: paralellik gecikmeyi kapatmak için var, kotayı koruyan şey toplam
+ * hız. İşçiler aynı sayacı paylaştığı için sıra kimde olursa olsun tur
+ * verilen hızın üstüne çıkmaz.
+ *
+ * @param {number} rps 0 → sınırsız
+ * @returns {() => Promise<void>}
+ */
+function createPacer(rps) {
+  if (!rps) return async () => {};
+
+  const gap = 1000 / rps;
+  let nextSlot = 0;
+
+  return async () => {
+    const now = Date.now();
+    const slot = Math.max(now, nextSlot);
+    nextSlot = slot + gap;
+    if (slot > now) await sleep(slot - now);
+  };
+}
+
 /**
  * `DEV_TOKEN` ayarlıyken `devGate` token taşımayan her isteğe 404 döner.
  * Isıtma kendi sunucusuna istek attığı için token'ı çerez olarak taşımalı;
@@ -100,9 +200,10 @@ function devGateHeader() {
  * @param {(ok: number, failed: number) => void} [report]
  *   Tur ilerlemesini `prewarmProgress`'e yazar. Tekrar turunda sayaçların
  *   anlamı değiştiği için çağıran taraf kendi formülünü verir.
+ * @param {() => Promise<void>} [pace] İstek başına beklenen hız freni.
  * @returns {Promise<{ ok: number, failed: number, failedPaths: string[] }>}
  */
-async function crawl(origin, paths, concurrency, report = undefined) {
+async function crawl(origin, paths, concurrency, report = undefined, pace = undefined) {
   const { brand } = getConfig();
   const cacheHeader = brand.cacheHeader.toLowerCase();
 
@@ -117,6 +218,8 @@ async function crawl(origin, paths, concurrency, report = undefined) {
       const target = paths[index];
       index += 1;
 
+      if (pace) await pace();
+
       const startedAt = Date.now();
 
       try {
@@ -191,8 +294,15 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
     process.env.NODE_ENV === "development" ? 2 : 4,
   );
 
+  const rps = num(process.env.PREWARM_RPS, num(getConfig().prewarm?.rps, 0));
+  const pace = createPacer(rps);
+
   const all = only?.length ? only : await collectPaths();
-  const paths = all.slice(0, limit);
+  // Elle verilen liste budanmaz ve sıralanmaz: çağıran tam olarak neyi
+  // istediğini biliyor (dev panelindeki "tekrar dene" bunu kullanır).
+  const paths = only?.length
+    ? all
+    : selectPrewarmPaths(all, limit, getConfig().prewarm?.rotate !== false);
 
   Object.assign(prewarmProgress, {
     active: true,
@@ -211,7 +321,13 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
   try {
     /** @type {string[]} */
     let failedPaths;
-    ({ ok, failed, failedPaths } = await crawl(origin, paths, concurrency));
+    ({ ok, failed, failedPaths } = await crawl(
+      origin,
+      paths,
+      concurrency,
+      undefined,
+      pace,
+    ));
 
     // Hatalar çoğunlukla upstream rate limit'i (429): ilk tur yüzlerce sayfayı
     // aynı anda çekerken API'yi zorluyor. Tek seri tekrar turu bu sayfaların
@@ -219,11 +335,23 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
     if (failedPaths.length) {
       const firstOk = ok;
       const firstFailed = failed;
-      const retry = await crawl(origin, failedPaths, 1, (retriedOk) => {
-        // Tekrar turunda her başarı bir hatayı başarıya çevirir.
-        prewarmProgress.ok = firstOk + retriedOk;
-        prewarmProgress.failed = firstFailed - retriedOk;
-      });
+
+      // Rate limit pencereleri saniye mertebesinde; hemen tekrar denemek aynı
+      // 429'u almak demek.
+      const retryDelay = setting("PREWARM_RETRY_DELAY_MS", "retryDelayMs", 2000);
+      await sleep(retryDelay);
+
+      const retry = await crawl(
+        origin,
+        failedPaths,
+        1,
+        (retriedOk) => {
+          // Tekrar turunda her başarı bir hatayı başarıya çevirir.
+          prewarmProgress.ok = firstOk + retriedOk;
+          prewarmProgress.failed = firstFailed - retriedOk;
+        },
+        pace,
+      );
       recovered = retry.ok;
       ok += retry.ok;
       failed -= retry.ok;
@@ -236,11 +364,15 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
 
   if (!quiet && paths.length) {
     const skipped = all.length - paths.length;
+    // Rotasyon açıkken sınırın dışında kalan yollar kaybolmuyor, bir sonraki
+    // tura kalıyor; log bunu ayırt etmeli, yoksa "400 yol atlandı" satırı
+    // hatalı bir kurulum sanılıyor.
+    const rotate = !only?.length && getConfig().prewarm?.rotate !== false;
     console.log(
       `[prewarm] warmed ${ok}/${paths.length} pages` +
         `${failed ? `, ${failed} failed` : ""}` +
         `${recovered ? `, ${recovered} recovered on the retry pass` : ""}` +
-        `${skipped > 0 ? `, ${skipped} over the limit` : ""}` +
+        `${skipped > 0 ? `, ${skipped} ${rotate ? "deferred to the next pass" : "over the limit"}` : ""}` +
         ` (${(elapsed / 1000).toFixed(1)}s)`,
     );
   }
@@ -264,20 +396,33 @@ export function startPrewarm({ port }) {
 
   const isDev = process.env.NODE_ENV === "development";
   const origin = `http://127.0.0.1:${port}`;
-  const run = () =>
-    prewarm({ origin }).catch((error) => {
+
+  // Hız frenli bir tur `intervalSeconds`'tan uzun sürebilir; üst üste binen
+  // turlar `prewarmProgress`'i bozar ve upstream'e iki kat yük bindirir.
+  let running = false;
+  const run = async () => {
+    if (running) return;
+    running = true;
+    try {
+      await prewarm({ origin });
+    } catch (error) {
       console.error("[prewarm] failed", error);
-    });
+    } finally {
+      running = false;
+    }
+  };
 
   // Isıtma ilk isteklerle yarışmasın diye gecikmeyle başlar. Dev'de gecikme
   // daha uzun: dosya kaydı süreci yeniden başlattığı için zamanlayıcı da
   // ölür; yalnızca sunucu bir süre sakin kalınca ısınır.
   const delay = setting("PREWARM_DELAY_MS", "delayMs", isDev ? 3000 : 500);
-  setTimeout(run, delay).unref();
+  setTimeout(() => void run(), delay).unref();
 
   // Girdiler `revalidate` ile yaşlanır; stale-while-revalidate sayesinde
   // ziyaretçi beklemez. Periyodik tur, hiç ziyaret edilmeyen sayfaları da
   // sıcak tutmak isteyen kurulumlar için opsiyoneldir.
+  // `rotate` ile birlikte bu ayar "damla damla ısıtma"ya dönüşür: her tur
+  // kuyruğun bir dilimini alır, yeterli tur sonunda liste baştan sona ısınır.
   const interval = setting("PREWARM_INTERVAL_SECONDS", "intervalSeconds", 0);
-  if (interval > 0) setInterval(run, interval * 1000).unref();
+  if (interval > 0) setInterval(() => void run(), interval * 1000).unref();
 }

package/src/server/render.js

@@ -226,20 +226,35 @@ export function route(controller, options = {}) {
         );
       }
 
-      const publicCache = cacheable && !leaked;
+      // Eksik veriyle üretilen çıktı süreç içi önbelleğe yazılmıyor; aynı
+      // çıktıya CDN'de `s-maxage` vermek o kararı bir katman yukarıda geri
+      // almak olurdu. Geçici bir 429 yüzünden üretilen 503, ters proxy'de
+      // dakikalarca yaşamamalı.
+      const publicCache = cacheable && !leaked && !result.degraded;
 
       res.status(result.status);
       res.setHeader("Content-Type", "text/html; charset=utf-8");
 
+      // Geçici upstream hatası: istemciye ve bota "bu kalıcı değil, sonra gel"
+      // demenin standart yolu.
+      if (result.retryAfter) {
+        res.setHeader("Retry-After", String(result.retryAfter));
+      }
+
+      // Teşhis başlığı `degraded` yanıtta da yazılır: "MISS" görmek, sayfanın
+      // önbellek yolundan geçtiğini ama saklanmadığını anlatan tek ipucu.
+      if (cacheable && !leaked) {
+        res.setHeader(
+          getConfig().brand.cacheHeader,
+          result.cached ? (result.stale ? "STALE" : "HIT") : "MISS",
+        );
+      }
+
       if (publicCache) {
         res.setHeader(
           "Cache-Control",
           `public, max-age=0, s-maxage=${revalidate}, stale-while-revalidate=60`,
         );
-        res.setHeader(
-          getConfig().brand.cacheHeader,
-          result.cached ? (result.stale ? "STALE" : "HIT") : "MISS",
-        );
       } else {
         res.setHeader("Cache-Control", PRIVATE_CACHE);
         // Anahtarında cookie olmayan bir cache'in bu yanıtı paylaşmasını
@@ -459,7 +474,7 @@ async function sendHtml(req, res, body, encoded, options = {}) {
  * @param {Function} controller
  * @param {{ pathname: string }} ctx
  * @returns {Promise<{ html: string, status: number, degraded?: boolean,
- *   storable?: boolean }>}
+ *   storable?: boolean, retryAfter?: number }>}
  */
 async function produce(controller, ctx) {
   try {
@@ -475,12 +490,39 @@ async function produce(controller, ctx) {
     };
   } 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 { html: await renderNotFound(), status: 404 };
     }
     throw error;
   }
 }
 
+/**
+ * Geçici bir upstream hatası yüzünden üretilemeyen sayfanın `Retry-After`
+ * değeri. Kısa tutuluyor: ziyaretçi de bot da birkaç saniye sonra gerçek
+ * içeriği bulabilsin.
+ */
+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]);
 
@@ -506,28 +548,39 @@ function hasUpstreamFailures(pathname) {
   const failures = getUpstreamFailures();
   if (!failures.length) return false;
 
-  /** @param {typeof failures} list */
-  const summarize = (list) =>
-    list.map((failure) => `${failure.status} ${failure.path}`).join(", ");
-
   const transient = failures.filter((failure) => isTransient(failure.status));
   const permanent = failures.filter((failure) => !isTransient(failure.status));
 
   if (permanent.length) {
     console.warn(
-      `[render] ${pathname} was produced with missing data, upstream is failing permanently (${summarize(permanent)})`,
+      `[render] ${pathname} was produced with missing data, upstream is failing permanently (${summarizeFailures(permanent)})`,
     );
   }
 
   if (!transient.length) return false;
 
   console.warn(
-    `[render] ${pathname} was produced with missing data, not caching it (${summarize(transient)})`,
+    `[render] ${pathname} was produced with missing data, not caching it (${summarizeFailures(transient)})`,
   );
 
   return true;
 }
 
+/**
+ * @returns {import('./upstream-tracking.js').UpstreamFailure[]}
+ */
+function transientUpstreamFailures() {
+  return getUpstreamFailures().filter((failure) => isTransient(failure.status));
+}
+
+/**
+ * @param {import('./upstream-tracking.js').UpstreamFailure[]} failures
+ * @returns {string}
+ */
+function summarizeFailures(failures) {
+  return failures.map((failure) => `${failure.status} ${failure.path}`).join(", ");
+}
+
 /**
  * 404 sayfası. `renderStatusPage(404)` için kısayol; route dosyalarında en sık
  * ihtiyaç duyulan durum bu olduğu için ayrı bir ad taşımaya devam ediyor.