jskelet 0.6.2 → 0.6.4

package/src/init.mjs

@@ -30,6 +30,8 @@ export default {
     return {
       /** How long a page's HTML stays in the cache (seconds). */
       html: { "/": 60 },
+      /** Edge stale window after that TTL. 0 omits the directive. */
+      staleWhileRevalidate: 60,
     };
   },
 

package/src/server/cache-blob.js

@@ -0,0 +1,70 @@
+/**
+ * Redis ve disk L2'nin ortak gövdesi.
+ *
+ * 1 KB altı düz JSON kalır (`redis-cli` ve küçük veri kayıtları okunaklı
+ * kalsın). Üstü `JSK\\x01` + brotli. zstd `node:zlib`'de 22.15'ten itibaren
+ * var; motor `>=22` olduğu için brotli — yanıt sıkıştırmasıyla aynı kalite.
+ */
+import zlib from "node:zlib";
+
+const COMPRESS_THRESHOLD = 1024;
+const CACHE_MAGIC = Buffer.from([0x4a, 0x53, 0x4b, 0x01]);
+const BROTLI_OPTIONS = {
+  params: {
+    [zlib.constants.BROTLI_PARAM_QUALITY]: 5,
+    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+  },
+};
+
+/**
+ * @param {string} json
+ * @param {Buffer} compressed
+ * @returns {string | Buffer}
+ */
+function pickPayload(json, compressed) {
+  const packed = Buffer.concat([CACHE_MAGIC, compressed]);
+  return packed.length < Buffer.byteLength(json) ? packed : json;
+}
+
+/**
+ * Küçük gövde düz `string` döner (çağıran senkron yazabilsin). Büyük gövde
+ * brotli bitince çözülen bir Promise.
+ *
+ * @param {unknown} value
+ * @returns {string | Buffer | Promise<string | Buffer> | null}
+ */
+export function encodeCacheValue(value) {
+  /** @type {string} */
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    return null;
+  }
+
+  if (Buffer.byteLength(json) < COMPRESS_THRESHOLD) return json;
+
+  return new Promise((resolve) => {
+    zlib.brotliCompress(Buffer.from(json), BROTLI_OPTIONS, (error, compressed) => {
+      if (error) resolve(json);
+      else resolve(pickPayload(json, compressed));
+    });
+  });
+}
+
+/**
+ * @param {Buffer | string} raw
+ * @returns {unknown}
+ */
+export function decodeCacheValue(raw) {
+  if (
+    Buffer.isBuffer(raw) &&
+    raw.length > CACHE_MAGIC.length &&
+    raw.subarray(0, CACHE_MAGIC.length).equals(CACHE_MAGIC)
+  ) {
+    return JSON.parse(zlib.brotliDecompressSync(raw.subarray(CACHE_MAGIC.length)).toString("utf8"));
+  }
+
+  const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : raw;
+  return JSON.parse(text);
+}

package/src/server/cache-control.js

@@ -0,0 +1,45 @@
+/**
+ * Tarayıcıya `max-age=0`, edge'e `CDN-Cache-Control`.
+ *
+ * `s-maxage` yazılmaz: Cloudflare `max-age=0` ile birlikte görünce nesneyi
+ * EXPIRED sayar. `must-revalidate`, `proxy-revalidate` ve `no-cache` aynı
+ * yanıtta stale penceresini keser; burada üretilmez. `s-maxage`'e dönen bir
+ * anahtar da yok — o mod aynı EXPIRED sonucunu geri getirir.
+ *
+ * Süreç içi HTML cache (`X-JSkelet-Cache: STALE`) ayrı katmandır; bu modül
+ * ona dokunmaz. Görsel optimizer kendi `max-age` + `stale-while-revalidate`
+ * yolunu kullanır.
+ */
+
+/** Tarayıcı kopyası tutulmaz; taze pencere edge başlığındadır. */
+const BROWSER_CACHE = "public, max-age=0";
+
+/**
+ * @param {number} maxAge Edge'in taze penceresi (saniye). HTML'de route TTL.
+ * @param {number} staleWhileRevalidate Taze pencere bitince eski kopyanın
+ *   sunulacağı süre. 0 ise direktif basılmaz.
+ * @returns {{ cacheControl: string, cdnCacheControl: string }}
+ */
+export function edgeCacheControl(maxAge, staleWhileRevalidate) {
+  /** @type {string[]} */
+  const directives = [`max-age=${maxAge}`];
+  if (staleWhileRevalidate > 0) {
+    directives.push(`stale-while-revalidate=${staleWhileRevalidate}`);
+  }
+
+  return {
+    cacheControl: BROWSER_CACHE,
+    cdnCacheControl: directives.join(", "),
+  };
+}
+
+/**
+ * @param {import('express').Response} res
+ * @param {number} maxAge
+ * @param {number} staleWhileRevalidate
+ */
+export function setEdgeCacheHeaders(res, maxAge, staleWhileRevalidate) {
+  const headers = edgeCacheControl(maxAge, staleWhileRevalidate);
+  res.setHeader("Cache-Control", headers.cacheControl);
+  res.setHeader("CDN-Cache-Control", headers.cdnCacheControl);
+}

package/src/server/data-cache.js

@@ -20,12 +20,13 @@
  * `cache.redis` açıkken bu önbellek ikinci bir kademeye (L2) yaslanır. Redis'e
  * en uygun katman burası: JSON küçük, sıkıştırılmış varyant sorunu yok ve
  * kazanç doğrudan API kotasına yazılıyor — bir node'un çektiği veri hepsine
- * yeter. Redis kapalı ya da erişilemez olduğunda bu modül birebir eskisi gibi
- * çalışır.
+ * yeter. Redis yoksa aynı kayıt diske yazılır; süreç yeniden açılınca upstream
+ * yeniden çağrılmaz.
  */
 import { getConfig } from "../config/index.js";
-import { DEFAULT_DATA_CACHE } from "../config/defaults.js";
+import { DATA_CACHE_BYTE_BUDGET, DEFAULT_DATA_CACHE } from "../config/defaults.js";
 import { recordDependency } from "./cache-deps.js";
+import { diskDrop, diskDropMatching, diskGetJson, diskSetJson, diskShares } from "./disk-cache.js";
 import { invalidateHtmlByDependency } from "./html-cache.js";
 import {
   cacheKey,
@@ -38,12 +39,24 @@ import {
 } from "./redis.js";
 
 /**
- * @typedef {{ value: unknown, expiresAt: number, staleUntil: number }} DataEntry
+ * @typedef {{ value: unknown, expiresAt: number, staleUntil: number, bytes: number }} DataEntry
  */
 
 /** @type {Map<string, DataEntry>} */
 const store = new Map();
 
+/**
+ * `store` içindeki JSON gövdelerin toplamı. Tam tarama yapmamak için tutulur.
+ * Her silme `forget` üzerinden geçer; LRU sırası değişimi sayacı oynatmaz.
+ */
+let storedBytes = 0;
+
+/**
+ * Testler tahliyeyi küçük bir bütçeyle doğrular. `null` → üretim tavanı.
+ * @type {number | null}
+ */
+let byteBudgetOverride = null;
+
 /** @type {Map<string, Promise<unknown>>} */
 const inflight = new Map();
 
@@ -103,27 +116,85 @@ function read(key) {
 
   const now = Date.now();
   if (now >= entry.staleUntil) {
-    store.delete(key);
+    forget(key);
     return null;
   }
 
-  // LRU: erişilen girdiyi sona taşı.
+  // LRU: erişilen girdiyi sona taşı. Bayt sayacı değişmez.
   store.delete(key);
   store.set(key, entry);
 
   return { value: entry.value, stale: now >= entry.expiresAt };
 }
 
-/** Girdi sınırını aşan en eski kayıtları düşürür. */
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function valueBytes(value) {
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string") return 0;
+    return Buffer.byteLength(json);
+  } catch {
+    // Serileşmeyen değer yine saklanır; ölçülemediği için küçük bir pay.
+    return 1024;
+  }
+}
+
+/** @returns {number} */
+function activeByteBudget() {
+  return byteBudgetOverride ?? DATA_CACHE_BYTE_BUDGET;
+}
+
+/**
+ * Store'dan silmenin tek yolu. Bayt sayacı buraya bağlı.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+function forget(key) {
+  const entry = store.get(key);
+  if (!entry) return false;
+  storedBytes = Math.max(0, storedBytes - (entry.bytes || 0));
+  store.delete(key);
+  return true;
+}
+
+/**
+ * Sayı tavanı veya bayt bütçesi aşılınca en eski girdiden düşer.
+ * @returns {void}
+ */
 function evict() {
   const { maxEntries } = settings();
-  while (store.size > maxEntries) {
+  const budget = activeByteBudget();
+
+  while (store.size > 0 && (store.size > maxEntries || storedBytes > budget)) {
     const oldest = store.keys().next().value;
     if (oldest === undefined) break;
-    store.delete(oldest);
+    if (!forget(oldest)) break;
   }
 }
 
+/**
+ * L1'e yazar. Bütçeden büyük tek değer saklanmaz.
+ *
+ * @param {string} key
+ * @param {DataEntry} entry
+ * @returns {boolean}
+ */
+function install(key, entry) {
+  const bytes = entry.bytes || valueBytes(entry.value);
+  entry.bytes = bytes;
+  forget(key);
+  if (bytes > activeByteBudget()) return false;
+
+  store.set(key, entry);
+  storedBytes += bytes;
+  evict();
+  return store.has(key);
+}
+
 /**
  * @param {string} key
  * @param {unknown} value
@@ -139,17 +210,20 @@ function write(key, value, ttlSeconds, staleFactor) {
     value,
     expiresAt: now + ttl,
     staleUntil: now + ttl + ttl * staleFactor,
+    bytes: valueBytes(value),
   };
 
-  store.set(key, entry);
+  // Bütçeye sığmayan değer Redis'e de yazılmaz: bir sonraki istek onu geri
+  // alıp yine reddeder. Çağıran sonuç yine `producer`'ın döndürdüğüdür.
+  if (!install(key, entry)) return;
 
   // Redis kopyası ateşle-unut: çağıran taraf beklemez. Anahtarın Redis ömrü
   // bayat penceresinin sonuna kadar, çünkü bayat veri de işe yarıyor.
   if (redisShares("data")) {
     redisSetJson(cacheKey("data", key), entry, entry.staleUntil - now);
+  } else if (diskShares("data")) {
+    diskSetJson("data", key, entry);
   }
-
-  evict();
 }
 
 /**
@@ -161,8 +235,8 @@ function write(key, value, ttlSeconds, staleFactor) {
  * @param {DataEntry} entry
  */
 function promote(key, entry) {
-  store.set(key, entry);
-  evict();
+  if (!entry.bytes) entry.bytes = valueBytes(entry.value);
+  install(key, entry);
 }
 
 /**
@@ -176,11 +250,16 @@ function promote(key, entry) {
  * @returns {Promise<DataEntry | null>}
  */
 async function readShared(key) {
-  if (!redisShares("data")) return null;
+  const onRedis = redisShares("data");
+  const onDisk = diskShares("data");
+  if (!onRedis && !onDisk) return null;
 
-  const entry = await redisGetJson(cacheKey("data", key));
+  const entry = onRedis ? await redisGetJson(cacheKey("data", key)) : await diskGetJson("data", key);
   if (!entry || typeof entry.expiresAt !== "number") return null;
-  if (Date.now() >= entry.expiresAt) return null;
+  if (Date.now() >= entry.expiresAt) {
+    if (onDisk) diskDrop("data", [key]);
+    return null;
+  }
 
   return /** @type {DataEntry} */ (entry);
 }
@@ -340,12 +419,9 @@ export function dataCache(fn, options) {
 export function clearDataCache(prefix) {
   const removed = clearLocal(prefix);
 
-  if (redisShares("data")) {
-    void redisDropMatching(
-      "data",
-      prefix === undefined ? undefined : (key) => key.startsWith(prefix),
-    );
-  }
+  const match = prefix === undefined ? undefined : (key) => key.startsWith(prefix);
+  if (redisShares("data")) void redisDropMatching("data", match);
+  else if (diskShares("data")) void diskDropMatching("data", match);
 
   // Yayın yerel silmeden **sonra** yapılır; diğer node'lar kendi anahtarlarını
   // kendileri tarar, çünkü hangi anahtarın nerede sıcak olduğu node'a bağlı.
@@ -368,10 +444,11 @@ function clearLocal(prefix) {
   if (prefix === undefined) {
     removed.push(...store.keys());
     store.clear();
+    storedBytes = 0;
   } else {
-    for (const key of store.keys()) {
+    for (const key of [...store.keys()]) {
       if (key.startsWith(prefix)) {
-        store.delete(key);
+        forget(key);
         removed.push(key);
       }
     }
@@ -386,7 +463,7 @@ function clearLocal(prefix) {
 onCacheEvent((event) => {
   if (event.type === "data:drop") {
     if (typeof event.key !== "string") return;
-    store.delete(event.key);
+    forget(event.key);
     invalidateHtmlByDependency([event.key]);
     return;
   }
@@ -406,7 +483,7 @@ onCacheEvent((event) => {
  * @returns {boolean} Girdi var mıydı.
  */
 export function dropDataCacheKey(key) {
-  const existed = store.delete(key);
+  const existed = forget(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.
@@ -414,6 +491,8 @@ export function dropDataCacheKey(key) {
 
   if (redisShares("data")) {
     void redisDropMatching("data", (candidate) => candidate === key);
+  } else if (diskShares("data")) {
+    diskDrop("data", [key]);
   }
 
   publishCacheEvent({ type: "data:drop", key });
@@ -426,6 +505,18 @@ export function getDataCacheSize() {
   return store.size;
 }
 
+/**
+ * Bellek freninin bayt tavanını geçici olarak değiştirir. Testler LRU
+ * tahliyesini küçük bir değerle doğrular; `null` üretim tavanına döner.
+ *
+ * @param {number | null} bytes
+ * @returns {void}
+ */
+export function setDataCacheByteBudget(bytes) {
+  byteBudgetOverride = bytes == null ? null : bytes;
+  evict();
+}
+
 /**
  * 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.

package/src/server/disk-cache.js

@@ -0,0 +1,233 @@
+/**
+ * Redis yokken L2: aynı brotli gövde `.jskelet/cache/<buildId>/` altına yazılır.
+ *
+ * Tek makinenin yeniden açılışını karşılar. Birden fazla instance aynı
+ * dizini paylaşmaz — o iş Redis'te kalır. Redis o türü paylaşıyorsa disk
+ * devreye girmez; iki kopya birbirini ezmesin.
+ *
+ * Dosya adı anahtarın sha256'sı. Başta anahtarın kendisi durur ki desenle
+ * silmek için gövdeyi çözmek gerekmesin. Süre Redis'teki `PX` yerine
+ * girdinin `expiresAt` alanındadır; süresi dolmuş dosya okununca silinir.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getConfig } from "../config/index.js";
+import { getBuildId } from "./assets.js";
+import { decodeCacheValue, encodeCacheValue } from "./cache-blob.js";
+import { redisShares } from "./redis.js";
+
+/** @type {string | null} `null` → config'den çöz. Testler mutlak yol verir. */
+let testRoot = null;
+
+let pruned = false;
+
+/**
+ * @param {string | null} root Mutlak dizin, ya da config yoluna dönmek için `null`.
+ */
+export function setDiskCacheRootForTests(root) {
+  testRoot = root;
+  pruned = false;
+}
+
+/**
+ * @returns {string | null}
+ */
+function directory() {
+  if (typeof testRoot === "string") return testRoot;
+
+  try {
+    return path.join(getConfig().dirs.generated, "cache", getBuildId());
+  } catch {
+    // Birim testleri config yüklemez. Disk yazısı o zaman da kapalı kalır.
+    return null;
+  }
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @returns {boolean}
+ */
+export function diskShares(kind) {
+  if (redisShares(kind)) return false;
+  return directory() !== null;
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function fileName(key) {
+  return crypto.createHash("sha256").update(key).digest("hex");
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @returns {string | null}
+ */
+function filePath(kind, key) {
+  const root = directory();
+  if (!root) return null;
+  return path.join(root, kind, fileName(key));
+}
+
+/**
+ * @param {string} key
+ * @param {string | Buffer} payload
+ * @returns {Buffer}
+ */
+function frame(key, payload) {
+  const keyBuf = Buffer.from(key);
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(keyBuf.length);
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return Buffer.concat([header, keyBuf, body]);
+}
+
+/**
+ * @param {Buffer} raw
+ * @returns {{ key: string, body: Buffer } | null}
+ */
+function unframe(raw) {
+  if (raw.length < 4) return null;
+  const keyLen = raw.readUInt32BE(0);
+  if (keyLen < 1 || keyLen > 65536 || raw.length < 4 + keyLen) return null;
+  return {
+    key: raw.subarray(4, 4 + keyLen).toString("utf8"),
+    body: raw.subarray(4 + keyLen),
+  };
+}
+
+/**
+ * Eski build kimliğinin dizinini siler. Redis'te o anahtarlar TTL ile ölür;
+ * dosyada karşılığı bu. Dev'de kimlik `dev` kaldığı için prune bir şey silmez.
+ *
+ * @param {string} dir
+ */
+function pruneOldBuilds(dir) {
+  if (pruned || testRoot) return;
+  pruned = true;
+
+  const parent = path.dirname(dir);
+  const current = path.basename(dir);
+
+  fs.readdir(parent, { withFileTypes: true })
+    .then((entries) =>
+      Promise.all(
+        entries
+          .filter((entry) => entry.isDirectory() && entry.name !== current)
+          .map((entry) => fs.rm(path.join(parent, entry.name), { recursive: true, force: true })),
+      ),
+    )
+    .catch(() => {
+      // Dizin henüz yoksa ya da silinemiyorsa L1 çalışmaya devam eder.
+    });
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @returns {Promise<unknown | null>}
+ */
+export async function diskGetJson(kind, key) {
+  const file = filePath(kind, key);
+  if (!file) return null;
+
+  try {
+    const framed = unframe(await fs.readFile(file));
+    if (!framed) return null;
+    return decodeCacheValue(framed.body);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ateşle-unut. Dönüş değeri testler bekleyebilsin diye durur; istek yolu
+ * beklemez.
+ *
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Promise<void>}
+ */
+export function diskSetJson(kind, key, value) {
+  const root = directory();
+  const file = filePath(kind, key);
+  if (!root || !file) return Promise.resolve();
+
+  pruneOldBuilds(root);
+
+  const encoded = encodeCacheValue(value);
+  if (encoded === null) return Promise.resolve();
+
+  const write = (/** @type {string | Buffer} */ payload) => {
+    const tmp = `${file}.${process.pid}.tmp`;
+    return fs
+      .mkdir(path.dirname(file), { recursive: true })
+      .then(() => fs.writeFile(tmp, frame(key, payload)))
+      .then(() => fs.rename(tmp, file))
+      .catch((error) => {
+        console.warn(
+          "[disk-cache] write failed",
+          error instanceof Error ? error.message : error,
+        );
+      });
+  };
+
+  if (typeof encoded === "string" || Buffer.isBuffer(encoded)) return write(encoded);
+  return encoded.then(write);
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @param {string[]} keys
+ */
+export function diskDrop(kind, keys) {
+  if (!directory() || !keys.length) return;
+
+  for (const key of keys) {
+    const file = filePath(kind, key);
+    if (file) fs.rm(file, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * @param {"html" | "data"} kind
+ * @param {(key: string) => boolean} [match] Verilmezse türün tamamı silinir.
+ * @returns {Promise<number>}
+ */
+export async function diskDropMatching(kind, match) {
+  const root = directory();
+  if (!root) return 0;
+
+  const folder = path.join(root, kind);
+  /** @type {string[]} */
+  let names;
+  try {
+    names = await fs.readdir(folder);
+  } catch {
+    return 0;
+  }
+
+  let dropped = 0;
+
+  await Promise.all(
+    names.map(async (name) => {
+      const file = path.join(folder, name);
+      try {
+        if (match) {
+          const framed = unframe(await fs.readFile(file));
+          if (!framed || !match(framed.key)) return;
+        }
+        await fs.rm(file, { force: true });
+        dropped += 1;
+      } catch {
+        // Yarışta silinmiş dosya sorun değil.
+      }
+    }),
+  );
+
+  return dropped;
+}