jskelet 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -10,6 +10,21 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- HTML cache key vary (`cache().vary`): `host: true` adds the public Host
+  (`x-forwarded-host` or `Host`, lowercase, no port) as `h=…|` before the path;
+  optional `headers` and `fn(req)` add further segments. Required on host-based
+  locale sites so one locale's HTML is not served on another. Classic prewarm
+  accepts `prewarm.origins` for multi-host warming when vary is on.
+
+### Changed
+
+- Marketing example visual language: darker ink canvas, solid cyan primary
+  CTAs, cyan-only glow/grid (indigo accents removed), and a measured trust
+  bar on the homepage (payload gzip, Node, license, zero web fonts) instead
+  of the marquee.
+
+### Added
+
 - Dynamic Open Graph images (Next.js `ImageResponse` / `opengraph-image`):
   `ogImage`, `sendOgImage`, `ogHandler`, and `ImageResponse` turn card fields or
   raw SVG into PNG when `sharp` is installed (SVG fallback otherwise). Wired in

package/docs/06-cache.md

@@ -43,8 +43,9 @@ sayfa da ilk ziyaretçide milisaniyeler içinde üretilir ve kota harcamaz.
 ## Public ve kişiye özel ayrımı
 
 Bu belgedeki her şey **herkese aynı gidebilen** HTML için geçerli. Cache
-anahtarında kimlik yok (yalnızca yol + query), yani önbellekteki bir sayfa onu
-ilk isteyen kişinin değil, o yolun cevabıdır.
+anahtarında kimlik yok (yalnızca yol + query + isteğe bağlı `vary`); yani
+önbellekteki bir sayfa onu ilk isteyen kişinin değil, o yolun (ve vary
+parçalarının) cevabıdır.
 
 Kullanıcıya bağlı bir sayfa bu yüzden ayrı bir yoldan geçer:
 
@@ -110,13 +111,14 @@ saklayabiliyordu.
 ## Cache anahtarı
 
 ```
-`${yol}?${izin verilen query parametreleri, sıralı}`
+`${varyPrefix}${yol}?${izin verilen query parametreleri, sıralı}`
 ```
 
-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
+`varyPrefix` varsayılan olarak boştur. Query'siz bir istek için anahtar
+`${varyPrefix}${yol}?` biçimindedir. **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.
 
 Hangi parametrenin çıktıyı gerçekten değiştirdiğini uygulama bildirir —
@@ -135,6 +137,48 @@ Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (dikkat: gir
 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).
 
+### Host / locale: `cache().vary`
+
+CDN zaten tam URL ile ayırır; asıl risk **origin L1** ve Redis HTML anahtarıdır.
+Host'tan locale üreten sitelerde (`tr.example.com` / `en.example.com`) vary
+olmadan ilk locale'in HTML'i diğer host'a servis edilir — Express 5'te istek
+nesnesine locale yazmak kırılgan bir kaçış yoludur.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, portsuz
+    host: true,
+    // veya özel:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Örnek anahtarlar: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Alan | Tip | Anlamı |
+| --- | --- | --- |
+| `host` | `boolean` | Public Host'u `h=…` olarak anahtara ekler |
+| `headers` | `string[]` | Verilen istek başlıklarını (`ad=değer`) ekler |
+| `fn` | `(req) => string \| null` | Dönüş değeri bir segment olarak eklenir (tam kontrol) |
+
+**Prewarm:** varsayılan ısıtma `http://127.0.0.1:<port>` üzerinden gider. 
+`vary.host` açıksa bu yalnızca loopback anahtarını ısıtır; locale sitelerinde
+çoklu origin gerekir:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+Port yazılmazsa dinleme portu eklenir. `onVisit` modunda ısıtma, vary açıkken
+ziyaretçinin `Host` başlığını kullanır.
+
 ## Stale-while-revalidate
 
 Girdi yapısı:
@@ -771,7 +815,7 @@ her istek ağ zaman aşımı beklemez.
 ### Anahtar düzeni
 
 ```
-_jskelet:{namespace}:{buildId}:html:{yol}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{yol}?{query}
 _jskelet:{namespace}:{buildId}:data:{anahtar}
 _jskelet:{namespace}:events
 ```
@@ -1074,9 +1118,12 @@ da trafik geldikçe (`onVisit`) yapılır. Kazanç aynı — tıklanan / komşu
 soğuk render'ı beklemez — fakat veri dondurulmaz; her girdi route'un
 `revalidate` süresiyle yaşlanır ve stale-while-revalidate ile arkada tazelenir.
 
-Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>`), çünkü
-cache anahtarı, sıkıştırma ve middleware zinciri normal trafikle bire bir aynı
-olsun.
+Isıtma **gerçek HTTP istekleriyle** yapılır (`http://127.0.0.1:<port>` ya da
+`cache().prewarm.origins`), çünkü cache anahtarı, sıkıştırma ve middleware
+zinciri normal trafikle bire bir aynı olsun. `vary.host` açıksa varsayılan
+loopback yalnızca o host'un anahtarını ısıtır — locale sitelerinde
+`origins: ["http://localhost", "http://tr.localhost"]` gibi çoklu origin
+gerekir.
 
 İki mod **karşılıklı dışlayıcıdır**. `cache().prewarm.onVisit` açıksa klasik
 alanlar (`max`, `priority`, `rotate`, `intervalSeconds`, …) ve
@@ -1336,6 +1383,10 @@ turunun gerçekten `MISS` → önbellek doldurup doldurmadığını buradan gör
   fazla `revalidate` + bir tazeleme turudur.
 - **Önbellek şişiyor.** Query parametreleri anahtara girdiği için kampanya
   parametreleri girdi çoğaltıyor olabilir.
+- **Yanlış dil / host HTML'i geliyor.** Host'tan locale üreten bir sitede
+  `cache().vary.host: true` yoksa ilk locale'in HTML'i diğer host'a servis
+  edilir. Prewarm yalnızca `127.0.0.1` ile ısınıyorsa `prewarm.origins` ile
+  locale host'larını ekleyin.
 - **Isıtma hiç çalışmıyor.** Klasik modda `hooks.prewarmPaths` tanımlı değil,
   `PREWARM=0` ayarlı ya da `cache().prewarm.enabled === false`. `onVisit`
   modunda `listen` sonrası logda `onVisit mode` satırını ve public cache'li

package/docs/07-yapilandirma.md

@@ -614,9 +614,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { 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 }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Varsayılan:**
-`{ 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 } }`
+`{ html: {}, query: {}, vary: { host: false }, 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, origins: [] } }`
 
 ### `cache().html`
 
@@ -671,6 +671,30 @@ Parametreler anahtara **sıralı** yazılır: `?a=1&b=2` ile `?b=2&a=1` aynı gi
 paylaşır. `route(fn, { private: true })` bu bölümden etkilenmez; private route
 hiçbir koşulda cache'lenmez.
 
+### `cache().vary`
+
+HTML cache anahtarına query allowlist'ten **bağımsız** sabit parçalar ekler.
+Host'tan locale üreten sitelerde `host: true` **zorunlu**; aksi halde ilk
+locale'in HTML'i diğer host'a servis edilir. CDN zaten tam URL ile ayırır —
+bu ayar origin L1 ve Redis HTML anahtarı içindir.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` yoksa `Host`), lowercase, portsuz → `h=…` |
+| `headers` | `string[]` | `[]` | İstek başlıkları `ad=değer` olarak eklenir |
+| `fn` | `(req) => string \| null` | — | Dönüş bir segment olarak eklenir |
+
+Anahtar biçimi: `${vary}|${yol}?${query}` (vary yoksa önek yok). Ayrıntı:
+[06-cache.md](./06-cache.md).
+
 ### `cache().maxEntries`
 
 **Tip:** `number` — **Varsayılan:** `500`
@@ -900,6 +924,7 @@ sayfadaki linkler). Birlikte verilemez — config yüklenirken hata.
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
 | `rotate` | `boolean` | `true` | Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder |
 | `priority` | `(string \| RegExp)[]` | `[]` | Isıtma sırası; eşleşen yollar her turda başa alınır |
+| `origins` | `string[]` | `[]` | Klasik turda ısıtılacak origin'ler. Boşsa `http://127.0.0.1:<port>`. `vary.host` açıksa locale host'ları buraya yazın |
 
 `priority` iki biçim kabul eder: config'in her yerinde geçerli olan desen
 sözdizimi ve doğrudan `RegExp`. Önce yazılan önce ısınır.
@@ -909,6 +934,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // vary.host açıksa loopback tek başına yetmez:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // ana sayfa
     "/piyasalar/:path*",      // tüm piyasa bölümü

package/docs/en/06-caching.md

@@ -46,9 +46,9 @@ milliseconds on the first visit, and spends no quota.
 ## Public versus per-visitor
 
 Everything in this document applies to HTML that **can go to everyone
-unchanged**. There is no identity in the cache key (only path + query), so a
-page in the cache is the answer for that path, not the answer for whoever asked
-for it first.
+unchanged**. There is no identity in the cache key (only path + query + optional
+`vary`), so a page in the cache is the answer for that path (and vary parts),
+not the answer for whoever asked for it first.
 
 A page that depends on the user therefore takes a separate path:
 
@@ -117,14 +117,15 @@ The cache also only kicks in for `GET` requests.
 ## The cache key
 
 ```
-`${path}?${the allowed query parameters, sorted}`
+`${varyPrefix}${path}?${the allowed query parameters, sorted}`
 ```
 
-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.
+`varyPrefix` is empty by default. For a request without a query the key is
+`${varyPrefix}${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.
 
 Which parameter actually changes the output is declared by the application, in
 `jskelet.config.mjs` → `cache().query`:
@@ -143,6 +144,49 @@ 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).
 
+### Host / locale: `cache().vary`
+
+A CDN already separates by full URL; the real risk is the **origin L1** and the
+Redis HTML key. On sites that derive locale from the host
+(`tr.example.com` / `en.example.com`), without vary the first locale's HTML is
+served to the other host — mutating the request object for locale is a fragile
+workaround under Express 5.
+
+```js
+cache: () => ({
+  html: { "/": 300, "/instruments/:slug": 300 },
+  vary: {
+    // true → public Host (x-forwarded-host || host), lowercase, no port
+    host: true,
+    // or custom:
+    // headers: ["x-locale"],
+    // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+  },
+}),
+```
+
+Example keys: `h=tr.investvio.com|/instruments/aapl?`,
+`h=tr.example.com&l=tr|/…?`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `host` | `boolean` | Adds the public Host as `h=…` |
+| `headers` | `string[]` | Adds the given request headers as `name=value` |
+| `fn` | `(req) => string \| null` | Appends the return value as a segment (full control) |
+
+**Prewarm:** the default warm-up goes through `http://127.0.0.1:<port>`. With
+`vary.host` that only warms the loopback key; locale sites need multiple
+origins:
+
+```js
+prewarm: {
+  origins: ["http://localhost", "http://tr.localhost"],
+},
+```
+
+If no port is written, the listen port is added. In `onVisit` mode, when vary
+is on, warming uses the visitor's `Host` header.
+
 ## Stale-while-revalidate
 
 The entry structure:
@@ -788,7 +832,7 @@ five consecutive failures, so requests do not each wait for a network timeout.
 ### Key layout
 
 ```
-_jskelet:{namespace}:{buildId}:html:{path}?{query}
+_jskelet:{namespace}:{buildId}:html:{vary|}{path}?{query}
 _jskelet:{namespace}:{buildId}:data:{key}
 _jskelet:{namespace}:events
 ```
@@ -1075,8 +1119,11 @@ but the data is not frozen; every entry ages with the route's `revalidate` and
 is refreshed in the background with stale-while-revalidate.
 
 The warm-up is done with **real HTTP requests**
-(`http://127.0.0.1:<port>`), so that the cache key, the compression and the
-middleware chain are exactly the same as with normal traffic.
+(`http://127.0.0.1:<port>` or `cache().prewarm.origins`), so that the cache key,
+the compression and the middleware chain are exactly the same as with normal
+traffic. With `vary.host`, the default loopback only warms that host's key —
+locale sites need multiple origins such as
+`origins: ["http://localhost", "http://tr.localhost"]`.
 
 The two modes are **mutually exclusive**. If `cache().prewarm.onVisit` is on,
 classic fields (`max`, `priority`, `rotate`, `intervalSeconds`, …) and
@@ -1339,6 +1386,10 @@ filled the cache.
   lag is at most `revalidate` + one refresh round.
 - **The cache is bloating.** Because query parameters go into the key, campaign
   parameters may be multiplying entries.
+- **Wrong language / host HTML.** On a site that derives locale from the host,
+  without `cache().vary.host: true` the first locale's HTML is served to the
+  other host. If prewarm only hits `127.0.0.1`, add the locale hosts via
+  `prewarm.origins`.
 - **The warm-up never runs.** In classic mode `hooks.prewarmPaths` is not
   defined, `PREWARM=0` is set, or `cache().prewarm.enabled === false`. In
   `onVisit` mode check the `onVisit mode` log line after `listen` and that a

package/docs/en/07-configuration.md

@@ -627,9 +627,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { 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 }` —
+`() => { html?: Record<string, number>, query?: Record<string, string[] | true>, vary?: { host?: boolean, headers?: string[], fn?: (req) => string | null }, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, upstream?: object, redis?: object, prewarm?: object }` —
 **Default:**
-`{ 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 } }`
+`{ html: {}, query: {}, vary: { host: false }, 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, origins: [] } }`
 
 ### `cache().html`
 
@@ -684,6 +684,31 @@ 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().vary`
+
+Adds fixed segments to the HTML cache key **independently** of the query
+allowlist. On sites that derive locale from the host, `host: true` is
+**required**; otherwise the first locale's HTML is served to the other host. A
+CDN already separates by full URL — this setting is for the origin L1 and the
+Redis HTML key.
+
+```js
+vary: {
+  host: true, // h=tr.example.com|…
+  // headers: ["x-locale"],
+  // fn: (req) => req.hostname.startsWith("tr.") ? "l=tr" : "l=en",
+}
+```
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | `boolean` | `false` | Public Host (`x-forwarded-host` else `Host`), lowercase, no port → `h=…` |
+| `headers` | `string[]` | `[]` | Request headers added as `name=value` |
+| `fn` | `(req) => string \| null` | — | Return value appended as a segment |
+
+Key shape: `${vary}|${path}?${query}` (no prefix when vary is empty). Details:
+[06-caching.md](./06-caching.md).
+
 ### `cache().maxEntries`
 
 **Type:** `number` — **Default:** `500`
@@ -920,6 +945,7 @@ page just visited). They cannot be combined — config load throws.
 | `intervalSeconds` | `number` | `0` | If greater than 0, the pass repeats periodically |
 | `rotate` | `boolean` | `true` | If the list is longer than `max`, periodic passes continue where they left off |
 | `priority` | `(string \| RegExp)[]` | `[]` | Warm-up order; matching paths are taken first on every pass |
+| `origins` | `string[]` | `[]` | Origins for the classic pass. Empty → `http://127.0.0.1:<port>`. With `vary.host`, list the locale hosts here |
 
 `priority` accepts two forms: the pattern syntax used everywhere in the config,
 and a plain `RegExp`. Whatever is written first is warmed first.
@@ -929,6 +955,8 @@ prewarm: {
   max: 500,
   rps: 4,
   intervalSeconds: 300,
+  // with vary.host, loopback alone is not enough:
+  origins: ["http://localhost", "http://tr.localhost"],
   priority: [
     "/",                     // the home page
     "/markets/:path*",        // the whole markets section

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "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/config/defaults.js

@@ -87,6 +87,13 @@ export const DEFAULT_PREWARM = {
    * @type {(string | RegExp)[]}
    */
   priority: [],
+  /**
+   * Klasik turda ısıtılacak origin listesi. Boşsa `http://127.0.0.1:<port>`.
+   * `cache().vary.host` açıkken locale host'ları buraya yazılmazsa yalnızca
+   * loopback anahtarı ısınır.
+   * @type {string[]}
+   */
+  origins: [],
 };
 
 /**
@@ -122,6 +129,7 @@ export const CLASSIC_PREWARM_KEYS = [
   "retryDelayMs",
   "rotate",
   "priority",
+  "origins",
 ];
 
 /**

package/src/config/index.js

@@ -16,7 +16,9 @@
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
  *   cache()     → { html?: { [source]: saniye },
- *                   query?: { [source]: string[] | true }, maxEntries?: number,
+ *                   query?: { [source]: string[] | true },
+ *                   vary?: { host?: boolean, headers?: string[], fn?: Function },
+ *                   maxEntries?: number,
  *                   data?: {...}, redis?: {...}, prewarm?: {...} }
  *   admin()     → { enabled?, basePath?, allowIps?, blockBots?, … }
  *   logs        → { console?, kinds?, file?, s3? }
@@ -107,6 +109,10 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, allow: true | string[] }[]} cacheQuery
  *   Yol deseni başına, HTML cache anahtarına girmesine izin verilen query
  *   parametreleri. Eşleşen kural yoksa query'li istek cache'lenmez.
+ * @property {{ host: boolean, headers: string[],
+ *   fn: ((req: import('express').Request) => string | null | undefined) | null }} cacheVary
+ *   Anahtara eklenen sabit parçalar (query allowlist'ten bağımsız). Host'tan
+ *   locale üreten sitelerde `host: true` zorunlu.
  * @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.
@@ -633,10 +639,42 @@ function normalizeQueryRules(raw) {
   return out;
 }
 
+/**
+ * `cache().vary` → HTML anahtarına host / header / özel fn parçası.
+ *
+ * @param {unknown} raw
+ * @returns {ResolvedConfig["cacheVary"]}
+ */
+function normalizeVary(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { host: false, headers: [], fn: null };
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const headers = asArray(source.headers, "cache().vary.headers")
+    .filter((name) => typeof name === "string" && name)
+    .map((name) => String(name).toLowerCase());
+
+  /** @type {ResolvedConfig["cacheVary"]["fn"]} */
+  let fn = null;
+  if (typeof source.fn === "function") {
+    fn = /** @type {ResolvedConfig["cacheVary"]["fn"]} */ (source.fn);
+  } else if (source.fn != null) {
+    console.warn("[config] cache().vary.fn must be a function, ignoring it");
+  }
+
+  return {
+    host: source.host === true,
+    headers,
+    fn,
+  };
+}
+
 /**
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"],
- *   cacheQuery: ResolvedConfig["cacheQuery"], htmlMaxEntries: number,
+ *   cacheQuery: ResolvedConfig["cacheQuery"],
+ *   cacheVary: ResolvedConfig["cacheVary"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
  *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
@@ -664,6 +702,7 @@ function normalizeCache(raw) {
   return {
     html,
     cacheQuery: queryRules,
+    cacheVary: normalizeVary(raw?.vary),
     htmlMaxEntries:
       Number.isFinite(maxEntries) && maxEntries > 0
         ? Math.floor(maxEntries)
@@ -775,6 +814,12 @@ function normalizePrewarm(raw) {
   // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
   const classic = { ...source };
   delete classic.onVisit;
+
+  const origins = asArray(classic.origins, "cache().prewarm.origins")
+    .filter((value) => typeof value === "string" && /^https?:\/\//i.test(value))
+    .map(String);
+  classic.origins = origins;
+
   return {
     ...DEFAULT_PREWARM,
     ...classic,
@@ -1074,6 +1119,7 @@ export async function loadConfig(options = {}) {
   const {
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -1097,6 +1143,7 @@ export async function loadConfig(options = {}) {
     rewrites: normalizeRewrites(rewrites),
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,

package/src/server/cache-vary.js

@@ -0,0 +1,113 @@
+/**
+ * HTML cache anahtarına host / header / özel fn ile sabit vary parçası ekler.
+ *
+ * CDN zaten tam URL ile ayırır; asıl risk origin L1 ve Redis HTML anahtarı —
+ * host'tan locale üreten sitelerde `vary.host: true` olmadan ilk locale'in
+ * HTML'i diğer host'a servis edilir.
+ */
+import { getConfig } from "../config/index.js";
+
+/**
+ * Public Host: `x-forwarded-host` (ilk değer) yoksa `Host`. Lowercase, portsuz.
+ * IPv6 (`[::1]:3000`) köşeli parantezleri korur.
+ *
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
+ * @returns {string}
+ */
+export function publicHost(req) {
+  const forwarded = headerValue(req, "x-forwarded-host");
+  const raw = forwarded || headerValue(req, "host") || "";
+  const first = raw.split(",")[0].trim().toLowerCase();
+  return stripPort(first);
+}
+
+/**
+ * @param {string} host
+ * @returns {string}
+ */
+function stripPort(host) {
+  if (!host) return "";
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    return end === -1 ? host : host.slice(0, end + 1);
+  }
+  // Birden fazla `:` → portsuz IPv6 (Host'ta nadir); tek `:` → host:port.
+  const colon = host.lastIndexOf(":");
+  if (colon === -1) return host;
+  if (host.indexOf(":") !== colon) return host;
+  return host.slice(0, colon);
+}
+
+/**
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} req
+ * @param {string} name
+ * @returns {string}
+ */
+function headerValue(req, name) {
+  const viaGet = req.get?.(name);
+  if (typeof viaGet === "string" && viaGet) return viaGet;
+
+  const raw = req.headers?.[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0] ? String(raw[0]) : "";
+  if (raw == null) return "";
+  return String(raw);
+}
+
+/**
+ * Anahtarın başına eklenen önek: `h=tr.example.com|` veya
+ * `h=…&x-locale=tr|`. Vary yoksa boş string.
+ *
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
+ * @returns {string}
+ */
+export function buildVaryPrefix(req) {
+  if (!req) return "";
+
+  let vary;
+  try {
+    vary = getConfig().cacheVary;
+  } catch {
+    return "";
+  }
+
+  if (!vary || (!vary.host && !vary.headers.length && !vary.fn)) return "";
+
+  /** @type {string[]} */
+  const parts = [];
+
+  if (vary.host) {
+    const host = publicHost(req);
+    if (host) parts.push(`h=${host}`);
+  }
+
+  for (const name of vary.headers) {
+    const value = headerValue(req, name).trim();
+    if (value) parts.push(`${name}=${value}`);
+  }
+
+  if (typeof vary.fn === "function") {
+    try {
+      const custom = vary.fn(/** @type {import('express').Request} */ (req));
+      if (custom != null && custom !== "") parts.push(String(custom));
+    } catch (error) {
+      console.warn("[cache] cache().vary.fn threw, ignoring it", error);
+    }
+  }
+
+  return parts.length ? `${parts.join("&")}|` : "";
+}
+
+/**
+ * Anahtardan yol kısmını çıkarır (`[vary|]yol?query` → `yol`).
+ * Invalidation hedefleri `/…` ile başlar; vary öneki eşleşmeye karışmamalı.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function pathOfCacheKey(key) {
+  const mark = key.indexOf("?");
+  const beforeQuery = mark === -1 ? key : key.slice(0, mark);
+  const sep = beforeQuery.indexOf("|/");
+  if (sep !== -1) return beforeQuery.slice(sep + 1);
+  return beforeQuery;
+}

package/src/server/html-cache.js

@@ -34,6 +34,7 @@ import { getConfig } from "../config/index.js";
 import { DEFAULT_HTML_CACHE_MAX_ENTRIES } from "../config/defaults.js";
 import { collectDependencies } from "./cache-deps.js";
 import { compilePattern, matchPattern } from "../config/pattern.js";
+import { pathOfCacheKey } from "./cache-vary.js";
 import {
   cacheKey,
   onCacheEvent,
@@ -662,8 +663,9 @@ function invalidateKey(key, hard) {
  * arkada ve anahtar başına tek seferde koşar. `hard: true` yalnızca eski
  * HTML'in gerçekten geçersiz olduğu durumlar için.
  *
- * Anahtar `yol?query` olduğundan eşleştirme **yol kısmına** yapılır: bir
- * yolun bütün query varyantları (`?utm_source=…` dahil) tek çağrıyla düşer.
+ * Anahtar `yol?query` (isteğe bağlı `vary|` önekiyle) olduğundan eşleştirme
+ * **yol kısmına** yapılır: bir yolun bütün query / host varyantları tek
+ * çağrıyla düşer.
  *
  * @param {string | RegExp | (string | RegExp)[]} target
  * @param {{ hard?: boolean }} [options]
@@ -733,14 +735,14 @@ function compileMatchers(targets) {
 }
 
 /**
- * Anahtar `yol?query`; eşleştirme **yol kısmına** yapılır.
+ * Anahtar `[vary|]yol?query`; eşleştirme **yol** kısmına yapılır.
+ * Vary öneki (`h=…|`) invalidation hedefiyle karışmasın.
  *
  * @param {string} key
  * @returns {string}
  */
 function pathOf(key) {
-  const mark = key.indexOf("?");
-  return mark === -1 ? key : key.slice(0, mark);
+  return pathOfCacheKey(key);
 }
 
 /**
@@ -879,6 +881,9 @@ function dropLocalKey(key) {
  * boşaltır. Isıtma turu bunları başa alır; iki tur aynı yolu tekrar
  * ısıtmasın diye okuma yıkıcıdır.
  *
+ * Vary öneki (`h=…|`) düşülür — HTTP ısıtması yalnızca yolu ister; host
+ * ayrımı `prewarm.origins` / istek Host'u ile yapılır.
+ *
  * @returns {string[]}
  */
 export function takeInvalidatedPaths() {
@@ -886,8 +891,13 @@ export function takeInvalidatedPaths() {
 
   const paths = [...invalidated];
   invalidated.clear();
-  // Anahtar `yol?query`; query boşsa sondaki `?` atılır.
-  return paths.map((key) => (key.endsWith("?") ? key.slice(0, -1) : key));
+  return paths.map((key) => {
+    const pathname = pathOfCacheKey(key);
+    const q = key.indexOf("?");
+    if (q === -1) return pathname;
+    const query = key.slice(q + 1);
+    return query ? `${pathname}?${query}` : pathname;
+  });
 }
 
 /**

package/src/server/prewarm.js

@@ -24,6 +24,65 @@ import { getDataCacheStats } from "./data-cache.js";
 import { isTransientStatus } from "./upstream-tracking.js";
 import { upstreamCooldownMs } from "./upstream-limiter.js";
 
+/**
+ * `cache().prewarm.origins` yoksa loopback. Port'suz origin'lere dinleme
+ * portu eklenir — `http://tr.localhost` → `http://tr.localhost:3000`.
+ *
+ * @param {number} port
+ * @returns {string[]}
+ */
+function resolvePrewarmOrigins(port) {
+  const configured = getConfig().prewarm?.origins;
+  const list = Array.isArray(configured)
+    ? configured.filter((value) => typeof value === "string" && value)
+    : [];
+
+  if (!list.length) return [`http://127.0.0.1:${port}`];
+
+  return list.map((origin) => {
+    try {
+      const url = new URL(origin);
+      if (!url.port) url.port = String(port);
+      return url.origin;
+    } catch {
+      return origin;
+    }
+  });
+}
+
+/**
+ * Vary açıkken ısıtma isteği ziyaretçinin Host'unu taşısın — aksi halde
+ * loopback anahtarı ısınır, gerçek locale host soğuk kalır.
+ *
+ * @param {{ get?: (name: string) => string | undefined,
+ *   headers?: Record<string, unknown>, protocol?: string } | undefined} req
+ * @param {string} fallback
+ * @returns {string}
+ */
+function originFromRequest(req, fallback) {
+  if (!req) return fallback;
+
+  let vary;
+  try {
+    vary = getConfig().cacheVary;
+  } catch {
+    return fallback;
+  }
+  if (!vary?.host && !vary?.headers?.length && !vary?.fn) return fallback;
+
+  const host =
+    req.get?.("host") ||
+    (typeof req.headers?.host === "string" ? req.headers.host : "");
+  if (!host) return fallback;
+
+  const forwarded = req.headers?.["x-forwarded-proto"];
+  const protoRaw = Array.isArray(forwarded)
+    ? forwarded[0]
+    : forwarded || req.protocol || "http";
+  const proto = String(protoRaw).split(",")[0].trim() || "http";
+  return `${proto}://${host}`;
+}
+
 /** Klasik turu yöneten env'ler; `onVisit` ile birlikte yasak. */
 const CLASSIC_PREWARM_ENV = [
   "PREWARM_MAX",
@@ -715,6 +774,9 @@ export function noteVisitWarm(html, context) {
     /** @type {string | undefined} */ (context.req?.headers?.["user-agent"]);
   if (ua && ua === getConfig().brand.prewarmUserAgent) return;
 
+  // Vary açıksa bu ziyaretin Host'u üzerinden ısıt — loopback anahtarı değil.
+  visitOrigin = originFromRequest(context.req, visitOrigin);
+
   const perPage = Number(getConfig().prewarm?.onVisit?.perPage) || 20;
   const links = extractSameOriginLinks(html, {
     limit: perPage,
@@ -796,12 +858,13 @@ export function startPrewarm({ port }) {
   const config = getConfig();
   if (process.env.PREWARM === "0") return;
 
-  const origin = `http://127.0.0.1:${port}`;
+  const origins = resolvePrewarmOrigins(port);
+  const origin = origins[0];
 
   // 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);
+  startExpiryWarmDrain(origins);
 
   if (config.prewarm?.onVisit?.enabled) {
     const classicEnv = CLASSIC_PREWARM_ENV.filter((key) => process.env[key]);
@@ -833,7 +896,10 @@ export function startPrewarm({ port }) {
     if (running) return;
     running = true;
     try {
-      await prewarm({ origin });
+      // `vary.host` açıkken her origin ayrı anahtar ısıtır.
+      for (const next of origins) {
+        await prewarm({ origin: next });
+      }
     } catch (error) {
       console.error("[prewarm] failed", error);
     } finally {
@@ -856,8 +922,8 @@ export function startPrewarm({ port }) {
   if (interval > 0) setInterval(() => void run(), interval * 1000).unref();
 }
 
-/** @type {string | null} */
-let expiryOrigin = null;
+/** @type {string[]} */
+let expiryOrigins = [];
 
 /** @type {boolean} */
 let expiryDraining = false;
@@ -869,11 +935,11 @@ 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
+ * @param {string[]} origins
  * @returns {void}
  */
-function startExpiryWarmDrain(origin) {
-  expiryOrigin = origin;
+function startExpiryWarmDrain(origins) {
+  expiryOrigins = origins.length ? origins : [];
   if (expiryDrainTimer) return;
   expiryDrainTimer = setInterval(() => {
     void drainExpiryWarm();
@@ -885,7 +951,7 @@ function startExpiryWarmDrain(origin) {
  * @returns {Promise<void>}
  */
 async function drainExpiryWarm() {
-  if (expiryDraining || !expiryOrigin) return;
+  if (expiryDraining || !expiryOrigins.length) return;
 
   const paths = takeInvalidatedPaths();
   if (!paths.length) return;
@@ -895,7 +961,9 @@ async function drainExpiryWarm() {
     const cold = paths.filter((path) => !isHtmlCacheFresh(path));
     if (!cold.length) return;
 
-    await prewarm({ origin: expiryOrigin, paths: cold, quiet: true });
+    for (const origin of expiryOrigins) {
+      await prewarm({ origin, paths: cold, quiet: true });
+    }
   } catch (error) {
     console.error("[prewarm] expiry warm failed", error);
   } finally {

package/src/server/render.js

@@ -18,6 +18,7 @@ import fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import ejs from "ejs";
 import { withHtmlCache } from "./html-cache.js";
+import { buildVaryPrefix } from "./cache-vary.js";
 import { getConfig, hook } from "../config/index.js";
 import { matchPattern } from "../config/pattern.js";
 import { encodeText, negotiateEncoding } from "./middleware/compression.js";
@@ -329,12 +330,14 @@ export function route(controller, options = {}) {
     // Anahtar `null` ise query bu yol için cache'lenebilir değil: sayfa
     // dinamik davranır. Anahtar yine de gerekiyor (hata sayfası ölçümü,
     // teşhis) ama TTL sıfırlanıp cache yolu kapatılır.
-    const key = buildCacheKey(req.path, ctx.query);
+    const key = buildCacheKey(req.path, ctx.query, req);
     const cacheable =
       !isPrivate && req.method === "GET" && Boolean(revalidate) && key !== null;
-    const cacheKey = key ?? `${req.path}?${new URLSearchParams(
-      Object.entries(ctx.query).map(([k, v]) => [k, String(v)]),
-    ).toString()}`;
+    const cacheKey =
+      key ??
+      `${buildVaryPrefix(req)}${req.path}?${new URLSearchParams(
+        Object.entries(ctx.query).map(([k, v]) => [k, String(v)]),
+      ).toString()}`;
 
     try {
       const result = await withRequestContext(context, () =>
@@ -582,6 +585,10 @@ function resolveQueryPolicy(pathname) {
 /**
  * HTML cache anahtarı, ya da query bu yol için cache'lenebilir değilse `null`.
  *
+ * Biçim: `${varyPrefix}${pathname}?${izin verilen query}`.
+ * Vary (`cache().vary`) query allowlist'ten bağımsız; host/locale sitelerinde
+ * ilk host'un HTML'inin diğerine servis edilmesini engeller.
+ *
  * Varsayılan olarak query parametresi taşıyan istek dinamiktir: `cache().query`
  * altında eşleşen bir kural olmadıkça cache'e hiç girmez. Aksi hâlde bir yolun
  * bütün `?utm_source=…` varyantları ayrı girdi olur ve LRU'daki gerçek
@@ -592,11 +599,13 @@ function resolveQueryPolicy(pathname) {
  *
  * @param {string} pathname
  * @param {Record<string, unknown>} query
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
  * @returns {string | null}
  */
-function buildCacheKey(pathname, query) {
+function buildCacheKey(pathname, query, req) {
+  const vary = buildVaryPrefix(req);
   const entries = Object.entries(query);
-  if (!entries.length) return `${pathname}?`;
+  if (!entries.length) return `${vary}${pathname}?`;
 
   const policy = resolveQueryPolicy(pathname);
   if (policy === null) return null;
@@ -612,7 +621,7 @@ function buildCacheKey(pathname, query) {
       .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
   );
 
-  return `${pathname}?${params.toString()}`;
+  return `${vary}${pathname}?${params.toString()}`;
 }
 
 /**