jskelet 0.1.2 → 0.1.4

package/src/config/index.js

@@ -15,7 +15,8 @@
  *   headers()   → [{ source, headers: [{ key, value }] }]
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
- *   cache()     → { html?: { [source]: saniye }, prewarm?: {...} }
+ *   cache()     → { html?: { [source]: saniye }, maxEntries?: number,
+ *                   data?: {...}, prewarm?: {...} }
  *
  * Fonksiyon olmayan bölümler (`brand`, `security`, `static`, `navigation`…)
  * düz nesne olarak okunur.
@@ -24,17 +25,20 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
-import { compilePattern } from "./pattern.js";
+import { compilePattern, matchPattern } from "./pattern.js";
 import {
   DEFAULT_BRAND,
+  DEFAULT_DATA_CACHE,
   DEFAULT_DEV_GATE_BYPASS,
   DEFAULT_DIRS,
+  DEFAULT_HTML_CACHE_MAX_ENTRIES,
   DEFAULT_NAVIGATION,
   DEFAULT_NAVIGATION_EXCLUDE,
   DEFAULT_PREWARM,
   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. */
@@ -63,7 +67,12 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, destination: string, statusCode: number }[]} redirects
  * @property {{ phase: "beforeFiles" | "afterFiles", pattern: CompiledPattern, destination: string }[]} rewrites
  * @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
  * @property {Record<string, Function>} hooks
  * @property {string} layout Layout `.ejs` dosyasının mutlak yolu.
@@ -168,8 +177,42 @@ function normalizeRewrites(raw) {
 }
 
 /**
+ * Isıtma sırası desenleri. İki biçim kabul edilir: config'in her yerinde
+ * geçerli olan `/haber/:slug` sözdizimi ve doğrudan `RegExp` — ikincisi
+ * "sonu `-yorumlar` ile bitenler" gibi desen sözdiziminin karşılamadığı
+ * kuralları yazabilmek için.
+ *
  * @param {unknown} raw
- * @returns {{ html: ResolvedConfig["html"], prewarm: Record<string, unknown> }}
+ * @returns {ResolvedConfig["prewarmPriority"]}
+ */
+function normalizePriority(raw) {
+  /** @type {ResolvedConfig["prewarmPriority"]} */
+  const out = [];
+
+  for (const entry of asArray(raw, "cache().prewarm.priority")) {
+    if (entry instanceof RegExp) {
+      out.push({ source: String(entry), test: (pathname) => entry.test(pathname) });
+      continue;
+    }
+
+    const pattern = compilePattern(entry);
+    if (!pattern) continue;
+    out.push({
+      source: pattern.source,
+      test: (pathname) => matchPattern(pattern, pathname) !== null,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
+ *   data: Record<string, unknown>, trackUpstream: boolean,
+ *   transientRetry: { attempts: number, delayMs: number },
+ *   prewarm: Record<string, unknown>,
+ *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
  */
 function normalizeCache(raw) {
   /** @type {ResolvedConfig["html"]} */
@@ -182,7 +225,28 @@ function normalizeCache(raw) {
     html.push({ pattern, seconds: value });
   }
 
-  return { html, prewarm: { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) } };
+  const prewarm = { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) };
+  const maxEntries = Number(raw?.maxEntries);
+
+  return {
+    html,
+    htmlMaxEntries:
+      Number.isFinite(maxEntries) && maxEntries > 0
+        ? 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,
+    prewarmPriority: normalizePriority(prewarm.priority),
+  };
 }
 
 /** Speculation Rules'un tanıdığı eagerness değerleri. */
@@ -388,7 +452,15 @@ export async function loadConfig(options = {}) {
     section("cache"),
   ]);
 
-  const { html, prewarm } = normalizeCache(cache);
+  const {
+    html,
+    htmlMaxEntries,
+    data,
+    trackUpstream,
+    transientRetry,
+    prewarm,
+    prewarmPriority,
+  } = normalizeCache(cache);
   const dirs = resolveDirs(root, source.paths);
   const brand = { ...DEFAULT_BRAND, ...(source.brand ?? {}) };
 
@@ -400,7 +472,12 @@ export async function loadConfig(options = {}) {
     redirects: normalizeRedirects(redirects),
     rewrites: normalizeRewrites(rewrites),
     html,
+    htmlMaxEntries,
+    data,
+    trackUpstream,
+    transientRetry,
     prewarm,
+    prewarmPriority,
     brand,
     hooks: source.hooks ?? {},
     layout: resolveLayout(dirs, source.layout),

package/src/index.js

@@ -45,6 +45,13 @@ export {
   getHtmlCacheSize,
   withHtmlCache,
 } from "./server/html-cache.js";
+export {
+  clearDataCache,
+  dataCache,
+  getDataCacheEntries,
+  getDataCacheSize,
+  withDataCache,
+} from "./server/data-cache.js";
 export { prewarm, prewarmProgress } from "./server/prewarm.js";
 export { createProxy } from "./server/middleware/upstream-proxy.js";
 export { getConfig, loadConfig } from "./config/index.js";

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/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);