annotatable-html 0.0.0-stage → 1.38.3

package/lib/serve.js

@@ -0,0 +1,293 @@
+'use strict';
+/* annotatable serve —— 本地伴随服务器
+ * 静态伺服目录 + 受控写回端点，让可批注 HTML 在 localhost 上获得
+ * 零点击、零授权的全自动保存（同源 POST，仅监听 127.0.0.1）。 */
+
+var http = require('http');
+var fs = require('fs');
+var path = require('path');
+var os = require('os');
+var core = require('./core');   /* v1.26.0：saveDocHtml（锁内 rev 复验+原子写+记票）与 readSideHist（/__annot/hist） */
+
+var MIME = {
+  '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8', '.json': 'application/json',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.svg': 'image/svg+xml', '.ico': 'image/x-icon',
+  '.md': 'text/plain; charset=utf-8'
+};
+
+/* 防本机 CSRF：仅接受 JSON content-type（跨站简单请求会被此拦下），
+   且 Origin 若存在必须为空（file://）或 localhost */
+function sameOriginGuard(req, res) {
+  var ct = (req.headers['content-type'] || '');
+  var og = (req.headers['origin'] || 'null');
+  if (ct.indexOf('application/json') === -1) { res.writeHead(403); res.end('bad content-type'); return false; }
+  if (og !== 'null' && og.indexOf('http://localhost') !== 0 && og.indexOf('http://127.0.0.1') !== 0) { res.writeHead(403); res.end('bad origin'); return false; }
+  return true;
+}
+/* 根目录边界校验与请求路径解析（withinRoot/safeServePath 在 start() 内定义——root 是每次启动的伺服根） */
+function readJsonBody(req, res, cap, cb) {
+  /* v1.28.1：必须按 Buffer 累积、end 时整体解码——旧写法对每个 chunk 独立 toString，
+     多字节 UTF-8 字符恰跨 chunk 边界即被打成 U+FFFD（调研页批语「划线」变「���」、
+     模板装饰 ═══ 变乱码实证；打中中文批注文本=静默数据腐蚀）。cap 按字节计。 */
+  var chunks = [], total = 0, dead = false;
+  req.on('data', function (c) {
+    if (dead) return;
+    chunks.push(c); total += c.length;
+    if (total > cap) { dead = true; req.destroy(); }
+  });
+  req.on('end', function () {
+    if (dead) return;
+    try { cb(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+    catch (e) { res.writeHead(400); res.end(String(e.message || e)); }
+  });
+}
+
+/* 探测占用者是不是自家 serve（POST /__annot/ping 应 pong）；1s 超时/连不上按「不是」处理 */
+function probeSelf(port, cb) {
+  var req = http.request({ host: '127.0.0.1', port: port, path: '/__annot/ping', method: 'POST', timeout: 1000 }, function (res) {
+    var b = '';
+    res.on('data', function (c) { b += c; });
+    res.on('end', function () { cb(b.indexOf('pong') !== -1); });
+  });
+  req.on('timeout', function () { req.destroy(); cb(false); });
+  req.on('error', function () { cb(false); });
+  req.end();
+}
+
+function start(root, port, opts) {
+  root = path.resolve(root || process.cwd());
+  if (port === undefined || port === null || port === '' || isNaN(port)) port = 8973;   // --port 0 = 系统挑空闲端口，是合法值别当缺省吞掉
+  var studioProvider = opts && typeof opts.studioProvider === 'function' ? opts.studioProvider : null;
+
+  /* 根目录边界校验：resolve 后必须仍落在伺服根内（防 ../ 越界） */
+  function withinRoot(p) {
+    return p === root || p.indexOf(root + path.sep) === 0;
+  }
+  /* 请求路径 → 伺服根内绝对路径；越界返回 null */
+  function safeServePath(rel) {
+    var p = path.resolve(root, '.' + rel);
+    return withinRoot(p) ? p : null;
+  }
+
+  var server = http.createServer(function (req, res) {
+    var u;
+    try { u = decodeURIComponent(req.url.split('?')[0]); } catch (e) { res.writeHead(400); res.end('bad url'); return; }
+
+    /* 心跳探测：页面据此判断处于服务器模式 */
+    if (req.method === 'POST' && u === '/__annot/ping') { res.writeHead(200); res.end('pong'); return; }
+
+    /* live-sync 探测（v1.21.0）：页面轮询本端点拿 rev/mtime，文件变了才热载，
+       免去每秒全文拉取。路径先过 safeServePath 边界校验，再限 .html。 */
+    if (req.method === 'GET' && u === '/__annot/rev') {
+      var qs;
+      try { qs = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e0) { qs = ''; }
+      try { qs = decodeURIComponent(qs); } catch (e1) { /* 保持原样 */ }
+      var rfp = safeServePath(qs);
+      if (!rfp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(rfp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      fs.readFile(rfp, 'utf8', function (re1, txt) {
+        if (re1) { res.writeHead(404); res.end('not found'); return; }
+        var rm = txt.match(/"rev"\s*:\s*(\d+)/);
+        var replyRev = function (st) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ rev: rm ? parseInt(rm[1], 10) : 0, mtime: st ? st.mtimeMs : 0, size: st ? st.size : txt.length }));
+        };
+        fs.stat(rfp, function (re3, st) { replyRev(re3 ? null : st); });
+      });
+      return;
+    }
+
+    /* 值守心跳查询（v1.33.0，issue#6）：读 .annotatable/<file>.watch.json 报 watcher 存活与心跳年龄。
+       只读端点；路径过 safeServePath 边界校验再限 .html，与 /__annot/rev 同一边界面。
+       页面值守灯据此渲染 在岗/心跳超龄/换班中/无人值守，让人在朝深渊喊话前先看见灯是红的。 */
+    if (req.method === 'GET' && u === '/__annot/status') {
+      var ws0;
+      try { ws0 = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e4) { ws0 = ''; }
+      try { ws0 = decodeURIComponent(ws0); } catch (e5) { /* 保持原样 */ }
+      var wsp = safeServePath(ws0);
+      if (!wsp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(wsp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      var replyStatus = function (o) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(o));
+      };
+      fs.readFile(path.join(path.dirname(wsp), '.annotatable', path.basename(wsp) + '.watch.json'), 'utf8', function (we4, wt4) {
+        if (we4) { replyStatus({ watching: false, state: 'none', ageSec: -1 }); return; }
+        try {
+          var wj = JSON.parse(wt4);
+          replyStatus({
+            watching: wj.state === 'watching',
+            state: wj.state || 'none',
+            ageSec: Math.max(0, Math.round((Date.now() - (wj.lastBeat || 0)) / 1000)),
+            pid: wj.pid || 0, startedAt: wj.startedAt || 0
+          });
+        } catch (e6) { replyStatus({ watching: false, state: 'none', ageSec: -1 }); }   // 撕裂心跳 ≈ 无心跳，按保守渲染
+      });
+      return;
+    }
+
+    /* 主题工坊页（v1.17.0）：仅 annotatable studio 启动时提供，内存直出不落盘 */
+    if (req.method === 'GET' && u === '/__annot/studio') {
+      if (!studioProvider) { res.writeHead(404); res.end('studio 未随 annotatable studio 启动'); return; }
+      try {
+        res.writeHead(200, { 'Content-Type': MIME['.html'] });
+        res.end(studioProvider());
+      } catch (e) { res.writeHead(500); res.end(String(e.message || e)); }
+      return;
+    }
+
+    /* 主题工坊保存（v1.17.0）：仅两种固定目标（伺服根目录 / ~/.annotatable），
+       文件名服务端写死，无路径遍历面 */
+    if (req.method === 'POST' && u === '/__annot/theme') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 2 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.css !== 'string' || (o.css && o.css.indexOf('\x00') !== -1)) throw new Error('bad payload');
+          if (o.css.length > 1024 * 1024) throw new Error('css 过大');
+          var target = o.scope === 'global'
+            ? path.join(os.homedir(), '.annotatable', 'annotatable.theme.css')
+            : path.join(root, 'annotatable.theme.css');
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, o.css);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, path: target }));
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* 受控写回：仅伺服目录内、仅 .html，防路径越界 */
+    if (req.method === 'POST' && u === '/__annot/save') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 20 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.path !== 'string' || typeof o.html !== 'string') throw new Error('bad payload');
+          var rel = o.path;
+          try { rel = decodeURIComponent(rel); } catch (e0) { /* 保持原样 */ }   // location.pathname 是百分号编码，中文文件名须解码
+          var target = path.resolve(root, '.' + rel);
+          if (target !== root && target.indexOf(root + path.sep) !== 0) throw new Error('路径越界');
+          if (!/\.html?$/i.test(target)) throw new Error('只允许写入 .html');
+          if (!fs.existsSync(target)) throw new Error('目标文件不在伺服目录中');
+          /* v1.26.0：rev 复验 + 文档锁 + 原子写 + 写票（saveDocHtml 内部完成）。
+             baseRev 缺省 = 老页面，跳过校验按现状放行；rev 不符 → 409+diskRev，
+             浏览器收到后自动重基合并重试（serverSaveNow 的 409 分支）。 */
+          var sr = core.saveDocHtml(target, o.html, (typeof o.rev === 'number' ? o.rev : null), 'serve');
+          if (!sr.ok) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'rev-conflict', diskRev: sr.diskRev }));
+            return;
+          }
+          res.writeHead(200); res.end('saved');
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* v1.26.0 读侧车账本（修待改进⑬半边）：serve 模式页面的「回退恢复原文」/回滚
+       由此取历史快照（FS Access 模式浏览器直读 .annotatable/，不走这里）。
+       只读、限伺服目录内 .html，core.histForFile 内部按 DOC_ID 归属校验防互染。 */
+    if (req.method === 'GET' && u === '/__annot/hist') {
+      var hq;
+      try { hq = new URL('http://x' + req.url).searchParams.get('path') || ''; } catch (e1) { hq = ''; }
+      try { hq = decodeURIComponent(hq); } catch (e2) { /* 保持原样 */ }
+      var hfp = safeServePath(hq);
+      if (!hfp) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!/\.html?$/i.test(hfp)) { res.writeHead(403); res.end('只允许查询 .html'); return; }
+      try {
+        var hj = JSON.stringify(core.histForFile(hfp));   // 先算后写头：histForFile 抛错（如坏路径 ENOENT）走 404，不打崩 serve
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(hj);
+      } catch (e3) {
+        if (!res.headersSent) { res.writeHead(404); res.end('not found'); } else res.end();
+      }
+      return;
+    }
+
+    /* v1.31.0 写侧车账本（serve 页面档案缺失收口）：此前 serve 模式只读不写，浏览器保存的
+       全量历史（含批注层快照/大纸条）无处落盘——版本历史面板「缺批注层快照」、回滚残废。
+       与读端点对称：限伺服目录内 .html；锁内 DOC_ID/文件名归属校验防互染
+       （core.writeHistForFile 内部完成，不符退 409），条数按盘上 store.histCaps 收敛。 */
+    if (req.method === 'POST' && u === '/__annot/hist') {
+      if (!sameOriginGuard(req, res)) return;
+      readJsonBody(req, res, 20 * 1024 * 1024, function (o) {
+        try {
+          if (!o || typeof o.path !== 'string' || !o.hist || typeof o.hist !== 'object') throw new Error('bad payload');
+          var grel = o.path;
+          try { grel = decodeURIComponent(grel); } catch (e0) { /* 保持原样 */ }
+          var gtarget = path.resolve(root, '.' + grel);
+          if (gtarget !== root && gtarget.indexOf(root + path.sep) !== 0) throw new Error('路径越界');
+          if (!/\.html?$/i.test(gtarget)) throw new Error('只允许写 .html 的档案');
+          if (!fs.existsSync(gtarget)) throw new Error('目标文件不在伺服目录中');
+          var gr = core.writeHistForFile(gtarget, o.hist);
+          if (!gr.ok) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: gr.error }));
+            return;
+          }
+          res.writeHead(200); res.end('hist-saved');
+        } catch (e) {
+          res.writeHead(400); res.end(String(e.message || e));
+        }
+      });
+      return;
+    }
+
+    /* 静态伺服（限制在 root 内） */
+    var rel = u.replace(/^\/+/, '');
+    var fp = rel ? path.resolve(root, rel) : root;
+    if (fp !== root && fp.indexOf(root + path.sep) !== 0) { res.writeHead(403); res.end('forbidden'); return; }
+    fs.stat(fp, function (err, st) {
+      if (!err && st.isDirectory()) fp = path.join(fp, 'index.html');
+      fs.readFile(fp, function (err2, data) {
+        if (err2) { res.writeHead(404); res.end('not found'); return; }
+        res.writeHead(200, { 'Content-Type': MIME[path.extname(fp).toLowerCase()] || 'application/octet-stream' });
+        res.end(data);
+      });
+    });
+  });
+
+  /* v1.26.1：一个坏请求/边角 bug 不再打死整个 serve（值守生命线）——记日志继续伺服。
+     代价：出异常的那条响应可能挂到浏览器超时重试，可接受；无此守卫时进程直接退出，全部自动保存失联。 */
+  process.on('uncaughtException', function (err) {
+    console.error('[' + new Date().toISOString() + '] serve 吞掉未捕获异常（继续伺服）: ' + ((err && err.stack) || err));
+  });
+
+  /* v1.27.1：绑定失败必须说实话。此前 EADDRINUSE 没挂 error 监听，异常落进上面的
+     uncaughtException 兜底、嘴上打印「继续伺服」，实际服务器从未 bind 成功、事件循环
+     清空后进程静默退出——值守以为活着，自动保存全失联。现如实报错并探测占用者身份后退出。 */
+  server.on('error', function (e) {
+    var code = (e && e.code) || 'UNKNOWN';
+    if (code !== 'EADDRINUSE') {
+      console.error('❌ serve 端口监听失败（' + code + '）：' + ((e && e.message) || e));
+      process.exit(1);
+      return;
+    }
+    console.error('❌ 端口 ' + port + ' 已被占用，serve 没有启动。');
+    probeSelf(port, function (isAnnot) {
+      if (isAnnot) {
+        console.error('   占用者就是另一个 annotatable serve——多半是上次值守/演示没停干净的孤儿进程（HANDOFF 已知坑）。');
+        console.error('   处置二选一：直接复用现有 http://localhost:' + port + '；');
+        console.error('             或 netstat -ano | findstr ":' + port + '" 查 PID 后 taskkill //F //PID <pid>，再重启。');
+      } else {
+        console.error('   处置二选一：换端口重启（--port <其他>，或 --port 0 让系统挑空闲端口）；');
+        console.error('             或 netstat -ano | findstr ":' + port + '" 查占用者 PID，确认不要就 taskkill //F //PID <pid>。');
+      }
+      process.exit(1);
+    });
+  });
+
+  return new Promise(function (resolve) {
+    server.listen(port, '127.0.0.1', function () {
+      var actual = (server.address() && server.address().port) || port;   // --port 0 时以系统实配为准
+      resolve({ url: 'http://localhost:' + actual, root: root, port: actual });
+    });
+  });
+}
+
+module.exports = { start: start };