gotenberg

package module
v1.8.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2025 License: MIT Imports: 10 Imported by: 0

README ¶

gotenberg-client

Go Reference Go Report Card License

A high-performance Go client for the Gotenberg HTTP API with a fluent interface. Built using only the Go standard library (via http-client).

Features:

  • Minimal dependencies (only stdlib + http-client)
  • Fluent API for building requests
  • Support for HTML/URL/Markdown to PDF conversion
  • Support for Office documents (Word, Excel, PowerPoint, etc.) to PDF conversion
  • PDF manipulation: merge, split, flatten, convert to PDF/A & PDF/UA, read/write metadata
  • Screenshot generation for web pages and HTML content
  • Webhook support
  • Download from URLs support
  • Request tracing support
  • Easy file/multipart uploads
  • Paper size, margins, and advanced PDF options

Quick Start: Synchronous HTML to PDF

See examples/cmd/chromium/helloworld for a basic HTML to PDF conversion example.

go run ./examples/cmd/chromium/helloworld

Markdown to PDF Conversion

Convert Markdown files to PDF with custom HTML templates. See examples/cmd/chromium/markdown for a complete example.

go run ./examples/cmd/chromium/markdown

Office Documents to PDF

Convert Office documents (Word, Excel, PowerPoint, etc.) to PDF. See examples/cmd/libreoffice/convert for a basic example.

go run ./examples/cmd/libreoffice/convert

Request Tracing

Gotenberg supports request tracing for better observability and debugging. By default, Gotenberg assigns a unique UUID trace to every request. You can also specify a custom trace identifier using the Trace() method:

resp, err := client.Chromium().
    ConvertHTML(context.Background(), htmlReader).
    Trace("my-custom-trace-12345").
    Send()

// The trace ID is returned in the response
log.Printf("Request trace: %s", resp.GotenbergTrace)

See examples/cmd/chromium/trace for a complete example.

Example: Async PDF Generation with Webhook

See examples/cmd/chromium/webhook for a full async webhook demo (HTML invoice to PDF, with logo, webhook server, and error handling).

# Run webhook example
go run ./examples/cmd/chromium/webhook

This will:

  • Start a local webhook server
  • Generate an invoice PDF using HTML template and logo
  • Receive the PDF via webhook callback from Gotenberg

Installation

go get github.com/nativebpm/gotenberg-client

Basic Usage

See the examples in examples/ for complete usage demonstrations:

Testing

Run all tests and benchmarks:

go test -v -bench=. ./...

Project Structure

  • gotenberg.go — main client with module accessors
  • chromium/ — Chromium module for HTML/URL/Markdown to PDF and screenshots
  • libreoffice/ — LibreOffice module for Office documents to PDF
  • pdfengines/ — PDF Engines module for PDF manipulation (merge, split, flatten, PDF/A, metadata)
  • examples/ — real-world usage examples
  • examples/cmd/chromium/helloworld — basic HTML to PDF conversion
  • examples/cmd/chromium/markdown — markdown to PDF conversion
  • examples/cmd/chromium/webhook — async webhook demo
  • examples/cmd/chromium/downloadfrom — download from URL example
  • examples/cmd/chromium/trace — request tracing example
  • examples/cmd/libreoffice/convert — Office document to PDF conversion
  • examples/cmd/libreoffice/downloadfrom — download Office documents from URL
  • examples/cmd/pdfengines/merge — PDF merge example
  • examples/model — invoice data structs
  • examples/pkg/templates/invoice — HTML template for invoice
  • examples/pkg/templates/markdown — HTML template for markdown
  • examples/pkg/image — logo generator

Dependencies

No third-party dependencies are required, ensuring minimal bloat and maximum compatibility.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation ¶

Overview ¶

Package gotenberg provides a client for the Gotenberg service. It offers a convenient API for document conversion using various engines.

Index ¶

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type CircuitBreakerConfig ¶ added in v1.8.7 

type CircuitBreakerConfig = httpclient.CircuitBreakerConfig

type Client ¶ 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Gotenberg HTTP client that wraps the base HTTP client with Gotenberg-specific functionality for document conversion.

func NewClient ¶ 

func NewClient(httpClient *http.Client, baseURL string) (*Client, error)

NewClient creates a new Gotenberg client with the given HTTP client and base URL. Returns an error if the base URL is invalid.

func (*Client) Chromium ¶ added in v1.7.0 

func (c *Client) Chromium() *chromium.Chromium

func (*Client) GetHealth ¶ added in v1.8.6 

func (c *Client) GetHealth(ctx context.Context) (*HealthResponse, error)

GetHealth performs a health check on the Gotenberg service. It returns the overall status and details about each module (e.g., Chromium, LibreOffice).

func (*Client) GetMetrics ¶ added in v1.8.6 

func (c *Client) GetMetrics(ctx context.Context) (string, error)

func (*Client) GetVersion ¶ added in v1.8.6 

func (c *Client) GetVersion(ctx context.Context) (string, error)

func (*Client) LibreOffice ¶ added in v1.7.1 

func (c *Client) LibreOffice() *libreoffice.LibreOffice

func (*Client) PDFEngines ¶ added in v1.7.1 

func (c *Client) PDFEngines() *pdfengines.PDFEngines

func (*Client) WithCircuitBreaker ¶ added in v1.8.7 

func (c *Client) WithCircuitBreaker() *Client

WithCircuitBreaker adds circuit breaker middleware with default config

func (*Client) WithCircuitBreakerConfig ¶ added in v1.8.7 

func (c *Client) WithCircuitBreakerConfig(config CircuitBreakerConfig) *Client

WithCircuitBreakerConfig adds circuit breaker middleware with custom config

func (*Client) WithLogging ¶ added in v1.8.7 

func (c *Client) WithLogging() *Client

WithLogging adds logging middleware

func (*Client) WithRateLimit ¶ added in v1.8.7 

func (c *Client) WithRateLimit(capacity int, refillRate time.Duration) *Client

WithRateLimit adds rate limiting middleware

func (*Client) WithRetry ¶ added in v1.8.7 

func (c *Client) WithRetry() *Client

WithRetry adds retry middleware with default config

func (*Client) WithRetryConfig ¶ added in v1.8.7 

func (c *Client) WithRetryConfig(config RetryConfig) *Client

WithRetryConfig adds retry middleware with custom config

type HealthResponse ¶ added in v1.8.6 

type HealthResponse struct {
	Status  string         `json:"status"`
	Details map[string]any `json:"details"`
}

HealthResponse represents the response from the health check endpoint.

type Response ¶ added in v1.3.1 

type Response = gotenberg.Response

Re-export common types for easier access.

type RetryConfig ¶ added in v1.8.7 

type RetryConfig = httpclient.RetryConfig

Re-export middleware types for easier access.

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
examples
cmd/chromium/converturl command
cmd/chromium/helloworld command
cmd/chromium/markdown command
cmd/chromium/timeout command
cmd/chromium/trace command
cmd/chromium/webhook command
cmd/health command
cmd/libreoffice/convert command
cmd/pdfengines/merge command
model
pkg/image
pkg/templates/invoice
pkg/templates/markdown
internal
chromium
Package chromium provides a client for the Gotenberg Chromium service.
 Package chromium provides a client for the Gotenberg Chromium service.
gotenberg
Package common provides shared types and constants for Gotenberg client modules.
 Package common provides shared types and constants for Gotenberg client modules.
libreoffice
Package libreoffice provides a client for the Gotenberg LibreOffice service.
 Package libreoffice provides a client for the Gotenberg LibreOffice service.
pdfengines
Package pdfengines provides a client for the Gotenberg PDF Engines service.
 Package pdfengines provides a client for the Gotenberg PDF Engines service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.