jskelet 0.2.1 → 0.2.3

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
 
@@ -441,6 +454,98 @@ cache: {
 `transientRetry: false` (or `attempts: 0`) disables the retry and falls straight
 through to the 503.
 
+## Upstream rate limit: `cache().upstream`
+
+Everything above describes what happens **after** a 429 arrives. This section is
+about not getting one in the first place.
+
+The brake sits inside the `trackUpstreamFetch()` wrapper, that is, where the
+real `fetch` call goes out. The prewarm pass's `prewarm.rps` cannot do this job:
+it counts **page** requests to our own server, but one page render may make one
+API call or twenty. What binds the quota is the number of calls, not the number
+of pages — and with the brake here, prewarming and real traffic spend the same
+budget.
+
+Off by default: unless `rate` is given, no request ever waits and the cost is a
+single branch.
+
+```js
+// jskelet.config.mjs
+cache: () => ({
+  upstream: {
+    rate: 10, // ceiling in calls per second, per host
+    burst: 20, // tolerance for short bursts
+    concurrency: 8, // calls in flight at once
+    hosts: {
+      // Endpoints with a different quota get their own settings.
+      "api.example.com": { rate: 3, concurrency: 2 },
+    },
+  },
+}),
+```
+
+### Three mechanisms, three different limits
+
+| Mechanism | What it bounds | Settings |
+| --- | --- | --- |
+| Token bucket | Average rate (calls per second) | `rate`, `burst` |
+| Concurrency | Instantaneous pressure (calls in flight) | `concurrency` |
+| AIMD | What the right rate actually is | `minRate`, `increaseStep`, `increaseIntervalMs`, `decreaseIntervalMs` |
+
+The third one is the real idea. A fixed rate is always either too slow or too
+fast: nobody can write the true quota limit into a config file, and it changes
+during the day anyway. So `rate` is treated as a **ceiling** and the actual rate
+moves with what the upstream says:
+
+- **429 or 503** → the rate is halved (multiplicative decrease). If the response
+  carries `Retry-After`, the bucket stops entirely for that long — the upstream
+  is already telling you how long to wait.
+- **Every clean window** → the rate climbs by `increaseStep` (additive
+  increase), up to the `rate` ceiling.
+
+Decreasing multiplicatively and increasing additively is deliberate. The other
+way round would earn a fresh 429 every window.
+
+### Circuit breaker
+
+A host that returns `breakerFailures` (default 5) rate limits in a row is
+bypassed entirely for `breakerCooldownMs`: the call is not made at all and is
+reported straight away as a transient failure.
+
+It looks harsh, but the asymmetry demands it: because a 429 counts as transient,
+the HTML produced by that call is **not stored**. So a pass that hit the rate
+limit spends quota and stores nothing in return — and the next pass finds the
+same page cold and tries again. The breaker stops that burn.
+
+```
+[upstream] api.example.com: 5 consecutive rate limits — bypassing for 10000ms (rate is now 1.2/s)
+```
+
+Only 429 and 503 count. A `400`/`404` is not a quota problem and neither is a
+`500`: slowing down does not fix them, it only makes the site slower.
+
+### Seeing the state
+
+`getUpstreamLimiterStatus()` returns the current rate, calls in flight and
+counters per host; the dev panel's **Server** tab prints the same thing. During
+a 429 storm, tuning without knowing "what rate is it down to right now" is
+guesswork.
+
+```js
+import { getUpstreamLimiterStatus } from "jskelet";
+
+// [{ host: "api.example.com", rate: 2.5, maxRate: 10, concurrency: 8,
+//    active: 3, throttled: 12, rejected: 40, bypassed: false, blockedMs: 0 }]
+```
+
+### Before turning it on
+
+The rate limit is a last resort. If hundreds of pages fetch the same upstream
+response, the real fix is keeping the
+[`withDataCache`](#cross-request-data-cache-withdatacache) TTL longer than the
+pass interval: a 400-page pass then makes one call for a shared endpoint. The
+brake slows those calls down, it does not reduce their number.
+
 ## Managing the cache
 
 `jskelet` exports these functions:
@@ -664,8 +769,220 @@ 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
+
+Instead of hand-writing the `getHtmlCacheEntries()` / `getRedisStatus()`
+endpoints above, the framework ships a panel. It is deliberately separate from
+the dev overlay: the overlay only exists while `NODE_ENV=development`, while the
+panel does not look at the environment — "why is this page stale", "did the
+webhook purge land", "is Redis actually connected" are production questions.
+
+```js
+// jskelet.config.mjs
+export default {
+  cache() {
+    return {
+      html: { "/news/:slug": 300 },
+      panel: { enabled: process.env.CACHE_PANEL === "1" },
+    };
+  },
+};
+```
+
+Without `enabled` **nothing is mounted**: the path does not exist, the module is
+never loaded and it costs the production process nothing. The environment
+variable (`JSKELET_CACHE_PANEL=1`) overrides the config, because the panel is
+usually opened once during an incident and editing the config file and
+redeploying is the last thing you want at that moment.
+
+When the panel is on, the server log prints the password:
+
+```
+[cache-panel] http://localhost:3000/_jskelet/cache — password for this run: 3f9c…
+```
+
+### Access and hardening
+
+- **The password is regenerated on every process start** (32 hex characters) and
+  only ever appears in the log. There is no persistent secret to leak: leaking
+  one means handing out the right to flush the cache, and a deploy should revoke
+  old access on its own.
+- **The password is not accepted in the query string,** so access logs, browser
+  history and the `Referer` header never carry it. Sign-in goes through the form.
+- **Three failed attempts ban the IP for 24 hours** (`banAttempts`, `banHours`).
+  Requests without a session count just like a wrong password; a successful
+  sign-in resets the counter.
+- **Banned and unauthorised requests get a `404`.** A 401 or 403 confirms the
+  panel exists; a 404 behaves as if it never did. The rest of the site is
+  untouched.
+- **Nothing is indexable:** every response carries `X-Robots-Tag: noindex,
+  nofollow, noarchive, nosnippet`, `Cache-Control: no-store` and
+  `Referrer-Policy: no-referrer`. The path is also exempt from prewarming and
+  from navigation speculation.
+- Actions require an `X-JSkelet-Cache-Panel` header — a header a cross-site form
+  cannot send, which is the panel's own CSRF brake.
+- Sessions and ban counters live in process memory; persisting them to disk
+  would be the wrong trade for a panel whose password changes on every restart.
+
+### What the panel shows
+
+| Area | Contents |
+| --- | --- |
+| 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 |
+| 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
+the counter in the heading says how many matches were cut. HTML bodies and
+cached values are **never returned** — the panel's job is to show state, not to
+export content.
+
+### What you can do from it
+
+| Action | Equivalent call |
+| --- | --- |
+| Invalidate (target + `hard`) | `invalidateHtmlCache(target, { hard })` |
+| `drop` a single row | `dropHtmlCacheKey(key)` / `dropDataCacheKey(key)` |
+| 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
+clustered setup.
+
+Dropping a single row is not the same as `invalidateHtmlCache()`: that one
+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
@@ -720,13 +1037,29 @@ Rules:
    parallelism. In dev, 4 requests per second apply by default: rendering runs
    on a single event loop, so an unpaced round leaves page requests and the dev
    panel's live channel waiting behind it.
-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:
+4. **A single serial retry round** is performed for the paths that hit a
+   **transient** failure (`concurrency: 1`). Permanent answers like `400`, `403`
+   or `404` are not retried: a deterministic error does not get better on the
+   second try and those calls spend quota for nothing. The summary shows them as
+   `N not retried (permanent)`.
+5. The wait before the retry is `retryDelayMs`, but when the rate limit is on and
+   something is holding it back, that wins: retrying 2 seconds into a 10 second
+   circuit breaker would just earn the same 429 up front.
+6. A summary is logged:
    `[prewarm] warmed 128/130 pages, 2 failed, 5 recovered on the retry pass (12.4s)`
 
+Then comes how much the pass actually touched the upstream:
+
+```text
+[prewarm] 12 upstream calls for 430 data reads (97% from the data cache, 38 coalesced)
+```
+
+This is the one line that tells you which way to turn the knob. If the ratio is
+low the fix is not the rate limit but a longer `withDataCache` TTL — the brake
+slows calls down, it does not reduce their number. The same counters are
+available through `getDataCacheStats()` and on the dev report's **Data cache**
+card.
+
 Request errors and the per-page render warnings (`was produced with missing
 data`, `returned notFound() while upstream is failing`, `could not be
 produced`) raised during the pass are not logged one by one. They are counted

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, 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 }, 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`
@@ -643,6 +677,39 @@ 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().upstream`
+
+A per-host rate limit for the `fetch` calls that go to upstream APIs. Off by
+default: unless `rate` is given, no request ever waits. `rate` is a ceiling; the
+actual rate pulls itself down in response to 429s and climbs back step by step
+during clean windows.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `rate` | `number` | `0` | Maximum calls per second. `0` → brake disabled |
+| `burst` | `number` | `0` | Bucket size; `0` → one second's budget of burst |
+| `concurrency` | `number` | `8` | Calls allowed in flight at once |
+| `minRate` | `number` | `0.5` | Floor of the decrease; the rate never goes below it |
+| `increaseStep` | `number` | `1` | Step of the additive increase (calls/second) |
+| `increaseIntervalMs` | `number` | `5000` | Increase period |
+| `decreaseIntervalMs` | `number` | `1000` | Minimum time between two decreases |
+| `breakerFailures` | `number` | `5` | Consecutive 429s after which the host is bypassed |
+| `breakerCooldownMs` | `number` | `10000` | How long the bypass lasts |
+| `hosts` | `Record<string, object>` | `{}` | Per-host overrides; same fields apply |
+
+Only `429` and `503` penalise the rate: a `400`/`404`/`500` is not a quota
+problem. Read the state with `getUpstreamLimiterStatus()` or from the dev
+panel's **Server** tab. Details, and what to check before turning it on:
+[06-caching.md](./06-caching.md).
+
+```js
+upstream: {
+  rate: 10,
+  concurrency: 4,
+  hosts: { "api.example.com": { rate: 3 } },
+}
+```
+
 ### `cache().redis`
 
 An optional Redis second tier (L2). The in-process cache stays primary; Redis
@@ -677,6 +744,68 @@ redis: {
 }
 ```
 
+### `cache().panel`
+
+The cache admin panel. It shows the state of the in-process tier and the Redis
+tier, and it triggers targeted invalidation, single-entry drops and prewarming.
+
+It does not look at the environment: without `enabled` **nothing is mounted**
+and the path does not exist. When it is on it also works in production — that is
+where the real questions ("why is this page stale", "did the webhook purge
+land") get asked.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Only turns on when explicitly `true` (`JSKELET_CACHE_PANEL` overrides it) |
+| `basePath` | `string` | `"/_jskelet/cache"` | Root of the panel |
+| `banAttempts` | `number` | `3` | How many failed attempts ban an IP |
+| `banHours` | `number` | `24` | How long the ban lasts |
+| `sessionHours` | `number` | `12` | Lifetime of the session cookie |
+
+The password is generated **on every process start** and only appears in the
+server log:
+
+```
+[cache-panel] http://localhost:3000/_jskelet/cache — password for this run: 3f9c…
+```
+
+There is no persistent secret (no config field, no environment variable):
+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",
+}
+```
+
 ### `cache().prewarm`
 
 | Field | Type | Default | Meaning |
@@ -801,6 +930,10 @@ and no warning is printed.
 | `HOST` | `startServer` | `::` | Interface to bind to. The default listens dual-stack (IPv6 + IPv4); it falls back to `0.0.0.0` where IPv6 is unavailable |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | The signed cookie secret. Read when `security.cookieSecret` is not set; if neither exists, the signed cookie API throws. [12](./12-dashboards-and-sessions.md) |
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
+| `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.1",
+  "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

@@ -0,0 +1,71 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <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 · 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
+        (<code>[cache-panel]</code>).
+      </p>
+      <input
+        id="password"
+        type="password"
+        name="password"
+        maxlength="64"
+        spellcheck="false"
+        autocomplete="off"
+        placeholder="32-character password"
+        autofocus
+      />
+      <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">
+      const form = document.getElementById("form");
+      const input = document.getElementById("password");
+      const error = document.getElementById("error");
+
+      form.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        error.textContent = "";
+
+        const response = await fetch("login", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ password: input.value }),
+        });
+
+        if (response.ok) {
+          location.reload();
+          return;
+        }
+
+        // Yasaklandıysa sunucu artık 404 dönüyor; kalan deneme sayısı
+        // bilinçli olarak bildirilmiyor.
+        error.textContent =
+          response.status === 404
+            ? "Too many attempts."
+            : "Invalid password.";
+        input.value = "";
+        input.focus();
+      });
+    </script>
+  </body>
+</html>