gotenberg

package module
v1.9.2 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 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
  • Health checks and service monitoring
  • Middleware support (retry, rate limiting, logging, circuit breaker)
  • 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.

Markdown to PDF Conversion

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

Office Documents to PDF

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

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.

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

Health Checks and Monitoring

The client provides methods to monitor the Gotenberg service health, version, and metrics.

See examples/cmd/health for a complete example.

Middleware Support

The client supports various middleware for enhanced reliability and observability.

Available middleware options:

  • Retry: Automatic retry on failures with configurable backoff
  • Rate Limiting: Control request rate to prevent overwhelming the service
  • Logging: Request/response logging with custom logger
  • Circuit Breaker: Fail fast when service is unavailable

See examples in the http-client repository for middleware usage examples.

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).

Installation

go get github.com/nativebpm/gotenberg-client

Basic Usage

package main

import (
	"context"
	"io"
	"log"
	"net/http"
	"os"
	"strings"

	"github.com/nativebpm/gotenberg-client"
)

func main() {
	client, err := gotenberg.NewClient(http.Client{}, "http://localhost:3000")
	if err != nil {
		log.Fatal(err)
	}

	html := strings.NewReader("<html><body><h1>Hello World!</h1></body></html>")

	resp, err := client.Chromium().
		ConvertHTML(context.Background(), html).
		PaperSizeA6().
		Margins(0.5, 0.5, 0.5, 0.5).
		Send()
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	f, _ := os.Create("out.pdf")
	io.Copy(f, resp.Body)
	f.Close()
}

See the examples in examples/ for complete usage demonstrations:

Testing

Run all tests and benchmarks.

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

Project Structure

  • gotenberg.go — main client with module accessors
  • health.go — health checks, version, and metrics
  • middleware.go — middleware support (retry, rate limiting, logging, circuit breaker)
  • 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/converturl — convert web page URL to PDF
  • 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/chromium/timeout — request timeout 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/cmd/health — health checks, version, and metrics
  • 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) SetTransport ¶ added in v1.9.0 

func (c *Client) SetTransport(rt http.RoundTripper) *Client

SetTransport sets a custom base RoundTripper. This will be wrapped by middlewares.

func (*Client) Use ¶ added in v1.9.0 

func (c *Client) Use(middleware func(http.RoundTripper) http.RoundTripper) *Client

Use adds a middleware to the client. Middlewares are applied in the order they are added. Each middleware is a function that takes a RoundTripper and returns a wrapped RoundTripper.

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) WithLogger ¶ added in v1.8.8 

func (c *Client) WithLogger(logger Logger) *Client

WithLogger adds logging middleware with logger

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 Logger ¶ added in v1.8.8 

type Logger = httpclient.Logger

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.