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

pkg/modules/qpdf/doc.go

@@ -1,3 +1,8 @@
-// Package qpdf provides a module which abstracts the CLI tool QPDF and
-// implements the gotenberg.PDFEngine interface.
+// Package qpdf provides an implementation of the gotenberg.PdfEngine
+// interface using the QPDF command-line tool. This package allows for the
+// merging  of PDF files but does not support conversion to specific PDF
+// formats. The path to the QPDF binary must be specified using the
+// QPDK_BIN_PATH environment variable.
+//
+// See: https://github.com/qpdf/qpdf.
 package qpdf

pkg/modules/qpdf/qpdf.go

@@ -13,26 +13,25 @@ import (
 )
 
 func init() {
-	gotenberg.MustRegisterModule(QPDF{})
+	gotenberg.MustRegisterModule(new(QPdf))
 }
 
-// QPDF abstracts the CLI tool QPDF and implements the gotenberg.PDFEngine
+// QPdf abstracts the CLI tool QPDF and implements the [gotenberg.PdfEngine]
 // interface.
-type QPDF struct {
+type QPdf struct {
 	binPath string
 }
 
-// Descriptor returns a QPDF's module descriptor.
-func (QPDF) Descriptor() gotenberg.ModuleDescriptor {
+// Descriptor returns a [QPdf]'s module descriptor.
+func (engine *QPdf) Descriptor() gotenberg.ModuleDescriptor {
 	return gotenberg.ModuleDescriptor{
 		ID:  "qpdf",
-		New: func() gotenberg.Module { return new(QPDF) },
+		New: func() gotenberg.Module { return new(QPdf) },
 	}
 }
 
-// Provision sets the modules properties. It returns an error if the
-// environment variable QPDF_BIN_PATH is not set.
-func (engine *QPDF) Provision(_ *gotenberg.Context) error {
+// Provision sets the modules properties.
+func (engine *QPdf) Provision(ctx *gotenberg.Context) error {
 	binPath, ok := os.LookupEnv("QPDF_BIN_PATH")
 	if !ok {
 		return errors.New("QPDF_BIN_PATH environment variable is not set")
@@ -44,21 +43,22 @@ func (engine *QPDF) Provision(_ *gotenberg.Context) error {
 }
 
 // Validate validates the module properties.
-func (engine QPDF) Validate() error {
+func (engine *QPdf) Validate() error {
 	_, err := os.Stat(engine.binPath)
 	if os.IsNotExist(err) {
-		return fmt.Errorf("QPDF binary path does not exist: %w", err)
+		return fmt.Errorf("QPdf binary path does not exist: %w", err)
 	}
 
 	return nil
 }
 
 // Metrics returns the metrics.
-func (engine QPDF) Metrics() ([]gotenberg.Metric, error) {
+func (engine *QPdf) Metrics() ([]gotenberg.Metric, error) {
+	// TODO: remove deprecated.
 	return []gotenberg.Metric{
 		{
 			Name:        "qpdf_active_instances_count",
-			Description: "Current number of active QPDF instances.",
+			Description: "Current number of active QPDF instances - deprecated.",
 			Read: func() float64 {
 				activeInstancesCountMu.RLock()
 				defer activeInstancesCountMu.RUnlock()
@@ -69,8 +69,8 @@ func (engine QPDF) Metrics() ([]gotenberg.Metric, error) {
 	}, nil
 }
 
-// Merge merges the given PDFs into a unique PDF.
-func (engine QPDF) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error {
+// Merge combines multiple PDFs into a single PDF.
+func (engine *QPdf) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error {
 	var args []string
 	args = append(args, "--empty")
 	args = append(args, "--pages")
@@ -99,9 +99,9 @@ func (engine QPDF) Merge(ctx context.Context, logger *zap.Logger, inputPaths []s
 	return fmt.Errorf("merge PDFs with QPDF: %w", err)
 }
 
-// Convert is not available for this PDF engine.
-func (engine QPDF) Convert(_ context.Context, _ *zap.Logger, format, _, _ string) error {
-	return fmt.Errorf("convert PDF to '%s' with QPDF: %w", format, gotenberg.ErrPDFEngineMethodNotAvailable)
+// Convert is not available in this implementation.
+func (engine *QPdf) Convert(ctx context.Context, logger *zap.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
+	return fmt.Errorf("convert PDF to '%+v' with QPDF: %w", formats, gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 var (
@@ -110,9 +110,9 @@ var (
 )
 
 var (
-	_ gotenberg.Module          = (*QPDF)(nil)
-	_ gotenberg.Provisioner     = (*QPDF)(nil)
-	_ gotenberg.Validator       = (*QPDF)(nil)
-	_ gotenberg.MetricsProvider = (*QPDF)(nil)
-	_ gotenberg.PDFEngine       = (*QPDF)(nil)
+	_ gotenberg.Module          = (*QPdf)(nil)
+	_ gotenberg.Provisioner     = (*QPdf)(nil)
+	_ gotenberg.Validator       = (*QPdf)(nil)
+	_ gotenberg.MetricsProvider = (*QPdf)(nil)
+	_ gotenberg.PdfEngine       = (*QPdf)(nil)
 )

pkg/modules/qpdf/qpdf_test.go

@@ -12,59 +12,67 @@ import (
 	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
 )
 
-func TestQPDF_Descriptor(t *testing.T) {
-	descriptor := QPDF{}.Descriptor()
+func TestQPdf_Descriptor(t *testing.T) {
+	descriptor := new(QPdf).Descriptor()
 
 	actual := reflect.TypeOf(descriptor.New())
-	expect := reflect.TypeOf(new(QPDF))
+	expect := reflect.TypeOf(new(QPdf))
 
 	if actual != expect {
 		t.Errorf("expected '%s' but got '%s'", expect, actual)
 	}
 }
 
-func TestQPDF_Provision(t *testing.T) {
-	mod := new(QPDF)
+func TestQPdf_Provision(t *testing.T) {
+	engine := new(QPdf)
 	ctx := gotenberg.NewContext(gotenberg.ParsedFlags{}, nil)
 
-	err := mod.Provision(ctx)
+	err := engine.Provision(ctx)
 	if err != nil {
 		t.Errorf("expected no error but got: %v", err)
 	}
 }
 
-func TestQPDF_Validate(t *testing.T) {
-	for i, tc := range []struct {
-		binPath   string
-		expectErr bool
+func TestQPdf_Validate(t *testing.T) {
+	for _, tc := range []struct {
+		scenario    string
+		binPath     string
+		expectError bool
 	}{
 		{
-			expectErr: true,
+			scenario:    "empty bin path",
+			binPath:     "",
+			expectError: true,
 		},
 		{
-			binPath:   "/foo",
-			expectErr: true,
+			scenario:    "bin path does not exist",
+			binPath:     "/foo",
+			expectError: true,
 		},
 		{
-			binPath: os.Getenv("QPDF_BIN_PATH"),
+			scenario:    "validate success",
+			binPath:     os.Getenv("QPDF_BIN_PATH"),
+			expectError: false,
 		},
 	} {
-		mod := new(QPDF)
-		mod.binPath = tc.binPath
-		err := mod.Validate()
+		t.Run(tc.scenario, func(t *testing.T) {
+			engine := new(QPdf)
+			engine.binPath = tc.binPath
+			err := engine.Validate()
 
-		if tc.expectErr && err == nil {
-			t.Errorf("test %d: expected error but got: %v", i, err)
-		}
+			if !tc.expectError && err != nil {
+				t.Fatalf("expected no error but got: %v", err)
+			}
 
-		if !tc.expectErr && err != nil {
-			t.Errorf("test %d: expected no error but got: %v", i, err)
-		}
+			if tc.expectError && err == nil {
+				t.Fatal("expected error but got none")
+			}
+		})
 	}
 }
 
-func TestQPDF_Metrics(t *testing.T) {
-	metrics, err := new(QPDF).Metrics()
+func TestQPdf_Metrics(t *testing.T) {
+	metrics, err := new(QPdf).Metrics()
 	if err != nil {
 		t.Errorf("expected no error but got: %v", err)
 	}
@@ -75,80 +83,84 @@ func TestQPDF_Metrics(t *testing.T) {
 
 	actual := metrics[0].Read()
 	if actual != 0 {
-		t.Errorf("expected %d QPDF instances, but got %f", 0, actual)
+		t.Errorf("expected %d QPdf instances, but got %f", 0, actual)
 	}
 }
 
-func TestQPDF_Merge(t *testing.T) {
-	for i, tc := range []struct {
-		ctx        context.Context
-		inputPaths []string
-		expectErr  bool
+func TestQPdf_Merge(t *testing.T) {
+	for _, tc := range []struct {
+		scenario    string
+		ctx         context.Context
+		inputPaths  []string
+		expectError bool
 	}{
 		{
-			ctx: context.TODO(),
+			scenario:    "invalid context",
+			ctx:         nil,
+			expectError: true,
+		},
+		{
+			scenario: "invalid input path",
+			ctx:      context.TODO(),
+			inputPaths: []string{
+				"foo",
+			},
+			expectError: true,
+		},
+		{
+			scenario: "single file success",
+			ctx:      context.TODO(),
 			inputPaths: []string{
 				"/tests/test/testdata/pdfengines/sample1.pdf",
 			},
 		},
 		{
-			ctx: context.TODO(),
+			scenario: "many files success",
+			ctx:      context.TODO(),
 			inputPaths: []string{
 				"/tests/test/testdata/pdfengines/sample1.pdf",
 				"/tests/test/testdata/pdfengines/sample2.pdf",
 			},
 		},
-		{
-			ctx:       nil,
-			expectErr: true,
-		},
-		{
-			ctx: context.TODO(),
-			inputPaths: []string{
-				"foo",
-			},
-			expectErr: true,
-		},
 	} {
-		func() {
-			mod := new(QPDF)
-
-			err := mod.Provision(nil)
+		t.Run(tc.scenario, func(t *testing.T) {
+			engine := new(QPdf)
+			err := engine.Provision(nil)
 			if err != nil {
-				t.Fatalf("test %d: expected error but got: %v", i, err)
+				t.Fatalf("expected error but got: %v", err)
 			}
 
 			fs := gotenberg.NewFileSystem()
 			outputDir, err := fs.MkdirAll()
 			if err != nil {
-				t.Fatalf("test %d: expected error but got: %v", i, err)
+				t.Fatalf("expected error but got: %v", err)
 			}
 
 			defer func() {
-				err := os.RemoveAll(fs.WorkingDirPath())
+				err = os.RemoveAll(fs.WorkingDirPath())
 				if err != nil {
-					t.Fatalf("test %d: expected no error while cleaning up but got: %v", i, err)
+					t.Fatalf("expected no error while cleaning up but got: %v", err)
 				}
 			}()
 
-			err = mod.Merge(tc.ctx, zap.NewNop(), tc.inputPaths, outputDir+"/foo.pdf")
+			err = engine.Merge(tc.ctx, zap.NewNop(), tc.inputPaths, outputDir+"/foo.pdf")
 
-			if tc.expectErr && err == nil {
-				t.Errorf("test %d: expected error but got: %v", i, err)
+			if !tc.expectError && err != nil {
+				t.Fatalf("expected no error but got: %v", err)
 			}
 
-			if !tc.expectErr && err != nil {
-				t.Errorf("test %d: expected no error but got: %v", i, err)
+			if tc.expectError && err == nil {
+				t.Fatal("expected error but got none")
 			}
-		}()
+		})
 	}
 }
 
-func TestQPDF_Convert(t *testing.T) {
-	mod := new(QPDF)
-	err := mod.Convert(context.TODO(), zap.NewNop(), "", "", "")
+func TestQPdf_Convert(t *testing.T) {
+	engine := new(QPdf)
+	err := engine.Convert(context.TODO(), zap.NewNop(), gotenberg.PdfFormats{}, "", "")
 
-	if !errors.Is(err, gotenberg.ErrPDFEngineMethodNotAvailable) {
-		t.Errorf("expected error %v, but got: %v", gotenberg.ErrPDFEngineMethodNotAvailable, err)
+	if !errors.Is(err, gotenberg.ErrPdfEngineMethodNotSupported) {
+		t.Errorf("expected error %v, but got: %v", gotenberg.ErrPdfEngineMethodNotSupported, err)
 	}
 }