feat: add 7.x source code

pkg/modules/pdfengines/doc.go

@@ -0,0 +1,3 @@
+// Package pdfengines provides a module which gathers modules that implements
+// the gotenberg.PDFEngine interface.
+package pdfengines

pkg/modules/pdfengines/multi.go

@@ -0,0 +1,81 @@
+package pdfengines
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/multierr"
+	"go.uber.org/zap"
+)
+
+// multiPDFEngines implements the gotenberg.PDFEngine interface and gathers one
+// or more gotenberg.PDFEngine. It provides a sort of fallback mechanism: if an
+// engine's method returns an error, it calls the same method from another
+// engine.
+type multiPDFEngines struct {
+	engines []gotenberg.PDFEngine
+}
+
+// newMultiPDFEngines returns a multiPDFEngines. Arguments' order determines the
+// order of the engines called.
+func newMultiPDFEngines(engines ...gotenberg.PDFEngine) *multiPDFEngines {
+	return &multiPDFEngines{
+		engines: engines,
+	}
+}
+
+// Merge tries to merge the given PDFs into a unique PDF thanks to its
+// children. If the context is done, it stops and returns an error.
+func (multi multiPDFEngines) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error {
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.engines {
+		go func(engine gotenberg.PDFEngine) {
+			errChan <- engine.Merge(ctx, logger, inputPaths, outputPath)
+		}(engine)
+
+		select {
+		case mergeErr := <-errChan:
+			errored := multierr.AppendInto(&err, mergeErr)
+			if !errored {
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	return fmt.Errorf("merge PDFs with multi PDF engines: %w", err)
+}
+
+// Convert converts the given PDF to a specific PDF format. thanks to its
+// children. If the context is done, it stops and returns an error.
+func (multi multiPDFEngines) Convert(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error {
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.engines {
+		go func(engine gotenberg.PDFEngine) {
+			errChan <- engine.Convert(ctx, logger, format, inputPath, outputPath)
+		}(engine)
+
+		select {
+		case mergeErr := <-errChan:
+			errored := multierr.AppendInto(&err, mergeErr)
+			if !errored {
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	return fmt.Errorf("convert PDF to '%s' with multi PDF engines: %w", format, err)
+}
+
+// Interface guards.
+var (
+	_ gotenberg.PDFEngine = (*multiPDFEngines)(nil)
+)

pkg/modules/pdfengines/multi_test.go

@@ -0,0 +1,215 @@
+package pdfengines
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func TestNewMultiPDFEngines(t *testing.T) {
+	engine1 := &ProtoPDFEngine{
+		merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+			return nil
+		},
+		convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+			return nil
+		},
+	}
+
+	engine2 := &ProtoPDFEngine{
+		merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+			return errors.New("foo")
+		},
+		convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+			return errors.New("foo")
+		},
+	}
+
+	multi := newMultiPDFEngines(engine1, engine2)
+
+	if len(multi.engines) != 2 {
+		t.Fatalf("expected %d engines but got %d", 2, len(multi.engines))
+	}
+
+	if !reflect.DeepEqual(engine1, multi.engines[0]) {
+		t.Errorf("expected %v, but got: %v", engine1, multi.engines[0])
+	}
+
+	if !reflect.DeepEqual(engine2, multi.engines[1]) {
+		t.Errorf("expected %v, but got: %v", engine2, multi.engines[1])
+	}
+}
+
+func TestMultiPDFEngines_Merge(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       context.Context
+		engines   []gotenberg.PDFEngine
+		expectErr bool
+	}{
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+		},
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return errors.New("foo")
+						},
+					},
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+		},
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return errors.New("foo")
+						},
+					},
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return errors.New("bar")
+						},
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() context.Context {
+				ctx, cancel := context.WithCancel(context.TODO())
+				defer cancel()
+
+				return ctx
+			}(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+	} {
+		multi := newMultiPDFEngines(tc.engines...)
+		err := multi.Merge(tc.ctx, nil, nil, "")
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+	}
+}
+
+func TestMultiPDFEngines_Convert(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       context.Context
+		engines   []gotenberg.PDFEngine
+		expectErr bool
+	}{
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+		},
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return errors.New("foo")
+						},
+					},
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+		},
+		{
+			ctx: context.TODO(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return errors.New("foo")
+						},
+					},
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return errors.New("bar")
+						},
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() context.Context {
+				ctx, cancel := context.WithCancel(context.TODO())
+				defer cancel()
+
+				return ctx
+			}(),
+			engines: func() []gotenberg.PDFEngine {
+				return []gotenberg.PDFEngine{
+					ProtoPDFEngine{
+						convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+							return nil
+						},
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+	} {
+		multi := newMultiPDFEngines(tc.engines...)
+		err := multi.Convert(tc.ctx, nil, "", "", "")
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+	}
+}

pkg/modules/pdfengines/pdfengines.go

@@ -0,0 +1,160 @@
+package pdfengines
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	flag "github.com/spf13/pflag"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(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 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 {
+	names         []string
+	engines       []gotenberg.PDFEngine
+	disableRoutes bool
+}
+
+// Descriptor returns a PDFEngines' module descriptor.
+func (PDFEngines) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "pdfengines",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("pdfengines", flag.ExitOnError)
+			fs.StringSlice("pdfengines-engines", make([]string, 0), "Set the PDF engines - all by default")
+			fs.Bool("pdfengines-disable-routes", false, "Disable the routes")
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(PDFEngines) },
+	}
+}
+
+// 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 {
+	flags := ctx.ParsedFlags()
+	names := flags.MustStringSlice("pdfengines-engines")
+	mod.disableRoutes = flags.MustBool("pdfengines-disable-routes")
+
+	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))
+
+	for i, engine := range engines {
+		mod.engines[i] = engine.(gotenberg.PDFEngine)
+	}
+
+	if len(names) > 0 {
+		// Selection from user.
+		mod.names = names
+
+		return nil
+	}
+
+	// No selection from user, use all PDF engines available.
+	mod.names = make([]string, len(mod.engines))
+
+	for i, engine := range mod.engines {
+		mod.names[i] = engine.(gotenberg.Module).Descriptor().ID
+	}
+
+	return nil
+}
+
+// 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 {
+	if len(mod.engines) == 0 {
+		return errors.New("no PDF engine")
+	}
+
+	availableEngines := make([]string, len(mod.engines))
+
+	for i, engine := range mod.engines {
+		availableEngines[i] = engine.(gotenberg.Module).Descriptor().ID
+	}
+
+	nonExistingEngines := make([]string, 0)
+
+	for _, name := range mod.names {
+		engineExists := false
+
+		for _, engine := range mod.engines {
+			if name == engine.(gotenberg.Module).Descriptor().ID {
+				engineExists = true
+				break
+			}
+		}
+
+		if !engineExists {
+			nonExistingEngines = append(nonExistingEngines, name)
+		}
+	}
+
+	if len(nonExistingEngines) == 0 {
+		return nil
+	}
+
+	return fmt.Errorf("non-existing PDF engine(s): %s - available PDF engine(s): %s", nonExistingEngines, availableEngines)
+}
+
+// PDFEngine returns a gotenberg.PDFEngine.
+func (mod PDFEngines) PDFEngine() (gotenberg.PDFEngine, error) {
+	engines := make([]gotenberg.PDFEngine, len(mod.engines))
+
+	i := 0
+	for _, engine := range mod.engines {
+		engines[i] = engine
+		i++
+	}
+
+	return newMultiPDFEngines(engines...), nil
+}
+
+// Routes returns the API routes.
+func (mod PDFEngines) Routes() ([]api.MultipartFormDataRoute, error) {
+	if mod.disableRoutes {
+		return nil, nil
+	}
+
+	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 []api.MultipartFormDataRoute{
+		mergeRoute(engine),
+		convertRoute(engine),
+	}, nil
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module            = (*PDFEngines)(nil)
+	_ gotenberg.Provisioner       = (*PDFEngines)(nil)
+	_ gotenberg.Validator         = (*PDFEngines)(nil)
+	_ gotenberg.PDFEngineProvider = (*PDFEngines)(nil)
+	_ api.MultipartFormDataRouter = (*PDFEngines)(nil)
+)

pkg/modules/pdfengines/pdfengines_test.go

@@ -0,0 +1,304 @@
+package pdfengines
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+type ProtoModule struct {
+	descriptor func() gotenberg.ModuleDescriptor
+}
+
+func (mod ProtoModule) Descriptor() gotenberg.ModuleDescriptor {
+	return mod.descriptor()
+}
+
+type ProtoValidator struct {
+	ProtoModule
+	validate func() error
+}
+
+func (mod ProtoValidator) Validate() error {
+	return mod.validate()
+}
+
+type ProtoPDFEngine struct {
+	ProtoValidator
+	merge   func(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error
+	convert func(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error
+}
+
+func (mod ProtoPDFEngine) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error {
+	return mod.merge(ctx, logger, inputPaths, outputPath)
+}
+
+func (mod ProtoPDFEngine) Convert(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error {
+	return mod.convert(ctx, logger, format, inputPath, outputPath)
+}
+
+func TestPDFEngine_Descriptor(t *testing.T) {
+	descriptor := PDFEngines{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(PDFEngines))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestPDFEngine_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                *gotenberg.Context
+		expectNames        []string
+		expectEnginesCount int
+		expectErr          bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				engine := struct{ ProtoPDFEngine }{}
+				engine.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return engine }}
+				}
+				engine.validate = func() error { return errors.New("foo") }
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(PDFEngines).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						engine.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				engine := struct{ ProtoPDFEngine }{}
+				engine.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return engine }}
+				}
+				engine.validate = func() error { return nil }
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(PDFEngines).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						engine.Descriptor(),
+					},
+				)
+			}(),
+			expectNames:        []string{"foo"},
+			expectEnginesCount: 1,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				engine1 := struct{ ProtoPDFEngine }{}
+				engine1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "a", New: func() gotenberg.Module { return engine1 }}
+				}
+				engine1.validate = func() error { return nil }
+
+				engine2 := struct{ ProtoPDFEngine }{}
+				engine2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "b", New: func() gotenberg.Module { return engine2 }}
+				}
+				engine2.validate = func() error { return nil }
+
+				fs := new(PDFEngines).Descriptor().FlagSet
+				err := fs.Parse([]string{"--pdfengines-engines=b", "--pdfengines-engines=a"})
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					[]gotenberg.ModuleDescriptor{
+						engine1.Descriptor(),
+						engine2.Descriptor(),
+					},
+				)
+			}(),
+			expectNames:        []string{"b", "a"},
+			expectEnginesCount: 2,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				engine1 := struct{ ProtoPDFEngine }{}
+				engine1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "a", New: func() gotenberg.Module { return engine1 }}
+				}
+				engine1.validate = func() error { return nil }
+
+				engine2 := struct{ ProtoPDFEngine }{}
+				engine2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "b", New: func() gotenberg.Module { return engine2 }}
+				}
+				engine2.validate = func() error { return nil }
+
+				fs := new(PDFEngines).Descriptor().FlagSet
+				err := fs.Parse([]string{"--pdfengines-engines=b"})
+
+				if err != nil {
+					t.Fatalf("expected error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					[]gotenberg.ModuleDescriptor{
+						engine1.Descriptor(),
+						engine2.Descriptor(),
+					},
+				)
+			}(),
+			expectNames:        []string{"b"},
+			expectEnginesCount: 2,
+		},
+	} {
+		mod := new(PDFEngines)
+		err := mod.Provision(tc.ctx)
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+
+		if len(tc.expectNames) != len(mod.names) {
+			t.Errorf("test %d: expected %d names but got %d", i, len(tc.expectNames), len(mod.names))
+		}
+
+		if tc.expectEnginesCount != len(mod.engines) {
+			t.Errorf("test %d: expected %d engines but got %d", i, tc.expectEnginesCount, len(mod.engines))
+		}
+
+		for index, name := range mod.names {
+			if name != tc.expectNames[index] {
+				t.Errorf("test %d: expected name at index %d to be %s, but got: %s", i, index, name, tc.expectNames[index])
+			}
+		}
+	}
+}
+
+func TestPDFEngine_Validate(t *testing.T) {
+	for i, tc := range []struct {
+		names     []string
+		engines   []gotenberg.PDFEngine
+		expectErr bool
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			names: []string{"foo"},
+			engines: func() []gotenberg.PDFEngine {
+				engine := struct{ ProtoPDFEngine }{}
+				engine.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return engine }}
+				}
+
+				return []gotenberg.PDFEngine{
+					engine,
+				}
+			}(),
+		},
+		{
+			names: []string{"foo", "bar", "baz"},
+			engines: func() []gotenberg.PDFEngine {
+				engine1 := struct{ ProtoPDFEngine }{}
+				engine1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return engine1 }}
+				}
+
+				engine2 := struct{ ProtoPDFEngine }{}
+				engine2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "baz", New: func() gotenberg.Module { return engine2 }}
+				}
+
+				return []gotenberg.PDFEngine{
+					engine1,
+					engine2,
+				}
+			}(),
+			expectErr: true,
+		},
+	} {
+		mod := new(PDFEngines)
+		mod.names = tc.names
+		mod.engines = tc.engines
+		err := mod.Validate()
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+	}
+}
+
+func TestPDFEngine_PDFEngine(t *testing.T) {
+	mod := new(PDFEngines)
+	mod.engines = []gotenberg.PDFEngine{
+		struct{ ProtoPDFEngine }{},
+	}
+
+	_, err := mod.PDFEngine()
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestPDFEngine_Routes(t *testing.T) {
+	for i, tc := range []struct {
+		expectRoutes  int
+		disableRoutes bool
+	}{
+		{
+			expectRoutes: 2,
+		},
+		{
+			disableRoutes: true,
+		},
+	} {
+		mod := new(PDFEngines)
+		mod.engines = []gotenberg.PDFEngine{
+			struct{ ProtoPDFEngine }{},
+		}
+		mod.disableRoutes = tc.disableRoutes
+
+		routes, err := mod.Routes()
+		if err != nil {
+			t.Fatalf("test %d: expected no error but got: %v", i, err)
+		}
+
+		if tc.expectRoutes != len(routes) {
+			t.Errorf("test %d: expected %d routes but got %d", i, tc.expectRoutes, len(routes))
+		}
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module    = (*ProtoModule)(nil)
+	_ gotenberg.Validator = (*ProtoValidator)(nil)
+	_ gotenberg.Module    = (*ProtoValidator)(nil)
+	_ gotenberg.PDFEngine = (*ProtoPDFEngine)(nil)
+	_ gotenberg.Module    = (*ProtoPDFEngine)(nil)
+	_ gotenberg.Validator = (*ProtoPDFEngine)(nil)
+)

pkg/modules/pdfengines/routes.go

@@ -0,0 +1,138 @@
+package pdfengines
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+)
+
+// mergeRoute returns an api.MultipartFormDataRoute which can merge PDFs.
+func mergeRoute(engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/pdfengines/merge",
+		Handler: func(ctx *api.Context) error {
+			// Let's get the data from the form and validate them.
+			var (
+				inputPaths []string
+				PDFformat  string
+			)
+
+			err := ctx.FormData().
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				String("pdfFormat", &PDFformat, "").
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			// Alright, let's merge the PDFs.
+
+			outputPath := ctx.GeneratePath(".pdf")
+
+			err = engine.Merge(ctx, ctx.Log(), inputPaths, outputPath)
+			if err != nil {
+				return fmt.Errorf("merge PDFs: %w", err)
+			}
+
+			// So far so good, the PDFs are merged into one unique PDF.
+			// Now, let's check if the client want to convert this result PDF
+			// to a specific PDF format.
+
+			if PDFformat != "" {
+				convertInputPath := outputPath
+				convertOutputPath := ctx.GeneratePath(".pdf")
+
+				err = engine.Convert(ctx, ctx.Log(), PDFformat, convertInputPath, convertOutputPath)
+
+				if err != nil {
+					if errors.Is(err, gotenberg.ErrPDFFormatNotAvailable) {
+						return api.WrapError(
+							fmt.Errorf("convert PDF: %w", err),
+							api.NewSentinelHTTPError(
+								http.StatusBadRequest,
+								fmt.Sprintf("At least one PDF engine does not handle the PDF format '%s' (pdfFormat), while other have failed to convert for other reasons", PDFformat),
+							),
+						)
+					}
+
+					return fmt.Errorf("convert PDF: %w", err)
+				}
+
+				// Important: the output path is now the converted file.
+				outputPath = convertOutputPath
+			}
+
+			// Last but not least, add the output path to the context so that
+			// the API is able to send it as a response to the client.
+
+			err = ctx.AddOutputPaths(outputPath)
+			if err != nil {
+				return fmt.Errorf("add output path: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// convertRoute returns an api.MultipartFormDataRoute which can convert a PDF
+// to a specific PDF format.
+func convertRoute(engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/pdfengines/convert",
+		Handler: func(ctx *api.Context) error {
+			// Let's get the data from the form and validate them.
+			var (
+				inputPaths []string
+				PDFformat  string
+			)
+
+			err := ctx.FormData().
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				MandatoryString("pdfFormat", &PDFformat).
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			// Alright, let's merge the PDFs.
+
+			outputPaths := make([]string, len(inputPaths))
+
+			for i, inputPath := range inputPaths {
+				outputPaths[i] = ctx.GeneratePath(".pdf")
+
+				err = engine.Convert(ctx, ctx.Log(), PDFformat, inputPath, outputPaths[i])
+
+				if err != nil {
+					if errors.Is(err, gotenberg.ErrPDFFormatNotAvailable) {
+						return api.WrapError(
+							fmt.Errorf("convert PDF: %w", err),
+							api.NewSentinelHTTPError(
+								http.StatusBadRequest,
+								fmt.Sprintf("At least one PDF engine does not handle the PDF format '%s' (pdfFormat), while other have failed to convert for other reasons", PDFformat),
+							),
+						)
+					}
+
+					return fmt.Errorf("convert PDF: %w", err)
+				}
+			}
+
+			// Last but not least, add the output paths to the context so that
+			// the API is able to send them as a response to the client.
+
+			err = ctx.AddOutputPaths(outputPaths...)
+			if err != nil {
+				return fmt.Errorf("add output paths: %w", err)
+			}
+
+			return nil
+		},
+	}
+}

pkg/modules/pdfengines/routes_test.go

@@ -0,0 +1,392 @@
+package pdfengines
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"go.uber.org/zap"
+)
+
+func TestMergeHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		engine                 gotenberg.PDFEngine
+		expectErr              bool
+		expectHTTPErr          bool
+		expectHTTPStatus       int
+		expectOutputPathsCount int
+	}{
+		{
+			ctx:              &api.MockContext{Context: &api.Context{}},
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return errors.New("foo")
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return nil
+					},
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return gotenberg.ErrPDFFormatNotAvailable
+					},
+				}
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return nil
+					},
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return errors.New("foo")
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetCancelled(true)
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return nil
+					},
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectOutputPathsCount: 1,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					merge: func(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectOutputPathsCount: 1,
+		},
+	} {
+		err := mergeRoute(tc.engine).Handler(tc.ctx.Context)
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+
+		var httpErr api.HTTPError
+		isHTTPErr := errors.As(err, &httpErr)
+
+		if tc.expectHTTPErr && !isHTTPErr {
+			t.Errorf("test %d: expected HTTP error but got: %v", i, err)
+		}
+
+		if !tc.expectHTTPErr && isHTTPErr {
+			t.Errorf("test %d: expected no HTTP error but got one: %v", i, httpErr)
+		}
+
+		if err != nil && tc.expectHTTPErr && isHTTPErr {
+			status, _ := httpErr.HTTPError()
+			if status != tc.expectHTTPStatus {
+				t.Errorf("test %d: expected %d HTTP status code but got %d", i, tc.expectHTTPStatus, status)
+			}
+		}
+
+		if tc.expectOutputPathsCount != len(tc.ctx.OutputPaths()) {
+			t.Errorf("test %d: expected %d output paths but got %d", i, tc.expectOutputPathsCount, len(tc.ctx.OutputPaths()))
+		}
+	}
+}
+
+func TestConvertHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		engine                 gotenberg.PDFEngine
+		expectErr              bool
+		expectHTTPErr          bool
+		expectHTTPStatus       int
+		expectOutputPathsCount int
+	}{
+		{
+			ctx:              &api.MockContext{Context: &api.Context{}},
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return gotenberg.ErrPDFFormatNotAvailable
+					},
+				}
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return errors.New("foo")
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetCancelled(true)
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectOutputPathsCount: 1,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.pdf": "/foo/foo.pdf",
+					"bar.pdf": "/foo/bar.pdf",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			expectOutputPathsCount: 2,
+		},
+	} {
+		err := convertRoute(tc.engine).Handler(tc.ctx.Context)
+
+		if tc.expectErr && err == nil {
+			t.Errorf("test %d: expected error but got: %v", i, err)
+		}
+
+		if !tc.expectErr && err != nil {
+			t.Errorf("test %d: expected no error but got: %v", i, err)
+		}
+
+		var httpErr api.HTTPError
+		isHTTPErr := errors.As(err, &httpErr)
+
+		if tc.expectHTTPErr && !isHTTPErr {
+			t.Errorf("test %d: expected HTTP error but got: %v", i, err)
+		}
+
+		if !tc.expectHTTPErr && isHTTPErr {
+			t.Errorf("test %d: expected no HTTP error but got one: %v", i, httpErr)
+		}
+
+		if err != nil && tc.expectHTTPErr && isHTTPErr {
+			status, _ := httpErr.HTTPError()
+			if status != tc.expectHTTPStatus {
+				t.Errorf("test %d: expected %d HTTP status code but got %d", i, tc.expectHTTPStatus, status)
+			}
+		}
+
+		if tc.expectOutputPathsCount != len(tc.ctx.OutputPaths()) {
+			t.Errorf("test %d: expected %d output paths but got %d", i, tc.expectOutputPathsCount, len(tc.ctx.OutputPaths()))
+		}
+	}
+}