whistle.figma-cache 1.0.0

package/lib/revalidate.js

@@ -0,0 +1,246 @@
+'use strict';
+
+/**
+ * 后台静默校验（Stale-While-Revalidate）
+ *
+ * 命中缓存时会立刻把本地文件交给 Figma，同时（在有冷却期约束的前提下）
+ * 在后台对同一个 URL 发起一次**条件请求**，用返回结果静默更新缓存：
+ *
+ *   304 Not Modified  → 只刷新 validatedAt，传输量约 0.5 KB，几乎零成本
+ *   200 OK            → 内容真的变了 → 原子替换本地缓存
+ *   其它              → 丢弃，绝不动缓存
+ *
+ * 为什么用条件请求而不是直接重下：
+ *   Figma 的静态资源每次刷新都要重新下载数十 MB。若每次命中都重下，
+ *   流量直接翻倍。带 If-None-Match 之后，绝大多数请求只会产生一个 304。
+ *
+ * 安全护栏（任何一条不满足都不替换缓存）：
+ *   · 必须是 200 且通过 policy.checkResponse（非 HTML、无 Set-Cookie、非 no-store）
+ *   · Content-Type 必须与缓存中记录的完全一致
+ *     —— 这道护栏专门用来挡住「被重定向到登录页/错误页」把缓存写坏
+ *   · body 非空且不超过上限
+ *
+ * 所有后台请求都是 fire-and-forget，任何异常都被吞掉，绝不影响前台响应。
+ */
+
+const http = require('http');
+const https = require('https');
+const zlib = require('zlib');
+const { URL } = require('url');
+
+const store = require('./store');
+const policy = require('./policy');
+
+const MAX_CONCURRENCY = 4;
+const TIMEOUT_MS = 30000;
+const MAX_BODY_SIZE = 64 * 1024 * 1024;
+const USER_AGENT =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36';
+
+/** 正在校验或排队中的 key，避免同一资源被重复触发 */
+const inflight = new Set();
+const queue = [];
+let running = 0;
+
+/**
+ * 是否需要为这个条目安排后台校验
+ */
+function shouldRevalidate(key, meta, cfg) {
+  if (!cfg || cfg.revalidate === -1) {
+    return false; // 显式关闭
+  }
+  if (inflight.has(key)) {
+    return false;
+  }
+  if (key.indexOf('\u0000') !== -1) {
+    return false;
+  }
+  if (cfg.revalidate > 0) {
+    const last = Number(meta.validatedAt || meta.createdAt) || 0;
+    if (Date.now() - last < cfg.revalidate * 1000) {
+      return false; // 还在冷却期内
+    }
+  }
+  return true;
+}
+
+/**
+ * 安排一次后台校验（非阻塞）
+ * @returns {boolean} 是否真的安排了
+ */
+function schedule(key, url, meta, cfg) {
+  try {
+    if (!shouldRevalidate(key, meta, cfg)) {
+      return false;
+    }
+    inflight.add(key);
+    queue.push({ key, url, meta, cfg });
+    pump();
+    return true;
+  } catch (e) {
+    inflight.delete(key);
+    return false;
+  }
+}
+
+function pump() {
+  while (running < MAX_CONCURRENCY && queue.length) {
+    const task = queue.shift();
+    running += 1;
+    runTask(task, () => {
+      running -= 1;
+      inflight.delete(task.key);
+      pump();
+    });
+  }
+}
+
+function decodeBody(buf, contentEncoding) {
+  const enc = String(contentEncoding || '').toLowerCase().trim();
+  if (!enc || enc === 'identity') {
+    return buf;
+  }
+  try {
+    if (enc === 'gzip' || enc === 'x-gzip') {
+      return zlib.gunzipSync(buf);
+    }
+    if (enc === 'deflate') {
+      return zlib.inflateSync(buf);
+    }
+    if (enc === 'br') {
+      return zlib.brotliDecompressSync(buf);
+    }
+    if (enc === 'zstd' && typeof zlib.zstdDecompressSync === 'function') {
+      return zlib.zstdDecompressSync(buf);
+    }
+  } catch (e) {
+    return null;
+  }
+  return null; // 不认识的编码，宁可不缓存
+}
+
+function runTask(task, done) {
+  let finished = false;
+  const finish = () => {
+    if (finished) {
+      return;
+    }
+    finished = true;
+    done();
+  };
+
+  let u;
+  try {
+    u = new URL(task.url);
+  } catch (e) {
+    return finish();
+  }
+  // 生产路径上只会出现 https（policy 已经卡过），允许 http 仅为了可测
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') {
+    return finish();
+  }
+
+  const stored = (task.meta && task.meta.headers) || {};
+  const headers = {
+    // 关键：要求不压缩，这样拿到的字节与缓存里（whistle 解压后）的格式一致
+    'Accept-Encoding': 'identity',
+    'User-Agent': USER_AGENT,
+    Accept: '*/*'
+  };
+  if (stored.etag) {
+    headers['If-None-Match'] = stored.etag;
+  }
+  if (stored['last-modified']) {
+    headers['If-Modified-Since'] = stored['last-modified'];
+  }
+
+  let req;
+  try {
+    const mod = u.protocol === 'http:' ? http : https;
+    req = mod.request(
+      {
+        protocol: u.protocol,
+        hostname: u.hostname,
+        port: u.port || (u.protocol === 'http:' ? 80 : 443),
+        path: u.pathname + (u.search || ''),
+        method: 'GET',
+        headers,
+        // 后台请求直连源站，故意不走 whistle 的规则链，避免自己拦自己
+        agent: false
+      },
+      (res) => {
+        const status = res.statusCode || 0;
+
+        // 304：内容没变，只刷新校验时间
+        if (status === 304) {
+          res.resume();
+          store.touchValidation(task.key);
+          return finish();
+        }
+
+        if (status !== 200) {
+          res.resume();
+          return finish();
+        }
+
+        const chunks = [];
+        let size = 0;
+        let aborted = false;
+        res.on('data', (chunk) => {
+          size += chunk.length;
+          if (size > MAX_BODY_SIZE) {
+            aborted = true;
+            res.destroy();
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on('error', () => {
+          aborted = true;
+          finish();
+        });
+        res.on('end', () => {
+          if (aborted) {
+            return finish();
+          }
+
+          const raw = Buffer.concat(chunks);
+          const body = decodeBody(raw, res.headers['content-encoding']);
+          if (!body || !body.length) {
+            return finish();
+          }
+
+          // ── 护栏：任何一条不满足都不动缓存 ──
+          if (!policy.checkResponse(status, res.headers).ok) {
+            return finish();
+          }
+          const newType = String(res.headers['content-type'] || '');
+          const oldType = String(task.meta.contentType || '');
+          if (oldType && newType.split(';')[0].trim() !== oldType.split(';')[0].trim()) {
+            // 类型变了 → 很可能是被重定向到了登录页/错误页，宁可不动
+            return finish();
+          }
+
+          // 计数由 store.replaceBody / store.touchValidation 内部按 304 / 200 分别累加
+          store.replaceBody(task.key, task.url, body, res.headers);
+          return finish();
+        });
+      }
+    );
+  } catch (e) {
+    return finish();
+  }
+
+  req.setTimeout(TIMEOUT_MS, () => {
+    try {
+      req.destroy();
+    } catch (e) {
+      /* ignore */
+    }
+    finish();
+  });
+  req.on('error', () => finish());
+  req.end();
+}
+
+module.exports = { schedule, inflight, queue };

package/lib/rulesServer.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * rulesServer hook —— 对应 whistle 的 REQ_RULES 钩子（请求阶段）
+ *
+ * whistle 在请求发出前会问我们一句：「这条请求你想加什么规则？」
+ * 我们据此给出两种回答：
+ *
+ *   命中磁盘 →  file://<body 文件>                 让 whistle 直接从本地回放，零网络
+ *   未命中   →  resWrite://<body 文件>             让 whistle 照常回源，顺手把响应落盘
+ *   不该管   →  返回空字符串                       完全不受影响
+ *
+ * 这里返回的是「规则文本」，由 whistle 自己执行 —— 所以本插件不需要接管请求、
+ * 不需要 MITM、不需要独立端口，生命周期天然跟随插件启停。
+ *
+ * 安全：任何异常都必须返回空字符串（放行），绝不阻断请求。
+ */
+
+const config = require('./config');
+const policy = require('./policy');
+const store = require('./store');
+const revalidate = require('./revalidate');
+
+/**
+ * 取本次请求的真实 URL
+ * whistle 的 setContext 会把 fullUrl / realUrl 挂在 req 上
+ */
+function fullUrlOf(req) {
+  const oReq = req.originalReq || {};
+  return oReq.realUrl || req.fullUrl || oReq.url || '';
+}
+
+function toSlash(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+function reply(res, text) {
+  const body = Buffer.from(text || '', 'utf8');
+  try {
+    res.writeHead(200, {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Content-Length': String(body.length)
+    });
+  } catch (e) {
+    /* ignore */
+  }
+  res.end(body);
+}
+
+/**
+ * 命中：让 whistle 用本地文件直接回放。
+ * 注意 `* ` 前缀：whistle 的插件钩子返回的是「完整规则行」，
+ * 缺少匹配模式时会被当成 pattern 而不是操作符，规则不会生效。
+ */
+/**
+ * 把存储下来的 Content-Type 映射成 whistle 的 resType 短名。
+ * 必须显式指定：因为 whistle 的 file:// 是按「文件扩展名」猜 MIME 的，
+ * 而 static.figma.com/uploads/<hash> 这类地址本身没有扩展名，会猜成 text/html。
+ * resType 的值不能带空格（规则文本按空白分词），所以只能用它而不是 resHeaders。
+ */
+const RESTYPE_BY_CT = [
+  [/javascript|ecmascript/i, 'js'],
+  [/text\/css/i, 'css'],
+  [/json/i, 'json'],
+  [/html/i, 'html'],
+  [/xml/i, 'xml']
+];
+
+function resTypeOf(contentType) {
+  const ct = String(contentType || '');
+  for (const [re, type] of RESTYPE_BY_CT) {
+    if (re.test(ct)) {
+      return type;
+    }
+  }
+  return '';
+}
+
+function hitRule(dir, contentType) {
+  const rt = resTypeOf(contentType);
+  // 传目录（以 / 结尾），让 whistle 自己拼接剩余路径
+  const parts = ['*', 'file://' + toSlash(dir) + '/'];
+  if (rt) {
+    parts.push('resType://' + rt);
+  }
+  // 关键：让 Chromium 也把这些资源存进它自己的缓存。
+  // 否则响应没有 Cache-Control，Chromium 不会缓存 -> 也就不会生成 code cache，
+  // 每次加载都要把几十 MB JS/WASM 重新解析编译一遍（实测 5 分钟重写 109MB WASM 缓存）。
+  parts.push('cache://31536000');
+  return parts.join(' ');
+}
+
+/**
+ * 未命中：让 whistle 回源并把响应体写到指定文件。
+ *
+ * 注意两个规则前面的 `* `：whistle 的插件钩子返回的是「完整规则行」，
+ * 形如 `模式 操作符://值`。单 token 的行会被当成 pattern（请求 URL 的匹配
+ * 表达式）而不是操作符，规则会静默失效 —— 这是踩过的坑。
+ * 这里只要一个通配模式就够了，因为插件规则只会合并进当前这一个请求。
+ */
+function missRule(dir) {
+  // 同样传目录：whistle 会把 URL 的剩余路径接到后面
+  return '* resWrite://' + toSlash(dir) + '/';
+}
+
+module.exports = (server) => {
+  server.on('request', (req, res) => {
+    let ruleText = '';
+
+    try {
+      const oReq = req.originalReq || {};
+      const url = fullUrlOf(req);
+      const cfg = config.resolveConfig(oReq.ruleValue);
+      store.use(cfg);
+
+      // ── 闸门 1：请求形态 ────────────────────────────────────────────
+      const method = oReq.method || 'GET';
+      const reqHeaders = oReq.headers || req.headers || {};
+      if (!policy.isSafeRequest({ method, headers: reqHeaders })) {
+        store.bump('bypass');
+        return reply(res, '');
+      }
+
+      // ── 闸门 2：URL 白名单 ─────────────────────────────────────────
+      const verdict = policy.checkUrl(url);
+      if (!verdict.ok) {
+        store.bump('bypass');
+        config.log(cfg, 'BYPASS(%s)  %s', verdict.reason, url);
+        return reply(res, '');
+      }
+
+      const key = store.keyOf(url);
+
+      // ── 命中 ───────────────────────────────────────────────────────
+      const hit = store.lookup(key, url, cfg);
+      if (hit) {
+        // 后台静默校验（非阻塞、有冷却期约束）；任何失败都不影响本次响应
+        try {
+          revalidate.schedule(key, url, hit.meta, cfg);
+        } catch (e) {
+          /* ignore */
+        }
+        config.log(cfg, 'HIT   %s KB  %s', Math.round(hit.size / 1024), url);
+        return reply(res, hitRule(hit.dir, hit.meta && hit.meta.contentType));
+      }
+
+      // ── 未命中：登记落盘意向，让 whistle 回源并顺手写盘 ─────────────
+      store.bump('miss');
+      const pending = store.beginPending(key, url, cfg);
+      config.log(cfg, 'MISS  %s', url);
+      return reply(res, missRule(pending.dir));
+    } catch (e) {
+      // 出任何问题都放行，绝不阻断
+      return reply(res, ruleText);
+    }
+  });
+};