jskelet 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -47,6 +47,12 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
+- The dev tools panel is now fed over a WebSocket (`<devBasePath>/ws`) instead of
+  polling `/stats` every two seconds. The server pushes statistics as they change
+  and sends live reload and CSS hot-swap events over the same connection, so an
+  open tab no longer keeps hitting the server while the panel is closed. No new
+  dependency is involved; if the socket cannot be opened, the panel falls back to
+  the previous SSE plus polling path.
 - `notFound()` is no longer served as a 404 when a transient upstream failure
   (`429`, `5xx`, network error) happened during the same render. The page is
   retried first and, if upstream is still failing, responds with an uncached

package/docs/09-dev-araclari.md

@@ -111,9 +111,9 @@ Restart satırı değişen dosyayı ya da sayısını gösterir:
 
 ## CSS hot-swap ve tam yenileme
 
-Dev sunucusu `.jskelet/manifest.json` dosyasını izler ve bir SSE kanalı
-(`<devBasePath>/events`) üzerinden tarayıcıya olay yayınlar. Manifest her build
-turunda yeniden yazıldığı için değişiklik tespiti manifest üzerinden yapılır.
+Dev sunucusu `.jskelet/manifest.json` dosyasını izler ve olayları canlı kanal
+(`<devBasePath>/ws`) üzerinden tarayıcıya yayınlar. Manifest her build turunda
+yeniden yazıldığı için değişiklik tespiti manifest üzerinden yapılır.
 
 | Değişen | Davranış |
 | --- | --- |
@@ -131,6 +131,27 @@ Sunucu yeniden başladığında overlay bunu **boot kimliğinden** anlar: her s
 kendine özgü bir `boot` değeri yayınlar, overlay değişikliği görüp "restarted"
 bilgisini gösterir ve kendi durumunu sıfırlamaz.
 
+## Canlı kanal
+
+Overlay'e giden her şey — istatistikler, live reload ve CSS hot-swap olayları —
+tek bir WebSocket üzerinden gelir (`<devBasePath>/ws`). Panel eskiden
+istatistikleri iki saniyede bir çekiyordu; açık her sekme, panel kapalıyken bile
+sunucuya sürekli istek atıyordu. Artık sunucu değişiklik oldukça iter: bir istek
+ya da hata kaydedildiğinde (120 ms birleştirilerek), ısıtma sürerken saniyede
+bir, geri kalan zamanda yalnızca uptime/bellek tazelensin diye dört saniyede bir.
+Bağlı panel yoksa hiçbir şey hesaplanmaz.
+
+El sıkışma HTTP `upgrade` olayında geçtiği ve o olay middleware zincirine hiç
+uğramadığı için kanal `listen` sonrası doğrudan sunucuya bağlanır
+(`attachDevSocket`). Sunucu tarafı `ws` gibi bir bağımlılık kullanmaz: yalnızca
+sunucu→istemci metin çerçevesi yazmak ve istemcinin ping/close çerçevelerini
+yanıtlamak gerekiyor.
+
+Soket hiç açılamazsa (araya giren bir proxy WebSocket'i geçirmiyor olabilir)
+overlay eski yola düşer: `/events` SSE akışı + `/stats` yoklaması. Soket kurulup
+sonra düşerse — yani sunucu yeniden başlıyorsa — yarım saniyede bir yeniden
+bağlanır ve gösterge bu sırada "bağlantı yok" der.
+
 ## Devtools overlay
 
 Sağ altta yüzen bir baloncuk; `Alt+D` ile açılır, `Esc` ya da karartma alanına
@@ -236,8 +257,9 @@ Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç gi
 | --- | --- | --- |
 | `/overlay.js` | GET | Overlay script'i |
 | `/logo.png` | GET | Overlay logosu |
-| `/events` | GET | SSE: live reload ve CSS hot-swap olayları |
-| `/stats` | GET | Anlık istatistikler (overlay 2 saniyede bir çeker) |
+| `/ws` | GET (upgrade) | Canlı kanal: istatistikler, live reload ve CSS hot-swap olayları |
+| `/events` | GET | SSE: yalnızca WebSocket kurulamazsa kullanılan yedek olay akışı |
+| `/stats` | GET | Anlık istatistikler; aynı yedek yolun veri ucu |
 | `/report` | GET | Rapor sayfası (HTML) |
 | `/report.js` | GET | Rapor sayfasının script'i |
 | `/report/data` | GET | Raporun tek veri kaynağı (JSON) |

package/docs/en/09-dev-tools.md

@@ -116,7 +116,7 @@ If `JSKELET_VERBOSE=1` is set, all files are listed when more than one changed.
 ## CSS hot-swap and full reload
 
 The dev server watches `.jskelet/manifest.json` and broadcasts events to the
-browser over an SSE channel (`<devBasePath>/events`). Since the manifest is
+browser over the live channel (`<devBasePath>/ws`). Since the manifest is
 rewritten on every build round, change detection is done through the manifest.
 
 | What changed | Behavior |
@@ -134,6 +134,28 @@ When the server restarts, the overlay figures it out from the **boot id**: every
 process broadcasts a unique `boot` value, the overlay sees the change, shows the
 "restarted" note and does not reset its own state.
 
+## The live channel
+
+Everything the overlay shows — statistics, live reload and CSS hot-swap events —
+arrives over a single WebSocket (`<devBasePath>/ws`). The panel used to poll for
+statistics every two seconds, so every open tab kept hitting the server even
+while the panel was closed. Now the server pushes as things change: when a
+request or an error is recorded (coalesced over 120 ms), once per second while
+prewarming runs, and every four seconds otherwise so uptime and memory stay
+fresh. Nothing is computed when no panel is connected.
+
+The handshake happens on the HTTP `upgrade` event, and that event never reaches
+the middleware chain, so the channel is attached straight to the server after
+`listen` (`attachDevSocket`). The server side pulls in no dependency such as
+`ws`: all it needs is to write server-to-client text frames and to answer the
+client's ping/close frames.
+
+If the socket cannot be opened at all (a proxy in between may not pass WebSocket
+through), the overlay falls back to the old path: the `/events` SSE stream plus
+polling `/stats`. If the socket opens and later drops — that is, the server is
+restarting — it reconnects every half second and the indicator reads
+"server restarting…" in the meantime.
+
 ## Devtools overlay
 
 A floating bubble in the bottom right; opened with `Alt+D`, closed with `Esc` or
@@ -240,8 +262,9 @@ Under `brand.devBasePath` (default `/__jskelet/dev`):
 | --- | --- | --- |
 | `/overlay.js` | GET | The overlay script |
 | `/logo.png` | GET | The overlay logo |
-| `/events` | GET | SSE: live reload and CSS hot-swap events |
-| `/stats` | GET | Current statistics (the overlay polls every 2 seconds) |
+| `/ws` | GET (upgrade) | Live channel: statistics, live reload and CSS hot-swap events |
+| `/events` | GET | SSE: the fallback event stream, used only when WebSocket cannot be established |
+| `/stats` | GET | Current statistics; the data endpoint of that same fallback |
 | `/report` | GET | The report page (HTML) |
 | `/report.js` | GET | The report page's script |
 | `/report/data` | GET | The report's single data source (JSON) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/client/devtools/overlay.js

@@ -11,6 +11,7 @@
  */
 
 const BASE = "/__jskelet/dev";
+/** Soket kurulamadığında düşülen yedek yoklama sıklığı. */
 const POLL_MS = 2000;
 const MAX_ERRORS = 100;
 
@@ -386,50 +387,112 @@ let restarts = 0;
 /* -------------------------------------------------------- canlı yenileme */
 
 /**
- * Sunucu olay akışı. Amaç titremeyi bitirmek: CSS değiştiğinde sayfa
- * yenilenmez, yalnızca stylesheet yeni sürümle takas edilir. Sunucu yeniden
- * başladığında (boot kimliği değişince) tek sefer tam yenileme yapılır;
- * overlay durumu sekme belleğinde durduğu için panel açık kalmaya devam eder.
+ * Sunucudan gelen her şey tek bir WebSocket üzerinden akar: istatistikler,
+ * CSS takası ve yeniden başlatma bildirimi. Eskiden istatistikler iki saniyede
+ * bir çekiliyordu; her açık sekme, panel kapalıyken bile sunucuya sürekli
+ * istek atıyordu.
+ *
+ * CSS değiştiğinde sayfa yenilenmez, yalnızca stylesheet yeni sürümle takas
+ * edilir. Sunucu yeniden başladığında (boot kimliği değişince) tek sefer tam
+ * yenileme yapılır; overlay durumu sekme belleğinde durduğu için panel açık
+ * kalmaya devam eder.
  */
-function connectEvents() {
-  const source = new EventSource(`${BASE}/events`);
+function connectSocket() {
+  let socket;
+  try {
+    socket = new WebSocket(
+      `${location.protocol === "https:" ? "wss" : "ws"}://${location.host}${BASE}/ws`,
+    );
+  } catch {
+    startFallback();
+    return;
+  }
 
-  source.addEventListener("message", (event) => {
-    /** @type {{ type: string, boot?: string, href?: string }} */
-    const payload = JSON.parse(event.data);
+  // Soket hiç açılamazsa (proxy WebSocket'i geçirmiyor olabilir) eski
+  // SSE + yoklama yoluna düşülür; dev akışı bir ara katman yüzünden körelmesin.
+  let opened = false;
 
-    if (payload.type === "hello") {
-      offline = false;
-      const previous = sessionStorage.getItem(BOOT_KEY);
-      sessionStorage.setItem(BOOT_KEY, payload.boot);
+  socket.addEventListener("open", () => {
+    opened = true;
+  });
 
-      if (previous && previous !== payload.boot) {
-        restarts += 1;
-        location.reload();
-        return;
-      }
+  socket.addEventListener("message", (event) => {
+    handleServerMessage(JSON.parse(event.data));
+  });
 
-      bootId = payload.boot;
-      render();
+  socket.addEventListener("close", () => {
+    if (!opened) {
+      startFallback();
       return;
     }
 
-    if (payload.type === "css") {
-      swapStylesheet(payload.href);
+    // Sunucu yeniden başlıyor: gösterge "bağlantı yok"a döner ve kısa aralıkla
+    // yeniden denenir. Açılışta gelen `hello` yeniden başlatmayı bildirir.
+    if (!offline) {
+      offline = true;
+      render();
+    }
+    setTimeout(connectSocket, 500);
+  });
+}
+
+/**
+ * Hem soketten hem yedek SSE akışından gelen paketler burada işlenir.
+ * @param {{ type: string, boot?: string, href?: string }} payload
+ */
+function handleServerMessage(payload) {
+  if (payload.type === "stats") {
+    applyStats(payload);
+    return;
+  }
+
+  if (payload.type === "hello") {
+    offline = false;
+    const previous = sessionStorage.getItem(BOOT_KEY);
+    sessionStorage.setItem(BOOT_KEY, payload.boot);
+
+    if (previous && previous !== payload.boot) {
+      restarts += 1;
+      location.reload();
       return;
     }
 
-    if (payload.type === "reload") location.reload();
-  });
+    bootId = payload.boot;
+    render();
+    return;
+  }
+
+  if (payload.type === "css") {
+    swapStylesheet(payload.href);
+    return;
+  }
+
+  if (payload.type === "reload") location.reload();
+}
+
+/**
+ * WebSocket kurulamadığında eski yol: SSE + periyodik yoklama. Bir kez
+ * başlatılır.
+ */
+let fallbackStarted = false;
 
+function startFallback() {
+  if (fallbackStarted) return;
+  fallbackStarted = true;
+
+  const source = new EventSource(`${BASE}/events`);
+  source.addEventListener("message", (event) =>
+    handleServerMessage(JSON.parse(event.data)),
+  );
   source.addEventListener("error", () => {
-    // Sunucu yeniden başlarken bağlantı düşer; EventSource kendi kendine
-    // yeniden bağlanır, biz yalnızca göstergeyi güncelleriz.
     if (!offline) {
       offline = true;
       render();
     }
   });
+
+  setInterval(pollServer, POLL_MS);
+  pollServer();
 }
 
 /**
@@ -446,24 +509,30 @@ function swapStylesheet(href) {
   current.after(next);
 }
 
+/**
+ * Sunucudan gelen istatistik paketini panele işler.
+ * @param {object} stats
+ */
+function applyStats(stats) {
+  // Süreç kimliği değiştiyse sunucu yeniden başlamıştır. Overlay kapanmaz,
+  // yalnızca sayacı artar; günlükler sunucuda kalıcı olduğu için de silinmez.
+  if (bootId && stats.boot !== bootId) restarts += 1;
+  bootId = stats.boot ?? bootId;
+
+  offline = false;
+  serverStats = stats;
+  render();
+}
+
+/** Yalnızca yedek yolda kullanılır; canlı veri soketten gelir. */
 async function pollServer() {
+  if (!fallbackStarted) return;
+
   try {
     const response = await fetch(`${BASE}/stats`, { cache: "no-store" });
     if (!response.ok) return;
 
-    const stats = await response.json();
-
-    // Süreç kimliği değiştiyse sunucu yeniden başlamıştır. Overlay kapanmaz,
-    // yalnızca sayacı artar; günlükler sunucuda kalıcı olduğu için de silinmez.
-    if (bootId && stats.boot !== bootId) restarts += 1;
-    bootId = stats.boot ?? bootId;
-
-    offline = false;
-    serverStats = stats;
-    render();
-
-    // Isıtma sürerken sayaç akıcı görünsün diye yoklama sıklaşır.
-    if (stats.prewarm?.active) setTimeout(pollServer, 600);
+    applyStats(await response.json());
   } catch {
     // Yeniden başlatma penceresi: eldeki veriler korunur, yalnızca durum
     // göstergesi "bağlantı yok"a döner.
@@ -1763,13 +1832,9 @@ function start() {
   bind(ensureRoot());
   render();
 
-  connectEvents();
-
-  setInterval(() => {
-    // Panel kapalıyken de rozet güncel kalsın diye sunucu yine yoklanır.
-    pollServer();
-  }, POLL_MS);
-  pollServer();
+  // Panel kapalıyken de rozet güncel kalsın diye kanal her zaman açılır;
+  // maliyeti tek bir bağlantı ve yalnızca değişiklik oldukça gelen paketler.
+  connectSocket();
 
   // Ölçümler oturmadan gönderilmesin; sonra sekmeden ayrılırken güncellenir.
   setTimeout(() => sendPageReport(), 3000);

package/src/server/create-app.js

@@ -168,7 +168,14 @@ export async function startServer(options = {}) {
   });
 
   return new Promise((resolve) => {
-    const server = app.listen(port, host, () => {
+    const server = app.listen(port, host, async () => {
+      // 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.
+      if (process.env.NODE_ENV === "development") {
+        const { attachDevSocket } = await import("./dev/devtools.js");
+        attachDevSocket(server);
+      }
+
       // 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(

package/src/server/dev/devtools.js

@@ -22,6 +22,7 @@ import {
   trackServerFetch,
 } from "./report.js";
 import { startVersionCheck, versionStatus } from "./version-check.mjs";
+import { broadcastSocket, socketCount, upgradeToSocket } from "./socket.js";
 
 /** Overlay dosyaları framework paketinden servis edilir, uygulamadan değil. */
 const DEVTOOLS_DIR = path.join(FRAMEWORK_ROOT, "src", "client", "devtools");
@@ -115,6 +116,7 @@ export function recordServerError(level, message, extra = {}) {
   });
   trim(errors);
   persist();
+  pushStats();
 }
 
 /**
@@ -177,6 +179,7 @@ function timing() {
       requests.push(entry);
       trim(requests);
       persist();
+      pushStats();
       // Terminalde canlı istek satırı.
       log.http(entry);
     });
@@ -185,6 +188,75 @@ function timing() {
   };
 }
 
+/* ----------------------------------------------------------- istatistikler */
+
+/**
+ * Overlay'in gösterdiği her şey tek pakette. `GET /stats` ve WebSocket aynı
+ * gövdeyi kullanır ki panel hangi yoldan beslenirse beslensin aynı şeyi
+ * görsün.
+ *
+ * @returns {object}
+ */
+function statsPayload() {
+  const usage = process.memoryUsage();
+
+  return {
+    type: "stats",
+    pid: process.pid,
+    // Overlay yeniden başlatmayı bu kimlikten anlar; kendi durumunu
+    // sıfırlamadan yalnızca "restarted" bilgisini gösterir.
+    boot: BOOT_ID,
+    uptime: process.uptime(),
+    node: process.version,
+    version: versionStatus(),
+    memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+    prewarm: { ...prewarmProgress },
+    requests: requests.slice(-25).reverse(),
+    errors: errors.slice(-25).reverse(),
+  };
+}
+
+/** @type {NodeJS.Timeout | null} */
+let statsTimer = null;
+
+/**
+ * Değişiklikleri panele iter. Bir sayfa yüklemesi arka arkaya birçok kayıt
+ * üretiyor (istek + uyarılar); paket başına bir çerçeve yerine kısa bir
+ * sessizlikten sonra tek çerçeve gönderilir.
+ */
+function pushStats() {
+  if (statsTimer || !socketCount()) return;
+
+  statsTimer = setTimeout(() => {
+    statsTimer = null;
+    broadcastSocket(statsPayload());
+  }, 120);
+
+  statsTimer.unref?.();
+}
+
+/**
+ * Zamana bağlı alanlar (uptime, bellek) ve ısıtma ilerlemesi bir olay
+ * üretmiyor; onlar için düşük frekanslı bir kalp atışı gerekiyor. Isıtma
+ * sürerken sayaç akıcı görünsün diye sıklaşır.
+ *
+ * Bağlı panel yokken hiçbir şey hesaplanmaz.
+ */
+function startHeartbeat() {
+  let tick = 0;
+
+  const timer = setInterval(() => {
+    if (!socketCount()) return;
+
+    tick += 1;
+    if (!prewarmProgress.active && tick % 4 !== 0) return;
+
+    broadcastSocket(statsPayload());
+  }, 1000);
+
+  timer.unref?.();
+}
+
 /* ------------------------------------------------------------ live reload */
 
 /** @type {Set<import('express').Response>} */
@@ -198,8 +270,14 @@ function send(res, payload) {
   res.write(`data: ${JSON.stringify(payload)}\n\n`);
 }
 
-/** @param {object} payload */
+/**
+ * Canlı yenileme olayları. Panel normalde WebSocket üzerinden dinler; SSE
+ * yalnızca soket kurulamadığında devreye giren yedek yol.
+ *
+ * @param {object} payload
+ */
 function broadcast(payload) {
+  broadcastSocket(payload);
   for (const client of clients) send(client, payload);
 }
 
@@ -285,22 +363,10 @@ function router() {
     req.on("close", () => clients.delete(res));
   });
 
+  // WebSocket kurulamadığında panelin düştüğü yedek uç.
   api.get("/stats", (req, res) => {
-    const usage = process.memoryUsage();
     res.setHeader("Cache-Control", "no-store");
-    res.json({
-      pid: process.pid,
-      // Overlay yeniden başlatmayı bu kimlikten anlar; kendi durumunu
-      // sıfırlamadan yalnızca "restarted" bilgisini gösterir.
-      boot: BOOT_ID,
-      uptime: process.uptime(),
-      node: process.version,
-      version: versionStatus(),
-      memory: { rss: usage.rss, heapUsed: usage.heapUsed },
-      prewarm: { ...prewarmProgress },
-      requests: requests.slice(-25).reverse(),
-      errors: errors.slice(-25).reverse(),
-    });
+    res.json(statsPayload());
   });
 
   // Detaylı rapor: kendi sayfası, script'i ve veri ucu.
@@ -364,6 +430,7 @@ function router() {
     errors.length = 0;
     requests.length = 0;
     persist();
+    pushStats();
     res.json({ ok: true });
   });
 
@@ -382,6 +449,30 @@ export function mountDevtools(app) {
   trackServerFetch();
   watchManifest();
   startVersionCheck();
+  startHeartbeat();
   app.use(timing());
   app.use(brand.devBasePath, router());
 }
+
+/**
+ * Canlı kanalı HTTP sunucusuna bağlar.
+ *
+ * Express uygulamasına takılamıyor: WebSocket el sıkışması `upgrade` olayında
+ * geçiyor ve o olay middleware zincirine hiç uğramıyor. Bu yüzden `listen`
+ * sonrası ayrı bir adım.
+ *
+ * @param {import('node:http').Server} server
+ */
+export function attachDevSocket(server) {
+  const endpoint = `${getConfig().brand.devBasePath}/ws`;
+
+  server.on("upgrade", (req, socket) => {
+    // Uygulamanın kendi WebSocket uçları olabilir; yalnızca bizimkini alırız.
+    if ((req.url ?? "").split("?")[0] !== endpoint) return;
+
+    upgradeToSocket(req, socket, (send) => {
+      send({ type: "hello", boot: BOOT_ID });
+      send(statsPayload());
+    });
+  });
+}

package/src/server/dev/socket.js

@@ -0,0 +1,157 @@
+/**
+ * Dev araçlarının canlı kanalı: küçük bir WebSocket sunucusu.
+ *
+ * Overlay eskiden istatistikleri iki saniyede bir `GET /stats` ile çekiyordu;
+ * panel kapalıyken bile her sekme sürekli istek atıyor, dev sunucusunun istek
+ * günlüğünü de kirletiyordu. Artık sunucu değişiklik oldukça (istek, hata,
+ * ısıtma ilerlemesi, CSS/JS değişimi) tek bağlantı üzerinden itiyor.
+ *
+ * Bağımlılık eklemiyoruz: yalnızca sunucu→istemci metin çerçevesi yazmak ve
+ * istemcinin ping/close çerçevelerini anlamak gerekiyor; bu da RFC 6455'in
+ * küçük bir alt kümesi. `permessage-deflate` yok, parça (fragment) yok —
+ * gönderdiğimiz paketler için ikisi de gereksiz.
+ */
+import { createHash } from "node:crypto";
+
+/** RFC 6455'te sabitlenmiş el sıkışma tuzu. */
+const GUID = "258EAFA5-E914-47DA-95CA-5AB0DC85B39A";
+
+/** @type {Set<import('node:net').Socket>} */
+const sockets = new Set();
+
+/** @param {string} key */
+function accept(key) {
+  return createHash("sha1")
+    .update(key + GUID)
+    .digest("base64");
+}
+
+/**
+ * Tek parçalı metin çerçevesi. Maskeleme yalnızca istemci→sunucu yönünde
+ * zorunlu olduğu için burada yok.
+ *
+ * @param {string} text
+ * @returns {Buffer}
+ */
+function frame(text) {
+  const payload = Buffer.from(text, "utf8");
+  const length = payload.length;
+
+  /** @type {Buffer} */
+  let header;
+  if (length < 126) {
+    header = Buffer.from([0x81, length]);
+  } else if (length < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x81;
+    header[1] = 126;
+    header.writeUInt16BE(length, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x81;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(length), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+/**
+ * İstemciden gelen çerçeveleri ayıklar. İçerik bizi ilgilendirmiyor; amaç
+ * kapanışı ve ping'i doğru yanıtlamak, aksi hâlde tarayıcı bağlantıyı
+ * "protokol hatası" sayıp kapatıyor.
+ *
+ * @param {import('node:net').Socket} socket
+ */
+function readFrames(socket) {
+  let buffer = Buffer.alloc(0);
+
+  socket.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    while (buffer.length >= 2) {
+      const opcode = buffer[0] & 0x0f;
+      const masked = (buffer[1] & 0x80) !== 0;
+      let length = buffer[1] & 0x7f;
+      let offset = 2;
+
+      if (length === 126) {
+        if (buffer.length < offset + 2) return;
+        length = buffer.readUInt16BE(offset);
+        offset += 2;
+      } else if (length === 127) {
+        if (buffer.length < offset + 8) return;
+        length = Number(buffer.readBigUInt64BE(offset));
+        offset += 8;
+      }
+
+      if (masked) offset += 4;
+      if (buffer.length < offset + length) return;
+
+      buffer = buffer.subarray(offset + length);
+
+      // 0x8 close, 0x9 ping. Veri çerçeveleri yok sayılır: istemcinin bize
+      // söyleyeceği bir şey yok, kanal tek yönlü kullanılıyor.
+      if (opcode === 0x8) {
+        socket.end(Buffer.from([0x88, 0x00]));
+        return;
+      }
+      if (opcode === 0x9) socket.write(Buffer.from([0x8a, 0x00]));
+    }
+  });
+}
+
+/**
+ * HTTP upgrade isteğini WebSocket bağlantısına çevirir.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:net').Socket} socket
+ * @param {(send: (payload: object) => void) => void} onOpen
+ *   Bağlantı kurulunca çağrılır; ilk paketi göndermek için kullanılır.
+ */
+export function upgradeToSocket(req, socket, onOpen) {
+  const key = req.headers["sec-websocket-key"];
+  if (!key) {
+    socket.destroy();
+    return;
+  }
+
+  socket.write(
+    "HTTP/1.1 101 Switching Protocols\r\n" +
+      "Upgrade: websocket\r\n" +
+      "Connection: Upgrade\r\n" +
+      `Sec-WebSocket-Accept: ${accept(String(key))}\r\n\r\n`,
+  );
+
+  // Küçük paketleri geciktirmenin anlamı yok; panel anlık görünmeli.
+  socket.setNoDelay(true);
+  // Bağlantı hataları (sekme kapanması, ağ) süreci düşürmemeli.
+  socket.on("error", () => socket.destroy());
+  socket.on("close", () => sockets.delete(socket));
+
+  readFrames(socket);
+  sockets.add(socket);
+
+  onOpen((payload) => {
+    if (!socket.destroyed) socket.write(frame(JSON.stringify(payload)));
+  });
+}
+
+/**
+ * Bağlı tüm panellere gönderir.
+ * @param {object} payload
+ */
+export function broadcastSocket(payload) {
+  if (!sockets.size) return;
+
+  const packet = frame(JSON.stringify(payload));
+  for (const socket of sockets) {
+    if (socket.destroyed) sockets.delete(socket);
+    else socket.write(packet);
+  }
+}
+
+/** @returns {number} açık panel sayısı */
+export function socketCount() {
+  return sockets.size;
+}