print2pdf

Documentation

Overview

Package print2pdf provides functions to save a webpage as a PDF file, leveraging Chromium and the DevTools Protocol.

Requires the environment variable CHROMIUM_PATH to be set with the full path to the Chromium binary.

The StartBrowser() function starts a headless instance of Chromium, to reduce startup time in long running services (like a web server), and therefore must be called before any call PrintPDF(). These functions can (and probably should) use different contexts: the one passed to StartBrowser() closes the whole browser when done or cancelled, while the one passed to PrintPDF() closes only the tab it uses.

Index

• Variables
• func Elapsed(message string) func()
• func PrintPDF(ctx context.Context, data GetPDFParams, h PDFHandler) (string, error)
• func Ptr[T any](v T) *T
• func Running() bool
• func StartBrowser(ctx context.Context) error
• type FileHandler
  • func NewFileHandler(path string) (FileHandler, error)
  • func (fh FileHandler) Close() error
  • func (fh FileHandler) Handle(r io.Reader) (string, error)
• type GetPDFParams
• type PDFHandler
• type PrintFormat
• type PrintMargins
• type S3Handler
  • func NewS3Handler(ctx context.Context, bucket, fileName string) (S3Handler, error)
  • func (sh S3Handler) Close() error
  • func (sh S3Handler) Handle(r io.Reader) (string, error)
• type StreamHandleReader
  • func NewStreamHandleReader(ctx context.Context, h chromedpio.StreamHandle) *StreamHandleReader
  • func (r *StreamHandleReader) Close() error
  • func (r *StreamHandleReader) Read(p []byte) (int, error)
• type StreamHandler
  • func NewStreamHandler(w io.Writer) StreamHandler
  • func (sh StreamHandler) Close() error
  • func (sh StreamHandler) Handle(r io.Reader) (string, error)
• type ValidationError
  • func NewValidationError(message string) ValidationError
  • func (v ValidationError) Error() string

Variables

var ChromiumPath = os.Getenv("CHROMIUM_PATH")

Chromium binary path. Required.

var FormatsMap = map[string]PrintFormat{
	"Letter":  {8.5, 11},
	"Legal":   {8.5, 14},
	"Tabloid": {11, 17},
	"Ledger":  {17, 11},
	"A0":      {33.1, 46.8},
	"A1":      {23.4, 33.1},
	"A2":      {16.54, 23.4},
	"A3":      {11.7, 16.54},
	"A4":      {8.27, 11.7},
	"A5":      {5.83, 8.27},
	"A6":      {4.13, 5.83},
}

Map of format names to their dimensions, in inches. Taken from https://pptr.dev/api/puppeteer.paperformat.

Functions

func Elapsed

func Elapsed(message string) func()

Write Elapsed time, to be used with defer.

func PrintPDF

func PrintPDF(ctx context.Context, data GetPDFParams, h PDFHandler) (string, error)

Print a webpage in PDF format and write the result to the input handler. Cancelling the context will close the tab. StartBrowser() must have been called once before calling this function.

func Ptr

func Ptr[T any](v T) *T

Convert literal values to pointers.

func Running

func Running() bool

Check if the browser is still running.

func StartBrowser

func StartBrowser(ctx context.Context) error

Allocate a browser to be reused by multiple invocations, to reduce startup time. Cancelling the context will close the browser. This function must be called before starting to print PDFs.

Types

type FileHandler

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

FileHandler handles saving a file in a local path.

func NewFileHandler

func NewFileHandler(path string) (FileHandler, error)

NewFileHandler returns a new instance of FileHandler.

func (FileHandler) Close

func (fh FileHandler) Close() error

Implement io.Closer interface.

func (FileHandler) Handle

func (fh FileHandler) Handle(r io.Reader) (string, error)

Implement PDFHandler interface.

type GetPDFParams

type GetPDFParams struct {
	// URL of the webpage to save. Required.
	Url string `json:"url"`
	// Filename of the generated PDF. A ".pdf" suffix will be appended if not present. Required.
	FileName string `json:"file_name"`
	// Media type to emulate. Accepted values are "print" and "screen". Default is "print".
	Media string `json:"media,omitempty"`
	// Page format. See FormatsMap for accepted values. Default is "A4".
	Format string `json:"format,omitempty"`
	// Print background graphics. Default is true.
	Background *bool `json:"background,omitempty"`
	// Page orientation. Accepted values are "landscape" and "portrait". Default is "portrait".
	Layout string `json:"layout,omitempty"`
	// Page margins in inches. Default is all 0.
	Margins *PrintMargins `json:"margin,omitempty"`
	// Scale of the webpage rendering. Default is 1.
	Scale float64 `json:"scale,omitempty"`
}

Parameters for generating a PDF.

type PDFHandler

type PDFHandler interface {
	// Include io.Closer interface, to accomodate implementations that need it.
	io.Closer
	// Handle writes the input stream to the implemented storage location, returning a URI (local path, URL, ...) or an error if any occur.
	Handle(io.Reader) (string, error)
}

PDFHandler is an interface implementing methods to handle saving a file to a storage location.

type PrintFormat

type PrintFormat struct {
	Width  float64
	Height float64
}

Represents a print format's width and height, in inches.

type PrintMargins

type PrintMargins struct {
	Top    float64 `json:"top,omitempty"`
	Bottom float64 `json:"bottom,omitempty"`
	Left   float64 `json:"left,omitempty"`
	Right  float64 `json:"right,omitempty"`
}

Page margins of the generated PDF, in inches.

type S3Handler

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

S3Handler handles uploading a file to an AWS S3 bucket.

func NewS3Handler

func NewS3Handler(ctx context.Context, bucket, fileName string) (S3Handler, error)

NewS3Handler returns a new instance of S3Uploader.

func (S3Handler) Close

func (sh S3Handler) Close() error

Implement io.Closer interface (noop).

func (S3Handler) Handle

func (sh S3Handler) Handle(r io.Reader) (string, error)

Implement PDFHandler interface.

type StreamHandleReader

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

StreamHandleReader is a helper to read a StreamHandle returned by chromedp when printing a web page to PDF with "ReturnAsStream" transfer mode. For more information about the protocol, see:

• https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF
• https://chromedevtools.github.io/devtools-protocol/tot/IO/

func NewStreamHandleReader

func NewStreamHandleReader(ctx context.Context, h chromedpio.StreamHandle) *StreamHandleReader

NewStreamHandleReader returns a new insance of StreamHandleReader.

func (*StreamHandleReader) Close

func (r *StreamHandleReader) Close() error

Implement io.Closer interface.

func (*StreamHandleReader) Read

func (r *StreamHandleReader) Read(p []byte) (int, error)

Implement io.Reader interface.

type StreamHandler

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

StreamHandler handles streaming a file.

func NewStreamHandler

func NewStreamHandler(w io.Writer) StreamHandler

NewStreamHandler returns a new instance of StreamHandler, which will stream the file to the provided writer.

func (StreamHandler) Close

func (sh StreamHandler) Close() error

Implement io.Closer interface (noop).

func (StreamHandler) Handle

func (sh StreamHandler) Handle(r io.Reader) (string, error)

Implement PDFHandler interface.

type ValidationError

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

Validation error in supplied parameter.

func NewValidationError

func NewValidationError(message string) ValidationError

Create a new validation error.

func (ValidationError) Error

func (v ValidationError) Error() string

Implement error interface.