gotenberg

package module
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2025 License: MIT Imports: 6 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 to PDF conversion
  • Webhook support
  • Easy file/multipart uploads
  • Paper size, margins, and advanced PDF options

Quick Start: Synchronous HTML to PDF

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

Example: Async PDF Generation with Webhook

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

go run ./examples/cmd/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

Testing

Run all tests and benchmarks:

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

Project Structure

  • gotenberg.go — main client implementation
  • examples/ — real-world usage: invoice template, logo, webhook server
  • examples/cmd/webhook — async webhook demo
  • examples/model — invoice data structs
  • examples/pkg/templates/invoice — HTML template for invoice
  • 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 converting HTML and URLs to PDF documents.

Index ¶

Constants ¶

View Source 
const (
	ConvertHTML = "/forms/chromium/convert/html"
	ConvertURL  = "/forms/chromium/convert/url"
)
View Source 
const (
	FieldSinglePage              = "singlePage"
	FieldPaperWidth              = "paperWidth"
	FieldPaperHeight             = "paperHeight"
	FieldMarginTop               = "marginTop"
	FieldMarginBottom            = "marginBottom"
	FieldMarginLeft              = "marginLeft"
	FieldMarginRight             = "marginRight"
	FieldPreferCSSPageSize       = "preferCssPageSize"
	FieldGenerateDocumentOutline = "generateDocumentOutline"
	FieldGenerateTaggedPDF       = "generateTaggedPdf"
	FieldPrintBackground         = "printBackground"
	FieldOmitBackground          = "omitBackground"
	FieldLandscape               = "landscape"
	FieldScale                   = "scale"
	FieldNativePageRanges        = "nativePageRanges"
)
View Source 
const (
	HeaderWebhookURL              = "Gotenberg-Webhook-Url"
	HeaderWebhookErrorURL         = "Gotenberg-Webhook-Error-Url"
	HeaderWebhookMethod           = "Gotenberg-Webhook-Method"
	HeaderWebhookErrorMethod      = "Gotenberg-Webhook-Error-Method"
	HeaderWebhookExtraHTTPHeaders = "Gotenberg-Webhook-Extra-Http-Headers"
	HeaderOutputFilename          = "Gotenberg-Output-Filename"
	HeaderGotenbergTrace          = "Gotenberg-Trace"
)
View Source 
const (
	FieldURL       = "url"
	FieldFiles     = "files"
	FileIndexHTML  = "index.html"
	FileFooterHTML = "footer.html"
	FileHeaderHTML = "header.html"
	FileStylesCSS  = "styles.css"
)

Variables ¶

View Source 
var (
	PaperSizeLetter  = [2]float64{8.5, 11}
	PaperSizeLegal   = [2]float64{8.5, 14}
	PaperSizeTabloid = [2]float64{11, 17}
	PaperSizeLedger  = [2]float64{17, 11}
	PaperSizeA0      = [2]float64{33.1, 46.8}
	PaperSizeA1      = [2]float64{23.4, 33.1}
	PaperSizeA2      = [2]float64{16.54, 23.4}
	PaperSizeA3      = [2]float64{11.7, 16.54}
	PaperSizeA4      = [2]float64{8.27, 11.7}
	PaperSizeA5      = [2]float64{5.83, 8.27}
	PaperSizeA6      = [2]float64{4.13, 5.83}
)

Functions ¶

This section is empty.

Types ¶

type Client ¶ 

type Client struct {
	*httpclient.Client
}

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) ConvertHTML ¶ added in v1.0.1 

func (c *Client) ConvertHTML(ctx context.Context, html io.Reader) *Request

ConvertHTML creates a request to convert HTML content to PDF. The html parameter should contain the HTML content to be converted.

func (*Client) ConvertURL ¶ added in v1.0.1 

func (c *Client) ConvertURL(ctx context.Context, url string) *Request

ConvertURL creates a request to convert a web page at the given URL to PDF.

type Request ¶ added in v1.1.1 

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

Request represents a Gotenberg conversion request builder. It wraps the underlying multipart request and provides Gotenberg-specific methods.

func (*Request) Bool ¶ added in v1.1.1 

func (r *Request) Bool(fieldName string, value bool) *Request

Bool adds a boolean form parameter to the conversion request.

func (*Request) File ¶ added in v1.1.1 

func (r *Request) File(key, filename string, content io.Reader) *Request

File adds a file to the conversion request.

func (*Request) Float ¶ added in v1.1.1 

func (r *Request) Float(fieldName string, value float64) *Request

Float adds a float64 form parameter to the conversion request.

func (*Request) Header ¶ added in v1.1.1 

func (r *Request) Header(key, value string) *Request

Header adds a header to the conversion request.

func (*Request) Margins ¶ added in v1.1.1 

func (r *Request) Margins(top, right, bottom, left float64) *Request

Margins sets the page margins for the PDF in inches. Parameters are in order: top, right, bottom, left.

func (*Request) OutputFilename ¶ added in v1.3.1 

func (r *Request) OutputFilename(filename string) *Request

OutputFilename sets the output filename for the generated PDF.

func (*Request) PaperSize ¶ added in v1.1.1 

func (r *Request) PaperSize(width, height float64) *Request

PaperSize sets the paper size for the PDF using width and height in inches.

func (*Request) PaperSizeA4 ¶ added in v1.1.1 

func (r *Request) PaperSizeA4() *Request

PaperSizeA4 sets the paper size to A4 format.

func (*Request) PaperSizeA6 ¶ added in v1.5.0 

func (r *Request) PaperSizeA6() *Request

PaperSizeA6 sets the paper size to A6 format.

func (*Request) PaperSizeLetter ¶ added in v1.1.1 

func (r *Request) PaperSizeLetter() *Request

PaperSizeLetter sets the paper size to Letter format.

func (*Request) Param ¶ added in v1.4.5 

func (r *Request) Param(key, value string) *Request

Param adds a form parameter to the conversion request.

func (*Request) Send ¶ added in v1.1.1 

func (r *Request) Send() (*Response, error)

Send executes the conversion request and returns the response. Returns an error if the request fails or the conversion cannot be completed.

func (*Request) WebhookErrorURL ¶ added in v1.4.0 

func (r *Request) WebhookErrorURL(url, method string) *Request

WebhookErrorURL sets the webhook URL and HTTP method for failed conversions.

func (*Request) WebhookHeader ¶ added in v1.4.6 

func (r *Request) WebhookHeader(key, value string) *Request

WebhookHeader adds a custom header to be sent with webhook requests. Multiple headers can be added by calling this method multiple times.

func (*Request) WebhookURL ¶ added in v1.4.0 

func (r *Request) WebhookURL(url, method string) *Request

WebhookURL sets the webhook URL and HTTP method for successful conversions.

type Response ¶ added in v1.3.1 

type Response struct {
	*http.Response
	GotenbergTrace string
}

Response represents a Gotenberg conversion response. It wraps the HTTP response and provides access to the Gotenberg trace header.

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
examples
cmd/helloworld command
cmd/webhook command
model
pkg/image
pkg/templates/invoice

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.