go-pdfium

go-pdfium is a fast, multi-threaded, and easy-to-use PDF library for Go applications. It acts as a binding for Google's PDFium C++ library, providing a high-level Go interface to handle complex PDF operations without requiring direct CGO or WebAssembly knowledge.

Key capabilities include:

• Document Management: Loading (from bytes, paths, or io.ReadSeeker), saving (to bytes, paths, or io.Writer), and metadata extraction.
• Rendering: Rendering pages to Go image.Image (RGBA or Grayscale) using DPI or pixel size, and exporting directly to JPEG or PNG.
• Text & Content: Extracting plain or structured text (including position, size, and font info), searching text, and handling bookmarks, links, and annotations.
• Editing: Rotating pages, importing pages, flattening, and form filling.
• Advanced Features: Handling XFA packets, attachments, JavaScript actions, and transformations.

The go-pdfium implementation ensures correctness across both Native and WebAssembly (Wasm) runtimes through several validation layers:

• Bit-identical Rendering: The Wasm SIMD kernels are bit-identical to PDFium's scalar paths by construction. Portable patches and exact-match caches (memos) also maintain bit-identity.
• Test Suite Validation: Every configuration passes the full go-pdfium test suite and renders hash-identically against the golden corpus.
• PDFium Test Suite: The project runs PDFium's own internal test suite for both native and Wasm configurations. Results are compared as differential sets of failing test names rather than simple counts to ensure identical behavior.
• Validation Methodology: Patches are validated against a 'null control' (a byte-identical baseline build) to ensure no unintended side effects, and against 'poison builds' (builds with deliberately incorrect constants) to verify that new code paths are actually being executed.

Because PDFium is not natively multithreaded, go-pdfium provides three distinct implementations that share the same interface. You can switch between them without changing your application logic.

Important Considerations:

• Thread Safety: All implementations are thread/subroutine safe. The library uses locking to ensure that PDFium operations are protected.
• Memory Usage: PDFium can be memory-intensive depending on PDF size and request type. Monitor the number of workers configured in multi_threaded mode.
• Wazero Performance: On architectures other than amd64 or arm64, Wazero will use an interpreter, which is significantly slower.

The go-pdfium project supports two backends: a native CGO backend and a WebAssembly (WASM) backend. When choosing between them, consider the following performance characteristics:

Performance Gap

• Current State (Scenario B): Against stock (unpatched) native PDFium, the WASM backend is approximately 1.83× slower (geomean).
• Future State (Scenario A): Once the portable PDFium patches are upstreamed to the official PDFium project, the gap is expected to become a near-uniform ~2.04× slower (geomean) across all document types.

Why the gap exists

The performance difference is primarily attributed to runtime overhead rather than algorithmic differences. Key factors include:

• wazero's single-pass JIT code quality.
• WASM-level memory bounds checking.
• 128-bit-only SIMD limitations.

When to use which

• Native (CGO): Use when maximum raw performance is required and your environment supports CGO. It is currently faster than WASM because it uses stock PDFium which lacks the specific optimizations applied to the WASM build.
• WebAssembly (WASM): Use for portability or environments where CGO is not feasible. The performance penalty is predictable (roughly 2×) and consistent across different document types (images, text, CAD-style, etc.).

The go-pdfium project utilizes various patches to optimize performance across both Native (CGO) and WebAssembly (WASM) runtimes. These patches are categorized by their portability and target runtime:

1. Portable patches under upstream review: These are designed to work on both Native and WASM and are currently being reviewed for inclusion in the main PDFium project. They include optimizations for png_predictor_perf, compositor_perf, and stretch_engine_perf.
2. Portable patches not yet upstreamed: These are validated for both backends but currently live only in the project's fork. Examples include jpeg_decode_bgr, swap_translate_perf, lcms_translate_memo, and t4_psfunc_memo.
3. WebAssembly-specific patches: These exploit wasm_simd128 or work around Emscripten platform gaps. They are compiled only for the WASM target and include optimizations for the stretch engine, compositor, and glyph blending.

Performance effects are measured using a 5000-document corpus benchmark. Note that some patches (like fillrect_memset_perf) may actually regress performance on Native runtimes due to how libc memset behaves on certain architectures.

Multi-threading in CGO is implemented using HashiCorp's Go Plugin System. It launches separate PDFium worker processes and routes requests via gRPC. This provides better safety, as segfaults in a worker are less likely to corrupt the main Go application.

1. Create a Worker Package

The worker package must be named main to be compiled as a binary.

package main

import (
	"github.com/klippa-app/go-pdfium/multi_threaded/worker"
)

func main() {
	worker.StartWorker(nil)
}

2. Configure the Worker Pool

Initialize the pool in your application (e.g., in an init() function) using multi_threaded.Init.

package renderer

import (
	"log"
	"time"

	"github.com/klippa-app/go-pdfium"
	"github.com/klippa-app/go-pdfium/multi_threaded"
)

var pool pdfium.Pool
var instance pdfium.Pdfium

func init() {
	pool = multi_threaded.Init(multi_threaded.Config{
		MinIdle:  1,
		MaxIdle:  1,
		MaxTotal: 1,
		Command: multi_threaded.Command{
			BinPath: "go", // Use actual binary path in production
			Args:    []string{"run", "pdfium/worker/main.go"},
		},
	})

	var err error
	instance, err = pool.GetInstance(time.Second * 30)
	if err != nil {
		log.Fatal(err)
	}
}