@jacksontian/kite-server 0.3.0 → 0.4.0

package/lib/store.js

@@ -0,0 +1,115 @@
+/**
+ * 持久化：单文件 JSON，异步落盘（脏标记 + 节流 + 串行化，全程无同步 IO）；
+ * 以及卡死任务回收（sweepStaleRunning）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function createStore(ctx) {
+  const DB_FILE = path.join(ctx.cfg.dataDir, 'tasks.json');
+  const MAX_TASKS = ctx.cfg.maxTasks;
+  const STALE_RUNNING_MS = ctx.cfg.staleRunningMs;
+
+  const state = { tasks: [], heartbeats: {} };
+
+  async function loadState() {
+    let raw;
+    try {
+      raw = await fs.promises.readFile(DB_FILE, 'utf8');
+    } catch {
+      return; // 首次启动，文件尚不存在，从空状态开始
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      state.tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+      state.heartbeats = parsed.heartbeats || {};
+    } catch {
+      // 文件损坏：先备份，避免被后续写盘静默覆盖丢失历史数据
+      console.warn('[server] tasks.json 已损坏，备份后从空状态启动');
+      await fs.promises.rename(DB_FILE, `${DB_FILE}.corrupt-${Date.now()}`).catch(() => {});
+    }
+  }
+
+  // 只保留最近 MAX_TASKS 个终态任务，进行中的不受影响，防止无限增长
+  function pruneFinishedTasks() {
+    const finished = state.tasks.filter((t) => ['done', 'failed', 'canceled'].includes(t.status));
+    if (finished.length > MAX_TASKS) {
+      const sorted = finished.sort((a, b) => b.finishedAt - a.finishedAt);
+      const cutoff = sorted[MAX_TASKS - 1].finishedAt;
+      state.tasks = state.tasks.filter(
+        (t) => !['done', 'failed', 'canceled'].includes(t.status) || t.finishedAt >= cutoff,
+      );
+    }
+  }
+
+  // 落盘策略：脏标记 + 300ms 节流合并高频写（心跳/日志上报），串行链防交叠，
+  // tmp + rename 原子替换。崩溃最多丢约 300ms 的变更，
+  // 卡住的 running 任务由心跳超时回收兜底，可接受。
+  let savePending = false;
+  let saveTimer = null;
+  let savingChain = Promise.resolve();
+
+  async function flushSave() {
+    if (!savePending) return;
+    savePending = false; // 先清脏标记再序列化快照；写失败会重新标脏重试
+    pruneFinishedTasks();
+    try {
+      const data = JSON.stringify(state, null, 2);
+      const tmp = DB_FILE + '.tmp';
+      // 0600：tasks.json 含全部命令/日志/结果，不允许同机其他用户读取
+      await fs.promises.writeFile(tmp, data, { mode: 0o600 });
+      await fs.promises.chmod(tmp, 0o600); // writeFile 的 mode 只在创建时生效，历史文件需显式收紧
+      await fs.promises.rename(tmp, DB_FILE);
+    } catch (err) {
+      console.error(`[server] 落盘失败，下次变更时重试: ${err.message}`);
+      scheduleSave();
+    }
+  }
+
+  function scheduleSave() {
+    savePending = true;
+    if (saveTimer) return;
+    saveTimer = setTimeout(() => {
+      saveTimer = null;
+      savingChain = savingChain.then(flushSave);
+    }, 300).unref();
+  }
+
+  // 退出前把待写变更落盘（systemd 停服走 SIGTERM）
+  for (const sig of ['SIGTERM', 'SIGINT']) {
+    process.on(sig, () => {
+      savingChain.then(flushSave).finally(() => process.exit(0));
+    });
+  }
+
+  // Worker 崩溃/掉线后，回收卡死在 running 的任务。
+  // pty 交互会话例外：时长不可预期，由 ptyIdleSec 空闲回收（见 sweepPtyIdle）
+  function sweepStaleRunning() {
+    const now = Date.now();
+    // 顺带清理离线超过 7 天的 Worker 心跳记录，防止 heartbeats 无限增长
+    let hbPruned = false;
+    for (const [id, hb] of Object.entries(state.heartbeats)) {
+      if (now - hb.at > 7 * 24 * 3600 * 1000) {
+        delete state.heartbeats[id];
+        hbPruned = true;
+      }
+    }
+    if (hbPruned) scheduleSave();
+    for (const t of state.tasks) {
+      if (t.status !== 'running' || t.type === 'pty') continue;
+      const hb = t.workerId ? state.heartbeats[t.workerId] : null;
+      const workerAlive = hb && now - hb.at < 90 * 1000;
+      if (!workerAlive && t.startedAt && now - t.startedAt > STALE_RUNNING_MS) {
+        t.status = 'failed';
+        t.finishedAt = now;
+        t.result = { error: 'Worker 离线超时，任务被服务端回收' };
+        t.logs.push('[server] Worker 心跳超时，任务被标记为失败');
+        ctx.broadcast({ type: 'task.updated', task: ctx.taskSummary(t), result: t.result });
+        ctx.notifyIm(t, 'failed');
+      }
+    }
+  }
+
+  return { state, loadState, scheduleSave, flushSave, sweepStaleRunning };
+}

package/lib/summary.js

@@ -0,0 +1,29 @@
+/**
+ * 任务/Worker 摘要视图：WS 推送与 API 列表共用的只读投影。
+ */
+
+export function taskSummary(t) {
+  return {
+    id: t.id,
+    type: t.type,
+    title: t.title,
+    status: t.status,
+    createdAt: t.createdAt,
+    startedAt: t.startedAt,
+    finishedAt: t.finishedAt,
+    workerId: t.workerId,
+    targetWorker: t.targetWorker || null,
+    logCount: t.logs.length,
+  };
+}
+
+export function workersSnapshot(heartbeats) {
+  const now = Date.now();
+  return Object.entries(heartbeats).map(([id, hb]) => ({
+    workerId: id,
+    hostname: hb.hostname,
+    lastSeenAt: hb.at,
+    online: now - hb.at < 90 * 1000,
+    projects: hb.projects || [],
+  }));
+}

package/lib/util.js

@@ -0,0 +1,37 @@
+/**
+ * 服务端通用小工具：常量时间比较、JSON 响应、请求体解析、任务公开视图。
+ */
+
+import crypto from 'node:crypto';
+
+export function timingSafeEqualStr(a, b) {
+  const ha = crypto.createHash('sha256').update(String(a)).digest();
+  const hb = crypto.createHash('sha256').update(String(b)).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+export function json(res, code, body) {
+  const data = JSON.stringify(body);
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+  res.end(data);
+}
+
+export function parseBody(rawBody) {
+  if (!rawBody || !rawBody.length) return {};
+  try {
+    return JSON.parse(rawBody.toString('utf8'));
+  } catch {
+    const err = new Error('invalid json');
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+export function publicTask(task) {
+  // 浅拷贝切断与内部状态的引用别名，防止响应侧改动波及 state.tasks；
+  // 任务现有字段（含 logs/result/payload）均为控制台可见，无需裁剪
+  return { ...task };
+}

package/lib/websocket.js

@@ -0,0 +1,261 @@
+/**
+ * WebSocket 连接管理：/ws 控制台实时广播 + pty 终端输入上行；
+ * /worker/ws Worker 任务通知与 pty 会话 IO 中继。
+ * 鉴权走连接后的第一条消息（Token 不进 URL，不落日志）。
+ */
+
+import { WebSocketServer } from 'ws';
+import { workersSnapshot } from './summary.js';
+import { PTY_TAIL_BYTES } from './pty.js';
+
+// maxPayload：限制单帧 1MiB（pty 单帧输出/输入远小于此），
+// 杜绝默认 100MiB 大帧配合广播造成的内存放大
+const WS_OPTS = { noServer: true, maxPayload: 1024 * 1024 };
+
+export function createWebSockets(ctx) {
+  const wss = new WebSocketServer(WS_OPTS);
+
+  wss.on('connection', (ws, req) => {
+    const remote = req.socket.remoteAddress;
+    ws.isAuthed = false;
+    ws.isAlive = true;
+
+    // 连接后 5 秒内必须完成鉴权，否则关闭，防止裸连接占资源
+    const authTimer = setTimeout(() => ws.close(4001, 'auth timeout'), 5000);
+
+    ws.on('message', (raw) => {
+      if (!ws.isAuthed) {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch {
+          ws.close(4002, 'bad auth message');
+          return;
+        }
+        if (!msg || msg.type !== 'auth') {
+          ws.close(4002, 'bad auth message');
+          return;
+        }
+        // 签名鉴权：sig = HMAC(密钥, "WS\nTS\nNONCE")，同样走时间窗 + nonce 防重放；
+        // 控制台通道只认控制台密钥
+        const result = ctx.auth.verifySignature(
+          ['WS', String(msg.ts), String(msg.nonce)],
+          msg.ts,
+          msg.nonce,
+          msg.sig,
+          ctx.cfg.apiSecret,
+        );
+        if (!result.ok) {
+          console.warn(`[server] 拒绝 WS 连接，来源 ${remote}：${result.reason}`);
+          ws.close(4003, 'auth failed');
+          return;
+        }
+        clearTimeout(authTimer);
+        ws.isAuthed = true;
+        ctx.wsClients.add(ws);
+        // 鉴权通过立即下发全量快照，之后的增量靠 broadcast
+        ws.send(
+          JSON.stringify({
+            type: 'hello',
+            tasks: [...ctx.state.tasks].sort((a, b) => b.createdAt - a.createdAt).slice(0, 50).map(ctx.taskSummary),
+            workers: workersSnapshot(ctx.state.heartbeats),
+          }),
+        );
+        return;
+      }
+
+      // 鉴权后只受理 pty 终端交互消息，其余一律忽略
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg.taskId !== 'string') return;
+      const taskId = msg.taskId.slice(0, 64);
+
+      if (msg.type === 'pty.attach') {
+        // 打开终端：先补回看缓冲，再告知 Worker 侧会话是否仍活；
+        // 不活时附带 reason，控制台据此区分等待指引：
+        //   not_claimed   任务还在 pending，等 Worker 上线领取
+        //   worker_offline 会话在册但 Worker 通道断开，重连后自动重新挂载
+        //   starting      已领取但 session.started 未到（或已退出待 finish 上报）
+        //   ended         任务已终态或不存在，会话已结束/被回收
+        const s = ctx.ptySessions.get(taskId);
+        const live = Boolean(s && s.ws && s.ws.readyState === s.ws.OPEN);
+        let reason;
+        if (!live) {
+          if (s) {
+            reason = 'worker_offline';
+          } else {
+            const task = ctx.state.tasks.find((t) => t.id === taskId);
+            if (!task || ['done', 'failed', 'canceled'].includes(task.status)) reason = 'ended';
+            else if (task.status === 'pending') reason = 'not_claimed';
+            else reason = 'starting';
+          }
+        }
+        ctx.wsSendJson(ws, {
+          type: 'pty.attach',
+          id: taskId,
+          tail: s ? s.tail : '',
+          live,
+          reason,
+        });
+        return;
+      }
+      if (msg.type === 'session.input') {
+        const s = ctx.ptySessions.get(taskId);
+        if (!s) return ctx.wsSendJson(ws, { type: 'pty.exited', id: taskId, reason: '会话已结束' });
+        s.lastActiveAt = Date.now();
+        ctx.wsSendJson(s.ws, { type: 'session.input', taskId, data: String(msg.data || '').slice(0, 65536) });
+        return;
+      }
+      if (msg.type === 'session.resize') {
+        const s = ctx.ptySessions.get(taskId);
+        if (!s) return;
+        ctx.wsSendJson(s.ws, {
+          type: 'session.resize',
+          taskId,
+          cols: Number(msg.cols) || 80,
+          rows: Number(msg.rows) || 24,
+        });
+        return;
+      }
+      if (msg.type === 'session.close') {
+        const s = ctx.ptySessions.get(taskId);
+        if (s) ctx.wsSendJson(s.ws, { type: 'session.close', taskId });
+      }
+    });
+
+    ws.on('pong', () => {
+      ws.isAlive = true;
+    });
+    ws.on('close', () => {
+      clearTimeout(authTimer);
+      ctx.wsClients.delete(ws);
+    });
+    ws.on('error', () => {});
+  });
+
+  // --- Worker 通道 /worker/ws：鉴权方式同 /ws；鉴权后下发 task.available，
+  // 并承载 pty 会话上行消息（session.started/output/exited）---
+  const workerWss = new WebSocketServer(WS_OPTS);
+
+  workerWss.on('connection', (ws, req) => {
+    const remote = req.socket.remoteAddress;
+    ws.isAuthed = false;
+    ws.isAlive = true;
+
+    const authTimer = setTimeout(() => ws.close(4001, 'auth timeout'), 5000);
+
+    ws.on('message', (raw) => {
+      if (!ws.isAuthed) {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch {
+          ws.close(4002, 'bad auth message');
+          return;
+        }
+        if (!msg || msg.type !== 'auth') {
+          ws.close(4002, 'bad auth message');
+          return;
+        }
+        // Worker 通道只认 Worker 侧密钥：控制台密钥泄露不能冒充 Worker 领任务。
+        // 逐一尝试 WORKER_AUTH 条目；命中 workerSecrets 绑定密钥时身份以绑定
+        // 为准（自报 workerId 不一致即拒绝），共享密钥为兼容路径（身份自报）
+        let result = { ok: false, reason: '缺少签名头' };
+        let boundId = null;
+        for (const entry of ctx.cfg.workerAuth) {
+          result = ctx.auth.verifySignature(
+            ['WS', String(msg.ts), String(msg.nonce)],
+            msg.ts,
+            msg.nonce,
+            msg.sig,
+            entry.secret,
+          );
+          if (result.ok) {
+            boundId = entry.workerId;
+            break;
+          }
+        }
+        if (!result.ok) {
+          console.warn(`[server] 拒绝 Worker WS 连接，来源 ${remote}：${result.reason}`);
+          ws.close(4003, 'auth failed');
+          return;
+        }
+        clearTimeout(authTimer);
+        const claimedId = String(msg.workerId || 'unknown').slice(0, 128);
+        if (boundId && claimedId !== boundId) {
+          console.warn(
+            `[server] 拒绝 Worker WS 连接，来源 ${remote}：workerId "${claimedId}" 与密钥绑定身份 "${boundId}" 不一致`,
+          );
+          ws.close(4003, 'identity mismatch');
+          return;
+        }
+        ws.isAuthed = true;
+        ws.workerId = boundId || claimedId;
+        ctx.wsWorkers.add(ws);
+        console.log(`[server] Worker ${ws.workerId} 通道已连接（来源 ${remote}）`);
+        // 断线窗口内可能已有积压任务，连接建立即补一次通知（只推指名本 Worker 的）
+        if (ctx.state.tasks.some((t) => t.status === 'pending' && t.targetWorker === ws.workerId)) {
+          ws.send(JSON.stringify({ type: 'task.available' }));
+        }
+        return;
+      }
+
+      // --- pty 会话上行消息 ---
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg.taskId !== 'string') return;
+      const taskId = msg.taskId.slice(0, 64);
+      const task = ctx.state.tasks.find((t) => t.id === taskId);
+
+      if (msg.type === 'session.started') {
+        // 会话注册（含 Worker 通道重连后的重新挂载）；只认该 Worker 自己领取的任务
+        if (!task || task.type !== 'pty' || task.workerId !== ws.workerId) return;
+        const prev = ctx.ptySessions.get(taskId);
+        ctx.ptySessions.set(taskId, {
+          ws,
+          tail: prev ? prev.tail : '',
+          lastActiveAt: Date.now(),
+        });
+        ctx.broadcast({ type: 'pty.started', id: taskId, pid: Number(msg.pid) || 0 });
+        return;
+      }
+      if (msg.type === 'session.output') {
+        const s = ctx.ptySessions.get(taskId);
+        if (!s) return;
+        const data = String(msg.data || '');
+        s.lastActiveAt = Date.now();
+        s.tail = (s.tail + data).slice(-PTY_TAIL_BYTES); // 回看缓冲，重连可重放
+        ctx.broadcast({ type: 'pty.data', id: taskId, data });
+        return;
+      }
+      if (msg.type === 'session.exited') {
+        // 只清会话映射；任务终态由 Worker 随后的 HTTP finish 上报负责
+        ctx.closePtySession(taskId, {});
+      }
+    });
+
+    ws.on('pong', () => {
+      ws.isAlive = true;
+    });
+    ws.on('close', () => {
+      clearTimeout(authTimer);
+      ctx.wsWorkers.delete(ws);
+      // 该连接持有的会话置为游离：PTY 在 Worker 上还活着，重连后会重新挂载；
+      // 超过 ptyIdleSec 未重连则由 sweepPtyIdle 判失败
+      for (const [, s] of ctx.ptySessions) {
+        if (s.ws === ws) s.ws = null;
+      }
+    });
+    ws.on('error', () => {});
+  });
+
+  return { wss, workerWss };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacksontian/kite-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "kite 云端信箱 API：HMAC 签名鉴权、任务队列、WebSocket 实时推送、手机端 Web 控制台",
   "type": "module",
   "license": "MIT",
@@ -8,15 +8,25 @@
     "node": ">=24.0.0"
   },
   "bin": {
-    "kites": "server.js"
+    "kites": "bin/server.js"
   },
-  "main": "server.js",
+  "main": "bin/server.js",
   "scripts": {
-    "test": "node --test"
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node --test",
+    "cov": "c8 --reporter=text --reporter=html node --test"
+  },
+  "c8": {
+    "exclude": [
+      "**/test/**",
+      "web/vendor/**",
+      "**/*.config.js"
+    ]
   },
   "files": [
-    "server.js",
-    "config.js",
+    "bin/",
+    "lib/",
     "web/",
     "deploy/",
     "config.example.yaml"
@@ -37,5 +47,11 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^12.0.0",
+    "eslint": "^10.9.0",
+    "globals": "^17.11.0"
   }
 }