jskelet 0.2.0 → 0.2.2

package/src/config/defaults.js

@@ -120,6 +120,42 @@ export const DEFAULT_DATA_CACHE = {
   staleFactor: 10,
 };
 
+/**
+ * Upstream API'ye giden isteklerin host başına hız freni.
+ *
+ * Varsayılan **kapalı** (`rate: 0`): fren, kotasını bilen bir uygulamanın
+ * bilinçli kararı. Açıldığında `rate` bir tavan olur ve gerçek hız 429
+ * cevaplarına göre kendini aşağı çeker (bkz. `src/server/upstream-limiter.js`).
+ *
+ * `hosts` ile tek tek uçlar ayrılabilir; API'lerin kotası aynı olmak zorunda
+ * değil:
+ *
+ *   upstream: { rate: 10, hosts: { "api.example.com": { rate: 3 } } }
+ */
+export const DEFAULT_UPSTREAM_LIMIT = {
+  /** Saniyedeki en fazla çağrı. 0 → fren tamamen kapalı. */
+  rate: 0,
+  /** Kova boyu; verilmezse bir saniyelik bütçe kadar patlamaya izin verilir. */
+  burst: 0,
+  /** Aynı anda uçabilecek çağrı. Ortalama hızdan bağımsız: anlık baskıyı bağlar. */
+  concurrency: 8,
+  /** Azalmanın dibi: hız buranın altına inmez, yoksa site tamamen durur. */
+  minRate: 0.5,
+  /** Toplamsal artışın adımı (çağrı/saniye) ve periyodu. */
+  increaseStep: 1,
+  increaseIntervalMs: 5000,
+  /**
+   * İki azalma arasındaki en kısa süre. Aynı anda uçan on çağrının hepsi 429
+   * dönerse hız on kez yarılanıp dibe vurmasın.
+   */
+  decreaseIntervalMs: 1000,
+  /** Devre kesici: art arda kaç 429'dan sonra host'a hiç gidilmeyeceği. */
+  breakerFailures: 5,
+  breakerCooldownMs: 10_000,
+  /** @type {Record<string, Record<string, number>>} */
+  hosts: {},
+};
+
 /**
  * Opsiyonel Redis ikinci kademesi (L2).
  *
@@ -155,8 +191,37 @@ export const DEFAULT_REDIS = {
   commandTimeoutMs: 200,
 };
 
+/**
+ * Önbellek yönetim paneli.
+ *
+ * `enabled` varsayılan olarak **kapalı** ve ortama bakmaz: panel açıldığında
+ * production'da da çalışır, ama açılması bilinçli bir karar olmalı. Kapalıyken
+ * router hiç mount edilmez — yolun kendisi de yok, yani 404 dönen bir uç bile
+ * ortaya çıkmaz.
+ *
+ * Şifre her süreç başlangıcında yeniden üretilir (bkz.
+ * `src/server/cache-panel.js`): panelin ömrü sürecin ömrü kadardır ve bir
+ * deploy eski erişimi otomatik olarak iptal eder. Bu yüzden config'te şifre
+ * alanı yok.
+ */
+export const DEFAULT_CACHE_PANEL = {
+  enabled: false,
+  basePath: "/_jskelet/cache",
+  /** Kaç başarısız denemeden sonra IP yasaklanır. */
+  banAttempts: 3,
+  /** Yasağın süresi. */
+  banHours: 24,
+  /** Oturumun ömrü; süreç yeniden başladığında zaten sıfırlanır. */
+  sessionHours: 12,
+};
+
 /** Oturuma bağlı sayfalar ısıtılmaz; uygulama kendi listesini verebilir. */
-export const DEFAULT_PREWARM_SKIP = ["/api/", "/_fragment/", "/__jskelet/"];
+export const DEFAULT_PREWARM_SKIP = [
+  "/api/",
+  "/_fragment/",
+  "/__jskelet/",
+  "/_jskelet/",
+];
 
 /**
  * Site içi gezinme ipuçları (Speculation Rules + view transition).
@@ -182,7 +247,7 @@ export const DEFAULT_NAVIGATION = {
  * hedefi olmayan uçların spekülatif istekle tetiklenmesi gerçek bir hata
  * kaynağı; uygulama kendi listesini `navigation.exclude` ile ekler.
  */
-export const DEFAULT_NAVIGATION_EXCLUDE = ["/api/*", "/_fragment/*"];
+export const DEFAULT_NAVIGATION_EXCLUDE = ["/api/*", "/_fragment/*", "/_jskelet/*"];
 
 /**
  * Güvenlik ayarları.

package/src/config/index.js

@@ -16,7 +16,8 @@
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
  *   cache()     → { html?: { [source]: saniye }, maxEntries?: number,
- *                   data?: {...}, redis?: {...}, prewarm?: {...} }
+ *                   data?: {...}, redis?: {...}, prewarm?: {...},
+ *                   panel?: {...} }
  *
  * Fonksiyon olmayan bölümler (`brand`, `security`, `static`, `navigation`…)
  * düz nesne olarak okunur.
@@ -28,6 +29,7 @@ import { pathToFileURL } from "node:url";
 import { compilePattern, matchPattern } from "./pattern.js";
 import {
   DEFAULT_BRAND,
+  DEFAULT_CACHE_PANEL,
   DEFAULT_DATA_CACHE,
   DEFAULT_DEV_GATE_BYPASS,
   DEFAULT_DIRS,
@@ -40,6 +42,7 @@ import {
   DEFAULT_SECURITY,
   DEFAULT_STATIC,
   DEFAULT_TRANSIENT_RETRY,
+  DEFAULT_UPSTREAM_LIMIT,
 } from "./defaults.js";
 
 /** Framework paketinin kökü — kendi şablonlarına ve varlıklarına erişir. */
@@ -87,6 +90,8 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {boolean} trackDependencies Render'ın okuduğu veri anahtarları kaydedilsin mi.
  * @property {{ attempts: number, delayMs: number }} transientRetry
  * @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 {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
  * @property {Record<string, unknown>} brand
@@ -249,6 +254,90 @@ function normalizeRedis(raw) {
   };
 }
 
+/**
+ * Upstream hız freni. Sayısal alanlar tipine zorlanır; bozuk bir değer freni
+ * yanlış ayarlamak yerine varsayılana döner.
+ *
+ * @param {unknown} raw
+ * @returns {typeof DEFAULT_UPSTREAM_LIMIT}
+ */
+function normalizeUpstream(raw) {
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const merged = { ...DEFAULT_UPSTREAM_LIMIT, ...source };
+
+  /** @param {string} key */
+  const positive = (key) => {
+    const value = Number(merged[key]);
+    return Number.isFinite(value) && value >= 0
+      ? value
+      : /** @type {any} */ (DEFAULT_UPSTREAM_LIMIT)[key];
+  };
+
+  /** @type {Record<string, Record<string, number>>} */
+  const hosts = {};
+  for (const [host, override] of Object.entries(merged.hosts ?? {})) {
+    if (override && typeof override === "object") hosts[host] = override;
+  }
+
+  return {
+    ...merged,
+    rate: positive("rate"),
+    burst: positive("burst"),
+    concurrency: Math.max(1, Math.floor(positive("concurrency"))),
+    minRate: positive("minRate"),
+    increaseStep: positive("increaseStep"),
+    increaseIntervalMs: positive("increaseIntervalMs"),
+    decreaseIntervalMs: positive("decreaseIntervalMs"),
+    breakerFailures: Math.floor(positive("breakerFailures")),
+    breakerCooldownMs: positive("breakerCooldownMs"),
+    hosts,
+  };
+}
+
+/**
+ * Önbellek panelinin bölümü.
+ *
+ * `enabled` yalnızca açıkça `true` verildiğinde ya da `JSKELET_CACHE_PANEL`
+ * ortam değişkeni ayarlandığında açılır: paneli yanlışlıkla açmanın bedeli,
+ * önbelleği boşaltabilen bir ucu internete koymak.
+ *
+ * Ortam değişkeni config'in **üstünde** duruyor, çünkü paneli genelde bir
+ * arıza sırasında tek seferlik açmak isteniyor ve o an config dosyasını
+ * değiştirip yeniden dağıtmak istenmiyor. `JSKELET_CACHE_PANEL=0` aynı
+ * mantıkla config'te açık olan paneli kapatır.
+ *
+ * @param {unknown} raw
+ * @returns {typeof DEFAULT_CACHE_PANEL}
+ */
+function normalizeCachePanel(raw) {
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const env = process.env.JSKELET_CACHE_PANEL;
+
+  const basePath =
+    typeof source.basePath === "string" && source.basePath.startsWith("/")
+      ? source.basePath.replace(/\/+$/, "")
+      : DEFAULT_CACHE_PANEL.basePath;
+
+  /** @param {string} key @param {number} min */
+  const positive = (key, min) => {
+    const value = Number(source[key]);
+    return Number.isFinite(value) && value >= min
+      ? value
+      : /** @type {any} */ (DEFAULT_CACHE_PANEL)[key];
+  };
+
+  return {
+    enabled:
+      env === undefined
+        ? source.enabled === true
+        : env !== "0" && env !== "false" && env !== "",
+    basePath: basePath || DEFAULT_CACHE_PANEL.basePath,
+    banAttempts: Math.floor(positive("banAttempts", 1)),
+    banHours: positive("banHours", 0),
+    sessionHours: positive("sessionHours", 0),
+  };
+}
+
 /**
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
@@ -256,6 +345,8 @@ function normalizeRedis(raw) {
  *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
  *   redis: RedisConfig,
+ *   upstream: typeof DEFAULT_UPSTREAM_LIMIT,
+ *   cachePanel: typeof DEFAULT_CACHE_PANEL,
  *   prewarm: Record<string, unknown>,
  *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
  */
@@ -292,6 +383,8 @@ function normalizeCache(raw) {
         ? { attempts: 0, delayMs: 0 }
         : { ...DEFAULT_TRANSIENT_RETRY, ...(raw?.transientRetry ?? {}) },
     redis: normalizeRedis(raw?.redis),
+    upstream: normalizeUpstream(raw?.upstream),
+    cachePanel: normalizeCachePanel(raw?.panel),
     // Desenler derlenmiş hâlde ayrı alanda tutulur: `prewarm` sayısal
     // ayarların düz torbası olarak kalsın, her turda yeniden derlenmesin.
     prewarm,
@@ -510,6 +603,8 @@ export async function loadConfig(options = {}) {
     trackDependencies,
     transientRetry,
     redis,
+    upstream,
+    cachePanel,
     prewarm,
     prewarmPriority,
   } = normalizeCache(cache);
@@ -530,6 +625,8 @@ export async function loadConfig(options = {}) {
     trackDependencies,
     transientRetry,
     redis,
+    upstream,
+    cachePanel,
     prewarm,
     prewarmPriority,
     brand,

package/src/index.js

@@ -41,6 +41,7 @@ export { headHints } from "./server/head-hints.js";
 export { renderHeadMeta } from "./server/metadata.js";
 export {
   clearHtmlCache,
+  dropHtmlCacheKey,
   getHtmlCacheEntries,
   getHtmlCacheSize,
   invalidateHtmlCache,
@@ -49,13 +50,17 @@ export {
 export {
   clearDataCache,
   dataCache,
+  dropDataCacheKey,
   getDataCacheEntries,
   getDataCacheSize,
+  getDataCacheStats,
   withDataCache,
 } 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";
+// 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";
 export { createProxy } from "./server/middleware/upstream-proxy.js";
 export { getConfig, loadConfig } from "./config/index.js";