closeDocument() on a still-loading document leaks the PDFium-native document handle
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Idoneità per principianti
- 55/100
- Tipo di issue
- Bug
- Chiarezza
- Specificata chiaramente
- Stato di attività
- Tranquilla
- Stack tecnologico
- typescript
- Ambito
- backend-api-design, performance
Direzione di ricerca
Start with closeDocument(), handleLoadTask(), and the SET_DOCUMENT_LOADED and CLOSE_DOCUMENT reducers in @embedpdf/plugin-document-manager/dist/index.js and @embedpdf/core/dist/index.js. Trace the loading path into PdfCache and DocumentContext in @embedpdf/engines/dist/direct-engine-C8xTbxym.js, then reproduce closing during a slow open. Done means loading documents closed directly or during destroy leave no retained native cache entry or allocation.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Environment
@embedpdf/plugin-document-manager2.15.0@embedpdf/engines2.15.0@embedpdf/core2.15.0- Browser-agnostic (reproduced by reading the compiled engine logic — not tied to a specific browser/runtime; applies to both the direct (
direct-engine) and worker-based engine builds, since both route through the samePdfCache/DocumentContextdisposal path)
Summary
Calling closeDocument(documentId) while that document is still in the loading state removes it from the document-manager's own tracking state, but never tells the engine to close it — and never cancels the in-flight engine open task either. When that open task later resolves, the PDFium document it opened has no owner left anywhere in the plugin: the store update that would have recorded it is a no-op against already-removed state, and nothing calls engine.closeDocument() for it afterward. The result is a native PDFium document (and its backing WASM heap allocation) that lives for the lifetime of the engine instance with no way for application code to release it. destroy() on the plugin has the same characteristic for any document that happens to still be loading when destroy() runs, since it is implemented as closeDocument() over every currently-tracked document.
Reproduction
Minimal step list (code sketch, not a runnable repo — the logic is deterministic from the compiled source, see Evidence below):
- Configure a
DocumentManagerPluginbacked by a realPdfiumEngine(direct or worker mode — both exhibit this). - Call
documentManager.openDocumentUrl({ url: '<a large/slow-to-fetch PDF>' }). This dispatchesstartLoadingDocumentand kicks offengine.openDocumentUrl(...), which internally fetches, then callsengine.openDocumentBuffer(...). - Before
onDocumentOpened(oronDocumentError) fires for that document, calldocumentManager.closeDocument(documentId). - Let the in-flight engine open task settle (it will —
FPDF_LoadMemDocumentsucceeds and the document is registered in the engine's internal cache regardless of what the plugin does in step 3). - Observe:
documentManager.getDocumentCount()/getOpenDocuments()show the document as gone (as expected — that part works). But the engine's own document cache (PdfCache.docs, keyed bydocumentId) still holds an entry for it, with a livedocPtrfromFPDF_LoadMemDocumentand a livefilePtrheap allocation — neither of which is ever passed toFPDF_CloseDocument/ freed. Repeating steps 2–4 in a loop against one long-lived engine instance grows this internal cache without bound; there is no application-level API that can reach these orphaned entries to close them, because the plugin never got to record the document's id/handle before it dropped the document from its own state.
Expected vs Actual
- Expected: Closing a document that hasn't finished loading yet either (a) cancels the in-flight open so the engine never materializes a native document for it, or (b) lets the open complete and then closes the resulting document via the engine, so no native resource outlives the app-level
closeDocument()call. - Actual: Neither happens. The native document is opened, cached inside the engine, and then permanently orphaned — no cancellation, no deferred close.
Evidence (installed npm dist for 2.15.0)
1. closeDocument() on a loading document skips the engine close entirely and doesn't touch the in-flight task.
@embedpdf/plugin-document-manager/dist/index.js:
closeDocument(documentId) {
const task = new Task();
const docState = this.coreState.core.documents[documentId];
if (!docState) { /* ...not found... */ }
if (docState.status === "loaded" && docState.document) {
this.engine.closeDocument(docState.document).wait(
() => {
this.dispatchCoreAction(closeDocument(documentId));
task.resolve();
},
(error) => { /* ... */ }
);
} else {
this.logger.info(
"DocumentManagerPlugin",
"CloseDocument",
`Closing document ${documentId} in ${docState.status} state (skipping engine close)`
);
this.dispatchCoreAction(closeDocument(documentId));
task.resolve();
}
return task;
}
The else branch is reached whenever docState.status !== "loaded" — i.e. "loading". It logs "skipping engine close" (the library is aware it's skipping something) and dispatches the core closeDocument action, which just removes the entry from state. It never references, awaits, or aborts the engineTask that openDocumentUrl/openDocumentBuffer started for this documentId:
openDocumentBuffer(options) {
...
const engineTask = this.engine.openDocumentBuffer(file, { ... });
task.resolve({ documentId, task: engineTask });
this.handleLoadTask(documentId, engineTask, "OpenDocumentBuffer");
return task;
}
...
handleLoadTask(documentId, engineTask, context) {
engineTask.wait(
(pdfDocument) => {
this.dispatchCoreAction(setDocumentLoaded(documentId, pdfDocument));
},
(error) => { this.handleLoadError(documentId, error, context); }
);
}
handleLoadTask keeps listening on engineTask independently of whatever closeDocument() did. There is no cross-wiring between the two.
2. When the engine task resolves after the fact, the resolved document is silently dropped by the reducer — nothing ever gets a handle to close it.
@embedpdf/core/dist/index.js, the SET_DOCUMENT_LOADED reducer:
case SET_DOCUMENT_LOADED: {
const { documentId, document } = action.payload;
const docState = state.documents[documentId];
if (!docState) return state;
return { ...state, documents: { ...state.documents, [documentId]: { ...docState, status: "loaded", document, ... } } };
}
Because the earlier CLOSE_DOCUMENT action already removed state.documents[documentId] (see the CLOSE_DOCUMENT case, which does const { [documentId]: removed, ...remainingDocs } = state.documents), this if (!docState) return state; guard makes the late setDocumentLoaded dispatch a complete no-op. The pdfDocument object handed back by the engine — the only application-level reference to the now-open native document — is discarded. No code path anywhere in the plugin then turns around and calls engine.closeDocument() for it.
3. The engine has already materialized and cached the native PDFium document by this point, independent of whether anyone is listening for the result.
@embedpdf/engines/dist/direct-engine-C8xTbxym.js, inside openDocumentBuffer on the executor:
const docPtr = this.pdfiumModule.FPDF_LoadMemDocument(filePtr, length, (options?.password) ?? "");
if (!docPtr) { /* ...error path closes+frees... */ }
... // page enumeration
const pdfDoc = { id: file.id, pageCount, pages, isEncrypted, isOwnerUnlocked, permissions, normalizedRotation: normalizeRotation };
this.cache.setDocument(file.id, filePtr, docPtr, normalizeRotation);
this.logger.perf(LOG_SOURCE, LOG_CATEGORY, `OpenDocumentBuffer`, "End", file.id);
return PdfTaskHelper.resolve(pdfDoc);
this.cache is a PdfCache:
class PdfCache {
constructor(pdfium, memoryManager, config = {}) {
this.docs = new Map();
...
}
setDocument(id, filePtr, docPtr, normalizeRotation = false) {
let ctx = this.docs.get(id);
if (!ctx) {
ctx = new DocumentContext(filePtr, docPtr, this.pdfium, this.memoryManager, { ...this.config, normalizeRotation });
this.docs.set(id, ctx);
}
}
closeDocument(docId) {
const ctx = this.docs.get(docId);
if (!ctx) return false;
this.docs.delete(docId);
ctx.dispose();
return true;
}
...
}
class DocumentContext {
constructor(filePtr, docPtr, pdfium, memoryManager, config) {
this.filePtr = filePtr;
this.docPtr = docPtr;
...
}
dispose() {
if (this.disposed) return;
this.disposed = true;
this.pageCache.forceReleaseAll();
this.pageCache.pdf.FPDF_CloseDocument(this.docPtr);
this.memoryManager.free(WasmPointer(this.filePtr));
}
}
setDocument runs synchronously as part of the executor call, the moment FPDF_LoadMemDocument succeeds — before the surrounding Task even resolves back up to the plugin. So by the time closeDocument() at the plugin level decided to "skip the engine close" (evidence #1), the engine's PdfCache.docs map is either about to gain, or has already gained, a live entry keyed by that documentId. The only way to remove it is engine.closeDocument({ id: documentId }) → PdfCache.closeDocument(docId) → ctx.dispose() → FPDF_CloseDocument(docPtr) + free filePtr. Nothing in the plugin calls this for a document that was closed while loading, so the entry — and the native document + heap allocation it owns — stays in PdfCache.docs for the life of the engine.
4. destroy() has the same characteristic.
@embedpdf/plugin-document-manager/dist/index.js:
closeAllDocuments() {
const documentIds = Object.keys(this.coreState.core.documents);
const tasks = documentIds.map((documentId) => this.closeDocument(documentId));
...
return Task.all(tasks);
}
async destroy() {
await this.closeAllDocuments().toPromise();
this.loadOptions.clear();
...
}
destroy() is implemented purely in terms of closeAllDocuments(), which is purely in terms of the same closeDocument() from evidence #1. Any document that is still "loading" at the moment destroy() is called hits the exact same "skipping engine close" branch, so it leaks the same way — destroy() does not guarantee the engine ends up with zero open native documents if there was an in-flight open at teardown time.
Impact
Low-impact for a page that opens one document and reloads the whole page between documents (the engine/WASM instance itself gets torn down with it). But it's a real, unbounded leak for any app that:
- keeps a single long-lived engine instance across document navigations (the common pattern for a multi-document viewer, a file browser preview pane, or a tabbed document workspace), and
- lets users navigate away from a document before it finishes loading — slow network, large file, or just a user clicking through a list quickly.
Each such navigation permanently grows the engine's WASM-side document table. There's no user-facing error; it just shows up as steadily rising memory in the WASM heap over a session, which is a hard failure mode to diagnose without reading this code path.
Workaround we use
Settle-then-close: don't close a loading document directly. Keep its event listeners alive, mark it for closing, and actually call closeDocument() only after it settles (onDocumentOpened or onDocumentError) — at which point it's either "loaded" (so the plugin's own closeDocument() correctly routes to the engine) or errored (so the engine never had a handle to leak in the first place).
const pendingClose = new Set();
documentManager.onDocumentOpened((docState) => {
if (pendingClose.has(docState.id)) {
pendingClose.delete(docState.id);
documentManager.closeDocument(docState.id);
}
});
documentManager.onDocumentError(({ documentId }) => {
pendingClose.delete(documentId);
});
function safeClose(documentId) {
const docState = documentManager.getDocumentState(documentId);
if (!docState) return;
if (docState.status === "loading") {
pendingClose.add(documentId);
return; // deferred; closeDocument() called from onDocumentOpened above
}
documentManager.closeDocument(documentId);
}
This avoids the leak, at the cost of every "close" on a loading document actually paying for the full open (and then immediate close) instead of being cancelled.
Related issues
This sits in the same error/lifecycle-channel neighborhood as #632 and #633, worth linking for context:
- #632 — worker
wasmInitfailures are silently swallowed byRemoteExecutor, leaving the engine hung with no rejected promise and no error surfaced. Different mechanism, but the same theme: a task/lifecycle signal that the engine emits doesn't reliably reach the code that's supposed to act on it. - #633 — worker
fetch(wasmUrl)can't resolve path-relative URLs because the worker's base is ablob:URL, so the documented relative-path config silently fails only in worker mode. Also a worker-boundary reliability issue, not directly the same bug, but flagging since it's in the same area of the codebase.
Not claiming this issue is the same bug as either — just noting the neighborhood in case there's a shared root cause worth looking at together (e.g. task/lifecycle signals not being reliably plumbed end-to-end across the plugin/engine boundary).
Thanks for the library — it's been solid for us, this is the one gap we've hit that looks like it needs an upstream fix rather than a workaround.
Optional follow-up PR sketch
A few shapes a fix could take, roughly in order of how surgical they are:
- Track loading documents in the plugin, close-on-settle internally. Give
DocumentManagerPluginthe samependingClosebookkeeping shown in the workaround above, built intocloseDocument()itself: ifdocState.status === "loading", register the id and letonDocumentLoaded/the error handler perform the actualengine.closeDocument()once the task settles, instead of silently dropping state. Smallest change, keeps the engine's open/close pairing intact, no new engine API needed. - Abort the engine task instead. Have
closeDocument()callengineTask.abort()(theTask/WorkerTaskQueuemachinery already supports cancelling a queued-but-not-yet-running task) and have the executor'sopenDocumentBuffercheck for cancellation before callingPdfCache.setDocument, so an aborted open never registers a native document in the first place. Needs the abort signal threaded fromTask.abort()down into the executor, which doesn't exist today. - Belt-and-suspenders:
closeAllDocuments()/destroy()sweep the engine's cache directly. Regardless of which of the above lands,PdfCache(or the engine interface) could expose something likecloseOrphaned(ids)/ a "close everything not in this id set" call sodestroy()can guarantee zero leaked native documents even if a plugin-level bug reintroduces this class of issue later.
Happy to sketch a PR for the first option if that's the preferred direction — it's the smallest, most contained change and doesn't touch the Task/queue abort semantics.
- Lingua principale
- TypeScript
- Stelle
- 4.5k
- Fork
- 317
- Merge medio
- 10h 16m
- PR unite (30g)
- 174
Preparare l'ambiente
Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di embedpdf/embed-pdf-viewer
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 88/100
embedpdf/embed-pdf-viewer#1098 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 85/100
embedpdf/embed-pdf-viewer#921 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 79/100
embedpdf/embed-pdf-viewer#889 ·
I maintainer di solito rispondono entro 1 giorno
-
[v2] TaskQueue: equal-priority tasks can run out of order when a randomUUID id starts with digitsAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
embedpdf/embed-pdf-viewer#874 ·
I maintainer di solito rispondono entro 1 giorno
-
Free text stays scrolled to the caret after editing endsForse già presa @chahore l’ha presa 36 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
embedpdf/embed-pdf-viewer#861 ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di embedpdf/embed-pdf-viewer
Issue simili
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 85/100
lingdojo/kana-dojo#34223 · 1 commento · 5 reazioni ·
I maintainer di solito rispondono entro 1 giorno
-
bug status: needs triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
mastra-ai/mastra#30587 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
area:web p2 product:business triage:active type:bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
cuadrao-ai/argus#2228 ·
I maintainer di solito rispondono entro 1 giorno
-
.Needs Triage .Team/Metabot Priority:P3 Type:Bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 73/100
metabase/metabase#87252 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
NuGet registry builds every URL from ROOT_URL, ignoring the host the client usedForse già presa @gritse l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
I maintainer di solito rispondono entro 1 giorno