📄 GoPdfSuit - Three PDF Engines, One Repo

🚀 gopdfsuit (language-agnostic REST API) · gopdflib (Go library) · pypdfsuit (Python bindings) - template-based PDF generation with multi-page support, merging, form filling, and HTML to PDF/Image conversion.

Star History

⚡ Performance & Efficiency

Zerodha gold-standard workload (5000 iterations, 48 workers, 80% retail · 15% active · 5% HFT), measured with x10 sequential runs on WSL2 (Intel i7-13700HX, Go 1.26.4, June 2026). See guides/BENCHMARKS.md for full suite.

Compliant runs enable PDF/A-4, PDF/UA-2, Arlington-compatible tagging, ECDSA P-256 signing, and font embedding (HFT output 2.29 MB, veraPDF 6/6 PASS). Non-compliant still outputs PDF 2.0 but turns PDF/A, tagging, signing, and font embedding off for a throughput ceiling reference (HFT output 221 KB).

Headline: Full compliance delivers ~6,600 ops/s peak on one machine - +150% vs the June 2026 baseline (2,646 ops/s) - while the same workload without compliance reaches ~37,900 ops/s peak (5.7× faster).

📑 Table of Contents

• Overview
• Prerequisites
• FAQ
• Development
• Contributing
• License

📚 Documentation

• 🌐 Web Documentation - Interactive API documentation and playground

• 📋 Template Reference - Complete JSON template format guide with examples

• 🛠️ Makefile Reference - Build, test, and deployment commands

📖 Overview

Three applications, one repository - pick the flavor that fits your stack:

Key Features:

• Template-Based Generation: Create PDFs from JSON templates with auto page breaks and flow control.
• Security & Compliance: Digital signatures (PKCS#7, X.509), AES-256 encryption, granular permissions, and PDF/A-4 & PDF/UA-2 compliance.
• Advanced Elements: Rich text styling, tables, barcodes, QR codes, SVG vector graphics, and interactive forms (checkboxes, radio buttons).
• Navigation: Auto-generated bookmarks, internal links, and named destinations.
• Form Filling: Fill generic AcroForms and XFDF data.
• Redaction: Securely redact sensitive information using specific coordinates or text search.
• Merge & Split: Combine multiple PDFs or split them.
• HTML Conversion: High-fidelity HTML to PDF/Image via headless Chrome.
• Web Interfaces: Built-in React UI for viewer, editor, merger, filler, and converters.

Requirements: Go 1.26.4, Google Chrome (for HTML conversion), Make (for build/test targets). See Prerequisites for the full list.

📋 Prerequisites

Windows

On Windows, use WSL (Windows Subsystem for Linux) for the best compatibility. The project relies on Make and Unix shell scripts that are not available in PowerShell or CMD. See CONTRIBUTING.md for setup details.

❓ FAQ

Go version compatibility?

This project requires Go 1.26.4 to build and run. The go.mod directive is set to go 1.26.4, and CI uses Go 1.26.4.

Install the exact version:

# Using go install (if you use multiple Go versions)
go install golang.org/dl/go1.26.4@latest
go1.26.4 download

# Verify
go1.26.4 version

Go 1.26.4 is recommended for runtime performance improvements (better GC, goroutine scheduling, hardware-accelerated crypto). The code does not rely on unreleased language features, but the module and dependencies are tested against 1.26.4 only.

For older Go toolchains: You can try changing the go directive in go.mod and running go mod tidy, but this is unsupported - official releases track Go 1.26.4.

Chrome not found error?

Install Google Chrome - required for HTML to PDF/Image conversion:

sudo apt install -y google-chrome-stable

How do auto page breaks work?

The system tracks Y position and creates new pages when content exceeds boundaries. Page borders and numbering are preserved across pages.

How do I create a digitally signed PDF?

Include the signature config with your PEM-encoded certificate and private key:

{
  "config": {
    "signature": {
      "enabled": true,
      "visible": true,
      "certificatePem": "-----BEGIN CERTIFICATE-----\n...",
      "privateKeyPem": "-----BEGIN PRIVATE KEY-----\n..."
    }
  }
}

Supports RSA and ECDSA keys with optional certificate chains.

What is PDF/A-4 compliance?

PDF/A-4 is the archival standard based on PDF 2.0. Enable it with "pdfaCompliant": true. This embeds all fonts (via Liberation fonts), adds XMP metadata, and follows strict structure requirements for long-term preservation.

How do internal links work?

1. Add a destination anchor to a cell: "dest": "my-section"
2. Link to it from another cell: "link": "#my-section"
3. Optionally add a bookmark: {"title": "My Section", "dest": "my-section"}

XFDF form filling limitations?

Uses byte-oriented approach with /NeedAppearances true. Works for most AcroForms, but PDFs with compressed object streams may need a library like pdfcpu for full compatibility.

Performance benchmarks?

Benchmarked on Intel i7-13700HX (24 cores), WSL2, Go 1.26.4. Zerodha workload: 80% retail · 15% active · 5% HFT. All PDFs PDF/A-4 + PDF/UA-2; retail ECDSA P-256.

Reproduce:

# gopdflib Zerodha gold standard (5000×48)
make bench-gopdflib-zerodha-x10
make bench-gopdflib-zerodha-nocomply-x10

# gopdfsuit (k6 + Gin)
make bench-k6

# pypdfsuit (rebuild bindings first: cd bindings/python && ./build.sh)
make bench-pypdfsuit-zerodha-x10
make bench-pypdfsuit-zerodha-nocomply-x10

All processing is in-memory with zero external runtime dependencies.

🛠️ Development

Windows users: Use WSL - Make and shell scripts are required. See Prerequisites.

# Build
make build
# or directly:
go build -o bin/gopdfsuit ./cmd/gopdfsuit

# Cross-compile
GOOS=linux GOARCH=amd64 go build -o bin/gopdfsuit-linux ./cmd/gopdfsuit

# Test
make test
# or:
go test -cover ./...

# Format & lint
make fmt && make lint

Project Structure

gopdfsuit/
├── bindings/           # Native language bindings (Python CGO)
├── cmd/gopdfsuit/      # Application entrypoint
├── docs/               # Built frontend assets
├── frontend/           # React frontend (Vite)
├── guides/             # Documentation guides
├── internal/
│   ├── handlers/       # HTTP handlers
│   ├── middleware/     # Gin middleware
│   ├── models/         # Template models
│   └── pdf/            # PDF generation & processing
├── pkg/
│   └── gopdflib/       # Standalone Go library
├── sampledata/         # Sample templates & data
└── test/               # Integration tests

🤝 Contributing

See CONTRIBUTING.md for setup, development workflow, testing, and pull request guidelines.

Quick start:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Run make fmt && make lint && make test
4. Commit changes and open a Pull Request

📄 License

MIT License - see LICENSE

Made with ❤️ by Chinmay Sawant

⭐ Star this repo if you find it helpful!

Developed from scratch with assistance from GitHub Copilot.