closeDocument() on a still-loading document leaks the PDFium-native document handle

Aperta
#754 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

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

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-manager 2.15.0
  • @embedpdf/engines 2.15.0
  • @embedpdf/core 2.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 same PdfCache/DocumentContext disposal 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):

  1. Configure a DocumentManagerPlugin backed by a real PdfiumEngine (direct or worker mode — both exhibit this).
  2. Call documentManager.openDocumentUrl({ url: '<a large/slow-to-fetch PDF>' }). This dispatches startLoadingDocument and kicks off engine.openDocumentUrl(...), which internally fetches, then calls engine.openDocumentBuffer(...).
  3. Before onDocumentOpened (or onDocumentError) fires for that document, call documentManager.closeDocument(documentId).
  4. Let the in-flight engine open task settle (it will — FPDF_LoadMemDocument succeeds and the document is registered in the engine's internal cache regardless of what the plugin does in step 3).
  5. Observe: documentManager.getDocumentCount() / getOpenDocuments() show the document as gone (as expected — that part works). But the engine's own document cache (PdfCache.docs, keyed by documentId) still holds an entry for it, with a live docPtr from FPDF_LoadMemDocument and a live filePtr heap allocation — neither of which is ever passed to FPDF_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 wasmInit failures are silently swallowed by RemoteExecutor, 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 a blob: 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 DocumentManagerPlugin the same pendingClose bookkeeping shown in the workaround above, built into closeDocument() itself: if docState.status === "loading", register the id and let onDocumentLoaded/the error handler perform the actual engine.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() call engineTask.abort() (the Task/WorkerTaskQueue machinery already supports cancelling a queued-but-not-yet-running task) and have the executor's openDocumentBuffer check for cancellation before calling PdfCache.setDocument, so an aborted open never registers a native document in the first place. Needs the abort signal threaded from Task.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 like closeOrphaned(ids) / a "close everything not in this id set" call so destroy() 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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di embedpdf/embed-pdf-viewer

Tutte le issue di embedpdf/embed-pdf-viewer

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.