jskelet 0.4.6 → 0.4.8

package/src/server/dev/devtools.js

@@ -13,6 +13,7 @@ import { createHash } from "node:crypto";
 import express from "express";
 import * as log from "../../log.mjs";
 import { FRAMEWORK_ROOT, getConfig } from "../../config/index.js";
+import { getRequestContext } from "../../http/request-context.js";
 import { prewarm, prewarmProgress } from "../prewarm.js";
 import { clearHtmlCache } from "../html-cache.js";
 import {
@@ -55,7 +56,21 @@ const STATE_FILE = path.join(
 /** @type {{ id: number, method: string, url: string, status: number, ms: number, cache: string | null, at: number }[]} */
 let requests = [];
 
-/** @type {{ id: number, level: string, message: string, stack: string | null, url: string | null, at: number }[]} */
+/**
+ * @typedef {{
+ *   id: number,
+ *   level: string,
+ *   message: string,
+ *   stack: string | null,
+ *   url: string | null,
+ *   page: string | null,
+ *   island: string | null,
+ *   details: unknown,
+ *   at: number,
+ * }} ServerError
+ */
+
+/** @type {ServerError[]} */
 let errors = [];
 
 let nextId = 1;
@@ -103,7 +118,13 @@ function trim(list) {
 /**
  * @param {string} level
  * @param {string} message
- * @param {{ stack?: string | null, url?: string | null }} [extra]
+ * @param {{
+ *   stack?: string | null,
+ *   url?: string | null,
+ *   page?: string | null,
+ *   island?: string | null,
+ *   details?: unknown,
+ * }} [extra]
  */
 export function recordServerError(level, message, extra = {}) {
   errors.push({
@@ -112,6 +133,9 @@ export function recordServerError(level, message, extra = {}) {
     message,
     stack: extra.stack ?? null,
     url: extra.url ?? null,
+    page: extra.page ?? null,
+    island: extra.island ?? null,
+    details: extra.details ?? null,
     at: Date.now(),
   });
   trim(errors);
@@ -121,21 +145,49 @@ export function recordServerError(level, message, extra = {}) {
 
 /**
  * `console.error` / `console.warn` çıktısını da overlay'e taşır: sunucudaki
- * uyarılar terminalde kaybolmasın.
+ * uyarılar terminalde kaybolmasın. Render bağlamındaysa sayfa yolu da yazılır.
  */
 function patchConsole() {
   for (const level of /** @type {const} */ (["error", "warn"])) {
     const original = console[level].bind(console);
     console[level] = (...args) => {
       const error = args.find((arg) => arg instanceof Error);
+      const page = currentPage();
       recordServerError(level, args.map(format).join(" "), {
         stack: error?.stack ?? null,
+        page,
+        url: page,
+        details: extractDetails(args),
       });
       original(...args);
     };
   }
 }
 
+/** @returns {string | null} */
+function currentPage() {
+  return getRequestContext()?.pathname ?? null;
+}
+
+/**
+ * console argümanlarından yapılandırılmış bir `details` alanı ayıklar.
+ * Uygulama `console.error("msg", { details: {...} })` yazdığında overlay
+ * nesneyi `[object Object]` yerine açılabilir JSON olarak görsün.
+ *
+ * @param {unknown[]} args
+ * @returns {unknown}
+ */
+function extractDetails(args) {
+  for (const arg of args) {
+    if (!arg || typeof arg !== "object" || arg instanceof Error) continue;
+    const record = /** @type {Record<string, unknown>} */ (arg);
+    if ("details" in record) return record.details;
+    if ("detail" in record) return record.detail;
+    return record;
+  }
+  return null;
+}
+
 /**
  * @param {unknown} value
  * @returns {string}
@@ -144,12 +196,73 @@ function format(value) {
   if (typeof value === "string") return value;
   if (value instanceof Error) return `${value.name}: ${value.message}`;
   try {
-    return JSON.stringify(value);
+    return JSON.stringify(value, (_key, nested) => {
+      // Döngüsel referanslarda stringify zaten fırlar; burada yalnızca
+      // Error örneklerini okunabilir kılmak yeterli.
+      if (nested instanceof Error) {
+        return { name: nested.name, message: nested.message };
+      }
+      return nested;
+    });
   } catch {
     return String(value);
   }
 }
 
+/**
+ * Upstream `fetch` başarısızlığını overlay hata listesine yazar.
+ *
+ * @param {{
+ *   url: string,
+ *   method: string,
+ *   status: number,
+ *   ms: number,
+ *   bytes: number,
+ *   error: string | null,
+ *   page: string | null,
+ *   details: unknown,
+ * }} call
+ */
+function recordApiFailure(call) {
+  // Aynı SSR turunda hem fetch sarmalayıcısı hem uygulama logger'ı aynı
+  // hatayı basabiliyor; kısa pencerede tekilleştir.
+  const last = errors.at(-1);
+  if (
+    last &&
+    last.url === call.url &&
+    last.page === call.page &&
+    Date.now() - last.at < 2000
+  ) {
+    // İlk kayıtta details yoksa sonrakinin gövdesini birleştir.
+    if (last.details == null && call.details != null) {
+      last.details = call.details;
+      if (call.error && !last.message.includes(call.error)) {
+        last.message = `${call.method} ${shortApiPath(call.url)} → ${call.error}`;
+      }
+      persist();
+      pushStats();
+    }
+    return;
+  }
+
+  recordServerError("error", `${call.method} ${shortApiPath(call.url)} → ${call.error ?? call.status}`, {
+    url: call.url,
+    page: call.page,
+    details: call.details,
+    stack: null,
+  });
+}
+
+/** @param {string} url */
+function shortApiPath(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.pathname + parsed.search;
+  } catch {
+    return url;
+  }
+}
+
 /** Her HTML isteğinin süresini ve cache durumunu kaydeder. */
 function timing() {
   /** @type {import('express').RequestHandler} */
@@ -448,7 +561,7 @@ export function mountDevtools(app) {
 
   restore();
   patchConsole();
-  trackServerFetch();
+  trackServerFetch({ onFailure: recordApiFailure });
   watchManifest();
   startVersionCheck();
   startHeartbeat();

package/src/server/dev/report.js

@@ -18,6 +18,7 @@ import { getRedisStatus } from "../redis.js";
 import { getUpstreamLimiterStatus } from "../upstream-limiter.js";
 import { prewarmProgress } from "../prewarm.js";
 import { getConfig } from "../../config/index.js";
+import { getRequestContext } from "../../http/request-context.js";
 
 /** Yollar config'ten: framework paket içine taşındığında `../..` sayan her hesap bozulur. */
 const ROOT = getConfig().root;
@@ -78,61 +79,176 @@ export function clearPageReports() {
 /* --------------------------------------------------- sunucu tarafı API çağrıları */
 
 /**
- * @type {{ url: string, host: string, method: string, status: number, ms: number,
- *   bytes: number, at: number, error: string | null }[]}
+ * @typedef {{
+ *   url: string,
+ *   host: string,
+ *   method: string,
+ *   status: number,
+ *   ms: number,
+ *   bytes: number,
+ *   at: number,
+ *   error: string | null,
+ *   page: string | null,
+ *   details: unknown,
+ * }} ServerApiCall
  */
+
+/** @type {ServerApiCall[]} */
 const serverApiCalls = [];
 const MAX_API_CALLS = 300;
 
+/** Başarısız çağrı gövdesinin overlay'e taşınacak üst sınırı. */
+const DETAILS_MAX = 4_000;
+
+/**
+ * @typedef {{
+ *   url: string,
+ *   method: string,
+ *   status: number,
+ *   ms: number,
+ *   bytes: number,
+ *   error: string | null,
+ *   page: string | null,
+ *   details: unknown,
+ * }} ApiFailure
+ */
+
 /**
  * SSR sırasında yapılan dış çağrıları ölçer. `globalThis.fetch` sarılır;
  * yalnızca dev'de çağrıldığı için üretim yolu dokunulmaz kalır.
+ *
+ * Başarısız cevaplar (4xx/5xx ya da ağ) isteğe bağlı `onFailure` ile
+ * overlay hata günlüğüne de düşer — uygulama kendi logger'ıyla stderr'e
+ * yazsa bile panel "hangi sayfa hangi API" bilgisini görsün.
+ *
+ * @param {{ onFailure?: (call: ApiFailure) => void }} [options]
  */
-export function trackServerFetch() {
+export function trackServerFetch(options = {}) {
   const original = globalThis.fetch;
-  if (original.__jskeletWrapped) return;
+  if (/** @type {any} */ (original).__jskeletWrapped) return;
+
+  const { onFailure } = options;
 
   /** @type {typeof fetch} */
   const wrapped = async (input, init) => {
     const url = typeof input === "string" ? input : (input?.url ?? String(input));
+    const method = String(init?.method ?? "GET").toUpperCase();
     const started = Date.now();
+    const page = currentPage();
 
     // Kendi sunucumuza yapılan istekler (ısıtma, sağlık kontrolü) API sayılmaz.
-    const isSelf = /^https?:\/\/(127\.0\.0\.1|localhost)/i.test(url);
+    const isSelf = /^https?:\/\/(127\.0\.0\.1|\[::1\]|localhost)(:|\/|$)/i.test(url);
 
     try {
       const response = await original(input, init);
       if (!isSelf) {
-        push({
+        const details = response.ok
+          ? null
+          : await readFailureDetails(response);
+        const error = response.ok ? null : summarizeFailure(response.status, details);
+        const call = {
           url,
-          method: init?.method ?? "GET",
+          method,
           status: response.status,
           ms: Date.now() - started,
           bytes: Number(response.headers.get("content-length") ?? 0),
-          error: response.ok ? null : `HTTP ${response.status}`,
-        });
+          error,
+          page,
+          details,
+        };
+        push(call);
+        if (error) onFailure?.(call);
       }
       return response;
     } catch (error) {
       if (!isSelf) {
-        push({
+        const message = error instanceof Error ? error.message : String(error);
+        const call = {
           url,
-          method: init?.method ?? "GET",
+          method,
           status: 0,
           ms: Date.now() - started,
           bytes: 0,
-          error: error instanceof Error ? error.message : String(error),
-        });
+          error: message,
+          page,
+          details: null,
+        };
+        push(call);
+        onFailure?.(call);
       }
       throw error;
     }
   };
 
-  wrapped.__jskeletWrapped = true;
+  /** @type {any} */ (wrapped).__jskeletWrapped = true;
   globalThis.fetch = wrapped;
 }
 
-/** @param {{ url: string, method: string, status: number, ms: number, bytes: number, error: string | null }} call */
+/** @returns {string | null} */
+function currentPage() {
+  return getRequestContext()?.pathname ?? null;
+}
+
+/**
+ * @param {Response} response
+ * @returns {Promise<unknown>}
+ */
+async function readFailureDetails(response) {
+  try {
+    const text = (await response.clone().text()).slice(0, DETAILS_MAX);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Overlay başlığı: durum + varsa API'nin kendi doğrulama mesajı.
+ *
+ * @param {number} status
+ * @param {unknown} details
+ * @returns {string}
+ */
+function summarizeFailure(status, details) {
+  const label = `HTTP ${status}`;
+  const detail = failureMessage(details);
+  return detail ? `${label}: ${detail}` : label;
+}
+
+/**
+ * Upstream gövdesinden kısa, okunabilir bir cümle çıkarır. `[object Object]`
+ * basmamak için nesneleri bilinçli dolaşır.
+ *
+ * @param {unknown} details
+ * @returns {string | null}
+ */
+function failureMessage(details) {
+  if (details == null) return null;
+  if (typeof details === "string") return details.slice(0, 280);
+  if (typeof details !== "object") return String(details);
+
+  const record = /** @type {Record<string, unknown>} */ (details);
+  for (const key of ["details", "detail", "message", "error", "title"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.slice(0, 280);
+    if (value && typeof value === "object") {
+      const nested = failureMessage(value);
+      if (nested) return nested;
+    }
+  }
+  try {
+    return JSON.stringify(details).slice(0, 280);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {Omit<ServerApiCall, "host" | "at">} call */
 function push(call) {
   let host = "—";
   try {

package/src/server/html-cache.js

@@ -815,3 +815,17 @@ export function getHtmlCacheEntries() {
     deps: entry.deps.size,
   }));
 }
+
+/**
+ * Yol (query'siz) için taze bir HTML girdisi var mı? Ziyaret ısıtması yalnızca
+ * soğuk / bayat hedefleri kuyruğa alır; HIT'leri yeniden çekmez.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isHtmlCacheFresh(pathname) {
+  if (typeof pathname !== "string" || !pathname.startsWith("/")) return false;
+  const entry = store.get(pathname);
+  if (!entry) return false;
+  return Date.now() < entry.expiresAt;
+}