jskelet 0.1.3 → 0.1.5

package/src/server/render.js

@@ -27,7 +27,11 @@ import {
   guardRequest,
   withRequestContext,
 } from "../http/request-context.js";
-import { getUpstreamFailures, withUpstreamTracking } from "./upstream-tracking.js";
+import {
+  getUpstreamFailures,
+  isTransientStatus,
+  withUpstreamTracking,
+} from "./upstream-tracking.js";
 import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
 import { renderHeadMeta } from "./metadata.js";
 import { asset, hasAsset } from "./assets.js";
@@ -471,49 +475,100 @@ async function sendHtml(req, res, body, encoded, options = {}) {
 }
 
 /**
+ * @typedef {{ html: string, status: number, degraded?: boolean,
+ *   storable?: boolean, retryAfter?: number }} Produced
+ */
+
+/**
+ * Controller'ı bir kez çalıştırır. `notFound()` fırlatıldığında sonucu
+ * ayırt edilebilir biçimde döner: çağıran taraf bunun gerçek bir 404 mü,
+ * yoksa upstream düştüğü için verinin gelmemesi mi olduğuna karar verecek.
+ *
  * @param {Function} controller
  * @param {{ pathname: string }} ctx
- * @returns {Promise<{ html: string, status: number, degraded?: boolean,
- *   storable?: boolean, retryAfter?: number }>}
+ * @returns {Promise<{ page: Produced } | { notFound: true,
+ *   transient: import('./upstream-tracking.js').UpstreamFailure[] }>}
  */
-async function produce(controller, ctx) {
+async function attempt(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),
-      // Kimliğe bağlı çıktı önbelleğe yazılmaz. Karar burada verilmeli:
-      // `withHtmlCache` yazma anında controller'ın ne okuduğunu bilemez.
-      storable: getRequestContext()?.tainted !== true,
+      page: {
+        html: rendered,
+        status: page.status ?? 200,
+        degraded: hasUpstreamFailures(ctx.pathname),
+        // Kimliğe bağlı çıktı önbelleğe yazılmaz. Karar burada verilmeli:
+        // `withHtmlCache` yazma anında controller'ın ne okuduğunu bilemez.
+        storable: getRequestContext()?.tainted !== true,
+      },
     };
   } catch (error) {
     if (isNotFoundError(error)) {
-      // Veri gelmediği için `notFound()` çağrılmış olabilir: geçici bir
-      // upstream hatası (429, 5xx, ağ) varken bunu 404 olarak servis etmek iki
-      // kere yanlış. Önbelleğe girip TTL boyunca "bu sayfa yok" cevabını
-      // sabitler ve arama motoru geçici bir rate limit'i kalıcı 404 sanar.
-      // Doğrusu 503: cache'lenmez, `Retry-After` ile gider, sonraki istek
-      // gerçek içeriği üretir.
-      const transient = transientUpstreamFailures();
-      if (transient.length) {
-        console.warn(
-          `[render] ${ctx.pathname} returned notFound() while upstream is failing ` +
-            `(${summarizeFailures(transient)}), serving an uncached 503 instead`,
-        );
-        return {
-          html: await renderStatusPage(503),
-          status: 503,
-          degraded: true,
-          retryAfter: RETRY_AFTER_SECONDS,
-        };
-      }
+      return { notFound: true, transient: transientUpstreamFailures() };
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {Function} controller
+ * @param {{ pathname: string }} ctx
+ * @returns {Promise<Produced>}
+ */
+async function produce(controller, ctx) {
+  const first = await attempt(controller, ctx);
+  if ("page" in first) return first.page;
+  // Deterministik "böyle bir sayfa yok" cevabı: tekrar denemenin anlamı yok.
+  if (!first.transient.length) return { html: await renderNotFound(), status: 404 };
+
+  // Buraya gelindiyse `notFound()` veri gelmediği için çağrılmış. **Var olan
+  // bir sayfayı** 404 olarak servis etmek en kötü sonuç: arama motoru geçici
+  // bir rate limit'i kalıcı bir kayıp sanar. Bu yüzden sayfa yeniden denenir —
+  // ısıtma günlükleri gösteriyor ki aynı yol saniyeler sonra 200 dönüyor.
+  const { attempts, delayMs } = transientRetry();
+  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})`,
+    );
+
+    // 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
+    // fırtınayı büyütmez.
+    await sleep(delayMs * round);
+
+    // Her deneme kendi upstream ve istek içi cache bağlamında çalışır: ilk
+    // turun hataları ikinci turun kararını kirletmesin ve memoize edilmiş
+    // boş cevaplar tekrar kullanılmasın.
+    const retried = await withUpstreamTracking(() =>
+      withRequestCache(() => attempt(controller, ctx)),
+    );
 
+    if ("page" in retried) return retried.page;
+    if (!retried.transient.length) {
+      // Bu kez upstream sağlam cevap verdi ve "yok" dedi: gerçek 404.
       return { html: await renderNotFound(), status: 404 };
     }
-    throw error;
+
+    failures = retried.transient;
   }
+
+  // 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`,
+  );
+
+  return {
+    html: await renderStatusPage(503),
+    status: 503,
+    degraded: true,
+    retryAfter: RETRY_AFTER_SECONDS,
+  };
 }
 
 /**
@@ -523,14 +578,32 @@ async function produce(controller, ctx) {
  */
 const RETRY_AFTER_SECONDS = 30;
 
-/** Ağ hatası (0) ve geçici olduğu varsayılan durumlar. */
-const TRANSIENT_STATUSES = new Set([0, 408, 425, 429]);
+/**
+ * Tekrar denemenin maliyeti upstream'e binen ikinci bir istek turu; bu yüzden
+ * varsayılan tek deneme ve kısa bekleme. Rate limit fırtınasında toplam yük
+ * iki katına çıkabilir, ama alternatifi var olan sayfaları 404'e düşürmek.
+ *
+ * @returns {{ attempts: number, delayMs: number }}
+ */
+function transientRetry() {
+  const raw = /** @type {any} */ (getConfig().transientRetry ?? {});
+  const attempts = Number(raw.attempts);
+  const delayMs = Number(raw.delayMs);
+
+  return {
+    attempts: Number.isFinite(attempts) && attempts >= 0 ? Math.floor(attempts) : 1,
+    delayMs: Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : 300,
+  };
+}
 
-/** @param {number} status */
-function isTransient(status) {
-  return TRANSIENT_STATUSES.has(status) || status >= 500;
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
 }
 
+
 /**
  * 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.
@@ -548,8 +621,8 @@ function hasUpstreamFailures(pathname) {
   const failures = getUpstreamFailures();
   if (!failures.length) return false;
 
-  const transient = failures.filter((failure) => isTransient(failure.status));
-  const permanent = failures.filter((failure) => !isTransient(failure.status));
+  const transient = failures.filter((failure) => isTransientStatus(failure.status));
+  const permanent = failures.filter((failure) => !isTransientStatus(failure.status));
 
   if (permanent.length) {
     console.warn(
@@ -570,7 +643,7 @@ function hasUpstreamFailures(pathname) {
  * @returns {import('./upstream-tracking.js').UpstreamFailure[]}
  */
 function transientUpstreamFailures() {
-  return getUpstreamFailures().filter((failure) => isTransient(failure.status));
+  return getUpstreamFailures().filter((failure) => isTransientStatus(failure.status));
 }
 
 /**

package/src/server/upstream-tracking.js

@@ -1,22 +1,25 @@
 /**
  * Render başına upstream API hatalarını toplar.
  *
- * `render.js` her sayfayı bu bağlam içinde üretir; uygulamanın HTTP istemcisi
- * başarısız bir upstream yanıtında `reportUpstreamFailure()` çağırır. Böylece
- * HTML önbelleği "bu çıktı eksik veriyle üretildi" bilgisine sahip olur ve
- * bozuk sayfayı saklamaz.
+ * `render.js` her sayfayı bu bağlam içinde üretir. Böylece HTML önbelleği "bu
+ * çıktı eksik veriyle üretildi" bilgisine sahip olur ve bozuk sayfayı saklamaz;
+ * `notFound()` de geçici bir hataya denk geldiğinde 404 olmaktan çıkar.
  *
- * Bağımlılık yönü bilinçli olarak tersine çevrilmiş: framework veri katmanını
- * tanımaz, veri katmanı framework'e haber verir. Hiç çağıran olmazsa maliyet
- * boş bir dizidir.
+ * Bilgi iki yoldan gelir:
  *
- * Kullanım (uygulamanın `lib/api/client.js` içinde):
+ *   1. **Otomatik** — `trackUpstreamFetch()` `globalThis.fetch`i sarar ve
+ *      geçici hataları (429, 5xx, ağ) kendiliğinden bildirir. `createApp()`
+ *      bunu açılışta kurar, yani hiçbir uygulama kodu gerekmez.
+ *   2. **Elle** — `fetch` kullanmayan bir istemci (veritabanı sürücüsü, gRPC,
+ *      SDK) için:
  *
- *   import { reportUpstreamFailure } from "jskelet/server";
+ *        import { reportUpstreamFailure } from "jskelet";
  *
- *   if (!response.ok) {
- *     reportUpstreamFailure({ status: response.status, path: url });
- *   }
+ *        if (!response.ok) {
+ *          reportUpstreamFailure({ status: response.status, path: url });
+ *        }
+ *
+ * İki yol aynı hatayı bildirirse tekilleştirilir.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -33,7 +36,94 @@ const storage = new AsyncLocalStorage();
  * @returns {void}
  */
 export function reportUpstreamFailure(failure) {
-  storage.getStore()?.failures.push(failure);
+  const store = storage.getStore();
+  if (!store) return;
+
+  // Aynı hatayı hem otomatik sarmalayıcı hem uygulamanın istemcisi
+  // bildirebilir; aynı satırı iki kez loglamanın faydası yok.
+  const duplicate = store.failures.some(
+    (existing) => existing.status === failure.status && existing.path === failure.path,
+  );
+  if (!duplicate) store.failures.push(failure);
+}
+
+/**
+ * Geçici sayılan durumlar: tekrar denemekle düzelebilenler. Bu liste
+ * `render.js` ile paylaşılır — hangi hatanın önbelleği engellediği ve hangi
+ * hatanın `notFound()`u 404 olmaktan çıkardığı tek yerde tanımlı olsun.
+ */
+const TRANSIENT_STATUSES = new Set([0, 408, 425, 429]);
+
+/**
+ * @param {number} status
+ * @returns {boolean}
+ */
+export function isTransientStatus(status) {
+  return TRANSIENT_STATUSES.has(status) || status >= 500;
+}
+
+/**
+ * `globalThis.fetch`i sarıp **geçici** upstream hatalarını kendiliğinden
+ * bildirir.
+ *
+ * Gerekçesi pratik: `reportUpstreamFailure()` sözleşmesi uygulamanın HTTP
+ * istemcisine bir satır eklemeyi gerektiriyor ve o satır yazılmadığında
+ * framework rate limit'i hiç göremiyor — veri gelmediği için `notFound()`
+ * çağıran sayfa 404 olarak servis ediliyordu. Otomatik izleme bu bilgiyi
+ * varsayılan hâle getirir; elle çağrı hâlâ geçerli ve tekilleştirilir.
+ *
+ * Yalnızca geçici durumlar bildirilir. `404`/`403` gibi deterministik
+ * cevaplar birçok API'de "böyle bir kayıt yok" anlamına geliyor ve onları
+ * otomatik olarak "eksik veri" saymak her sayfada yanlış uyarı üretirdi.
+ *
+ * Kendi sunucumuza yapılan istekler atlanır: ısıtma turu ve sağlık kontrolü
+ * upstream değil.
+ *
+ * @returns {void}
+ */
+export function trackUpstreamFetch() {
+  const original = globalThis.fetch;
+  if (/** @type {any} */ (original).__jskeletUpstreamTracked) return;
+
+  /** @type {typeof fetch} */
+  const wrapped = async (input, init) => {
+    // İstek bir render bağlamı içinde değilse (script, zamanlayıcı) hiçbir
+    // şey yapılmaz: sarmalayıcının maliyeti bir `getStore()` çağrısı.
+    if (!storage.getStore()) return original(input, init);
+
+    const url = requestUrl(input);
+    if (isSelfRequest(url)) return original(input, init);
+
+    try {
+      const response = await original(input, init);
+      if (!response.ok && isTransientStatus(response.status)) {
+        reportUpstreamFailure({ status: response.status, path: url });
+      }
+      return response;
+    } catch (error) {
+      // Yanıt hiç gelmedi: ağ hatası her zaman geçicidir.
+      reportUpstreamFailure({ status: 0, path: url });
+      throw error;
+    }
+  };
+
+  /** @type {any} */ (wrapped).__jskeletUpstreamTracked = true;
+  globalThis.fetch = wrapped;
+}
+
+/**
+ * @param {RequestInfo | URL} input
+ * @returns {string}
+ */
+function requestUrl(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.href;
+  return /** @type {Request} */ (input)?.url ?? String(input);
+}
+
+/** @param {string} url */
+function isSelfRequest(url) {
+  return /^https?:\/\/(127\.0\.0\.1|\[::1\]|localhost)(:|\/|$)/i.test(url);
 }
 
 /**