[v2] TaskQueue: equal-priority tasks can run out of order when a randomUUID id starts with digits

Open Beginner friendly
#874 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
backend

Research direction

Start in packages/engines/src/lib/orchestrator/task-queue.ts, where sortQueue() orders tasks and extractTime() parses the id's first segment, and in generateId(), which may return a UUID. Run the reproduction in the issue, which enqueues four setFormFieldState calls with a crafted all-digit UUID, and check that the written order is ['M', 'Mu', 'Mul', 'Mull']. Done when equal-priority, equal-rank tasks run in enqueue order regardless of id format, for example by recording a per-queue counter at enqueue time.

Written by the indexing model from the issue text.

Description

Affects: the 2.x line. Reported on @embedpdf/engines 2.14.4, and still the same in 2.15.1 and on the v2 branch (packages/engines/src/lib/orchestrator/task-queue.ts). The rewritten queue on main (packages/engine/main/src/worker/WorkerQueue.ts) does not use this tie-break, so this is about 2.x only.

What happens

PdfEngine runs everything through one WorkerTaskQueue with concurrency: 1. Before taking the next task, process() calls sortQueue(), which orders by priority, then by rank, then by extractTime(id), i.e. Number(id.split("-")[0]) (or 0 when that is not finite).

That tie-break assumes the fallback id format `${Date.now()}-${random}`. When crypto.randomUUID is available, though, generateId() returns a UUID, whose first segment is 8 random hex characters:

  • Usually that segment is not a number. extractTime returns 0, and because Array.prototype.sort is stable those tasks keep their enqueue order.
  • When the segment does parse as a number (all 8 characters are digits, about 2.3% of ids, or an exponent form such as 12345e67), extractTime returns a large value. That task then sorts behind every task of the same priority that was queued after it.

setFormFieldState and saveAsCopy are both Priority.MEDIUM, and typing in a form field enqueues one setFormFieldState per change. So an earlier value of a field can be written after a later one, and the field (or a following saveAsCopy) ends up with a stale value. We first saw this as an intermittent end-to-end test failure: a field kept "Mul" after "Muller AG" had been typed.

Reproduction (deterministic, run against 2.14.4)
import { PdfEngine } from '@embedpdf/engines';
import { Task } from '@embedpdf/models';

// The second id is an "unlucky" UUID whose first segment is all digits.
const ids = [
	'aaaaaaaa-0000-4000-8000-000000000001',
	'12345678-0000-4000-8000-000000000002',
	'bbbbbbbb-0000-4000-8000-000000000003',
	'cccccccc-0000-4000-8000-000000000004',
];
crypto.randomUUID = () => ids.shift() as ReturnType<Crypto['randomUUID']>;

const written: string[] = [];
const executor = {
	// Each write settles asynchronously, so later writes wait in the queue.
	setFormFieldState: (_doc, _page, _annotation, field) => {
		const task = new Task<boolean, unknown>();
		setTimeout(() => {
			written.push(field.value);
			task.resolve(true);
		}, 5);
		return task;
	},
	destroy: () => {},
};

const engine = new PdfEngine(executor as never, { imageConverter: (() => Promise.resolve(new Blob())) as never });
const doc = { id: 'doc' } as never;
const page = { index: 0 } as never;
const tasks = ['M', 'Mu', 'Mul', 'Mull'].map((value) =>
	engine.setFormFieldState(doc, page, {} as never, { value } as never),
);
await Promise.all(tasks.map((task) => task.toPromise()));

console.log(written); // expected ['M', 'Mu', 'Mul', 'Mull'], actual ['M', 'Mul', 'Mull', 'Mu']
Suggested fix

Make the tie-break independent of the id format, for example with a per-queue counter recorded at enqueue time, and order equal-priority, equal-rank tasks by that counter instead of parsing the id. As a stopgap we patched generateId() to return `${++seq}-${random}` with a per-queue counter. That keeps equal-priority tasks in enqueue order. The same queue code is also bundled into @embedpdf/snippet.

Dominant language
TypeScript
Stars
4.5k
Forks
317
Avg merge
10h 16m
Merged PRs (30d)
174

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from embedpdf/embed-pdf-viewer

All issues in embedpdf/embed-pdf-viewer

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.