jskelet 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -87,12 +87,14 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
-- Request errors raised during a prewarm pass are no longer logged one by one.
-  They are counted while the pass runs and printed as a single summary line
-  afterwards, grouped by status and message with the most frequent kinds first,
-  so a flaky upstream can no longer bury the "warmed N/M pages" line under
-  hundreds of stack traces. Errors from real traffic are logged as before, and
-  the dev tools panel still shows the per-path detail.
+- Errors and warnings raised during a prewarm pass are no longer logged one per
+  page. Request errors and the per-page render warnings (`was produced with
+  missing data`, `returned notFound() while upstream is failing`, `could not be
+  produced`) are counted while the pass runs and printed as a single summary
+  block afterwards, grouped by message with the most frequent kinds first, so a
+  failing upstream can no longer bury the "warmed N/M pages" line under hundreds
+  of near-identical lines. Real traffic logs as before, and the dev tools panel
+  still shows the per-path detail.
 - The marketing example's changelog page is now a timeline: releases are laid out
   along a rail with a sticky version column, each change group gets its own card
   with a coloured rule and item count, and a row of version chips at the top

package/docs/06-cache.md

@@ -706,13 +706,15 @@ Kurallar:
 5. Özet loglanır:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
-Tur sırasında oluşan istek hataları tek tek loglanmaz; sayılır ve tur bitince
-özetin ardından tek bir satırda, en sık görülen türler başta olacak şekilde
-basılır:
+Tur sırasında oluşan istek hataları ve sayfa başına basılan render uyarıları
+(`was produced with missing data`, `returned notFound() while upstream is
+failing`, `could not be produced`) tek tek loglanmaz; sayılır ve tur bitince
+özetin ardından, en sık görülen türler başta olacak şekilde basılır:
 
 ```text
-[prewarm] 37 request errors were not logged individually:
-  31× 502 upstream fetch failed: /api/quotes
+[prewarm] 137 problems were not logged individually:
+  94× missing data, upstream is failing permanently (403 /api/v1/polls)
+  37× missing data, upstream is failing permanently (400 /api/v1/posts)
   6× 500 Cannot read properties of undefined (reading 'title')
 ```
 

package/docs/en/06-caching.md

@@ -727,13 +727,15 @@ Rules:
 5. A summary is logged:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
-Request errors raised during the pass are not logged one by one. They are
-counted while the pass runs and printed after the summary as a single line,
-grouped by status and message with the most frequent kinds first:
+Request errors and the per-page render warnings (`was produced with missing
+data`, `returned notFound() while upstream is failing`, `could not be
+produced`) raised during the pass are not logged one by one. They are counted
+while the pass runs and printed after the summary, most frequent kinds first:
 
 ```text
-[prewarm] 37 request errors were not logged individually:
-  31× 502 upstream fetch failed: /api/quotes
+[prewarm] 137 problems were not logged individually:
+  94× missing data, upstream is failing permanently (403 /api/v1/polls)
+  37× missing data, upstream is failing permanently (400 /api/v1/posts)
   6× 500 Cannot read properties of undefined (reading 'title')
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/server/prewarm.js

@@ -20,6 +20,7 @@
  */
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
+import { getRequestContext } from "../http/request-context.js";
 import { takeInvalidatedPaths } from "./html-cache.js";
 
 /**
@@ -45,11 +46,13 @@ export const prewarmProgress = {
 };
 
 /**
- * Isıtma turu sırasında bastırılan istek hataları: mesaj → kaç kez görüldü.
+ * Isıtma turu sırasında bastırılan uyarılar: mesaj → kaç kez görüldü.
  *
  * Yüzlerce yolu tarayan bir tur, upstream bir an için tıksırdığında yüzlerce
- * yığın izini loga döküyor ve asıl bilgi (kaç sayfa ısındı) kayboluyor. Tur
- * boyunca hatalar burada toplanır, tur bitince tek satırda özetlenir.
+ * satır loga döküyor ve asıl bilgi (kaç sayfa ısındı) kayboluyor. Tur boyunca
+ * mesajlar burada toplanır, tur bitince tek satırda özetlenir. Yol adı
+ * anahtara girmez: gruplanabilmesi için mesajın kendisi yeterli, tek bir yolun
+ * ayrıntısı zaten `entries` üzerinden dev panelinde görünüyor.
  * @type {Map<string, number>}
  */
 const suppressed = new Map();
@@ -59,19 +62,41 @@ const suppressed = new Map();
  * ısıtmanın user-agent'ıyla geldiğinde doğru; gerçek trafiğin hataları her
  * zaman loglanmaya devam eder.
  *
- * @param {{ get?: (name: string) => string | undefined }} req
+ * @param {{ get?: (name: string) => string | undefined } | null | undefined} req
  * @returns {boolean}
  */
 export function isPrewarmRequest(req) {
-  if (!prewarmProgress.active) return false;
+  if (!prewarmProgress.active || !req) return false;
   const ua = req.get?.("user-agent");
   return Boolean(ua) && ua === getConfig().brand.prewarmUserAgent;
 }
 
 /**
- * Bastırılan bir hatayı sayaca ekler. Yığın izi saklanmaz: özet satırının
- * amacı "neyin bozulduğunu" göstermek, hatayı ayıklamak değil — tek bir yol
- * için ayrıntı isteyen dev paneli `entries` üzerinden bakar.
+ * Şu an işlenen istek ısıtma turuna mı ait? `req` elde olmayan derin
+ * katmanlar (render, cache) için: yanıt nesnesi istek bağlamında taşınıyor.
+ *
+ * @returns {boolean}
+ */
+function inPrewarmRequest() {
+  if (!prewarmProgress.active) return false;
+  return isPrewarmRequest(getRequestContext()?.res?.req);
+}
+
+/**
+ * Isıtma turuna ait bir uyarıyı loglamak yerine sayar.
+ *
+ * @param {string} message Gruplama anahtarı; yol adı içermemeli.
+ * @returns {boolean} `true` ise sayıldı, çağıran taraf loglamamalı.
+ */
+export function suppressForPrewarm(message) {
+  if (!inPrewarmRequest()) return false;
+  suppressed.set(message, (suppressed.get(message) ?? 0) + 1);
+  return true;
+}
+
+/**
+ * Bastırılan bir istek hatasını sayaca ekler. Yığın izi saklanmaz: özet
+ * satırının amacı "neyin bozulduğunu" göstermek, hatayı ayıklamak değil.
  *
  * @param {number} status
  * @param {unknown} error
@@ -439,7 +464,7 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
       const total = ranked.reduce((sum, [, n]) => sum + n, 0);
 
       console.warn(
-        `[prewarm] ${total} request error${total === 1 ? "" : "s"} were not logged individually:\n` +
+        `[prewarm] ${total} problem${total === 1 ? " was" : "s were"} not logged individually:\n` +
           shown.map(([message, n]) => `  ${n}× ${message}`).join("\n") +
           (rest ? `\n  … ${rest} more in ${ranked.length - shown.length} other kinds` : ""),
       );

package/src/server/render.js

@@ -39,6 +39,7 @@ 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";
+import { suppressForPrewarm } from "./prewarm.js";
 
 const isDev = process.env.NODE_ENV === "development";
 
@@ -530,10 +531,12 @@ async function produce(controller, ctx) {
   let failures = first.transient;
 
   for (let round = 1; round <= attempts; round += 1) {
-    console.warn(
-      `[render] ${ctx.pathname} returned notFound() while upstream is failing ` +
-        `(${summarizeFailures(failures)}), retrying (${round}/${attempts})`,
-    );
+    const retryDetail =
+      `returned notFound() while upstream is failing ` +
+      `(${summarizeFailures(failures)}), retrying (${round}/${attempts})`;
+    if (!suppressForPrewarm(retryDetail)) {
+      console.warn(`[render] ${ctx.pathname} ${retryDetail}`);
+    }
 
     // Beklemeden tekrar denemek rate limit'e girmiş bir API'de aynı 429'u
     // getirir; kısa bekleme hem pencerenin dönmesine şans verir hem de
@@ -558,10 +561,12 @@ async function produce(controller, ctx) {
 
   // Denemeler tükendi. 404 yerine 503: önbelleğe girmez, `Retry-After` taşır
   // ve bir sonraki istek gerçek içeriği üretebilir.
-  console.warn(
-    `[render] ${ctx.pathname} could not be produced, upstream is still failing ` +
-      `(${summarizeFailures(failures)}), serving an uncached 503 instead of a 404`,
-  );
+  const outageDetail =
+    `could not be produced, upstream is still failing ` +
+    `(${summarizeFailures(failures)}), serving an uncached 503 instead of a 404`;
+  if (!suppressForPrewarm(outageDetail)) {
+    console.warn(`[render] ${ctx.pathname} ${outageDetail}`);
+  }
 
   return {
     html: await renderStatusPage(503),
@@ -624,17 +629,22 @@ function hasUpstreamFailures(pathname) {
   const transient = failures.filter((failure) => isTransientStatus(failure.status));
   const permanent = failures.filter((failure) => !isTransientStatus(failure.status));
 
+  // Isıtma turu yüzlerce yolu tarıyor; aynı upstream arızası her yol için bir
+  // satır basınca tur özeti kayboluyor. Turun uyarıları sayılıp sonunda
+  // toplanır (bkz. `suppressForPrewarm`).
   if (permanent.length) {
-    console.warn(
-      `[render] ${pathname} was produced with missing data, upstream is failing permanently (${summarizeFailures(permanent)})`,
-    );
+    const detail = `missing data, upstream is failing permanently (${summarizeFailures(permanent)})`;
+    if (!suppressForPrewarm(detail)) {
+      console.warn(`[render] ${pathname} was produced with ${detail}`);
+    }
   }
 
   if (!transient.length) return false;
 
-  console.warn(
-    `[render] ${pathname} was produced with missing data, not caching it (${summarizeFailures(transient)})`,
-  );
+  const detail = `missing data, not caching it (${summarizeFailures(transient)})`;
+  if (!suppressForPrewarm(detail)) {
+    console.warn(`[render] ${pathname} was produced with ${detail}`);
+  }
 
   return true;
 }