XWX-AI commited on
Commit
f70c501
·
1 Parent(s): ab19cdf

feat(priority): 144号方案 P1——PRO优先级队列(Ed25519本地验签)+免费80%墙与闩锁+OOM护栏+排队信息+/health

Browse files

①PRO 优先级(P1.1):lib/entitlement-verify.js(jose@6,EdDSA/Ed25519,网站同款公钥 AUTH_SIGNING_PUBLIC_KEY 本地验签零回源;fail-open 三重保险——无公钥=功能关闭行为同旧版、验签任何失败=free、绝不拦截请求)。PRO 判据与插件 isPro 同口径:plan==='pro' 或 products 含 'exporter'——token 的 plan 是 Backup 域语义,exporter-only 付费用户 plan 恒 'free',只认 plan 会漏掉这部分付费 PRO(2026-11-07 本地实测发现)。waiters 恒保持 pro 段在前各段 FIFO;dedupe 升格(PRO 提交同内容→排队中既有作业 free→pro 原位插队,零渲染)+修复 PENDING 阶段不复用的缺口(容量闸收紧后重复提交会吃 429)。
②免费 80% 墙+闩锁(2026-11-07 产品决策):freeQueueLimit 默认 40/50(PDF_JOB_FREE_QUEUE_LIMIT 可调);到限即闩上——免费 admission 全部冻结(渲染完成腾出的空位也不放行),active<恢复水位(50%)才解冻;PRO 完全豁免(提交不解锁)。软墙(无闩锁)会被"作业完成→60ms空窗→竞速"反复击穿(本地实测用户反复撞入),PRO 保留位形同虚设——标准熔断器 half-open 模式。
③OOM 护栏(P1.5):maxPendingBytes 256MB(PENDING+RUNNING payload 总量,超限 429 memory_guard);大文档(>5MB)串行渲染 bigDocConcurrency=1(S3 压测:2×12.4MB 并发≈12GB,串行后最坏≈6GB,OOM 结构性拆除;pump 跳过被闸大件继续派小件,吞吐不变);queued≥10 拒收新大件(对 PRO 一视同仁——物理容量保护非公平策略)。
④排队信息(P1.2):202/轮询响应体 queue_position(前方=排队作业数+在渲染数)+eta_ms(大文档串行×EWMA_big + 小文档÷并发×EWMA_small;EWMA 由成功渲染回报校准,初值 30s/120s=PostHog 体积加权均值与 S2/S3 压测);202 另带 X-Queue-Position/X-Queue-Eta-Ms 头;CORS exposedHeaders 放行(content 直连兜底路径可读,顺带修复 X-Image-* 从未可读)。
⑤/health(P0.2/P1.5):uptime/rss/heap/队列水位/pendingBytes/护栏配置/闩锁状态/双池 stats(no-store)——三用途:cron-job.org 保活 ping(消除 HF 48h 休眠)、外部告警数据源、Vercel pdf_capacity 状态源。
⑥429 语义化(P0.3 前提):{error:'queue_full', retryable:true, reason:'overloaded'|'memory_guard', latched?}——客户端据此拆分"排队满"与"真超时";日志新增 auth=absent|present|present_invalid(不落 token 内容,JWT 含 email PII)+tier。
⑦queueWaitMs 修复:创建时置 0 后从未更新,SUCCEEDED 日志恒 queued=0ms——补真实计算(创建→开跑,过载取证关键指标)。
测试:新增 tests/unit(node --test 零依赖)24 用例:优先级顺序(pro 插队/同层FIFO)/分层上限与灰度安全(tiering 关闭行为同旧版)/闩锁冻结与水位边界(=仍闩,<才解)/字节上限/大件串行与深度闸/排队信息与202头/dedupe复用与升格/验签全分类(含 exporter-only、过期、错钥、灰度关闭态)。真容器验证(docker --cpus=2 --memory=16g 等比 HF)9/9:PRO 穿墙插队 pos=2 vs 免费拒收 latched、memory_guard 拒大件放小件、X-Queue-* 头全链路。jose@6 新增依赖(验签)。部署(手动,由用户执行):HF Space Settings→Secrets 加 AUTH_SIGNING_PUBLIC_KEY(值=网站侧同名公钥,公钥可分发无安全影响)→ git push → curl /health 应 tiering_enabled:true。

docker-compose.yml CHANGED
@@ -31,6 +31,11 @@ services:
31
  # Tune with: docker compose up -d --build pdf-test (edit here or override)
32
  - PDF_POOL_SIZE=4
33
  - WIDGET_MAX_CONCURRENT=3
 
 
 
 
 
34
  logging:
35
  driver: "json-file"
36
  options:
 
31
  # Tune with: docker compose up -d --build pdf-test (edit here or override)
32
  - PDF_POOL_SIZE=4
33
  - WIDGET_MAX_CONCURRENT=3
34
+ # PRO 优先级本地验证(144 号 P1.1):与 llm-tools .env.local 同一把 Ed25519
35
+ # 公钥(公钥可分发,桌面APP二进制内嵌同款)——插件 dev 模式登录
36
+ # localhost:4100 签发的 entitlement JWT 在此验签生效,tier=pro 享
37
+ # 优先出队 + 免费上限(80%)豁免
38
+ - AUTH_SIGNING_PUBLIC_KEY=1Zr3THjscbP-X-ag4VNqUfT_2GhzVECYq-r6_zC6pIo
39
  logging:
40
  driver: "json-file"
41
  options:
lib/entitlement-verify.js ADDED
@@ -0,0 +1,82 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Entitlement token 本地验签(144 号方案 P1.1:服务端 PRO 优先级)。
3
+ *
4
+ * 来源链路:插件登录后,网站(llm-tools)在 /api/desktop/auth/* 的响应体里
5
+ * 下发 `entitlement` 字段 —— 一枚 **EdDSA(Ed25519) 签名的 JWT**(jose SignJWT,
6
+ * lib/auth/token.ts)。claims 含 plan("pro"|"free")/products/sub/exp。插件把它
7
+ * 存入 storage 并随 PDF 作业提交头 `Authorization: Bearer <token>` 送到本服务;
8
+ * 本模块用公钥**本地验签**(零网络回源),验过且 plan==="pro" 即享受高优先级。
9
+ *
10
+ * 为什么用 jose 而不是手写 crypto.verify:行业共识(NextAuth 等同款库,社区
11
+ * 充分测试)——alg 混淆攻击防护、claims 校验、base64url 边角由它兜住;手写
12
+ * 需要自己钉死 alg==='EdDSA' 并处理 small-order key 等已知边角(bun#46252)。
13
+ *
14
+ * 安全与失效语义(刻意保守,绝不因验签把付费用户挡在门外):
15
+ * - 环境变量 AUTH_SIGNING_PUBLIC_KEY 未配置 ⇒ 功能关闭,所有人按 free 处理
16
+ * (灰度上线默认态,与现有行为完全一致);
17
+ * - 验签任何失败(格式/签名/过期>60s 容差)⇒ 返回 free,**绝不拒绝请求**;
18
+ * - 只读 plan claim,不落日志不落盘(token 内含 email PII,绝不打印)。
19
+ */
20
+
21
+ 'use strict';
22
+
23
+ const crypto = require('node:crypto');
24
+ const { jwtVerify } = require('jose');
25
+
26
+ /** base64url(raw 32B 公钥) → Node KeyObject;非法输入返回 null */
27
+ function loadPublicKey(b64url) {
28
+ try {
29
+ const x = String(b64url || '').trim().replace(/-/g, '+').replace(/_/g, '/');
30
+ const raw = Buffer.from(x, 'base64');
31
+ if (raw.length !== 32) return null;
32
+ return crypto.createPublicKey({
33
+ key: { kty: 'OKP', crv: 'Ed25519', x: Buffer.from(raw).toString('base64url') },
34
+ format: 'jwk',
35
+ });
36
+ } catch {
37
+ return null;
38
+ }
39
+ }
40
+
41
+ /**
42
+ * @param {Object} [opts]
43
+ * @param {string} [opts.publicKeyB64Url] 默认读 env AUTH_SIGNING_PUBLIC_KEY;
44
+ * 测试注入用。空 ⇒ verifyTier 恒返回 'free'(功能关闭态)。
45
+ * @param {(m:string)=>void} [opts.log]
46
+ * @returns {{ verifyTier: (authHeader:string|null|undefined)=>Promise<'pro'|'free'>,
47
+ * enabled: boolean }}
48
+ */
49
+ function createTierVerifier(opts = {}) {
50
+ const log = opts.log || ((m) => console.log(m));
51
+ const key = loadPublicKey(opts.publicKeyB64Url ?? process.env.AUTH_SIGNING_PUBLIC_KEY);
52
+ const enabled = key !== null;
53
+ if (opts.publicKeyB64Url ?? process.env.AUTH_SIGNING_PUBLIC_KEY) {
54
+ if (!enabled) log('[TIER] AUTH_SIGNING_PUBLIC_KEY set but not a valid Ed25519 raw key — PRO priority disabled');
55
+ }
56
+ if (!enabled) log('[TIER] AUTH_SIGNING_PUBLIC_KEY not set — PRO priority disabled (all jobs free tier)');
57
+
58
+ async function verifyTier(authHeader) {
59
+ if (!enabled) return 'free';
60
+ const token = typeof authHeader === 'string' && authHeader.startsWith('Bearer ')
61
+ ? authHeader.slice(7).trim()
62
+ : null;
63
+ if (!token) return 'free';
64
+ try {
65
+ const { payload } = await jwtVerify(token, key, { algorithms: ['EdDSA'], clockTolerance: 60 });
66
+ // PRO 判据与插件侧 isPro 同口径(entitlement.js isPro):plan==='pro'
67
+ // **或** products 含 'exporter'。token 的 plan 是 Backup 域语义——只买
68
+ // Chat Exporter(exporter)未买 Backup 的付费用户 plan 恒为 'free',
69
+ // 若只认 plan 会把这部分付费 PRO 判成 free(2026-11-07 本地实测发现)。
70
+ if (!payload) return 'free';
71
+ const products = Array.isArray(payload.products) ? payload.products : [];
72
+ return (payload.plan === 'pro' || products.includes('exporter')) ? 'pro' : 'free';
73
+ } catch {
74
+ // 过期/被改/非本服务票据 → 按 free 放行(不拦截、不告警刷屏)
75
+ return 'free';
76
+ }
77
+ }
78
+
79
+ return { verifyTier, enabled };
80
+ }
81
+
82
+ module.exports = { createTierVerifier, loadPublicKey };
lib/pdf-jobs.js CHANGED
@@ -26,6 +26,35 @@
26
  *
27
  * 并发闸 `concurrency` 是有意义的**背压**:作业排队时客户端只是在轮询,
28
  * 不占用任何长连接——这是同步模式做不到的。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
29
  */
30
 
31
  'use strict';
@@ -36,6 +65,9 @@ const path = require('node:path');
36
 
37
  const STATUS = { PENDING: 'PENDING', RUNNING: 'RUNNING', SUCCEEDED: 'SUCCEEDED', FAILED: 'FAILED', CANCELED: 'CANCELED' };
38
  const TERMINAL = new Set([STATUS.SUCCEEDED, STATUS.FAILED, STATUS.CANCELED]);
 
 
 
39
 
40
  function sha256(buf) {
41
  return crypto.createHash('sha256').update(buf).digest('hex');
@@ -71,6 +103,20 @@ function createNoTimeoutLoopbackFetch() {
71
  * @param {number} [cfg.ttlMs] 结果保留时长(默认 30 分钟)
72
  * @param {number} [cfg.maxTotalBytes] 结果总字节上限,超了按完成时间淘汰(默认 2 GiB)
73
  * @param {number} [cfg.queueLimit] 排队作业上限(默认 50),超了直接 429
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74
  * @param {string} [cfg.resultDir] 结果落盘目录,默认 os.tmpdir()/xwx-pdf-jobs
75
  * @param {(msg:string)=>void} [cfg.log]
76
  * @param {number} [cfg.orphanMaxAgeMs] RUNNING 孤儿看守阈值(默认 30 分钟):回环取件
@@ -90,6 +136,23 @@ function createPdfJobService(cfg) {
90
  ttlMs = 30 * 60_000,
91
  maxTotalBytes = 2 * 1024 * 1024 * 1024,
92
  queueLimit = 50,
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93
  resultDir = path.join(require('node:os').tmpdir(), 'xwx-pdf-jobs'),
94
  sweepIntervalMs = 60_000,
95
  orphanMaxAgeMs = 30 * 60_000,
@@ -107,7 +170,67 @@ function createPdfJobService(cfg) {
107
  const byDigest = new Map(); // sha256(body) -> jobId
108
  const jobFetchCancels = new Map(); // jobId -> AbortController(孤儿看守取消回环传输用)
109
  let running = 0;
110
- const waiters = [];
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
111
 
112
  const nowIso = () => new Date().toISOString();
113
  const resultFile = (id) => path.join(resultDir, `${id}.pdf`);
@@ -121,14 +244,26 @@ function createPdfJobService(cfg) {
121
  return job;
122
  }
123
 
124
- /** 入队;并发未满则立刻开跑 */
 
 
125
  function pump() {
126
  while (running < concurrency && waiters.length) {
127
- const job = waiters.shift();
128
- if (job.status !== STATUS.PENDING) continue; // 已被取消/复用
 
 
 
 
 
 
 
 
129
  running += 1;
 
130
  execute(job).finally(() => {
131
  running -= 1;
 
132
  pump();
133
  });
134
  }
@@ -138,6 +273,9 @@ function createPdfJobService(cfg) {
138
  async function execute(job) {
139
  const t0 = Date.now();
140
  touch(job, { status: STATUS.RUNNING, phase: 'RENDERING', startedAt: nowIso() });
 
 
 
141
  // 传输层不设固定超时(渲染预算归同步端点单一所有),但保留取消通道:
142
  // 孤儿看守判死作业时中止回环 fetch,让 execute 尽快落终态、释放并发闸槽位,
143
  // 避免"永不响应的同步端点"把 worker 槽位永久占死
@@ -171,7 +309,12 @@ function createPdfJobService(cfg) {
171
  finishedAt: nowIso(), expiresAt: Date.now() + ttlMs,
172
  });
173
  job.digest && byDigest.set(job.digest, job.jobId);
174
- log(`[PDF-JOB] ${job.jobId} SUCCEEDED ${(buf.length / 1048576).toFixed(2)}MB @${((Date.now() - t0) / 1000).toFixed(1)}s (queued=${job.queueWaitMs}ms)`);
 
 
 
 
 
175
  enforceRetention();
176
  } catch (e) {
177
  if (job.status === STATUS.RUNNING) {
@@ -239,6 +382,9 @@ function createPdfJobService(cfg) {
239
  finishedAt: job.finishedAt || null,
240
  bytes: job.bytes || null,
241
  reused: job.reused === true,
 
 
 
242
  error: job.status === STATUS.FAILED ? job.error : undefined,
243
  });
244
 
@@ -254,22 +400,60 @@ function createPdfJobService(cfg) {
254
  }
255
  if (!raw.length) return res.status(400).json({ error: 'empty_payload' });
256
 
 
 
 
 
 
 
 
 
 
 
 
 
257
  const digest = sha256(raw);
258
  const existingId = byDigest.get(digest);
259
  const existing = existingId ? jobs.get(existingId) : null;
260
- if (existing && (existing.status === STATUS.RUNNING || existing.status === STATUS.SUCCEEDED)) {
261
- // 同内容已在渲染/已完成 ⇒ 复用,绝不重复烧 CPU
 
 
 
 
 
 
 
 
 
 
 
262
  existing.reused = true;
263
  res.set('Location', rel(existing.jobId));
264
- log(`[PDF-JOB] dedupe hit → ${existing.jobId} status=${existing.status} bytes=${raw.length}`);
265
  return res.status(202).json({ ...statusPayload(existing), Location: rel(existing.jobId) });
266
  }
267
 
268
  const active = [...jobs.values()].filter((j) => !TERMINAL.has(j.status)).length;
269
- if (active >= queueLimit) {
270
- res.set('Retry-After', '10');
271
- return res.status(429).json({ error: 'queue_full', active });
 
 
 
 
 
 
 
 
 
 
272
  }
 
 
 
 
 
273
 
274
  const job = {
275
  jobId: crypto.randomUUID(),
@@ -277,6 +461,8 @@ function createPdfJobService(cfg) {
277
  body: raw.toString('utf8'),
278
  status: STATUS.PENDING,
279
  phase: 'QUEUED',
 
 
280
  createdAt: nowIso(),
281
  lastUpdatedAt: nowIso(),
282
  queuedAt: Date.now(),
@@ -284,13 +470,21 @@ function createPdfJobService(cfg) {
284
  job.queueWaitMs = 0;
285
  jobs.set(job.jobId, job);
286
  byDigest.set(digest, job.jobId);
287
- waiters.push(job);
288
  setImmediate(pump);
289
 
 
290
  res.set('Location', rel(job.jobId));
291
  res.set('Retry-After', '3');
292
- log(`[PDF-JOB] accepted ${job.jobId} payloadKB=${(raw.length / 1024) | 0} active=${active + 1} running=${running}`);
293
- return res.status(202).json({ jobId: job.jobId, status: job.status, phase: job.phase, Location: rel(job.jobId) });
 
 
 
 
 
 
 
294
  });
295
 
296
  app.get('/api/pdf_jobs/:id', (req, res) => {
@@ -350,6 +544,7 @@ function createPdfJobService(cfg) {
350
  jobs: jobs.size,
351
  concurrency,
352
  ttlMs,
 
353
  totalResultBytes: [...jobs.values()].reduce((s, j) => s + (j.bytes || 0), 0),
354
  });
355
  });
@@ -363,7 +558,24 @@ function createPdfJobService(cfg) {
363
  return 8;
364
  }
365
 
366
- return { register, jobs, STATUS, stats: () => ({ running, queued: waiters.length, jobs: jobs.size }) };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
367
  }
368
 
369
  module.exports = { createPdfJobService, STATUS };
 
26
  *
27
  * 并发闸 `concurrency` 是有意义的**背压**:作业排队时客户端只是在轮询,
28
  * 不占用任何长连接——这是同步模式做不到的。
29
+ *
30
+ * ── PRO 优先级 + 过载护栏(144 号方案 P1.1/P1.5,2026-11-05)──────────────
31
+ * 压测结论(temp/test/2026-11-03):过载下系统本身稳定排空(fail-fast + 无雪崩),
32
+ * 缺的是三样:优先级(PRO 与免费无差别吃 429)、排队可视化(客户端只看到静默
33
+ * 等待)、大文档 OOM 引信(50 深 ×12MB 队列 → 内核 OOM killer 杀 Chromium)。
34
+ * 本版加入(行业模式:Priority Queue + load shedding,付费流量绕过共享容量帽):
35
+ * 1. **PRO 优先出队**:提交头 `Authorization: Bearer <entitlement JWT>` 经
36
+ * verifyTier(lib/entitlement-verify.js,本地验签零回源)判层;waiters 数组
37
+ * 恒保持「pro 段在前、free 段在后,各段内 FIFO」,pump 永远先派发 pro。
38
+ * 验签失败/过期/无 token ⇒ free(绝不拦截,fail-open)。
39
+ * 2. **免费队列独立上限** freeQueueLimit(默认 25 < queueLimit 50):突发时
40
+ * 免费用户先吃 429,PRO 槽位受保护。tiering 关闭(无公钥)时该上限自动
41
+ * 失效回 queueLimit——功能未上线不得改变现有行为。
42
+ * 3. **待处理字节上限** maxPendingBytes(默认 256MB):PENDING+RUNNING 作业的
43
+ * payload 总量超限再收大件就是 S3 压测的 OOM 引信(46×12.4MB 排队即 94%
44
+ * 内存),超出 ⇒ 429 reason=memory_guard。
45
+ * 4. **大文档串行** bigDocConcurrency(默认 1):>5MB 的作业同一时刻最多 1 个
46
+ * 在渲染。S3 实测 2 个并发 12.4MB 渲染 ≈ 12GB(Chromium 光栅化大 HTML),
47
+ * 串行后最坏 ≈ 6GB,OOM 被结构性拆除;小文档不受影响(吞吐不变)。
48
+ * 5. **排队深度超阈拒收大件**:queued ≥ bigDocQueueDepth(默认 10)时新到
49
+ * >5MB 作业直接 429 memory_guard——串行下它们尾部必然 >20min 客户端预算,
50
+ * 诚实的提前 fail-fast 优于 20 分钟后超时(对 PRO 一视同仁:这是物理容量
51
+ * 保护,不是公平策略)。
52
+ * 6. **排队可视化**:202/轮询响应体携带 queue_position(pro 优先顺序下的前方
53
+ * 作业数)与 eta_ms(EWMA 估算,小/大文档各一条均值,成功渲染回报校准);
54
+ * 202 另带 X-Queue-Position / X-Queue-Eta-Ms 头(同值,便于网关侧观测)。
55
+ * 7. **429 语义化**:响应体从 {error:'queue_full',active} 扩为
56
+ * {error:'queue_full', retryable:true, reason:'overloaded'|'memory_guard',
57
+ * active}——客户端据此区分「排队满」与「真超时」(P0.3 文案拆分的前提)。
58
  */
59
 
60
  'use strict';
 
65
 
66
  const STATUS = { PENDING: 'PENDING', RUNNING: 'RUNNING', SUCCEEDED: 'SUCCEEDED', FAILED: 'FAILED', CANCELED: 'CANCELED' };
67
  const TERMINAL = new Set([STATUS.SUCCEEDED, STATUS.FAILED, STATUS.CANCELED]);
68
+ // 幂等复用判定:FAILED/CANCELED 之外的都可复用(含 PENDING——重复提交不需要等
69
+ // 渲染开始才去重;FAILED/CANCELED 不复用,重提交拿全新作业是既有语义)
70
+ const TERMINAL_UNKNOWN = new Set([STATUS.FAILED, STATUS.CANCELED]);
71
 
72
  function sha256(buf) {
73
  return crypto.createHash('sha256').update(buf).digest('hex');
 
103
  * @param {number} [cfg.ttlMs] 结果保留时长(默认 30 分钟)
104
  * @param {number} [cfg.maxTotalBytes] 结果总字节上限,超了按完成时间淘汰(默认 2 GiB)
105
  * @param {number} [cfg.queueLimit] 排队作业上限(默认 50),超了直接 429
106
+ * @param {boolean} [cfg.tieringEnabled] PRO 分层总开关(公钥就绪才为 true)。
107
+ * 关闭时所有作业按 free 处理且 freeQueueLimit 自动失效(=queueLimit),
108
+ * 保证未部署公钥的实例行为与旧版完全一致。
109
+ * @param {number} [cfg.freeQueueLimit] 免费档排队上限(默认 25 < queueLimit):
110
+ * 突发时免费作业先吃 429,PRO 槽位受保护(付费流量绕过共享容量帽)
111
+ * @param {number} [cfg.maxPendingBytes] 非终态作业 payload 总字节上限(默认 256MB),
112
+ * 超限 429 memory_guard——S3 压测:46×12.4MB 排队 = OOM 引信
113
+ * @param {number} [cfg.bigDocBytes] 「大文档」阈值(默认 5MB)
114
+ * @param {number} [cfg.bigDocConcurrency] 大文档并行渲染上限(默认 1:串行拆 OOM)
115
+ * @param {number} [cfg.bigDocQueueDepth] 排队深度达到该值后拒收新大文档(默认 10)
116
+ * @param {number} [cfg.etaSmallMs] 小文档渲染时长 EWMA 初值(默认 30s,PostHog 90 天体积加权均值 ≈26s)
117
+ * @param {number} [cfg.etaBigMs] 大文档渲染时长 EWMA 初值(默认 120s,S2 实测 5MB≈25s / S3 12MB≈100s 的保守取值)
118
+ * @param {(authHeader:string|null|undefined)=>Promise<'pro'|'free'>} [cfg.verifyTier]
119
+ * 提交头验签(lib/entitlement-verify.js 注入);缺省恒 'free'
120
  * @param {string} [cfg.resultDir] 结果落盘目录,默认 os.tmpdir()/xwx-pdf-jobs
121
  * @param {(msg:string)=>void} [cfg.log]
122
  * @param {number} [cfg.orphanMaxAgeMs] RUNNING 孤儿看守阈值(默认 30 分钟):回环取件
 
136
  ttlMs = 30 * 60_000,
137
  maxTotalBytes = 2 * 1024 * 1024 * 1024,
138
  queueLimit = 50,
139
+ tieringEnabled = false,
140
+ // 2026-11-07 产品决策(用户实测反馈):默认 = queueLimit 的 80%——队列到 80%
141
+ // 免费就挤不进去,恒留 ≥20% 槽位给 PRO。此前 25/50 语义相同但比例未显式化。
142
+ freeQueueLimit = 40,
143
+ maxPendingBytes = 256 * 1024 * 1024,
144
+ bigDocBytes = 5 * 1024 * 1024,
145
+ bigDocConcurrency = 1,
146
+ bigDocQueueDepth = 10,
147
+ etaSmallMs = 30_000,
148
+ etaBigMs = 120_000,
149
+ // 免费闩锁恢复水位(freeLatchRecovery × effectiveFreeLimit):到达免费上限
150
+ // 即"闩上"——此后免费提交**全部拒收**(哪怕渲染完成让 active 短暂低于上限,
151
+ // 也不许免费再进),直到 active < 恢复水位才"解锁"重新放行。没有闩锁,
152
+ // 上限只是一道每次作业完成都会重开的门(2026-11-07 本地实测:用户反复撞进
153
+ // 空窗被受理),顶部的 PRO 保留位形同虚设。标准熔断器 half-open 模式。
154
+ freeLatchRecovery = 0.5,
155
+ verifyTier,
156
  resultDir = path.join(require('node:os').tmpdir(), 'xwx-pdf-jobs'),
157
  sweepIntervalMs = 60_000,
158
  orphanMaxAgeMs = 30 * 60_000,
 
170
  const byDigest = new Map(); // sha256(body) -> jobId
171
  const jobFetchCancels = new Map(); // jobId -> AbortController(孤儿看守取消回环传输用)
172
  let running = 0;
173
+ const waiters = []; // 恒保持「pro 段在前、free 段在后,各段内 FIFO」
174
+ let bigDocRunning = 0; // 正在渲染的大文档数(≤ bigDocConcurrency,OOM 护栏)
175
+ // 渲染时长 EWMA(排队 ETA 校准):初值来自 PostHog 体积加权均值/S 压测,成功渲染回报后收敛
176
+ let ewmaSmallMs = Math.max(1_000, etaSmallMs);
177
+ let ewmaBigMs = Math.max(1_000, etaBigMs);
178
+
179
+ // 分层未启用(未部署公钥)时免费上限自动失效——功能灰度不得改变现有行为
180
+ const effectiveFreeLimit = tieringEnabled ? Math.min(freeQueueLimit, queueLimit) : queueLimit;
181
+ // 免费闩锁:到达上限即闩上,active 降到恢复水位以下才解锁(见 cfg 注释)
182
+ let freeLatched = false;
183
+ const freeUnlatchAt = Math.max(1, Math.floor(effectiveFreeLimit * freeLatchRecovery));
184
+ const isBig = (job) => (job.payloadBytes || 0) > bigDocBytes;
185
+
186
+ /** 非终态作业的 payload 总字节(PENDING + RUNNING)——OOM 护栏的计量口径 */
187
+ function pendingBytes() {
188
+ let total = 0;
189
+ for (const j of jobs.values()) {
190
+ if (!TERMINAL.has(j.status) && j.payloadBytes) total += j.payloadBytes;
191
+ }
192
+ return total;
193
+ }
194
+
195
+ /** 把作业按层插入 waiters:pro 插到 free 段之前(段内 FIFO),free 追加队尾 */
196
+ function enqueueWaiter(job) {
197
+ if (job.tier !== 'pro') {
198
+ waiters.push(job);
199
+ return;
200
+ }
201
+ let idx = waiters.length;
202
+ for (let i = 0; i < waiters.length; i++) {
203
+ if (waiters[i].tier !== 'pro') { idx = i; break; }
204
+ }
205
+ waiters.splice(idx, 0, job);
206
+ }
207
+
208
+ /**
209
+ * 排队信息估算(诚实近似,非承诺)。口径 = 「到我拿到成品为止」:
210
+ * position = 前方的排队作业数(pro 优先派发序)+ 正在渲染中的作业数
211
+ * (用户感知的"前方 N 人"包含正在渲染的——它们同样挡在我前面);
212
+ * eta = 大文档(串行槽位)× 大文档 EWMA + 小文档 ÷ concurrency × 小文档 EWMA,
213
+ * 排队的与在渲染中的一并计入(position=0 但渲染槽全忙时依然有等待)。
214
+ */
215
+ function queueInfoFor(job) {
216
+ if (job.status !== STATUS.PENDING) return { queue_position: null, eta_ms: null };
217
+ let smallsAhead = 0;
218
+ let bigsAhead = 0;
219
+ for (const w of waiters) {
220
+ if (w === job) break;
221
+ if (w.status !== STATUS.PENDING) continue;
222
+ if (isBig(w)) bigsAhead += 1; else smallsAhead += 1;
223
+ }
224
+ const smallRunning = Math.max(0, running - bigDocRunning);
225
+ const position = smallsAhead + bigsAhead + running;
226
+ const eta = bigsAhead * ewmaBigMs
227
+ + bigDocRunning * ewmaBigMs
228
+ + ((smallsAhead + smallRunning) / Math.max(1, concurrency)) * ewmaSmallMs;
229
+ return {
230
+ queue_position: position,
231
+ eta_ms: Math.max(0, Math.round(eta)),
232
+ };
233
+ }
234
 
235
  const nowIso = () => new Date().toISOString();
236
  const resultFile = (id) => path.join(resultDir, `${id}.pdf`);
 
244
  return job;
245
  }
246
 
247
+ /** 入队;并发未满则立刻���跑。派发顺序 = pro 优先(waiters 已按层排序),
248
+ * 大文档受 bigDocConcurrency 串行闸约束:头部大文档等串行槽位时,跳过它
249
+ * 继续派发其后的小文档(小件先排空,大件独占——S3 OOM 护栏)。 */
250
  function pump() {
251
  while (running < concurrency && waiters.length) {
252
+ let pick = -1;
253
+ for (let i = 0; i < waiters.length; i++) {
254
+ const w = waiters[i];
255
+ if (w.status !== STATUS.PENDING) continue; // 已被取消/复用(排空后清理)
256
+ if (isBig(w) && bigDocRunning >= bigDocConcurrency) continue;
257
+ pick = i;
258
+ break;
259
+ }
260
+ if (pick === -1) break;
261
+ const [job] = waiters.splice(pick, 1);
262
  running += 1;
263
+ if (isBig(job)) bigDocRunning += 1;
264
  execute(job).finally(() => {
265
  running -= 1;
266
+ if (isBig(job)) bigDocRunning = Math.max(0, bigDocRunning - 1);
267
  pump();
268
  });
269
  }
 
273
  async function execute(job) {
274
  const t0 = Date.now();
275
  touch(job, { status: STATUS.RUNNING, phase: 'RENDERING', startedAt: nowIso() });
276
+ // 真实排队时长(创建→开跑):原代码在创建时置 0 后从不更新,SUCCEEDED 日志
277
+ // 恒打 queued=0ms——过载取证时这是关键指标,2026-11-06 本地实测暴露后补上
278
+ job.queueWaitMs = Date.now() - job.queuedAt;
279
  // 传输层不设固定超时(渲染预算归同步端点单一所有),但保留取消通道:
280
  // 孤儿看守判死作业时中止回环 fetch,让 execute 尽快落终态、释放并发闸槽位,
281
  // 避免"永不响应的同步端点"把 worker 槽位永久占死
 
309
  finishedAt: nowIso(), expiresAt: Date.now() + ttlMs,
310
  });
311
  job.digest && byDigest.set(job.digest, job.jobId);
312
+ // 成功渲染回报 EWMA(排队 ETA 校准):指数平滑 α=0.3,只认成功——
313
+ // 失败/孤儿时长(多为异常路径)会污染估计
314
+ const renderMs = Date.now() - t0;
315
+ if (isBig(job)) ewmaBigMs = Math.round(ewmaBigMs * 0.7 + renderMs * 0.3);
316
+ else ewmaSmallMs = Math.round(ewmaSmallMs * 0.7 + renderMs * 0.3);
317
+ log(`[PDF-JOB] ${job.jobId} SUCCEEDED ${(buf.length / 1048576).toFixed(2)}MB @${((Date.now() - t0) / 1000).toFixed(1)}s (queued=${job.queueWaitMs}ms tier=${job.tier || 'free'})`);
318
  enforceRetention();
319
  } catch (e) {
320
  if (job.status === STATUS.RUNNING) {
 
382
  finishedAt: job.finishedAt || null,
383
  bytes: job.bytes || null,
384
  reused: job.reused === true,
385
+ // 排队可视化(144 号 P1.2):仅在排队中给出,渲染中/终态为 null(客户端
386
+ // 据 phase 切换文案,数值缺失时显示无位置估计的通用排队态——兼容旧客户端)
387
+ ...queueInfoFor(job),
388
  error: job.status === STATUS.FAILED ? job.error : undefined,
389
  });
390
 
 
400
  }
401
  if (!raw.length) return res.status(400).json({ error: 'empty_payload' });
402
 
403
+ // 分层判定(144 号 P1.1):Authorization 头里的 entitlement JWT 本地验签。
404
+ // 任何失败(无 token/过期/非法)都按 free 放行——绝不因验签拦截请求。
405
+ let tier = 'free';
406
+ let authState = 'absent';
407
+ if (typeof verifyTier === 'function') {
408
+ const hdr = req.headers && req.headers.authorization;
409
+ authState = typeof hdr === 'string' && hdr.startsWith('Bearer ') && hdr.length > 20 ? 'present' : 'absent';
410
+ try { tier = await verifyTier(hdr); }
411
+ catch { tier = 'free'; }
412
+ if (authState === 'present' && tier !== 'pro') authState = 'present_invalid';
413
+ }
414
+
415
  const digest = sha256(raw);
416
  const existingId = byDigest.get(digest);
417
  const existing = existingId ? jobs.get(existingId) : null;
418
+ if (existing && !TERMINAL_UNKNOWN.has(existing.status)) {
419
+ // 同内容已在排队/渲染/已完成 ⇒ 复用,绝不重复烧 CPU(复用不受容量闸约束:
420
+ // 复用零新增渲染,拒收它只会逼客户端重提交同一内容。2026-11-05 修正:旧版
421
+ // 只复用 RUNNING/SUCCEEDED——PENDING 阶段的重复提交会落到容量闸吃 429,
422
+ // 免费上限收紧后这个缺口从无害变有害(同内容还在队列里就被拒之门外)。
423
+ // PRO 提交同内容时顺带把排队中的既有作业升级为 pro(同结果,插队零渲染)。
424
+ if (tier === 'pro' && existing.status === STATUS.PENDING && existing.tier !== 'pro') {
425
+ const wi = waiters.indexOf(existing);
426
+ if (wi >= 0) waiters.splice(wi, 1);
427
+ existing.tier = 'pro';
428
+ enqueueWaiter(existing);
429
+ log(`[PDF-JOB] dedupe promoted → ${existing.jobId} free→pro (queued=${waiters.length})`);
430
+ }
431
  existing.reused = true;
432
  res.set('Location', rel(existing.jobId));
433
+ log(`[PDF-JOB] dedupe hit → ${existing.jobId} status=${existing.status} bytes=${raw.length} tier=${tier}`);
434
  return res.status(202).json({ ...statusPayload(existing), Location: rel(existing.jobId) });
435
  }
436
 
437
  const active = [...jobs.values()].filter((j) => !TERMINAL.has(j.status)).length;
438
+ // 过载阶梯(144 号 P1.1/P1.5 + 2026-11-07 闩锁):① 总队列满 ② 免费上限
439
+ // (带闩锁:到限即冻结免费 admission,直到 active < 恢复水位——没有闩锁,
440
+ // 每次作业完成都会短暂重开大门,免费用户撞空窗挤入,PRO 保留位失效)
441
+ // ③ 待处理字节 ④ 深排队拒大件。语义化响应体(retryable/reason)供客户端
442
+ // 拆分「排队满」与「真超时」的文案(P0.3)。
443
+ const reject429 = (reason, retryAfter, latched = false) => {
444
+ res.set('Retry-After', String(retryAfter));
445
+ log(`[PDF-JOB] rejected 429 reason=${reason} tier=${tier} auth=${authState} active=${active} queued=${waiters.length} latched=${latched} pendingBytes=${pendingBytes()}`);
446
+ return res.status(429).json({ error: 'queue_full', retryable: true, reason, active, queued: waiters.length, latched: latched || undefined });
447
+ };
448
+ if (tier !== 'pro') {
449
+ if (freeLatched && active < freeUnlatchAt) freeLatched = false; // 恢复水位解锁
450
+ if (active >= effectiveFreeLimit) freeLatched = true;
451
  }
452
+ if (active >= queueLimit) return reject429('overloaded', 10);
453
+ if (tier !== 'pro' && freeLatched) return reject429('overloaded', 10, true);
454
+ if (pendingBytes() + raw.length > maxPendingBytes) return reject429('memory_guard', 30);
455
+ const queued = active - running;
456
+ if (raw.length > bigDocBytes && queued >= bigDocQueueDepth) return reject429('memory_guard', 30);
457
 
458
  const job = {
459
  jobId: crypto.randomUUID(),
 
461
  body: raw.toString('utf8'),
462
  status: STATUS.PENDING,
463
  phase: 'QUEUED',
464
+ tier,
465
+ payloadBytes: raw.length,
466
  createdAt: nowIso(),
467
  lastUpdatedAt: nowIso(),
468
  queuedAt: Date.now(),
 
470
  job.queueWaitMs = 0;
471
  jobs.set(job.jobId, job);
472
  byDigest.set(digest, job.jobId);
473
+ enqueueWaiter(job);
474
  setImmediate(pump);
475
 
476
+ const qi = queueInfoFor(job);
477
  res.set('Location', rel(job.jobId));
478
  res.set('Retry-After', '3');
479
+ if (qi.queue_position !== null) {
480
+ res.set('X-Queue-Position', String(qi.queue_position));
481
+ res.set('X-Queue-Eta-Ms', String(qi.eta_ms));
482
+ }
483
+ log(`[PDF-JOB] accepted ${job.jobId} payloadKB=${(raw.length / 1024) | 0} active=${active + 1} running=${running} tier=${tier} auth=${authState} pos=${qi.queue_position}`);
484
+ return res.status(202).json({
485
+ jobId: job.jobId, status: job.status, phase: job.phase, Location: rel(job.jobId),
486
+ queue_position: qi.queue_position, eta_ms: qi.eta_ms,
487
+ });
488
  });
489
 
490
  app.get('/api/pdf_jobs/:id', (req, res) => {
 
544
  jobs: jobs.size,
545
  concurrency,
546
  ttlMs,
547
+ pendingBytes: pendingBytes(),
548
  totalResultBytes: [...jobs.values()].reduce((s, j) => s + (j.bytes || 0), 0),
549
  });
550
  });
 
558
  return 8;
559
  }
560
 
561
+ return {
562
+ register, jobs, STATUS,
563
+ stats: () => ({
564
+ running,
565
+ queued: waiters.length,
566
+ jobs: jobs.size,
567
+ pendingBytes: pendingBytes(),
568
+ bigDocRunning,
569
+ tieringEnabled,
570
+ freeQueueLimit: effectiveFreeLimit,
571
+ freeLatched,
572
+ freeUnlatchAt,
573
+ queueLimit,
574
+ maxPendingBytes,
575
+ ewmaSmallMs,
576
+ ewmaBigMs,
577
+ }),
578
+ };
579
  }
580
 
581
  module.exports = { createPdfJobService, STATUS };
package-lock.json CHANGED
@@ -13,6 +13,7 @@
13
  "chartjs-node-canvas": "^5.0.0",
14
  "cors": "^2.8.5",
15
  "express": "^4.18.2",
 
16
  "lucide-static": "^1.55.0",
17
  "puppeteer": "^24.0.0",
18
  "shiki": "^1.24.0",
@@ -3635,6 +3636,15 @@
3635
  "jiti": "bin/jiti.js"
3636
  }
3637
  },
 
 
 
 
 
 
 
 
 
3638
  "node_modules/jotai": {
3639
  "version": "2.20.0",
3640
  "resolved": "https://registry.npmjs.org/jotai/-/jotai-2.20.0.tgz",
 
13
  "chartjs-node-canvas": "^5.0.0",
14
  "cors": "^2.8.5",
15
  "express": "^4.18.2",
16
+ "jose": "^6.2.15",
17
  "lucide-static": "^1.55.0",
18
  "puppeteer": "^24.0.0",
19
  "shiki": "^1.24.0",
 
3636
  "jiti": "bin/jiti.js"
3637
  }
3638
  },
3639
+ "node_modules/jose": {
3640
+ "version": "6.2.15",
3641
+ "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.15.tgz",
3642
+ "integrity": "sha512-qdF6ewcZARtef63fJ9AKKZPgxw+t7USH6HLXYcD4CrdmSvDp79rpJSPFEKc90QBeGS63u1KQtN2MZQHC0yDIzA==",
3643
+ "license": "MIT",
3644
+ "funding": {
3645
+ "url": "https://github.com/sponsors/panva"
3646
+ }
3647
+ },
3648
  "node_modules/jotai": {
3649
  "version": "2.20.0",
3650
  "resolved": "https://registry.npmjs.org/jotai/-/jotai-2.20.0.tgz",
package.json CHANGED
@@ -9,6 +9,7 @@
9
  "chartjs-node-canvas": "^5.0.0",
10
  "cors": "^2.8.5",
11
  "express": "^4.18.2",
 
12
  "lucide-static": "^1.55.0",
13
  "puppeteer": "^24.0.0",
14
  "shiki": "^1.24.0",
 
9
  "chartjs-node-canvas": "^5.0.0",
10
  "cors": "^2.8.5",
11
  "express": "^4.18.2",
12
+ "jose": "^6.2.15",
13
  "lucide-static": "^1.55.0",
14
  "puppeteer": "^24.0.0",
15
  "shiki": "^1.24.0",
server.js CHANGED
@@ -26,6 +26,7 @@ const express = require('express');
26
  const puppeteer = require('puppeteer');
27
  const cors = require('cors');
28
  const { createPdfJobService } = require('./lib/pdf-jobs');
 
29
  const { getHighlighter } = require('shiki');
30
  const fs = require('fs');
31
  const path = require('path');
@@ -236,13 +237,57 @@ const widgetPool = new BrowserPool({
236
 
237
  console.log(`[PERF] PDF browser pool: size=${PDF_POOL_SIZE}, recycleAfter=${PDF_RECYCLE_AFTER}, widgetConcurrent=${WIDGET_MAX_CONCURRENT}, widgetPoolSize=${WIDGET_MAX_CONCURRENT}`);
238
 
239
- app.use(cors());
 
 
 
 
 
 
240
  app.use(express.json({ limit: '50mb' }));
241
 
242
  app.get('/', (req, res) => {
243
  res.send(`Puppeteer PDF Server Running (${isTest ? '测试环境' : '生产环境'})`);
244
  });
245
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
246
  app.post('/api/generate_pdf', async (req, res) => {
247
  const startTime = Date.now();
248
 
@@ -1497,6 +1542,11 @@ app.post('/api/render_charts', async (req, res) => {
1497
  // 同步 /api/generate_pdf 保留原样服务全部老客户端;新作业端点把"一次长静默请求"
1498
  // 拆成"短提交 + 短轮询 + 短下载",链路上任何 idle 型中间盒都碰不到长连接。
1499
  // 实现细节与三条设计决定见 lib/pdf-jobs.js 头注释。
 
 
 
 
 
1500
  const pdfJobs = createPdfJobService({
1501
  selfOrigin: `http://127.0.0.1:${port}`,
1502
  concurrency: Number(process.env.PDF_JOB_CONCURRENCY || 2),
@@ -1504,6 +1554,13 @@ const pdfJobs = createPdfJobService({
1504
  // 孤儿看守阈值:客户端作业总预算 20 分钟(插件 PDF_JOB_BUDGET_MS),30 分钟 =
1505
  // 全部客户端离场后留 10 分钟余量,只做后端内部卫生,不影响任何等待体验
1506
  orphanMaxAgeMs: Number(process.env.PDF_JOB_ORPHAN_MAX_AGE_MS || 30 * 60 * 1000),
 
 
 
 
 
 
 
1507
  });
1508
  pdfJobs.register(app);
1509
 
 
26
  const puppeteer = require('puppeteer');
27
  const cors = require('cors');
28
  const { createPdfJobService } = require('./lib/pdf-jobs');
29
+ const { createTierVerifier } = require('./lib/entitlement-verify');
30
  const { getHighlighter } = require('shiki');
31
  const fs = require('fs');
32
  const path = require('path');
 
237
 
238
  console.log(`[PERF] PDF browser pool: size=${PDF_POOL_SIZE}, recycleAfter=${PDF_RECYCLE_AFTER}, widgetConcurrent=${WIDGET_MAX_CONCURRENT}, widgetPoolSize=${WIDGET_MAX_CONCURRENT}`);
239
 
240
+ // Access-Control-Expose-Headers:自定义响应头对「content 直连兜底」路径可读
241
+ // (SW 代理通道读全部头不受 CORS 管,但 backendFetch 兜底的页面源 fetch 受管)。
242
+ // X-Image-* 是 generate_pdf 一直在下发却从未可读的头(顺带修复);
243
+ // X-Queue-* 服务排队可视化(144 号 P1.2)。Retry-After 本就是 CORS-safelisted。
244
+ app.use(cors({
245
+ exposedHeaders: ['X-Queue-Position', 'X-Queue-Eta-Ms', 'X-Image-Status', 'X-Image-Count'],
246
+ }));
247
  app.use(express.json({ limit: '50mb' }));
248
 
249
  app.get('/', (req, res) => {
250
  res.send(`Puppeteer PDF Server Running (${isTest ? '测试环境' : '生产环境'})`);
251
  });
252
 
253
+ // ─── /health(144 号 P0.2 + P1.5)───────────────────────────────────────────
254
+ // 三用途:①UptimeRobot/cron-job.org 免费保活 ping(消除 HF 48h 强制休眠与分钟级
255
+ // 冷启动)②外部告警数据源(内存/队列水位)③Vercel 侧 pdf_capacity 动态状态源。
256
+ // 轻量只读:不碰浏览器池,缓存敏感值于内存常量,可被外部高频 ping。
257
+ const BOOT_AT = Date.now();
258
+ app.get('/health', (req, res) => {
259
+ const mem = process.memoryUsage();
260
+ const jobStats = typeof pdfJobs.stats === 'function' ? pdfJobs.stats() : null;
261
+ res.set('Cache-Control', 'no-store');
262
+ res.json({
263
+ ok: true,
264
+ uptime_s: Math.round((Date.now() - BOOT_AT) / 1000),
265
+ memory: {
266
+ rss_mb: Math.round(mem.rss / 1048576),
267
+ heap_used_mb: Math.round(mem.heapUsed / 1048576),
268
+ },
269
+ pdf_jobs: jobStats ? {
270
+ running: jobStats.running,
271
+ queued: jobStats.queued,
272
+ pending_bytes: jobStats.pendingBytes,
273
+ big_doc_running: jobStats.bigDocRunning,
274
+ concurrency: jobStats.concurrency ?? undefined,
275
+ queue_limit: jobStats.queueLimit,
276
+ free_queue_limit: jobStats.freeQueueLimit,
277
+ free_latched: jobStats.freeLatched,
278
+ free_unlatch_at: jobStats.freeUnlatchAt,
279
+ tiering_enabled: jobStats.tieringEnabled,
280
+ max_pending_bytes: jobStats.maxPendingBytes,
281
+ eta_small_ms: jobStats.ewmaSmallMs,
282
+ eta_big_ms: jobStats.ewmaBigMs,
283
+ } : null,
284
+ pools: {
285
+ pdf: { size: pdfPool.size, stats: pdfPool.stats },
286
+ widget: { size: widgetPool.size, stats: widgetPool.stats },
287
+ },
288
+ });
289
+ });
290
+
291
  app.post('/api/generate_pdf', async (req, res) => {
292
  const startTime = Date.now();
293
 
 
1542
  // 同步 /api/generate_pdf 保留原样服务全部老客户端;新作业端点把"一次长静默请求"
1543
  // 拆成"短提交 + 短轮询 + 短下载",链路上任何 idle 型中间盒都碰不到长连接。
1544
  // 实现细节与三条设计决定见 lib/pdf-jobs.js 头注释。
1545
+ //
1546
+ // PRO 优先级(144 号 P1.1):验签公钥 = 网站侧 AUTH_SIGNING_PUBLIC_KEY(同一把
1547
+ // Ed25519 公钥,base64url raw 32B)——未配置时 tieringEnabled=false,所有作业按
1548
+ // free 处理且免费队列上限自动失效,行为与旧版完全一致(灰度安全)。
1549
+ const tierVerifier = createTierVerifier({ log: (m) => console.log(m) });
1550
  const pdfJobs = createPdfJobService({
1551
  selfOrigin: `http://127.0.0.1:${port}`,
1552
  concurrency: Number(process.env.PDF_JOB_CONCURRENCY || 2),
 
1554
  // 孤儿看守阈值:客户端作业总预算 20 分钟(插件 PDF_JOB_BUDGET_MS),30 分钟 =
1555
  // 全部客户端离场后留 10 分钟余量,只做后端内部卫生,不影响任何等待体验
1556
  orphanMaxAgeMs: Number(process.env.PDF_JOB_ORPHAN_MAX_AGE_MS || 30 * 60 * 1000),
1557
+ tieringEnabled: tierVerifier.enabled,
1558
+ verifyTier: tierVerifier.verifyTier,
1559
+ freeQueueLimit: Number(process.env.PDF_JOB_FREE_QUEUE_LIMIT || 40), // 80% of queueLimit(50):留 PRO 保留位(2026-11-07 产品决策)
1560
+ maxPendingBytes: Number(process.env.PDF_JOB_MAX_PENDING_BYTES || 256 * 1024 * 1024),
1561
+ bigDocBytes: Number(process.env.PDF_JOB_BIG_DOC_BYTES || 5 * 1024 * 1024),
1562
+ bigDocConcurrency: Number(process.env.PDF_JOB_BIG_DOC_CONCURRENCY || 1),
1563
+ bigDocQueueDepth: Number(process.env.PDF_JOB_BIG_DOC_QUEUE_DEPTH || 10),
1564
  });
1565
  pdfJobs.register(app);
1566
 
tests/unit/entitlement-verify.test.mjs ADDED
@@ -0,0 +1,96 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * entitlement token 本地验签单测(144 号 P1.1,2026-11-05)。
3
+ *
4
+ * 运行:node --test tests/unit/
5
+ * 测试内用 node:crypto 现生成 Ed25519 密钥对 + jose SignJWT 签发与
6
+ * llm-tools/lib/auth/token.ts 同构的 token(EdDSA, plan claim),验证
7
+ * createTierVerifier 的全部分类路径与 fail-open 语义。
8
+ */
9
+ import { test, describe } from 'node:test';
10
+ import assert from 'node:assert/strict';
11
+ import { createRequire } from 'node:module';
12
+ import { generateKeyPairSync } from 'node:crypto';
13
+ import { SignJWT, exportJWK } from 'jose';
14
+
15
+ const require = createRequire(import.meta.url);
16
+ const { createTierVerifier, loadPublicKey } = require('../../lib/entitlement-verify.js');
17
+
18
+ async function makeKeyPair() {
19
+ const { publicKey, privateKey } = generateKeyPairSync('ed25519');
20
+ const jwk = await exportJWK(publicKey); // { kty:'OKP', crv:'Ed25519', x }
21
+ return { publicKeyB64Url: jwk.x, privateKey };
22
+ }
23
+
24
+ async function sign(privateKey, claims, { expires = '24h' } = {}) {
25
+ return new SignJWT(claims)
26
+ .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT' })
27
+ .setIssuedAt()
28
+ .setExpirationTime(expires)
29
+ .sign(privateKey);
30
+ }
31
+
32
+ describe('loadPublicKey', () => {
33
+ test('接受 base64url raw 32B(网站 AUTH_SIGNING_PUBLIC_KEY 形态)', async () => {
34
+ const { publicKeyB64Url } = await makeKeyPair();
35
+ assert.ok(loadPublicKey(publicKeyB64Url), '合法公钥应构造成功');
36
+ assert.equal(loadPublicKey('not-base64!!'), null);
37
+ assert.equal(loadPublicKey('AAAA'), null, '长度非 32B 拒绝');
38
+ assert.equal(loadPublicKey(''), null);
39
+ assert.equal(loadPublicKey(undefined), null);
40
+ });
41
+ });
42
+
43
+ describe('verifyTier 分类', () => {
44
+ test('plan=pro → pro;plan=free → free;无 token → free', async () => {
45
+ const { publicKeyB64Url, privateKey } = await makeKeyPair();
46
+ const v = createTierVerifier({ publicKeyB64Url, log: () => {} });
47
+ assert.equal(v.enabled, true);
48
+ const proToken = await sign(privateKey, { sub: 'u1', plan: 'pro', products: ['backup', 'exporter'] });
49
+ const freeToken = await sign(privateKey, { sub: 'u2', plan: 'free', products: [] });
50
+ assert.equal(await v.verifyTier(`Bearer ${proToken}`), 'pro');
51
+ assert.equal(await v.verifyTier(`Bearer ${freeToken}`), 'free');
52
+ assert.equal(await v.verifyTier(null), 'free');
53
+ assert.equal(await v.verifyTier(undefined), 'free');
54
+ assert.equal(await v.verifyTier('Basic abc'), 'free', '非 Bearer 形态 → free');
55
+ assert.equal(await v.verifyTier('Bearer not-a-jwt'), 'free', '垃圾 token → free 不抛错');
56
+ });
57
+
58
+ test('exporter-only 付费用户(plan=free + products 含 exporter)→ pro(与插件 isPro 同口径)', async () => {
59
+ // 2026-11-07 本地实测发现:token 的 plan 是 Backup 域语义,exporter-only
60
+ // 付费用户 plan 恒 'free'——只认 plan 会漏掉这部分付费 PRO
61
+ const { publicKeyB64Url, privateKey } = await makeKeyPair();
62
+ const v = createTierVerifier({ publicKeyB64Url, log: () => {} });
63
+ const exporterOnly = await sign(privateKey, { sub: 'u3', plan: 'free', products: ['exporter'] });
64
+ assert.equal(await v.verifyTier(`Bearer ${exporterOnly}`), 'pro');
65
+ const backupOnly = await sign(privateKey, { sub: 'u4', plan: 'free', products: ['backup'] });
66
+ assert.equal(await v.verifyTier(`Bearer ${backupOnly}`), 'free', '只有 Backup 无 exporter → 不享插件导出优先级');
67
+ });
68
+
69
+ test('过期 token(含 60s 容差内)→ free,绝不拦截', async () => {
70
+ const { publicKeyB64Url, privateKey } = await makeKeyPair();
71
+ const v = createTierVerifier({ publicKeyB64Url, log: () => {} });
72
+ const expired = await sign(privateKey, { sub: 'u1', plan: 'pro' }, { expires: '-1h' });
73
+ assert.equal(await v.verifyTier(`Bearer ${expired}`), 'free');
74
+ });
75
+
76
+ test('错误公钥签发的 token → free(签名不匹配)', async () => {
77
+ const { publicKeyB64Url } = await makeKeyPair();
78
+ const other = await makeKeyPair();
79
+ const v = createTierVerifier({ publicKeyB64Url, log: () => {} });
80
+ const forged = await sign(other.privateKey, { sub: 'u1', plan: 'pro' });
81
+ assert.equal(await v.verifyTier(`Bearer ${forged}`), 'free');
82
+ });
83
+
84
+ test('公钥未配置 ⇒ 功能关闭:恒 free 且 enabled=false(灰度安全)', async () => {
85
+ const { privateKey } = await makeKeyPair();
86
+ const v = createTierVerifier({ publicKeyB64Url: '', log: () => {} });
87
+ assert.equal(v.enabled, false);
88
+ const proToken = await sign(privateKey, { sub: 'u1', plan: 'pro' });
89
+ assert.equal(await v.verifyTier(`Bearer ${proToken}`), 'free');
90
+ });
91
+
92
+ test('非法公钥值 ⇒ enabled=false(与未配置同语义)', () => {
93
+ const v = createTierVerifier({ publicKeyB64Url: '!!!bad!!!', log: () => {} });
94
+ assert.equal(v.enabled, false);
95
+ });
96
+ });
tests/unit/pdf-jobs-priority.test.mjs ADDED
@@ -0,0 +1,359 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * pdf-jobs PRO 优先级 + 过载护栏单测(144 号方案 P1.1/P1.5/P1.2,2026-11-05)。
3
+ *
4
+ * 运行:node --test tests/unit/
5
+ * 无框架依赖(node:test 内置);createPdfJobService 的 fetchImpl 注入点用来
6
+ * 控制渲染时长,从而确定性地观测派发顺序/排队信息/429 阶梯。
7
+ */
8
+ import { test, describe } from 'node:test';
9
+ import assert from 'node:assert/strict';
10
+ import { createRequire } from 'node:module';
11
+ import { mkdtempSync, rmSync } from 'node:fs';
12
+ import { tmpdir } from 'node:os';
13
+ import { join } from 'node:path';
14
+
15
+ const require = createRequire(import.meta.url);
16
+ const { createPdfJobService, STATUS } = require('../../lib/pdf-jobs.js');
17
+
18
+ const PDF_BYTES = Buffer.from('%PDF-1.4 test');
19
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
20
+
21
+ /** 可控渲染时长的假回环:每次调用登记 body,renderMs 后返回假 PDF */
22
+ function makeFakeRender(order, renderMs = 80) {
23
+ return async (url, opts = {}) => {
24
+ order.push(String(opts.body || ''));
25
+ if (renderMs > 0) await sleep(renderMs);
26
+ return {
27
+ ok: true,
28
+ status: 200,
29
+ arrayBuffer: async () => PDF_BYTES.buffer.slice(PDF_BYTES.byteOffset, PDF_BYTES.byteOffset + PDF_BYTES.length),
30
+ };
31
+ };
32
+ }
33
+
34
+ function makeService(overrides = {}, renderMs = 80) {
35
+ const order = [];
36
+ const dir = mkdtempSync(join(tmpdir(), 'pdf-jobs-test-'));
37
+ const svc = createPdfJobService({
38
+ selfOrigin: 'http://127.0.0.1:1',
39
+ concurrency: 1,
40
+ sweepIntervalMs: 3_600_000,
41
+ resultDir: join(dir, 'r'),
42
+ fetchImpl: makeFakeRender(order, renderMs),
43
+ log: () => {},
44
+ ...overrides,
45
+ });
46
+ const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }); } catch { /* win 临时目录 */ } };
47
+ return { svc, order, cleanup };
48
+ }
49
+
50
+ /** 挂载提交/轮询路由并返回可调用的 handler */
51
+ function mount(svc) {
52
+ const app = {
53
+ post: (p, h) => { if (p === '/api/pdf_jobs') app.submit = h; },
54
+ get: (p, h) => { if (p === '/api/pdf_jobs/:id') app.poll = h; },
55
+ delete: (p, h) => { if (p === '/api/pdf_jobs/:id') app.cancel = h; },
56
+ };
57
+ svc.register(app);
58
+ const send = async (bodyStr, tier = 'free') => {
59
+ const req = {
60
+ body: { body: bodyStr },
61
+ headers: tier === 'pro' ? { authorization: 'Bearer pro-token' } : {},
62
+ };
63
+ const res = { headers: {}, redirected: false };
64
+ res.set = (k, v) => { res.headers[String(k).toLowerCase()] = v; return res; };
65
+ res.status = (c) => { res.statusCode = c; return res; };
66
+ res.json = (o) => { res.body = o; return res; };
67
+ res.redirect = (c, loc) => { res.statusCode = c; res.location = loc; res.redirected = true; return res; };
68
+ await app.submit(req, res);
69
+ return res;
70
+ };
71
+ const poll = (jobId) => {
72
+ const res = { headers: {}, redirected: false };
73
+ res.set = (k, v) => { res.headers[k] = v; return res; };
74
+ res.status = (c) => { res.statusCode = c; return res; };
75
+ res.json = (o) => { res.body = o; return res; };
76
+ res.redirect = (c, loc) => { res.statusCode = c; res.location = loc; res.redirected = true; return res; };
77
+ app.poll({ params: { id: jobId } }, res);
78
+ return res;
79
+ };
80
+ const cancel = (jobId) => {
81
+ const res = { headers: {} };
82
+ res.set = (k, v) => { res.headers[k] = v; return res; };
83
+ res.status = (c) => { res.statusCode = c; return res; };
84
+ res.json = (o) => { res.body = o; return res; };
85
+ app.cancel({ params: { id: jobId } }, res);
86
+ return res;
87
+ };
88
+ return { send, poll, cancel };
89
+ }
90
+
91
+ describe('PRO 优先级派发', () => {
92
+ const tiered = { verifyTier: async (h) => (h && h.startsWith('Bearer ') ? 'pro' : 'free') };
93
+
94
+ test('pro 后到但先渲染(插队到 free 段之前)', async () => {
95
+ const made = makeService({ concurrency: 1, ...tiered }, 60);
96
+ const { send } = mount(made.svc);
97
+ const f1 = await send('free-1');
98
+ await sleep(10); // 让 pump 派发 free-1(渲染挂 60ms,此时它处于 RUNNING)
99
+ const f2 = await send('free-2');
100
+ const p1 = await send('pro-1', 'pro');
101
+ assert.equal(f1.statusCode, 202);
102
+ assert.equal(f2.statusCode, 202);
103
+ assert.equal(p1.statusCode, 202);
104
+ assert.equal(p1.body.queue_position, 1, '前方 = 1 个在渲染的 free-1(free-2 排在 pro 之后不计入)');
105
+
106
+ await sleep(500); // free-1 → pro-1 → free-2
107
+ assert.deepEqual(
108
+ made.order.map((b) => JSON.parse(b).body),
109
+ ['free-1', 'pro-1', 'free-2'],
110
+ 'pro 必须插到所有 free 之前渲染',
111
+ );
112
+ made.cleanup();
113
+ });
114
+
115
+ test('同层内保持 FIFO', async () => {
116
+ const made = makeService({ concurrency: 1, ...tiered }, 30);
117
+ const { send } = mount(made.svc);
118
+ await send('p1', 'pro');
119
+ await send('p2', 'pro');
120
+ await send('f1', 'free');
121
+ await send('p3', 'pro');
122
+ await sleep(400);
123
+ assert.deepEqual(made.order.map((b) => JSON.parse(b).body), ['p1', 'p2', 'p3', 'f1']);
124
+ made.cleanup();
125
+ });
126
+
127
+ test('无 Authorization 头 ⇒ free(fail-open,绝不拦截)', async () => {
128
+ const made = makeService({ concurrency: 1, verifyTier: async () => 'pro' }, 20);
129
+ const { send } = mount(made.svc);
130
+ await send('a');
131
+ await send('b');
132
+ await sleep(200);
133
+ assert.deepEqual(made.order.map((b) => JSON.parse(b).body), ['a', 'b']);
134
+ made.cleanup();
135
+ });
136
+ });
137
+
138
+ describe('过载 429 阶梯(语义化响应体)', () => {
139
+ test('免费独立上限:free 先吃 429,PRO 绕过直到 queueLimit', async () => {
140
+ const made = makeService({
141
+ concurrency: 1,
142
+ queueLimit: 6,
143
+ freeQueueLimit: 3,
144
+ tieringEnabled: true,
145
+ verifyTier: async (h) => (h && h.startsWith('Bearer ') ? 'pro' : 'free'),
146
+ }, 5_000); // 渲染挂住 → 全部堆在队列里
147
+ const { send } = mount(made.svc);
148
+ await send('f1'); await send('f2'); await send('f3');
149
+ const f4 = await send('f4', 'free');
150
+ assert.equal(f4.statusCode, 429, '第 4 个 free 超出 freeQueueLimit=3 → 429');
151
+ assert.equal(f4.body.error, 'queue_full');
152
+ assert.equal(f4.body.retryable, true);
153
+ assert.equal(f4.body.reason, 'overloaded');
154
+ assert.ok(f4.headers['retry-after']);
155
+ const p1 = await send('p1', 'pro');
156
+ const p2 = await send('p2', 'pro');
157
+ const p3 = await send('p3', 'pro');
158
+ assert.equal(p1.statusCode, 202, 'PRO 绕过免费上限');
159
+ assert.equal(p2.statusCode, 202);
160
+ assert.equal(p3.statusCode, 202);
161
+ const p4 = await send('p4', 'pro');
162
+ assert.equal(p4.statusCode, 429, '总上限 queueLimit=6 对 PRO 依然生效');
163
+ assert.equal(p4.body.reason, 'overloaded');
164
+ made.svc.jobs.clear();
165
+ made.cleanup();
166
+ });
167
+
168
+ test('tiering 关闭时免费上限失效(灰度安全:行为同旧版)', async () => {
169
+ const made = makeService({
170
+ concurrency: 1,
171
+ queueLimit: 6,
172
+ freeQueueLimit: 2,
173
+ tieringEnabled: false, // 关键:无公钥部署形态
174
+ }, 5_000);
175
+ const { send } = mount(made.svc);
176
+ const codes = [];
177
+ for (let i = 0; i < 6; i++) codes.push((await send(`f${i}`)).statusCode);
178
+ assert.deepEqual(codes, [202, 202, 202, 202, 202, 202], '无公钥 → 6 个 free 全收(旧版行为)');
179
+ made.svc.jobs.clear();
180
+ made.cleanup();
181
+ });
182
+
183
+ test('待处理字节上限 → 429 memory_guard', async () => {
184
+ const made = makeService({ concurrency: 1, maxPendingBytes: 1000 }, 5_000);
185
+ const { send } = mount(made.svc);
186
+ const r1 = await send('x'.repeat(900));
187
+ assert.equal(r1.statusCode, 202);
188
+ const r2 = await send('x'.repeat(200));
189
+ assert.equal(r2.statusCode, 429);
190
+ assert.equal(r2.body.reason, 'memory_guard');
191
+ assert.equal(r2.body.retryable, true);
192
+ made.svc.jobs.clear();
193
+ made.cleanup();
194
+ });
195
+
196
+ test('排队深度超阈拒收大文档(小文档不受影响)', async () => {
197
+ const bigDocBytes = 500;
198
+ const made = makeService({
199
+ concurrency: 1,
200
+ bigDocBytes,
201
+ bigDocQueueDepth: 2,
202
+ maxPendingBytes: 100 * 1024 * 1024,
203
+ }, 5_000);
204
+ const { send } = mount(made.svc);
205
+ await send('q-filler-1');
206
+ await send('q-filler-2');
207
+ await send('q-filler-3'); // queued=2(1 running)
208
+ const big = await send('B'.repeat(bigDocBytes + 1));
209
+ assert.equal(big.statusCode, 429);
210
+ assert.equal(big.body.reason, 'memory_guard', 'queued≥2 时新大文档被拒');
211
+ const small = await send('tiny');
212
+ assert.equal(small.statusCode, 202, '小文档不受大文档深度闸影响');
213
+ made.svc.jobs.clear();
214
+ made.cleanup();
215
+ });
216
+
217
+ test('幂等复用不受容量闸约束(PENDING 也复用)+ PRO 提交同内容升格插队', async () => {
218
+ const made = makeService({
219
+ concurrency: 1,
220
+ queueLimit: 1,
221
+ freeQueueLimit: 1,
222
+ verifyTier: async (h) => (h && h.startsWith('Bearer ') ? 'pro' : 'free'),
223
+ }, 5_000);
224
+ const { send } = mount(made.svc);
225
+ const r1 = await send('same-content');
226
+ const r2 = await send('same-content');
227
+ assert.equal(r1.statusCode, 202);
228
+ assert.equal(r2.statusCode, 202, '同内容复用即使队列已满也放行(复用零新增渲染,PENDING 阶段同样适用)');
229
+ assert.equal(r2.body.reused, true);
230
+ const r3 = await send('same-content', 'pro');
231
+ assert.equal(r3.statusCode, 202);
232
+ assert.equal(r3.body.queue_position, 0, 'PRO 提交同内容 → 排队中的既有作业升格 pro → 插到队首');
233
+ made.svc.jobs.clear();
234
+ made.cleanup();
235
+ });
236
+ });
237
+
238
+ describe('大文档串行(OOM 护栏)', () => {
239
+ test('bigDocConcurrency=1:两个大文档不并行,其后小文档不受阻', async () => {
240
+ const bigDocBytes = 100;
241
+ const made = makeService({ concurrency: 3, bigDocBytes, bigDocConcurrency: 1 }, 120);
242
+ const { send } = mount(made.svc);
243
+ await send('B'.repeat(bigDocBytes + 1) + '#1');
244
+ await send('B'.repeat(bigDocBytes + 1) + '#2');
245
+ await send('small-1');
246
+ await send('small-2');
247
+ await sleep(80); // 首个大文档已开始,其余应派发 small-1/small-2(大2等待)
248
+ const dispatched = made.order.map((b) => JSON.parse(b).body);
249
+ assert.equal(dispatched.filter((b) => b.startsWith('B')).length, 1, '同一时刻只派发 1 个大文档');
250
+ assert.ok(dispatched.includes('small-1') && dispatched.includes('small-2'), '大文档等串行槽位时小文档继续派发');
251
+ made.svc.jobs.clear();
252
+ made.cleanup();
253
+ });
254
+ });
255
+
256
+ describe('排队可视化信息(queue_position / eta_ms)', () => {
257
+ test('排队作业携带位置与 ETA;渲染后为 null;202 带 X-Queue-* 头', async () => {
258
+ const made = makeService({ concurrency: 1, etaSmallMs: 30_000 }, 60);
259
+ const { send, poll } = mount(made.svc);
260
+ const r1 = await send('job-1');
261
+ const r2 = await send('job-2');
262
+ assert.equal(r1.statusCode, 202);
263
+ assert.equal(r2.statusCode, 202);
264
+ assert.equal(r2.body.queue_position, 1);
265
+ assert.ok(Number.isFinite(r2.body.eta_ms) && r2.body.eta_ms >= 0, 'eta_ms 为非负数');
266
+ assert.ok(r2.headers['x-queue-position'] !== undefined, '202 响应带 X-Queue-Position 头');
267
+ assert.ok(r2.headers['x-queue-eta-ms'] !== undefined, '202 响应带 X-Queue-Eta-Ms 头');
268
+ await sleep(220); // 两个都渲染完
269
+ const done = poll(r2.body.jobId);
270
+ assert.equal(done.statusCode, 303, 'SUCCEEDED → 303 转下载');
271
+ made.cleanup();
272
+ });
273
+
274
+ test('轮询端点:排队中给出位置;RUNNING 后置 null', async () => {
275
+ const made = makeService({ concurrency: 1, etaSmallMs: 30_000 }, 5_000); // 挂住渲染
276
+ const { send, poll } = mount(made.svc);
277
+ const r1 = await send('running-1');
278
+ const r2 = await send('queued-2');
279
+ const q = poll(r2.body.jobId);
280
+ assert.equal(q.statusCode, 200);
281
+ assert.equal(q.body.status, STATUS.PENDING);
282
+ assert.equal(q.body.queue_position, 1);
283
+ assert.equal(q.body.eta_ms, 30_000, '前方 1 个 small、concurrency=1 → eta=ewmaSmall 初值');
284
+ await sleep(50); // 让 setImmediate(pump) 跑到:running-1 进入 RUNNING(渲染挂住 5s)
285
+ const r1s = poll(r1.body.jobId);
286
+ assert.equal(r1s.body.status, STATUS.RUNNING);
287
+ assert.equal(r1s.body.queue_position, null, 'RUNNING 作业无排队信息');
288
+ made.svc.jobs.clear();
289
+ made.cleanup();
290
+ });
291
+
292
+ test('eta 随成功渲染收敛(EWMA 更新)', async () => {
293
+ const made = makeService({ concurrency: 1, etaSmallMs: 30_000 }, 40);
294
+ const { send } = mount(made.svc);
295
+ await send('e-1');
296
+ await sleep(150);
297
+ const st = made.svc.stats();
298
+ assert.ok(st.ewmaSmallMs < 30_000, `成功渲染(40ms)后 EWMA 应从 30000 下降,实际 ${st.ewmaSmallMs}`);
299
+ made.cleanup();
300
+ });
301
+
302
+ test('stats() 暴露护栏水位(/health 数据源)', async () => {
303
+ const made = makeService({ concurrency: 2, tieringEnabled: true, freeQueueLimit: 7 }, 5_000);
304
+ const { send } = mount(made.svc);
305
+ await send('s-1');
306
+ const st = made.svc.stats();
307
+ assert.equal(st.tieringEnabled, true);
308
+ assert.equal(st.freeQueueLimit, 7);
309
+ assert.equal(st.maxPendingBytes, 256 * 1024 * 1024);
310
+ assert.ok(st.pendingBytes > 0);
311
+ made.svc.jobs.clear();
312
+ made.cleanup();
313
+ });
314
+
315
+ test('默认免费上限 = queueLimit 的 80%(2026-11-07 产品决策:留 PRO 保留位)', () => {
316
+ const made = makeService({ concurrency: 2, tieringEnabled: true }, 5_000);
317
+ const st = made.svc.stats();
318
+ assert.equal(st.queueLimit, 50);
319
+ assert.equal(st.freeQueueLimit, 40, '默认必须是 50 的 80%,PRO 恒有 ≥10 槽位');
320
+ made.cleanup();
321
+ });
322
+
323
+ test('免费闩锁:到限冻结后渲染完成腾出的空位也不再放行免费,直到跌破恢复水位', async () => {
324
+ // freeQueueLimit=4 → 恢复水位 = floor(4×0.5)=2。渲染挂住(5s),用 DELETE
325
+ // 精确控制 active——确定性验证闩锁的「冻结 → 水位以下才解锁」两段语义
326
+ const tiered = { tieringEnabled: true, freeQueueLimit: 4, verifyTier: async (h) => (h && h.startsWith('Bearer ') ? 'pro' : 'free') };
327
+ const made = makeService({ concurrency: 1, ...tiered }, 5_000);
328
+ const { send, cancel } = mount(made.svc);
329
+ const f1 = await send('f1'); const f2 = await send('f2');
330
+ const f3 = await send('f3'); const f4 = await send('f4');
331
+ assert.deepEqual([f1, f2, f3, f4].map((r) => r.statusCode), [202, 202, 202, 202], '填到上限 4');
332
+ const f5 = await send('f5');
333
+ assert.equal(f5.statusCode, 429);
334
+ assert.equal(f5.body.latched, true, '到限即闩上');
335
+ // active=3(≥水位2):渲染完成腾出的空位也不再放行免费
336
+ cancel(f2.body.jobId);
337
+ const f6 = await send('f6');
338
+ assert.equal(f6.statusCode, 429, 'active=3 仍在闩锁期');
339
+ assert.equal(f6.body.latched, true);
340
+ // active=2(=水位,边界):不 <2 → 仍闩
341
+ cancel(f3.body.jobId);
342
+ const f7 = await send('f7');
343
+ assert.equal(f7.statusCode, 429, 'active=2 等于水位(不小于)仍闩');
344
+ // PRO 不受闩锁影响:照常受理(这也证明闩锁期 active 会因 PRO 入队上升)
345
+ const p1 = await send('p1', 'pro');
346
+ assert.equal(p1.statusCode, 202, 'PRO 完全绕过闩锁');
347
+ const f8 = await send('f8');
348
+ assert.equal(f8.statusCode, 429, 'PRO 提交不解锁免费闩锁');
349
+ // active=1(< 水位 2):解锁,免费重新放行
350
+ cancel(f4.body.jobId);
351
+ const f9 = await send('f9');
352
+ assert.equal(f9.statusCode, 429, 'active=2 仍闩(p1 入队后 active 回升)');
353
+ cancel(p1.body.jobId);
354
+ const f10 = await send('f10');
355
+ assert.equal(f10.statusCode, 202, 'active=1 < 水位 2 → 解锁放行');
356
+ made.svc.jobs.clear();
357
+ made.cleanup();
358
+ });
359
+ });