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

pkg/modules/pdftk/doc.go

@@ -1,3 +1,8 @@
-// Package pdftk provides a module which abstracts the CLI tool PDFtk and
-// implements the gotenberg.PDFEngine interface.
+// Package pdftk provides an implementation of the gotenberg.PdfEngine
+// interface using the PDFtk 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 PDFtk binary must be specified using the
+// PDFTK_BIN_PATH environment variable.
+//
+// See: https://gitlab.com/pdftk-java/pdftk.
 package pdftk

pkg/modules/pdftk/pdftk.go

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

pkg/modules/pdftk/pdftk_test.go

@@ -12,59 +12,67 @@ import (
 	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
 )
 
-func TestPDFtk_Descriptor(t *testing.T) {
-	descriptor := PDFtk{}.Descriptor()
+func TestPdfTk_Descriptor(t *testing.T) {
+	descriptor := new(PdfTk).Descriptor()
 
 	actual := reflect.TypeOf(descriptor.New())
-	expect := reflect.TypeOf(new(PDFtk))
+	expect := reflect.TypeOf(new(PdfTk))
 
 	if actual != expect {
 		t.Errorf("expected '%s' but got '%s'", expect, actual)
 	}
 }
 
-func TestPDFtk_Provision(t *testing.T) {
-	mod := new(PDFtk)
+func TestPdfTk_Provision(t *testing.T) {
+	engine := new(PdfTk)
 	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 TestPDFtk_Validate(t *testing.T) {
-	for i, tc := range []struct {
-		binPath   string
-		expectErr bool
+func TestPdfTk_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("PDFTK_BIN_PATH"),
+			scenario:    "validate success",
+			binPath:     os.Getenv("PDFTK_BIN_PATH"),
+			expectError: false,
 		},
 	} {
-		mod := new(PDFtk)
-		mod.binPath = tc.binPath
-		err := mod.Validate()
+		t.Run(tc.scenario, func(t *testing.T) {
+			engine := new(PdfTk)
+			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 TestPDFtk_Metrics(t *testing.T) {
-	metrics, err := new(PDFtk).Metrics()
+func TestPdfTk_Metrics(t *testing.T) {
+	metrics, err := new(PdfTk).Metrics()
 	if err != nil {
 		t.Fatalf("expected no error but got: %v", err)
 	}
@@ -79,76 +87,80 @@ func TestPDFtk_Metrics(t *testing.T) {
 	}
 }
 
-func TestPDFtk_Merge(t *testing.T) {
-	for i, tc := range []struct {
-		ctx        context.Context
-		inputPaths []string
-		expectErr  bool
+func TestPdfTk_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(PDFtk)
-
-			err := mod.Provision(nil)
+		t.Run(tc.scenario, func(t *testing.T) {
+			engine := new(PdfTk)
+			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 TestPDFtk_Convert(t *testing.T) {
-	mod := new(PDFtk)
-	err := mod.Convert(context.TODO(), zap.NewNop(), "", "", "")
+func TestPdfTk_Convert(t *testing.T) {
+	engine := new(PdfTk)
+	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)
 	}
 }