jskelet 0.6.2 → 0.6.3

package/src/server/create-app.js

@@ -1,366 +1,366 @@
-/**
- * Express uygulamasını kurar ve dinlemeye başlar.
- *
- * Middleware **sırası** bu dosyanın asıl değeri; her konumun bir sebebi var
- * ve yer değiştirmek sessiz bozulmalara yol açıyor:
- *
- *   1. rewrites(beforeFiles) — statik dosyalardan da önce çalışmalı, yoksa
- *      `/assets/x.js` yolunu başka bir yere taşıyan kural işlemez.
- *   2. compression — static'ten önce; sonra gelirse statik dosyalar sıkışmaz.
- *   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.
- *   3c. robots.txt — statikten önce, compression'ın içinde: kullanıcının
- *      gövdesine framework Disallow bloğu eklenir. Sıkıştırılmış kopyanın
- *      (Content-Encoding dolu) üzerine yazılmaz.
- *   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).
- *   4b. admin paneli (açıksa) — statikten sonra, route'lardan önce: kendi
- *      gövde ayrıştırıcısını taşır ve uygulama yolunu gölgeleyemez.
- *   4c. image optimizer (images.remote) — uzak görselleri webp'ye çevirir;
- *      body parser'dan önce, admin ile aynı katmanda.
- *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
- *      maliyeti ödenmesin.
- *   5b. csrf — body parser'lardan sonra: token form alanından okunuyor.
- *      Rewrite'lardan önce, çünkü kontrol istemcinin gördüğü yola bakar.
- *   5c. auth handoff (açıksa) — CSRF'den *sonra*: mint POST origin koruması
- *      görsün. Redeem GET güvenli metot; route render'ından önce kalır.
- *   6. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
- *   7. route'lar → 404 → hata yönetimi.
- */
-import path from "node:path";
-import process from "node:process";
-import express from "express";
-import { compression } from "./middleware/compression.js";
-import { robotsTxtMiddleware } from "./middleware/robots-txt.js";
-import { headersMiddleware } from "./middleware/headers.js";
-import { csrf } from "./middleware/csrf.js";
-import { staticPrecompressed } from "./middleware/static-precompressed.js";
-import { devGate } from "./middleware/dev-gate.js";
-import { redirects } from "./middleware/redirects.js";
-import { trailingSlash } from "./middleware/trailing-slash.js";
-import { configRewrites } from "./middleware/upstream-proxy.js";
-import { getConfig, loadConfig } from "../config/index.js";
-import { IMMUTABLE_CACHE } from "../config/defaults.js";
-import { registerRoutes } from "./router.js";
-import { renderNotFound } from "./render.js";
-import { renderStatusPage, statusFromError } from "./status-page.js";
-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";
-import { ensurePortFree } from "./port-guard.js";
-
-/**
- * @param {{ root?: string, configFile?: string }} [options]
- * @returns {Promise<import('express').Express>}
- */
-export async function createApp(options = {}) {
-  // Config middleware'lerden önce okunur; yoksa uyarı basar, akış durmaz.
-  await loadConfig(options);
-  const config = getConfig();
-
-  // Upstream hatalarının izlenmesi route'lardan önce kurulmalı: sarmalayıcı
-  // yalnızca render bağlamı içindeki `fetch` çağrılarına bakar, ama bağlamın
-  // ilk kurulduğu istek de kapsanmalı.
-  if (config.trackUpstream) trackUpstreamFetch();
-
-  // Hız freni sarmalayıcının içinden okunuyor; ayarı ona vermek yeterli.
-  // `cache().upstream.rate` verilmedikçe hiçbir istek beklemez.
-  configureUpstreamLimiter(config.upstream);
-
-  // Önbelleğin ikinci kademesi route'lardan önce kurulmalı: ilk istek de
-  // paylaşımlı kopyayı görebilsin. Bağlanamazsa uyarı basılır ve uygulama
-  // bellek içi önbellekle çalışmaya devam eder — middleware sırasına
-  // 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");
-  app.use((req, res, next) => {
-    res.setHeader("X-Powered-By", config.brand.poweredBy);
-    next();
-  });
-
-  app.set("etag", "strong");
-  // Ters proxy arkasında doğru protokol ve istemci IP'si için. Doğrudan
-  // internete açık bir sunucuda kapatılmalı: açıkken istemci kendi
-  // `X-Forwarded-For` başlığını uydurabilir ve rate limit ile audit log
-  // yanlış IP görür.
-  app.set("trust proxy", config.security.trustProxy);
-
-  app.use(configRewrites("beforeFiles"));
-  app.use(compression());
-  app.use(headersMiddleware());
-  app.use(devGate());
-  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());
-  }
-
-  // Kullanıcının robots.txt'i statik dosya da olabilir, route da. İkisi de
-  // bu sarmalayıcıdan geçer. compression'dan sonra durur: ek, sıkıştırılmış
-  // baytların değil düz metnin sonuna yazılır.
-  app.use(robotsTxtMiddleware());
-
-  app.use(staticPrecompressed(config.dirs.public));
-  app.use(
-    express.static(config.dirs.public, {
-      index: false,
-      redirect: false,
-      // Hash'siz dosyalar (favicon, robots eki, elle konmuş görseller) içerik
-      // değişse de aynı adla kalıyor; bir yıllık cache onları güncellenemez
-      // hâle getiriyordu. Hash'li çıktı aşağıda ayrıca immutable işaretlenir.
-      maxAge: "1h",
-      setHeaders(res, filePath) {
-        if (filePath.includes(`${path.sep}assets${path.sep}`)) {
-          res.setHeader("Cache-Control", IMMUTABLE_CACHE);
-        }
-      },
-    }),
-  );
-
-  // Dev overlay yalnızca development'ta; dinamik import sayesinde prod
-  // sürecine hiçbir şey yüklenmez.
-  if (process.env.NODE_ENV === "development") {
-    const { mountDevtools } = await import("./dev/devtools.js");
-    mountDevtools(app);
-  }
-
-  // Yönetim paneli ortama bakmaz, config'e bakar: açıkça etkinleştirilmedikçe
-  // modül hiç yüklenmez ve yol da yoktur. Kendi gövde ayrıştırıcısını
-  // taşıdığı için aşağıdaki parser'lardan önce durabiliyor; route'lardan
-  // önce olması gerekiyor ki uygulama aynı yolu gölgeleyemesin.
-  if (config.admin.enabled) {
-    const { mountAdmin } = await import("./admin/mount.js");
-    mountAdmin(app);
-  }
-
-  // Uzak görsel proxy: allowHosts doluysa mount. Statikten sonra, body
-  // parser'dan önce — görsel GET'lerinde gövde ayrıştırma maliyeti ödenmesin.
-  if (config.images && config.images !== false && config.images.remote) {
-    const { mountImageOptimizer } = await import("./image-optimizer.js");
-    await mountImageOptimizer(app);
-  }
-
-  app.use(express.urlencoded({ extended: false, limit: "64kb" }));
-  app.use(express.json({ limit: "256kb" }));
-
-  app.use(csrf());
-
-  const handoff = config.auth?.crossSubdomainHandoff;
-  if (
-    handoff === true ||
-    (handoff &&
-      typeof handoff === "object" &&
-      /** @type {{ enabled?: boolean }} */ (handoff).enabled !== false)
-  ) {
-    const { mountAuthHandoff } = await import("./auth/handoff.js");
-    mountAuthHandoff(app);
-  }
-
-  app.use(configRewrites("afterFiles"));
-
-  await registerRoutes(app);
-
-  app.use(async (req, res, next) => {
-    try {
-      // headersMiddleware `/assets/*` için immutable basmış olabilir; eksik bir
-      // hash'li dosyanın 404'ü CDN'de bir yıl zehirlenmesin.
-      res.status(404).setHeader("Cache-Control", "no-store");
-      res.type("html").send(await renderNotFound());
-    } catch (error) {
-      next(error);
-    }
-  });
-
-  // Hata yönetimi: notFound/redirect kontrol akışı burada da yakalanır,
-  // çünkü bir controller dışında (ör. middleware içinde) fırlatılabilir.
-  app.use(async (error, req, res, next) => {
-    if (res.headersSent) {
-      next(error);
-      return;
-    }
-
-    if (isRedirectError(error)) {
-      res.redirect(error.statusCode, error.location);
-      return;
-    }
-
-    if (isNotFoundError(error)) {
-      res.status(404).setHeader("Cache-Control", "no-store");
-      res.type("html").send(await renderNotFound());
-      return;
-    }
-
-    const status = statusFromError(error);
-    // Isıtma turunun hataları tek tek loglanmaz; tur bitince özet olarak
-    // basılır. Yüzlerce yolu tarayan bir tur, upstream bir an tıksırdığında
-    // logu yığın izleriyle dolduruyordu.
-    if (isPrewarmRequest(req)) notePrewarmError(status, error);
-    else console.error(`[${status}] ${req.method} ${req.originalUrl}`, error);
-
-    // Hata sayfası hiçbir katmanda saklanmamalı: geçici bir upstream arızası
-    // CDN'de dakikalarca yaşayan bir 500 sayfasına dönüşmesin.
-    res.setHeader("Cache-Control", "no-store");
-    res
-      .status(status)
-      .type("html")
-      .send(await renderStatusPage(status, { error }));
-  });
-
-  return app;
-}
-
-/**
- * Uygulamayı kurup dinlemeye başlar. CLI `jskelet start` bunu çağırır;
- * gömülü kullanımda `createApp()` tercih edilir.
- *
- * Port doluysa başlamaz. `murder: true` veya argv'de `--murder` varsa
- * dinleyen süreç öldürülüp bağlama denenir.
- *
- * @param {{ root?: string, configFile?: string, port?: number, host?: string, murder?: boolean }} [options]
- * @returns {Promise<import('http').Server>}
- */
-export async function startServer(options = {}) {
-  const port = Number(options.port ?? process.env.PORT ?? 3000);
-  const murder =
-    options.murder === true || process.argv.includes("--murder");
-
-  // createApp pahalı; dolu portta uygulama kurmadan önce net hata ver.
-  await ensurePortFree(port, { murder });
-
-  const app = await createApp(options);
-
-  // Varsayılan `::`, `0.0.0.0` değil: ikisi de "tüm arayüzler" demek, ama
-  // yalnızca IPv6 soketi çift yığın çalışır ve `localhost`un `::1`e çözüldüğü
-  // durumu da kapsar. Tarayıcılar `localhost` için önce `::1` deniyor; sıradan
-  // isteklerde IPv4'e düşüyorlar ama WebSocket el sıkışması bu geri düşüşü
-  // yapmadan "failed" veriyordu. IPv6'sı olmayan bir makinede bağlama hata
-  // verir; aşağıda IPv4'e dönülür.
-  const host = options.host ?? process.env.HOST ?? null;
-
-  // Tek bir istek hatası süreci düşürmesin; logla ve ayakta kal. Bir haber
-  // sitesinde tek sayfanın hatası tüm siteyi indirmemeli.
-  process.on("unhandledRejection", (reason) => {
-    console.error("[unhandledRejection]", reason);
-  });
-  process.on("uncaughtException", (error) => {
-    console.error("[uncaughtException]", error);
-  });
-
-  // Dev panelinin canlı kanalı: el sıkışma `upgrade` olayında geçtiği için
-  // middleware zincirine değil, doğrudan sunucuya bağlanır. Modül `listen`den
-  // önce yüklenir; dinleme başladıktan sonra beklenen bir `await` kalırsa ilk
-  // upgrade isteği dinleyici yokken gelip reddedilebiliyor.
-  const attachDevSocket =
-    process.env.NODE_ENV === "development"
-      ? (await import("./dev/devtools.js")).attachDevSocket
-      : null;
-
-  return new Promise((resolve, reject) => {
-    /** @param {string} address */
-    const listen = (address) => {
-      const server = app.listen(port, address, () => {
-        // Bu satırın biçimi sözleşme: `jskelet dev` sunucunun hazır olduğunu
-        // buradan anlar ve özet satırını ona göre basar.
-        console.log(
-          `jskelet → http://localhost:${port} (${process.env.NODE_ENV ?? "production"})`,
-        );
-        startPrewarm({ port });
-        attachShutdown(server);
-        resolve(server);
-      });
-
-      server.on("error", (error) => {
-        // IPv6 desteklenmiyorsa yalnızca varsayılan adres için IPv4'e dönülür;
-        // kullanıcı bir adres verdiyse sessizce başkasını dinlemek yanlış olur.
-        if (!host && isAddressUnsupported(error)) {
-          listen("0.0.0.0");
-          return;
-        }
-        if (error.code === "EADDRINUSE") {
-          const hint = murder
-            ? `port ${port} is still in use after --murder`
-            : `port ${port} is already in use. Pass --murder to kill it and start, or set PORT to another value.`;
-          const wrapped = new Error(hint);
-          /** @type {NodeJS.ErrnoException} */ (wrapped).code = "EADDRINUSE";
-          reject(wrapped);
-          return;
-        }
-        reject(error);
-      });
-
-      attachDevSocket?.(server);
-    };
-
-    listen(host ?? "::");
-  });
-}
-
-/**
- * `SIGTERM`/`SIGINT` sonrası düzenli kapanış.
- *
- * 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
- * WebSocket'i sunucuyu süresiz ayakta tutuyor ve Ctrl+C yanıt vermiyormuş gibi
- * görünüyordu. Sinyal geldiğinde ters proxy zaten trafik göndermiyor.
- *
- * Yine de bir zamanlayıcı var: Redis kapanışı askıda kalırsa süreç `SIGKILL`
- * beklemek zorunda kalmasın.
- *
- * @param {import('http').Server} server
- */
-function attachShutdown(server) {
-  let closing = false;
-
-  const shutdown = () => {
-    // İkinci sinyal beklemeyi kısa kessin: kullanıcı Ctrl+C'ye tekrar bastıysa
-    // gerçekten çıkmak istiyor.
-    if (closing) process.exit(0);
-    closing = true;
-
-    const timer = setTimeout(() => process.exit(0), 3000);
-    timer.unref();
-
-    server.close();
-    server.closeAllConnections?.();
-
-    void Promise.all([disconnectRedis(), flushLogs().then(() => closeLogs())])
-      .finally(() => {
-        clearTimeout(timer);
-        process.exit(0);
-      });
-  };
-
-  process.once("SIGTERM", shutdown);
-  process.once("SIGINT", shutdown);
-}
-
-/**
- * @param {NodeJS.ErrnoException} error
- * @returns {boolean} adres ailesi bu makinede kullanılamıyor mu
- */
-function isAddressUnsupported(error) {
-  return error.code === "EAFNOSUPPORT" || error.code === "EADDRNOTAVAIL";
-}
+/**
+ * Express uygulamasını kurar ve dinlemeye başlar.
+ *
+ * Middleware **sırası** bu dosyanın asıl değeri; her konumun bir sebebi var
+ * ve yer değiştirmek sessiz bozulmalara yol açıyor:
+ *
+ *   1. rewrites(beforeFiles) — statik dosyalardan da önce çalışmalı, yoksa
+ *      `/assets/x.js` yolunu başka bir yere taşıyan kural işlemez.
+ *   2. compression — static'ten önce; sonra gelirse statik dosyalar sıkışmaz.
+ *   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.
+ *   3c. robots.txt — statikten önce, compression'ın içinde: kullanıcının
+ *      gövdesine framework Disallow bloğu eklenir. Sıkıştırılmış kopyanın
+ *      (Content-Encoding dolu) üzerine yazılmaz.
+ *   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).
+ *   4b. admin paneli (açıksa) — statikten sonra, route'lardan önce: kendi
+ *      gövde ayrıştırıcısını taşır ve uygulama yolunu gölgeleyemez.
+ *   4c. image optimizer (images.remote) — uzak görselleri webp'ye çevirir;
+ *      body parser'dan önce, admin ile aynı katmanda.
+ *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
+ *      maliyeti ödenmesin.
+ *   5b. csrf — body parser'lardan sonra: token form alanından okunuyor.
+ *      Rewrite'lardan önce, çünkü kontrol istemcinin gördüğü yola bakar.
+ *   5c. auth handoff (açıksa) — CSRF'den *sonra*: mint POST origin koruması
+ *      görsün. Redeem GET güvenli metot; route render'ından önce kalır.
+ *   6. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
+ *   7. route'lar → 404 → hata yönetimi.
+ */
+import path from "node:path";
+import process from "node:process";
+import express from "express";
+import { compression } from "./middleware/compression.js";
+import { robotsTxtMiddleware } from "./middleware/robots-txt.js";
+import { headersMiddleware } from "./middleware/headers.js";
+import { csrf } from "./middleware/csrf.js";
+import { staticPrecompressed } from "./middleware/static-precompressed.js";
+import { devGate } from "./middleware/dev-gate.js";
+import { redirects } from "./middleware/redirects.js";
+import { trailingSlash } from "./middleware/trailing-slash.js";
+import { configRewrites } from "./middleware/upstream-proxy.js";
+import { getConfig, loadConfig } from "../config/index.js";
+import { IMMUTABLE_CACHE } from "../config/defaults.js";
+import { registerRoutes } from "./router.js";
+import { renderNotFound } from "./render.js";
+import { renderStatusPage, statusFromError } from "./status-page.js";
+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";
+import { ensurePortFree } from "./port-guard.js";
+
+/**
+ * @param {{ root?: string, configFile?: string }} [options]
+ * @returns {Promise<import('express').Express>}
+ */
+export async function createApp(options = {}) {
+  // Config middleware'lerden önce okunur; yoksa uyarı basar, akış durmaz.
+  await loadConfig(options);
+  const config = getConfig();
+
+  // Upstream hatalarının izlenmesi route'lardan önce kurulmalı: sarmalayıcı
+  // yalnızca render bağlamı içindeki `fetch` çağrılarına bakar, ama bağlamın
+  // ilk kurulduğu istek de kapsanmalı.
+  if (config.trackUpstream) trackUpstreamFetch();
+
+  // Hız freni sarmalayıcının içinden okunuyor; ayarı ona vermek yeterli.
+  // `cache().upstream.rate` verilmedikçe hiçbir istek beklemez.
+  configureUpstreamLimiter(config.upstream);
+
+  // Önbelleğin ikinci kademesi route'lardan önce kurulmalı: ilk istek de
+  // paylaşımlı kopyayı görebilsin. Bağlanamazsa uyarı basılır ve uygulama
+  // bellek içi önbellekle çalışmaya devam eder — middleware sırasına
+  // 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");
+  app.use((req, res, next) => {
+    res.setHeader("X-Powered-By", config.brand.poweredBy);
+    next();
+  });
+
+  app.set("etag", "strong");
+  // Ters proxy arkasında doğru protokol ve istemci IP'si için. Doğrudan
+  // internete açık bir sunucuda kapatılmalı: açıkken istemci kendi
+  // `X-Forwarded-For` başlığını uydurabilir ve rate limit ile audit log
+  // yanlış IP görür.
+  app.set("trust proxy", config.security.trustProxy);
+
+  app.use(configRewrites("beforeFiles"));
+  app.use(compression());
+  app.use(headersMiddleware());
+  app.use(devGate());
+  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());
+  }
+
+  // Kullanıcının robots.txt'i statik dosya da olabilir, route da. İkisi de
+  // bu sarmalayıcıdan geçer. compression'dan sonra durur: ek, sıkıştırılmış
+  // baytların değil düz metnin sonuna yazılır.
+  app.use(robotsTxtMiddleware());
+
+  app.use(staticPrecompressed(config.dirs.public));
+  app.use(
+    express.static(config.dirs.public, {
+      index: false,
+      redirect: false,
+      // Hash'siz dosyalar (favicon, robots eki, elle konmuş görseller) içerik
+      // değişse de aynı adla kalıyor; bir yıllık cache onları güncellenemez
+      // hâle getiriyordu. Hash'li çıktı aşağıda ayrıca immutable işaretlenir.
+      maxAge: "1h",
+      setHeaders(res, filePath) {
+        if (filePath.includes(`${path.sep}assets${path.sep}`)) {
+          res.setHeader("Cache-Control", IMMUTABLE_CACHE);
+        }
+      },
+    }),
+  );
+
+  // Dev overlay yalnızca development'ta; dinamik import sayesinde prod
+  // sürecine hiçbir şey yüklenmez.
+  if (process.env.NODE_ENV === "development") {
+    const { mountDevtools } = await import("./dev/devtools.js");
+    mountDevtools(app);
+  }
+
+  // Yönetim paneli ortama bakmaz, config'e bakar: açıkça etkinleştirilmedikçe
+  // modül hiç yüklenmez ve yol da yoktur. Kendi gövde ayrıştırıcısını
+  // taşıdığı için aşağıdaki parser'lardan önce durabiliyor; route'lardan
+  // önce olması gerekiyor ki uygulama aynı yolu gölgeleyemesin.
+  if (config.admin.enabled) {
+    const { mountAdmin } = await import("./admin/mount.js");
+    mountAdmin(app);
+  }
+
+  // Uzak görsel proxy: allowHosts doluysa mount. Statikten sonra, body
+  // parser'dan önce — görsel GET'lerinde gövde ayrıştırma maliyeti ödenmesin.
+  if (config.images && config.images !== false && config.images.remote) {
+    const { mountImageOptimizer } = await import("./image-optimizer.js");
+    await mountImageOptimizer(app);
+  }
+
+  app.use(express.urlencoded({ extended: false, limit: "64kb" }));
+  app.use(express.json({ limit: "256kb" }));
+
+  app.use(csrf());
+
+  const handoff = config.auth?.crossSubdomainHandoff;
+  if (
+    handoff === true ||
+    (handoff &&
+      typeof handoff === "object" &&
+      /** @type {{ enabled?: boolean }} */ (handoff).enabled !== false)
+  ) {
+    const { mountAuthHandoff } = await import("./auth/handoff.js");
+    mountAuthHandoff(app);
+  }
+
+  app.use(configRewrites("afterFiles"));
+
+  await registerRoutes(app);
+
+  app.use(async (req, res, next) => {
+    try {
+      // headersMiddleware `/assets/*` için immutable basmış olabilir; eksik bir
+      // hash'li dosyanın 404'ü CDN'de bir yıl zehirlenmesin.
+      res.status(404).setHeader("Cache-Control", "no-store");
+      res.type("html").send(await renderNotFound());
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  // Hata yönetimi: notFound/redirect kontrol akışı burada da yakalanır,
+  // çünkü bir controller dışında (ör. middleware içinde) fırlatılabilir.
+  app.use(async (error, req, res, next) => {
+    if (res.headersSent) {
+      next(error);
+      return;
+    }
+
+    if (isRedirectError(error)) {
+      res.redirect(error.statusCode, error.location);
+      return;
+    }
+
+    if (isNotFoundError(error)) {
+      res.status(404).setHeader("Cache-Control", "no-store");
+      res.type("html").send(await renderNotFound());
+      return;
+    }
+
+    const status = statusFromError(error);
+    // Isıtma turunun hataları tek tek loglanmaz; tur bitince özet olarak
+    // basılır. Yüzlerce yolu tarayan bir tur, upstream bir an tıksırdığında
+    // logu yığın izleriyle dolduruyordu.
+    if (isPrewarmRequest(req)) notePrewarmError(status, error);
+    else console.error(`[${status}] ${req.method} ${req.originalUrl}`, error);
+
+    // Hata sayfası hiçbir katmanda saklanmamalı: geçici bir upstream arızası
+    // CDN'de dakikalarca yaşayan bir 500 sayfasına dönüşmesin.
+    res.setHeader("Cache-Control", "no-store");
+    res
+      .status(status)
+      .type("html")
+      .send(await renderStatusPage(status, { error }));
+  });
+
+  return app;
+}
+
+/**
+ * Uygulamayı kurup dinlemeye başlar. CLI `jskelet start` bunu çağırır;
+ * gömülü kullanımda `createApp()` tercih edilir.
+ *
+ * Port doluysa başlamaz. `murder: true` veya argv'de `--murder` varsa
+ * dinleyen süreç öldürülüp bağlama denenir.
+ *
+ * @param {{ root?: string, configFile?: string, port?: number, host?: string, murder?: boolean }} [options]
+ * @returns {Promise<import('http').Server>}
+ */
+export async function startServer(options = {}) {
+  const port = Number(options.port ?? process.env.PORT ?? 3000);
+  const murder =
+    options.murder === true || process.argv.includes("--murder");
+
+  // createApp pahalı; dolu portta uygulama kurmadan önce net hata ver.
+  await ensurePortFree(port, { murder });
+
+  const app = await createApp(options);
+
+  // Varsayılan `::`, `0.0.0.0` değil: ikisi de "tüm arayüzler" demek, ama
+  // yalnızca IPv6 soketi çift yığın çalışır ve `localhost`un `::1`e çözüldüğü
+  // durumu da kapsar. Tarayıcılar `localhost` için önce `::1` deniyor; sıradan
+  // isteklerde IPv4'e düşüyorlar ama WebSocket el sıkışması bu geri düşüşü
+  // yapmadan "failed" veriyordu. IPv6'sı olmayan bir makinede bağlama hata
+  // verir; aşağıda IPv4'e dönülür.
+  const host = options.host ?? process.env.HOST ?? null;
+
+  // Tek bir istek hatası süreci düşürmesin; logla ve ayakta kal. Bir haber
+  // sitesinde tek sayfanın hatası tüm siteyi indirmemeli.
+  process.on("unhandledRejection", (reason) => {
+    console.error("[unhandledRejection]", reason);
+  });
+  process.on("uncaughtException", (error) => {
+    console.error("[uncaughtException]", error);
+  });
+
+  // Dev panelinin canlı kanalı: el sıkışma `upgrade` olayında geçtiği için
+  // middleware zincirine değil, doğrudan sunucuya bağlanır. Modül `listen`den
+  // önce yüklenir; dinleme başladıktan sonra beklenen bir `await` kalırsa ilk
+  // upgrade isteği dinleyici yokken gelip reddedilebiliyor.
+  const attachDevSocket =
+    process.env.NODE_ENV === "development"
+      ? (await import("./dev/devtools.js")).attachDevSocket
+      : null;
+
+  return new Promise((resolve, reject) => {
+    /** @param {string} address */
+    const listen = (address) => {
+      const server = app.listen(port, address, () => {
+        // Bu satırın biçimi sözleşme: `jskelet dev` sunucunun hazır olduğunu
+        // buradan anlar ve özet satırını ona göre basar.
+        console.log(
+          `jskelet → http://localhost:${port} (${process.env.NODE_ENV ?? "production"})`,
+        );
+        startPrewarm({ port });
+        attachShutdown(server);
+        resolve(server);
+      });
+
+      server.on("error", (error) => {
+        // IPv6 desteklenmiyorsa yalnızca varsayılan adres için IPv4'e dönülür;
+        // kullanıcı bir adres verdiyse sessizce başkasını dinlemek yanlış olur.
+        if (!host && isAddressUnsupported(error)) {
+          listen("0.0.0.0");
+          return;
+        }
+        if (error.code === "EADDRINUSE") {
+          const hint = murder
+            ? `port ${port} is still in use after --murder`
+            : `port ${port} is already in use. Pass --murder to kill it and start, or set PORT to another value.`;
+          const wrapped = new Error(hint);
+          /** @type {NodeJS.ErrnoException} */ (wrapped).code = "EADDRINUSE";
+          reject(wrapped);
+          return;
+        }
+        reject(error);
+      });
+
+      attachDevSocket?.(server);
+    };
+
+    listen(host ?? "::");
+  });
+}
+
+/**
+ * `SIGTERM`/`SIGINT` sonrası düzenli kapanış.
+ *
+ * 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
+ * WebSocket'i sunucuyu süresiz ayakta tutuyor ve Ctrl+C yanıt vermiyormuş gibi
+ * görünüyordu. Sinyal geldiğinde ters proxy zaten trafik göndermiyor.
+ *
+ * Yine de bir zamanlayıcı var: Redis kapanışı askıda kalırsa süreç `SIGKILL`
+ * beklemek zorunda kalmasın.
+ *
+ * @param {import('http').Server} server
+ */
+function attachShutdown(server) {
+  let closing = false;
+
+  const shutdown = () => {
+    // İkinci sinyal beklemeyi kısa kessin: kullanıcı Ctrl+C'ye tekrar bastıysa
+    // gerçekten çıkmak istiyor.
+    if (closing) process.exit(0);
+    closing = true;
+
+    const timer = setTimeout(() => process.exit(0), 3000);
+    timer.unref();
+
+    server.close();
+    server.closeAllConnections?.();
+
+    void Promise.all([disconnectRedis(), flushLogs().then(() => closeLogs())])
+      .finally(() => {
+        clearTimeout(timer);
+        process.exit(0);
+      });
+  };
+
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+}
+
+/**
+ * @param {NodeJS.ErrnoException} error
+ * @returns {boolean} adres ailesi bu makinede kullanılamıyor mu
+ */
+function isAddressUnsupported(error) {
+  return error.code === "EAFNOSUPPORT" || error.code === "EADDRNOTAVAIL";
+}