jskelet 0.1.1

package/src/server/prewarm.js

@@ -0,0 +1,283 @@
+/**
+ * Sunucu açılışında sayfaları önden render edip HTML cache'ini doldurur.
+ *
+ * Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz:
+ * HTML cache süreç belleğinde yaşadığı için ısıtma da süreç ayağa kalkınca
+ * yapılır. Kazanç aynı — ilk ziyaretçi soğuk render'ı beklemez — fakat veri
+ * dondurulmaz: her girdi route'un `revalidate` süresiyle yaşlanır ve
+ * stale-while-revalidate ile arkada tazelenir.
+ *
+ * Isıtma gerçek HTTP istekleriyle yapılır: cache anahtarı, sıkıştırma ve
+ * middleware zinciri normal trafikle bire bir aynı olsun. Hangi yolların
+ * ısıtılacağını uygulama `hooks.prewarmPaths()` ile bildirir; genelde
+ * sitemap üreten fonksiyonun aynısıdır.
+ */
+import process from "node:process";
+import { getConfig, hook } from "../config/index.js";
+
+/**
+ * Isıtmanın canlı durumu. Dev araçları bunu okuyup ilerlemeyi gösterir;
+ * üretimde kimse okumazsa da maliyeti bir nesnedir.
+ */
+export const prewarmProgress = {
+  active: false,
+  done: 0,
+  total: 0,
+  ok: 0,
+  failed: 0,
+  /** @type {number | null} */
+  startedAt: null,
+  /** @type {number | null} */
+  finishedAt: null,
+  /**
+   * Denenen her yolun sonucu; dev panelindeki Prewarming sekmesi bunu listeler.
+   * @type {{ path: string, status: number, ms: number, bytes: number,
+   *   cache: string | null, error: string | null }[]}
+   */
+  entries: [],
+};
+
+/** @param {unknown} value @param {number} fallback */
+function num(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/**
+ * Ayar sırası: ortam değişkeni → `jskelet.config.mjs` → kod varsayılanı.
+ * Env önde, çünkü tek seferlik deneyler config'i düzenlemeden yapılabilsin.
+ *
+ * @param {string} envKey
+ * @param {string} configKey
+ * @param {number} fallback
+ * @returns {number}
+ */
+function setting(envKey, configKey, fallback) {
+  return num(process.env[envKey], num(getConfig().prewarm?.[configKey], fallback));
+}
+
+/**
+ * @returns {Promise<string[]>}
+ */
+async function collectPaths() {
+  const { prewarmSkip } = getConfig();
+  const paths = await hook("prewarmPaths", []);
+
+  if (!Array.isArray(paths)) {
+    console.warn("[prewarm] hooks.prewarmPaths() dizi döndürmeli, yok sayıldı");
+    return [];
+  }
+
+  // Tekilleştirme sırayı korur: liste `PREWARM_MAX` ile budandığı için
+  // uygulamanın verdiği öncelik sırası anlamlıdır.
+  return [...new Set(paths)].filter(
+    (candidate) =>
+      typeof candidate === "string" &&
+      candidate.startsWith("/") &&
+      !prewarmSkip.some((prefix) => candidate.startsWith(prefix)),
+  );
+}
+
+/**
+ * `DEV_TOKEN` ayarlıyken `devGate` token taşımayan her isteğe 404 döner.
+ * Isıtma kendi sunucusuna istek attığı için token'ı çerez olarak taşımalı;
+ * yoksa tüm sayfalar 404 alır ve önbellek hiç dolmaz.
+ *
+ * @returns {Record<string, string>}
+ */
+function devGateHeader() {
+  const token = process.env.DEV_TOKEN;
+  if (!token) return {};
+
+  const cookie = getConfig().brand.devTokenCookie;
+  return { cookie: `${cookie}=${encodeURIComponent(token)}` };
+}
+
+/**
+ * @param {string} origin
+ * @param {string[]} paths
+ * @param {number} concurrency
+ * @param {(ok: number, failed: number) => void} [report]
+ *   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.
+ * @returns {Promise<{ ok: number, failed: number, failedPaths: string[] }>}
+ */
+async function crawl(origin, paths, concurrency, report = undefined) {
+  const { brand } = getConfig();
+  const cacheHeader = brand.cacheHeader.toLowerCase();
+
+  let index = 0;
+  let ok = 0;
+  let failed = 0;
+  /** @type {string[]} */
+  const failedPaths = [];
+
+  async function worker() {
+    while (index < paths.length) {
+      const target = paths[index];
+      index += 1;
+
+      const startedAt = Date.now();
+
+      try {
+        const response = await fetch(`${origin}${target}`, {
+          headers: {
+            // Sıkıştırılmış gövde de cache'lensin.
+            "accept-encoding": "br, gzip",
+            "user-agent": brand.prewarmUserAgent,
+            ...devGateHeader(),
+          },
+        });
+        // Gövde okunmadan bağlantı açık kalır.
+        const body = await response.arrayBuffer();
+        if (response.ok) ok += 1;
+        else {
+          failed += 1;
+          failedPaths.push(target);
+        }
+
+        prewarmProgress.entries.push({
+          path: target,
+          status: response.status,
+          ms: Date.now() - startedAt,
+          bytes: body.byteLength,
+          cache: response.headers.get(cacheHeader),
+          error: response.ok ? null : `HTTP ${response.status}`,
+        });
+      } catch (error) {
+        failed += 1;
+        failedPaths.push(target);
+        prewarmProgress.entries.push({
+          path: target,
+          status: 0,
+          ms: Date.now() - startedAt,
+          bytes: 0,
+          cache: null,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      if (report) {
+        report(ok, failed);
+      } else {
+        prewarmProgress.done = ok + failed;
+        prewarmProgress.ok = ok;
+        prewarmProgress.failed = failed;
+      }
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, paths.length) }, worker),
+  );
+
+  return { ok, failed, failedPaths };
+}
+
+/**
+ * @param {{ origin: string, quiet?: boolean, paths?: string[] }} options
+ *   `paths` verilirse hook çağrılmaz, yalnızca o yollar ısıtılır (dev
+ *   panelindeki "tekrar dene" bunu kullanır).
+ * @returns {Promise<{ ok: number, failed: number, total: number, elapsed: number }>}
+ */
+export async function prewarm({ origin, quiet = false, paths: only }) {
+  const started = Date.now();
+  const limit = setting("PREWARM_MAX", "max", 400);
+  // Dev'de daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın
+  // render'ıyla CPU için yarışmasın.
+  const concurrency = setting(
+    "PREWARM_CONCURRENCY",
+    "concurrency",
+    process.env.NODE_ENV === "development" ? 2 : 4,
+  );
+
+  const all = only?.length ? only : await collectPaths();
+  const paths = all.slice(0, limit);
+
+  Object.assign(prewarmProgress, {
+    active: true,
+    done: 0,
+    total: paths.length,
+    ok: 0,
+    failed: 0,
+    startedAt: started,
+    finishedAt: null,
+    entries: [],
+  });
+
+  let ok = 0;
+  let failed = 0;
+  let recovered = 0;
+  try {
+    /** @type {string[]} */
+    let failedPaths;
+    ({ ok, failed, failedPaths } = await crawl(origin, paths, concurrency));
+
+    // 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 firstOk = ok;
+      const firstFailed = failed;
+      const retry = await crawl(origin, failedPaths, 1, (retriedOk) => {
+        // Tekrar turunda her başarı bir hatayı başarıya çevirir.
+        prewarmProgress.ok = firstOk + retriedOk;
+        prewarmProgress.failed = firstFailed - retriedOk;
+      });
+      recovered = retry.ok;
+      ok += retry.ok;
+      failed -= retry.ok;
+    }
+  } finally {
+    prewarmProgress.active = false;
+    prewarmProgress.finishedAt = Date.now();
+  }
+  const elapsed = Date.now() - started;
+
+  if (!quiet && paths.length) {
+    const skipped = all.length - paths.length;
+    console.log(
+      `[prewarm] ${ok}/${paths.length} sayfa ısıtıldı` +
+        `${failed ? `, ${failed} hata` : ""}` +
+        `${recovered ? `, ${recovered} sayfa tekrar turunda kurtarıldı` : ""}` +
+        `${skipped > 0 ? `, ${skipped} sayfa limit dışı` : ""}` +
+        ` (${(elapsed / 1000).toFixed(1)}s)`,
+    );
+  }
+
+  return { ok, failed, total: paths.length, elapsed };
+}
+
+/**
+ * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır; isteğe
+ * bağlı olarak periyodik tekrarlar. Hiçbir hata süreci düşürmez.
+ *
+ * @param {{ port: number }} options
+ * @returns {void}
+ */
+export function startPrewarm({ port }) {
+  const config = getConfig();
+  if (process.env.PREWARM === "0") return;
+  if (process.env.PREWARM !== "1" && config.prewarm?.enabled === false) return;
+  // Isıtacak yol bildirmeyen bir projede zamanlayıcı kurmanın anlamı yok.
+  if (typeof config.hooks?.prewarmPaths !== "function") return;
+
+  const isDev = process.env.NODE_ENV === "development";
+  const origin = `http://127.0.0.1:${port}`;
+  const run = () =>
+    prewarm({ origin }).catch((error) => {
+      console.error("[prewarm] başarısız", error);
+    });
+
+  // Isıtma ilk isteklerle yarışmasın diye gecikmeyle başlar. Dev'de gecikme
+  // daha uzun: dosya kaydı süreci yeniden başlattığı için zamanlayıcı da
+  // ölür; yalnızca sunucu bir süre sakin kalınca ısınır.
+  const delay = setting("PREWARM_DELAY_MS", "delayMs", isDev ? 3000 : 500);
+  setTimeout(run, delay).unref();
+
+  // Girdiler `revalidate` ile yaşlanır; stale-while-revalidate sayesinde
+  // ziyaretçi beklemez. Periyodik tur, hiç ziyaret edilmeyen sayfaları da
+  // sıcak tutmak isteyen kurulumlar için opsiyoneldir.
+  const interval = setting("PREWARM_INTERVAL_SECONDS", "intervalSeconds", 0);
+  if (interval > 0) setInterval(run, interval * 1000).unref();
+}

package/src/server/render.js

@@ -0,0 +1,356 @@
+/**
+ * EJS render katmanı + HTML TTL cache (ISR ikamesi).
+ *
+ * Controller sözleşmesi:
+ *   async (ctx) => { view, data?, metadata?, status?, revalidate?, head?,
+ *                    bodyClass?, entries? }
+ * `ctx` → { params, query, pathname, req }
+ *
+ * `route()` üç kapsamı belirli bir sırayla iç içe kurar:
+ *   withHtmlCache( withUpstreamTracking( withRequestCache( controller ) ) )
+ * Sıra önemli — istek içi cache en içte olmalı ki aynı render'daki iki
+ * çağrı tek upstream isteğine düşsün; upstream takibi HTML cache'in içinde
+ * olmalı ki eksik veriyle üretilen çıktı önbelleğe yazılmasın.
+ */
+import path from "node:path";
+import process from "node:process";
+import ejs from "ejs";
+import { withHtmlCache } from "./html-cache.js";
+import { getConfig, hook } from "../config/index.js";
+import { matchPattern } from "../config/pattern.js";
+import { encodeText, negotiateEncoding } from "./middleware/compression.js";
+import { navigationHints, preconnectHints } from "./head-hints.js";
+import { withRequestCache } from "../http/request-cache.js";
+import { getUpstreamFailures, withUpstreamTracking } from "./upstream-tracking.js";
+import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
+import { renderHeadMeta } from "./metadata.js";
+import { asset, hasAsset } from "./assets.js";
+import * as html from "../views/helpers/html.js";
+import * as tags from "../views/helpers/tags.js";
+import { loadComponents } from "../views/components/loader.js";
+import { renderStatusPage } from "./status-page.js";
+
+const isDev = process.env.NODE_ENV === "development";
+
+/**
+ * Şablonlara otomatik geçen yardımcılar ve EJS ayarları. Bileşen taraması
+ * dosya sistemine dokunduğu için bir kez yapılır; config yüklenmeden
+ * hesaplanamaz, bu yüzden ilk render'da kurulur.
+ *
+ * @type {{ helpers: Record<string, unknown>, options: ejs.Options,
+ *   viewsDir: string, layout: string } | null}
+ */
+let engine = null;
+
+/**
+ * @returns {Promise<NonNullable<typeof engine>>}
+ */
+async function getEngine() {
+  if (engine) return engine;
+
+  const config = getConfig();
+  const viewsDir = config.dirs.views;
+
+  engine = {
+    viewsDir,
+    layout: config.layout,
+    helpers: {
+      ...html,
+      ...tags,
+      ...(await loadComponents(path.join(viewsDir, "components"))),
+      asset,
+      hasAsset,
+    },
+    options: {
+      // `include('partials/header')` gibi çağrılar views kökünden çözülür.
+      root: viewsDir,
+      views: [viewsDir],
+      cache: !isDev,
+      rmWhitespace: true,
+      async: true,
+    },
+  };
+
+  return engine;
+}
+
+/**
+ * Uygulama geliştirirken bileşen dosyaları değişince kayıt yenilenmeli.
+ * Dev sunucusu süreci yeniden başlattığı için normalde gerekmez; gömülü
+ * kullanımlar (test, script) için dışa açık.
+ *
+ * @returns {void}
+ */
+export function resetRenderEngine() {
+  engine = null;
+}
+
+/**
+ * Layout kullanmadan tek bir şablon render eder. Fragment/partial uçları
+ * ve e-posta şablonları bunu kullanır.
+ *
+ * @param {string} view `views/` altındaki yol, uzantısız (örn. "pages/home")
+ * @param {object} [data]
+ * @returns {Promise<string>}
+ */
+export async function renderView(view, data = {}) {
+  const { viewsDir, helpers, options } = await getEngine();
+  const file = path.join(viewsDir, `${view}.ejs`);
+  return ejs.renderFile(file, { ...helpers, ...data }, options);
+}
+
+/**
+ * Sayfayı layout içinde render eder.
+ *
+ * @param {{ view: string, data?: object, metadata?: object, head?: string,
+ *   bodyClass?: string, entries?: string[], pathname?: string }} page
+ * @returns {Promise<string>}
+ */
+export async function renderPage(page) {
+  const { helpers, options, layout } = await getEngine();
+  const config = getConfig();
+
+  const metadata = {
+    ...(await hook("metadata", {}, page)),
+    ...(page.metadata ?? {}),
+  };
+
+  // Layout bağlamı ve gövde paralel üretilir: navigasyon çoğu projede
+  // upstream'den geliyor ve gövde render'ıyla sırayla beklemek her sayfaya
+  // gereksiz gecikme ekliyor.
+  const [body, context] = await Promise.all([
+    renderView(page.view, { ...(page.data ?? {}), metadata }),
+    hook("layoutContext", {}, { pathname: page.pathname ?? "", metadata }),
+  ]);
+
+  return ejs.renderFile(
+    layout,
+    {
+      ...helpers,
+      ...context,
+      metadata,
+      // Boş varsayılan bilinçli: "/" yazmak her sayfayı ana sayfa sanıp
+      // logoyu <h1> olarak bastıran türde hatalara yol açıyor.
+      pathname: page.pathname ?? "",
+      lang: context.lang ?? config.brand.lang ?? "en",
+      headMeta: renderHeadMeta(metadata),
+      structuredData: context.structuredData ?? [],
+      // Preconnect her sayfada aynı; LCP preload'ını sayfa kendisi ekler.
+      // Gezinme ipuçları preconnect'ten sonra: spekülasyon bir sonraki sayfayı
+      // ilgilendiriyor, bu sayfanın LCP'sinin önüne geçmemeli.
+      extraHead:
+        preconnectHints() +
+        navigationHints() +
+        (page.head ?? "") +
+        (context.extraHead ?? ""),
+      bodyClass: page.bodyClass ?? context.bodyClass ?? "",
+      entries: page.entries ?? [],
+      devtools: isDev,
+      devBasePath: config.brand.devBasePath,
+      body,
+    },
+    options,
+  );
+}
+
+/**
+ * Controller'ı çalıştırıp yanıtı yazar; notFound/redirect kontrol akışını,
+ * HTML cache'ini ve hata yönetimini üstlenir.
+ *
+ * @param {(ctx: { params: object, query: object, pathname: string,
+ *   req: import('express').Request }) => Promise<object>} controller
+ * @param {{ revalidate?: number }} [options]
+ * @returns {import('express').RequestHandler}
+ */
+export function route(controller, options = {}) {
+  return async (req, res, next) => {
+    const ctx = {
+      params: req.params ?? {},
+      query: req.query ?? {},
+      pathname: req.path,
+      req,
+    };
+
+    const revalidate = resolveRevalidate(req.path, options.revalidate);
+    const cacheable = req.method === "GET" && Boolean(revalidate);
+    const cacheKey = `${req.path}?${new URLSearchParams(
+      Object.entries(ctx.query).map(([k, v]) => [k, String(v)]),
+    ).toString()}`;
+
+    try {
+      const result = await withHtmlCache(cacheKey, cacheable ? revalidate : 0, () =>
+        withUpstreamTracking(() => withRequestCache(() => produce(controller, ctx))),
+      );
+
+      res.status(result.status);
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      if (cacheable) {
+        res.setHeader(
+          "Cache-Control",
+          `public, max-age=0, s-maxage=${revalidate}, stale-while-revalidate=60`,
+        );
+      }
+      res.setHeader(
+        getConfig().brand.cacheHeader,
+        result.cached ? (result.stale ? "STALE" : "HIT") : "MISS",
+      );
+      await sendHtml(req, res, result.html, result.encoded);
+    } catch (error) {
+      if (isRedirectError(error)) {
+        res.redirect(error.statusCode, error.location);
+        return;
+      }
+      next(error);
+    }
+  };
+}
+
+/**
+ * `jskelet.config.mjs` → `cache().html` route'un kendi `revalidate`'ini ezer.
+ * Sonuç yol başına hatırlanır: her istekte desen taraması yapılmaz.
+ *
+ * @type {Map<string, number | undefined>}
+ */
+const revalidateByPath = new Map();
+
+/**
+ * Yakalayıcı bir route'ta (`/:slug`) her benzersiz yol burada kalıcı bir girdi
+ * bırakıyor; sınır olmadan bu, uzun ömürlü süreçte bellek sızıntısına dönüşür.
+ * Desen taraması ucuz olduğu için en eski girdileri atmak güvenli.
+ */
+const REVALIDATE_CACHE_MAX = 2000;
+
+/**
+ * @param {string} pathname
+ * @param {number | undefined} fallback
+ * @returns {number | undefined}
+ */
+function resolveRevalidate(pathname, fallback) {
+  const rules = getConfig().html;
+  if (!rules.length) return fallback;
+
+  if (revalidateByPath.has(pathname)) {
+    return revalidateByPath.get(pathname) ?? fallback;
+  }
+
+  const match = rules.find((rule) => matchPattern(rule.pattern, pathname));
+
+  if (revalidateByPath.size >= REVALIDATE_CACHE_MAX) {
+    const oldest = revalidateByPath.keys().next().value;
+    if (oldest !== undefined) revalidateByPath.delete(oldest);
+  }
+
+  revalidateByPath.set(pathname, match?.seconds);
+  return match ? match.seconds : fallback;
+}
+
+/**
+ * Cache'lenmiş bir sayfa aynı gövdeyi her istekte yeniden sıkıştırmasın diye
+ * brotli/gzip çıktısı HTML ile birlikte saklanır. `Content-Encoding` burada
+ * ayarlandığı için sıkıştırma middleware'i devreye girmez.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {string} body
+ * @param {Map<string, Buffer>} [encoded]
+ * @returns {Promise<void>}
+ */
+async function sendHtml(req, res, body, encoded) {
+  const encoding =
+    req.method === "HEAD" ? null : negotiateEncoding(req.headers["accept-encoding"]);
+
+  if (!encoding || !encoded) {
+    res.send(body);
+    return;
+  }
+
+  let buffer = encoded.get(encoding);
+  if (!buffer) {
+    buffer = await encodeText(body, encoding);
+    encoded.set(encoding, buffer);
+  }
+
+  res.setHeader("Content-Encoding", encoding);
+  res.setHeader("Vary", "Accept-Encoding");
+  res.setHeader("Content-Length", String(buffer.length));
+  res.end(buffer);
+}
+
+/**
+ * @param {Function} controller
+ * @param {{ pathname: string }} ctx
+ * @returns {Promise<{ html: string, status: number, degraded?: boolean }>}
+ */
+async function produce(controller, ctx) {
+  try {
+    const page = await controller(ctx);
+    const rendered = await renderPage({ pathname: ctx.pathname, ...page });
+    return {
+      html: rendered,
+      status: page.status ?? 200,
+      degraded: hasUpstreamFailures(ctx.pathname),
+    };
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return { html: await renderNotFound(), status: 404 };
+    }
+    throw error;
+  }
+}
+
+/** Ağ hatası (0) ve geçici olduğu varsayılan durumlar. */
+const TRANSIENT_STATUSES = new Set([0, 408, 425, 429]);
+
+/** @param {number} status */
+function isTransient(status) {
+  return TRANSIENT_STATUSES.has(status) || status >= 500;
+}
+
+/**
+ * Render sırasında upstream düştüyse çıktı eksik veri içeriyor demektir.
+ * Böyle bir HTML önbelleğe yazılmaz: sonraki istek yeniden dener.
+ *
+ * Ancak yalnızca *geçici* hatalar için. 400/403/404 gibi deterministik
+ * cevaplar tekrar denemekle düzelmez; onlar yüzünden önbelleği kapatmak
+ * sayfayı her ziyarette baştan render etmek olur — içerik yine aynı eksik
+ * hâliyle döner, ziyaretçi sadece render süresini öder. Bu yüzden kalıcı
+ * hatalar yalnızca loglanır, önbelleği engellemez.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function hasUpstreamFailures(pathname) {
+  const failures = getUpstreamFailures();
+  if (!failures.length) return false;
+
+  /** @param {typeof failures} list */
+  const summarize = (list) =>
+    list.map((failure) => `${failure.status} ${failure.path}`).join(", ");
+
+  const transient = failures.filter((failure) => isTransient(failure.status));
+  const permanent = failures.filter((failure) => !isTransient(failure.status));
+
+  if (permanent.length) {
+    console.warn(
+      `[render] ${pathname} eksik veriyle üretildi, upstream kalıcı hata veriyor (${summarize(permanent)})`,
+    );
+  }
+
+  if (!transient.length) return false;
+
+  console.warn(
+    `[render] ${pathname} eksik veriyle üretildi, önbelleğe alınmıyor (${summarize(transient)})`,
+  );
+
+  return true;
+}
+
+/**
+ * 404 sayfası. `renderStatusPage(404)` için kısayol; route dosyalarında en sık
+ * ihtiyaç duyulan durum bu olduğu için ayrı bir ad taşımaya devam ediyor.
+ *
+ * @returns {Promise<string>}
+ */
+export async function renderNotFound() {
+  return renderStatusPage(404);
+}