whistle.figma-cache 1.0.0

package/lib/config.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * 配置解析
+ *
+ * 默认配置写死在代码里，rules.txt 里不带任何参数即可工作（零配置）。
+ * 如需调整，可在 Rules 面板追加一条更高优先级的规则覆盖，例如：
+ *
+ *   www.figma.com/webpack-artifacts/  figma-cache://ttl=0,maxSize=8192,log=1
+ *
+ * 支持的参数：
+ *   dir          缓存目录（绝对路径），默认 <插件目录>/data/cache
+ *   ttl          缓存有效期，如 0 / 3600 / 30d / 12h；0 表示永不过期（默认）
+ *                URL 内含内容哈希，语义上不可变，所以默认永不过期
+ *   maxSize      缓存总量上限，单位 MB，默认 4096
+ *   maxFileSize  单个文件缓存上限，单位 MB，默认 64
+ *   revalidate   后台静默校验的冷却期，默认 24h；0 = 每次命中都校验；-1 = 关闭
+ *   log          1 时在 Whistle 插件控制台打印 HIT/MISS/STORE 日志，默认 0
+ */
+
+const path = require('path');
+
+const PLUGIN_ROOT = path.join(__dirname, '..');
+
+const DEFAULTS = {
+  dir: path.join(PLUGIN_ROOT, 'data', 'cache'),
+  ttl: 0,
+  maxSize: 4096,
+  maxFileSize: 64,
+  revalidate: 86400,
+  bodySettleMs: 500,
+  log: 0
+};
+
+/**
+ * 解析形如 "ttl=30d,maxSize=8192" 的参数串
+ */
+function parseParams(value) {
+  const out = {};
+  if (!value) {
+    return out;
+  }
+  String(value)
+    .split(/[,;]/)
+    .forEach((seg) => {
+      const idx = seg.indexOf('=');
+      if (idx <= 0) {
+        return;
+      }
+      const key = seg.slice(0, idx).trim();
+      const val = seg.slice(idx + 1).trim();
+      if (key) {
+        out[key] = val;
+      }
+    });
+  return out;
+}
+
+/**
+ * 把 "30d" / "12h" / "600" 转成秒；非法值返回 fallback
+ */
+function toSeconds(input, fallback) {
+  if (input == null || input === '') {
+    return fallback;
+  }
+  const m = /^(\d+(?:\.\d+)?)\s*(s|m|h|d|w)?$/i.exec(String(input).trim());
+  if (!m) {
+    return fallback;
+  }
+  const n = parseFloat(m[1]);
+  if (!isFinite(n) || n < 0) {
+    return fallback;
+  }
+  const unit = (m[2] || 's').toLowerCase();
+  const factor = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 }[unit] || 1;
+  return Math.round(n * factor);
+}
+
+function toPositiveNumber(input, fallback) {
+  const n = parseFloat(input);
+  return isFinite(n) && n > 0 ? n : fallback;
+}
+
+/** 毫秒参数（允许 0） */
+function toMillis(input, fallback) {
+  if (input == null || input === '') {
+    return fallback;
+  }
+  const n = parseFloat(input);
+  return isFinite(n) && n >= 0 ? n : fallback;
+}
+
+/**
+ * 后台校验冷却期。
+ *   86400 / 24h / 1d → 同一资源 24 小时内最多校验一次（默认）
+ *   0                → 每次命中都校验
+ *   -1 / off         → 完全关闭后台校验
+ */
+function toRevalidate(input, fallback) {
+  if (input == null || input === '') {
+    return fallback;
+  }
+  const s = String(input).trim().toLowerCase();
+  if (s === '-1' || s === 'off' || s === 'false' || s === 'no' || s === 'none') {
+    return -1;
+  }
+  return toSeconds(s, fallback);
+}
+
+const cacheByValue = new Map();
+
+/**
+ * 根据 ruleValue 得到生效配置（带缓存，避免每次请求重复解析）
+ */
+function resolveConfig(ruleValue) {
+  const raw = ruleValue == null ? '' : String(ruleValue);
+  if (cacheByValue.has(raw)) {
+    return cacheByValue.get(raw);
+  }
+
+  const p = parseParams(raw);
+  const cfg = {
+    dir: p.dir ? path.resolve(p.dir) : DEFAULTS.dir,
+    ttl: toSeconds(p.ttl, DEFAULTS.ttl),
+    maxSize: toPositiveNumber(p.maxSize, DEFAULTS.maxSize),
+    maxFileSize: toPositiveNumber(p.maxFileSize, DEFAULTS.maxFileSize),
+    revalidate: toRevalidate(p.revalidate, DEFAULTS.revalidate),
+    bodySettleMs: toMillis(p.bodySettle, DEFAULTS.bodySettleMs),
+    log: String(p.log || '0') === '1' || String(p.log || '').toLowerCase() === 'true'
+  };
+
+  cacheByValue.set(raw, cfg);
+  return cfg;
+}
+
+/**
+ * 轻量日志（只在 log=1 时输出）。用 console.log 可被 Whistle 写入插件控制台。
+ */
+function log(cfg, ...args) {
+  if (!cfg || !cfg.log) {
+    return;
+  }
+  try {
+    // eslint-disable-next-line no-console
+    console.log('[figma-cache]', ...args);
+  } catch (e) {
+    /* ignore */
+  }
+}
+
+module.exports = {
+  PLUGIN_ROOT,
+  DEFAULTS,
+  resolveConfig,
+  parseParams,
+  toSeconds,
+  log
+};

package/lib/policy.js

@@ -0,0 +1,237 @@
+'use strict';
+
+/**
+ * 缓存准入策略 —— 本插件的【安全核心】
+ *
+ * 设计原则：
+ *   1. 白名单，不是黑名单。只有明确认定「内容哈希命名、永远不可变」的
+ *      URL 才允许进入缓存，其余一律放行给 Whistle 原生流程。
+ *   2. 这是一道独立于 rules.txt 的第二道闸门。即使规则被误改成
+ *      www.figma.com/ 这种宽匹配，只要 URL 不满足白名单，也不会被缓存。
+ *   3. 涉及画布 / 文件内容 / 接口 / 签名地址的请求，一律硬性拒绝。
+ *
+ * 【绝对不能缓存的东西】
+ *   · 画布与文件数据：/file/、/design/、/board/、/proto/、/multiplayer
+ *   · 接口：/api/、/graphql
+ *   · 用户内容素材：s3-alpha.figma.com、s3-alpha-sig.figma.com、*.amazonaws.com
+ *   · 带查询串的地址（签名 token、缓存破坏参数）
+ *   · 非 GET 请求、WebSocket 升级请求
+ *   · 非 200 响应、带 Set-Cookie 的响应、Cache-Control 含 no-store/private
+ */
+
+// ── 可缓存白名单 ───────────────────────────────────────────────────────────
+// host 必须精确匹配，path 必须满足「文件名内含足够长的十六进制哈希」
+const ALLOW = [
+  {
+    name: 'figma-editor-bundle',
+    // 例：/webpack-artifacts/assets/vendor-1d532d39d96c5d27.min.js.br
+    //     /webpack-artifacts/assets/3866-6a39a297e15317ca.min.js.br
+    host: /^(?:www\.)?figma\.com$/i,
+    path: /^\/webpack-artifacts\/assets\/[A-Za-z0-9._$-]+-[0-9a-f]{8,}\.(?:min\.)?(?:js|mjs|css|json|wasm)(?:\.(?:br|gz))?$/i
+  },
+  {
+    name: 'figma-static-cdn',
+    // 仅放行已验证存在的 /uploads/<内容哈希> 路径。
+    // 例：/uploads/<40 位内容哈希>，响应头 cache-control: max-age=31536000
+    //
+    // 如需放行其它路径（如 /fonts/、/fullscreen/），请先用下面命令确认
+    // 该路径确实带长缓存头且文件名含内容哈希，再往这里加：
+    //   curl -sSI https://static.figma.com/xxx | grep -i cache-control
+    host: /^static\.figma\.com$/i,
+    path: /^\/uploads\/[0-9a-f]{32,}(?:\.[A-Za-z0-9]+)?$/i
+  }
+];
+
+// ── 硬性拒绝：域名（画布素材 / 用户内容 / 签名地址）────────────────────────
+const DENY_HOST = [
+  /(^|\.)s3-alpha\.figma\.com$/i,
+  /(^|\.)s3-alpha-sig\.figma\.com$/i,
+  /(^|\.)s3-downtime\.figma\.com$/i,
+  /(^|\.)api\.figma\.com$/i,
+  /(^|\.)amazonaws\.com$/i,
+  /(^|\.)cloudfront\.net$/i,
+  /(^|\.)figma-alpha-api\./i
+];
+
+// ── 硬性拒绝：路径关键字（画布 / 文件 / 接口 / 实时协作）──────────────────
+const DENY_PATH = [
+  '/api/',
+  '/graphql',
+  '/file/',
+  '/design/',
+  '/board/',
+  '/proto/',
+  '/multiplayer',
+  '/render/',
+  '/export/',
+  '/__/',
+  '/v1/'
+];
+
+// ── 存储哪些响应头 ─────────────────────────────────────────────────────────
+const HEADER_KEEP = [
+  'content-type',
+  'content-encoding',
+  'cache-control',
+  'etag',
+  'last-modified',
+  'vary',
+  'content-language',
+  'access-control-allow-origin'
+];
+
+// 命中后重新下发的缓存时长（一年）—— 让 Chromium 也一起缓存，形成双层
+const REPLAY_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+
+/**
+ * 请求本身是否适合缓存
+ */
+function isSafeRequest(req) {
+  if (!req || req.method !== 'GET') {
+    return false;
+  }
+  const h = req.headers || {};
+  // WebSocket / HTTP Upgrade 一律不碰
+  if (h.upgrade || h['sec-websocket-key'] || h['sec-websocket-version']) {
+    return false;
+  }
+  // 明确要求不走缓存的请求，尊重它
+  const cc = String(h['cache-control'] || '').toLowerCase();
+  if (cc.indexOf('no-store') !== -1) {
+    return false;
+  }
+  // 分段请求（媒体拖动进度等）不缓存，避免把 206 或半截内容当成完整资源
+  if (h.range) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * URL 是否在白名单内
+ * @returns {{ok: boolean, reason: string, rule?: string}}
+ */
+function checkUrl(rawUrl) {
+  if (!rawUrl || typeof rawUrl !== 'string') {
+    return { ok: false, reason: 'empty-url' };
+  }
+
+  let u;
+  try {
+    u = new URL(rawUrl);
+  } catch (e) {
+    return { ok: false, reason: 'invalid-url' };
+  }
+
+  if (u.protocol !== 'https:') {
+    return { ok: false, reason: 'not-https' };
+  }
+
+  // 任何查询串都不缓存：签名地址 / 带 token / 缓存破坏参数都在这里被拦掉
+  if (u.search && u.search.length > 1) {
+    return { ok: false, reason: 'has-query' };
+  }
+
+  const host = u.hostname.toLowerCase();
+  const path = u.pathname;
+
+  if (DENY_HOST.some((re) => re.test(host))) {
+    return { ok: false, reason: 'deny-host' };
+  }
+
+  const lowerPath = path.toLowerCase();
+  const hitDeny = DENY_PATH.find((seg) => lowerPath.indexOf(seg) !== -1);
+  if (hitDeny) {
+    return { ok: false, reason: 'deny-path:' + hitDeny };
+  }
+
+  const rule = ALLOW.find((r) => r.host.test(host) && r.path.test(path));
+  if (!rule) {
+    return { ok: false, reason: 'not-allowlisted' };
+  }
+
+  return { ok: true, reason: 'allow', rule: rule.name };
+}
+
+/**
+ * 响应是否适合落盘
+ * @returns {{ok: boolean, reason: string}}
+ */
+function checkResponse(statusCode, headers) {
+  if (statusCode !== 200) {
+    return { ok: false, reason: 'status-' + statusCode };
+  }
+  const h = headers || {};
+
+  if (h['set-cookie']) {
+    return { ok: false, reason: 'set-cookie' };
+  }
+
+  const cc = String(h['cache-control'] || '').toLowerCase();
+  if (cc.indexOf('no-store') !== -1) {
+    return { ok: false, reason: 'no-store' };
+  }
+  if (cc.indexOf('private') !== -1) {
+    return { ok: false, reason: 'private' };
+  }
+
+  const ct = String(h['content-type'] || '').toLowerCase();
+  if (ct.indexOf('text/html') !== -1) {
+    return { ok: false, reason: 'html' };
+  }
+
+  if (String(h['vary'] || '').trim() === '*') {
+    return { ok: false, reason: 'vary-star' };
+  }
+
+  return { ok: true, reason: 'ok' };
+}
+
+/**
+ * 从原始响应头中挑出需要持久化的部分
+ */
+function pickStoreHeaders(headers, bodyLength) {
+  const out = {};
+  HEADER_KEEP.forEach((key) => {
+    const val = headers[key];
+    if (val != null && val !== '') {
+      out[key] = Array.isArray(val) ? val.join(', ') : String(val);
+    }
+  });
+
+  // content-length 一律以实际落盘字节数为准，避免「Whistle 已解压但
+  // 头里还写着压缩后长度」这类不一致把报文搞坏
+  const declared = Number(headers['content-length']);
+  out['content-length'] = String(bodyLength);
+
+  // 若声明长度与实际字节数不符，说明上游流已被解压，此时必须摘掉
+  // content-encoding，否则回放时会按错误的方式解码
+  if (out['content-encoding'] && isFinite(declared) && declared > 0 && declared !== bodyLength) {
+    delete out['content-encoding'];
+  }
+
+  return out;
+}
+
+/**
+ * 命中缓存时下发给客户端的响应头
+ */
+function buildReplayHeaders(storeHeaders, bodyLength) {
+  const out = Object.assign({}, storeHeaders);
+  out['content-length'] = String(bodyLength);
+  out['cache-control'] = REPLAY_CACHE_CONTROL;
+  out['x-figma-cache'] = 'HIT';
+  return out;
+}
+
+module.exports = {
+  ALLOW,
+  DENY_HOST,
+  DENY_PATH,
+  REPLAY_CACHE_CONTROL,
+  isSafeRequest,
+  checkUrl,
+  checkResponse,
+  pickStoreHeaders,
+  buildReplayHeaders
+};

package/lib/resRulesServer.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * resRulesServer hook —— 对应 whistle 的 RES_RULES 钩子（响应阶段）
+ *
+ * 这个阶段 whistle 已经拿到源站响应，所以我们能读到：
+ *   req.originalRes.statusCode   响应状态码
+ *   req.headers                  响应头（whistle 在 resRules 阶段把 res.headers 当请求头传过来）
+ *
+ * 职责很简单：把 REQ_RULES 阶段登记的「落盘意向」转正成一条可命中的 meta 记录。
+ * 不满足条件（非 200、带 Set-Cookie、no-store 等）就丢弃意向，避免缓存脏数据。
+ *
+ * 注意：命中回放时不会有 pending（转正时已删除），所以这里天然不会自我覆盖。
+ */
+
+const config = require('./config');
+const policy = require('./policy');
+const store = require('./store');
+
+function fullUrlOf(req) {
+  const oReq = req.originalReq || {};
+  return oReq.realUrl || req.fullUrl || oReq.url || '';
+}
+
+function reply(res) {
+  try {
+    res.writeHead(200, {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Content-Length': '0'
+    });
+  } catch (e) {
+    /* ignore */
+  }
+  res.end();
+}
+
+module.exports = (server) => {
+  server.on('request', (req, res) => {
+    try {
+      const oReq = req.originalReq || {};
+      const url = fullUrlOf(req);
+      const cfg = config.resolveConfig(oReq.ruleValue);
+      store.use(cfg);
+
+      const verdict = policy.checkUrl(url);
+      if (!verdict.ok) {
+        return reply(res);
+      }
+
+      const key = store.keyOf(url);
+
+      // 没有待转正的意向 → 可能是命中回放，也可能是别人加的规则，什么都不做
+      if (!store.hasPending(key)) {
+        return reply(res);
+      }
+
+      // 状态码拿不到时宁可放弃，也不要误判成 200 缓存一个错误页
+      const oRes = req.originalRes || {};
+      const rawStatus = oRes.statusCode;
+      if (rawStatus == null || rawStatus === '') {
+        store.dropPending(key);
+        config.log(cfg, 'DROP(no-status)  %s', url);
+        return reply(res);
+      }
+
+      const status = Number(rawStatus) || 0;
+      const resHeaders = req.headers || {};
+
+      const result = store.commitPending(key, status, resHeaders, cfg);
+      if (result.ok) {
+        config.log(cfg, 'PEND  %s  %s', resHeaders['content-type'] || '', url);
+      } else {
+        config.log(cfg, 'SKIP(%s)  %s', result.reason, url);
+      }
+    } catch (e) {
+      /* 静默失败，不影响响应 */
+    }
+    return reply(res);
+  });
+};