jskelet 0.2.1 → 0.2.2

package/docs/en/07-configuration.md

@@ -572,9 +572,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, redis?: object, prewarm?: object }` —
+`() => { html?: Record<string, number>, 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: {}, 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`
 
@@ -643,6 +643,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 +710,42 @@ 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).
+
+```js
+panel: {
+  enabled: process.env.CACHE_PANEL === "1",
+}
+```
+
 ### `cache().prewarm`
 
 | Field | Type | Default | Meaning |
@@ -801,6 +870,7 @@ 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) |
 | `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.2",
   "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,63 @@
+<!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</title>
+    <link rel="stylesheet" href="panel.css" />
+  </head>
+  <body class="login">
+    <form id="form" autocomplete="off">
+      <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>
+    </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>

package/src/client/cache-panel/panel.css

@@ -0,0 +1,448 @@
+/*
+ * Önbellek panelinin stili. Framework'ün build hattından geçmez: panel
+ * doğrudan diskten servis edilir ve uygulamanın Tailwind çıktısına bağlı
+ * olmamalı — panelin açık olduğu bir kurulumda `jskelet build` hiç
+ * koşmamış olabilir.
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+:root {
+  color-scheme: dark;
+  --bg: #0a0b0e;
+  --panel: #12141a;
+  --panel-2: #171a21;
+  --line: #23272f;
+  --text: #e7e9ee;
+  --muted: #8b93a1;
+  --accent: #6ea8fe;
+  --ok: #4ade80;
+  --warn: #fbbf24;
+  --bad: #f87171;
+  --radius: 10px;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  min-height: 100vh;
+  background:
+    radial-gradient(1200px 600px at 20% -10%, #16202f 0%, transparent 60%),
+    var(--bg);
+  color: var(--text);
+  font:
+    14px/1.5 ui-sans-serif,
+    system-ui,
+    -apple-system,
+    "Segoe UI",
+    sans-serif;
+}
+
+code,
+.mono,
+input,
+table {
+  font-family:
+    ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+    monospace;
+}
+
+a {
+  color: var(--accent);
+}
+
+/* ------------------------------------------------------------------ giriş */
+
+.login {
+  display: grid;
+  place-items: center;
+  min-height: 100vh;
+  padding: 24px;
+}
+
+.login form {
+  width: 100%;
+  max-width: 420px;
+  padding: 28px;
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  background: var(--panel);
+  box-shadow: 0 24px 60px rgb(0 0 0 / 45%);
+}
+
+.login h1 {
+  margin: 0 0 6px;
+  font-size: 18px;
+  letter-spacing: -0.01em;
+}
+
+.login p {
+  margin: 0 0 20px;
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.login input {
+  width: 100%;
+  padding: 11px 12px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: #0d0f14;
+  color: var(--text);
+  font-size: 13px;
+  letter-spacing: 0.06em;
+}
+
+.login input:focus {
+  border-color: var(--accent);
+  outline: none;
+}
+
+.login button {
+  width: 100%;
+  margin-top: 12px;
+}
+
+.error {
+  min-height: 18px;
+  margin-top: 10px;
+  color: var(--bad);
+  font-size: 12px;
+}
+
+/* ------------------------------------------------------------------ düzen */
+
+header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  align-items: center;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--line);
+  background: rgb(10 11 14 / 85%);
+  backdrop-filter: blur(8px);
+  position: sticky;
+  top: 0;
+  z-index: 5;
+}
+
+header h1 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 600;
+}
+
+header .spacer {
+  flex: 1;
+}
+
+.chip {
+  padding: 3px 9px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  color: var(--muted);
+  font-size: 11.5px;
+  white-space: nowrap;
+}
+
+.chip.on {
+  border-color: color-mix(in oklab, var(--ok) 45%, var(--line));
+  color: var(--ok);
+}
+
+.chip.off {
+  border-color: color-mix(in oklab, var(--bad) 45%, var(--line));
+  color: var(--bad);
+}
+
+.chip.idle {
+  border-color: color-mix(in oklab, var(--warn) 45%, var(--line));
+  color: var(--warn);
+}
+
+main {
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 12px;
+}
+
+.card {
+  padding: 14px 16px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--panel);
+}
+
+.card .label {
+  color: var(--muted);
+  font-size: 11.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.card .value {
+  margin-top: 6px;
+  font-size: 22px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+.card .sub {
+  margin-top: 2px;
+  color: var(--muted);
+  font-size: 12px;
+}
+
+section {
+  margin-top: 20px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--panel);
+  overflow: hidden;
+}
+
+section > h2 {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  margin: 0;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--line);
+  background: var(--panel-2);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+section > h2 .count {
+  color: var(--muted);
+  font-weight: 400;
+}
+
+.body {
+  padding: 14px 16px;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+}
+
+.row + .row {
+  margin-top: 10px;
+}
+
+/* --------------------------------------------------------------- kontroller */
+
+button {
+  padding: 8px 13px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel-2);
+  color: var(--text);
+  font: inherit;
+  font-size: 12.5px;
+  cursor: pointer;
+}
+
+button:hover:not(:disabled) {
+  border-color: color-mix(in oklab, var(--accent) 50%, var(--line));
+  color: #fff;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+button.primary {
+  border-color: color-mix(in oklab, var(--accent) 55%, var(--line));
+  background: color-mix(in oklab, var(--accent) 18%, var(--panel-2));
+}
+
+button.danger {
+  border-color: color-mix(in oklab, var(--bad) 45%, var(--line));
+  color: color-mix(in oklab, var(--bad) 80%, var(--text));
+}
+
+button.tiny {
+  padding: 3px 8px;
+  font-size: 11px;
+}
+
+input[type="text"],
+input[type="password"],
+input[type="search"] {
+  padding: 8px 11px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #0d0f14;
+  color: var(--text);
+  font-size: 12.5px;
+}
+
+input[type="text"]:focus,
+input[type="search"]:focus {
+  border-color: var(--accent);
+  outline: none;
+}
+
+input.grow {
+  flex: 1;
+  min-width: 220px;
+}
+
+label.check {
+  display: inline-flex;
+  gap: 6px;
+  align-items: center;
+  color: var(--muted);
+  font-size: 12.5px;
+  white-space: nowrap;
+}
+
+.hint {
+  margin: 8px 0 0;
+  color: var(--muted);
+  font-size: 12px;
+}
+
+/* -------------------------------------------------------------- sekme/tablo */
+
+.tabs {
+  display: flex;
+  gap: 4px;
+  margin-left: auto;
+}
+
+.tabs button {
+  border-color: transparent;
+  background: transparent;
+  color: var(--muted);
+}
+
+.tabs button[aria-selected="true"] {
+  border-color: var(--line);
+  background: var(--panel);
+  color: var(--text);
+}
+
+.scroll {
+  max-height: 460px;
+  overflow: auto;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12.5px;
+}
+
+th {
+  position: sticky;
+  top: 0;
+  padding: 9px 12px;
+  border-bottom: 1px solid var(--line);
+  background: var(--panel-2);
+  color: var(--muted);
+  font-weight: 500;
+  text-align: left;
+  white-space: nowrap;
+}
+
+td {
+  padding: 8px 12px;
+  border-bottom: 1px solid color-mix(in oklab, var(--line) 60%, transparent);
+  vertical-align: middle;
+}
+
+tr:last-child td {
+  border-bottom: none;
+}
+
+td.key {
+  max-width: 520px;
+  overflow-wrap: anywhere;
+}
+
+td.num {
+  text-align: right;
+  white-space: nowrap;
+}
+
+td.actions {
+  text-align: right;
+  white-space: nowrap;
+}
+
+.tag {
+  padding: 1px 7px;
+  border-radius: 999px;
+  font-size: 11px;
+}
+
+.tag.fresh {
+  background: color-mix(in oklab, var(--ok) 18%, transparent);
+  color: var(--ok);
+}
+
+.tag.stale {
+  background: color-mix(in oklab, var(--warn) 18%, transparent);
+  color: var(--warn);
+}
+
+.empty {
+  padding: 28px 16px;
+  color: var(--muted);
+  text-align: center;
+}
+
+/* ------------------------------------------------------------------ toast */
+
+#toast {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  z-index: 20;
+  display: grid;
+  gap: 8px;
+  justify-items: end;
+}
+
+.toast {
+  max-width: 420px;
+  padding: 10px 14px;
+  border: 1px solid var(--line);
+  border-left: 3px solid var(--ok);
+  border-radius: 8px;
+  background: var(--panel);
+  box-shadow: 0 12px 30px rgb(0 0 0 / 45%);
+  font-size: 12.5px;
+  animation: rise 0.18s ease-out;
+}
+
+.toast.bad {
+  border-left-color: var(--bad);
+}
+
+@keyframes rise {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+}