feat: 实现 Chromium PDF 导出与精确预览
This commit is contained in:
SkyJourney
@@ -1,10 +1,19 @@
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import type { FastifyInstance } from "fastify";
|
||||
import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { buildApp } from "../src/app.js";
|
||||
import {
|
||||
createPdfContentDisposition,
|
||||
createPdfFileName
|
||||
} from "../src/app.js";
|
||||
import { createThemeRegistry } from "../src/theme-registry.js";
|
||||
import {
|
||||
PdfEngineOverloadedError,
|
||||
type PdfGenerator
|
||||
} from "../src/pdf-engine.js";
|
||||
import { defaultExportConfig } from "@md-to-pdf/core";
|
||||
|
||||
let app: FastifyInstance | undefined;
|
||||
let temporaryDirectory: string | undefined;
|
||||
@@ -40,6 +49,36 @@ afterEach(async () => {
|
||||
});
|
||||
|
||||
describe("预览 API", () => {
|
||||
it("关闭应用时释放 PDF 生成器", async () => {
|
||||
const close = vi.fn(async () => undefined);
|
||||
const pdfGenerator = {
|
||||
generate: vi.fn(),
|
||||
close
|
||||
} as unknown as PdfGenerator;
|
||||
app = buildApp({ pdfGenerator, logger: false });
|
||||
|
||||
await app.close();
|
||||
|
||||
expect(close).toHaveBeenCalledTimes(1);
|
||||
app = undefined;
|
||||
});
|
||||
|
||||
it("按配置在应用就绪时预热 PDF 浏览器", async () => {
|
||||
const warmup = vi.fn(async () => undefined);
|
||||
app = buildApp({
|
||||
logger: false,
|
||||
prewarmPdfBrowser: true,
|
||||
pdfGenerator: {
|
||||
generate: vi.fn(),
|
||||
warmup,
|
||||
close: vi.fn(async () => undefined)
|
||||
} as unknown as PdfGenerator
|
||||
});
|
||||
|
||||
await app.ready();
|
||||
expect(warmup).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("渲染 Markdown 并返回安全文章结构", async () => {
|
||||
app = buildApp();
|
||||
const response = await app.inject({
|
||||
@@ -222,3 +261,134 @@ describe("预览 API", () => {
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("PDF API", () => {
|
||||
it("生成 PDF 并返回安全的 UTF-8 下载文件名", async () => {
|
||||
const generate = vi.fn(async () => ({
|
||||
pdf: Buffer.from("%PDF-test"),
|
||||
pageCount: 3,
|
||||
mermaidErrors: ["图表 1"],
|
||||
timings: {
|
||||
queueMs: 0,
|
||||
browserMs: 1,
|
||||
contextMs: 2,
|
||||
navigationMs: 3,
|
||||
documentRenderMs: 4,
|
||||
runtimeSetupMs: 0.1,
|
||||
mermaidMs: 0.2,
|
||||
mermaidFitMs: 0.3,
|
||||
mermaidConversionMs: 0.35,
|
||||
resourceWaitMs: 0.4,
|
||||
paginationMs: 0.5,
|
||||
finalizeMs: 0.6,
|
||||
runtimeTotalMs: 2.1,
|
||||
pdfPrintMs: 5,
|
||||
totalMs: 15
|
||||
}
|
||||
}));
|
||||
app = buildApp({
|
||||
logger: false,
|
||||
pdfGenerator: {
|
||||
generate,
|
||||
close: vi.fn(async () => undefined)
|
||||
}
|
||||
});
|
||||
|
||||
const response = await app.inject({
|
||||
method: "POST",
|
||||
url: "/api/pdf",
|
||||
payload: {
|
||||
markdown: "# 测试文档",
|
||||
fileName: "目录/测试文档.md",
|
||||
language: "zh-CN",
|
||||
exportConfig: defaultExportConfig
|
||||
}
|
||||
});
|
||||
|
||||
expect(response.statusCode).toBe(200);
|
||||
expect(response.headers["content-type"]).toContain(
|
||||
"application/pdf"
|
||||
);
|
||||
expect(response.headers["content-disposition"]).toContain(
|
||||
"filename*=UTF-8''%E6%B5%8B%E8%AF%95%E6%96%87%E6%A1%A3.pdf"
|
||||
);
|
||||
expect(response.headers["x-pdf-page-count"]).toBe("3");
|
||||
expect(response.headers["x-mermaid-error-count"]).toBe("1");
|
||||
expect(response.headers["server-timing"]).toContain(
|
||||
"document-render;dur=4.0"
|
||||
);
|
||||
expect(response.headers["server-timing"]).toContain(
|
||||
"pdf-print;dur=5.0"
|
||||
);
|
||||
expect(response.headers["server-timing"]).toContain(
|
||||
"mermaid;dur=0.2"
|
||||
);
|
||||
expect(response.headers["server-timing"]).toContain(
|
||||
"mermaid-conversion;dur=0.3"
|
||||
);
|
||||
expect(response.headers["server-timing"]).toContain(
|
||||
"pagination;dur=0.5"
|
||||
);
|
||||
expect(response.rawPayload).toEqual(Buffer.from("%PDF-test"));
|
||||
expect(generate).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
articleHtml: expect.stringContaining('id="write"'),
|
||||
themeCss: expect.stringContaining("#write"),
|
||||
exportConfig: defaultExportConfig
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("拒绝无效导出配置", async () => {
|
||||
app = buildApp({ logger: false });
|
||||
const response = await app.inject({
|
||||
method: "POST",
|
||||
url: "/api/pdf",
|
||||
payload: {
|
||||
markdown: "# 测试",
|
||||
exportConfig: {
|
||||
...defaultExportConfig,
|
||||
version: 999
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
expect(response.statusCode).toBe(400);
|
||||
expect(response.json().error).toBe("INVALID_EXPORT_CONFIG");
|
||||
});
|
||||
|
||||
it("映射 PDF 队列已满错误", async () => {
|
||||
app = buildApp({
|
||||
logger: false,
|
||||
pdfGenerator: {
|
||||
generate: vi.fn(async () => {
|
||||
throw new PdfEngineOverloadedError();
|
||||
}),
|
||||
close: vi.fn(async () => undefined)
|
||||
}
|
||||
});
|
||||
const response = await app.inject({
|
||||
method: "POST",
|
||||
url: "/api/pdf",
|
||||
payload: {
|
||||
markdown: "# 测试",
|
||||
exportConfig: defaultExportConfig
|
||||
}
|
||||
});
|
||||
|
||||
expect(response.statusCode).toBe(503);
|
||||
expect(response.headers["retry-after"]).toBe("5");
|
||||
expect(response.json().error).toBe("PDF_QUEUE_FULL");
|
||||
});
|
||||
|
||||
it("规范化 PDF 文件名和下载响应头", () => {
|
||||
expect(createPdfFileName("../报告.markdown")).toBe("报告.pdf");
|
||||
expect(createPdfFileName("非法<>名称.md")).toBe(
|
||||
"非法__名称.pdf"
|
||||
);
|
||||
expect(createPdfFileName(undefined)).toBe("文档.pdf");
|
||||
expect(createPdfContentDisposition("报告.pdf")).toContain(
|
||||
"filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf"
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { Browser } from "playwright";
|
||||
import { defaultExportConfig } from "@md-to-pdf/core";
|
||||
import {
|
||||
ConcurrencyGate,
|
||||
PdfEngineClosedError,
|
||||
PdfEngineOverloadedError,
|
||||
PdfRenderTimeoutError,
|
||||
PlaywrightPdfGenerator,
|
||||
isAllowedPdfRequestUrl,
|
||||
type PdfRenderPayload
|
||||
} from "../src/pdf-engine.js";
|
||||
|
||||
function payload(): PdfRenderPayload {
|
||||
return {
|
||||
articleHtml: '<article id="write"><h1>测试</h1></article>',
|
||||
fileName: "测试.md",
|
||||
metadata: {
|
||||
title: "测试",
|
||||
author: "",
|
||||
subject: "",
|
||||
keywords: [],
|
||||
language: "zh-CN"
|
||||
},
|
||||
features: [],
|
||||
themeCss: "#write { color: #333; }",
|
||||
exportConfig: defaultExportConfig
|
||||
};
|
||||
}
|
||||
|
||||
function fakeBrowser(options: { hangOnGoto?: boolean } = {}) {
|
||||
const route = vi.fn();
|
||||
const closeContext = vi.fn(async () => undefined);
|
||||
const closeBrowser = vi.fn(async () => undefined);
|
||||
const pdfBuffer = Buffer.from("%PDF-test");
|
||||
const page = {
|
||||
setDefaultTimeout: vi.fn(),
|
||||
setDefaultNavigationTimeout: vi.fn(),
|
||||
emulateMedia: vi.fn(async () => undefined),
|
||||
goto: options.hangOnGoto
|
||||
? vi.fn(() => new Promise(() => undefined))
|
||||
: vi.fn(async () => undefined),
|
||||
waitForFunction: vi.fn(async () => undefined),
|
||||
evaluate: vi.fn(async () => ({
|
||||
pageCount: 2,
|
||||
contentHeight: 2200,
|
||||
mermaidErrors: [],
|
||||
timings: {
|
||||
setupMs: 1,
|
||||
mermaidMs: 2,
|
||||
mermaidFitMs: 3,
|
||||
mermaidConversionMs: 3.5,
|
||||
resourceWaitMs: 4,
|
||||
paginationMs: 5,
|
||||
finalizeMs: 6,
|
||||
totalMs: 21
|
||||
}
|
||||
})),
|
||||
pdf: vi.fn(async () => pdfBuffer)
|
||||
};
|
||||
const context = {
|
||||
route,
|
||||
newPage: vi.fn(async () => page),
|
||||
close: closeContext
|
||||
};
|
||||
const browser = {
|
||||
newContext: vi.fn(async () => context),
|
||||
close: closeBrowser,
|
||||
on: vi.fn()
|
||||
} as unknown as Browser;
|
||||
|
||||
return {
|
||||
browser,
|
||||
closeBrowser,
|
||||
closeContext,
|
||||
context,
|
||||
page,
|
||||
pdfBuffer,
|
||||
route
|
||||
};
|
||||
}
|
||||
|
||||
describe("PDF 并发控制", () => {
|
||||
it("限制并发并拒绝超过排队上限的任务", async () => {
|
||||
const gate = new ConcurrencyGate(1, 1);
|
||||
let releaseFirst: (() => void) | undefined;
|
||||
const first = gate.run(
|
||||
() =>
|
||||
new Promise<void>((resolve) => {
|
||||
releaseFirst = resolve;
|
||||
})
|
||||
);
|
||||
const second = gate.run(async () => undefined);
|
||||
|
||||
await expect(
|
||||
gate.run(async () => undefined)
|
||||
).rejects.toBeInstanceOf(PdfEngineOverloadedError);
|
||||
|
||||
releaseFirst?.();
|
||||
await first;
|
||||
await second;
|
||||
});
|
||||
});
|
||||
|
||||
describe("PDF 网络策略", () => {
|
||||
it("只允许渲染同源和内嵌资源", () => {
|
||||
const origin = "http://127.0.0.1:5173";
|
||||
expect(
|
||||
isAllowedPdfRequestUrl(
|
||||
"http://127.0.0.1:5173/api/themes/a.css",
|
||||
origin
|
||||
)
|
||||
).toBe(true);
|
||||
expect(isAllowedPdfRequestUrl("data:image/png;base64,AA", origin))
|
||||
.toBe(true);
|
||||
expect(isAllowedPdfRequestUrl("blob:http://127.0.0.1/id", origin))
|
||||
.toBe(true);
|
||||
expect(
|
||||
isAllowedPdfRequestUrl("https://example.com/font.woff2", origin)
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Playwright PDF 生成器", () => {
|
||||
it("复用浏览器、隔离上下文并返回 PDF", async () => {
|
||||
const fake = fakeBrowser();
|
||||
const generator = new PlaywrightPdfGenerator({
|
||||
launchBrowser: async () => fake.browser,
|
||||
timeoutMs: 1_000
|
||||
});
|
||||
|
||||
const first = await generator.generate(payload());
|
||||
const second = await generator.generate(payload());
|
||||
|
||||
expect(first.pdf.toString()).toBe("%PDF-test");
|
||||
expect(first.pdf).toBe(fake.pdfBuffer);
|
||||
expect(first.pageCount).toBe(2);
|
||||
expect(first.timings).toEqual(
|
||||
expect.objectContaining({
|
||||
queueMs: expect.any(Number),
|
||||
browserMs: expect.any(Number),
|
||||
contextMs: expect.any(Number),
|
||||
navigationMs: expect.any(Number),
|
||||
documentRenderMs: expect.any(Number),
|
||||
runtimeSetupMs: 1,
|
||||
mermaidMs: 2,
|
||||
mermaidFitMs: 3,
|
||||
mermaidConversionMs: 3.5,
|
||||
resourceWaitMs: 4,
|
||||
paginationMs: 5,
|
||||
finalizeMs: 6,
|
||||
runtimeTotalMs: 21,
|
||||
pdfPrintMs: expect.any(Number),
|
||||
totalMs: expect.any(Number)
|
||||
})
|
||||
);
|
||||
expect(second.pdf.toString()).toBe("%PDF-test");
|
||||
expect(fake.browser.newContext).toHaveBeenCalledTimes(2);
|
||||
expect(fake.closeContext).toHaveBeenCalledTimes(2);
|
||||
expect(fake.page.pdf).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
pageRanges: "1-2",
|
||||
preferCSSPageSize: true,
|
||||
printBackground: true,
|
||||
scale: 1
|
||||
})
|
||||
);
|
||||
|
||||
await generator.close();
|
||||
expect(fake.closeBrowser).toHaveBeenCalledTimes(1);
|
||||
await expect(generator.generate(payload())).rejects.toBeInstanceOf(
|
||||
PdfEngineClosedError
|
||||
);
|
||||
});
|
||||
|
||||
it("可以在首个生成请求前预热浏览器", async () => {
|
||||
const fake = fakeBrowser();
|
||||
const launchBrowser = vi.fn(async () => fake.browser);
|
||||
const generator = new PlaywrightPdfGenerator({
|
||||
launchBrowser,
|
||||
timeoutMs: 1_000
|
||||
});
|
||||
|
||||
await generator.warmup();
|
||||
await generator.warmup();
|
||||
expect(launchBrowser).toHaveBeenCalledTimes(1);
|
||||
expect(fake.browser.newContext).not.toHaveBeenCalled();
|
||||
|
||||
await generator.generate(payload());
|
||||
expect(launchBrowser).toHaveBeenCalledTimes(1);
|
||||
await generator.close();
|
||||
});
|
||||
|
||||
it("超时后关闭独立上下文", async () => {
|
||||
const fake = fakeBrowser({ hangOnGoto: true });
|
||||
const generator = new PlaywrightPdfGenerator({
|
||||
launchBrowser: async () => fake.browser,
|
||||
timeoutMs: 10
|
||||
});
|
||||
|
||||
await expect(generator.generate(payload())).rejects.toBeInstanceOf(
|
||||
PdfRenderTimeoutError
|
||||
);
|
||||
expect(fake.closeContext).toHaveBeenCalledTimes(1);
|
||||
await generator.close();
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user