jskelet 0.2.2 → 0.2.3

package/src/config/index.js

@@ -15,7 +15,8 @@
  *   headers()   → [{ source, headers: [{ key, value }] }]
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
- *   cache()     → { html?: { [source]: saniye }, maxEntries?: number,
+ *   cache()     → { html?: { [source]: saniye },
+ *                   query?: { [source]: string[] | true }, maxEntries?: number,
  *                   data?: {...}, redis?: {...}, prewarm?: {...},
  *                   panel?: {...} }
  *
@@ -30,6 +31,7 @@ import { compilePattern, matchPattern } from "./pattern.js";
 import {
   DEFAULT_BRAND,
   DEFAULT_CACHE_PANEL,
+  DEFAULT_CLOUDFLARE,
   DEFAULT_DATA_CACHE,
   DEFAULT_DEV_GATE_BYPASS,
   DEFAULT_DIRS,
@@ -84,6 +86,9 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, destination: string, statusCode: number }[]} redirects
  * @property {{ phase: "beforeFiles" | "afterFiles", pattern: CompiledPattern, destination: string }[]} rewrites
  * @property {{ pattern: CompiledPattern, seconds: number }[]} html
+ * @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 {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.
@@ -92,6 +97,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {RedisConfig} redis Opsiyonel Redis ikinci kademesi.
  * @property {typeof DEFAULT_UPSTREAM_LIMIT} upstream Upstream hız freni.
  * @property {typeof DEFAULT_CACHE_PANEL} cachePanel Önbellek yönetim paneli.
+ * @property {typeof DEFAULT_CLOUDFLARE} cloudflare Cloudflare cache yüzeyi.
  * @property {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
  * @property {Record<string, unknown>} brand
@@ -338,15 +344,87 @@ function normalizeCachePanel(raw) {
   };
 }
 
+/**
+ * Cloudflare bölümü. Token burada da verilebiliyor ama önerilen yol env;
+ * normalizasyon sadece tipleri sabitler, sırrı okumak `cloudflare.js`'in işi.
+ *
+ * @param {unknown} raw
+ * @returns {typeof DEFAULT_CLOUDFLARE}
+ */
+function normalizeCloudflare(raw) {
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const hours = Number(source.analyticsHours);
+
+  /** @param {unknown} value */
+  const text = (value) => (typeof value === "string" && value ? value : null);
+
+  return {
+    enabled: source.enabled !== false,
+    zoneId: text(source.zoneId),
+    apiToken: text(source.apiToken),
+    // Şema yazılırsa purge URL'i `https://https://…` olur; baştaki şema atılır.
+    hostname: text(source.hostname)?.replace(/^https?:\/\//, "") ?? null,
+    analyticsHours:
+      Number.isFinite(hours) && hours > 0
+        ? Math.min(72, Math.floor(hours))
+        : DEFAULT_CLOUDFLARE.analyticsHours,
+  };
+}
+
+/**
+ * `cache().query` → yol deseni başına, cache anahtarına girmesine izin verilen
+ * query parametreleri.
+ *
+ * Varsayılan bilinçli olarak "query varsa sayfa dinamik": bir yolun bütün
+ * query varyantlarını cache'lemek, `?utm_source=…` gibi sonsuz sayıda anahtar
+ * üretip LRU'daki gerçek sayfaları dışarı atıyor. Hangi parametrenin çıktıyı
+ * gerçekten değiştirdiğini yalnızca uygulama bilir, o yüzden izin listesi
+ * config'ten gelir.
+ *
+ * Bir desen `true` ile eşlenirse bütün parametreler anahtara girer (eski
+ * davranış), `[]` ile eşlenirse hiçbiri girmez — yani query yok sayılır ve
+ * bütün varyantlar query'siz sürümün HTML'ini paylaşır.
+ *
+ * @param {unknown} raw
+ * @returns {ResolvedConfig["cacheQuery"]}
+ */
+function normalizeQueryRules(raw) {
+  /** @type {ResolvedConfig["cacheQuery"]} */
+  const out = [];
+
+  for (const [source, value] of Object.entries(raw ?? {})) {
+    const pattern = compilePattern(source);
+    if (!pattern) continue;
+
+    if (value === true) {
+      out.push({ pattern, allow: true });
+      continue;
+    }
+    if (value === false) continue;
+
+    const allow = asArray(
+      typeof value === "string" ? [value] : value,
+      `cache().query["${source}"]`,
+    )
+      .filter((name) => typeof name === "string" && name)
+      .map(String);
+    out.push({ pattern, allow });
+  }
+
+  return out;
+}
+
 /**
  * @param {unknown} raw
- * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
+ * @returns {{ html: ResolvedConfig["html"],
+ *   cacheQuery: ResolvedConfig["cacheQuery"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
  *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
  *   redis: RedisConfig,
  *   upstream: typeof DEFAULT_UPSTREAM_LIMIT,
  *   cachePanel: typeof DEFAULT_CACHE_PANEL,
+ *   cloudflare: typeof DEFAULT_CLOUDFLARE,
  *   prewarm: Record<string, unknown>,
  *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
  */
@@ -362,10 +440,12 @@ function normalizeCache(raw) {
   }
 
   const prewarm = { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) };
+  const queryRules = normalizeQueryRules(raw?.query);
   const maxEntries = Number(raw?.maxEntries);
 
   return {
     html,
+    cacheQuery: queryRules,
     htmlMaxEntries:
       Number.isFinite(maxEntries) && maxEntries > 0
         ? Math.floor(maxEntries)
@@ -385,6 +465,7 @@ function normalizeCache(raw) {
     redis: normalizeRedis(raw?.redis),
     upstream: normalizeUpstream(raw?.upstream),
     cachePanel: normalizeCachePanel(raw?.panel),
+    cloudflare: normalizeCloudflare(raw?.cloudflare),
     // Desenler derlenmiş hâlde ayrı alanda tutulur: `prewarm` sayısal
     // ayarların düz torbası olarak kalsın, her turda yeniden derlenmesin.
     prewarm,
@@ -597,6 +678,7 @@ export async function loadConfig(options = {}) {
 
   const {
     html,
+    cacheQuery,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -605,6 +687,7 @@ export async function loadConfig(options = {}) {
     redis,
     upstream,
     cachePanel,
+    cloudflare,
     prewarm,
     prewarmPriority,
   } = normalizeCache(cache);
@@ -619,6 +702,7 @@ export async function loadConfig(options = {}) {
     redirects: normalizeRedirects(redirects),
     rewrites: normalizeRewrites(rewrites),
     html,
+    cacheQuery,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -627,6 +711,7 @@ export async function loadConfig(options = {}) {
     redis,
     upstream,
     cachePanel,
+    cloudflare,
     prewarm,
     prewarmPriority,
     brand,

package/src/index.js

@@ -58,7 +58,22 @@ export {
 } from "./server/data-cache.js";
 // Paylaşımlı önbellek kademesinin durumu. Bağlantı kurulmamışken de güvenle
 // çağrılır; healthcheck uçları bunu okuyor.
-export { getRedisStatus } from "./server/redis.js";
+// `getRedisDetails()` bağlantının nereye kurulduğunu ve hangi türleri
+// paylaştığını söyler (şifre asla dönmez); `inspectRedis()` tür başına anahtar
+// sayar — bir `SCAN` turu olduğu için istek yolunda çağrılmamalı.
+export { getRedisDetails, getRedisStatus, inspectRedis } from "./server/redis.js";
+// CDN kademesi. JSkelet'in önbelleği origin önbelleği; ziyaretçinin gördüğü
+// kopya edge'de duruyor. Bir içeriği gerçekten tazelemek için ikisini birlikte
+// düşürmek gerekiyor: `invalidateHtmlCache()` + `purgeCloudflare()`.
+export {
+  cloudflareConfigured,
+  fetchCacheAnalytics,
+  fetchCloudflareOverview,
+  fetchPathEdges,
+  getCloudflareStatus,
+  purgeCloudflare,
+  toCloudflareUrls,
+} from "./server/cloudflare.js";
 // Upstream hız freninin host başına durumu: healthcheck ve teşhis uçları için.
 export { getUpstreamLimiterStatus } from "./server/upstream-limiter.js";
 export { prewarm, prewarmProgress } from "./server/prewarm.js";

package/src/log.mjs

@@ -284,6 +284,31 @@ function truncate(text, max) {
 /** Kutunun içi sabit genişlikte; uzun satırlar kırpılır. */
 const BOX = 52;
 
+/**
+ * Çerçeveli bilgi kutusu.
+ *
+ * Açılış logunda kaybolmaması gereken tek şey sır: önbellek panelinin şifresi
+ * her restart'ta değişiyor ve kullanıcı onu bir kez, akışın içinde görüyor.
+ * Genişlik içeriğe göre büyür — bir URL'i ya da 32 haneli bir şifreyi
+ * kırpmak kutunun bütün amacını bozar.
+ *
+ * @param {{ title: string, lines: string[],
+ *   tint?: (value: string) => string }} info `lines` içinde boş string ayırıcı
+ *   satır olur. Satırlar **düz metin** olmalı: bir ANSI dizisi `length`e
+ *   sayıldığı için hizalamayı bozar, rengi çerçeve taşır.
+ */
+export function box({ title, lines, tint = c.cyan }) {
+  const width = Math.max(BOX, title.length + 4, ...lines.map((text) => text.length + 4));
+  const top = `┌─ ${title} ${"─".repeat(width - title.length - 3)}┐`;
+  const bottom = `└${"─".repeat(width)}┘`;
+
+  write(`\n${tint(top)}\n`);
+  for (const text of ["", ...lines, ""]) {
+    write(`${tint("│")}  ${text}${" ".repeat(width - 4 - text.length)}  ${tint("│")}\n`);
+  }
+  write(`${tint(bottom)}\n\n`);
+}
+
 /**
  * Çerçeveli hata kutusu — kendi framework'ünü geliştirirken hatanın
  * akış içinde kaybolmaması için.

package/src/server/cache-panel.js

@@ -26,10 +26,18 @@
  */
 import crypto from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import express from "express";
+import * as log from "../log.mjs";
 import { FRAMEWORK_ROOT, getConfig } from "../config/index.js";
+import {
+  FRAMEWORK_HOMEPAGE,
+  FRAMEWORK_LICENSE,
+  FRAMEWORK_NODE_RANGE,
+  FRAMEWORK_VERSION,
+} from "../version.mjs";
 import { safeEqual } from "../http/cookies.js";
 import {
   clearHtmlCache,
@@ -44,8 +52,25 @@ import {
   getDataCacheEntries,
   getDataCacheSize,
 } from "./data-cache.js";
-import { getRedisStatus, redisDropMatching } from "./redis.js";
+import {
+  getRedisDetails,
+  getRedisStatus,
+  inspectRedis,
+  redisDropMatching,
+} from "./redis.js";
 import { getUpstreamLimiterStatus } from "./upstream-limiter.js";
+import {
+  clearCloudflareCacheReserve,
+  cloudflareConfigured,
+  fetchCacheAnalytics,
+  fetchCloudflareOverview,
+  fetchPathEdges,
+  getCloudflareStatus,
+  purgeCloudflare,
+  setCloudflareFeature,
+  setCloudflareSetting,
+  toCloudflareUrls,
+} from "./cloudflare.js";
 import { prewarm, prewarmProgress } from "./prewarm.js";
 
 /** Panel dosyaları framework paketinden servis edilir, uygulamadan değil. */
@@ -199,9 +224,9 @@ function notFound(res) {
  * göndermenin faydası yok.
  *
  * @param {string} query Anahtar filtresi (boş → filtre yok).
- * @returns {object}
+ * @returns {Promise<object>}
  */
-function snapshot(query) {
+async function snapshot(query) {
   const term = query.trim().toLowerCase();
   /** @param {{ key: string }} entry */
   const matches = (entry) => !term || entry.key.toLowerCase().includes(term);
@@ -216,6 +241,13 @@ function snapshot(query) {
   return {
     boot: BOOT_ID,
     generatedAt: Date.now(),
+    release: {
+      version: FRAMEWORK_VERSION,
+      license: FRAMEWORK_LICENSE,
+      node: FRAMEWORK_NODE_RANGE,
+      homepage: FRAMEWORK_HOMEPAGE,
+    },
+    host: await hostStatus(),
     process: {
       pid: process.pid,
       node: process.version,
@@ -231,7 +263,14 @@ function snapshot(query) {
       matched: htmlMatched.length,
       entries: htmlMatched
         .sort((a, b) => b.bytes - a.bytes)
-        .slice(0, MAX_LISTED),
+        .slice(0, MAX_LISTED)
+        // Anahtar `yol?query`; query boşken sonda yalnız bir `?` kalıyor.
+        // Silme işlemleri gerçek anahtarı kullanmaya devam eder, panel
+        // ziyaret edilebilir yolu gösterir.
+        .map((entry) => ({
+          ...entry,
+          url: entry.key.endsWith("?") ? entry.key.slice(0, -1) : entry.key,
+        })),
     },
     data: {
       size: getDataCacheSize(),
@@ -242,12 +281,60 @@ function snapshot(query) {
         .sort((a, b) => a.expiresIn - b.expiresIn)
         .slice(0, MAX_LISTED),
     },
-    redis: getRedisStatus(),
+    redis: { ...getRedisStatus(), ...getRedisDetails() },
+    // Cloudflare yalnızca kurulum özeti: zone bilgisi ve analitik ağa çıkıyor
+    // ve döküm birkaç saniyede bir yenileniyor. Ayrıntı ayrı uçta.
+    cloudflare: getCloudflareStatus(),
     upstream: getUpstreamLimiterStatus(),
     prewarm: { ...prewarmProgress },
   };
 }
 
+/**
+ * Makinenin RAM ve disk durumu.
+ *
+ * Paylaşımlı kademe kapalıyken önbelleğin tamamı bu sürecin belleğinde
+ * yaşıyor ve `maxEntries` ile RAM arasındaki ilişki panelde görünmediği sürece
+ * ayarlanamıyor: "500 girdi çok mu" sorusunun cevabı makinede ne kadar boş
+ * bellek kaldığına bağlı. Disk, HTML önbelleğinin kendisi için değil, ısıtma
+ * ve build çıktısının yaşadığı yer için: dolu bir diskte `jskelet build`
+ * sessizce hatalı manifest bırakıyor.
+ *
+ * `statfs` desteklenmeyen bir platform ya da erişilemeyen bir yol sadece
+ * `null` disk demek; panel yine açılır.
+ *
+ * @returns {Promise<object>}
+ */
+async function hostStatus() {
+  const total = os.totalmem();
+  const free = os.freemem();
+
+  /** @type {{ path: string, total: number, free: number } | null} */
+  let disk = null;
+
+  try {
+    const root = getConfig().root;
+    const stats = await fs.promises.statfs(root);
+    disk = {
+      path: root,
+      total: stats.blocks * stats.bsize,
+      // `bavail`, `bfree` değil: ayrılmış blokları boş göstermek yanıltıcı.
+      free: stats.bavail * stats.bsize,
+    };
+  } catch {
+    disk = null;
+  }
+
+  return {
+    platform: `${os.platform()} ${os.arch()}`,
+    cpus: os.cpus().length,
+    // Windows'ta `loadavg()` her zaman sıfır döner; panel bunu gizler.
+    load: os.loadavg()[0],
+    memory: { total, free, used: total - free },
+    disk,
+  };
+}
+
 /* --------------------------------------------------------------- aksiyonlar */
 
 /**
@@ -316,6 +403,20 @@ async function runAction(body, req) {
       };
     }
 
+    case "redis:inspect": {
+      const result = await inspectRedis();
+      if (!result.ok) return { ok: false, message: "Redis is not reachable" };
+
+      const parts = [
+        `${result.html} html keys`,
+        `${result.data} data keys`,
+        result.totalKeys !== null ? `${result.totalKeys} keys in db` : null,
+        result.usedMemory ? `${result.usedMemory} used` : null,
+      ].filter(Boolean);
+
+      return { ok: true, message: parts.join(" · ") };
+    }
+
     case "redis:drop": {
       const kind = body.kind === "data" ? "data" : "html";
       const status = getRedisStatus();
@@ -327,6 +428,93 @@ async function runAction(body, req) {
       return { ok: true, message: `${dropped} shared ${kind} keys dropped` };
     }
 
+    /* ------------------------------------------------------- cloudflare */
+
+    case "cf:purge-everything": {
+      const result = await purgeCloudflare({ everything: true });
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? "Cloudflare cache purged (everything)"
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
+    case "cf:purge-urls": {
+      // Panelin elindeki HTML anahtarları yol; Cloudflare tam URL istiyor.
+      // Origin, isteğin geldiği host'tan türetilir ki tek zone'lu kurulumda
+      // ayrıca ayar gerekmesin.
+      const paths = Array.isArray(body.paths) ? body.paths.map(String) : [];
+      if (!paths.length) return { ok: false, message: "No paths given" };
+
+      const urls = toCloudflareUrls(paths, originOf(req));
+      if (!urls.length) {
+        return {
+          ok: false,
+          message: "Could not build absolute URLs — set cache().cloudflare.hostname",
+        };
+      }
+
+      const result = await purgeCloudflare({ files: urls });
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? `Purged ${result.purged} URLs at Cloudflare in ${result.batches} request(s)`
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
+    case "cf:purge-keys": {
+      /** @type {"prefixes" | "hosts" | "tags"} */
+      const kind =
+        body.kind === "hosts" ? "hosts" : body.kind === "tags" ? "tags" : "prefixes";
+
+      const values = String(body.values ?? "")
+        .split(/[\s,]+/)
+        .filter(Boolean);
+
+      if (!values.length) return { ok: false, message: "Nothing to purge" };
+
+      const result = await purgeCloudflare({ [kind]: values });
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? `Purged ${result.purged} ${kind} at Cloudflare`
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
+    case "cf:setting": {
+      const result = await setCloudflareSetting(body.id, body.value);
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? `Cloudflare ${body.id} is now ${result.value}`
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
+    case "cf:feature": {
+      const value = body.value === "on" ? "on" : "off";
+      const result = await setCloudflareFeature(body.feature, value);
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? `Cloudflare ${body.feature} turned ${value}`
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
+    case "cf:clear-reserve": {
+      const result = await clearCloudflareCacheReserve();
+      return {
+        ok: result.ok,
+        message: result.ok
+          ? "Cache Reserve clear started — it runs asynchronously at Cloudflare"
+          : `Cloudflare: ${result.error}`,
+      };
+    }
+
     case "prewarm": {
       if (prewarmProgress.active) {
         return { ok: false, message: "A prewarm round is already running" };
@@ -396,13 +584,18 @@ function router() {
     sendFile(res, authenticated(req) ? "panel.html" : "login.html");
   });
 
-  // Stil giriş sayfasında da gerekiyor, yani oturumdan önce servis edilir.
-  // İçinde durum bilgisi yok.
+  // Stil ve logo giriş sayfasında da gerekiyor, yani oturumdan önce servis
+  // edilir. İkisinde de durum bilgisi yok.
   api.get("/panel.css", (req, res) => {
     res.type("text/css");
     sendFile(res, "panel.css");
   });
 
+  api.get("/logo.png", (req, res) => {
+    res.type("image/png");
+    fs.createReadStream(path.join(FRAMEWORK_ROOT, "src", "logo.png")).pipe(res);
+  });
+
   api.post("/login", express.json({ limit: "4kb" }), (req, res) => {
     const password = typeof req.body?.password === "string" ? req.body.password : "";
 
@@ -457,9 +650,29 @@ function router() {
     sendFile(res, "panel.js");
   });
 
-  api.get("/data", (req, res) => {
+  api.get("/data", async (req, res) => {
     const query = typeof req.query.q === "string" ? req.query.q : "";
-    res.json(snapshot(query));
+    res.json(await snapshot(query));
+  });
+
+  // Cloudflare ayrı uçlarda: her ikisi de ağa çıkıyor ve döküm turuna
+  // bağlanırlarsa panel Cloudflare'in gecikmesi kadar yavaşlar.
+  api.get("/cloudflare", async (req, res) => {
+    res.json(await fetchCloudflareOverview({ force: req.query.force === "1" }));
+  });
+
+  api.post("/cloudflare/analytics", express.json({ limit: "8kb" }), async (req, res) => {
+    if (!cloudflareConfigured()) {
+      res.json({ ok: false, error: "not configured" });
+      return;
+    }
+
+    const hours = Number(req.body?.hours) || undefined;
+    const path = typeof req.body?.path === "string" ? req.body.path.trim() : "";
+
+    // Yol verildiyse soru "bu sayfa hangi edge'lerden servis edildi", yoksa
+    // "zone genelinde cache oranı ne".
+    res.json(path ? await fetchPathEdges({ path, hours }) : await fetchCacheAnalytics({ hours }));
   });
 
   api.post("/action", express.json({ limit: "64kb" }), async (req, res) => {
@@ -479,6 +692,18 @@ function router() {
   return api;
 }
 
+/**
+ * Purge URL'lerinin kökü. `cloudflare.hostname` verilmediğinde panelin
+ * açıldığı origin kullanılır: tek zone'lu bir kurulumda ikisi zaten aynı.
+ *
+ * @param {import('express').Request} req
+ * @returns {string | undefined}
+ */
+function originOf(req) {
+  const host = req.get("host");
+  return host ? `${req.protocol}://${host}` : undefined;
+}
+
 /**
  * @param {import('express').Response} res
  * @param {string} name
@@ -497,9 +722,17 @@ export function mountCachePanel(app) {
 
   app.use(settings.basePath, router());
 
+  // Şifre akışın içinde tek bir satır olarak kaybolmamalı: kullanıcı onu bir
+  // kez görüyor ve her restart'ta değişiyor.
   const port = process.env.PORT ?? 3000;
-  console.log(
-    `[cache-panel] http://localhost:${port}${settings.basePath} — ` +
-      `password for this run: ${PASSWORD}`,
-  );
+  log.box({
+    title: "CACHE PANEL",
+    lines: [
+      `http://localhost:${port}${settings.basePath}`,
+      "",
+      `password  ${PASSWORD}`,
+      "",
+      "Valid until this process restarts.",
+    ],
+  });
 }