jskelet 0.2.1 → 0.2.2

package/src/server/dev/report.js

@@ -13,8 +13,9 @@ 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 { getDataCacheSize, getDataCacheStats } from "../data-cache.js";
 import { getRedisStatus } from "../redis.js";
+import { getUpstreamLimiterStatus } from "../upstream-limiter.js";
 import { prewarmProgress } from "../prewarm.js";
 import { getConfig } from "../../config/index.js";
 
@@ -351,10 +352,16 @@ export function buildReport(devtools) {
       // 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(),
+      // Sayaçlar dökümün yerine geçmiyor, onu tamamlıyor: "kaç girdi var"
+      // sorusundan çok "kaç okuma upstream'e gitti" sorusu karar veriyor.
+      dataStats: getDataCacheStats(),
       // Paylaşımlı kademe kapalıyken de basılır: "Redis'i açtım ama neden
       // çalışmıyor" sorusunun cevabı en çok burada aranıyor.
       redis: getRedisStatus(),
     },
+    // Hız freninin o anki durumu. 429 fırtınasında "şu an saniyede kaça
+    // indi" bilgisi olmadan ayar yapmak körlemesine oluyor.
+    upstream: getUpstreamLimiterStatus(),
     prewarm: { ...prewarmProgress },
     requests: devtools.requests,
     errors: devtools.errors,

package/src/server/html-cache.js

@@ -686,6 +686,11 @@ onCacheEvent((event) => {
     return;
   }
 
+  if (event.type === "html:drop") {
+    if (typeof event.key === "string") dropLocalKey(event.key);
+    return;
+  }
+
   if (event.type !== "html:invalidate") return;
 
   const targets = /** @type {(string | RegExp)[]} */ (
@@ -742,6 +747,37 @@ export function invalidateHtmlByDependency(dataKeys) {
   return keys.size;
 }
 
+/**
+ * Tek bir önbellek **anahtarını** düşürür.
+ *
+ * `invalidateHtmlCache()` yol deseniyle çalışıyor ve bir yolun bütün query
+ * varyantlarını birlikte düşürüyor. Yönetim paneli listedeki tek satırı
+ * silebilmek istiyor: `/liste?sayfa=2` düşerken `/liste?sayfa=3` sıcak
+ * kalmalı. Desen sözdiziminde `?` kaçırılamadığı için ayrı bir yüzey.
+ *
+ * @param {string} key `yol?query` biçiminde tam anahtar.
+ * @returns {boolean} Girdi var mıydı.
+ */
+export function dropHtmlCacheKey(key) {
+  const existed = dropLocalKey(key);
+
+  if (redisShares("html")) redisDrop([cacheKey("html", key)]);
+  publishCacheEvent({ type: "html:drop", key });
+
+  return existed;
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function dropLocalKey(key) {
+  // Uçuştaki tazeleme de geçersiz: silinen girdiyi geri yazmamalı.
+  tokens.delete(key);
+  invalidated.delete(key);
+  return drop(key);
+}
+
 /**
  * Invalidate edilmiş ve henüz kimsenin istemediği yolları döner ve kuyruğu
  * boşaltır. Isıtma turu bunları başa alır; iki tur aynı yolu tekrar

package/src/server/prewarm.js

@@ -22,6 +22,9 @@ import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
 import { getRequestContext } from "../http/request-context.js";
 import { takeInvalidatedPaths } from "./html-cache.js";
+import { getDataCacheStats } from "./data-cache.js";
+import { isTransientStatus } from "./upstream-tracking.js";
+import { upstreamCooldownMs } from "./upstream-limiter.js";
 
 /**
  * Isıtmanın canlı durumu. Dev araçları bunu okuyup ilerlemeyi gösterir;
@@ -266,7 +269,10 @@ function devGateHeader() {
  *   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[] }>}
+ * @returns {Promise<{ ok: number, failed: number,
+ *   failures: { path: string, status: number }[] }>}
+ *   `failures` durum koduyla birlikte döner: tekrar turuna yalnızca geçici
+ *   hatalar alınıyor, kalıcı olanı yeniden denemek boşa çağrı.
  */
 async function crawl(origin, paths, concurrency, report = undefined, pace = undefined) {
   const { brand } = getConfig();
@@ -275,8 +281,8 @@ async function crawl(origin, paths, concurrency, report = undefined, pace = unde
   let index = 0;
   let ok = 0;
   let failed = 0;
-  /** @type {string[]} */
-  const failedPaths = [];
+  /** @type {{ path: string, status: number }[]} */
+  const failures = [];
 
   async function worker() {
     while (index < paths.length) {
@@ -301,7 +307,7 @@ async function crawl(origin, paths, concurrency, report = undefined, pace = unde
         if (response.ok) ok += 1;
         else {
           failed += 1;
-          failedPaths.push(target);
+          failures.push({ path: target, status: response.status });
         }
 
         prewarmProgress.entries.push({
@@ -314,7 +320,8 @@ async function crawl(origin, paths, concurrency, report = undefined, pace = unde
         });
       } catch (error) {
         failed += 1;
-        failedPaths.push(target);
+        // Yanıt hiç gelmedi: ağ hatası her zaman geçici, tekrar denenir.
+        failures.push({ path: target, status: 0 });
         prewarmProgress.entries.push({
           path: target,
           status: 0,
@@ -339,7 +346,66 @@ async function crawl(origin, paths, concurrency, report = undefined, pace = unde
     Array.from({ length: Math.min(concurrency, paths.length) }, worker),
   );
 
-  return { ok, failed, failedPaths };
+  return { ok, failed, failures };
+}
+
+/**
+ * Tekrar turuna girecek yollar. Yalnızca geçici hatalar: `400`/`403`/`404` gibi
+ * deterministik cevaplar tekrar denemekle düzelmez ve o çağrılar kotadan
+ * karşılıksız yiyor. Sınıflandırma render tarafıyla aynı listeden
+ * (`isTransientStatus`), yoksa iki yer birbirinden kayar.
+ *
+ * @param {{ path: string, status: number }[]} failures
+ * @returns {string[]}
+ */
+function retryablePaths(failures) {
+  return failures
+    .filter((failure) => isTransientStatus(failure.status))
+    .map((failure) => failure.path);
+}
+
+/**
+ * Tekrar turundan önce beklenecek süre.
+ *
+ * Sabit bekleme yanlış soruyu cevaplıyordu: doğru süreyi upstream biliyor.
+ * Hız freni açıkken `Retry-After` ya da devre kesicinin soğuma süresi zaten
+ * elimizde; 10 saniye kapalı kalacak bir kesiciden 2 saniye sonra tekrar
+ * denemek, aynı 429'u peşin peşin almak demek.
+ *
+ * @returns {number} ms
+ */
+function retryDelayMs() {
+  const configured = setting("PREWARM_RETRY_DELAY_MS", "retryDelayMs", 2000);
+  const cooldown = upstreamCooldownMs();
+
+  // Fren kapalıysa `cooldown` 0 olur ve davranış eskisi gibi kalır. Üst sınır
+  // turun sonsuza kadar açık kalmasını engelliyor.
+  return Math.min(Math.max(configured, cooldown), 60_000);
+}
+
+/**
+ * Turun veri önbelleği üzerinden upstream'e ne kadar dokunduğunu özetler.
+ *
+ * @param {ReturnType<typeof getDataCacheStats>} before Tur başındaki sayaçlar.
+ * @returns {string} Okunacak bir şey yoksa boş dize.
+ */
+function upstreamUsage(before) {
+  const after = getDataCacheStats();
+  const reads = after.reads - before.reads;
+  if (reads <= 0) return "";
+
+  const produced = after.produced - before.produced;
+  const coalesced = after.coalesced - before.coalesced;
+  const shared = after.shared - before.shared;
+  const served = reads - produced;
+  const ratio = Math.round((served / reads) * 100);
+
+  return (
+    `${produced} upstream call${produced === 1 ? "" : "s"} for ${reads} data read${reads === 1 ? "" : "s"} ` +
+    `(${ratio}% from the data cache` +
+    `${coalesced ? `, ${coalesced} coalesced` : ""}` +
+    `${shared ? `, ${shared} from the shared tier` : ""})`
+  );
 }
 
 /**
@@ -392,13 +458,18 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
   });
   suppressed.clear();
 
+  // Kotanın gerçekten ne kadar harcandığı ancak veri önbelleğinden görülür:
+  // 400 sayfalık bir tur, ortak bir uç için tek çağrı da yapabilir dört yüz de.
+  const dataBefore = getDataCacheStats();
+
   let ok = 0;
   let failed = 0;
   let recovered = 0;
+  let skippedRetry = 0;
   try {
-    /** @type {string[]} */
-    let failedPaths;
-    ({ ok, failed, failedPaths } = await crawl(
+    /** @type {{ path: string, status: number }[]} */
+    let failures;
+    ({ ok, failed, failures } = await crawl(
       origin,
       paths,
       concurrency,
@@ -409,18 +480,18 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
     // 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
     // önbelleğe girmesini sağlıyor; aksi hâlde ziyaretçi soğuk render'ı öder.
-    if (failedPaths.length) {
+    const retryPaths = retryablePaths(failures);
+    skippedRetry = failures.length - retryPaths.length;
+
+    if (retryPaths.length) {
       const firstOk = ok;
       const firstFailed = failed;
 
-      // 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);
+      await sleep(retryDelayMs());
 
       const retry = await crawl(
         origin,
-        failedPaths,
+        retryPaths,
         1,
         (retriedOk) => {
           // Tekrar turunda her başarı bir hatayı başarıya çevirir.
@@ -450,10 +521,18 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
         `${pending.length ? `, ${pending.length} invalidated` : ""}` +
         `${failed ? `, ${failed} failed` : ""}` +
         `${recovered ? `, ${recovered} recovered on the retry pass` : ""}` +
+        `${skippedRetry ? `, ${skippedRetry} not retried (permanent)` : ""}` +
         `${skipped > 0 ? `, ${skipped} ${rotate ? "deferred to the next pass" : "over the limit"}` : ""}` +
         ` (${(elapsed / 1000).toFixed(1)}s)`,
     );
 
+    // Turun upstream'e ne kadar dokunduğu. Asıl karar bu satıra bakılarak
+    // veriliyor: 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.
+    const upstreamCalls = upstreamUsage(dataBefore);
+    if (upstreamCalls) console.log(`[prewarm] ${upstreamCalls}`);
+
     // Tur boyunca bastırılan hatalar: en sık görülenler önce, liste uzarsa
     // kalanı tek satırda toplanır. Amaç, logu şişirmeden "ne bozuldu"yu
     // görünür tutmak.

package/src/server/upstream-limiter.js

@@ -0,0 +1,376 @@
+/**
+ * Upstream API'ye giden isteklerin host başına hız freni.
+ *
+ * Isıtma turundaki `rps` ayarı bu işi yapamıyordu: o, kendi sunucumuza atılan
+ * **sayfa** isteklerini sayıyor. 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ı. Bu
+ * yüzden fren `trackUpstreamFetch()` sarmalayıcısına, yani gerçek çağrının
+ * geçtiği yere konuyor — ısıtma da, gerçek trafik de aynı bütçeden harcar.
+ *
+ * Üç mekanizma birlikte çalışıyor, çünkü üç farklı şeyi sınırlıyorlar:
+ *
+ *   token bucket → ortalama hız (saniyedeki çağrı)
+ *   concurrency  → anlık baskı (aynı anda uçan çağrı)
+ *   AIMD         → doğru hızın ne olduğu
+ *
+ * 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. 429 geldiğinde hızı
+ * yarıya indirip (çarpımsal azalma) temiz geçen her pencerede bir adım geri
+ * çıkmak (toplamsal artış), sınırı elle ayar yapılmadan bulur.
+ *
+ * Devre kesici de aynı gerekçeyle var: 429 geçici sayıldığı için o çağrıyla
+ * üretilen HTML önbelleğe **yazılmıyor**. Yani rate limit'e girmiş bir turda
+ * kota harcanır ve karşılığında hiçbir şey saklanmaz. Art arda 429 alan bir
+ * host'a bir süre hiç gitmemek, o boşa yanmayı kesiyor.
+ *
+ * Varsayılan **kapalı**: `rate` verilmedikçe hiçbir istek beklemez. Framework
+ * mevcut kurulumların davranışını sessizce değiştirmez.
+ */
+import { DEFAULT_UPSTREAM_LIMIT } from "../config/defaults.js";
+
+/**
+ * @typedef {object} HostState
+ * @property {string} host
+ * @property {number} maxRate Config'te verilen tavan; AIMD bunun üstüne çıkmaz.
+ * @property {number} minRate Azalmanın dibi; 0'a inip tamamen kilitlenmesin.
+ * @property {number} rate Saniyedeki izin — AIMD bunu oynatır.
+ * @property {number} burst Kovanın boyu: kısa patlamalara verilen tolerans.
+ * @property {number} concurrency Aynı anda uçabilecek çağrı sayısı.
+ * @property {number} tokens
+ * @property {number} refilledAt
+ * @property {number} active Uçuştaki çağrı.
+ * @property {(() => void)[]} waiters Boş yuva bekleyenler.
+ * @property {Promise<void>} chain Admission sırası (FIFO).
+ * @property {number} blockedUntil `Retry-After` boyunca kova tamamen durur.
+ * @property {number} consecutiveFailures
+ * @property {number} bypassUntil Devre kesicinin açık kaldığı an.
+ * @property {number} adjustedAt Son AIMD kararının zamanı.
+ * @property {number} throttled Kaç kez 429/503 görüldü (teşhis için).
+ * @property {number} rejected Devre kesici kaç çağrıyı hiç göndermedi.
+ */
+
+/** @type {Map<string, HostState>} */
+const hosts = new Map();
+
+/** @type {typeof DEFAULT_UPSTREAM_LIMIT} */
+let settings = { ...DEFAULT_UPSTREAM_LIMIT };
+
+/**
+ * `createApp()` config yüklendikten sonra bir kez çağırır. Ayar değiştiğinde
+ * host durumları sıfırlanır: eski `maxRate`'e göre ayarlanmış bir `rate`
+ * yeni tavanın üstünde kalabilir.
+ *
+ * @param {Record<string, unknown> | undefined} config `cache().upstream`
+ * @returns {void}
+ */
+export function configureUpstreamLimiter(config) {
+  settings = { ...DEFAULT_UPSTREAM_LIMIT, ...(config ?? {}) };
+  hosts.clear();
+}
+
+/** @returns {boolean} */
+function enabled() {
+  return settings.rate > 0 || hostOverrides().length > 0;
+}
+
+/** @returns {[string, Record<string, number>][]} */
+function hostOverrides() {
+  const raw = /** @type {Record<string, any>} */ (settings.hosts ?? {});
+  return Object.entries(raw);
+}
+
+/**
+ * @param {string} url
+ * @returns {string | null} Host, ya da URL çözülemediyse `null`.
+ */
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} host
+ * @returns {HostState}
+ */
+function stateFor(host) {
+  const existing = hosts.get(host);
+  if (existing) return existing;
+
+  const override = /** @type {Record<string, any>} */ (settings.hosts ?? {})[host] ?? {};
+  const merged = { ...settings, ...override };
+  const rate = num(merged.rate, 0);
+
+  /** @type {HostState} */
+  const created = {
+    host,
+    maxRate: rate,
+    minRate: Math.min(num(merged.minRate, DEFAULT_UPSTREAM_LIMIT.minRate), rate || 1),
+    rate: rate,
+    // Kova boyu verilmezse bir saniyelik bütçe: hız 4/s ise dört çağrılık bir
+    // patlama tolere edilir, beşincisi bekler.
+    burst: num(merged.burst, 0) || Math.max(1, Math.ceil(rate)),
+    concurrency: Math.floor(num(merged.concurrency, DEFAULT_UPSTREAM_LIMIT.concurrency)),
+    tokens: num(merged.burst, 0) || Math.max(1, Math.ceil(rate)),
+    refilledAt: Date.now(),
+    active: 0,
+    waiters: [],
+    chain: Promise.resolve(),
+    blockedUntil: 0,
+    consecutiveFailures: 0,
+    bypassUntil: 0,
+    // 0, `Date.now()` değil: ilk saniye içinde gelen bir 429 de hızı
+    // düşürmeli. Aksi hâlde ısıtma turunun ilk patlaması cezasız kalıyor.
+    adjustedAt: 0,
+    throttled: 0,
+    rejected: 0,
+  };
+
+  hosts.set(host, created);
+  return created;
+}
+
+/** @param {unknown} value @param {number} fallback */
+function num(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
+}
+
+/**
+ * Geçen süreye göre kovayı doldurur ve hata görülmeyen pencereler için hızı
+ * bir adım yukarı çeker. İkisi aynı yerde: her ikisi de "zaman geçti" bilgisine
+ * dayanıyor ve zamanlayıcı kurmadan, çağrı anında hesaplanıyorlar — boşta duran
+ * bir süreç için sayaç işletmenin anlamı yok.
+ *
+ * @param {HostState} state
+ * @returns {void}
+ */
+function refill(state) {
+  const now = Date.now();
+  const elapsed = now - state.refilledAt;
+
+  if (elapsed > 0) {
+    state.tokens = Math.min(state.burst, state.tokens + (elapsed * state.rate) / 1000);
+    state.refilledAt = now;
+  }
+
+  if (state.rate >= state.maxRate) return;
+  if (now - state.adjustedAt < settings.increaseIntervalMs) return;
+
+  // Toplamsal artış: azalma yarıya indiriyor, geri çıkış adım adım. Ters
+  // olsaydı (hızlı çık, yavaş in) her pencerede yeniden 429 yerdik.
+  state.rate = Math.min(state.maxRate, state.rate + num(settings.increaseStep, 1));
+  state.adjustedAt = now;
+}
+
+/**
+ * @param {HostState} state
+ * @returns {number} Kaç ms sonra tekrar denenmeli; 0 → yuva hazır.
+ */
+function waitFor(state) {
+  const now = Date.now();
+  if (state.blockedUntil > now) return state.blockedUntil - now;
+
+  refill(state);
+  if (state.tokens >= 1) return 0;
+
+  // Bir tokenlik eksiğin dolması için gereken süre. `rate` düşükken bu
+  // saniyeler olabilir; beklemek doğru davranış — alternatifi 429.
+  return Math.max(10, Math.ceil(((1 - state.tokens) / state.rate) * 1000));
+}
+
+/**
+ * Boş bir eşzamanlılık yuvası bekler.
+ *
+ * @param {HostState} state
+ * @returns {Promise<void>}
+ */
+function waitForSlot(state) {
+  if (state.active < state.concurrency) return Promise.resolve();
+  return new Promise((resolve) => state.waiters.push(resolve));
+}
+
+/**
+ * Çağrı için izin alır. `null` dönerse fren kapalı ya da host çözülemedi;
+ * `blocked` dönerse devre kesici açık ve çağrı hiç yapılmamalı.
+ *
+ * @param {string} url
+ * @returns {Promise<{ blocked: boolean, host: string, release: () => void } | null>}
+ */
+export async function limitUpstream(url) {
+  if (!enabled()) return null;
+
+  const host = hostOf(url);
+  if (!host) return null;
+
+  const state = stateFor(host);
+  if (!state.maxRate) return null;
+
+  if (state.bypassUntil > Date.now()) {
+    state.rejected += 1;
+    return { blocked: true, host, release: () => {} };
+  }
+
+  // Admission FIFO: her çağrı kendinden öncekinin izin almasını bekler. Sıra
+  // olmadan, uyanan çağrılar rastgele yarışır ve ilk gelen en son geçebilir.
+  const previous = state.chain;
+  /** @type {() => void} */
+  let releaseChain = () => {};
+  state.chain = new Promise((resolve) => {
+    releaseChain = resolve;
+  });
+
+  try {
+    await previous;
+
+    for (;;) {
+      await waitForSlot(state);
+      const wait = waitFor(state);
+      if (wait === 0) break;
+      await sleep(wait);
+    }
+
+    state.tokens -= 1;
+    state.active += 1;
+  } finally {
+    releaseChain();
+  }
+
+  let released = false;
+  return {
+    blocked: false,
+    host,
+    release: () => {
+      if (released) return;
+      released = true;
+      state.active -= 1;
+      state.waiters.shift()?.();
+    },
+  };
+}
+
+/**
+ * Yanıtın hıza etkisini işler. 429/503 hızı yarıya indirir ve `Retry-After`
+ * varsa kovayı o süre boyunca tamamen durdurur; başarı sayaçları sıfırlar.
+ *
+ * @param {string} host
+ * @param {number} status `0` → ağ hatası (yanıt gelmedi).
+ * @param {string | null} [retryAfter] `Retry-After` başlığı.
+ * @returns {void}
+ */
+export function noteUpstreamResponse(host, status, retryAfter = null) {
+  const state = hosts.get(host);
+  if (!state) return;
+
+  // Yalnızca "yavaşla" anlamına gelen cevaplar hızı cezalandırı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.
+  if (status !== 429 && status !== 503) {
+    state.consecutiveFailures = 0;
+    return;
+  }
+
+  state.throttled += 1;
+  state.consecutiveFailures += 1;
+
+  const now = Date.now();
+  const cooldown = retryAfterMs(retryAfter);
+  if (cooldown) state.blockedUntil = Math.max(state.blockedUntil, now + cooldown);
+
+  // Çarpımsal azalma, ama pencere başına bir kez: aynı anda uçan on çağrı
+  // hep 429 dönerse hız on kez yarılanıp dibe vururdu.
+  if (now - state.adjustedAt >= settings.decreaseIntervalMs) {
+    state.rate = Math.max(state.minRate, state.rate / 2);
+    state.adjustedAt = now;
+  }
+
+  if (
+    state.consecutiveFailures >= settings.breakerFailures &&
+    state.bypassUntil <= now
+  ) {
+    state.bypassUntil = now + settings.breakerCooldownMs;
+    console.warn(
+      `[upstream] ${state.host}: ${state.consecutiveFailures} consecutive rate limits — ` +
+        `bypassing for ${settings.breakerCooldownMs}ms (rate is now ${state.rate.toFixed(1)}/s)`,
+    );
+  }
+}
+
+/**
+ * `Retry-After` iki biçimde gelir: saniye ya da HTTP tarihi.
+ *
+ * @param {string | null | undefined} value
+ * @returns {number} ms; okunamazsa 0.
+ */
+function retryAfterMs(value) {
+  if (!value) return 0;
+
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, 300_000);
+
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return 0;
+
+  return Math.min(Math.max(0, date - Date.now()), 300_000);
+}
+
+/**
+ * Dev paneli ve teşhis için host başına durum. Fren kapalıysa boş dizi.
+ *
+ * @returns {{ host: string, rate: number, maxRate: number, concurrency: number,
+ *   active: number, throttled: number, rejected: number, bypassed: boolean,
+ *   blockedMs: number, bypassedMs: number }[]}
+ */
+export function getUpstreamLimiterStatus() {
+  const now = Date.now();
+
+  return [...hosts.values()].map((state) => ({
+    host: state.host,
+    rate: Number(state.rate.toFixed(2)),
+    maxRate: state.maxRate,
+    concurrency: state.concurrency,
+    active: state.active,
+    throttled: state.throttled,
+    rejected: state.rejected,
+    bypassed: state.bypassUntil > now,
+    blockedMs: Math.max(0, state.blockedUntil - now),
+    bypassedMs: Math.max(0, state.bypassUntil - now),
+  }));
+}
+
+/**
+ * Freni bekleten en uzun süre. Isıtma turunun tekrar denemesi bunu kullanıyor:
+ * sabit bir bekleme, kesici 10 saniye açıkken 2 saniye sonra tekrar denemek
+ * demekti — yani aynı 429'u peşin peşin almak.
+ *
+ * @returns {number} ms; fren kapalıysa ya da bekleyen bir şey yoksa 0.
+ */
+export function upstreamCooldownMs() {
+  const now = Date.now();
+  let longest = 0;
+
+  for (const state of hosts.values()) {
+    longest = Math.max(longest, state.bypassUntil - now, state.blockedUntil - now);
+  }
+
+  return Math.max(0, longest);
+}
+
+/**
+ * Testler için: ayarları verip tüm host durumlarını sıfırlar.
+ *
+ * @param {Record<string, unknown>} [config]
+ * @returns {void}
+ */
+export function resetUpstreamLimiterForTests(config = {}) {
+  configureUpstreamLimiter(config);
+}

package/src/server/upstream-tracking.js

@@ -20,8 +20,13 @@
  *        }
  *
  * İki yol aynı hatayı bildirirse tekilleştirilir.
+ *
+ * Sarmalayıcı aynı zamanda hız freninin durduğu yerdir
+ * (`upstream-limiter.js`): kotayı harcayan şey sayfa isteği değil, buradan
+ * geçen çağrı. Fren varsayılan olarak kapalı.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { limitUpstream, noteUpstreamResponse } from "./upstream-limiter.js";
 
 /**
  * @typedef {{ status: number, path: string }} UpstreamFailure
@@ -94,16 +99,36 @@ export function trackUpstreamFetch() {
     const url = requestUrl(input);
     if (isSelfRequest(url)) return original(input, init);
 
+    // Hız freni burada, çünkü kotayı harcayan şey sayfa değil bu çağrı.
+    // Kapalıysa (varsayılan) `null` döner ve tek maliyeti bir dal.
+    const permit = await limitUpstream(url);
+
+    if (permit?.blocked) {
+      // Devre kesici açık: 429 yiyeceğini bildiğimiz bir çağrıyı yapmıyoruz.
+      // Render tarafı bunu geçici hata olarak görür, yani sayfa önbelleğe
+      // yazılmaz ve bir sonraki istek yeniden dener.
+      reportUpstreamFailure({ status: 429, path: url });
+      return new Response(null, { status: 429, statusText: "Too Many Requests" });
+    }
+
     try {
       const response = await original(input, init);
+
+      if (permit) {
+        noteUpstreamResponse(permit.host, response.status, response.headers.get("retry-after"));
+      }
+
       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.
+      if (permit) noteUpstreamResponse(permit.host, 0, null);
       reportUpstreamFailure({ status: 0, path: url });
       throw error;
+    } finally {
+      permit?.release();
     }
   };