jskelet 0.6.3 → 0.6.4

package/src/server/cache-blob.js

@@ -1,70 +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);
-}
+/**
+ * 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/cache-deps.js

@@ -1,42 +1,42 @@
-/**
- * Bir render'ın hangi veri anahtarlarını okuduğunu kaydeder.
- *
- * `request-cache.js` ile aynı desen: `AsyncLocalStorage`, bağlam yoksa her şey
- * sessizce devre dışı. Script'ten, cron'dan ya da istek dışı bir yerden yapılan
- * `withDataCache` çağrıları hiçbir şeye yazılmaz.
- *
- * Neden gerekli: HTML önbelleğinin elinde "bu sayfa şu içerikten etkilenir"
- * bilgisi yoktu, dolayısıyla bir içerik güncellendiğinde tek seçenek TTL'i
- * beklemek ya da tüm önbelleği boşaltmaktı. Bağımlılığı uygulamanın elle
- * bildirmesi (tag'lemek) ise en sık yapılan hatayı davet ediyor: detay
- * sayfasını işaretleyip aynı içeriği listeleyen ana sayfayı unutmak.
- *
- * Burada bildirim yok, **gözlem** var: render sırasında fiilen okunan anahtarlar
- * kaydedilir. Ana sayfa o veriyi okuduysa listede olur, okumadıysa olmaz.
- */
-import { AsyncLocalStorage } from "node:async_hooks";
-
-/** @type {AsyncLocalStorage<Set<string>>} */
-const storage = new AsyncLocalStorage();
-
-/**
- * `run`'ı, içindeki `recordDependency()` çağrılarının `deps`'e yazacağı bir
- * bağlamda çalıştırır.
- *
- * @template T
- * @param {Set<string>} deps
- * @param {() => T} run
- * @returns {T}
- */
-export function collectDependencies(deps, run) {
-  return storage.run(deps, run);
-}
-
-/**
- * Bu render'ın bir veri anahtarını okuduğunu bildirir. Bağlam yoksa no-op.
- *
- * @param {string} key
- */
-export function recordDependency(key) {
-  storage.getStore()?.add(key);
-}
+/**
+ * Bir render'ın hangi veri anahtarlarını okuduğunu kaydeder.
+ *
+ * `request-cache.js` ile aynı desen: `AsyncLocalStorage`, bağlam yoksa her şey
+ * sessizce devre dışı. Script'ten, cron'dan ya da istek dışı bir yerden yapılan
+ * `withDataCache` çağrıları hiçbir şeye yazılmaz.
+ *
+ * Neden gerekli: HTML önbelleğinin elinde "bu sayfa şu içerikten etkilenir"
+ * bilgisi yoktu, dolayısıyla bir içerik güncellendiğinde tek seçenek TTL'i
+ * beklemek ya da tüm önbelleği boşaltmaktı. Bağımlılığı uygulamanın elle
+ * bildirmesi (tag'lemek) ise en sık yapılan hatayı davet ediyor: detay
+ * sayfasını işaretleyip aynı içeriği listeleyen ana sayfayı unutmak.
+ *
+ * Burada bildirim yok, **gözlem** var: render sırasında fiilen okunan anahtarlar
+ * kaydedilir. Ana sayfa o veriyi okuduysa listede olur, okumadıysa olmaz.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** @type {AsyncLocalStorage<Set<string>>} */
+const storage = new AsyncLocalStorage();
+
+/**
+ * `run`'ı, içindeki `recordDependency()` çağrılarının `deps`'e yazacağı bir
+ * bağlamda çalıştırır.
+ *
+ * @template T
+ * @param {Set<string>} deps
+ * @param {() => T} run
+ * @returns {T}
+ */
+export function collectDependencies(deps, run) {
+  return storage.run(deps, run);
+}
+
+/**
+ * Bu render'ın bir veri anahtarını okuduğunu bildirir. Bağlam yoksa no-op.
+ *
+ * @param {string} key
+ */
+export function recordDependency(key) {
+  storage.getStore()?.add(key);
+}

package/src/server/cache-vary.js

@@ -1,113 +1,113 @@
-/**
- * HTML cache anahtarına host / header / özel fn ile sabit vary parçası ekler.
- *
- * CDN zaten tam URL ile ayırır; asıl risk origin L1 ve Redis HTML anahtarı —
- * host'tan locale üreten sitelerde `vary.host: true` olmadan ilk locale'in
- * HTML'i diğer host'a servis edilir.
- */
-import { getConfig } from "../config/index.js";
-
-/**
- * Public Host: `x-forwarded-host` (ilk değer) yoksa `Host`. Lowercase, portsuz.
- * IPv6 (`[::1]:3000`) köşeli parantezleri korur.
- *
- * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
- * @returns {string}
- */
-export function publicHost(req) {
-  const forwarded = headerValue(req, "x-forwarded-host");
-  const raw = forwarded || headerValue(req, "host") || "";
-  const first = raw.split(",")[0].trim().toLowerCase();
-  return stripPort(first);
-}
-
-/**
- * @param {string} host
- * @returns {string}
- */
-function stripPort(host) {
-  if (!host) return "";
-  if (host.startsWith("[")) {
-    const end = host.indexOf("]");
-    return end === -1 ? host : host.slice(0, end + 1);
-  }
-  // Birden fazla `:` → portsuz IPv6 (Host'ta nadir); tek `:` → host:port.
-  const colon = host.lastIndexOf(":");
-  if (colon === -1) return host;
-  if (host.indexOf(":") !== colon) return host;
-  return host.slice(0, colon);
-}
-
-/**
- * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
- * @param {string} name
- * @returns {string}
- */
-function headerValue(req, name) {
-  const viaGet = req.get?.(name);
-  if (typeof viaGet === "string" && viaGet) return viaGet;
-
-  const raw = req.headers?.[name.toLowerCase()];
-  if (Array.isArray(raw)) return raw[0] ? String(raw[0]) : "";
-  if (raw == null) return "";
-  return String(raw);
-}
-
-/**
- * Anahtarın başına eklenen önek: `h=tr.example.com|` veya
- * `h=…&x-locale=tr|`. Vary yoksa boş string.
- *
- * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
- * @returns {string}
- */
-export function buildVaryPrefix(req) {
-  if (!req) return "";
-
-  let vary;
-  try {
-    vary = getConfig().cacheVary;
-  } catch {
-    return "";
-  }
-
-  if (!vary || (!vary.host && !vary.headers.length && !vary.fn)) return "";
-
-  /** @type {string[]} */
-  const parts = [];
-
-  if (vary.host) {
-    const host = publicHost(req);
-    if (host) parts.push(`h=${host}`);
-  }
-
-  for (const name of vary.headers) {
-    const value = headerValue(req, name).trim();
-    if (value) parts.push(`${name}=${value}`);
-  }
-
-  if (typeof vary.fn === "function") {
-    try {
-      const custom = vary.fn(/** @type {import('express').Request} */ (req));
-      if (custom != null && custom !== "") parts.push(String(custom));
-    } catch (error) {
-      console.warn("[cache] cache().vary.fn threw, ignoring it", error);
-    }
-  }
-
-  return parts.length ? `${parts.join("&")}|` : "";
-}
-
-/**
- * Anahtardan yol kısmını çıkarır (`[vary|]yol?query` → `yol`).
- * Invalidation hedefleri `/…` ile başlar; vary öneki eşleşmeye karışmamalı.
- *
- * @param {string} key
- * @returns {string}
- */
-export function pathOfCacheKey(key) {
-  const mark = key.indexOf("?");
-  const beforeQuery = mark === -1 ? key : key.slice(0, mark);
-  const sep = beforeQuery.indexOf("|/");
-  if (sep !== -1) return beforeQuery.slice(sep + 1);
-  return beforeQuery;
-}
+/**
+ * HTML cache anahtarına host / header / özel fn ile sabit vary parçası ekler.
+ *
+ * CDN zaten tam URL ile ayırır; asıl risk origin L1 ve Redis HTML anahtarı —
+ * host'tan locale üreten sitelerde `vary.host: true` olmadan ilk locale'in
+ * HTML'i diğer host'a servis edilir.
+ */
+import { getConfig } from "../config/index.js";
+
+/**
+ * Public Host: `x-forwarded-host` (ilk değer) yoksa `Host`. Lowercase, portsuz.
+ * IPv6 (`[::1]:3000`) köşeli parantezleri korur.
+ *
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
+ * @returns {string}
+ */
+export function publicHost(req) {
+  const forwarded = headerValue(req, "x-forwarded-host");
+  const raw = forwarded || headerValue(req, "host") || "";
+  const first = raw.split(",")[0].trim().toLowerCase();
+  return stripPort(first);
+}
+
+/**
+ * @param {string} host
+ * @returns {string}
+ */
+function stripPort(host) {
+  if (!host) return "";
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    return end === -1 ? host : host.slice(0, end + 1);
+  }
+  // Birden fazla `:` → portsuz IPv6 (Host'ta nadir); tek `:` → host:port.
+  const colon = host.lastIndexOf(":");
+  if (colon === -1) return host;
+  if (host.indexOf(":") !== colon) return host;
+  return host.slice(0, colon);
+}
+
+/**
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
+ * @param {string} name
+ * @returns {string}
+ */
+function headerValue(req, name) {
+  const viaGet = req.get?.(name);
+  if (typeof viaGet === "string" && viaGet) return viaGet;
+
+  const raw = req.headers?.[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0] ? String(raw[0]) : "";
+  if (raw == null) return "";
+  return String(raw);
+}
+
+/**
+ * Anahtarın başına eklenen önek: `h=tr.example.com|` veya
+ * `h=…&x-locale=tr|`. Vary yoksa boş string.
+ *
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
+ * @returns {string}
+ */
+export function buildVaryPrefix(req) {
+  if (!req) return "";
+
+  let vary;
+  try {
+    vary = getConfig().cacheVary;
+  } catch {
+    return "";
+  }
+
+  if (!vary || (!vary.host && !vary.headers.length && !vary.fn)) return "";
+
+  /** @type {string[]} */
+  const parts = [];
+
+  if (vary.host) {
+    const host = publicHost(req);
+    if (host) parts.push(`h=${host}`);
+  }
+
+  for (const name of vary.headers) {
+    const value = headerValue(req, name).trim();
+    if (value) parts.push(`${name}=${value}`);
+  }
+
+  if (typeof vary.fn === "function") {
+    try {
+      const custom = vary.fn(/** @type {import('express').Request} */ (req));
+      if (custom != null && custom !== "") parts.push(String(custom));
+    } catch (error) {
+      console.warn("[cache] cache().vary.fn threw, ignoring it", error);
+    }
+  }
+
+  return parts.length ? `${parts.join("&")}|` : "";
+}
+
+/**
+ * Anahtardan yol kısmını çıkarır (`[vary|]yol?query` → `yol`).
+ * Invalidation hedefleri `/…` ile başlar; vary öneki eşleşmeye karışmamalı.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function pathOfCacheKey(key) {
+  const mark = key.indexOf("?");
+  const beforeQuery = mark === -1 ? key : key.slice(0, mark);
+  const sep = beforeQuery.indexOf("|/");
+  if (sep !== -1) return beforeQuery.slice(sep + 1);
+  return beforeQuery;
+}