jskelet 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -10,6 +10,28 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- An optional Redis tier behind both caches, turned on with
+  `cache().redis: { enabled: true, url }` and `npm install ioredis`. The
+  in-process cache stays primary and every request still reads it; Redis only
+  does the two things a single process cannot. An instance that has never seen a
+  path finds the HTML another replica already produced, so a fresh container or a
+  post-deploy replacement does not re-render and re-fetch everything from
+  scratch. And `invalidateHtmlCache()`, `clearHtmlCache()` and
+  `clearDataCache()` now reach every replica over pub/sub instead of only the one
+  that received the webhook — until now the others waited out the TTL and a
+  visitor saw old or new content depending on where they landed. Keys live under
+  `_jskelet:{namespace}:{buildId}:…`, where the build id makes HTML from a
+  previous deploy expire on its own rather than pointing at asset files that no
+  longer exist. Personalised (`storable: false`), degraded and non-200 responses
+  are never shared. If `ioredis` is missing, Redis is unreachable or it goes down
+  mid-flight, a warning is printed and the site keeps serving from memory.
+- `getRedisStatus()` reports whether the shared tier is connected, which key
+  prefix and build id it is using, and how many command failures there have
+  been — usable from a healthcheck endpoint. The same summary appears in the dev
+  panel report.
+- Servers started with `startServer()` now shut down on `SIGTERM`/`SIGINT`
+  instead of being killed: the listener is closed and the Redis connection is
+  drained so in-flight writes are not cut mid-command.
 - Targeted HTML invalidation: `invalidateHtmlCache(target, { hard })` takes a
   path, the config pattern syntax (`/news/:slug`), a regular expression or a list
   of them, and returns how many entries were affected. By default it **stales**
@@ -65,12 +87,27 @@ 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.
+- 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
+  jumps straight to a release.
 - The dev tools panel is now fed over a WebSocket (`<devBasePath>/ws`) instead of
   polling `/stats` every two seconds. The server pushes statistics as they change
   and sends live reload and CSS hot-swap events over the same connection, so an
   open tab no longer keeps hitting the server while the panel is closed. No new
   dependency is involved; if the socket cannot be opened, the panel falls back to
   the previous SSE plus polling path.
+- The server now binds to `::` instead of `0.0.0.0` when no `HOST` is given, so a
+  single dual-stack socket answers both IPv6 and IPv4. Browsers resolve
+  `localhost` to `::1` first and, unlike ordinary requests, a WebSocket handshake
+  does not fall back to IPv4 — which made the dev panel's live channel fail on an
+  IPv4-only socket. Where IPv6 is unavailable the bind falls back to `0.0.0.0`.
 - Prewarming no longer holds up the rest of the dev server. In development it now
   runs with a single worker and a default limit of 4 requests per second
   (`prewarm.rps` / `PREWARM_RPS` still override it), so page requests and the dev
@@ -97,6 +134,13 @@ one is listed under a **Breaking** heading.
   `node_modules` can still serve the docs. In development the local file wins
   and nothing is cached. The branch is overridable with `DOCS_REF`.
 
+### Fixed
+
+- The dev panel's WebSocket handshake was answered with a `Sec-WebSocket-Accept`
+  value derived from a mistyped protocol constant. Browsers verify that value and
+  closed the connection immediately with "Incorrect 'Sec-WebSocket-Accept' header
+  value", so the panel silently fell back to polling.
+
 ## [0.1.2] - 2026-08-30
 
 ### Added

package/docs/06-cache.md

@@ -530,7 +530,124 @@ silinmiş dosyayı istemeye devam eder ([09-dev-araclari.md](./09-dev-araclari.m
 
 Önbellek süreç belleğinde yaşadığı için birden fazla süreç/kopya çalıştırıyorsanız
 her birinin kendi önbelleği olur; `clearHtmlCache()` yalnızca çağrıldığı süreci
-etkiler.
+etkiler. Birden fazla instance çalıştıran bir kurulumda bunu aşmanın yolu bir
+sonraki bölümde.
+
+## Paylaşımlı önbellek: Redis
+
+Varsayılan önbellek tek prosese ait. Bu, tek instance çalışan bir sitede en hızlı
+ve en basit kurulum — ama üç kopya çalıştırdığınızda iki sorun çıkar:
+
+1. **Her kopya kendi başına ısınır.** Yeni bir instance açıldığında ya da bir
+   deploy sonrası konteyner yenilendiğinde önbellek boştur; aynı sayfa üç kez
+   render edilir, aynı veri üç kez çekilir.
+2. **Invalidation tek kopyaya ulaşır.** `invalidateHtmlCache()` çağıran webhook
+   yalnızca isteği alan instance'ı tazeler; diğerleri TTL'i bekler. Ziyaretçi
+   hangi kopyaya düştüğüne göre eski ya da yeni içeriği görür.
+
+`cache().redis` bu iki sorunu çözer. Redis **birincil store olmaz**: bellek içi
+önbellek (L1) aynen kalır ve her istek onu okur; Redis ikinci kademedir (L2).
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/haber/:slug": 300 },
+      redis: {
+        enabled: true,
+        url: process.env.REDIS_URL,
+        namespace: "haber-sitesi",
+      },
+    };
+  },
+};
+```
+
+`ioredis` opsiyonel bir peer bağımlılıktır, uygulamanın kendisine kurulur:
+
+```bash
+npm install ioredis
+```
+
+Kurulmadıysa ya da Redis'e bağlanılamıyorsa uyarı basılır ve site **bellek içi
+önbellekle çalışmaya devam eder**. Redis çalışırken düşerse aynı şey olur: bir
+devre kesici art arda beş hatadan sonra katmanı beş saniye baypas eder, böylece
+her istek ağ zaman aşımı beklemez.
+
+### Ne kazanırsınız
+
+- **Soğuk instance sıcak önbellek bulur.** L1'de olmayan bir yol için render
+  çalışmadan önce Redis okunur; başka bir kopya o sayfayı ürettiyse render hiç
+  çalışmaz.
+- **Veri önbelleği kotayı bir kez harcar.** `withDataCache` aynı mantıkla
+  çalışır ve kazanç burada daha büyük: JSON küçük, bir kopyanın çektiği veri
+  hepsine yeter.
+- **Invalidation her kopyaya gider.** `invalidateHtmlCache()`,
+  `clearHtmlCache()` ve `clearDataCache()` bir pub/sub kanalına mesaj bırakır;
+  her instance kendi L1'ine aynı işlemi uygular. Deseni yayınlar, eşleşen
+  anahtarları değil — hangi yolun nerede sıcak olduğu kopyaya bağlı.
+
+### Anahtar düzeni
+
+```
+_jskelet:{namespace}:{buildId}:html:{yol}?{query}
+_jskelet:{namespace}:{buildId}:data:{anahtar}
+_jskelet:{namespace}:events
+```
+
+`buildId` her build'de değişir (`jskelet build` bunu `.jskelet/build.json`
+dosyasına yazar) ve **zorunlu bir parçadır**: saklanan HTML hash'li varlık
+yollarını gömüyor, yani bir deploy'dan sonra eski HTML geçersizdir. Kimlik
+önekte durduğu için yeni sürüm kendiliğinden yeni bir isim alanına yazar, eski
+anahtarlar TTL ile ölür — elle temizlik ya da `FLUSHDB` gerekmez. Build
+çalıştırılmadıysa kimlik `dev` olur.
+
+`namespace` aynı Redis'i paylaşan birden fazla uygulamayı ayırır. Olay kanalı
+bilinçli olarak `buildId` **taşımaz**: deploy sırasında eski ve yeni sürüm yan
+yana koşuyor ve bir purge ikisine de ulaşmalı.
+
+### Bilmeniz gereken takaslar
+
+- **Kişiye özel çıktı paylaşılmaz.** `storable: false` işaretlenen bir render
+  (cookie/`Authorization` okuyan sayfa) Redis'e hiç yazılmaz. Tek prosesteyken
+  bile geçerli olan bu kural paylaşımlı kademede daha da kritik: sızması, bir
+  kullanıcının HTML'ini tüm kümeye servis etmek olur. `degraded` render ve 200
+  dışındaki durum kodları da paylaşılmaz.
+- **Sıkıştırılmış gövdeler varsayılan olarak yerel kalır.** `storeEncoded: true`
+  ile açılabilir, ama girdi başına boyutu iki-üç katına çıkarır; brotli'yi
+  yeniden üretmek çoğu zaman Redis'ten indirmekten ucuzdur.
+- **Yumuşak invalidation Redis kopyasını siler.** Bayatlatmanın Redis karşılığı
+  her anahtar için oku-değiştir-yaz turu demek ve bir webhook binlerce anahtarı
+  birden düşürüyor. Silmenin bedeli, o yolu hiç görmemiş bir kopyanın bir kez
+  render etmesi; L1'i sıcak olan kopyalar eski HTML'i bayat pencerede servis
+  etmeye devam eder.
+- **Yalnızca taze girdi kabul edilir.** Bayat bir kopyayı L1'e almak tazelemeyi
+  sonsuza kadar ertelerdi: girdi bayat kalır, her tur yine Redis'i okur ve
+  render hiç çalışmaz.
+- **Tutarlılık nihai.** Bir purge ile o purge'ün her kopyaya ulaşması arasında
+  kısa bir pencere var. Bu pencerede bir kopya eski HTML'i servis edebilir;
+  süresi TTL ile sınırlı.
+- **Dev'de kapalı tutun.** Dev sunucusu manifest her değiştiğinde önbelleği
+  boşaltıyor; paylaşımlı bir store bunu anlamsızlaştırır. `enabled` yalnızca
+  açıkça `true` verildiğinde açılır.
+
+### Durumu görmek
+
+```js
+import { getRedisStatus } from "jskelet";
+
+app.get("/api/healthcheck", (req, res) => {
+  res.json({ ok: true, cache: getRedisStatus() });
+});
+```
+
+Bağlantı kurulmamışken de güvenle çağrılır. Dönen nesne
+`{ enabled, connected, keyPrefix, buildId, errors, bypassed }`; `bypassed` devre
+kesicinin açık olduğunu, `errors` toplam komut hatasını gösterir. Aynı özet dev
+panelinin raporunda da var ([09-dev-araclari.md](./09-dev-araclari.md)).
+
+Ayarların tam listesi: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ## Prewarm — açılışta ısıtma
 
@@ -589,6 +706,20 @@ 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:
+
+```text
+[prewarm] 37 request errors were not logged individually:
+  31× 502 upstream fetch failed: /api/quotes
+  6× 500 Cannot read properties of undefined (reading 'title')
+```
+
+Böylece bir anlık upstream arızası "warmed …" satırını yüzlerce yığın izinin
+altına gömmüyor. Gerçek trafiğin hataları eskisi gibi anında loglanır, tek bir
+yolun ayrıntısı için dev panelindeki **Prewarming** sekmesine bakılır.
+
 ### Isıtma sırası: `priority`
 
 ```js

package/docs/07-yapilandirma.md

@@ -560,9 +560,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, redis?: object, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -627,6 +627,40 @@ denenir. Amaç var olan bir sayfanın 404'e dönüşmemesi; denemeler tükenirse
 önbelleğe girmeyen bir 503 olur. `false` ya da `attempts: 0` tekrarı kapatır.
 Ayrıntı: [06-cache.md](./06-cache.md).
 
+### `cache().redis`
+
+Opsiyonel Redis ikinci kademesi (L2). Bellek içi önbellek birincil kalır; Redis
+yalnızca L1'de bulunmayan bir yol için render'ı atlatır ve invalidation'ı diğer
+instance'lara yayar. `ioredis` uygulamaya kurulmalı (`npm install ioredis`);
+kurulmadıysa ya da bağlanılamıyorsa uyarı basılır ve site bellek içi önbellekle
+çalışmaya devam eder.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Yalnızca açıkça `true` verildiğinde açılır |
+| `url` | `string \| null` | `null` | `redis://` ya da `rediss://`. Boşsa ioredis varsayılanı (`localhost:6379`) |
+| `namespace` | `string` | `"default"` | Aynı Redis'i paylaşan uygulamaları ayırır |
+| `keyPrefix` | `string` | `"_jskelet"` | Anahtar düzeninin kökü |
+| `html` | `boolean` | `true` | HTML gövdeleri paylaşılsın mı |
+| `data` | `boolean` | `true` | `withDataCache` girdileri paylaşılsın mı |
+| `storeEncoded` | `boolean` | `false` | Brotli/gzip gövdeleri de paylaşılsın mı; girdi başına boyutu iki-üç katına çıkarır |
+| `events` | `boolean` | `true` | pub/sub üzerinden invalidation yayını |
+| `commandTimeoutMs` | `number` | `200` | Tek bir komutun en fazla bekletebileceği süre |
+
+Anahtarlar `_jskelet:{namespace}:{buildId}:html:{yol}?{query}` biçiminde yaşar.
+`buildId` her build'de değişir, böylece deploy sonrası eski HTML kendiliğinden
+geçersiz olur. Kişiye özel (`storable: false`), `degraded` ve 200 dışındaki
+yanıtlar paylaşımlı kademeye hiç yazılmaz. Takaslar ve teşhis:
+[06-cache.md](./06-cache.md).
+
+```js
+redis: {
+  enabled: process.env.NODE_ENV === "production",
+  url: process.env.REDIS_URL,
+  namespace: "haber-sitesi",
+}
+```
+
 ### `cache().prewarm`
 
 | Alan | Tip | Varsayılan | Anlamı |
@@ -747,7 +781,7 @@ basılmaz.
 | --- | --- | --- | --- |
 | `NODE_ENV` | her yer | `production` (start/build), `development` (dev) | Dev overlay, EJS cache, manifest yeniden okuma, route hata davranışı ve prewarm varsayılanlarını belirler. `jskelet dev` bunu kendisi ayarlar — `cross-env` gerekmez. |
 | `PORT` | `startServer` | `3000` | Dinlenecek port |
-| `HOST` | `startServer` | `0.0.0.0` | Bağlanılacak arayüz |
+| `HOST` | `startServer` | `::` | Bağlanılacak arayüz. Varsayılan çift yığın dinler (IPv6 + IPv4); IPv6 yoksa `0.0.0.0`'a düşer |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | İmzalı cookie sırrı. `security.cookieSecret` verilmediğinde buradan okunur; ikisi de yoksa imzalı cookie API'si hata verir. [12](./12-panel-ve-oturum.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |

package/docs/10-dagitim.md

@@ -43,7 +43,7 @@ ayarlamayı düşünmeniz gerekenler:
 | --- | --- | --- |
 | `NODE_ENV` | `production` | Şablon cache'i, manifest'in bir kez okunması, bozuk route modülünde fırlatma |
 | `PORT` | `3000` | Orkestratörünüzün beklediği port |
-| `HOST` | `0.0.0.0` | Kapsayıcı içinde dışarıdan erişim için (varsayılan) |
+| `HOST` | `0.0.0.0` | Yalnızca IPv4 dinlemek gerekiyorsa. Varsayılan `::` zaten çift yığın dinler |
 | `PREWARM_MAX` | Site boyutuna göre | Açılışta ısıtılacak sayfa sayısı |
 | `PREWARM_INTERVAL_SECONDS` | `0` ya da uzun bir değer | Hiç ziyaret edilmeyen sayfaları sıcak tutmak isterseniz |
 | `DEV_TOKEN` | Yalnızca staging'de | Yayına açılmamış ortamı gizler |

package/docs/en/06-caching.md

@@ -542,7 +542,129 @@ not cleared the page would keep requesting a deleted file
 
 Because the cache lives in process memory, if you run more than one
 process/replica each one has its own cache; `clearHtmlCache()` only affects the
-process it is called in.
+process it is called in. The next section covers how to get past this when you
+run several instances.
+
+## A shared cache: Redis
+
+The default cache belongs to a single process. That is the fastest and simplest
+setup for a site running one instance — but two problems appear once you run
+three replicas:
+
+1. **Every replica warms up on its own.** When a new instance comes up, or a
+   container is replaced after a deploy, its cache is empty: the same page is
+   rendered three times and the same data is fetched three times.
+2. **Invalidation reaches one replica.** The webhook that calls
+   `invalidateHtmlCache()` only refreshes the instance that received the
+   request; the others wait for the TTL. A visitor sees the old or the new
+   content depending on which replica they land on.
+
+`cache().redis` solves both. Redis is **not the primary store**: the in-process
+cache (L1) stays exactly as it is and every request reads it; Redis is a second
+tier (L2).
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/news/:slug": 300 },
+      redis: {
+        enabled: true,
+        url: process.env.REDIS_URL,
+        namespace: "news-site",
+      },
+    };
+  },
+};
+```
+
+`ioredis` is an optional peer dependency, installed in the application itself:
+
+```bash
+npm install ioredis
+```
+
+If it is not installed, or Redis cannot be reached, a warning is printed and the
+site **keeps running on the in-process cache**. The same happens if Redis goes
+down while running: a circuit breaker bypasses the tier for five seconds after
+five consecutive failures, so requests do not each wait for a network timeout.
+
+### What you get
+
+- **A cold instance finds a warm cache.** For a path that is not in L1, Redis is
+  read before the render runs; if another replica already produced that page, the
+  render never happens.
+- **The data cache spends the quota once.** `withDataCache` works the same way,
+  and the gain is bigger here: JSON is small, and what one replica fetched is
+  enough for all of them.
+- **Invalidation reaches every replica.** `invalidateHtmlCache()`,
+  `clearHtmlCache()` and `clearDataCache()` leave a message on a pub/sub
+  channel and each instance applies the same operation to its own L1. The
+  pattern is published, not the matched keys — which path is hot where depends
+  on the replica.
+
+### Key layout
+
+```
+_jskelet:{namespace}:{buildId}:html:{path}?{query}
+_jskelet:{namespace}:{buildId}:data:{key}
+_jskelet:{namespace}:events
+```
+
+`buildId` changes with every build (`jskelet build` writes it to
+`.jskelet/build.json`) and it is a **required** part: the stored HTML embeds
+hashed asset paths, so after a deploy the old HTML is invalid. Because the id
+sits in the prefix, a new version automatically writes into a new namespace and
+the old keys die with their TTL — no manual cleanup and no `FLUSHDB`. When the
+build has not been run the id is `dev`.
+
+`namespace` separates several applications sharing one Redis. The event channel
+deliberately does **not** carry `buildId`: during a deploy the old and the new
+version run side by side and a purge has to reach both.
+
+### Trade-offs worth knowing
+
+- **Personalised output is never shared.** A render marked `storable: false` (a
+  page that read a cookie or `Authorization`) is never written to Redis. The
+  rule already holds in a single process, but it matters far more in a shared
+  tier: a leak would mean serving one user's HTML to the whole cluster.
+  `degraded` renders and non-200 status codes are not shared either.
+- **Compressed bodies stay local by default.** `storeEncoded: true` turns this
+  on, but it doubles or triples the size per entry; recomputing brotli is
+  usually cheaper than downloading it from Redis.
+- **A soft invalidation deletes the Redis copy.** Staling in Redis would mean a
+  read-modify-write round per key, and a webhook drops thousands of keys at
+  once. The cost of deleting is one render on a replica that never saw that
+  path; replicas whose L1 is hot keep serving the old HTML through the stale
+  window.
+- **Only fresh entries are accepted.** Promoting a stale copy into L1 would
+  postpone the refresh forever: the entry stays stale, every pass reads Redis
+  again and the render never runs.
+- **Consistency is eventual.** There is a short window between a purge and that
+  purge reaching every replica. During it a replica may serve the old HTML; the
+  window is bounded by the TTL.
+- **Keep it off in dev.** The dev server clears the cache whenever the manifest
+  changes, which makes a shared store pointless. `enabled` only turns on when
+  `true` is passed explicitly.
+
+### Seeing the status
+
+```js
+import { getRedisStatus } from "jskelet";
+
+app.get("/api/healthcheck", (req, res) => {
+  res.json({ ok: true, cache: getRedisStatus() });
+});
+```
+
+Safe to call even with no connection. The returned object is
+`{ enabled, connected, keyPrefix, buildId, errors, bypassed }`; `bypassed` tells
+you the circuit breaker is open and `errors` is the total command failure count.
+The same summary is in the dev panel report
+([09-dev-tools.md](./09-dev-tools.md)).
+
+The full list of settings: [07-configuration.md](./07-configuration.md).
 
 ## Prewarm — warming up at startup
 
@@ -605,6 +727,21 @@ 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:
+
+```text
+[prewarm] 37 request errors were not logged individually:
+  31× 502 upstream fetch failed: /api/quotes
+  6× 500 Cannot read properties of undefined (reading 'title')
+```
+
+This way a momentary upstream failure cannot bury the "warmed …" line under
+hundreds of stack traces. Errors from real traffic are logged immediately as
+before; for the detail of a single path, look at the **Prewarming** tab in the
+dev panel.
+
 ### Warm-up order: `priority`
 
 ```js

package/docs/en/07-configuration.md

@@ -572,9 +572,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, redis?: object, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -643,6 +643,40 @@ transient upstream failure. The point is that an existing page never turns into
 a 404; if the retries are exhausted the response is an uncached 503. `false` or
 `attempts: 0` disables the retry. Details: [06-caching.md](./06-caching.md).
 
+### `cache().redis`
+
+An optional Redis second tier (L2). The in-process cache stays primary; Redis
+only skips the render for a path that is not in L1 and spreads invalidation to
+the other instances. `ioredis` has to be installed in the application
+(`npm install ioredis`); if it is missing or unreachable a warning is printed and
+the site keeps running on the in-process cache.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Only turns on when `true` is passed explicitly |
+| `url` | `string \| null` | `null` | `redis://` or `rediss://`. When empty, the ioredis default (`localhost:6379`) |
+| `namespace` | `string` | `"default"` | Separates applications sharing one Redis |
+| `keyPrefix` | `string` | `"_jskelet"` | Root of the key layout |
+| `html` | `boolean` | `true` | Whether HTML bodies are shared |
+| `data` | `boolean` | `true` | Whether `withDataCache` entries are shared |
+| `storeEncoded` | `boolean` | `false` | Whether brotli/gzip bodies are shared too; doubles or triples the size per entry |
+| `events` | `boolean` | `true` | Invalidation broadcast over pub/sub |
+| `commandTimeoutMs` | `number` | `200` | At most how long a single command may block |
+
+Keys live as `_jskelet:{namespace}:{buildId}:html:{path}?{query}`. `buildId`
+changes with every build, so old HTML becomes invalid on its own after a deploy.
+Personalised (`storable: false`), `degraded` and non-200 responses are never
+written to the shared tier. Trade-offs and diagnosis:
+[06-caching.md](./06-caching.md).
+
+```js
+redis: {
+  enabled: process.env.NODE_ENV === "production",
+  url: process.env.REDIS_URL,
+  namespace: "news-site",
+}
+```
+
 ### `cache().prewarm`
 
 | Field | Type | Default | Meaning |
@@ -764,7 +798,7 @@ and no warning is printed.
 | --- | --- | --- | --- |
 | `NODE_ENV` | everywhere | `production` (start/build), `development` (dev) | Determines the dev overlay, EJS cache, manifest re-reading, route error behaviour and prewarm defaults. `jskelet dev` sets it itself — `cross-env` is not needed. |
 | `PORT` | `startServer` | `3000` | Port to listen on |
-| `HOST` | `startServer` | `0.0.0.0` | Interface to bind to |
+| `HOST` | `startServer` | `::` | Interface to bind to. The default listens dual-stack (IPv6 + IPv4); it falls back to `0.0.0.0` where IPv6 is unavailable |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | The signed cookie secret. Read when `security.cookieSecret` is not set; if neither exists, the signed cookie API throws. [12](./12-dashboards-and-sessions.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
 | `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |

package/docs/en/10-deployment.md

@@ -44,7 +44,7 @@ considering in production:
 | --- | --- | --- |
 | `NODE_ENV` | `production` | Template cache, reading the manifest once, throwing on a broken route module |
 | `PORT` | `3000` | The port your orchestrator expects |
-| `HOST` | `0.0.0.0` | For external access inside a container (the default) |
+| `HOST` | `0.0.0.0` | Only if you need to listen on IPv4 alone; the `::` default already listens dual-stack |
 | `PREWARM_MAX` | Depends on site size | Number of pages warmed at startup |
 | `PREWARM_INTERVAL_SECONDS` | `0` or a long value | If you want to keep never-visited pages warm |
 | `DEV_TOKEN` | Staging only | Hides an environment that is not public yet |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "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",
@@ -66,6 +66,7 @@
   "peerDependencies": {
     "@phosphor-icons/core": "^2.1.1",
     "@tailwindcss/postcss": "^4.3.3",
+    "ioredis": "^5.4.0 || ^6.0.0",
     "lightningcss": "^1.32.0",
     "postcss": "^8.5.26",
     "sharp": "^0.35.4",
@@ -78,6 +79,9 @@
     "@tailwindcss/postcss": {
       "optional": true
     },
+    "ioredis": {
+      "optional": true
+    },
     "lightningcss": {
       "optional": true
     },

package/src/build/paths.mjs

@@ -74,7 +74,32 @@ function manifestFile() {
 /** @param {Record<string, string>} manifest */
 export function writeManifest(manifest) {
   fs.mkdirSync(paths.generated, { recursive: true });
-  fs.writeFileSync(manifestFile(), `${JSON.stringify(manifest, null, 2)}\n`);
+  const json = `${JSON.stringify(manifest, null, 2)}\n`;
+  fs.writeFileSync(manifestFile(), json);
+  writeBuildId(json);
+}
+
+/**
+ * Build kimliği: manifest içeriğinin hash'i.
+ *
+ * Paylaşımlı bir önbellekte (Redis) HTML anahtarları bu kimliği taşımak
+ * zorunda. Saklanan HTML hash'li varlık yollarını gömüyor; yeni bir deploy'dan
+ * sonra eski HTML başka bir node'dan geri gelirse artık var olmayan
+ * `/assets/app.<eskihash>.css` istenir ve sayfa stilsiz kalır. Kimlik önekte
+ * durduğunda yeni build kendiliğinden yeni bir isim alanına yazar, eskisi TTL
+ * ile ölür — elle temizlik gerekmez.
+ *
+ * Kimlik manifest'in **içine** yazılmaz: oradaki her anahtar `asset()`
+ * yüzeyine sızıyor.
+ *
+ * @param {string} manifestJson
+ */
+function writeBuildId(manifestJson) {
+  const payload = { id: hash(manifestJson), createdAt: new Date().toISOString() };
+  fs.writeFileSync(
+    path.join(paths.generated, "build.json"),
+    `${JSON.stringify(payload, null, 2)}\n`,
+  );
 }
 
 /**

package/src/config/defaults.js

@@ -120,6 +120,41 @@ export const DEFAULT_DATA_CACHE = {
   staleFactor: 10,
 };
 
+/**
+ * Opsiyonel Redis ikinci kademesi (L2).
+ *
+ * Redis **birincil store değil**: bellek içi önbellek (L1) aynen kalır, Redis
+ * iki iş yapar — L1'de bulunmayan bir sayfa için render'ı atlatmak ve
+ * invalidation'ı bütün node'lara yaymak. Tek instance çalışan bir kurulumda
+ * kazanç neredeyse yok; bu yüzden `enabled` varsayılan olarak kapalı.
+ *
+ * `storeEncoded` kapalı, çünkü sıkıştırılmış gövdeleri de paylaşmak girdi
+ * başına boyutu iki-üç katına çıkarır ve brotli'yi yeniden üretmek Redis'ten
+ * indirmekten çoğu zaman daha ucuz.
+ */
+export const DEFAULT_REDIS = {
+  enabled: false,
+  /** `redis://` ya da `rediss://`. Boşsa ioredis varsayılanı (localhost:6379). */
+  url: /** @type {string | null} */ (null),
+  /** Aynı Redis'i paylaşan birden fazla uygulamayı ayırır. */
+  namespace: "default",
+  keyPrefix: "_jskelet",
+  /** HTML gövdeleri paylaşılsın mı. */
+  html: true,
+  /** Veri önbelleği paylaşılsın mı. */
+  data: true,
+  /** Brotli/gzip gövdeleri de paylaşılsın mı. */
+  storeEncoded: false,
+  /** pub/sub üzerinden invalidation yayını. */
+  events: true,
+  /**
+   * Tek bir komutun en fazla bekletebileceği süre. Önbellek okuması isteği
+   * bloklayan bir adım: Redis takıldığında render'a düşmek, ağı beklemekten
+   * iyidir.
+   */
+  commandTimeoutMs: 200,
+};
+
 /** Oturuma bağlı sayfalar ısıtılmaz; uygulama kendi listesini verebilir. */
 export const DEFAULT_PREWARM_SKIP = ["/api/", "/_fragment/", "/__jskelet/"];