From 87262fcc9703d7d9a8141d9b176b5f63c69a51c6 Mon Sep 17 00:00:00 2001 From: krflol Date: Sun, 1 Nov 2026 17:19:28 -0600 Subject: [PATCH 1/3] chore: exclude development tooling from language statistics --- .gitattributes | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitattributes b/.gitattributes index 7be2fd5..bd00cd4 100644 --- a/.gitattributes +++ b/.gitattributes @@ -6,3 +6,6 @@ test/fixtures/radial-gradient-endpoints-2.5.43.json -text assets/fonts/*-OFL.txt -whitespace test/fonts/*-OFL.txt -whitespace + +# Keep build, release, and verification tooling out of language statistics. +tools/** -linguist-detectable From 4649d875521793ac063a268eee6ccb1d33f45dbf Mon Sep 17 00:00:00 2001 From: krflol Date: Sun, 1 Nov 2026 18:22:50 -0600 Subject: [PATCH 2/3] Fix Windows worker startup cancellation in 0.9.5 --- .github/workflows/ci.yml | 2 + README.md | 7 ++- docs/render-queue.md | 6 +- engine/Cargo.lock | 2 +- engine/Cargo.toml | 2 +- package-lock.json | 4 +- package.json | 2 +- src/worker.js | 10 ++- tools/check-startup-cancellation.mjs | 94 ++++++++++++++++++++++++++++ tools/verify-pack.mjs | 10 +++ 10 files changed, 128 insertions(+), 11 deletions(-) create mode 100644 tools/check-startup-cancellation.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 33ea76d..5cdd94f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -175,6 +175,7 @@ jobs: output/pack-verification/verification.json output/pack-verification/text-extraction.json output/pack-verification/queue-tests.log + output/pack-verification/startup-cancellation.log output/pack-verification/default-styles-tests.log output/pack-verification/named-fonts-tests.log output/pack-verification/named-fonts/ @@ -343,6 +344,7 @@ jobs: path: | output/pack-verification/verification.json output/pack-verification/queue-tests.log + output/pack-verification/startup-cancellation.log output/pack-verification/default-styles-tests.log output/pack-verification/component-tests.log output/pack-verification/batch-tests.log diff --git a/README.md b/README.md index 7ae78c3..e8b1af7 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,12 @@ no Python, Rust compiler, browser, or system fonts. MIT licensed. Use `fullbleed` in Node.js, `fullbleed/browser` in a web application, or [`fullbleed/cloudflare`](docs/cloudflare.md) inside a Cloudflare Worker. -Package **0.9.4** wraps the published **Fullbleed 2.5.51** engine. +Package **0.9.5** wraps the published **Fullbleed 2.5.51** engine. -A winning `font-family` declaration now replaces an earlier variable-based +This release fixes a Windows worker-startup cancellation race. Aborted renders +release their worker before the queue starts the next render. + +A winning `font-family` declaration replaces an earlier variable-based family. If its variable cannot resolve, the text inherits its parent family instead of reviving a declaration that lost the cascade. diff --git a/docs/render-queue.md b/docs/render-queue.md index 24a65a4..bb5291e 100644 --- a/docs/render-queue.md +++ b/docs/render-queue.md @@ -91,6 +91,10 @@ PDF and preview bytes with standalone rendering. They also exercise overload, FIFO starts, queued and active cancellation, waiting deadlines, input snapshots, render failure, shutdown before and after startup, and recovery after terminating a process-isolated child. CI runs these checks on Node 22, 24 and 26 across Linux, -Windows and macOS. The [release evidence](https://github.com/fullbleed-engine/fullbleed-node/releases) +Windows and macOS. A separate 64-cycle check sweeps cancellation delays after +workers come online, waits for each worker to exit, then compares the next PDF +and preview with an uncancelled baseline. It retains the lifecycle counts and recovery files +in `output/queue-verification/startup-cancellation.json` and `startup-recovery.*`. +The [release evidence](https://github.com/fullbleed-engine/fullbleed-node/releases) retains the observed results and PDF/PNG fixtures; it is not a general throughput or memory-capacity claim. diff --git a/engine/Cargo.lock b/engine/Cargo.lock index aae1110..876b689 100644 --- a/engine/Cargo.lock +++ b/engine/Cargo.lock @@ -15,7 +15,7 @@ dependencies = [ [[package]] name = "fullbleed-node-adapter" -version = "0.9.4" +version = "0.9.5" dependencies = [ "fullbleed", "serde_json", diff --git a/engine/Cargo.toml b/engine/Cargo.toml index 6bd2b33..4c6635c 100644 --- a/engine/Cargo.toml +++ b/engine/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "fullbleed-node-adapter" -version = "0.9.4" +version = "0.9.5" edition = "2024" license = "MIT" publish = false diff --git a/package-lock.json b/package-lock.json index e3e4769..11c31a1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "fullbleed", - "version": "0.9.4", + "version": "0.9.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "fullbleed", - "version": "0.9.4", + "version": "0.9.5", "license": "MIT", "dependencies": { "@bjorn3/browser_wasi_shim": "0.4.2" diff --git a/package.json b/package.json index 48be487..d328777 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "fullbleed", - "version": "0.9.4", + "version": "0.9.5", "description": "Generate PDFs from HTML/CSS, components or JSX in Node.js, browsers and Cloudflare Workers, with bundled fonts and PNG previews.", "type": "module", "main": "./src/index.cjs", diff --git a/src/worker.js b/src/worker.js index 8176282..94c2dcd 100644 --- a/src/worker.js +++ b/src/worker.js @@ -1,6 +1,10 @@ // SPDX-License-Identifier: MIT import { parentPort, workerData } from 'node:worker_threads'; -import { runEngine } from './engine-runner.js'; +import { runEngineSync } from './engine-runner.js'; -const result = await runEngine(workerData); -parentPort.postMessage(result, result.ok ? [result.pdf.buffer, ...result.previews.map(page => page.buffer)] : []); +// Finish module evaluation before starting CPU-bound work. Cancellation during +// the dynamic import can otherwise leave worker.terminate() pending on Windows. +setImmediate(() => { + const result = runEngineSync(workerData); + parentPort.postMessage(result, result.ok ? [result.pdf.buffer, ...result.previews.map(page => page.buffer)] : []); +}); diff --git a/tools/check-startup-cancellation.mjs b/tools/check-startup-cancellation.mjs new file mode 100644 index 0000000..d2f4766 --- /dev/null +++ b/tools/check-startup-cancellation.mjs @@ -0,0 +1,94 @@ +// SPDX-License-Identifier: MIT +// Exercise the installed package through its public API, including real workers. +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import { mkdirSync, writeFileSync } from 'node:fs'; +import { createRequire } from 'node:module'; +import { join, resolve } from 'node:path'; + +const [consumerArg, outputArg] = process.argv.slice(2); +assert(consumerArg && outputArg, 'Use check-startup-cancellation.mjs CONSUMER OUTPUT'); +const output = resolve(outputArg); +mkdirSync(output, { recursive: true }); +const require = createRequire(join(resolve(consumerArg), 'package.json')); +const { createRenderQueue, FullbleedError, version, engineVersion } = require('fullbleed'); +const input = { html: '

Recovered invoice

Services: USD 1,200.00

', previewDpi: 96 }; +const longInput = { html: '
Long document
'.repeat(1000), css: 'div {break-after:page}', previewDpi: 96 }; +const hash = bytes => createHash('sha256').update(bytes).digest('hex'); +const code = expected => error => error instanceof FullbleedError && error.code === expected; +const active = new Set(); +let created = 0, peak = 0, online, phase = 'warmup', cycle = -1; +const cycles = []; +const observe = worker => { + created++; + active.add(worker); + peak = Math.max(peak, active.size); + worker.once('exit', () => active.delete(worker)); + if (online) { + const resolveOnline = online; + online = undefined; + worker.once('online', resolveOnline); + } +}; +process.on('worker', observe); +const record = (ok, extra = {}) => { + const result = { ok, packageVersion: version, engineVersion, node: process.version, + platform: process.platform, cycle, phase, cycles, workersCreated: created, + peakWorkers: peak, remainingWorkers: active.size, ...extra }; + writeFileSync(join(output, 'startup-cancellation.json'), JSON.stringify(result, null, 2) + '\n'); + return result; +}; +// A leaked worker must fail this verifier rather than leave the CI child alive. +async function bounded(promise, label) { + phase = label; + const timer = setTimeout(() => { + record(false, { error: `${label} remained pending for 10 seconds` }); + console.error(`Startup cancellation stalled at cycle ${cycle}: ${label}`); + process.exit(1); + }, 10000); + try { return await promise; } finally { clearTimeout(timer); } +} +const queue = createRenderQueue({ concurrency: 1, maxQueue: 1 }); +try { + const baseline = await bounded(queue.renderPdf(input), 'warmup'); + const expected = { pdf: hash(baseline.pdf), png: hash(baseline.previews[0]) }; + for (cycle = 0; cycle < 64; cycle++) { + const startedAt = performance.now(); + const started = new Promise(resolve => { online = resolve; }); + const before = created; + const controller = new AbortController(); + const cancelled = assert.rejects(queue.renderPdf({ ...longInput, signal: controller.signal }), code('ABORTED')); + await bounded(started, 'worker online'); + // Sweep the startup window, including cancellation after execution begins. + const waitingTimeoutMs = [8, 16, 20, 24, 32, 48, 64, 96][cycle % 8]; + await bounded(assert.rejects(queue.renderPdf({ ...input, timeoutMs: waitingTimeoutMs }), code('TIMEOUT')), 'queued deadline'); + assert.equal(queue.pendingCount, 0); + assert.equal(created, before + 1, 'The expired queued job must not create a worker.'); + controller.abort(); + await bounded(cancelled, 'aborted worker exit'); + assert.equal(active.size, 0, 'Cancellation must await the actual worker exit.'); + assert.equal(queue.activeCount, 0); + const recovered = await bounded(queue.renderPdf(input), 'recovery render'); + assert.equal(recovered.pages, 1); + assert.equal(recovered.missingGlyphs, 0); + assert.equal(recovered.previews.length, 1); + assert.deepEqual({ pdf: hash(recovered.pdf), png: hash(recovered.previews[0]) }, expected); + assert.equal(active.size, 0); + assert.equal(created, before + 2); + cycles.push({ cycle, waitingTimeoutMs, milliseconds: Math.round(performance.now() - startedAt), outputMatchesBaseline: true, remainingWorkers: active.size }); + } + await bounded(queue.close(), 'queue close'); + assert.equal(peak, 1); + assert.equal(created, 129); + writeFileSync(join(output, 'startup-recovery.pdf'), baseline.pdf); + writeFileSync(join(output, 'startup-recovery.png'), baseline.previews[0]); + phase = 'complete'; + record(true, { expected, settledQueueActiveCount: queue.activeCount, settledQueuePendingCount: queue.pendingCount }); + console.log(JSON.stringify({ ok: true, cycles: cycles.length, workersCreated: created, peakWorkers: peak, remainingWorkers: active.size, ...expected })); +} catch (error) { + record(false, { error: error.stack }); + console.error(error); + process.exit(1); +} finally { + process.off('worker', observe); +} diff --git a/tools/verify-pack.mjs b/tools/verify-pack.mjs index e5c5e6e..d87e93e 100644 --- a/tools/verify-pack.mjs +++ b/tools/verify-pack.mjs @@ -158,6 +158,16 @@ const queuePassed = Number(queueRun.stdout.match(/^# pass (\d+)$/m)?.[1]); assert(queueTests >= 14 && queueTests === queuePassed, 'All queue lifecycle checks must pass.'); const queueSmoke = { ...JSON.parse(await readFile(join(queueOutput, 'burst.json'), 'utf8')), tests: queueTests, passed: queuePassed }; +// Repeat the installed startup/cancel/recovery path that previously left a +// Windows worker alive after cancellation during dynamic module evaluation. +const startupRun = spawnSync(process.execPath, [join(root, 'tools/check-startup-cancellation.mjs'), install, queueOutput], { + cwd: install, env, encoding: 'utf8', timeout: 120000, +}); +await writeFile(join(output, 'startup-cancellation.log'), startupRun.stdout + startupRun.stderr); +assert.equal(startupRun.status, 0, startupRun.stderr || startupRun.stdout); +const startupCancellation = JSON.parse(await readFile(join(queueOutput, 'startup-cancellation.json'), 'utf8')); +assert(startupCancellation.ok && startupCancellation.cycles.length === 64 && startupCancellation.remainingWorkers === 0); +queueSmoke.startupCancellation = startupCancellation; await mkdir(join(install, 'fonts/family'), { recursive: true }); await copyFile(join(root, 'test/named-fonts.test.mjs'), join(install, 'named-fonts.test.mjs')); for (const name of ['LibreCaslonText[wght].ttf', 'OFL.txt']) From b832c653a170174767d8316b8de23eef08d76cfd Mon Sep 17 00:00:00 2001 From: krflol Date: Sun, 1 Nov 2026 18:30:46 -0600 Subject: [PATCH 3/3] Align the Cloudflare starter with package 0.9.5 --- examples/cloudflare/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/cloudflare/package.json b/examples/cloudflare/package.json index 098b969..d1c0252 100644 --- a/examples/cloudflare/package.json +++ b/examples/cloudflare/package.json @@ -11,6 +11,6 @@ "test": "node --test test/request.test.mjs", "test:worker": "node test/worker.mjs" }, - "dependencies": { "fullbleed": "0.9.4" }, + "dependencies": { "fullbleed": "0.9.5" }, "devDependencies": { "wrangler": "4.151.3" } }