jskelet 0.5.1 → 0.5.3

package/src/config/index.js

@@ -16,7 +16,9 @@
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
  *   cache()     → { html?: { [source]: saniye },
- *                   query?: { [source]: string[] | true }, maxEntries?: number,
+ *                   query?: { [source]: string[] | true },
+ *                   vary?: { host?: boolean, headers?: string[], fn?: Function },
+ *                   maxEntries?: number,
  *                   data?: {...}, redis?: {...}, prewarm?: {...} }
  *   admin()     → { enabled?, basePath?, allowIps?, blockBots?, … }
  *   logs        → { console?, kinds?, file?, s3? }
@@ -107,6 +109,10 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, allow: true | string[] }[]} cacheQuery
  *   Yol deseni başına, HTML cache anahtarına girmesine izin verilen query
  *   parametreleri. Eşleşen kural yoksa query'li istek cache'lenmez.
+ * @property {{ host: boolean, headers: string[],
+ *   fn: ((req: import('express').Request) => string | null | undefined) | null }} cacheVary
+ *   Anahtara eklenen sabit parçalar (query allowlist'ten bağımsız). Host'tan
+ *   locale üreten sitelerde `host: true` zorunlu.
  * @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.
@@ -633,10 +639,42 @@ function normalizeQueryRules(raw) {
   return out;
 }
 
+/**
+ * `cache().vary` → HTML anahtarına host / header / özel fn parçası.
+ *
+ * @param {unknown} raw
+ * @returns {ResolvedConfig["cacheVary"]}
+ */
+function normalizeVary(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { host: false, headers: [], fn: null };
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const headers = asArray(source.headers, "cache().vary.headers")
+    .filter((name) => typeof name === "string" && name)
+    .map((name) => String(name).toLowerCase());
+
+  /** @type {ResolvedConfig["cacheVary"]["fn"]} */
+  let fn = null;
+  if (typeof source.fn === "function") {
+    fn = /** @type {ResolvedConfig["cacheVary"]["fn"]} */ (source.fn);
+  } else if (source.fn != null) {
+    console.warn("[config] cache().vary.fn must be a function, ignoring it");
+  }
+
+  return {
+    host: source.host === true,
+    headers,
+    fn,
+  };
+}
+
 /**
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"],
- *   cacheQuery: ResolvedConfig["cacheQuery"], htmlMaxEntries: number,
+ *   cacheQuery: ResolvedConfig["cacheQuery"],
+ *   cacheVary: ResolvedConfig["cacheVary"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
  *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
@@ -664,6 +702,7 @@ function normalizeCache(raw) {
   return {
     html,
     cacheQuery: queryRules,
+    cacheVary: normalizeVary(raw?.vary),
     htmlMaxEntries:
       Number.isFinite(maxEntries) && maxEntries > 0
         ? Math.floor(maxEntries)
@@ -775,6 +814,12 @@ function normalizePrewarm(raw) {
   // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
   const classic = { ...source };
   delete classic.onVisit;
+
+  const origins = asArray(classic.origins, "cache().prewarm.origins")
+    .filter((value) => typeof value === "string" && /^https?:\/\//i.test(value))
+    .map(String);
+  classic.origins = origins;
+
   return {
     ...DEFAULT_PREWARM,
     ...classic,
@@ -1074,6 +1119,7 @@ export async function loadConfig(options = {}) {
   const {
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -1097,6 +1143,7 @@ export async function loadConfig(options = {}) {
     rewrites: normalizeRewrites(rewrites),
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,

package/src/index.js

@@ -38,6 +38,16 @@ export {
 export { reportUpstreamFailure } from "./server/upstream-tracking.js";
 export { asset, hasAsset, optimizedImage, getSpriteIds } from "./server/assets.js";
 export { remoteImageUrl, parseAllowedRemoteUrl } from "./server/image-optimizer.js";
+export {
+  ImageResponse,
+  OG_SIZE,
+  buildOgSvg,
+  escapeXml,
+  ogHandler,
+  ogImage,
+  sendOgImage,
+  wrapText,
+} from "./server/og-image.js";
 export { headHints } from "./server/head-hints.js";
 export { renderHeadMeta } from "./server/metadata.js";
 export {

package/src/server/cache-vary.js

@@ -0,0 +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;
+}

package/src/server/html-cache.js

@@ -34,6 +34,7 @@ import { getConfig } from "../config/index.js";
 import { DEFAULT_HTML_CACHE_MAX_ENTRIES } from "../config/defaults.js";
 import { collectDependencies } from "./cache-deps.js";
 import { compilePattern, matchPattern } from "../config/pattern.js";
+import { pathOfCacheKey } from "./cache-vary.js";
 import {
   cacheKey,
   onCacheEvent,
@@ -662,8 +663,9 @@ function invalidateKey(key, hard) {
  * arkada ve anahtar başına tek seferde koşar. `hard: true` yalnızca eski
  * HTML'in gerçekten geçersiz olduğu durumlar için.
  *
- * Anahtar `yol?query` olduğundan eşleştirme **yol kısmına** yapılır: bir
- * yolun bütün query varyantları (`?utm_source=…` dahil) tek çağrıyla düşer.
+ * Anahtar `yol?query` (isteğe bağlı `vary|` önekiyle) olduğundan eşleştirme
+ * **yol kısmına** yapılır: bir yolun bütün query / host varyantları tek
+ * çağrıyla düşer.
  *
  * @param {string | RegExp | (string | RegExp)[]} target
  * @param {{ hard?: boolean }} [options]
@@ -733,14 +735,14 @@ function compileMatchers(targets) {
 }
 
 /**
- * Anahtar `yol?query`; eşleştirme **yol kısmına** yapılır.
+ * Anahtar `[vary|]yol?query`; eşleştirme **yol** kısmına yapılır.
+ * Vary öneki (`h=…|`) invalidation hedefiyle karışmasın.
  *
  * @param {string} key
  * @returns {string}
  */
 function pathOf(key) {
-  const mark = key.indexOf("?");
-  return mark === -1 ? key : key.slice(0, mark);
+  return pathOfCacheKey(key);
 }
 
 /**
@@ -879,6 +881,9 @@ function dropLocalKey(key) {
  * boşaltır. Isıtma turu bunları başa alır; iki tur aynı yolu tekrar
  * ısıtmasın diye okuma yıkıcıdır.
  *
+ * Vary öneki (`h=…|`) düşülür — HTTP ısıtması yalnızca yolu ister; host
+ * ayrımı `prewarm.origins` / istek Host'u ile yapılır.
+ *
  * @returns {string[]}
  */
 export function takeInvalidatedPaths() {
@@ -886,8 +891,13 @@ export function takeInvalidatedPaths() {
 
   const paths = [...invalidated];
   invalidated.clear();
-  // Anahtar `yol?query`; query boşsa sondaki `?` atılır.
-  return paths.map((key) => (key.endsWith("?") ? key.slice(0, -1) : key));
+  return paths.map((key) => {
+    const pathname = pathOfCacheKey(key);
+    const q = key.indexOf("?");
+    if (q === -1) return pathname;
+    const query = key.slice(q + 1);
+    return query ? `${pathname}?${query}` : pathname;
+  });
 }
 
 /**

package/src/server/og-image.js

@@ -0,0 +1,356 @@
+/**
+ * Dinamik Open Graph görselleri — Next.js `ImageResponse` /
+ * `opengraph-image.tsx` karşılığı.
+ *
+ * JSX yok: ya hazır kart alanları (`title`, `description`, `siteName`) ya da
+ * ham `svg` verilir. sharp (opsiyonel peer) varsa PNG üretilir; yoksa SVG
+ * döner. Sosyal kazıyıcıların çoğu PNG beklediği için prod'da sharp önerilir.
+ *
+ * Domain bilgisi taşınmaz — metin, renk ve SVG uygulama tarafındandır.
+ */
+import { tryImportFromApp } from "../build/resolve-peer.mjs";
+import { getConfig } from "../config/index.js";
+import { isNotFoundError } from "../http/control-flow.js";
+
+/** @type {((input: Buffer, opts?: object) => import('sharp').Sharp) | null | undefined} */
+let sharpModule;
+
+/** Sosyal kartlar için yaygın boyut (Facebook / X / LinkedIn). */
+export const OG_SIZE = Object.freeze({ width: 1200, height: 630 });
+
+const DEFAULT_CACHE =
+  "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800";
+
+/**
+ * @typedef {object} OgCardOptions
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {string} [siteName]
+ * @property {string} [background] Düz SVG rengi (`#0f172a`)
+ * @property {string} [color] Ana metin rengi
+ * @property {string} [mutedColor] Açıklama / site adı
+ * @property {string} [accent] Sol şerit rengi
+ */
+
+/**
+ * @typedef {OgCardOptions & {
+ *   svg?: string,
+ *   width?: number,
+ *   height?: number,
+ *   format?: 'png' | 'svg',
+ *   cacheControl?: string,
+ * }} OgImageOptions
+ */
+
+/**
+ * @typedef {object} OgImageResult
+ * @property {Buffer} body
+ * @property {string} contentType
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * XML metin kaçışı — kullanıcı başlığı SVG'ye gömülür.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeXml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Kelime sınırında satır kır. Uzun kelime kesilir; taşan içerik son satırda `…`.
+ * @param {string} text
+ * @param {number} maxChars
+ * @param {number} maxLines
+ * @returns {string[]}
+ */
+export function wrapText(text, maxChars, maxLines) {
+  const words = String(text ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!words.length || maxLines < 1 || maxChars < 1) return [];
+
+  /** @type {string[]} */
+  const lines = [];
+  let current = "";
+  let overflow = false;
+
+  const pushCurrent = () => {
+    if (!current) return;
+    lines.push(current);
+    current = "";
+  };
+
+  for (const word of words) {
+    if (lines.length >= maxLines) {
+      overflow = true;
+      break;
+    }
+
+    const candidate = current ? `${current} ${word}` : word;
+    if (candidate.length <= maxChars) {
+      current = candidate;
+      continue;
+    }
+
+    pushCurrent();
+    if (lines.length >= maxLines) {
+      overflow = true;
+      break;
+    }
+
+    if (word.length <= maxChars) {
+      current = word;
+      continue;
+    }
+
+    let rest = word;
+    while (rest.length > maxChars) {
+      if (lines.length >= maxLines) {
+        overflow = true;
+        rest = "";
+        break;
+      }
+      lines.push(rest.slice(0, maxChars));
+      rest = rest.slice(maxChars);
+    }
+    current = rest;
+  }
+
+  if (current && lines.length < maxLines) {
+    lines.push(current);
+  } else if (current) {
+    overflow = true;
+  }
+
+  if (overflow && lines.length) {
+    const last = lines[lines.length - 1];
+    const base = last.endsWith("…") ? last.slice(0, -1) : last;
+    const trimmed = base.slice(0, Math.max(1, maxChars - 1));
+    lines[lines.length - 1] = `${trimmed}…`;
+  }
+
+  return lines;
+}
+
+/**
+ * Hazır kart SVG'si. Uygulama kendi SVG'sini vermek isterse `svg` kullanır.
+ * @param {OgCardOptions & { width?: number, height?: number }} options
+ * @returns {string}
+ */
+export function buildOgSvg(options = {}) {
+  const width = options.width ?? OG_SIZE.width;
+  const height = options.height ?? OG_SIZE.height;
+  const background = options.background ?? "#0f172a";
+  const color = options.color ?? "#f8fafc";
+  const muted = options.mutedColor ?? "#94a3b8";
+  const accent = options.accent ?? "#38bdf8";
+
+  const titleLines = wrapText(options.title ?? "", 28, 3);
+  const descLines = wrapText(options.description ?? "", 52, 2);
+  const siteName = options.siteName ? escapeXml(options.siteName) : "";
+
+  const titleTs = titleLines
+    .map((line, i) => {
+      const dy = i === 0 ? 0 : 72;
+      return `<tspan x="80" dy="${dy}">${escapeXml(line)}</tspan>`;
+    })
+    .join("");
+
+  const descTs = descLines
+    .map((line, i) => {
+      const dy = i === 0 ? 0 : 40;
+      return `<tspan x="80" dy="${dy}">${escapeXml(line)}</tspan>`;
+    })
+    .join("");
+
+  const titleY = 200;
+  const descY = titleY + Math.max(titleLines.length, 1) * 72 + 36;
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+    `<rect width="100%" height="100%" fill="${escapeXml(background)}"/>` +
+    `<rect x="0" y="0" width="14" height="${height}" fill="${escapeXml(accent)}"/>` +
+    (titleTs
+      ? `<text x="80" y="${titleY}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="64" font-weight="700" fill="${escapeXml(color)}">${titleTs}</text>`
+      : "") +
+    (descTs
+      ? `<text x="80" y="${descY}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="30" font-weight="400" fill="${escapeXml(muted)}">${descTs}</text>`
+      : "") +
+    (siteName
+      ? `<text x="80" y="${height - 64}" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="24" font-weight="600" fill="${escapeXml(muted)}">${siteName}</text>`
+      : "") +
+    `</svg>`
+  );
+}
+
+/**
+ * @returns {Promise<((input: Buffer, opts?: object) => import('sharp').Sharp) | null>}
+ */
+async function loadSharp() {
+  if (sharpModule !== undefined) return sharpModule;
+
+  /** @type {any} */
+  let mod = null;
+  try {
+    mod = await tryImportFromApp(getConfig().root, "sharp");
+  } catch {
+    // Config yoksa (birim test) doğrudan çözümle.
+    try {
+      mod = await import("sharp");
+    } catch {
+      mod = null;
+    }
+  }
+
+  sharpModule = mod?.default ?? mod ?? null;
+  return sharpModule;
+}
+
+/**
+ * SVG veya kart alanlarından PNG/SVG gövde üretir.
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export async function ogImage(options = {}) {
+  const width = options.width ?? OG_SIZE.width;
+  const height = options.height ?? OG_SIZE.height;
+  const svg =
+    typeof options.svg === "string" && options.svg.trim()
+      ? options.svg
+      : buildOgSvg({ ...options, width, height });
+
+  const preferSvg = options.format === "svg";
+  const sharp = preferSvg ? null : await loadSharp();
+
+  if (!sharp) {
+    return {
+      body: Buffer.from(svg, "utf8"),
+      contentType: "image/svg+xml; charset=utf-8",
+      width,
+      height,
+    };
+  }
+
+  const body = await sharp(Buffer.from(svg, "utf8"))
+    .resize(width, height, { fit: "fill" })
+    .png()
+    .toBuffer();
+
+  return {
+    body,
+    contentType: "image/png",
+    width,
+    height,
+  };
+}
+
+/**
+ * Express yanıtına OG görseli basar.
+ * @param {import('express').Response} res
+ * @param {OgImageOptions} [options]
+ * @returns {Promise<OgImageResult>}
+ */
+export async function sendOgImage(res, options = {}) {
+  const result = await ogImage(options);
+  const cacheControl = options.cacheControl ?? DEFAULT_CACHE;
+
+  res.status(200);
+  res.setHeader("Content-Type", result.contentType);
+  res.setHeader("Cache-Control", cacheControl);
+  res.setHeader("Content-Length", String(result.body.length));
+  // Kazıyıcılar ve CDN'ler için boyut ipucu (meta ile de verilir).
+  res.setHeader("X-Og-Width", String(result.width));
+  res.setHeader("X-Og-Height", String(result.height));
+  res.end(result.body);
+  return result;
+}
+
+/**
+ * Next `opengraph-image` route handler'ına yakın Express sarmalayıcı.
+ *
+ * Factory `null` dönerse veya `notFound()` fırlatırsa 404.
+ *
+ * @param {(ctx: { params: Record<string, string>, query: import('express').Request['query'], req: import('express').Request }) =>
+ *   OgImageOptions | null | Promise<OgImageOptions | null>} factory
+ * @param {OgImageOptions} [defaults] Her istekte birleşen varsayılanlar
+ * @returns {import('express').RequestHandler}
+ */
+export function ogHandler(factory, defaults = {}) {
+  return async (req, res, next) => {
+    try {
+      const result = await factory({
+        params: req.params ?? {},
+        query: req.query,
+        req,
+      });
+      if (result == null) {
+        res.status(404).end();
+        return;
+      }
+      await sendOgImage(res, { ...defaults, ...result });
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        res.status(404).end();
+        return;
+      }
+      next(error);
+    }
+  };
+}
+
+/**
+ * Next.js `new ImageResponse(...)` DX'si. JSX yok — ilk argüman SVG string
+ * veya kart alanları nesnesi.
+ *
+ * @example
+ * ```js
+ * return new ImageResponse(
+ *   { title: post.title, description: post.excerpt, siteName: "Blog" },
+ *   { width: 1200, height: 630 },
+ * );
+ * // handler içinde: await image.send(res)
+ * ```
+ */
+export class ImageResponse {
+  /** @type {OgImageOptions} */
+  #options;
+
+  /**
+   * @param {string | OgCardOptions} element
+   * @param {Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & { width?: number, height?: number }} [init]
+   */
+  constructor(element, init = {}) {
+    if (typeof element === "string") {
+      this.#options = { ...init, svg: element };
+    } else {
+      this.#options = { ...element, ...init };
+    }
+  }
+
+  /** @returns {OgImageOptions} */
+  get options() {
+    return this.#options;
+  }
+
+  /** @returns {Promise<OgImageResult>} */
+  async buffer() {
+    return ogImage(this.#options);
+  }
+
+  /**
+   * @param {import('express').Response} res
+   * @returns {Promise<OgImageResult>}
+   */
+  async send(res) {
+    return sendOgImage(res, this.#options);
+  }
+}