jskelet 0.2.1 → 0.2.3

package/src/server/data-cache.js

@@ -47,6 +47,31 @@ const store = new Map();
 /** @type {Map<string, Promise<unknown>>} */
 const inflight = new Map();
 
+/**
+ * Süreç ömrü boyunca biriken sayaçlar.
+ *
+ * Isıtma turunun kotayı ne kadar harcadığı ancak buradan görülüyor: tur
+ * bittiğinde `produced` kaç gerçek upstream çağrısı yapıldığını, `hits` kaçının
+ * hiç gitmediğini söyler. Oran düşükse çözüm hız freni değil, TTL'i uzatmak —
+ * fren çağrıları yavaşlatır, sayısını azaltmaz.
+ */
+const stats = {
+  /** Taze girdiden servis edildi. */
+  hits: 0,
+  /** Bayat girdiden servis edildi; tazeleme arkada koştu. */
+  stale: 0,
+  /** Girdi yoktu, çağıran bekledi. */
+  misses: 0,
+  /** Aynı anahtarı eşzamanlı isteyen çağrılar tek üretime düştü. */
+  coalesced: 0,
+  /** Paylaşımlı kademeden geldi; upstream'e gitmedi. */
+  shared: 0,
+  /** `producer` gerçekten çalıştı — kotaya yazılan tek sayı. */
+  produced: 0,
+  /** `ttlSeconds: 0` ile önbellek tamamen atlandı. */
+  bypassed: 0,
+};
+
 /**
  * Ayarlar config'ten okunur ama config yüklenmemiş olabilir: bu modül
  * script'lerden ve testlerden de çağrılabiliyor. `getConfig()` fırlatırsa
@@ -171,7 +196,10 @@ 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;
+  if (pending) {
+    stats.coalesced += 1;
+    return pending;
+  }
 
   const staleFactor = options.staleFactor ?? settings().staleFactor;
 
@@ -196,10 +224,12 @@ async function produce(key, ttlSeconds, producer, options, staleFactor) {
   // Kotayı koruyan `inflight` birleştirmesinin küme çapındaki karşılığı bu.
   const shared = await readShared(key);
   if (shared) {
+    stats.shared += 1;
     promote(key, shared);
     return shared.value;
   }
 
+  stats.produced += 1;
   const value = await producer();
 
   const empty = value === undefined || value === null;
@@ -224,7 +254,10 @@ async function produce(key, ttlSeconds, producer, options, staleFactor) {
  * @template T
  */
 export async function withDataCache(key, ttlSeconds, producer, options = {}) {
-  if (!ttlSeconds) return producer();
+  if (!ttlSeconds) {
+    stats.bypassed += 1;
+    return producer();
+  }
 
   // Bu anahtarı okuyan render, `clearDataCache(key)` çağrıldığında etkilenen
   // sayfalar arasında sayılsın. Render bağlamı yoksa çağrı no-op.
@@ -233,6 +266,9 @@ export async function withDataCache(key, ttlSeconds, producer, options = {}) {
   const hit = read(key);
 
   if (hit) {
+    if (hit.stale) stats.stale += 1;
+    else stats.hits += 1;
+
     // 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.
@@ -244,6 +280,8 @@ export async function withDataCache(key, ttlSeconds, producer, options = {}) {
     return /** @type {T} */ (hit.value);
   }
 
+  stats.misses += 1;
+
   try {
     return /** @type {T} */ (await refresh(key, ttlSeconds, producer, options));
   } catch (error) {
@@ -346,15 +384,67 @@ function clearLocal(prefix) {
 // Uzak bir node veri düşürdüğünde bu proses de kendi L1'ini temizler; zincir
 // `invalidateHtmlByDependency` üzerinden etkilenen sayfalara kadar gider.
 onCacheEvent((event) => {
+  if (event.type === "data:drop") {
+    if (typeof event.key !== "string") return;
+    store.delete(event.key);
+    invalidateHtmlByDependency([event.key]);
+    return;
+  }
+
   if (event.type !== "data:clear") return;
   clearLocal(typeof event.prefix === "string" ? event.prefix : undefined);
 });
 
+/**
+ * Tek bir veri anahtarını düşürür.
+ *
+ * `clearDataCache()` **önek** eşleştiriyor: `quote:v2:AAPL` verildiğinde
+ * `quote:v2:AAPLX` de düşer. Yönetim panelinde listeden seçilen satır tam
+ * olarak o anahtar olmalı, komşusu değil.
+ *
+ * @param {string} key
+ * @returns {boolean} Girdi var mıydı.
+ */
+export function dropDataCacheKey(key) {
+  const existed = store.delete(key);
+
+  // Silme, girdi bu node'da olmasa da yayılır: anahtar başka bir node'da ya da
+  // yalnızca Redis'te sıcak olabilir.
+  invalidateHtmlByDependency([key]);
+
+  if (redisShares("data")) {
+    void redisDropMatching("data", (candidate) => candidate === key);
+  }
+
+  publishCacheEvent({ type: "data:drop", key });
+
+  return existed;
+}
+
 /** @returns {number} */
 export function getDataCacheSize() {
   return store.size;
 }
 
+/**
+ * Süreç başından beri biriken sayaçlar. `produced` kotaya yazılan tek sayıdır:
+ * geri kalan her şey upstream'e hiç gitmemiş bir okuma.
+ *
+ * @returns {typeof stats & { reads: number, hitRatio: number }}
+ *   `reads` önbellekten geçen toplam okuma, `hitRatio` bunların kaçının
+ *   upstream'e gitmediği (0–1).
+ */
+export function getDataCacheStats() {
+  const reads = stats.hits + stats.stale + stats.misses;
+  const avoided = stats.hits + stats.stale;
+
+  return {
+    ...stats,
+    reads,
+    hitRatio: reads ? Number((avoided / reads).toFixed(3)) : 0,
+  };
+}
+
 /**
  * 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.

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/redis.js

@@ -405,6 +405,114 @@ export function getRedisStatus() {
   };
 }
 
+/**
+ * Bağlantının **nereye** kurulduğu ve hangi ayarlarla çalıştığı.
+ *
+ * Şifre asla dönmez: bağlantı URL'i `redis://user:pass@host` biçiminde
+ * olabiliyor ve panelin işi adresi göstermek, sırrı değil. Ayrıştırılamayan
+ * bir URL için adres `"custom"` olur — bozuk bir değer teşhis ucunu
+ * düşürmemeli.
+ *
+ * @returns {{ address: string, secure: boolean, db: string | null,
+ *   namespace: string, keyPrefix: string, html: boolean, data: boolean,
+ *   storeEncoded: boolean, events: boolean, commandTimeoutMs: number,
+ *   subscribed: boolean }}
+ */
+export function getRedisDetails() {
+  let address = "localhost:6379 (ioredis default)";
+  let secure = false;
+  /** @type {string | null} */
+  let db = null;
+
+  if (settings.url) {
+    try {
+      const parsed = new URL(settings.url);
+      address = `${parsed.hostname}:${parsed.port || 6379}`;
+      secure = parsed.protocol === "rediss:";
+      const name = parsed.pathname.replace(/^\//, "");
+      db = name || null;
+    } catch {
+      address = "custom";
+    }
+  }
+
+  return {
+    address,
+    secure,
+    db,
+    namespace: settings.namespace,
+    keyPrefix: settings.keyPrefix,
+    html: settings.html === true,
+    data: settings.data === true,
+    storeEncoded: settings.storeEncoded === true,
+    events: settings.events === true,
+    commandTimeoutMs: settings.commandTimeoutMs,
+    subscribed: Boolean(subscriber),
+  };
+}
+
+/**
+ * Paylaşımlı kademede gerçekten **ne durduğunu** sayar: tür başına anahtar
+ * sayısı ve sunucunun bildirdiği bellek kullanımı.
+ *
+ * Ayrı bir çağrı olması gerekiyor. Sayım `SCAN` turu demek ve panelin döküm
+ * ucu birkaç saniyede bir yenileniyor; her turda tüm keyspace'i taramak
+ * Redis'i teşhis uğruna yormak olurdu. Panel bunu düğmeye basınca çağırır.
+ *
+ * @returns {Promise<{ ok: boolean, html: number, data: number,
+ *   usedMemory: string | null, totalKeys: number | null }>}
+ */
+export async function inspectRedis() {
+  if (!usable()) return { ok: false, html: 0, data: 0, usedMemory: null, totalKeys: null };
+
+  try {
+    const [html, data] = await Promise.all([count("html"), count("data")]);
+
+    /** @type {string | null} */
+    let usedMemory = null;
+    /** @type {number | null} */
+    let totalKeys = null;
+
+    try {
+      const info = await client.info("memory");
+      usedMemory = /used_memory_human:(\S+)/.exec(String(info))?.[1] ?? null;
+      totalKeys = Number(await client.dbsize());
+    } catch {
+      // `INFO`/`DBSIZE` kısıtlı bir kurulumda (managed Redis) reddedilebilir;
+      // anahtar sayıları yine geçerli.
+    }
+
+    noteSuccess();
+    return { ok: true, html, data, usedMemory, totalKeys };
+  } catch (error) {
+    noteFailure("inspect", error);
+    return { ok: false, html: 0, data: 0, usedMemory: null, totalKeys: null };
+  }
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @returns {Promise<number>}
+ */
+async function count(kind) {
+  let cursor = "0";
+  let total = 0;
+
+  do {
+    const [next, keys] = await client.scan(
+      cursor,
+      "MATCH",
+      `${prefix}:${kind}:*`,
+      "COUNT",
+      500,
+    );
+    cursor = next;
+    total += keys.length;
+  } while (cursor !== "0");
+
+  return total;
+}
+
 /**
  * Bağlantıları kapatır. `SIGTERM` sonrası uçuştaki komutların bitmesi
  * beklenir (`quit`), zorla kesilmez.

package/src/server/render.js

@@ -207,8 +207,13 @@ export function route(controller, options = {}) {
     const revalidate = isPrivate
       ? undefined
       : resolveRevalidate(req.path, options.revalidate);
-    const cacheable = !isPrivate && req.method === "GET" && Boolean(revalidate);
-    const cacheKey = `${req.path}?${new URLSearchParams(
+    // Anahtar `null` ise query bu yol için cache'lenebilir değil: sayfa
+    // dinamik davranır. Anahtar yine de gerekiyor (hata sayfası ölçümü,
+    // teşhis) ama TTL sıfırlanıp cache yolu kapatılır.
+    const key = buildCacheKey(req.path, ctx.query);
+    const cacheable =
+      !isPrivate && req.method === "GET" && Boolean(revalidate) && key !== null;
+    const cacheKey = key ?? `${req.path}?${new URLSearchParams(
       Object.entries(ctx.query).map(([k, v]) => [k, String(v)]),
     ).toString()}`;
 
@@ -409,6 +414,73 @@ const revalidateByPath = new Map();
  */
 const REVALIDATE_CACHE_MAX = 2000;
 
+/**
+ * Aynı gerekçeyle (yakalayıcı route'ta sınırsız büyüme) query kuralı da yol
+ * başına hatırlanır.
+ *
+ * @type {Map<string, true | string[] | null>}
+ */
+const queryPolicyByPath = new Map();
+
+/**
+ * @param {string} pathname
+ * @returns {true | string[] | null} `null`: bu yol için hiçbir parametreye
+ *   izin verilmiyor.
+ */
+function resolveQueryPolicy(pathname) {
+  if (queryPolicyByPath.has(pathname)) {
+    return queryPolicyByPath.get(pathname) ?? null;
+  }
+
+  const rules = getConfig().cacheQuery;
+  const match = rules.find((rule) => matchPattern(rule.pattern, pathname));
+
+  if (queryPolicyByPath.size >= REVALIDATE_CACHE_MAX) {
+    const oldest = queryPolicyByPath.keys().next().value;
+    if (oldest !== undefined) queryPolicyByPath.delete(oldest);
+  }
+
+  const policy = match ? match.allow : null;
+  queryPolicyByPath.set(pathname, policy);
+  return policy;
+}
+
+/**
+ * HTML cache anahtarı, ya da query bu yol için cache'lenebilir değilse `null`.
+ *
+ * Varsayılan olarak query parametresi taşıyan istek dinamiktir: `cache().query`
+ * altında eşleşen bir kural olmadıkça cache'e hiç girmez. Aksi hâlde bir yolun
+ * bütün `?utm_source=…` varyantları ayrı girdi olur ve LRU'daki gerçek
+ * sayfaları dışarı atar.
+ *
+ * İzin verilen parametreler **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı
+ * sayfa olduğu için aynı anahtarı almalı.
+ *
+ * @param {string} pathname
+ * @param {Record<string, unknown>} query
+ * @returns {string | null}
+ */
+function buildCacheKey(pathname, query) {
+  const entries = Object.entries(query);
+  if (!entries.length) return `${pathname}?`;
+
+  const policy = resolveQueryPolicy(pathname);
+  if (policy === null) return null;
+
+  const kept =
+    policy === true ? entries : entries.filter(([name]) => policy.includes(name));
+
+  // İzin listesi dışındaki parametreler anahtara girmez: sayfa cache'lenir ve
+  // bütün kampanya varyantları tek kopyayı paylaşır.
+  const params = new URLSearchParams(
+    kept
+      .map(/** @returns {[string, string]} */ ([name, value]) => [name, String(value)])
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  );
+
+  return `${pathname}?${params.toString()}`;
+}
+
 /**
  * @param {string} pathname
  * @param {number | undefined} fallback