jskelet 0.3.0 → 0.3.2

package/src/server/admin/snapshot.js

@@ -2,9 +2,12 @@
  * Admin paneli cache / host / process dökümü.
  *
  * HTML gövdesi ve veri değerleri dönmez — yalnızca meta.
+ * System sayfasındaki çubuklar **bu sürecin** payını gösterir (makine
+ * toplamına oranla), host'un genel doluluğunu değil.
  */
 import fs from "node:fs";
 import os from "node:os";
+import path from "node:path";
 import process from "node:process";
 import { getConfig } from "../../config/index.js";
 import {
@@ -29,8 +32,25 @@ import { prewarmProgress } from "../prewarm.js";
 /** Listelerin üst sınırı: veri önbelleğinde on binlerce anahtar olabiliyor. */
 const MAX_LISTED = 500;
 
+/** Disk ölçümünde atlanan dizinler — node_modules her poll'da taranmasın. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  "coverage",
+  ".turbo",
+  ".next",
+]);
+
 export const BOOT_ID = `${Date.now()}-${process.pid}`;
 
+/** @type {{ usage: NodeJS.CpuUsage; at: number } | null} */
+let cpuSample = null;
+
+/** @type {{ at: number, bytes: number, root: string } | null} */
+let diskSample = null;
+
 /**
  * @param {string} query Anahtar filtresi (boş → filtre yok).
  * @returns {Promise<object>}
@@ -46,6 +66,9 @@ export async function snapshot(query) {
   const htmlMatched = html.filter(matches);
   const dataMatched = data.filter(matches);
   const usage = process.memoryUsage();
+  const host = await hostStatus();
+  const cpuPercent = sampleProcessCpu(host.cpus);
+  const appDiskBytes = await sampleAppDisk(getConfig().root);
 
   return {
     boot: BOOT_ID,
@@ -56,13 +79,17 @@ export async function snapshot(query) {
       node: FRAMEWORK_NODE_RANGE,
       homepage: FRAMEWORK_HOMEPAGE,
     },
-    host: await hostStatus(),
+    host,
     process: {
       pid: process.pid,
       node: process.version,
       uptime: process.uptime(),
       env: process.env.NODE_ENV ?? "production",
       memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+      /** 0–100: bu sürecin tüm çekirdek kapasitesine oranı. */
+      cpuPercent,
+      /** Proje kökünün (node_modules hariç) disk boyutu. */
+      diskBytes: appDiskBytes,
     },
     html: {
       size: getHtmlCacheSize(),
@@ -94,6 +121,94 @@ export async function snapshot(query) {
   };
 }
 
+/**
+ * İki örnek arasındaki `process.cpuUsage` farkından süreç CPU yüzdesi.
+ * İlk çağrıda örnek alınır ve 0 döner — panelin bir sonraki turunda anlamlı.
+ *
+ * @param {number} cores
+ * @returns {number}
+ */
+function sampleProcessCpu(cores) {
+  const now = Date.now();
+  const current = process.cpuUsage();
+
+  if (!cpuSample) {
+    cpuSample = { usage: current, at: now };
+    return 0;
+  }
+
+  const elapsedMs = now - cpuSample.at;
+  const delta = process.cpuUsage(cpuSample.usage);
+  cpuSample = { usage: current, at: now };
+
+  if (elapsedMs <= 0 || cores <= 0) return 0;
+
+  // user+system mikro-saniye → ms; duvar süresi × çekirdek = kapasite.
+  const cpuMs = (delta.user + delta.system) / 1000;
+  const capacityMs = elapsedMs * cores;
+  return Math.max(0, Math.min(100, (cpuMs / capacityMs) * 100));
+}
+
+/**
+ * Proje kökünün boyutu (ağır dizinler atlanır). 60 sn önbellek.
+ *
+ * @param {string} root
+ * @returns {Promise<number>}
+ */
+async function sampleAppDisk(root) {
+  if (diskSample && diskSample.root === root && Date.now() - diskSample.at < 60_000) {
+    return diskSample.bytes;
+  }
+
+  const bytes = await measureDir(root);
+  diskSample = { at: Date.now(), bytes, root };
+  return bytes;
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<number>}
+ */
+async function measureDir(dir) {
+  let total = 0;
+
+  /** @type {string[]} */
+  const stack = [dir];
+
+  while (stack.length) {
+    const current = stack.pop();
+    if (!current) continue;
+
+    let entries;
+    try {
+      entries = await fs.promises.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === "." || entry.name === "..") continue;
+      if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      try {
+        const stats = await fs.promises.stat(full);
+        total += stats.size;
+      } catch {
+        // silinmiş / erişilemeyen dosya
+      }
+    }
+  }
+
+  return total;
+}
+
 /**
  * @returns {Promise<object>}
  */

package/src/server/create-app.js

@@ -10,6 +10,8 @@
  *   3. headers → devGate → redirects → trailingSlash — gate'in 404'ü
  *      redirect'ten önce; trailingSlash config redirects'ten sonra, böylece
  *      açık kurallar istenen yolu önce görür.
+ *   3b. access log (açıksa) — tamamlanan yanıtların süresi; admin/prewarm
+ *      içeride elenir.
  *   4. staticPrecompressed → express.static — build'de üretilmiş `.br`/`.gz`
  *      kopyalar varsa onlar servis edilir (kalite 11), yoksa istek altındaki
  *      static'e düşer ve middleware anında sıkıştırır (kalite 5).
@@ -42,6 +44,7 @@ import { isPrewarmRequest, notePrewarmError, startPrewarm } from "./prewarm.js";
 import { trackUpstreamFetch } from "./upstream-tracking.js";
 import { configureUpstreamLimiter } from "./upstream-limiter.js";
 import { connectRedis, disconnectRedis } from "./redis.js";
+import { configureLogs, flushLogs, closeLogs } from "./logs/pipeline.js";
 import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
 
 /**
@@ -68,6 +71,10 @@ export async function createApp(options = {}) {
   // dokunmayan, tamamen opsiyonel bir adım.
   await connectRedis(config);
 
+  // Kalıcı log sink'leri (dosya / S3). Credential eksikse uyarı + no-op;
+  // site düşmez. Access middleware gerektiğinde biraz aşağıda mount edilir.
+  const { accessLog } = await configureLogs(config);
+
   const app = express();
 
   app.disable("x-powered-by");
@@ -90,6 +97,13 @@ export async function createApp(options = {}) {
   app.use(redirects());
   app.use(trailingSlash());
 
+  // Access log: headers/redirects sonrası, statikten önce — böylece
+  // tamamlanan her yanıt (304 dahil) süre alır; admin/prewarm içeride elenir.
+  if (accessLog) {
+    const { accessLogMiddleware } = await import("./logs/access-middleware.js");
+    app.use(accessLogMiddleware());
+  }
+
   app.use(staticPrecompressed(config.dirs.public));
   app.use(
     express.static(config.dirs.public, {
@@ -248,8 +262,10 @@ export async function startServer(options = {}) {
 /**
  * `SIGTERM`/`SIGINT` sonrası düzenli kapanış.
  *
- * Kapatılması gereken tek dış bağlantı Redis ve `quit` uçuştaki komutların
- * bitmesini bekliyor; sert `disconnect` yarıda kalan bir `SET` bırakabiliyor.
+ * Kapatılması gereken dış kaynaklar Redis ve log sink buffer'ları. Redis
+ * `quit` uçuştaki komutların bitmesini bekliyor; sert `disconnect` yarıda
+ * kalan bir `SET` bırakabiliyor. S3 sink kapanışta kalan batch'i PutObject
+ * ile gönderir.
  *
  * Açık HTTP bağlantıları **beklenmez**. `close()` tek başına yalnızca yeni
  * bağlantıyı reddediyor; keep-alive bir istemci ya da dev panelinin
@@ -276,10 +292,11 @@ function attachShutdown(server) {
     server.close();
     server.closeAllConnections?.();
 
-    void disconnectRedis().finally(() => {
-      clearTimeout(timer);
-      process.exit(0);
-    });
+    void Promise.all([disconnectRedis(), flushLogs().then(() => closeLogs())])
+      .finally(() => {
+        clearTimeout(timer);
+        process.exit(0);
+      });
   };
 
   process.once("SIGTERM", shutdown);

package/src/server/logs/access-middleware.js

@@ -0,0 +1,66 @@
+/**
+ * HTTP access log middleware.
+ *
+ * Admin ve prewarm yolları atlanır. Kayıt `log.http` ile stdout'a (console
+ * açıksa) ve `acceptLogEntry` ile sink'lere gider. `emitHttp` kapalı olduğu
+ * için `log.http` abonelere ikinci kez yazmaz.
+ */
+import * as log from "../../log.mjs";
+import { getConfig } from "../../config/index.js";
+import { acceptLogEntry } from "./pipeline.js";
+
+/**
+ * @param {{ basePath?: string }} [options]
+ * @returns {import('express').RequestHandler}
+ */
+export function accessLogMiddleware(options = {}) {
+  const config = getConfig();
+  const brand = config.brand;
+  const basePath =
+    options.basePath ??
+    (config.admin.enabled ? config.admin.basePath : null);
+
+  /** @type {import('express').RequestHandler} */
+  return (req, res, next) => {
+    const pathname = req.path || "";
+    if (basePath && (pathname === basePath || pathname.startsWith(`${basePath}/`))) {
+      return next();
+    }
+
+    if (req.headers["user-agent"] === brand.prewarmUserAgent) {
+      return next();
+    }
+
+    const started = process.hrtime.bigint();
+
+    res.on("finish", () => {
+      const ms = Number(process.hrtime.bigint() - started) / 1e6;
+      const cache = /** @type {string | null} */ (
+        res.getHeader(brand.cacheHeader) ?? null
+      );
+
+      const info = {
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        ms,
+        cache,
+      };
+
+      // Stdout (console açıksa). emitHttp kapalı → subscribe çiftlemez.
+      log.http(info);
+
+      acceptLogEntry({
+        kind: "http",
+        method: info.method,
+        url: info.url,
+        path: req.path,
+        status: info.status,
+        ms: info.ms,
+        cache: info.cache,
+      });
+    });
+
+    next();
+  };
+}

package/src/server/logs/file-sink.js

@@ -0,0 +1,66 @@
+/**
+ * Günlük rotasyonlu NDJSON dosya sink'i.
+ *
+ * Yol `path.resolve(root, dir)` ile bulunur — `getConfig().dirs` şişirilmez;
+ * log dizini opsiyonel bir yüzey ve çoğu kurulumda hiç açılmaz.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @typedef {{ write: (entry: Record<string, unknown>) => Promise<void>,
+ *   flush: () => Promise<void>, close: () => Promise<void> }} LogSink
+ */
+
+/**
+ * @param {{ root: string, dir: string }} options
+ * @returns {LogSink}
+ */
+export function createFileSink(options) {
+  const baseDir = path.resolve(options.root, options.dir);
+  /** @type {string | null} */
+  let currentDay = null;
+  /** @type {string | null} */
+  let currentPath = null;
+  let ready = false;
+
+  /** @returns {string} */
+  function dayStamp(date = new Date()) {
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(date.getUTCDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+  }
+
+  /**
+   * @param {string} day
+   * @returns {Promise<string>}
+   */
+  async function ensureFile(day) {
+    if (!ready) {
+      await fs.mkdir(baseDir, { recursive: true });
+      ready = true;
+    }
+    if (currentDay === day && currentPath) return currentPath;
+    currentDay = day;
+    currentPath = path.join(baseDir, `jskelet-${day}.log`);
+    return currentPath;
+  }
+
+  return {
+    async write(entry) {
+      const day = dayStamp(
+        typeof entry.at === "number" ? new Date(entry.at) : new Date(),
+      );
+      const file = await ensureFile(day);
+      await fs.appendFile(file, `${JSON.stringify(entry)}\n`, "utf8");
+    },
+    async flush() {
+      // appendFile senkron flush eder; ekstra iş yok.
+    },
+    async close() {
+      currentDay = null;
+      currentPath = null;
+    },
+  };
+}

package/src/server/logs/pipeline.js

@@ -0,0 +1,164 @@
+/**
+ * Structured log pipeline: `log.subscribe` → kinds filtresi → file / S3.
+ *
+ * Sink yokken abone olunmaz: `emitLog` boş Set üzerinde döner ve stdout
+ * yoluna maliyet eklemez. Credential eksikse S3 açılmaz, site ayağa kalkar.
+ */
+import process from "node:process";
+import * as log from "../../log.mjs";
+import { createFileSink } from "./file-sink.js";
+import { createS3Sink } from "./s3-sink.js";
+
+/**
+ * @typedef {import('../../config/index.js').LogsConfig} LogsConfig
+ * @typedef {import('../../config/index.js').ResolvedConfig} ResolvedConfig
+ * @typedef {import('./file-sink.js').LogSink} LogSink
+ */
+
+/** @type {(() => void) | null} */
+let unsubscribe = null;
+/** @type {LogSink[]} */
+let sinks = [];
+/** @type {Set<string>} */
+let kindSet = new Set();
+let accessMounted = false;
+
+/**
+ * @returns {import('./s3-put.js').AwsCredentials | null}
+ */
+function readCredentials() {
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+  if (!accessKeyId || !secretAccessKey) return null;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    sessionToken: process.env.AWS_SESSION_TOKEN || null,
+  };
+}
+
+/**
+ * Access middleware mount edilmeli mi?
+ *
+ * Dev'de yalnızca console isteniyorsa mount edilmez — HTML satırlarını
+ * zaten devtools basıyor; çift kayıt olmasın. Sink açıksa ya da production
+ * console access log istiyorsa mount edilir.
+ *
+ * @param {LogsConfig} logs
+ * @returns {boolean}
+ */
+export function shouldMountAccessLog(logs) {
+  if (!logs.kinds.includes("http")) return false;
+  if (logs.file.enabled || logs.s3.enabled) return true;
+  return logs.console && process.env.NODE_ENV !== "development";
+}
+
+/**
+ * @param {ResolvedConfig} config
+ * @returns {Promise<{ accessLog: boolean }>}
+ */
+export async function configureLogs(config) {
+  await closeLogs();
+
+  const logs = config.logs;
+  kindSet = new Set(logs.kinds);
+  accessMounted = shouldMountAccessLog(logs);
+
+  log.configureLog({
+    console: logs.console,
+    // Access middleware HTTP'yi kendisi pipeline'a yazar; log.http yalnızca
+    // stdout için kalsın — aksi hâlde HTML istekleri (devtools) çiftlenir.
+    emitHttp: !accessMounted,
+  });
+
+  /** @type {LogSink[]} */
+  const next = [];
+
+  if (logs.file.enabled) {
+    next.push(createFileSink({ root: config.root, dir: logs.file.dir }));
+  }
+
+  if (logs.s3.enabled) {
+    const credentials = readCredentials();
+    if (!logs.s3.bucket) {
+      console.warn("[logs] s3.enabled but no bucket (set JSKELET_LOG_BUCKET or logs.s3.bucket)");
+    } else if (!logs.s3.region) {
+      console.warn("[logs] s3.enabled but no region (set AWS_REGION or logs.s3.region)");
+    } else if (!credentials) {
+      console.warn(
+        "[logs] s3.enabled but AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY missing — S3 sink disabled",
+      );
+    } else {
+      next.push(
+        createS3Sink({
+          bucket: logs.s3.bucket,
+          prefix: logs.s3.prefix,
+          region: logs.s3.region,
+          endpoint: logs.s3.endpoint,
+          credentials,
+          flushIntervalMs: logs.s3.flushIntervalMs,
+          maxBatch: logs.s3.maxBatch,
+        }),
+      );
+    }
+  }
+
+  sinks = next;
+
+  if (sinks.length) {
+    unsubscribe = log.subscribe((raw) => {
+      acceptLogEntry(raw);
+    });
+  }
+
+  return { accessLog: accessMounted };
+}
+
+/**
+ * Access middleware ve `log.subscribe` ortak giriş noktası.
+ *
+ * @param {Record<string, unknown>} raw
+ */
+export function acceptLogEntry(raw) {
+  if (!sinks.length) return;
+
+  const kind = typeof raw.kind === "string" ? raw.kind : "event";
+  if (!kindSet.has(kind)) return;
+
+  const entry = {
+    ...raw,
+    kind,
+    at: typeof raw.at === "number" ? raw.at : Date.now(),
+  };
+
+  for (const sink of sinks) {
+    void sink.write(entry).catch((error) => {
+      console.warn("[logs] sink write failed", error);
+    });
+  }
+}
+
+/**
+ * Kapanışta buffer'ları boşaltır.
+ *
+ * @returns {Promise<void>}
+ */
+export async function flushLogs() {
+  await Promise.all(sinks.map((sink) => sink.flush()));
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+export async function closeLogs() {
+  if (unsubscribe) {
+    unsubscribe();
+    unsubscribe = null;
+  }
+  const closing = sinks;
+  sinks = [];
+  await Promise.all(closing.map((sink) => sink.close()));
+  kindSet = new Set();
+  accessMounted = false;
+  log.configureLog({ console: true, emitHttp: true });
+}