jskelet 0.2.4 → 0.3.0

package/src/server/admin/inventory.js

@@ -0,0 +1,188 @@
+/**
+ * Route ve view envanteri — admin paneline salt okunur döküm.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getConfig } from "../../config/index.js";
+import { list as listLogs } from "./event-log.js";
+
+/**
+ * Express router stack'ini dolaşır. İç API kırılgan; yalnızca gözlem için.
+ *
+ * @param {import('express').Express} app
+ * @returns {{ method: string, path: string }[]}
+ */
+export function listExpressRoutes(app) {
+  /** @type {{ method: string, path: string }[]} */
+  const out = [];
+  const stack = /** @type {any} */ (app)?._router?.stack;
+  if (!Array.isArray(stack)) return out;
+
+  /**
+   * @param {any[]} layers
+   * @param {string} prefix
+   */
+  function walk(layers, prefix) {
+    for (const layer of layers) {
+      if (layer.route) {
+        const routePath = joinPath(prefix, layer.route.path);
+        const methods = Object.keys(layer.route.methods || {}).filter(
+          (name) => layer.route.methods[name],
+        );
+        for (const method of methods) {
+          out.push({ method: method.toUpperCase(), path: routePath });
+        }
+        continue;
+      }
+
+      if (layer.name === "router" && layer.handle?.stack) {
+        const mount = layer.regexp ? regexpToPrefix(layer.regexp) : "";
+        walk(layer.handle.stack, joinPath(prefix, mount));
+      }
+    }
+  }
+
+  walk(stack, "");
+  return out.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {string}
+ */
+function joinPath(a, b) {
+  if (!a) return b || "/";
+  if (!b || b === "/") return a || "/";
+  return `${a.replace(/\/+$/, "")}/${String(b).replace(/^\/+/, "")}`;
+}
+
+/**
+ * Express mount regexp → okunabilir önek. Tam doğruluk şart değil.
+ *
+ * @param {RegExp} regexp
+ * @returns {string}
+ */
+function regexpToPrefix(regexp) {
+  const source = regexp.source
+    .replace("^\\/", "/")
+    .replace("\\/?(?=\\/|$)", "")
+    .replace(/\$$/, "")
+    .replace(/\\\//g, "/")
+    .replace(/\(\?:\(\?=.*$/, "");
+  if (!source.startsWith("/")) return "";
+  const cleaned = source.replace(/[^a-zA-Z0-9/_\-.:*]/g, "");
+  return cleaned || "";
+}
+
+/**
+ * `routes/` altındaki (veya config.routes listesindeki) modül dosyaları.
+ *
+ * @returns {{ file: string, relative: string }[]}
+ */
+export function listRouteModules() {
+  const config = getConfig();
+  const root = config.root;
+
+  const files = config.routes
+    ? config.routes.map((entry) => path.resolve(root, entry))
+    : discover(config.dirs.routes);
+
+  return files.map((file) => ({
+    file,
+    relative: path.relative(root, file).replaceAll("\\", "/"),
+  }));
+}
+
+/**
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function discover(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      discover(full, out);
+      continue;
+    }
+    if (!/\.(js|mjs)$/.test(entry.name)) continue;
+    if (entry.name.startsWith("_")) continue;
+    out.push(full);
+  }
+
+  return out;
+}
+
+/**
+ * `views/` altındaki şablon ve bileşen dosyaları.
+ *
+ * @returns {{ relative: string, kind: "ejs" | "js" | "other" }[]}
+ */
+export function listViews() {
+  const config = getConfig();
+  const root = config.dirs.views;
+  /** @type {{ relative: string, kind: "ejs" | "js" | "other" }[]} */
+  const out = [];
+
+  /**
+   * @param {string} dir
+   */
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      const relative = path.relative(root, full).replaceAll("\\", "/");
+      const kind = entry.name.endsWith(".ejs")
+        ? "ejs"
+        : /\.(js|mjs)$/.test(entry.name)
+          ? "js"
+          : "other";
+      out.push({ relative, kind });
+    }
+  }
+
+  walk(root);
+  return out;
+}
+
+/**
+ * Son HTTP log'larından path başına özet.
+ *
+ * @returns {Record<string, { status: number, ms: number, cache: string | null, at: number, count: number }>}
+ */
+export function routeActivity() {
+  /** @type {Record<string, { status: number, ms: number, cache: string | null, at: number, count: number }>} */
+  const byPath = {};
+
+  for (const entry of listLogs(0, 500)) {
+    if (entry.kind !== "http") continue;
+    const key = typeof entry.route === "string" && entry.route
+      ? entry.route
+      : String(entry.path ?? entry.url ?? "");
+    if (!key) continue;
+
+    const prev = byPath[key];
+    byPath[key] = {
+      status: Number(entry.status) || 0,
+      ms: Number(entry.ms) || 0,
+      cache: /** @type {string | null} */ (entry.cache ?? null),
+      at: entry.at,
+      count: (prev?.count ?? 0) + 1,
+    };
+  }
+
+  return byPath;
+}

package/src/server/admin/mount.js

@@ -0,0 +1,56 @@
+/**
+ * Framework yönetim paneli (`/_jskelet/admin`).
+ *
+ * Dev overlay'den ayrı: `NODE_ENV`'e bakmaz, yalnızca `admin().enabled` /
+ * `JSKELET_ADMIN` ile açılır. Kapalıyken modül yüklenmez ve yol yoktur.
+ *
+ * Şifre süreç başlangıcında üretilir ve log kutusunda bir kez basılır.
+ */
+import process from "node:process";
+import * as log from "../../log.mjs";
+import { getConfig } from "../../config/index.js";
+import { PASSWORD } from "./auth.js";
+import { createAdminRouter } from "./router.js";
+import { configureEventLog, requestLogMiddleware } from "./event-log.js";
+
+/** @type {typeof import('../../config/defaults.js').DEFAULT_ADMIN} */
+let settings;
+
+/**
+ * @returns {typeof import('../../config/defaults.js').DEFAULT_ADMIN}
+ */
+function getSettings() {
+  return settings;
+}
+
+/**
+ * Paneli uygulamaya bağlar, istek log middleware'ini kurar ve şifreyi loglar.
+ *
+ * @param {import('express').Express} app
+ */
+export function mountAdmin(app) {
+  settings = getConfig().admin;
+
+  configureEventLog({
+    basePath: settings.basePath,
+    logSize: settings.logSize,
+    prewarmUserAgent: String(getConfig().brand.prewarmUserAgent ?? ""),
+  });
+
+  app.use(settings.basePath, createAdminRouter(getSettings, app));
+  // Route'lardan önce mount edilir; `finish` anında Express `req.route`
+  // doldurmuş olur. Admin yolları ring'e yazılmaz.
+  app.use(requestLogMiddleware());
+
+  const port = process.env.PORT ?? 3000;
+  log.box({
+    title: "ADMIN",
+    lines: [
+      `http://localhost:${port}${settings.basePath}`,
+      "",
+      `password  ${PASSWORD}`,
+      "",
+      "Valid until this process restarts.",
+    ],
+  });
+}

package/src/server/admin/router.js

@@ -0,0 +1,216 @@
+/**
+ * Admin paneli Express router'ı.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import express from "express";
+import { FRAMEWORK_ROOT } from "../../config/index.js";
+import {
+  ACTION_HEADER,
+  authenticated,
+  clearSessionCookie,
+  createSession,
+  destroySession,
+  passwordMatches,
+  sessionCookie,
+} from "./auth.js";
+import { clearOffender, gateMiddleware, noteFailure } from "./gate.js";
+import { snapshot } from "./snapshot.js";
+import { runAction } from "./actions.js";
+import {
+  list as listLogs,
+  subscribeLive,
+} from "./event-log.js";
+import {
+  listExpressRoutes,
+  listRouteModules,
+  listViews,
+  routeActivity,
+} from "./inventory.js";
+import {
+  cloudflareConfigured,
+  fetchCacheAnalytics,
+  fetchCloudflareOverview,
+  fetchPathEdges,
+} from "../cloudflare.js";
+
+const PANEL_DIR = path.join(FRAMEWORK_ROOT, "src", "client", "admin");
+
+/**
+ * @param {() => typeof import('../../config/defaults.js').DEFAULT_ADMIN} getSettings
+ * @param {import('express').Express} app
+ * @returns {import('express').Router}
+ */
+export function createAdminRouter(getSettings, app) {
+  const api = express.Router();
+
+  api.use((req, res, next) => {
+    res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
+    res.setHeader("X-Robots-Tag", "noindex, nofollow, noarchive, nosnippet");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    next();
+  });
+
+  api.use(gateMiddleware(getSettings));
+
+  // Soft page routes → aynı shell (client path ile sekme seçer).
+  // JSON API'ler ayrı `/api/*` altında: `/logs` hem sayfa hem döküm olamaz.
+  const shellPages = ["/", "/cache", "/routes", "/views", "/logs", "/system"];
+  for (const page of shellPages) {
+    api.get(page, (req, res) => {
+      const settings = getSettings();
+      const bare = req.originalUrl.split("?")[0];
+      if (page === "/" && !bare.endsWith("/")) {
+        res.redirect(302, `${settings.basePath}/`);
+        return;
+      }
+
+      res.type("html");
+      sendFile(res, authenticated(req) ? "panel.html" : "login.html");
+    });
+  }
+
+  api.get("/panel.css", (req, res) => {
+    res.type("text/css");
+    sendFile(res, "panel.css");
+  });
+
+  api.get("/i18n.js", (req, res) => {
+    res.type("application/javascript");
+    sendFile(res, "i18n.js");
+  });
+
+  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 settings = getSettings();
+    const password = typeof req.body?.password === "string" ? req.body.password : "";
+
+    if (!passwordMatches(password)) {
+      noteFailure(req, password ? "wrong password" : "empty password", settings);
+      res.status(401).json({ ok: false, message: "Invalid password" });
+      return;
+    }
+
+    const { token, maxAge } = createSession(settings.sessionHours);
+    clearOffender(req);
+    res.setHeader("Set-Cookie", sessionCookie(settings.basePath, token, maxAge));
+    res.json({ ok: true });
+  });
+
+  api.use((req, res, next) => {
+    if (authenticated(req)) return next();
+
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      noteFailure(req, `unauthenticated ${req.method} ${req.path}`, getSettings());
+    }
+
+    res.status(404).type("text/plain").send("Not Found");
+  });
+
+  api.post("/logout", (req, res) => {
+    const settings = getSettings();
+    destroySession(req);
+    res.setHeader("Set-Cookie", clearSessionCookie(settings.basePath));
+    res.json({ ok: true });
+  });
+
+  api.get("/panel.js", (req, res) => {
+    res.type("application/javascript");
+    sendFile(res, "panel.js");
+  });
+
+  api.get("/data", async (req, res) => {
+    const query = typeof req.query.q === "string" ? req.query.q : "";
+    res.json(await snapshot(query));
+  });
+
+  api.get("/api/routes", (req, res) => {
+    res.json({
+      routes: listExpressRoutes(app),
+      modules: listRouteModules(),
+      activity: routeActivity(),
+    });
+  });
+
+  api.get("/api/views", (req, res) => {
+    res.json({ views: listViews() });
+  });
+
+  api.get("/api/logs", (req, res) => {
+    const after = Number(req.query.after) || 0;
+    const limit = Number(req.query.limit) || 200;
+    res.json({ entries: listLogs(after, limit) });
+  });
+
+  api.get("/api/logs/stream", (req, res) => {
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-store, no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.flushHeaders?.();
+
+    const replay = listLogs(0, 100);
+    for (const entry of replay) {
+      res.write(`data: ${JSON.stringify(entry)}\n\n`);
+    }
+
+    const unsubscribe = subscribeLive((entry) => {
+      res.write(`data: ${JSON.stringify(entry)}\n\n`);
+    });
+
+    const heartbeat = setInterval(() => {
+      res.write(": ping\n\n");
+    }, 15000);
+
+    req.on("close", () => {
+      clearInterval(heartbeat);
+      unsubscribe();
+    });
+  });
+
+  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 pathValue = typeof req.body?.path === "string" ? req.body.path.trim() : "";
+    res.json(
+      pathValue
+        ? await fetchPathEdges({ path: pathValue, hours })
+        : await fetchCacheAnalytics({ hours }),
+    );
+  });
+
+  api.post("/action", express.json({ limit: "64kb" }), async (req, res) => {
+    if (req.get(ACTION_HEADER) !== "1") {
+      res.status(404).type("text/plain").send("Not Found");
+      return;
+    }
+
+    try {
+      res.json(await runAction(req.body ?? {}, req));
+    } catch (error) {
+      console.error("[admin] action failed", error);
+      res.status(500).json({ ok: false, message: "Action failed, see server logs" });
+    }
+  });
+
+  return api;
+}
+
+/**
+ * @param {import('express').Response} res
+ * @param {string} name
+ */
+function sendFile(res, name) {
+  fs.createReadStream(path.join(PANEL_DIR, name)).pipe(res);
+}

package/src/server/admin/snapshot.js

@@ -0,0 +1,126 @@
+/**
+ * Admin paneli cache / host / process dökümü.
+ *
+ * HTML gövdesi ve veri değerleri dönmez — yalnızca meta.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import process from "node:process";
+import { getConfig } from "../../config/index.js";
+import {
+  FRAMEWORK_HOMEPAGE,
+  FRAMEWORK_LICENSE,
+  FRAMEWORK_NODE_RANGE,
+  FRAMEWORK_VERSION,
+} from "../../version.mjs";
+import {
+  getHtmlCacheEntries,
+  getHtmlCacheSize,
+} from "../html-cache.js";
+import {
+  getDataCacheEntries,
+  getDataCacheSize,
+} from "../data-cache.js";
+import { getRedisDetails, getRedisStatus } from "../redis.js";
+import { getUpstreamLimiterStatus } from "../upstream-limiter.js";
+import { getCloudflareStatus } from "../cloudflare.js";
+import { prewarmProgress } from "../prewarm.js";
+
+/** Listelerin üst sınırı: veri önbelleğinde on binlerce anahtar olabiliyor. */
+const MAX_LISTED = 500;
+
+export const BOOT_ID = `${Date.now()}-${process.pid}`;
+
+/**
+ * @param {string} query Anahtar filtresi (boş → filtre yok).
+ * @returns {Promise<object>}
+ */
+export async function snapshot(query) {
+  const term = query.trim().toLowerCase();
+  /** @param {{ key: string }} entry */
+  const matches = (entry) => !term || entry.key.toLowerCase().includes(term);
+
+  const html = getHtmlCacheEntries();
+  const data = getDataCacheEntries();
+
+  const htmlMatched = html.filter(matches);
+  const dataMatched = data.filter(matches);
+  const usage = process.memoryUsage();
+
+  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,
+      uptime: process.uptime(),
+      env: process.env.NODE_ENV ?? "production",
+      memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+    },
+    html: {
+      size: getHtmlCacheSize(),
+      maxEntries: getConfig().htmlMaxEntries,
+      bytes: html.reduce((total, entry) => total + entry.bytes, 0),
+      stale: html.filter((entry) => entry.stale).length,
+      matched: htmlMatched.length,
+      entries: htmlMatched
+        .sort((a, b) => b.bytes - a.bytes)
+        .slice(0, MAX_LISTED)
+        .map((entry) => ({
+          ...entry,
+          url: entry.key.endsWith("?") ? entry.key.slice(0, -1) : entry.key,
+        })),
+    },
+    data: {
+      size: getDataCacheSize(),
+      maxEntries: Number(getConfig().data?.maxEntries) || 0,
+      stale: data.filter((entry) => entry.stale).length,
+      matched: dataMatched.length,
+      entries: dataMatched
+        .sort((a, b) => a.expiresIn - b.expiresIn)
+        .slice(0, MAX_LISTED),
+    },
+    redis: { ...getRedisStatus(), ...getRedisDetails() },
+    cloudflare: getCloudflareStatus(),
+    upstream: getUpstreamLimiterStatus(),
+    prewarm: { ...prewarmProgress },
+  };
+}
+
+/**
+ * @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,
+      free: stats.bavail * stats.bsize,
+    };
+  } catch {
+    disk = null;
+  }
+
+  return {
+    platform: `${os.platform()} ${os.arch()}`,
+    cpus: os.cpus().length,
+    load: os.loadavg()[0],
+    memory: { total, free, used: total - free },
+    disk,
+  };
+}

package/src/server/cloudflare.js

@@ -306,11 +306,20 @@ async function graphql(query, variables) {
 }
 
 /**
+ * GraphQL analitik penceresinin iki ucu. Yalnızca `datetime_geq` gönderilirse
+ * Cloudflare üst sınırı sorguyu işlediği ana koyuyor; Free zone'larda tavan
+ * tam 1 gün ve ağ gecikmesi `1d179ms…` gibi bir taşma üretip reddediyor.
+ * İki uç aynı `Date.now()`'dan hesaplanınca pencere tam N saat kalır.
+ *
  * @param {number} hours
- * @returns {string} ISO zaman damgası
+ * @returns {{ since: string, until: string }}
  */
-function since(hours) {
-  return new Date(Date.now() - hours * 3600_000).toISOString();
+function timeWindow(hours) {
+  const untilMs = Date.now();
+  return {
+    since: new Date(untilMs - hours * 3600_000).toISOString(),
+    until: new Date(untilMs).toISOString(),
+  };
 }
 
 /**
@@ -330,13 +339,14 @@ function since(hours) {
 export async function fetchCacheAnalytics(options = {}) {
   const config = settings();
   const hours = Math.max(1, Math.min(72, options.hours ?? config.analyticsHours));
+  const { since, until } = timeWindow(hours);
 
   const query = `
-    query CacheStatus($zone: String!, $since: Time!) {
+    query CacheStatus($zone: String!, $since: Time!, $until: Time!) {
       viewer {
         zones(filter: { zoneTag: $zone }) {
           httpRequestsAdaptiveGroups(
-            filter: { datetime_geq: $since }
+            filter: { datetime_geq: $since, datetime_leq: $until }
             limit: 50
             orderBy: [count_DESC]
           ) {
@@ -348,7 +358,7 @@ export async function fetchCacheAnalytics(options = {}) {
       }
     }`;
 
-  const response = await graphql(query, { zone: config.zoneId, since: since(hours) });
+  const response = await graphql(query, { zone: config.zoneId, since, until });
   if (!response.ok) return { ok: false, hours, sampled: true, rows: [], error: response.error };
 
   const groups = response.data?.viewer?.zones?.[0]?.httpRequestsAdaptiveGroups ?? [];
@@ -381,13 +391,14 @@ export async function fetchCacheAnalytics(options = {}) {
 export async function fetchPathEdges({ path, hours }) {
   const config = settings();
   const window = Math.max(1, Math.min(72, hours ?? config.analyticsHours));
+  const { since, until } = timeWindow(window);
 
   const query = `
-    query PathEdges($zone: String!, $since: Time!, $path: String!) {
+    query PathEdges($zone: String!, $since: Time!, $until: Time!, $path: String!) {
       viewer {
         zones(filter: { zoneTag: $zone }) {
           httpRequestsAdaptiveGroups(
-            filter: { datetime_geq: $since, clientRequestPath: $path }
+            filter: { datetime_geq: $since, datetime_leq: $until, clientRequestPath: $path }
             limit: 500
             orderBy: [count_DESC]
           ) {
@@ -400,7 +411,8 @@ export async function fetchPathEdges({ path, hours }) {
 
   const response = await graphql(query, {
     zone: config.zoneId,
-    since: since(window),
+    since,
+    until,
     path,
   });