jskelet 0.2.2 → 0.2.3

package/docs/03-routing.md

@@ -123,6 +123,10 @@ app.get(
 | `revalidate` | `number` (saniye) | HTML önbellek TTL'i. Verilmezse ya da 0 ise bu route önbelleklenmez. `jskelet.config.mjs` → `cache().html` içindeki eşleşen bir kural bu değeri **ezer**. |
 | `private` | `boolean` | Sayfa ziyaretçiye bağlı. Önbellek devre dışı kalır, `cache().html` deseni bunu **ezemez**, yanıt `private, no-store` ve `Vary: Cookie` ile ETag'siz gider. |
 
+`revalidate` verilse bile **query parametresi taşıyan istek varsayılan olarak
+dinamiktir**; o yol için `cache().query` altında bir izin listesi tanımlamak
+gerekir ([06-cache.md](./06-cache.md)).
+
 Oturuma bağlı her sayfa `private: true` almalı; önbellek anahtarında kimlik
 olmadığı için bayrak olmadan bir kullanıcının HTML'i bir başkasına servis
 edilir. Framework bu hatayı çalışma zamanında da yakalıyor (controller cookie

package/docs/06-cache.md

@@ -110,17 +110,30 @@ saklayabiliyordu.
 ## Cache anahtarı
 
 ```
-`${req.path}?${new URLSearchParams(query).toString()}`
+`${yol}?${izin verilen query parametreleri, sıralı}`
 ```
 
-Yani yol **ve tüm query parametreleri** anahtarın parçasıdır. `/liste?sayfa=2`
-ile `/liste?sayfa=3` ayrı girdilerdir.
+Query'siz bir istek için anahtar yalnızca yoldur. **Query parametresi taşıyan
+istek varsayılan olarak dinamiktir**: önbelleğe hiç girmez ve `private,
+no-store` ile gider. Bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
+gibi sonsuz sayıda anahtar üretiyor ve 500 girdilik store'da LRU, gerçek
+sayfaları kampanya varyantları için dışarı atıyor.
 
-Bunun pratik sonucu: query string'e bağlı olmayan bir sayfa, farklı kampanya
-parametreleriyle (`?utm_source=…`) çağrıldığında her kombinasyon için ayrı bir
-girdi üretir. Bu tür parametreleri ters proxy katmanında temizlemek ya da
-önbelleği kapatmak (`revalidate` vermemek) makul bir önlemdir; store varsayılan
-olarak en fazla 500 girdi tutar ve LRU ile en eskiyi düşürür.
+Hangi parametrenin çıktıyı gerçekten değiştirdiğini uygulama bildirir —
+`jskelet.config.mjs` → `cache().query`:
+
+```js
+cache: () => ({
+  html: { "/liste": 60 },
+  query: { "/liste": ["sayfa"] },
+}),
+```
+
+Artık `/liste?sayfa=2` ile `/liste?sayfa=3` ayrı girdiler, `/liste?sayfa=2&utm_source=x`
+ise `?sayfa=2` kopyasını paylaşır: listede olmayan parametre anahtara girmez.
+Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (dikkat: girdi
+sayısını sınırlayan tek şey `maxEntries` olur), `[]` ile eşlenirse query tamamen
+yok sayılır. Ayrıntı: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ## Stale-while-revalidate
 
@@ -738,6 +751,13 @@ Bağlantı kurulmamışken de güvenle çağrılır. Dönen nesne
 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)).
 
+İki teşhis yüzeyi daha var:
+
+| Çağrı | Ne der |
+| --- | --- |
+| `getRedisDetails()` | Bağlantının **nereye** kurulduğu: adres, TLS, veritabanı, `namespace`, hangi türlerin paylaşıldığı, purge yayınına abone olunup olunmadığı. Şifre asla dönmez — bağlantı URL'i sır taşıyor olabilir. |
+| `inspectRedis()` | Paylaşımlı kademede gerçekten ne durduğu: tür başına anahtar sayısı, `DBSIZE` ve `used_memory`. Bir `SCAN` turu olduğu için **istek yolunda çağrılmaz**; yönetim panelinde de ayrı bir düğmeye bağlı. |
+
 Ayarların tam listesi: [07-yapilandirma.md](./07-yapilandirma.md).
 
 ## Yönetim paneli
@@ -795,9 +815,12 @@ Panel açıldığında sunucu logu şifreyi basar:
 
 | Bölüm | Gösterdiği |
 | --- | --- |
-| Üst satır | Ortam, pid, uptime, RSS |
+| Üst satır | Sürüm, ortam, pid, uptime, RSS |
 | Kartlar | HTML girdi sayısı ve sınırı, bellekteki HTML boyutu, bayat girdi sayısı, veri girdisi sayısı, Redis durumu (`connected` / `bypassed` / `off`), ısıtma turunun ilerlemesi |
-| Girdi listesi | HTML: anahtar, taze/bayat, boyut, durum kodu, kalan TTL, bağımlılık sayısı, hazır sıkıştırılmış gövdeler. Veri: anahtar, taze/bayat, kalan TTL |
+| Paylaşımlı kademe | Bağlantının **nereye** kurulduğu (adres, TLS, veritabanı), anahtar öneki ve `namespace`, `buildId`, hangi türlerin paylaşıldığı, sıkıştırılmış gövde ve purge yayını durumu, komut zaman aşımı ve hata sayısı. Kapalıysa yerine Redis önerisi ve kurulum parçacığı çıkar. |
+| Cloudflare | Zone, plan, cache ile ilgili zone ayarları, development mode'un kalan süresi, Tiered Cache / Cache Reserve durumu ve cache isabet oranı. Bağlı değilse kurulum parçacığı çıkar. |
+| Host | Makinenin RAM kullanımı ve projenin bulunduğu diskin doluluğu |
+| Girdi listesi | HTML: yol (yeni sekmede açılır), taze/bayat, boyut, durum kodu, kalan TTL, bağımlılık sayısı, hazır sıkıştırılmış gövdeler. Veri: anahtar (tıklayınca panoya kopyalanır), taze/bayat, kalan TTL |
 
 Liste **anahtar bazında filtrelenir** ve filtre sunucuda uygulanır: veri
 önbelleğinde on binlerce anahtar olabiliyor. Her istekte en fazla 500 satır
@@ -814,7 +837,10 @@ değil.
 | Clear HTML cache | `clearHtmlCache()` |
 | Clear data cache (önek opsiyonel) | `clearDataCache(prefix)` |
 | Drop shared keys | Redis'teki `html` ya da `data` isim alanını tarar ve düşürür |
+| Count keys in Redis | `inspectRedis()` — tür başına anahtar sayısı, `DBSIZE` ve `used_memory` |
 | Prewarm | `prewarm()` — tur arkada koşar, ilerleme kartta görünür |
+| Cloudflare purge (her şey / bellekteki URL'ler / prefix / host / tag) | `purgeCloudflare()` |
+| Cloudflare ayarı ya da özelliği değiştirmek | Zone ayarları ve Tiered Cache / Cache Reserve |
 
 Hepsi paylaşımlı kademeye de yayılır: tek kopyanın önbelleğini boşaltmak,
 kümede çalışan bir kurulumda "temizledim ama hâlâ eski" sorusunu üretir.
@@ -824,6 +850,117 @@ desenine bakar ve bir yolun **bütün** query varyantlarını düşürür,
 `dropHtmlCacheKey()` ise tam anahtarı alır — `/liste?sayfa=2` düşerken
 `/liste?sayfa=3` sıcak kalır.
 
+## CDN kademesi: Cloudflare
+
+Buraya kadar anlatılan her şey **origin** önbelleği. Önünde Cloudflare varsa
+ziyaretçinin gördüğü HTML çoğu zaman hiç size ulaşmıyor: edge'deki kopya
+TTL'ini doldurana kadar servis edilir. Bu yüzden `invalidateHtmlCache()`
+tek başına "sayfayı güncelledim ama eski hâli görünüyor" sorununu çözmez —
+origin tazelenir, edge beklemeye devam eder.
+
+JSkelet iki kademeyi aynı yerden yönetilebilir kılar.
+
+### Kurulum
+
+Token bir sır; config dosyasına değil ortama yazılır:
+
+```bash
+JSKELET_CLOUDFLARE_KEY=... # API token
+JSKELET_CLOUDFLARE_ZONE_ID=... # zone kimliği
+JSKELET_CLOUDFLARE_HOSTNAME=example.com # opsiyonel
+```
+
+Token'a gereken izinler, yapmak istediğinize göre: purge için `Zone.Cache
+Purge`, ayarları değiştirmek için `Zone.Zone Settings`, isabet oranı ve edge
+kırılımı için `Zone.Analytics` (salt okunur). Yalnızca purge izni verilen bir
+token'la panel açılır, ayar bölümleri hata yazar.
+
+Zone kimliği ve site adı sır olmadığı için `jskelet.config.mjs` içinden de
+verilebilir; env her zaman önceliklidir:
+
+```js
+cache: {
+  cloudflare: {
+    zoneId: "…",
+    hostname: "example.com", // purge tam URL ister; yol → URL çevrimi için
+    analyticsHours: 24,
+  },
+}
+```
+
+`hostname` verilmezse purge URL'leri panelin açıldığı origin'den türetilir.
+Paneli iç bir adresten (`http://10.0.0.4:3000`) açıyorsanız bu adresin
+Cloudflare'de karşılığı yok; o kurulumda `hostname` zorunlu.
+
+### Ne yapılabilir
+
+Cloudflare'in cache yüzeyinde ne varsa panelde de var:
+
+| İşlem | Not |
+| --- | --- |
+| Purge everything | Zone'un tamamı. En kaba araç; ısınma maliyeti yüksek |
+| Purge by URL | Panelin o an bellekte tuttuğu sayfalar tek düğmeyle; ya da satır başına `cf purge` |
+| Purge by prefix / host / tag | Artık her planda çalışıyor; istek başına 100 anahtar |
+| Development mode | Üç saat boyunca edge önbelleğini baypas eder, sonra kendiliğinden kapanır |
+| Cache level, browser cache TTL, query string sıralaması, Always Online | Zone ayarları |
+| Tiered Cache, Regional Tiered Cache, Cache Reserve | Plana bağlı; kapalı planda "unavailable" görünür |
+| Clear Cache Reserve | Purge'den ayrı: `purge_everything` edge'i düşürür, R2'deki kalıcı kopya kalır |
+
+Uzun URL listeleri istek başına 100 anahtarlık partilere bölünür ve **sırayla**
+gönderilir. Paralel göndermek Free planda dakikada beş isteklik hız freni
+yüzünden yarısı reddedilen bir tur demek.
+
+Kod tarafında aynı yüzey:
+
+```js
+import { invalidateHtmlCache, purgeCloudflare, toCloudflareUrls } from "jskelet";
+
+export async function onPostPublished(slug) {
+  const paths = ["/", `/blog/${slug}`];
+
+  invalidateHtmlCache(paths); // origin
+  await purgeCloudflare({ files: toCloudflareUrls(paths) }); // edge
+}
+```
+
+Bu modüldeki hiçbir fonksiyon fırlatmaz: token yoksa, Cloudflare 403 dönerse
+ya da ağ düşerse sonuç `{ ok: false, error }` olur. Bir CDN arızası içerik
+yayınlama akışını kesmemeli.
+
+### "Bu sayfa kaç edge'de cache'li?" — sorulabilen ve sorulamayan
+
+Cloudflare API'sinde bir objenin **envanterini** veren uç yok. Yüzlerce şehirde
+birbirinden bağımsız önbellekler var ve hiçbiri "şu an bende bu URL'in kopyası
+var mı" sorusuna cevap vermiyor. Panel bu yüzden envanter değil **gözlem**
+gösterir: bir yol girip sorguladığınızda GraphQL analitiğinden son N saatte
+hangi kolonun (IST, FRA, AMS…) o yolu kaç kez cache'ten, kaç kez origin'den
+servis ettiği gelir.
+
+```js
+const report = await fetchPathEdges({ path: "/blog", hours: 24 });
+// → { colos: [{ colo: "IST", hits: 7, misses: 2 }, …], hits, misses }
+```
+
+Okurken iki sınırı akılda tutun: hiç istek almamış bir edge listede görünmez,
+kopyası olsa da; ve veri kümesi örneklemeli, yani oranlar güvenilir ama mutlak
+sayılar yaklaşıktır.
+
+Seçtiğiniz bir edge'i **ısıtmanın** da yolu yok. Bir obje ancak o koloya
+yönlenen gerçek bir istekle o edge'in önbelleğine giriyor; sunucudan
+"Frankfurt'a bunu cache'let" diyemezsiniz. Pratikte yapılabilen üç şey var:
+
+- **Origin'i ısıtmak** (`prewarm`): ilk isteği alan edge cevabı hazır bulur,
+  o istek yavaşlamaz.
+- **Tiered Cache**: edge'ler origin'e doğrudan gitmez, aradaki üst katmandan
+  besleniyor; bir şehirdeki ilk istek diğer şehirler için de ısıtma sayılır.
+- **Cache Reserve**: uzun kuyruklu içerik için R2'de kalıcı kopya; edge
+  düşünce istek origin'e kadar inmiyor.
+
+`hit` oranınız düşükse önce cevabın cache'lenebilir olup olmadığına bakın:
+`Cache-Control: private`, `Set-Cookie` ve query string ayarları edge'in
+cache'lememe kararının en sık sebepleri, ve bu panelde `dynamic` olarak
+görünür.
+
 ## Prewarm — açılışta ısıtma
 
 Next'teki build-time prerender'ın karşılığı, ama çıktı diske yazılmaz: önbellek

package/docs/07-yapilandirma.md

@@ -115,6 +115,7 @@ export default {
   async cache() {
     return {
       html: { "/": 60, "/haber/:slug": 300 },
+      query: { "/arama": ["q", "page"] },
       maxEntries: 500,
       data: { maxEntries: 10000, staleFactor: 10 },
       prewarm: {
@@ -560,9 +561,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, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, query: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -582,6 +583,39 @@ Tek istisna `route(fn, { private: true })`: bu route'ta desen eşleşse bile yok
 sayılır. Kilidin tek yönlü olması bilinçli — ters yönde bir hata, bir
 kullanıcının HTML'inin bir başkasına servis edilmesi anlamına geliyor.
 
+### `cache().query`
+
+Desen → cache anahtarına girmesine izin verilen query parametreleri.
+
+**Varsayılan olarak query parametresi taşıyan istek dinamiktir**: `cache().html`
+o yolu kapsıyor olsa bile HTML önbelleğine hiç girmez, `private, no-store` ile
+gider. Sebebi basit — bir yolun bütün varyantlarını cache'lemek `?utm_source=…`
+gibi sonsuz sayıda anahtar üretiyor ve `maxEntries` sınırına dayandığında
+LRU'daki gerçek sayfaları dışarı atıyor. Hangi parametrenin çıktıyı gerçekten
+değiştirdiğini yalnızca uygulama bilir.
+
+```js
+query: {
+  "/arama": ["q", "page"], // yalnızca bu ikisi anahtara girer
+  "/urunler": ["kategori"],
+  "/rapor/:id": true, // bütün parametreler anahtara girer
+  "/kampanya": [], // query tamamen yok sayılır
+}
+```
+
+- **İzin listesi** (`string[]`): listedeki parametreler anahtara girer, her
+ farklı değer kendi girdisini alır. Listede olmayan parametreler **yok
+ sayılır** — sayfa yine cache'lenir ve bütün kampanya varyantları tek kopyayı
+ paylaşır.
+- **`true`**: bütün parametreler anahtara girer. Anahtar sayısını sınırlayan
+ tek şey `maxEntries` olur; yalnızca değer kümesi kapalı olan yollarda kullan.
+- **`[]`**: query hiç dikkate alınmaz, bütün varyantlar query'siz sürümün
+ HTML'ini alır.
+
+Parametreler anahtara **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı girdiyi
+paylaşır. `route(fn, { private: true })` bu bölümden etkilenmez; private route
+hiçbir koşulda cache'lenmez.
+
 ### `cache().maxEntries`
 
 **Tip:** `number` — **Varsayılan:** `500`
@@ -722,6 +756,30 @@ yetkisi demek ve her deploy eski erişimi kendiliğinden iptal etmeli. Yasaklı
 yetkisiz her cevap `404`'tür. Kullanım ve ekran ayrıntıları:
 [06-cache.md](./06-cache.md).
 
+### `cache().cloudflare`
+
+CDN kademesi. JSkelet'in önbelleği origin önbelleği; ziyaretçinin gördüğü kopya
+edge'de duruyor. Bu bölüm bağlıysa panelden edge purge'ü, cache ile ilgili zone
+ayarları ve cache isabet oranı yönetilebilir.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | `false` verilirse env'de token olsa bile yüzey kapalı kalır |
+| `zoneId` | `string \| null` | `null` | Zone kimliği (`JSKELET_CLOUDFLARE_ZONE_ID` ezer) |
+| `apiToken` | `string \| null` | `null` | Token; **env tercih edilir**, config'e yazmak sırrı repoya sokar |
+| `hostname` | `string \| null` | `null` | Purge tam URL ister; yol → URL çevrimi bu ad üzerinden yapılır. Verilmezse panelin açıldığı origin kullanılır |
+| `analyticsHours` | `number` | `24` | Analitik penceresi, en çok `72` |
+
+Token yalnızca `JSKELET_CLOUDFLARE_KEY` ile verildiğinde config dosyası temiz
+kalır; izinler yapılacak işe göre: purge için `Zone.Cache Purge`, ayarlar için
+`Zone.Zone Settings`, isabet oranı için `Zone.Analytics` (salt okunur). Token
+hiçbir panel cevabında dönmez, yalnızca "env'den geldi" bilgisi görünür.
+
+Zone bağlı değilse panel bir uyarı değil kurulum önerisi gösterir; Cloudflare
+hata dönerse ilgili bölüm hatayı yazar ve panelin kalanı çalışmaya devam eder.
+Neyin sorulabildiği — özellikle "bu sayfa kaç edge'de cache'li" sorusunun neden
+tam cevabı olmadığı — [06-cache.md](./06-cache.md) içinde.
+
 ```js
 panel: {
   enabled: process.env.CACHE_PANEL === "1",
@@ -852,6 +910,9 @@ basılmaz.
 | `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) |
 | `JSKELET_CACHE_PANEL` | `createApp` | — | Ayarlıysa önbellek panelini açar; `0` config'te açık olan paneli kapatır. Env config'i ezer, çünkü panel genelde bir arıza sırasında tek seferlik açılır. [06](./06-cache.md) |
+| `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache yüzeyi | — | API token. Verilene kadar CDN purge'ü ve edge analitiği kapalıdır; config'teki `apiToken`'ı ezer. Token hiçbir cevapta dönmez. [06](./06-cache.md) |
+| `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache yüzeyi | — | Zone kimliği. Token'la birlikte verilmedikçe hiçbir Cloudflare ucu çağrılmaz |
+| `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache yüzeyi | — | Purge URL'lerinin kökü. Panel iç bir adresten açılıyorsa gerekir |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Paralel işçi sayısı |

package/docs/en/03-routing.md

@@ -126,6 +126,10 @@ app.get(
 | `revalidate` | `number` (seconds) | The HTML cache TTL. If it is not given, or is 0, this route is not cached. A matching rule in `jskelet.config.mjs` → `cache().html` **overrides** this value. |
 | `private` | `boolean` | The page depends on the visitor. The cache is disabled, a `cache().html` pattern **cannot** override that, and the response is sent with `private, no-store` and `Vary: Cookie`, without an ETag. |
 
+Even with `revalidate` given, **a request that carries a query parameter is
+dynamic by default**; that path needs an allowlist under `cache().query`
+([06-caching.md](./06-caching.md)).
+
 Every session-dependent page needs `private: true`; because identity is not part
 of the cache key, without the flag one user's HTML is served to another. The
 framework also catches this at runtime (a render that reads cookies is never

package/docs/en/06-caching.md

@@ -117,18 +117,31 @@ The cache also only kicks in for `GET` requests.
 ## The cache key
 
 ```
-`${req.path}?${new URLSearchParams(query).toString()}`
+`${path}?${the allowed query parameters, sorted}`
 ```
 
-So the path **and all query parameters** are part of the key. `/list?page=2`
-and `/list?page=3` are separate entries.
+For a request without a query the key is just the path. **A request that carries
+a query parameter is dynamic by default**: it never enters the cache and is sent
+with `private, no-store`. Caching every variant of a path mints an unbounded
+number of keys (`?utm_source=…` and friends), and in a 500-entry store LRU then
+evicts the real pages in favour of campaign variants.
 
-The practical consequence: a page that does not depend on the query string
-produces a separate entry for every combination when it is called with
-different campaign parameters (`?utm_source=…`). Stripping such parameters at
-the reverse proxy layer, or turning off the cache (by not supplying
-`revalidate`), is a reasonable precaution; by default the store holds at most
-500 entries and evicts the oldest with LRU.
+Which parameter actually changes the output is declared by the application, in
+`jskelet.config.mjs` → `cache().query`:
+
+```js
+cache: () => ({
+  html: { "/list": 60 },
+  query: { "/list": ["page"] },
+}),
+```
+
+Now `/list?page=2` and `/list?page=3` are separate entries, while
+`/list?page=2&utm_source=x` shares the `?page=2` copy: a parameter outside the
+list never reaches the key. A pattern mapped to `true` puts every parameter in
+the key (careful: nothing but `maxEntries` then bounds the entry count), and one
+mapped to `[]` ignores the query entirely. Details:
+[07-configuration.md](./07-configuration.md).
 
 ## Stale-while-revalidate
 
@@ -756,6 +769,13 @@ 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)).
 
+Two more diagnostic surfaces:
+
+| Call | What it tells you |
+| --- | --- |
+| `getRedisDetails()` | **Where** the connection points: address, TLS, database, `namespace`, which kinds are shared, whether the purge channel is subscribed. The password is never returned — a connection URL may carry one. |
+| `inspectRedis()` | What is actually in the shared tier: keys per kind, `DBSIZE` and `used_memory`. It runs a `SCAN`, so **never call it on the request path**; in the admin panel it sits behind its own button. |
+
 The full list of settings: [07-configuration.md](./07-configuration.md).
 
 ## The admin panel
@@ -817,9 +837,12 @@ When the panel is on, the server log prints the password:
 
 | Area | Contents |
 | --- | --- |
-| Top bar | Environment, pid, uptime, RSS |
+| Top bar | Version, environment, pid, uptime, RSS |
 | Cards | HTML entry count and limit, HTML bytes in memory, stale entry count, data entry count, Redis state (`connected` / `bypassed` / `off`), prewarm progress |
-| Entry list | HTML: key, fresh/stale, size, status code, remaining TTL, dependency count, precompressed bodies. Data: key, fresh/stale, remaining TTL |
+| Shared tier | **Where** the connection points (address, TLS, database), the key prefix and `namespace`, the `buildId`, which kinds are shared, the state of compressed bodies and the purge broadcast, the command timeout and the error count. When it is off, a Redis recommendation with an install snippet takes its place. |
+| Cloudflare | Zone, plan, cache related zone settings, how long development mode has left, Tiered Cache / Cache Reserve state and the cache hit ratio. When no zone is connected, a setup snippet takes its place. |
+| Host | The machine's memory usage and how full the disk holding the project is |
+| Entry list | HTML: path (opens in a new tab), fresh/stale, size, status code, remaining TTL, dependency count, precompressed bodies. Data: key (click to copy), fresh/stale, remaining TTL |
 
 The list is **filtered by key** and the filter runs on the server: a data cache
 can hold tens of thousands of keys. At most 500 rows come back per request and
@@ -836,7 +859,10 @@ export content.
 | Clear HTML cache | `clearHtmlCache()` |
 | Clear data cache (optional prefix) | `clearDataCache(prefix)` |
 | Drop shared keys | Scans and unlinks the `html` or `data` namespace in Redis |
+| Count keys in Redis | `inspectRedis()` — keys per kind, `DBSIZE` and `used_memory` |
 | Prewarm | `prewarm()` — the pass runs in the background, progress shows in the card |
+| Cloudflare purge (everything / URLs held here / prefix / host / tag) | `purgeCloudflare()` |
+| Change a Cloudflare setting or feature | Zone settings and Tiered Cache / Cache Reserve |
 
 Each one propagates to the shared tier as well: clearing a single replica's
 cache is what produces the "I cleared it and it is still old" question in a
@@ -847,6 +873,116 @@ matches a path pattern and takes down **every** query variant of a path, while
 `dropHtmlCacheKey()` takes the exact key — `/list?page=2` goes and
 `/list?page=3` stays hot.
 
+## The CDN tier: Cloudflare
+
+Everything above is the **origin** cache. With Cloudflare in front, the HTML
+your visitors get usually never reaches you: the copy at the edge is served
+until its TTL runs out. That is why `invalidateHtmlCache()` alone does not fix
+"I updated the page but the old one still shows" — the origin refreshes, the
+edge keeps waiting.
+
+JSkelet lets you drive both tiers from the same place.
+
+### Setup
+
+The token is a secret, so it goes in the environment, not in a config file:
+
+```bash
+JSKELET_CLOUDFLARE_KEY=... # API token
+JSKELET_CLOUDFLARE_ZONE_ID=... # zone identifier
+JSKELET_CLOUDFLARE_HOSTNAME=example.com # optional
+```
+
+Which permissions the token needs depends on what you want to do: `Zone.Cache
+Purge` to purge, `Zone.Zone Settings` to change settings, `Zone.Analytics`
+(read) for the hit ratio and the edge breakdown. A purge-only token still opens
+the panel; the settings sections just report an error.
+
+The zone id and site name are not secrets, so they can also come from
+`jskelet.config.mjs`. The environment always wins:
+
+```js
+cache: {
+  cloudflare: {
+    zoneId: "…",
+    hostname: "example.com", // purging wants absolute URLs; this turns paths into them
+    analyticsHours: 24,
+  },
+}
+```
+
+Without `hostname`, purge URLs are derived from the origin the panel was opened
+on. If you reach the panel over an internal address (`http://10.0.0.4:3000`),
+that address means nothing to Cloudflare — there, `hostname` is required.
+
+### What you can do
+
+Whatever Cloudflare's cache surface offers is in the panel:
+
+| Action | Note |
+| --- | --- |
+| Purge everything | The whole zone. The bluntest tool; warming back up is expensive |
+| Purge by URL | Every page currently held in memory with one button, or `cf purge` per row |
+| Purge by prefix / host / tag | Available on all plans now; 100 keys per request |
+| Development mode | Bypasses the edge cache for three hours, then turns itself off |
+| Cache level, browser cache TTL, query string sorting, Always Online | Zone settings |
+| Tiered Cache, Regional Tiered Cache, Cache Reserve | Plan dependent; shows "unavailable" where the plan lacks it |
+| Clear Cache Reserve | Separate from purging: `purge_everything` drops the edges, the persistent copy in R2 stays |
+
+Long URL lists are split into batches of 100 keys and sent **sequentially**.
+Sending them in parallel means half the batch rejected on the Free plan, where
+purging is limited to five requests per minute.
+
+The same surface from code:
+
+```js
+import { invalidateHtmlCache, purgeCloudflare, toCloudflareUrls } from "jskelet";
+
+export async function onPostPublished(slug) {
+  const paths = ["/", `/blog/${slug}`];
+
+  invalidateHtmlCache(paths); // origin
+  await purgeCloudflare({ files: toCloudflareUrls(paths) }); // edge
+}
+```
+
+Nothing in this module throws: with no token, on a Cloudflare 403 or when the
+network drops, the result is `{ ok: false, error }`. A CDN outage should not
+break your publishing flow.
+
+### "How many edges hold this page?" — what can and cannot be asked
+
+There is no Cloudflare endpoint that lists the **inventory** of an object.
+Hundreds of cities run independent caches and none of them will answer "do you
+currently hold this URL". So the panel shows observation rather than inventory:
+enter a path and the GraphQL analytics tell you which colo (IST, FRA, AMS…)
+served it from cache and how often it went to the origin over the last N hours.
+
+```js
+const report = await fetchPathEdges({ path: "/blog", hours: 24 });
+// → { colos: [{ colo: "IST", hits: 7, misses: 2 }, …], hits, misses }
+```
+
+Two limits to keep in mind while reading it: an edge that received no request
+does not appear at all, even if it holds a copy; and the dataset is sampled, so
+ratios are reliable while absolute counts are estimates.
+
+There is also no way to **warm** an edge you pick. An object enters an edge
+cache only through a real request routed there; you cannot tell Frankfurt from
+your server to go cache something. Three things do work in practice:
+
+- **Warm the origin** (`prewarm`): the edge that takes the first request finds
+  a ready response, so that request is not the slow one.
+- **Tiered Cache**: edges do not go straight to the origin, they pull from an
+  upper tier — the first request in one city counts as warming for the others.
+- **Cache Reserve**: a persistent copy in R2 for long-tail content, so requests
+  do not reach the origin when an edge evicts.
+
+If your `hit` ratio is low, check whether the response is cacheable at all
+before anything else: `Cache-Control: private`, `Set-Cookie` and query string
+settings are the most common reasons an edge decides not to cache, and they
+show up as `dynamic` in this panel.
+
 ## Prewarm — warming up at startup
 
 The equivalent of Next's build-time prerender, except the output is not written

package/docs/en/07-configuration.md

@@ -119,6 +119,7 @@ export default {
   async cache() {
     return {
       html: { "/": 60, "/news/:slug": 300 },
+      query: { "/search": ["q", "page"] },
       maxEntries: 500,
       data: { maxEntries: 10000, staleFactor: 10 },
       prewarm: {
@@ -572,9 +573,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, upstream?: object, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, query: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, upstream: { rate: 0 }, redis: { enabled: false }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -594,6 +595,39 @@ html: {
 }
 ```
 
+### `cache().query`
+
+A pattern → list of query parameters allowed into the cache key.
+
+**By default a request that carries a query parameter is dynamic**: even when
+`cache().html` covers that path, the response never enters the HTML cache and
+is sent with `private, no-store`. The reason is simple — caching every variant
+of a path mints an unbounded number of keys (`?utm_source=…` and friends), and
+once the `maxEntries` limit is reached those keys evict the real pages. Only the
+application knows which parameter actually changes the output.
+
+```js
+query: {
+  "/search": ["q", "page"], // only these two belong to the key
+  "/products": ["category"],
+  "/report/:id": true, // every parameter belongs to the key
+  "/campaign": [], // the query is ignored entirely
+}
+```
+
+- **Allowlist** (`string[]`): the listed parameters become part of the key and
+ each distinct value gets its own entry. Parameters outside the list are
+ **ignored** — the page is still cached and every campaign variant shares one
+ copy.
+- **`true`**: every parameter belongs to the key. Nothing but `maxEntries`
+ bounds the number of entries, so use it only where the value set is closed.
+- **`[]`**: the query is not considered at all; every variant is served the HTML
+ of the query-less version.
+
+Parameters are written into the key **sorted**, so `?a=1&b=2` and `?b=2&a=1`
+share one entry. `route(fn, { private: true })` is unaffected by this section; a
+private route is never cached under any condition.
+
 ### `cache().maxEntries`
 
 **Type:** `number` — **Default:** `500`
@@ -740,6 +774,32 @@ leaking one means handing out the right to flush the cache, and a deploy should
 revoke old access on its own. Banned and unauthorised requests all get a `404`.
 Usage and screens: [06-caching.md](./06-caching.md).
 
+### `cache().cloudflare`
+
+The CDN tier. JSkelet's cache is the origin cache; the copy your visitors get
+sits at the edge. With this section connected, the panel can purge the edge,
+read and change cache related zone settings and show the cache hit ratio.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | Set `false` to keep the surface off even when a token is present in the environment |
+| `zoneId` | `string \| null` | `null` | Zone identifier (`JSKELET_CLOUDFLARE_ZONE_ID` overrides it) |
+| `apiToken` | `string \| null` | `null` | The token; **prefer the environment**, putting it here puts a secret in the repo |
+| `hostname` | `string \| null` | `null` | Purging wants absolute URLs; paths are resolved against this name. Falls back to the origin the panel was opened on |
+| `analyticsHours` | `number` | `24` | Analytics window, at most `72` |
+
+Passing the token only through `JSKELET_CLOUDFLARE_KEY` keeps the config file
+clean. Permissions follow what you intend to do: `Zone.Cache Purge` to purge,
+`Zone.Zone Settings` for settings, `Zone.Analytics` (read) for the hit ratio.
+The token is never returned in a panel response — only the fact that it came
+from the environment.
+
+With no zone connected the panel shows a setup snippet rather than a warning,
+and if Cloudflare returns an error that section reports it while the rest of the
+panel keeps working. What can actually be asked — in particular why "how many
+edges hold this page" has no exact answer — is in
+[06-caching.md](./06-caching.md).
+
 ```js
 panel: {
   enabled: process.env.CACHE_PANEL === "1",
@@ -871,6 +931,9 @@ and no warning is printed.
 | `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) |
 | `JSKELET_CACHE_PANEL` | `createApp` | — | When set, turns the cache panel on; `0` turns off a panel enabled in the config. The env wins because the panel is usually opened once during an incident. [06](./06-caching.md) |
+| `JSKELET_CLOUDFLARE_KEY` | Cloudflare cache surface | — | API token. Until it is set, CDN purging and edge analytics stay off; it overrides `apiToken` in the config. The token is never returned in a response. [06](./06-caching.md) |
+| `JSKELET_CLOUDFLARE_ZONE_ID` | Cloudflare cache surface | — | Zone identifier. No Cloudflare endpoint is called unless it is set alongside the token |
+| `JSKELET_CLOUDFLARE_HOSTNAME` | Cloudflare cache surface | — | The root for purge URLs. Required when the panel is opened over an internal address |
 | `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |
 | `PREWARM_MAX` | `prewarm` | `400` | At most how many paths are prewarmed |
 | `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Number of parallel workers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",

package/src/client/cache-panel/login.html

@@ -5,11 +5,16 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="robots" content="noindex, nofollow, noarchive, nosnippet" />
     <meta name="referrer" content="no-referrer" />
-    <title>Cache</title>
+    <title>Cache · JSkelet</title>
+    <link rel="icon" href="logo.png" />
     <link rel="stylesheet" href="panel.css" />
   </head>
   <body class="login">
     <form id="form" autocomplete="off">
+      <div class="brand">
+        <img src="logo.png" alt="" width="30" height="30" />
+        <span class="wordmark">JSkelet</span>
+      </div>
       <h1>Cache panel</h1>
       <p>
         This run's password is printed in the server log
@@ -27,6 +32,9 @@
       />
       <button class="primary" type="submit">Unlock</button>
       <p class="error" id="error"></p>
+      <p class="hint m0">
+        Three failed attempts block this address for 24 hours.
+      </p>
     </form>
 
     <script type="module">