jskelet 0.1.2 → 0.1.4

package/docs/en/06-caching.md

@@ -4,8 +4,9 @@ This document explains JSkelet's ISR substitute in full detail: the HTML TTL
 cache and its stale-while-revalidate behaviour, where `revalidate` comes from,
 how the cache key is built, the values of the `X-JSkelet-Cache` header, why the
 compressed body is kept in the cache, per-request memoization
-(`withRequestCache` / `cache()`), how upstream failures affect the cache
-(`reportUpstreamFailure`) and the prewarm round at server startup. The
+(`withRequestCache` / `cache()`), the data cache (`withDataCache`), how upstream
+failures affect the cache (automatic tracking and `reportUpstreamFailure`) and the prewarm round at
+server startup. The
 measurement rationale behind the decisions is in
 [02-architecture.md](./02-architecture.md), and the full reference of config
 fields is in [07-configuration.md](./07-configuration.md).
@@ -18,6 +19,7 @@ route(controller, { revalidate })
      └─ withUpstreamTracking(...)              ← missing data detection
          └─ withRequestCache(...)              ← per-request memoization
              └─ produce() → controller + renderPage
+                              └─ withDataCache(...)  ← upstream data cache
 ```
 
 The order matters: the **per-request cache must be innermost** so that two
@@ -25,6 +27,22 @@ calls in the same render collapse into a single upstream request; **upstream
 tracking must be inside the HTML cache** so that output produced with missing
 data is not written to the cache.
 
+How the two caches divide the work:
+
+| | HTML cache | Data cache |
+| --- | --- | --- |
+| What it holds | The whole page (+ its compressed body) | The JSON that came from upstream |
+| Entry size | ~100-200 kB | ~1-20 kB |
+| Entry limit | 500 (`cache().maxEntries`) | 10,000 (`cache().data.maxEntries`) |
+| Who benefits | Pages with traffic: not even rendered | The long tail: rendered, but without going to the API |
+
+In practice this distinction means: on a site with tens of thousands of paths it
+is impossible to keep every page hot as HTML — a warm-up that goes past 500
+entries deletes what it just warmed. For the long tail the goal is not "have the
+HTML ready" but **"have the data that produces the page available without going
+to the API"**. Then a page that was never warmed is also produced within
+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
@@ -109,8 +127,8 @@ 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; the store holds at most 500 entries
-and evicts the oldest with LRU.
+`revalidate`), is a reasonable precaution; by default the store holds at most
+500 entries and evicts the oldest with LRU.
 
 ## Stale-while-revalidate
 
@@ -141,8 +159,8 @@ data in the HTML can be at most `revalidate + one refresh round` behind. That
 price is acceptable, because live fields such as prices are updated on the
 client over WebSocket.
 
-The store is an LRU: an accessed entry is moved to the end, and once
-`MAX_ENTRIES = 500` is exceeded the oldest is evicted.
+The store is an LRU: an accessed entry is moved to the end, and once the limit
+(`cache().maxEntries`, 500 by default) is exceeded the oldest is evicted.
 
 ## What gets written to the cache
 
@@ -223,15 +241,118 @@ Details:
 - `withRequestCache(run)` is exported; it can be used to set up the same scope
   outside `route()` (for example in an Express handler you wrote yourself).
 
+## Cross-request data cache: `withDataCache`
+
+`cache()` only lives for the duration of **a single request**. What it takes to
+protect the long tail from the API quota is a data layer that lives across
+requests, has a TTL and refreshes itself:
+
+```js
+// lib/api/articles.js
+import { withDataCache, reportUpstreamFailure } from "jskelet";
+
+export async function getArticle(slug) {
+  return withDataCache(`news:${slug}`, 600, async () => {
+    const response = await fetch(`${process.env.API_ORIGIN}/articles/${slug}`);
+
+    if (!response.ok) {
+      reportUpstreamFailure({ status: response.status, path: `/articles/${slug}` });
+      return null;
+    }
+
+    return response.json();
+  });
+}
+```
+
+The wrapper form of the same pattern — the key is derived from the arguments:
+
+```js
+import { dataCache } from "jskelet";
+
+export const getArticle = dataCache(
+  async (slug) => apiGet(`/articles/${slug}`),
+  { key: "news", revalidate: 600 },
+);
+```
+
+Behaviour:
+
+| State | Result |
+| --- | --- |
+| Fresh entry | Returns immediately, the `producer` does not run |
+| TTL expired, still inside the stale window | The stale value returns **immediately**, the refresh runs in the background |
+| No entry | The `producer` is awaited |
+| The `producer` failed, a stale entry exists | The stale value returns, warning: `[data-cache] producer failed, serving stale value: …` |
+| The `producer` failed, there is no entry | The error goes to the caller |
+
+Details:
+
+- **Concurrent calls for the same key collapse into one upstream request.** This
+  is the behaviour that saves the most quota during warm-up rounds: if 50 pages
+  want the same index data, the API is called once.
+- **`null` and `undefined` are not stored.** An application's HTTP client
+  usually returns `null` on failure; storing that would freeze a transient 429
+  into "no data" for the whole TTL. Pass `{ storeEmpty: true }` if you want the
+  empty answer stored deliberately.
+- **The stale window is longer than the HTML one**: `staleFactor` defaults to 10,
+  so an entry stays as an emergency fallback for 11 times its TTL. Stale data is
+  better than an incomplete page. It can be turned off per key with
+  `{ staleFactor: 0 }`.
+- The key belongs entirely to the application: distinctions such as language,
+  version or page number go into the key (`news:en:v2:${slug}`).
+- When the TTL is `0` the cache is disabled and the `producer` runs on every
+  call — enough to switch a setting off temporarily.
+
+The management surface:
+
+| Function | What it does |
+| --- | --- |
+| `withDataCache(key, ttlSeconds, producer, options?)` | The main entry point |
+| `dataCache(fn, { key, revalidate, … })` | The function wrapper |
+| `clearDataCache(prefix?)` | Drops the entries matching the prefix (or all of them), returns how many were removed |
+| `getDataCacheSize()` | The number of entries |
+| `getDataCacheEntries()` | A dump: `{ key, stale, expiresIn }`. The value itself is not returned. |
+
+`clearDataCache("news:")` is the counterpart of a "this content was updated"
+webhook: it drops one section's data so the next HTML refresh picks up the new
+content.
+
 ## Degraded render: `reportUpstreamFailure`
 
 If upstream went down during the render, the output contains missing data.
 Rather than serving such HTML for the whole TTL, the right behaviour is to
 **never write it** to the cache: the next request tries again.
 
-The dependency direction is deliberately inverted: the framework does not know
-about the data layer, the data layer notifies the framework. If nobody ever
-calls it, the cost is an empty array.
+This information arrives through two paths.
+
+### Automatic tracking (the default)
+
+At startup `createApp()` wraps `globalThis.fetch` and reports **transient**
+failures (`429`, `5xx`, network errors) from calls made during a render on its
+own. No application code is needed; if your API client talks over `fetch`, the
+rate limit protection is already in place.
+
+The details:
+
+- Only calls inside a render scope count. A `fetch` from a script, a cron job or
+  anywhere outside a request is left untouched.
+- Requests to our own server (`localhost`, `127.0.0.1`) are skipped: the warm-up
+  round and the health check are not upstream.
+- Deterministic answers such as `404`/`403` are **not** reported automatically.
+  In most APIs a `404` means "no such record"; treating it as missing data would
+  produce a false warning on every not-found page.
+- To turn it off: `cache().trackUpstream: false`. An application that wraps
+  `fetch` itself (metrics, retries, a circuit breaker) may prefer that.
+
+### Manual reporting
+
+For a client that does not use `fetch` (a database driver, gRPC, a vendor SDK),
+or for a layer that wants to flag permanent failures too, the contract is
+unchanged. The dependency direction is deliberately inverted: the framework does
+not know about the data layer, the data layer notifies the framework. If nobody
+ever calls it, the cost is an empty array. If the same failure arrives through
+both paths it is de-duplicated.
 
 ```js
 // lib/api/client.js
@@ -267,6 +388,58 @@ do not get better by retrying. Turning the cache off because of them would mean
 rendering the page from scratch on every visit — the content comes back just as
 incomplete, and the visitor only pays the render time.
 
+Output produced with missing data is **not offered to shared caches** either: a
+`degraded` response gets `private, no-store` instead of `public, s-maxage=…`.
+Taking back the "do not store" decision at the CDN would repeat the same mistake
+one layer up. The diagnostic header (`X-JSkelet-Cache: MISS`) is still written.
+
+### When `notFound()` coincides with a transient failure
+
+A controller that calls `notFound()` because no data arrived can turn the whole
+site into 404s when upstream is rate limited — and because those 404s enter the
+cache, a temporary quota problem becomes a "this page does not exist" answer for
+the whole TTL. For a search engine that is a permanent loss.
+
+The framework separates the two cases: if a **transient** upstream failure
+happened during the render, `notFound()` is not served as a 404. In order:
+
+1. The page is **retried** after a short delay (once by default, after 300 ms).
+   The retry runs in its own upstream and per-request cache scope, so neither
+   the first round's failure nor its memoized empty answers affect it.
+2. If the second round can produce the page, the visitor sees the **real
+   content** and the output is cached normally. Warm-up logs show this is
+   common: the same path returns 200 seconds later.
+3. If the retries are exhausted the response is a `503` — not cached, carrying
+   `Retry-After`, and the next request can still produce the real content.
+
+| During the render | Result of `notFound()` |
+| --- | --- |
+| A transient failure exists (`429`, `5xx`, network error) | Retry → the page if it succeeds; otherwise `503`, `Retry-After: 30`, `no-store` |
+| The retry got a clean answer saying "not there" | A normal `404` |
+| A permanent failure (`404`, `403`…) or no failure | A normal `404`, no retry |
+
+The log lines:
+
+```
+[render] /news/x returned notFound() while upstream is failing (429 /api/...), retrying (1/1)
+[render] /news/x could not be produced, upstream is still failing (429 /api/...), serving an uncached 503 instead of a 404
+```
+
+So **an existing page never turns into a 404**: either the real content arrives,
+or an uncached 503 does. Nothing is frozen as "missing".
+
+The cost of a retry is a second round of requests on upstream, which is why the
+default is a single attempt. The setting is `cache().transientRetry`:
+
+```js
+cache: {
+  transientRetry: { attempts: 2, delayMs: 500 },
+}
+```
+
+`transientRetry: false` (or `attempts: 0`) disables the retry and falls straight
+through to the 503.
+
 ## Managing the cache
 
 `jskelet` exports these functions:
@@ -345,26 +518,78 @@ Rules:
 - Ones starting with one of the `prewarmSkip` prefixes are skipped. The default
   list: `/api/`, `/_fragment/`, `/__jskelet/`. Session-dependent pages should
   not be warmed.
-- Deduplication **preserves order**: since the list is trimmed with
-  `PREWARM_MAX`, the priority order the application gives is meaningful — put
-  the most important pages first.
+- Deduplication **preserves order**: when no `priority` is given, the order the
+  application provides is meaningful — put the most important pages first.
 - If this hook is not defined the warm-up is never set up; not even the timer
   is started.
 
 ### Round logic
 
-1. The list is collected and trimmed with `PREWARM_MAX` (400 by default).
-2. `PREWARM_CONCURRENCY` workers send requests in parallel (4 in prod, 2 in
-   dev). Less parallelism in dev: so the scan does not compete for CPU with the
-   render of the page you currently have open in the browser.
-3. **A single serial retry round** is performed for the failed paths
-   (`concurrency: 1`). The errors are mostly upstream rate limiting (429): the
-   first round strains the API while fetching hundreds of pages at once. The
-   retry round gets those pages into the cache; otherwise the visitor pays for
-   the cold render.
-4. A summary is logged:
+1. The list is collected. If it is longer than `max` (400 by default) a slice is
+   selected: the paths matching `priority` are taken first **on every round**,
+   and the remaining slots are filled from the queue.
+2. `concurrency` workers send requests in parallel (4 in prod, 2 in dev). Less
+   parallelism in dev: so the scan does not compete for CPU with the render of
+   the page you currently have open in the browser.
+3. If `rps` is given, the round never goes above that rate — no matter the
+   parallelism.
+4. **A single serial retry round** is performed for the failed paths after
+   waiting `retryDelayMs` (`concurrency: 1`). The wait is deliberate: rate limit
+   windows are on the order of seconds, so retrying immediately just earns the
+   same 429.
+5. A summary is logged:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
+### Warm-up order: `priority`
+
+```js
+// jskelet.config.mjs
+cache: () => ({
+  prewarm: {
+    priority: [
+      "/",
+      "/markets/:path*",
+      /-comments$/,
+    ],
+  },
+}),
+```
+
+The pattern syntax (`/news/:slug`) and a plain `RegExp` can be used together;
+the latter is for rules the pattern syntax does not cover, such as "everything
+ending in `-comments`". Whatever is written first is warmed first; paths that
+match nothing go to the queue and keep their relative order.
+
+### Drip warm-up: `rotate` + `rps` + `intervalSeconds`
+
+On a site with 10,000 paths, warming everything in a single round is neither
+possible (the HTML cache holds 500 entries) nor right (the API quota runs out).
+The correct behaviour is to spread the list over time:
+
+```js
+prewarm: {
+  max: 300,               // 300 pages per round
+  rps: 4,                 // at most 4 requests per second
+  intervalSeconds: 300,   // a round every 5 minutes
+  rotate: true,           // the queue continues where it left off
+  priority: ["/", "/markets/:path*"],
+}
+```
+
+In this setup the priority pages are refreshed on every round, the rest of the
+queue is walked end to end across rounds, and upstream never sees more than four
+requests per second. Used together with the data cache, the warm-up barely
+reaches the API after the second round: it reads from the data layer.
+
+With rotation on, the paths left outside the limit are not lost, they are left
+for the next round; the log distinguishes this:
+`… , 700 deferred to the next pass`. With `rotate: false` you get the classic
+behaviour — every round warms the same first slice of the list and the rest is
+never warmed (`… , 700 over the limit`).
+
+If a round takes longer than `intervalSeconds`, a new round is not started;
+overlapping rounds would put twice the load on upstream.
+
 The requests go out with the headers `user-agent: jskelet-prewarm`
 (`brand.prewarmUserAgent`) and `accept-encoding: br, gzip`; the second one so
 that the compressed body enters the cache too.
@@ -397,10 +622,14 @@ comes first so that one-off experiments can be done without editing the config.
 | Setting | Env | `cache().prewarm` | Default |
 | --- | --- | --- | --- |
 | On/off | `PREWARM=0` disables it, `PREWARM=1` overrides the config and enables it | `enabled` | `true` |
-| Maximum paths | `PREWARM_MAX` | `max` | `400` |
+| Maximum paths per round | `PREWARM_MAX` | `max` | `400` |
 | Parallelism | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
+| Requests per second | `PREWARM_RPS` | `rps` | `0` (unlimited) |
 | Startup delay (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
+| Retry round delay (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Period (seconds) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (off) |
+| Queue rotation | — | `rotate` | `true` |
+| Warm-up order | — | `priority` | `[]` |
 
 Numeric settings only accept **positive and finite** values; an invalid value
 silently falls through to the next layer.
@@ -445,6 +674,18 @@ filled the cache.
   parameters may be multiplying entries.
 - **The warm-up never runs.** `hooks.prewarmPaths` is not defined, `PREWARM=0`
   is set, or `cache().prewarm.enabled === false`.
+- **The warm-up round pushes the API into 429.** No `rps` was given. Lowering
+  `concurrency` is not enough; the setting that protects the quota is the total
+  rate. The lasting fix is the data cache: after the second round the warm-up
+  does not reach upstream.
+- **The warm-up list is longer than `max` and its tail never warms.** `rotate`
+  may be `false`; the `over the limit` phrase in the log shows this.
+- **A whole section returns 404.** Upstream may be down. The page is now retried
+  once and, failing that, a 503 that does not enter the cache is returned
+  instead of a 404; look for the `returned notFound() while upstream is failing`
+  line in the log. If you still see 404s, the failure may come from a non-`fetch`
+  client (which needs `reportUpstreamFailure()`) or `cache().trackUpstream` is
+  off.
 
 ## What's next
 

package/docs/en/07-configuration.md

@@ -119,7 +119,17 @@ export default {
   async cache() {
     return {
       html: { "/": 60, "/news/:slug": 300 },
-      prewarm: { enabled: true, max: 400, concurrency: 4, intervalSeconds: 0 },
+      maxEntries: 500,
+      data: { maxEntries: 10000, staleFactor: 10 },
+      prewarm: {
+        enabled: true,
+        max: 400,
+        concurrency: 4,
+        rps: 0,
+        intervalSeconds: 0,
+        rotate: true,
+        priority: ["/", "/news/:slug"],
+      },
     };
   },
 
@@ -561,8 +571,10 @@ Details: [03-routing.md](./03-routing.md).
 
 ## `cache()`
 
-**Type:** `() => { html?: Record<string, number>, prewarm?: object }` —
-**Default:** `{ html: {}, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+**Type:**
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+**Default:**
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -582,18 +594,76 @@ html: {
 }
 ```
 
+### `cache().maxEntries`
+
+**Type:** `number` — **Default:** `500`
+
+The entry limit of the HTML cache. Because an entry costs a hundred kilobytes,
+raising this number burns through memory quickly; trying to solve a site with
+tens of thousands of paths from here is the wrong layer — the right place is
+`cache().data`.
+
+### `cache().data`
+
+The upstream data cache (`withDataCache`). Details:
+[06-caching.md](./06-caching.md).
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `maxEntries` | `number` | `10000` | The LRU entry limit. The limit is high because JSON is tens of times smaller than HTML. |
+| `staleFactor` | `number` | `10` | For how many TTLs an entry stays usable after the TTL expired. `0` → no stale serving. |
+
+### `cache().trackUpstream`
+
+**Type:** `boolean` — **Default:** `true`
+
+When on, `globalThis.fetch` is wrapped and transient upstream failures (`429`,
+`5xx`, network) during a render are reported automatically; calling
+`reportUpstreamFailure()` is not required. An application that wraps `fetch`
+itself can turn this off.
+
+### `cache().transientRetry`
+
+**Type:** `{ attempts?: number, delayMs?: number } | false` —
+**Default:** `{ attempts: 1, delayMs: 300 }`
+
+How many extra times a page is tried when `notFound()` was called because of a
+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().prewarm`
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
-| `max` | `number` | `400` | At most how many paths are prewarmed |
+| `max` | `number` | `400` | At most how many paths are prewarmed per pass |
 | `concurrency` | `number` | prod 4, dev 2 | Number of parallel workers |
+| `rps` | `number` | `0` | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. |
 | `delayMs` | `number` | prod 500, dev 3000 | Delay of the first pass after startup |
+| `retryDelayMs` | `number` | `2000` | How long to wait before the retry pass |
 | `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 |
+
+`priority` accepts two forms: the pattern syntax used everywhere in the config,
+and a plain `RegExp`. Whatever is written first is warmed first.
+
+```js
+prewarm: {
+  max: 500,
+  rps: 4,
+  intervalSeconds: 300,
+  priority: [
+    "/",                     // the home page
+    "/markets/:path*",        // the whole markets section
+    /-comments$/,             // a rule the pattern syntax does not cover
+  ],
+}
+```
 
-Each one can be overridden by an environment variable of the same name; env
-takes precedence. Details: [06-caching.md](./06-caching.md).
+Each numeric field can be overridden by an environment variable of the same
+name; env takes precedence. Details: [06-caching.md](./06-caching.md).
 
 ## `hooks`
 
@@ -689,7 +759,9 @@ and no warning is printed.
 | `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 2 | Number of parallel workers |
+| `PREWARM_RPS` | `prewarm` | `0` | At most how many prewarm requests per second; `0` is unlimited |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | Delay of the first pass |
+| `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | The wait before the retry pass |
 | `PREWARM_INTERVAL_SECONDS` | `startPrewarm` | `0` | If greater than 0, a periodic pass |
 | `JSKELET_VERBOSE` | `jskelet dev` | — | If `1`, all of the changed files are listed on restart |
 | `JSKELET_COLOR` | `jskelet/log` | — | If `1`, colour is forced. Because child processes write to a pipe, colour detection turns off; `jskelet dev` sets this itself. |

package/package.json

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

@@ -55,6 +55,69 @@ export const DEFAULT_PREWARM = {
   concurrency: 4,
   /** İki tur arasında beklenen süre: upstream'e ani yük binmesin. */
   delayMs: 0,
+  /**
+   * Saniyedeki en fazla ısıtma isteği. 0 → sınırsız (yalnızca `concurrency`
+   * frenler). Upstream'i kota sınırının altında tutmanın en doğrudan yolu bu:
+   * paralellik ne kadar yükselse de tur bu hızın üstüne çıkmaz.
+   */
+  rps: 0,
+  /**
+   * Tekrar turundan önce beklenen süre. Rate limit pencereleri saniye
+   * mertebesinde; hemen tekrar denemek aynı 429'u almak demek.
+   */
+  retryDelayMs: 2000,
+  /**
+   * Liste `max`'tan uzunsa periyodik turlar kaldığı yerden devam eder.
+   * Böylece 10.000 yolluk bir site tek turda değil, turlar boyunca ısınır.
+   * `priority` eşleşen yollar her turda ısıtıldığı için rotasyon yalnızca
+   * kuyruğu dolaşır.
+   */
+  rotate: true,
+  /**
+   * Isıtma sırasını belirleyen desenler. String (`/haber/:slug`) ya da
+   * `RegExp` kabul eder; önce yazılan önce ısınır.
+   * @type {(string | RegExp)[]}
+   */
+  priority: [],
+};
+
+/**
+ * HTML önbelleğinin girdi sınırı. 500 girdi ortalama bir sayfa boyutunda
+ * yaklaşık 100-200 MB tutar; uzun kuyruklu siteler bunu yükseltmek yerine
+ * veri önbelleğine yaslanmalı (bkz. `DEFAULT_DATA_CACHE`).
+ */
+export const DEFAULT_HTML_CACHE_MAX_ENTRIES = 500;
+
+/**
+ * `notFound()` geçici bir upstream hatasına denk geldiğinde sayfanın kaç kez
+ * daha denenmesi gerektiği.
+ *
+ * Varsayılan tek deneme: maliyeti upstream'e binen ikinci bir istek turu, ama
+ * alternatifi var olan bir sayfayı 404 olarak servis etmek — arama motoru için
+ * geçici bir rate limit'in kalıcı kayba dönüşmesi. `attempts: 0` tekrarı
+ * kapatır ve doğrudan önbelleğe girmeyen 503'e düşer.
+ */
+export const DEFAULT_TRANSIENT_RETRY = {
+  attempts: 1,
+  delayMs: 300,
+};
+
+/**
+ * Upstream veri önbelleği.
+ *
+ * HTML önbelleğinden bilinçli olarak çok daha büyük: JSON, aynı sayfanın
+ * HTML'ine göre onlarca kat küçük. Uzun kuyruğu (on binlerce haber/etiket)
+ * HTML olarak tutmak imkânsız, verisini tutmak ise ucuz — ve API kotasını
+ * koruyan katman burası.
+ */
+export const DEFAULT_DATA_CACHE = {
+  maxEntries: 10000,
+  /**
+   * TTL dolduktan sonra girdinin kaç TTL boyunca daha kullanılabileceği.
+   * HTML'deki 1 katsayısından yüksek: bayat veri, eksik sayfadan iyidir ve
+   * upstream düştüğünde tek elde kalan şey budur.
+   */
+  staleFactor: 10,
 };
 
 /** Oturuma bağlı sayfalar ısıtılmaz; uygulama kendi listesini verebilir. */