gotenberg

package
v7.5.1 Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2022 License: MIT Imports: 18 Imported by: 2

Documentation

Overview

Package gotenberg provides most of the logic of the module system.

caddyserver/caddy, licensed under the Apache License 2.0, has significantly inspired this module system.

More details are available on https://caddyserver.com/.

Index

Constants

View Source 
const (
	FormatPDFA1a string = "PDF/A-1a"
	FormatPDFA1b string = "PDF/A-1b"
	FormatPDFA2a string = "PDF/A-2a"
	FormatPDFA2b string = "PDF/A-2b"
	FormatPDFA2u string = "PDF/A-2u"
	FormatPDFA3a string = "PDF/A-3a"
	FormatPDFA3b string = "PDF/A-3b"
	FormatPDFA3u string = "PDF/A-3u"
)

Variables

View Source 
var (
	// ErrPDFEngineMethodNotAvailable happens if a PDFEngine method is not
	// available in the implementation.
	ErrPDFEngineMethodNotAvailable = errors.New("method not available")

	// ErrPDFFormatNotAvailable happens if a PDFEngine Convert's method does
	// not handle a specific format.
	ErrPDFFormatNotAvailable = errors.New("PDF format not available")
)

Functions

func MkdirAll 

func MkdirAll() (string, error)

MkdirAll creates a random directory based on the temporary path and returns its absolute path.

func MustRegisterModule 

func MustRegisterModule(mod Module)

MustRegisterModule registers a module.

To register a module, create an init() method in the module main go file: 

func init() {
	gotenberg.MustRegisterModule(YourModule{})
}

Then, in the main command (github.com/gotenberg/gotenberg/v7/cmd/gotenberg), import the module: 

imports (
	// Gotenberg modules.
	_ "your_module_path"
)

func NewDirPath 

func NewDirPath() string

NewDirPath returns a random absolute path based on the temporary path.

func TmpPath 

func TmpPath() string

TmpPath returns the default directory to use for temporary files and directories. Most if not all files and directories created by the application and its dependencies must be based on this default directory.

Types

type App 

type App interface {
	Start() error
	// StartupMessage returns a custom message to display on startup. If it
	// returns an empty string, a default startup message is used instead.
	StartupMessage() string
	Stop(ctx context.Context) error
}

App is a module interface for modules which can be started or stopped by the application.

type Cmd 

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

Cmd wraps an exec.Cmd.

func Command 

func Command(logger *zap.Logger, binPath string, args ...string) Cmd

Command creates a Cmd without a context. It configures the internal exec.Cmd of Cmd so that we may kill its unix process and all its children without creating orphans.

See https://medium.com/@felixge/killing-a-child-process-and-all-of-its-children-in-go-54079af94773.

func CommandContext 

func CommandContext(ctx context.Context, logger *zap.Logger, binPath string, args ...string) (Cmd, error)

CommandContext creates a Cmd with a context. It configures the internal exec.Cmd of Cmd so that we may kill its unix process and all its children without creating orphans.

See https://medium.com/@felixge/killing-a-child-process-and-all-of-its-children-in-go-54079af94773.

func (Cmd) Exec 

func (cmd Cmd) Exec() (int, error)

Exec executes the command and wait for its completion or until the context is done. In any case, it kills the unix process and all its children.

func (Cmd) Kill 

func (cmd Cmd) Kill() error

Kill kills the unix process and all its children without creating orphans.

See https://medium.com/@felixge/killing-a-child-process-and-all-of-its-children-in-go-54079af94773.

func (Cmd) Start 

func (cmd Cmd) Start() error

Start starts the command but does not wait for its completion.

func (Cmd) Wait added in v7.5.0 

func (cmd Cmd) Wait() error

Wait waits for the command to complete. It should be called when using the Start method, so that the command does not leak zombies.

type Context 

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

Context is a struct which helps initializing modules. When provisioning, a module may use the context to get other modules that it needs internally.

func NewContext 

func NewContext(
	flags ParsedFlags,
	descriptors []ModuleDescriptor,
) *Context

NewContext creates a Context. In a module, prefer the Provisioner interface to get a Context.

func (*Context) Module 

func (ctx *Context) Module(kind interface{}) (interface{}, error)

Module returns a module which satisfies the requested interface. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	mod, _ := ctx.Module(new(ModuleInterface))
	real := mod.(ModuleInterface)
}

If the module has not yet been initialized, this method initializes it. Otherwise, returns the already initialized instance.

func (*Context) Modules 

func (ctx *Context) Modules(kind interface{}) ([]interface{}, error)

Modules returns the list of modules which satisfies the requested interface. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	mods, _ := ctx.Modules(new(ModuleInterface))
	for _, mod := range mods {
		real := mod.(ModuleInterface)
		// ...
	}
}

If one or more modules have not yet been initialized, this method initializes them. Otherwise, returns the already initialized instances.

func (Context) ParsedFlags 

func (ctx Context) ParsedFlags() ParsedFlags

ParsedFlags returns the parsed flags. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	flags := ctx.ParsedFlags()
	m.foo = flags.RequiredString("foo")
}

type LoggerProvider 

type LoggerProvider interface {
	Logger(mod Module) (*zap.Logger, error)
}

LoggerProvider is a module interface which exposes a method for creating a zap.Logger for other modules. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	provider, _ := ctx.Module(new(gotenberg.LoggerProvider))
	logger, _   := provider.(gotenberg.LoggerProvider).Logger(m)
}

type LoggerProviderMock added in v7.5.0 

type LoggerProviderMock struct {
	LoggerMock func(mod Module) (*zap.Logger, error)
}

LoggerProviderMock is a mock for the LoggerProvider interface.

func (LoggerProviderMock) Logger added in v7.5.0 

func (provider LoggerProviderMock) Logger(mod Module) (*zap.Logger, error)

type Metric added in v7.1.0 

type Metric struct {
	// Name is the unique identifier.
	// Required.
	Name string

	// Description describes the metric.
	// Optional.
	Description string

	// Read returns the current value.
	// Required.
	Read func() float64
}

Metric represents a unitary metric.

type MetricsProvider added in v7.1.0 

type MetricsProvider interface {
	Metrics() ([]Metric, error)
}

MetricsProvider is a module interface which provides a list of Metric. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	provider, _ := ctx.Module(new(gotenberg.MetricsProvider))
	metrics, _  := provider.(gotenberg.MetricsProvider).Metrics()
}

type Module 

type Module interface {
	Descriptor() ModuleDescriptor
}

Module is a sort of plugin which adds new functionalities to the application or other modules. 

type YourModule struct {
	property string
}

func (YourModule) Descriptor() gotenberg.ModuleDescriptor {
	return gotenberg.ModuleDescriptor{
		ID: "your_module",
		FlagSet: func() *flag.FlagSet {
			fs := flag.NewFlagSet("your_module", flag.ExitOnError)
			fs.String("your_module-property", "default value", "flag description")

			return fs
		}(),
		New: func() gotenberg.Module { return new(YourModule) },
	}
}

type ModuleDescriptor 

type ModuleDescriptor struct {
	// ID is the unique name (snake case) of the module.
	// Required.
	ID string

	// FlagSet is the definition of the flags of the module.
	// Optional.
	FlagSet *flag.FlagSet

	// New returns a new and empty instance of the module's type.
	// Required.
	New func() Module
}

ModuleDescriptor describes your module for the application.

func GetModuleDescriptors 

func GetModuleDescriptors() []ModuleDescriptor

GetModuleDescriptors returns the descriptors of all registered modules.

type ModuleMock added in v7.5.0 

type ModuleMock struct {
	DescriptorMock func() ModuleDescriptor
}

ModuleMock is a mock for the Module interface.

func (ModuleMock) Descriptor added in v7.5.0 

func (mod ModuleMock) Descriptor() ModuleDescriptor

type PDFEngine 

type PDFEngine interface {
	// Merge merges the given PDFs into a unique PDF. The pages' order reflects
	// order of the given files.
	Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error

	// Convert converts the given PDF to a specific PDF format.
	Convert(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error
}

PDFEngine is a module interface which exposes methods for manipulating one or more PDFs. Implementations may abstract powerful tools like PDFtk, or fulfill those methods contracts in Golang directly.

type PDFEngineMock added in v7.5.0 

type PDFEngineMock struct {
	MergeMock   func(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error
	ConvertMock func(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error
}

PDFEngineMock is a mock for the PDFEngine interface.

func (PDFEngineMock) Convert added in v7.5.0 

func (engine PDFEngineMock) Convert(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error

func (PDFEngineMock) Merge added in v7.5.0 

func (engine PDFEngineMock) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error

type PDFEngineProvider 

type PDFEngineProvider interface {
	PDFEngine() (PDFEngine, error)
}

PDFEngineProvider is a module interface which exposes a method for creating a PDFEngine for other modules. 

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	provider, _  := ctx.Module(new(gotenberg.PDFEngineProvider))
	pdfengines, _ := provider.(gotenberg.PDFEngineProvider).PDFEngine()
}

type PDFEngineProviderMock added in v7.5.0 

type PDFEngineProviderMock struct {
	PDFEngineMock func() (PDFEngine, error)
}

PDFEngineProviderMock is a mock for the PDFEngineProvider interface.

func (PDFEngineProviderMock) PDFEngine added in v7.5.0 

func (provider PDFEngineProviderMock) PDFEngine() (PDFEngine, error)

type ParsedFlags 

type ParsedFlags struct {
	*flag.FlagSet
}

ParsedFlags wraps a flag.FlagSet so that retrieving the typed values is easier.

func (*ParsedFlags) MustBool 

func (f *ParsedFlags) MustBool(name string) bool

MustBool returns the boolean value of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedBool added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedBool(deprecated string, newName string) bool

MustDeprecatedBool returns the boolean value of a deprecated flag if it was explicitly set or the int value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedDuration added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedDuration(deprecated string, newName string) time.Duration

MustDeprecatedDuration returns the time.Duration value of a deprecated flag if it was explicitly set or the time.Duration value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedFloat64 added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedFloat64(deprecated string, newName string) float64

MustDeprecatedFloat64 returns the float value of a deprecated flag if it was explicitly set or the float value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedHumanReadableBytesString added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedHumanReadableBytesString(deprecated string, newName string) string

MustDeprecatedHumanReadableBytesString returns the human-readable bytes string of a deprecated flag if it was explicitly set or the human-readable bytes string of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedInt added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedInt(deprecated string, newName string) int

MustDeprecatedInt returns the int value of a deprecated flag if it was explicitly set or the int value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedRegexp added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedRegexp(deprecated string, newName string) *regexp.Regexp

MustDeprecatedRegexp returns the regular expression of a deprecated flag if it was explicitly set or the regular expression of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedString added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedString(deprecated string, newName string) string

MustDeprecatedString returns the string value of a deprecated flag if it was explicitly set or the string value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDeprecatedStringSlice added in v7.1.0 

func (f *ParsedFlags) MustDeprecatedStringSlice(deprecated string, newName string) []string

MustDeprecatedStringSlice returns the string slice value of a deprecated flag if it was explicitly set or the string slice value of the new flag. It panics if an error occurs.

func (*ParsedFlags) MustDuration 

func (f *ParsedFlags) MustDuration(name string) time.Duration

MustDuration returns the time.Duration value of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustFloat64 

func (f *ParsedFlags) MustFloat64(name string) float64

MustFloat64 returns the float value of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustHumanReadableBytesString 

func (f *ParsedFlags) MustHumanReadableBytesString(name string) string

MustHumanReadableBytesString returns the human-readable bytes string of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustInt 

func (f *ParsedFlags) MustInt(name string) int

MustInt returns the int value of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustRegexp 

func (f *ParsedFlags) MustRegexp(name string) *regexp.Regexp

MustRegexp returns the regular expression of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustString 

func (f *ParsedFlags) MustString(name string) string

MustString returns the string value of a flag given by name. It panics if an error occurs.

func (*ParsedFlags) MustStringSlice 

func (f *ParsedFlags) MustStringSlice(name string) []string

MustStringSlice returns the string slice value of a flag given by name. It panics if an error occurs.

type Provisioner 

type Provisioner interface {
	Provision(*Context) error
}

Provisioner is a module interface for modules which have to be initialized according to flags, environment variables, the context, etc.

type SystemLogger added in v7.3.1 

type SystemLogger interface {
	SystemMessages() []string
}

SystemLogger is a module interface for modules which want to display messages on startup.

type Validator 

type Validator interface {
	Validate() error
}

Validator is a module interface for modules which have to be validated after provisioning.

type ValidatorMock added in v7.5.0 

type ValidatorMock struct {
	ValidateMock func() error
}

ValidatorMock is a mock for the Validator interface.

func (ValidatorMock) Validate added in v7.5.0 

func (mod ValidatorMock) Validate() error

Source Files

View all Source files

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.