XWX-AI commited on
Commit
7a795b3
·
1 Parent(s): 2e02419

fix(pdf): 作业回环取件解除undici默认300s头超时——大文档渲染成功却被判死根除+RUNNING孤儿看守30分钟(136号方案)

Browse files

根因(2026-10-30 NotebookLM 469问真机取证): worker回环调用/api/generate_pdf用
globalThis.fetch, 其默认Dispatcher带headersTimeout/bodyTimeout=300000ms。
渲染>300s的文档(16.8MB纯文本/2811页实测264~327s)取件在~301s整抛
TypeError: fetch failed(cause=HeadersTimeoutError/UND_ERR_HEADERS_TIMEOUT),
作业判死→客户端收500→按退避整轮重试再烧一遍完整渲染, 最坏10分钟且可能再败。
pdf-test容器日志三例全卡300s线: 296.61s成功/327s渲染完成但301s判死/264s成功。
135号思考步导出使渲染时长从~120s推过300s线才踩响这条存量地雷。

修复①: createNoTimeoutLoopbackFetch()——npm undici fetch+Agent
(headersTimeout:0/bodyTimeout:0)为默认loopbackFetch; cfg.fetchImpl测试注入
语义不变; fetch与Agent同包同引擎, 规避node20内置undici 5.x与npm 7.x跨包
brand校验风险。与server.js既有server.requestTimeout=0(入站方向,408修复)
配套, 覆盖出站回环方向; 渲染预算单一所有权仍是同步端点应用层动态超时
(立方公式封顶60min, Promise.race强制), 传输层不设竞争性超时。

修复②: RUNNING孤儿看守orphanMaxAgeMs默认30分钟(env PDF_JOB_ORPHAN_MAX_AGE_MS):
解除传输超时后'同步端点永不响应'场景失去旧300s的意外自愈——RUNNING不过期+
同内容重提交按摘要复用=永久卡死。30min=客户端作业总预算20min(插件
PDF_JOB_BUDGET_MS)耗尽后+10min余量, 彼时已无客户端在等, 只做后端内部卫生;
已观测渲染最长5.5min给足5倍余量。判死同时abort取消通道中止回环fetch,
execute()尽快落终态释放并发闸槽位; execute晚到结果守卫(status!==RUNNING
丢弃)防已判死作业被迟到的渲染结果复活。

依赖: +undici@^7.28.0(容器node v20.20.2满足≥20.18.1)。

server.js整文件同时携带并行会话的HIGHLIGHT_SYNTAX_ALIAS(xml→html高亮语法
映射, data-language标签保持原语言; 136号方案perplexity围栏语言归一的对齐项),
按共通文件整体提交原则一并入库。

验证: A/B复现程序(裸globalThis.fetch 306s桩300.8s失败HeadersTimeoutError /
Agent关超时306s成功, 错误签名与生产500逐字一致)+306s桩端到端经真实pdf-jobs
默认路径SUCCEEDED@306.1s(修复前该路径必死于~301s)+孤儿看守秒级确定性3/3
(挂起桩0.61s判FAILED(job_orphaned)→取消通道生效→重提交拿全新作业成功,
temp/test/notebooklm/2026-10-30/verify-{undici-headers-timeout,pdf-jobs-over-300s,orphan-guard}.mjs);
pdf-test容器重建后构造冒烟+容器内默认阈值30min实测。
兼容性: 对全部已发布插件版本零契约变化——同步端点一字未动(老版本无感);
作业通道版本(2026-10-15起)客户端只感受到>300s渲染从'必败+整轮重试'变为
'一次成功'(20min预算≫5.5min), FAILED分类仅按httpStatus与消息文案无关。

Files changed (4) hide show
  1. lib/pdf-jobs.js +68 -5
  2. package-lock.json +13 -3
  3. package.json +2 -1
  4. server.js +16 -3
lib/pdf-jobs.js CHANGED
@@ -41,6 +41,28 @@ function sha256(buf) {
41
  return crypto.createHash('sha256').update(buf).digest('hex');
42
  }
43
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
44
  /**
45
  * @param {Object} cfg
46
  * @param {string} cfg.selfOrigin 本服务自身的 origin(回环调用用),如 http://127.0.0.1:7860
@@ -51,6 +73,13 @@ function sha256(buf) {
51
  * @param {number} [cfg.queueLimit] 排队作业上限(默认 50),超了直接 429
52
  * @param {string} [cfg.resultDir] 结果落盘目录,默认 os.tmpdir()/xwx-pdf-jobs
53
  * @param {(msg:string)=>void} [cfg.log]
 
 
 
 
 
 
 
54
  * @param {typeof fetch} [cfg.fetchImpl] 仅供测试注入
55
  */
56
  function createPdfJobService(cfg) {
@@ -63,15 +92,20 @@ function createPdfJobService(cfg) {
63
  queueLimit = 50,
64
  resultDir = path.join(require('node:os').tmpdir(), 'xwx-pdf-jobs'),
65
  sweepIntervalMs = 60_000,
 
66
  log = (m) => console.log(m),
67
- fetchImpl = globalThis.fetch,
68
  } = cfg;
69
 
 
 
 
70
  if (!selfOrigin) throw new Error('createPdfJobService: selfOrigin is required');
71
  fs.mkdirSync(resultDir, { recursive: true });
72
 
73
  const jobs = new Map(); // jobId -> job
74
  const byDigest = new Map(); // sha256(body) -> jobId
 
75
  let running = 0;
76
  const waiters = [];
77
 
@@ -104,13 +138,25 @@ function createPdfJobService(cfg) {
104
  async function execute(job) {
105
  const t0 = Date.now();
106
  touch(job, { status: STATUS.RUNNING, phase: 'RENDERING', startedAt: nowIso() });
 
 
 
 
 
107
  try {
108
- const resp = await fetchImpl(selfOrigin + syncPath, {
109
  method: 'POST',
110
  headers: { 'Content-Type': 'application/json' },
111
  body: job.body,
 
112
  });
113
  const buf = Buffer.from(await resp.arrayBuffer());
 
 
 
 
 
 
114
  if (!resp.ok) {
115
  // 后端已给出 HTTP 语义错误(400/413/500…)——原样带进作业状态,客户端据此分类
116
  const snippet = buf.subarray(0, 500).toString('utf8');
@@ -128,15 +174,32 @@ function createPdfJobService(cfg) {
128
  log(`[PDF-JOB] ${job.jobId} SUCCEEDED ${(buf.length / 1048576).toFixed(2)}MB @${((Date.now() - t0) / 1000).toFixed(1)}s (queued=${job.queueWaitMs}ms)`);
129
  enforceRetention();
130
  } catch (e) {
131
- touch(job, { status: STATUS.FAILED, phase: 'FAILED', error: { message: `render_loopback_${e.name || 'Error'}: ${e.message}` } });
132
- log(`[PDF-JOB] ${job.jobId} ERROR ${e.name}: ${e.message}`);
 
 
 
 
133
  }
134
  }
135
 
136
- /** 立即回收已过期结果;并按总量上限淘汰最早完成的 */
137
  function enforceRetention() {
138
  const t = Date.now();
139
  for (const [id, job] of jobs) {
 
 
 
 
 
 
 
 
 
 
 
 
 
140
  if (job.file && ((job.expiresAt && job.expiresAt < t) || TERMINAL.has(job.status) && job.status !== STATUS.SUCCEEDED)) {
141
  discard(id, job);
142
  }
 
41
  return crypto.createHash('sha256').update(buf).digest('hex');
42
  }
43
 
44
+ /**
45
+ * 回环取件专用 fetch:解除 undici 默认 300s 头超时。
46
+ *
47
+ * worker 回环调用的是同步渲染端点,大文档要等几分钟才有响应头(16.8MB 纯文本
48
+ * / 2811 页实测 264–327s)。globalThis.fetch 的默认 Dispatcher 带
49
+ * headersTimeout/bodyTimeout=300s,渲染一旦越过 300s,取件在 ~301s 抛
50
+ * TypeError: fetch failed(cause=HeadersTimeoutError/UND_ERR_HEADERS_TIMEOUT),
51
+ * 作业判死、客户端收到 500 后整轮重试再烧一遍完整渲染(2026-10-30 取证:
52
+ * 296.61s 成功 / ~301s 失败 / 264s 成功,全部卡在 300s 线上;A/B 复现程序
53
+ * verify-undici-headers-timeout.mjs:裸 fetch 300.8s 失败,Agent 关闭超时
54
+ * 306s 成功)。与 server.js 的 server.requestTimeout=0(入站方向同一语义)
55
+ * 配套,这里覆盖出站回环方向。
56
+ *
57
+ * fetch 与 Agent 均取自 npm undici(与 Node 内置同引擎):同包实例经
58
+ * dispatcher 注入无跨包 brand 校验风险,node:20 内置 5.x 与 npm 7.x 混用不安全。
59
+ */
60
+ function createNoTimeoutLoopbackFetch() {
61
+ const { fetch: undiciFetch, Agent } = require('undici');
62
+ const agent = new Agent({ headersTimeout: 0, bodyTimeout: 0 });
63
+ return (url, opts = {}) => undiciFetch(url, { ...opts, dispatcher: agent });
64
+ }
65
+
66
  /**
67
  * @param {Object} cfg
68
  * @param {string} cfg.selfOrigin 本服务自身的 origin(回环调用用),如 http://127.0.0.1:7860
 
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 分钟):回环取件
77
+ * 解除 300s 默认超时后(见 createNoTimeoutLoopbackFetch),对"同步端点永不响应"
78
+ * 的极端场景失去了旧超时的意外自愈——RUNNING 不过期 + 同内容重提交按摘要复用
79
+ * = 永久卡死。30 分钟 = 客户端侧作业总预算(插件 PDF_JOB_BUDGET_MS=20min)耗尽
80
+ * 后再留 10 分钟余量:彼时已无任何客户端在等结果,判死只影响后端内部卫生,
81
+ * 不影响任何人的等待体验。已观测渲染最长 5.5 分钟(16.8MB/2811 页),
82
+ * 30 分钟给足 5 倍余量
83
  * @param {typeof fetch} [cfg.fetchImpl] 仅供测试注入
84
  */
85
  function createPdfJobService(cfg) {
 
92
  queueLimit = 50,
93
  resultDir = path.join(require('node:os').tmpdir(), 'xwx-pdf-jobs'),
94
  sweepIntervalMs = 60_000,
95
+ orphanMaxAgeMs = 30 * 60_000,
96
  log = (m) => console.log(m),
97
+ fetchImpl,
98
  } = cfg;
99
 
100
+ // 默认走无超时回环 fetch;测试注入的 fetchImpl 语义自带(如需超时行为由注入方决定)
101
+ const loopbackFetch = fetchImpl || createNoTimeoutLoopbackFetch();
102
+
103
  if (!selfOrigin) throw new Error('createPdfJobService: selfOrigin is required');
104
  fs.mkdirSync(resultDir, { recursive: true });
105
 
106
  const jobs = new Map(); // jobId -> job
107
  const byDigest = new Map(); // sha256(body) -> jobId
108
+ const jobFetchCancels = new Map(); // jobId -> AbortController(孤儿看守取消回环传输用)
109
  let running = 0;
110
  const waiters = [];
111
 
 
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 槽位永久占死
144
+ const cancel = new AbortController();
145
+ jobFetchCancels.set(job.jobId, cancel);
146
  try {
147
+ const resp = await loopbackFetch(selfOrigin + syncPath, {
148
  method: 'POST',
149
  headers: { 'Content-Type': 'application/json' },
150
  body: job.body,
151
+ signal: cancel.signal,
152
  });
153
  const buf = Buffer.from(await resp.arrayBuffer());
154
+ // 孤儿守卫:看守已在异常超龄时把本作业判 FAILED,晚到的渲染结果不得复活
155
+ // 它(复活会让客户端已拿到的 FAILED 与摘要复用指向互相矛盾的状态)
156
+ if (job.status !== STATUS.RUNNING) {
157
+ log(`[PDF-JOB] ${job.jobId} late result after ${job.status}, discarded`);
158
+ return;
159
+ }
160
  if (!resp.ok) {
161
  // 后端已给出 HTTP 语义错误(400/413/500…)——原样带进作业状态,客户端据此分类
162
  const snippet = buf.subarray(0, 500).toString('utf8');
 
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) {
178
+ touch(job, { status: STATUS.FAILED, phase: 'FAILED', error: { message: `render_loopback_${e.name || 'Error'}: ${e.message}` } });
179
+ }
180
+ log(`[PDF-JOB] ${job.jobId} ERROR ${e.name}: ${e.message} (status=${job.status})`);
181
+ } finally {
182
+ jobFetchCancels.delete(job.jobId);
183
  }
184
  }
185
 
186
+ /** 立即回收已过期结果;并按总量上限淘汰最早完成的;顺带执行 RUNNING 孤儿看守 */
187
  function enforceRetention() {
188
  const t = Date.now();
189
  for (const [id, job] of jobs) {
190
+ // 孤儿看守:RUNNING 超阈值 ⇒ 同步端点的应用层预算已失效(已观测渲染最长
191
+ // 5.5 分钟;客户端作业总预算 20 分钟,彼时已无人在等),判死让摘要表干净、
192
+ // 重提交能拿全新作业(FAILED 不复用)。execute() 的晚到结果由 statusRunning 守卫丢弃。
193
+ if (job.status === STATUS.RUNNING && job.startedAt &&
194
+ t - Date.parse(job.startedAt) > orphanMaxAgeMs) {
195
+ touch(job, {
196
+ status: STATUS.FAILED, phase: 'FAILED',
197
+ error: { message: `job_orphaned: RUNNING exceeded ${Math.round(orphanMaxAgeMs / 60000)}min without completing` },
198
+ });
199
+ // 同步中止回环传输:execute() 尽快落 catch 终态并释放并发闸槽位
200
+ jobFetchCancels.get(id)?.abort(new Error('job_orphaned'));
201
+ log(`[PDF-JOB] ${job.jobId} ORPHANED after ${Math.round((t - Date.parse(job.startedAt)) / 60000)}min RUNNING`);
202
+ }
203
  if (job.file && ((job.expiresAt && job.expiresAt < t) || TERMINAL.has(job.status) && job.status !== STATUS.SUCCEEDED)) {
204
  discard(id, job);
205
  }
package-lock.json CHANGED
@@ -1,12 +1,12 @@
1
  {
2
  "name": "pdf-server",
3
- "version": "3.1.2",
4
  "lockfileVersion": 3,
5
  "requires": true,
6
  "packages": {
7
  "": {
8
  "name": "pdf-server",
9
- "version": "3.1.2",
10
  "dependencies": {
11
  "@mermaid-js/mermaid-cli": "^11.0.0",
12
  "chart.js": "^4.4.8",
@@ -15,7 +15,8 @@
15
  "express": "^4.18.2",
16
  "lucide-static": "^1.55.0",
17
  "puppeteer": "^24.0.0",
18
- "shiki": "^1.24.0"
 
19
  }
20
  },
21
  "node_modules/@alloc/quick-lru": {
@@ -5874,6 +5875,15 @@
5874
  "integrity": "sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==",
5875
  "license": "MIT"
5876
  },
 
 
 
 
 
 
 
 
 
5877
  "node_modules/undici-types": {
5878
  "version": "7.24.6",
5879
  "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
 
1
  {
2
  "name": "pdf-server",
3
+ "version": "3.2.3",
4
  "lockfileVersion": 3,
5
  "requires": true,
6
  "packages": {
7
  "": {
8
  "name": "pdf-server",
9
+ "version": "3.2.3",
10
  "dependencies": {
11
  "@mermaid-js/mermaid-cli": "^11.0.0",
12
  "chart.js": "^4.4.8",
 
15
  "express": "^4.18.2",
16
  "lucide-static": "^1.55.0",
17
  "puppeteer": "^24.0.0",
18
+ "shiki": "^1.24.0",
19
+ "undici": "^7.30.1"
20
  }
21
  },
22
  "node_modules/@alloc/quick-lru": {
 
5875
  "integrity": "sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==",
5876
  "license": "MIT"
5877
  },
5878
+ "node_modules/undici": {
5879
+ "version": "7.30.1",
5880
+ "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz",
5881
+ "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==",
5882
+ "license": "MIT",
5883
+ "engines": {
5884
+ "node": ">=20.18.1"
5885
+ }
5886
+ },
5887
  "node_modules/undici-types": {
5888
  "version": "7.24.6",
5889
  "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
package.json CHANGED
@@ -11,7 +11,8 @@
11
  "express": "^4.18.2",
12
  "lucide-static": "^1.55.0",
13
  "puppeteer": "^24.0.0",
14
- "shiki": "^1.24.0"
 
15
  },
16
  "scripts": {
17
  "start": "node server.js"
 
11
  "express": "^4.18.2",
12
  "lucide-static": "^1.55.0",
13
  "puppeteer": "^24.0.0",
14
+ "shiki": "^1.24.0",
15
+ "undici": "^7.30.1"
16
  },
17
  "scripts": {
18
  "start": "node server.js"
server.js CHANGED
@@ -85,6 +85,15 @@ async function initShiki() {
85
  }
86
 
87
  // Pre-highlight code blocks in HTML using Shiki (inline styles)
 
 
 
 
 
 
 
 
 
88
  function highlightHtmlWithShiki(html, themeName = 'github-light') {
89
  if (!shikiHighlighter) return html;
90
 
@@ -100,12 +109,13 @@ function highlightHtmlWithShiki(html, themeName = 'github-light') {
100
  || preAttrs.match(/data-language="(\w+)"/i);
101
  if (classMatch) lang = classMatch[1].toLowerCase();
102
 
103
- // Try Shiki highlight
104
- if (lang && shikiHighlighter.getLoadedLanguages().includes(lang)) {
 
105
  try {
106
  let highlighted = shikiHighlighter.codeToHtml(codeText
107
  .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/&quot;/g, '"'),
108
- { lang, theme: shikiTheme }
109
  );
110
  // Restore data-language attribute for CSS language label display
111
  highlighted = highlighted.replace(/<pre\s/, `<pre data-language="${lang}" `);
@@ -1475,6 +1485,9 @@ const pdfJobs = createPdfJobService({
1475
  selfOrigin: `http://127.0.0.1:${port}`,
1476
  concurrency: Number(process.env.PDF_JOB_CONCURRENCY || 2),
1477
  ttlMs: Number(process.env.PDF_JOB_TTL_MS || 30 * 60 * 1000),
 
 
 
1478
  });
1479
  pdfJobs.register(app);
1480
 
 
85
  }
86
 
87
  // Pre-highlight code blocks in HTML using Shiki (inline styles)
88
+ //
89
+ // 高亮语法映射(2026-10-30):语言标签与高亮语法解耦。Perplexity 等平台在标签上显示
90
+ // 归一语言(xml),但底层高亮引擎(prism markup)带内嵌 JS/CSS 着色——Shiki 的 xml
91
+ // 语法是纯 XML(script 内 const 等关键字无色),html 语法才有内嵌 JS。用 html 语法
92
+ // 高亮、保留 xml 标签 = 与网页渲染逐字同语义(网页同款:标签/属性/内嵌 JS 全有色)。
93
+ const HIGHLIGHT_SYNTAX_ALIAS = {
94
+ xml: 'html', // prism markup 同语义:内嵌 script/style 的 JS/CSS 着色
95
+ };
96
+
97
  function highlightHtmlWithShiki(html, themeName = 'github-light') {
98
  if (!shikiHighlighter) return html;
99
 
 
109
  || preAttrs.match(/data-language="(\w+)"/i);
110
  if (classMatch) lang = classMatch[1].toLowerCase();
111
 
112
+ // Try Shiki highlight(语法别名只影响高亮引擎,data-language 标签保持原语言)
113
+ const syntax = HIGHLIGHT_SYNTAX_ALIAS[lang] || lang;
114
+ if (syntax && shikiHighlighter.getLoadedLanguages().includes(syntax)) {
115
  try {
116
  let highlighted = shikiHighlighter.codeToHtml(codeText
117
  .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/&quot;/g, '"'),
118
+ { lang: syntax, theme: shikiTheme }
119
  );
120
  // Restore data-language attribute for CSS language label display
121
  highlighted = highlighted.replace(/<pre\s/, `<pre data-language="${lang}" `);
 
1485
  selfOrigin: `http://127.0.0.1:${port}`,
1486
  concurrency: Number(process.env.PDF_JOB_CONCURRENCY || 2),
1487
  ttlMs: Number(process.env.PDF_JOB_TTL_MS || 30 * 60 * 1000),
1488
+ // 孤儿看守阈值:客户端作业总预算 20 分钟(插件 PDF_JOB_BUDGET_MS),30 分钟 =
1489
+ // 全部客户端离场后留 10 分钟余量,只做后端内部卫生,不影响任何等待体验
1490
+ orphanMaxAgeMs: Number(process.env.PDF_JOB_ORPHAN_MAX_AGE_MS || 30 * 60 * 1000),
1491
  });
1492
  pdfJobs.register(app);
1493