jskelet 0.2.0 → 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

@@ -20,7 +20,11 @@
  */
 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;
@@ -45,11 +49,13 @@ export const prewarmProgress = {
 };
 
 /**
- * Isıtma turu sırasında bastırılan istek hataları: mesaj → kaç kez görüldü.
+ * Isıtma turu sırasında bastırılan uyarılar: mesaj → kaç kez görüldü.
  *
  * Yüzlerce yolu tarayan bir tur, upstream bir an için tıksırdığında yüzlerce
- * yığın izini loga döküyor ve asıl bilgi (kaç sayfa ısındı) kayboluyor. Tur
- * boyunca hatalar burada toplanır, tur bitince tek satırda özetlenir.
+ * satır loga döküyor ve asıl bilgi (kaç sayfa ısındı) kayboluyor. Tur boyunca
+ * mesajlar burada toplanır, tur bitince tek satırda özetlenir. Yol adı
+ * anahtara girmez: gruplanabilmesi için mesajın kendisi yeterli, tek bir yolun
+ * ayrıntısı zaten `entries` üzerinden dev panelinde görünüyor.
  * @type {Map<string, number>}
  */
 const suppressed = new Map();
@@ -59,19 +65,41 @@ const suppressed = new Map();
  * ısıtmanın user-agent'ıyla geldiğinde doğru; gerçek trafiğin hataları her
  * zaman loglanmaya devam eder.
  *
- * @param {{ get?: (name: string) => string | undefined }} req
+ * @param {{ get?: (name: string) => string | undefined } | null | undefined} req
  * @returns {boolean}
  */
 export function isPrewarmRequest(req) {
-  if (!prewarmProgress.active) return false;
+  if (!prewarmProgress.active || !req) return false;
   const ua = req.get?.("user-agent");
   return Boolean(ua) && ua === getConfig().brand.prewarmUserAgent;
 }
 
 /**
- * Bastırılan bir hatayı sayaca ekler. Yığın izi saklanmaz: özet satırının
- * amacı "neyin bozulduğunu" göstermek, hatayı ayıklamak değil — tek bir yol
- * için ayrıntı isteyen dev paneli `entries` üzerinden bakar.
+ * Şu an işlenen istek ısıtma turuna mı ait? `req` elde olmayan derin
+ * katmanlar (render, cache) için: yanıt nesnesi istek bağlamında taşınıyor.
+ *
+ * @returns {boolean}
+ */
+function inPrewarmRequest() {
+  if (!prewarmProgress.active) return false;
+  return isPrewarmRequest(getRequestContext()?.res?.req);
+}
+
+/**
+ * Isıtma turuna ait bir uyarıyı loglamak yerine sayar.
+ *
+ * @param {string} message Gruplama anahtarı; yol adı içermemeli.
+ * @returns {boolean} `true` ise sayıldı, çağıran taraf loglamamalı.
+ */
+export function suppressForPrewarm(message) {
+  if (!inPrewarmRequest()) return false;
+  suppressed.set(message, (suppressed.get(message) ?? 0) + 1);
+  return true;
+}
+
+/**
+ * Bastırılan bir istek hatasını sayaca ekler. Yığın izi saklanmaz: özet
+ * satırının amacı "neyin bozulduğunu" göstermek, hatayı ayıklamak değil.
  *
  * @param {number} status
  * @param {unknown} error
@@ -241,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();
@@ -250,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) {
@@ -276,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({
@@ -289,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,
@@ -314,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` : ""})`
+  );
 }
 
 /**
@@ -367,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,
@@ -384,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.
@@ -425,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.
@@ -439,7 +543,7 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
       const total = ranked.reduce((sum, [, n]) => sum + n, 0);
 
       console.warn(
-        `[prewarm] ${total} request error${total === 1 ? "" : "s"} were not logged individually:\n` +
+        `[prewarm] ${total} problem${total === 1 ? " was" : "s were"} not logged individually:\n` +
           shown.map(([message, n]) => `  ${n}× ${message}`).join("\n") +
           (rest ? `\n  … ${rest} more in ${ranked.length - shown.length} other kinds` : ""),
       );

package/src/server/render.js

@@ -39,6 +39,7 @@ import * as html from "../views/helpers/html.js";
 import * as tags from "../views/helpers/tags.js";
 import { loadComponents } from "../views/components/loader.js";
 import { renderStatusPage } from "./status-page.js";
+import { suppressForPrewarm } from "./prewarm.js";
 
 const isDev = process.env.NODE_ENV === "development";
 
@@ -530,10 +531,12 @@ async function produce(controller, ctx) {
   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})`,
-    );
+    const retryDetail =
+      `returned notFound() while upstream is failing ` +
+      `(${summarizeFailures(failures)}), retrying (${round}/${attempts})`;
+    if (!suppressForPrewarm(retryDetail)) {
+      console.warn(`[render] ${ctx.pathname} ${retryDetail}`);
+    }
 
     // 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
@@ -558,10 +561,12 @@ async function produce(controller, ctx) {
 
   // 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`,
-  );
+  const outageDetail =
+    `could not be produced, upstream is still failing ` +
+    `(${summarizeFailures(failures)}), serving an uncached 503 instead of a 404`;
+  if (!suppressForPrewarm(outageDetail)) {
+    console.warn(`[render] ${ctx.pathname} ${outageDetail}`);
+  }
 
   return {
     html: await renderStatusPage(503),
@@ -624,17 +629,22 @@ function hasUpstreamFailures(pathname) {
   const transient = failures.filter((failure) => isTransientStatus(failure.status));
   const permanent = failures.filter((failure) => !isTransientStatus(failure.status));
 
+  // Isıtma turu yüzlerce yolu tarıyor; aynı upstream arızası her yol için bir
+  // satır basınca tur özeti kayboluyor. Turun uyarıları sayılıp sonunda
+  // toplanır (bkz. `suppressForPrewarm`).
   if (permanent.length) {
-    console.warn(
-      `[render] ${pathname} was produced with missing data, upstream is failing permanently (${summarizeFailures(permanent)})`,
-    );
+    const detail = `missing data, upstream is failing permanently (${summarizeFailures(permanent)})`;
+    if (!suppressForPrewarm(detail)) {
+      console.warn(`[render] ${pathname} was produced with ${detail}`);
+    }
   }
 
   if (!transient.length) return false;
 
-  console.warn(
-    `[render] ${pathname} was produced with missing data, not caching it (${summarizeFailures(transient)})`,
-  );
+  const detail = `missing data, not caching it (${summarizeFailures(transient)})`;
+  if (!suppressForPrewarm(detail)) {
+    console.warn(`[render] ${pathname} was produced with ${detail}`);
+  }
 
   return true;
 }