feat: add 7.x source code

.dockerignore

@@ -0,0 +1 @@
+.git

.github/workflows/continuous_delivery.yml

@@ -0,0 +1,27 @@
+name: Continuous Delivery
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+
+  release:
+    name: Release Docker image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      - name: Checkout source code
+        uses: actions/checkout@v2
+      - name: Log in to Docker Hub Container Registry
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Build and push Docker image
+        run: |
+          make release GOTENBERG_VERSION=${{ github.event.release.tag_name }}
+          make release GOTENBERG_VERSION=${{ github.event.release.tag_name }} DOCKER_REGISTRY=thecodingmachine

.github/workflows/continuous_integration.yml

@@ -0,0 +1,43 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v2
+      - name: Run linters
+        uses: golangci/golangci-lint-action@v2
+        with:
+          version: v1.39
+
+  tests:
+    needs:
+      - Lint
+    name: Tests
+    # TODO: once arm64 actions are available, also run the tests on this architecture.
+    # See: https://github.com/actions/virtual-environments/issues/2552#issuecomment-771478000.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      - name: Checkout source code
+        uses: actions/checkout@v2
+      - name: Build testing environment
+        run: make build build-tests
+      - name: Run tests
+        run: |
+          make tests-once
+          bash <(curl -s https://codecov.io/bash)

.gitignore

@@ -0,0 +1,2 @@
+/coverage.html
+/coverage.txt

.golangci.yml

@@ -0,0 +1,30 @@
+linters:
+  disable-all: true
+  enable:
+    - bodyclose
+    - deadcode
+    - errcheck
+    - gofmt
+    - goimports
+    - gosec
+    - gosimple
+    - govet
+    - ineffassign
+    - misspell
+    - prealloc
+    - staticcheck
+    - structcheck
+    - typecheck
+    - unconvert
+    - unused
+    - varcheck
+
+run:
+  deadline: 5m
+  issues-exit-code: 1
+  tests: false
+
+output:
+  format: 'colored-line-number'
+  print-issued-lines: true
+  print-linter-name: true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Julien Neuhart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,133 @@
+.PHONY: help
+help: ## Show the help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: it
+it: build build-tests ## Initialize the development environment
+
+GOLANG_VERSION=1.16
+DOCKER_REGISTRY=gotenberg
+GOTENBERG_VERSION=snapshot
+GOTENBERG_USER_GID=1001
+GOTENBERG_USER_UID=1001
+PDFTK_VERSION=1353200058 # See https://gitlab.com/pdftk-java/pdftk/-/releases - Binary package.
+GOLANGCI_LINT_VERSION=v1.39.0 # See https://github.com/golangci/golangci-lint/releases.
+
+.PHONY: build
+build: ## Build the Gotenberg's Docker image
+	docker build \
+	--build-arg GOLANG_VERSION=$(GOLANG_VERSION) \
+	--build-arg GOTENBERG_VERSION=$(GOTENBERG_VERSION) \
+	--build-arg GOTENBERG_USER_GID=$(GOTENBERG_USER_GID) \
+	--build-arg GOTENBERG_USER_UID=$(GOTENBERG_USER_UID) \
+	--build-arg PDFTK_VERSION=$(PDFTK_VERSION) \
+	-t $(DOCKER_REGISTRY)/gotenberg:$(GOTENBERG_VERSION) \
+	-f build/Dockerfile .
+
+GOTENBERG_GRACEFUL_SHUTDOWN_DURATION=30s
+API_PORT=3000
+API_PORT_FROM_ENV=
+API_READ_TIMEOUT=30s
+API_PROCESS_TIMEOUT=30s
+API_WRITE_TIMEOUT=30s
+API_ROOT_PATH=/
+API_TRACE_HEADER=Gotenberg-Trace
+API_DISABLE_HEALTH_CHECK_LOGGING=false
+API_WEBHOOK_ALLOW_LIST=
+API_WEBHOOK_DENY_LIST=
+API_WEBHOOK_ERROR_ALLOW_LIST=
+API_WEBHOOK_ERROR_DENY_LIST=
+API_WEBHOOK_MAX_RETRY=4
+API_WEBHOOK_RETRY_MIN_WAIT=1s
+API_WEBHOOK_RETRY_MAX_WAIT=30s
+API_DISABLE_WEBHOOK=false
+CHROMIUM_USER_AGENT=
+CHROMIUM_INCOGNITO=false
+CHROMIUM_IGNORE_CERTIFICATE_ERRORS=false
+CHROMIUM_ALLOW_LIST=
+CHROMIUM_DENY_LIST=
+CHROMIUM_DISABLE_ROUTES=false
+LIBREOFFICE_DISABLES_ROUTES=false
+LOG_LEVEL=info
+LOG_FORMAT=auto
+PDFENGINES_ENGINES=
+PDFENGINES_DISABLE_ROUTES=false
+
+.PHONY: run
+run: ## Start a Gotenberg container
+	docker run --rm -it \
+	-p $(API_PORT):$(API_PORT) \
+	$(DOCKER_REGISTRY)/gotenberg:$(GOTENBERG_VERSION) \
+	gotenberg \
+	--gotenberg-graceful-shutdown-duration=$(GOTENBERG_GRACEFUL_SHUTDOWN_DURATION) \
+	--api-port=$(API_PORT) \
+	--api-port-from-env=$(API_PORT_FROM_ENV) \
+	--api-read-timeout=$(API_READ_TIMEOUT) \
+	--api-process-timeout=$(API_PROCESS_TIMEOUT) \
+	--api-write-timeout=$(API_WRITE_TIMEOUT) \
+	--api-root-path=$(API_ROOT_PATH) \
+	--api-trace-header=$(API_TRACE_HEADER) \
+	--api-disable-health-check-logging=$(API_DISABLE_HEALTH_CHECK_LOGGING) \
+	--api-webhook-allow-list=$(API_WEBHOOK_ALLOW_LIST) \
+	--api-webhook-deny-list=$(API_WEBHOOK_DENY_LIST) \
+	--api-webhook-error-allow-list=$(API_WEBHOOK_ERROR_ALLOW_LIST) \
+	--api-webhook-error-deny-list=$(API_WEBHOOK_ERROR_DENY_LIST) \
+	--api-webhook-max-retry=$(API_WEBHOOK_MAX_RETRY) \
+	--api-webhook-retry-min-wait=$(API_WEBHOOK_RETRY_MIN_WAIT) \
+	--api-webhook-retry-max-wait=$(API_WEBHOOK_RETRY_MAX_WAIT) \
+	--api-disable-webhook=$(API_DISABLE_WEBHOOK) \
+	--chromium-user-agent=$(CHROMIUM_USER_AGENT) \
+	--chromium-incognito=$(CHROMIUM_INCOGNITO) \
+	--chromium-ignore-certificate-errors=$(CHROMIUM_IGNORE_CERTIFICATE_ERRORS) \
+	--chromium-allow-list=$(CHROMIUM_ALLOW_LIST) \
+	--chromium-deny-list=$(CHROMIUM_DENY_LIST) \
+	--chromium-disable-routes=$(CHROMIUM_DISABLE_ROUTES) \
+	--libreoffice-disable-routes=$(LIBREOFFICE_DISABLES_ROUTES) \
+	--log-level=$(LOG_LEVEL) \
+	--log-format=$(LOG_FORMAT) \
+	--pdfengines-engines=$(PDFENGINES_ENGINES) \
+	--pdfengines-disable-routes=$(PDFENGINES_DISABLE_ROUTES)
+
+.PHONY: build-tests
+build-tests: ## Build the tests' Docker image
+	docker build \
+	--build-arg GOLANG_VERSION=$(GOLANG_VERSION) \
+	--build-arg DOCKER_REGISTRY=$(DOCKER_REGISTRY) \
+	--build-arg GOTENBERG_VERSION=$(GOTENBERG_VERSION) \
+	--build-arg GOLANGCI_LINT_VERSION=$(GOLANGCI_LINT_VERSION) \
+	-t $(DOCKER_REGISTRY)/gotenberg:$(GOTENBERG_VERSION)-tests \
+	-f test/Dockerfile .
+
+.PHONY: tests
+tests: ## Start the testing environment
+	docker run --rm -it \
+	-v $(PWD):/tests \
+	$(DOCKER_REGISTRY)/gotenberg:$(GOTENBERG_VERSION)-tests \
+	bash
+
+.PHONY: tests-once
+tests-once: ## Run the tests once (prefer the "tests" command while developing)
+	docker run --rm  \
+	-v $(PWD):/tests \
+	$(DOCKER_REGISTRY)/gotenberg:$(GOTENBERG_VERSION)-tests \
+	gotest
+
+.PHONY: fmt
+fmt: ## Format the code and "optimize" the dependencies
+	go fmt ./...
+	go mod tidy
+
+.PHONY: godoc
+godoc: ## Run a webserver with Gotenberg godoc (go get golang.org/x/tools/cmd/godoc)
+	$(info http://localhost:6060/pkg/github.com/gotenberg/gotenberg/v7)
+	godoc -http=:6060
+
+.PHONY: release
+release: ## Build the Gotenberg's Docker image for linux/amd64 and linux/arm64 platforms, then push it to a Docker Registry
+	./scripts/release.sh \
+ 	$(GOLANG_VERSION) \
+	$(GOTENBERG_VERSION) \
+	$(GOTENBERG_USER_GID) \
+	$(GOTENBERG_USER_UID) \
+	$(PDFTK_VERSION) \
+	$(DOCKER_REGISTRY)

README.md

@@ -0,0 +1,46 @@
+<p align="center">
+    <img src="https://user-images.githubusercontent.com/8983173/130322857-185831e2-f041-46eb-a17f-0a69d066c4e5.png" alt="Gotenberg Logo" width="150" height="150" />
+<h3 align="center">Gotenberg</h3>
+<p align="center">A Docker-powered stateless API for PDF files</p>
+<p align="center"><a href="https://gotenberg.dev/docs/about">Documentation</a><!-- &#183; <a href="#">OpenAPI</a></p>-->
+</p>
+
+---
+
+Gotenberg provides a developer-friendly API to interact with powerful tools like Chromium and LibreOffice to convert many
+documents to PDF, transform them, merge them, and more!
+
+## Quick Start
+
+Open a terminal and run the following command:
+
+```
+docker run --rm -p 3000:3000 gotenberg/gotenberg:7
+```
+
+Alternatively, using the historic Docker registry from our sponsor [TheCodingMachine](https://www.thecodingmachine.com):
+
+```
+docker run --rm -p 3000:3000 thecodingmachine/gotenberg:7
+```
+
+The API is now available on your host at http://localhost:3000.
+
+Head to the [documentation](https://gotenberg.dev/docs/about) to learn how to interact with it 🚀
+
+## Sponsors
+
+<p align="center">
+    <a href="https://thecodingmachine.com">
+        <img src="https://user-images.githubusercontent.com/8983173/130324668-9d6e7b35-53a3-49c7-a574-38190d2bd6b0.png" alt="TheCodingMachine Logo" width="429" height="210" />
+    </a>
+</p>
+
+## Badges
+
+[![Docker pulls](https://img.shields.io/docker/pulls/gotenberg/gotenberg)](https://hub.docker.com/r/gotenberg/gotenberg)
+[![Docker pulls](https://img.shields.io/docker/pulls/thecodingmachine/gotenberg)](https://hub.docker.com/r/thecodingmachine/gotenberg)
+[![Continuous Integration](https://github.com/gotenberg/gotenberg/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/gotenberg/gotenberg/actions/workflows/continuous_integration.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/gotenberg/gotenberg.svg)](https://pkg.go.dev/github.com/gotenberg/gotenberg/v7)
+[![Codecov](https://codecov.io/gh/gotenberg/gotenberg/branch/main/graph/badge.svg)](https://codecov.io/gh/gotenberg/gotenberg)
+[![Go Report Card](https://goreportcard.com/badge/github.com/gotenberg/gotenberg)](https://goreportcard.com/report/gotenberg/gotenberg)

build/Dockerfile

@@ -0,0 +1,145 @@
+# Note: ARG instructions do not create additional layers.
+# Instead, next layers will concatenate them.
+ARG GOLANG_VERSION
+ARG GOTENBERG_VERSION
+
+FROM golang:$GOLANG_VERSION AS builder
+
+ENV CGO_ENABLED 0
+
+# Define the working directory outside of $GOPATH (we're using go modules).
+WORKDIR /home
+
+# Install module dependencies.
+COPY go.mod go.sum ./
+
+RUN go mod download &&\
+    go mod verify
+
+# Copy the source code.
+COPY cmd ./cmd
+COPY internal ./internal
+COPY pkg ./pkg
+
+# Build the binary.
+RUN go build -o gotenberg -ldflags "-X gotenberg.version=$GOTENBERG_VERSION" cmd/gotenberg/main.go
+
+FROM debian:buster-slim
+
+LABEL author="Julien Neuhart" \
+      description="A Docker-powered stateless API for PDF files." \
+      github="https://github.com/gotenberg/gotenberg" \
+      version="$GOTENBER_VERSION" \
+      website="https://gotenberg.dev"
+
+# Improve fonts subpixel hinting and smoothing.
+# Credits:
+# https://github.com/arachnys/athenapdf/issues/69.
+# https://github.com/arachnys/athenapdf/commit/ba25a8d80a25d08d58865519c4cd8756dc9a336d.
+COPY build/fonts.conf /etc/fonts/conf.d/100-gotenberg.conf
+
+# Simple wrapper around Java and PDFtk.
+COPY build/pdftk.sh /usr/bin/pdftk
+
+# Setup the Docker image.
+ARG GOTENBERG_USER_GID
+ARG GOTENBERG_USER_UID
+ARG PDFTK_VERSION
+
+RUN \
+    # Create a non-root user.
+    # All processes in the Docker container will run with this dedicated user.
+    groupadd --gid "$GOTENBERG_USER_GID" gotenberg &&\
+    useradd --uid "$GOTENBERG_USER_UID" --gid gotenberg --shell /bin/bash --home /home/gotenberg --no-create-home gotenberg &&\
+    mkdir /home/gotenberg &&\
+    chown gotenberg: /home/gotenberg &&\
+    # Install dependencies required for the next instructions or debugging.
+    # Note: procps for "top" command (useful when debugging processes).
+    # Note: tini is a helper for reaping zombie processes.
+    apt-get update -qq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends curl gnupg procps tini &&\
+    # Install fonts.
+    # Credits:
+    # https://github.com/arachnys/athenapdf/blob/master/cli/Dockerfile.
+    # https://help.accusoft.com/PrizmDoc/v12.1/HTML/Installing_Asian_Fonts_on_Ubuntu_and_Debian.html.
+    curl -o ./ttf-mscorefonts-installer_3.8_all.deb http://httpredir.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
+    ./ttf-mscorefonts-installer_3.8_all.deb \
+    culmus \
+    fonts-beng \
+    fonts-hosny-amiri \
+    fonts-lklug-sinhala \
+    fonts-lohit-guru \
+    fonts-lohit-knda \
+    fonts-samyak-gujr \
+    fonts-samyak-mlym \
+    fonts-samyak-taml \
+    fonts-sarai \
+    fonts-sil-abyssinica \
+    fonts-sil-padauk \
+    fonts-telu \
+    fonts-thai-tlwg \
+    ttf-wqy-zenhei \
+    fonts-arphic-uming \
+    fonts-ipafont-mincho \
+    fonts-ipafont-gothic \
+    fonts-unfonts-core \
+    # LibreOffice recommends.
+    fonts-crosextra-caladea \
+    fonts-crosextra-carlito \
+    fonts-dejavu \
+    fonts-dejavu-extra \
+    fonts-liberation \
+    fonts-liberation2 \
+    fonts-linuxlibertine \
+    fonts-noto-core \
+    fonts-noto-mono \
+    fonts-noto-ui-core \
+    fonts-sil-gentium \
+    fonts-sil-gentium-basic &&\
+    rm -f ./ttf-mscorefonts-installer_3.8_all.deb &&\
+    echo "deb https://httpredir.debian.org/debian/ buster-backports main contrib non-free" >> /etc/apt/sources.list &&\
+    apt-get update -qq &&\
+    # Install Chromium and LibreOffice.
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends chromium &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t buster-backports libreoffice &&\
+    # Download unoconv (Python script).
+    curl -Ls https://raw.githubusercontent.com/dagwieers/unoconv/master/unoconv -o /usr/bin/unoconv &&\
+    chmod +x /usr/bin/unoconv &&\
+    # unoconv will look for the Python binary, which has to be at version 3.
+    ln -s /usr/bin/python3 /usr/bin/python &&\
+    # Download PDFtk.
+    # Credits: https://github.com/thecodingmachine/gotenberg/pull/273.
+    curl -o /usr/bin/pdftk-all.jar "https://gitlab.com/pdftk-java/pdftk/-/jobs/$PDFTK_VERSION/artifacts/raw/build/libs/pdftk-all.jar" &&\
+    chmod a+x /usr/bin/pdftk-all.jar &&\
+    # See https://github.com/nextcloud/docker/issues/380.
+    mkdir -p /usr/share/man/man1mkdir -p /usr/share/man/man1 &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends default-jre-headless &&\
+    # Cleanup.
+    # Note: the Debian image does automatically a clean after each install thanks to a hook.
+    # Therefore, there is no need for apt-get clean.
+    # See https://stackoverflow.com/a/24417119/3248473.
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* &&\
+    # Print versions of main dependencies.
+    chromium --version &&\
+    libreoffice --version &&\
+    unoconv --version &&\
+    pdftk --version
+
+# Copy the Gotenberg binary from the builder stage.
+COPY --from=builder /home/gotenberg /usr/bin/
+
+# Environment variables required by modules or else.
+ENV GC_EXCLUDE_SUBSTR "hsperfdata_root,hsperfdata_gotenberg"
+ENV CHROMIUM_BIN_PATH /usr/bin/chromium
+ENV UNOCONV_BIN_PATH /usr/bin/unoconv
+ENV PDFTK_BIN_PATH /usr/bin/pdftk
+
+USER gotenberg
+WORKDIR /home/gotenberg
+
+# Default API port.
+EXPOSE 3000
+
+ENTRYPOINT [ "/usr/bin/tini", "--" ]
+CMD [ "gotenberg" ]

build/Dockerfile.cloudrun

@@ -0,0 +1,15 @@
+# Note: ARG instructions do not create additional layers.
+# Instead, next layers will concatenate them.
+ARG DOCKER_REGISTRY
+ARG GOTENBERG_VERSION
+
+FROM $DOCKER_REGISTRY/gotenberg:$GOTENBERG_VERSION
+
+USER root
+
+# For security reasons, the non-root user gotenberg does not own the Tini binary by default.
+# However, some providers like Cloud Run from Google Cloud cannot start a Docker container in that case.
+# See https://github.com/thecodingmachine/gotenberg/issues/90#issuecomment-543551353.
+RUN chown gotenberg: /usr/bin/tini
+
+USER gotenberg

build/fonts.conf

@@ -0,0 +1,29 @@
+<?xml version='1.0'?>
+<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
+<fontconfig>
+ <match target="font">
+  <edit mode="assign" name="rgba">
+   <const>rgb</const>
+  </edit>
+ </match>
+ <match target="font">
+  <edit mode="assign" name="hinting">
+   <bool>true</bool>
+  </edit>
+ </match>
+ <match target="font">
+  <edit mode="assign" name="hintstyle">
+   <const>hintslight</const>
+  </edit>
+ </match>
+ <match target="font">
+  <edit mode="assign" name="antialias">
+   <bool>true</bool>
+  </edit>
+ </match>
+  <match target="font">
+    <edit mode="assign" name="lcdfilter">
+      <const>lcddefault</const>
+    </edit>
+  </match>
+</fontconfig>

build/pdftk.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+exec java -jar /usr/bin/pdftk-all.jar "$@"

cmd/gotenberg/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	gotenbergapp "github.com/gotenberg/gotenberg/v7/internal/app/gotenberg"
+
+	// Gotenberg modules.
+	_ "github.com/gotenberg/gotenberg/v7/pkg/standard"
+	// PDF engines.
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/pdfengine"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/pdfcpu"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/pdftk"
+)
+
+func main() {
+	gotenbergapp.Run()
+}

go.mod

@@ -0,0 +1,38 @@
+module github.com/gotenberg/gotenberg/v7
+
+go 1.16
+
+require (
+	github.com/alexliesenfeld/health v0.6.0
+	github.com/andybalholm/brotli v1.0.3 // indirect
+	github.com/chromedp/cdproto v0.0.0-20210808225517-c36c1bd4c35e
+	github.com/chromedp/chromedp v0.7.4
+	github.com/golang/snappy v0.0.4 // indirect
+	github.com/google/uuid v1.3.0
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-retryablehttp v0.7.0
+	github.com/klauspost/compress v1.13.4 // indirect
+	github.com/klauspost/pgzip v1.2.5 // indirect
+	github.com/labstack/echo/v4 v4.5.0
+	github.com/labstack/gommon v0.3.0
+	github.com/mattn/go-isatty v0.0.13 // indirect
+	github.com/mholt/archiver/v3 v3.5.0
+	github.com/microcosm-cc/bluemonday v1.0.15
+	github.com/nwaples/rardecode v1.1.2 // indirect
+	github.com/pdfcpu/pdfcpu v0.3.12
+	github.com/pierrec/lz4/v4 v4.1.8 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0
+	github.com/spf13/pflag v1.0.5
+	github.com/ulikunitz/xz v0.5.10 // indirect
+	go.uber.org/atomic v1.9.0 // indirect
+	go.uber.org/multierr v1.7.0
+	go.uber.org/zap v1.19.0
+	golang.org/x/crypto v0.0.0-20210817164053-32db794688a5 // indirect
+	golang.org/x/image v0.0.0-20210628002857-a66eb6448b8d // indirect
+	golang.org/x/net v0.0.0-20210813160813-60bc85c4be6d // indirect
+	golang.org/x/sync v0.0.0-20210220032951-036812b2e83c
+	golang.org/x/sys v0.0.0-20210820121016-41cdb8703e55 // indirect
+	golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b
+	golang.org/x/text v0.3.7
+	golang.org/x/tools v0.1.5 // indirect
+)

internal/app/gotenberg/gotenberg.go

@@ -0,0 +1,116 @@
+package gotenberg
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"time"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	flag "github.com/spf13/pflag"
+)
+
+// See https://patorjk.com/software/taag/#p=display&f=Small%20Slant&t=Gotenberg.
+// Credits: https://github.com/labstack/echo/blob/v4.3.0/echo.go#L240.
+const banner = `
+  _____     __           __               
+ / ___/__  / /____ ___  / /  ___ _______ _
+/ (_ / _ \/ __/ -_) _ \/ _ \/ -_) __/ _ '/
+\___/\___/\__/\__/_//_/_.__/\__/_/  \_, / 
+                                   /___/
+
+A Docker-powered stateless API for PDF files.
+Version: %s
+-------------------------------------------------------
+`
+
+var version = "snapshot"
+
+func Run() {
+	fmt.Printf(banner, version)
+
+	// Creates the roo` FlagSet and adds the modules flags to it.
+	fs := flag.NewFlagSet("gotenberg", flag.ExitOnError)
+	fs.Duration("gotenberg-graceful-shutdown-duration", time.Duration(30)*time.Second, "Set the graceful shutdown duration")
+
+	descriptors := gotenberg.GetModuleDescriptors()
+	var modsInfo string
+	for _, desc := range descriptors {
+		fs.AddFlagSet(desc.FlagSet)
+		modsInfo += desc.ID + " "
+	}
+
+	fmt.Printf("[SYSTEM] modules: %s\n", modsInfo)
+
+	// Parses the flags...
+	err := fs.Parse(os.Args[1:])
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+
+	// ...and creates a wrapper around those.
+	parsedFlags := gotenberg.ParsedFlags{FlagSet: fs}
+
+	// Get the graceful shutdown duration.
+	gracefulShutdownDuration := parsedFlags.MustDuration("gotenberg-graceful-shutdown-duration")
+
+	ctx := gotenberg.NewContext(parsedFlags, descriptors)
+
+	// Starts application modules.
+	apps, err := ctx.Modules(new(gotenberg.App))
+	if err != nil {
+		fmt.Printf("[FATAL] %s\n", err)
+		os.Exit(1)
+	}
+
+	for _, a := range apps {
+		go func(app gotenberg.App) {
+			id := app.(gotenberg.Module).Descriptor().ID
+			err = app.Start()
+
+			if err != nil {
+				fmt.Printf("[FATAL] starting %s: %s\n", id, err)
+				os.Exit(1)
+			}
+
+			startupMessage := app.StartupMessage()
+			if startupMessage == "" {
+				fmt.Printf("[SYSTEM] %s: application started\n", id)
+
+				return
+			}
+
+			fmt.Printf("[SYSTEM] %s: %s\n", id, startupMessage)
+		}(a.(gotenberg.App))
+
+	}
+
+	quit := make(chan os.Signal, 1)
+
+	// We'll accept graceful shutdowns when quit via SIGINT (Ctrl+C).
+	signal.Notify(quit, os.Interrupt)
+
+	// Block until we receive our signal.
+	<-quit
+
+	gracefulShutdownCtx, cancel := context.WithTimeout(context.Background(), gracefulShutdownDuration)
+	defer cancel()
+
+	fmt.Printf("[SYSTEM] graceful shutdown of %s\n", gracefulShutdownDuration)
+
+	for _, a := range apps {
+		id := a.(gotenberg.Module).Descriptor().ID
+		app := a.(gotenberg.App)
+
+		err = app.Stop(gracefulShutdownCtx)
+		if err != nil {
+			fmt.Printf("[ERROR] stopping %s: %s\n", id, err)
+		}
+
+		fmt.Printf("[SYSTEM] %s: application stopped\n", id)
+	}
+
+	os.Exit(0)
+}

pkg/gotenberg/cmd.go

@@ -0,0 +1,187 @@
+package gotenberg
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os/exec"
+	"strings"
+	"syscall"
+
+	"go.uber.org/zap"
+)
+
+// Cmd wraps an exec.Cmd.
+type Cmd struct {
+	ctx     context.Context
+	logger  *zap.Logger
+	process *exec.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 Command(logger *zap.Logger, binPath string, args ...string) Cmd {
+	cmd := exec.Command(binPath, args...)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+
+	return Cmd{
+		ctx:     nil,
+		logger:  logger.Named("cmd"),
+		process: cmd,
+	}
+}
+
+// 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 CommandContext(ctx context.Context, logger *zap.Logger, binPath string, args ...string) (Cmd, error) {
+	if ctx == nil {
+		return Cmd{}, errors.New("nil context")
+	}
+
+	cmd := exec.CommandContext(ctx, binPath, args...)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+
+	return Cmd{
+		ctx:     ctx,
+		logger:  logger.Named("cmd"),
+		process: cmd,
+	}, nil
+}
+
+// Start starts the command but does not wait for its completion.
+func (cmd Cmd) Start() error {
+	err := cmd.pipeOutput()
+	if err != nil {
+		return fmt.Errorf("pipe unix process output: %w", err)
+	}
+
+	cmd.logger.Debug(fmt.Sprintf("start unix process: %s", strings.Join(cmd.process.Args, " ")))
+
+	err = cmd.process.Start()
+	if err != nil {
+		return fmt.Errorf("start unix process: %w", err)
+	}
+
+	return nil
+}
+
+// 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 Cmd) Exec() error {
+	if cmd.ctx == nil {
+		return errors.New("nil context")
+	}
+
+	err := cmd.Start()
+	if err != nil {
+		return fmt.Errorf("start command: %w", err)
+	}
+
+	errChan := make(chan error, 1)
+
+	go func() {
+		errChan <- cmd.process.Wait()
+	}()
+
+	select {
+	case err = <-errChan:
+		errProc := cmd.Kill()
+		if errProc != nil {
+			cmd.logger.Error(errProc.Error())
+		}
+
+		if err == nil {
+			return nil
+		}
+
+		return fmt.Errorf("unix process error: %w", err)
+	case <-cmd.ctx.Done():
+		errProc := cmd.Kill()
+		if errProc != nil {
+			cmd.logger.Error(errProc.Error())
+		}
+
+		return fmt.Errorf("context done: %w", cmd.ctx.Err())
+	}
+}
+
+// pipeOutput creates logs entries according to the process stdout and stderr.
+// It does nothing if the logging level is not debug.
+func (cmd Cmd) pipeOutput() error {
+	checkedEntry := cmd.logger.Check(zap.DebugLevel, "check for debug level before piping unix process output")
+	if checkedEntry == nil {
+		return nil
+	}
+
+	stdout, err := cmd.process.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("pipe unix process stdout: %w", err)
+	}
+
+	stderr, err := cmd.process.StderrPipe()
+	if err != nil {
+		return fmt.Errorf("unix process sdterr: %w", err)
+	}
+
+	// logCommandOutput creates logs entries according to a reader
+	// (either stdout or stderr).
+	logCommandOutput := func(logger *zap.Logger, reader io.ReadCloser) {
+		r := bufio.NewReader(reader)
+		defer reader.Close()
+
+		for {
+			line, _, err := r.ReadLine()
+
+			if err != nil {
+				if err != io.EOF && !strings.Contains(err.Error(), "file already closed") {
+					logger.Error(fmt.Sprintf("pipe unix process output error: %s", err))
+				}
+
+				break
+			}
+
+			if len(line) != 0 {
+				logger.Debug(string(line))
+			}
+		}
+	}
+
+	go logCommandOutput(cmd.logger.Named("stdout"), stdout)
+	go logCommandOutput(cmd.logger.Named("stderr"), stderr)
+
+	return nil
+}
+
+// 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 Cmd) Kill() error {
+	if cmd.process == nil {
+		// We cannot use the logger here, because for whatever reason using it
+		// result to a panic.
+		// cmd.logger.Debug("no process, skip killing")
+		return nil
+	}
+
+	err := syscall.Kill(-cmd.process.Process.Pid, syscall.SIGKILL)
+	if err == nil {
+		cmd.logger.Debug("unix process killed")
+		return nil
+	}
+
+	// If the process does not exist anymore, the error is irrelevant.
+	if strings.Contains(err.Error(), "no such process") {
+		cmd.logger.Debug("unix process already killed")
+		return nil
+	}
+
+	return fmt.Errorf("kill unix process: %w", err)
+}

pkg/gotenberg/cmd_test.go

@@ -0,0 +1,220 @@
+package gotenberg
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+func TestCommand(t *testing.T) {
+	cmd := Command(zap.NewNop(), "foo")
+
+	if !cmd.process.SysProcAttr.Setpgid {
+		t.Error("expected Setpgid to be true")
+	}
+}
+
+func TestCommandContext(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       context.Context
+		expectErr bool
+	}{
+		{
+			ctx:       nil,
+			expectErr: true,
+		},
+		{
+			ctx: context.TODO(),
+		},
+	} {
+		cmd, err := CommandContext(tc.ctx, zap.NewNop(), "foo")
+
+		if err == nil && !cmd.process.SysProcAttr.Setpgid {
+			t.Fatalf("test %d: expected Setpgid to be true", i)
+		}
+
+		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 TestCmd_Start(t *testing.T) {
+	for i, tc := range []struct {
+		cmd       Cmd
+		expectErr bool
+	}{
+		{
+			cmd:       Command(zap.NewNop(), "foo"),
+			expectErr: true,
+		},
+		{
+			cmd: Command(zap.NewNop(), "echo", "Hello", "World"),
+		},
+	} {
+		err := tc.cmd.Start()
+
+		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 TestCmd_Exec(t *testing.T) {
+	for i, tc := range []struct {
+		cmd       Cmd
+		timeout   time.Duration
+		expectErr bool
+	}{
+		{
+			cmd:       Command(zap.NewNop(), "foo"),
+			expectErr: true,
+		},
+		{
+			cmd:       Command(zap.NewNop(), "foo"),
+			timeout:   time.Duration(5) * time.Second,
+			expectErr: true,
+		},
+		{
+			cmd:     Command(zap.NewNop(), "echo", "Hello", "World"),
+			timeout: time.Duration(5) * time.Second,
+		},
+		{
+			cmd:       Command(zap.NewNop(), "sleep", "3"),
+			timeout:   time.Duration(2) * time.Second,
+			expectErr: true,
+		},
+	} {
+		if tc.timeout > 0 {
+			ctx, cancel := context.WithTimeout(context.TODO(), tc.timeout)
+			defer cancel()
+
+			tc.cmd.ctx = ctx
+		}
+
+		err := tc.cmd.Exec()
+
+		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 TestCmd_pipeOutput(t *testing.T) {
+	for i, tc := range []struct {
+		cmd       Cmd
+		run       bool
+		expectErr bool
+	}{
+		{
+			cmd: Command(zap.NewNop(), "echo", "Hello", "World"),
+		},
+		{
+			cmd: func() Cmd {
+				cmd := Command(zap.NewExample(), "echo", "Hello", "World")
+				_, err := cmd.process.StdoutPipe()
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return cmd
+			}(),
+			expectErr: true,
+		},
+		{
+			cmd: func() Cmd {
+				cmd := Command(zap.NewExample(), "echo", "Hello", "World")
+				_, err := cmd.process.StderrPipe()
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return cmd
+			}(),
+			expectErr: true,
+		},
+		{
+			cmd: Command(zap.NewExample(), "echo", "Hello", "World"),
+			run: true,
+		},
+	} {
+		err := tc.cmd.pipeOutput()
+
+		if tc.run {
+			errStart := tc.cmd.process.Start()
+
+			if errStart != nil {
+				t.Fatalf("test %d: expected no error but got: %v", i, err)
+			}
+		}
+
+		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 TestCmd_Kill(t *testing.T) {
+	for i, tc := range []struct {
+		cmd       Cmd
+		expectErr bool
+	}{
+		{
+			cmd: Cmd{logger: zap.NewNop()},
+		},
+		{
+			cmd: func() Cmd {
+				cmd := Command(zap.NewNop(), "sleep", "60")
+				err := cmd.process.Start()
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return cmd
+			}(),
+		},
+		{
+			cmd: func() Cmd {
+				cmd := Command(zap.NewNop(), "echo", "Hello", "World")
+				err := cmd.process.Run()
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return cmd
+			}(),
+		},
+	} {
+		err := tc.cmd.Kill()
+
+		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/gotenberg/context.go

@@ -0,0 +1,125 @@
+package gotenberg
+
+import (
+	"fmt"
+	"reflect"
+)
+
+// Context is a struct which helps initializing modules. When provisioning, a
+// module may use the context to get other modules that it needs internally.
+type Context struct {
+	flags           ParsedFlags
+	descriptors     []ModuleDescriptor
+	moduleInstances map[string]interface{}
+}
+
+// NewContext creates a Context.
+// In a module, prefer the Provisioner interface to get a Context.
+func NewContext(
+	flags ParsedFlags,
+	descriptors []ModuleDescriptor,
+) *Context {
+	return &Context{
+		flags:           flags,
+		descriptors:     descriptors,
+		moduleInstances: make(map[string]interface{}),
+	}
+}
+
+// ParsedFlags returns the parsed flags.
+//
+//	func (m *YourModule) Provision(ctx *gotenberg.Context) error {
+//		flags := ctx.ParsedFlags()
+//		m.foo = flags.RequiredString("foo")
+//	}
+func (ctx Context) ParsedFlags() ParsedFlags {
+	return ctx.flags
+}
+
+// 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 (ctx *Context) Module(kind interface{}) (interface{}, error) {
+	mods, err := ctx.Modules(kind)
+
+	if err != nil {
+		return nil, fmt.Errorf("get module: %w", err)
+	}
+
+	if len(mods) != 1 {
+		return nil, fmt.Errorf("expected to have one and only one %s module", kind)
+	}
+
+	return mods[0], nil
+}
+
+// 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 (ctx *Context) Modules(kind interface{}) ([]interface{}, error) {
+	realKind := reflect.TypeOf(kind).Elem()
+
+	var mods []interface{}
+
+	for _, desc := range ctx.descriptors {
+		newInstance := desc.New()
+
+		if ok := reflect.TypeOf(newInstance).Implements(realKind); ok {
+			// The module implements the requested interface.
+			// We check if it has already been initialized.
+			instance, ok := ctx.moduleInstances[desc.ID]
+
+			if ok {
+				mods = append(mods, instance)
+			} else {
+				err := ctx.loadModule(desc.ID, newInstance)
+				if err != nil {
+					return nil, err
+				}
+
+				mods = append(mods, newInstance)
+			}
+		}
+	}
+
+	return mods, nil
+}
+
+// loadModule calls the Provision and/or Validate methods of the requested
+// module if it satisfies the Provisioner and/or Validator interfaces.
+func (ctx *Context) loadModule(id string, instance interface{}) error {
+	if prov, ok := instance.(Provisioner); ok {
+		// The instance can be provisioned.
+		err := prov.Provision(ctx)
+		if err != nil {
+			return fmt.Errorf("provision module %s: %w", id, err)
+		}
+	}
+
+	if validator, ok := instance.(Validator); ok {
+		// The instance can be validated.
+		err := validator.Validate()
+		if err != nil {
+			return fmt.Errorf("validate module %s: %w", id, err)
+		}
+	}
+
+	ctx.moduleInstances[id] = instance
+
+	return nil
+}

pkg/gotenberg/context_test.go

@@ -0,0 +1,195 @@
+package gotenberg
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestNewContext(t *testing.T) {
+	if NewContext(ParsedFlags{}, nil) == nil {
+		t.Error("expected a non-nil value")
+	}
+}
+
+func TestContext_ParsedFlags(t *testing.T) {
+	ctx := NewContext(ParsedFlags{}, nil)
+
+	actual := ctx.ParsedFlags()
+	expect := ParsedFlags{}
+
+	if actual != expect {
+		t.Errorf("expected %v but got %v", expect, actual)
+	}
+}
+
+func TestContext_Module(t *testing.T) {
+	for i, tc := range []struct {
+		mods      []ModuleDescriptor
+		kind      interface{}
+		expectErr bool
+	}{
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return errors.New("foo") }
+
+				return []ModuleDescriptor{mod.Descriptor()}
+			}(),
+			kind:      new(Provisioner),
+			expectErr: true,
+		},
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return nil }
+
+				return []ModuleDescriptor{mod.Descriptor(), mod.Descriptor()}
+			}(),
+			kind:      new(Provisioner),
+			expectErr: true,
+		},
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return nil }
+
+				return []ModuleDescriptor{mod.Descriptor()}
+			}(),
+			kind: new(Provisioner),
+		},
+	} {
+
+		ctx := NewContext(ParsedFlags{}, tc.mods)
+		_, err := ctx.Module(tc.kind)
+
+		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 TestContext_Modules(t *testing.T) {
+	for i, tc := range []struct {
+		mods      []ModuleDescriptor
+		kind      interface{}
+		expectErr bool
+	}{
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return errors.New("foo") }
+
+				return []ModuleDescriptor{mod.Descriptor()}
+			}(),
+			kind:      new(Provisioner),
+			expectErr: true,
+		},
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return nil }
+
+				return []ModuleDescriptor{mod.Descriptor(), mod.Descriptor()}
+			}(),
+			kind: new(Provisioner),
+		},
+		{
+			mods: func() []ModuleDescriptor {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return nil }
+
+				return []ModuleDescriptor{mod.Descriptor()}
+			}(),
+			kind: new(Provisioner),
+		},
+	} {
+
+		ctx := NewContext(ParsedFlags{}, tc.mods)
+		_, err := ctx.Modules(tc.kind)
+
+		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 TestContext_loadModule(t *testing.T) {
+	for i, tc := range []struct {
+		instance  interface{}
+		expectErr bool
+	}{
+		{
+			instance: func() interface{} {
+				mod := struct{ ProtoProvisioner }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.provision = func(ctx *Context) error { return errors.New("foo") }
+
+				return mod
+			}(),
+			expectErr: true,
+		},
+		{
+			instance: func() interface{} {
+				mod := struct{ ProtoValidator }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.validate = func() error { return errors.New("foo") }
+
+				return mod
+			}(),
+			expectErr: true,
+		},
+		{
+			instance: func() interface{} {
+				mod := struct{ ProtoValidator }{}
+				mod.descriptor = func() ModuleDescriptor {
+					return ModuleDescriptor{ID: "foo", New: func() Module { return mod }}
+				}
+				mod.validate = func() error { return nil }
+
+				return mod
+			}(),
+		},
+	} {
+
+		ctx := NewContext(ParsedFlags{}, nil)
+		err := ctx.loadModule("foo", tc.instance)
+
+		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/gotenberg/doc.go

@@ -0,0 +1,7 @@
+// 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/.
+package gotenberg

pkg/gotenberg/flags.go

@@ -0,0 +1,109 @@
+package gotenberg
+
+import (
+	"regexp"
+	"time"
+
+	"github.com/labstack/gommon/bytes"
+	flag "github.com/spf13/pflag"
+)
+
+// ParsedFlags wraps a flag.FlagSet so that retrieving the typed values is
+// easier.
+type ParsedFlags struct {
+	*flag.FlagSet
+}
+
+// MustString returns the string value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustString(name string) string {
+	val, err := f.GetString(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustStringSlice returns the string slice value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustStringSlice(name string) []string {
+	val, err := f.GetStringSlice(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustBool returns the boolean value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustBool(name string) bool {
+	val, err := f.GetBool(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustInt returns the int value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustInt(name string) int {
+	val, err := f.GetInt(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustFloat64 returns the float value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustFloat64(name string) float64 {
+	val, err := f.GetFloat64(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustDuration returns the time.Duration value of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustDuration(name string) time.Duration {
+	val, err := f.GetDuration(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustHumanReadableBytesString returns the human-readable bytes string of a
+// flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustHumanReadableBytesString(name string) string {
+	val, err := f.GetString(name)
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = bytes.Parse(val)
+	if err != nil {
+		panic(err)
+	}
+
+	return val
+}
+
+// MustRegexp returns the regular expression of a flag given by name.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustRegexp(name string) *regexp.Regexp {
+	val, err := f.GetString(name)
+	if err != nil {
+		panic(err)
+	}
+
+	return regexp.MustCompile(val)
+}

pkg/gotenberg/flags_test.go

@@ -0,0 +1,378 @@
+package gotenberg
+
+import (
+	"testing"
+	"time"
+
+	flag "github.com/spf13/pflag"
+)
+
+func TestParsedFlags_MustString(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.String("foo", "", "")
+
+	err := fs.Parse([]string{"--foo=foo"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustString(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustStringSlice(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.StringSlice("foo", make([]string, 0), "")
+
+	err := fs.Parse([]string{"--foo=foo", "--foo=bar", "--foo=baz"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustStringSlice(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustBool(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.Bool("foo", false, "")
+
+	err := fs.Parse([]string{"--foo=true"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustBool(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustInt(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.Int("foo", 0, "")
+
+	err := fs.Parse([]string{"--foo=1"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustInt(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustFloat64(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.Float64("foo", 1.0, "")
+
+	err := fs.Parse([]string{"--foo=2.0"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustFloat64(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustDuration(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.Duration("foo", time.Duration(1)*time.Second, "")
+
+	err := fs.Parse([]string{"--foo=2m"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustDuration(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustHumanReadableBytesString(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.String("foo", "1MB", "")
+	fs.String("bar", "1MB", "")
+
+	err := fs.Parse([]string{"--foo=1GB", "--bar=foo"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+		{
+			name:        "baz",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustHumanReadableBytesString(tc.name)
+		}()
+	}
+}
+
+func TestParsedFlags_MustRegexp(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.String("foo", "", "")
+	fs.String("bar", "", "")
+
+	err := fs.Parse([]string{"--foo=", "--bar=*"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for i, tc := range []struct {
+		name        string
+		expectPanic bool
+	}{
+		{
+			name: "foo",
+		},
+		{
+			name:        "bar",
+			expectPanic: true,
+		},
+		{
+			name:        "baz",
+			expectPanic: true,
+		},
+	} {
+		func() {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			parsedFlags.MustRegexp(tc.name)
+		}()
+	}
+}

pkg/gotenberg/fs.go

@@ -0,0 +1,33 @@
+package gotenberg
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/google/uuid"
+)
+
+// 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.
+func TmpPath() string {
+	return os.TempDir()
+}
+
+// NewDirPath returns a random absolute path based on the temporary path.
+func NewDirPath() string {
+	return fmt.Sprintf("%s/%s", TmpPath(), uuid.New())
+}
+
+// MkdirAll creates a random directory based on the temporary path and
+// returns its absolute path.
+func MkdirAll() (string, error) {
+	path := NewDirPath()
+
+	err := os.MkdirAll(path, 0755)
+	if err != nil {
+		return "", fmt.Errorf("create directory %s: %w", path, err)
+	}
+
+	return path, nil
+}

pkg/gotenberg/fs_test.go

@@ -0,0 +1,59 @@
+package gotenberg
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestTmpPath(t *testing.T) {
+	osTempDir := os.TempDir()
+	tmpPath := TmpPath()
+
+	if tmpPath != osTempDir {
+		t.Errorf("expected path '%s' but got '%s'", osTempDir, tmpPath)
+	}
+}
+
+func TestNewDirPath(t *testing.T) {
+	newDirPath := NewDirPath()
+	tmpPath := TmpPath()
+
+	if !strings.HasPrefix(newDirPath, tmpPath) {
+		t.Fatalf("expected path '%s' to start with '%s'", newDirPath, tmpPath)
+	}
+
+	newDirPaths := make([]string, 1000)
+	for i := range newDirPaths {
+		newDirPaths[i] = NewDirPath()
+	}
+
+	for i, newDirPath := range newDirPaths {
+		for j, comparison := range newDirPaths {
+			if i == j {
+				continue
+			}
+
+			if newDirPath == comparison {
+				t.Fatalf("expected path '%s' (index %d) to be unique, but found an identical path on index %d", newDirPath, i, j)
+			}
+		}
+	}
+}
+
+func TestMkdirAll(t *testing.T) {
+	path, err := MkdirAll()
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	tmpPath := TmpPath()
+	if !strings.HasPrefix(path, tmpPath) {
+		t.Fatalf("expected path '%s' to start with '%s'", path, tmpPath)
+	}
+
+	_, err = os.Stat(path)
+	if os.IsNotExist(err) {
+		t.Errorf("expected path '%s' to exist but got: %v", path, err)
+	}
+}

pkg/gotenberg/logging.go

@@ -0,0 +1,14 @@
+package gotenberg
+
+import "go.uber.org/zap"
+
+// 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 LoggerProvider interface {
+	Logger(mod Module) (*zap.Logger, error)
+}

pkg/gotenberg/modules.go

@@ -0,0 +1,135 @@
+package gotenberg
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"sync"
+
+	flag "github.com/spf13/pflag"
+)
+
+// 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 Module interface {
+	Descriptor() ModuleDescriptor
+}
+
+// ModuleDescriptor describes your module for the application.
+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
+}
+
+// Provisioner is a module interface for modules which have to be initialized
+// according to flags, environment variables, the context, etc.
+type Provisioner interface {
+	Provision(*Context) error
+}
+
+// Validator is a module interface for modules which have to be validated after
+// provisioning.
+type Validator interface {
+	Validate() error
+}
+
+// App is a module interface for modules which can be started or stopped by the
+// application.
+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
+}
+
+// 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 MustRegisterModule(mod Module) {
+	desc := mod.Descriptor()
+
+	if desc.ID == "" {
+		panic("module with an empty ID cannot be registered")
+	}
+
+	if desc.New == nil {
+		panic("module New function cannot be nil")
+	}
+
+	if val := desc.New(); val == nil {
+		panic("module New function cannot return a nil instance")
+	}
+
+	descriptorsMu.Lock()
+	defer descriptorsMu.Unlock()
+
+	if _, ok := descriptors[desc.ID]; ok {
+		panic(fmt.Sprintf("module %s is already registered", desc.ID))
+	}
+
+	descriptors[desc.ID] = desc
+}
+
+// GetModuleDescriptors returns the descriptors of all registered modules.
+func GetModuleDescriptors() []ModuleDescriptor {
+	descriptorsMu.RLock()
+	defer descriptorsMu.RUnlock()
+
+	mods := make([]ModuleDescriptor, len(descriptors))
+	i := 0
+
+	for _, desc := range descriptors {
+		mods[i] = desc
+		i++
+	}
+
+	sort.Slice(mods, func(i, j int) bool {
+		return mods[i].ID < mods[j].ID
+	})
+
+	return mods
+}
+
+var (
+	descriptors   = make(map[string]ModuleDescriptor)
+	descriptorsMu sync.RWMutex
+)

pkg/gotenberg/modules_test.go

@@ -0,0 +1,135 @@
+package gotenberg
+
+import (
+	"reflect"
+	"testing"
+)
+
+type ProtoModule struct {
+	descriptor func() ModuleDescriptor
+}
+
+func (mod ProtoModule) Descriptor() ModuleDescriptor {
+	return mod.descriptor()
+}
+
+type ProtoProvisioner struct {
+	ProtoModule
+	provision func(ctx *Context) error
+}
+
+func (mod ProtoProvisioner) Provision(ctx *Context) error {
+	return mod.provision(ctx)
+}
+
+type ProtoValidator struct {
+	ProtoModule
+	validate func() error
+}
+
+func (mod ProtoValidator) Validate() error {
+	return mod.validate()
+}
+
+func TestMustRegisterModule(t *testing.T) {
+	descriptorsMu.RLock()
+	descriptors = map[string]ModuleDescriptor{
+		"a": {ID: "a"},
+	}
+	descriptorsMu.RUnlock()
+
+	for i, tc := range []struct {
+		ID          string
+		New         func() Module
+		expectPanic bool
+	}{
+		{
+			ID:          "",
+			New:         func() Module { return new(ProtoModule) },
+			expectPanic: true,
+		},
+		{
+			ID:          "b",
+			New:         nil,
+			expectPanic: true,
+		},
+		{
+			ID:          "b",
+			New:         func() Module { return nil },
+			expectPanic: true,
+		},
+		{
+			ID:          "a",
+			New:         func() Module { return new(ProtoModule) },
+			expectPanic: true,
+		},
+		{
+			ID:  "b",
+			New: func() Module { return new(ProtoModule) },
+		},
+	} {
+		func() {
+			mod := struct{ ProtoModule }{}
+			mod.descriptor = func() ModuleDescriptor { return ModuleDescriptor{ID: tc.ID, New: tc.New} }
+
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Errorf("test %d: expected panic but got none", i)
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("test %d: expected no panic but got: %v", i, r)
+					}
+				}()
+			}
+
+			MustRegisterModule(mod)
+		}()
+	}
+
+	descriptorsMu.RLock()
+	descriptors = make(map[string]ModuleDescriptor)
+	descriptorsMu.RUnlock()
+}
+
+func TestGetModuleDescriptors(t *testing.T) {
+	descriptorsMu.RLock()
+	descriptors = map[string]ModuleDescriptor{
+		"d": {ID: "d"},
+		"c": {ID: "c"},
+		"b": {ID: "b"},
+		"a": {ID: "a"},
+	}
+	descriptorsMu.RUnlock()
+
+	expect := []ModuleDescriptor{
+		{ID: "a"},
+		{ID: "b"},
+		{ID: "c"},
+		{ID: "d"},
+	}
+
+	actual := GetModuleDescriptors()
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %v but got %v", expect, actual)
+	}
+
+	descriptorsMu.RLock()
+	descriptors = make(map[string]ModuleDescriptor)
+	descriptorsMu.RUnlock()
+}
+
+// Interface guards.
+var (
+	_ Module      = (*ProtoModule)(nil)
+	_ Provisioner = (*ProtoProvisioner)(nil)
+	_ Module      = (*ProtoProvisioner)(nil)
+	_ Validator   = (*ProtoValidator)(nil)
+	_ Module      = (*ProtoValidator)(nil)
+)

pkg/gotenberg/pdfengine.go

@@ -0,0 +1,52 @@
+package gotenberg
+
+import (
+	"context"
+	"errors"
+
+	"go.uber.org/zap"
+)
+
+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")
+)
+
+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"
+)
+
+// 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 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
+}
+
+// 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 PDFEngineProvider interface {
+	PDFEngine() (PDFEngine, error)
+}

pkg/modules/api/api.go

@@ -0,0 +1,494 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/alexliesenfeld/health"
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/gc"
+	"github.com/labstack/echo/v4"
+	flag "github.com/spf13/pflag"
+	"go.uber.org/multierr"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(API{})
+}
+
+// API is a module which provides an HTTP server. Other modules may add
+// "multipart/form-data" routes, middlewares or health checks.
+type API struct {
+	port                      int
+	readTimeout               time.Duration
+	processTimeout            time.Duration
+	writeTimeout              time.Duration
+	rootPath                  string
+	traceHeader               string
+	disableHealthCheckLogging bool
+	webhookAllowList          *regexp.Regexp
+	webhookDenyList           *regexp.Regexp
+	webhookErrorAllowList     *regexp.Regexp
+	webhookErrorDenyList      *regexp.Regexp
+	webhookMaxRetry           int
+	webhookRetryMinWait       time.Duration
+	webhookRetryMaxWait       time.Duration
+	disableWebhook            bool
+
+	multipartFormDataRoutes []MultipartFormDataRoute
+	externalMiddlewares     []Middleware
+	healthChecks            []health.CheckerOption
+	logger                  *zap.Logger
+	srv                     *echo.Echo
+}
+
+// MultipartFormDataRouter is a module interface which adds
+// "multipart/form-data" routes to the API.
+type MultipartFormDataRouter interface {
+	Routes() ([]MultipartFormDataRoute, error)
+}
+
+// MultipartFormDataRoute represents a "multipart/form-data" route. All routes
+// uses the HTTP POST method.
+type MultipartFormDataRoute struct {
+	// Path is the sub path of the route. Must start with a slash.
+	// Required.
+	Path string
+
+	// Handler is the function which handles the request.
+	// Required.
+	Handler func(ctx *Context) error
+}
+
+// MiddlewareProvider is a module interface which adds middlewares to the API.
+type MiddlewareProvider interface {
+	Middlewares() ([]Middleware, error)
+}
+
+// MiddlewarePriority is a type which helps to determine the execution order of
+// middlewares provided by the MiddlewareProvider modules.
+type MiddlewarePriority uint32
+
+const (
+	VeryLowPriority MiddlewarePriority = iota
+	LowPriority
+	MediumPriority
+	HighPriority
+	VeryHighPriority
+)
+
+// Middleware is a middleware which can be added to the API's middlewares
+// chain.
+//
+//  middleware := &Middleware{
+//    Handler: func() echo.MiddlewareFunc {
+//      return func(next echo.HandlerFunc) echo.HandlerFunc {
+//        return func(c echo.Context) error {
+//          rootPath := c.Get("rootPath").(string)
+//          healthURI := fmt.Sprintf("%shealth", rootPath)
+//
+//          // Skip the middleware if health check URI.
+//          if c.Request().RequestURI == healthURI {
+//            // Call the next middleware in the chain.
+//            return next(c)
+//          }
+//
+//          // Your middleware process.
+//          // ...
+//
+//          // Call the next middleware in the chain.
+//          return next(c)
+//        }
+//      }
+//    }(),
+//  }
+type Middleware struct {
+	// RunBeforeRouter tells if the middleware should run before the router
+	// process an HTTP request.
+	// Optional.
+	RunBeforeRouter bool
+
+	// Priority tells if the middleware should be positioned high or not in
+	// the middlewares chain.
+	// Default to VeryLowPriority.
+	// Optional.
+	Priority MiddlewarePriority
+
+	// Handler is the function of the middleware.
+	// Required.
+	Handler echo.MiddlewareFunc
+}
+
+// HealthChecker is a module interface which allows adding health checks to the
+// API.
+//
+// See https://github.com/alexliesenfeld/health for more details.
+type HealthChecker interface {
+	Checks() ([]health.CheckerOption, error)
+}
+
+// Descriptor returns an API's module descriptor.
+func (API) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "api",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("api", flag.ExitOnError)
+			fs.Int("api-port", 3000, "Set the port on which the API should listen")
+			fs.String("api-port-from-env", "", "Set the environment variable with the port on which the API should listen - override the default port")
+			fs.Duration("api-read-timeout", time.Duration(30)*time.Second, "Set the maximum duration allowed to read a complete request, including the body")
+			fs.Duration("api-process-timeout", time.Duration(30)*time.Second, "Set the maximum duration allowed to process a request")
+			fs.Duration("api-write-timeout", time.Duration(30)*time.Second, "Set the maximum duration before timing out writes of the response")
+			fs.String("api-root-path", "/", "Set the root path of the API - for service discovery via URL paths")
+			fs.String("api-trace-header", "Gotenberg-Trace", "Set the header name to use for identifying requests")
+			fs.Bool("api-disable-health-check-logging", false, "Disable health check logging")
+			fs.String("api-webhook-allow-list", "", "Set the allowed URLs for the webhook feature using a regular expression")
+			fs.String("api-webhook-deny-list", "", "Set the denied URLs for the webhook feature using a regular expression")
+			fs.String("api-webhook-error-allow-list", "", "Set the allowed URLs in case of an error for the webhook feature using a regular expression")
+			fs.String("api-webhook-error-deny-list", "", "Set the denied URLs in case of an error for the webhook feature using a regular expression")
+			fs.Int("api-webhook-max-retry", 4, "Set the maximum number of retries for the webhook feature")
+			fs.Duration("api-webhook-retry-min-wait", time.Duration(1)*time.Second, "Set the minimum duration to wait before trying to call the webhook again")
+			fs.Duration("api-webhook-retry-max-wait", time.Duration(30)*time.Second, "Set the maximum duration to wait before trying to call the webhook again")
+			fs.Bool("api-disable-webhook", false, "Disable the webhook feature")
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(API) },
+	}
+}
+
+// Provision sets the module properties.
+func (a *API) Provision(ctx *gotenberg.Context) error {
+	flags := ctx.ParsedFlags()
+	a.port = flags.MustInt("api-port")
+	a.readTimeout = flags.MustDuration("api-read-timeout")
+	a.processTimeout = flags.MustDuration("api-process-timeout")
+	a.writeTimeout = flags.MustDuration("api-write-timeout")
+	a.rootPath = flags.MustString("api-root-path")
+	a.traceHeader = flags.MustString("api-trace-header")
+	a.disableHealthCheckLogging = flags.MustBool("api-disable-health-check-logging")
+	a.webhookAllowList = flags.MustRegexp("api-webhook-allow-list")
+	a.webhookDenyList = flags.MustRegexp("api-webhook-deny-list")
+	a.webhookErrorAllowList = flags.MustRegexp("api-webhook-error-allow-list")
+	a.webhookErrorDenyList = flags.MustRegexp("api-webhook-error-deny-list")
+	a.webhookMaxRetry = flags.MustInt("api-webhook-max-retry")
+	a.webhookRetryMinWait = flags.MustDuration("api-webhook-retry-min-wait")
+	a.webhookRetryMaxWait = flags.MustDuration("api-webhook-retry-max-wait")
+	a.disableWebhook = flags.MustBool("api-disable-webhook")
+
+	// Port from env?
+	portEnvVar := flags.MustString("api-port-from-env")
+	if portEnvVar != "" {
+		val, ok := os.LookupEnv(portEnvVar)
+
+		if !ok {
+			return fmt.Errorf("environment variable '%s' does not exist", portEnvVar)
+		}
+
+		if val == "" {
+			return fmt.Errorf("environment variable '%s' is empty", portEnvVar)
+		}
+
+		port, err := strconv.Atoi(val)
+		if err != nil {
+			return fmt.Errorf("get int value of environment variable '%s': %w", portEnvVar, err)
+		}
+
+		a.port = port
+	}
+
+	// Get routes from modules.
+	mods, err := ctx.Modules(new(MultipartFormDataRouter))
+	if err != nil {
+		return fmt.Errorf("get multipart/form-data routers: %w", err)
+	}
+
+	routers := make([]MultipartFormDataRouter, len(mods))
+	for i, router := range mods {
+		routers[i] = router.(MultipartFormDataRouter)
+	}
+
+	for _, router := range routers {
+		routes, err := router.Routes()
+		if err != nil {
+			return fmt.Errorf("get routes: %w", err)
+		}
+
+		a.multipartFormDataRoutes = append(a.multipartFormDataRoutes, routes...)
+	}
+
+	// Get middlewares from modules.
+	mods, err = ctx.Modules(new(MiddlewareProvider))
+	if err != nil {
+		return fmt.Errorf("get middleware providers: %w", err)
+	}
+
+	middlewareProviders := make([]MiddlewareProvider, len(mods))
+	for i, middlewareProvider := range mods {
+		middlewareProviders[i] = middlewareProvider.(MiddlewareProvider)
+	}
+
+	for _, middlewareProvider := range middlewareProviders {
+		middlewares, err := middlewareProvider.Middlewares()
+		if err != nil {
+			return fmt.Errorf("get middlewares: %w", err)
+		}
+
+		a.externalMiddlewares = append(a.externalMiddlewares, middlewares...)
+	}
+
+	// Sort middlewares by priority.
+	sort.Slice(a.externalMiddlewares, func(i, j int) bool {
+		return a.externalMiddlewares[i].Priority > a.externalMiddlewares[j].Priority
+	})
+
+	// Get health checks from modules.
+	mods, err = ctx.Modules(new(HealthChecker))
+	if err != nil {
+		return fmt.Errorf("get health checkers: %w", err)
+	}
+
+	healthCheckers := make([]HealthChecker, len(mods))
+	for i, healthChecker := range mods {
+		healthCheckers[i] = healthChecker.(HealthChecker)
+	}
+
+	for _, healthChecker := range healthCheckers {
+		checks, err := healthChecker.Checks()
+		if err != nil {
+			return fmt.Errorf("get health checks: %w", err)
+		}
+
+		a.healthChecks = append(a.healthChecks, checks...)
+	}
+
+	loggerProvider, err := ctx.Module(new(gotenberg.LoggerProvider))
+	if err != nil {
+		return fmt.Errorf("get logger provider: %w", err)
+	}
+
+	logger, err := loggerProvider.(gotenberg.LoggerProvider).Logger(a)
+	if err != nil {
+		return fmt.Errorf("get logger: %w", err)
+	}
+
+	a.logger = logger
+
+	return nil
+}
+
+// Validate validates the module properties.
+func (a API) Validate() error {
+	var err error
+
+	if a.port < 1 || a.port > 65535 {
+		err = multierr.Append(err,
+			errors.New("port must be more than 1 and less than 65535"),
+		)
+	}
+
+	if !strings.HasPrefix(a.rootPath, "/") {
+		err = multierr.Append(err,
+			errors.New("root path must start with /"),
+		)
+	}
+
+	if !strings.HasSuffix(a.rootPath, "/") {
+		err = multierr.Append(err,
+			errors.New("root path must end with /"),
+		)
+	}
+
+	if len(strings.TrimSpace(a.traceHeader)) == 0 {
+		err = multierr.Append(err,
+			errors.New("trace header must not be empty"),
+		)
+	}
+
+	if err != nil {
+		return err
+	}
+
+	routesMap := make(map[string]MultipartFormDataRoute, len(a.multipartFormDataRoutes))
+
+	for _, route := range a.multipartFormDataRoutes {
+		if route.Path == "" {
+			return errors.New("route with empty path cannot be registered")
+		}
+
+		if !strings.HasPrefix(route.Path, "/") {
+			return fmt.Errorf("route %s does not start with /", route.Path)
+		}
+
+		if route.Handler == nil {
+			return fmt.Errorf("route %s has a nil handler", route.Path)
+		}
+
+		if _, ok := routesMap[route.Path]; ok {
+			return fmt.Errorf("route %s is already registered", route.Path)
+		}
+
+		routesMap[route.Path] = route
+	}
+
+	for _, middleware := range a.externalMiddlewares {
+		if middleware.Handler == nil {
+			return errors.New("a middleware has a nil handler")
+		}
+	}
+
+	return nil
+}
+
+// Start starts the HTTP server.
+func (a *API) Start() error {
+	a.srv = echo.New()
+	a.srv.HideBanner = true
+	a.srv.HidePort = true
+	a.srv.Server.ReadTimeout = a.readTimeout
+	a.srv.Server.WriteTimeout = a.writeTimeout
+	a.srv.HTTPErrorHandler = httpErrorHandler(a.traceHeader)
+
+	a.srv.Pre(
+		latencyMiddleware(),
+		rootPathMiddleware(a.rootPath),
+		traceMiddleware(a.traceHeader),
+		loggerMiddleware(a.logger, a.disableHealthCheckLogging),
+	)
+
+	for _, externalMiddleware := range a.externalMiddlewares {
+		if externalMiddleware.RunBeforeRouter {
+			a.srv.Pre(externalMiddleware.Handler)
+
+			continue
+		}
+
+		a.srv.Use(externalMiddleware.Handler)
+	}
+
+	hardTimeout := a.processTimeout + (time.Duration(5) * time.Second)
+
+	a.srv.GET(
+		fmt.Sprintf("%shealth", a.rootPath),
+		func() echo.HandlerFunc {
+			checks := append(a.healthChecks, health.WithTimeout(a.processTimeout))
+			checker := health.NewChecker(checks...)
+
+			return func(echoCtx echo.Context) error {
+				health.NewHandler(checker).ServeHTTP(echoCtx.Response().Writer, echoCtx.Request())
+
+				return nil
+			}
+		}(),
+		timeoutMiddleware(hardTimeout),
+	)
+
+	formsGroup := a.srv.Group(
+		fmt.Sprintf("%sforms", a.rootPath),
+		contextMiddleware(
+			contextMiddlewareConfig{
+				traceHeader: a.traceHeader,
+				timeout: struct {
+					process time.Duration
+					write   time.Duration
+				}{
+					process: a.processTimeout,
+					write:   a.writeTimeout,
+				},
+				webhook: struct {
+					allowList      *regexp.Regexp
+					denyList       *regexp.Regexp
+					errorAllowList *regexp.Regexp
+					errorDenyList  *regexp.Regexp
+					maxRetry       int
+					retryMinWait   time.Duration
+					retryMaxWait   time.Duration
+					disable        bool
+				}{
+					allowList:      a.webhookAllowList,
+					denyList:       a.webhookDenyList,
+					errorAllowList: a.webhookErrorAllowList,
+					errorDenyList:  a.webhookErrorDenyList,
+					maxRetry:       a.webhookMaxRetry,
+					retryMinWait:   a.webhookRetryMinWait,
+					retryMaxWait:   a.webhookRetryMaxWait,
+					disable:        a.disableWebhook,
+				},
+			},
+		),
+		timeoutMiddleware(hardTimeout),
+	)
+
+	// Add routes from other modules.
+	for _, route := range a.multipartFormDataRoutes {
+		formsGroup.POST(
+			route.Path,
+			func(route MultipartFormDataRoute) echo.HandlerFunc {
+				return func(c echo.Context) error {
+					ctx := c.Get("context").(*Context)
+
+					err := route.Handler(ctx)
+					if err != nil {
+						return fmt.Errorf("handle request: %w", err)
+					}
+
+					return nil
+				}
+			}(route),
+		)
+	}
+
+	// As the listen method is blocking, run it in a goroutine.
+	go func() {
+		err := a.srv.Start(fmt.Sprintf(":%d", a.port))
+		if !errors.Is(err, http.ErrServerClosed) {
+			a.logger.Fatal(err.Error())
+		}
+	}()
+
+	return nil
+}
+
+// StartupMessage returns a custom startup message.
+func (a API) StartupMessage() string {
+	return fmt.Sprintf("server listening on port %d", a.port)
+}
+
+// Stop stops the HTTP server.
+func (a API) Stop(ctx context.Context) error {
+	return a.srv.Shutdown(ctx)
+}
+
+// GraceDuration updates the expiration time of files and directories parsed by
+// the gc.GarbageCollector.
+func (a API) GraceDuration() time.Duration {
+	duration := a.readTimeout + a.processTimeout + a.writeTimeout
+
+	if a.disableWebhook {
+		return duration
+	}
+
+	for i := 0; i < a.webhookMaxRetry; i++ {
+		// Yep... Golang does not allow int * time.Duration.
+		duration += a.webhookRetryMaxWait
+	}
+
+	return duration
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module                         = (*API)(nil)
+	_ gotenberg.Provisioner                    = (*API)(nil)
+	_ gotenberg.Validator                      = (*API)(nil)
+	_ gotenberg.App                            = (*API)(nil)
+	_ gc.GarbageCollectorGraceDurationModifier = (*API)(nil)
+)

pkg/modules/api/api_test.go

@@ -0,0 +1,793 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/alexliesenfeld/health"
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/labstack/echo/v4"
+	"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 ProtoMultipartFormDataRouter struct {
+	ProtoValidator
+	routes func() ([]MultipartFormDataRoute, error)
+}
+
+func (mod ProtoMultipartFormDataRouter) Routes() ([]MultipartFormDataRoute, error) {
+	return mod.routes()
+}
+
+type ProtoMiddlewareProvider struct {
+	ProtoValidator
+	middlewares func() ([]Middleware, error)
+}
+
+func (mod ProtoMiddlewareProvider) Middlewares() ([]Middleware, error) {
+	return mod.middlewares()
+}
+
+type ProtoHealthChecker struct {
+	ProtoValidator
+	checks func() ([]health.CheckerOption, error)
+}
+
+func (mod ProtoHealthChecker) Checks() ([]health.CheckerOption, error) {
+	return mod.checks()
+}
+
+type ProtoLoggerProvider struct {
+	ProtoModule
+	logger func(mod gotenberg.Module) (*zap.Logger, error)
+}
+
+func (factory ProtoLoggerProvider) Logger(mod gotenberg.Module) (*zap.Logger, error) {
+	return factory.logger(mod)
+}
+
+func TestAPI_Descriptor(t *testing.T) {
+	descriptor := API{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(API))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestAPI_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx               *gotenberg.Context
+		setEnv            func(i int)
+		expectPort        int
+		expectMiddlewares []Middleware
+		expectErr         bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				fs := new(API).Descriptor().FlagSet
+				err := fs.Parse([]string{"--api-port-from-env=FOO"})
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					nil,
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				fs := new(API).Descriptor().FlagSet
+				err := fs.Parse([]string{"--api-port-from-env=PORT"})
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					nil,
+				)
+			}(),
+			setEnv: func(i int) {
+				err := os.Setenv("PORT", "")
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			},
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				fs := new(API).Descriptor().FlagSet
+				err := fs.Parse([]string{"--api-port-from-env=PORT"})
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					nil,
+				)
+			}(),
+			setEnv: func(i int) {
+				err := os.Setenv("PORT", "foo")
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			},
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				fs := new(API).Descriptor().FlagSet
+				err := fs.Parse([]string{"--api-port-from-env=PORT"})
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: fs,
+					},
+					nil,
+				)
+			}(),
+			setEnv: func(i int) {
+				err := os.Setenv("PORT", "1337")
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			},
+			expectPort: 1337,
+			expectErr:  true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoMultipartFormDataRouter }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return errors.New("foo")
+				}
+				mod.routes = func() ([]MultipartFormDataRoute, error) {
+					return nil, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoMiddlewareProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return errors.New("foo")
+				}
+				mod.middlewares = func() ([]Middleware, error) {
+					return nil, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoMiddlewareProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return nil
+				}
+				mod.middlewares = func() ([]Middleware, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoMultipartFormDataRouter }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return nil
+				}
+				mod.routes = func() ([]MultipartFormDataRoute, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoHealthChecker }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return errors.New("foo")
+				}
+				mod.checks = func() ([]health.CheckerOption, error) {
+					return nil, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoHealthChecker }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error {
+					return nil
+				}
+				mod.checks = func() ([]health.CheckerOption, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoLoggerProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.logger = func(_ gotenberg.Module) (*zap.Logger, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod1 := struct{ ProtoMultipartFormDataRouter }{}
+				mod1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod1 }}
+				}
+				mod1.validate = func() error {
+					return nil
+				}
+				mod1.routes = func() ([]MultipartFormDataRoute, error) {
+					return []MultipartFormDataRoute{{}}, nil
+				}
+
+				mod2 := struct{ ProtoMiddlewareProvider }{}
+				mod2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod2 }}
+				}
+				mod2.validate = func() error {
+					return nil
+				}
+				mod2.middlewares = func() ([]Middleware, error) {
+					return []Middleware{
+						{
+							Priority: VeryLowPriority,
+						},
+						{
+							Priority: LowPriority,
+						},
+						{
+							Priority: MediumPriority,
+						},
+						{
+							Priority: HighPriority,
+						},
+						{
+							Priority: VeryHighPriority,
+						},
+					}, nil
+				}
+
+				mod3 := struct{ ProtoHealthChecker }{}
+				mod3.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "baz", New: func() gotenberg.Module { return mod3 }}
+				}
+				mod3.validate = func() error {
+					return nil
+				}
+				mod3.checks = func() ([]health.CheckerOption, error) {
+					return []health.CheckerOption{health.WithDisabledAutostart()}, nil
+				}
+
+				mod4 := struct{ ProtoLoggerProvider }{}
+				mod4.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "qux", New: func() gotenberg.Module { return mod4 }}
+				}
+				mod4.logger = func(_ gotenberg.Module) (*zap.Logger, error) {
+					return zap.NewNop(), nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(API).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod1.Descriptor(),
+						mod2.Descriptor(),
+						mod3.Descriptor(),
+						mod4.Descriptor(),
+					},
+				)
+			}(),
+			expectMiddlewares: []Middleware{
+				{
+					Priority: VeryHighPriority,
+				},
+				{
+					Priority: HighPriority,
+				},
+				{
+					Priority: MediumPriority,
+				},
+				{
+					Priority: LowPriority,
+				},
+				{
+					Priority: VeryLowPriority,
+				},
+			},
+		},
+	} {
+		if tc.setEnv != nil {
+			tc.setEnv(i)
+		}
+
+		mod := new(API)
+		err := mod.Provision(tc.ctx)
+
+		if tc.expectPort != 0 && mod.port != tc.expectPort {
+			t.Errorf("expected port %d but got %d", tc.expectPort, mod.port)
+		}
+
+		if !reflect.DeepEqual(mod.externalMiddlewares, tc.expectMiddlewares) {
+			t.Errorf("expected %+v, but got: %+v", tc.expectMiddlewares, mod.externalMiddlewares)
+		}
+
+		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 TestAPI_Validate(t *testing.T) {
+	for i, tc := range []struct {
+		port        int
+		rootPath    string
+		traceHeader string
+		routes      []MultipartFormDataRoute
+		middlewares []Middleware
+		expectErr   bool
+	}{
+		{
+			port:      0,
+			expectErr: true,
+		},
+		{
+			port:      65536,
+			rootPath:  "foo",
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			routes: []MultipartFormDataRoute{
+				{
+					Path: "",
+				},
+			},
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			routes: []MultipartFormDataRoute{
+				{
+					Path: "foo",
+				},
+			},
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			routes: []MultipartFormDataRoute{
+				{
+					Path: "/foo",
+				},
+			},
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			routes: []MultipartFormDataRoute{
+				{
+					Path:    "/foo",
+					Handler: func(_ *Context) error { return nil },
+				},
+				{
+					Path:    "/foo",
+					Handler: func(_ *Context) error { return nil },
+				},
+			},
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			middlewares: []Middleware{
+				{
+					Priority: HighPriority,
+				},
+			},
+			expectErr: true,
+		},
+		{
+			port:        10,
+			rootPath:    "/foo/",
+			traceHeader: "foo",
+			routes: []MultipartFormDataRoute{
+				{
+					Path:    "/foo",
+					Handler: func(_ *Context) error { return nil },
+				},
+			},
+			middlewares: []Middleware{
+				{
+					Priority: HighPriority,
+					Handler: func() echo.MiddlewareFunc {
+						return func(next echo.HandlerFunc) echo.HandlerFunc {
+							return func(c echo.Context) error {
+								return next(c)
+							}
+						}
+					}(),
+				},
+			},
+		},
+	} {
+		mod := API{
+			port:                    tc.port,
+			rootPath:                tc.rootPath,
+			traceHeader:             tc.traceHeader,
+			multipartFormDataRoutes: tc.routes,
+			externalMiddlewares:     tc.middlewares,
+		}
+
+		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 TestAPI_Start(t *testing.T) {
+	mod := new(API)
+	mod.port = 3000
+	mod.rootPath = "/"
+	mod.multipartFormDataRoutes = []MultipartFormDataRoute{
+		{
+			Path: "/foo",
+			Handler: func(ctx *Context) error {
+				ctx.outputPaths = []string{
+					"/tests/test/testdata/api/sample1.txt",
+				}
+
+				return nil
+			},
+		},
+		{
+			Path:    "/bar",
+			Handler: func(_ *Context) error { return errors.New("foo") },
+		},
+	}
+	mod.externalMiddlewares = []Middleware{
+		{
+			RunBeforeRouter: true,
+			Handler: func() echo.MiddlewareFunc {
+				return func(next echo.HandlerFunc) echo.HandlerFunc {
+					return func(c echo.Context) error {
+						return next(c)
+					}
+				}
+			}(),
+		},
+		{
+			Handler: func() echo.MiddlewareFunc {
+				return func(next echo.HandlerFunc) echo.HandlerFunc {
+					return func(c echo.Context) error {
+						return next(c)
+					}
+				}
+			}(),
+		},
+	}
+	mod.logger = zap.NewNop()
+
+	err := mod.Start()
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	// health request.
+	recorder := httptest.NewRecorder()
+	healthRequest := httptest.NewRequest(http.MethodGet, "/health", nil)
+
+	mod.srv.ServeHTTP(recorder, healthRequest)
+	if recorder.Code != http.StatusOK {
+		t.Errorf("expected %d status code but got %d", http.StatusOK, recorder.Code)
+	}
+
+	// "multipart/form-data" request.
+	multipartRequest := func(URL string) *http.Request {
+		body := &bytes.Buffer{}
+
+		writer := multipart.NewWriter(body)
+
+		defer func() {
+			err := writer.Close()
+			if err != nil {
+				t.Fatalf("expected no error but got: %v", err)
+			}
+		}()
+
+		err := writer.WriteField("foo", "foo")
+		if err != nil {
+			t.Fatalf("expected no error but got: %v", err)
+		}
+
+		part, err := writer.CreateFormFile("foo.txt", "foo.txt")
+		if err != nil {
+			t.Fatalf("expected no error but got: %v", err)
+		}
+
+		_, err = part.Write([]byte("foo"))
+		if err != nil {
+			t.Fatalf("expected no error but got: %v", err)
+		}
+
+		req := httptest.NewRequest(http.MethodPost, URL, body)
+		req.Header.Set(echo.HeaderContentType, writer.FormDataContentType())
+
+		return req
+	}
+
+	recorder = httptest.NewRecorder()
+	mod.srv.ServeHTTP(recorder, multipartRequest("/forms/foo"))
+
+	if recorder.Code != http.StatusOK {
+		t.Errorf("expected %d status code but got %d", http.StatusOK, recorder.Code)
+	}
+
+	recorder = httptest.NewRecorder()
+	mod.srv.ServeHTTP(recorder, multipartRequest("/forms/bar"))
+
+	if recorder.Code != http.StatusInternalServerError {
+		t.Errorf("expected %d status code but got %d", http.StatusInternalServerError, recorder.Code)
+	}
+
+	err = mod.srv.Shutdown(context.TODO())
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestAPI_StartupMessage(t *testing.T) {
+	mod := API{
+		port: 3000,
+	}
+
+	actual := mod.StartupMessage()
+	expect := "server listening on port 3000"
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestAPI_Stop(t *testing.T) {
+	mod := API{
+		port: 3000,
+		multipartFormDataRoutes: []MultipartFormDataRoute{
+			{
+				Path:    "/foo",
+				Handler: func(_ *Context) error { return nil },
+			},
+		},
+		logger: zap.NewNop(),
+	}
+
+	err := mod.Start()
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	err = mod.Stop(context.TODO())
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestAPI_GraceDuration(t *testing.T) {
+	for i, tc := range []struct {
+		mod    API
+		expect time.Duration
+	}{
+		{
+			mod: API{
+				readTimeout:    time.Duration(1) * time.Second,
+				processTimeout: time.Duration(1) * time.Second,
+				writeTimeout:   time.Duration(1) * time.Second,
+				disableWebhook: true,
+			},
+			expect: time.Duration(3) * time.Second,
+		},
+		{
+			mod: API{
+				readTimeout:         time.Duration(1) * time.Second,
+				processTimeout:      time.Duration(1) * time.Second,
+				writeTimeout:        time.Duration(1) * time.Second,
+				webhookMaxRetry:     5,
+				webhookRetryMaxWait: time.Duration(5) * time.Second,
+			},
+			expect: time.Duration(28) * time.Second,
+		},
+	} {
+		actual := tc.mod.GraceDuration()
+
+		if actual != tc.expect {
+			t.Errorf("test %d: expected '%s' but got '%s'", i, tc.expect, actual)
+		}
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module         = (*ProtoModule)(nil)
+	_ gotenberg.Validator      = (*ProtoValidator)(nil)
+	_ gotenberg.Module         = (*ProtoValidator)(nil)
+	_ MultipartFormDataRouter  = (*ProtoMultipartFormDataRouter)(nil)
+	_ gotenberg.Module         = (*ProtoMultipartFormDataRouter)(nil)
+	_ gotenberg.Validator      = (*ProtoMultipartFormDataRouter)(nil)
+	_ MiddlewareProvider       = (*ProtoMiddlewareProvider)(nil)
+	_ gotenberg.Module         = (*ProtoMiddlewareProvider)(nil)
+	_ gotenberg.Validator      = (*ProtoMiddlewareProvider)(nil)
+	_ HealthChecker            = (*ProtoHealthChecker)(nil)
+	_ gotenberg.Module         = (*ProtoHealthChecker)(nil)
+	_ gotenberg.Validator      = (*ProtoHealthChecker)(nil)
+	_ gotenberg.LoggerProvider = (*ProtoLoggerProvider)(nil)
+	_ gotenberg.Module         = (*ProtoLoggerProvider)(nil)
+)

pkg/modules/api/context.go

@@ -0,0 +1,319 @@
+package api
+
+import (
+	"compress/flate"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/google/uuid"
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/labstack/echo/v4"
+	"github.com/mholt/archiver/v3"
+	"go.uber.org/zap"
+	"golang.org/x/text/runes"
+	"golang.org/x/text/transform"
+	"golang.org/x/text/unicode/norm"
+)
+
+var (
+	// ErrContextAlreadyClosed happens when the context has been canceled.
+	ErrContextAlreadyClosed = errors.New("context already closed")
+
+	// ErrOutOfBoundsOutputPath happens when an output path is not within
+	// context's working directory. It enforces having all the files in the
+	// same directory.
+	ErrOutOfBoundsOutputPath = errors.New("output path is not within context's working directory")
+)
+
+// Context is the request context for a "multipart/form-data" requests.
+type Context struct {
+	dirPath string
+	values  map[string][]string
+	files   map[string]string
+
+	outputPaths []string
+
+	cancelled bool
+	logger    *zap.Logger
+	echoCtx   echo.Context
+	context.Context
+}
+
+// newContext returns a Context by parsing a "multipart/form-data" request.
+func newContext(echoCtx echo.Context, logger *zap.Logger, timeout time.Duration) (*Context, context.CancelFunc, error) {
+	processCtx, processCancel := context.WithTimeout(context.Background(), timeout)
+
+	ctx := &Context{
+		outputPaths: make([]string, 0),
+		cancelled:   false,
+		logger:      logger,
+		echoCtx:     echoCtx,
+		Context:     processCtx,
+	}
+
+	// A custom cancel function which removes the context's working directory
+	// when called.
+	cancel := func() context.CancelFunc {
+		return func() {
+			if ctx.cancelled {
+				return
+			}
+
+			processCancel()
+
+			if ctx.dirPath == "" {
+				return
+			}
+
+			err := os.RemoveAll(ctx.dirPath)
+			if err != nil {
+				ctx.logger.Error(fmt.Sprintf("remove context's working directory: %s", err))
+
+				return
+			}
+
+			ctx.logger.Debug(fmt.Sprintf("'%s' removed", ctx.dirPath))
+			ctx.cancelled = true
+		}
+	}()
+
+	form, err := echoCtx.MultipartForm()
+	if err != nil {
+
+		if errors.Is(err, http.ErrNotMultipart) {
+			return nil, cancel, WrapError(
+				fmt.Errorf("get multipart form: %w", err),
+				NewSentinelHTTPError(http.StatusUnsupportedMediaType, "Invalid 'Content-Type' header value: want 'multipart/form-data'"),
+			)
+		}
+
+		if errors.Is(err, http.ErrMissingBoundary) {
+			return nil, cancel, WrapError(
+				fmt.Errorf("get multipart form: %w", err),
+				NewSentinelHTTPError(http.StatusUnsupportedMediaType, "Invalid 'Content-Type' header value: no boundary"),
+			)
+		}
+
+		if strings.Contains(err.Error(), io.EOF.Error()) {
+			return nil, cancel, WrapError(
+				fmt.Errorf("get multipart form: %w", err),
+				NewSentinelHTTPError(http.StatusBadRequest, "Malformed body: it does not match the 'Content-Type' header boundaries"),
+			)
+		}
+
+		return nil, cancel, fmt.Errorf("get multipart form: %w", err)
+	}
+
+	dirPath, err := gotenberg.MkdirAll()
+	if err != nil {
+		return nil, cancel, fmt.Errorf("create working directory: %w", err)
+	}
+
+	ctx.dirPath = dirPath
+	ctx.values = form.Value
+	ctx.files = make(map[string]string)
+
+	copyToDisk := func(fh *multipart.FileHeader) error {
+		// Avoid directory traversal and normalize filename.
+		// See https://github.com/thecodingmachine/gotenberg/issues/104.
+		// See https://github.com/thecodingmachine/gotenberg/issues/228.
+		t := transform.Chain(norm.NFD, runes.Remove(runes.In(unicode.Mn)), norm.NFC)
+
+		filename, _, err := transform.String(t, strings.ToLower(filepath.Base(fh.Filename)))
+		if err != nil {
+			return fmt.Errorf("transform filename: %w", err)
+		}
+
+		in, err := fh.Open()
+		if err != nil {
+			return fmt.Errorf("open multipart file: %w", err)
+		}
+
+		defer func() {
+			err := in.Close()
+			if err != nil {
+				logger.Error(fmt.Sprintf("close file header: %s", err))
+			}
+		}()
+
+		path := fmt.Sprintf("%s/%s", ctx.dirPath, filename)
+
+		out, err := os.Create(path)
+		if err != nil {
+			return fmt.Errorf("create local file: %w", err)
+		}
+
+		defer func() {
+			err := out.Close()
+			if err != nil {
+				logger.Error(fmt.Sprintf("close local file: %s", err))
+			}
+		}()
+
+		_, err = io.Copy(out, in)
+		if err != nil {
+			return fmt.Errorf("copy multipart file to local file: %w", err)
+		}
+
+		ctx.files[filename] = path
+
+		return nil
+	}
+
+	for _, files := range form.File {
+		for _, fh := range files {
+			err = copyToDisk(fh)
+
+			if err != nil {
+				return ctx, cancel, fmt.Errorf("copy to disk: %w", err)
+			}
+		}
+	}
+
+	ctx.Log().Debug(fmt.Sprintf("form data values: %+v", ctx.values))
+	ctx.Log().Debug(fmt.Sprintf("form data files: %+v", ctx.files))
+
+	return ctx, cancel, err
+}
+
+// Request returns the http.Request.
+func (ctx Context) Request() *http.Request {
+	return ctx.echoCtx.Request()
+}
+
+// FormData return a FormData.
+func (ctx Context) FormData() *FormData {
+	return &FormData{
+		values: ctx.values,
+		files:  ctx.files,
+		errors: nil,
+	}
+}
+
+// GeneratePath generates a path within the context's working directory. It
+// does not create a file.
+func (ctx Context) GeneratePath(extension string) string {
+	return fmt.Sprintf("%s/%s%s", ctx.dirPath, uuid.New(), extension)
+}
+
+// AddOutputPaths adds the given paths. Those paths will be used later to build
+// the output file.
+func (ctx *Context) AddOutputPaths(paths ...string) error {
+	if ctx.cancelled {
+		return ErrContextAlreadyClosed
+	}
+
+	for _, path := range paths {
+		if !strings.HasPrefix(path, ctx.dirPath) {
+			return ErrOutOfBoundsOutputPath
+		}
+
+		ctx.outputPaths = append(ctx.outputPaths, path)
+	}
+
+	return nil
+}
+
+// Log returns the context zap.Logger.
+func (ctx Context) Log() *zap.Logger {
+	return ctx.logger
+}
+
+// buildOutputFile builds the output file according to the output paths
+// registered in the context. If many output paths, an archive is created.
+func (ctx Context) buildOutputFile() (string, error) {
+	if ctx.cancelled {
+		return "", ErrContextAlreadyClosed
+	}
+
+	if len(ctx.outputPaths) == 0 {
+		return "", errors.New("no output path")
+	}
+
+	if len(ctx.outputPaths) == 1 {
+		ctx.logger.Debug(fmt.Sprintf("only one output file '%s', skip archive creation", ctx.outputPaths[0]))
+
+		return ctx.outputPaths[0], nil
+	}
+
+	z := archiver.Zip{
+		CompressionLevel:       flate.DefaultCompression,
+		MkdirAll:               true,
+		SelectiveCompression:   true,
+		ContinueOnError:        false,
+		OverwriteExisting:      false,
+		ImplicitTopLevelFolder: false,
+	}
+
+	archivePath := ctx.GeneratePath(".zip")
+
+	err := z.Archive(ctx.outputPaths, archivePath)
+	if err != nil {
+		return "", fmt.Errorf("archive output files: %w", err)
+	}
+
+	ctx.logger.Debug(fmt.Sprintf("archive '%s' created", archivePath))
+
+	return archivePath, nil
+}
+
+// MockContext is a helper for tests.
+//
+//  ctx := &api.MockContext{Context: &api.Context{}}
+type MockContext struct {
+	*Context
+}
+
+// SetDirPath sets the context's working directory path.
+//
+//  ctx := &api.MockContext{Context: &api.Context{}}
+//  ctx.SetDirPath("/foo")
+func (ctx *MockContext) SetDirPath(path string) {
+	ctx.dirPath = path
+}
+
+// SetValues sets the values.
+//
+//  ctx := &api.MockContext{Context: &api.Context{}}
+//  ctx.SetValues(map[string][]string{
+//    "url": {
+//      "foo",
+//    },
+//  })
+func (ctx *MockContext) SetValues(values map[string][]string) {
+	ctx.values = values
+}
+
+// SetFiles sets the files.
+//
+//  ctx := &api.MockContext{Context: &api.Context{}}
+//  ctx.SetFiles(map[string]string{
+//    "foo": "/foo",
+//  })
+func (ctx *MockContext) SetFiles(files map[string]string) {
+	ctx.files = files
+}
+
+// SetCancelled sets if the context is cancelled or not.
+//
+//  ctx := &api.MockContext{Context: &api.Context{}}
+//  ctx.SetCancelled(true)
+func (ctx *MockContext) SetCancelled(cancelled bool) {
+	ctx.cancelled = cancelled
+}
+
+// OutputPaths returns the registered output paths.
+//  ctx := &api.MockContext{Context: &api.Context{}}
+//  outputPaths := ctx.OutputPaths()
+func (ctx MockContext) OutputPaths() []string {
+	return ctx.outputPaths
+}

pkg/modules/api/context_test.go

@@ -0,0 +1,373 @@
+package api
+
+import (
+	"bytes"
+	"errors"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/labstack/echo/v4"
+	"go.uber.org/zap"
+)
+
+func TestNewContext(t *testing.T) {
+	for i, tc := range []struct {
+		request          *http.Request
+		expectErr        bool
+		expectHTTPErr    bool
+		expectHTTPStatus int
+	}{
+		{
+			request:          httptest.NewRequest(http.MethodPost, "/", nil),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusUnsupportedMediaType,
+		},
+		{
+			request: func() *http.Request {
+				req := httptest.NewRequest(http.MethodPost, "/", nil)
+				req.Header.Set(echo.HeaderContentType, echo.MIMEMultipartForm)
+
+				return req
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusUnsupportedMediaType,
+		},
+		{
+			request: func() *http.Request {
+				body := &bytes.Buffer{}
+
+				writer := multipart.NewWriter(body)
+
+				defer func() {
+					err := writer.Close()
+					if err != nil {
+						t.Fatalf("expected no error but got: %v", err)
+					}
+				}()
+
+				err := writer.WriteField("foo", "foo")
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				req := httptest.NewRequest(http.MethodPost, "/", nil)
+				req.Header.Set(echo.HeaderContentType, writer.FormDataContentType())
+
+				return req
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			request: func() *http.Request {
+				body := &bytes.Buffer{}
+
+				writer := multipart.NewWriter(body)
+
+				defer func() {
+					err := writer.Close()
+					if err != nil {
+						t.Fatalf("expected no error but got: %v", err)
+					}
+				}()
+
+				err := writer.WriteField("foo", "foo")
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				part, err := writer.CreateFormFile("foo.txt", "foo.txt")
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				_, err = part.Write([]byte("foo"))
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				req := httptest.NewRequest(http.MethodPost, "/", body)
+				req.Header.Set(echo.HeaderContentType, writer.FormDataContentType())
+
+				return req
+			}(),
+		},
+	} {
+		handler := func(c echo.Context) error {
+			_, cancel, err := newContext(c, zap.NewNop(), time.Duration(10)*time.Second)
+			defer cancel()
+			// Context already cancelled.
+			defer cancel()
+
+			if err != nil {
+				return err
+			}
+
+			return nil
+		}
+
+		recorder := httptest.NewRecorder()
+
+		srv := echo.New()
+		srv.HideBanner = true
+		srv.HidePort = true
+
+		c := srv.NewContext(tc.request, recorder)
+		err := handler(c)
+
+		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 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)
+			}
+		}
+	}
+}
+
+func TestContext_Request(t *testing.T) {
+	request := httptest.NewRequest(http.MethodPost, "/", nil)
+	recorder := httptest.NewRecorder()
+	c := echo.New().NewContext(request, recorder)
+
+	ctx := Context{
+		echoCtx: c,
+	}
+
+	if !reflect.DeepEqual(ctx.Request(), c.Request()) {
+		t.Errorf("expected %v but got %v", ctx.Request(), c.Request())
+	}
+}
+
+func TestContext_FormData(t *testing.T) {
+	ctx := Context{
+		values: map[string][]string{
+			"foo": {"foo"},
+		},
+		files: map[string]string{
+			"foo.txt": "/foo.txt",
+		},
+	}
+
+	actual := ctx.FormData()
+	expect := &FormData{
+		values: ctx.values,
+		files:  ctx.files,
+	}
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %+v but got %+v", expect, actual)
+	}
+}
+
+func TestContext_GeneratePath(t *testing.T) {
+	ctx := Context{
+		dirPath: "/foo",
+	}
+
+	path := ctx.GeneratePath(".pdf")
+
+	if !strings.HasPrefix(path, ctx.dirPath) {
+		t.Errorf("expected '%s' to start with '%s'", path, ctx.dirPath)
+	}
+}
+
+func TestContext_AddOutputPaths(t *testing.T) {
+	for i, tc := range []struct {
+		ctx         *Context
+		path        string
+		expectCount int
+		expectErr   bool
+	}{
+		{
+			ctx:       &Context{cancelled: true},
+			expectErr: true,
+		},
+		{
+			ctx:       &Context{dirPath: "/foo"},
+			path:      "/bar/foo.txt",
+			expectErr: true,
+		},
+		{
+			ctx:         &Context{dirPath: "/foo"},
+			path:        "/foo/foo.txt",
+			expectCount: 1,
+		},
+	} {
+		err := tc.ctx.AddOutputPaths(tc.path)
+
+		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.ctx.outputPaths) != tc.expectCount {
+			t.Errorf("test %d: expected %d output paths but got %d", i, tc.expectCount, len(tc.ctx.outputPaths))
+		}
+	}
+}
+
+func TestContext_Log(t *testing.T) {
+	expect := zap.NewNop()
+	ctx := Context{logger: expect}
+	actual := ctx.Log()
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %v but got %v", expect, actual)
+	}
+}
+
+func TestContext_buildOutputFile(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       *Context
+		expectErr bool
+	}{
+		{
+			ctx:       &Context{cancelled: true},
+			expectErr: true,
+		},
+		{
+			ctx:       &Context{},
+			expectErr: true,
+		},
+		{
+			ctx: &Context{outputPaths: []string{"foo.txt"}},
+		},
+		{
+			ctx:       &Context{outputPaths: []string{"foo.txt", "foo.pdf"}},
+			expectErr: true,
+		},
+		{
+			ctx: &Context{
+				outputPaths: []string{
+					"/tests/test/testdata/api/sample1.txt",
+					"/tests/test/testdata/api/sample1.txt",
+				},
+			},
+		},
+	} {
+		dirPath, err := gotenberg.MkdirAll()
+		if err != nil {
+			t.Fatalf("%d: expected no erro but got: %v", i, err)
+		}
+
+		tc.ctx.dirPath = dirPath
+		tc.ctx.logger = zap.NewNop()
+
+		_, err = tc.ctx.buildOutputFile()
+
+		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)
+		}
+
+		err = os.RemoveAll(dirPath)
+		if err != nil {
+			t.Fatalf("%d: expected no erro but got: %v", i, err)
+		}
+	}
+}
+
+func TestMockContext_SetDirPath(t *testing.T) {
+	mock := &MockContext{&Context{}}
+	mock.SetDirPath("/foo")
+
+	actual := mock.dirPath
+	expect := "/foo"
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestMockContext_SetValues(t *testing.T) {
+	mock := &MockContext{&Context{}}
+	mock.SetValues(map[string][]string{
+		"foo": {"foo"},
+	})
+
+	actual := mock.values
+	expect := map[string][]string{
+		"foo": {"foo"},
+	}
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %+v but got: %+v", expect, actual)
+	}
+}
+
+func TestMockContext_SetFiles(t *testing.T) {
+	mock := &MockContext{&Context{}}
+	mock.SetFiles(map[string]string{
+		"foo": "/foo",
+	})
+
+	actual := mock.files
+	expect := map[string]string{
+		"foo": "/foo",
+	}
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %+v but got: %+v", expect, actual)
+	}
+}
+
+func TestMockContext_SetCancelled(t *testing.T) {
+	mock := &MockContext{&Context{}}
+	mock.SetCancelled(true)
+
+	actual := mock.cancelled
+
+	if !actual {
+		t.Errorf("expected %t but got %t", true, actual)
+	}
+}
+
+func TestMockContext_OutputPaths(t *testing.T) {
+	mock := MockContext{
+		&Context{
+			outputPaths: []string{"/foo"},
+		},
+	}
+
+	actual := mock.OutputPaths()
+	expect := []string{"/foo"}
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %+v but got: %+v", expect, actual)
+	}
+}

pkg/modules/api/doc.go

@@ -0,0 +1,3 @@
+// Package api provides a module which is an HTTP server. Other modules may
+// add multipart/form-data routes, middlewares, and health checks.
+package api

pkg/modules/api/errors.go

@@ -0,0 +1,77 @@
+package api
+
+// Credits: https://www.joeshaw.org/error-handling-in-go-http-applications.
+
+// HTTPError is an interface allowing to retrieve the HTTP details of an error.
+type HTTPError interface {
+	HTTPError() (int, string)
+}
+
+// SentinelHTTPError is the HTTP sidekick of an error.
+type SentinelHTTPError struct {
+	status  int
+	message string
+}
+
+// NewSentinelHTTPError creates a SentinelHTTPError. The message will be sent
+// as the response's body if returned from an handler, so make sure to not leak
+// sensible information.
+func NewSentinelHTTPError(status int, message string) SentinelHTTPError {
+	return SentinelHTTPError{
+		status:  status,
+		message: message,
+	}
+}
+
+// Error returns the message.
+func (err SentinelHTTPError) Error() string {
+	return err.message
+}
+
+// HTTPError returns the status and message.
+func (err SentinelHTTPError) HTTPError() (int, string) {
+	return err.status, err.message
+}
+
+// sentinelWrappedError contains both the error which will logged and the
+// sidekick SentinelHTTPError.
+type sentinelWrappedError struct {
+	error
+	sentinel SentinelHTTPError
+}
+
+func (w sentinelWrappedError) Is(err error) bool {
+	return w.sentinel == err
+}
+
+func (w sentinelWrappedError) HTTPError() (int, string) {
+	return w.sentinel.HTTPError()
+}
+
+// WrapError wraps the given error with a SentinelHTTPError. The wrapped error
+// will be displayed in a log, while the SentinelHTTPError will be sent in the
+// response.
+//
+//  return api.WrapError(
+//    // This first error will be logged.
+//    fmt.Errorf("my action: %w", err),
+//    // The HTTP error will be sent as a response.
+//    api.NewSentinelHTTPError(
+//      http.StatusForbidden,
+//      "Hey, you did something wrong!"
+//    ),
+//  )
+func WrapError(err error, sentinel SentinelHTTPError) error {
+	return sentinelWrappedError{
+		error:    err,
+		sentinel: sentinel,
+	}
+}
+
+// Interface guards.
+var (
+	_ error     = (*SentinelHTTPError)(nil)
+	_ HTTPError = (*SentinelHTTPError)(nil)
+	_ error     = (*sentinelWrappedError)(nil)
+	_ HTTPError = (*sentinelWrappedError)(nil)
+)

pkg/modules/api/errors_test.go

@@ -0,0 +1,108 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+	"reflect"
+	"testing"
+)
+
+func TestNewSentinelHTTPError(t *testing.T) {
+	actual := NewSentinelHTTPError(http.StatusInternalServerError, "foo")
+	expect := SentinelHTTPError{
+		status:  http.StatusInternalServerError,
+		message: "foo",
+	}
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %v but got %v", expect, actual)
+	}
+}
+
+func TestSentinelHTTPError_Error(t *testing.T) {
+	err := SentinelHTTPError{
+		message: "foo",
+	}
+
+	actual := err.Error()
+	expect := "foo"
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestSentinelHTTPError_HTTPError(t *testing.T) {
+	actualStatus, actualMessage := SentinelHTTPError{
+		status:  http.StatusInternalServerError,
+		message: "foo",
+	}.HTTPError()
+
+	expectStatus := http.StatusInternalServerError
+	expectMessage := "foo"
+
+	if actualStatus != expectStatus {
+		t.Errorf("expected %d but got %d", expectStatus, actualStatus)
+	}
+
+	if actualMessage != expectMessage {
+		t.Errorf("expected '%s' but got '%s'", expectMessage, actualMessage)
+	}
+}
+
+func TestSentinelWrappedError_Is(t *testing.T) {
+	errSentinel := SentinelHTTPError{}
+
+	err := sentinelWrappedError{
+		error:    errors.New("foo"),
+		sentinel: errSentinel,
+	}
+
+	if !err.Is(errSentinel) {
+		t.Error("expected true")
+	}
+}
+
+func TestSentinelWrappedError_HTTPError(t *testing.T) {
+	expectStatus, expectMessage := SentinelHTTPError{
+		status:  http.StatusInternalServerError,
+		message: "foo",
+	}.HTTPError()
+
+	actualStatus, actualMessage := sentinelWrappedError{
+		error: errors.New("foo"),
+		sentinel: SentinelHTTPError{
+			status:  http.StatusInternalServerError,
+			message: "foo",
+		},
+	}.HTTPError()
+
+	if actualStatus != expectStatus {
+		t.Errorf("expected %d but got %d", expectStatus, actualStatus)
+	}
+
+	if actualMessage != expectMessage {
+		t.Errorf("expected '%s' but got '%s'", expectMessage, actualMessage)
+	}
+}
+
+func TestWrapError(t *testing.T) {
+	errFoo := errors.New("foo")
+
+	expect := sentinelWrappedError{
+		error: errFoo,
+		sentinel: SentinelHTTPError{
+			status:  http.StatusInternalServerError,
+			message: "foo",
+		},
+	}
+
+	actual := WrapError(errFoo, SentinelHTTPError{
+		status:  http.StatusInternalServerError,
+		message: "foo",
+	})
+
+	if !reflect.DeepEqual(actual, expect) {
+		t.Errorf("expected %v but got %v", expect, actual)
+	}
+}

pkg/modules/api/formdata.go

@@ -0,0 +1,439 @@
+package api
+
+import (
+	"fmt"
+	"io/ioutil"
+	"net/http"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"go.uber.org/multierr"
+)
+
+// FormData is a helper for validating and hydrating values from a
+// "multipart/form-data" request.
+//
+//  form := ctx.FormData()
+type FormData struct {
+	values map[string][]string
+	files  map[string]string
+	errors error
+}
+
+// Validate returns nil or an error related to the FormData values, with a
+// SentinelHTTPError (status code 400, errors' details as message) wrapped
+// inside.
+//
+//  var foo string
+//
+//  err := ctx.FormData().
+//     MandatoryString("foo", &foo, "bar").
+//     Validate()
+func (form FormData) Validate() error {
+	if form.errors == nil {
+		return nil
+	}
+
+	return WrapError(
+		form.errors,
+		NewSentinelHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid form data: %s", form.errors)),
+	)
+}
+
+// String binds a form data value to a string variable.
+//
+//  var foo string
+//
+//  ctx.FormData().String("foo", &foo, "bar")
+func (form *FormData) String(key string, target *string, defaultValue string) *FormData {
+	return form.mustValue(key, target, defaultValue)
+}
+
+// MandatoryString binds a form data value to a string variable. It populates
+// an error if the value is empty or the "key" does not exist.
+//
+//  var foo string
+//
+//  ctx.FormData().MandatoryString("foo", &foo)
+func (form *FormData) MandatoryString(key string, target *string) *FormData {
+	return form.mustMandatoryValue(key, target)
+}
+
+// Bool binds a form data value to a bool variable. It populates an error if
+// the value is not bool.
+//
+//  var foo bool
+//
+//  ctx.FormData().Bool("foo", &foo, true)
+func (form *FormData) Bool(key string, target *bool, defaultValue bool) *FormData {
+	return form.mustValue(key, target, defaultValue)
+}
+
+// MandatoryBool binds a form data value to a bool variable. It populates an
+// error if the value is not bool, is empty, or the "key" does not exist.
+//
+//  var foo bool
+//
+//  ctx.FormData().MandatoryBool("foo", &foo)
+func (form *FormData) MandatoryBool(key string, target *bool) *FormData {
+	return form.mustMandatoryValue(key, target)
+}
+
+// Int binds a form data value to an int variable. It populates an error if the
+// value is not int.
+//
+//  var foo int
+//
+//  ctx.FormData().Int("foo", &foo, 2)
+func (form *FormData) Int(key string, target *int, defaultValue int) *FormData {
+	return form.mustValue(key, target, defaultValue)
+}
+
+// MandatoryInt binds a form data value to an int variable. It populates an
+// error if the value is not int, is empty, or the "key" does not exist.
+//
+//  var foo int
+//
+//  ctx.FormData().MandatoryInt("foo", &foo)
+func (form *FormData) MandatoryInt(key string, target *int) *FormData {
+	return form.mustMandatoryValue(key, target)
+}
+
+// Float64 binds a form data value to a float64 variable. It populates an error
+// if the value is not float64.
+//
+//  var foo float64
+//
+//  ctx.FormData().Float64("foo", &foo, 2.0)
+func (form *FormData) Float64(key string, target *float64, defaultValue float64) *FormData {
+	return form.mustValue(key, target, defaultValue)
+}
+
+// MandatoryFloat64 binds a form data value to a float64 variable. It populates
+// an error if the is not float64, is empty, or the "key" does not exist.
+//
+//  var foo float64
+//
+//  ctx.FormData().MandatoryFloat64("foo", &foo)
+func (form *FormData) MandatoryFloat64(key string, target *float64) *FormData {
+	return form.mustMandatoryValue(key, target)
+}
+
+// Duration binds a form data value to a time.Duration variable. It populates
+// an error if the form data value is not time.Duration.
+//
+//  var foo time.Duration
+//
+//  ctx.FormData().Duration("foo", &foo, time.Duration(2) * time.Second)
+func (form *FormData) Duration(key string, target *time.Duration, defaultValue time.Duration) *FormData {
+	return form.mustValue(key, target, defaultValue)
+}
+
+// MandatoryDuration binds a form data value to a time.Duration variable. It
+// populates an error if the value is not time.Duration, is empty, or the "key"
+// does not exist.
+//
+//  var foo time.Duration
+//
+//  ctx.FormData().MandatoryDuration("foo", &foo)
+func (form *FormData) MandatoryDuration(key string, target *time.Duration) *FormData {
+	return form.mustMandatoryValue(key, target)
+}
+
+// Custom helps to define a custom binding function for a form data value.
+//
+//  var foo map[string]string
+//
+//  ctx.FormData().Custom("foo", func(value string) error {
+//    if value == "" {
+//      foo = "bar"
+//
+//      return nil
+//    }
+//
+//    err := json.Unmarshal([]byte(value), &foo)
+//    if err != nil {
+//      return fmt.Errorf("unmarshal foo: %w", err)
+//    }
+//
+//    return nil
+//  })
+func (form *FormData) Custom(key string, assign func(value string) error) *FormData {
+	var value string
+	form.mustValue(key, &value, "")
+
+	err := assign(value)
+	if err != nil {
+		form.append(
+			fmt.Errorf("form value '%s' is invalid (got '%s', resulting to %w)", key, value, err),
+		)
+	}
+
+	return form
+}
+
+// MandatoryCustom helps to define a custom binding function for a form data
+// value. It populates an error if the value is empty or the "key" does not
+// exist.
+//
+//  var foo map[string]string
+//
+//  ctx.FormData().MandatoryCustom("foo", func(value string) error {
+//    err := json.Unmarshal([]byte(value), &foo)
+//    if err != nil {
+//      return fmt.Errorf("unmarshal foo: %w", err)
+//    }
+//
+//    return nil
+//  })
+func (form *FormData) MandatoryCustom(key string, assign func(value string) error) *FormData {
+	var value string
+	form.mustMandatoryValue(key, &value)
+
+	if value == "" {
+		return form
+	}
+
+	err := assign(value)
+	if err != nil {
+		form.append(
+			fmt.Errorf("form value '%s' is invalid (got '%s', resulting to %w)", key, value, err),
+		)
+	}
+
+	return form
+}
+
+// Path binds the absolute path of a form data file to a string variable.
+//
+//  var path string
+//
+//  ctx.FormData().Path("foo.txt", &path)
+func (form *FormData) Path(filename string, target *string) *FormData {
+	return form.path(filename, target)
+}
+
+// MandatoryPath binds the absolute path ofa  form data file to a string
+// variable. It populates an error if the file does not exist.
+//
+//  var path string
+//
+//  ctx.FormData().MandatoryPath("foo.txt", &path)
+func (form *FormData) MandatoryPath(filename string, target *string) *FormData {
+	return form.mandatoryPath(filename, target)
+}
+
+// Content binds the content of a form data file to a string variable.
+//
+//  var content string
+//
+//  ctx.FormData().Content("foo.txt", &content, "bar")
+func (form *FormData) Content(filename string, target *string, defaultValue string) *FormData {
+	var path string
+	form.path(filename, &path)
+
+	if path == "" {
+		*target = defaultValue
+
+		return form
+	}
+
+	return form.readFile(path, filename, target)
+}
+
+// MandatoryContent binds the content of a form data file to a string variable.
+// It populates an error if the file does not exist.
+//
+//  var content string
+//
+//  ctx.FormData().MandatoryContent("foo.txt", &content)
+func (form *FormData) MandatoryContent(filename string, target *string) *FormData {
+	var path string
+	form.mandatoryPath(filename, &path)
+
+	if path == "" {
+		return form
+	}
+
+	return form.readFile(path, filename, target)
+}
+
+// Paths binds the absolute paths of form data files, according to a list of
+// file extensions, to a string slice variable.
+//
+//  var paths []string
+//
+//  ctx.FormData().Paths([]string{".txt"}, &paths)
+func (form *FormData) Paths(extensions []string, target *[]string) *FormData {
+	return form.paths(extensions, target)
+}
+
+// MandatoryPaths binds the absolute paths of form data files, according to a
+// list of file extensions, to a string slice variable. It populates an error
+// if there is no file for given file extensions.
+//
+//  var paths []string
+//
+//  ctx.FormData().MandatoryPaths([]string{".txt"}, &paths)
+func (form *FormData) MandatoryPaths(extensions []string, target *[]string) *FormData {
+	form.paths(extensions, target)
+
+	if len(*target) > 0 {
+		return form
+	}
+
+	form.append(
+		fmt.Errorf("no form file found for extensions: %v", extensions),
+	)
+
+	return form
+}
+
+// paths binds the absolute paths of form data files, according to a list of
+// file extensions, to a string slice variable.
+func (form *FormData) paths(extensions []string, target *[]string) *FormData {
+	for filename, path := range form.files {
+		for _, ext := range extensions {
+			// See https://github.com/thecodingmachine/gotenberg/issues/228.
+			if strings.ToLower(filepath.Ext(filename)) == ext {
+				*target = append(*target, path)
+			}
+		}
+	}
+
+	// See https://github.com/thecodingmachine/gotenberg/issues/139.
+	sort.Strings(*target)
+
+	return form
+}
+
+// append adds an error to the list of errors.
+func (form *FormData) append(err error) {
+	form.errors = multierr.Append(form.errors, err)
+}
+
+// mustValue binds the target interface with a form data value. If the value is
+// empty or the "key" does not exist, it binds the default value. Currently,
+// only the string, bool, int, float64 and time.Duration types are bindable.
+func (form *FormData) mustValue(key string, target interface{}, defaultValue interface{}) *FormData {
+	val, ok := form.values[key]
+
+	if !ok || val[0] == "" {
+		switch t := (target).(type) {
+		case *string:
+			*t = defaultValue.(string)
+		case *bool:
+			*t = defaultValue.(bool)
+		case *int:
+			*t = defaultValue.(int)
+		case *float64:
+			*t = defaultValue.(float64)
+		case *time.Duration:
+			*t = defaultValue.(time.Duration)
+		default:
+			panic("target type not supported")
+		}
+
+		return form
+	}
+
+	return form.mustAssign(key, val[0], target)
+}
+
+// mustMandatoryValue binds the target interface with a form data value. It
+// populates an error if the value is empty or the "key" does not exist.
+// Currently, only the string, bool, int, float64 and time.Duration types are
+// bindable.
+func (form *FormData) mustMandatoryValue(key string, target interface{}) *FormData {
+	val, ok := form.values[key]
+
+	if !ok || val[0] == "" {
+		form.append(
+			fmt.Errorf("form value '%s' is required", key),
+		)
+
+		return form
+	}
+
+	form.mustAssign(key, val[0], target)
+
+	return form
+}
+
+// mustAssign parses the string value and tries to convert it to the target
+// interface real type. Currently, only the string, bool, int, float64 and
+// time.Duration types are bindable.
+func (form *FormData) mustAssign(key, value string, target interface{}) *FormData {
+	var err error
+
+	switch t := (target).(type) {
+	case *string:
+		*t = value
+	case *bool:
+		*t, err = strconv.ParseBool(value)
+	case *int:
+		*t, err = strconv.Atoi(value)
+	case *float64:
+		*t, err = strconv.ParseFloat(value, 64)
+	case *time.Duration:
+		*t, err = time.ParseDuration(value)
+	default:
+		panic("target type not supported")
+	}
+
+	if err != nil {
+		form.append(
+			fmt.Errorf("form value '%s' is invalid (got '%s', resulting to %w)", key, value, err),
+		)
+	}
+
+	return form
+}
+
+// path binds the absolute path of a form data file to a string variable.
+func (form *FormData) path(filename string, target *string) *FormData {
+	for name, path := range form.files {
+		if name == filename {
+			*target = path
+			return form
+		}
+	}
+
+	return form
+}
+
+// mandatoryPath binds the absolute path of a form data file to a string
+// variable. It populates an error if the file does not exist.
+func (form *FormData) mandatoryPath(filename string, target *string) *FormData {
+	form.path(filename, target)
+
+	if *target != "" {
+		return form
+	}
+
+	form.append(
+		fmt.Errorf("form file '%s' is required", filename),
+	)
+
+	return form
+}
+
+// readFile binds the content of a file to a string variable. It populates an
+// error if it fails to read the file content.
+func (form *FormData) readFile(path, filename string, target *string) *FormData {
+	b, err := ioutil.ReadFile(path)
+	if err != nil {
+		form.append(
+			fmt.Errorf("form file '%s' is invalid (%w)", filename, err),
+		)
+
+		return form
+	}
+
+	*target = string(b)
+
+	return form
+}

pkg/modules/api/middlewares.go

@@ -0,0 +1,576 @@
+package api
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/hashicorp/go-retryablehttp"
+	"github.com/labstack/echo/v4"
+	"go.uber.org/zap"
+)
+
+// httpErrorHandler is the centralized HTTP error handler. It parses the error,
+// returns either a response as "text/plain; charset=UTF-8" or, if a webhook
+// client exists in the echo.Context, sends a request to the webhook error URL
+// with a JSON body containing the trace, the status and the error message.
+func httpErrorHandler(traceHeader string) echo.HTTPErrorHandler {
+	return func(err error, c echo.Context) {
+		parseError := func(err error) (int, string) {
+			echoErr, ok := err.(*echo.HTTPError)
+			if ok {
+				return echoErr.Code, http.StatusText(echoErr.Code)
+			}
+
+			if errors.Is(err, context.DeadlineExceeded) {
+				return http.StatusServiceUnavailable, http.StatusText(http.StatusServiceUnavailable)
+			}
+
+			var httpErr HTTPError
+			if errors.As(err, &httpErr) {
+				return httpErr.HTTPError()
+			}
+
+			// Default 500 status code.
+			return http.StatusInternalServerError, http.StatusText(http.StatusInternalServerError)
+		}
+
+		status, message := parseError(err)
+
+		logger := c.Get("logger").(*zap.Logger)
+		clientOrNil := c.Get("webhookClient")
+
+		// No webhook client, meaning we can send the error as a response.
+		if clientOrNil == nil {
+			c.Response().Header().Add(echo.HeaderContentType, echo.MIMETextPlainCharsetUTF8)
+
+			err = c.String(status, message)
+
+			if err != nil {
+				logger.Error(fmt.Sprintf("send error response: %s", err.Error()))
+			}
+
+			return
+		}
+
+		// We have to send the error to the webhook.
+		client := clientOrNil.(*webhookClient)
+
+		body := struct {
+			Status  int    `json:"status"`
+			Message string `json:"message"`
+		}{
+			Status:  status,
+			Message: message,
+		}
+
+		b, err := json.Marshal(body)
+		if err != nil {
+			logger.Error(fmt.Sprintf("marshal JSON: %s", err.Error()))
+
+			return
+		}
+
+		headers := map[string]string{
+			echo.HeaderContentType: echo.MIMEApplicationJSONCharsetUTF8,
+			traceHeader:            c.Get("trace").(string),
+		}
+
+		err = client.send(bytes.NewReader(b), headers, true)
+		if err != nil {
+			logger.Error(fmt.Sprintf("send error response to webhook: %s", err.Error()))
+		}
+	}
+}
+
+// latencyMiddleware sets the start time in the echo.Context under "startTime".
+// Its value will be used later to calculate a request latency.
+//
+//  startTime := c.Get("startTime").(time.Time)
+func latencyMiddleware() echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			// First piece for calculating the latency.
+			startTime := time.Now()
+			c.Set("startTime", startTime)
+
+			// Call the next middleware in the chain.
+			return next(c)
+		}
+	}
+}
+
+// rootPathMiddleware sets the root path in the echo.Context under "rootPath".
+// Its value may be used to skip a middleware execution based on a request
+// URI.
+//
+//  rootPath := c.Get("rootPath").(string)
+//  healthURI := fmt.Sprintf("%shealth", rootPath)
+//
+//  // Skip the middleware if health check URI.
+//  if c.Request().RequestURI == healthURI {
+//    // Call the next middleware in the chain.
+//    return next(c)
+//  }
+func rootPathMiddleware(rootPath string) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			c.Set("rootPath", rootPath)
+
+			// Call the next middleware in the chain.
+			return next(c)
+		}
+	}
+}
+
+// traceMiddleware sets the request identifier in the echo.Context under
+// "trace". Its value is either retrieved from the trace header or generated if
+// the header is not present / its value is empty.
+//
+//  trace := c.Get("trace").(string)
+func traceMiddleware(header string) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			// Get or create the request identifier.
+			trace := c.Request().Header.Get(header)
+
+			if trace == "" {
+				trace = uuid.New().String()
+			}
+
+			c.Set("trace", trace)
+			c.Response().Header().Add(header, trace)
+
+			// Call the next middleware in the chain.
+			return next(c)
+		}
+	}
+}
+
+// loggerMiddleware sets the logger in the echo.Context under "logger" and logs
+// a request result (but does not log a webhook call result, which is the job
+// of the webhookClient).
+//
+//  logger := c.Get("logger").(*zap.Logger)
+func loggerMiddleware(logger *zap.Logger, skipHealthRouteLogging bool) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			startTime := c.Get("startTime").(time.Time)
+			trace := c.Get("trace").(string)
+
+			// Create the request logger and add it to our locals.
+			reqLogger := logger.With(zap.String("trace", trace))
+			c.Set("logger", reqLogger)
+
+			// Call the next middleware in the chain.
+			err := next(c)
+			if err != nil {
+				c.Error(err)
+			}
+
+			if skipHealthRouteLogging {
+				rootPath := c.Get("rootPath").(string)
+				healthURI := fmt.Sprintf("%shealth", rootPath)
+
+				if c.Request().RequestURI == healthURI {
+					return nil
+				}
+			}
+
+			// Last piece for calculating the latency.
+			finishTime := time.Now()
+
+			// Now, let's log!
+			fields := make([]zap.Field, 12)
+			fields[0] = zap.String("remote_ip", c.RealIP())
+			fields[1] = zap.String("host", c.Request().Host)
+			fields[2] = zap.String("uri", c.Request().RequestURI)
+			fields[3] = zap.String("method", c.Request().Method)
+			fields[4] = zap.String("path", func() string {
+				path := c.Request().URL.Path
+
+				if path == "" {
+					path = "/"
+				}
+
+				return path
+			}())
+			fields[5] = zap.String("referer", c.Request().Referer())
+			fields[6] = zap.String("user_agent", c.Request().UserAgent())
+			fields[7] = zap.Int("status", c.Response().Status)
+			fields[8] = zap.Int64("latency", int64(finishTime.Sub(startTime)))
+			fields[9] = zap.String("latency_human", finishTime.Sub(startTime).String())
+			fields[10] = zap.Int64("bytes_in", c.Request().ContentLength)
+			fields[11] = zap.Int64("bytes_out", c.Response().Size)
+
+			if err != nil {
+				reqLogger.Error(err.Error(), fields...)
+			} else {
+				reqLogger.Info("request handled", fields...)
+			}
+
+			return nil
+		}
+	}
+}
+
+type contextMiddlewareConfig struct {
+	traceHeader string
+	timeout     struct {
+		process time.Duration
+		write   time.Duration
+	}
+	webhook struct {
+		allowList      *regexp.Regexp
+		denyList       *regexp.Regexp
+		errorAllowList *regexp.Regexp
+		errorDenyList  *regexp.Regexp
+		maxRetry       int
+		retryMinWait   time.Duration
+		retryMaxWait   time.Duration
+		disable        bool
+	}
+}
+
+// contextMiddleware handles the result of a "multipart/form-data" request. If
+// a webhook URL is present in the headers, exit early and process the result
+// in a goroutine.
+func contextMiddleware(cfg contextMiddlewareConfig) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			webhookURL := c.Request().Header.Get("Gotenberg-Webhook-Url")
+			logger := c.Get("logger").(*zap.Logger).With(zap.Bool("webhook", webhookURL != ""))
+
+			// We create a context with a timeout so that underlying processes are
+			// able to stop early and handle correctly a timeout scenario.
+			ctx, cancel, err := newContext(c, logger, cfg.timeout.process)
+			if err != nil {
+				cancel()
+
+				return fmt.Errorf("create request context: %w", err)
+			}
+			c.Set("context", ctx)
+
+			// Helper function for retrieving/creating the output filename.
+			outputFilename := func(outputPath string) string {
+				filename := c.Request().Header.Get("Gotenberg-Output-Filename")
+
+				if filename == "" {
+					return filepath.Base(outputPath)
+				}
+
+				return fmt.Sprintf("%s%s", filename, filepath.Ext(outputPath))
+			}
+
+			if webhookURL == "" {
+				defer cancel()
+
+				// No webhook URL, call the next middleware in the chain.
+				err := next(c)
+
+				if err != nil {
+					return err
+				}
+
+				// No error, let's build the output file.
+				outputPath, err := ctx.buildOutputFile()
+				if err != nil {
+					return fmt.Errorf("build output file: %w", err)
+				}
+
+				// Send the output file.
+				err = c.Attachment(outputPath, outputFilename(outputPath))
+				if err != nil {
+					return fmt.Errorf("send response: %w", err)
+				}
+
+				return nil
+			}
+
+			// Ok, we got a webhook URL.
+
+			if cfg.webhook.disable {
+				// The client requested the webhook feature, but it has been
+				// disabled. Let's tell the client about that.
+				cancel()
+
+				return WrapError(
+					errors.New("webhook feature requested but it is disabled"),
+					NewSentinelHTTPError(http.StatusForbidden, "Invalid 'Gotenberg-Webhook-Url' header: feature is disabled"),
+				)
+			}
+
+			// Do we have a webhook error URL in case of... error?
+			webhookErrorURL := c.Request().Header.Get("Gotenberg-Webhook-Error-Url")
+
+			if webhookErrorURL == "" {
+				cancel()
+
+				return WrapError(
+					errors.New("empty webhook error URL"),
+					NewSentinelHTTPError(http.StatusBadRequest, "Invalid 'Gotenberg-Webhook-Error-Url' header: empty value or header not provided"),
+				)
+			}
+
+			// Let's check if the webhook URLs are acceptable according to our
+			// allowed/denied lists.
+			filter := func(URL, header string, allowList, denyList *regexp.Regexp) error {
+				if !allowList.MatchString(URL) {
+					return WrapError(
+						fmt.Errorf("'%s' does not match the expression from the allowed list", URL),
+						NewSentinelHTTPError(
+							http.StatusForbidden,
+							fmt.Sprintf("Invalid '%s' header value: '%s' does not match the authorized URLs", header, URL),
+						),
+					)
+				}
+
+				if denyList.String() != "" && denyList.MatchString(URL) {
+					return WrapError(
+						fmt.Errorf("'%s' matches the expression from the denied list", URL),
+						NewSentinelHTTPError(
+							http.StatusForbidden,
+							fmt.Sprintf("Invalid '%s' header value: '%s' does not match the authorized URLs", header, URL),
+						),
+					)
+				}
+
+				return nil
+			}
+
+			err = filter(webhookURL, "Gotenberg-Webhook-Url", cfg.webhook.allowList, cfg.webhook.denyList)
+			if err != nil {
+				cancel()
+
+				return fmt.Errorf("filter webhook URL: %w", err)
+			}
+
+			err = filter(webhookErrorURL, "Gotenberg-Webhook-Error-Url", cfg.webhook.errorAllowList, cfg.webhook.errorDenyList)
+			if err != nil {
+				cancel()
+
+				return fmt.Errorf("filter webhook error URL: %w", err)
+			}
+
+			// Let's check the HTTP methods for calling the webhook URLs.
+			methodFromHeader := func(header string) (string, error) {
+				method := c.Request().Header.Get(header)
+
+				if method == "" {
+					return http.MethodPost, nil
+				}
+
+				method = strings.ToUpper(method)
+
+				switch method {
+				case http.MethodPost:
+					return method, nil
+				case http.MethodPatch:
+					return method, nil
+				case http.MethodPut:
+					return method, nil
+				}
+
+				return "", WrapError(
+					fmt.Errorf("webhook method '%s' is not '%s', '%s' or '%s'", method, http.MethodPost, http.MethodPatch, http.MethodPut),
+					NewSentinelHTTPError(
+						http.StatusBadRequest,
+						fmt.Sprintf("Invalid '%s' header value: expected '%s', '%s' or '%s', but got '%s'", header, http.MethodPost, http.MethodPatch, http.MethodPut, method),
+					),
+				)
+			}
+
+			webhookMethod, err := methodFromHeader("Gotenberg-Webhook-Method")
+			if err != nil {
+				cancel()
+
+				return fmt.Errorf("get method to use for webhook: %w", err)
+			}
+
+			webhookErrorMethod, err := methodFromHeader("Gotenberg-Webhook-Error-Method")
+			if err != nil {
+				cancel()
+
+				return fmt.Errorf("get method to use for webhook error: %w", err)
+			}
+
+			// What about extra HTTP headers?
+			var extraHTTPHeaders map[string]string
+
+			extraHTTPHeadersJSON := c.Request().Header.Get("Gotenberg-Webhook-Extra-Http-Headers")
+			if extraHTTPHeadersJSON != "" {
+				err = json.Unmarshal([]byte(extraHTTPHeadersJSON), &extraHTTPHeaders)
+				if err != nil {
+					cancel()
+
+					return WrapError(
+						fmt.Errorf("unmarshal webhook extra HTTP headers: %w", err),
+						NewSentinelHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid 'Gotenberg-Webhook-Extra-Http-Headers' header value: %s", err.Error())),
+					)
+				}
+			}
+
+			client := &webhookClient{
+				url:              webhookURL,
+				method:           webhookMethod,
+				errorURL:         webhookErrorURL,
+				errorMethod:      webhookErrorMethod,
+				extraHTTPHeaders: extraHTTPHeaders,
+				startTime:        c.Get("startTime").(time.Time),
+
+				client: &retryablehttp.Client{
+					HTTPClient: &http.Client{
+						Timeout: cfg.timeout.write,
+					},
+					RetryMax:     cfg.webhook.maxRetry,
+					RetryWaitMin: cfg.webhook.retryMinWait,
+					RetryWaitMax: cfg.webhook.retryMaxWait,
+					Logger: leveledLogger{
+						logger: logger,
+					},
+					CheckRetry: retryablehttp.DefaultRetryPolicy,
+					Backoff:    retryablehttp.DefaultBackoff,
+				},
+				logger: logger,
+			}
+
+			c.Set("webhookClient", client)
+
+			// As a webhook URL has been given, we handle the request in a
+			// goroutine and return immediately.
+			go func() {
+				defer cancel()
+
+				// Call the next middleware in the chain.
+				err := next(c)
+
+				if err != nil {
+					// The process failed for whatever reason. Let's send the
+					// details to the webhook.
+					ctx.Log().Error(err.Error())
+					c.Error(err)
+
+					return
+				}
+
+				// No error, let's get build the output file.
+				outputPath, err := ctx.buildOutputFile()
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("build output file: %s", err))
+					c.Error(err)
+
+					return
+				}
+
+				outputFile, err := os.Open(outputPath)
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("open output file: %s", err))
+					c.Error(err)
+
+					return
+				}
+
+				defer func() {
+					err := outputFile.Close()
+					if err != nil {
+						ctx.Log().Error(fmt.Sprintf("close output file: %s", err))
+					}
+				}()
+
+				fileHeader := make([]byte, 512)
+				_, err = outputFile.Read(fileHeader)
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("read header of output file: %s", err))
+					c.Error(err)
+
+					return
+				}
+
+				fileStat, err := outputFile.Stat()
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("get stat from output file: %s", err))
+					c.Error(err)
+
+					return
+				}
+
+				_, err = outputFile.Seek(0, 0)
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("reset output file reader: %s", err))
+					c.Error(err)
+
+					return
+				}
+
+				headers := map[string]string{
+					echo.HeaderContentDisposition: fmt.Sprintf("attachement; filename=%q", outputFilename(outputPath)),
+					echo.HeaderContentType:        http.DetectContentType(fileHeader),
+					echo.HeaderContentLength:      strconv.FormatInt(fileStat.Size(), 10),
+					cfg.traceHeader:               c.Get("trace").(string),
+				}
+
+				// Send the output file to the webhook.
+				err = client.send(bufio.NewReader(outputFile), headers, false)
+				if err != nil {
+					ctx.Log().Error(fmt.Sprintf("send output file to webhook: %s", err))
+					c.Error(err)
+				}
+			}()
+
+			return c.NoContent(http.StatusNoContent)
+		}
+	}
+}
+
+// timeoutMiddleware manages hard timeout scenarios, i.e., when a route handler
+// fails to timeout as expected.
+func timeoutMiddleware(hardTimeout time.Duration) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			logger := c.Get("logger").(*zap.Logger)
+
+			// Define a hard timeout if the route handler fails to timeout as
+			// expected.
+			hardTimeoutCtx, hardTimeoutCancel := context.WithTimeout(
+				context.Background(),
+				hardTimeout,
+			)
+			defer hardTimeoutCancel()
+
+			errChan := make(chan error, 1)
+
+			go func() {
+				// In case of hard timeout, a panic may occur.
+				// This deferred function allows us to recover from such scenarios.
+				defer func() {
+					if r := recover(); r != nil {
+						logger.Debug(fmt.Sprintf("recovering from a panic (possible cause being a hard timeout): %s", r))
+					}
+				}()
+
+				// Call the next middleware in the chain.
+				errChan <- next(c)
+			}()
+
+			select {
+			case err := <-errChan:
+				return err
+			case <-hardTimeoutCtx.Done():
+				logger.Debug("hard timeout as the route handler did not timeout as expected")
+
+				return fmt.Errorf("hard timeout: %w", hardTimeoutCtx.Err())
+			}
+		}
+	}
+}

pkg/modules/api/webhook.go

@@ -0,0 +1,139 @@
+package api
+
+import (
+	"fmt"
+	"io"
+	"strconv"
+	"time"
+
+	"github.com/hashicorp/go-retryablehttp"
+	"github.com/labstack/echo/v4"
+	"go.uber.org/zap"
+)
+
+// webhookClient gathers all the data required to send a request to a webhook.
+type webhookClient struct {
+	url              string
+	method           string
+	errorURL         string
+	errorMethod      string
+	extraHTTPHeaders map[string]string
+	startTime        time.Time
+
+	client *retryablehttp.Client
+	logger *zap.Logger
+}
+
+// send call the webhook either to send the success response or the error response.
+func (webhook webhookClient) send(body io.Reader, headers map[string]string, erroed bool) error {
+	URL := webhook.url
+	if erroed {
+		URL = webhook.errorURL
+	}
+
+	method := webhook.method
+	if erroed {
+		method = webhook.errorMethod
+	}
+
+	req, err := retryablehttp.NewRequest(method, URL, body)
+	if err != nil {
+		return fmt.Errorf("create '%s' request to '%s': %w", method, URL, err)
+	}
+
+	req.Header.Set("User-Agent", "Gotenberg")
+
+	// Extra HTTP headers are the custom headers from the user.
+	for key, value := range webhook.extraHTTPHeaders {
+		req.Header.Set(key, value)
+	}
+
+	// Middleware caller's headers > extra HTTP headers from the user.
+
+	contentLength, ok := headers[echo.HeaderContentLength]
+	if ok {
+		// Golang "http" package should automatically calculate the size of the
+		// body. But, when using a buffered file reader, it does not work.
+		// Worse, the "Content-Length" header is also removed. Therefore, in
+		// order to keep this valuable information, we have to trust the caller
+		// by reading the value of the "Content-Length" entry and set it as the
+		// content length of the request. It's kinda sub-optimal, but hey, at
+		// least it works.
+
+		bodySize, err := strconv.ParseInt(contentLength, 10, 64)
+
+		if err != nil {
+			return fmt.Errorf("parse content length entry: %w", err)
+		}
+
+		req.ContentLength = bodySize
+	}
+
+	for key, value := range headers {
+		req.Header.Set(key, value)
+	}
+
+	resp, err := webhook.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("send '%s' request to '%s': %w", method, URL, err)
+	}
+
+	defer func() {
+		err := resp.Body.Close()
+		if err != nil {
+			webhook.logger.Error(fmt.Sprintf("close response body from '%s': %s", URL, err))
+		}
+	}()
+
+	// Last piece for calculating the latency.
+	finishTime := time.Now()
+
+	// Now let's log!
+	fields := make([]zap.Field, 5)
+	fields[0] = zap.String("webhook_url", URL)
+	fields[1] = zap.String("method", method)
+	fields[2] = zap.Int64("latency", int64(finishTime.Sub(webhook.startTime)))
+	fields[3] = zap.String("latency_human", finishTime.Sub(webhook.startTime).String())
+	fields[4] = zap.Int64("bytes_out", req.ContentLength)
+
+	if erroed {
+		webhook.logger.Warn("request to webhook with error details handled", fields...)
+
+		return nil
+	}
+
+	webhook.logger.Info("request to webhook handled", fields...)
+
+	return nil
+}
+
+// leveledLogger is wrapper around a zap.Logger which is used by the
+// retryablehttp.Client.
+type leveledLogger struct {
+	logger *zap.Logger
+}
+
+// Error logs a message at error level using the wrapped zap.Logger.
+func (leveled leveledLogger) Error(msg string, keysAndValues ...interface{}) {
+	leveled.logger.Error(fmt.Sprintf("%s: %+v", msg, keysAndValues))
+}
+
+// Warn logs a message at warning level using the wrapped zap.Logger.
+func (leveled leveledLogger) Warn(msg string, keysAndValues ...interface{}) {
+	leveled.logger.Warn(fmt.Sprintf("%s: %+v", msg, keysAndValues))
+}
+
+// Info logs a message at info level using the wrapped zap.Logger.
+func (leveled leveledLogger) Info(msg string, keysAndValues ...interface{}) {
+	leveled.logger.Info(fmt.Sprintf("%s: %+v", msg, keysAndValues))
+}
+
+// Debug logs a message at debug level using the wrapped zap.Logger.
+func (leveled leveledLogger) Debug(msg string, keysAndValues ...interface{}) {
+	leveled.logger.Debug(fmt.Sprintf("%s: %+v", msg, keysAndValues))
+}
+
+// Interface guards.
+var (
+	_ retryablehttp.LeveledLogger = (*leveledLogger)(nil)
+)

pkg/modules/api/webhook_test.go

@@ -0,0 +1,23 @@
+package api
+
+import (
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+func TestLeveledLogger_Error(t *testing.T) {
+	leveledLogger{logger: zap.NewNop()}.Error("foo")
+}
+
+func TestLeveledLogger_Warn(t *testing.T) {
+	leveledLogger{logger: zap.NewNop()}.Warn("foo")
+}
+
+func TestLeveledLogger_Info(t *testing.T) {
+	leveledLogger{logger: zap.NewNop()}.Info("foo")
+}
+
+func TestLeveledLogger_Debug(t *testing.T) {
+	leveledLogger{logger: zap.NewNop()}.Debug("foo")
+}

pkg/modules/chromium/chromium.go

@@ -0,0 +1,477 @@
+package chromium
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/chromedp/cdproto/network"
+	"github.com/chromedp/cdproto/page"
+	"github.com/chromedp/chromedp"
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	flag "github.com/spf13/pflag"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(Chromium{})
+}
+
+var (
+	// ErrURLNotAuthorized happens if a URL is not acceptable according to the
+	// allowed/denied lists.
+	ErrURLNotAuthorized = errors.New("URL not authorized")
+
+	// ErrInvalidPrinterSettings happens if the Options have one or more
+	// aberrant values.
+	ErrInvalidPrinterSettings = errors.New("invalid printer settings")
+
+	// ErrPageRangesSyntaxError happens if the Options have an invalid page
+	// ranges.
+	ErrPageRangesSyntaxError = errors.New("page ranges syntax error")
+
+	// ErrRpccMessageTooLarge happens when the messages received by
+	// ChromeDevTools are larger than 100 MB.
+	ErrRpccMessageTooLarge = errors.New("rpcc message too large")
+)
+
+// Chromium is a module which provides both an API and routes for converting
+// HTML document to PDF.
+type Chromium struct {
+	binPath                 string
+	engine                  gotenberg.PDFEngine
+	userAgent               string
+	incognito               bool
+	ignoreCertificateErrors bool
+	allowList               *regexp.Regexp
+	denyList                *regexp.Regexp
+	disableRoutes           bool
+}
+
+// Options are the available options for converting HTML document to PDF.
+type Options struct {
+	// WaitDelay is the duration to wait when loading an HTML document before
+	// converting it to PDF.
+	// Optional.
+	WaitDelay time.Duration
+
+	// WaitWindowStatus is the window.status value to wait for before
+	// converting an HTML document to PDF.
+	// Optional.
+	WaitWindowStatus string
+
+	// ExtraHTTPHeaders are the HTTP headers to send by Chromium while loading
+	// the HTML document.
+	// Optional.
+	ExtraHTTPHeaders map[string]string
+
+	// Landscape sets the paper orientation.
+	// Optional.
+	Landscape bool
+
+	// PrintBackground prints the background graphics.
+	// Optional.
+	PrintBackground bool
+
+	// Scale is the scale of the page rendering.
+	// Optional.
+	Scale float64
+
+	// PaperWidth is the paper width, in inches.
+	// Optional.
+	PaperWidth float64
+
+	// PaperHeight is the paper height, in inches.
+	// Optional.
+	PaperHeight float64
+
+	// MarginTop is the top margin, in inches.
+	// Optional.
+	MarginTop float64
+
+	// MarginBottom is the bottom margin, in inches.
+	// Optional.
+	MarginBottom float64
+
+	// MarginLeft is the left margin, in inches.
+	// Optional.
+	MarginLeft float64
+
+	// MarginRight is the right margin, in inches.
+	// Optional.
+	MarginRight float64
+
+	// Page ranges to print, e.g., '1-5, 8, 11-13'. Empty means all pages.
+	// Optional.
+	PageRanges string
+
+	// HeaderTemplate is the HTML template of the header. It should be valid
+	// HTML  markup with following classes used to inject printing values into
+	// them:
+	// - date: formatted print date
+	// - title: document title
+	// - url: document location
+	// - pageNumber: current page number
+	// - totalPages: total pages in the document
+	// For example, <span class=title></span> would generate span containing
+	// the title.
+	// Optional.
+	HeaderTemplate string
+
+	// FooterTemplate is the HTML template of the footer. It should use the
+	// same format as the HeaderTemplate.
+	// Optional.
+	FooterTemplate string
+
+	// PreferCSSPageSize defines whether to prefer page size as defined by CSS.
+	// If false, the content will be scaled to fit the paper size.
+	// Optional.
+	PreferCSSPageSize bool
+}
+
+// DefaultOptions returns the default values for Options.
+func DefaultOptions() Options {
+	return Options{
+		WaitDelay:         0,
+		WaitWindowStatus:  "",
+		ExtraHTTPHeaders:  nil,
+		Landscape:         false,
+		PrintBackground:   false,
+		Scale:             1.0,
+		PaperWidth:        8.5,
+		PaperHeight:       11,
+		MarginTop:         0.39,
+		MarginBottom:      0.39,
+		MarginLeft:        0.39,
+		MarginRight:       0.39,
+		PageRanges:        "",
+		HeaderTemplate:    "<html><head></head><body></body></html>",
+		FooterTemplate:    "<html><head></head><body></body></html>",
+		PreferCSSPageSize: false,
+	}
+}
+
+// API helps to interact with Chromium for converting HTML documents to PDF.
+type API interface {
+	PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, options Options) error
+}
+
+// Provider is a module interface which exposes a method for creating an API
+// for other modules.
+//
+//	func (m *YourModule) Provision(ctx *gotenberg.Context) error {
+//		provider, _ := ctx.Module(new(chromium.Provider))
+//		chromium, _ := provider.(chromium.Provider).Chromium()
+//	}
+type Provider interface {
+	Chromium() (API, error)
+}
+
+// Descriptor returns a Chromium's module descriptor.
+func (mod Chromium) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "chromium",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("chromium", flag.ExitOnError)
+			fs.String("chromium-user-agent", "", "Override the default User-Agent header")
+			fs.Bool("chromium-incognito", false, "Start Chromium with incognito mode")
+			fs.Bool("chromium-ignore-certificate-errors", false, "Ignore the certificate errors")
+			fs.String("chromium-allow-list", "", "Set the allowed URLs for Chromium using a regular expression")
+			fs.String("chromium-deny-list", "", "Set the denied URLs for Chromium using a regular expression")
+			fs.Bool("chromium-disable-routes", false, "Disable the routes")
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(Chromium) },
+	}
+}
+
+// Provision sets the module properties.
+func (mod *Chromium) Provision(ctx *gotenberg.Context) error {
+	flags := ctx.ParsedFlags()
+	mod.ignoreCertificateErrors = flags.MustBool("chromium-ignore-certificate-errors")
+	mod.allowList = flags.MustRegexp("chromium-allow-list")
+	mod.denyList = flags.MustRegexp("chromium-deny-list")
+	mod.disableRoutes = flags.MustBool("chromium-disable-routes")
+
+	binPath, ok := os.LookupEnv("CHROMIUM_BIN_PATH")
+	if !ok {
+		return errors.New("CHROMIUM_BIN_PATH environment variable is not set")
+	}
+
+	mod.binPath = binPath
+
+	provider, err := ctx.Module(new(gotenberg.PDFEngineProvider))
+	if err != nil {
+		return fmt.Errorf("get PDF engine provider: %w", err)
+	}
+
+	engine, err := provider.(gotenberg.PDFEngineProvider).PDFEngine()
+	if err != nil {
+		return fmt.Errorf("get PDF engine: %w", err)
+	}
+
+	mod.engine = engine
+
+	return nil
+}
+
+// Validate validates the module properties.
+func (mod Chromium) Validate() error {
+	_, err := os.Stat(mod.binPath)
+	if os.IsNotExist(err) {
+		return fmt.Errorf("chromium binary path does not exist: %w", err)
+	}
+
+	return nil
+}
+
+// Chromium returns an API for interacting with Chromium for converting HTML
+// documents to PDF.
+func (mod Chromium) Chromium() (API, error) {
+	return mod, nil
+}
+
+// Routes returns the API routes.
+func (mod Chromium) Routes() ([]api.MultipartFormDataRoute, error) {
+	if mod.disableRoutes {
+		return nil, nil
+	}
+
+	return []api.MultipartFormDataRoute{
+		convertURLRoute(mod, mod.engine),
+		convertHTMLRoute(mod, mod.engine),
+		convertMarkdownRoute(mod, mod.engine),
+	}, nil
+}
+
+// PDF converts a URL to PDF. It creates a dedicated Chromium instance.
+// Substantial calls to this method may increase CPU and memory usage
+// drastically. In such a scenario, the given context may also be done before
+// the end of the conversion.
+func (mod Chromium) PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, options Options) error {
+	userProfileDirPath := gotenberg.NewDirPath()
+
+	args := append(chromedp.DefaultExecAllocatorOptions[:],
+		chromedp.ExecPath(mod.binPath),
+		chromedp.NoSandbox,
+		// See:
+		// https://github.com/puppeteer/puppeteer/issues/661
+		// https://github.com/puppeteer/puppeteer/issues/2410
+		chromedp.Flag("font-render-hinting", "none"),
+		chromedp.UserDataDir(userProfileDirPath),
+	)
+
+	if mod.userAgent != "" {
+		args = append(args, chromedp.UserAgent(mod.userAgent))
+	}
+
+	if mod.incognito {
+		args = append(args, chromedp.Flag("incognito", mod.incognito))
+	}
+
+	if mod.ignoreCertificateErrors {
+		args = append(args, chromedp.IgnoreCertErrors)
+	}
+
+	allocatorCtx, cancel := chromedp.NewExecAllocator(ctx, args...)
+	defer cancel()
+
+	taskCtx, cancel := chromedp.NewContext(allocatorCtx)
+	defer cancel()
+
+	if !mod.allowList.MatchString(URL) {
+		return fmt.Errorf("'%s' does not match the expression from the allowed list: %w", URL, ErrURLNotAuthorized)
+	}
+
+	if mod.denyList.String() != "" && mod.denyList.MatchString(URL) {
+		return fmt.Errorf("'%s' matches the expression from the denied list: %w", URL, ErrURLNotAuthorized)
+	}
+
+	printToPDF := func(URL string, options Options, result *[]byte) chromedp.Tasks {
+		return chromedp.Tasks{
+			network.Enable(),
+			chromedp.ActionFunc(func(ctx context.Context) error {
+				if len(options.ExtraHTTPHeaders) == 0 {
+					logger.Debug("no extra HTTP headers")
+
+					return nil
+				}
+
+				logger.Debug(fmt.Sprintf("extra HTTP headers: %+v", options.ExtraHTTPHeaders))
+
+				headers := make(network.Headers, len(options.ExtraHTTPHeaders))
+				for key, value := range options.ExtraHTTPHeaders {
+					headers[key] = value
+				}
+
+				err := network.SetExtraHTTPHeaders(headers).Do(ctx)
+				if err == nil {
+					return nil
+				}
+
+				return fmt.Errorf("set extra HTTP headers: %w", err)
+			}),
+			chromedp.ActionFunc(func(ctx context.Context) error {
+				logger.Debug(fmt.Sprintf("navigate to '%s'", URL))
+
+				_, _, _, err := page.Navigate(URL).Do(ctx)
+				if err != nil {
+					return fmt.Errorf("navigate to '%s': %w", URL, err)
+				}
+
+				err = runBatch(
+					ctx,
+					waitForEventDomContentEventFired(ctx, logger),
+					waitForEventLoadEventFired(ctx, logger),
+					waitForEventNetworkIdle(ctx, logger),
+					waitForEventLoadingFinished(ctx, logger),
+				)
+
+				if err == nil {
+					return nil
+				}
+
+				return fmt.Errorf("wait for events: %w", err)
+			}),
+			chromedp.ActionFunc(func(ctx context.Context) error {
+				if options.WaitDelay > 0 {
+					// We wait for a given amount of time so that JavaScript
+					// scripts have a chance to finish before printing the page
+					// to PDF.
+					logger.Debug(fmt.Sprintf("wait '%s' before print", options.WaitDelay))
+
+					select {
+					case <-ctx.Done():
+						return fmt.Errorf("wait delay: %w", ctx.Err())
+					case <-time.After(options.WaitDelay):
+						return nil
+					}
+				}
+
+				return nil
+			}),
+			chromedp.ActionFunc(func(ctx context.Context) error {
+				if options.WaitWindowStatus == "" {
+					return nil
+				}
+
+				// We wait until the evaluation of
+				// "window.status === options.WaitWindowStatus" is true or
+				// until the context is done.
+				logger.Debug(fmt.Sprintf("wait for window.status === '%s' before print", options.WaitWindowStatus))
+
+				ticker := time.NewTicker(time.Duration(100) * time.Millisecond)
+
+				for {
+					select {
+					case <-ctx.Done():
+						ticker.Stop()
+
+						return fmt.Errorf("wait for window.status === '%s': %w", options.WaitWindowStatus, ctx.Err())
+					case <-ticker.C:
+						var ok bool
+
+						evaluate := chromedp.Evaluate(fmt.Sprintf("window.status === '%s'", options.WaitWindowStatus), &ok)
+						err := evaluate.Do(ctx)
+
+						if err != nil {
+							return fmt.Errorf("evaluate: %w", err)
+						}
+
+						if ok {
+							ticker.Stop()
+
+							return nil
+						}
+
+						continue
+					}
+				}
+			}),
+			chromedp.ActionFunc(func(ctx context.Context) error {
+				printToPDF := page.PrintToPDF().
+					WithLandscape(options.Landscape).
+					WithPrintBackground(options.PrintBackground).
+					WithScale(options.Scale).
+					WithPaperWidth(options.PaperWidth).
+					WithPaperHeight(options.PaperHeight).
+					WithMarginTop(options.MarginTop).
+					WithMarginBottom(options.MarginBottom).
+					WithMarginLeft(options.MarginLeft).
+					WithMarginRight(options.MarginRight).
+					WithIgnoreInvalidPageRanges(false).
+					WithPageRanges(options.PageRanges).
+					WithDisplayHeaderFooter(true).
+					WithHeaderTemplate(options.HeaderTemplate).
+					WithFooterTemplate(options.FooterTemplate).
+					WithPreferCSSPageSize(options.PreferCSSPageSize)
+
+				logger.Debug(fmt.Sprintf("print to PDF with: %+v", printToPDF))
+
+				data, _, err := printToPDF.Do(ctx)
+				if err != nil {
+					return fmt.Errorf("print to PDF: %w", err)
+				}
+
+				*result = data
+
+				return nil
+			}),
+		}
+	}
+
+	var buffer []byte
+	err := chromedp.Run(taskCtx, printToPDF(URL, options, &buffer))
+
+	// Always remove the user profile directory created by Chromium.
+	go func() {
+		logger.Debug(fmt.Sprintf("remove user profile directory '%s'", userProfileDirPath))
+
+		err := os.RemoveAll(userProfileDirPath)
+		if err != nil {
+			logger.Error(fmt.Sprintf("remove user profile directory: %s", err))
+		}
+	}()
+
+	if err != nil {
+		errMessage := err.Error()
+
+		if strings.Contains(errMessage, "Show invalid printer settings error (-32000)") {
+			return ErrInvalidPrinterSettings
+		}
+
+		if strings.Contains(errMessage, "Page range syntax error") {
+			return ErrPageRangesSyntaxError
+		}
+
+		if strings.Contains(errMessage, "rpcc: message too large") {
+			return ErrRpccMessageTooLarge
+		}
+
+		return fmt.Errorf("chromium PDF: %w", err)
+	}
+
+	err = ioutil.WriteFile(outputPath, buffer, 0600)
+	if err != nil {
+		return fmt.Errorf("write result to output path: %w", err)
+	}
+
+	return nil
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module            = (*Chromium)(nil)
+	_ gotenberg.Provisioner       = (*Chromium)(nil)
+	_ gotenberg.Validator         = (*Chromium)(nil)
+	_ api.MultipartFormDataRouter = (*Chromium)(nil)
+	_ API                         = (*Chromium)(nil)
+	_ Provider                    = (*Chromium)(nil)
+)

pkg/modules/chromium/chromium_test.go

@@ -0,0 +1,366 @@
+package chromium
+
+import (
+	"context"
+	"errors"
+	"io/ioutil"
+	"os"
+	"reflect"
+	"regexp"
+	"testing"
+	"time"
+
+	"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 ProtoAPI struct {
+	pdf func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error
+}
+
+func (mod ProtoAPI) PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, options Options) error {
+	return mod.pdf(ctx, logger, URL, outputPath, options)
+}
+
+type ProtoPDFEngineProvider struct {
+	ProtoModule
+	pdfEngine func() (gotenberg.PDFEngine, error)
+}
+
+func (mod ProtoPDFEngineProvider) PDFEngine() (gotenberg.PDFEngine, error) {
+	return mod.pdfEngine()
+}
+
+type ProtoPDFEngine struct {
+	merge   func(_ context.Context, _ *zap.Logger, _ []string, _ string) error
+	convert func(_ context.Context, _ *zap.Logger, _, _, _ 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 TestDefaultOptions(t *testing.T) {
+	actual := DefaultOptions()
+	notExpect := Options{}
+
+	if reflect.DeepEqual(actual, notExpect) {
+		t.Errorf("expected %v and got identical %v", actual, notExpect)
+	}
+}
+
+func TestChromium_Descriptor(t *testing.T) {
+	descriptor := Chromium{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(Chromium))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestChromium_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       *gotenberg.Context
+		expectErr bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(Chromium).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoPDFEngineProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod }}
+				}
+				mod.pdfEngine = func() (gotenberg.PDFEngine, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(Chromium).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoPDFEngineProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod }}
+				}
+				mod.pdfEngine = func() (gotenberg.PDFEngine, error) {
+					return struct{ ProtoPDFEngine }{}, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(Chromium).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+		},
+	} {
+		mod := new(Chromium)
+		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)
+		}
+	}
+}
+
+func TestChromium_Validate(t *testing.T) {
+	for i, tc := range []struct {
+		binPath   string
+		expectErr bool
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			binPath:   "/foo",
+			expectErr: true,
+		},
+		{
+			binPath: os.Getenv("CHROMIUM_BIN_PATH"),
+		},
+	} {
+		mod := new(Chromium)
+		mod.binPath = tc.binPath
+		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 TestChromium_Chromium(t *testing.T) {
+	mod := new(Chromium)
+
+	_, err := mod.Chromium()
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestChromium_Routes(t *testing.T) {
+	for i, tc := range []struct {
+		expectRoutes  int
+		disableRoutes bool
+	}{
+		{
+			expectRoutes: 3,
+		},
+		{
+			disableRoutes: true,
+		},
+	} {
+		mod := new(Chromium)
+		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))
+		}
+	}
+}
+
+func TestChromium_PDF(t *testing.T) {
+	for i, tc := range []struct {
+		timeout                 time.Duration
+		cancel                  context.CancelFunc
+		URL                     string
+		options                 Options
+		userAgent               string
+		incognito               bool
+		ignoreCertificateErrors bool
+		allowList               *regexp.Regexp
+		denyList                *regexp.Regexp
+		expectErr               bool
+	}{
+		{
+			URL:       "https://google.com",
+			allowList: regexp.MustCompile("https://google.fr"),
+			expectErr: true,
+		},
+		{
+			URL:       "https://google.com",
+			denyList:  regexp.MustCompile("https://google.com"),
+			expectErr: true,
+		},
+		{
+			URL: "",
+			options: Options{
+				ExtraHTTPHeaders: map[string]string{
+					"foo": "bar",
+				},
+			},
+			expectErr: true,
+		},
+		{
+			URL: "https://google.com",
+			options: Options{
+				WaitDelay: time.Duration(1) * time.Nanosecond,
+			},
+		},
+		{
+			timeout: time.Duration(3) * time.Second,
+			URL:     "file:///tests/test/testdata/chromium/html/sample2/index.html",
+			options: Options{
+				WaitWindowStatus: "foo",
+			},
+			expectErr: true,
+		},
+		{
+			timeout: time.Duration(3) * time.Second,
+			URL:     "file:///tests/test/testdata/chromium/html/sample2/index.html",
+			options: Options{
+				WaitWindowStatus: "ready",
+			},
+		},
+		{
+			URL: "https://google.com",
+			options: Options{
+				MarginBottom: 100,
+			},
+			expectErr: true,
+		},
+		{
+			URL: "https://google.com",
+			options: Options{
+				PageRanges: "foo",
+			},
+			expectErr: true,
+		},
+		{
+			URL:                     "https://google.com",
+			userAgent:               "foo",
+			incognito:               true,
+			ignoreCertificateErrors: true,
+		},
+		{
+			URL: "file:///tests/test/testdata/chromium/html/sample1/index.html",
+		},
+		{
+			URL: "https://google.com",
+			options: Options{
+				HeaderTemplate: func() string {
+					b, err := ioutil.ReadFile("/tests/test/testdata/chromium/url/sample2/header.html")
+					if err != nil {
+						t.Fatalf("expected no error but got: %v", err)
+					}
+
+					return string(b)
+				}(),
+				FooterTemplate: func() string {
+					b, err := ioutil.ReadFile("/tests/test/testdata/chromium/url/sample2/footer.html")
+					if err != nil {
+						t.Fatalf("expected no error but got: %v", err)
+					}
+
+					return string(b)
+				}(),
+			},
+		},
+	} {
+		func() {
+			mod := new(Chromium)
+			mod.binPath = os.Getenv("CHROMIUM_BIN_PATH")
+			mod.userAgent = tc.userAgent
+			mod.incognito = tc.incognito
+			mod.ignoreCertificateErrors = tc.ignoreCertificateErrors
+
+			if tc.allowList == nil {
+				tc.allowList = regexp.MustCompile("")
+			}
+
+			if tc.denyList == nil {
+				tc.denyList = regexp.MustCompile("")
+			}
+
+			mod.allowList = tc.allowList
+			mod.denyList = tc.denyList
+
+			outputDir, err := gotenberg.MkdirAll()
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			defer func() {
+				err := os.RemoveAll(outputDir)
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			}()
+
+			if tc.timeout == 0 {
+				err = mod.PDF(context.Background(), zap.NewNop(), tc.URL, outputDir+"/foo.pdf", tc.options)
+			} else {
+				ctx, cancel := context.WithTimeout(context.Background(), tc.timeout)
+				defer cancel()
+
+				err = mod.PDF(ctx, zap.NewNop(), tc.URL, outputDir+"/foo.pdf", tc.options)
+			}
+
+			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)
+			}
+		}()
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module            = (*ProtoModule)(nil)
+	_ API                         = (*ProtoAPI)(nil)
+	_ gotenberg.PDFEngineProvider = (*ProtoPDFEngineProvider)(nil)
+	_ gotenberg.Module            = (*ProtoPDFEngineProvider)(nil)
+	_ gotenberg.PDFEngine         = (*ProtoPDFEngine)(nil)
+)

pkg/modules/chromium/doc.go

@@ -0,0 +1,4 @@
+// Package chromium provides a module which adds routes for converting HTML
+// documents to PDF. Other modules may also retrieve the API provided by this
+// module.
+package chromium

pkg/modules/chromium/events.go

@@ -0,0 +1,122 @@
+package chromium
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/chromedp/cdproto/network"
+	"github.com/chromedp/cdproto/page"
+	"github.com/chromedp/chromedp"
+	"go.uber.org/zap"
+	"golang.org/x/sync/errgroup"
+)
+
+// waitForEventDomContentEventFired waits until the event DomContentEventFired
+// is fired or the context timeout.
+func waitForEventDomContentEventFired(ctx context.Context, logger *zap.Logger) func() error {
+	return func() error {
+		ch := make(chan struct{})
+		cctx, cancel := context.WithCancel(ctx)
+		chromedp.ListenTarget(cctx, func(ev interface{}) {
+			switch ev.(type) {
+			case *page.EventDomContentEventFired:
+				cancel()
+				close(ch)
+			}
+		})
+
+		select {
+		case <-ch:
+			logger.Debug("event DomContentEventFired fired")
+			return nil
+		case <-ctx.Done():
+			return fmt.Errorf("wait for event DomContentEventFired: %w", ctx.Err())
+		}
+	}
+}
+
+// waitForEventLoadEventFired waits until the event LoadEventFired is fired or
+// the context timeout.
+func waitForEventLoadEventFired(ctx context.Context, logger *zap.Logger) func() error {
+	return func() error {
+		ch := make(chan struct{})
+		cctx, cancel := context.WithCancel(ctx)
+		chromedp.ListenTarget(cctx, func(ev interface{}) {
+			switch ev.(type) {
+			case *page.EventLoadEventFired:
+				cancel()
+				close(ch)
+			}
+		})
+
+		select {
+		case <-ch:
+			logger.Debug("event LoadEventFired fired")
+			return nil
+		case <-ctx.Done():
+			return fmt.Errorf("wait for event LoadEventFired: %w", ctx.Err())
+		}
+	}
+}
+
+// waitForEventNetworkIdle waits until the event networkIdle is fired or the
+// context timeout.
+func waitForEventNetworkIdle(ctx context.Context, logger *zap.Logger) func() error {
+	return func() error {
+		ch := make(chan struct{})
+		cctx, cancel := context.WithCancel(ctx)
+		chromedp.ListenTarget(cctx, func(ev interface{}) {
+			switch e := ev.(type) {
+			case *page.EventLifecycleEvent:
+				if e.Name == "networkIdle" {
+					cancel()
+					close(ch)
+				}
+			}
+		})
+
+		select {
+		case <-ch:
+			logger.Debug("event networkIdle fired")
+			return nil
+		case <-ctx.Done():
+			return fmt.Errorf("wait for event networkIdle: %w", ctx.Err())
+		}
+	}
+}
+
+// waitForEventLoadingFinished waits until the event LoadingFinished is fired
+// or the context timeout.
+func waitForEventLoadingFinished(ctx context.Context, logger *zap.Logger) func() error {
+	return func() error {
+		ch := make(chan struct{})
+		cctx, cancel := context.WithCancel(ctx)
+		chromedp.ListenTarget(cctx, func(ev interface{}) {
+			switch ev.(type) {
+			case *network.EventLoadingFinished:
+				cancel()
+				close(ch)
+			}
+		})
+
+		select {
+		case <-ch:
+			logger.Debug("event LoadingFinished fired")
+			return nil
+		case <-ctx.Done():
+			return fmt.Errorf("wait for event LoadingFinished: %w", ctx.Err())
+		}
+	}
+}
+
+// runBatch runs all functions simultaneously and waits until all of them are
+// completed or an error is encountered.
+func runBatch(ctx context.Context, fn ...func() error) error {
+	eg, _ := errgroup.WithContext(ctx)
+
+	for _, f := range fn {
+		eg.Go(f)
+	}
+
+	return eg.Wait()
+}

pkg/modules/chromium/routes.go

@@ -0,0 +1,340 @@
+package chromium
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"html/template"
+	"io/ioutil"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"github.com/microcosm-cc/bluemonday"
+	"github.com/russross/blackfriday/v2"
+	"go.uber.org/multierr"
+)
+
+// FormDataChromiumPDFOptions creates Options form the form data. Fallback to
+// default value if the considered key is not present.
+func FormDataChromiumPDFOptions(ctx *api.Context) (*api.FormData, Options) {
+	defaultOptions := DefaultOptions()
+
+	var (
+		waitDelay                                        time.Duration
+		waitWindowStatus                                 string
+		extraHTTPHeaders                                 map[string]string
+		landscape, printBackground                       bool
+		scale, paperWidth, paperHeight                   float64
+		marginTop, marginBottom, marginLeft, marginRight float64
+		pageRanges                                       string
+		headerTemplate, footerTemplate                   string
+		preferCSSPageSize                                bool
+	)
+
+	form := ctx.FormData().
+		Duration("waitDelay", &waitDelay, defaultOptions.WaitDelay).
+		String("waitWindowStatus", &waitWindowStatus, defaultOptions.WaitWindowStatus).
+		Custom("extraHttpHeaders", func(value string) error {
+			if value == "" {
+				extraHTTPHeaders = defaultOptions.ExtraHTTPHeaders
+
+				return nil
+			}
+
+			err := json.Unmarshal([]byte(value), &extraHTTPHeaders)
+			if err != nil {
+				return fmt.Errorf("unmarshal extra HTTP headers: %w", err)
+			}
+
+			return nil
+		}).
+		Bool("landscape", &landscape, defaultOptions.Landscape).
+		Bool("printBackground", &printBackground, defaultOptions.PrintBackground).
+		Float64("scale", &scale, defaultOptions.Scale).
+		Float64("paperWidth", &paperWidth, defaultOptions.PaperWidth).
+		Float64("paperHeight", &paperHeight, defaultOptions.PaperHeight).
+		Float64("marginTop", &marginTop, defaultOptions.MarginTop).
+		Float64("marginBottom", &marginBottom, defaultOptions.MarginBottom).
+		Float64("marginLeft", &marginLeft, defaultOptions.MarginLeft).
+		Float64("marginRight", &marginRight, defaultOptions.MarginRight).
+		String("nativePageRanges", &pageRanges, defaultOptions.PageRanges).
+		Content("header.html", &headerTemplate, defaultOptions.HeaderTemplate).
+		Content("footer.html", &footerTemplate, defaultOptions.FooterTemplate).
+		Bool("preferCssPageSize", &preferCSSPageSize, defaultOptions.PreferCSSPageSize)
+
+	options := Options{
+		WaitDelay:         waitDelay,
+		WaitWindowStatus:  waitWindowStatus,
+		ExtraHTTPHeaders:  extraHTTPHeaders,
+		Landscape:         landscape,
+		PrintBackground:   printBackground,
+		Scale:             scale,
+		PaperWidth:        paperWidth,
+		PaperHeight:       paperHeight,
+		MarginTop:         marginTop,
+		MarginBottom:      marginBottom,
+		MarginLeft:        marginLeft,
+		MarginRight:       marginRight,
+		PageRanges:        pageRanges,
+		HeaderTemplate:    headerTemplate,
+		FooterTemplate:    footerTemplate,
+		PreferCSSPageSize: preferCSSPageSize,
+	}
+
+	return form, options
+}
+
+// convertURLRoute returns an api.MultipartFormDataRoute route which can
+// convert a URL to PDF.
+func convertURLRoute(chromium API, engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/chromium/convert/url",
+		Handler: func(ctx *api.Context) error {
+			form, options := FormDataChromiumPDFOptions(ctx)
+
+			var (
+				URL       string
+				PDFformat string
+			)
+
+			err := form.
+				MandatoryString("url", &URL).
+				String("pdfFormat", &PDFformat, "").
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			err = convertURL(ctx, chromium, engine, URL, PDFformat, options)
+			if err != nil {
+				return fmt.Errorf("convert URL to PDF: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// convertHTMLRoute returns an api.MultipartFormDataRoute route which can
+// convert an HTML file to PDF.
+func convertHTMLRoute(chromium API, engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/chromium/convert/html",
+		Handler: func(ctx *api.Context) error {
+			form, options := FormDataChromiumPDFOptions(ctx)
+
+			var (
+				inputPath string
+				PDFformat string
+			)
+
+			err := form.
+				MandatoryPath("index.html", &inputPath).
+				String("pdfFormat", &PDFformat, "").
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			URL := fmt.Sprintf("file://%s", inputPath)
+
+			err = convertURL(ctx, chromium, engine, URL, PDFformat, options)
+			if err != nil {
+				return fmt.Errorf("convert HTML to PDF: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// convertMarkdownRoute returns an api.MultipartFormDataRoute route which can
+// convert markdown files to PDF.
+func convertMarkdownRoute(chromium API, engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/chromium/convert/markdown",
+		Handler: func(ctx *api.Context) error {
+			form, options := FormDataChromiumPDFOptions(ctx)
+
+			var (
+				inputPath     string
+				markdownPaths []string
+				PDFformat     string
+			)
+
+			err := form.
+				MandatoryPath("index.html", &inputPath).
+				MandatoryPaths([]string{".md"}, &markdownPaths).
+				String("pdfFormat", &PDFformat, "").
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			// We have to convert each markdown file referenced in the HTML
+			// file to... HTML. Thanks to the "html/template" package, we are
+			// able to provide the "toHTML" function which the user may call
+			// directly inside the HTML file.
+
+			var markdownFilesNotFoundErr error
+
+			tmpl, err := template.
+				New(filepath.Base(inputPath)).
+				Funcs(template.FuncMap{
+					"toHTML": func(filename string) (template.HTML, error) {
+						var path string
+
+						for _, markdownPath := range markdownPaths {
+							markdownFilename := filepath.Base(markdownPath)
+
+							if filename == markdownFilename {
+								path = markdownPath
+								break
+							}
+						}
+
+						if path == "" {
+							markdownFilesNotFoundErr = multierr.Append(
+								markdownFilesNotFoundErr,
+								fmt.Errorf("'%s'", filename),
+							)
+
+							return "", nil
+						}
+
+						b, err := ioutil.ReadFile(path)
+						if err != nil {
+							return "", fmt.Errorf("read markdown file '%s': %w", filename, err)
+						}
+
+						unsafe := blackfriday.Run(b)
+						sanitized := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
+
+						// #nosec
+						return template.HTML(sanitized), nil
+					},
+				}).ParseFiles(inputPath)
+
+			if err != nil {
+				return fmt.Errorf("parse template file: %w", err)
+			}
+
+			var buffer bytes.Buffer
+
+			err = tmpl.Execute(&buffer, &struct{}{})
+			if err != nil {
+				return fmt.Errorf("execute template: %w", err)
+			}
+
+			if markdownFilesNotFoundErr != nil {
+				return api.WrapError(
+					fmt.Errorf("markdown files not found: %w", markdownFilesNotFoundErr),
+					api.NewSentinelHTTPError(
+						http.StatusBadRequest,
+						fmt.Sprintf("Markdown file(s) not found: %s", markdownFilesNotFoundErr),
+					),
+				)
+			}
+
+			inputPath = ctx.GeneratePath(".html")
+
+			err = os.WriteFile(inputPath, buffer.Bytes(), 0600)
+			if err != nil {
+				return fmt.Errorf("write template result: %w", err)
+			}
+
+			URL := fmt.Sprintf("file://%s", inputPath)
+
+			err = convertURL(ctx, chromium, engine, URL, PDFformat, options)
+			if err != nil {
+				return fmt.Errorf("convert markdown to PDF: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// convertURL is a stub which is called by the other methods of this file.
+func convertURL(ctx *api.Context, chromium API, engine gotenberg.PDFEngine, URL, PDFformat string, options Options) error {
+	outputPath := ctx.GeneratePath(".pdf")
+
+	err := chromium.PDF(ctx, ctx.Log(), URL, outputPath, options)
+	if err != nil {
+
+		if errors.Is(err, ErrURLNotAuthorized) {
+			return api.WrapError(
+				fmt.Errorf("convert to PDF: %w", err),
+				api.NewSentinelHTTPError(
+					http.StatusForbidden,
+					fmt.Sprintf("'%s' does not match the authorized URLs", URL),
+				),
+			)
+		}
+
+		if errors.Is(err, ErrInvalidPrinterSettings) {
+			return api.WrapError(
+				fmt.Errorf("convert to PDF: %w", err),
+				api.NewSentinelHTTPError(
+					http.StatusBadRequest,
+					"Chromium does not handle the provided settings; please check for aberrant form values",
+				),
+			)
+		}
+
+		if errors.Is(err, ErrPageRangesSyntaxError) {
+			return api.WrapError(
+				fmt.Errorf("convert to PDF: %w", err),
+				api.NewSentinelHTTPError(
+					http.StatusBadRequest,
+					fmt.Sprintf("Chromium does not handle the page ranges '%s' (nativePageRanges)", options.PageRanges),
+				),
+			)
+		}
+
+		return fmt.Errorf("convert to PDF: %w", err)
+	}
+
+	// So far so good, the URL has been converted to 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
+	}
+
+	err = ctx.AddOutputPaths(outputPath)
+	if err != nil {
+		return fmt.Errorf("add output path: %w", err)
+	}
+
+	return nil
+}

pkg/modules/chromium/routes_test.go

@@ -0,0 +1,676 @@
+package chromium
+
+import (
+	"context"
+	"errors"
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"net/http"
+	"os"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"go.uber.org/zap"
+)
+
+func TestFormDataChromiumPDFOptions(t *testing.T) {
+	for i, tc := range []struct {
+		ctx     *api.MockContext
+		options Options
+	}{
+		{
+			ctx:     &api.MockContext{Context: &api.Context{}},
+			options: DefaultOptions(),
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetValues(map[string][]string{
+					"extraHttpHeaders": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			options: DefaultOptions(),
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetValues(map[string][]string{
+					"extraHttpHeaders": {
+						`{"foo":"bar"}`,
+					},
+				})
+
+				return ctx
+			}(),
+			options: func() Options {
+				options := DefaultOptions()
+				options.ExtraHTTPHeaders = map[string]string{
+					"foo": "bar",
+				}
+
+				return options
+			}(),
+		},
+	} {
+		_, actual := FormDataChromiumPDFOptions(tc.ctx.Context)
+
+		if !reflect.DeepEqual(actual, tc.options) {
+			t.Errorf("test %d: expected %v but got: %v", i, tc.options, actual)
+		}
+	}
+}
+
+func TestConvertURLHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		api                    API
+		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{
+					"url": {
+						"",
+					},
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetValues(map[string][]string{
+					"url": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetValues(map[string][]string{
+					"url": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			expectOutputPathsCount: 1,
+		},
+	} {
+		err := convertURLRoute(tc.api, nil).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 TestConvertHTMLHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		api                    API
+		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.html": "/foo/foo.html",
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html": "/foo/foo.html",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html": "/foo/foo.html",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			expectOutputPathsCount: 1,
+		},
+	} {
+		err := convertHTMLRoute(tc.api, nil).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 TestConvertMarkdownHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		api                    API
+		outputDir              string
+		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.html": "/foo/foo.html",
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html": "/foo/foo.html",
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html":  "/foo/foo.html",
+					"markdown.md": "/foo/markdown.md",
+				})
+
+				return ctx
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html":   "/tests/test/testdata/chromium/markdown/sample2/index.html",
+					"markdown1.md": "/foo/markdown1.md",
+				})
+
+				return ctx
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html":   "/tests/test/testdata/chromium/markdown/sample1/index.html",
+					"markdown1.md": "/foo/markdown1.md",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetFiles(map[string]string{
+					"index.html":   "/tests/test/testdata/chromium/markdown/sample1/index.html",
+					"markdown1.md": "/tests/test/testdata/chromium/markdown/sample1/markdown1.md",
+					"markdown2.md": "/tests/test/testdata/chromium/markdown/sample1/markdown2.md",
+					"markdown3.md": "/tests/test/testdata/chromium/markdown/sample1/markdown3.md",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetDirPath("/tmp/foo")
+				ctx.SetFiles(map[string]string{
+					"index.html":   "/tests/test/testdata/chromium/markdown/sample1/index.html",
+					"markdown1.md": "/tests/test/testdata/chromium/markdown/sample1/markdown1.md",
+					"markdown2.md": "/tests/test/testdata/chromium/markdown/sample1/markdown2.md",
+					"markdown3.md": "/tests/test/testdata/chromium/markdown/sample1/markdown3.md",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			outputDir: "/tmp/foo",
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetDirPath("/tmp/foo")
+				ctx.SetFiles(map[string]string{
+					"index.html":   "/tests/test/testdata/chromium/markdown/sample1/index.html",
+					"markdown1.md": "/tests/test/testdata/chromium/markdown/sample1/markdown1.md",
+					"markdown2.md": "/tests/test/testdata/chromium/markdown/sample1/markdown2.md",
+					"markdown3.md": "/tests/test/testdata/chromium/markdown/sample1/markdown3.md",
+				})
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			outputDir:              "/tmp/foo",
+			expectOutputPathsCount: 1,
+		},
+	} {
+		func() {
+			if tc.outputDir != "" {
+				err := os.MkdirAll(tc.outputDir, 0755)
+
+				if err != nil {
+					t.Fatalf("test %d: expected error but got: %v", i, err)
+				}
+
+				defer func() {
+					err := os.RemoveAll(tc.outputDir)
+					if err != nil {
+						t.Fatalf("test %d: expected no error but got: %v", i, err)
+					}
+				}()
+			}
+
+			err := convertMarkdownRoute(tc.api, nil).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 TestConvertURL(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		api                    API
+		engine                 gotenberg.PDFEngine
+		PDFformat              string
+		expectErr              bool
+		expectHTTPErr          bool
+		expectHTTPStatus       int
+		expectOutputPathsCount int
+	}{
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return ErrURLNotAuthorized
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusForbidden,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return ErrInvalidPrinterSettings
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return ErrPageRangesSyntaxError
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return errors.New("foo")
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return gotenberg.ErrPDFFormatNotAvailable
+					},
+				}
+			}(),
+			PDFformat:        "foo",
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return errors.New("foo")
+					},
+				}
+			}(),
+			PDFformat: "foo",
+			expectErr: true,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			engine: func() gotenberg.PDFEngine {
+				return &ProtoPDFEngine{
+					convert: func(_ context.Context, _ *zap.Logger, _, _, _ string) error {
+						return nil
+					},
+				}
+			}(),
+			PDFformat:              "foo",
+			expectOutputPathsCount: 1,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+				ctx.SetCancelled(true)
+
+				return ctx
+			}(),
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() API {
+				chromiumAPI := struct{ ProtoAPI }{}
+				chromiumAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ Options) error {
+					return nil
+				}
+
+				return chromiumAPI
+			}(),
+			expectOutputPathsCount: 1,
+		},
+	} {
+		err := convertURL(tc.ctx.Context, tc.api, tc.engine, "", tc.PDFformat, DefaultOptions())
+
+		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()))
+		}
+	}
+}

pkg/modules/gc/doc.go

@@ -0,0 +1,3 @@
+// Package gc provides a module for removing files and directories that have
+// expired.
+package gc

pkg/modules/gc/gc.go

@@ -0,0 +1,235 @@
+package gc
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(GarbageCollector{})
+}
+
+// GarbageCollector is a module for removing files and directories that have
+// expired. It allows us to make sure that the application does not leak files
+// or directories when running.
+type GarbageCollector struct {
+	rootPath      string
+	graceDuration time.Duration
+	excludeSubstr []string
+
+	ticker *time.Ticker
+	done   chan bool
+
+	logger *zap.Logger
+}
+
+// GarbageCollectorGraceDurationModifier is a module interface which allows to
+// update the expiration time of files and directories parsed by the garbage
+// collector. For instance, if the grace duration is 30s, the garbage collector
+// will remove paths that have a modification time older than 30s. If there are
+// many GarbageCollectorGraceDurationModifier, only the longest grace duration
+// is selected.
+type GarbageCollectorGraceDurationModifier interface {
+	GraceDuration() time.Duration
+}
+
+// GarbageCollectorExcludeSubstrModifier is a module interface which adds the
+// given substrings to the exclude list of the garbage collector. If a path
+// contains one of those substrings, the garbage collector ignores it.
+type GarbageCollectorExcludeSubstrModifier interface {
+	ExcludeSubstr() []string
+}
+
+// Descriptor returns a GarbageCollector's module descriptor.
+func (gc GarbageCollector) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID:  "gc",
+		New: func() gotenberg.Module { return new(GarbageCollector) },
+	}
+}
+
+// Provision sets the module properties.
+func (gc *GarbageCollector) Provision(ctx *gotenberg.Context) error {
+	gc.rootPath = gotenberg.TmpPath()
+
+	graceDurationModifiers, err := ctx.Modules(new(GarbageCollectorGraceDurationModifier))
+	if err != nil {
+		return fmt.Errorf("get grace duration modifiers: %w", err)
+	}
+
+	for _, graceDurationModifier := range graceDurationModifiers {
+		modifier := graceDurationModifier.(GarbageCollectorGraceDurationModifier)
+
+		if gc.graceDuration < modifier.GraceDuration() {
+			gc.graceDuration = modifier.GraceDuration()
+		}
+	}
+
+	excludeSubstrModifiers, err := ctx.Modules(new(GarbageCollectorExcludeSubstrModifier))
+	if err != nil {
+		return fmt.Errorf("get exclude substr modifiers: %w", err)
+	}
+
+	gc.excludeSubstr = strings.Split(os.Getenv("GC_EXCLUDE_SUBSTR"), ",")
+
+	for _, excludeSubstrModifier := range excludeSubstrModifiers {
+		modifier := excludeSubstrModifier.(GarbageCollectorExcludeSubstrModifier)
+
+		gc.excludeSubstr = append(gc.excludeSubstr, modifier.ExcludeSubstr()...)
+	}
+
+	loggerProvider, err := ctx.Module(new(gotenberg.LoggerProvider))
+	if err != nil {
+		return fmt.Errorf("get logger provider: %w", err)
+	}
+
+	logger, err := loggerProvider.(gotenberg.LoggerProvider).Logger(gc)
+	if err != nil {
+		return fmt.Errorf("get logger: %w", err)
+	}
+
+	gc.logger = logger
+
+	return nil
+}
+
+// Start starts the garbage collector.
+func (gc *GarbageCollector) Start() error {
+	gc.ticker = time.NewTicker(gc.graceDuration + time.Duration(1)*time.Second)
+	gc.done = make(chan bool, 1)
+
+	go func() {
+		for {
+			func() {
+				gcMu.RLock()
+				defer gcMu.RUnlock()
+
+				select {
+				case <-gc.done:
+					return
+				case <-gc.ticker.C:
+					gc.collect(false)
+				}
+			}()
+		}
+	}()
+
+	return nil
+}
+
+// collect parses the root path of the garbage collector and removes files or
+// directories that have expired. It ignores the expiration date if the "force"
+// argument is set to true.
+func (gc GarbageCollector) collect(force bool) {
+	expirationTime := time.Now().Add(-gc.graceDuration)
+
+	// To make sure that the next Walk method stays on
+	// the root level of the considered path, we have to
+	// return a filepath.SkipDir error if the current path
+	// is a directory.
+	skipDirOrNil := func(info os.FileInfo) error {
+		if info.IsDir() {
+			return filepath.SkipDir
+		}
+
+		return nil
+	}
+
+	removePath := func(path string) {
+		err := os.RemoveAll(path)
+		if err != nil {
+			gc.logger.Error(fmt.Sprintf("remove '%s': %s", path, err))
+		}
+
+		gc.logger.Debug(fmt.Sprintf("'%s' removed", path))
+	}
+
+	err := filepath.Walk(gc.rootPath, func(path string, info os.FileInfo, pathErr error) error {
+		if pathErr != nil {
+			// For whatever reasons, the Walk method failed
+			// to process the current path.
+			return pathErr
+		}
+
+		if path == gc.rootPath {
+			return nil
+		}
+
+		for _, substr := range gc.excludeSubstr {
+			if strings.Contains(info.Name(), substr) {
+				return skipDirOrNil(info)
+			}
+		}
+
+		if force {
+			removePath(path)
+
+			return skipDirOrNil(info)
+		}
+
+		if info.ModTime().Before(expirationTime) {
+			removePath(path)
+		}
+
+		return skipDirOrNil(info)
+	})
+
+	if err != nil {
+		gc.logger.Error(err.Error())
+	}
+}
+
+// StartupMessage returns an empty string.
+func (gc GarbageCollector) StartupMessage() string {
+	return ""
+}
+
+// Stop stops the garbage collector.
+func (gc *GarbageCollector) Stop(ctx context.Context) error {
+	_, ok := ctx.Deadline()
+	if !ok {
+		return errors.New("no context dead line")
+	}
+
+	// Block until the context is done so that other module may gracefully stop
+	// before we do a shutdown cleanup. We skip this step if we receive a
+	// SIGINT in the meantime.
+	gc.logger.Debug("wait for the end of grace duration")
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, os.Interrupt)
+
+	select {
+	case <-quit:
+		return nil
+	case <-ctx.Done():
+		break
+	}
+
+	gc.ticker.Stop()
+	gc.done <- true
+
+	gc.logger.Debug("shutdown cleanup...")
+	gc.collect(true)
+
+	return nil
+}
+
+var gcMu sync.RWMutex
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*GarbageCollector)(nil)
+	_ gotenberg.Provisioner = (*GarbageCollector)(nil)
+	_ gotenberg.App         = (*GarbageCollector)(nil)
+)

pkg/modules/gc/gc_test.go

@@ -0,0 +1,468 @@
+package gc
+
+import (
+	"context"
+	"errors"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"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 ProtoGarbageCollectorGraceDurationModifier struct {
+	ProtoValidator
+	graceDuration func() time.Duration
+}
+
+func (mod ProtoGarbageCollectorGraceDurationModifier) GraceDuration() time.Duration {
+	return mod.graceDuration()
+}
+
+type ProtoGarbageCollectorExcludeSubstrModifier struct {
+	ProtoValidator
+	excludeSubstr func() []string
+}
+
+func (mod ProtoGarbageCollectorExcludeSubstrModifier) ExcludeSubstr() []string {
+	return mod.excludeSubstr()
+}
+
+type ProtoLoggerProvider struct {
+	ProtoModule
+	logger func(mod gotenberg.Module) (*zap.Logger, error)
+}
+
+func (factory ProtoLoggerProvider) Logger(mod gotenberg.Module) (*zap.Logger, error) {
+	return factory.logger(mod)
+}
+
+func TestGarbageCollector_Descriptor(t *testing.T) {
+	descriptor := GarbageCollector{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(GarbageCollector))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestGarbageCollector_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                 *gotenberg.Context
+		expectGraceDuration time.Duration
+		expectExcludeSubstr []string
+		expectErr           bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct {
+					ProtoGarbageCollectorGraceDurationModifier
+				}{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error { return errors.New("foo") }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod.Descriptor(),
+				})
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct {
+					ProtoGarbageCollectorExcludeSubstrModifier
+				}{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.validate = func() error { return errors.New("foo") }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod.Descriptor(),
+				})
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx:       gotenberg.NewContext(gotenberg.ParsedFlags{}, make([]gotenberg.ModuleDescriptor, 0)),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct {
+					ProtoLoggerProvider
+				}{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.logger = func(mod gotenberg.Module) (*zap.Logger, error) { return nil, errors.New("foo") }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod.Descriptor(),
+				})
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct {
+					ProtoLoggerProvider
+				}{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.logger = func(mod gotenberg.Module) (*zap.Logger, error) { return zap.NewNop(), nil }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod.Descriptor(),
+				})
+			}(),
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod1 := struct {
+					ProtoGarbageCollectorGraceDurationModifier
+				}{}
+				mod1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod1 }}
+				}
+				mod1.graceDuration = func() time.Duration { return time.Duration(10) * time.Second }
+				mod1.validate = func() error { return nil }
+
+				mod2 := struct {
+					ProtoGarbageCollectorGraceDurationModifier
+				}{}
+				mod2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod2 }}
+				}
+				mod2.graceDuration = func() time.Duration { return time.Duration(20) * time.Second }
+				mod2.validate = func() error { return nil }
+
+				mod3 := struct {
+					ProtoLoggerProvider
+				}{}
+				mod3.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "baz", New: func() gotenberg.Module { return mod3 }}
+				}
+				mod3.logger = func(mod gotenberg.Module) (*zap.Logger, error) { return zap.NewNop(), nil }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod1.Descriptor(),
+					mod2.Descriptor(),
+					mod3.Descriptor(),
+				})
+			}(),
+			expectGraceDuration: time.Duration(20) * time.Second,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod1 := struct {
+					ProtoGarbageCollectorExcludeSubstrModifier
+				}{}
+				mod1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod1 }}
+				}
+				mod1.excludeSubstr = func() []string { return []string{"foo"} }
+				mod1.validate = func() error { return nil }
+
+				mod2 := struct {
+					ProtoGarbageCollectorExcludeSubstrModifier
+				}{}
+				mod2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod2 }}
+				}
+				mod2.excludeSubstr = func() []string { return []string{"bar"} }
+				mod2.validate = func() error { return nil }
+
+				mod3 := struct {
+					ProtoLoggerProvider
+				}{}
+				mod3.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "baz", New: func() gotenberg.Module { return mod3 }}
+				}
+				mod3.logger = func(mod gotenberg.Module) (*zap.Logger, error) { return zap.NewNop(), nil }
+
+				return gotenberg.NewContext(gotenberg.ParsedFlags{}, []gotenberg.ModuleDescriptor{
+					mod1.Descriptor(),
+					mod2.Descriptor(),
+					mod3.Descriptor(),
+				})
+			}(),
+			expectExcludeSubstr: func() []string {
+				expect := strings.Split(os.Getenv("GC_EXCLUDE_SUBSTR"), ",")
+				return append(expect, "foo", "bar")
+			}(),
+		},
+	} {
+		mod := new(GarbageCollector)
+		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 tc.expectGraceDuration != 0 && tc.expectGraceDuration != mod.graceDuration {
+			t.Errorf("test %d: expected grace duration of '%s' but got '%s'", i, tc.expectGraceDuration, mod.graceDuration)
+		}
+
+		if tc.expectExcludeSubstr != nil && !reflect.DeepEqual(tc.expectExcludeSubstr, mod.excludeSubstr) {
+			t.Errorf("test %d: expected exclude substr '%s' but got '%s'", i, tc.expectExcludeSubstr, mod.excludeSubstr)
+		}
+	}
+}
+
+func TestGarbageCollector_Start(t *testing.T) {
+	mod := new(GarbageCollector)
+	mod.logger = zap.NewNop()
+
+	path, err := gotenberg.MkdirAll()
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	mod.rootPath = path
+
+	err = mod.Start()
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+
+	time.Sleep(time.Duration(2) * time.Second)
+	mod.ticker.Stop()
+	mod.done <- true
+}
+
+func TestGarbageCollector_collect(t *testing.T) {
+	for i, tc := range []struct {
+		gc              *GarbageCollector
+		expectNotExists []string
+		expectExists    []string
+		force           bool
+	}{
+		{
+			gc: func() *GarbageCollector {
+				mod := new(GarbageCollector)
+				mod.logger = zap.NewNop()
+
+				path, err := gotenberg.MkdirAll()
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				mod.rootPath = path
+
+				err = os.WriteFile(path+"/foo", []byte{1}, 0755)
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				mod.excludeSubstr = []string{
+					"foo",
+				}
+
+				return mod
+			}(),
+			expectExists: []string{
+				"/foo",
+			},
+		},
+		{
+			gc: func() *GarbageCollector {
+				mod := new(GarbageCollector)
+				mod.logger = zap.NewNop()
+
+				path, err := gotenberg.MkdirAll()
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				mod.rootPath = path
+
+				err = os.WriteFile(path+"/foo", []byte{1}, 0755)
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				err = os.MkdirAll(path+"/bar", 0755)
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return mod
+			}(),
+			expectNotExists: []string{
+				"/foo",
+				"/bar",
+			},
+			force: true,
+		},
+		{
+			gc: func() *GarbageCollector {
+				mod := new(GarbageCollector)
+				mod.logger = zap.NewNop()
+				mod.graceDuration = time.Duration(10) * time.Second
+
+				path, err := gotenberg.MkdirAll()
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				mod.rootPath = path
+
+				err = os.WriteFile(path+"/foo", []byte{1}, 0755)
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				newTime := time.Now().Add(-time.Duration(20) * time.Second)
+				err = os.Chtimes(path+"/foo", newTime, newTime)
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				err = os.WriteFile(path+"/bar", []byte{1}, 0755)
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				newTime = time.Now().Add(time.Duration(10) * time.Second)
+				err = os.Chtimes(path+"/bar", newTime, newTime)
+
+				if err != nil {
+					t.Fatalf("expected no error but got: %v", err)
+				}
+
+				return mod
+			}(),
+			expectNotExists: []string{
+				"/foo",
+			},
+			expectExists: []string{
+				"/bar",
+			},
+		},
+	} {
+		tc.gc.collect(tc.force)
+
+		for _, name := range tc.expectNotExists {
+			path := tc.gc.rootPath + name
+			_, err := os.Stat(path)
+			if !os.IsNotExist(err) {
+				t.Errorf("test %d: expected '%s' not to exist but got: %v", i, path, err)
+			}
+		}
+
+		for _, name := range tc.expectExists {
+			path := tc.gc.rootPath + name
+			_, err := os.Stat(path)
+			if os.IsNotExist(err) {
+				t.Errorf("test %d: expected '%s' to exist but got: %v", i, path, err)
+			}
+		}
+
+		err := os.RemoveAll(tc.gc.rootPath)
+		if err != nil {
+			t.Fatalf("test %d: expected no error but got: %v", i, err)
+		}
+	}
+}
+
+func TestGarbageCollector_StartupMessage(t *testing.T) {
+	actual := new(GarbageCollector).StartupMessage()
+	expect := ""
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestGarbageCollector_Stop(t *testing.T) {
+	for i, tc := range []struct {
+		timeout   time.Duration
+		expectErr bool
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			timeout: time.Duration(1) * time.Nanosecond,
+		},
+	} {
+		func() {
+			mod := new(GarbageCollector)
+			mod.logger = zap.NewNop()
+
+			path, err := gotenberg.MkdirAll()
+			if err != nil {
+				t.Fatalf("test %d: expected no error but got: %v", i, err)
+			}
+
+			mod.rootPath = path
+
+			err = mod.Start()
+			if err != nil {
+				t.Fatalf("test %d: expected no error but got: %v", i, err)
+			}
+
+			if tc.timeout == 0 {
+				err = mod.Stop(context.TODO())
+			} else {
+				ctx, cancel := context.WithTimeout(context.Background(), tc.timeout)
+				defer cancel()
+
+				err = mod.Stop(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)
+			}
+		}()
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module                      = (*ProtoModule)(nil)
+	_ gotenberg.Validator                   = (*ProtoValidator)(nil)
+	_ GarbageCollectorGraceDurationModifier = (*ProtoGarbageCollectorGraceDurationModifier)(nil)
+	_ gotenberg.Module                      = (*ProtoGarbageCollectorGraceDurationModifier)(nil)
+	_ gotenberg.Validator                   = (*ProtoGarbageCollectorGraceDurationModifier)(nil)
+	_ GarbageCollectorExcludeSubstrModifier = (*ProtoGarbageCollectorExcludeSubstrModifier)(nil)
+	_ gotenberg.Module                      = (*ProtoGarbageCollectorExcludeSubstrModifier)(nil)
+	_ gotenberg.Validator                   = (*ProtoGarbageCollectorExcludeSubstrModifier)(nil)
+	_ gotenberg.LoggerProvider              = (*ProtoLoggerProvider)(nil)
+	_ gotenberg.Module                      = (*ProtoLoggerProvider)(nil)
+)

pkg/modules/libreoffice/doc.go

@@ -0,0 +1,3 @@
+// Package libreoffice provides a module which adds a route for converting
+// document to PDF with LibreOffice.
+package libreoffice

pkg/modules/libreoffice/libreoffice.go

@@ -0,0 +1,86 @@
+package libreoffice
+
+import (
+	"fmt"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	flag "github.com/spf13/pflag"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(LibreOffice{})
+}
+
+// LibreOffice is a module which provides a route for converting documents to
+// PDF with LibreOffice.
+type LibreOffice struct {
+	unoconv       unoconv.API
+	engine        gotenberg.PDFEngine
+	disableRoutes bool
+}
+
+// Descriptor returns a LibreOffice's module descriptor.
+func (LibreOffice) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "libreoffice",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("libreoffice", flag.ExitOnError)
+			fs.Bool("libreoffice-disable-routes", false, "Disable the routes")
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(LibreOffice) },
+	}
+}
+
+// Provision sets the module properties.
+func (mod *LibreOffice) Provision(ctx *gotenberg.Context) error {
+	flags := ctx.ParsedFlags()
+	mod.disableRoutes = flags.MustBool("libreoffice-disable-routes")
+
+	provider, err := ctx.Module(new(unoconv.Provider))
+	if err != nil {
+		return fmt.Errorf("get unoconv provider: %w", err)
+	}
+
+	uno, err := provider.(unoconv.Provider).Unoconv()
+	if err != nil {
+		return fmt.Errorf("get unoconv API: %w", err)
+	}
+
+	mod.unoconv = uno
+
+	provider, err = ctx.Module(new(gotenberg.PDFEngineProvider))
+	if err != nil {
+		return fmt.Errorf("get PDF engine provider: %w", err)
+	}
+
+	engine, err := provider.(gotenberg.PDFEngineProvider).PDFEngine()
+	if err != nil {
+		return fmt.Errorf("get PDF engine: %w", err)
+	}
+
+	mod.engine = engine
+
+	return nil
+}
+
+// Routes returns the API routes.
+func (mod LibreOffice) Routes() ([]api.MultipartFormDataRoute, error) {
+	if mod.disableRoutes {
+		return nil, nil
+	}
+
+	return []api.MultipartFormDataRoute{
+		convertRoute(mod.unoconv, mod.engine),
+	}, nil
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module            = (*LibreOffice)(nil)
+	_ gotenberg.Provisioner       = (*LibreOffice)(nil)
+	_ api.MultipartFormDataRouter = (*LibreOffice)(nil)
+)

pkg/modules/libreoffice/libreoffice_test.go

@@ -0,0 +1,250 @@
+package libreoffice
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	"go.uber.org/zap"
+)
+
+type ProtoModule struct {
+	descriptor func() gotenberg.ModuleDescriptor
+}
+
+func (mod ProtoModule) Descriptor() gotenberg.ModuleDescriptor {
+	return mod.descriptor()
+}
+
+type ProtoUnoconvProvider struct {
+	ProtoModule
+	unoconv func() (unoconv.API, error)
+}
+
+func (mod ProtoUnoconvProvider) Unoconv() (unoconv.API, error) {
+	return mod.unoconv()
+}
+
+type ProtoUnoconvAPI struct {
+	pdf        func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error
+	extensions func() []string
+}
+
+func (mod ProtoUnoconvAPI) PDF(ctx context.Context, logger *zap.Logger, inputPath, outputPath string, options unoconv.Options) error {
+	return mod.pdf(ctx, logger, inputPath, outputPath, options)
+}
+
+func (mod ProtoUnoconvAPI) Extensions() []string {
+	return mod.extensions()
+}
+
+type ProtoPDFEngineProvider struct {
+	ProtoModule
+	pdfEngine func() (gotenberg.PDFEngine, error)
+}
+
+func (mod ProtoPDFEngineProvider) PDFEngine() (gotenberg.PDFEngine, error) {
+	return mod.pdfEngine()
+}
+
+type ProtoPDFEngine struct {
+	merge   func(_ context.Context, _ *zap.Logger, _ []string, _ string) error
+	convert func(_ context.Context, _ *zap.Logger, _, _, _ 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 TestLibreOffice_Descriptor(t *testing.T) {
+	descriptor := LibreOffice{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(LibreOffice))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestLibreOffice_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       *gotenberg.Context
+		expectErr bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoModule }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(LibreOffice).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoUnoconvProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.unoconv = func() (unoconv.API, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(LibreOffice).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoUnoconvProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.unoconv = func() (unoconv.API, error) {
+					return struct{ ProtoUnoconvAPI }{}, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(LibreOffice).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod1 := struct{ ProtoUnoconvProvider }{}
+				mod1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod1 }}
+				}
+				mod1.unoconv = func() (unoconv.API, error) {
+					return struct{ ProtoUnoconvAPI }{}, nil
+				}
+
+				mod2 := struct{ ProtoPDFEngineProvider }{}
+				mod2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod2 }}
+				}
+				mod2.pdfEngine = func() (gotenberg.PDFEngine, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(LibreOffice).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod1.Descriptor(),
+						mod2.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod1 := struct{ ProtoUnoconvProvider }{}
+				mod1.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod1 }}
+				}
+				mod1.unoconv = func() (unoconv.API, error) {
+					return struct{ ProtoUnoconvAPI }{}, nil
+				}
+
+				mod2 := struct{ ProtoPDFEngineProvider }{}
+				mod2.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "bar", New: func() gotenberg.Module { return mod2 }}
+				}
+				mod2.pdfEngine = func() (gotenberg.PDFEngine, error) {
+					return struct{ ProtoPDFEngine }{}, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: new(LibreOffice).Descriptor().FlagSet,
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod1.Descriptor(),
+						mod2.Descriptor(),
+					},
+				)
+			}(),
+		},
+	} {
+		mod := new(LibreOffice)
+		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)
+		}
+	}
+}
+
+func TestLibreOffice_Routes(t *testing.T) {
+	for i, tc := range []struct {
+		expectRoutes  int
+		disableRoutes bool
+	}{
+		{
+			expectRoutes: 1,
+		},
+		{
+			disableRoutes: true,
+		},
+	} {
+		mod := new(LibreOffice)
+		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)
+	_ unoconv.Provider            = (*ProtoUnoconvProvider)(nil)
+	_ gotenberg.Module            = (*ProtoUnoconvProvider)(nil)
+	_ unoconv.API                 = (*ProtoUnoconvAPI)(nil)
+	_ gotenberg.PDFEngineProvider = (*ProtoPDFEngineProvider)(nil)
+	_ gotenberg.Module            = (*ProtoPDFEngineProvider)(nil)
+	_ gotenberg.PDFEngine         = (*ProtoPDFEngine)(nil)
+)

pkg/modules/libreoffice/pdfengine/doc.go

@@ -0,0 +1,3 @@
+// Package pdfengine provides a module which abstracts the CLI tool unoconv and
+// implements the gotenberg.PDFEngine interface.
+package pdfengine

pkg/modules/libreoffice/pdfengine/pdfengine.go

@@ -0,0 +1,76 @@
+package pdfengine
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(UnoconvPDFEngine{})
+}
+
+// UnoconvPDFEngine abstracts the CLI tool unoconv and implements the
+// gotenberg.PDFEngine interface.
+type UnoconvPDFEngine struct {
+	unoconv unoconv.API
+}
+
+// Descriptor returns a UnoconvPDFEngine's module descriptor.
+func (engine UnoconvPDFEngine) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID:  "unoconv-pdfengine",
+		New: func() gotenberg.Module { return new(UnoconvPDFEngine) },
+	}
+}
+
+// Provision sets the module properties.
+func (engine *UnoconvPDFEngine) Provision(ctx *gotenberg.Context) error {
+	provider, err := ctx.Module(new(unoconv.Provider))
+	if err != nil {
+		return fmt.Errorf("get unoconv provider: %w", err)
+	}
+
+	uno, err := provider.(unoconv.Provider).Unoconv()
+	if err != nil {
+		return fmt.Errorf("get unoconv API: %w", err)
+	}
+
+	engine.unoconv = uno
+
+	return nil
+}
+
+// Merge is not available for this PDF engine.
+func (engine UnoconvPDFEngine) Merge(_ context.Context, _ *zap.Logger, _ []string, _ string) error {
+	return fmt.Errorf("merge PDFs with unoconv: %w", gotenberg.ErrPDFEngineMethodNotAvailable)
+}
+
+// Convert converts the given PDF to a specific PDF format. Currently, only the
+// PDF/A-1 format is available. If another PDF format is requested, it returns
+// a gotenberg.ErrPDFFormatNotAvailable error.
+func (engine UnoconvPDFEngine) Convert(ctx context.Context, logger *zap.Logger, format, inputPath, outputPath string) error {
+	if format != gotenberg.FormatPDFA1a {
+		return fmt.Errorf("convert PDF to '%s' with unoconv: %w", format, gotenberg.ErrPDFFormatNotAvailable)
+	}
+
+	err := engine.unoconv.PDF(ctx, logger, inputPath, outputPath, unoconv.Options{
+		PDFArchive: true,
+	})
+
+	if err == nil {
+		return nil
+	}
+
+	return fmt.Errorf("convert PDF to '%s' with unoconv: %w", format, err)
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*UnoconvPDFEngine)(nil)
+	_ gotenberg.Provisioner = (*UnoconvPDFEngine)(nil)
+	_ gotenberg.PDFEngine   = (*UnoconvPDFEngine)(nil)
+)

pkg/modules/libreoffice/pdfengine/pdfengine_test.go

@@ -0,0 +1,197 @@
+package pdfengine
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	flag "github.com/spf13/pflag"
+	"go.uber.org/zap"
+)
+
+type ProtoModule struct {
+	descriptor func() gotenberg.ModuleDescriptor
+}
+
+func (mod ProtoModule) Descriptor() gotenberg.ModuleDescriptor {
+	return mod.descriptor()
+}
+
+type ProtoUnoconvProvider struct {
+	ProtoModule
+	unoconv func() (unoconv.API, error)
+}
+
+func (mod ProtoUnoconvProvider) Unoconv() (unoconv.API, error) {
+	return mod.unoconv()
+}
+
+type ProtoUnoconvAPI struct {
+	pdf func(ctx context.Context, logger *zap.Logger, inputPath, outputPath string, options unoconv.Options) error
+}
+
+func (mod ProtoUnoconvAPI) PDF(ctx context.Context, logger *zap.Logger, inputPath, outputPath string, options unoconv.Options) error {
+	return mod.pdf(ctx, logger, inputPath, outputPath, options)
+}
+
+func (mod ProtoUnoconvAPI) Extensions() []string {
+	return nil
+}
+
+func TestUnoconvPDFEngine_Descriptor(t *testing.T) {
+	descriptor := UnoconvPDFEngine{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(UnoconvPDFEngine))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestUnoconvPDFEngine_Provision(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       *gotenberg.Context
+		expectErr bool
+	}{
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoModule }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: flag.NewFlagSet("foo", flag.ExitOnError),
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoUnoconvProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.unoconv = func() (unoconv.API, error) {
+					return nil, errors.New("foo")
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: flag.NewFlagSet("foo", flag.ExitOnError),
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *gotenberg.Context {
+				mod := struct{ ProtoUnoconvProvider }{}
+				mod.descriptor = func() gotenberg.ModuleDescriptor {
+					return gotenberg.ModuleDescriptor{ID: "foo", New: func() gotenberg.Module { return mod }}
+				}
+				mod.unoconv = func() (unoconv.API, error) {
+					return struct{ ProtoUnoconvAPI }{}, nil
+				}
+
+				return gotenberg.NewContext(
+					gotenberg.ParsedFlags{
+						FlagSet: flag.NewFlagSet("foo", flag.ExitOnError),
+					},
+					[]gotenberg.ModuleDescriptor{
+						mod.Descriptor(),
+					},
+				)
+			}(),
+		},
+	} {
+		mod := new(UnoconvPDFEngine)
+		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)
+		}
+	}
+}
+
+func TestUnoconvPDFEngine_Merge(t *testing.T) {
+	mod := new(UnoconvPDFEngine)
+	err := mod.Merge(context.TODO(), zap.NewNop(), nil, "")
+
+	if !errors.Is(err, gotenberg.ErrPDFEngineMethodNotAvailable) {
+		t.Errorf("expected error %v, but got: %v", gotenberg.ErrPDFEngineMethodNotAvailable, err)
+	}
+}
+
+func TestUnoconvPDFEngine_Convert(t *testing.T) {
+	for i, tc := range []struct {
+		api       unoconv.API
+		format    string
+		expectErr bool
+	}{
+		{
+			format:    "",
+			expectErr: true,
+		},
+		{
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, __ string, _ unoconv.Options) error {
+					return errors.New("foo")
+				}
+
+				return unoconvAPI
+			}(),
+			format:    gotenberg.FormatPDFA1a,
+			expectErr: true,
+		},
+		{
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, __ string, _ unoconv.Options) error {
+					return nil
+				}
+
+				return unoconvAPI
+			}(),
+			format: gotenberg.FormatPDFA1a,
+		},
+	} {
+		mod := new(UnoconvPDFEngine)
+		mod.unoconv = tc.api
+
+		err := mod.Convert(context.TODO(), zap.NewNop(), tc.format, "", "")
+
+		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)
+		}
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module = (*ProtoModule)(nil)
+	_ unoconv.Provider = (*ProtoUnoconvProvider)(nil)
+	_ gotenberg.Module = (*ProtoUnoconvProvider)(nil)
+	_ unoconv.API      = (*ProtoUnoconvAPI)(nil)
+)

pkg/modules/libreoffice/routes.go

@@ -0,0 +1,177 @@
+package libreoffice
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+)
+
+// convertRoute returns an api.MultipartFormDataRoute which can convert
+// LibreOffice documents to PDF.
+func convertRoute(uno unoconv.API, engine gotenberg.PDFEngine) api.MultipartFormDataRoute {
+	return api.MultipartFormDataRoute{
+		Path: "/libreoffice/convert",
+		Handler: func(ctx *api.Context) error {
+			// Let's get the data from the form and validate them.
+			var (
+				inputPaths         []string
+				landscape          bool
+				nativePageRanges   string
+				nativePDFA1aFormat bool
+				PDFformat          string
+				merge              bool
+			)
+
+			err := ctx.FormData().
+				MandatoryPaths(uno.Extensions(), &inputPaths).
+				Bool("landscape", &landscape, false).
+				String("nativePageRanges", &nativePageRanges, "").
+				Bool("nativePdfA1aFormat", &nativePDFA1aFormat, false).
+				String("pdfFormat", &PDFformat, "").
+				Bool("merge", &merge, false).
+				Validate()
+
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			if nativePDFA1aFormat && PDFformat != "" {
+				return api.WrapError(
+					errors.New("got both 'pdfFormat' and 'nativePdfA1aFormat' form values"),
+					api.NewSentinelHTTPError(http.StatusBadRequest, "Both 'pdfFormat' and 'nativePdfA1aFormat' form values are provided"),
+				)
+			}
+
+			// Alright, let's convert each document to PDF.
+
+			outputPaths := make([]string, len(inputPaths))
+
+			for i, inputPath := range inputPaths {
+				outputPaths[i] = ctx.GeneratePath(".pdf")
+
+				options := unoconv.Options{
+					Landscape:  landscape,
+					PageRanges: nativePageRanges,
+					PDFArchive: nativePDFA1aFormat,
+				}
+
+				err = uno.PDF(ctx, ctx.Log(), inputPath, outputPaths[i], options)
+
+				if err != nil {
+					if errors.Is(err, unoconv.ErrMalformedPageRanges) {
+						return api.WrapError(
+							fmt.Errorf("convert to PDF: %w", err),
+							api.NewSentinelHTTPError(http.StatusBadRequest, fmt.Sprintf("Malformed page ranges '%s' (nativePageRanges)", options.PageRanges)),
+						)
+					}
+
+					return fmt.Errorf("convert to PDF: %w", err)
+				}
+			}
+
+			// So far so good, let's check if we have to merge the PDFs. Quick
+			// win: if there is only one PDF, skip this step.
+
+			if len(outputPaths) > 1 && merge {
+				outputPath := ctx.GeneratePath(".pdf")
+
+				err = engine.Merge(ctx, ctx.Log(), outputPaths, outputPath)
+				if err != nil {
+					return fmt.Errorf("merge PDFs: %w", err)
+				}
+
+				// Now, let's check if the client want to convert this result
+				// PDF to a specific PDF format.
+
+				// Note: nativePdfA1aFormat has not been specified if we reach
+				// this part of the code. Indeed, the handler returns early on
+				// an error if both nativePdfA1aFormat and pdfFormat are
+				// present.
+
+				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
+			}
+
+			// Ok, we don't have to merge the PDFs. Let's check if the client
+			// want to convert each PDF to a specific PDF format.
+
+			// Note: nativePdfA1aFormat has not been specified if we reach this
+			// part of the code. Indeed, the handler returns early on an error
+			// if both nativePdfA1aFormat and pdfFormat are present.
+
+			if PDFformat != "" {
+				convertOutputPaths := make([]string, len(outputPaths))
+
+				for i, outputPath := range outputPaths {
+					convertInputPath := outputPath
+					convertOutputPaths[i] = ctx.GeneratePath(".pdf")
+
+					err = engine.Convert(ctx, ctx.Log(), PDFformat, convertInputPath, convertOutputPaths[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)
+					}
+
+				}
+
+				// Important: the output paths are now the converted files.
+				outputPaths = convertOutputPaths
+			}
+
+			// 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/libreoffice/routes_test.go

@@ -0,0 +1,541 @@
+package libreoffice
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	"github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	"go.uber.org/zap"
+)
+
+func TestConvertHandler(t *testing.T) {
+	for i, tc := range []struct {
+		ctx                    *api.MockContext
+		api                    unoconv.API
+		engine                 gotenberg.PDFEngine
+		expectErr              bool
+		expectHTTPErr          bool
+		expectHTTPStatus       int
+		expectOutputPathsCount int
+	}{
+		{
+			ctx: &api.MockContext{Context: &api.Context{}},
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".foo",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"nativePdfA1aFormat": {
+						"true",
+					},
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return unoconv.ErrMalformedPageRanges
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			expectErr:        true,
+			expectHTTPErr:    true,
+			expectHTTPStatus: http.StatusBadRequest,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return errors.New("foo")
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"merge": {
+						"true",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"merge": {
+						"true",
+					},
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"merge": {
+						"true",
+					},
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"merge": {
+						"true",
+					},
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"merge": {
+						"true",
+					},
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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
+					},
+				}
+			}(),
+			expectErr: true,
+		},
+		{
+			ctx: func() *api.MockContext {
+				ctx := &api.MockContext{Context: &api.Context{}}
+
+				ctx.SetFiles(map[string]string{
+					"foo.docx": "/foo/foo.docx",
+					"bar.docx": "/foo/bar.docx",
+				})
+				ctx.SetValues(map[string][]string{
+					"pdfFormat": {
+						"foo",
+					},
+				})
+
+				return ctx
+			}(),
+			api: func() unoconv.API {
+				unoconvAPI := struct{ ProtoUnoconvAPI }{}
+				unoconvAPI.pdf = func(_ context.Context, _ *zap.Logger, _, _ string, _ unoconv.Options) error {
+					return nil
+				}
+				unoconvAPI.extensions = func() []string {
+					return []string{
+						".docx",
+					}
+				}
+
+				return unoconvAPI
+			}(),
+			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: 2,
+		},
+	} {
+		err := convertRoute(tc.api, 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()))
+		}
+	}
+}

pkg/modules/libreoffice/unoconv/doc.go

@@ -0,0 +1,2 @@
+// Package unoconv provides a module which abstracts the CLI tool unoconv.
+package unoconv

pkg/modules/libreoffice/unoconv/unoconv.go

@@ -0,0 +1,287 @@
+package unoconv
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(Unoconv{})
+}
+
+// ErrMalformedPageRanges happens if the page ranges option cannot be
+// interpreted by LibreOffice.
+var ErrMalformedPageRanges = errors.New("page ranges are malformed")
+
+// Unoconv is a module which provides an API to interact with unoconv.
+type Unoconv struct {
+	binPath string
+}
+
+// Options gathers available options when converting a document to PDF.
+type Options struct {
+	// Landscape allows to change the orientation of the resulting PDF.
+	// Optional.
+	Landscape bool
+
+	// PageRanges allows to select the pages to convert.
+	// TODO: should prefer a method form PDFEngine.
+	// Optional.
+	PageRanges string
+
+	// PDFArchive allows to convert the resulting PDF to PDF/A-1a.
+	// In a module, prefer the Convert method from the gotenberg.PDFEngine
+	// interface.
+	// Optional.
+	PDFArchive bool
+}
+
+// API is an abstraction on top of unoconv.
+//
+// See https://github.com/unoconv/unoconv.
+type API interface {
+	PDF(ctx context.Context, logger *zap.Logger, inputPath, outputPath string, options Options) error
+	Extensions() []string
+}
+
+// Provider is a module interface which exposes a method for creating an API
+// for other modules.
+//
+//	func (m *YourModule) Provision(ctx *gotenberg.Context) error {
+//		provider, _ := ctx.Module(new(unoconv.Provider))
+//		uno, _      := provider.(unoconv.Provider).Unoconv()
+//	}
+type Provider interface {
+	Unoconv() (API, error)
+}
+
+// Descriptor returns a Unoconv's module descriptor.
+func (Unoconv) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID:  "unoconv",
+		New: func() gotenberg.Module { return new(Unoconv) },
+	}
+}
+
+// Provision sets the module properties. It returns an error if the environment
+// variable UNOCONV_BIN_PATH is not set.
+func (mod *Unoconv) Provision(_ *gotenberg.Context) error {
+	binPath, ok := os.LookupEnv("UNOCONV_BIN_PATH")
+	if !ok {
+		return errors.New("UNOCONV_BIN_PATH environment variable is not set")
+	}
+
+	mod.binPath = binPath
+
+	return nil
+}
+
+// Validate validates the module properties.
+func (mod Unoconv) Validate() error {
+	_, err := os.Stat(mod.binPath)
+	if os.IsNotExist(err) {
+		return fmt.Errorf("unoconv binary path does not exist: %w", err)
+	}
+
+	return nil
+}
+
+// Unoconv returns an API for interacting with unoconv.
+func (mod Unoconv) Unoconv() (API, error) {
+	return mod, nil
+}
+
+// PDF converts a document to PDF. It creates a dedicated LibreOffice instance
+// thanks to a custom user profile directory and a free port. Substantial calls
+// to this method may increase CPU and memory usage drastically. In such a
+// scenario, the given context may also be done before the end of the
+// conversion.
+func (mod Unoconv) PDF(ctx context.Context, logger *zap.Logger, inputPath, outputPath string, options Options) error {
+	port, err := func() (int, error) {
+		listener, err := net.Listen("tcp", "127.0.0.1:0")
+		if err != nil {
+			return 0, fmt.Errorf("listen on the local network address: %w", err)
+		}
+		defer func() {
+			err := listener.Close()
+			if err != nil {
+				logger.Error(fmt.Sprintf("close listener: %s", err.Error()))
+			}
+		}()
+
+		addr := listener.Addr().String()
+
+		_, portStr, err := net.SplitHostPort(addr)
+		if err != nil {
+			return 0, fmt.Errorf("get free port from host: %w", err)
+		}
+
+		return strconv.Atoi(portStr)
+	}()
+
+	if err != nil {
+		return fmt.Errorf("get free port: %w", err)
+	}
+
+	userProfileDirPath := gotenberg.NewDirPath()
+
+	args := []string{
+		"--user-profile",
+		fmt.Sprintf("//%s", userProfileDirPath),
+		"--port",
+		fmt.Sprintf("%d", port),
+		"--format",
+		"pdf",
+	}
+
+	if options.Landscape {
+		args = append(args, "--printer", "PaperOrientation=landscape")
+	}
+
+	if options.PageRanges != "" {
+		args = append(args, "--export", fmt.Sprintf("PageRange=%s", options.PageRanges))
+	}
+
+	if options.PDFArchive {
+		args = append(args, "--export", "SelectPdfVersion=1")
+	}
+
+	args = append(args, "--output", outputPath, inputPath)
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, mod.binPath, args...)
+	if err != nil {
+		return fmt.Errorf("create unoconv command: %w", err)
+	}
+
+	logger.Debug(fmt.Sprintf("print to PDF with: %+v", options))
+
+	err = cmd.Exec()
+
+	// Always remove the user profile directory created by LibreOffice.
+	// See https://github.com/thecodingmachine/gotenberg/issues/192.
+	go func() {
+		logger.Debug(fmt.Sprintf("remove user profile directory '%s'", userProfileDirPath))
+
+		err := os.RemoveAll(userProfileDirPath)
+		if err != nil {
+			logger.Error(fmt.Sprintf("remove user profile directory: %s", err))
+		}
+	}()
+
+	if err == nil {
+		return nil
+	}
+
+	// Unoconv/LibreOffice errors are not explicit.
+	// That's why we have to make an educated guess according to the exit code
+	// and given inputs.
+
+	if strings.Contains(err.Error(), "exit status 5") && options.PageRanges != "" {
+		return ErrMalformedPageRanges
+	}
+
+	// Possible errors:
+	// 1. Unoconv/LibreOffice failed for some reason.
+	// 2. Context done.
+	//
+	// On the second scenario, LibreOffice might not had time to remove some of
+	// its temporary files, as it has been killed without warning. The garbage
+	// collector will delete them for us (if the module is loaded).
+	return fmt.Errorf("unoconv PDF: %w", err)
+}
+
+// Extensions returns the file extensions available with unoconv.
+func (mod Unoconv) Extensions() []string {
+	return []string{
+		".bib",
+		".doc",
+		".xml",
+		".docx",
+		".fodt",
+		".html",
+		".ltx",
+		".txt",
+		".odt",
+		".ott",
+		".pdb",
+		".pdf",
+		".psw",
+		".rtf",
+		".sdw",
+		".stw",
+		".sxw",
+		".uot",
+		".vor",
+		".wps",
+		".epub",
+		".png",
+		".bmp",
+		".emf",
+		".eps",
+		".fodg",
+		".gif",
+		".jpg",
+		".met",
+		".odd",
+		".otg",
+		".pbm",
+		".pct",
+		".pgm",
+		".ppm",
+		".ras",
+		".std",
+		".svg",
+		".svm",
+		".swf",
+		".sxd",
+		".sxw",
+		".tiff",
+		".xhtml",
+		".xpm",
+		".fodp",
+		".potm",
+		".pot",
+		".pptx",
+		".pps",
+		".ppt",
+		".pwp",
+		".sda",
+		".sdd",
+		".sti",
+		".sxi",
+		".uop",
+		".wmf",
+		".csv",
+		".dbf",
+		".dif",
+		".fods",
+		".ods",
+		".ots",
+		".pxl",
+		".sdc",
+		".slk",
+		".stc",
+		".sxc",
+		".uos",
+		".xls",
+		".xlt",
+		".xlsx",
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*Unoconv)(nil)
+	_ gotenberg.Provisioner = (*Unoconv)(nil)
+	_ gotenberg.Validator   = (*Unoconv)(nil)
+	_ API                   = (*Unoconv)(nil)
+	_ Provider              = (*Unoconv)(nil)
+)

pkg/modules/libreoffice/unoconv/unoconv_test.go

@@ -0,0 +1,154 @@
+package unoconv
+
+import (
+	"context"
+	"os"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func TestUnoconv_Descriptor(t *testing.T) {
+	descriptor := Unoconv{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(Unoconv))
+
+	if actual != expect {
+		t.Errorf("expected '%'s' but got '%s'", expect, actual)
+	}
+}
+
+func TestUnoconv_Provision(t *testing.T) {
+	mod := new(Unoconv)
+	ctx := gotenberg.NewContext(gotenberg.ParsedFlags{}, nil)
+
+	err := mod.Provision(ctx)
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestUnoconv_Validate(t *testing.T) {
+	for i, tc := range []struct {
+		binPath   string
+		expectErr bool
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			binPath:   "/foo",
+			expectErr: true,
+		},
+		{
+			binPath: os.Getenv("UNOCONV_BIN_PATH"),
+		},
+	} {
+		mod := new(Unoconv)
+		mod.binPath = tc.binPath
+		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 TestUnoconv_Unoconv(t *testing.T) {
+	mod := new(Unoconv)
+
+	_, err := mod.Unoconv()
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestUnoconv_PDF(t *testing.T) {
+	for i, tc := range []struct {
+		ctx       context.Context
+		inputPath string
+		options   Options
+		expectErr bool
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			ctx:       context.Background(),
+			inputPath: "/tests/test/testdata/libreoffice/sample1.docx",
+			options: Options{
+				Landscape:  true,
+				PageRanges: "1-2",
+				PDFArchive: true,
+			},
+		},
+		{
+			ctx:       context.Background(),
+			inputPath: "/tests/test/testdata/libreoffice/sample1.docx",
+			options: Options{
+				PageRanges: "foo",
+			},
+			expectErr: true,
+		},
+		{
+			ctx: func() context.Context {
+				ctx, cancel := context.WithCancel(context.TODO())
+				defer cancel()
+
+				return ctx
+			}(),
+			inputPath: "/tests/test/testdata/libreoffice/sample1.docx",
+			expectErr: true,
+		},
+	} {
+		func() {
+			mod := new(Unoconv)
+
+			err := mod.Provision(nil)
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			outputDir, err := gotenberg.MkdirAll()
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			defer func() {
+				err := os.RemoveAll(outputDir)
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			}()
+
+			err = mod.PDF(tc.ctx, zap.NewNop(), tc.inputPath, outputDir+"/foo.pdf", tc.options)
+
+			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 TestUnoconv_Extensions(t *testing.T) {
+	mod := new(Unoconv)
+	extensions := mod.Extensions()
+
+	actual := len(extensions)
+	expect := 73
+
+	if actual != expect {
+		t.Errorf("expected %d extentions but got %d", expect, actual)
+	}
+}

pkg/modules/logging/doc.go

@@ -0,0 +1,3 @@
+// Package logging provides a module which creates a zap.Logger for other
+// modules.
+package logging

pkg/modules/logging/logging.go

@@ -0,0 +1,169 @@
+package logging
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	flag "github.com/spf13/pflag"
+	"go.uber.org/multierr"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"golang.org/x/term"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(Logging{})
+}
+
+const (
+	errorLoggingLevel = "error"
+	warnLoggingLevel  = "warn"
+	infoLoggingLevel  = "info"
+	debugLoggingLevel = "debug"
+)
+
+const (
+	autoLoggingFormat = "auto"
+	jsonLoggingFormat = "json"
+	textLoggingFormat = "text"
+)
+
+// Logging is a module which implements the gotenberg.LoggerProvider interface.
+type Logging struct {
+	level  string
+	format string
+}
+
+// Descriptor returns a Logging's module descriptor.
+func (Logging) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "logging",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("logging", flag.ExitOnError)
+			fs.String("log-level", infoLoggingLevel, fmt.Sprintf("Set the log level - %s, %s, %s, or %s", errorLoggingLevel, warnLoggingLevel, infoLoggingLevel, debugLoggingLevel))
+			fs.String("log-format", autoLoggingFormat, fmt.Sprintf("Set log format - %s, %s, or %s", autoLoggingFormat, jsonLoggingFormat, textLoggingFormat))
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(Logging) },
+	}
+}
+
+// Provision sets the log level and format.
+func (log *Logging) Provision(ctx *gotenberg.Context) error {
+	flags := ctx.ParsedFlags()
+
+	log.level = flags.MustString("log-level")
+	log.format = flags.MustString("log-format")
+
+	return nil
+}
+
+// Validate validates the log level and format.
+func (log Logging) Validate() error {
+	var err error
+
+	switch log.level {
+	case errorLoggingLevel, warnLoggingLevel, infoLoggingLevel, debugLoggingLevel:
+		break
+	default:
+		err = multierr.Append(
+			err,
+			fmt.Errorf("log level must be either %s, %s, %s or %s", errorLoggingLevel, warnLoggingLevel, infoLoggingLevel, debugLoggingLevel),
+		)
+	}
+
+	switch log.format {
+	case autoLoggingFormat, jsonLoggingFormat, textLoggingFormat:
+		break
+	default:
+		err = multierr.Append(
+			err,
+			fmt.Errorf("log format must be either %s, %s or %s", autoLoggingFormat, jsonLoggingFormat, textLoggingFormat),
+		)
+	}
+
+	return err
+}
+
+// Logger returns a zap.Logger.
+func (log Logging) Logger(mod gotenberg.Module) (*zap.Logger, error) {
+	if logger == nil {
+		lvl, err := newLogLevel(log.level)
+		if err != nil {
+			return nil, fmt.Errorf("get log level: %w", err)
+		}
+
+		encoder, err := newLogEncoder(log.format)
+		if err != nil {
+			return nil, fmt.Errorf("get log encoder: %w", err)
+		}
+
+		core := zapcore.NewCore(encoder, os.Stderr, lvl)
+		logger = zap.New(core)
+
+		// nolint
+		defer logger.Sync()
+	}
+
+	return logger.Named(mod.Descriptor().ID), nil
+}
+
+func newLogLevel(level string) (zapcore.Level, error) {
+	switch level {
+	case errorLoggingLevel:
+		return zap.ErrorLevel, nil
+	case warnLoggingLevel:
+		return zap.WarnLevel, nil
+	case infoLoggingLevel:
+		return zap.InfoLevel, nil
+	case debugLoggingLevel:
+		return zap.DebugLevel, nil
+	default:
+		return -2, fmt.Errorf("%s is not a recognized log level", level)
+	}
+}
+
+func newLogEncoder(format string) (zapcore.Encoder, error) {
+	isTerminal := term.IsTerminal(int(os.Stdout.Fd()))
+	encCfg := zap.NewProductionEncoderConfig()
+
+	if isTerminal {
+		// If interactive terminal, make output more human-readable by default.
+		// Credits: https://github.com/caddyserver/caddy/blob/v2.1.1/logging.go#L671.
+		encCfg.EncodeTime = func(ts time.Time, encoder zapcore.PrimitiveArrayEncoder) {
+			encoder.AppendString(ts.UTC().Format("2006/01/02 15:04:05.000"))
+		}
+
+		if format == textLoggingFormat || format == autoLoggingFormat {
+			encCfg.EncodeLevel = zapcore.CapitalColorLevelEncoder
+		}
+	}
+
+	if format == autoLoggingFormat && isTerminal {
+		format = textLoggingFormat
+	} else if format == autoLoggingFormat {
+		format = jsonLoggingFormat
+	}
+
+	switch format {
+	case textLoggingFormat:
+		return zapcore.NewConsoleEncoder(encCfg), nil
+	case jsonLoggingFormat:
+		return zapcore.NewJSONEncoder(encCfg), nil
+	default:
+		return nil, fmt.Errorf("%s is not a recognized log format", format)
+	}
+}
+
+var logger *zap.Logger = nil
+
+// Interface guards.
+var (
+	_ gotenberg.Module         = (*Logging)(nil)
+	_ gotenberg.Provisioner    = (*Logging)(nil)
+	_ gotenberg.Validator      = (*Logging)(nil)
+	_ gotenberg.LoggerProvider = (*Logging)(nil)
+)

pkg/modules/logging/logging_test.go

@@ -0,0 +1,199 @@
+package logging
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap/zapcore"
+)
+
+type ProtoModule struct {
+	descriptor func() gotenberg.ModuleDescriptor
+}
+
+func (mod ProtoModule) Descriptor() gotenberg.ModuleDescriptor {
+	return mod.descriptor()
+}
+
+func TestLogging_Descriptor(t *testing.T) {
+	descriptor := Logging{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(Logging))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestLogging_Provision(t *testing.T) {
+	logging := new(Logging)
+	fs := logging.Descriptor().FlagSet
+
+	err := fs.Parse([]string{""})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	ctx := gotenberg.NewContext(gotenberg.ParsedFlags{FlagSet: fs}, nil)
+
+	err = logging.Provision(ctx)
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestLogging_Validate(t *testing.T) {
+	for i, tc := range []struct {
+		level, format string
+		expectErr     bool
+	}{
+		{
+			level:     "foo",
+			expectErr: true,
+		},
+		{
+			level:     debugLoggingLevel,
+			format:    "foo",
+			expectErr: true,
+		},
+		{
+			level:  debugLoggingLevel,
+			format: autoLoggingFormat,
+		},
+	} {
+		mod := new(Logging)
+		mod.level = tc.level
+		mod.format = tc.format
+
+		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 TestLogging_Logger(t *testing.T) {
+	for i, tc := range []struct {
+		level, format string
+		expectErr     bool
+	}{
+		{
+			level:     "foo",
+			expectErr: true,
+		},
+		{
+			level:     debugLoggingLevel,
+			format:    "foo",
+			expectErr: true,
+		},
+		{
+			level:  debugLoggingLevel,
+			format: autoLoggingFormat,
+		},
+	} {
+		mod := new(Logging)
+		mod.level = tc.level
+		mod.format = tc.format
+
+		_, err := mod.Logger(ProtoModule{
+			descriptor: func() gotenberg.ModuleDescriptor {
+				return gotenberg.ModuleDescriptor{ID: "foo", New: 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 TestNewLogLevel(t *testing.T) {
+	for i, tc := range []struct {
+		level          string
+		expectZapLevel zapcore.Level
+		expectErr      bool
+	}{
+		{
+			level:          errorLoggingLevel,
+			expectZapLevel: zapcore.ErrorLevel,
+		},
+		{
+			level:          warnLoggingLevel,
+			expectZapLevel: zapcore.WarnLevel,
+		},
+		{
+			level:          infoLoggingLevel,
+			expectZapLevel: zapcore.InfoLevel,
+		},
+		{
+			level:          debugLoggingLevel,
+			expectZapLevel: zapcore.DebugLevel,
+		},
+		{
+			level:          "foo",
+			expectZapLevel: -2,
+			expectErr:      true,
+		},
+	} {
+		actual, err := newLogLevel(tc.level)
+
+		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 tc.expectZapLevel != actual {
+			t.Errorf("test %d: expected %d level but got %d", i, tc.expectZapLevel, actual)
+		}
+	}
+}
+
+func TestNewLogEncoder(t *testing.T) {
+	for i, tc := range []struct {
+		format    string
+		expectErr bool
+	}{
+		{
+			format: autoLoggingFormat,
+		},
+		{
+			format: textLoggingFormat,
+		},
+		{
+			format: jsonLoggingFormat,
+		},
+		{
+			format:    "foo",
+			expectErr: true,
+		},
+	} {
+		_, err := newLogEncoder(tc.format)
+
+		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)
+		}
+	}
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module = (*ProtoModule)(nil)
+)

pkg/modules/pdfcpu/doc.go

@@ -0,0 +1,4 @@
+// Package pdfcpu provides a module which wraps the
+// https://github.com/pdfcpu/pdfcpu library and implements the
+// gotenberg.PDFEngine interface.
+package pdfcpu

pkg/modules/pdfcpu/pdfcpu.go

@@ -0,0 +1,62 @@
+package pdfcpu
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	pdfcpuAPI "github.com/pdfcpu/pdfcpu/pkg/api"
+	pdfcpuLog "github.com/pdfcpu/pdfcpu/pkg/log"
+	pdfcpuConfig "github.com/pdfcpu/pdfcpu/pkg/pdfcpu"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(PDFcpu{})
+}
+
+// PDFcpu is a module which wraps the https://github.com/pdfcpu/pdfcpu library
+// and implements the gotenberg.PDFEngine interface.
+type PDFcpu struct {
+	conf *pdfcpuConfig.Configuration
+}
+
+// Descriptor returns a PDFcpu's module descriptor.
+func (engine PDFcpu) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID:  "pdfcpu",
+		New: func() gotenberg.Module { return new(PDFcpu) },
+	}
+}
+
+// Provision sets the engine properties.
+func (engine *PDFcpu) Provision(_ *gotenberg.Context) error {
+	pdfcpuConfig.ConfigPath = "disable"
+	pdfcpuLog.DisableLoggers()
+
+	engine.conf = pdfcpuConfig.NewDefaultConfiguration()
+
+	return nil
+}
+
+// Merge merges the given PDFs into a unique PDF.
+func (engine PDFcpu) Merge(_ context.Context, _ *zap.Logger, inputPaths []string, outputPath string) error {
+	err := pdfcpuAPI.MergeCreateFile(inputPaths, outputPath, engine.conf)
+	if err == nil {
+		return nil
+	}
+
+	return fmt.Errorf("merge PDFs with PDFcpu: %w", err)
+}
+
+// Convert is not available for this PDF engine.
+func (engine PDFcpu) Convert(_ context.Context, _ *zap.Logger, format, _, _ string) error {
+	return fmt.Errorf("convert PDF to '%s' with PDFcpu: %w", format, gotenberg.ErrPDFEngineMethodNotAvailable)
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*PDFcpu)(nil)
+	_ gotenberg.Provisioner = (*PDFcpu)(nil)
+	_ gotenberg.PDFEngine   = (*PDFcpu)(nil)
+)

pkg/modules/pdfcpu/pdfcpu_test.go

@@ -0,0 +1,98 @@
+package pdfcpu
+
+import (
+	"context"
+	"errors"
+	"os"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func TestPDFcpu_Descriptor(t *testing.T) {
+	descriptor := PDFcpu{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	expect := reflect.TypeOf(new(PDFcpu))
+
+	if actual != expect {
+		t.Errorf("expected '%s' but got '%s'", expect, actual)
+	}
+}
+
+func TestPDFcpu_Provision(t *testing.T) {
+	mod := new(PDFcpu)
+	ctx := gotenberg.NewContext(gotenberg.ParsedFlags{}, nil)
+
+	err := mod.Provision(ctx)
+	if err != nil {
+		t.Errorf("expected no error but got: %v", err)
+	}
+}
+
+func TestPDFcpu_Merge(t *testing.T) {
+	for i, tc := range []struct {
+		inputPaths []string
+		expectErr  bool
+	}{
+		{
+			inputPaths: []string{
+				"/tests/test/testdata/pdfengines/sample1.pdf",
+			},
+		},
+		{
+			inputPaths: []string{
+				"/tests/test/testdata/pdfengines/sample1.pdf",
+				"/tests/test/testdata/pdfengines/sample2.pdf",
+			},
+		},
+		{
+			inputPaths: []string{
+				"foo",
+			},
+			expectErr: true,
+		},
+	} {
+		func() {
+			mod := new(PDFcpu)
+
+			err := mod.Provision(nil)
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			outputDir, err := gotenberg.MkdirAll()
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			defer func() {
+				err := os.RemoveAll(outputDir)
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			}()
+
+			err = mod.Merge(nil, nil, tc.inputPaths, outputDir+"/foo.pdf")
+
+			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 TestPDFcpu_Convert(t *testing.T) {
+	mod := new(PDFcpu)
+	err := mod.Convert(context.TODO(), zap.NewNop(), "", "", "")
+
+	if !errors.Is(err, gotenberg.ErrPDFEngineMethodNotAvailable) {
+		t.Errorf("expected error %v, but got: %v", gotenberg.ErrPDFEngineMethodNotAvailable, err)
+	}
+}

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()))
+		}
+	}
+}

pkg/modules/pdftk/doc.go

@@ -0,0 +1,3 @@
+// Package pdftk provides a module which abstracts the CLI tool PDFtk and
+// implements the gotenberg.PDFEngine interface.
+package pdftk

pkg/modules/pdftk/pdftk.go

@@ -0,0 +1,84 @@
+package pdftk
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(PDFtk{})
+}
+
+// PDFtk abstracts the CLI tool PDFtk and implements the gotenberg.PDFEngine
+// interface.
+type PDFtk struct {
+	binPath string
+}
+
+// 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) },
+	}
+}
+
+// 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 {
+	binPath, ok := os.LookupEnv("PDFTK_BIN_PATH")
+	if !ok {
+		return errors.New("PDFTK_BIN_PATH environment variable is not set")
+	}
+
+	engine.binPath = binPath
+
+	return nil
+}
+
+// Validate validates the module properties.
+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 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 {
+	var args []string
+	args = append(args, inputPaths...)
+	args = append(args, "cat", "output", outputPath)
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		return fmt.Errorf("create command: %w", err)
+	}
+
+	err = cmd.Exec()
+	if err == nil {
+		return nil
+	}
+
+	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)
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*PDFtk)(nil)
+	_ gotenberg.Provisioner = (*PDFtk)(nil)
+	_ gotenberg.Validator   = (*PDFtk)(nil)
+	_ gotenberg.PDFEngine   = (*PDFtk)(nil)
+)

pkg/modules/pdftk/pdftk_test.go

@@ -0,0 +1,136 @@
+package pdftk
+
+import (
+	"context"
+	"errors"
+	"os"
+	"reflect"
+	"testing"
+
+	"github.com/gotenberg/gotenberg/v7/pkg/gotenberg"
+	"go.uber.org/zap"
+)
+
+func TestPDFtk_Descriptor(t *testing.T) {
+	descriptor := PDFtk{}.Descriptor()
+
+	actual := reflect.TypeOf(descriptor.New())
+	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)
+	ctx := gotenberg.NewContext(gotenberg.ParsedFlags{}, nil)
+
+	err := mod.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
+	}{
+		{
+			expectErr: true,
+		},
+		{
+			binPath:   "/foo",
+			expectErr: true,
+		},
+		{
+			binPath: os.Getenv("PDFTK_BIN_PATH"),
+		},
+	} {
+		mod := new(PDFtk)
+		mod.binPath = tc.binPath
+		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 TestPDFtk_Merge(t *testing.T) {
+	for i, tc := range []struct {
+		ctx        context.Context
+		inputPaths []string
+		expectErr  bool
+	}{
+		{
+			ctx: context.TODO(),
+			inputPaths: []string{
+				"/tests/test/testdata/pdfengines/sample1.pdf",
+			},
+		},
+		{
+			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)
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			outputDir, err := gotenberg.MkdirAll()
+			if err != nil {
+				t.Fatalf("test %d: expected error but got: %v", i, err)
+			}
+
+			defer func() {
+				err := os.RemoveAll(outputDir)
+				if err != nil {
+					t.Fatalf("test %d: expected no error but got: %v", i, err)
+				}
+			}()
+
+			err = mod.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.expectErr && err != nil {
+				t.Errorf("test %d: expected no error but got: %v", i, err)
+			}
+		}()
+	}
+}
+
+func TestPDFtk_Convert(t *testing.T) {
+	mod := new(PDFtk)
+	err := mod.Convert(context.TODO(), zap.NewNop(), "", "", "")
+
+	if !errors.Is(err, gotenberg.ErrPDFEngineMethodNotAvailable) {
+		t.Errorf("expected error %v, but got: %v", gotenberg.ErrPDFEngineMethodNotAvailable, err)
+	}
+}

pkg/standard/doc.go

@@ -0,0 +1,2 @@
+// Package standard imports the application's default modules.
+package standard

pkg/standard/imports.go

@@ -0,0 +1,11 @@
+package standard
+
+import (
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/api"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/chromium"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/gc"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/libreoffice/unoconv"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/logging"
+	_ "github.com/gotenberg/gotenberg/v7/pkg/modules/pdfengines"
+)

scripts/release.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+set -e
+
+GOLANG_VERSION="$1"
+GOTENBERG_VERSION="$2"
+GOTENBERG_USER_GID="$3"
+GOTENBERG_USER_UID="$4"
+PDFTK_VERSION="$5"
+DOCKER_REGISTRY="$6"
+
+GOTENBERG_VERSION="${GOTENBERG_VERSION//v}"
+SEMVER=( ${GOTENBERG_VERSION//./ } )
+VERSION_LENGTH=${#SEMVER[@]}
+
+if [ $VERSION_LENGTH -ne 3 ]; then
+    echo "$VERSION is not semver."
+    exit 1
+fi
+
+docker buildx build \
+  --build-arg GOLANG_VERSION="$GOLANG_VERSION" \
+  --build-arg GOTENBERG_VERSION="$GOTENBERG_VERSION" \
+  --build-arg GOTENBERG_USER_GID="$GOTENBERG_USER_GID" \
+  --build-arg GOTENBERG_USER_UID="$GOTENBERG_USER_UID" \
+  --build-arg PDFTK_VERSION="$PDFTK_VERSION" \
+  --platform linux/amd64 \
+  --platform linux/arm64 \
+  -t "$DOCKER_REGISTRY/gotenberg:latest" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}.${SEMVER[1]}" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}.${SEMVER[1]}.${SEMVER[2]}" \
+  --push \
+  -f build/Dockerfile .
+
+# Cloud Run variant.
+docker buildx build \
+  --build-arg DOCKER_REGISTRY="$DOCKER_REGISTRY" \
+  --build-arg GOTENBERG_VERSION="$GOTENBERG_VERSION" \
+  --platform linux/amd64 \
+  --platform linux/arm64 \
+  -t "$DOCKER_REGISTRY/gotenberg:latest-cloudrun" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}-cloudrun" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}.${SEMVER[1]}-cloudrun" \
+  -t "$DOCKER_REGISTRY/gotenberg:${SEMVER[0]}.${SEMVER[1]}.${SEMVER[2]}-cloudrun" \
+  --push \
+  -f build/Dockerfile.cloudrun .

test/Dockerfile

@@ -0,0 +1,45 @@
+ARG GOLANG_VERSION
+ARG DOCKER_REGISTRY
+ARG GOTENBERG_VERSION
+ARG GOLANGCI_LINT_VERSION
+
+FROM golang:$GOLANG_VERSION-stretch as golang
+
+# We're extending the Gotenberg's Docker image because our code relies on external
+# dependencies like Google Chrome, LibreOffice, etc.
+FROM $DOCKER_REGISTRY/gotenberg:$GOTENBERG_VERSION
+
+USER root
+
+COPY --from=golang /usr/local/go /usr/local/go
+COPY ./test/docker-entrypoint.sh /usr/bin/docker-entrypoint.sh
+COPY ./test/golint.sh /usr/bin/golint
+COPY ./test/gotest.sh /usr/bin/gotest
+COPY ./test/gotodos.sh /usr/bin/gotodos
+
+ENV GOPATH /go
+ENV PATH $GOPATH/bin:/usr/local/go/bin:$PATH
+ENV CGO_ENABLED 1
+
+RUN apt-get update -qq &&\
+    apt-get install -y -qq --no-install-recommends  \
+    sudo \
+    # gcc for cgo.
+    g++ \
+    gcc \
+    libc6-dev \
+    make \
+    pkg-config &&\
+    rm -rf /var/lib/apt/lists/* &&\
+    mkdir -p "$GOPATH/src" "$GOPATH/bin" &&\
+    chmod -R 777 "$GOPATH" &&\
+    adduser gotenberg sudo &&\
+    echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers &&\
+    # We cannot use $PATH in the next command (print $PATH instead of the environment variable value).
+    sed -i 's#/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin#/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/go/bin:/usr/local/go/bin#g' /etc/sudoers &&\
+    curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin $GOLANGCI_LINT_VERSION
+
+# Pristine working directory.
+WORKDIR /tests
+
+ENTRYPOINT [ "docker-entrypoint.sh" ]

test/docker-entrypoint.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# This entrypoint allows us to set the UID and GID of the host user so that
+# our testing environment does not override files permissions from the host.
+# Credits: https://github.com/thecodingmachine/docker-images-php.
+
+set +e
+mkdir testing_file_system_rights.foo
+chmod 700 testing_file_system_rights.foo
+su gotenberg -c "touch testing_file_system_rights.foo/foo > /dev/null 2>&1"
+HAS_CONSISTENT_RIGHTS=$?
+
+if [[ "$HAS_CONSISTENT_RIGHTS" != "0" ]]; then
+    # If not specified, the DOCKER_USER is the owner of the current working directory (heuristic!).
+    DOCKER_USER=`ls -dl $(pwd) | cut -d " " -f 3`
+else
+    # macOs or Windows.
+    # Note: in most cases, we don't care about the rights (they are not respected).
+    FILE_OWNER=`ls -dl testing_file_system_rights.foo/foo | cut -d " " -f 3`
+    if [[ "$FILE_OWNER" == "root" ]]; then
+        # If root, we are likely on a Windows host.
+        # All files will belong to root, but it does not matter as everybody can write/delete
+        # those (0777 access rights).
+        DOCKER_USER=gotenberg
+    else
+        # In case of a NFS mount (common on macOS), the created files will belong to the NFS user.
+        DOCKER_USER=$FILE_OWNER
+    fi
+fi
+
+rm -rf testing_file_system_rights.foo
+set -e
+unset HAS_CONSISTENT_RIGHTS
+
+# Note: DOCKER_USER is either a username (if the user exists in the container),
+# otherwise a user ID (a user from the host).
+
+# DOCKER_USER is an ID.
+if [[ "$DOCKER_USER" =~ ^[0-9]+$ ]] ; then
+    # Let's change the gotenberg user's ID in order to match this free ID.
+    usermod -u $DOCKER_USER -G sudo gotenberg
+    DOCKER_USER=gotenberg
+fi
+
+DOCKER_USER_ID=`id -ur $DOCKER_USER`
+
+# Fix access rights to stdout and stderr.
+set +e
+chown $DOCKER_USER /proc/self/fd/{1,2}
+set -e
+
+# Install modules.
+set -x
+go mod download
+go mod tidy
+set +x
+
+# Run the command with the correct user.
+exec "sudo" "-E" "-H" "-u" "#$DOCKER_USER_ID" "$@"

test/golint.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -x
+
+golangci-lint run

test/gotest.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+set -x
+
+go test -race -covermode=atomic -coverprofile=/tests/coverage.txt ./...
+go tool cover -html=coverage.txt -o /tests/coverage.html

test/gotodos.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set -x
+
+golangci-lint run \
+	--no-config \
+	--disable-all \
+	--enable godox

test/testdata/api/sample1.txt

@@ -0,0 +1 @@
+foo

test/testdata/chromium/html/sample1/footer.html

@@ -0,0 +1,15 @@
+<html>
+<head>
+    <style>
+        body {
+            font-size: 30rem;
+            margin: 4rem auto;
+        }
+    </style>
+</head>
+<body>
+<p>
+    <span class="pageNumber"></span> of <span class="totalPages"></span>
+</p>
+</body>
+</html>

test/testdata/chromium/html/sample1/header.html

@@ -0,0 +1,13 @@
+<html>
+<head>
+    <style>
+        body {
+            font-size: 8rem;
+            margin: 4rem auto;
+        }
+    </style>
+</head>
+<body>
+<span class="title"></span>
+</body>
+</html>

test/testdata/chromium/html/sample1/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <link rel="stylesheet" type="text/css" href="style.css">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
+    <title>Gutenberg</title>
+</head>
+<body>
+<div class="page-break-after">
+    <div class="center">
+        <h1>Gutenberg</h1>
+        <img src="img.gif">
+    </div>
+
+    <blockquote cite="https://sites.google.com/site/johanngutenbergper5/q">
+        <p>It is a press, certainly, but a press from which shall flow in inexhaustible streams...Through it, God will spread His Word. A spring of truth shall flow from it: like a new star it shall scatter the darkness of ignorance, and cause a light heretofore unknown to shine amongst men.</p>
+        <footer>— <a href="https://sites.google.com/site/johanngutenbergper5/q">Johannes Gutenberg</a></cite></footer>
+    </blockquote>
+</div>
+
+<div class="page-break-after">
+    <h2>This paragraph use the default font</h2>
+    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
+
+    <h2>This paragraph use a Google font</h2>
+    <p class="google-font">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
+
+    <h2>This paragraph use a local font</h2>
+    <p class="local-font">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
+</div>
+
+<div class="center">
+    <h1>This image is loaded from a URL</h1>
+    <img src="https://gutendev.com/wp-content/uploads/2018/10/01_03-1.jpg">
+</div>
+</body>
+</html>

test/testdata/chromium/html/sample1/style.css

@@ -0,0 +1,28 @@
+body {
+    font-family: Arial, Helvetica, sans-serif;
+}
+
+.center {
+    text-align: center;
+}
+
+.google-font {
+    font-family: 'Montserrat', sans-serif;
+}
+
+@font-face {
+    font-family: 'Local';
+    src: url('font.woff') format('woff');
+    font-weight: normal;
+    font-style: normal;
+}
+
+.local-font {
+    font-family: 'Local'
+}
+
+@media print {
+    .page-break-after {
+        page-break-after: always;
+    }
+}

test/testdata/chromium/html/sample2/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Gutenberg</title>
+</head>
+<body>
+
+<p id="status">
+    No window.status
+</p>
+
+<script type="application/javascript">
+    const delay = ms => new Promise(res => setTimeout(res, ms))
+
+    const changeStatus = async (status) => {
+        await delay(2000)
+        console.log('waited 2s')
+
+        document.getElementById('status').innerText = 'window.status === ' + status
+
+        window.status = status
+    };
+
+    changeStatus('ready')
+</script>
+</body>
+</html>

test/testdata/chromium/markdown/sample1/footer.html

@@ -0,0 +1,15 @@
+<html>
+<head>
+    <style>
+        body {
+            font-size: 8rem;
+            margin: 4rem auto;
+        }
+    </style>
+</head>
+<body>
+<p>
+    <span class="pageNumber"></span> of <span class="totalPages"></span>
+</p>
+</body>
+</html>

test/testdata/chromium/markdown/sample1/header.html

@@ -0,0 +1,13 @@
+<html>
+<head>
+    <style>
+        body {
+            font-size: 8rem;
+            margin: 4rem auto;
+        }
+    </style>
+</head>
+<body>
+<span class="title"></span>
+</body>
+</html>

test/testdata/chromium/markdown/sample1/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <link rel="stylesheet" type="text/css" href="style.css">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
+    <title>Gutenberg</title>
+</head>
+<body>
+<div class="page-break-after">
+    <div class="center">
+        <h1>Gutenberg</h1>
+        <img src="img.gif">
+    </div>
+
+    <blockquote cite="https://sites.google.com/site/johanngutenbergper5/q">
+        <p>It is a press, certainly, but a press from which shall flow in inexhaustible streams...Through it, God will spread His Word. A spring of truth shall flow from it: like a new star it shall scatter the darkness of ignorance, and cause a light heretofore unknown to shine amongst men.</p>
+        <footer>— <a href="https://sites.google.com/site/johanngutenbergper5/q">Johannes Gutenberg</a></cite></footer>
+    </blockquote>
+</div>
+
+<div class="page-break-after">
+    {{ toHTML "markdown1.md" }}
+
+    <div class="google-font">
+        {{ toHTML "markdown2.md" }}
+    </div>
+
+    <div class="local-font">
+        {{ toHTML "markdown3.md" }}
+    </div>
+</div>
+</body>
+</html>

test/testdata/chromium/markdown/sample1/markdown1.md

@@ -0,0 +1,3 @@
+## This paragraph uses the default font and has been generated from a markdown file
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.