jskelet 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -10,6 +10,12 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Early HTML cache refresh before TTL expiry: the last successful produce time
+  (`produceMs`) sets a lead window (`min(max(produceMs×2, 250ms), ttl/2)`). A
+  still-fresh `HIT` in that window revalidates in the background; idle entries
+  are soft-staled by a sweeper and drained over HTTP even without classic
+  `prewarmPaths` (`PREWARM=0` disables both). In-flight refreshes no longer drop
+  the entry when `staleUntil` elapses.
 - Route-level stylesheets: put files in `styles/pages/*.css` and load them from
   the controller with `styles: ["home.css"]` (same contract as island
   `entries`). The layout emits them after global `app.css`; dev hot-swaps any

package/docs/06-cache.md

@@ -142,15 +142,29 @@ Girdi yapısı:
 ```
 expiresAt  = now + ttl
 staleUntil = now + ttl * 2      (STALE_FACTOR = 1)
+produceMs  = son başarılı üretimin süresi (ms)
 ```
 
 Okuma davranışı:
 
 | Durum | Yanıt | Arka plan |
 | --- | --- | --- |
-| `now < expiresAt` | Önbellekteki HTML, `HIT` | — |
+| `now < expiresAt - leadMs` | Önbellekteki HTML, `HIT` | — |
+| `expiresAt - leadMs ≤ now < expiresAt` | Önbellekteki HTML, `HIT` | **Erken tazeleme** başlar |
 | `expiresAt ≤ now < staleUntil` | Önbellekteki HTML **anında**, `STALE` | Tazeleme başlatılır |
-| `now ≥ staleUntil` | Girdi silinir, taze render, `MISS` | — |
+| `now ≥ staleUntil` | Girdi silinir, taze render, `MISS` (uçuştaki tazeleme varken silinmez) | — |
+
+`leadMs` sayfanın load süresini hesaba katar:
+
+```
+leadMs = min(max(produceMs * 2, 250ms), ttl / 2)
+```
+
+Böylece yavaş bir sayfa TTL dolduğu anda hâlâ soğuk render'a düşmez: taze
+HTML çoğu zaman `expiresAt` gelmeden yazılmış olur. Trafik yoksa bir sweeper
+aynı pencerede girdiyi soft-bayatlatır ve ısıtma kuyruğuna alır; `startPrewarm`
+( `PREWARM=0` değilse) kuyruğu HTTP ile boşaltır — klasik `prewarmPaths`
+olmasa da.
 
 Stale penceresinde tazelemenin hatası isteği etkilemez: eski HTML pencere
 boyunca geçerli kalır ve hata yalnızca loglanır

package/docs/07-yapilandirma.md

@@ -622,7 +622,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 
 Desen → saniye eşlemesi. Eşleşen kural, route'un kendi `revalidate` değerini
 **ezer**. Negatif ya da sonlu olmayan değerler yok sayılır; `0` "önbellekleme"
-anlamına gelir.
+anlamına gelir. TTL dolmadan önce framework, son render süresine göre erken
+arka plan tazelemesi başlatır (ayrı bir config alanı yok; ayrıntı
+[06-cache.md](./06-cache.md)).
 
 ```js
 html: {

package/docs/en/06-caching.md

@@ -150,15 +150,29 @@ The entry structure:
 ```
 expiresAt  = now + ttl
 staleUntil = now + ttl * 2      (STALE_FACTOR = 1)
+produceMs  = duration of the last successful produce (ms)
 ```
 
 Read behaviour:
 
 | State | Response | Background |
 | --- | --- | --- |
-| `now < expiresAt` | The cached HTML, `HIT` | — |
+| `now < expiresAt - leadMs` | The cached HTML, `HIT` | — |
+| `expiresAt - leadMs ≤ now < expiresAt` | The cached HTML, `HIT` | **Early refresh** starts |
 | `expiresAt ≤ now < staleUntil` | The cached HTML **immediately**, `STALE` | A refresh is started |
-| `now ≥ staleUntil` | The entry is deleted, fresh render, `MISS` | — |
+| `now ≥ staleUntil` | The entry is deleted, fresh render, `MISS` (not while a refresh is in flight) | — |
+
+`leadMs` accounts for the page’s load time:
+
+```
+leadMs = min(max(produceMs * 2, 250ms), ttl / 2)
+```
+
+So a slow page does not fall back to a cold render the moment TTL ends: fresh
+HTML is usually written before `expiresAt`. With no traffic, a sweeper
+soft-stales the entry in the same window and queues it for warming;
+`startPrewarm` (unless `PREWARM=0`) drains that queue over HTTP — even when
+classic `prewarmPaths` is absent.
 
 A failure of the refresh inside the stale window does not affect the request:
 the old HTML stays valid for the whole window and the error is only logged

package/docs/en/07-configuration.md

@@ -635,7 +635,9 @@ Details: [03-routing.md](./03-routing.md).
 
 A pattern → seconds mapping. A matching rule **overrides** the route's own
 `revalidate` value. Negative or non-finite values are ignored; `0` means "no
-caching".
+caching". Before TTL ends the framework starts an early background refresh
+based on the last render duration (no separate config field; see
+[06-caching.md](./06-caching.md)).
 
 The one exception is `route(fn, { private: true })`: on that route a matching
 pattern is ignored. The lock is deliberately one-way — a mistake in the other

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk (or EJS) SSR, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/server/html-cache.js

@@ -7,6 +7,11 @@
  * tazeleme turu` kadar geride olabilir. Fiyat gibi canlı alanlar istemcide
  * WebSocket'ten güncellendiği için bu gecikme ekranda görünmez.
  *
+ * TTL dolmadan önce de tazelenir (**erken tazeleme**): son başarılı üretimin
+ * süresi (`produceMs`) kadar önden arka plan refresh başlar, böylece yavaş
+ * bir sayfa TTL anında hâlâ soğuk render'a düşmez. Trafik yoksa sweeper
+ * girdiyi soft-bayatlatır ve ısıtma kuyruğuna alır.
+ *
  * TTL'in yanında ikinci bir tazelik kaynağı daha var: **hedefli
  * invalidation**. Bir içerik güncellendiğinde tüm önbelleği boşaltmak
  * (`clearHtmlCache()`) o an sıcak olan her sayfayı soğuk render'a çevirir;
@@ -50,9 +55,12 @@ import {
  * `encoded` haritası yanıt yolunda (`sendHtml`) doluyor, yani yazma anında
  * boş; `storeEncoded` açıkken harita büyüdüğünde girdi yeniden paylaşılır.
  *
+ * `produceMs`: son başarılı üretimin süresi. Erken tazeleme penceresi bundan
+ * türetilir; Redis'ten gelen kopyada yoksa varsayılan kullanılır.
+ *
  * @typedef {{ html: string, status: number, expiresAt: number,
  *   staleUntil: number, encoded: Map<string, Buffer>, deps: Set<string>,
- *   storedAt: number, sharedEncodings: number }} HtmlEntry
+ *   storedAt: number, sharedEncodings: number, produceMs: number }} HtmlEntry
  */
 
 /**
@@ -94,12 +102,27 @@ function trackDependencies() {
  */
 const STALE_FACTOR = 1;
 
+/**
+ * Redis'ten gelen veya süresi bilinmeyen girdiler için erken tazeleme lead'i.
+ * Ölçülmüş `produceMs` yokken aşırı iyimser (0) kalmamak için.
+ */
+const DEFAULT_PRODUCE_MS = 500;
+
+/** Erken tazelemenin alt sınırı — çok hızlı sayfalar da TTL'den önce ısınsın. */
+const EARLY_REFRESH_MIN_MS = 250;
+
+/** Trafiksiz girdileri erken pencerede soft-bayatlatma aralığı. */
+const EARLY_SWEEP_INTERVAL_MS = 1000;
+
 /** @type {Map<string, HtmlEntry>} */
 const store = new Map();
 
 /** @type {Map<string, Promise<{ html: string, status: number }>>} */
 const inflight = new Map();
 
+/** @type {ReturnType<typeof setInterval> | null} */
+let earlySweepTimer = null;
+
 /**
  * Uçuştaki her tazelemenin kimliği. Bir girdi tazelenirken invalidate
  * edilirse o tazelemenin sonucu **artık geçersizdir**: render, purge'den önce
@@ -148,6 +171,54 @@ const purgedDeps = new Map();
 
 const MAX_PURGED_DEPS = 1000;
 
+/**
+ * Erken tazeleme lead'i: son render süresinin 2 katı (en az 250 ms), TTL'in
+ * yarısından fazla olamaz — kısa TTL'lerde sürekli refresh döngüsü olmasın.
+ *
+ * @param {number} produceMs
+ * @param {number} ttlMs
+ * @returns {number}
+ */
+export function earlyRefreshLeadMs(produceMs, ttlMs) {
+  const measured =
+    Number.isFinite(produceMs) && produceMs > 0 ? produceMs : DEFAULT_PRODUCE_MS;
+  const lead = Math.max(measured * 2, EARLY_REFRESH_MIN_MS);
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return lead;
+  return Math.min(lead, ttlMs / 2);
+}
+
+/**
+ * @param {HtmlEntry} entry
+ * @returns {number}
+ */
+function entryTtlMs(entry) {
+  // Soft-bayatlatılmış girdide expiresAt 0; orijinal TTL storedAt farkından
+  // okunamaz. O durumda produceMs üzerinden güvenli bir üst sınır yeter.
+  if (entry.expiresAt > entry.storedAt) return entry.expiresAt - entry.storedAt;
+  return Math.max(entry.produceMs * 4, EARLY_REFRESH_MIN_MS * 2);
+}
+
+/**
+ * @param {HtmlEntry} entry
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+function isEarly(entry, now = Date.now()) {
+  if (now >= entry.expiresAt) return false;
+  const lead = earlyRefreshLeadMs(entry.produceMs, entryTtlMs(entry));
+  return now >= entry.expiresAt - lead;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function normalizeProduceMs(value) {
+  const n = Number(value);
+  if (Number.isFinite(n) && n >= 0) return Math.round(n);
+  return DEFAULT_PRODUCE_MS;
+}
+
 /**
  * Girdiyi ters indeksten söker. Bu adım atlanırsa indeks, düşen girdilerin
  * anahtarlarını tutmaya devam eder ve sessizce sızar.
@@ -183,7 +254,7 @@ function drop(key) {
 /**
  * @param {string} key
  * @returns {{ html: string, status: number, encoded: Map<string, Buffer>,
- *   stale: boolean } | null}
+ *   stale: boolean, early: boolean } | null}
  */
 function read(key) {
   const entry = store.get(key);
@@ -191,8 +262,12 @@ function read(key) {
 
   const now = Date.now();
   if (now >= entry.staleUntil) {
-    drop(key);
-    return null;
+    // Uçuştaki tazeleme bitene kadar girdiyi tut: yavaş upstream'de
+    // staleUntil dolup MISS'e düşmek erken tazelemenin amacını bozar.
+    if (!inflight.has(key)) {
+      drop(key);
+      return null;
+    }
   }
 
   // LRU: erişilen girdiyi sona taşı.
@@ -206,11 +281,13 @@ function read(key) {
     share(key, entry);
   }
 
+  const stale = now >= entry.expiresAt;
   return {
     html: entry.html,
     status: entry.status,
     encoded: entry.encoded,
-    stale: now >= entry.expiresAt,
+    stale,
+    early: !stale && isEarly(entry, now),
   };
 }
 
@@ -234,6 +311,7 @@ function share(key, entry) {
     storedAt: entry.storedAt,
     expiresAt: entry.expiresAt,
     staleUntil: entry.staleUntil,
+    produceMs: entry.produceMs,
     deps: [...entry.deps],
   };
 
@@ -298,6 +376,7 @@ async function readShared(key) {
     deps,
     storedAt,
     sharedEncodings: encoded.size,
+    produceMs: normalizeProduceMs(payload.produceMs),
   };
 }
 
@@ -306,8 +385,9 @@ async function readShared(key) {
  * @param {{ html: string, status: number }} value
  * @param {number} ttlSeconds
  * @param {Set<string> | null} deps Render sırasında okunan veri anahtarları.
+ * @param {number} [produceMs] Son üretimin süresi (ms).
  */
-function write(key, value, ttlSeconds, deps = null) {
+function write(key, value, ttlSeconds, deps = null, produceMs = DEFAULT_PRODUCE_MS) {
   const now = Date.now();
 
   /** @type {HtmlEntry} */
@@ -322,6 +402,7 @@ function write(key, value, ttlSeconds, deps = null) {
     deps: deps ?? new Set(),
     storedAt: now,
     sharedEncodings: 0,
+    produceMs: normalizeProduceMs(produceMs),
   };
 
   install(key, entry);
@@ -385,6 +466,9 @@ function refresh(key, ttlSeconds, producer) {
   const pending = inflight.get(key);
   if (pending) return pending;
 
+  // Tazeleme sürerken staleUntil dolmasın: drop → MISS yolu kapanır.
+  extendStaleWhileRefreshing(key);
+
   const token = {};
   tokens.set(key, token);
 
@@ -397,6 +481,17 @@ function refresh(key, ttlSeconds, producer) {
   return task;
 }
 
+/**
+ * @param {string} key
+ */
+function extendStaleWhileRefreshing(key) {
+  const entry = store.get(key);
+  if (!entry) return;
+  const lead = earlyRefreshLeadMs(entry.produceMs, entryTtlMs(entry));
+  const floor = Date.now() + lead;
+  if (entry.staleUntil < floor) entry.staleUntil = floor;
+}
+
 /**
  * @param {string} key
  * @param {number} ttlSeconds
@@ -436,7 +531,7 @@ async function produce(key, ttlSeconds, producer, token) {
   // öncesinde başlamış demektir; yazmak az önce düşürüleni geri koyardı.
   const valid = tokens.get(key) === token && !readsPurgedData(deps, startedAt);
   if (valid && value.status === 200 && !value.degraded && value.storable !== false) {
-    write(key, value, ttlSeconds, deps);
+    write(key, value, ttlSeconds, deps, Date.now() - startedAt);
   }
 
   return value;
@@ -447,7 +542,7 @@ async function produce(key, ttlSeconds, producer, token) {
  * @param {number} ttlSeconds 0 → cache yok
  * @param {() => Promise<{ html: string, status: number }>} producer
  * @returns {Promise<{ html: string, status: number, cached: boolean,
- *   stale?: boolean, encoded?: Map<string, Buffer> }>}
+ *   stale?: boolean, early?: boolean, encoded?: Map<string, Buffer> }>}
  */
 export async function withHtmlCache(key, ttlSeconds, producer) {
   if (!ttlSeconds) {
@@ -460,7 +555,8 @@ export async function withHtmlCache(key, ttlSeconds, producer) {
   if (hit) {
     // Süresi geçmiş girdi anında döner; tazeleme arkada yürür ve hatası
     // isteği etkilemez (eski HTML stale penceresi boyunca geçerli kalır).
-    if (hit.stale) {
+    // Erken pencerede de aynı: hâlâ HIT, ama TTL dolmadan taze HTML yazılsın.
+    if (hit.stale || hit.early) {
       invalidated.delete(key);
       void refresh(key, ttlSeconds, producer).catch((error) => {
         console.error(`[html-cache] background refresh failed: ${key}`, error);
@@ -829,3 +925,42 @@ export function isHtmlCacheFresh(pathname) {
   if (!entry) return false;
   return Date.now() < entry.expiresAt;
 }
+
+/**
+ * Erken tazeleme penceresine girmiş (veya TTL'i dolmuş) trafiksiz girdileri
+ * soft-bayatlatır ve ısıtma kuyruğuna alır. HTTP ısıtması producer'sız
+ * çalıştığı için soft-bayat şart: taze HIT yenileme tetiklemez.
+ *
+ * @returns {number} İşaretlenen girdi sayısı.
+ */
+export function sweepEarlyExpiry() {
+  const now = Date.now();
+  let marked = 0;
+
+  for (const [key, entry] of store) {
+    if (inflight.has(key)) continue;
+    // Zaten soft-bayat / kuyrukta — her saniye yeniden ekleme.
+    if (entry.expiresAt === 0) continue;
+    if (now < entry.expiresAt && !isEarly(entry, now)) continue;
+
+    entry.expiresAt = 0;
+    if (invalidated.size < MAX_INVALIDATED) invalidated.add(key);
+    marked += 1;
+  }
+
+  return marked;
+}
+
+/**
+ * Trafiksiz sayfaların TTL öncesi soft-bayatlatılması. `startPrewarm` açar;
+ * `PREWARM=0` iken hiç kurulmaz. `unref` — süreç kapanışını geciktirmez.
+ *
+ * @returns {void}
+ */
+export function startEarlyExpirySweep() {
+  if (earlySweepTimer) return;
+  earlySweepTimer = setInterval(() => {
+    sweepEarlyExpiry();
+  }, EARLY_SWEEP_INTERVAL_MS);
+  earlySweepTimer.unref();
+}

package/src/server/prewarm.js

@@ -19,7 +19,7 @@
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
 import { getRequestContext } from "../http/request-context.js";
-import { isHtmlCacheFresh, takeInvalidatedPaths } from "./html-cache.js";
+import { isHtmlCacheFresh, takeInvalidatedPaths, startEarlyExpirySweep } from "./html-cache.js";
 import { getDataCacheStats } from "./data-cache.js";
 import { isTransientStatus } from "./upstream-tracking.js";
 import { upstreamCooldownMs } from "./upstream-limiter.js";
@@ -786,7 +786,8 @@ async function drainVisitWarm() {
 
 /**
  * Açılışta ısıtmayı tetikler. `listen` geri çağrısından çağrılır.
- * `onVisit` modunda zamanlayıcı yok: yalnızca origin kaydı ve kuyruk.
+ * `onVisit` modunda klasik zamanlayıcı yok; yine de erken-TTL invalidation
+ * drain'i çalışır — soft-bayatlayan sweeper'ın kuyruğu boşalmasın.
  *
  * @param {{ port: number }} options
  * @returns {void}
@@ -797,6 +798,11 @@ export function startPrewarm({ port }) {
 
   const origin = `http://127.0.0.1:${port}`;
 
+  // Klasik `prewarmPaths` olmasa da TTL öncesi soft-bayatlayan girdiler
+  // HTTP ile ısıtılsın. `PREWARM=0` yukarıda her şeyi keser.
+  startEarlyExpirySweep();
+  startExpiryWarmDrain(origin);
+
   if (config.prewarm?.onVisit?.enabled) {
     const classicEnv = CLASSIC_PREWARM_ENV.filter((key) => process.env[key]);
     if (classicEnv.length) {
@@ -814,7 +820,8 @@ export function startPrewarm({ port }) {
   }
 
   if (process.env.PREWARM !== "1" && config.prewarm?.enabled === false) return;
-  // Isıtacak yol bildirmeyen bir projede zamanlayıcı kurmanın anlamı yok.
+  // Isıtacak yol bildirmeyen bir projede klasik tur zamanlayıcısı gerekmez;
+  // expiry drain yine de yukarıda kuruldu.
   if (typeof config.hooks?.prewarmPaths !== "function") return;
 
   const isDev = process.env.NODE_ENV === "development";
@@ -848,3 +855,50 @@ export function startPrewarm({ port }) {
   const interval = setting("PREWARM_INTERVAL_SECONDS", "intervalSeconds", 0);
   if (interval > 0) setInterval(() => void run(), interval * 1000).unref();
 }
+
+/** @type {string | null} */
+let expiryOrigin = null;
+
+/** @type {boolean} */
+let expiryDraining = false;
+
+/** @type {ReturnType<typeof setInterval> | null} */
+let expiryDrainTimer = null;
+
+/**
+ * Soft-bayat / invalidate kuyruğunu periyodik boşaltır. Klasik tur ve onVisit
+ * aynı kuyruğu da okur; bu drain `prewarmPaths` yokken de çalışır.
+ *
+ * @param {string} origin
+ * @returns {void}
+ */
+function startExpiryWarmDrain(origin) {
+  expiryOrigin = origin;
+  if (expiryDrainTimer) return;
+  expiryDrainTimer = setInterval(() => {
+    void drainExpiryWarm();
+  }, 1000);
+  expiryDrainTimer.unref();
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+async function drainExpiryWarm() {
+  if (expiryDraining || !expiryOrigin) return;
+
+  const paths = takeInvalidatedPaths();
+  if (!paths.length) return;
+
+  expiryDraining = true;
+  try {
+    const cold = paths.filter((path) => !isHtmlCacheFresh(path));
+    if (!cold.length) return;
+
+    await prewarm({ origin: expiryOrigin, paths: cold, quiet: true });
+  } catch (error) {
+    console.error("[prewarm] expiry warm failed", error);
+  } finally {
+    expiryDraining = false;
+  }
+}