jskelet 0.1.4 → 0.1.6

package/src/client/devtools/overlay.js

@@ -11,6 +11,7 @@
  */
 
 const BASE = "/__jskelet/dev";
+/** Soket kurulamadığında düşülen yedek yoklama sıklığı. */
 const POLL_MS = 2000;
 const MAX_ERRORS = 100;
 
@@ -386,50 +387,112 @@ let restarts = 0;
 /* -------------------------------------------------------- canlı yenileme */
 
 /**
- * Sunucu olay akışı. Amaç titremeyi bitirmek: CSS değiştiğinde sayfa
- * yenilenmez, yalnızca stylesheet yeni sürümle takas edilir. Sunucu yeniden
- * başladığında (boot kimliği değişince) tek sefer tam yenileme yapılır;
- * overlay durumu sekme belleğinde durduğu için panel açık kalmaya devam eder.
+ * Sunucudan gelen her şey tek bir WebSocket üzerinden akar: istatistikler,
+ * CSS takası ve yeniden başlatma bildirimi. Eskiden istatistikler iki saniyede
+ * bir çekiliyordu; her açık sekme, panel kapalıyken bile sunucuya sürekli
+ * istek atıyordu.
+ *
+ * CSS değiştiğinde sayfa yenilenmez, yalnızca stylesheet yeni sürümle takas
+ * edilir. Sunucu yeniden başladığında (boot kimliği değişince) tek sefer tam
+ * yenileme yapılır; overlay durumu sekme belleğinde durduğu için panel açık
+ * kalmaya devam eder.
  */
-function connectEvents() {
-  const source = new EventSource(`${BASE}/events`);
+function connectSocket() {
+  let socket;
+  try {
+    socket = new WebSocket(
+      `${location.protocol === "https:" ? "wss" : "ws"}://${location.host}${BASE}/ws`,
+    );
+  } catch {
+    startFallback();
+    return;
+  }
 
-  source.addEventListener("message", (event) => {
-    /** @type {{ type: string, boot?: string, href?: string }} */
-    const payload = JSON.parse(event.data);
+  // Soket hiç açılamazsa (proxy WebSocket'i geçirmiyor olabilir) eski
+  // SSE + yoklama yoluna düşülür; dev akışı bir ara katman yüzünden körelmesin.
+  let opened = false;
 
-    if (payload.type === "hello") {
-      offline = false;
-      const previous = sessionStorage.getItem(BOOT_KEY);
-      sessionStorage.setItem(BOOT_KEY, payload.boot);
+  socket.addEventListener("open", () => {
+    opened = true;
+  });
 
-      if (previous && previous !== payload.boot) {
-        restarts += 1;
-        location.reload();
-        return;
-      }
+  socket.addEventListener("message", (event) => {
+    handleServerMessage(JSON.parse(event.data));
+  });
 
-      bootId = payload.boot;
-      render();
+  socket.addEventListener("close", () => {
+    if (!opened) {
+      startFallback();
       return;
     }
 
-    if (payload.type === "css") {
-      swapStylesheet(payload.href);
+    // Sunucu yeniden başlıyor: gösterge "bağlantı yok"a döner ve kısa aralıkla
+    // yeniden denenir. Açılışta gelen `hello` yeniden başlatmayı bildirir.
+    if (!offline) {
+      offline = true;
+      render();
+    }
+    setTimeout(connectSocket, 500);
+  });
+}
+
+/**
+ * Hem soketten hem yedek SSE akışından gelen paketler burada işlenir.
+ * @param {{ type: string, boot?: string, href?: string }} payload
+ */
+function handleServerMessage(payload) {
+  if (payload.type === "stats") {
+    applyStats(payload);
+    return;
+  }
+
+  if (payload.type === "hello") {
+    offline = false;
+    const previous = sessionStorage.getItem(BOOT_KEY);
+    sessionStorage.setItem(BOOT_KEY, payload.boot);
+
+    if (previous && previous !== payload.boot) {
+      restarts += 1;
+      location.reload();
       return;
     }
 
-    if (payload.type === "reload") location.reload();
-  });
+    bootId = payload.boot;
+    render();
+    return;
+  }
+
+  if (payload.type === "css") {
+    swapStylesheet(payload.href);
+    return;
+  }
+
+  if (payload.type === "reload") location.reload();
+}
+
+/**
+ * WebSocket kurulamadığında eski yol: SSE + periyodik yoklama. Bir kez
+ * başlatılır.
+ */
+let fallbackStarted = false;
 
+function startFallback() {
+  if (fallbackStarted) return;
+  fallbackStarted = true;
+
+  const source = new EventSource(`${BASE}/events`);
+  source.addEventListener("message", (event) =>
+    handleServerMessage(JSON.parse(event.data)),
+  );
   source.addEventListener("error", () => {
-    // Sunucu yeniden başlarken bağlantı düşer; EventSource kendi kendine
-    // yeniden bağlanır, biz yalnızca göstergeyi güncelleriz.
     if (!offline) {
       offline = true;
       render();
     }
   });
+
+  setInterval(pollServer, POLL_MS);
+  pollServer();
 }
 
 /**
@@ -446,24 +509,30 @@ function swapStylesheet(href) {
   current.after(next);
 }
 
+/**
+ * Sunucudan gelen istatistik paketini panele işler.
+ * @param {object} stats
+ */
+function applyStats(stats) {
+  // Süreç kimliği değiştiyse sunucu yeniden başlamıştır. Overlay kapanmaz,
+  // yalnızca sayacı artar; günlükler sunucuda kalıcı olduğu için de silinmez.
+  if (bootId && stats.boot !== bootId) restarts += 1;
+  bootId = stats.boot ?? bootId;
+
+  offline = false;
+  serverStats = stats;
+  render();
+}
+
+/** Yalnızca yedek yolda kullanılır; canlı veri soketten gelir. */
 async function pollServer() {
+  if (!fallbackStarted) return;
+
   try {
     const response = await fetch(`${BASE}/stats`, { cache: "no-store" });
     if (!response.ok) return;
 
-    const stats = await response.json();
-
-    // Süreç kimliği değiştiyse sunucu yeniden başlamıştır. Overlay kapanmaz,
-    // yalnızca sayacı artar; günlükler sunucuda kalıcı olduğu için de silinmez.
-    if (bootId && stats.boot !== bootId) restarts += 1;
-    bootId = stats.boot ?? bootId;
-
-    offline = false;
-    serverStats = stats;
-    render();
-
-    // Isıtma sürerken sayaç akıcı görünsün diye yoklama sıklaşır.
-    if (stats.prewarm?.active) setTimeout(pollServer, 600);
+    applyStats(await response.json());
   } catch {
     // Yeniden başlatma penceresi: eldeki veriler korunur, yalnızca durum
     // göstergesi "bağlantı yok"a döner.
@@ -1763,13 +1832,9 @@ function start() {
   bind(ensureRoot());
   render();
 
-  connectEvents();
-
-  setInterval(() => {
-    // Panel kapalıyken de rozet güncel kalsın diye sunucu yine yoklanır.
-    pollServer();
-  }, POLL_MS);
-  pollServer();
+  // Panel kapalıyken de rozet güncel kalsın diye kanal her zaman açılır;
+  // maliyeti tek bir bağlantı ve yalnızca değişiklik oldukça gelen paketler.
+  connectSocket();
 
   // Ölçümler oturmadan gönderilmesin; sonra sekmeden ayrılırken güncellenir.
   setTimeout(() => sendPageReport(), 3000);

package/src/config/index.js

@@ -70,6 +70,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @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.
+ * @property {boolean} trackDependencies Render'ın okuduğu veri anahtarları kaydedilsin mi.
  * @property {{ attempts: number, delayMs: number }} transientRetry
  * @property {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
@@ -210,6 +211,7 @@ function normalizePriority(raw) {
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
+ *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
  *   prewarm: Record<string, unknown>,
  *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
@@ -238,6 +240,10 @@ function normalizeCache(raw) {
     // Otomatik upstream izleme kapatılabilir olmalı: `fetch`i kendisi saran
     // bir uygulama (ölçüm, retry, circuit breaker) çakışma yaşayabilir.
     trackUpstream: raw?.trackUpstream !== false,
+    // Hangi sayfanın hangi veri anahtarını okuduğu kaydedilsin mi.
+    // `withDataCache` kullanmayan bir uygulamada kaydedilecek bir şey yok;
+    // kapatmak bağlam kurma maliyetini de kaldırır.
+    trackDependencies: raw?.trackDependencies !== false,
     transientRetry:
       raw?.transientRetry === false
         ? { attempts: 0, delayMs: 0 }
@@ -457,6 +463,7 @@ export async function loadConfig(options = {}) {
     htmlMaxEntries,
     data,
     trackUpstream,
+    trackDependencies,
     transientRetry,
     prewarm,
     prewarmPriority,
@@ -475,6 +482,7 @@ export async function loadConfig(options = {}) {
     htmlMaxEntries,
     data,
     trackUpstream,
+    trackDependencies,
     transientRetry,
     prewarm,
     prewarmPriority,

package/src/index.js

@@ -43,6 +43,7 @@ export {
   clearHtmlCache,
   getHtmlCacheEntries,
   getHtmlCacheSize,
+  invalidateHtmlCache,
   withHtmlCache,
 } from "./server/html-cache.js";
 export {

package/src/server/cache-deps.js

@@ -0,0 +1,42 @@
+/**
+ * Bir render'ın hangi veri anahtarlarını okuduğunu kaydeder.
+ *
+ * `request-cache.js` ile aynı desen: `AsyncLocalStorage`, bağlam yoksa her şey
+ * sessizce devre dışı. Script'ten, cron'dan ya da istek dışı bir yerden yapılan
+ * `withDataCache` çağrıları hiçbir şeye yazılmaz.
+ *
+ * Neden gerekli: HTML önbelleğinin elinde "bu sayfa şu içerikten etkilenir"
+ * bilgisi yoktu, dolayısıyla bir içerik güncellendiğinde tek seçenek TTL'i
+ * beklemek ya da tüm önbelleği boşaltmaktı. Bağımlılığı uygulamanın elle
+ * bildirmesi (tag'lemek) ise en sık yapılan hatayı davet ediyor: detay
+ * sayfasını işaretleyip aynı içeriği listeleyen ana sayfayı unutmak.
+ *
+ * Burada bildirim yok, **gözlem** var: render sırasında fiilen okunan anahtarlar
+ * kaydedilir. Ana sayfa o veriyi okuduysa listede olur, okumadıysa olmaz.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** @type {AsyncLocalStorage<Set<string>>} */
+const storage = new AsyncLocalStorage();
+
+/**
+ * `run`'ı, içindeki `recordDependency()` çağrılarının `deps`'e yazacağı bir
+ * bağlamda çalıştırır.
+ *
+ * @template T
+ * @param {Set<string>} deps
+ * @param {() => T} run
+ * @returns {T}
+ */
+export function collectDependencies(deps, run) {
+  return storage.run(deps, run);
+}
+
+/**
+ * Bu render'ın bir veri anahtarını okuduğunu bildirir. Bağlam yoksa no-op.
+ *
+ * @param {string} key
+ */
+export function recordDependency(key) {
+  storage.getStore()?.add(key);
+}

package/src/server/create-app.js

@@ -167,6 +167,15 @@ export async function startServer(options = {}) {
     console.error("[uncaughtException]", error);
   });
 
+  // Dev panelinin canlı kanalı: el sıkışma `upgrade` olayında geçtiği için
+  // middleware zincirine değil, doğrudan sunucuya bağlanır. Modül `listen`den
+  // önce yüklenir; dinleme başladıktan sonra beklenen bir `await` kalırsa ilk
+  // upgrade isteği dinleyici yokken gelip reddedilebiliyor.
+  const attachDevSocket =
+    process.env.NODE_ENV === "development"
+      ? (await import("./dev/devtools.js")).attachDevSocket
+      : null;
+
   return new Promise((resolve) => {
     const server = app.listen(port, host, () => {
       // Bu satırın biçimi sözleşme: `jskelet dev` sunucunun hazır olduğunu
@@ -177,5 +186,7 @@ export async function startServer(options = {}) {
       startPrewarm({ port });
       resolve(server);
     });
+
+    attachDevSocket?.(server);
   });
 }

package/src/server/data-cache.js

@@ -19,6 +19,8 @@
  */
 import { getConfig } from "../config/index.js";
 import { DEFAULT_DATA_CACHE } from "../config/defaults.js";
+import { recordDependency } from "./cache-deps.js";
+import { invalidateHtmlByDependency } from "./html-cache.js";
 
 /**
  * @typedef {{ value: unknown, expiresAt: number, staleUntil: number }} DataEntry
@@ -144,6 +146,10 @@ function refresh(key, ttlSeconds, producer, options) {
 export async function withDataCache(key, ttlSeconds, producer, options = {}) {
   if (!ttlSeconds) return producer();
 
+  // Bu anahtarı okuyan render, `clearDataCache(key)` çağrıldığında etkilenen
+  // sayfalar arasında sayılsın. Render bağlamı yoksa çağrı no-op.
+  recordDependency(key);
+
   const hit = read(key);
 
   if (hit) {
@@ -202,24 +208,31 @@ export function dataCache(fn, options) {
  * Bir anahtarı ya da önek eşleşen tüm anahtarları düşürür. Webhook ile
  * "bu haber güncellendi" bilgisi geldiğinde kullanılır.
  *
+ * Düşen anahtarları **render sırasında okumuş** HTML girdileri de bayatlar:
+ * uygulamanın ayrıca `invalidateHtmlCache()` çağırması gerekmez ve aynı veriyi
+ * gösteren liste sayfalarını unutmak mümkün değildir (bkz. `cache-deps.js`).
+ *
  * @param {string} [prefix] Verilmezse tüm önbellek boşaltılır.
  * @returns {number} Silinen girdi sayısı.
  */
 export function clearDataCache(prefix) {
+  /** @type {string[]} */
+  const removed = [];
+
   if (prefix === undefined) {
-    const size = store.size;
+    removed.push(...store.keys());
     store.clear();
-    return size;
-  }
-
-  let removed = 0;
-  for (const key of store.keys()) {
-    if (key.startsWith(prefix)) {
-      store.delete(key);
-      removed += 1;
+  } else {
+    for (const key of store.keys()) {
+      if (key.startsWith(prefix)) {
+        store.delete(key);
+        removed.push(key);
+      }
     }
   }
-  return removed;
+
+  if (removed.length) invalidateHtmlByDependency(removed);
+  return removed.length;
 }
 
 /** @returns {number} */

package/src/server/dev/devtools.js

@@ -22,6 +22,7 @@ import {
   trackServerFetch,
 } from "./report.js";
 import { startVersionCheck, versionStatus } from "./version-check.mjs";
+import { broadcastSocket, socketCount, upgradeToSocket } from "./socket.js";
 
 /** Overlay dosyaları framework paketinden servis edilir, uygulamadan değil. */
 const DEVTOOLS_DIR = path.join(FRAMEWORK_ROOT, "src", "client", "devtools");
@@ -115,6 +116,7 @@ export function recordServerError(level, message, extra = {}) {
   });
   trim(errors);
   persist();
+  pushStats();
 }
 
 /**
@@ -177,6 +179,7 @@ function timing() {
       requests.push(entry);
       trim(requests);
       persist();
+      pushStats();
       // Terminalde canlı istek satırı.
       log.http(entry);
     });
@@ -185,6 +188,70 @@ function timing() {
   };
 }
 
+/* ----------------------------------------------------------- istatistikler */
+
+/**
+ * Overlay'in gösterdiği her şey tek pakette. `GET /stats` ve WebSocket aynı
+ * gövdeyi kullanır ki panel hangi yoldan beslenirse beslensin aynı şeyi
+ * görsün.
+ *
+ * @returns {object}
+ */
+function statsPayload() {
+  const usage = process.memoryUsage();
+
+  return {
+    type: "stats",
+    pid: process.pid,
+    // Overlay yeniden başlatmayı bu kimlikten anlar; kendi durumunu
+    // sıfırlamadan yalnızca "restarted" bilgisini gösterir.
+    boot: BOOT_ID,
+    uptime: process.uptime(),
+    node: process.version,
+    version: versionStatus(),
+    memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+    prewarm: { ...prewarmProgress },
+    requests: requests.slice(-25).reverse(),
+    errors: errors.slice(-25).reverse(),
+  };
+}
+
+/** @type {NodeJS.Timeout | null} */
+let statsTimer = null;
+
+/**
+ * Değişiklikleri panele iter. Bir sayfa yüklemesi arka arkaya birçok kayıt
+ * üretiyor (istek + uyarılar); paket başına bir çerçeve yerine kısa bir
+ * sessizlikten sonra tek çerçeve gönderilir.
+ */
+function pushStats() {
+  if (statsTimer || !socketCount()) return;
+
+  statsTimer = setTimeout(() => {
+    statsTimer = null;
+    broadcastSocket(statsPayload());
+  }, 120);
+
+  statsTimer.unref?.();
+}
+
+/**
+ * Zamana bağlı alanlar (uptime, bellek, ısıtma sayacı) bir olay üretmiyor;
+ * onlar için sabit bir kalp atışı var. Bilinçli olarak ısıtmadan bağımsız:
+ * kanalın temposu bir arka plan işine göre değişirse panel de o işin ritmine
+ * bağlanmış olur.
+ *
+ * Bağlı panel yokken hiçbir şey hesaplanmaz.
+ */
+function startHeartbeat() {
+  const timer = setInterval(() => {
+    if (!socketCount()) return;
+    broadcastSocket(statsPayload());
+  }, 2000);
+
+  timer.unref?.();
+}
+
 /* ------------------------------------------------------------ live reload */
 
 /** @type {Set<import('express').Response>} */
@@ -198,8 +265,14 @@ function send(res, payload) {
   res.write(`data: ${JSON.stringify(payload)}\n\n`);
 }
 
-/** @param {object} payload */
+/**
+ * Canlı yenileme olayları. Panel normalde WebSocket üzerinden dinler; SSE
+ * yalnızca soket kurulamadığında devreye giren yedek yol.
+ *
+ * @param {object} payload
+ */
 function broadcast(payload) {
+  broadcastSocket(payload);
   for (const client of clients) send(client, payload);
 }
 
@@ -285,22 +358,10 @@ function router() {
     req.on("close", () => clients.delete(res));
   });
 
+  // WebSocket kurulamadığında panelin düştüğü yedek uç.
   api.get("/stats", (req, res) => {
-    const usage = process.memoryUsage();
     res.setHeader("Cache-Control", "no-store");
-    res.json({
-      pid: process.pid,
-      // Overlay yeniden başlatmayı bu kimlikten anlar; kendi durumunu
-      // sıfırlamadan yalnızca "restarted" bilgisini gösterir.
-      boot: BOOT_ID,
-      uptime: process.uptime(),
-      node: process.version,
-      version: versionStatus(),
-      memory: { rss: usage.rss, heapUsed: usage.heapUsed },
-      prewarm: { ...prewarmProgress },
-      requests: requests.slice(-25).reverse(),
-      errors: errors.slice(-25).reverse(),
-    });
+    res.json(statsPayload());
   });
 
   // Detaylı rapor: kendi sayfası, script'i ve veri ucu.
@@ -364,6 +425,7 @@ function router() {
     errors.length = 0;
     requests.length = 0;
     persist();
+    pushStats();
     res.json({ ok: true });
   });
 
@@ -382,6 +444,30 @@ export function mountDevtools(app) {
   trackServerFetch();
   watchManifest();
   startVersionCheck();
+  startHeartbeat();
   app.use(timing());
   app.use(brand.devBasePath, router());
 }
+
+/**
+ * Canlı kanalı HTTP sunucusuna bağlar.
+ *
+ * Express uygulamasına takılamıyor: WebSocket el sıkışması `upgrade` olayında
+ * geçiyor ve o olay middleware zincirine hiç uğramıyor. Bu yüzden `listen`
+ * sonrası ayrı bir adım.
+ *
+ * @param {import('node:http').Server} server
+ */
+export function attachDevSocket(server) {
+  const endpoint = `${getConfig().brand.devBasePath}/ws`;
+
+  server.on("upgrade", (req, socket) => {
+    // Uygulamanın kendi WebSocket uçları olabilir; yalnızca bizimkini alırız.
+    if ((req.url ?? "").split("?")[0] !== endpoint) return;
+
+    upgradeToSocket(req, socket, (send) => {
+      send({ type: "hello", boot: BOOT_ID });
+      send(statsPayload());
+    });
+  });
+}