feat(pdfengines): add PDF/UA (#714)

pkg/modules/pdfengines/pdfengines.go

@@ -12,28 +12,28 @@ import (
 )
 
 func init() {
-	gotenberg.MustRegisterModule(PDFEngines{})
+	gotenberg.MustRegisterModule(new(PdfEngines))
 }
 
-// PDFEngines is a module which gathers available gotenberg.PDFEngine modules.
-// The available gotenberg.PDFEngine modules can be either all
-// gotenberg.PDFEngine modules or the modules selected by the user thanks to
-// the "engines" flag.
+// PdfEngines acts as an aggregator and manager for multiple PDF engine
+// modules. It enables the selection and ordering of PDF engines based on user
+// preferences passed via command-line flags. The [PdfEngines] module also
+// implements the [gotenberg.PdfEngine] interface, providing a unified approach
+// to PDF processing across the various engines it manages.
 //
-// PDFEngines wraps the gotenberg.PDFEngine modules in an internal struct which
-// also implements gotenberg.PDFEngine. This struct provides a sort of fallback
-// mechanism: if an engine's method returns an error, it calls the same method
-// from another engine.
-//
-// This module implements the gotenberg.PDFEngineProvider interface.
-type PDFEngines struct {
+// When processing PDFs, [PdfEngines] will attempt to use the engines in the
+// order they were defined. If the primary engine encounters an error,
+// [PdfEngines] can fall back to the next available engine. It also implements
+// the [api.Router] interface to expose relevant PDF processing routes if
+// enabled.
+type PdfEngines struct {
 	names         []string
-	engines       []gotenberg.PDFEngine
+	engines       []gotenberg.PdfEngine
 	disableRoutes bool
 }
 
-// Descriptor returns a PDFEngines' module descriptor.
-func (PDFEngines) Descriptor() gotenberg.ModuleDescriptor {
+// Descriptor returns a PdfEngines' module descriptor.
+func (mod *PdfEngines) Descriptor() gotenberg.ModuleDescriptor {
 	return gotenberg.ModuleDescriptor{
 		ID: "pdfengines",
 		FlagSet: func() *flag.FlagSet {
@@ -43,13 +43,13 @@ func (PDFEngines) Descriptor() gotenberg.ModuleDescriptor {
 
 			return fs
 		}(),
-		New: func() gotenberg.Module { return new(PDFEngines) },
+		New: func() gotenberg.Module { return new(PdfEngines) },
 	}
 }
 
-// Provision gets either all gotenberg.PDFEngine modules or the modules
+// Provision gets either all [gotenberg.PdfEngine] modules or the modules
 // selected by the user thanks to the "engines" flag.
-func (mod *PDFEngines) Provision(ctx *gotenberg.Context) error {
+func (mod *PdfEngines) Provision(ctx *gotenberg.Context) error {
 	flags := ctx.ParsedFlags()
 	names := flags.MustStringSlice("pdfengines-engines")
 	mod.disableRoutes = flags.MustBool("pdfengines-disable-routes")
@@ -66,15 +66,15 @@ func (mod *PDFEngines) Provision(ctx *gotenberg.Context) error {
 
 	logger = logger.Named("pdfengines")
 
-	engines, err := ctx.Modules(new(gotenberg.PDFEngine))
+	engines, err := ctx.Modules(new(gotenberg.PdfEngine))
 	if err != nil {
 		return fmt.Errorf("get PDF engines: %w", err)
 	}
 
-	mod.engines = make([]gotenberg.PDFEngine, len(engines))
+	mod.engines = make([]gotenberg.PdfEngine, len(engines))
 
 	for i, engine := range engines {
-		mod.engines[i] = engine.(gotenberg.PDFEngine)
+		mod.engines[i] = engine.(gotenberg.PdfEngine)
 	}
 
 	if len(names) > 0 {
@@ -82,9 +82,10 @@ func (mod *PDFEngines) Provision(ctx *gotenberg.Context) error {
 		mod.names = names
 
 		for i, name := range names {
-			logger.Warn("unoconv-pdfengine is deprecated; prefer api-pdfengine instead")
-			if name == "unoconv-pdfengine" {
-				mod.names[i] = "api-pdfengine"
+			// FIXME: deprecated.
+			if name == "unoconv-pdfengine" || name == "uno-pdfengine" {
+				logger.Warn(fmt.Sprintf("%s is deprecated; prefer libreoffice-pdfengine instead", name))
+				mod.names[i] = "libreoffice-pdfengine"
 			}
 		}
 
@@ -101,10 +102,10 @@ func (mod *PDFEngines) Provision(ctx *gotenberg.Context) error {
 	return nil
 }
 
-// Validate validates there is at least one gotenberg.PDFEngine module
-// available. It also validates that selected gotenberg.PDFEngine modules
+// Validate validates there is at least one [gotenberg.PdfEngine] module
+// available. It also validates that selected [gotenberg.PdfEngine] modules
 // actually exist.
-func (mod PDFEngines) Validate() error {
+func (mod *PdfEngines) Validate() error {
 	if len(mod.engines) == 0 {
 		return errors.New("no PDF engine")
 	}
@@ -139,17 +140,17 @@ func (mod PDFEngines) Validate() error {
 	return fmt.Errorf("non-existing PDF engine(s): %s - available PDF engine(s): %s", nonExistingEngines, availableEngines)
 }
 
-// SystemMessages returns one message with the selected gotenberg.PDFEngine
+// SystemMessages returns one message with the selected [gotenberg.PdfEngine]
 // modules.
-func (mod PDFEngines) SystemMessages() []string {
+func (mod *PdfEngines) SystemMessages() []string {
 	return []string{
 		strings.Join(mod.names[:], " "),
 	}
 }
 
-// PDFEngine returns a gotenberg.PDFEngine.
-func (mod PDFEngines) PDFEngine() (gotenberg.PDFEngine, error) {
-	engines := make([]gotenberg.PDFEngine, len(mod.names))
+// PdfEngine returns a [gotenberg.PdfEngine].
+func (mod *PdfEngines) PdfEngine() (gotenberg.PdfEngine, error) {
+	engines := make([]gotenberg.PdfEngine, len(mod.names))
 
 	for i, name := range mod.names {
 		for _, engine := range mod.engines {
@@ -160,20 +161,20 @@ func (mod PDFEngines) PDFEngine() (gotenberg.PDFEngine, error) {
 		}
 	}
 
-	return newMultiPDFEngines(engines...), nil
+	return newMultiPdfEngines(engines...), nil
 }
 
 // Routes returns the HTTP routes.
-func (mod PDFEngines) Routes() ([]api.Route, error) {
+func (mod *PdfEngines) Routes() ([]api.Route, error) {
 	if mod.disableRoutes {
 		return nil, nil
 	}
 
-	engine, err := mod.PDFEngine()
+	engine, err := mod.PdfEngine()
 	if err != nil {
 		// Should not happen, unless our provider implementation
 		// changes in the future.
-		return nil, fmt.Errorf("get pdf engine: %w", err)
+		return nil, fmt.Errorf("get pdf mod: %w", err)
 	}
 
 	return []api.Route{
@@ -184,10 +185,10 @@ func (mod PDFEngines) Routes() ([]api.Route, error) {
 
 // Interface guards.
 var (
-	_ gotenberg.Module            = (*PDFEngines)(nil)
-	_ gotenberg.Provisioner       = (*PDFEngines)(nil)
-	_ gotenberg.Validator         = (*PDFEngines)(nil)
-	_ gotenberg.SystemLogger      = (*PDFEngines)(nil)
-	_ gotenberg.PDFEngineProvider = (*PDFEngines)(nil)
-	_ api.Router                  = (*PDFEngines)(nil)
+	_ gotenberg.Module            = (*PdfEngines)(nil)
+	_ gotenberg.Provisioner       = (*PdfEngines)(nil)
+	_ gotenberg.Validator         = (*PdfEngines)(nil)
+	_ gotenberg.SystemLogger      = (*PdfEngines)(nil)
+	_ gotenberg.PdfEngineProvider = (*PdfEngines)(nil)
+	_ api.Router                  = (*PdfEngines)(nil)
 )