fix(chromium): assets not loading

Bumps [github.com/chromedp/chromedp](https://github.com/chromedp/chromedp) from 0.14.2 to 0.15.0.
- [Release notes](https://github.com/chromedp/chromedp/releases)
- [Commits](https://github.com/chromedp/chromedp/compare/v0.14.2...v0.15.0)

---
updated-dependencies:
- dependency-name: github.com/chromedp/chromedp
  dependency-version: 0.15.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

.bruno/AGENTS.md

@@ -0,0 +1,65 @@
+# Bruno API Collection
+
+A [Bruno](https://www.usebruno.com/) collection lives in `.bruno/` and mirrors every Gotenberg route. When adding or updating a route, update the collection to match.
+
+## Structure
+
+```
+.bruno/
+├── bruno.json                     # Collection config
+├── collection.bru                 # Collection-level defaults (Gotenberg-Trace header)
+├── environments/
+│   ├── Local.bru                  # baseUrl: http://localhost:3000
+│   └── Demo.bru                   # baseUrl: https://demo.gotenberg.dev
+├── Health & Info/                  # GET routes
+├── Chromium/Convert/               # POST routes grouped by module
+├── Chromium/Screenshot/
+├── LibreOffice/
+└── PDF Engines/<Feature>/          # One folder per feature (Merge, Split, Rotate, …)
+```
+
+## `.bru` File Format
+
+```bru
+meta {
+  name: <Human-readable name>
+  type: http
+  seq: <order within folder>
+}
+
+post {
+  url: {{baseUrl}}/forms/<path>
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/<file>)
+  <mandatoryField>: <value>
+  ~<optionalField>: <value>
+}
+
+headers {
+  ~Gotenberg-Output-Filename: <name>
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}
+```
+
+## Conventions
+
+- **Mandatory fields** are listed without prefix; **optional fields** are prefixed with `~` (disabled by default in Bruno).
+- **File references** use relative paths to `test/integration/testdata/`.
+- **Webhook and output filename headers** are included on every POST route as optional (`~`).
+- **One `.bru` file per request**. For routes with read/write variants (e.g., bookmarks, metadata), create separate files in the same folder.
+
+## Checklist When Adding/Updating a Route
+
+1. Create or update the `.bru` file in the matching folder under `.bruno/`.
+2. Include all form fields from the route handler — check `FormData*` calls in the route function.
+3. For file upload fields (`files`, `watermark`, `stamp`, `embeds`), use `@file(...)` with a suitable test file.
+4. Verify the URL path matches the route's `Path` field exactly.
+5. If you add a new module folder, keep the naming consistent (e.g., `PDF Engines/Rotate/`).

.bruno/Chromium/Convert/HTML to PDF.bru

@@ -0,0 +1,73 @@
+meta {
+  name: HTML to PDF
+  type: http
+  seq: 2
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/convert/html
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page-1-html/index.html)
+  ~landscape: false
+  ~printBackground: false
+  ~scale: 1.0
+  ~singlePage: false
+  ~paperWidth: 8.5
+  ~paperHeight: 11
+  ~marginTop: 0.39
+  ~marginBottom: 0.39
+  ~marginLeft: 0.39
+  ~marginRight: 0.39
+  ~nativePageRanges: 1-2
+  ~preferCssPageSize: false
+  ~generateDocumentOutline: false
+  ~generateTaggedPdf: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: print
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+  ~splitMode: intervals
+  ~splitSpan: 1
+  ~splitUnify: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-file
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Chromium/Convert/Markdown to PDF.bru

@@ -0,0 +1,74 @@
+meta {
+  name: Markdown to PDF
+  type: http
+  seq: 3
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/convert/markdown
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page-1-markdown/index.html)
+  files: @file(../../test/integration/testdata/page-1-markdown/page_1.md)
+  ~landscape: false
+  ~printBackground: false
+  ~scale: 1.0
+  ~singlePage: false
+  ~paperWidth: 8.5
+  ~paperHeight: 11
+  ~marginTop: 0.39
+  ~marginBottom: 0.39
+  ~marginLeft: 0.39
+  ~marginRight: 0.39
+  ~nativePageRanges: 1-2
+  ~preferCssPageSize: false
+  ~generateDocumentOutline: false
+  ~generateTaggedPdf: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: print
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+  ~splitMode: intervals
+  ~splitSpan: 1
+  ~splitUnify: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-file
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Chromium/Convert/URL to PDF.bru

@@ -0,0 +1,73 @@
+meta {
+  name: URL to PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/convert/url
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  url: https://example.com
+  ~landscape: false
+  ~printBackground: false
+  ~scale: 1.0
+  ~singlePage: false
+  ~paperWidth: 8.5
+  ~paperHeight: 11
+  ~marginTop: 0.39
+  ~marginBottom: 0.39
+  ~marginLeft: 0.39
+  ~marginRight: 0.39
+  ~nativePageRanges: 1-2
+  ~preferCssPageSize: false
+  ~generateDocumentOutline: false
+  ~generateTaggedPdf: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: print
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+  ~splitMode: intervals
+  ~splitSpan: 1
+  ~splitUnify: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-file
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Chromium/Screenshot/HTML Screenshot.bru

@@ -0,0 +1,47 @@
+meta {
+  name: HTML Screenshot
+  type: http
+  seq: 2
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/screenshot/html
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page-1-html/index.html)
+  ~width: 800
+  ~height: 600
+  ~clip: false
+  ~format: png
+  ~quality: 100
+  ~optimizeForSpeed: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: screen
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-screenshot
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Chromium/Screenshot/Markdown Screenshot.bru

@@ -0,0 +1,48 @@
+meta {
+  name: Markdown Screenshot
+  type: http
+  seq: 3
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/screenshot/markdown
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page-1-markdown/index.html)
+  files: @file(../../test/integration/testdata/page-1-markdown/page_1.md)
+  ~width: 800
+  ~height: 600
+  ~clip: false
+  ~format: png
+  ~quality: 100
+  ~optimizeForSpeed: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: screen
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-screenshot
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Chromium/Screenshot/URL Screenshot.bru

@@ -0,0 +1,47 @@
+meta {
+  name: URL Screenshot
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/chromium/screenshot/url
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  url: https://example.com
+  ~width: 800
+  ~height: 600
+  ~clip: false
+  ~format: png
+  ~quality: 100
+  ~optimizeForSpeed: false
+  ~skipNetworkIdleEvent: false
+  ~failOnHttpStatusCodes: [499,599]
+  ~failOnResourceHttpStatusCodes: []
+  ~ignoreResourceHttpStatusDomains: []
+  ~failOnResourceLoadingFailed: false
+  ~failOnConsoleExceptions: false
+  ~waitDelay: 0s
+  ~waitWindowStatus:
+  ~waitForExpression:
+  ~waitForSelector:
+  ~cookies: [{"name":"my_cookie","value":"my_value","domain":"example.com"}]
+  ~userAgent:
+  ~extraHttpHeaders: {"X-Custom-Header":"value"}
+  ~emulatedMediaType: screen
+  ~emulatedMediaFeatures: {"prefers-color-scheme":"dark"}
+  ~omitBackground: false
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-screenshot
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/Health & Info/Debug.bru

@@ -0,0 +1,11 @@
+meta {
+  name: Debug
+  type: http
+  seq: 3
+}
+
+get {
+  url: {{baseUrl}}/debug
+  body: none
+  auth: none
+}

.bruno/Health & Info/Health.bru

@@ -0,0 +1,11 @@
+meta {
+  name: Health
+  type: http
+  seq: 1
+}
+
+get {
+  url: {{baseUrl}}/health
+  body: none
+  auth: none
+}

.bruno/Health & Info/Prometheus Metrics.bru

@@ -0,0 +1,11 @@
+meta {
+  name: Prometheus Metrics
+  type: http
+  seq: 4
+}
+
+get {
+  url: {{baseUrl}}/prometheus/metrics
+  body: none
+  auth: none
+}

.bruno/Health & Info/Version.bru

@@ -0,0 +1,11 @@
+meta {
+  name: Version
+  type: http
+  seq: 2
+}
+
+get {
+  url: {{baseUrl}}/version
+  body: none
+  auth: none
+}

.bruno/LibreOffice/Convert to PDF.bru

@@ -0,0 +1,90 @@
+meta {
+  name: Convert to PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/libreoffice/convert
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.docx)
+  ~password:
+  ~landscape: false
+  ~nativePageRanges:
+  ~updateIndexes: false
+  ~exportFormFields: true
+  ~allowDuplicateFieldNames: false
+  ~exportBookmarks: true
+  ~exportBookmarksToPdfDestination: false
+  ~exportPlaceholders: false
+  ~exportNotes: false
+  ~exportNotesPages: false
+  ~exportOnlyNotesPages: false
+  ~exportNotesInMargin: false
+  ~convertOooTargetToPdfTarget: false
+  ~exportLinksRelativeFsys: false
+  ~exportHiddenSlides: false
+  ~skipEmptyPages: false
+  ~addOriginalDocumentAsStream: false
+  ~singlePageSheets: false
+  ~initialView: 0
+  ~initialPage: 1
+  ~magnification: 0
+  ~zoom: 100
+  ~pageLayout: 0
+  ~firstPageOnLeft: false
+  ~resizeWindowToInitialPage: false
+  ~centerWindow: false
+  ~openInFullScreenMode: false
+  ~displayPDFDocumentTitle: true
+  ~hideViewerMenubar: false
+  ~hideViewerToolbar: false
+  ~hideViewerWindowControls: false
+  ~useTransitionEffects: true
+  ~openBookmarkLevels: -1
+  ~losslessImageCompression: false
+  ~quality: 90
+  ~reduceImageResolution: false
+  ~maxImageResolution: 300
+  ~nativeWatermarkText:
+  ~nativeWatermarkColor: 0
+  ~nativeWatermarkFontHeight: 0
+  ~nativeWatermarkRotateAngle: 0
+  ~nativeWatermarkFontName:
+  ~nativeTiledWatermarkText:
+  ~nativePdfFormats: true
+  ~merge: false
+  ~flatten: false
+  ~splitMode: intervals
+  ~splitSpan: 1
+  ~splitUnify: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: my-file
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Bookmarks/Read Bookmarks.bru

@@ -0,0 +1,24 @@
+meta {
+  name: Read Bookmarks
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/bookmarks/read
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+}
+
+headers {
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Bookmarks/Write Bookmarks.bru

@@ -0,0 +1,26 @@
+meta {
+  name: Write Bookmarks
+  type: http
+  seq: 2
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/bookmarks/write
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  bookmarks: [{"title":"Chapter 1","page":1,"children":[{"title":"Section 1.1","page":1}]}]
+}
+
+headers {
+  ~Gotenberg-Output-Filename: with-bookmarks
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Convert/Convert PDF.bru

@@ -0,0 +1,27 @@
+meta {
+  name: Convert PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/convert
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  pdfa: PDF/A-1b
+  ~pdfua: true
+}
+
+headers {
+  ~Gotenberg-Output-Filename: converted
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Embed/Embed Files.bru

@@ -0,0 +1,27 @@
+meta {
+  name: Embed Files
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/embed
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  embeds: @file(../../test/integration/testdata/page_1.pdf)
+  ~downloadFrom: [{"url":"https://example.com/attachment.xml","embedded":true}]
+}
+
+headers {
+  ~Gotenberg-Output-Filename: with-embeds
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Encrypt/Encrypt PDF.bru

@@ -0,0 +1,27 @@
+meta {
+  name: Encrypt PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/encrypt
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  userPassword: secret123
+  ~ownerPassword: owner456
+}
+
+headers {
+  ~Gotenberg-Output-Filename: encrypted
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Flatten/Flatten PDF.bru

@@ -0,0 +1,25 @@
+meta {
+  name: Flatten PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/flatten
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+}
+
+headers {
+  ~Gotenberg-Output-Filename: flattened
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Merge/Merge PDFs.bru

@@ -0,0 +1,44 @@
+meta {
+  name: Merge PDFs
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/merge
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  files: @file(../../test/integration/testdata/page_2.pdf)
+  ~flatten: false
+  ~autoIndexBookmarks: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~bookmarks: [{"title":"Page 1","page":1},{"title":"Page 2","page":2}]
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: merged
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Metadata/Read Metadata.bru

@@ -0,0 +1,24 @@
+meta {
+  name: Read Metadata
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/metadata/read
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+}
+
+headers {
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Metadata/Write Metadata.bru

@@ -0,0 +1,26 @@
+meta {
+  name: Write Metadata
+  type: http
+  seq: 2
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/metadata/write
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  metadata: {"Author":"Bruno","Copyright":"Bruno","Creator":"Gotenberg","Keywords":["test"],"Marked":true,"Producer":"Gotenberg","Subject":"Test","Title":"Test Document","Trapped":"Unknown"}
+}
+
+headers {
+  ~Gotenberg-Output-Filename: with-metadata
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Rotate/Rotate PDF.bru

@@ -0,0 +1,27 @@
+meta {
+  name: Rotate PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/rotate
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  rotateAngle: 90
+  ~rotatePages: 1-2
+}
+
+headers {
+  ~Gotenberg-Output-Filename: rotated
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Split/Split PDF.bru

@@ -0,0 +1,44 @@
+meta {
+  name: Split PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/split
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/pages_3.pdf)
+  splitMode: intervals
+  splitSpan: 1
+  ~splitUnify: false
+  ~flatten: false
+  ~pdfa: PDF/A-1b
+  ~pdfua: true
+  ~metadata: {"Author":"Bruno","Title":"Test"}
+  ~userPassword:
+  ~ownerPassword:
+  ~watermarkSource: text
+  ~watermarkExpression: CONFIDENTIAL
+  ~watermarkPages:
+  ~watermarkOptions: {"scale":"0.5 abs","rot":"45","fillcolor":"#FF0000"}
+  ~stampSource: text
+  ~stampExpression: DRAFT
+  ~stampPages:
+  ~stampOptions: {"scale":"0.5 abs","rot":"45"}
+  ~rotateAngle: 90
+  ~rotatePages:
+}
+
+headers {
+  ~Gotenberg-Output-Filename: split
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Stamp/Stamp PDF.bru

@@ -0,0 +1,31 @@
+meta {
+  name: Stamp PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/stamp
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  stampSource: text
+  stampExpression: APPROVED
+  ~stampPages: 1-2
+  ~stampOptions: {"font":"Helvetica","fontSize":"48","color":"#00FF00","opacity":"0.5","rotation":"0"}
+  ~stamp: @file(../../test/integration/testdata/watermark.png)
+  ~downloadFrom: [{"url":"https://example.com/stamp.png","field":"stamp"}]
+}
+
+headers {
+  ~Gotenberg-Output-Filename: stamped
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/PDF Engines/Watermark/Watermark PDF.bru

@@ -0,0 +1,31 @@
+meta {
+  name: Watermark PDF
+  type: http
+  seq: 1
+}
+
+post {
+  url: {{baseUrl}}/forms/pdfengines/watermark
+  body: multipartForm
+  auth: none
+}
+
+body:multipart-form {
+  files: @file(../../test/integration/testdata/page_1.pdf)
+  watermarkSource: text
+  watermarkExpression: CONFIDENTIAL
+  ~watermarkPages: 1-2
+  ~watermarkOptions: {"font":"Helvetica","fontSize":"48","color":"#FF0000","opacity":"0.3","rotation":"45"}
+  ~watermark: @file(../../test/integration/testdata/watermark.png)
+  ~downloadFrom: [{"url":"https://example.com/watermark.png","field":"watermark"}]
+}
+
+headers {
+  ~Gotenberg-Output-Filename: watermarked
+  ~Gotenberg-Webhook-Url: http://localhost:8080/webhook
+  ~Gotenberg-Webhook-Error-Url: http://localhost:8080/webhook/error
+  ~Gotenberg-Webhook-Events-Url: http://localhost:8080/webhook/events
+  ~Gotenberg-Webhook-Method: POST
+  ~Gotenberg-Webhook-Error-Method: POST
+  ~Gotenberg-Webhook-Extra-Http-Headers: {"X-Custom":"value"}
+}

.bruno/bruno.json

@@ -0,0 +1,6 @@
+{
+  "version": "1",
+  "name": "Gotenberg",
+  "type": "collection",
+  "ignore": ["node_modules", ".git"]
+}

.bruno/collection.bru

@@ -0,0 +1,3 @@
+headers {
+  Gotenberg-Trace: {{traceId}}
+}

.bruno/environments/Demo.bru

@@ -0,0 +1,4 @@
+vars {
+  baseUrl: https://demo.gotenberg.dev
+  traceId: bruno-demo
+}

.bruno/environments/Local.bru

@@ -0,0 +1,4 @@
+vars {
+  baseUrl: http://localhost:3000
+  traceId: bruno-local
+}

.github/actions/build-test-push/action.yml

@@ -48,7 +48,7 @@ runs:
       uses: docker/setup-buildx-action@v3
 
     - name: Check out code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Log in to Docker Hub
       if: inputs.docker_hub_username != ''
@@ -60,30 +60,43 @@ runs:
     - name: Build ${{ inputs.platform }}
       id: build
       shell: bash
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+        INPUT_PLATFORM: ${{ inputs.platform }}
+        INPUT_ALTERNATE_REPOSITORY: ${{ inputs.alternate_repository }}
+        INPUT_DRY_RUN: ${{ inputs.dry_run }}
       run: |
         .github/actions/build-test-push/build.sh \
-          --version "${{ inputs.version }}" \
-          --platform "${{ inputs.platform }}" \
-          --alternate-repository "${{ inputs.alternate_repository }}" \
-          --dry-run "${{ inputs.dry_run }}"
+          --version "$INPUT_VERSION" \
+          --platform "$INPUT_PLATFORM" \
+          --alternate-repository "$INPUT_ALTERNATE_REPOSITORY" \
+          --dry-run "$INPUT_DRY_RUN"
 
     - name: Run integration tests
       if: inputs.skip_integrations_tests != 'true'
       shell: bash
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+        INPUT_PLATFORM: ${{ inputs.platform }}
+        INPUT_ALTERNATE_REPOSITORY: ${{ inputs.alternate_repository }}
+        INPUT_DRY_RUN: ${{ inputs.dry_run }}
       run: |
         .github/actions/build-test-push/test.sh \
-          --version "${{ inputs.version }}" \
-          --platform "${{ inputs.platform }}" \
-          --alternate-repository "${{ inputs.alternate_repository }}" \
-          --dry-run "${{ inputs.dry_run }}"
+          --version "$INPUT_VERSION" \
+          --platform "$INPUT_PLATFORM" \
+          --alternate-repository "$INPUT_ALTERNATE_REPOSITORY" \
+          --dry-run "$INPUT_DRY_RUN"
 
     - name: Push
       if: inputs.docker_hub_username != ''
       shell: bash
+      env:
+        INPUT_TAGS: ${{ steps.build.outputs.tags }},${{ steps.build.outputs.tags_cloud_run }},${{ steps.build.outputs.tags_aws_lambda }}
+        INPUT_DRY_RUN: ${{ inputs.dry_run }}
       run: |
         .github/actions/build-test-push/push.sh \
-          --tags "${{ steps.build.outputs.tags }},${{ steps.build.outputs.tags_cloud_run }},${{ steps.build.outputs.tags_aws_lambda }}" \
-          --dry-run "${{ inputs.dry_run }}"
+          --tags "$INPUT_TAGS" \
+          --dry-run "$INPUT_DRY_RUN"
 
     - name: Outputs
       shell: bash

.github/actions/clean/action.yml

@@ -23,9 +23,12 @@ runs:
       env:
         DOCKERHUB_USERNAME: ${{ inputs.docker_hub_username }}
         DOCKERHUB_TOKEN: ${{ inputs.docker_hub_password }}
+        INPUT_TAGS: ${{ inputs.tags }}
+        INPUT_SNAPSHOT_VERSION: ${{ inputs.snapshot_version }}
+        INPUT_DRY_RUN: ${{ inputs.dry_run }}
       shell: bash
       run: |
         .github/actions/clean/clean.sh \
-          --tags "${{ inputs.tags }}" \
-          --snapshot-version "${{ inputs.snapshot_version }}" \
-          --dry-run "${{ inputs.dry_run }}"
+          --tags "$INPUT_TAGS" \
+          --snapshot-version "$INPUT_SNAPSHOT_VERSION" \
+          --dry-run "$INPUT_DRY_RUN"

.github/actions/merge/action.yml

@@ -31,7 +31,7 @@ runs:
       uses: docker/setup-buildx-action@v3
 
     - name: Check out code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Log in to Docker Hub
       uses: docker/login-action@v3
@@ -41,8 +41,12 @@ runs:
 
     - name: Merge
       shell: bash
+      env:
+        INPUT_TAGS: ${{ inputs.tags }}
+        INPUT_ALTERNATE_REGISTRY: ${{ inputs.alternate_registry }}
+        INPUT_DRY_RUN: ${{ inputs.dry_run }}
       run: |
         .github/actions/merge/merge.sh \
-          --tags "${{ inputs.tags }}" \
-          --alternate-registry "${{ inputs.alternate_registry }}" \
-          --dry-run "${{ inputs.dry_run }}"
+          --tags "$INPUT_TAGS" \
+          --alternate-registry "$INPUT_ALTERNATE_REGISTRY" \
+          --dry-run "$INPUT_DRY_RUN"

.golangci.yml

@@ -24,13 +24,14 @@ linters:
     - ineffassign
     - misspell
     - prealloc
-    - promlinter
     - staticcheck
     - testableexamples
     - tparallel
     - unconvert
     - unused
+    - sloglint
     - usetesting
+    - gocritic
     - wastedassign
     - whitespace
   exclusions:
@@ -40,10 +41,6 @@ linters:
       - common-false-positives
       - legacy
       - std-error-handling
-    paths:
-      - third_party$
-      - builtin$
-      - examples$
 formatters:
   enable:
     - gci
@@ -59,7 +56,3 @@ formatters:
       custom-order: true
   exclusions:
     generated: lax
-    paths:
-      - third_party$
-      - builtin$
-      - examples$

AGENTS.md

@@ -1,66 +1,181 @@
 # Operational Guidelines for Gotenberg
 
-As an AI agent working on the Gotenberg repository, you are expected to act with the diligence and architectural foresight of a Senior Go Engineer. Gotenberg is a widely used production dependency; stability and backward compatibility are paramount.
+You are working on **Gotenberg**, a Docker-based API for converting documents to PDF. It is a widely used production dependency. Stability and backward compatibility are paramount. When in doubt about whether a change is breaking, flag it rather than assuming it's safe.
 
-## 1. Core Philosophy & Stability
+## Mandatory Workflow
 
-- **Backward Compatibility is Law:** This project creates a public API. Never modify existing flags, configuration environment variables, or API form fields unless explicitly instructed to perform a breaking change. If a change is breaking, it must be flagged immediately in the plan.
-- **Defensive Programming:** Assume input data is malformed. Handle errors explicitly. Do not panic.
-- **Atomic Commits:** Isolate refactoring from feature additions. A Pull Request should do one thing well.
+Every task MUST follow these five steps in order. Do not skip any step.
 
-## 2. Development Workflow & Tooling
+### Step 1 — Plan
 
-You must rely strictly on the project's Makefile for build and verification tasks. Do not run `go` commands directly unless debugging a specific package requires it.
+Before writing any code, produce a plan that covers:
 
-- **Formatting:** Run `make fmt` to format Go code before committing.
-- **Linting:**
-  - Run `make lint` to ensure Go code strictly adheres to the `.golangci.yml` configuration.
-  - Run `make lint-prettier` to verify formatting for non-Go files (Markdown, YAML, etc.).
-  - Zero linting errors are permitted.
-- **Building:** Run `make build` to verify compilation and Docker image construction.
+- **Problem statement**: What needs to change and why.
+- **Proposed solution**: The recommended approach with enough detail to implement (files to modify, interface changes, pipeline positioning, form fields, etc.).
+- **Alternatives considered**: At least one alternative approach when pertinent, with a brief explanation of why the proposed solution is preferred.
+- **Scope**: List every file that will be created or modified.
+- **Testing strategy**: Which integration test tags will be affected, what new scenarios are needed, and whether unit tests are required.
 
-## 3. Architecture & Code Structure
+Present the plan to the user and wait for approval before proceeding to Step 2. If the user provides a plan, validate it against the codebase and flag any issues before implementing.
 
-- **Idiomatic Go:** Follow "Effective Go" principles.
-- **Directory Separation:**
-  - `cmd/`: Application entry points only. Contains wiring and startup logic. **No business logic is permitted here.**
-  - `pkg/`: Core library code and modules. All business logic resides here.
-- **Module System:** Gotenberg is modular (e.g., Chromium, LibreOffice). When adding features, determine if they belong to an existing module or require a new strict isolation.
+### Step 2 — Implement
 
-## 4. Testing Standards
+Implement the approved plan following the coding standards and patterns described in this document. After implementation, verify the build compiles (`go build ./...`).
 
-Gotenberg utilizes a split testing strategy. **Integration tests are the primary and preferred method for verifying features.**
+### Step 3 — Test
 
-- **Integration Tests (`make test-integration`):**
-  - **First Priority:** Always start here when adding features or routes.
-  - Gotenberg uses **Gherkin (Godog)** for end-to-end verification.
-  - You **must** create or update the corresponding `.feature` file in `test/integration`.
-  - These tests run within the Docker context; ensure environment consistency.
-- **Unit Tests (`make test-unit`):**
-  - Use table-driven tests for pure logic within `pkg/`.
-  - Mock external dependencies (filesystem, network) where appropriate.
+Write or update tests based on the plan's testing strategy:
 
-## 5. Documentation Requirements
+- **Integration tests** (primary): Gherkin scenarios in `test/integration/features/`. See [`test/integration/AGENTS.md`](test/integration/AGENTS.md) for the full reference.
+- **Unit tests** (when applicable): Table-driven tests in `*_test.go` files using mocks from `pkg/gotenberg/mocks.go`.
 
-- **No README Updates:** Do not modify the root `README.md` unless explicitly asked.
-- **GoDoc is Mandatory:**
-  - **New Packages:** If creating a new package, you must include a `doc.go` file containing the package-level documentation.
-  - **Exported Symbols:** Every exported function, type, constant, and variable must have a proper GoDoc comment starting with its name.
-  - **Quality:** Comments must be complete sentences explaining _what_ the symbol does and _how_ to use it.
-  - **Example:**
-    ```go
-    // Convert transforms the input document to PDF using the Chromium engine.
-    // It returns an error if the connection to the browser instance fails.
-    func Convert(...) error
-    ```
+### Step 4 — Review
 
-## 6. Definition of Done
+Self-review the implementation against the [Review Checklist](#review-checklist). Fix any issues found before presenting the result to the user.
 
-A task is considered complete only when:
+### Step 5 — Commit
 
-1.  The code compiles via `make build`.
-2.  The code is formatted via `make fmt`.
-3.  All linters pass via `make lint` and `make lint-prettier`.
-4.  Integration scenarios pass via `make test-integration`.
-5.  Unit tests pass via `make test-unit`.
-6.  All exported symbols and new packages have compliant GoDoc.
+Present the review to the user and **wait for explicit approval**. Do NOT commit until the user confirms. Once approved, create a commit following the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+<type>(<scope>): <description>
+```
+
+Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `build`. The scope should match the module or area of the change (e.g., `chromium`, `pdfengines`, `api`).
+
+Stage only the files related to the change. Do not use `git add -A` or `git add .`.
+
+---
+
+## Core Principles
+
+- **Backward compatibility is law.** Never modify existing CLI flags, environment variables, or API form fields unless explicitly instructed to perform a breaking change. Flag any breaking change immediately.
+- **Defensive programming.** Assume input is malformed. Handle errors explicitly. Never panic.
+- **Atomic commits.** One feature or fix per PR. Isolate refactoring from feature work.
+- **Idiomatic Go.** Follow "Effective Go" principles. All exported symbols must have GoDoc comments starting with their name.
+
+## Project Layout
+
+```
+cmd/gotenberg/       → Entry point only (wiring/startup). No business logic.
+pkg/gotenberg/       → Core module system, interfaces, utilities, mocks.
+pkg/modules/         → Feature modules (api, chromium, libreoffice, pdfengines, etc.).
+pkg/standard/        → Wires all standard modules together via imports.
+test/integration/    → Gherkin feature files + Go test infrastructure.
+build/               → Dockerfile, fonts, Chromium config.
+.bruno/              → Bruno API collection (mirrors every route).
+```
+
+Key interfaces live in `pkg/gotenberg/` — `Module`, `Provisioner`, `Validator`, `Debuggable`. Every module implements `Descriptor()` and self-registers. When adding features, determine if they belong in an existing module or require a new one.
+
+## Codebase Navigation
+
+- Start with `pkg/gotenberg/` for core interfaces and `pkg/modules/` for feature implementations.
+- The integration test infrastructure in `test/integration/scenario/` is well-structured — read `scenario.go` and `containers.go` to understand the Gherkin step definitions before writing new tests.
+- Mocks for all major interfaces are in `pkg/gotenberg/mocks.go` — use them for unit tests rather than creating new ones.
+- Import ordering is enforced: standard library, third-party, then `github.com/gotenberg/gotenberg/v8` — separated by blank lines.
+- When making changes, run only the relevant integration test tag rather than the full suite (40min timeout).
+- Telemetry infrastructure lives in `pkg/gotenberg/telemetry.go` (global Logger, Tracer, Meter) and `pkg/gotenberg/internal/` (log handlers, OTEL SDK init). HTTP semantic conventions are in `pkg/gotenberg/semconv/`.
+
+---
+
+## Makefile — the Only Build Interface
+
+All build and verification tasks go through the Makefile. Do not run `go` commands directly unless debugging a specific package.
+
+| Command                 | Purpose                                                       | When to use                                                                  |
+| ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `make build`            | Build the Docker image                                        | Before integration tests, or to verify compilation                           |
+| `make run`              | Run Gotenberg container via `docker compose`                  | Manual testing. Flags are configured via Makefile variables and compose.yaml |
+| `make telemetry`        | Start OpenTelemetry collector and OpenObserve                 | When testing telemetry locally                                               |
+| `make down`             | Stop all compose containers                                   | After manual testing                                                         |
+| `make fmt`              | Format Go code (`go fix`, `golangci-lint fmt`, `go mod tidy`) | Before every commit                                                          |
+| `make lint`             | Lint Go code (strict `.golangci.yml` config)                  | Before every commit. Zero errors permitted                                   |
+| `make lint-prettier`    | Lint non-Go files (Markdown, YAML, etc.) with Prettier        | Before every commit                                                          |
+| `make prettify`         | Format non-Go files (Markdown, YAML, etc.) with Prettier      | Before every commit                                                          |
+| `make test-unit`        | Run unit tests (`go test -race ./...`)                        | After code changes to `pkg/`                                                 |
+| `make test-integration` | Run integration tests (Gherkin/Godog, 40min timeout)          | After any feature or route change                                            |
+| `make godoc`            | Serve GoDoc at `localhost:6060`                               | To verify documentation                                                      |
+
+## Module System
+
+Gotenberg uses a self-registering module architecture inspired by CaddyServer. Each module:
+
+- Lives in `pkg/modules/<name>/`
+- Implements the `gotenberg.Module` interface (at minimum `Descriptor()`)
+- May also implement `gotenberg.Provisioner`, `gotenberg.Validator`, or `gotenberg.Debuggable`
+- Self-registers via `init()` and is wired through `pkg/standard/`
+
+When adding a feature, first determine if it belongs in an existing module. Only create a new module if the feature represents a genuinely separate concern.
+
+## Coding Patterns
+
+- **Error handling:** Always wrap errors with context using `fmt.Errorf("description: %w", err)`. Never swallow errors silently.
+- **Import ordering:** Enforced by `gci` — standard library, then third-party, then `github.com/gotenberg/gotenberg/v8`. Three groups separated by blank lines.
+- **Mocks:** Comprehensive mock implementations for all major interfaces live in `pkg/gotenberg/mocks.go`. Use these for unit tests.
+- **Logging:** Use `gotenberg.Logger(mod)` to get the module's slog logger during `Provision()`. All log calls must be context-aware: `logger.DebugContext(ctx, msg)`, `logger.InfoContext(ctx, msg)`, `logger.ErrorContext(ctx, msg)`. This propagates trace/span IDs into structured logs when OpenTelemetry is active.
+- **Telemetry:** External tool calls (Chromium, LibreOffice, PDF engines, webhooks, downloads) must create OTEL spans with `trace.SpanKindClient` and `semconv.ServerAddress("toolname")`. Use `gotenberg.Tracer()` and `gotenberg.Meter()` for traces and metrics respectively.
+- **No business logic in `cmd/`:** The `cmd/gotenberg/` package is strictly for wiring and startup.
+
+---
+
+## Review Checklist
+
+### Backward Compatibility
+
+- [ ] No existing CLI flags renamed or removed
+- [ ] No existing environment variables renamed or removed
+- [ ] No existing API form fields renamed or removed
+- [ ] No existing HTTP endpoints changed or removed
+- [ ] No changes to default values that alter existing behavior
+- [ ] Deprecated flags have both old and new names registered, with `fs.MarkDeprecated()`
+
+If any of these are violated, the change **must** be flagged as a breaking change.
+
+### Linting Standards
+
+The `.golangci.yml` enforces strict rules including: `gosec`, `govet`, `errcheck`, `staticcheck`, `dupl`, `bodyclose`, `exhaustive`, `errname`, `sloglint`, `gocritic`, and more. Zero linting errors are permitted.
+
+Formatters enforce `gci`, `gofmt`, `gofumpt`, `goimports` with import ordering:
+
+1. Standard library
+2. Third-party packages
+3. `github.com/gotenberg/gotenberg/v8`
+
+Three groups separated by blank lines.
+
+### Code Quality
+
+- Errors are wrapped with context: `fmt.Errorf("description: %w", err)`. No swallowed errors.
+- No business logic in `cmd/`.
+- No panics in production code paths.
+- Input is validated defensively.
+- New features belong in the correct module (or justify a new one).
+
+### Documentation
+
+- Every exported function, type, constant, and variable has a GoDoc comment starting with its name.
+- New packages include a `doc.go` file.
+- `README.md` is not modified unless explicitly requested.
+
+### Definition of Done
+
+A change is ready to merge only when:
+
+1. Code compiles: `go build ./...`
+2. Code is formatted: `make fmt`
+3. All linters pass: `make lint` and `make lint-prettier`
+4. Integration tests pass: `make test-integration` (at minimum, the relevant `TAGS`)
+5. Unit tests pass: `make test-unit`
+6. All exported symbols and new packages have compliant GoDoc
+7. Bruno collection is updated (if routes were added or modified)
+
+---
+
+## Scoped Guidelines
+
+Detailed guidelines for specific areas of the codebase live in their own `AGENTS.md` files:
+
+- [`test/integration/AGENTS.md`](test/integration/AGENTS.md) — Integration test framework, Gherkin step reference, available tags, and how to write new tests.
+- [`.bruno/AGENTS.md`](.bruno/AGENTS.md) — Bruno API collection structure, `.bru` file format, conventions, and route update checklist.
+- [`pkg/modules/pdfengines/AGENTS.md`](pkg/modules/pdfengines/AGENTS.md) — How to add new PDF engine features (Makefile variable and flag).

CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Code — Gotenberg
+
+Read [AGENTS.md](AGENTS.md) first. It contains everything: core principles, project layout, coding standards, the mandatory 4-step workflow (Plan → Implement → Test → Review), integration test reference, review checklist, and Bruno collection guidelines.

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to Gotenberg
+
+Thank you for your interest in contributing to Gotenberg! This guide will help you get started.
+
+## Getting Started
+
+### Prerequisites
+
+- Go (see version in `go.mod`)
+- Docker
+- Node.js (see version in `.node-version`) — for Prettier linting
+- [golangci-lint](https://golangci-lint.run/) v2+
+
+### Build and Run
+
+```bash
+make build # Build the Docker image
+make run   # Run a local Gotenberg container
+```
+
+### Development Loop
+
+```bash
+# Write your code, then:
+make fmt              # Format Go code
+make prettify         # Format non-Go files (Markdown, YAML, etc.)
+make lint             # Lint Go code (zero errors permitted)
+make lint-prettier    # Lint non-Go files
+make test-unit        # Run unit tests
+make build            # Build the Docker image (required before integration tests)
+make test-integration # Run all integration tests
+make telemetry        # Start OpenTelemetry collector and OpenObserve
+make down             # Stop all compose containers
+```
+
+To run only the integration tests relevant to your change:
+
+```bash
+make test-integration TAGS=health
+make test-integration TAGS=chromium-convert-html
+make test-integration TAGS="merge,split"
+```
+
+## Submitting a Pull Request
+
+Before opening a PR, verify:
+
+1. Code compiles: `make build`
+2. Code is formatted: `make fmt` and `make prettify`
+3. All linters pass: `make lint` and `make lint-prettier`
+4. Integration tests pass: `make test-integration` (at minimum, the relevant tags)
+5. Unit tests pass: `make test-unit`
+6. All exported symbols and new packages have GoDoc comments
+
+### Guidelines
+
+- **Conventional Commits.** Commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `feat(chromium): add screenshot endpoint`, `fix(api): handle empty body`).
+- **One thing per PR.** Keep features, bug fixes, and refactoring in separate PRs.
+- **Backward compatibility matters.** Do not rename or remove existing CLI flags, environment variables, or API form fields without discussion.
+- **Integration tests first.** When adding a feature or route, start by writing the Gherkin scenario in `test/integration/features/`.
+- **Logging uses `gotenberg.Logger(mod)`** with context-aware calls (`*Context` variants).
+- **External operations have OTEL traces** with appropriate SpanKind and semconv attributes.
+- **No business logic in `cmd/`.** All logic belongs in `pkg/`.
+
+## Detailed Guidelines
+
+The [`AGENTS.md`](AGENTS.md) files contain comprehensive guidelines used by both human contributors and AI-assisted tools:
+
+| File                                                                   | What it covers                                                                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| [`AGENTS.md`](AGENTS.md)                                               | Core principles, mandatory workflow, project layout, coding patterns, module system, Makefile reference, review checklist |
+| [`test/integration/AGENTS.md`](test/integration/AGENTS.md)             | Integration test framework (Godog/Gherkin), available tags, step reference, how to write new tests                        |
+| [`.bruno/AGENTS.md`](.bruno/AGENTS.md)                                 | Bruno API collection structure, `.bru` file format, conventions, route update checklist                                   |
+| [`pkg/modules/pdfengines/AGENTS.md`](pkg/modules/pdfengines/AGENTS.md) | How to add new PDF engine features (Makefile variable and flag)                                                           |

GEMINI.md

@@ -0,0 +1,3 @@
+# Gemini — Gotenberg
+
+Read [AGENTS.md](AGENTS.md) first. It contains everything: core principles, project layout, coding standards, the mandatory 4-step workflow (Plan → Implement → Test → Review), integration test reference, review checklist, and Bruno collection guidelines.

Makefile

@@ -29,13 +29,14 @@ API_DOWNLOAD_FROM_ALLOW_LIST=
 API_DOWNLOAD_FROM_DENY_LIST=
 API_DOWNLOAD_FROM_MAX_RETRY=4
 API_DISABLE_DOWNLOAD_FROM=false
-API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY=false
-API_DISABLE_ROOT_ROUTE_TELEMETRY=false
-API_DISABLE_VERSION_ROUTE_TELEMETRY=false
-API_DISABLE_DEBUG_ROUTE_TELEMETRY=false
+API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY=true
+API_DISABLE_ROOT_ROUTE_TELEMETRY=true
+API_DISABLE_DEBUG_ROUTE_TELEMETRY=true
+API_DISABLE_VERSION_ROUTE_TELEMETRY=true
 API_ENABLE_DEBUG_ROUTE=false
 CHROMIUM_RESTART_AFTER=100
 CHROMIUM_MAX_QUEUE_SIZE=0
+CHROMIUM_IDLE_SHUTDOWN_TIMEOUT=0
 CHROMIUM_MAX_CONCURRENCY=6
 CHROMIUM_AUTO_START=false
 CHROMIUM_START_TIMEOUT=20s
@@ -53,6 +54,7 @@ CHROMIUM_DISABLE_JAVASCRIPT=false
 CHROMIUM_DISABLE_ROUTES=false
 LIBREOFFICE_RESTART_AFTER=10
 LIBREOFFICE_MAX_QUEUE_SIZE=0
+LIBREOFFICE_IDLE_SHUTDOWN_TIMEOUT=0
 LIBREOFFICE_AUTO_START=false
 LIBREOFFICE_START_TIMEOUT=20s
 LIBREOFFICE_DISABLE_ROUTES=false
@@ -60,15 +62,26 @@ LOG_LEVEL=info
 LOG_FIELDS_PREFIX=
 LOG_STD_FORMAT=auto
 LOG_STD_ENABLE_GCP_FIELDS=false
+PDFENGINES_DISABLE_ROUTES=false
 PDFENGINES_MERGE_ENGINES=qpdf,pdfcpu,pdftk
 PDFENGINES_SPLIT_ENGINES=pdfcpu,qpdf,pdftk
 PDFENGINES_FLATTEN_ENGINES=qpdf
 PDFENGINES_CONVERT_ENGINES=libreoffice-pdfengine
 PDFENGINES_READ_METADATA_ENGINES=exiftool
 PDFENGINES_WRITE_METADATA_ENGINES=exiftool
+PDFENGINES_READ_BOOKMARKS_ENGINES=pdfcpu
+PDFENGINES_WRITE_BOOKMARKS_ENGINES=pdfcpu
+PDFENGINES_WATERMARK_ENGINES=pdfcpu,pdftk
+PDFENGINES_STAMP_ENGINES=pdfcpu,pdftk
 PDFENGINES_ENCRYPT_ENGINES=qpdf,pdfcpu,pdftk
-PDFENGINES_DISABLE_ROUTES=false
-PDFENGINES_ADD_ATTACHMENTS_ENGINES=pdfcpu
+PDFENGINES_ROTATE_ENGINES=pdfcpu,pdftk
+PDFENGINES_EMBED_ENGINES=pdfcpu
+PROMETHEUS_NAMESPACE=gotenberg
+PROMETHEUS_COLLECT_INTERVAL=1s
+PROMETHEUS_DISABLE_ROUTE_LOGGING=false
+PROMETHEUS_DISABLE_ROUTE_TELEMETRY=true
+PROMETHEUS_DISABLE_COLLECT=false
+PROMETHEUS_METRICS_PATH=/prometheus/metrics
 OTEL_SERVICE_NAME=gotenberg
 OTEL_TRACES_EXPORTER=none
 OTEL_METRICS_EXPORTER=none
@@ -114,6 +127,9 @@ NO_CONCURRENCY=false
 # chromium-convert-html
 # chromium-convert-markdown
 # chromium-convert-url
+# chromium-screenshot-html
+# chromium-screenshot-markdown
+# chromium-screenshot-url
 # debug
 # health
 # libreoffice
@@ -121,8 +137,8 @@ NO_CONCURRENCY=false
 # output-filename
 # pdfengines
 # pdfengines-convert
-# pdfengines-attachments
-# attachments
+# pdfengines-embed
+# embed
 # pdfengines-encrypt
 # encrypt
 # pdfengines-flatten
@@ -133,15 +149,23 @@ NO_CONCURRENCY=false
 # metadata
 # pdfengines-split
 # split
+# pdfengines-watermark
+# watermark
+# pdfengines-stamp
+# stamp
+# pdfengines-rotate
+# rotate
+# pdfengines-bookmarks
+# bookmarks
+# prometheus-metrics
 # root
 # version
 # webhook
 # download-from
-# telemetry
 TAGS=
 
 .PHONY: test-integration
-test-integration: ## Run integration tests
+test-integration: ## Run integration tests (automatically retries failed scenarios up to 3 times)
 	go test -timeout 40m -tags=integration -v github.com/gotenberg/gotenberg/v8/test/integration -args \
 	--gotenberg-docker-repository=$(DOCKER_REPOSITORY) \
 	--gotenberg-version=$(GOTENBERG_VERSION) \

README.md

@@ -1,7 +1,7 @@
 <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 containerized API for seamless PDF conversion</p>
+    <p align="center">A Docker-based API for converting documents to PDF</p>
     <p align="center">
         <a href="https://hub.docker.com/r/gotenberg/gotenberg"><img alt="Total downloads (gotenberg/gotenberg)" src="https://img.shields.io/docker/pulls/gotenberg/gotenberg"></a>
         <a href="https://github.com/gotenberg/gotenberg/actions/workflows/continuous-integration.yml"><img alt="Continuous Integration" src="https://github.com/gotenberg/gotenberg/actions/workflows/continuous-integration.yml/badge.svg"></a>
@@ -10,33 +10,54 @@
     <p align="center">
         <a href="https://trendshift.io/repositories/2996"><img src="https://trendshift.io/api/badge/repositories/2996" alt="gotenberg%2Fgotenberg | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
     </p>
-    <p align="center"><a href="https://gotenberg.dev/docs/getting-started/introduction">Read the Documentation</a> &#183; <a href="https://gotenberg.dev/docs/getting-started/installation#live-demo-">Try the Live Demo</a> 🔥</p>
+    <p align="center">
+        <a href="https://gotenberg.dev/docs/getting-started/introduction"><strong>Documentation</strong></a> &#183;
+        <a href="https://gotenberg.dev/docs/getting-started/installation#live-demo"><strong>Live Demo</strong></a> &#183;
+        <a href="https://github.com/gotenberg/gotenberg/discussions"><strong>Community</strong></a>
+    </p>
 </p>
 
 ---
 
-**Gotenberg** is a containerized API that abstracts the complexity of PDF conversion.
+**Gotenberg** is a Docker-based API for converting documents to PDF. Trusted in production by thousands of companies. Also adopted by notable open-source projects.
 
-It provides a `multipart/form-data` interface for interacting with powerful engines like Chromium and LibreOffice.
-Instead of managing heavy dependencies, browser versions, or fonts in your own backend, simply send your files to
-Gotenberg and get a PDF in return.
+Send your files via `multipart/form-data`, get a PDF back. No need to manage Chromium, LibreOffice, or fonts yourself.
 
 ## Quick Start
 
-Open a terminal and run the following command:
-
 ```bash
 docker run --rm -p 3000:3000 gotenberg/gotenberg:8
 ```
 
-With the API running at `http://localhost:3000`, you are now ready to head
-to the **[Full Documentation](https://gotenberg.dev/docs/getting-started/introduction)** to discover how to convert URLs,
-local files, inject custom CSS, merge PDFs, and more.
+Convert a URL to PDF:
+
+```bash
+curl \
+  --request POST http://localhost:3000/forms/chromium/convert/url \
+  --form url=https://sparksuite.github.io/simple-html-invoice-template/ \
+  -o invoice.pdf
+```
+
+## Features
+
+- **HTML, URL, Markdown to PDF** via Headless Chromium
+- **Office documents to PDF** via LibreOffice (100+ formats)
+- **Merge, split, rotate, flatten** PDFs
+- **Watermark, stamp, encrypt** PDFs
+- **PDF/A and PDF/UA** compliance
+- **Screenshots** of URLs and HTML
+- **Read/write metadata and bookmarks**
+
+See the [full documentation](https://gotenberg.dev/docs/getting-started/introduction).
+
+## Contributing
+
+Questions and feedback: [GitHub Discussions](https://github.com/gotenberg/gotenberg/discussions).
+Bug reports: [GitHub Issues](https://github.com/gotenberg/gotenberg/issues).
 
 ## Sponsors
 
-Open-source development takes a significant amount of time, energy, and dedication. If Gotenberg helps streamline your
-workflow or powers your business, please consider supporting its continuous improvement by [**becoming a sponsor**](https://github.com/sponsors/gulien)! ❤️
+If Gotenberg powers your workflow or your business, consider [**becoming a sponsor**](https://github.com/sponsors/gulien).
 
 **Historic & GitHub Sponsors**
 

build/Dockerfile

@@ -64,7 +64,7 @@ RUN \
 
 # Note: jdeps helps finding which modules a JAR requires.
 # Currently only for PDFtk, as we don't rely on LibreOffice UNO Java SDK.
-ENV JAVA_MODULES=java.base,java.desktop,java.xml
+ENV JAVA_MODULES=java.base,java.desktop,java.naming,java.sql
 
 RUN jlink \
     --add-modules $JAVA_MODULES \
@@ -74,25 +74,6 @@ RUN jlink \
     --compress=2 \
     --output /custom-jre
 
-# ----------------------------------------------
-# Downloader stage
-# ----------------------------------------------
-FROM debian:13-slim AS downloader-stage
-
-# See https://gitlab.com/pdftk-java/pdftk/-/releases - Binary package.
-ARG PDFTK_VERSION=v3.3.3
-
-RUN apt-get update -qq && \
-    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends curl ca-certificates
-
-WORKDIR /downloads
-
-RUN curl -Ls https://raw.githubusercontent.com/gotenberg/unoconverter/v0.2.0/unoconv -o unoconverter &&\
-    chmod +x unoconverter
-
-RUN curl -o pdftk-all.jar "https://gitlab.com/api/v4/projects/5024297/packages/generic/pdftk-java/$PDFTK_VERSION/pdftk-all.jar" &&\
-    chmod a+x pdftk-all.jar
-
 # ----------------------------------------------
 # Base image stage
 # ----------------------------------------------
@@ -100,14 +81,8 @@ FROM debian:13-slim AS base-image-stage
 
 ARG TIMEZONE=UTC
 ENV TZ=$TIMEZONE
-# Set default characterset encoding to UTF-8.
-# See:
-# https://github.com/gotenberg/gotenberg/issues/104
-# https://github.com/gotenberg/gotenberg/issues/730
-ENV LANG=C.UTF-8
-ENV LC_ALL=C.UTF-8
 
-COPY --link --from=custom-jre-stage /custom-jre /opt/java
+COPY --from=custom-jre-stage /custom-jre /opt/java
 
 ENV PATH="/opt/java/bin:${PATH}"
 
@@ -119,6 +94,10 @@ FROM base-image-stage
 ARG GOTENBERG_VERSION=snapshot
 ARG GOTENBERG_USER_GID=1001
 ARG GOTENBERG_USER_UID=1001
+# See https://github.com/googlefonts/noto-emoji/releases.
+ARG NOTO_COLOR_EMOJI_VERSION=v2.051
+# See https://gitlab.com/pdftk-java/pdftk/-/releases - Binary package.
+ARG PDFTK_VERSION=v3.3.3
 
 LABEL org.opencontainers.image.title="Gotenberg" \
     org.opencontainers.image.description="A containerized API for seamless PDF conversion." \
@@ -136,55 +115,134 @@ RUN \
     chown gotenberg: /home/gotenberg
 
 RUN \
-    echo "deb http://deb.debian.org/debian trixie-backports main" >> /etc/apt/sources.list &&\
+    # Install system dependencies required for the next instructions or debugging.
+    # Note: tini is a helper for reaping zombie processes.
+    apt-get update -qq &&\
+    apt-get upgrade -yqq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends curl gnupg tini python3 python3-distutils-extra &&\
+    # 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/*
+
+RUN \
+    # 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.1_all.deb http://httpredir.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8.1_all.deb &&\
+    apt-get update -qq &&\
+    apt-get upgrade -yqq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
+    ./ttf-mscorefonts-installer_3.8.1_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-ukai \
+    fonts-arphic-uming \
+    fonts-ipafont-mincho \
+    fonts-ipafont-gothic \
+    fonts-unfonts-core \
+    # LibreOffice recommends.
+    fonts-crosextra-caladea \
+    fonts-crosextra-carlito \
+    fonts-dejavu \
+    fonts-liberation \
+    fonts-liberation2 \
+    fonts-linuxlibertine \
+    fonts-noto-cjk \
+    fonts-noto-core \
+    fonts-noto-mono \
+    fonts-noto-ui-core \
+    fonts-sil-gentium \
+    fonts-sil-gentium-basic &&\
+    rm -f ./ttf-mscorefonts-installer_3.8.1_all.deb &&\
+    # Add Color and Black-and-White Noto emoji font.
+    # Credits:
+    # https://github.com/gotenberg/gotenberg/pull/325.
+    # https://github.com/googlefonts/noto-emoji.
+    curl -Ls "https://github.com/googlefonts/noto-emoji/raw/$NOTO_COLOR_EMOJI_VERSION/fonts/NotoColorEmoji.ttf" -o /usr/local/share/fonts/NotoColorEmoji.ttf &&\
+    # Cleanup.
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+RUN \
+    # Install Hyphenation for LibreOffice.
+    # Credits: https://wiki.archlinux.org/title/LibreOffice.
     apt-get update -qq &&\
     apt-get upgrade -yqq &&\
-    # Note: tini is a helper for reaping zombie processes.
     DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
-        tini python3 python3-distutils-extra \
-        # Install fonts.
-        # Essential metric-compatible fonts for LibreOffice layout fidelity (replaces MS Fonts).
-        fonts-crosextra-carlito \
-        fonts-crosextra-caladea \
-        fonts-liberation \
-        fonts-liberation2 \
-        # Reliable general-purpose fallback for Chromium.
-        fonts-dejavu \
-        # Unified CJK (Chinese, Japanese, Korean) support.
-        fonts-noto-cjk \
-        # Standard Emoji support.
-        fonts-noto-color-emoji \
-        # Install Hyphenation for LibreOffice.
-        # Credits: https://wiki.archlinux.org/title/LibreOffice.
         hyphen-af hyphen-as hyphen-be hyphen-bg hyphen-bn hyphen-ca hyphen-cs hyphen-da hyphen-de hyphen-el \
         hyphen-en-gb hyphen-en-us hyphen-eo hyphen-es hyphen-fr hyphen-gl hyphen-gu hyphen-hi hyphen-hr hyphen-hu \
         hyphen-id hyphen-is hyphen-it hyphen-kn hyphen-lt hyphen-lv hyphen-ml hyphen-mn hyphen-mr hyphen-nl \
         hyphen-no hyphen-or hyphen-pa hyphen-pl hyphen-pt-br hyphen-pt-pt hyphen-ro hyphen-ru hyphen-sk hyphen-sl \
-        hyphen-sr hyphen-sv hyphen-ta hyphen-te hyphen-th hyphen-uk hyphen-zu \
-        # Install Chromium.
-        chromium \
-        # Install QPDF & ExifTool (PDF engines).
-        qpdf exiftool &&\
-    # Install LibreOffice & unoconverter.
-    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t trixie-backports \
-        libreoffice-writer libreoffice-calc libreoffice-impress libreoffice-draw python3-uno &&\
-    # unoconverter will look for the Python binary, which has to be at version 3.
-    ln -s /usr/bin/python3 /usr/bin/python &&\
-    # See https://github.com/nextcloud/docker/issues/380.
-    mkdir -p /usr/share/man/man1 &&\
+        hyphen-sr hyphen-sv hyphen-ta hyphen-te hyphen-th hyphen-uk hyphen-zu &&\
     # Cleanup.
-    apt-get autoremove -yqq &&\
-    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* /usr/share/man/* /usr/share/info/*
-
-# Copy downloaded artifacts (unoconverter & PDFtk).
-COPY --link --from=downloader-stage /downloads/unoconverter /usr/bin/unoconverter
-COPY --link --from=downloader-stage /downloads/pdftk-all.jar /usr/bin/pdftk-all.jar
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 RUN \
-    # Install PDFtk bash wrapper.
+    # Install Chromium.
+    apt-get update -qq &&\
+    apt-get upgrade -yqq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends chromium &&\
+    # Verify installation.
+    chromium --version &&\
+    # Cleanup.
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+# Set default characterset encoding to UTF-8.
+# See:
+# https://github.com/gotenberg/gotenberg/issues/104
+# https://github.com/gotenberg/gotenberg/issues/730
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+RUN \
+    # Install LibreOffice & unoconverter. \
+    echo "deb http://deb.debian.org/debian trixie-backports main" >> /etc/apt/sources.list &&\
+    apt-get update -qq &&\
+    apt-get upgrade -yqq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t trixie-backports libreoffice &&\
+    curl -Ls https://raw.githubusercontent.com/gotenberg/unoconverter/v0.2.0/unoconv -o /usr/bin/unoconverter &&\
+    chmod +x /usr/bin/unoconverter &&\
+    # unoconverter will look for the Python binary, which has to be at version 3.
+    ln -s /usr/bin/python3 /usr/bin/python &&\
+    # Verify installations.
+    libreoffice --version &&\
+    unoconverter --version &&\
+    # Cleanup.
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+RUN \
+    # Install PDFtk, QPDF & ExifTool (PDF engines).
     # See https://github.com/gotenberg/gotenberg/pull/273.
+    curl -o /usr/bin/pdftk-all.jar "https://gitlab.com/api/v4/projects/5024297/packages/generic/pdftk-java/$PDFTK_VERSION/pdftk-all.jar" &&\
+    chmod a+x /usr/bin/pdftk-all.jar &&\
     printf '#!/bin/bash\n\nexec java -jar /usr/bin/pdftk-all.jar "$@"' > /usr/bin/pdftk && \
-    chmod +x /usr/bin/pdftk
+    chmod +x /usr/bin/pdftk &&\
+    apt-get update -qq &&\
+    apt-get upgrade -yqq &&\
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends qpdf exiftool &&\
+    # See https://github.com/nextcloud/docker/issues/380.
+    mkdir -p /usr/share/man/man1 &&\
+    # Verify installations.
+    pdftk --version &&\
+    qpdf --version &&\
+    exiftool --version &&\
+    # Cleanup.
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 # Support for arbitrary user IDs (OpenShift).
 # See:
@@ -199,15 +257,15 @@ RUN \
 # Credits:
 # https://github.com/arachnys/athenapdf/issues/69.
 # https://github.com/arachnys/athenapdf/commit/ba25a8d80a25d08d58865519c4cd8756dc9a336d.
-COPY --link build/fonts.conf /etc/fonts/conf.d/100-gotenberg.conf
+COPY build/fonts.conf /etc/fonts/conf.d/100-gotenberg.conf
 
 # Copy dictionnaries so that hypens work on Chromium.
 # See https://github.com/gotenberg/gotenberg/issues/1293.
-COPY --link --chown="$GOTENBERG_USER_UID:$GOTENBERG_USER_GID" build/chromium-hyphen-data /opt/gotenberg/chromium-hyphen-data
+COPY --chown=gotenberg:gotenberg build/chromium-hyphen-data /opt/gotenberg/chromium-hyphen-data
 
 # Copy the Golang binaries.
-COPY --link --from=pdfcpu-binary-stage /home/pdfcpu /usr/bin/
-COPY --link --from=gotenberg-binary-stage /home/gotenberg /usr/bin/
+COPY --from=pdfcpu-binary-stage /home/pdfcpu /usr/bin/
+COPY --from=gotenberg-binary-stage /home/gotenberg /usr/bin/
 
 # Environment variables required by modules or else.
 ENV CHROMIUM_BIN_PATH=/usr/bin/chromium
@@ -219,6 +277,11 @@ ENV QPDF_BIN_PATH=/usr/bin/qpdf
 ENV EXIFTOOL_BIN_PATH=/usr/bin/exiftool
 ENV PDFCPU_BIN_PATH=/usr/bin/pdfcpu
 
+# OpenTelemetry defaults (noop - no telemetry overhead unless explicitly enabled).
+ENV OTEL_TRACES_EXPORTER=none
+ENV OTEL_METRICS_EXPORTER=none
+ENV OTEL_LOGS_EXPORTER=none
+
 USER gotenberg
 WORKDIR /home/gotenberg
 
@@ -226,4 +289,4 @@ WORKDIR /home/gotenberg
 EXPOSE 3000
 
 ENTRYPOINT [ "/usr/bin/tini", "--" ]
-CMD [ "gotenberg" ]
+CMD [ "gotenberg" ]

cmd/gotenberg.go

@@ -25,7 +25,7 @@ const banner = `
 \___/\___/\__/\__/_//_/_.__/\__/_/  \_, / 
                                    /___/
 
-A containerized API for seamless PDF conversion.
+A Docker-based API for converting documents to PDF.
 Version: %s
 -------------------------------------------------------
 `
@@ -43,10 +43,24 @@ func Run() {
 	fs.Bool("gotenberg-hide-banner", false, "Hide the banner")
 	fs.Duration("gotenberg-graceful-shutdown-duration", time.Duration(30)*time.Second, "Set the graceful shutdown duration")
 	fs.Bool("gotenberg-build-debug-data", true, "Set if build data is needed")
-	fs.String("log-level", gotenberg.InfoLoggingLevel, fmt.Sprintf("Choose the level of logging detail. Options include %s, %s, %s, or %s", gotenberg.ErrorLoggingLevel, gotenberg.WarnLoggingLevel, gotenberg.InfoLoggingLevel, gotenberg.DebugLoggingLevel))
-	fs.String("log-fields-prefix", "", "Prepend a specified prefix to each field in the logs")
-	fs.String("log-std-format", gotenberg.AutoLoggingFormat, fmt.Sprintf("Specify the format of standard logging. Options include %s, %s, or %s", gotenberg.AutoLoggingFormat, gotenberg.JsonLoggingFormat, gotenberg.TextLoggingFormat))
-	fs.Bool("log-std-enable-gcp-fields", false, "Enable Google Cloud Platform fields for standard logging - namely: time, message, severity")
+
+	// Logging & telemetry flags.
+	fs.String("log-level", gotenberg.InfoLoggingLevel, "Set the log level")
+	fs.String("log-fields-prefix", "", "Prepend a specified prefix to each log field key")
+	fs.String("log-std-format", gotenberg.AutoLoggingFormat, "Set the log format for standard output")
+	fs.Bool("log-std-enable-gcp-fields", false, "Use GCP-compatible field names in log output")
+
+	// Deprecated logging flags.
+	fs.String("log-format", gotenberg.AutoLoggingFormat, "Set the log format")
+	fs.Bool("log-enable-gcp-fields", false, "Use GCP-compatible field names")
+
+	if err := errors.Join(
+		fs.MarkDeprecated("log-format", "use --log-std-format instead"),
+		fs.MarkDeprecated("log-enable-gcp-fields", "use --log-std-enable-gcp-fields instead"),
+	); err != nil {
+		fmt.Printf("[FATAL] mark deprecated flags: %s\n", err)
+		os.Exit(1)
+	}
 
 	descriptors := gotenberg.GetModuleDescriptors()
 	var modsInfo strings.Builder
@@ -80,10 +94,11 @@ func Run() {
 				fmt.Printf("[FATAL] invalid overriding value '%s' from %s: %v\n", val, envName, err)
 				os.Exit(1)
 			}
+			f.Changed = true
 			return
 		}
 
-		err = f.Value.Set(val)
+		err = fs.Set(f.Name, val)
 		if err != nil {
 			fmt.Printf("[FATAL] invalid overriding value '%s' from %s: %v\n", val, envName, err)
 			os.Exit(1)
@@ -95,43 +110,43 @@ func Run() {
 	hideBanner := parsedFlags.MustBool("gotenberg-hide-banner")
 	gracefulShutdownDuration := parsedFlags.MustDuration("gotenberg-graceful-shutdown-duration")
 
+	// Initialize telemetry (logging + OTEL).
 	serviceName := os.Getenv("OTEL_SERVICE_NAME")
 	if serviceName == "" {
 		serviceName = "gotenberg"
 	}
 
-	telemetryConfig := gotenberg.TelemetryConfig{
-		// OpenTelemetry.
-		ServiceName:    serviceName,
-		ServiceVersion: Version,
-		// Logging.
-		LogLevel:              parsedFlags.MustString("log-level"),
+	telemetryCfg := gotenberg.TelemetryConfig{
+		ServiceName:           serviceName,
+		ServiceVersion:        Version,
+		LogLevel:              parsedFlags.MustDeprecatedString("log-format", "log-std-format"),
 		LogFieldsPrefix:       parsedFlags.MustString("log-fields-prefix"),
 		LogStdFormat:          parsedFlags.MustDeprecatedString("log-format", "log-std-format"),
 		LogStdEnableGcpFields: parsedFlags.MustDeprecatedBool("log-enable-gcp-fields", "log-std-enable-gcp-fields"),
 	}
+	// LogLevel uses its own flag, not the format flag.
+	telemetryCfg.LogLevel = parsedFlags.MustString("log-level")
+
+	err = telemetryCfg.Validate()
+	if err != nil {
+		fmt.Printf("[FATAL] invalid telemetry config: %s\n", err)
+		os.Exit(1)
+	}
+
+	shutdownTelemetry, err := gotenberg.StartTelemetry(telemetryCfg)
+	if err != nil {
+		fmt.Printf("[FATAL] start telemetry: %s\n", err)
+		os.Exit(1)
+	}
 
 	if !hideBanner {
 		fmt.Printf(banner, Version)
 	}
-
-	err = telemetryConfig.Validate()
-	if err != nil {
-		fmt.Printf("[FATAL] telemetry: %s\n", err)
-		os.Exit(1)
-	}
-
-	// Telemetry.
-	shutdownTelemetry, err := gotenberg.StartTelemetry(telemetryConfig)
-	if err != nil {
-		fmt.Printf("[FATAL] telemetry: %s\n", err)
-		os.Exit(1)
-	}
-
-	// Modules.
 	fmt.Printf("[SYSTEM] modules: %s\n", modsInfo.String())
+
 	ctx := gotenberg.NewContext(parsedFlags, descriptors)
 
+	// Start application modules.
 	apps, err := ctx.Modules(new(gotenberg.App))
 	if err != nil {
 		fmt.Printf("[FATAL] %s\n", err)
@@ -223,16 +238,18 @@ func Run() {
 
 	err = eg.Wait()
 	if err != nil {
+		cancel()
 		fmt.Printf("[FATAL] %v\n", err)
-		os.Exit(1)
+		os.Exit(1) //nolint:gocritic // defers are already called explicitly above
 	}
 
+	// Shutdown telemetry (flush spans, metrics, logs).
 	err = shutdownTelemetry(gracefulShutdownCtx)
 	if err != nil {
-		fmt.Printf("[FATAL] telemetry: %v\n", err)
-		os.Exit(1)
+		cancel()
+		fmt.Printf("[FATAL] %v\n", err)
+		os.Exit(1) //nolint:gocritic // defers are already called explicitly above
 	}
-	fmt.Printf("[SYSTEM] telemetry: shutdown success\n")
 
 	os.Exit(0)
 }

compose.yaml

@@ -33,12 +33,13 @@ services:
       - "--api-disable-download-from=${API_DISABLE_DOWNLOAD_FROM}"
       - "--api-disable-health-check-route-telemetry=${API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY}"
       - "--api-disable-root-route-telemetry=${API_DISABLE_ROOT_ROUTE_TELEMETRY}"
-      - "--api-disable-version-route-telemetry=${API_DISABLE_VERSION_ROUTE_TELEMETRY}"
       - "--api-disable-debug-route-telemetry=${API_DISABLE_DEBUG_ROUTE_TELEMETRY}"
+      - "--api-disable-version-route-telemetry=${API_DISABLE_VERSION_ROUTE_TELEMETRY}"
       - "--api-enable-debug-route=${API_ENABLE_DEBUG_ROUTE}"
       - "--chromium-restart-after=${CHROMIUM_RESTART_AFTER}"
       - "--chromium-auto-start=${CHROMIUM_AUTO_START}"
       - "--chromium-max-queue-size=${CHROMIUM_MAX_QUEUE_SIZE}"
+      - "--chromium-idle-shutdown-timeout=${CHROMIUM_IDLE_SHUTDOWN_TIMEOUT}"
       - "--chromium-max-concurrency=${CHROMIUM_MAX_CONCURRENCY}"
       - "--chromium-start-timeout=${CHROMIUM_START_TIMEOUT}"
       - "--chromium-allow-insecure-localhost=${CHROMIUM_ALLOW_INSECURE_LOCALHOST}"
@@ -55,6 +56,7 @@ services:
       - "--chromium-disable-routes=${CHROMIUM_DISABLE_ROUTES}"
       - "--libreoffice-restart-after=${LIBREOFFICE_RESTART_AFTER}"
       - "--libreoffice-max-queue-size=${LIBREOFFICE_MAX_QUEUE_SIZE}"
+      - "--libreoffice-idle-shutdown-timeout=${LIBREOFFICE_IDLE_SHUTDOWN_TIMEOUT}"
       - "--libreoffice-auto-start=${LIBREOFFICE_AUTO_START}"
       - "--libreoffice-start-timeout=${LIBREOFFICE_START_TIMEOUT}"
       - "--libreoffice-disable-routes=${LIBREOFFICE_DISABLE_ROUTES}"
@@ -68,9 +70,20 @@ services:
       - "--pdfengines-convert-engines=${PDFENGINES_CONVERT_ENGINES}"
       - "--pdfengines-read-metadata-engines=${PDFENGINES_READ_METADATA_ENGINES}"
       - "--pdfengines-write-metadata-engines=${PDFENGINES_WRITE_METADATA_ENGINES}"
+      - "--pdfengines-read-bookmarks-engines=${PDFENGINES_READ_BOOKMARKS_ENGINES}"
+      - "--pdfengines-write-bookmarks-engines=${PDFENGINES_WRITE_BOOKMARKS_ENGINES}"
+      - "--pdfengines-watermark-engines=${PDFENGINES_WATERMARK_ENGINES}"
+      - "--pdfengines-stamp-engines=${PDFENGINES_STAMP_ENGINES}"
       - "--pdfengines-encrypt-engines=${PDFENGINES_ENCRYPT_ENGINES}"
+      - "--pdfengines-rotate-engines=${PDFENGINES_ROTATE_ENGINES}"
+      - "--pdfengines-embed-engines=${PDFENGINES_EMBED_ENGINES}"
       - "--pdfengines-disable-routes=${PDFENGINES_DISABLE_ROUTES}"
-      - "--pdfengines-add-attachments-engines=${PDFENGINES_ADD_ATTACHMENTS_ENGINES}"
+      - "--prometheus-namespace=${PROMETHEUS_NAMESPACE}"
+      - "--prometheus-collect-interval=${PROMETHEUS_COLLECT_INTERVAL}"
+      - "--prometheus-disable-route-logging=${PROMETHEUS_DISABLE_ROUTE_LOGGING}"
+      - "--prometheus-disable-route-telemetry=${PROMETHEUS_DISABLE_ROUTE_TELEMETRY}"
+      - "--prometheus-disable-collect=${PROMETHEUS_DISABLE_COLLECT}"
+      - "--prometheus-metrics-path=${PROMETHEUS_METRICS_PATH}"
       - "--webhook-enable-sync-mode=${WEBHOOK_ENABLE_SYNC_MODE}"
       - "--webhook-allow-list=${WEBHOOK_ALLOW_LIST}"
       - "--webhook-deny-list=${WEBHOOK_DENY_LIST}"
@@ -90,14 +103,20 @@ services:
     ports:
       - "4317:4317" # OTLP gRPC receiver
     depends_on:
-      - openobserve
+      openobserve:
+        condition: service_started
+    restart: on-failure
 
   openobserve:
     image: public.ecr.aws/zinclabs/openobserve:latest
     restart: always
     ports:
       - "5080:5080"
-      - "5081:5081" # OTLP gRPC ingestion
+      - "5081:5081"
     environment:
       ZO_ROOT_USER_EMAIL: telemetry@gotenberg.dev
       ZO_ROOT_USER_PASSWORD: telemetry
+
+networks:
+  default:
+    enable_ipv6: false

go.mod

@@ -5,8 +5,8 @@ go 1.26.0
 require (
 	github.com/alexliesenfeld/health v0.8.1
 	github.com/barasher/go-exiftool v1.10.0
-	github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266d
-	github.com/chromedp/chromedp v0.14.2
+	github.com/chromedp/cdproto v0.0.0-20260321001828-e3e3800016bc
+	github.com/chromedp/chromedp v0.15.1
 	github.com/cucumber/godog v0.15.1
 	github.com/dlclark/regexp2 v1.11.5
 	github.com/docker/docker v28.5.2+incompatible
@@ -18,11 +18,12 @@ require (
 	github.com/labstack/gommon v0.4.2
 	github.com/mholt/archives v0.1.5
 	github.com/microcosm-cc/bluemonday v1.0.27
-	github.com/shirou/gopsutil/v4 v4.26.1
+	github.com/prometheus/client_golang v1.23.2
+	github.com/shirou/gopsutil/v4 v4.26.2
 	github.com/spf13/pflag v1.0.10
 	github.com/stretchr/testify v1.11.1
-	github.com/testcontainers/testcontainers-go v0.40.0
-	go.opentelemetry.io/contrib/bridges/otelslog v0.15.0
+	github.com/testcontainers/testcontainers-go v0.41.0
+	go.opentelemetry.io/contrib/bridges/otelslog v0.17.0
 	go.opentelemetry.io/contrib/exporters/autoexport v0.67.0
 	go.opentelemetry.io/otel v1.42.0
 	go.opentelemetry.io/otel/log v0.18.0
@@ -31,11 +32,10 @@ require (
 	go.opentelemetry.io/otel/sdk/log v0.18.0
 	go.opentelemetry.io/otel/sdk/metric v1.42.0
 	go.opentelemetry.io/otel/trace v1.42.0
-	go.uber.org/multierr v1.11.0
-	golang.org/x/net v0.51.0
-	golang.org/x/sync v0.19.0
-	golang.org/x/term v0.40.0
-	golang.org/x/text v0.34.0
+	golang.org/x/net v0.52.0
+	golang.org/x/sync v0.20.0
+	golang.org/x/term v0.41.0
+	golang.org/x/text v0.35.0
 )
 
 require (
@@ -81,17 +81,17 @@ require (
 	github.com/hashicorp/go-memdb v1.3.5 // indirect
 	github.com/hashicorp/golang-lru v1.0.2 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
-	github.com/klauspost/compress v1.18.4 // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
 	github.com/klauspost/pgzip v1.2.6 // indirect
-	github.com/lufia/plan9stats v0.0.0-20260216142805-b3301c5f2a88 // indirect
+	github.com/lufia/plan9stats v0.0.0-20260324052639-156f7da3f749 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mikelolasagasti/xz v1.0.1 // indirect
-	github.com/minio/minlz v1.0.1 // indirect
+	github.com/minio/minlz v1.1.0 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/go-archive v0.2.0 // indirect
-	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/patternmatcher v0.6.1 // indirect
 	github.com/moby/sys/sequential v0.6.0 // indirect
 	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
@@ -101,11 +101,10 @@ require (
 	github.com/nwaples/rardecode/v2 v2.2.2 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
-	github.com/pierrec/lz4/v4 v4.1.25 // indirect
+	github.com/pierrec/lz4/v4 v4.1.26 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
-	github.com/prometheus/client_golang v1.23.2 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.67.5 // indirect
 	github.com/prometheus/otlptranslator v1.0.0 // indirect
@@ -121,7 +120,7 @@ require (
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/bridges/prometheus v0.67.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.18.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.18.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.42.0 // indirect
@@ -133,15 +132,15 @@ require (
 	go.opentelemetry.io/otel/exporters/stdout/stdoutlog v0.18.0 // indirect
 	go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.42.0 // indirect
 	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.42.0 // indirect
-	go.opentelemetry.io/proto/otlp v1.9.0 // indirect
-	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	go.opentelemetry.io/proto/otlp v1.10.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.4 // indirect
 	go4.org v0.0.0-20260112195520-a5071408f32f // indirect
-	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
-	golang.org/x/time v0.14.0 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 // indirect
-	google.golang.org/grpc v1.79.2 // indirect
+	golang.org/x/crypto v0.49.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 // indirect
+	google.golang.org/grpc v1.79.3 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -30,10 +30,10 @@ github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1x
 github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
-github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266d h1:ZtA1sedVbEW7EW80Iz2GR3Ye6PwbJAJXjv7D74xG6HU=
-github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266d/go.mod h1:NItd7aLkcfOA/dcMXvl8p1u+lQqioRMq/SqDp71Pb/k=
-github.com/chromedp/chromedp v0.14.2 h1:r3b/WtwM50RsBZHMUm9fsNhhzRStTHrKdr2zmwbZSzM=
-github.com/chromedp/chromedp v0.14.2/go.mod h1:rHzAv60xDE7VNy/MYtTUrYreSc0ujt2O1/C3bzctYBo=
+github.com/chromedp/cdproto v0.0.0-20260321001828-e3e3800016bc h1:wkN/LMi5vc60pBRWx6qpbk/aEvq3/ZVNpnMvsw8PVVU=
+github.com/chromedp/cdproto v0.0.0-20260321001828-e3e3800016bc/go.mod h1:cbyjALe67vDvlvdiG9369P8w5U2w6IshwtyD2f2Tvag=
+github.com/chromedp/chromedp v0.15.1 h1:EJWiPm7BNqDqjYy6U0lTSL5wNH+iNt9GjC3a4gfjNyQ=
+github.com/chromedp/chromedp v0.15.1/go.mod h1:CdTHtUqD/dqaFw/cvFWtTydoEQS44wLBuwbMR9EkOY4=
 github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM=
 github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8=
 github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
@@ -134,8 +134,8 @@ github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/klauspost/compress v1.4.1/go.mod h1:RyIbtBH6LamlWaDj8nUwkbUhJ87Yi3uG0guNDohfE1A=
-github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
-github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid v1.2.0/go.mod h1:Pj4uuM528wm8OyEC2QMXAi2YiTZ96dNQPGgoMS4s3ek=
 github.com/klauspost/pgzip v1.2.6 h1:8RXeL5crjEUFnR2/Sn6GJNWtSQ3Dk8pq4CL3jvdDyjU=
 github.com/klauspost/pgzip v1.2.6/go.mod h1:Ch1tH69qFZu15pkjo5kYi6mth2Zzwzt50oCQKQE9RUs=
@@ -154,8 +154,8 @@ github.com/labstack/gommon v0.4.2 h1:F8qTUNXgG1+6WQmqoUWnz8WiEU60mXVVw0P4ht1WRA0
 github.com/labstack/gommon v0.4.2/go.mod h1:QlUFxVM+SNXhDL/Z7YhocGIBYOiwB0mXm1+1bAPHPyU=
 github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo=
 github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
-github.com/lufia/plan9stats v0.0.0-20260216142805-b3301c5f2a88 h1:PTw+yKnXcOFCR6+8hHTyWBeQ/P4Nb7dd4/0ohEcWQuM=
-github.com/lufia/plan9stats v0.0.0-20260216142805-b3301c5f2a88/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
+github.com/lufia/plan9stats v0.0.0-20260324052639-156f7da3f749 h1:Qj3hTcdWH8uMZDI41HNuTuJN525C7NBrbtH5kSO6fPk=
+github.com/lufia/plan9stats v0.0.0-20260324052639-156f7da3f749/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
 github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
@@ -168,14 +168,14 @@ github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwX
 github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
 github.com/mikelolasagasti/xz v1.0.1 h1:Q2F2jX0RYJUG3+WsM+FJknv+6eVjsjXNDV0KJXZzkD0=
 github.com/mikelolasagasti/xz v1.0.1/go.mod h1:muAirjiOUxPRXwm9HdDtB3uoRPrGnL85XHtokL9Hcgc=
-github.com/minio/minlz v1.0.1 h1:OUZUzXcib8diiX+JYxyRLIdomyZYzHct6EShOKtQY2A=
-github.com/minio/minlz v1.0.1/go.mod h1:qT0aEB35q79LLornSzeDH75LBf3aH1MV+jB5w9Wasec=
+github.com/minio/minlz v1.1.0 h1:rUOGu3EP4EqJC5k3qCsIwEnZiJULKqtRyDdqbhlvMmQ=
+github.com/minio/minlz v1.1.0/go.mod h1:qT0aEB35q79LLornSzeDH75LBf3aH1MV+jB5w9Wasec=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
 github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
-github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
-github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U=
+github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
 github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w3A14Sw=
 github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs=
 github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
@@ -198,8 +198,8 @@ github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJw
 github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
 github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde h1:x0TT0RDC7UhAVbbWWBzr41ElhJx5tXPWkIHA2HWPRuw=
 github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0=
-github.com/pierrec/lz4/v4 v4.1.25 h1:kocOqRffaIbU5djlIBr7Wh+cx82C0vtFb0fOurZHqD0=
-github.com/pierrec/lz4/v4 v4.1.25/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
+github.com/pierrec/lz4/v4 v4.1.26 h1:GrpZw1gZttORinvzBdXPUXATeqlJjqUG/D87TKMnhjY=
+github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -219,8 +219,8 @@ github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4Ul
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/shirou/gopsutil/v4 v4.26.1 h1:TOkEyriIXk2HX9d4isZJtbjXbEjf5qyKPAzbzY0JWSo=
-github.com/shirou/gopsutil/v4 v4.26.1/go.mod h1:medLI9/UNAb0dOI9Q3/7yWSqKkj00u+1tgY8nvv41pc=
+github.com/shirou/gopsutil/v4 v4.26.2 h1:X8i6sicvUFih4BmYIGT1m2wwgw2VG9YgrDTi7cIRGUI=
+github.com/shirou/gopsutil/v4 v4.26.2/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/sorairolake/lzip-go v0.3.8 h1:j5Q2313INdTA80ureWYRhX+1K78mUXfMoPZCw/ivWik=
@@ -244,8 +244,8 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o
 github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/testcontainers/testcontainers-go v0.40.0 h1:pSdJYLOVgLE8YdUY2FHQ1Fxu+aMnb6JfVz1mxk7OeMU=
-github.com/testcontainers/testcontainers-go v0.40.0/go.mod h1:FSXV5KQtX2HAMlm7U3APNyLkkap35zNLxukw9oBi/MY=
+github.com/testcontainers/testcontainers-go v0.41.0 h1:mfpsD0D36YgkxGj2LrIyxuwQ9i2wCKAD+ESsYM1wais=
+github.com/testcontainers/testcontainers-go v0.41.0/go.mod h1:pdFrEIfaPl24zmBjerWTTYaY0M6UHsqA1YSvsoU40MI=
 github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=
 github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
 github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
@@ -263,14 +263,14 @@ github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/bridges/otelslog v0.15.0 h1:yOYhGNPZseueTTvWp5iBD3/CthrmvayUXYEX862dDi4=
-go.opentelemetry.io/contrib/bridges/otelslog v0.15.0/go.mod h1:CvaNVqIfcybc+7xqZNubbE+26K6P7AKZF/l0lE2kdCk=
+go.opentelemetry.io/contrib/bridges/otelslog v0.17.0 h1:NFIS6x7wyObQ7cR84x7bt1sr8nYBx89s3x3GwRjw40k=
+go.opentelemetry.io/contrib/bridges/otelslog v0.17.0/go.mod h1:39SaByOyDMRMe872AE7uelMuQZidIw7LLFAnQi0FWTE=
 go.opentelemetry.io/contrib/bridges/prometheus v0.67.0 h1:dkBzNEAIKADEaFnuESzcXvpd09vxvDZsOjx11gjUqLk=
 go.opentelemetry.io/contrib/bridges/prometheus v0.67.0/go.mod h1:Z5RIwRkZgauOIfnG5IpidvLpERjhTninpP1dTG2jTl4=
 go.opentelemetry.io/contrib/exporters/autoexport v0.67.0 h1:4fnRcNpc6YFtG3zsFw9achKn3XgmxPxuMuqIL5rE8e8=
 go.opentelemetry.io/contrib/exporters/autoexport v0.67.0/go.mod h1:qTvIHMFKoxW7HXg02gm6/Wofhq5p3Ib/A/NNt1EoBSQ=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
 go.opentelemetry.io/otel v1.42.0 h1:lSQGzTgVR3+sgJDAU/7/ZMjN9Z+vUip7leaqBKy4sho=
 go.opentelemetry.io/otel v1.42.0/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc=
 go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.18.0 h1:deI9UQMoGFgrg5iLPgzueqFPHevDl+28YKfSpPTI6rY=
@@ -309,44 +309,42 @@ go.opentelemetry.io/otel/sdk/metric v1.42.0 h1:D/1QR46Clz6ajyZ3G8SgNlTJKBdGp84q9
 go.opentelemetry.io/otel/sdk/metric v1.42.0/go.mod h1:Ua6AAlDKdZ7tdvaQKfSmnFTdHx37+J4ba8MwVCYM5hc=
 go.opentelemetry.io/otel/trace v1.42.0 h1:OUCgIPt+mzOnaUTpOQcBiM/PLQ/Op7oq6g4LenLmOYY=
 go.opentelemetry.io/otel/trace v1.42.0/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc=
-go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
-go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
+go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
+go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
-go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
-go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
-go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go4.org v0.0.0-20260112195520-a5071408f32f h1:ziUVAjmTPwQMBmYR1tbdRFJPtTcQUI12fH9QQjfb0Sw=
 go4.org v0.0.0-20260112195520-a5071408f32f/go.mod h1:ZRJnO5ZI4zAwMFp+dS1+V6J6MSyAowhRqAE+DPa1Xp0=
-golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
-golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
-golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
-golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
-golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
-golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
-golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
+golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
 gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171 h1:tu/dtnW1o3wfaxCOjSLn5IRX4YDcJrtlpzYkhHhGaC4=
-google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171/go.mod h1:M5krXqk4GhBKvB596udGL3UyjL4I1+cTbK0orROM9ng=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 h1:ggcbiqK8WWh6l1dnltU4BgWGIGo+EVYxCaAPih/zQXQ=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.2 h1:fRMD94s2tITpyJGtBBn7MkMseNpOZU8ZxgC3MMBaXRU=
-google.golang.org/grpc v1.79.2/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 h1:41r6JMbpzBMen0R/4TZeeAmGXSJC7DftGINUodzTkPI=
+google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:EIQZ5bFCfRQDV4MhRle7+OgjNtZ6P1PiZBgAKuxXu/Y=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 h1:ndE4FoJqsIceKP2oYSnUZqhTdYufCYYkqwtFzfrhI7w=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
+google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

pkg/gotenberg/cmd.go

@@ -62,7 +62,7 @@ func (cmd *Cmd) Start() error {
 		return fmt.Errorf("pipe unix process output: %w", err)
 	}
 
-	cmd.logger.DebugContext(cmd.ctx, fmt.Sprintf("start unix process: %s", strings.Join(cmd.process.Args, " ")))
+	cmd.logger.DebugContext(context.Background(), fmt.Sprintf("start unix process: %s", strings.Join(cmd.process.Args, " ")))
 
 	err = cmd.process.Start()
 	if err != nil {
@@ -109,7 +109,7 @@ func (cmd *Cmd) Exec() (int, error) {
 	case err = <-errChan:
 		errProc := cmd.Kill()
 		if errProc != nil {
-			cmd.logger.ErrorContext(cmd.ctx, errProc.Error())
+			cmd.logger.ErrorContext(context.Background(), errProc.Error())
 		}
 
 		if err == nil {
@@ -124,7 +124,7 @@ func (cmd *Cmd) Exec() (int, error) {
 	case <-cmd.ctx.Done():
 		errProc := cmd.Kill()
 		if errProc != nil {
-			cmd.logger.ErrorContext(cmd.ctx, errProc.Error())
+			cmd.logger.ErrorContext(context.Background(), errProc.Error())
 		}
 
 		return 62, fmt.Errorf("context done: %w", cmd.ctx.Err())
@@ -134,7 +134,7 @@ func (cmd *Cmd) Exec() (int, error) {
 // 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 {
-	if !cmd.logger.Enabled(cmd.ctx, slog.LevelDebug) {
+	if !cmd.logger.Enabled(context.Background(), slog.LevelDebug) {
 		return nil
 	}
 
@@ -155,7 +155,7 @@ func (cmd *Cmd) pipeOutput() error {
 		defer func(reader io.ReadCloser) {
 			err := reader.Close()
 			if err != nil && !strings.Contains(err.Error(), "file already closed") {
-				logger.ErrorContext(cmd.ctx, fmt.Sprintf("close reader: %s", err))
+				logger.ErrorContext(context.Background(), fmt.Sprintf("close reader: %s", err))
 			}
 		}(reader)
 
@@ -163,14 +163,14 @@ func (cmd *Cmd) pipeOutput() error {
 			line, _, err := r.ReadLine()
 			if err != nil {
 				if err != io.EOF && !strings.Contains(err.Error(), "file already closed") {
-					logger.ErrorContext(cmd.ctx, fmt.Sprintf("pipe unix process output error: %s", err))
+					logger.ErrorContext(context.Background(), fmt.Sprintf("pipe unix process output error: %s", err))
 				}
 
 				break
 			}
 
 			if len(line) != 0 {
-				logger.DebugContext(cmd.ctx, string(line))
+				logger.DebugContext(context.Background(), string(line))
 			}
 		}
 	}
@@ -194,13 +194,13 @@ func (cmd *Cmd) Kill() error {
 
 	err := syscall.Kill(-cmd.process.Process.Pid, syscall.SIGKILL)
 	if err == nil {
-		cmd.logger.DebugContext(cmd.ctx, "unix process killed")
+		cmd.logger.DebugContext(context.Background(), "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.DebugContext(cmd.ctx, "unix process already killed")
+		cmd.logger.DebugContext(context.Background(), "unix process already killed")
 		return nil
 	}
 

pkg/gotenberg/filter.go

@@ -12,40 +12,57 @@ import (
 // ErrFiltered happens if a value is filtered by the [FilterDeadline] function.
 var ErrFiltered = errors.New("value filtered")
 
-// FilterDeadline checks if given value is allowed and not denied according to
-// regex patterns. It returns a [context.DeadlineExceeded] if it takes too long
-// to process.
-func FilterDeadline(allowed, denied *regexp2.Regexp, s string, deadline time.Time) error {
-	// FIXME: not ideal to compile everytime, but is there another way to create a clone?
-	if allowed.String() != "" {
-		allow := regexp2.MustCompile(allowed.String(), 0)
-		allow.MatchTimeout = time.Until(deadline)
+// FilterDeadline checks if the given value is allowed and not denied according
+// to regex patterns. The allowed list uses OR semantics (value must match at
+// least one pattern). The denied list uses OR semantics (value is denied if it
+// matches any pattern). It returns a [context.DeadlineExceeded] if it takes
+// too long to process.
+func FilterDeadline(allowed, denied []*regexp2.Regexp, s string, deadline time.Time) error {
+	if len(allowed) > 0 {
+		matched := false
 
-		ok, err := allow.MatchString(s)
-		if err != nil {
-			if time.Now().After(deadline) {
-				return context.DeadlineExceeded
+		for _, pattern := range allowed {
+			// FIXME: not ideal to compile everytime, but is there another way to create a clone?
+			clone := regexp2.MustCompile(pattern.String(), 0)
+			clone.MatchTimeout = time.Until(deadline)
+
+			ok, err := clone.MatchString(s)
+			if err != nil {
+				if time.Now().After(deadline) {
+					return context.DeadlineExceeded
+				}
+
+				return fmt.Errorf("'%s' cannot handle '%s': %w", clone.String(), s, err)
+			}
+
+			if ok {
+				matched = true
+				break
 			}
-			return fmt.Errorf("'%s' cannot handle '%s': %w", allow.String(), s, err)
 		}
-		if !ok {
-			return fmt.Errorf("'%s' does not match the expression from the allowed list: %w", s, ErrFiltered)
+
+		if !matched {
+			return fmt.Errorf("'%s' does not match any expression from the allowed list: %w", s, ErrFiltered)
 		}
 	}
 
-	if denied.String() != "" {
-		deny := regexp2.MustCompile(denied.String(), 0)
-		deny.MatchTimeout = time.Until(deadline)
+	if len(denied) > 0 {
+		for _, pattern := range denied {
+			clone := regexp2.MustCompile(pattern.String(), 0)
+			clone.MatchTimeout = time.Until(deadline)
 
-		ok, err := deny.MatchString(s)
-		if err != nil {
-			if time.Now().After(deadline) {
-				return context.DeadlineExceeded
+			ok, err := clone.MatchString(s)
+			if err != nil {
+				if time.Now().After(deadline) {
+					return context.DeadlineExceeded
+				}
+
+				return fmt.Errorf("'%s' cannot handle '%s': %w", clone.String(), s, err)
+			}
+
+			if ok {
+				return fmt.Errorf("'%s' matches the expression from the denied list: %w", s, ErrFiltered)
 			}
-			return fmt.Errorf("'%s' cannot handle '%s': %w", deny.String(), s, err)
-		}
-		if ok {
-			return fmt.Errorf("'%s' matches the expression from the denied list: %w", s, ErrFiltered)
 		}
 	}
 

pkg/gotenberg/filter_test.go

@@ -12,8 +12,8 @@ import (
 func TestFilterDeadline(t *testing.T) {
 	for _, tc := range []struct {
 		scenario      string
-		allowed       *regexp2.Regexp
-		denied        *regexp2.Regexp
+		allowed       []*regexp2.Regexp
+		denied        []*regexp2.Regexp
 		s             string
 		deadline      time.Time
 		expectError   bool
@@ -21,17 +21,17 @@ func TestFilterDeadline(t *testing.T) {
 	}{
 		{
 			scenario:      "DeadlineExceeded (allowed)",
-			allowed:       regexp2.MustCompile("foo", 0),
-			denied:        regexp2.MustCompile("", 0),
+			allowed:       []*regexp2.Regexp{regexp2.MustCompile("foo", 0)},
+			denied:        nil,
 			s:             "foo",
 			deadline:      time.Now().Add(time.Duration(-1) * time.Hour),
 			expectError:   true,
 			expectedError: context.DeadlineExceeded,
 		},
 		{
-			scenario:      "ErrFiltered (allowed)",
-			allowed:       regexp2.MustCompile("foo", 0),
-			denied:        regexp2.MustCompile("", 0),
+			scenario:      "ErrFiltered (allowed, no match)",
+			allowed:       []*regexp2.Regexp{regexp2.MustCompile("foo", 0)},
+			denied:        nil,
 			s:             "bar",
 			deadline:      time.Now().Add(time.Duration(5) * time.Second),
 			expectError:   true,
@@ -39,8 +39,8 @@ func TestFilterDeadline(t *testing.T) {
 		},
 		{
 			scenario:      "DeadlineExceeded (denied)",
-			allowed:       regexp2.MustCompile("", 0),
-			denied:        regexp2.MustCompile("foo", 0),
+			allowed:       nil,
+			denied:        []*regexp2.Regexp{regexp2.MustCompile("foo", 0)},
 			s:             "foo",
 			deadline:      time.Now().Add(time.Duration(-1) * time.Hour),
 			expectError:   true,
@@ -48,21 +48,55 @@ func TestFilterDeadline(t *testing.T) {
 		},
 		{
 			scenario:      "ErrFiltered (denied)",
-			allowed:       regexp2.MustCompile("", 0),
-			denied:        regexp2.MustCompile("foo", 0),
+			allowed:       nil,
+			denied:        []*regexp2.Regexp{regexp2.MustCompile("foo", 0)},
 			s:             "foo",
 			deadline:      time.Now().Add(time.Duration(5) * time.Second),
 			expectError:   true,
 			expectedError: ErrFiltered,
 		},
 		{
-			scenario:    "success",
-			allowed:     regexp2.MustCompile("", 0),
-			denied:      regexp2.MustCompile("", 0),
+			scenario:    "success (empty lists)",
+			allowed:     nil,
+			denied:      nil,
 			s:           "foo",
 			deadline:    time.Now().Add(time.Duration(5) * time.Second),
 			expectError: false,
 		},
+		{
+			scenario:    "multi-pattern allow list, second matches",
+			allowed:     []*regexp2.Regexp{regexp2.MustCompile("^https://", 0), regexp2.MustCompile("^file:///tmp/", 0)},
+			denied:      nil,
+			s:           "file:///tmp/abc/index.html",
+			deadline:    time.Now().Add(time.Duration(5) * time.Second),
+			expectError: false,
+		},
+		{
+			scenario:      "multi-pattern allow list, none matches",
+			allowed:       []*regexp2.Regexp{regexp2.MustCompile("^https://", 0), regexp2.MustCompile("^ftp://", 0)},
+			denied:        nil,
+			s:             "file:///tmp/abc/index.html",
+			deadline:      time.Now().Add(time.Duration(5) * time.Second),
+			expectError:   true,
+			expectedError: ErrFiltered,
+		},
+		{
+			scenario:      "multi-pattern deny list, second matches",
+			allowed:       nil,
+			denied:        []*regexp2.Regexp{regexp2.MustCompile("^ftp://", 0), regexp2.MustCompile("^file:.*", 0)},
+			s:             "file:///etc/passwd",
+			deadline:      time.Now().Add(time.Duration(5) * time.Second),
+			expectError:   true,
+			expectedError: ErrFiltered,
+		},
+		{
+			scenario:    "https URL passes deny list targeting file://",
+			allowed:     nil,
+			denied:      []*regexp2.Regexp{regexp2.MustCompile("^file:.*", 0)},
+			s:           "https://example.com",
+			deadline:    time.Now().Add(time.Duration(5) * time.Second),
+			expectError: false,
+		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
 			err := FilterDeadline(tc.allowed, tc.denied, tc.s, tc.deadline)

pkg/gotenberg/flags.go

@@ -222,3 +222,32 @@ func (f *ParsedFlags) MustDeprecatedRegexp(deprecated string, newName string) *r
 
 	return f.MustRegexp(newName)
 }
+
+// MustRegexpSlice returns a slice of compiled regular expressions from a
+// string-slice flag given by name. Empty strings are skipped.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustRegexpSlice(name string) []*regexp2.Regexp {
+	vals := f.MustStringSlice(name)
+
+	var regexps []*regexp2.Regexp
+	for _, val := range vals {
+		if val == "" {
+			continue
+		}
+
+		regexps = append(regexps, regexp2.MustCompile(val, 0))
+	}
+
+	return regexps
+}
+
+// MustDeprecatedRegexpSlice returns the slice of compiled regular expressions
+// of a deprecated flag if it was explicitly set or the slice of the new flag.
+// It panics if an error occurs.
+func (f *ParsedFlags) MustDeprecatedRegexpSlice(deprecated string, newName string) []*regexp2.Regexp {
+	if f.Changed(deprecated) {
+		return f.MustRegexpSlice(deprecated)
+	}
+
+	return f.MustRegexpSlice(newName)
+}

pkg/gotenberg/flags_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/dlclark/regexp2"
 	flag "github.com/spf13/pflag"
 )
 
@@ -833,3 +834,120 @@ func TestParsedFlags_MustDeprecatedRegexp(t *testing.T) {
 		})
 	}
 }
+
+func TestParsedFlags_MustRegexpSlice(t *testing.T) {
+	fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+	fs.StringSlice("foo", []string{}, "")
+
+	err := fs.Parse([]string{"--foo=^file:.*", "--foo=^ftp://.*"})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags := ParsedFlags{FlagSet: fs}
+
+	for _, tc := range []struct {
+		scenario    string
+		name        string
+		expectPanic bool
+		expectLen   int
+	}{
+		{
+			scenario:    "success with multiple patterns",
+			name:        "foo",
+			expectPanic: false,
+			expectLen:   2,
+		},
+		{
+			scenario:    "non-existing flag",
+			name:        "bar",
+			expectPanic: true,
+		},
+	} {
+		t.Run(tc.scenario, func(t *testing.T) {
+			if tc.expectPanic {
+				defer func() {
+					if r := recover(); r == nil {
+						t.Fatal("expected panic but got none")
+					}
+				}()
+			}
+
+			if !tc.expectPanic {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Fatalf("expected no panic but got: %v", r)
+					}
+				}()
+			}
+
+			result := parsedFlags.MustRegexpSlice(tc.name)
+
+			if !tc.expectPanic && len(result) != tc.expectLen {
+				t.Errorf("expected %d regexps but got %d", tc.expectLen, len(result))
+			}
+		})
+	}
+
+	// Test empty strings are skipped.
+	fs2 := flag.NewFlagSet("tests2", flag.ContinueOnError)
+	fs2.StringSlice("baz", []string{""}, "")
+
+	err = fs2.Parse([]string{})
+	if err != nil {
+		t.Fatalf("expected no error but got: %v", err)
+	}
+
+	parsedFlags2 := ParsedFlags{FlagSet: fs2}
+	result := parsedFlags2.MustRegexpSlice("baz")
+	if len(result) != 0 {
+		t.Errorf("expected 0 regexps for empty strings but got %d", len(result))
+	}
+}
+
+func TestParsedFlags_MustDeprecatedRegexpSlice(t *testing.T) {
+	for _, tc := range []struct {
+		scenario      string
+		rawFlags      []string
+		expectPattern string
+	}{
+		{
+			scenario:      "deprecated flag value",
+			rawFlags:      []string{"--foo=^file:.*"},
+			expectPattern: "^file:.*",
+		},
+		{
+			scenario:      "non-deprecated flag value",
+			rawFlags:      []string{"--bar=^ftp://.*"},
+			expectPattern: "^ftp://.*",
+		},
+		{
+			scenario:      "deprecated flag value > non-deprecated flag value",
+			rawFlags:      []string{"--foo=^file:.*", "--bar=^ftp://.*"},
+			expectPattern: "^file:.*",
+		},
+	} {
+		t.Run(tc.scenario, func(t *testing.T) {
+			fs := flag.NewFlagSet("tests", flag.ContinueOnError)
+			fs.StringSlice("foo", []string{}, "")
+			fs.StringSlice("bar", []string{}, "")
+
+			parsedFlags := ParsedFlags{FlagSet: fs}
+
+			err := parsedFlags.Parse(tc.rawFlags)
+			if err != nil {
+				t.Fatalf("expected no error but got: %v", err)
+			}
+
+			actual := parsedFlags.MustDeprecatedRegexpSlice("foo", "bar")
+			if len(actual) != 1 {
+				t.Fatalf("expected 1 regexp but got %d", len(actual))
+			}
+			if actual[0].String() != tc.expectPattern {
+				t.Errorf("expected pattern '%s' but got '%s'", tc.expectPattern, actual[0].String())
+			}
+		})
+	}
+
+	_ = regexp2.None // Keep import alive.
+}

pkg/gotenberg/gc.go

@@ -38,7 +38,7 @@ func GarbageCollect(ctx context.Context, logger *slog.Logger, rootPath string, i
 
 		for _, substr := range includeSubstr {
 			if (strings.Contains(info.Name(), substr) || path == substr) && info.ModTime().Before(expirationTime) {
-				err := os.RemoveAll(path)
+				err := os.RemoveAll(path) //nolint:gosec // G122: rootPath is a trusted internal working directory
 				if err != nil {
 					return fmt.Errorf("garbage collect '%s': %w", path, err)
 				}

pkg/gotenberg/gc_test.go

@@ -67,7 +67,7 @@ func TestGarbageCollect(t *testing.T) {
 				}
 			}()
 
-			err := GarbageCollect(context.Background(), slog.New(slog.NewJSONHandler(os.Stdout, nil)), tc.rootPath, tc.includeSubstr, time.Now())
+			err := GarbageCollect(context.Background(), slog.New(slog.DiscardHandler), tc.rootPath, tc.includeSubstr, time.Now())
 
 			if !tc.expectError && err != nil {
 				t.Fatalf("expected no error but got: %v", err)

pkg/gotenberg/internal/log/stdhandler.go

@@ -71,16 +71,17 @@ func NewStdHandler(level slog.Level, format string, fieldsPrefix string, enableG
 		// Configure level encoding based on format and GCP settings.
 		if a.Key == slog.LevelKey {
 			l := a.Value.Any().(slog.Level)
-			if format == textLoggingFormat && isTerminal {
+			switch {
+			case format == textLoggingFormat && isTerminal:
 				if enableGcpFields {
 					a.Value = slog.StringValue(gcpSeverityColorEncoder(l))
 				} else {
 					a.Value = slog.StringValue(levelToColor(l).Add(l.String()))
 				}
-			} else if enableGcpFields && format != textLoggingFormat {
+			case enableGcpFields && format != textLoggingFormat:
 				a.Key = "severity"
 				a.Value = slog.StringValue(gcpSeverity(l))
-			} else {
+			default:
 				a.Value = slog.StringValue(strings.ToLower(l.String()))
 			}
 		}

pkg/gotenberg/logging.go

@@ -0,0 +1 @@
+package gotenberg

pkg/gotenberg/metrics.go

@@ -0,0 +1,26 @@
+package gotenberg
+
+// Metric represents a unitary metric.
+type Metric struct {
+	// Name is the unique identifier.
+	// Required.
+	Name string
+
+	// Description describes the metric.
+	// Optional.
+	Description string
+
+	// Read returns the current value.
+	// Required.
+	Read func() float64
+}
+
+// MetricsProvider is a module interface which provides a list of [Metric].
+//
+//	func (m *YourModule) Provision(ctx *gotenberg.Context) error {
+//		provider, _ := ctx.Module(new(gotenberg.MetricsProvider))
+//		metrics, _  := provider.(gotenberg.MetricsProvider).Metrics()
+//	}
+type MetricsProvider interface {
+	Metrics() ([]Metric, error)
+}

pkg/gotenberg/mocks.go

@@ -50,9 +50,15 @@ type PdfEngineMock struct {
 	FlattenMock        func(ctx context.Context, logger *slog.Logger, inputPath string) error
 	ConvertMock        func(ctx context.Context, logger *slog.Logger, formats PdfFormats, inputPath, outputPath string) error
 	ReadMetadataMock   func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error)
+	PageCountMock      func(ctx context.Context, logger *slog.Logger, inputPath string) (int, error)
 	WriteMetadataMock  func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error
+	ReadBookmarksMock  func(ctx context.Context, logger *slog.Logger, inputPath string) ([]Bookmark, error)
 	EncryptMock        func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error
-	AddAttachmentsMock func(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error
+	EmbedFilesMock     func(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error
+	WriteBookmarksMock func(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []Bookmark) error
+	WatermarkMock      func(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error
+	StampMock          func(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error
+	RotateMock         func(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error
 }
 
 func (engine *PdfEngineMock) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
@@ -75,16 +81,40 @@ func (engine *PdfEngineMock) ReadMetadata(ctx context.Context, logger *slog.Logg
 	return engine.ReadMetadataMock(ctx, logger, inputPath)
 }
 
+func (engine *PdfEngineMock) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	return engine.PageCountMock(ctx, logger, inputPath)
+}
+
 func (engine *PdfEngineMock) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
 	return engine.WriteMetadataMock(ctx, logger, metadata, inputPath)
 }
 
+func (engine *PdfEngineMock) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]Bookmark, error) {
+	return engine.ReadBookmarksMock(ctx, logger, inputPath)
+}
+
 func (engine *PdfEngineMock) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
 	return engine.EncryptMock(ctx, logger, inputPath, userPassword, ownerPassword)
 }
 
-func (engine *PdfEngineMock) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	return engine.AddAttachmentsMock(ctx, logger, filePaths, inputPath)
+func (engine *PdfEngineMock) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	return engine.EmbedFilesMock(ctx, logger, filePaths, inputPath)
+}
+
+func (engine *PdfEngineMock) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []Bookmark) error {
+	return engine.WriteBookmarksMock(ctx, logger, inputPath, bookmarks)
+}
+
+func (engine *PdfEngineMock) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error {
+	return engine.WatermarkMock(ctx, logger, inputPath, stamp)
+}
+
+func (engine *PdfEngineMock) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error {
+	return engine.StampMock(ctx, logger, inputPath, stamp)
+}
+
+func (engine *PdfEngineMock) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	return engine.RotateMock(ctx, logger, inputPath, angle, pages)
 }
 
 // PdfEngineProviderMock is a mock for the [PdfEngineProvider] interface.
@@ -122,8 +152,8 @@ type ProcessSupervisorMock struct {
 	HealthyMock          func() bool
 	RunMock              func(ctx context.Context, logger *slog.Logger, task func() error) error
 	ReqQueueSizeMock     func() int64
-	ActiveTasksCountMock func() int64
 	RestartsCountMock    func() int64
+	ActiveTasksCountMock func() int64
 }
 
 func (s *ProcessSupervisorMock) Launch() error {
@@ -146,12 +176,21 @@ func (s *ProcessSupervisorMock) ReqQueueSize() int64 {
 	return s.ReqQueueSizeMock()
 }
 
+func (s *ProcessSupervisorMock) RestartsCount() int64 {
+	return s.RestartsCountMock()
+}
+
 func (s *ProcessSupervisorMock) ActiveTasksCount() int64 {
 	return s.ActiveTasksCountMock()
 }
 
-func (s *ProcessSupervisorMock) RestartsCount() int64 {
-	return s.RestartsCountMock()
+// MetricsProviderMock is a mock for the [MetricsProvider] interface.
+type MetricsProviderMock struct {
+	MetricsMock func() ([]Metric, error)
+}
+
+func (provider *MetricsProviderMock) Metrics() ([]Metric, error) {
+	return provider.MetricsMock()
 }
 
 // MkdirAllMock is a mock for the [MkdirAll] interface.
@@ -180,6 +219,7 @@ var (
 	_ PdfEngineProvider = (*PdfEngineProviderMock)(nil)
 	_ Process           = (*ProcessMock)(nil)
 	_ ProcessSupervisor = (*ProcessSupervisorMock)(nil)
+	_ MetricsProvider   = (*MetricsProviderMock)(nil)
 	_ MkdirAll          = (*MkdirAllMock)(nil)
 	_ PathRename        = (*PathRenameMock)(nil)
 )

pkg/gotenberg/pdfengine.go

@@ -27,6 +27,14 @@ var (
 	// ErrPdfEncryptionNotSupported is returned when encryption
 	// is not supported by the PDF engine.
 	ErrPdfEncryptionNotSupported = errors.New("encryption not supported")
+
+	// ErrPdfStampSourceNotSupported is returned when a stamp source type
+	// is not supported by the PDF engine.
+	ErrPdfStampSourceNotSupported = errors.New("stamp source not supported")
+
+	// ErrPdfRotateAngleNotSupported is returned when the rotation angle is
+	// not supported.
+	ErrPdfRotateAngleNotSupported = errors.New("rotation angle not supported")
 )
 
 // PdfEngineInvalidArgsError represents an error returned by a PDF engine when
@@ -48,6 +56,33 @@ func NewPdfEngineInvalidArgs(engine, msg string) error {
 	return &PdfEngineInvalidArgsError{engine, msg}
 }
 
+const (
+	// StampSourceText represents a text-based stamp source.
+	StampSourceText string = "text"
+
+	// StampSourceImage represents an image-based stamp source.
+	StampSourceImage string = "image"
+
+	// StampSourcePDF represents a PDF-based stamp source.
+	StampSourcePDF string = "pdf"
+)
+
+// Stamp gathers the data required to apply a watermark or stamp to a PDF.
+type Stamp struct {
+	// Source is one of "text", "image", or "pdf".
+	Source string
+
+	// Expression is the text content (for text source) or file path (for
+	// image/pdf source).
+	Expression string
+
+	// Pages is the optional page range to apply the stamp to.
+	Pages string
+
+	// Options holds engine-specific styling options.
+	Options map[string]string
+}
+
 const (
 	// SplitModeIntervals represents a mode where a PDF is split at specific
 	// intervals.
@@ -108,6 +143,14 @@ type PdfFormats struct {
 	PdfUa bool
 }
 
+// Bookmark represents a node in the PDF document's outline
+// (table of contents).
+type Bookmark struct {
+	Title    string     `json:"title"`
+	Page     int        `json:"page"`
+	Children []Bookmark `json:"children,omitempty"`
+}
+
 // PdfEngine provides an interface for operations on PDFs. Implementations
 // can use various tools like PDFtk, or implement functionality directly in
 // Go.
@@ -134,18 +177,39 @@ type PdfEngine interface {
 	// ReadMetadata extracts the metadata of a given PDF file.
 	ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error)
 
+	// PageCount returns the number of pages in a PDF file.
+	PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error)
+
 	// WriteMetadata writes the metadata into a given PDF file.
 	WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error
 
+	// ReadBookmarks reads the document outline (bookmarks) of a PDF file.
+	ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]Bookmark, error)
+
+	// WriteBookmarks adds a document outline (bookmarks) to a PDF file.
+	// The bookmarks parameter represents the hierarchical tree of the outline.
+	WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []Bookmark) error
+
 	// Encrypt adds password protection to a PDF file.
 	// The userPassword is required to open the document.
 	// The ownerPassword provides full access to the document.
 	// If the ownerPassword is empty, it defaults to the userPassword.
 	Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error
 
-	// AddAttachments adds attachments into a PDF. All files are attached as
-	// file attachments without modifying the main PDF content.
-	AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error
+	// EmbedFiles embeds files into a PDF. All files are embedded as file attachments
+	// without modifying the main PDF content.
+	// TODO: attachments instead? Rename the route?
+	EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error
+
+	// Watermark applies a watermark (behind page content) to a PDF file.
+	Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error
+
+	// Stamp applies a stamp (on top of page content) to a PDF file.
+	Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp Stamp) error
+
+	// Rotate rotates pages of a PDF file by the given angle (90, 180, 270).
+	// If pages is empty, all pages are rotated.
+	Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error
 }
 
 // PdfEngineProvider offers an interface to instantiate a [PdfEngine].

pkg/gotenberg/supervisor.go

@@ -7,6 +7,7 @@ import (
 	"log/slog"
 	"sync"
 	"sync/atomic"
+	"time"
 )
 
 // ErrProcessAlreadyRestarting happens if the [ProcessSupervisor] is trying
@@ -53,9 +54,9 @@ type ProcessSupervisor interface {
 
 	// Healthy checks and returns the health status of the managed [Process].
 	//
-	// If the process has not been started or is restarting, it is considered
-	// healthy and true is returned. Otherwise, it returns the health status of
-	// the actual process.
+	// A non-started process is considered healthy (startup is deferred until
+	// the first request). Returns false if the process is currently restarting
+	// or is reported unhealthy by the underlying [Process].
 	Healthy() bool
 
 	// Run executes a provided task while managing the state of the [Process].
@@ -70,44 +71,53 @@ type ProcessSupervisor interface {
 	// ReqQueueSize returns the current size of the request queue.
 	ReqQueueSize() int64
 
-	// ActiveTasksCount returns the current number of active tasks.
-	ActiveTasksCount() int64
-
 	// RestartsCount returns the current number of restart.
 	RestartsCount() int64
+
+	// ActiveTasksCount returns the current number of active tasks.
+	ActiveTasksCount() int64
 }
 
 type processSupervisor struct {
-	logger          *slog.Logger
-	process         Process
-	maxReqLimit     int64
-	maxQueueSize    int64
-	maxConcurrency  int64
-	semaphore       chan struct{}
-	firstStart      atomic.Bool
-	firstStartOnce  sync.Once
-	firstStartErr   error
-	reqCounter      atomic.Int64
-	reqQueueSize    atomic.Int64
-	restartsCounter atomic.Int64
-	isRestarting    atomic.Bool
-	activeTasks     atomic.Int64
-	restartMutex    sync.Mutex
+	logger         *slog.Logger
+	process        Process
+	maxReqLimit    int64
+	maxQueueSize   int64
+	maxConcurrency int64
+	semaphore      chan struct{}
+	firstStart     atomic.Bool
+	firstStartOnce sync.Once
+	// firstStartErr stores the error from the first Launch attempt executed
+	// via firstStartOnce. Subsequent callers that enter the !firstStart block
+	// need to observe this value after the Once has completed, without
+	// re-executing the closure.
+	firstStartErr       error
+	reqCounter          atomic.Int64
+	reqQueueSize        atomic.Int64
+	restartsCounter     atomic.Int64
+	isRestarting        atomic.Bool
+	activeTasks         atomic.Int64
+	restartMutex        sync.Mutex
+	idleShutdownTimeout time.Duration
+	lastActivity        atomic.Int64  // unix nano timestamp of last completed task
+	idleMu              sync.Mutex    // protects idleStopChan
+	idleStopChan        chan struct{} // signal to stop the idle ticker goroutine
 }
 
 // NewProcessSupervisor initializes a new [ProcessSupervisor].
-func NewProcessSupervisor(logger *slog.Logger, process Process, maxReqLimit, maxQueueSize, maxConcurrency int64) ProcessSupervisor {
+func NewProcessSupervisor(logger *slog.Logger, process Process, maxReqLimit, maxQueueSize, maxConcurrency int64, idleShutdownTimeout time.Duration) ProcessSupervisor {
 	if maxConcurrency < 1 {
 		maxConcurrency = 1
 	}
 
 	b := &processSupervisor{
-		logger:         logger,
-		process:        process,
-		semaphore:      make(chan struct{}, maxConcurrency),
-		maxReqLimit:    maxReqLimit,
-		maxQueueSize:   maxQueueSize,
-		maxConcurrency: maxConcurrency,
+		logger:              logger,
+		process:             process,
+		semaphore:           make(chan struct{}, maxConcurrency),
+		maxReqLimit:         maxReqLimit,
+		maxQueueSize:        maxQueueSize,
+		maxConcurrency:      maxConcurrency,
+		idleShutdownTimeout: idleShutdownTimeout,
 	}
 	b.reqCounter.Store(0)
 	b.reqQueueSize.Store(0)
@@ -126,6 +136,12 @@ func (s *processSupervisor) Launch() error {
 	}
 
 	s.firstStart.Store(true)
+
+	if s.idleShutdownTimeout > 0 {
+		s.lastActivity.Store(time.Now().UnixNano())
+		s.startIdleTicker()
+	}
+
 	s.logger.DebugContext(context.Background(), "process successfully started")
 
 	return nil
@@ -133,6 +149,9 @@ func (s *processSupervisor) Launch() error {
 
 func (s *processSupervisor) Shutdown() error {
 	s.logger.DebugContext(context.Background(), "shutdown process")
+
+	s.stopIdleTicker()
+
 	err := s.process.Stop(s.logger)
 	if err != nil {
 		return fmt.Errorf("shutdown process: %w", err)
@@ -148,8 +167,9 @@ func (s *processSupervisor) restart() error {
 
 	err := s.Shutdown()
 	if err != nil {
-		// No big deal? Chances are it's already stopped.
-		s.logger.DebugContext(context.Background(), fmt.Sprintf("stop process before restart: %s", err))
+		// Not necessarily critical — chances are the process is already stopped,
+		// but worth flagging in case it indicates a real issue.
+		s.logger.WarnContext(context.Background(), fmt.Sprintf("stop process before restart: %s", err))
 	}
 
 	err = s.Launch()
@@ -166,117 +186,84 @@ func (s *processSupervisor) restart() error {
 
 func (s *processSupervisor) Healthy() bool {
 	if !s.firstStart.Load() {
-		// A non-started process is always healthy.
+		// A non-started process is considered healthy: Gotenberg defers
+		// process startup until the first request to keep resource usage low.
+		// Reporting unhealthy here would cause container orchestrators to
+		// restart the pod before any request arrives.
 		return true
 	}
 
 	if s.isRestarting.Load() {
-		// A restarting process is always healthy.
-		return true
+		// A restarting process is not yet healthy — this gives load balancers
+		// honest information so they can avoid routing traffic to this node.
+		return false
 	}
 
 	return s.process.Healthy(s.logger)
 }
 
 func (s *processSupervisor) Run(ctx context.Context, logger *slog.Logger, task func() error) error {
-	// A user reported a potential issue:
-	//
-	// "Although the counting operation is atomic, nothing prevent 2 concurrent
-	// goroutines to retrieve the same 'currentQueueSize' and to compare its
-	// value against the max limit. Then, resulting queue size would be 1 above
-	// the allowed limit."
-	//
-	// However, he was unable to actually trigger this issue, even when sending
-	// a lot of requests.
-	//
-	// For now, the best option is to consider this issue to be unlikely to
-	// happen, and keep the code as it is because it is more readable this way.
-	//
-	// See https://github.com/gotenberg/gotenberg/issues/951.
-	currentQueueSize := s.reqQueueSize.Load()
-	if s.maxQueueSize > 0 && currentQueueSize >= s.maxQueueSize {
-		return ErrMaximumQueueSizeExceeded
+	// Atomically check and increment the queue size to avoid the TOCTOU race
+	// originally reported in https://github.com/gotenberg/gotenberg/issues/951.
+	for {
+		current := s.reqQueueSize.Load()
+		if s.maxQueueSize > 0 && current >= s.maxQueueSize {
+			return ErrMaximumQueueSizeExceeded
+		}
+		if s.reqQueueSize.CompareAndSwap(current, current+1) {
+			break
+		}
 	}
 
-	s.reqQueueSize.Add(1)
+	// Decrement when Run() returns, regardless of which path is taken
+	// (context timeout, task completion, error, etc.). This ensures the
+	// request is counted as "in the queue" for the entire duration of Run(),
+	// preventing new requests from entering while one is being processed.
+	// See https://github.com/gotenberg/gotenberg/issues/1502.
+	defer s.reqQueueSize.Add(-1)
 
 	for {
 		err := func() error {
-			select {
-			case s.semaphore <- struct{}{}:
-				logger.DebugContext(ctx, "process lock acquired")
-
-				// If a restart drain is in progress, release the slot
-				// immediately so the drain can acquire it instead.
-				if s.isRestarting.Load() {
-					<-s.semaphore
-					return ErrProcessAlreadyRestarting
-				}
-
-				s.reqQueueSize.Add(-1)
-				s.reqCounter.Add(1)
-				s.activeTasks.Add(1)
-				releaseSemaphore := true
-
-				defer func() {
-					s.activeTasks.Add(-1)
-					if releaseSemaphore {
-						logger.DebugContext(ctx, "process lock released")
-						<-s.semaphore
-					}
-				}()
-
-				if !s.firstStart.Load() {
-					s.firstStartOnce.Do(func() {
-						s.firstStartErr = s.runWithDeadline(ctx, func() error {
-							return s.Launch()
-						})
-					})
-					if s.firstStartErr != nil {
-						return fmt.Errorf("process first start: %w", s.firstStartErr)
-					}
-				}
-
-				if !s.Healthy() {
-					s.logger.DebugContext(ctx, "process is unhealthy, cannot handle task, restarting...")
-					err := s.doRestart(ctx)
-					if err != nil {
-						return fmt.Errorf("process restart before task: %w", err)
-					}
-				}
-
-				err := s.runWithDeadline(ctx, task)
-
-				if s.maxReqLimit > 0 && s.reqCounter.Load() >= s.maxReqLimit {
-					// Only one goroutine should trigger the restart.
-					if s.restartMutex.TryLock() {
-						s.logger.DebugContext(ctx, "max request limit reached, restarting eagerly...")
-						releaseSemaphore = false
-
-						go func() {
-							restartErr := s.doRestartLocked(context.Background())
-							s.restartMutex.Unlock()
-							if restartErr != nil {
-								s.logger.ErrorContext(context.Background(), fmt.Sprintf("process restart after task: %v", restartErr))
-							}
-							logger.DebugContext(context.Background(), "process lock released")
-							<-s.semaphore
-						}()
-					}
-				}
-
-				// Note: no error wrapping because it leaks on Chromium console exceptions output.
+			if err := s.acquireSlot(ctx, logger); err != nil {
 				return err
-			case <-ctx.Done():
-				logger.DebugContext(ctx, "failed to acquire process lock before deadline")
-				s.reqQueueSize.Add(-1)
-
-				return fmt.Errorf("acquire process lock: %w", ctx.Err())
 			}
+
+			s.reqCounter.Add(1)
+			s.activeTasks.Add(1)
+			semaphoreOwned := true
+
+			defer func() {
+				s.activeTasks.Add(-1)
+				if s.idleShutdownTimeout > 0 {
+					s.lastActivity.Store(time.Now().UnixNano())
+				}
+				if semaphoreOwned {
+					logger.DebugContext(ctx, "process lock released")
+					<-s.semaphore
+				}
+			}()
+
+			if err := s.ensureStarted(ctx); err != nil {
+				return err
+			}
+
+			if err := s.ensureHealthy(ctx); err != nil {
+				return err
+			}
+
+			err := s.runWithDeadline(ctx, task)
+
+			if s.maybeRestartAfterTask(logger) {
+				semaphoreOwned = false
+			}
+
+			// Note: no error wrapping because it leaks on Chromium console exceptions output.
+			return err
 		}()
 
 		if errors.Is(err, ErrProcessAlreadyRestarting) {
 			logger.DebugContext(ctx, "process is already restarting, trying to acquire process lock again...")
+			time.Sleep(10 * time.Millisecond)
 			continue
 		}
 
@@ -285,6 +272,174 @@ func (s *processSupervisor) Run(ctx context.Context, logger *slog.Logger, task f
 	}
 }
 
+// startIdleTicker starts a background goroutine that periodically checks
+// whether the process has been idle long enough to shut down.
+func (s *processSupervisor) startIdleTicker() {
+	stopChan := make(chan struct{})
+
+	s.idleMu.Lock()
+	s.idleStopChan = stopChan
+	s.idleMu.Unlock()
+
+	go func() {
+		ticker := time.NewTicker(s.idleShutdownTimeout)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				s.maybeIdleShutdown()
+			case <-stopChan:
+				return
+			}
+		}
+	}()
+}
+
+// stopIdleTicker signals the idle ticker goroutine to exit, if one is running.
+func (s *processSupervisor) stopIdleTicker() {
+	s.idleMu.Lock()
+	defer s.idleMu.Unlock()
+
+	if s.idleStopChan != nil {
+		close(s.idleStopChan)
+		s.idleStopChan = nil
+	}
+}
+
+// maybeIdleShutdown stops the process if it has been idle for longer than
+// the configured timeout. It is safe to call concurrently with Run and
+// restart.
+func (s *processSupervisor) maybeIdleShutdown() {
+	if !s.firstStart.Load() || s.isRestarting.Load() {
+		return
+	}
+
+	if s.activeTasks.Load() > 0 || s.reqQueueSize.Load() > 0 {
+		return
+	}
+
+	lastNano := s.lastActivity.Load()
+	if lastNano == 0 || time.Since(time.Unix(0, lastNano)) < s.idleShutdownTimeout {
+		return
+	}
+
+	if !s.restartMutex.TryLock() {
+		return
+	}
+	defer s.restartMutex.Unlock()
+
+	// Double-check after acquiring the lock.
+	if s.activeTasks.Load() > 0 || s.reqQueueSize.Load() > 0 {
+		return
+	}
+
+	s.logger.InfoContext(context.Background(), "idle shutdown timeout reached, stopping process")
+
+	// Stop the ticker — it will be restarted on the next Launch().
+	s.stopIdleTicker()
+
+	err := s.process.Stop(s.logger)
+	if err != nil {
+		s.logger.WarnContext(context.Background(), fmt.Sprintf("idle shutdown: %s", err))
+		return
+	}
+
+	// Reset state so ensureStarted() re-launches on next request.
+	s.firstStart.Store(false)
+	s.firstStartOnce = sync.Once{}
+	s.firstStartErr = nil
+	s.reqCounter.Store(0)
+
+	s.logger.InfoContext(context.Background(), "process stopped due to idle timeout")
+}
+
+// acquireSlot attempts to acquire a semaphore slot, yielding it back if a
+// restart drain is in progress.
+func (s *processSupervisor) acquireSlot(ctx context.Context, logger *slog.Logger) error {
+	select {
+	case s.semaphore <- struct{}{}:
+		// If a restart drain is in progress, release the slot
+		// immediately so the drain can acquire it instead.
+		if s.isRestarting.Load() {
+			<-s.semaphore
+			return ErrProcessAlreadyRestarting
+		}
+
+		logger.DebugContext(ctx, "process lock acquired")
+
+		return nil
+	case <-ctx.Done():
+		logger.DebugContext(ctx, "failed to acquire process lock before deadline")
+
+		return fmt.Errorf("acquire process lock: %w", ctx.Err())
+	}
+}
+
+// ensureStarted performs a one-time lazy launch of the process on its first
+// use. Subsequent calls are no-ops.
+func (s *processSupervisor) ensureStarted(ctx context.Context) error {
+	if s.firstStart.Load() {
+		return nil
+	}
+
+	s.firstStartOnce.Do(func() {
+		s.firstStartErr = s.runWithDeadline(ctx, func() error {
+			return s.Launch()
+		})
+	})
+
+	if s.firstStartErr != nil {
+		return fmt.Errorf("process first start: %w", s.firstStartErr)
+	}
+
+	return nil
+}
+
+// ensureHealthy checks the underlying process health and triggers a
+// synchronous restart if the process is unhealthy. Skips the check if a
+// restart is already in progress.
+func (s *processSupervisor) ensureHealthy(ctx context.Context) error {
+	if s.isRestarting.Load() || s.process.Healthy(s.logger) {
+		return nil
+	}
+
+	s.logger.DebugContext(context.Background(), "process is unhealthy, cannot handle task, restarting...")
+
+	if err := s.doRestart(ctx); err != nil {
+		return fmt.Errorf("process restart before task: %w", err)
+	}
+
+	return nil
+}
+
+// maybeRestartAfterTask checks if the maximum request limit has been reached
+// and, if so, triggers an asynchronous restart. If a restart is initiated, it
+// takes ownership of the caller's semaphore slot (the caller must not release
+// it). Returns true if ownership was taken.
+func (s *processSupervisor) maybeRestartAfterTask(logger *slog.Logger) bool {
+	if s.maxReqLimit <= 0 || s.reqCounter.Load() < s.maxReqLimit {
+		return false
+	}
+
+	if !s.restartMutex.TryLock() {
+		return false
+	}
+
+	s.logger.DebugContext(context.Background(), "max request limit reached, restarting eagerly...")
+
+	go func() {
+		restartErr := s.doRestartLocked(context.Background())
+		s.restartMutex.Unlock()
+		if restartErr != nil {
+			s.logger.ErrorContext(context.Background(), fmt.Sprintf("process restart after task: %v", restartErr))
+		}
+		logger.DebugContext(context.Background(), "process lock released")
+		<-s.semaphore
+	}()
+
+	return true
+}
+
 // doRestart coordinates a process restart, draining all active concurrent
 // tasks before stopping and restarting the process.
 func (s *processSupervisor) doRestart(ctx context.Context) error {
@@ -346,14 +501,14 @@ func (s *processSupervisor) ReqQueueSize() int64 {
 	return s.reqQueueSize.Load()
 }
 
-func (s *processSupervisor) ActiveTasksCount() int64 {
-	return s.activeTasks.Load()
-}
-
 func (s *processSupervisor) RestartsCount() int64 {
 	return s.restartsCounter.Load()
 }
 
+func (s *processSupervisor) ActiveTasksCount() int64 {
+	return s.activeTasks.Load()
+}
+
 // Interface guards.
 var (
 	_ ProcessSupervisor = (*processSupervisor)(nil)

pkg/gotenberg/supervisor_test.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"log/slog"
-	"os"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -38,7 +37,7 @@ func TestProcessSupervisor_Launch(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			process := &ProcessMock{
 				StartMock: func(logger *slog.Logger) error {
@@ -46,7 +45,7 @@ func TestProcessSupervisor_Launch(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, 5, 0, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(logger, process, 5, 0, 1, 0).(*processSupervisor)
 			if tc.firstStartSet {
 				ps.firstStart.Store(true)
 			}
@@ -86,7 +85,7 @@ func TestProcessSupervisor_Shutdown(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			process := &ProcessMock{
 				StopMock: func(logger *slog.Logger) error {
@@ -94,7 +93,7 @@ func TestProcessSupervisor_Shutdown(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, 5, 0, 1)
+			ps := NewProcessSupervisor(logger, process, 5, 0, 1, 0)
 			err := ps.Shutdown()
 
 			if !tc.expectError && err != nil {
@@ -135,7 +134,7 @@ func TestProcessSupervisor_restart(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			process := &ProcessMock{
 				StartMock: func(logger *slog.Logger) error {
@@ -146,7 +145,7 @@ func TestProcessSupervisor_restart(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, 5, 0, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(logger, process, 5, 0, 1, 0).(*processSupervisor)
 
 			err := ps.restart()
 
@@ -170,15 +169,15 @@ func TestProcessSupervisor_Healthy(t *testing.T) {
 		expectHealthy       bool
 	}{
 		{
-			scenario:         "non-started process is always healthy",
+			scenario:         "non-started process is healthy",
 			initiallyStarted: false,
 			expectHealthy:    true,
 		},
 		{
-			scenario:            "restarting process is always healthy",
+			scenario:            "restarting process is not healthy",
 			initiallyStarted:    true,
 			initiallyRestarting: true,
-			expectHealthy:       true,
+			expectHealthy:       false,
 		},
 		{
 			scenario:         "process reports as healthy",
@@ -194,7 +193,7 @@ func TestProcessSupervisor_Healthy(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			process := &ProcessMock{
 				HealthyMock: func(logger *slog.Logger) bool {
@@ -202,7 +201,7 @@ func TestProcessSupervisor_Healthy(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, 5, 0, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(logger, process, 5, 0, 1, 0).(*processSupervisor)
 			if tc.initiallyStarted {
 				ps.firstStart.Store(true)
 			}
@@ -365,7 +364,7 @@ func TestProcessSupervisor_Run(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			var startCalls, healthyCalls, stopCalls atomic.Int64
 			startCalls.Store(0)
@@ -387,7 +386,7 @@ func TestProcessSupervisor_Run(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, tc.maxReqLimit, tc.maxQueueSize, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(logger, process, tc.maxReqLimit, tc.maxQueueSize, 1, 0).(*processSupervisor)
 			if tc.initiallyStarted {
 				ps.firstStart.Store(true)
 			}
@@ -471,7 +470,7 @@ func TestProcessSupervisor_runWithDeadline(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			ps := NewProcessSupervisor(slog.New(slog.NewJSONHandler(os.Stdout, nil)), new(ProcessMock), 0, 0, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(slog.New(slog.DiscardHandler), new(ProcessMock), 0, 0, 1, 0).(*processSupervisor)
 
 			ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
 			if tc.ctxDone {
@@ -496,7 +495,7 @@ func TestProcessSupervisor_runWithDeadline(t *testing.T) {
 }
 
 func TestProcessSupervisor_ReqQueueSize(t *testing.T) {
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	logger := slog.New(slog.DiscardHandler)
 	process := &ProcessMock{
 		StartMock: func(logger *slog.Logger) error {
 			return nil
@@ -505,7 +504,7 @@ func TestProcessSupervisor_ReqQueueSize(t *testing.T) {
 			return true
 		},
 	}
-	ps := NewProcessSupervisor(logger, process, 0, 0, 1).(*processSupervisor)
+	ps := NewProcessSupervisor(logger, process, 0, 0, 1, 0).(*processSupervisor)
 
 	// Simulating a lock.
 	ps.semaphore <- struct{}{}
@@ -552,6 +551,111 @@ func TestProcessSupervisor_ReqQueueSize(t *testing.T) {
 	}
 }
 
+func TestProcessSupervisor_QueueSizeCAS(t *testing.T) {
+	logger := slog.New(slog.DiscardHandler)
+
+	process := &ProcessMock{
+		StartMock: func(logger *slog.Logger) error {
+			return nil
+		},
+		HealthyMock: func(logger *slog.Logger) bool {
+			return true
+		},
+	}
+
+	maxQueueSize := int64(50)
+	// maxConcurrency=1 so all goroutines block on the semaphore, exercising queue logic.
+	ps := NewProcessSupervisor(logger, process, 0, maxQueueSize, 1, 0).(*processSupervisor)
+
+	// Simulating a lock so that all goroutines queue up.
+	ps.semaphore <- struct{}{}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	goroutines := 100
+	var wg sync.WaitGroup
+	var exceeded atomic.Int64
+
+	for range goroutines {
+		wg.Go(func() {
+			err := ps.Run(ctx, logger, func() error {
+				return nil
+			})
+			if err != nil {
+				if errors.Is(err, ErrMaximumQueueSizeExceeded) {
+					exceeded.Add(1)
+				}
+			}
+		})
+	}
+
+	// Wait a bit for goroutines to queue up.
+	time.Sleep(50 * time.Millisecond)
+
+	currentQueue := ps.ReqQueueSize()
+	if currentQueue > maxQueueSize {
+		t.Fatalf("queue size %d exceeded max %d", currentQueue, maxQueueSize)
+	}
+
+	cancel()
+	wg.Wait()
+
+	if exceeded.Load() < int64(goroutines)-maxQueueSize {
+		t.Errorf("expected at least %d rejections, got %d", goroutines-int(maxQueueSize), exceeded.Load())
+	}
+}
+
+func TestProcessSupervisor_QueueSizeIncludesActiveTasks(t *testing.T) {
+	logger := slog.New(slog.DiscardHandler)
+
+	process := &ProcessMock{
+		StartMock: func(logger *slog.Logger) error {
+			return nil
+		},
+		HealthyMock: func(logger *slog.Logger) bool {
+			return true
+		},
+	}
+
+	// maxQueueSize=1, maxConcurrency=1: only one request at a time.
+	ps := NewProcessSupervisor(logger, process, 0, 1, 1, 0)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	taskStarted := make(chan struct{})
+	taskDone := make(chan struct{})
+
+	// Start a long-running task that holds the slot.
+	var wg sync.WaitGroup
+	wg.Go(func() {
+		err := ps.Run(ctx, logger, func() error {
+			close(taskStarted)
+			<-taskDone
+			return nil
+		})
+		if err != nil {
+			t.Errorf("first task: unexpected error: %v", err)
+		}
+	})
+
+	// Wait for the first task to be running.
+	<-taskStarted
+
+	// A second request should be rejected immediately because the queue
+	// slot is still held by the active task.
+	err := ps.Run(ctx, logger, func() error {
+		return nil
+	})
+	if !errors.Is(err, ErrMaximumQueueSizeExceeded) {
+		t.Fatalf("expected ErrMaximumQueueSizeExceeded but got: %v", err)
+	}
+
+	close(taskDone)
+	wg.Wait()
+}
+
 func TestProcessSupervisor_RestartsCount(t *testing.T) {
 	for _, tc := range []struct {
 		scenario              string
@@ -593,7 +697,7 @@ func TestProcessSupervisor_RestartsCount(t *testing.T) {
 		},
 	} {
 		t.Run(tc.scenario, func(t *testing.T) {
-			logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+			logger := slog.New(slog.DiscardHandler)
 
 			process := &ProcessMock{
 				StartMock: func(logger *slog.Logger) error {
@@ -604,7 +708,7 @@ func TestProcessSupervisor_RestartsCount(t *testing.T) {
 				},
 			}
 
-			ps := NewProcessSupervisor(logger, process, 0, 0, 1).(*processSupervisor)
+			ps := NewProcessSupervisor(logger, process, 0, 0, 1, 0).(*processSupervisor)
 			ps.restartsCounter.Store(tc.initialRestartsCount)
 
 			for i := 0; i < tc.restartAttempts; i++ {
@@ -620,7 +724,7 @@ func TestProcessSupervisor_RestartsCount(t *testing.T) {
 }
 
 func TestProcessSupervisor_ConcurrentRun(t *testing.T) {
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	logger := slog.New(slog.DiscardHandler)
 
 	var startCalls atomic.Int64
 	process := &ProcessMock{
@@ -637,7 +741,7 @@ func TestProcessSupervisor_ConcurrentRun(t *testing.T) {
 	}
 
 	maxConcurrency := int64(3)
-	ps := NewProcessSupervisor(logger, process, 0, 0, maxConcurrency).(*processSupervisor)
+	ps := NewProcessSupervisor(logger, process, 0, 0, maxConcurrency, 0).(*processSupervisor)
 
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
@@ -684,7 +788,7 @@ func TestProcessSupervisor_ConcurrentRun(t *testing.T) {
 }
 
 func TestProcessSupervisor_RestartDrainsAllSlots(t *testing.T) {
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	logger := slog.New(slog.DiscardHandler)
 
 	process := &ProcessMock{
 		StartMock: func(logger *slog.Logger) error {
@@ -699,7 +803,7 @@ func TestProcessSupervisor_RestartDrainsAllSlots(t *testing.T) {
 	}
 
 	maxConcurrency := int64(3)
-	ps := NewProcessSupervisor(logger, process, 3, 0, maxConcurrency).(*processSupervisor)
+	ps := NewProcessSupervisor(logger, process, 3, 0, maxConcurrency, 0).(*processSupervisor)
 	ps.firstStart.Store(true)
 
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -737,3 +841,103 @@ func TestProcessSupervisor_RestartDrainsAllSlots(t *testing.T) {
 		t.Fatalf("expected 1 restart, got %d", ps.RestartsCount())
 	}
 }
+
+func TestProcessSupervisor_IdleShutdown(t *testing.T) {
+	logger := slog.New(slog.DiscardHandler)
+
+	var stopCalls atomic.Int64
+	process := &ProcessMock{
+		StartMock: func(logger *slog.Logger) error {
+			return nil
+		},
+		StopMock: func(logger *slog.Logger) error {
+			stopCalls.Add(1)
+			return nil
+		},
+		HealthyMock: func(logger *slog.Logger) bool {
+			return true
+		},
+	}
+
+	idleTimeout := 50 * time.Millisecond
+	ps := NewProcessSupervisor(logger, process, 0, 0, 1, idleTimeout).(*processSupervisor)
+
+	ctx := context.Background()
+	err := ps.Run(ctx, logger, func() error {
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Wait for idle shutdown to fire.
+	deadline := time.After(2 * time.Second)
+	for ps.firstStart.Load() {
+		select {
+		case <-deadline:
+			t.Fatal("timed out waiting for idle shutdown")
+		default:
+			time.Sleep(10 * time.Millisecond)
+		}
+	}
+
+	if stopCalls.Load() < 1 {
+		t.Fatal("expected process to be stopped via idle shutdown")
+	}
+
+	// Verify re-launch on next request.
+	err = ps.Run(ctx, logger, func() error {
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("unexpected error on re-launch: %v", err)
+	}
+
+	if !ps.firstStart.Load() {
+		t.Fatal("expected process to be re-launched after idle shutdown")
+	}
+}
+
+func TestProcessSupervisor_IdleShutdownSkippedWhenActive(t *testing.T) {
+	logger := slog.New(slog.DiscardHandler)
+
+	var stopCalls atomic.Int64
+	taskRunning := make(chan struct{})
+	taskDone := make(chan struct{})
+
+	process := &ProcessMock{
+		StartMock: func(logger *slog.Logger) error {
+			return nil
+		},
+		StopMock: func(logger *slog.Logger) error {
+			stopCalls.Add(1)
+			return nil
+		},
+		HealthyMock: func(logger *slog.Logger) bool {
+			return true
+		},
+	}
+
+	idleTimeout := 50 * time.Millisecond
+	ps := NewProcessSupervisor(logger, process, 0, 0, 1, idleTimeout)
+
+	ctx := context.Background()
+	go func() {
+		_ = ps.Run(ctx, logger, func() error {
+			close(taskRunning)
+			<-taskDone
+			return nil
+		})
+	}()
+
+	<-taskRunning
+
+	// Wait longer than the idle timeout while a task is active.
+	time.Sleep(idleTimeout * 3)
+
+	if stopCalls.Load() > 0 {
+		t.Fatal("idle shutdown should not fire while a task is active")
+	}
+
+	close(taskDone)
+}

pkg/gotenberg/telemetry.go

@@ -11,7 +11,6 @@ import (
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/trace"
-	"go.uber.org/multierr"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg/internal/log"
 	internalotel "github.com/gotenberg/gotenberg/v8/pkg/gotenberg/internal/otel"
@@ -55,13 +54,13 @@ func (cfg TelemetryConfig) Validate() error {
 	var err error
 
 	if cfg.ServiceName == "" {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("service name must not be empty"),
 		)
 	}
 
 	if cfg.ServiceVersion == "" {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("service version must not be empty"),
 		)
 	}
@@ -70,7 +69,7 @@ func (cfg TelemetryConfig) Validate() error {
 	case ErrorLoggingLevel, WarnLoggingLevel, InfoLoggingLevel, DebugLoggingLevel:
 		break
 	default:
-		err = multierr.Append(
+		err = errors.Join(
 			err,
 			fmt.Errorf("log level must be either %s, %s, %s or %s", ErrorLoggingLevel, WarnLoggingLevel, InfoLoggingLevel, DebugLoggingLevel),
 		)
@@ -80,7 +79,7 @@ func (cfg TelemetryConfig) Validate() error {
 	case AutoLoggingFormat, JsonLoggingFormat, TextLoggingFormat:
 		break
 	default:
-		err = multierr.Append(
+		err = errors.Join(
 			err,
 			fmt.Errorf("standard log format must be either %s, %s or %s", AutoLoggingFormat, JsonLoggingFormat, TextLoggingFormat),
 		)

pkg/modules/api/api.go

@@ -7,7 +7,6 @@ import (
 	"log/slog"
 	"net"
 	"net/http"
-	"os"
 	"sort"
 	"strings"
 	"time"
@@ -16,7 +15,6 @@ import (
 	"github.com/dlclark/regexp2"
 	"github.com/labstack/echo/v4"
 	flag "github.com/spf13/pflag"
-	"go.uber.org/multierr"
 	"golang.org/x/net/http2"
 	"golang.org/x/sync/errgroup"
 
@@ -28,7 +26,7 @@ func init() {
 }
 
 // Api is a module that provides an HTTP server. Other modules may add routes,
-// middlewares, or health checks.
+// middlewares or health checks.
 type Api struct {
 	port                             int
 	bindIp                           string
@@ -38,14 +36,14 @@ type Api struct {
 	bodyLimit                        int64
 	timeout                          time.Duration
 	rootPath                         string
+	correlationIdHeader              string
 	basicAuthUsername                string
 	basicAuthPassword                string
-	correlationIdHeader              string
 	downloadFromCfg                  downloadFromConfig
 	disableHealthCheckRouteTelemetry bool
 	disableRootRouteTelemetry        bool
-	disableVersionRouteTelemetry     bool
 	disableDebugRouteTelemetry       bool
+	disableVersionRouteTelemetry     bool
 	enableDebugRoute                 bool
 
 	routes              []Route
@@ -59,8 +57,8 @@ type Api struct {
 }
 
 type downloadFromConfig struct {
-	allowList *regexp2.Regexp
-	denyList  *regexp2.Regexp
+	allowList []*regexp2.Regexp
+	denyList  []*regexp2.Regexp
 	maxRetry  int
 	disable   bool
 }
@@ -84,7 +82,8 @@ type Route struct {
 	// Optional.
 	IsMultipart bool
 
-	// DisableTelemetry disables the telemetry and logging for this route.
+	// DisableTelemetry disables telemetry (logging, tracing, metrics) for
+	// this route.
 	// Optional.
 	DisableTelemetry bool
 
@@ -122,6 +121,29 @@ const (
 
 // Middleware is a middleware that 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 {
 	// Stack tells in which stack the middleware should be located.
 	// Default to [DefaultStack].
@@ -171,18 +193,29 @@ func (a *Api) Descriptor() gotenberg.ModuleDescriptor {
 			fs.Duration("api-timeout", time.Duration(30)*time.Second, "Set the time limit for requests")
 			fs.String("api-body-limit", "", "Set the body limit for multipart/form-data requests - it accepts values like 5MB, 1GB, etc")
 			fs.String("api-root-path", "/", "Set the root path of the API - for service discovery via URL paths")
+			fs.String("api-correlation-id-header", "Gotenberg-Trace", "Set the header name to use for identifying requests")
 			fs.Bool("api-enable-basic-auth", false, "Enable basic authentication - will look for the GOTENBERG_API_BASIC_AUTH_USERNAME and GOTENBERG_API_BASIC_AUTH_PASSWORD environment variables")
-			fs.String("api-correlation-id-header", "X-Correlation-ID", "Set the header name to use to set the correlation id in the logs")
-			fs.String("api-download-from-allow-list", "", "Set the allowed URLs for the download from feature using a regular expression")
-			fs.String("api-download-from-deny-list", "", "Set the denied URLs for the download from feature using a regular expression")
+			fs.StringSlice("api-download-from-allow-list", []string{}, "Set the allowed URLs for the download from feature using regular expressions - supports multiple values")
+			fs.StringSlice("api-download-from-deny-list", []string{}, "Set the denied URLs for the download from feature using regular expressions - supports multiple values")
 			fs.Int("api-download-from-max-retry", 4, "Set the maximum number of retries for the download from feature")
 			fs.Bool("api-disable-download-from", false, "Disable the download from feature")
-			fs.Bool("api-disable-health-check-route-telemetry", false, "Disable the health check route telemetry")
-			fs.Bool("api-disable-root-route-telemetry", false, "Disable the root route telemetry")
-			fs.Bool("api-disable-version-route-telemetry", false, "Disable the version route telemetry")
-			fs.Bool("api-disable-debug-route-telemetry", false, "Disable the debug route telemetry")
+			fs.Bool("api-disable-health-check-route-telemetry", true, "Disable telemetry for health check route")
+			fs.Bool("api-disable-root-route-telemetry", true, "Disable telemetry for the root route")
+			fs.Bool("api-disable-debug-route-telemetry", true, "Disable telemetry for the debug route")
+			fs.Bool("api-disable-version-route-telemetry", true, "Disable telemetry for the version route")
 			fs.Bool("api-enable-debug-route", false, "Enable the debug route")
 
+			// Deprecated flags.
+			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")
+
+			err := errors.Join(
+				fs.MarkDeprecated("api-trace-header", "use --api-correlation-id-header instead"),
+				fs.MarkDeprecated("api-disable-health-check-logging", "use --api-disable-health-check-route-telemetry instead"),
+			)
+			if err != nil {
+				panic(err)
+			}
 			return fs
 		}(),
 		New: func() gotenberg.Module { return new(Api) },
@@ -200,17 +233,17 @@ func (a *Api) Provision(ctx *gotenberg.Context) error {
 	a.timeout = flags.MustDuration("api-timeout")
 	a.bodyLimit = flags.MustHumanReadableBytes("api-body-limit")
 	a.rootPath = flags.MustString("api-root-path")
-	a.correlationIdHeader = flags.MustString("api-correlation-id-header")
+	a.correlationIdHeader = flags.MustDeprecatedString("api-trace-header", "api-correlation-id-header")
 	a.downloadFromCfg = downloadFromConfig{
-		allowList: flags.MustRegexp("api-download-from-allow-list"),
-		denyList:  flags.MustRegexp("api-download-from-deny-list"),
+		allowList: flags.MustRegexpSlice("api-download-from-allow-list"),
+		denyList:  flags.MustRegexpSlice("api-download-from-deny-list"),
 		maxRetry:  flags.MustInt("api-download-from-max-retry"),
 		disable:   flags.MustBool("api-disable-download-from"),
 	}
-	a.disableHealthCheckRouteTelemetry = flags.MustBool("api-disable-health-check-route-telemetry")
+	a.disableHealthCheckRouteTelemetry = flags.MustDeprecatedBool("api-disable-health-check-logging", "api-disable-health-check-route-telemetry")
 	a.disableRootRouteTelemetry = flags.MustBool("api-disable-root-route-telemetry")
-	a.disableVersionRouteTelemetry = flags.MustBool("api-disable-version-route-telemetry")
 	a.disableDebugRouteTelemetry = flags.MustBool("api-disable-debug-route-telemetry")
+	a.disableVersionRouteTelemetry = flags.MustBool("api-disable-version-route-telemetry")
 	a.enableDebugRoute = flags.MustBool("api-enable-debug-route")
 
 	// Port from env?
@@ -329,33 +362,39 @@ func (a *Api) Validate() error {
 	var err error
 
 	if a.port < 1 || a.port > 65535 {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("port must be more than 1 and less than 65535"),
 		)
 	}
 
 	if a.bindIp != "" && net.ParseIP(a.bindIp) == nil {
-		err = multierr.Append(err, errors.New("IP must be a valid IP address"))
+		err = errors.Join(err, errors.New("IP must be a valid IP address"))
 	}
 
 	if (a.tlsCertFile != "" && a.tlsKeyFile == "") || (a.tlsCertFile == "" && a.tlsKeyFile != "") {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("both TLS certificate and key files must be set"),
 		)
 	}
 
 	if !strings.HasPrefix(a.rootPath, "/") {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("root path must start with /"),
 		)
 	}
 
 	if !strings.HasSuffix(a.rootPath, "/") {
-		err = multierr.Append(err,
+		err = errors.Join(err,
 			errors.New("root path must end with /"),
 		)
 	}
 
+	if len(strings.TrimSpace(a.correlationIdHeader)) == 0 {
+		err = errors.Join(err,
+			errors.New("trace header must not be empty"),
+		)
+	}
+
 	if err != nil {
 		return err
 	}
@@ -422,40 +461,29 @@ func (a *Api) Start() error {
 			disableTelemetryForPaths = append(disableTelemetryForPaths, strings.TrimPrefix(route.Path, "/"))
 		}
 	}
-	// Check if the user wishes to disable telemetry for system routes.
-	// Note: root path will be used as prefix in the underlying middlewares.
+
+	// Check if the user wishes to disable telemetry for specific routes.
 	if a.disableHealthCheckRouteTelemetry {
 		disableTelemetryForPaths = append(disableTelemetryForPaths, "health")
 	}
-
 	if a.disableRootRouteTelemetry {
 		disableTelemetryForPaths = append(disableTelemetryForPaths, "")
 	}
-
+	if a.disableDebugRouteTelemetry {
+		disableTelemetryForPaths = append(disableTelemetryForPaths, "debug")
+	}
 	if a.disableVersionRouteTelemetry {
 		disableTelemetryForPaths = append(disableTelemetryForPaths, "version")
 	}
 
-	if a.disableDebugRouteTelemetry {
-		disableTelemetryForPaths = append(disableTelemetryForPaths, "debug")
-	}
-
-	// Always disable telemetry for favicon.
-	disableTelemetryForPaths = append(disableTelemetryForPaths,
-		"favicon.ico",
-	)
+	serverName := fmt.Sprintf("%s:%d", a.bindIp, a.port)
 
 	// Add the API middlewares.
-	hostname, err := os.Hostname()
-	if err != nil {
-		return fmt.Errorf("get hostname: %w", err)
-	}
-
 	a.srv.Pre(
 		latencyMiddleware(),
 		rootPathMiddleware(a.rootPath),
 		outputFilenameMiddleware(),
-		telemetryMiddleware(a.logger, hostname, a.correlationIdHeader, disableTelemetryForPaths),
+		telemetryMiddleware(a.logger, serverName, a.correlationIdHeader, disableTelemetryForPaths),
 	)
 
 	// Add the modules' middlewares in their respective stacks.
@@ -527,7 +555,9 @@ func (a *Api) Start() error {
 	)
 
 	// Let's not forget the health check routes...
-	checks := append(a.healthChecks, health.WithTimeout(a.timeout))
+	checks := make([]health.CheckerOption, len(a.healthChecks), len(a.healthChecks)+1)
+	copy(checks, a.healthChecks)
+	checks = append(checks, health.WithTimeout(a.timeout))
 	checker := health.NewChecker(checks...)
 	healthCheckHandler := health.NewHandler(checker)
 
@@ -575,7 +605,7 @@ func (a *Api) Start() error {
 		eg.Go(f)
 	}
 
-	err = eg.Wait()
+	err := eg.Wait()
 	if err != nil {
 		return fmt.Errorf("waiting for modules readiness: %w", err)
 	}
@@ -593,7 +623,6 @@ func (a *Api) Start() error {
 		}
 		if !errors.Is(err, http.ErrServerClosed) {
 			a.logger.ErrorContext(context.Background(), err.Error())
-			os.Exit(1)
 		}
 	}()
 

pkg/modules/api/context.go

@@ -21,13 +21,14 @@ import (
 	"github.com/labstack/echo/v4"
 	"github.com/mholt/archives"
 	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/propagation"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/text/unicode/norm"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
-	semconvutil "github.com/gotenberg/gotenberg/v8/pkg/gotenberg/semconv"
 )
 
 var (
@@ -42,12 +43,13 @@ var (
 
 // Context is the request context for a "multipart/form-data" request.
 type Context struct {
-	dirPath      string
-	values       map[string][]string
-	files        map[string]string
-	filesByField map[string][]string
-	outputPaths  []string
-	cancelled    bool
+	dirPath        string
+	values         map[string][]string
+	files          map[string]string
+	filesByField   map[string][]string
+	diskToOriginal map[string]string
+	outputPaths    []string
+	cancelled      bool
 
 	logger     *slog.Logger
 	echoCtx    echo.Context
@@ -85,8 +87,14 @@ type downloadFrom struct {
 	// ExtraHttpHeaders are the HTTP headers to send alongside.
 	ExtraHttpHeaders map[string]string `json:"extraHttpHeaders"`
 
-	// Download as an attachment file.
-	Attachment bool `json:"attachment"`
+	// Embedded routes the downloaded file as an embed. Deprecated: use
+	// Field instead. Kept for backward compatibility.
+	Embedded bool `json:"embedded"`
+
+	// Field routes the downloaded file to a specific form field bucket.
+	// Supported values: "watermark", "stamp". For embeds, prefer the
+	// Embedded flag or set Field to "embedded".
+	Field string `json:"field"`
 }
 
 // newContext returns a [Context] by parsing a "multipart/form-data" request.
@@ -135,12 +143,12 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 
 			err := os.RemoveAll(ctx.dirPath)
 			if err != nil {
-				ctx.logger.ErrorContext(ctx, fmt.Sprintf("remove context's working directory: %s", err))
+				ctx.logger.ErrorContext(context.Background(), fmt.Sprintf("remove context's working directory: %s", err))
 
 				return
 			}
 
-			ctx.logger.DebugContext(ctx, fmt.Sprintf("'%s' context's working directory removed", ctx.dirPath))
+			ctx.logger.DebugContext(context.Background(), fmt.Sprintf("'%s' context's working directory removed", ctx.dirPath))
 			ctx.cancelled = true
 		}
 	}()
@@ -193,6 +201,7 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 	ctx.values = form.Value
 	ctx.files = make(map[string]string)
 	ctx.filesByField = make(map[string][]string)
+	ctx.diskToOriginal = make(map[string]string)
 
 	// First, try to download files listed in the "downloadFrom" form field, if
 	// any.
@@ -228,10 +237,18 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 					return fmt.Errorf("filter URL: %w", err)
 				}
 
-				logger.DebugContext(ctx, fmt.Sprintf("download file from '%s'", dl.Url))
+				dlCtx, dlSpan := gotenberg.Tracer().Start(ctx, "GET Download From",
+					trace.WithSpanKind(trace.SpanKindClient),
+					trace.WithAttributes(semconv.ServerAddress(dl.Url)),
+				)
 
-				req, err := retryablehttp.NewRequestWithContext(ctx, http.MethodGet, dl.Url, nil)
+				logger.DebugContext(dlCtx, fmt.Sprintf("download file from '%s'", dl.Url))
+
+				req, err := retryablehttp.NewRequest(http.MethodGet, dl.Url, nil)
 				if err != nil {
+					dlSpan.RecordError(err)
+					dlSpan.SetStatus(codes.Error, err.Error())
+					dlSpan.End()
 					return fmt.Errorf("create request to '%s': %w", dl.Url, err)
 				}
 
@@ -239,20 +256,16 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 				for key, value := range dl.ExtraHttpHeaders {
 					req.Header.Set(key, value)
 				}
-				req.Header.Set(echoCtx.Get("correlationIdHeader").(string), echoCtx.Get("correlationId").(string))
 
-				// OpenTelemetry.
-				meter := gotenberg.Meter()
-				semconvClient := semconvutil.NewHTTPClient(meter)
+				// Inject OTEL trace context into outbound request.
+				otel.GetTextMapPropagator().Inject(dlCtx, propagation.HeaderCarrier(req.Header))
 
-				tracer := gotenberg.Tracer()
-				traceCtx, span := tracer.Start(ctx, fmt.Sprintf("%s Download From", req.Method),
-					trace.WithSpanKind(trace.SpanKindClient),
-					trace.WithAttributes(semconvClient.RequestTraceAttrs(req.Request)...),
-				)
-				defer span.End()
-
-				otel.GetTextMapPropagator().Inject(traceCtx, propagation.HeaderCarrier(req.Header))
+				// Propagate correlation ID header.
+				if correlationIdHeader, ok := echoCtx.Get("correlationIdHeader").(string); ok {
+					if correlationId, ok := echoCtx.Get("correlationId").(string); ok {
+						req.Header.Set(correlationIdHeader, correlationId)
+					}
+				}
 
 				client := &retryablehttp.Client{
 					HTTPClient: &http.Client{
@@ -261,23 +274,21 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 					RetryMax:     downloadFromCfg.maxRetry,
 					RetryWaitMin: time.Duration(1) * time.Second,
 					RetryWaitMax: time.Until(deadline),
-					Logger:       gotenberg.NewLeveledLogger(logger).WithContext(ctx),
+					Logger:       gotenberg.NewLeveledLogger(logger),
 					CheckRetry:   retryablehttp.DefaultRetryPolicy,
 					Backoff:      retryablehttp.DefaultBackoff,
 				}
 
 				resp, err := client.Do(req)
 				if err != nil {
-					span.RecordError(err)
-					span.SetStatus(semconvClient.Status(0))
+					dlSpan.RecordError(err)
+					dlSpan.SetStatus(codes.Error, err.Error())
+					dlSpan.End()
 					return WrapError(
 						fmt.Errorf("download file from to '%s': %w", dl.Url, err),
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Unable to download file from '%s': %s", dl.Url, err)),
 					)
 				}
-
-				span.SetAttributes(semconvClient.ResponseTraceAttrs(resp)...)
-				span.SetStatus(semconvClient.Status(resp.StatusCode))
 				defer func() {
 					err := resp.Body.Close()
 					if err != nil {
@@ -286,16 +297,24 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 				}()
 
 				if resp.StatusCode != http.StatusOK {
+					dlErr := fmt.Errorf("download file from to '%s': got status: '%s'", dl.Url, resp.Status)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
 					return WrapError(
-						fmt.Errorf("download file from to '%s': got status: '%s'", dl.Url, resp.Status),
+						dlErr,
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Unable to download file from '%s': got status: '%s'", dl.Url, resp.Status)),
 					)
 				}
 
 				contentDisposition := resp.Header.Get("Content-Disposition")
 				if contentDisposition == "" {
+					dlErr := fmt.Errorf("no 'Content-Disposition' header from '%s'", dl.Url)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
 					return WrapError(
-						fmt.Errorf("no 'Content-Disposition' header from '%s'", dl.Url),
+						dlErr,
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("No 'Content-Disposition' header from '%s'", dl.Url)),
 					)
 				}
@@ -305,16 +324,24 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 				//  See: https://github.com/golang/go/issues/69551.
 				_, params, err := mime.ParseMediaType(contentDisposition)
 				if err != nil {
+					dlErr := fmt.Errorf("parse 'Content-Disposition' header '%s' from '%s': %w", contentDisposition, dl.Url, err)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
 					return WrapError(
-						fmt.Errorf("parse 'Content-Disposition' header '%s' from '%s': %w", contentDisposition, dl.Url, err),
+						dlErr,
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Invalid 'Content-Disposition' header '%s' from '%s': %s", contentDisposition, dl.Url, err)),
 					)
 				}
 
 				filename, ok := params["filename"]
 				if !ok {
+					dlErr := fmt.Errorf("get filename from 'Content-Disposition' header '%s' from '%s'", contentDisposition, dl.Url)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
 					return WrapError(
-						fmt.Errorf("get filename from 'Content-Disposition' header '%s' from '%s'", contentDisposition, dl.Url),
+						dlErr,
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Invalid 'Content-Disposition' header '%s' from '%s': no filename", contentDisposition, dl.Url)),
 					)
 				}
@@ -323,11 +350,20 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 				// normalized.
 				// See: https://github.com/gotenberg/gotenberg/issues/662.
 				filename = norm.NFC.String(filepath.Base(filename))
-				path := fmt.Sprintf("%s/%s", dirPath, filename)
+
+				// Use a UUID-based name on disk to avoid filesystem
+				// NAME_MAX limits with long filenames.
+				// See: https://github.com/gotenberg/gotenberg/issues/1500.
+				safeName := uuid.New().String() + filepath.Ext(filename)
+				path := fmt.Sprintf("%s/%s", ctx.dirPath, safeName)
 
 				out, err := os.Create(path)
 				if err != nil {
-					return fmt.Errorf("create local file: %w", err)
+					dlErr := fmt.Errorf("create local file: %w", err)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
+					return dlErr
 				}
 				defer func() {
 					err := out.Close()
@@ -341,12 +377,27 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 
 				_, err = io.Copy(out, reader)
 				if err != nil {
-					return fmt.Errorf("copy downloaded file from '%s' to local file: %w", dl.Url, err)
+					dlErr := fmt.Errorf("copy downloaded file from '%s' to local file: %w", dl.Url, err)
+					dlSpan.RecordError(dlErr)
+					dlSpan.SetStatus(codes.Error, dlErr.Error())
+					dlSpan.End()
+					return dlErr
 				}
 
+				dlSpan.SetStatus(codes.Ok, "")
+				dlSpan.End()
+
 				ctx.files[filename] = path
-				if dl.Attachment {
-					ctx.filesByField[AttachmentsFormField] = append(ctx.filesByField[AttachmentsFormField], path)
+				ctx.diskToOriginal[path] = filename
+
+				// Route the downloaded file to the appropriate field bucket.
+				switch {
+				case dl.Field == "embedded" || dl.Embedded:
+					ctx.filesByField[EmbedsFormField] = append(ctx.filesByField[EmbedsFormField], path)
+				case dl.Field == "watermark":
+					ctx.filesByField[WatermarkFormField] = append(ctx.filesByField[WatermarkFormField], path)
+				case dl.Field == "stamp":
+					ctx.filesByField[StampFormField] = append(ctx.filesByField[StampFormField], path)
 				}
 
 				return nil
@@ -368,7 +419,7 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		defer func() {
 			err := in.Close()
 			if err != nil {
-				logger.ErrorContext(ctx, fmt.Sprintf("close file header: %s", err))
+				logger.ErrorContext(context.Background(), fmt.Sprintf("close file header: %s", err))
 			}
 		}()
 
@@ -379,7 +430,12 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		// normalized.
 		// See: https://github.com/gotenberg/gotenberg/issues/662.
 		filename := norm.NFC.String(filepath.Base(fh.Filename))
-		path := fmt.Sprintf("%s/%s", ctx.dirPath, filename)
+
+		// Use a UUID-based name on disk to avoid filesystem
+		// NAME_MAX limits with long filenames.
+		// See: https://github.com/gotenberg/gotenberg/issues/1500.
+		safeName := uuid.New().String() + filepath.Ext(filename)
+		path := fmt.Sprintf("%s/%s", ctx.dirPath, safeName)
 
 		out, err := os.Create(path)
 		if err != nil {
@@ -388,7 +444,7 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		defer func() {
 			err := out.Close()
 			if err != nil {
-				logger.ErrorContext(ctx, fmt.Sprintf("close local file: %s", err))
+				logger.ErrorContext(context.Background(), fmt.Sprintf("close local file: %s", err))
 			}
 		}()
 
@@ -398,6 +454,7 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		}
 
 		ctx.files[filename] = path
+		ctx.diskToOriginal[path] = filename
 
 		return nil
 	}
@@ -416,6 +473,23 @@ func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSys
 		}
 	}
 
+	// Create symlinks from original filenames to UUID-based disk names
+	// so that relative asset references (e.g., <img src="image.png">)
+	// resolve correctly when Chromium navigates to a file:// URL.
+	// Symlink creation is best-effort: it may fail for filenames that
+	// exceed the filesystem NAME_MAX limit (the reason UUIDs were
+	// introduced in the first place).
+	for originalName, diskPath := range ctx.files {
+		symlinkPath := fmt.Sprintf("%s/%s", ctx.dirPath, originalName)
+		if symlinkPath == diskPath {
+			continue
+		}
+		err = os.Symlink(filepath.Base(diskPath), symlinkPath)
+		if err != nil {
+			logger.DebugContext(context.Background(), fmt.Sprintf("skip symlink for '%s': %s", originalName, err))
+		}
+	}
+
 	ctx.Log().DebugContext(ctx, fmt.Sprintf("form fields: %+v", ctx.values))
 	ctx.Log().DebugContext(ctx, fmt.Sprintf("form files: %+v", ctx.files))
 	ctx.Log().DebugContext(ctx, fmt.Sprintf("form files by field: %+v", ctx.filesByField))
@@ -432,13 +506,34 @@ func (ctx *Context) Request() *http.Request {
 // FormData return a [FormData].
 func (ctx *Context) FormData() *FormData {
 	return &FormData{
-		values:       ctx.values,
-		files:        ctx.files,
-		filesByField: ctx.filesByField,
-		errors:       nil,
+		values:         ctx.values,
+		files:          ctx.files,
+		filesByField:   ctx.filesByField,
+		diskToOriginal: ctx.diskToOriginal,
+		errors:         nil,
 	}
 }
 
+// OriginalFilename returns the original filename associated with a disk path.
+// If no mapping exists, it falls back to [filepath.Base].
+func (ctx *Context) OriginalFilename(diskPath string) string {
+	if original, ok := ctx.diskToOriginal[diskPath]; ok {
+		return original
+	}
+	return filepath.Base(diskPath)
+}
+
+// RegisterDiskPath associates a disk path with an original filename so that
+// [Context.OriginalFilename] can resolve it later.
+func (ctx *Context) RegisterDiskPath(diskPath, originalFilename string) {
+	ctx.diskToOriginal[diskPath] = originalFilename
+}
+
+// DirPath returns the path to the request's working directory.
+func (ctx *Context) DirPath() string {
+	return ctx.dirPath
+}
+
 // GeneratePath generates a path within the context's working directory.
 // It generates a new UUID-based filename. It does not create a file.
 func (ctx *Context) GeneratePath(extension string) string {
@@ -446,10 +541,14 @@ func (ctx *Context) GeneratePath(extension string) string {
 }
 
 // GeneratePathFromFilename generates a path within the context's working
-// directory, using the given filename (with extension). It does not create
-// a file.
+// directory. It uses a UUID-based name on disk to avoid filesystem NAME_MAX
+// limits but registers the given filename so that [Context.OriginalFilename]
+// can resolve it. It does not create a file.
 func (ctx *Context) GeneratePathFromFilename(filename string) string {
-	return fmt.Sprintf("%s/%s", ctx.dirPath, filename)
+	safeName := uuid.New().String() + filepath.Ext(filename)
+	path := fmt.Sprintf("%s/%s", ctx.dirPath, safeName)
+	ctx.diskToOriginal[path] = filename
+	return path
 }
 
 // CreateSubDirectory creates a subdirectory within the context's working
@@ -516,7 +615,7 @@ func (ctx *Context) BuildOutputFile() (string, error) {
 	filesInfo, err := archives.FilesFromDisk(ctx.Context, nil, func() map[string]string {
 		f := make(map[string]string)
 		for _, outputPath := range ctx.outputPaths {
-			f[outputPath] = ""
+			f[outputPath] = ctx.OriginalFilename(outputPath)
 		}
 		return f
 	}())
@@ -552,7 +651,7 @@ func (ctx *Context) OutputFilename(outputPath string) string {
 	filename := ctx.echoCtx.Get("outputFilename").(string)
 
 	if filename == "" {
-		return filepath.Base(outputPath)
+		return ctx.OriginalFilename(outputPath)
 	}
 
 	return fmt.Sprintf("%s%s", filename, filepath.Ext(outputPath))

pkg/modules/api/context_test.go

@@ -7,7 +7,6 @@ import (
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
-	"os"
 	"testing"
 	"time"
 
@@ -36,7 +35,7 @@ func TestNewContext_Cancellation(t *testing.T) {
 	rec := httptest.NewRecorder()
 	c := e.NewContext(req, rec)
 
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	logger := slog.New(slog.DiscardHandler)
 	fs := gotenberg.NewFileSystem(new(gotenberg.OsMkdirAll))
 	timeout := time.Duration(10) * time.Second
 	downloadFromCfg := downloadFromConfig{

pkg/modules/api/formdata.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"errors"
 	"fmt"
 	"math"
 	"net/http"
@@ -12,14 +13,18 @@ import (
 	"strings"
 	"time"
 
-	"go.uber.org/multierr"
-
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
 
-// AttachmentsFormField represents the form field name for attaching files.
 const (
-	AttachmentsFormField string = "attachments"
+	// EmbedsFormField represents the form field name for embedding files.
+	EmbedsFormField string = "embeds"
+
+	// WatermarkFormField represents the form field name for the watermark file.
+	WatermarkFormField string = "watermark"
+
+	// StampFormField represents the form field name for the stamp file.
+	StampFormField string = "stamp"
 )
 
 // FormData is a helper for validating and hydrating values from a
@@ -27,10 +32,11 @@ const (
 //
 //	form := ctx.FormData()
 type FormData struct {
-	values       map[string][]string
-	files        map[string]string
-	filesByField map[string][]string
-	errors       error
+	values         map[string][]string
+	files          map[string]string
+	filesByField   map[string][]string
+	diskToOriginal map[string]string
+	errors         error
 }
 
 // Validate returns nil or an error related to the [FormData] values, with a
@@ -365,20 +371,20 @@ func (form *FormData) Paths(extensions []string, target *[]string) *FormData {
 	return form.paths(extensions, target)
 }
 
-// Attachments binds the absolute paths of form data files that should be
-// attached in the PDF. Only files uploaded with the "attachments" field name
+// Embeds binds the absolute paths of form data files that should be
+// embedded in the PDF. Only files uploaded with the "embeds" field name
 // will be included.
 //
-//	var attachments []string
+//	var embeds []string
 //
-//	ctx.FormData().Attachments(&attachments)
-func (form *FormData) Attachments(target *[]string) *FormData {
+//	ctx.FormData().Embeds(&embeds)
+func (form *FormData) Embeds(target *[]string) *FormData {
 	if form.errors != nil {
 		return form
 	}
 
-	// Get files from the "attachments" field
-	if paths, ok := form.filesByField[AttachmentsFormField]; ok {
+	// Get files from the "embeds" field
+	if paths, ok := form.filesByField[EmbedsFormField]; ok {
 		*target = append(*target, paths...)
 	}
 
@@ -406,34 +412,96 @@ func (form *FormData) MandatoryPaths(extensions []string, target *[]string) *For
 	return form
 }
 
+// Watermark binds the absolute path of the form data file that should be
+// used as a watermark source. Only a file uploaded with the "watermark"
+// field name will be included.
+func (form *FormData) Watermark(target *string) *FormData {
+	if form.errors != nil {
+		return form
+	}
+
+	if paths, ok := form.filesByField[WatermarkFormField]; ok && len(paths) > 0 {
+		*target = paths[0]
+	}
+
+	return form
+}
+
+// Stamp binds the absolute path of the form data file that should be
+// used as a stamp source. Only a file uploaded with the "stamp"
+// field name will be included.
+func (form *FormData) Stamp(target *string) *FormData {
+	if form.errors != nil {
+		return form
+	}
+
+	if paths, ok := form.filesByField[StampFormField]; ok && len(paths) > 0 {
+		*target = paths[0]
+	}
+
+	return form
+}
+
 // paths bind the absolute paths of form data files, according to a list of
 // file extensions, to a string slice variable.
-// attachments are excluded.
+// embeds, watermark, and stamp files are excluded.
 func (form *FormData) paths(extensions []string, target *[]string) *FormData {
-	attachments, ok := form.filesByField[AttachmentsFormField]
+	embeds, ok := form.filesByField[EmbedsFormField]
+	watermarks, wmOk := form.filesByField[WatermarkFormField]
+	stamps, stOk := form.filesByField[StampFormField]
+
+	// Collect (originalFilename, diskPath) pairs so that we can sort by
+	// original filename rather than by UUID-based disk name.
+	// See https://github.com/gotenberg/gotenberg/issues/1500.
+	type entry struct {
+		original string
+		disk     string
+	}
+	var entries []entry
 
 	for filename, path := range form.files {
-		if ok && slices.Contains(attachments, path) {
+		if ok && slices.Contains(embeds, path) {
+			continue
+		}
+
+		if wmOk && slices.Contains(watermarks, path) {
+			continue
+		}
+
+		if stOk && slices.Contains(stamps, path) {
 			continue
 		}
 
 		for _, ext := range extensions {
 			// See https://github.com/gotenberg/gotenberg/issues/228.
 			if strings.ToLower(filepath.Ext(filename)) == ext {
-				*target = append(*target, path)
+				entries = append(entries, entry{original: filename, disk: path})
 			}
 		}
 	}
 
 	// See https://github.com/gotenberg/gotenberg/issues/139.
-	sort.Sort(gotenberg.AlphanumericSort(*target))
+	originals := make(gotenberg.AlphanumericSort, len(entries))
+	for i, e := range entries {
+		originals[i] = e.original
+	}
+	sort.Sort(originals)
+
+	// Build a lookup from original name to disk path.
+	lookup := make(map[string]string, len(entries))
+	for _, e := range entries {
+		lookup[e.original] = e.disk
+	}
+	for _, o := range originals {
+		*target = append(*target, lookup[o])
+	}
 
 	return form
 }
 
 // append adds an error to the list of errors.
 func (form *FormData) append(err error) {
-	form.errors = multierr.Append(form.errors, err)
+	form.errors = errors.Join(form.errors, err)
 }
 
 // mustValue binds the target interface with a form field. If the value is

pkg/modules/api/formdata_test.go

@@ -1613,15 +1613,15 @@ func TestFormData_Paths(t *testing.T) {
 			expectCount: 2,
 		},
 		{
-			scenario: "files except attachments",
+			scenario: "files except embeds",
 			form: &FormData{
 				files: map[string]string{
-					"foo.pdf":           "/foo.pdf",
-					"attachments_1.pdf": "/attachments_1.pdf",
-					"attachments_2.xml": "/attachments_2.xml",
+					"foo.pdf":     "/foo.pdf",
+					"embed_1.pdf": "/embed_1.pdf",
+					"embed_2.xml": "/embed_2.xml",
 				},
 				filesByField: map[string][]string{
-					"attachments": {"/attachments_1.pdf", "/attachments_2.xml"},
+					"embeds": {"/embed_1.pdf", "/embed_2.xml"},
 				},
 			},
 			extensions: []string{".pdf"},
@@ -1759,7 +1759,7 @@ func TestFormData_mustAssign(t *testing.T) {
 	form.mustAssign("foo", "foo", &target)
 }
 
-func TestFormData_Attachments(t *testing.T) {
+func TestFormData_Embeds(t *testing.T) {
 	expected := []string{"/bar.xml", "/baz.xml"}
 
 	var actual []string
@@ -1770,13 +1770,13 @@ func TestFormData_Attachments(t *testing.T) {
 			"baz.xml": "/baz.xml",
 		},
 		filesByField: map[string][]string{
-			"attachments": {"/bar.xml", "/baz.xml"},
+			"embeds": {"/bar.xml", "/baz.xml"},
 		},
 	}
-	form.Attachments(&actual)
+	form.Embeds(&actual)
 
 	if len(actual) != len(expected) {
-		t.Errorf("expected %d attachments but got %d", len(expected), len(actual))
+		t.Errorf("expected %d embeds but got %d", len(expected), len(actual))
 	}
 
 	if !reflect.DeepEqual(actual, expected) {

pkg/modules/api/middlewares.go

@@ -5,7 +5,6 @@ import (
 	"crypto/subtle"
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/http"
 	"path/filepath"
@@ -67,8 +66,15 @@ func ParseError(err error) (int, string) {
 		return http.StatusBadRequest, "At least one PDF engine cannot process the requested metadata, while others may have failed to convert due to different issues"
 	}
 
-	var invalidArgsError *gotenberg.PdfEngineInvalidArgsError
-	if errors.As(err, &invalidArgsError) {
+	if errors.Is(err, gotenberg.ErrPdfStampSourceNotSupported) {
+		return http.StatusBadRequest, "At least one PDF engine cannot process the requested stamp source type, while others may have failed due to different issues"
+	}
+
+	if errors.Is(err, gotenberg.ErrPdfRotateAngleNotSupported) {
+		return http.StatusBadRequest, "At least one PDF engine cannot process the requested rotation angle, while others may have failed due to different issues"
+	}
+
+	if invalidArgsError, ok := errors.AsType[*gotenberg.PdfEngineInvalidArgsError](err); ok {
 		return http.StatusBadRequest, invalidArgsError.Error()
 	}
 
@@ -197,7 +203,7 @@ func telemetryMiddleware(logger *slog.Logger, serverName, correlationIdHeader st
 			}
 
 			if skipTelemetry {
-				c.Set("logger", slog.New(slog.NewJSONHandler(io.Discard, nil)))
+				c.Set("logger", slog.New(slog.DiscardHandler))
 
 				err := next(c)
 				if err != nil {

pkg/modules/api/mocks.go

@@ -74,7 +74,7 @@ func (ctx *ContextMock) OutputPaths() []string {
 // SetLogger sets the logger.
 //
 //	ctx := &api.ContextMock{Context: &api.Context{}}
-//	ctx.SetLogger(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
+//	ctx.SetLogger(slog.Default())
 func (ctx *ContextMock) SetLogger(logger *slog.Logger) {
 	ctx.logger = logger
 }

pkg/modules/chromium/browser.go

@@ -19,10 +19,6 @@ import (
 	"github.com/chromedp/chromedp"
 	"github.com/dlclark/regexp2"
 	"github.com/shirou/gopsutil/v4/process"
-	"go.opentelemetry.io/otel/attribute"
-	"go.opentelemetry.io/otel/codes"
-	semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
-	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
@@ -46,8 +42,8 @@ type browserArguments struct {
 	hyphenDataDirPath        string
 
 	// Tasks specific.
-	allowList         *regexp2.Regexp
-	denyList          *regexp2.Regexp
+	allowList         []*regexp2.Regexp
+	denyList          []*regexp2.Regexp
 	clearCache        bool
 	clearCookies      bool
 	disableJavaScript bool
@@ -81,10 +77,7 @@ func (b *chromiumBrowser) Start(logger *slog.Logger) error {
 		return errors.New("browser is already started")
 	}
 
-	debug := &debugLogger{
-		ctx:    b.initialCtx,
-		logger: logger,
-	}
+	debug := &debugLogger{logger: logger}
 	b.userProfileDirPath = b.fs.NewDirPath()
 
 	// See https://github.com/gotenberg/gotenberg/issues/1293.
@@ -206,9 +199,9 @@ func (b *chromiumBrowser) Stop(logger *slog.Logger) error {
 
 					err = p.KillWithContext(killCtx)
 					if err != nil {
-						logger.ErrorContext(killCtx, fmt.Sprintf("kill process: %v", err))
+						logger.ErrorContext(context.Background(), fmt.Sprintf("kill process: %v", err))
 					} else {
-						logger.DebugContext(killCtx, fmt.Sprintf("Chromium process %d killed", p.Pid))
+						logger.DebugContext(context.Background(), fmt.Sprintf("Chromium process %d killed", p.Pid))
 					}
 				}()
 			}
@@ -273,7 +266,7 @@ func (b *chromiumBrowser) Healthy(logger *slog.Logger) bool {
 		return err
 	}))
 	if err != nil {
-		logger.ErrorContext(ctx, fmt.Sprintf("browser health check failed: %s", err))
+		logger.ErrorContext(context.Background(), fmt.Sprintf("browser health check failed: %s", err))
 		return false
 	}
 
@@ -363,9 +356,10 @@ func (b *chromiumBrowser) do(ctx context.Context, logger *slog.Logger, url strin
 	// the extra HTTP headers, if any.
 	// See https://github.com/gotenberg/gotenberg/issues/1011.
 	listenForEventRequestPaused(taskCtx, logger, eventRequestPausedOptions{
-		allowList:        b.arguments.allowList,
-		denyList:         b.arguments.denyList,
-		extraHttpHeaders: options.ExtraHttpHeaders,
+		allowList:           b.arguments.allowList,
+		denyList:            b.arguments.denyList,
+		allowedFilePrefixes: options.AllowedFilePrefixes,
+		extraHttpHeaders:    options.ExtraHttpHeaders,
 	})
 
 	var (
@@ -388,6 +382,7 @@ func (b *chromiumBrowser) do(ctx context.Context, logger *slog.Logger, url strin
 			ignoreResourceHttpStatusDomains: options.IgnoreResourceHttpStatusDomains,
 			invalidResourceHttpStatusCode:   &invalidResourceHttpStatusCode,
 			invalidResourceHttpStatusCodeMu: &invalidResourceHttpStatusCodeMu,
+			cancelOnMainPageError:           taskCancel,
 		})
 	}
 
@@ -417,30 +412,45 @@ func (b *chromiumBrowser) do(ctx context.Context, logger *slog.Logger, url strin
 		loadingFailedMu:         &loadingFailedMu,
 		resourceLoadingFailed:   &resourceLoadingFailed,
 		resourceLoadingFailedMu: &resourceLoadingFailedMu,
+		cancelOnMainPageError:   taskCancel,
 	})
 
-	clientCtx, clientSpan := gotenberg.Tracer().Start(taskCtx, "cdp.execute",
-		trace.WithSpanKind(trace.SpanKindClient),
-		trace.WithAttributes(
-			semconv.ServerAddress("127.0.0.1"),
-			semconv.ServicePeerName("chromium"),
-			semconv.RPCSystemNameKey.String("cdp"),
-			// Legacy attribute for older APMs (Datadog, Jaeger) to draw the
-			// dependency graph.
-			attribute.String("peer.service", "chromium"),
-		),
-	)
+	runErr := chromedp.Run(taskCtx, tasks...)
 
-	err = chromedp.Run(clientCtx, tasks...)
-	if err != nil {
-		clientSpan.RecordError(err)
-		clientSpan.SetStatus(codes.Error, err.Error())
+	// Check event-driven errors first — they take priority over chromedp.Run
+	// errors because they carry the actual root cause (e.g., HTTP 500 from
+	// the main page). When we cancel taskCtx on a main page error,
+	// chromedp.Run returns a context error that is less informative.
+	// See https://github.com/gotenberg/gotenberg/issues/1492.
+
+	// See https://github.com/gotenberg/gotenberg/issues/613.
+	invalidHttpStatusCodeMu.RLock()
+	defer invalidHttpStatusCodeMu.RUnlock()
+
+	if invalidHttpStatusCode != nil {
+		return fmt.Errorf("%v: %w", invalidHttpStatusCode, ErrInvalidHttpStatusCode)
 	}
 
-	clientSpan.End()
+	// See https://github.com/gotenberg/gotenberg/issues/1021.
+	invalidResourceHttpStatusCodeMu.RLock()
+	defer invalidResourceHttpStatusCodeMu.RUnlock()
 
-	if err != nil {
-		errMessage := err.Error()
+	if invalidResourceHttpStatusCode != nil {
+		return fmt.Errorf("%v: %w", invalidResourceHttpStatusCode, ErrInvalidResourceHttpStatusCode)
+	}
+
+	// See:
+	// https://github.com/gotenberg/gotenberg/issues/913.
+	// https://github.com/gotenberg/gotenberg/issues/959.
+	loadingFailedMu.RLock()
+	defer loadingFailedMu.RUnlock()
+
+	if loadingFailed != nil {
+		return fmt.Errorf("%v: %w", loadingFailed, ErrLoadingFailed)
+	}
+
+	if runErr != nil {
+		errMessage := runErr.Error()
 
 		if strings.Contains(errMessage, "Printing failed (-32000)") {
 			return ErrPrintingFailed
@@ -462,23 +472,7 @@ func (b *chromiumBrowser) do(ctx context.Context, logger *slog.Logger, url strin
 			return ErrRpccMessageTooLarge
 		}
 
-		return fmt.Errorf("handle tasks: %w", err)
-	}
-
-	// See https://github.com/gotenberg/gotenberg/issues/613.
-	invalidHttpStatusCodeMu.RLock()
-	defer invalidHttpStatusCodeMu.RUnlock()
-
-	if invalidHttpStatusCode != nil {
-		return fmt.Errorf("%v: %w", invalidHttpStatusCode, ErrInvalidHttpStatusCode)
-	}
-
-	// See https://github.com/gotenberg/gotenberg/issues/1021.
-	invalidResourceHttpStatusCodeMu.RLock()
-	defer invalidResourceHttpStatusCodeMu.RUnlock()
-
-	if invalidResourceHttpStatusCode != nil {
-		return fmt.Errorf("%v: %w", invalidResourceHttpStatusCode, ErrInvalidResourceHttpStatusCode)
+		return fmt.Errorf("handle tasks: %w", runErr)
 	}
 
 	// See https://github.com/gotenberg/gotenberg/issues/262.
@@ -489,16 +483,6 @@ func (b *chromiumBrowser) do(ctx context.Context, logger *slog.Logger, url strin
 		return fmt.Errorf("%v: %w", consoleExceptions, ErrConsoleExceptions)
 	}
 
-	// See:
-	// https://github.com/gotenberg/gotenberg/issues/913.
-	// https://github.com/gotenberg/gotenberg/issues/959.
-	loadingFailedMu.RLock()
-	defer loadingFailedMu.RUnlock()
-
-	if loadingFailed != nil {
-		return fmt.Errorf("%v: %w", loadingFailed, ErrLoadingFailed)
-	}
-
 	// See https://github.com/gotenberg/gotenberg/issues/1021.
 	if options.FailOnResourceLoadingFailed {
 		if resourceLoadingFailed != nil {

pkg/modules/chromium/chromium.go

@@ -18,6 +18,8 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/metric"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
+	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 	"github.com/gotenberg/gotenberg/v8/pkg/modules/api"
@@ -186,6 +188,12 @@ type Options struct {
 	// OmitBackground hides the default white background and allows generating
 	// PDFs with transparency.
 	OmitBackground bool
+
+	// AllowedFilePrefixes restricts file:// sub-resource access to only these
+	// directory prefixes. Applied in listenForEventRequestPaused in addition
+	// to the global allow/deny lists. Set internally by route handlers, not
+	// via form data.
+	AllowedFilePrefixes []string
 }
 
 // EmulatedMediaFeature gathers the available entries for emulating a media
@@ -283,7 +291,7 @@ type PdfOptions struct {
 	PreferCssPageSize bool
 
 	// GenerateDocumentOutline defines whether the document outline should be
-	// attached into the PDF.
+	// embedded into the PDF.
 	GenerateDocumentOutline bool
 
 	// GenerateTaggedPdf defines whether to generate tagged (accessible)
@@ -427,6 +435,7 @@ func (mod *Chromium) Descriptor() gotenberg.ModuleDescriptor {
 			fs := flag.NewFlagSet("chromium", flag.ExitOnError)
 			fs.Int64("chromium-restart-after", 100, "Number of conversions after which Chromium will automatically restart. Set to 0 to disable this feature")
 			fs.Int64("chromium-max-queue-size", 0, "Maximum request queue size for Chromium. Set to 0 to disable this feature")
+			fs.Duration("chromium-idle-shutdown-timeout", 0, "Shutdown Chromium after being idle for the given duration. Set to 0 to disable this feature")
 			fs.Int64("chromium-max-concurrency", 6, "Maximum number of concurrent conversions. Chromium supports up to 6")
 			fs.Bool("chromium-auto-start", false, "Automatically launch Chromium upon initialization if set to true; otherwise, Chromium will start at the time of the first conversion")
 			fs.Duration("chromium-start-timeout", time.Duration(20)*time.Second, "Maximum duration to wait for Chromium to start or restart")
@@ -436,13 +445,20 @@ func (mod *Chromium) Descriptor() gotenberg.ModuleDescriptor {
 			fs.Bool("chromium-allow-file-access-from-files", false, "Allow file:// URIs to read other file:// URIs")
 			fs.String("chromium-host-resolver-rules", "", "Set custom mappings to the host resolver")
 			fs.String("chromium-proxy-server", "", "Set the outbound proxy server; this switch only affects HTTP and HTTPS requests")
-			fs.String("chromium-allow-list", "", "Set the allowed URLs for Chromium using a regular expression")
-			fs.String("chromium-deny-list", `^file:(?!//\/tmp/).*`, "Set the denied URLs for Chromium using a regular expression")
+			fs.StringSlice("chromium-allow-list", []string{}, "Set the allowed URLs for Chromium using regular expressions - supports multiple values")
+			fs.StringSlice("chromium-deny-list", []string{`^file:(?!//\/tmp/).*`}, "Set the denied URLs for Chromium using regular expressions - supports multiple values")
 			fs.Bool("chromium-clear-cache", false, "Clear Chromium cache between each conversion")
 			fs.Bool("chromium-clear-cookies", false, "Clear Chromium cookies between each conversion")
 			fs.Bool("chromium-disable-javascript", false, "Disable JavaScript")
 			fs.Bool("chromium-disable-routes", false, "Disable the routes")
 
+			// Deprecated flags.
+			fs.Bool("chromium-incognito", false, "Start Chromium with incognito mode")
+			err := fs.MarkDeprecated("chromium-incognito", "this flag is ignored as it provides no benefits")
+			if err != nil {
+				panic(err)
+			}
+
 			return fs
 		}(),
 		New: func() gotenberg.Module { return new(Chromium) },
@@ -477,8 +493,8 @@ func (mod *Chromium) Provision(ctx *gotenberg.Context) error {
 		wsUrlReadTimeout:         flags.MustDuration("chromium-start-timeout"),
 		hyphenDataDirPath:        hyphenDataDirPath,
 
-		allowList:         flags.MustRegexp("chromium-allow-list"),
-		denyList:          flags.MustRegexp("chromium-deny-list"),
+		allowList:         flags.MustRegexpSlice("chromium-allow-list"),
+		denyList:          flags.MustRegexpSlice("chromium-deny-list"),
 		clearCache:        flags.MustBool("chromium-clear-cache"),
 		clearCookies:      flags.MustBool("chromium-clear-cookies"),
 		disableJavaScript: flags.MustBool("chromium-disable-javascript"),
@@ -489,7 +505,7 @@ func (mod *Chromium) Provision(ctx *gotenberg.Context) error {
 
 	// Process.
 	mod.browser = newChromiumBrowser(mod.args)
-	mod.supervisor = gotenberg.NewProcessSupervisor(mod.logger, mod.browser, flags.MustInt64("chromium-restart-after"), flags.MustInt64("chromium-max-queue-size"), mod.maxConcurrency)
+	mod.supervisor = gotenberg.NewProcessSupervisor(mod.logger, mod.browser, flags.MustInt64("chromium-restart-after"), flags.MustInt64("chromium-max-queue-size"), mod.maxConcurrency, flags.MustDuration("chromium-idle-shutdown-timeout"))
 
 	// PDF Engine.
 	provider, err := ctx.Module(new(gotenberg.PdfEngineProvider))
@@ -502,104 +518,107 @@ func (mod *Chromium) Provision(ctx *gotenberg.Context) error {
 	}
 	mod.engine = engine
 
-	// OpenTelemetry.
+	// Metrics.
 	meter := gotenberg.Meter()
-	_, err = meter.Int64ObservableCounter(
-		"chromium.process.restarts.total",
-		metric.WithDescription("Current number of Chromium restarts."),
-		metric.WithUnit("{restart}"),
+
+	// Observable gauges.
+	_, err = meter.Int64ObservableGauge(
+		"chromium.requests.active",
+		metric.WithDescription("Current number of active Chromium requests"),
+		metric.WithUnit("{request}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := mod.supervisor.RestartsCount()
-			o.Observe(val)
+			o.Observe(mod.supervisor.ActiveTasksCount())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create process restarts observable counter: %w", err)
+		return fmt.Errorf("create chromium.requests.active gauge: %w", err)
 	}
 
 	_, err = meter.Int64ObservableGauge(
 		"chromium.requests.queue_size",
-		metric.WithDescription("Current number of Chromium conversion requests waiting to be treated."),
+		metric.WithDescription("Current number of Chromium conversion requests waiting to be treated"),
 		metric.WithUnit("{request}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := mod.supervisor.ReqQueueSize()
-			o.Observe(val)
+			o.Observe(mod.supervisor.ReqQueueSize())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests queue size observable gauge: %w", err)
+		return fmt.Errorf("create chromium.requests.queue_size gauge: %w", err)
 	}
 
-	_, err = meter.Int64ObservableGauge(
-		"chromium.requests.active",
-		metric.WithDescription("Current number of Chromium conversion requests actively being processed."),
-		metric.WithUnit("{request}"),
+	_, err = meter.Int64ObservableCounter(
+		"chromium.process.restarts.total",
+		metric.WithDescription("Current number of Chromium restarts"),
+		metric.WithUnit("{restart}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := mod.supervisor.ActiveTasksCount()
-			o.Observe(val)
+			o.Observe(mod.supervisor.RestartsCount())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests active observable gauge: %w", err)
+		return fmt.Errorf("create chromium.process.restarts.total counter: %w", err)
 	}
 
+	// Counters.
 	mod.reqsCounter, err = meter.Int64Counter(
 		"chromium.requests.total",
-		metric.WithDescription("Total number of Chromium conversion requests."),
+		metric.WithDescription("Total number of Chromium conversion requests"),
 		metric.WithUnit("{request}"),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests total counter: %w", err)
+		return fmt.Errorf("create chromium.requests.total counter: %w", err)
 	}
 
 	mod.errsCounter, err = meter.Int64Counter(
 		"chromium.errors.total",
-		metric.WithDescription("Total number of Chromium errors."),
+		metric.WithDescription("Total number of Chromium conversion errors"),
 		metric.WithUnit("{error}"),
 	)
 	if err != nil {
-		return fmt.Errorf("create errors total counter: %w", err)
+		return fmt.Errorf("create chromium.errors.total counter: %w", err)
 	}
 
+	// Histograms.
+	durationBuckets := metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60)
+
 	mod.conversionDurationCounter, err = meter.Float64Histogram(
 		"chromium.conversion.duration",
-		metric.WithDescription("Duration of each HTML-to-PDF conversion."),
+		metric.WithDescription("Duration of Chromium conversions"),
 		metric.WithUnit("s"),
-		metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60),
+		durationBuckets,
 	)
 	if err != nil {
-		return fmt.Errorf("create conversion duration histogram: %w", err)
+		return fmt.Errorf("create chromium.conversion.duration histogram: %w", err)
 	}
 
 	mod.queueWaitDurationCounter, err = meter.Float64Histogram(
 		"chromium.queue.wait.duration",
-		metric.WithDescription("Time a request spends waiting in the queue before processing starts."),
+		metric.WithDescription("Duration of waiting in queue for Chromium conversions"),
 		metric.WithUnit("s"),
-		metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60),
+		durationBuckets,
 	)
 	if err != nil {
-		return fmt.Errorf("create queue wait duration histogram: %w", err)
+		return fmt.Errorf("create chromium.queue.wait.duration histogram: %w", err)
 	}
 
 	mod.pdfOutputSizeCounter, err = meter.Int64Histogram(
 		"chromium.pdf.output.size",
-		metric.WithDescription("Size of the generated PDF files."),
+		metric.WithDescription("Size of PDF output from Chromium conversions"),
 		metric.WithUnit("By"),
 	)
 	if err != nil {
-		return fmt.Errorf("create pdf output size histogram: %w", err)
+		return fmt.Errorf("create chromium.pdf.output.size histogram: %w", err)
 	}
 
 	mod.imageOutputSizeCounter, err = meter.Int64Histogram(
 		"chromium.image.output.size",
-		metric.WithDescription("Size of the generated image files."),
+		metric.WithDescription("Size of image output from Chromium screenshots"),
 		metric.WithUnit("By"),
 	)
 	if err != nil {
-		return fmt.Errorf("create image output size histogram: %w", err)
+		return fmt.Errorf("create chromium.image.output.size histogram: %w", err)
 	}
 
 	return nil
@@ -681,6 +700,26 @@ func (mod *Chromium) Debug() map[string]any {
 	return debug
 }
 
+// Metrics returns the metrics.
+func (mod *Chromium) Metrics() ([]gotenberg.Metric, error) {
+	return []gotenberg.Metric{
+		{
+			Name:        "chromium_requests_queue_size",
+			Description: "Current number of Chromium conversion requests waiting to be treated.",
+			Read: func() float64 {
+				return float64(mod.supervisor.ReqQueueSize())
+			},
+		},
+		{
+			Name:        "chromium_restarts_count",
+			Description: "Current number of Chromium restarts.",
+			Read: func() float64 {
+				return float64(mod.supervisor.RestartsCount())
+			},
+		},
+	}, nil
+}
+
 // Checks adds a health check that verifies if Chromium is healthy.
 func (mod *Chromium) Checks() ([]health.CheckerOption, error) {
 	return []health.CheckerOption{
@@ -749,9 +788,10 @@ func (mod *Chromium) Routes() ([]api.Route, error) {
 
 // Pdf converts a URL to PDF.
 func (mod *Chromium) Pdf(ctx context.Context, logger *slog.Logger, url, outputPath string, options PdfOptions) error {
-	// Note: no error wrapping because it leaks on errors we want to display to
-	// the end user.
-	ctx, span := gotenberg.Tracer().Start(ctx, "Chromium.Pdf")
+	ctx, span := gotenberg.Tracer().Start(ctx, "chromium.Pdf",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(mod.args.binPath)),
+	)
 	defer span.End()
 
 	start := time.Now()
@@ -772,17 +812,15 @@ func (mod *Chromium) Pdf(ctx context.Context, logger *slog.Logger, url, outputPa
 			status = "error"
 		}
 
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-
 		reason := "unknown"
-		if errors.Is(err, context.DeadlineExceeded) {
+		switch {
+		case errors.Is(err, context.DeadlineExceeded):
 			reason = "timeout"
-		} else if errors.Is(err, context.Canceled) {
+		case errors.Is(err, context.Canceled):
 			reason = "context_cancelled"
-		} else if errors.Is(err, ErrInvalidHttpStatusCode) || errors.Is(err, ErrInvalidResourceHttpStatusCode) || errors.Is(err, ErrLoadingFailed) || errors.Is(err, ErrResourceLoadingFailed) || errors.Is(err, ErrInvalidEvaluationExpression) || errors.Is(err, ErrInvalidSelectorQuery) {
+		case errors.Is(err, ErrInvalidHttpStatusCode) || errors.Is(err, ErrInvalidResourceHttpStatusCode) || errors.Is(err, ErrLoadingFailed) || errors.Is(err, ErrResourceLoadingFailed) || errors.Is(err, ErrInvalidEvaluationExpression) || errors.Is(err, ErrInvalidSelectorQuery):
 			reason = "invalid_input"
-		} else if errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) || errors.Is(err, gotenberg.ErrProcessAlreadyRestarting) {
+		case errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) || errors.Is(err, gotenberg.ErrProcessAlreadyRestarting):
 			reason = "chromium_unavailable"
 		}
 
@@ -816,15 +854,21 @@ func (mod *Chromium) Pdf(ctx context.Context, logger *slog.Logger, url, outputPa
 		if fileInfo, statErr := os.Stat(outputPath); statErr == nil {
 			mod.pdfOutputSizeCounter.Record(ctx, fileInfo.Size())
 		}
+
+		span.SetStatus(codes.Ok, "")
+		return nil
 	}
 
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 func (mod *Chromium) Screenshot(ctx context.Context, logger *slog.Logger, url, outputPath string, options ScreenshotOptions) error {
-	// Note: no error wrapping because it leaks on errors we want to display to
-	// the end user.
-	ctx, span := gotenberg.Tracer().Start(ctx, "Chromium.Screenshot")
+	ctx, span := gotenberg.Tracer().Start(ctx, "chromium.Screenshot",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(mod.args.binPath)),
+	)
 	defer span.End()
 
 	start := time.Now()
@@ -845,19 +889,17 @@ func (mod *Chromium) Screenshot(ctx context.Context, logger *slog.Logger, url, o
 			status = "error"
 		}
 
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-
 		reason := "unknown"
-		if errors.Is(err, context.DeadlineExceeded) {
+		switch {
+		case errors.Is(err, context.DeadlineExceeded):
 			reason = "timeout"
-		} else if errors.Is(err, context.Canceled) {
+		case errors.Is(err, context.Canceled):
 			reason = "context_cancelled"
-		} else if errors.Is(err, ErrInvalidHttpStatusCode) || errors.Is(err, ErrInvalidResourceHttpStatusCode) || errors.Is(err, ErrLoadingFailed) || errors.Is(err, ErrResourceLoadingFailed) || errors.Is(err, ErrInvalidEvaluationExpression) || errors.Is(err, ErrInvalidSelectorQuery) {
+		case errors.Is(err, ErrInvalidHttpStatusCode) || errors.Is(err, ErrInvalidResourceHttpStatusCode) || errors.Is(err, ErrLoadingFailed) || errors.Is(err, ErrResourceLoadingFailed) || errors.Is(err, ErrInvalidEvaluationExpression) || errors.Is(err, ErrInvalidSelectorQuery):
 			reason = "invalid_input"
-		} else if errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) {
+		case errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded):
 			reason = "chromium_maximum_queue_size_exceeded"
-		} else if errors.Is(err, gotenberg.ErrProcessAlreadyRestarting) {
+		case errors.Is(err, gotenberg.ErrProcessAlreadyRestarting):
 			reason = "chromium_unavailable"
 		}
 
@@ -891,20 +933,26 @@ func (mod *Chromium) Screenshot(ctx context.Context, logger *slog.Logger, url, o
 		if fileInfo, statErr := os.Stat(outputPath); statErr == nil {
 			mod.imageOutputSizeCounter.Record(ctx, fileInfo.Size())
 		}
+
+		span.SetStatus(codes.Ok, "")
+		return nil
 	}
 
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Interface guards.
 var (
-	_ gotenberg.Module      = (*Chromium)(nil)
-	_ gotenberg.Provisioner = (*Chromium)(nil)
-	_ gotenberg.Validator   = (*Chromium)(nil)
-	_ gotenberg.App         = (*Chromium)(nil)
-	_ gotenberg.Debuggable  = (*Chromium)(nil)
-	_ api.HealthChecker     = (*Chromium)(nil)
-	_ api.Router            = (*Chromium)(nil)
-	_ Api                   = (*Chromium)(nil)
-	_ Provider              = (*Chromium)(nil)
+	_ gotenberg.Module          = (*Chromium)(nil)
+	_ gotenberg.Provisioner     = (*Chromium)(nil)
+	_ gotenberg.Validator       = (*Chromium)(nil)
+	_ gotenberg.App             = (*Chromium)(nil)
+	_ gotenberg.Debuggable      = (*Chromium)(nil)
+	_ gotenberg.MetricsProvider = (*Chromium)(nil)
+	_ api.HealthChecker         = (*Chromium)(nil)
+	_ api.Router                = (*Chromium)(nil)
+	_ Api                       = (*Chromium)(nil)
+	_ Provider                  = (*Chromium)(nil)
 )

pkg/modules/chromium/debug.go

@@ -10,20 +10,19 @@ import (
 // debugLogger is wrapper around a [slog.Logger] which is used for debugging
 // Chromium.
 type debugLogger struct {
-	ctx    context.Context
 	logger *slog.Logger
 }
 
 // Write logs the bytes in a debug message.
 func (debug *debugLogger) Write(p []byte) (n int, err error) {
-	debug.logger.DebugContext(debug.ctx, string(p))
+	debug.logger.DebugContext(context.Background(), string(p))
 
 	return len(p), nil
 }
 
 // Printf logs a debug message.
 func (debug *debugLogger) Printf(format string, v ...any) {
-	debug.logger.DebugContext(debug.ctx, fmt.Sprintf(format, v...))
+	debug.logger.DebugContext(context.Background(), fmt.Sprintf(format, v...))
 }
 
 // Interface guards.

pkg/modules/chromium/events.go

@@ -2,6 +2,7 @@ package chromium
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
@@ -17,14 +18,14 @@ import (
 	"github.com/chromedp/cdproto/runtime"
 	"github.com/chromedp/chromedp"
 	"github.com/dlclark/regexp2"
-	"go.uber.org/multierr"
 	"golang.org/x/sync/errgroup"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
 
 type eventRequestPausedOptions struct {
-	allowList, denyList *regexp2.Regexp
+	allowList, denyList []*regexp2.Regexp
+	allowedFilePrefixes []string
 	extraHttpHeaders    []ExtraHttpHeader
 }
 
@@ -40,8 +41,7 @@ func listenForEventRequestPaused(ctx context.Context, logger *slog.Logger, optio
 	}
 
 	chromedp.ListenTarget(ctx, func(ev any) {
-		switch e := ev.(type) {
-		case *fetch.EventRequestPaused:
+		if e, ok := ev.(*fetch.EventRequestPaused); ok {
 			go func() {
 				logger.DebugContext(ctx, fmt.Sprintf("event EventRequestPaused fired for '%s'", e.Request.URL))
 				allow := true
@@ -58,6 +58,25 @@ func listenForEventRequestPaused(ctx context.Context, logger *slog.Logger, optio
 					allow = false
 				}
 
+				// Additional restriction: if the sub-resource is a file:// URL
+				// and we have allowed file prefixes, restrict access to only
+				// those directories. This prevents cross-request file access
+				// in /tmp.
+				if allow && strings.HasPrefix(e.Request.URL, "file://") && len(options.allowedFilePrefixes) > 0 {
+					prefixMatch := false
+					for _, prefix := range options.allowedFilePrefixes {
+						if strings.HasPrefix(e.Request.URL, "file://"+prefix) {
+							prefixMatch = true
+							break
+						}
+					}
+
+					if !prefixMatch {
+						logger.WarnContext(ctx, fmt.Sprintf("'%s' is not within any allowed file prefix", e.Request.URL))
+						allow = false
+					}
+				}
+
 				cctx := chromedp.FromContext(ctx)
 				executorCtx := cdp.WithExecutor(ctx, cctx.Target)
 
@@ -87,12 +106,13 @@ func listenForEventRequestPaused(ctx context.Context, logger *slog.Logger, optio
 						}
 
 						ok, err := header.Scope.MatchString(e.Request.URL)
-						if err != nil {
+						switch {
+						case err != nil:
 							logger.ErrorContext(ctx, fmt.Sprintf("fail to match extra HTTP header '%s' scope with URL '%s': %s", header.Name, e.Request.URL, err))
-						} else if ok {
+						case ok:
 							logger.DebugContext(ctx, fmt.Sprintf("extra HTTP header '%s' (scoped) will be set for request URL '%s'", header.Name, e.Request.URL))
 							extraHttpHeadersToSet = append(extraHttpHeadersToSet, header)
-						} else {
+						default:
 							logger.DebugContext(ctx, fmt.Sprintf("scoped extra HTTP header '%s' (scoped) will not be set for request URL '%s'", header.Name, e.Request.URL))
 						}
 					}
@@ -148,6 +168,7 @@ type eventResponseReceivedOptions struct {
 	ignoreResourceHttpStatusDomains []string
 	invalidResourceHttpStatusCode   *error
 	invalidResourceHttpStatusCodeMu *sync.RWMutex
+	cancelOnMainPageError           context.CancelFunc
 }
 
 // listenForEventResponseReceived listens for an invalid HTTP status code
@@ -177,8 +198,7 @@ func listenForEventResponseReceived(
 	}
 
 	chromedp.ListenTarget(ctx, func(ev any) {
-		switch ev := ev.(type) {
-		case *network.EventResponseReceived:
+		if ev, ok := ev.(*network.EventResponseReceived); ok {
 			if ev.Response.URL == options.mainPageUrl {
 				logger.DebugContext(ctx, fmt.Sprintf("event EventResponseReceived fired for main page: %+v", ev.Response))
 
@@ -187,6 +207,14 @@ func listenForEventResponseReceived(
 					defer options.invalidHttpStatusCodeMu.Unlock()
 
 					*options.invalidHttpStatusCode = fmt.Errorf("%d: %s", ev.Response.Status, ev.Response.StatusText)
+
+					// Cancel the task context so that any in-flight wait
+					// operations (waitForSelector, waitForExpression, etc.)
+					// abort immediately instead of polling until timeout.
+					// See https://github.com/gotenberg/gotenberg/issues/1492.
+					if options.cancelOnMainPageError != nil {
+						options.cancelOnMainPageError()
+					}
 				}
 
 				return
@@ -203,7 +231,7 @@ func listenForEventResponseReceived(
 				options.invalidResourceHttpStatusCodeMu.Lock()
 				defer options.invalidResourceHttpStatusCodeMu.Unlock()
 
-				*options.invalidResourceHttpStatusCode = multierr.Append(
+				*options.invalidResourceHttpStatusCode = errors.Join(
 					*options.invalidResourceHttpStatusCode,
 					fmt.Errorf("%s - %d: %s", ev.Response.URL, ev.Response.Status, http.StatusText(int(ev.Response.Status))),
 				)
@@ -290,6 +318,7 @@ type eventLoadingFailedOptions struct {
 	loadingFailedMu         *sync.RWMutex
 	resourceLoadingFailed   *error
 	resourceLoadingFailedMu *sync.RWMutex
+	cancelOnMainPageError   context.CancelFunc
 }
 
 // listenForEventLoadingFailed listens for an event indicating that the main
@@ -300,13 +329,12 @@ type eventLoadingFailedOptions struct {
 // https://github.com/gotenberg/gotenberg/issues/1021.
 func listenForEventLoadingFailed(ctx context.Context, logger *slog.Logger, options eventLoadingFailedOptions) {
 	chromedp.ListenTarget(ctx, func(ev any) {
-		switch ev := ev.(type) {
-		case *network.EventLoadingFailed:
+		if ev, ok := ev.(*network.EventLoadingFailed); ok {
 			logger.DebugContext(ctx, fmt.Sprintf("event EventLoadingFailed fired: %+v", ev.ErrorText))
 
 			// We are looking for common errors.
 			// TODO: sufficient?
-			errors := []string{
+			knownErrors := []string{
 				"net::ERR_CONNECTION_CLOSED",
 				"net::ERR_CONNECTION_RESET",
 				"net::ERR_CONNECTION_REFUSED",
@@ -320,8 +348,8 @@ func listenForEventLoadingFailed(ctx context.Context, logger *slog.Logger, optio
 				"net::ERR_FILE_NOT_FOUND",
 				"net::ERR_HTTP2_PROTOCOL_ERROR",
 			}
-			if !slices.Contains(errors, ev.ErrorText) {
-				logger.DebugContext(ctx, fmt.Sprintf("skip EventLoadingFailed: '%s' is not part of %+v", ev.ErrorText, errors))
+			if !slices.Contains(knownErrors, ev.ErrorText) {
+				logger.DebugContext(ctx, fmt.Sprintf("skip EventLoadingFailed: '%s' is not part of %+v", ev.ErrorText, knownErrors))
 				return
 			}
 
@@ -335,6 +363,13 @@ func listenForEventLoadingFailed(ctx context.Context, logger *slog.Logger, optio
 
 				*options.loadingFailed = fmt.Errorf("%s", ev.ErrorText)
 
+				// Cancel the task context so that any in-flight wait
+				// operations abort immediately.
+				// See https://github.com/gotenberg/gotenberg/issues/1492.
+				if options.cancelOnMainPageError != nil {
+					options.cancelOnMainPageError()
+				}
+
 				return
 			}
 
@@ -343,7 +378,7 @@ func listenForEventLoadingFailed(ctx context.Context, logger *slog.Logger, optio
 			options.resourceLoadingFailedMu.Lock()
 			defer options.resourceLoadingFailedMu.Unlock()
 
-			*options.resourceLoadingFailed = multierr.Append(
+			*options.resourceLoadingFailed = errors.Join(
 				*options.resourceLoadingFailed,
 				fmt.Errorf("resource %s: %s", ev.Type, ev.ErrorText),
 			)
@@ -356,14 +391,13 @@ func listenForEventLoadingFailed(ctx context.Context, logger *slog.Logger, optio
 // See https://github.com/gotenberg/gotenberg/issues/262.
 func listenForEventExceptionThrown(ctx context.Context, logger *slog.Logger, consoleExceptions *error, consoleExceptionsMu *sync.RWMutex) {
 	chromedp.ListenTarget(ctx, func(ev any) {
-		switch ev := ev.(type) {
-		case *runtime.EventExceptionThrown:
+		if ev, ok := ev.(*runtime.EventExceptionThrown); ok {
 			logger.DebugContext(ctx, fmt.Sprintf("event EventExceptionThrown fired: %+v", ev.ExceptionDetails))
 
 			consoleExceptionsMu.Lock()
 			defer consoleExceptionsMu.Unlock()
 
-			*consoleExceptions = multierr.Append(*consoleExceptions, fmt.Errorf("\n%+v", ev.ExceptionDetails))
+			*consoleExceptions = errors.Join(*consoleExceptions, fmt.Errorf("\n%+v", ev.ExceptionDetails))
 		}
 	})
 }
@@ -375,8 +409,7 @@ func waitForEventDomContentEventFired(ctx context.Context, logger *slog.Logger)
 		ch := make(chan struct{})
 		cctx, cancel := context.WithCancel(ctx)
 		chromedp.ListenTarget(cctx, func(ev any) {
-			switch ev.(type) {
-			case *page.EventDomContentEventFired:
+			if _, ok := ev.(*page.EventDomContentEventFired); ok {
 				cancel()
 				close(ch)
 			}
@@ -399,8 +432,7 @@ func waitForEventLoadEventFired(ctx context.Context, logger *slog.Logger) func()
 		ch := make(chan struct{})
 		cctx, cancel := context.WithCancel(ctx)
 		chromedp.ListenTarget(cctx, func(ev any) {
-			switch ev.(type) {
-			case *page.EventLoadEventFired:
+			if _, ok := ev.(*page.EventLoadEventFired); ok {
 				cancel()
 				close(ch)
 			}
@@ -423,12 +455,9 @@ func waitForEventNetworkIdle(ctx context.Context, logger *slog.Logger) func() er
 		ch := make(chan struct{})
 		cctx, cancel := context.WithCancel(ctx)
 		chromedp.ListenTarget(cctx, func(ev any) {
-			switch e := ev.(type) {
-			case *page.EventLifecycleEvent:
-				if e.Name == "networkIdle" {
-					cancel()
-					close(ch)
-				}
+			if e, ok := ev.(*page.EventLifecycleEvent); ok && e.Name == "networkIdle" {
+				cancel()
+				close(ch)
 			}
 		})
 
@@ -449,12 +478,9 @@ func waitForEventNetworkAlmostIdle(ctx context.Context, logger *slog.Logger) fun
 		ch := make(chan struct{})
 		cctx, cancel := context.WithCancel(ctx)
 		chromedp.ListenTarget(cctx, func(ev any) {
-			switch e := ev.(type) {
-			case *page.EventLifecycleEvent:
-				if e.Name == "networkIdle2" {
-					cancel()
-					close(ch)
-				}
+			if e, ok := ev.(*page.EventLifecycleEvent); ok && e.Name == "networkIdle2" {
+				cancel()
+				close(ch)
 			}
 		})
 
@@ -475,8 +501,7 @@ func waitForEventLoadingFinished(ctx context.Context, logger *slog.Logger) func(
 		ch := make(chan struct{})
 		cctx, cancel := context.WithCancel(ctx)
 		chromedp.ListenTarget(cctx, func(ev any) {
-			switch ev.(type) {
-			case *network.EventLoadingFinished:
+			if _, ok := ev.(*network.EventLoadingFinished); ok {
 				cancel()
 				close(ch)
 			}

pkg/modules/chromium/routes.go

@@ -17,7 +17,6 @@ import (
 	"github.com/gomarkdown/markdown"
 	"github.com/labstack/echo/v4"
 	"github.com/microcosm-cc/bluemonday"
-	"go.uber.org/multierr"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 	"github.com/gotenberg/gotenberg/v8/pkg/modules/api"
@@ -150,7 +149,7 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 
 			for i, cookie := range cookies {
 				if strings.TrimSpace(cookie.Name) == "" || strings.TrimSpace(cookie.Value) == "" || strings.TrimSpace(cookie.Domain) == "" {
-					err = multierr.Append(err, fmt.Errorf("cookie %d must have its name, value and domain set", i))
+					err = errors.Join(err, fmt.Errorf("cookie %d must have its name, value and domain set", i))
 				}
 			}
 
@@ -183,14 +182,12 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 						if len(parts) == 2 && strings.ToLower(parts[0]) == "scope" && parts[1] != "" {
 							scope = parts[1]
 						} else {
-							err = multierr.Append(err, fmt.Errorf("invalid scope '%s' for header '%s'", scope, k))
+							err = errors.Join(err, fmt.Errorf("invalid scope '%s' for header '%s'", scope, k))
 							invalidScopeToken = true
 							break
 						}
-					} else {
-						if token != "" {
-							valueTokens = append(valueTokens, token)
-						}
+					} else if token != "" {
+						valueTokens = append(valueTokens, token)
 					}
 				}
 
@@ -202,7 +199,7 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 				if len(scope) > 0 {
 					p, errCompile := regexp2.Compile(scope, regexp2.None)
 					if errCompile != nil {
-						err = multierr.Append(err, fmt.Errorf("invalid scope regex pattern for header '%s': %w", k, errCompile))
+						err = errors.Join(err, fmt.Errorf("invalid scope regex pattern for header '%s': %w", k, errCompile))
 						continue
 					}
 					scopeRegexp = p
@@ -417,7 +414,12 @@ func convertUrlRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 			pdfFormats := pdfengines.FormDataPdfFormats(form)
 			metadata := pdfengines.FormDataPdfMetadata(form, false)
 			userPassword, ownerPassword := pdfengines.FormDataPdfEncrypt(form)
-			attachmentsPaths := pdfengines.FormDataPdfAttachments(form)
+			embedPaths := pdfengines.FormDataPdfEmbeds(form)
+			watermark := pdfengines.FormDataPdfWatermark(form, false)
+			watermarkFile := pdfengines.FormDataPdfWatermarkFile(form)
+			stamp := pdfengines.FormDataPdfStamp(form, false)
+			stampFile := pdfengines.FormDataPdfStampFile(form)
+			rotateAngle, rotatePages := pdfengines.FormDataPdfRotate(form, false)
 
 			var url string
 			err := form.
@@ -427,7 +429,14 @@ func convertUrlRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
-			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, attachmentsPaths)
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
+			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, embedPaths, watermark, stamp, rotateAngle, rotatePages)
 			if err != nil {
 				return fmt.Errorf("convert URL to PDF: %w", err)
 			}
@@ -480,7 +489,12 @@ func convertHtmlRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 			pdfFormats := pdfengines.FormDataPdfFormats(form)
 			metadata := pdfengines.FormDataPdfMetadata(form, false)
 			userPassword, ownerPassword := pdfengines.FormDataPdfEncrypt(form)
-			attachmentsPaths := pdfengines.FormDataPdfAttachments(form)
+			embedPaths := pdfengines.FormDataPdfEmbeds(form)
+			watermark := pdfengines.FormDataPdfWatermark(form, false)
+			watermarkFile := pdfengines.FormDataPdfWatermarkFile(form)
+			stamp := pdfengines.FormDataPdfStamp(form, false)
+			stampFile := pdfengines.FormDataPdfStampFile(form)
+			rotateAngle, rotatePages := pdfengines.FormDataPdfRotate(form, false)
 
 			var inputPath string
 			err := form.
@@ -490,8 +504,16 @@ func convertHtmlRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
 			url := fmt.Sprintf("file://%s", inputPath)
-			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, attachmentsPaths)
+			options.AllowedFilePrefixes = []string{ctx.DirPath()}
+			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, embedPaths, watermark, stamp, rotateAngle, rotatePages)
 			if err != nil {
 				return fmt.Errorf("convert HTML to PDF: %w", err)
 			}
@@ -521,6 +543,7 @@ func screenshotHtmlRoute(chromium Api) api.Route {
 			}
 
 			url := fmt.Sprintf("file://%s", inputPath)
+			options.AllowedFilePrefixes = []string{ctx.DirPath()}
 			err = screenshotUrl(ctx, chromium, url, options)
 			if err != nil {
 				return fmt.Errorf("HTML screenshot: %w", err)
@@ -545,7 +568,12 @@ func convertMarkdownRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 			pdfFormats := pdfengines.FormDataPdfFormats(form)
 			metadata := pdfengines.FormDataPdfMetadata(form, false)
 			userPassword, ownerPassword := pdfengines.FormDataPdfEncrypt(form)
-			attachmentsPaths := pdfengines.FormDataPdfAttachments(form)
+			embedPaths := pdfengines.FormDataPdfEmbeds(form)
+			watermark := pdfengines.FormDataPdfWatermark(form, false)
+			watermarkFile := pdfengines.FormDataPdfWatermarkFile(form)
+			stamp := pdfengines.FormDataPdfStamp(form, false)
+			stampFile := pdfengines.FormDataPdfStampFile(form)
+			rotateAngle, rotatePages := pdfengines.FormDataPdfRotate(form, false)
 
 			var (
 				inputPath     string
@@ -560,12 +588,20 @@ func convertMarkdownRoute(chromium Api, engine gotenberg.PdfEngine) api.Route {
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
 			url, err := markdownToHtml(ctx, inputPath, markdownPaths)
 			if err != nil {
 				return fmt.Errorf("transform markdown file(s) to HTML: %w", err)
 			}
 
-			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, attachmentsPaths)
+			options.AllowedFilePrefixes = []string{ctx.DirPath()}
+			err = convertUrl(ctx, chromium, engine, url, options, mode, pdfFormats, metadata, userPassword, ownerPassword, embedPaths, watermark, stamp, rotateAngle, rotatePages)
 			if err != nil {
 				return fmt.Errorf("convert markdown to PDF: %w", err)
 			}
@@ -604,6 +640,7 @@ func screenshotMarkdownRoute(chromium Api) api.Route {
 				return fmt.Errorf("transform markdown file(s) to HTML: %w", err)
 			}
 
+			options.AllowedFilePrefixes = []string{ctx.DirPath()}
 			err = screenshotUrl(ctx, chromium, url, options)
 			if err != nil {
 				return fmt.Errorf("markdown screenshot: %w", err)
@@ -629,7 +666,7 @@ func markdownToHtml(ctx *api.Context, inputPath string, markdownPaths []string)
 				var path string
 
 				for _, markdownPath := range markdownPaths {
-					markdownFilename := filepath.Base(markdownPath)
+					markdownFilename := ctx.OriginalFilename(markdownPath)
 
 					if filename == markdownFilename {
 						path = markdownPath
@@ -638,7 +675,7 @@ func markdownToHtml(ctx *api.Context, inputPath string, markdownPaths []string)
 				}
 
 				if path == "" {
-					markdownFilesNotFoundErr = multierr.Append(
+					markdownFilesNotFoundErr = errors.Join(
 						markdownFilesNotFoundErr,
 						fmt.Errorf("'%s'", filename),
 					)
@@ -689,7 +726,7 @@ func markdownToHtml(ctx *api.Context, inputPath string, markdownPaths []string)
 	return fmt.Sprintf("file://%s", inputPath), nil
 }
 
-func convertUrl(ctx *api.Context, chromium Api, engine gotenberg.PdfEngine, url string, options PdfOptions, mode gotenberg.SplitMode, pdfFormats gotenberg.PdfFormats, metadata map[string]any, userPassword, ownerPassword string, attachmentsPaths []string) error {
+func convertUrl(ctx *api.Context, chromium Api, engine gotenberg.PdfEngine, url string, options PdfOptions, mode gotenberg.SplitMode, pdfFormats gotenberg.PdfFormats, metadata map[string]any, userPassword, ownerPassword string, embedPaths []string, watermark, stamp gotenberg.Stamp, rotateAngle int, rotatePages string) error {
 	outputPath := ctx.GeneratePath(".pdf")
 	// See https://github.com/gotenberg/gotenberg/issues/1130.
 	filename := ctx.OutputFilename(outputPath)
@@ -751,26 +788,48 @@ func convertUrl(ctx *api.Context, chromium Api, engine gotenberg.PdfEngine, url
 		return fmt.Errorf("convert to PDF: %w", err)
 	}
 
+	err = pdfengines.ValidatePdfFormatsCompat(pdfFormats, userPassword, embedPaths)
+	if err != nil {
+		return err
+	}
+
 	outputPaths, err := pdfengines.SplitPdfStub(ctx, engine, mode, []string{outputPath})
 	if err != nil {
 		return fmt.Errorf("split PDF: %w", err)
 	}
 
+	err = pdfengines.WatermarkStub(ctx, engine, watermark, outputPaths)
+	if err != nil {
+		return fmt.Errorf("watermark PDFs: %w", err)
+	}
+
+	err = pdfengines.StampStub(ctx, engine, stamp, outputPaths)
+	if err != nil {
+		return fmt.Errorf("stamp PDFs: %w", err)
+	}
+
+	err = pdfengines.RotateStub(ctx, engine, rotateAngle, rotatePages, outputPaths)
+	if err != nil {
+		return fmt.Errorf("rotate PDFs: %w", err)
+	}
+
 	convertOutputPaths, err := pdfengines.ConvertStub(ctx, engine, pdfFormats, outputPaths)
 	if err != nil {
 		return fmt.Errorf("convert PDF(s): %w", err)
 	}
 
-	err = pdfengines.AddAttachmentsStub(ctx, engine, attachmentsPaths, convertOutputPaths)
-	if err != nil {
-		return fmt.Errorf("add attachments into PDFs: %w", err)
-	}
-
+	// Metadata, embeds are written after Convert, as LibreOffice
+	// strips them during PDF/A conversion.
 	err = pdfengines.WriteMetadataStub(ctx, engine, metadata, convertOutputPaths)
 	if err != nil {
 		return fmt.Errorf("write metadata: %w", err)
 	}
 
+	err = pdfengines.EmbedFilesStub(ctx, engine, embedPaths, convertOutputPaths)
+	if err != nil {
+		return fmt.Errorf("embed files into PDFs: %w", err)
+	}
+
 	err = pdfengines.EncryptPdfStub(ctx, engine, userPassword, ownerPassword, convertOutputPaths)
 	if err != nil {
 		return fmt.Errorf("encrypt PDFs: %w", err)

pkg/modules/chromium/tasks.go

@@ -31,7 +31,9 @@ func printToPdfActionFunc(logger *slog.Logger, outputPath string, options PdfOpt
 
 			// There are 96 CSS pixels per inch.
 			// See https://issues.chromium.org/issues/40267771#comment14.
-			paperHeight = cssContentSize.Height / 96
+			// We add top and bottom margins so that the content area
+			// is large enough to fit the entire content.
+			paperHeight = (cssContentSize.Height / 96) + options.MarginTop + options.MarginBottom
 			pageRanges = "1" // little dirty hack to avoid leftovers.
 		}
 
@@ -303,28 +305,28 @@ func userAgentOverride(logger *slog.Logger, userAgent string) chromedp.ActionFun
 // network.SetExtraHTTPHeaders set the headers for ALL requests from the page.
 // See https://github.com/gotenberg/gotenberg/issues/1011.
 //
-//func extraHttpHeadersActionFunc(logger *slog.Logger, extraHttpHeaders map[string]string) chromedp.ActionFunc {
-//	return func(ctx context.Context) error {
-//		if len(extraHttpHeaders) == 0 {
-//			logger.DebugContext(ctx, "no extra HTTP headers")
-//			return nil
-//		}
+//  func extraHttpHeadersActionFunc(logger *slog.Logger, extraHttpHeaders map[string]string) chromedp.ActionFunc {
+// 	return func(ctx context.Context) error {
+// 		if len(extraHttpHeaders) == 0 {
+// 			logger.DebugContext(ctx,"no extra HTTP headers")
+// 			return nil
+// 		}
 //
-//		logger.DebugContext(ctx, fmt.Sprintf("extra HTTP headers: %+v", extraHttpHeaders))
+// 		logger.DebugContext(ctx,fmt.Sprintf("extra HTTP headers: %+v", extraHttpHeaders))
 //
-//		headers := make(network.Headers, len(extraHttpHeaders))
-//		for key, value := range extraHttpHeaders {
-//			headers[key] = value
-//		}
+// 		headers := make(network.Headers, len(extraHttpHeaders))
+// 		for key, value := range extraHttpHeaders {
+// 			headers[key] = value
+// 		}
 //
-//		err := network.SetExtraHTTPHeaders(headers).Do(ctx)
-//		if err == nil {
-//			return nil
-//		}
+// 		err := network.SetExtraHTTPHeaders(headers).Do(ctx)
+// 		if err == nil {
+// 			return nil
+// 		}
 //
-//		return fmt.Errorf("set extra HTTP headers: %w", err)
-//	}
-//}
+// 		return fmt.Errorf("set extra HTTP headers: %w", err)
+// 	}
+// }
 
 func navigateActionFunc(logger *slog.Logger, url string, skipNetworkIdleEvent, skipNetworkAlmostIdleEvent bool) chromedp.ActionFunc {
 	return func(ctx context.Context) error {

pkg/modules/exiftool/exiftool.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/barasher/go-exiftool"
 	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
@@ -77,63 +78,66 @@ func (engine *ExifTool) Debug() map[string]any {
 
 // Merge is not available in this implementation.
 func (engine *ExifTool) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.Merge", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Merge",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("merge PDFs with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Split is not available in this implementation.
 func (engine *ExifTool) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.Split", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Split",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("split PDF with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return nil, err
 }
 
 // Flatten is not available in this implementation.
 func (engine *ExifTool) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Flatten",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("flatten PDF with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Convert is not available in this implementation.
 func (engine *ExifTool) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.Convert", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Convert",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("convert PDF to '%+v' with ExifTool: %w", formats, gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // ReadMetadata extracts the metadata of a given PDF file.
 func (engine *ExifTool) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.ReadMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	exifTool, err := exiftool.NewExiftool(exiftool.SetExiftoolBinaryPath(engine.binPath))
@@ -159,12 +163,16 @@ func (engine *ExifTool) ReadMetadata(ctx context.Context, logger *slog.Logger, i
 		return nil, err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return fileMetadata[0].Fields, nil
 }
 
 // WriteMetadata writes the metadata into a given PDF file.
 func (engine *ExifTool) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.WriteMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	exifTool, err := exiftool.NewExiftool(exiftool.SetExiftoolBinaryPath(engine.binPath))
@@ -217,6 +225,17 @@ func (engine *ExifTool) WriteMetadata(ctx context.Context, logger *slog.Logger,
 		delete(fileMetadata[0].Fields, tag)
 	}
 
+	// Filter user-supplied metadata to prevent ExifTool pseudo-tags from
+	// triggering dangerous side effects like file renames or moves.
+	// See https://exiftool.org/TagNames/Extra.html.
+	dangerousTags := []string{
+		"FileName",  // Writing this triggers a file rename in ExifTool
+		"Directory", // Writing this triggers a file move in ExifTool
+	}
+	for _, tag := range dangerousTags {
+		delete(metadata, tag)
+	}
+
 	for key, value := range metadata {
 		switch val := value.(type) {
 		case string:
@@ -265,34 +284,158 @@ func (engine *ExifTool) WriteMetadata(ctx context.Context, logger *slog.Logger,
 		return err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return nil
 }
 
+// PageCount returns the number of pages in a PDF file using ExifTool.
+func (engine *ExifTool) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.PageCount",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	metadata, err := engine.ReadMetadata(ctx, logger, inputPath)
+	if err != nil {
+		err = fmt.Errorf("read metadata with ExifTool: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return 0, err
+	}
+
+	pageCountValue, ok := metadata["PageCount"]
+	if !ok {
+		err = errors.New("PageCount not found in metadata")
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return 0, err
+	}
+
+	switch val := pageCountValue.(type) {
+	case int:
+		span.SetStatus(codes.Ok, "")
+		return val, nil
+	case int64:
+		span.SetStatus(codes.Ok, "")
+		return int(val), nil
+	case float64:
+		span.SetStatus(codes.Ok, "")
+		return int(val), nil
+	case string:
+		var res int
+		_, err := fmt.Sscanf(val, "%d", &res)
+		if err != nil {
+			err = fmt.Errorf("parse PageCount string '%s': %w", val, err)
+			span.RecordError(err)
+			span.SetStatus(codes.Error, err.Error())
+			return 0, err
+		}
+		span.SetStatus(codes.Ok, "")
+		return res, nil
+	default:
+		err = fmt.Errorf("unexpected PageCount type '%T'", pageCountValue)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return 0, err
+	}
+}
+
+// WriteBookmarks is not available in this implementation.
+func (engine *ExifTool) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.WriteBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("write PDF bookmarks with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// ReadBookmarks is not available in this implementation.
+func (engine *ExifTool) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.ReadBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("read PDF bookmarks with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return nil, err
+}
+
 // Encrypt is not available in this implementation.
 func (engine *ExifTool) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Encrypt",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("encrypt PDF using ExifTool: %w", gotenberg.ErrPdfEncryptionNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
-// AddAttachments is not available in this implementation.
-func (engine *ExifTool) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "ExifTool.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
+// EmbedFiles is not available in this implementation.
+func (engine *ExifTool) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.EmbedFiles",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
-	err := fmt.Errorf("add attachments with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	err := fmt.Errorf("embed files with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
 
+// Watermark is not available in this implementation.
+func (engine *ExifTool) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Watermark",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("watermark PDF with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// Stamp is not available in this implementation.
+func (engine *ExifTool) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Stamp",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("stamp PDF with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// Rotate is not available in this implementation.
+func (engine *ExifTool) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	_, span := gotenberg.Tracer().Start(ctx, "exiftool.Rotate",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("rotate PDF with ExifTool: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 

pkg/modules/libreoffice/api/api.go

@@ -16,7 +16,8 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/metric"
-	"go.uber.org/multierr"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
+	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 	"github.com/gotenberg/gotenberg/v8/pkg/modules/api"
@@ -138,6 +139,66 @@ type Options struct {
 	// one page.
 	SinglePageSheets bool
 
+	// InitialView specifies how the PDF document should be displayed when
+	// opened. 0 = neither outlines nor thumbnails, 1 = outline pane open,
+	// 2 = thumbnail pane open.
+	InitialView int
+
+	// InitialPage specifies the page on which the PDF document should be
+	// opened in the viewer.
+	InitialPage int
+
+	// Magnification specifies the action to be performed when the PDF document
+	// is opened. 0 = default, 1 = fit entire page, 2 = fit page width,
+	// 3 = fit visible, 4 = use zoom value from Zoom property.
+	Magnification int
+
+	// Zoom specifies the zoom level the PDF document is opened with. Only
+	// used if Magnification is set to 4.
+	Zoom int
+
+	// PageLayout specifies the page layout when the document is opened.
+	// 0 = default, 1 = single page, 2 = one column, 3 = two columns.
+	PageLayout int
+
+	// FirstPageOnLeft is used with PageLayout value 3. If true, the first
+	// page is displayed on the left side.
+	FirstPageOnLeft bool
+
+	// ResizeWindowToInitialPage specifies that the PDF viewer window is
+	// resized to show the whole initial page.
+	ResizeWindowToInitialPage bool
+
+	// CenterWindow specifies that the PDF viewer window is centered on the
+	// screen.
+	CenterWindow bool
+
+	// OpenInFullScreenMode specifies that the PDF viewer window is opened
+	// full screen.
+	OpenInFullScreenMode bool
+
+	// DisplayPDFDocumentTitle specifies that the document title is displayed
+	// in the PDF viewer title bar.
+	DisplayPDFDocumentTitle bool
+
+	// HideViewerMenubar specifies whether to hide the PDF viewer menubar.
+	HideViewerMenubar bool
+
+	// HideViewerToolbar specifies whether to hide the PDF viewer toolbar.
+	HideViewerToolbar bool
+
+	// HideViewerWindowControls specifies whether to hide the PDF viewer
+	// window controls.
+	HideViewerWindowControls bool
+
+	// UseTransitionEffects specifies that slide transitions are exported to
+	// PDF. Only active for Impress documents.
+	UseTransitionEffects bool
+
+	// OpenBookmarkLevels specifies how many bookmark levels should be opened
+	// in the reader. -1 = all levels, 1-10 = specific level.
+	OpenBookmarkLevels int
+
 	// LosslessImageCompression specifies if images are exported to PDF using
 	// a lossless compression format like PNG or compressed using the JPEG
 	// format.
@@ -156,6 +217,29 @@ type Options struct {
 	// Possible values are: 75, 150, 300, 600 and 1200.
 	MaxImageResolution int
 
+	// NativeWatermarkText specifies the text for a watermark to be drawn on
+	// every page of the exported PDF file.
+	// See https://help.libreoffice.org/latest/en-US/text/shared/guide/pdf_params.html.
+	NativeWatermarkText string
+
+	// NativeWatermarkColor specifies the color for the watermark text as a
+	// decimal long value. Default is 8388223 (light green).
+	NativeWatermarkColor int
+
+	// NativeWatermarkFontHeight specifies the font size for the watermark text.
+	NativeWatermarkFontHeight int
+
+	// NativeWatermarkRotateAngle specifies the rotation angle for the watermark
+	// text in tenths of a degree (e.g., 450 = 45°).
+	NativeWatermarkRotateAngle int
+
+	// NativeWatermarkFontName specifies the font name for the watermark text.
+	// Default is "Helvetica".
+	NativeWatermarkFontName string
+
+	// NativeTiledWatermarkText specifies the tiled watermark text.
+	NativeTiledWatermarkText string
+
 	// PdfFormats allows to convert the resulting PDF to PDF/A-1b, PDF/A-2b,
 	// PDF/A-3b and PDF/UA.
 	PdfFormats gotenberg.PdfFormats
@@ -183,10 +267,31 @@ func DefaultOptions() Options {
 		SkipEmptyPages:                  false,
 		AddOriginalDocumentAsStream:     false,
 		SinglePageSheets:                false,
+		InitialView:                     0,
+		InitialPage:                     1,
+		Magnification:                   0,
+		Zoom:                            100,
+		PageLayout:                      0,
+		FirstPageOnLeft:                 false,
+		ResizeWindowToInitialPage:       false,
+		CenterWindow:                    false,
+		OpenInFullScreenMode:            false,
+		DisplayPDFDocumentTitle:         true,
+		HideViewerMenubar:               false,
+		HideViewerToolbar:               false,
+		HideViewerWindowControls:        false,
+		UseTransitionEffects:            true,
+		OpenBookmarkLevels:              -1,
 		LosslessImageCompression:        false,
 		Quality:                         90,
 		ReduceImageResolution:           false,
 		MaxImageResolution:              300,
+		NativeWatermarkText:             "",
+		NativeWatermarkColor:            8388223,
+		NativeWatermarkFontHeight:       0,
+		NativeWatermarkRotateAngle:      0,
+		NativeWatermarkFontName:         "Helvetica",
+		NativeTiledWatermarkText:        "",
 		PdfFormats: gotenberg.PdfFormats{
 			PdfA:  "",
 			PdfUa: false,
@@ -219,6 +324,7 @@ func (a *Api) Descriptor() gotenberg.ModuleDescriptor {
 			fs := flag.NewFlagSet("api", flag.ExitOnError)
 			fs.Int64("libreoffice-restart-after", 10, "Number of conversions after which LibreOffice will automatically restart. Set to 0 to disable this feature")
 			fs.Int64("libreoffice-max-queue-size", 0, "Maximum request queue size for LibreOffice. Set to 0 to disable this feature")
+			fs.Duration("libreoffice-idle-shutdown-timeout", 0, "Shutdown LibreOffice after being idle for the given duration. Set to 0 to disable this feature")
 			fs.Bool("libreoffice-auto-start", false, "Automatically launch LibreOffice upon initialization if set to true; otherwise, LibreOffice will start at the time of the first conversion")
 			fs.Duration("libreoffice-start-timeout", time.Duration(20)*time.Second, "Maximum duration to wait for LibreOffice to start or restart")
 
@@ -254,97 +360,102 @@ func (a *Api) Provision(ctx *gotenberg.Context) error {
 
 	// Process.
 	a.libreOffice = newLibreOfficeProcess(a.args)
-	a.supervisor = gotenberg.NewProcessSupervisor(a.logger, a.libreOffice, flags.MustInt64("libreoffice-restart-after"), flags.MustInt64("libreoffice-max-queue-size"), 1)
+	a.supervisor = gotenberg.NewProcessSupervisor(a.logger, a.libreOffice, flags.MustInt64("libreoffice-restart-after"), flags.MustInt64("libreoffice-max-queue-size"), 1, flags.MustDuration("libreoffice-idle-shutdown-timeout"))
 
-	// OpenTelemetry.
+	// Metrics.
 	meter := gotenberg.Meter()
-	_, err := meter.Int64ObservableCounter(
-		"libreoffice.process.restarts.total",
-		metric.WithDescription("Current number of LibreOffice restarts."),
-		metric.WithUnit("{restart}"),
+
+	// Observable gauges.
+	var err error
+
+	_, err = meter.Int64ObservableGauge(
+		"libreoffice.requests.active",
+		metric.WithDescription("Current number of active LibreOffice requests"),
+		metric.WithUnit("{request}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := a.supervisor.RestartsCount()
-			o.Observe(val)
+			o.Observe(a.supervisor.ActiveTasksCount())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create process restarts observable counter: %w", err)
+		return fmt.Errorf("create libreoffice.requests.active gauge: %w", err)
 	}
 
 	_, err = meter.Int64ObservableGauge(
 		"libreoffice.requests.queue_size",
-		metric.WithDescription("Current number of LibreOffice conversion requests waiting to be treated."),
+		metric.WithDescription("Current number of LibreOffice conversion requests waiting to be treated"),
 		metric.WithUnit("{request}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := a.supervisor.ReqQueueSize()
-			o.Observe(val)
+			o.Observe(a.supervisor.ReqQueueSize())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests queue size observable gauge: %w", err)
+		return fmt.Errorf("create libreoffice.requests.queue_size gauge: %w", err)
 	}
 
-	_, err = meter.Int64ObservableGauge(
-		"libreoffice.requests.active",
-		metric.WithDescription("Current number of LibreOffice conversion requests actively being processed."),
-		metric.WithUnit("{request}"),
+	_, err = meter.Int64ObservableCounter(
+		"libreoffice.process.restarts.total",
+		metric.WithDescription("Current number of LibreOffice restarts"),
+		metric.WithUnit("{restart}"),
 		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
-			val := a.supervisor.ActiveTasksCount()
-			o.Observe(val)
+			o.Observe(a.supervisor.RestartsCount())
 			return nil
 		}),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests active observable gauge: %w", err)
+		return fmt.Errorf("create libreoffice.process.restarts.total counter: %w", err)
 	}
 
+	// Counters.
 	a.reqsCounter, err = meter.Int64Counter(
 		"libreoffice.requests.total",
-		metric.WithDescription("Total number of LibreOffice conversion requests."),
+		metric.WithDescription("Total number of LibreOffice conversion requests"),
 		metric.WithUnit("{request}"),
 	)
 	if err != nil {
-		return fmt.Errorf("create requests total counter: %w", err)
+		return fmt.Errorf("create libreoffice.requests.total counter: %w", err)
 	}
 
 	a.errsCounter, err = meter.Int64Counter(
 		"libreoffice.errors.total",
-		metric.WithDescription("Total number of LibreOffice errors."),
+		metric.WithDescription("Total number of LibreOffice conversion errors"),
 		metric.WithUnit("{error}"),
 	)
 	if err != nil {
-		return fmt.Errorf("create errors total counter: %w", err)
+		return fmt.Errorf("create libreoffice.errors.total counter: %w", err)
 	}
 
+	// Histograms.
+	durationBuckets := metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60)
+
 	a.conversionDurationCounter, err = meter.Float64Histogram(
 		"libreoffice.conversion.duration",
-		metric.WithDescription("Duration of each PDF conversion."),
+		metric.WithDescription("Duration of LibreOffice conversions"),
 		metric.WithUnit("s"),
-		metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60),
+		durationBuckets,
 	)
 	if err != nil {
-		return fmt.Errorf("create conversion duration histogram: %w", err)
+		return fmt.Errorf("create libreoffice.conversion.duration histogram: %w", err)
 	}
 
 	a.queueWaitDurationCounter, err = meter.Float64Histogram(
 		"libreoffice.queue.wait.duration",
-		metric.WithDescription("Time a request spends waiting in the queue before processing starts."),
+		metric.WithDescription("Duration of waiting in queue for LibreOffice conversions"),
 		metric.WithUnit("s"),
-		metric.WithExplicitBucketBoundaries(0.5, 1, 2, 5, 10, 30, 60),
+		durationBuckets,
 	)
 	if err != nil {
-		return fmt.Errorf("create queue wait duration histogram: %w", err)
+		return fmt.Errorf("create libreoffice.queue.wait.duration histogram: %w", err)
 	}
 
 	a.pdfOutputSizeCounter, err = meter.Int64Histogram(
 		"libreoffice.pdf.output.size",
-		metric.WithDescription("Size of the generated PDF files."),
+		metric.WithDescription("Size of PDF output from LibreOffice conversions"),
 		metric.WithUnit("By"),
 	)
 	if err != nil {
-		return fmt.Errorf("create pdf output size histogram: %w", err)
+		return fmt.Errorf("create libreoffice.pdf.output.size histogram: %w", err)
 	}
 
 	return nil
@@ -356,12 +467,12 @@ func (a *Api) Validate() error {
 
 	_, statErr := os.Stat(a.args.binPath)
 	if os.IsNotExist(statErr) {
-		err = multierr.Append(err, fmt.Errorf("LibreOffice binary path does not exist: %w", statErr))
+		err = errors.Join(err, fmt.Errorf("LibreOffice binary path does not exist: %w", statErr))
 	}
 
 	_, statErr = os.Stat(a.args.unoBinPath)
 	if os.IsNotExist(statErr) {
-		err = multierr.Append(err, fmt.Errorf("unoconverter binary path does not exist: %w", statErr))
+		err = errors.Join(err, fmt.Errorf("unoconverter binary path does not exist: %w", statErr))
 	}
 
 	return err
@@ -424,6 +535,26 @@ func (a *Api) Debug() map[string]any {
 	return debug
 }
 
+// Metrics returns the metrics.
+func (a *Api) Metrics() ([]gotenberg.Metric, error) {
+	return []gotenberg.Metric{
+		{
+			Name:        "libreoffice_requests_queue_size",
+			Description: "Current number of LibreOffice conversion requests waiting to be treated.",
+			Read: func() float64 {
+				return float64(a.supervisor.ReqQueueSize())
+			},
+		},
+		{
+			Name:        "libreoffice_restarts_count",
+			Description: "Current number of LibreOffice restarts.",
+			Read: func() float64 {
+				return float64(a.supervisor.RestartsCount())
+			},
+		},
+	}, nil
+}
+
 // Checks adds a health check that verifies if LibreOffice is healthy.
 func (a *Api) Checks() ([]health.CheckerOption, error) {
 	return []health.CheckerOption{
@@ -475,7 +606,10 @@ func (a *Api) LibreOffice() (Uno, error) {
 
 // Pdf converts a document to PDF.
 func (a *Api) Pdf(ctx context.Context, logger *slog.Logger, inputPath, outputPath string, options Options) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "LibreOffice.Pdf")
+	ctx, span := gotenberg.Tracer().Start(ctx, "libreoffice.Pdf",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(a.args.binPath)),
+	)
 	defer span.End()
 
 	start := time.Now()
@@ -486,78 +620,62 @@ func (a *Api) Pdf(ctx context.Context, logger *slog.Logger, inputPath, outputPat
 		return a.libreOffice.pdf(ctx, logger, inputPath, outputPath, options)
 	})
 
-	end := time.Now()
-
+	// Determine status and error reason.
 	status := "success"
+	reason := ""
+
 	if err != nil {
-		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
+		switch {
+		case errors.Is(err, context.DeadlineExceeded):
 			status = "timeout"
-		} else {
+			reason = "timeout"
+		case errors.Is(err, context.Canceled):
 			status = "error"
+			reason = "context_cancelled"
+		case errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) || errors.Is(err, gotenberg.ErrProcessAlreadyRestarting):
+			status = "error"
+			reason = "libreoffice_unavailable"
+		default:
+			status = "error"
+			reason = "unknown"
 		}
 	}
 
+	// Record metrics.
+	attrs := metric.WithAttributes(attribute.String("status", status))
+	a.reqsCounter.Add(ctx, 1, attrs)
+
+	if reason != "" {
+		a.errsCounter.Add(ctx, 1, metric.WithAttributes(attribute.String("reason", reason)))
+	}
+
 	if !conversionStart.IsZero() {
-		waitDuration := conversionStart.Sub(start).Seconds()
-		conversionDuration := end.Sub(conversionStart).Seconds()
+		queueWait := conversionStart.Sub(start).Seconds()
+		a.queueWaitDurationCounter.Record(ctx, queueWait, attrs)
 
-		a.queueWaitDurationCounter.Record(ctx, waitDuration, metric.WithAttributes(
-			attribute.String("status", status),
-		))
-		a.conversionDurationCounter.Record(ctx, conversionDuration, metric.WithAttributes(
-			attribute.String("status", status),
-		))
-	} else {
-		waitDuration := end.Sub(start).Seconds()
-		a.queueWaitDurationCounter.Record(ctx, waitDuration, metric.WithAttributes(
-			attribute.String("status", status),
-		))
+		conversionDuration := time.Since(conversionStart).Seconds()
+		a.conversionDurationCounter.Record(ctx, conversionDuration, attrs)
 	}
 
-	a.reqsCounter.Add(ctx, 1, metric.WithAttributes(
-		attribute.String("status", status),
-	))
-
 	if err == nil {
-		if fileInfo, statErr := os.Stat(outputPath); statErr == nil {
-			a.pdfOutputSizeCounter.Record(ctx, fileInfo.Size())
+		stat, statErr := os.Stat(outputPath)
+		if statErr == nil {
+			a.pdfOutputSizeCounter.Record(ctx, stat.Size(), attrs)
 		}
+
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
-	reason := "unknown"
-	if errors.Is(err, context.DeadlineExceeded) {
-		reason = "timeout"
-	} else if errors.Is(err, context.Canceled) {
-		reason = "context_cancelled"
-	} else if errors.Is(err, ErrInvalidPdfFormats) {
-		reason = "invalid_input"
-	} else if errors.Is(err, gotenberg.ErrMaximumQueueSizeExceeded) {
-		reason = "libreoffice_maximum_queue_size_exceeded"
-	} else if errors.Is(err, gotenberg.ErrProcessAlreadyRestarting) {
-		reason = "libreoffice_unavailable"
-	}
-
-	a.errsCounter.Add(ctx, 1, metric.WithAttributes(
-		attribute.String("reason", reason),
-	))
-
 	// See https://github.com/gotenberg/gotenberg/issues/639.
 	if errors.Is(err, ErrCoreDumped) {
 		logger.DebugContext(ctx, fmt.Sprintf("got a '%s' error, retry conversion", err))
-		err = a.Pdf(ctx, logger, inputPath, outputPath, options)
-		if err != nil {
-			span.RecordError(err)
-			span.SetStatus(codes.Error, err.Error())
-		}
-		return err
+		return a.Pdf(ctx, logger, inputPath, outputPath, options)
 	}
 
-	err = fmt.Errorf("supervisor run task: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
-
-	return err
+	return fmt.Errorf("supervisor run task: %w", err)
 }
 
 // Extensions returns the file extensions available for conversions.
@@ -699,12 +817,13 @@ func (a *Api) Extensions() []string {
 
 // Interface guards.
 var (
-	_ gotenberg.Module      = (*Api)(nil)
-	_ gotenberg.Provisioner = (*Api)(nil)
-	_ gotenberg.Validator   = (*Api)(nil)
-	_ gotenberg.App         = (*Api)(nil)
-	_ gotenberg.Debuggable  = (*Api)(nil)
-	_ api.HealthChecker     = (*Api)(nil)
-	_ Uno                   = (*Api)(nil)
-	_ Provider              = (*Api)(nil)
+	_ gotenberg.Module          = (*Api)(nil)
+	_ gotenberg.Provisioner     = (*Api)(nil)
+	_ gotenberg.Validator       = (*Api)(nil)
+	_ gotenberg.App             = (*Api)(nil)
+	_ gotenberg.Debuggable      = (*Api)(nil)
+	_ gotenberg.MetricsProvider = (*Api)(nil)
+	_ api.HealthChecker         = (*Api)(nil)
+	_ Uno                       = (*Api)(nil)
+	_ Provider                  = (*Api)(nil)
 )

pkg/modules/libreoffice/api/libreoffice.go

@@ -12,11 +12,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"go.opentelemetry.io/otel/attribute"
-	"go.opentelemetry.io/otel/codes"
-	semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
-	"go.opentelemetry.io/otel/trace"
-
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
 
@@ -90,7 +85,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 		return fmt.Errorf("execute LibreOffice: %w", err)
 	}
 
-	logger.DebugContext(ctx, "got exit code 81, e.g., LibreOffice first start")
+	logger.DebugContext(context.Background(), "got exit code 81, e.g., LibreOffice first start")
 
 	// Second start (daemon).
 	cmd = gotenberg.Command(logger, p.arguments.binPath, args...)
@@ -127,7 +122,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 			connChan <- nil
 			err = conn.Close()
 			if err != nil {
-				logger.DebugContext(ctx, fmt.Sprintf("close connection after health checking the LibreOffice: %v", err))
+				logger.DebugContext(context.Background(), fmt.Sprintf("close connection after health checking the LibreOffice: %v", err))
 			}
 
 			break
@@ -164,7 +159,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 		logger.DebugContext(context.Background(), fmt.Sprintf("'%s' LibreOffice's user profile directory removed", userProfileDirPath))
 	}()
 
-	logger.DebugContext(ctx, "waiting for the LibreOffice socket to be available...")
+	logger.DebugContext(context.Background(), "waiting for the LibreOffice socket to be available...")
 
 	for {
 		select {
@@ -173,7 +168,7 @@ func (p *libreOfficeProcess) Start(logger *slog.Logger) error {
 				return fmt.Errorf("LibreOffice socket not available: %w", err)
 			}
 
-			logger.DebugContext(ctx, "LibreOffice socket available")
+			logger.DebugContext(context.Background(), "LibreOffice socket available")
 			success = true
 
 			return nil
@@ -300,19 +295,58 @@ func (p *libreOfficeProcess) pdf(ctx context.Context, logger *slog.Logger, input
 	args = append(args, "--export", fmt.Sprintf("IsSkipEmptyPages=%t", options.SkipEmptyPages))
 	args = append(args, "--export", fmt.Sprintf("IsAddStream=%t", options.AddOriginalDocumentAsStream))
 	args = append(args, "--export", fmt.Sprintf("SinglePageSheets=%t", options.SinglePageSheets))
+	args = append(args, "--export", fmt.Sprintf("InitialView=%d", options.InitialView))
+	args = append(args, "--export", fmt.Sprintf("InitialPage=%d", options.InitialPage))
+	args = append(args, "--export", fmt.Sprintf("Magnification=%d", options.Magnification))
+	args = append(args, "--export", fmt.Sprintf("Zoom=%d", options.Zoom))
+	args = append(args, "--export", fmt.Sprintf("PageLayout=%d", options.PageLayout))
+	args = append(args, "--export", fmt.Sprintf("FirstPageOnLeft=%t", options.FirstPageOnLeft))
+	args = append(args, "--export", fmt.Sprintf("ResizeWindowToInitialPage=%t", options.ResizeWindowToInitialPage))
+	args = append(args, "--export", fmt.Sprintf("CenterWindow=%t", options.CenterWindow))
+	args = append(args, "--export", fmt.Sprintf("OpenInFullScreenMode=%t", options.OpenInFullScreenMode))
+	args = append(args, "--export", fmt.Sprintf("DisplayPDFDocumentTitle=%t", options.DisplayPDFDocumentTitle))
+	args = append(args, "--export", fmt.Sprintf("HideViewerMenubar=%t", options.HideViewerMenubar))
+	args = append(args, "--export", fmt.Sprintf("HideViewerToolbar=%t", options.HideViewerToolbar))
+	args = append(args, "--export", fmt.Sprintf("HideViewerWindowControls=%t", options.HideViewerWindowControls))
+	args = append(args, "--export", fmt.Sprintf("UseTransitionEffects=%t", options.UseTransitionEffects))
+	args = append(args, "--export", fmt.Sprintf("OpenBookmarkLevels=%d", options.OpenBookmarkLevels))
 	args = append(args, "--export", fmt.Sprintf("UseLosslessCompression=%t", options.LosslessImageCompression))
 	args = append(args, "--export", fmt.Sprintf("Quality=%d", options.Quality))
 	args = append(args, "--export", fmt.Sprintf("ReduceImageResolution=%t", options.ReduceImageResolution))
 	args = append(args, "--export", fmt.Sprintf("MaxImageResolution=%d", options.MaxImageResolution))
 
+	if options.NativeWatermarkText != "" {
+		args = append(args, "--export", fmt.Sprintf("Watermark=%s", options.NativeWatermarkText))
+	}
+
+	if options.NativeWatermarkColor != 0 {
+		args = append(args, "--export", fmt.Sprintf("WatermarkColor=%d", options.NativeWatermarkColor))
+	}
+
+	if options.NativeWatermarkFontHeight > 0 {
+		args = append(args, "--export", fmt.Sprintf("WatermarkFontHeight=%d", options.NativeWatermarkFontHeight))
+	}
+
+	if options.NativeWatermarkRotateAngle != 0 {
+		args = append(args, "--export", fmt.Sprintf("WatermarkRotateAngle=%d", options.NativeWatermarkRotateAngle))
+	}
+
+	if options.NativeWatermarkFontName != "" && options.NativeWatermarkFontName != "Helvetica" {
+		args = append(args, "--export", fmt.Sprintf("WatermarkFontName=%s", options.NativeWatermarkFontName))
+	}
+
+	if options.NativeTiledWatermarkText != "" {
+		args = append(args, "--export", fmt.Sprintf("TiledWatermark=%s", options.NativeTiledWatermarkText))
+	}
+
 	switch options.PdfFormats.PdfA {
 	case "":
 	case gotenberg.PdfA1b:
-		args = append(args, "--export", "SelectPdfVersion=1")
+		args = append(args, "--export", "SelectPdfVersion=1", "--export", "EmbedStandardFonts=true")
 	case gotenberg.PdfA2b:
-		args = append(args, "--export", "SelectPdfVersion=2")
+		args = append(args, "--export", "SelectPdfVersion=2", "--export", "EmbedStandardFonts=true")
 	case gotenberg.PdfA3b:
-		args = append(args, "--export", "SelectPdfVersion=3")
+		args = append(args, "--export", "SelectPdfVersion=3", "--export", "EmbedStandardFonts=true")
 	default:
 		return ErrInvalidPdfFormats
 	}
@@ -323,6 +357,7 @@ func (p *libreOfficeProcess) pdf(ctx context.Context, logger *slog.Logger, input
 			"--export", "PDFUACompliance=true",
 			"--export", "UseTaggedPDF=true",
 			"--export", "EnableTextAccessForAccessibilityTools=true",
+			"--export", "EmbedStandardFonts=true",
 		)
 	} else {
 		args = append(
@@ -335,35 +370,14 @@ func (p *libreOfficeProcess) pdf(ctx context.Context, logger *slog.Logger, input
 
 	args = append(args, "--output", outputPath, inputPath)
 
-	p.cfgMu.RLock()
-	clientCtx, clientSpan := gotenberg.Tracer().Start(ctx, "uno.execute",
-		trace.WithSpanKind(trace.SpanKindClient),
-		trace.WithAttributes(
-			semconv.ServerAddress("127.0.0.1"),
-			semconv.ServerPort(p.socketPort),
-			semconv.ServicePeerName("libreoffice"),
-			// Legacy attribute for older APMs (Datadog, Jaeger) to draw the
-			// dependency graph.
-			attribute.String("peer.service", "libreoffice"),
-		),
-	)
-	p.cfgMu.RUnlock()
-
-	cmd, err := gotenberg.CommandContext(clientCtx, logger, p.arguments.unoBinPath, args...)
+	cmd, err := gotenberg.CommandContext(ctx, logger, p.arguments.unoBinPath, args...)
 	if err != nil {
 		return fmt.Errorf("create uno command: %w", err)
 	}
 
-	logger.DebugContext(clientCtx, fmt.Sprintf("print to PDF with: %+v", options))
+	logger.DebugContext(ctx, fmt.Sprintf("print to PDF with: %+v", options))
 
 	exitCode, err := cmd.Exec()
-	if err != nil {
-		clientSpan.RecordError(err)
-		clientSpan.SetStatus(codes.Error, err.Error())
-	}
-
-	clientSpan.End()
-
 	if err == nil {
 		return nil
 	}

pkg/modules/libreoffice/pdfengine/pdfengine.go

@@ -6,9 +6,6 @@ import (
 	"fmt"
 	"log/slog"
 
-	"go.opentelemetry.io/otel/codes"
-	"go.opentelemetry.io/otel/trace"
-
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 	"github.com/gotenberg/gotenberg/v8/pkg/modules/libreoffice/api"
 )
@@ -50,44 +47,17 @@ func (engine *LibreOfficePdfEngine) Provision(ctx *gotenberg.Context) error {
 
 // Merge is not available in this implementation.
 func (engine *LibreOfficePdfEngine) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.Merge", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
-	err := fmt.Errorf("merge PDFs with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return err
+	return fmt.Errorf("merge PDFs with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // Split is not available in this implementation.
 func (engine *LibreOfficePdfEngine) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.Split", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
-	err := fmt.Errorf("split PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return nil, err
+	return nil, fmt.Errorf("split PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // Flatten is not available in this implementation.
 func (engine *LibreOfficePdfEngine) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
-	err := fmt.Errorf("flatten PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return err
+	return fmt.Errorf("flatten PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // Convert converts the given PDF to a specific PDF format. Currently, only the
@@ -95,9 +65,6 @@ func (engine *LibreOfficePdfEngine) Flatten(ctx context.Context, logger *slog.Lo
 // PDF format is requested, it returns a [gotenberg.ErrPdfFormatNotSupported]
 // error.
 func (engine *LibreOfficePdfEngine) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.Convert", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
 	opts := api.DefaultOptions()
 	opts.PdfFormats = formats
 	err := engine.unoApi.Pdf(ctx, logger, inputPath, outputPath, opts)
@@ -107,73 +74,60 @@ func (engine *LibreOfficePdfEngine) Convert(ctx context.Context, logger *slog.Lo
 	}
 
 	if errors.Is(err, api.ErrInvalidPdfFormats) {
-		err = fmt.Errorf("convert PDF to '%+v' with LibreOffice: %w", formats, gotenberg.ErrPdfFormatNotSupported)
-	} else {
-		err = fmt.Errorf("convert PDF to '%+v' with LibreOffice: %w", formats, err)
+		return fmt.Errorf("convert PDF to '%+v' with LibreOffice: %w", formats, gotenberg.ErrPdfFormatNotSupported)
 	}
 
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return err
+	return fmt.Errorf("convert PDF to '%+v' with LibreOffice: %w", formats, err)
 }
 
 // ReadMetadata is not available in this implementation.
 func (engine *LibreOfficePdfEngine) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
-	err := fmt.Errorf("read PDF metadata with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return nil, err
+	return nil, fmt.Errorf("read PDF metadata with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // WriteMetadata is not available in this implementation.
 func (engine *LibreOfficePdfEngine) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
+	return fmt.Errorf("write PDF metadata with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
 
-	err := fmt.Errorf("write PDF metadata with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+// PageCount is not available in this implementation.
+func (engine *LibreOfficePdfEngine) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	return 0, fmt.Errorf("page count with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
 
-	return err
+// WriteBookmarks is not available in this implementation.
+func (engine *LibreOfficePdfEngine) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	return fmt.Errorf("write PDF bookmarks with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
+
+// ReadBookmarks is not available in this implementation.
+func (engine *LibreOfficePdfEngine) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	return nil, fmt.Errorf("read PDF bookmarks with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // Encrypt is not available in this implementation.
 func (engine *LibreOfficePdfEngine) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
-
-	err := fmt.Errorf("encrypt PDF using LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
-	return err
+	return fmt.Errorf("encrypt PDF using LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
-// AddAttachments is not available in this implementation.
-func (engine *LibreOfficePdfEngine) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "LibreOfficePdfEngine.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
-	defer span.End()
+// EmbedFiles is not available in this implementation.
+func (engine *LibreOfficePdfEngine) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	return fmt.Errorf("embed files with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
 
-	err := fmt.Errorf("add attachments with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+// Watermark is not available in this implementation.
+func (engine *LibreOfficePdfEngine) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	return fmt.Errorf("watermark PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
 
-	return err
+// Stamp is not available in this implementation.
+func (engine *LibreOfficePdfEngine) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	return fmt.Errorf("stamp PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+}
+
+// Rotate is not available in this implementation.
+func (engine *LibreOfficePdfEngine) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	return fmt.Errorf("rotate PDF with LibreOffice: %w", gotenberg.ErrPdfEngineMethodNotSupported)
 }
 
 // Interface guards.

pkg/modules/libreoffice/routes.go

@@ -31,7 +31,12 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 			pdfFormats := pdfengines.FormDataPdfFormats(form)
 			metadata := pdfengines.FormDataPdfMetadata(form, false)
 			userPassword, ownerPassword := pdfengines.FormDataPdfEncrypt(form)
-			attachmentsPaths := pdfengines.FormDataPdfAttachments(form)
+			embedPaths := pdfengines.FormDataPdfEmbeds(form)
+			watermark := pdfengines.FormDataPdfWatermark(form, false)
+			watermarkFile := pdfengines.FormDataPdfWatermarkFile(form)
+			stamp := pdfengines.FormDataPdfStamp(form, false)
+			stampFile := pdfengines.FormDataPdfStampFile(form)
+			angle, rotatePages := pdfengines.FormDataPdfRotate(form, false)
 
 			zeroValuedSplitMode := gotenberg.SplitMode{}
 
@@ -60,6 +65,27 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 				quality                         int
 				reduceImageResolution           bool
 				maxImageResolution              int
+				nativeWatermarkText             string
+				nativeWatermarkColor            int
+				initialView                     int
+				initialPage                     int
+				magnification                   int
+				zoom                            int
+				pageLayout                      int
+				firstPageOnLeft                 bool
+				resizeWindowToInitialPage       bool
+				centerWindow                    bool
+				openInFullScreenMode            bool
+				displayPDFDocumentTitle         bool
+				hideViewerMenubar               bool
+				hideViewerToolbar               bool
+				hideViewerWindowControls        bool
+				useTransitionEffects            bool
+				openBookmarkLevels              int
+				nativeWatermarkFontHeight       int
+				nativeWatermarkRotateAngle      int
+				nativeWatermarkFontName         string
+				nativeTiledWatermarkText        string
 				nativePdfFormats                bool
 				merge                           bool
 				flatten                         bool
@@ -86,6 +112,105 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 				Bool("skipEmptyPages", &skipEmptyPages, defaultOptions.SkipEmptyPages).
 				Bool("addOriginalDocumentAsStream", &addOriginalDocumentAsStream, defaultOptions.AddOriginalDocumentAsStream).
 				Bool("singlePageSheets", &singlePageSheets, defaultOptions.SinglePageSheets).
+				Custom("initialView", func(value string) error {
+					if value == "" {
+						initialView = defaultOptions.InitialView
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if !slices.Contains([]int{0, 1, 2}, intValue) {
+						return errors.New("value is not 0, 1 or 2")
+					}
+					initialView = intValue
+					return nil
+				}).
+				Custom("initialPage", func(value string) error {
+					if value == "" {
+						initialPage = defaultOptions.InitialPage
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if intValue < 1 {
+						return errors.New("value is inferior to 1")
+					}
+					initialPage = intValue
+					return nil
+				}).
+				Custom("magnification", func(value string) error {
+					if value == "" {
+						magnification = defaultOptions.Magnification
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if !slices.Contains([]int{0, 1, 2, 3, 4}, intValue) {
+						return errors.New("value is not 0, 1, 2, 3 or 4")
+					}
+					magnification = intValue
+					return nil
+				}).
+				Custom("zoom", func(value string) error {
+					if value == "" {
+						zoom = defaultOptions.Zoom
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if intValue < 1 {
+						return errors.New("value is inferior to 1")
+					}
+					zoom = intValue
+					return nil
+				}).
+				Custom("pageLayout", func(value string) error {
+					if value == "" {
+						pageLayout = defaultOptions.PageLayout
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if !slices.Contains([]int{0, 1, 2, 3}, intValue) {
+						return errors.New("value is not 0, 1, 2 or 3")
+					}
+					pageLayout = intValue
+					return nil
+				}).
+				Bool("firstPageOnLeft", &firstPageOnLeft, defaultOptions.FirstPageOnLeft).
+				Bool("resizeWindowToInitialPage", &resizeWindowToInitialPage, defaultOptions.ResizeWindowToInitialPage).
+				Bool("centerWindow", &centerWindow, defaultOptions.CenterWindow).
+				Bool("openInFullScreenMode", &openInFullScreenMode, defaultOptions.OpenInFullScreenMode).
+				Bool("displayPDFDocumentTitle", &displayPDFDocumentTitle, defaultOptions.DisplayPDFDocumentTitle).
+				Bool("hideViewerMenubar", &hideViewerMenubar, defaultOptions.HideViewerMenubar).
+				Bool("hideViewerToolbar", &hideViewerToolbar, defaultOptions.HideViewerToolbar).
+				Bool("hideViewerWindowControls", &hideViewerWindowControls, defaultOptions.HideViewerWindowControls).
+				Bool("useTransitionEffects", &useTransitionEffects, defaultOptions.UseTransitionEffects).
+				Custom("openBookmarkLevels", func(value string) error {
+					if value == "" {
+						openBookmarkLevels = defaultOptions.OpenBookmarkLevels
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if intValue != -1 && (intValue < 1 || intValue > 10) {
+						return errors.New("value is not -1 or between 1 and 10")
+					}
+					openBookmarkLevels = intValue
+					return nil
+				}).
 				Bool("losslessImageCompression", &losslessImageCompression, defaultOptions.LosslessImageCompression).
 				Custom("quality", func(value string) error {
 					if value == "" {
@@ -128,6 +253,48 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 					maxImageResolution = intValue
 					return nil
 				}).
+				String("nativeWatermarkText", &nativeWatermarkText, defaultOptions.NativeWatermarkText).
+				Custom("nativeWatermarkColor", func(value string) error {
+					if value == "" {
+						nativeWatermarkColor = defaultOptions.NativeWatermarkColor
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					nativeWatermarkColor = intValue
+					return nil
+				}).
+				Custom("nativeWatermarkFontHeight", func(value string) error {
+					if value == "" {
+						nativeWatermarkFontHeight = defaultOptions.NativeWatermarkFontHeight
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					if intValue < 0 {
+						return errors.New("value is inferior to 0")
+					}
+					nativeWatermarkFontHeight = intValue
+					return nil
+				}).
+				Custom("nativeWatermarkRotateAngle", func(value string) error {
+					if value == "" {
+						nativeWatermarkRotateAngle = defaultOptions.NativeWatermarkRotateAngle
+						return nil
+					}
+					intValue, err := strconv.Atoi(value)
+					if err != nil {
+						return err
+					}
+					nativeWatermarkRotateAngle = intValue
+					return nil
+				}).
+				String("nativeWatermarkFontName", &nativeWatermarkFontName, defaultOptions.NativeWatermarkFontName).
+				String("nativeTiledWatermarkText", &nativeTiledWatermarkText, defaultOptions.NativeTiledWatermarkText).
 				Bool("nativePdfFormats", &nativePdfFormats, true).
 				Bool("merge", &merge, false).
 				Bool("flatten", &flatten, false).
@@ -136,6 +303,21 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
+			err = pdfengines.ValidatePdfFormatsCompat(pdfFormats, userPassword, embedPaths)
+			if err != nil {
+				return err
+			}
+
+			hasPostProcessing := watermark.Source != "" || stamp.Source != "" || angle != 0 ||
+				len(embedPaths) > 0 || len(metadata) > 0 || flatten
+
 			outputPaths := make([]string, len(inputPaths))
 			for i, inputPath := range inputPaths {
 				outputPaths[i] = ctx.GeneratePath(".pdf")
@@ -159,15 +341,37 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 					SkipEmptyPages:                  skipEmptyPages,
 					AddOriginalDocumentAsStream:     addOriginalDocumentAsStream,
 					SinglePageSheets:                singlePageSheets,
+					InitialView:                     initialView,
+					InitialPage:                     initialPage,
+					Magnification:                   magnification,
+					Zoom:                            zoom,
+					PageLayout:                      pageLayout,
+					FirstPageOnLeft:                 firstPageOnLeft,
+					ResizeWindowToInitialPage:       resizeWindowToInitialPage,
+					CenterWindow:                    centerWindow,
+					OpenInFullScreenMode:            openInFullScreenMode,
+					DisplayPDFDocumentTitle:         displayPDFDocumentTitle,
+					HideViewerMenubar:               hideViewerMenubar,
+					HideViewerToolbar:               hideViewerToolbar,
+					HideViewerWindowControls:        hideViewerWindowControls,
+					UseTransitionEffects:            useTransitionEffects,
+					OpenBookmarkLevels:              openBookmarkLevels,
 					LosslessImageCompression:        losslessImageCompression,
 					Quality:                         quality,
 					ReduceImageResolution:           reduceImageResolution,
 					MaxImageResolution:              maxImageResolution,
+					NativeWatermarkText:             nativeWatermarkText,
+					NativeWatermarkColor:            nativeWatermarkColor,
+					NativeWatermarkFontHeight:       nativeWatermarkFontHeight,
+					NativeWatermarkRotateAngle:      nativeWatermarkRotateAngle,
+					NativeWatermarkFontName:         nativeWatermarkFontName,
+					NativeTiledWatermarkText:        nativeTiledWatermarkText,
 				}
 
-				if nativePdfFormats && splitMode == zeroValuedSplitMode {
+				if nativePdfFormats && splitMode == zeroValuedSplitMode && !hasPostProcessing {
 					// Only natively apply given PDF formats if we're not
-					// splitting the PDF later.
+					// splitting the PDF later and no post-processing features
+					// are enabled (as they would degrade compliance).
 					options.PdfFormats = pdfFormats
 				}
 
@@ -216,7 +420,8 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 					// document.docx -> document.docx.pdf, so that split naming
 					// document.docx_0.pdf, etc.
 					for i, inputPath := range inputPaths {
-						outputPath := fmt.Sprintf("%s.pdf", inputPath)
+						originalName := ctx.OriginalFilename(inputPath)
+						outputPath := ctx.GeneratePathFromFilename(originalName + ".pdf")
 
 						err = ctx.Rename(outputPaths[i], outputPath)
 						if err != nil {
@@ -233,7 +438,32 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 				}
 			}
 
-			if !nativePdfFormats || (nativePdfFormats && splitMode != zeroValuedSplitMode) {
+			err = pdfengines.WatermarkStub(ctx, engine, watermark, outputPaths)
+			if err != nil {
+				return fmt.Errorf("watermark PDFs: %w", err)
+			}
+
+			err = pdfengines.StampStub(ctx, engine, stamp, outputPaths)
+			if err != nil {
+				return fmt.Errorf("stamp PDFs: %w", err)
+			}
+
+			err = pdfengines.RotateStub(ctx, engine, angle, rotatePages, outputPaths)
+			if err != nil {
+				return fmt.Errorf("rotate PDFs: %w", err)
+			}
+
+			if flatten {
+				err = pdfengines.FlattenStub(ctx, engine, outputPaths)
+				if err != nil {
+					return fmt.Errorf("flatten PDFs: %w", err)
+				}
+			}
+
+			needsConvertStub := !nativePdfFormats ||
+				(nativePdfFormats && splitMode != zeroValuedSplitMode) ||
+				(nativePdfFormats && hasPostProcessing)
+			if needsConvertStub {
 				convertOutputPaths, err := pdfengines.ConvertStub(ctx, engine, pdfFormats, outputPaths)
 				if err != nil {
 					return fmt.Errorf("convert PDFs: %w", err)
@@ -253,21 +483,16 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 				}
 			}
 
-			err = pdfengines.AddAttachmentsStub(ctx, engine, attachmentsPaths, outputPaths)
-			if err != nil {
-				return fmt.Errorf("add attachments into PDFs: %w", err)
-			}
-
+			// Metadata, embeds are written after Convert, as LibreOffice
+			// strips them during PDF/A conversion.
 			err = pdfengines.WriteMetadataStub(ctx, engine, metadata, outputPaths)
 			if err != nil {
 				return fmt.Errorf("write metadata: %w", err)
 			}
 
-			if flatten {
-				err = pdfengines.FlattenStub(ctx, engine, outputPaths)
-				if err != nil {
-					return fmt.Errorf("flatten PDFs: %w", err)
-				}
+			err = pdfengines.EmbedFilesStub(ctx, engine, embedPaths, outputPaths)
+			if err != nil {
+				return fmt.Errorf("embed files into PDFs: %w", err)
 			}
 
 			err = pdfengines.EncryptPdfStub(ctx, engine, userPassword, ownerPassword, outputPaths)
@@ -278,7 +503,8 @@ func convertRoute(libreOffice libreofficeapi.Uno, engine gotenberg.PdfEngine) ap
 			if len(outputPaths) > 1 && splitMode == zeroValuedSplitMode {
 				// If .zip archive, document.docx -> document.docx.pdf.
 				for i, inputPath := range inputPaths {
-					outputPath := fmt.Sprintf("%s.pdf", inputPath)
+					originalName := ctx.OriginalFilename(inputPath)
+					outputPath := ctx.GeneratePathFromFilename(originalName + ".pdf")
 
 					err = ctx.Rename(outputPaths[i], outputPath)
 					if err != nil {

pkg/modules/pdfcpu/pdfcpu.go

@@ -1,7 +1,9 @@
 package pdfcpu
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -9,10 +11,12 @@ import (
 	"os/exec"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
 	"syscall"
 
 	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
@@ -28,6 +32,16 @@ type PdfCpu struct {
 	binPath string
 }
 
+type pdfcpuBookmark struct {
+	Title    string           `json:"title"`
+	Page     int              `json:"page"`
+	Children []pdfcpuBookmark `json:"kids,omitempty"`
+}
+
+type pdfcpuBookmarks struct {
+	Bookmarks []pdfcpuBookmark `json:"bookmarks"`
+}
+
 // Descriptor returns a [PdfCpu]'s module descriptor.
 func (engine *PdfCpu) Descriptor() gotenberg.ModuleDescriptor {
 	return gotenberg.ModuleDescriptor{
@@ -86,7 +100,10 @@ func (engine *PdfCpu) Debug() map[string]any {
 
 // Merge combines multiple PDFs into a single PDF.
 func (engine *PdfCpu) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfCpu.Merge", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Merge",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	args := make([]string, 0, 2+len(inputPaths))
@@ -103,20 +120,22 @@ func (engine *PdfCpu) Merge(ctx context.Context, logger *slog.Logger, inputPaths
 
 	_, err = cmd.Exec()
 	if err == nil {
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
 	err = fmt.Errorf("merge PDFs with pdfcpu: %w", err)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Split splits a given PDF file.
 func (engine *PdfCpu) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfCpu.Split", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Split",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	var args []string
@@ -176,76 +195,273 @@ func (engine *PdfCpu) Split(ctx context.Context, logger *slog.Logger, mode goten
 
 	sort.Sort(digitSuffixSort(outputPaths))
 
+	span.SetStatus(codes.Ok, "")
 	return outputPaths, nil
 }
 
 // Flatten is not available in this implementation.
 func (engine *PdfCpu) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfCpu.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Flatten",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("flatten PDF with pdfcpu: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Convert is not available in this implementation.
 func (engine *PdfCpu) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfCpu.Convert", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Convert",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("convert PDF to '%+v' with pdfcpu: %w", formats, gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // ReadMetadata is not available in this implementation.
 func (engine *PdfCpu) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfCpu.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdfcpu.ReadMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("read PDF metadata with pdfcpu: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return nil, err
 }
 
 // WriteMetadata is not available in this implementation.
 func (engine *PdfCpu) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfCpu.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdfcpu.WriteMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("write PDF metadata with pdfcpu: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
-// AddAttachments adds attachments into a PDF. All files are attached as
-// file attachments without modifying the main PDF content.
-func (engine *PdfCpu) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfCpu.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
+// PageCount is not available in this implementation.
+func (engine *PdfCpu) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "pdfcpu.PageCount",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
-	if len(filePaths) == 0 {
+	err := fmt.Errorf("page count with pdfcpu: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return 0, err
+}
+
+// ReadBookmarks reads the document outline (bookmarks) of a PDF file using pdfcpu.
+func (engine *PdfCpu) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.ReadBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	tmpPath := fmt.Sprintf("%s.read.json", inputPath)
+	args := []string{"bookmarks", "export", inputPath, tmpPath}
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return nil, err
+	}
+
+	defer func() {
+		err := os.Remove(tmpPath)
+		if err != nil && !os.IsNotExist(err) {
+			logger.ErrorContext(ctx, fmt.Sprintf("remove temporary bookmarks JSON file: %v", err))
+		}
+	}()
+
+	_, cmdErr := cmd.Exec()
+
+	// Check file existence and size.
+	info, statErr := os.Stat(tmpPath)
+
+	if cmdErr != nil {
+		// If the file wasn't created, or it was created but is 0 bytes,
+		// it means pdfcpu had no bookmarks to write.
+		if os.IsNotExist(statErr) || (statErr == nil && info.Size() == 0) {
+			span.SetStatus(codes.Ok, "")
+			return make([]gotenberg.Bookmark, 0), nil
+		}
+
+		// Fallback: Check the error string just in case pdfcpu failed without
+		// touching the file.
+		if strings.Contains(strings.ToLower(cmdErr.Error()), "no bookmarks") {
+			span.SetStatus(codes.Ok, "")
+			return make([]gotenberg.Bookmark, 0), nil
+		}
+		err = fmt.Errorf("read bookmarks with pdfcpu: %w", cmdErr)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return nil, err
+	}
+
+	// If cmd succeeded, but output a 0-byte file anyway.
+	if info != nil && info.Size() == 0 {
+		span.SetStatus(codes.Ok, "")
+		return make([]gotenberg.Bookmark, 0), nil
+	}
+
+	// Read the file content.
+	jsonBytes, err := os.ReadFile(tmpPath)
+	if err != nil {
+		err = fmt.Errorf("read temporary bookmarks JSON file: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return nil, err
+	}
+
+	// Check if the content is just empty whitespace.
+	if len(bytes.TrimSpace(jsonBytes)) == 0 {
+		span.SetStatus(codes.Ok, "")
+		return make([]gotenberg.Bookmark, 0), nil
+	}
+
+	var data pdfcpuBookmarks
+	err = json.Unmarshal(jsonBytes, &data)
+	if err != nil {
+		err = fmt.Errorf("unmarshal bookmarks: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return nil, err
+	}
+
+	// Safety check: Does the parsed JSON actually contain bookmarks?
+	if len(data.Bookmarks) == 0 {
+		span.SetStatus(codes.Ok, "")
+		return make([]gotenberg.Bookmark, 0), nil
+	}
+
+	var mapBookmarks func(bookmarks []pdfcpuBookmark) []gotenberg.Bookmark
+	mapBookmarks = func(bookmarks []pdfcpuBookmark) []gotenberg.Bookmark {
+		res := make([]gotenberg.Bookmark, len(bookmarks))
+		for i, b := range bookmarks {
+			res[i] = gotenberg.Bookmark{
+				Title:    b.Title,
+				Page:     b.Page,
+				Children: mapBookmarks(b.Children),
+			}
+		}
+		return res
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return mapBookmarks(data.Bookmarks), nil
+}
+
+// WriteBookmarks adds a document outline (bookmarks) to a PDF file using pdfcpu.
+func (engine *PdfCpu) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.WriteBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	if len(bookmarks) == 0 {
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
-	logger.DebugContext(ctx, fmt.Sprintf("attaching %d file(s) to %s: %v", len(filePaths), inputPath, filePaths))
+	var mapBookmarks func(bookmarks []gotenberg.Bookmark) []pdfcpuBookmark
+	mapBookmarks = func(bookmarks []gotenberg.Bookmark) []pdfcpuBookmark {
+		res := make([]pdfcpuBookmark, len(bookmarks))
+		for i, b := range bookmarks {
+			res[i] = pdfcpuBookmark{
+				Title:    b.Title,
+				Page:     b.Page,
+				Children: mapBookmarks(b.Children),
+			}
+		}
+		return res
+	}
+
+	data := pdfcpuBookmarks{
+		Bookmarks: mapBookmarks(bookmarks),
+	}
+
+	jsonBytes, err := json.Marshal(data)
+	if err != nil {
+		err = fmt.Errorf("marshal bookmarks: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	tmpPath := fmt.Sprintf("%s.json", inputPath)
+	err = os.WriteFile(tmpPath, jsonBytes, 0o600)
+	if err != nil {
+		err = fmt.Errorf("write temporary bookmarks JSON file: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	defer func() {
+		err := os.Remove(tmpPath)
+		if err != nil {
+			logger.ErrorContext(ctx, fmt.Sprintf("remove temporary bookmarks JSON file: %v", err))
+		}
+	}()
+
+	args := []string{"bookmarks", "import", "-replace", inputPath, tmpPath, inputPath}
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	_, err = cmd.Exec()
+	if err != nil {
+		err = fmt.Errorf("write bookmarks with pdfcpu: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// EmbedFiles embeds files into a PDF. All files are embedded as file attachments
+// without modifying the main PDF content.
+func (engine *PdfCpu) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.EmbedFiles",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	if len(filePaths) == 0 {
+		span.SetStatus(codes.Ok, "")
+		return nil
+	}
+
+	logger.DebugContext(ctx, fmt.Sprintf("embedding %d file(s) to %s: %v", len(filePaths), inputPath, filePaths))
 
 	args := make([]string, 0, 3+len(filePaths))
 	args = append(args, "attachments", "add", inputPath)
@@ -267,12 +483,16 @@ func (engine *PdfCpu) AddAttachments(ctx context.Context, logger *slog.Logger, f
 		return err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return nil
 }
 
 // Encrypt adds password protection to a PDF file using pdfcpu.
 func (engine *PdfCpu) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfCpu.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Encrypt",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	if userPassword == "" {
@@ -310,6 +530,120 @@ func (engine *PdfCpu) Encrypt(ctx context.Context, logger *slog.Logger, inputPat
 		return err
 	}
 
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// Watermark applies a watermark (behind page content) to a PDF file using pdfcpu.
+func (engine *PdfCpu) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Watermark",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := engine.applyStampOrWatermark(ctx, logger, "watermark", inputPath, stamp)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// Stamp applies a stamp (on top of page content) to a PDF file using pdfcpu.
+func (engine *PdfCpu) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Stamp",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := engine.applyStampOrWatermark(ctx, logger, "stamp", inputPath, stamp)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// Rotate rotates pages of a PDF file by the given angle using pdfcpu.
+func (engine *PdfCpu) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdfcpu.Rotate",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	args := []string{"rotate"}
+	if pages != "" {
+		args = append(args, "-pages", pages)
+	}
+	args = append(args, "--", inputPath, strconv.Itoa(angle), inputPath)
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	_, err = cmd.Exec()
+	if err != nil {
+		err = fmt.Errorf("rotate PDF with pdfcpu: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+func (engine *PdfCpu) applyStampOrWatermark(ctx context.Context, logger *slog.Logger, command string, inputPath string, stamp gotenberg.Stamp) error {
+	var mode string
+	switch stamp.Source {
+	case gotenberg.StampSourceText:
+		mode = "text"
+	case gotenberg.StampSourceImage:
+		mode = "image"
+	case gotenberg.StampSourcePDF:
+		mode = "pdf"
+	default:
+		return fmt.Errorf("%s PDF with pdfcpu: %w", command, gotenberg.ErrPdfStampSourceNotSupported)
+	}
+
+	// Build description from Options map.
+	var descParts []string
+	for k, v := range stamp.Options {
+		descParts = append(descParts, fmt.Sprintf("%s:%s", k, v))
+	}
+	description := strings.Join(descParts, ", ")
+
+	args := []string{command, "add", "-mode", mode}
+
+	if stamp.Pages != "" {
+		args = append(args, "-pages", stamp.Pages)
+	}
+
+	args = append(args, "--", stamp.Expression, description, inputPath, inputPath)
+
+	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 fmt.Errorf("%s PDF with pdfcpu: %w", command, err)
+	}
+
 	return nil
 }
 

pkg/modules/pdfengines/AGENTS.md

@@ -0,0 +1,14 @@
+# Adding PDF Engine Features
+
+When adding a new PDF engine capability (e.g., bookmarks, watermark, stamp, embed), you must update the Makefile to include the corresponding engine list variable and flag. Every `--pdfengines-*-engines` flag registered in `pkg/modules/pdfengines/pdfengines.go` must have a matching entry in the Makefile:
+
+1. **Add a variable** in the Makefile's variable block (around line 60-70):
+   ```makefile
+   PDFENGINES_<FEATURE>_ENGINES=<default engines>
+   ```
+2. **Add the flag** in the Makefile's command args block (around line 140-155):
+   ```makefile
+   --pdfengines-<feature>-engines=$(PDFENGINES_<FEATURE>_ENGINES) \
+   ```
+
+The default value should match what is defined in `pdfengines.go`'s `fs.StringSlice(...)` call for that flag.

pkg/modules/pdfengines/multi.go

@@ -1,28 +1,32 @@
-//nolint:dupl
 package pdfengines
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"sync"
 
 	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/trace"
-	"go.uber.org/multierr"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
 
 type multiPdfEngines struct {
-	mergeEngines         []gotenberg.PdfEngine
-	splitEngines         []gotenberg.PdfEngine
-	flattenEngines       []gotenberg.PdfEngine
-	convertEngines       []gotenberg.PdfEngine
-	readMetadataEngines  []gotenberg.PdfEngine
-	writeMetadataEngines []gotenberg.PdfEngine
-	passwordEngines      []gotenberg.PdfEngine
-	attachmentsEngines   []gotenberg.PdfEngine
+	mergeEngines          []gotenberg.PdfEngine
+	splitEngines          []gotenberg.PdfEngine
+	flattenEngines        []gotenberg.PdfEngine
+	convertEngines        []gotenberg.PdfEngine
+	readMetadataEngines   []gotenberg.PdfEngine
+	writeMetadataEngines  []gotenberg.PdfEngine
+	passwordEngines       []gotenberg.PdfEngine
+	embedEngines          []gotenberg.PdfEngine
+	readBookmarksEngines  []gotenberg.PdfEngine
+	writeBookmarksEngines []gotenberg.PdfEngine
+	watermarkEngines      []gotenberg.PdfEngine
+	stampEngines          []gotenberg.PdfEngine
+	rotateEngines         []gotenberg.PdfEngine
 }
 
 func newMultiPdfEngines(
@@ -33,24 +37,37 @@ func newMultiPdfEngines(
 	readMetadataEngines,
 	writeMetadataEngines,
 	passwordEngines,
-	attachmentsEngines []gotenberg.PdfEngine,
+	embedEngines,
+	readBookmarksEngines,
+	writeBookmarksEngines,
+	watermarkEngines,
+	stampEngines,
+	rotateEngines []gotenberg.PdfEngine,
 ) *multiPdfEngines {
 	return &multiPdfEngines{
-		mergeEngines:         mergeEngines,
-		splitEngines:         splitEngines,
-		flattenEngines:       flattenEngines,
-		convertEngines:       convertEngines,
-		readMetadataEngines:  readMetadataEngines,
-		writeMetadataEngines: writeMetadataEngines,
-		passwordEngines:      passwordEngines,
-		attachmentsEngines:   attachmentsEngines,
+		mergeEngines:          mergeEngines,
+		splitEngines:          splitEngines,
+		flattenEngines:        flattenEngines,
+		convertEngines:        convertEngines,
+		readMetadataEngines:   readMetadataEngines,
+		writeMetadataEngines:  writeMetadataEngines,
+		passwordEngines:       passwordEngines,
+		embedEngines:          embedEngines,
+		readBookmarksEngines:  readBookmarksEngines,
+		writeBookmarksEngines: writeBookmarksEngines,
+		watermarkEngines:      watermarkEngines,
+		stampEngines:          stampEngines,
+		rotateEngines:         rotateEngines,
 	}
 }
 
 // Merge combines multiple PDF files into a single document using the first
 // available engine that supports PDF merging.
+//
+//nolint:dupl
 func (multi *multiPdfEngines) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.Merge", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Merge", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -63,8 +80,10 @@ func (multi *multiPdfEngines) Merge(ctx context.Context, logger *slog.Logger, in
 
 		select {
 		case mergeErr := <-errChan:
-			errored := multierr.AppendInto(&err, mergeErr)
-			if !errored {
+			if mergeErr != nil {
+				err = errors.Join(err, mergeErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -75,6 +94,7 @@ func (multi *multiPdfEngines) Merge(ctx context.Context, logger *slog.Logger, in
 	err = fmt.Errorf("merge PDFs with multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 
@@ -86,7 +106,8 @@ type splitResult struct {
 // Split divides the PDF into separate pages using the first available engine
 // that supports PDF splitting.
 func (multi *multiPdfEngines) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.Split", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Split", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -104,9 +125,10 @@ func (multi *multiPdfEngines) Split(ctx context.Context, logger *slog.Logger, mo
 		case result := <-resultChan:
 			if result.err != nil {
 				mu.Lock()
-				err = multierr.Append(err, result.err)
+				err = errors.Join(err, result.err)
 				mu.Unlock()
 			} else {
+				span.SetStatus(codes.Ok, "")
 				return result.outputPaths, nil
 			}
 		case <-ctx.Done():
@@ -117,13 +139,15 @@ func (multi *multiPdfEngines) Split(ctx context.Context, logger *slog.Logger, mo
 	err = fmt.Errorf("split PDF with multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return nil, err
 }
 
 // Flatten merges existing annotation appearances with page content using the
 // first available engine that supports flattening.
 func (multi *multiPdfEngines) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -136,8 +160,10 @@ func (multi *multiPdfEngines) Flatten(ctx context.Context, logger *slog.Logger,
 
 		select {
 		case mergeErr := <-errChan:
-			errored := multierr.AppendInto(&err, mergeErr)
-			if !errored {
+			if mergeErr != nil {
+				err = errors.Join(err, mergeErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -148,13 +174,15 @@ func (multi *multiPdfEngines) Flatten(ctx context.Context, logger *slog.Logger,
 	err = fmt.Errorf("flatten PDF with multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 
 // Convert transforms the given PDF to a specific PDF format using the first
 // available engine that supports PDF conversion.
 func (multi *multiPdfEngines) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.Convert", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Convert", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -167,8 +195,10 @@ func (multi *multiPdfEngines) Convert(ctx context.Context, logger *slog.Logger,
 
 		select {
 		case mergeErr := <-errChan:
-			errored := multierr.AppendInto(&err, mergeErr)
-			if !errored {
+			if mergeErr != nil {
+				err = errors.Join(err, mergeErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -179,6 +209,7 @@ func (multi *multiPdfEngines) Convert(ctx context.Context, logger *slog.Logger,
 	err = fmt.Errorf("convert PDF to '%+v' with multi PDF engines: %w", formats, err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 
@@ -189,8 +220,11 @@ type readMetadataResult struct {
 
 // ReadMetadata extracts metadata from a PDF file using the first available
 // engine that supports metadata reading.
+//
+//nolint:dupl
 func (multi *multiPdfEngines) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -208,9 +242,10 @@ func (multi *multiPdfEngines) ReadMetadata(ctx context.Context, logger *slog.Log
 		case result := <-resultChan:
 			if result.err != nil {
 				mu.Lock()
-				err = multierr.Append(err, result.err)
+				err = errors.Join(err, result.err)
 				mu.Unlock()
 			} else {
+				span.SetStatus(codes.Ok, "")
 				return result.metadata, nil
 			}
 		case <-ctx.Done():
@@ -221,13 +256,15 @@ func (multi *multiPdfEngines) ReadMetadata(ctx context.Context, logger *slog.Log
 	err = fmt.Errorf("read PDF metadata with multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return nil, err
 }
 
-// WriteMetadata attachments metadata into a PDF file using the first available
+// WriteMetadata embeds metadata into a PDF file using the first available
 // engine that supports metadata writing.
 func (multi *multiPdfEngines) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -240,8 +277,10 @@ func (multi *multiPdfEngines) WriteMetadata(ctx context.Context, logger *slog.Lo
 
 		select {
 		case writeMetadataErr := <-errChan:
-			errored := multierr.AppendInto(&err, writeMetadataErr)
-			if !errored {
+			if writeMetadataErr != nil {
+				err = errors.Join(err, writeMetadataErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -252,13 +291,142 @@ func (multi *multiPdfEngines) WriteMetadata(ctx context.Context, logger *slog.Lo
 	err = fmt.Errorf("write PDF metadata with multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
+	return err
+}
+
+type pageCountResult struct {
+	pageCount int
+	err       error
+}
+
+// PageCount returns the number of pages in a PDF file using the first available
+// engine that supports metadata reading.
+func (multi *multiPdfEngines) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.PageCount", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	var mu sync.Mutex // to safely append errors.
+
+	for _, engine := range multi.readMetadataEngines {
+		resultChan := make(chan pageCountResult, 1)
+
+		go func(engine gotenberg.PdfEngine) {
+			pageCount, err := engine.PageCount(ctx, logger, inputPath)
+			resultChan <- pageCountResult{pageCount: pageCount, err: err}
+		}(engine)
+
+		select {
+		case result := <-resultChan:
+			if result.err != nil {
+				mu.Lock()
+				err = errors.Join(err, result.err)
+				mu.Unlock()
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return result.pageCount, nil
+			}
+		case <-ctx.Done():
+			return 0, ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("page count with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
+	return 0, err
+}
+
+type readBookmarksResult struct {
+	bookmarks []gotenberg.Bookmark
+	err       error
+}
+
+// ReadBookmarks reads bookmarks from a PDF file using the first available
+// engine that supports bookmarks reading.
+//
+//nolint:dupl
+func (multi *multiPdfEngines) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.ReadBookmarks", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	var mu sync.Mutex // to safely append errors.
+
+	for _, engine := range multi.readBookmarksEngines {
+		resultChan := make(chan readBookmarksResult, 1)
+
+		go func(engine gotenberg.PdfEngine) {
+			bookmarks, err := engine.ReadBookmarks(ctx, logger, inputPath)
+			resultChan <- readBookmarksResult{bookmarks: bookmarks, err: err}
+		}(engine)
+
+		select {
+		case result := <-resultChan:
+			if result.err != nil {
+				mu.Lock()
+				err = errors.Join(err, result.err)
+				mu.Unlock()
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return result.bookmarks, nil
+			}
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("read PDF bookmarks with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
+	return nil, err
+}
+
+// WriteBookmarks adds a document outline (bookmarks) to a PDF file using the
+// first available engine that supports bookmarks writing.
+func (multi *multiPdfEngines) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.WriteBookmarks", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.writeBookmarksEngines {
+		go func(engine gotenberg.PdfEngine) {
+			errChan <- engine.WriteBookmarks(ctx, logger, inputPath, bookmarks)
+		}(engine)
+
+		select {
+		case writeBookmarksErr := <-errChan:
+			if writeBookmarksErr != nil {
+				err = errors.Join(err, writeBookmarksErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("write PDF bookmarks with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 
 // Encrypt adds password protection to a PDF file using the first available
 // engine that supports password protection.
 func (multi *multiPdfEngines) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
@@ -271,8 +439,10 @@ func (multi *multiPdfEngines) Encrypt(ctx context.Context, logger *slog.Logger,
 
 		select {
 		case protectErr := <-errChan:
-			errored := multierr.AppendInto(&err, protectErr)
-			if !errored {
+			if protectErr != nil {
+				err = errors.Join(err, protectErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -283,27 +453,33 @@ func (multi *multiPdfEngines) Encrypt(ctx context.Context, logger *slog.Logger,
 	err = fmt.Errorf("encrypt PDF using multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 
-// AddAttachments adds attachments into a PDF using the first available
-// engine that supports file attaching.
-func (multi *multiPdfEngines) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "multiPdfEngines.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
+// EmbedFiles embeds files into a PDF using the first available
+// engine that supports file embedding.
+//
+//nolint:dupl
+func (multi *multiPdfEngines) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.EmbedFiles", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
 
 	var err error
 	errChan := make(chan error, 1)
 
-	for _, engine := range multi.attachmentsEngines {
+	for _, engine := range multi.embedEngines {
 		go func(engine gotenberg.PdfEngine) {
-			errChan <- engine.AddAttachments(ctx, logger, filePaths, inputPath)
+			errChan <- engine.EmbedFiles(ctx, logger, filePaths, inputPath)
 		}(engine)
 
 		select {
-		case attachmentsErr := <-errChan:
-			errored := multierr.AppendInto(&err, attachmentsErr)
-			if !errored {
+		case embedErr := <-errChan:
+			if embedErr != nil {
+				err = errors.Join(err, embedErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
 				return nil
 			}
 		case <-ctx.Done():
@@ -311,9 +487,119 @@ func (multi *multiPdfEngines) AddAttachments(ctx context.Context, logger *slog.L
 		}
 	}
 
-	err = fmt.Errorf("add attachments into PDF using multi PDF engines: %w", err)
+	err = fmt.Errorf("embed files into PDF using multi PDF engines: %w", err)
 	span.RecordError(err)
 	span.SetStatus(codes.Error, err.Error())
+
+	return err
+}
+
+// Watermark applies a watermark (behind page content) to a PDF file using the
+// first available engine that supports watermarking.
+//
+//nolint:dupl
+func (multi *multiPdfEngines) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Watermark", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.watermarkEngines {
+		go func(engine gotenberg.PdfEngine) {
+			errChan <- engine.Watermark(ctx, logger, inputPath, stamp)
+		}(engine)
+
+		select {
+		case watermarkErr := <-errChan:
+			if watermarkErr != nil {
+				err = errors.Join(err, watermarkErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("watermark PDF with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
+	return err
+}
+
+// Stamp applies a stamp (on top of page content) to a PDF file using the
+// first available engine that supports stamping.
+//
+//nolint:dupl
+func (multi *multiPdfEngines) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Stamp", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.stampEngines {
+		go func(engine gotenberg.PdfEngine) {
+			errChan <- engine.Stamp(ctx, logger, inputPath, stamp)
+		}(engine)
+
+		select {
+		case stampErr := <-errChan:
+			if stampErr != nil {
+				err = errors.Join(err, stampErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("stamp PDF with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
+	return err
+}
+
+// Rotate rotates pages of a PDF file using the first available engine that
+// supports rotation.
+func (multi *multiPdfEngines) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "pdfengines.Rotate", trace.WithSpanKind(trace.SpanKindInternal))
+	defer span.End()
+
+	var err error
+	errChan := make(chan error, 1)
+
+	for _, engine := range multi.rotateEngines {
+		go func(engine gotenberg.PdfEngine) {
+			errChan <- engine.Rotate(ctx, logger, inputPath, angle, pages)
+		}(engine)
+
+		select {
+		case rotateErr := <-errChan:
+			if rotateErr != nil {
+				err = errors.Join(err, rotateErr)
+			} else {
+				span.SetStatus(codes.Ok, "")
+				return nil
+			}
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	err = fmt.Errorf("rotate PDF with multi PDF engines: %w", err)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+
 	return err
 }
 

pkg/modules/pdfengines/multi_test.go

@@ -1,650 +0,0 @@
-package pdfengines
-
-import (
-	"context"
-	"errors"
-	"log/slog"
-	"os"
-	"testing"
-
-	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
-)
-
-func TestMultiPdfEngines_Merge(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				mergeEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: false,
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				mergeEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: false,
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				mergeEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				mergeEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						MergeMock: func(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			err := tc.engine.Merge(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), nil, "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_Encrypt(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				passwordEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				passwordEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				passwordEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				passwordEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						EncryptMock: func(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			err := tc.engine.Encrypt(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), "", "", "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_Split(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				splitEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				splitEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				splitEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				splitEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						SplitMock: func(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-							return nil, nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			_, err := tc.engine.Split(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), gotenberg.SplitMode{}, "", "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_Flatten(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				flattenEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				flattenEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				flattenEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				flattenEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						FlattenMock: func(ctx context.Context, logger *slog.Logger, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			err := tc.engine.Flatten(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_Convert(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				convertEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				convertEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				convertEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				convertEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ConvertMock: func(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			err := tc.engine.Convert(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), gotenberg.PdfFormats{}, "", "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_ReadMetadata(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				readMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return make(map[string]any), nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				readMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return nil, errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return make(map[string]any), nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				readMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return nil, errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return nil, errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				readMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						ReadMetadataMock: func(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-							return make(map[string]any), nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			_, err := tc.engine.ReadMetadata(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}
-
-func TestMultiPdfEngines_WriteMetadata(t *testing.T) {
-	for _, tc := range []struct {
-		scenario    string
-		engine      *multiPdfEngines
-		ctx         context.Context
-		expectError bool
-	}{
-		{
-			scenario: "nominal behavior",
-			engine: &multiPdfEngines{
-				writeMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "at least one engine does not return an error",
-			engine: &multiPdfEngines{
-				writeMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: context.Background(),
-		},
-		{
-			scenario: "all engines return an error",
-			engine: &multiPdfEngines{
-				writeMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return errors.New("foo")
-						},
-					},
-				},
-			},
-			ctx:         context.Background(),
-			expectError: true,
-		},
-		{
-			scenario: "context expired",
-			engine: &multiPdfEngines{
-				writeMetadataEngines: []gotenberg.PdfEngine{
-					&gotenberg.PdfEngineMock{
-						WriteMetadataMock: func(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-							return nil
-						},
-					},
-				},
-			},
-			ctx: func() context.Context {
-				ctx, cancel := context.WithCancel(context.Background())
-				cancel()
-
-				return ctx
-			}(),
-			expectError: true,
-		},
-	} {
-		t.Run(tc.scenario, func(t *testing.T) {
-			err := tc.engine.WriteMetadata(tc.ctx, slog.New(slog.NewJSONHandler(os.Stdout, nil)), nil, "")
-
-			if !tc.expectError && err != nil {
-				t.Fatalf("expected no error but got: %v", err)
-			}
-
-			if tc.expectError && err == nil {
-				t.Fatal("expected error but got none")
-			}
-		})
-	}
-}

pkg/modules/pdfengines/pdfengines.go

@@ -28,16 +28,21 @@ func init() {
 // the [api.Router] interface to expose relevant PDF processing routes if
 // enabled.
 type PdfEngines struct {
-	mergeNames         []string
-	splitNames         []string
-	flattenNames       []string
-	convertNames       []string
-	readMetadataNames  []string
-	writeMetadataNames []string
-	encryptNames       []string
-	attachmentsNames   []string
-	engines            []gotenberg.PdfEngine
-	disableRoutes      bool
+	mergeNames          []string
+	splitNames          []string
+	flattenNames        []string
+	convertNames        []string
+	readMetadataNames   []string
+	writeMetadataNames  []string
+	encryptNames        []string
+	embedNames          []string
+	readBookmarksNames  []string
+	writeBookmarksNames []string
+	watermarkNames      []string
+	stampNames          []string
+	rotateNames         []string
+	engines             []gotenberg.PdfEngine
+	disableRoutes       bool
 }
 
 // Descriptor returns a PdfEngines' module descriptor.
@@ -52,10 +57,22 @@ func (mod *PdfEngines) Descriptor() gotenberg.ModuleDescriptor {
 			fs.StringSlice("pdfengines-convert-engines", []string{"libreoffice-pdfengine"}, "Set the PDF engines and their order for the convert feature - empty means all")
 			fs.StringSlice("pdfengines-read-metadata-engines", []string{"exiftool"}, "Set the PDF engines and their order for the read metadata feature - empty means all")
 			fs.StringSlice("pdfengines-write-metadata-engines", []string{"exiftool"}, "Set the PDF engines and their order for the write metadata feature - empty means all")
-			fs.StringSlice("pdfengines-encrypt-engines", []string{"qpdf", "pdfcpu", "pdftk"}, "Set the PDF engines and their order for the password protection feature - empty means all")
-			fs.StringSlice("pdfengines-add-attachments-engines", []string{"pdfcpu"}, "Set the PDF engines and their order for the file attaching feature - empty means all")
+			fs.StringSlice("pdfengines-encrypt-engines", []string{"qpdf", "pdftk", "pdfcpu"}, "Set the PDF engines and their order for the password protection feature - empty means all")
+			fs.StringSlice("pdfengines-embed-engines", []string{"pdfcpu"}, "Set the PDF engines and their order for the file embedding feature - empty means all")
+			fs.StringSlice("pdfengines-read-bookmarks-engines", []string{"pdfcpu"}, "Set the PDF engines and their order for the read bookmarks feature - empty means all")
+			fs.StringSlice("pdfengines-write-bookmarks-engines", []string{"pdfcpu"}, "Set the PDF engines and their order for the write bookmarks feature - empty means all")
+			fs.StringSlice("pdfengines-watermark-engines", []string{"pdfcpu", "pdftk"}, "Set the PDF engines and their order for the watermark feature - empty means all")
+			fs.StringSlice("pdfengines-stamp-engines", []string{"pdfcpu", "pdftk"}, "Set the PDF engines and their order for the stamp feature - empty means all")
+			fs.StringSlice("pdfengines-rotate-engines", []string{"pdfcpu", "pdftk"}, "Set the PDF engines and their order for the rotate feature - empty means all")
 			fs.Bool("pdfengines-disable-routes", false, "Disable the routes")
 
+			// Deprecated flags.
+			fs.StringSlice("pdfengines-engines", make([]string, 0), "Set the default PDF engines and their default order - all by default")
+			err := fs.MarkDeprecated("pdfengines-engines", "use other flags for a more granular selection of PDF engines per method")
+			if err != nil {
+				panic(err)
+			}
+
 			return fs
 		}(),
 		New: func() gotenberg.Module { return new(PdfEngines) },
@@ -73,7 +90,12 @@ func (mod *PdfEngines) Provision(ctx *gotenberg.Context) error {
 	readMetadataNames := flags.MustStringSlice("pdfengines-read-metadata-engines")
 	writeMetadataNames := flags.MustStringSlice("pdfengines-write-metadata-engines")
 	encryptNames := flags.MustStringSlice("pdfengines-encrypt-engines")
-	attachmentsNames := flags.MustStringSlice("pdfengines-add-attachments-engines")
+	embedNames := flags.MustStringSlice("pdfengines-embed-engines")
+	readBookmarksNames := flags.MustStringSlice("pdfengines-read-bookmarks-engines")
+	writeBookmarksNames := flags.MustStringSlice("pdfengines-write-bookmarks-engines")
+	watermarkNames := flags.MustStringSlice("pdfengines-watermark-engines")
+	stampNames := flags.MustStringSlice("pdfengines-stamp-engines")
+	rotateNames := flags.MustStringSlice("pdfengines-rotate-engines")
 	mod.disableRoutes = flags.MustBool("pdfengines-disable-routes")
 
 	engines, err := ctx.Modules(new(gotenberg.PdfEngine))
@@ -93,12 +115,12 @@ func (mod *PdfEngines) Provision(ctx *gotenberg.Context) error {
 	}
 
 	// Example in the case of deprecated module name.
-	//for i, name := range defaultNames {
-	//	if name == "unoconv-pdfengine" || name == "uno-pdfengine" {
-	//		logger.WarnContext(ctx, fmt.Sprintf("%s is deprecated; prefer libreoffice-pdfengine instead", name))
-	//		mod.defaultNames[i] = "libreoffice-pdfengine"
-	//	}
-	//}
+	// for i, name := range defaultNames {
+	// 	if name == "unoconv-pdfengine" || name == "uno-pdfengine" {
+	// 		logger.Warn(fmt.Sprintf("%s is deprecated; prefer libreoffice-pdfengine instead", name))
+	// 		mod.defaultNames[i] = "libreoffice-pdfengine"
+	// 	}
+	// }
 
 	mod.mergeNames = defaultNames
 	if len(mergeNames) > 0 {
@@ -135,9 +157,34 @@ func (mod *PdfEngines) Provision(ctx *gotenberg.Context) error {
 		mod.encryptNames = encryptNames
 	}
 
-	mod.attachmentsNames = defaultNames
-	if len(attachmentsNames) > 0 {
-		mod.attachmentsNames = attachmentsNames
+	mod.embedNames = defaultNames
+	if len(embedNames) > 0 {
+		mod.embedNames = embedNames
+	}
+
+	mod.readBookmarksNames = defaultNames
+	if len(readBookmarksNames) > 0 {
+		mod.readBookmarksNames = readBookmarksNames
+	}
+
+	mod.writeBookmarksNames = defaultNames
+	if len(writeBookmarksNames) > 0 {
+		mod.writeBookmarksNames = writeBookmarksNames
+	}
+
+	mod.watermarkNames = defaultNames
+	if len(watermarkNames) > 0 {
+		mod.watermarkNames = watermarkNames
+	}
+
+	mod.stampNames = defaultNames
+	if len(stampNames) > 0 {
+		mod.stampNames = stampNames
+	}
+
+	mod.rotateNames = defaultNames
+	if len(rotateNames) > 0 {
+		mod.rotateNames = rotateNames
 	}
 
 	return nil
@@ -188,7 +235,12 @@ func (mod *PdfEngines) Validate() error {
 	findNonExistingEngines(mod.readMetadataNames)
 	findNonExistingEngines(mod.writeMetadataNames)
 	findNonExistingEngines(mod.encryptNames)
-	findNonExistingEngines(mod.attachmentsNames)
+	findNonExistingEngines(mod.embedNames)
+	findNonExistingEngines(mod.readBookmarksNames)
+	findNonExistingEngines(mod.writeBookmarksNames)
+	findNonExistingEngines(mod.watermarkNames)
+	findNonExistingEngines(mod.stampNames)
+	findNonExistingEngines(mod.rotateNames)
 
 	if len(nonExistingEngines) == 0 {
 		return nil
@@ -201,13 +253,19 @@ func (mod *PdfEngines) Validate() error {
 // modules.
 func (mod *PdfEngines) SystemMessages() []string {
 	return []string{
-		fmt.Sprintf("merge engines - %s", strings.Join(mod.mergeNames[:], " ")),
-		fmt.Sprintf("split engines - %s", strings.Join(mod.splitNames[:], " ")),
-		fmt.Sprintf("flatten engines - %s", strings.Join(mod.flattenNames[:], " ")),
-		fmt.Sprintf("convert engines - %s", strings.Join(mod.convertNames[:], " ")),
-		fmt.Sprintf("read metadata engines - %s", strings.Join(mod.readMetadataNames[:], " ")),
-		fmt.Sprintf("write metadata engines - %s", strings.Join(mod.writeMetadataNames[:], " ")),
-		fmt.Sprintf("encrypt engines - %s", strings.Join(mod.encryptNames[:], " ")),
+		fmt.Sprintf("merge engines - %s", strings.Join(mod.mergeNames, " ")),
+		fmt.Sprintf("split engines - %s", strings.Join(mod.splitNames, " ")),
+		fmt.Sprintf("flatten engines - %s", strings.Join(mod.flattenNames, " ")),
+		fmt.Sprintf("convert engines - %s", strings.Join(mod.convertNames, " ")),
+		fmt.Sprintf("read metadata engines - %s", strings.Join(mod.readMetadataNames, " ")),
+		fmt.Sprintf("write metadata engines - %s", strings.Join(mod.writeMetadataNames, " ")),
+		fmt.Sprintf("encrypt engines - %s", strings.Join(mod.encryptNames, " ")),
+		fmt.Sprintf("embed engines - %s", strings.Join(mod.embedNames, " ")),
+		fmt.Sprintf("read bookmarks engines - %s", strings.Join(mod.readBookmarksNames, " ")),
+		fmt.Sprintf("write bookmarks engines - %s", strings.Join(mod.writeBookmarksNames, " ")),
+		fmt.Sprintf("watermark engines - %s", strings.Join(mod.watermarkNames, " ")),
+		fmt.Sprintf("stamp engines - %s", strings.Join(mod.stampNames, " ")),
+		fmt.Sprintf("rotate engines - %s", strings.Join(mod.rotateNames, " ")),
 	}
 }
 
@@ -235,7 +293,12 @@ func (mod *PdfEngines) PdfEngine() (gotenberg.PdfEngine, error) {
 		engines(mod.readMetadataNames),
 		engines(mod.writeMetadataNames),
 		engines(mod.encryptNames),
-		engines(mod.attachmentsNames),
+		engines(mod.embedNames),
+		engines(mod.readBookmarksNames),
+		engines(mod.writeBookmarksNames),
+		engines(mod.watermarkNames),
+		engines(mod.stampNames),
+		engines(mod.rotateNames),
 	), nil
 }
 
@@ -259,8 +322,13 @@ func (mod *PdfEngines) Routes() ([]api.Route, error) {
 		convertRoute(engine),
 		readMetadataRoute(engine),
 		writeMetadataRoute(engine),
+		readBookmarksRoute(engine),
+		writeBookmarksRoute(engine),
 		encryptRoute(engine),
-		attachmentsRoute(engine),
+		embedRoute(engine),
+		watermarkRoute(engine),
+		stampRoute(engine),
+		rotateRoute(engine),
 	}, nil
 }
 

pkg/modules/pdfengines/routes.go

@@ -5,10 +5,12 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
 
+	"github.com/google/uuid"
 	"github.com/labstack/echo/v4"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
@@ -84,7 +86,7 @@ func FormDataPdfSplitMode(form *api.FormData, mandatory bool) gotenberg.SplitMod
 }
 
 // FormDataPdfFormats creates [gotenberg.PdfFormats] from the form data.
-// Fallback to default value if the considered key is not present.
+// Fallback to the default value if the considered key is not present.
 func FormDataPdfFormats(form *api.FormData) gotenberg.PdfFormats {
 	var (
 		pdfa  string
@@ -128,6 +130,129 @@ func FormDataPdfMetadata(form *api.FormData, mandatory bool) map[string]any {
 	return metadata
 }
 
+// FormDataPdfBookmarks creates bookmarks from the form data.
+func FormDataPdfBookmarks(form *api.FormData, mandatory bool) any {
+	var bookmarks any
+
+	bookmarksFunc := func(value string) error {
+		if len(value) > 0 {
+			var list []gotenberg.Bookmark
+			err := json.Unmarshal([]byte(value), &list)
+			if err == nil {
+				bookmarks = list
+				return nil
+			}
+
+			var m map[string][]gotenberg.Bookmark
+			err = json.Unmarshal([]byte(value), &m)
+			if err == nil {
+				bookmarks = m
+				return nil
+			}
+
+			return fmt.Errorf("unmarshal bookmarks: %w", err)
+		}
+		return nil
+	}
+
+	if mandatory {
+		form.MandatoryCustom("bookmarks", func(value string) error {
+			return bookmarksFunc(value)
+		})
+	} else {
+		form.Custom("bookmarks", func(value string) error {
+			return bookmarksFunc(value)
+		})
+	}
+
+	return bookmarks
+}
+
+// FormDataPdfRotate creates rotation parameters from the form data.
+func FormDataPdfRotate(form *api.FormData, mandatory bool) (int, string) {
+	var angle int
+	var pages string
+
+	angleFunc := func(value string) error {
+		if value == "" {
+			return nil
+		}
+		v, err := strconv.Atoi(value)
+		if err != nil {
+			return err
+		}
+		if v != 90 && v != 180 && v != 270 {
+			return errors.New("wrong value, expected 90, 180, or 270")
+		}
+		angle = v
+		return nil
+	}
+
+	if mandatory {
+		form.MandatoryCustom("rotateAngle", func(value string) error {
+			return angleFunc(value)
+		})
+	} else {
+		form.Custom("rotateAngle", func(value string) error {
+			return angleFunc(value)
+		})
+	}
+	form.String("rotatePages", &pages, "")
+
+	return angle, pages
+}
+
+// RotateStub rotates pages of PDF files. If angle is 0, it does nothing.
+func RotateStub(ctx *api.Context, engine gotenberg.PdfEngine, angle int, pages string, inputPaths []string) error {
+	if angle == 0 {
+		return nil
+	}
+
+	for _, inputPath := range inputPaths {
+		err := engine.Rotate(ctx, ctx.Log(), inputPath, angle, pages)
+		if err != nil {
+			return fmt.Errorf("rotate '%s': %w", inputPath, err)
+		}
+	}
+
+	return nil
+}
+
+// ValidatePdfFormatsCompat checks for incompatible combinations of PDF formats
+// with other features and returns an appropriate error if found.
+func ValidatePdfFormatsCompat(pdfFormats gotenberg.PdfFormats, userPassword string, embedPaths []string) error {
+	zeroValued := gotenberg.PdfFormats{}
+	if pdfFormats == zeroValued {
+		return nil
+	}
+
+	// PDF/A forbids encryption per the standard.
+	if pdfFormats.PdfA != "" && userPassword != "" {
+		return api.WrapError(
+			errors.New("PDF/A format is incompatible with encryption"),
+			api.NewSentinelHttpError(
+				http.StatusBadRequest,
+				"Invalid form data: PDF/A format is incompatible with encryption",
+			),
+		)
+	}
+
+	// Only PDF/A-3 variants allow embedded file attachments.
+	if pdfFormats.PdfA != "" && len(embedPaths) > 0 {
+		if pdfFormats.PdfA != gotenberg.PdfA3a && pdfFormats.PdfA != gotenberg.PdfA3b && pdfFormats.PdfA != gotenberg.PdfA3u {
+			return api.WrapError(
+				fmt.Errorf("PDF format '%s' does not support embedded files", pdfFormats.PdfA),
+				api.NewSentinelHttpError(
+					http.StatusBadRequest,
+					fmt.Sprintf("Invalid form data: PDF format '%s' does not support embedded files; only PDF/A-3 variants allow attachments", pdfFormats.PdfA),
+				),
+			)
+		}
+	}
+
+	return nil
+}
+
 // MergeStub merges given PDFs. If only one input PDF, it does nothing and
 // returns the corresponding input path.
 func MergeStub(ctx *api.Context, engine gotenberg.PdfEngine, inputPaths []string) (string, error) {
@@ -159,9 +284,9 @@ func SplitPdfStub(ctx *api.Context, engine gotenberg.PdfEngine, mode gotenberg.S
 
 	var outputPaths []string
 	for _, inputPath := range inputPaths {
-		inputPathNoExt := inputPath[:len(inputPath)-len(filepath.Ext(inputPath))]
-		filenameNoExt := filepath.Base(inputPathNoExt)
-		outputDirPath, err := ctx.CreateSubDirectory(strings.ReplaceAll(filepath.Base(filenameNoExt), ".", "_"))
+		originalName := ctx.OriginalFilename(inputPath)
+		originalNameNoExt := strings.TrimSuffix(originalName, filepath.Ext(originalName))
+		outputDirPath, err := ctx.CreateSubDirectory(uuid.New().String())
 		if err != nil {
 			return nil, fmt.Errorf("create subdirectory from input path: %w", err)
 		}
@@ -174,15 +299,18 @@ func SplitPdfStub(ctx *api.Context, engine gotenberg.PdfEngine, mode gotenberg.S
 		// Keep the original filename.
 		for i, path := range paths {
 			var newPath string
+			var newOriginal string
 			if mode.Unify && mode.Mode == gotenberg.SplitModePages {
+				newOriginal = fmt.Sprintf("%s.pdf", originalNameNoExt)
 				newPath = fmt.Sprintf(
-					"%s/%s.pdf",
-					outputDirPath, filenameNoExt,
+					"%s/%s",
+					outputDirPath, uuid.New().String()+".pdf",
 				)
 			} else {
+				newOriginal = fmt.Sprintf("%s_%d.pdf", originalNameNoExt, i)
 				newPath = fmt.Sprintf(
-					"%s/%s_%d.pdf",
-					outputDirPath, filenameNoExt, i,
+					"%s/%s",
+					outputDirPath, uuid.New().String()+".pdf",
 				)
 			}
 
@@ -191,6 +319,7 @@ func SplitPdfStub(ctx *api.Context, engine gotenberg.PdfEngine, mode gotenberg.S
 				return nil, fmt.Errorf("rename path: %w", err)
 			}
 
+			ctx.RegisterDiskPath(newPath, newOriginal)
 			outputPaths = append(outputPaths, newPath)
 
 			if mode.Unify && mode.Mode == gotenberg.SplitModePages {
@@ -254,12 +383,64 @@ func WriteMetadataStub(ctx *api.Context, engine gotenberg.PdfEngine, metadata ma
 	return nil
 }
 
-// FormDataPdfAttachments extracts attached file paths from form data.
-// Only files uploaded with the "attachments" field name are included.
-func FormDataPdfAttachments(form *api.FormData) []string {
-	var attachmentsPaths []string
-	form.Attachments(&attachmentsPaths)
-	return attachmentsPaths
+func shiftBookmarks(bookmarks []gotenberg.Bookmark, offset int) []gotenberg.Bookmark {
+	if offset == 0 {
+		return bookmarks
+	}
+	shifted := make([]gotenberg.Bookmark, len(bookmarks))
+	for i, b := range bookmarks {
+		shifted[i] = gotenberg.Bookmark{
+			Title:    b.Title,
+			Page:     b.Page + offset,
+			Children: shiftBookmarks(b.Children, offset),
+		}
+	}
+	return shifted
+}
+
+// WriteBookmarksStub writes the bookmarks into PDF files. If no bookmarks, it
+// does nothing.
+func WriteBookmarksStub(ctx *api.Context, engine gotenberg.PdfEngine, bookmarks any, inputPaths []string) error {
+	if bookmarks == nil {
+		return nil
+	}
+
+	switch b := bookmarks.(type) {
+	case []gotenberg.Bookmark:
+		if len(b) == 0 {
+			return nil
+		}
+
+		for _, inputPath := range inputPaths {
+			err := engine.WriteBookmarks(ctx, ctx.Log(), inputPath, b)
+			if err != nil {
+				return fmt.Errorf("write bookmarks into '%s': %w", inputPath, err)
+			}
+		}
+	case map[string][]gotenberg.Bookmark:
+		for _, inputPath := range inputPaths {
+			filename := ctx.OriginalFilename(inputPath)
+			if specificBookmarks, ok := b[filename]; ok {
+				err := engine.WriteBookmarks(ctx, ctx.Log(), inputPath, specificBookmarks)
+				if err != nil {
+					return fmt.Errorf("write bookmarks into '%s': %w", inputPath, err)
+				}
+			}
+		}
+	default:
+		// Should not happen.
+		return fmt.Errorf("bookmarks type '%T' not supported", bookmarks)
+	}
+
+	return nil
+}
+
+// FormDataPdfEmbeds extracts embedded file paths from form data.
+// Only files uploaded with the "embeds" field name are included.
+func FormDataPdfEmbeds(form *api.FormData) []string {
+	var embedPaths []string
+	form.Embeds(&embedPaths)
+	return embedPaths
 }
 
 // FormDataPdfEncrypt extracts encryption parameters from form data.
@@ -285,16 +466,152 @@ func EncryptPdfStub(ctx *api.Context, engine gotenberg.PdfEngine, userPassword,
 	return nil
 }
 
-// AddAttachmentsStub adds attachments into PDF files.
-func AddAttachmentsStub(ctx *api.Context, engine gotenberg.PdfEngine, attachmentsPaths []string, inputPaths []string) error {
-	if len(attachmentsPaths) == 0 {
+// EmbedFilesStub embeds files into PDF files.
+func EmbedFilesStub(ctx *api.Context, engine gotenberg.PdfEngine, embedPaths []string, inputPaths []string) error {
+	if len(embedPaths) == 0 {
+		return nil
+	}
+
+	// Engines like pdfcpu use filepath.Base(path) as the attachment name
+	// inside the PDF. Since disk filenames are now UUID-based, we create
+	// symlinks with the original names so that embeds are named correctly.
+	// See: https://github.com/gotenberg/gotenberg/issues/1500.
+	embedDir, err := ctx.CreateSubDirectory(uuid.New().String())
+	if err != nil {
+		return fmt.Errorf("create embed subdirectory: %w", err)
+	}
+
+	resolvedPaths := make([]string, len(embedPaths))
+	for i, embedPath := range embedPaths {
+		originalName := ctx.OriginalFilename(embedPath)
+		resolvedPath := fmt.Sprintf("%s/%s", embedDir, originalName)
+		err := os.Symlink(embedPath, resolvedPath)
+		if err != nil {
+			return fmt.Errorf("symlink embed file '%s': %w", originalName, err)
+		}
+		resolvedPaths[i] = resolvedPath
+	}
+
+	for _, inputPath := range inputPaths {
+		err := engine.EmbedFiles(ctx, ctx.Log(), resolvedPaths, inputPath)
+		if err != nil {
+			return fmt.Errorf("embed files into PDF '%s': %w", inputPath, err)
+		}
+	}
+
+	return nil
+}
+
+// FormDataPdfWatermark creates a [gotenberg.Stamp] for watermarking from the
+// form data.
+func FormDataPdfWatermark(form *api.FormData, mandatory bool) gotenberg.Stamp {
+	return formDataPdfStampOrWatermark(form, "watermark", mandatory)
+}
+
+// FormDataPdfStamp creates a [gotenberg.Stamp] for stamping from the form data.
+func FormDataPdfStamp(form *api.FormData, mandatory bool) gotenberg.Stamp {
+	return formDataPdfStampOrWatermark(form, "stamp", mandatory)
+}
+
+func formDataPdfStampOrWatermark(form *api.FormData, prefix string, mandatory bool) gotenberg.Stamp {
+	var (
+		source     string
+		expression string
+		pages      string
+		options    map[string]string
+	)
+
+	sourceFunc := func(value string) error {
+		if value != "" && value != gotenberg.StampSourceText && value != gotenberg.StampSourceImage && value != gotenberg.StampSourcePDF {
+			return fmt.Errorf("wrong value, expected either '%s', '%s' or '%s'", gotenberg.StampSourceText, gotenberg.StampSourceImage, gotenberg.StampSourcePDF)
+		}
+		source = value
+		return nil
+	}
+
+	optionsFunc := func(value string) error {
+		if value == "" {
+			return nil
+		}
+		err := json.Unmarshal([]byte(value), &options)
+		if err != nil {
+			return fmt.Errorf("unmarshal %s options: %w", prefix, err)
+		}
+		return nil
+	}
+
+	if mandatory {
+		form.
+			MandatoryCustom(prefix+"Source", func(value string) error {
+				return sourceFunc(value)
+			}).
+			String(prefix+"Expression", &expression, "").
+			String(prefix+"Pages", &pages, "").
+			Custom(prefix+"Options", func(value string) error {
+				return optionsFunc(value)
+			})
+	} else {
+		form.
+			Custom(prefix+"Source", func(value string) error {
+				return sourceFunc(value)
+			}).
+			String(prefix+"Expression", &expression, "").
+			String(prefix+"Pages", &pages, "").
+			Custom(prefix+"Options", func(value string) error {
+				return optionsFunc(value)
+			})
+	}
+
+	return gotenberg.Stamp{
+		Source:     source,
+		Expression: expression,
+		Pages:      pages,
+		Options:    options,
+	}
+}
+
+// FormDataPdfWatermarkFile extracts the watermark file path from form data.
+func FormDataPdfWatermarkFile(form *api.FormData) string {
+	var path string
+	form.Watermark(&path)
+	return path
+}
+
+// FormDataPdfStampFile extracts the stamp file path from form data.
+func FormDataPdfStampFile(form *api.FormData) string {
+	var path string
+	form.Stamp(&path)
+	return path
+}
+
+// WatermarkStub applies a watermark to a list of PDF files. If the stamp has
+// no source, it does nothing.
+func WatermarkStub(ctx *api.Context, engine gotenberg.PdfEngine, stamp gotenberg.Stamp, inputPaths []string) error {
+	if stamp.Source == "" {
 		return nil
 	}
 
 	for _, inputPath := range inputPaths {
-		err := engine.AddAttachments(ctx, ctx.Log(), attachmentsPaths, inputPath)
+		err := engine.Watermark(ctx, ctx.Log(), inputPath, stamp)
 		if err != nil {
-			return fmt.Errorf("add attachments into PDF '%s': %w", inputPath, err)
+			return fmt.Errorf("watermark '%s': %w", inputPath, err)
+		}
+	}
+
+	return nil
+}
+
+// StampStub applies a stamp to a list of PDF files. If the stamp has
+// no source, it does nothing.
+func StampStub(ctx *api.Context, engine gotenberg.PdfEngine, stamp gotenberg.Stamp, inputPaths []string) error {
+	if stamp.Source == "" {
+		return nil
+	}
+
+	for _, inputPath := range inputPaths {
+		err := engine.Stamp(ctx, ctx.Log(), inputPath, stamp)
+		if err != nil {
+			return fmt.Errorf("stamp '%s': %w", inputPath, err)
 		}
 	}
 
@@ -313,38 +630,60 @@ func mergeRoute(engine gotenberg.PdfEngine) api.Route {
 			form := ctx.FormData()
 			pdfFormats := FormDataPdfFormats(form)
 			metadata := FormDataPdfMetadata(form, false)
+			bookmarks := FormDataPdfBookmarks(form, false)
 			userPassword, ownerPassword := FormDataPdfEncrypt(form)
-			attachmentsPaths := FormDataPdfAttachments(form)
+			embedPaths := FormDataPdfEmbeds(form)
+			watermark := FormDataPdfWatermark(form, false)
+			watermarkFile := FormDataPdfWatermarkFile(form)
+			stamp := FormDataPdfStamp(form, false)
+			stampFile := FormDataPdfStampFile(form)
+			angle, rotatePages := FormDataPdfRotate(form, false)
 
 			var inputPaths []string
 			var flatten bool
+			var autoIndexBookmarks bool
 			err := form.
 				MandatoryPaths([]string{".pdf"}, &inputPaths).
 				Bool("flatten", &flatten, false).
+				Bool("autoIndexBookmarks", &autoIndexBookmarks, false).
 				Validate()
 			if err != nil {
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
+			err = ValidatePdfFormatsCompat(pdfFormats, userPassword, embedPaths)
+			if err != nil {
+				return err
+			}
+
 			outputPath := ctx.GeneratePath(".pdf")
 			err = engine.Merge(ctx, ctx.Log(), inputPaths, outputPath)
 			if err != nil {
 				return fmt.Errorf("merge PDFs: %w", err)
 			}
 
-			outputPaths, err := ConvertStub(ctx, engine, pdfFormats, []string{outputPath})
+			outputPaths := []string{outputPath}
+
+			err = WatermarkStub(ctx, engine, watermark, outputPaths)
 			if err != nil {
-				return fmt.Errorf("convert PDF: %w", err)
+				return fmt.Errorf("watermark PDFs: %w", err)
 			}
 
-			err = AddAttachmentsStub(ctx, engine, attachmentsPaths, outputPaths)
+			err = StampStub(ctx, engine, stamp, outputPaths)
 			if err != nil {
-				return fmt.Errorf("add attachments into PDFs: %w", err)
+				return fmt.Errorf("stamp PDFs: %w", err)
 			}
 
-			err = WriteMetadataStub(ctx, engine, metadata, outputPaths)
+			err = RotateStub(ctx, engine, angle, rotatePages, outputPaths)
 			if err != nil {
-				return fmt.Errorf("write metadata: %w", err)
+				return fmt.Errorf("rotate PDFs: %w", err)
 			}
 
 			if flatten {
@@ -354,6 +693,67 @@ func mergeRoute(engine gotenberg.PdfEngine) api.Route {
 				}
 			}
 
+			outputPaths, err = ConvertStub(ctx, engine, pdfFormats, outputPaths)
+			if err != nil {
+				return fmt.Errorf("convert PDF: %w", err)
+			}
+
+			// Bookmarks, metadata, and embeds are written after Convert,
+			// as LibreOffice strips them during PDF/A conversion.
+
+			var finalBookmarks []gotenberg.Bookmark
+			if b, ok := bookmarks.([]gotenberg.Bookmark); ok {
+				finalBookmarks = b
+			} else {
+				bMap, _ := bookmarks.(map[string][]gotenberg.Bookmark)
+				if bMap != nil || autoIndexBookmarks {
+					offset := 0
+					for _, inputPath := range inputPaths {
+						filename := ctx.OriginalFilename(inputPath)
+
+						var fileBookmarks []gotenberg.Bookmark
+						if bMap != nil {
+							fileBookmarks = bMap[filename]
+						}
+
+						if len(fileBookmarks) == 0 && autoIndexBookmarks {
+							fb, err := engine.ReadBookmarks(ctx, ctx.Log(), inputPath)
+							if err != nil {
+								return fmt.Errorf("read bookmarks of '%s': %w", filename, err)
+							}
+							fileBookmarks = fb
+						}
+
+						if len(fileBookmarks) > 0 {
+							finalBookmarks = append(finalBookmarks, shiftBookmarks(fileBookmarks, offset)...)
+						}
+
+						pageCount, err := engine.PageCount(ctx, ctx.Log(), inputPath)
+						if err != nil {
+							return fmt.Errorf("get page count of '%s': %w", filename, err)
+						}
+						offset += pageCount
+					}
+				}
+			}
+
+			if len(finalBookmarks) > 0 {
+				err = WriteBookmarksStub(ctx, engine, finalBookmarks, outputPaths)
+				if err != nil {
+					return fmt.Errorf("write bookmarks: %w", err)
+				}
+			}
+
+			err = WriteMetadataStub(ctx, engine, metadata, outputPaths)
+			if err != nil {
+				return fmt.Errorf("write metadata: %w", err)
+			}
+
+			err = EmbedFilesStub(ctx, engine, embedPaths, outputPaths)
+			if err != nil {
+				return fmt.Errorf("embed files into PDFs: %w", err)
+			}
+
 			err = EncryptPdfStub(ctx, engine, userPassword, ownerPassword, outputPaths)
 			if err != nil {
 				return fmt.Errorf("encrypt PDFs: %w", err)
@@ -383,7 +783,12 @@ func splitRoute(engine gotenberg.PdfEngine) api.Route {
 			pdfFormats := FormDataPdfFormats(form)
 			metadata := FormDataPdfMetadata(form, false)
 			userPassword, ownerPassword := FormDataPdfEncrypt(form)
-			attachmentsPaths := FormDataPdfAttachments(form)
+			embedPaths := FormDataPdfEmbeds(form)
+			watermark := FormDataPdfWatermark(form, false)
+			watermarkFile := FormDataPdfWatermarkFile(form)
+			stamp := FormDataPdfStamp(form, false)
+			stampFile := FormDataPdfStampFile(form)
+			angle, rotatePages := FormDataPdfRotate(form, false)
 
 			var inputPaths []string
 			var flatten bool
@@ -395,31 +800,60 @@ func splitRoute(engine gotenberg.PdfEngine) api.Route {
 				return fmt.Errorf("validate form data: %w", err)
 			}
 
+			if (watermark.Source == gotenberg.StampSourceImage || watermark.Source == gotenberg.StampSourcePDF) && watermarkFile != "" {
+				watermark.Expression = watermarkFile
+			}
+			if (stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF) && stampFile != "" {
+				stamp.Expression = stampFile
+			}
+
+			err = ValidatePdfFormatsCompat(pdfFormats, userPassword, embedPaths)
+			if err != nil {
+				return err
+			}
+
 			outputPaths, err := SplitPdfStub(ctx, engine, mode, inputPaths)
 			if err != nil {
 				return fmt.Errorf("split PDFs: %w", err)
 			}
 
+			err = WatermarkStub(ctx, engine, watermark, outputPaths)
+			if err != nil {
+				return fmt.Errorf("watermark PDFs: %w", err)
+			}
+
+			err = StampStub(ctx, engine, stamp, outputPaths)
+			if err != nil {
+				return fmt.Errorf("stamp PDFs: %w", err)
+			}
+
+			err = RotateStub(ctx, engine, angle, rotatePages, outputPaths)
+			if err != nil {
+				return fmt.Errorf("rotate PDFs: %w", err)
+			}
+
+			if flatten {
+				err = FlattenStub(ctx, engine, outputPaths)
+				if err != nil {
+					return fmt.Errorf("flatten PDFs: %w", err)
+				}
+			}
+
 			convertOutputPaths, err := ConvertStub(ctx, engine, pdfFormats, outputPaths)
 			if err != nil {
 				return fmt.Errorf("convert PDFs: %w", err)
 			}
 
-			err = AddAttachmentsStub(ctx, engine, attachmentsPaths, convertOutputPaths)
-			if err != nil {
-				return fmt.Errorf("add attachments into PDFs: %w", err)
-			}
-
+			// Metadata, embeds are written after Convert, as LibreOffice
+			// strips them during PDF/A conversion.
 			err = WriteMetadataStub(ctx, engine, metadata, convertOutputPaths)
 			if err != nil {
 				return fmt.Errorf("write metadata: %w", err)
 			}
 
-			if flatten {
-				err = FlattenStub(ctx, engine, convertOutputPaths)
-				if err != nil {
-					return fmt.Errorf("flatten PDFs: %w", err)
-				}
+			err = EmbedFilesStub(ctx, engine, embedPaths, convertOutputPaths)
+			if err != nil {
+				return fmt.Errorf("embed files into PDFs: %w", err)
 			}
 
 			err = EncryptPdfStub(ctx, engine, userPassword, ownerPassword, convertOutputPaths)
@@ -565,7 +999,7 @@ func readMetadataRoute(engine gotenberg.PdfEngine) api.Route {
 					return fmt.Errorf("read metadata: %w", err)
 				}
 
-				res[filepath.Base(inputPath)] = metadata
+				res[ctx.OriginalFilename(inputPath)] = metadata
 			}
 
 			err = c.JSON(http.StatusOK, res)
@@ -619,6 +1053,83 @@ func writeMetadataRoute(engine gotenberg.PdfEngine) api.Route {
 	}
 }
 
+// readBookmarksRoute returns an [api.Route] which returns the bookmarks of PDFs.
+func readBookmarksRoute(engine gotenberg.PdfEngine) api.Route {
+	return api.Route{
+		Method:      http.MethodPost,
+		Path:        "/forms/pdfengines/bookmarks/read",
+		IsMultipart: true,
+		Handler: func(c echo.Context) error {
+			ctx := c.Get("context").(*api.Context)
+
+			var inputPaths []string
+			err := ctx.FormData().
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				Validate()
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			res := make(map[string][]gotenberg.Bookmark, len(inputPaths))
+			for _, inputPath := range inputPaths {
+				bookmarks, err := engine.ReadBookmarks(ctx, ctx.Log(), inputPath)
+				if err != nil {
+					return fmt.Errorf("read bookmarks: %w", err)
+				}
+
+				res[ctx.OriginalFilename(inputPath)] = bookmarks
+			}
+
+			err = c.JSON(http.StatusOK, res)
+			if err != nil {
+				if strings.Contains(err.Error(), "request method or response status code does not allow body") {
+					// High probability that the user is using the webhook
+					// feature. It does not make sense for this route.
+					return api.ErrNoOutputFile
+				}
+				return fmt.Errorf("return JSON response: %w", err)
+			}
+
+			return api.ErrNoOutputFile
+		},
+	}
+}
+
+// writeBookmarksRoute returns an [api.Route] which can write bookmarks into PDFs.
+func writeBookmarksRoute(engine gotenberg.PdfEngine) api.Route {
+	return api.Route{
+		Method:      http.MethodPost,
+		Path:        "/forms/pdfengines/bookmarks/write",
+		IsMultipart: true,
+		Handler: func(c echo.Context) error {
+			ctx := c.Get("context").(*api.Context)
+
+			form := ctx.FormData()
+			bookmarks := FormDataPdfBookmarks(form, true)
+
+			var inputPaths []string
+			err := form.
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				Validate()
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			err = WriteBookmarksStub(ctx, engine, bookmarks, inputPaths)
+			if err != nil {
+				return fmt.Errorf("write bookmarks: %w", err)
+			}
+
+			err = ctx.AddOutputPaths(inputPaths...)
+			if err != nil {
+				return fmt.Errorf("add output paths: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
 // encryptRoute returns an [api.Route] which can add password protection to PDFs.
 func encryptRoute(engine gotenberg.PdfEngine) api.Route {
 	return api.Route{
@@ -657,17 +1168,18 @@ func encryptRoute(engine gotenberg.PdfEngine) api.Route {
 	}
 }
 
-// attachmentsRoute returns an [api.Route] which can add attached files to PDFs.
-func attachmentsRoute(engine gotenberg.PdfEngine) api.Route {
+// embedRoute returns an [api.Route] which can add embedded files to PDFs.
+// TODO: attachments instead?
+func embedRoute(engine gotenberg.PdfEngine) api.Route {
 	return api.Route{
 		Method:      http.MethodPost,
-		Path:        "/forms/pdfengines/attachments/add",
+		Path:        "/forms/pdfengines/embed",
 		IsMultipart: true,
 		Handler: func(c echo.Context) error {
 			ctx := c.Get("context").(*api.Context)
 
 			form := ctx.FormData()
-			attachmentsPaths := FormDataPdfAttachments(form)
+			embedPaths := FormDataPdfEmbeds(form)
 
 			var inputPaths []string
 			err := form.
@@ -676,10 +1188,146 @@ func attachmentsRoute(engine gotenberg.PdfEngine) api.Route {
 			if err != nil {
 				return fmt.Errorf("validate form data: %w", err)
 			}
-
-			err = AddAttachmentsStub(ctx, engine, attachmentsPaths, inputPaths)
+			err = EmbedFilesStub(ctx, engine, embedPaths, inputPaths)
 			if err != nil {
-				return fmt.Errorf("add attachments into PDFs: %w", err)
+				return fmt.Errorf("embed files into PDFs: %w", err)
+			}
+
+			err = ctx.AddOutputPaths(inputPaths...)
+			if err != nil {
+				return fmt.Errorf("add output paths: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// watermarkRoute returns an [api.Route] which can add watermarks to PDFs.
+//
+//nolint:dupl
+func watermarkRoute(engine gotenberg.PdfEngine) api.Route {
+	return api.Route{
+		Method:      http.MethodPost,
+		Path:        "/forms/pdfengines/watermark",
+		IsMultipart: true,
+		Handler: func(c echo.Context) error {
+			ctx := c.Get("context").(*api.Context)
+
+			form := ctx.FormData()
+			stamp := FormDataPdfWatermark(form, true)
+			watermarkFile := FormDataPdfWatermarkFile(form)
+
+			var inputPaths []string
+			err := form.
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				Validate()
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			if stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF {
+				if watermarkFile == "" {
+					return api.WrapError(
+						errors.New("no watermark file provided"),
+						api.NewSentinelHttpError(
+							http.StatusBadRequest,
+							"Invalid form data: a watermark file is required for image or pdf source",
+						),
+					)
+				}
+				stamp.Expression = watermarkFile
+			}
+
+			err = WatermarkStub(ctx, engine, stamp, inputPaths)
+			if err != nil {
+				return fmt.Errorf("watermark PDFs: %w", err)
+			}
+
+			err = ctx.AddOutputPaths(inputPaths...)
+			if err != nil {
+				return fmt.Errorf("add output paths: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// stampRoute returns an [api.Route] which can add stamps to PDFs.
+//
+//nolint:dupl
+func stampRoute(engine gotenberg.PdfEngine) api.Route {
+	return api.Route{
+		Method:      http.MethodPost,
+		Path:        "/forms/pdfengines/stamp",
+		IsMultipart: true,
+		Handler: func(c echo.Context) error {
+			ctx := c.Get("context").(*api.Context)
+
+			form := ctx.FormData()
+			stamp := FormDataPdfStamp(form, true)
+			stampFile := FormDataPdfStampFile(form)
+
+			var inputPaths []string
+			err := form.
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				Validate()
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			if stamp.Source == gotenberg.StampSourceImage || stamp.Source == gotenberg.StampSourcePDF {
+				if stampFile == "" {
+					return api.WrapError(
+						errors.New("no stamp file provided"),
+						api.NewSentinelHttpError(
+							http.StatusBadRequest,
+							"Invalid form data: a stamp file is required for image or pdf source",
+						),
+					)
+				}
+				stamp.Expression = stampFile
+			}
+
+			err = StampStub(ctx, engine, stamp, inputPaths)
+			if err != nil {
+				return fmt.Errorf("stamp PDFs: %w", err)
+			}
+
+			err = ctx.AddOutputPaths(inputPaths...)
+			if err != nil {
+				return fmt.Errorf("add output paths: %w", err)
+			}
+
+			return nil
+		},
+	}
+}
+
+// rotateRoute returns an [api.Route] which can rotate pages of PDFs.
+func rotateRoute(engine gotenberg.PdfEngine) api.Route {
+	return api.Route{
+		Method:      http.MethodPost,
+		Path:        "/forms/pdfengines/rotate",
+		IsMultipart: true,
+		Handler: func(c echo.Context) error {
+			ctx := c.Get("context").(*api.Context)
+
+			form := ctx.FormData()
+			angle, pages := FormDataPdfRotate(form, true)
+
+			var inputPaths []string
+			err := form.
+				MandatoryPaths([]string{".pdf"}, &inputPaths).
+				Validate()
+			if err != nil {
+				return fmt.Errorf("validate form data: %w", err)
+			}
+
+			err = RotateStub(ctx, engine, angle, pages, inputPaths)
+			if err != nil {
+				return fmt.Errorf("rotate PDFs: %w", err)
 			}
 
 			err = ctx.AddOutputPaths(inputPaths...)

pkg/modules/pdftk/pdftk.go

@@ -12,6 +12,7 @@ import (
 	"syscall"
 
 	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
@@ -82,7 +83,10 @@ func (engine *PdfTk) Debug() map[string]any {
 
 // Split splits a given PDF file.
 func (engine *PdfTk) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfTk.Split", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Split",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	var args []string
@@ -120,12 +124,16 @@ func (engine *PdfTk) Split(ctx context.Context, logger *slog.Logger, mode gotenb
 		return nil, err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return []string{outputPath}, nil
 }
 
 // Merge combines multiple PDFs into a single PDF.
 func (engine *PdfTk) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfTk.Merge", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Merge",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	args := make([]string, 0, 3+len(inputPaths))
@@ -142,76 +150,120 @@ func (engine *PdfTk) Merge(ctx context.Context, logger *slog.Logger, inputPaths
 
 	_, err = cmd.Exec()
 	if err == nil {
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
 	err = fmt.Errorf("merge PDFs with PDFtk: %w", err)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Flatten is not available in this implementation.
 func (engine *PdfTk) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfTk.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.Flatten",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("flatten PDF with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Convert is not available in this implementation.
 func (engine *PdfTk) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfTk.Convert", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.Convert",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("convert PDF to '%+v' with PDFtk: %w", formats, gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // ReadMetadata is not available in this implementation.
 func (engine *PdfTk) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfTk.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.ReadMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("read PDF metadata with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return nil, err
 }
 
 // WriteMetadata is not available in this implementation.
 func (engine *PdfTk) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfTk.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.WriteMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("write PDF metadata with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
+// PageCount is not available in this implementation.
+func (engine *PdfTk) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.PageCount",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("page count with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return 0, err
+}
+
+// WriteBookmarks is not available in this implementation.
+func (engine *PdfTk) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.WriteBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("write PDF bookmarks with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// ReadBookmarks is not available in this implementation.
+func (engine *PdfTk) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.ReadBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("read PDF bookmarks with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return nil, err
+}
+
 // Encrypt adds password protection to a PDF file using PDFtk.
 func (engine *PdfTk) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "PdfTk.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Encrypt",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	if userPassword == "" {
@@ -262,21 +314,185 @@ func (engine *PdfTk) Encrypt(ctx context.Context, logger *slog.Logger, inputPath
 		return err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return nil
 }
 
-// AddAttachments is not available in this implementation.
-func (engine *PdfTk) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "PdfTk.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
+// EmbedFiles is not available in this implementation.
+func (engine *PdfTk) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	_, span := gotenberg.Tracer().Start(ctx, "pdftk.EmbedFiles",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
-	err := fmt.Errorf("add attachments with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
+	err := fmt.Errorf("embed files with PDFtk: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// Watermark applies a watermark (behind page content) to a PDF file using PDFtk.
+// Only PDF source is supported.
+//
+//nolint:dupl
+func (engine *PdfTk) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Watermark",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	if stamp.Source != gotenberg.StampSourcePDF {
+		err := fmt.Errorf("watermark PDF with PDFtk: %w", gotenberg.ErrPdfStampSourceNotSupported)
 		span.RecordError(err)
 		span.SetStatus(codes.Error, err.Error())
+		return err
 	}
 
-	return err
+	tmpPath := inputPath + ".tmp"
+
+	args := []string{inputPath, "background", stamp.Expression, "output", tmpPath}
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	_, err = cmd.Exec()
+	if err != nil {
+		err = fmt.Errorf("watermark PDF with PDFtk: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	err = os.Rename(tmpPath, inputPath)
+	if err != nil {
+		err = fmt.Errorf("rename temporary output file with input file: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// Stamp applies a stamp (on top of page content) to a PDF file using PDFtk.
+// Only PDF source is supported.
+//
+//nolint:dupl
+func (engine *PdfTk) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Stamp",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	if stamp.Source != gotenberg.StampSourcePDF {
+		err := fmt.Errorf("stamp PDF with PDFtk: %w", gotenberg.ErrPdfStampSourceNotSupported)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	tmpPath := inputPath + ".tmp"
+
+	args := []string{inputPath, "stamp", stamp.Expression, "output", tmpPath}
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	_, err = cmd.Exec()
+	if err != nil {
+		err = fmt.Errorf("stamp PDF with PDFtk: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	err = os.Rename(tmpPath, inputPath)
+	if err != nil {
+		err = fmt.Errorf("rename temporary output file with input file: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
+}
+
+// Rotate rotates all pages of a PDF file by the given angle using PDFtk.
+// Page-specific rotation is not supported; if pages is non-empty,
+// ErrPdfEngineMethodNotSupported is returned.
+func (engine *PdfTk) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	ctx, span := gotenberg.Tracer().Start(ctx, "pdftk.Rotate",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	if pages != "" {
+		err := fmt.Errorf("rotate PDF with PDFtk (page-specific rotation): %w", gotenberg.ErrPdfEngineMethodNotSupported)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	var direction string
+	switch angle {
+	case 90:
+		direction = "east"
+	case 180:
+		direction = "south"
+	case 270:
+		direction = "west"
+	default:
+		err := fmt.Errorf("rotate PDF with PDFtk: %w", gotenberg.ErrPdfRotateAngleNotSupported)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	tmpPath := inputPath + ".tmp"
+	args := []string{inputPath, "cat", "1-end" + direction, "output", tmpPath}
+
+	cmd, err := gotenberg.CommandContext(ctx, logger, engine.binPath, args...)
+	if err != nil {
+		err = fmt.Errorf("create command: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	_, err = cmd.Exec()
+	if err != nil {
+		err = fmt.Errorf("rotate PDF with PDFtk: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	err = os.Rename(tmpPath, inputPath)
+	if err != nil {
+		err = fmt.Errorf("rename temporary output file with input file: %w", err)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	span.SetStatus(codes.Ok, "")
+	return nil
 }
 
 // Interface guards.

pkg/modules/prometheus/doc.go

@@ -0,0 +1,5 @@
+// Package prometheus provides a module which collects metrics and exposes them
+// via an HTTP route.
+//
+// See: https://prometheus.io/.
+package prometheus

pkg/modules/prometheus/prometheus.go

@@ -0,0 +1,205 @@
+package prometheus
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/labstack/echo/v4"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+	flag "github.com/spf13/pflag"
+
+	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
+	"github.com/gotenberg/gotenberg/v8/pkg/modules/api"
+)
+
+func init() {
+	gotenberg.MustRegisterModule(new(Prometheus))
+}
+
+// Prometheus is a module that collects metrics and exposes them via an HTTP
+// route.
+type Prometheus struct {
+	namespace             string
+	interval              time.Duration
+	disableRouteTelemetry bool
+	disableCollect        bool
+	metricsPath           string
+
+	metrics  []gotenberg.Metric
+	registry *prometheus.Registry
+}
+
+// Descriptor returns a [Prometheus]'s module descriptor.
+func (mod *Prometheus) Descriptor() gotenberg.ModuleDescriptor {
+	return gotenberg.ModuleDescriptor{
+		ID: "prometheus",
+		FlagSet: func() *flag.FlagSet {
+			fs := flag.NewFlagSet("prometheus", flag.ExitOnError)
+			fs.String("prometheus-namespace", "gotenberg", "Set the namespace of modules' metrics")
+			fs.Duration("prometheus-collect-interval", time.Duration(1)*time.Second, "Set the interval for collecting modules' metrics")
+			fs.Bool("prometheus-disable-route-telemetry", true, "Disable telemetry for the Prometheus metrics route")
+			fs.Bool("prometheus-disable-collect", false, "Disable the collect of metrics")
+			fs.String("prometheus-metrics-path", "/prometheus/metrics", "Path for Prometheus metrics endpoint")
+
+			// Deprecated flags.
+			fs.Bool("prometheus-disable-route-logging", false, "Disable the route logging")
+
+			err := fs.MarkDeprecated("prometheus-disable-route-logging", "use --prometheus-disable-route-telemetry instead")
+			if err != nil {
+				panic(err)
+			}
+
+			return fs
+		}(),
+		New: func() gotenberg.Module { return new(Prometheus) },
+	}
+}
+
+// Provision sets the module properties.
+func (mod *Prometheus) Provision(ctx *gotenberg.Context) error {
+	flags := ctx.ParsedFlags()
+	mod.namespace = flags.MustString("prometheus-namespace")
+	mod.interval = flags.MustDuration("prometheus-collect-interval")
+	mod.disableRouteTelemetry = flags.MustDeprecatedBool("prometheus-disable-route-logging", "prometheus-disable-route-telemetry")
+	mod.disableCollect = flags.MustBool("prometheus-disable-collect")
+	mod.metricsPath = flags.MustString("prometheus-metrics-path")
+
+	if mod.disableCollect {
+		// Exit early.
+		return nil
+	}
+
+	// Get metrics from modules.
+	mods, err := ctx.Modules(new(gotenberg.MetricsProvider))
+	if err != nil {
+		return fmt.Errorf("get metrics providers: %w", err)
+	}
+
+	metricsProviders := make([]gotenberg.MetricsProvider, len(mods))
+	for i, metricsProvider := range mods {
+		metricsProviders[i] = metricsProvider.(gotenberg.MetricsProvider)
+	}
+
+	for _, metricsProvider := range metricsProviders {
+		metrics, err := metricsProvider.Metrics()
+		if err != nil {
+			return fmt.Errorf("get metrics: %w", err)
+		}
+
+		mod.metrics = append(mod.metrics, metrics...)
+	}
+
+	mod.registry = prometheus.NewRegistry()
+
+	return nil
+}
+
+// Validate validates the module properties.
+func (mod *Prometheus) Validate() error {
+	if mod.disableCollect {
+		// Exit early.
+		return nil
+	}
+
+	if mod.namespace == "" {
+		return errors.New("namespace must not be empty")
+	}
+
+	if mod.metricsPath == "" {
+		return errors.New("metrics path cannot be empty")
+	}
+
+	metricsMap := make(map[string]string, len(mod.metrics))
+
+	for _, metric := range mod.metrics {
+		if metric.Name == "" {
+			return errors.New("metric name cannot be empty")
+		}
+
+		if metric.Read == nil {
+			return fmt.Errorf("metric '%s' has nil read method", metric.Name)
+		}
+
+		if _, ok := metricsMap[metric.Name]; ok {
+			return fmt.Errorf("metric '%s' is already registered", metric.Name)
+		}
+
+		metricsMap[metric.Name] = metric.Name
+	}
+
+	return nil
+}
+
+// Start starts the collect.
+func (mod *Prometheus) Start() error {
+	if mod.disableCollect {
+		// Exit early.
+		return nil
+	}
+
+	for _, metric := range mod.metrics {
+		gauge := prometheus.NewGauge(
+			prometheus.GaugeOpts{
+				Namespace: mod.namespace,
+				Name:      metric.Name,
+				Help:      metric.Description,
+			},
+		)
+
+		mod.registry.MustRegister(gauge)
+
+		go func(gauge prometheus.Gauge, metric gotenberg.Metric) {
+			for {
+				gauge.Set(metric.Read())
+				time.Sleep(mod.interval)
+			}
+		}(gauge, metric)
+	}
+
+	return nil
+}
+
+// StartupMessage returns a custom startup message.
+func (mod *Prometheus) StartupMessage() string {
+	if mod.disableCollect {
+		return "collect disabled"
+	}
+
+	return "collecting metrics"
+}
+
+// Stop does nothing.
+func (mod *Prometheus) Stop(ctx context.Context) error {
+	return nil
+}
+
+// Routes returns the HTTP route.
+func (mod *Prometheus) Routes() ([]api.Route, error) {
+	if mod.disableCollect {
+		return nil, nil
+	}
+
+	return []api.Route{
+		{
+			Method:           http.MethodGet,
+			Path:             mod.metricsPath,
+			DisableTelemetry: mod.disableRouteTelemetry,
+			Handler: echo.WrapHandler(
+				promhttp.HandlerFor(mod.registry, promhttp.HandlerOpts{}),
+			),
+		},
+	}, nil
+}
+
+// Interface guards.
+var (
+	_ gotenberg.Module      = (*Prometheus)(nil)
+	_ gotenberg.Provisioner = (*Prometheus)(nil)
+	_ gotenberg.Validator   = (*Prometheus)(nil)
+	_ gotenberg.App         = (*Prometheus)(nil)
+	_ api.Router            = (*Prometheus)(nil)
+)

pkg/modules/qpdf/qpdf.go

@@ -12,6 +12,7 @@ import (
 	"syscall"
 
 	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
@@ -85,7 +86,10 @@ func (engine *QPdf) Debug() map[string]any {
 
 // Split splits a given PDF file.
 func (engine *QPdf) Split(ctx context.Context, logger *slog.Logger, mode gotenberg.SplitMode, inputPath, outputDirPath string) ([]string, error) {
-	ctx, span := gotenberg.Tracer().Start(ctx, "QPdf.Split", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "qpdf.Split",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	var args []string
@@ -126,12 +130,16 @@ func (engine *QPdf) Split(ctx context.Context, logger *slog.Logger, mode gotenbe
 		return nil, err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return []string{outputPath}, nil
 }
 
 // Merge combines multiple PDFs into a single PDF.
 func (engine *QPdf) Merge(ctx context.Context, logger *slog.Logger, inputPaths []string, outputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "QPdf.Merge", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "qpdf.Merge",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	args := make([]string, 0, 4+len(engine.globalArgs)+len(inputPaths))
@@ -151,21 +159,23 @@ func (engine *QPdf) Merge(ctx context.Context, logger *slog.Logger, inputPaths [
 
 	_, err = cmd.Exec()
 	if err == nil {
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
 	err = fmt.Errorf("merge PDFs with QPDF: %w", err)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Flatten merges annotation appearances with page content, deleting the
 // original annotations.
 func (engine *QPdf) Flatten(ctx context.Context, logger *slog.Logger, inputPath string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "QPdf.Flatten", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "qpdf.Flatten",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	args := make([]string, 0, 4+len(engine.globalArgs))
@@ -185,62 +195,106 @@ func (engine *QPdf) Flatten(ctx context.Context, logger *slog.Logger, inputPath
 
 	_, err = cmd.Exec()
 	if err == nil {
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
 	err = fmt.Errorf("flatten PDFs with QPDF: %w", err)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // Convert is not available in this implementation.
 func (engine *QPdf) Convert(ctx context.Context, logger *slog.Logger, formats gotenberg.PdfFormats, inputPath, outputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "QPdf.Convert", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.Convert",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("convert PDF to '%+v' with QPDF: %w", formats, gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
 // ReadMetadata is not available in this implementation.
 func (engine *QPdf) ReadMetadata(ctx context.Context, logger *slog.Logger, inputPath string) (map[string]any, error) {
-	_, span := gotenberg.Tracer().Start(ctx, "QPdf.ReadMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.ReadMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("read PDF metadata with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return nil, err
 }
 
 // WriteMetadata is not available in this implementation.
 func (engine *QPdf) WriteMetadata(ctx context.Context, logger *slog.Logger, metadata map[string]any, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "QPdf.WriteMetadata", trace.WithSpanKind(trace.SpanKindInternal))
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.WriteMetadata",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	err := fmt.Errorf("write PDF metadata with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
-
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 
+// PageCount is not available in this implementation.
+func (engine *QPdf) PageCount(ctx context.Context, logger *slog.Logger, inputPath string) (int, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.PageCount",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("page count with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return 0, err
+}
+
+// WriteBookmarks is not available in this implementation.
+func (engine *QPdf) WriteBookmarks(ctx context.Context, logger *slog.Logger, inputPath string, bookmarks []gotenberg.Bookmark) error {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.WriteBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("write PDF bookmarks with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// ReadBookmarks is not available in this implementation.
+func (engine *QPdf) ReadBookmarks(ctx context.Context, logger *slog.Logger, inputPath string) ([]gotenberg.Bookmark, error) {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.ReadBookmarks",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("read PDF bookmarks with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return nil, err
+}
+
 // Encrypt adds password protection to a PDF file using QPDF.
 func (engine *QPdf) Encrypt(ctx context.Context, logger *slog.Logger, inputPath, userPassword, ownerPassword string) error {
-	ctx, span := gotenberg.Tracer().Start(ctx, "QPdf.Encrypt", trace.WithSpanKind(trace.SpanKindInternal))
+	ctx, span := gotenberg.Tracer().Start(ctx, "qpdf.Encrypt",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
 	if userPassword == "" {
@@ -276,20 +330,63 @@ func (engine *QPdf) Encrypt(ctx context.Context, logger *slog.Logger, inputPath,
 		return err
 	}
 
+	span.SetStatus(codes.Ok, "")
 	return nil
 }
 
-// AddAttachments is not available in this implementation.
-func (engine *QPdf) AddAttachments(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
-	_, span := gotenberg.Tracer().Start(ctx, "QPdf.AddAttachments", trace.WithSpanKind(trace.SpanKindInternal))
+// EmbedFiles is not available in this implementation.
+func (engine *QPdf) EmbedFiles(ctx context.Context, logger *slog.Logger, filePaths []string, inputPath string) error {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.EmbedFiles",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
 	defer span.End()
 
-	err := fmt.Errorf("add attachments with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
-	if err != nil {
-		span.RecordError(err)
-		span.SetStatus(codes.Error, err.Error())
-	}
+	err := fmt.Errorf("embed files with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
 
+// Watermark is not available in this implementation.
+func (engine *QPdf) Watermark(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.Watermark",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("watermark PDF with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// Stamp is not available in this implementation.
+func (engine *QPdf) Stamp(ctx context.Context, logger *slog.Logger, inputPath string, stamp gotenberg.Stamp) error {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.Stamp",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("stamp PDF with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
+	return err
+}
+
+// Rotate is not available in this implementation.
+func (engine *QPdf) Rotate(ctx context.Context, logger *slog.Logger, inputPath string, angle int, pages string) error {
+	_, span := gotenberg.Tracer().Start(ctx, "qpdf.Rotate",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(engine.binPath)),
+	)
+	defer span.End()
+
+	err := fmt.Errorf("rotate PDF with QPDF: %w", gotenberg.ErrPdfEngineMethodNotSupported)
+	span.RecordError(err)
+	span.SetStatus(codes.Error, err.Error())
 	return err
 }
 

pkg/modules/webhook/client.go

@@ -2,6 +2,7 @@ package webhook
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"log/slog"
@@ -12,11 +13,12 @@ import (
 	"github.com/hashicorp/go-retryablehttp"
 	"github.com/labstack/echo/v4"
 	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/codes"
 	"go.opentelemetry.io/otel/propagation"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
-	semconvutil "github.com/gotenberg/gotenberg/v8/pkg/gotenberg/semconv"
 )
 
 // client gathers all the data required to send a request to a webhook.
@@ -25,6 +27,7 @@ type client struct {
 	method           string
 	errorUrl         string
 	errorMethod      string
+	eventsUrl        string
 	extraHttpHeaders map[string]string
 	startTime        time.Time
 
@@ -33,7 +36,7 @@ type client struct {
 }
 
 // send call the webhook either to send the success response or the error response.
-func (c client) send(ctx context.Context, body io.Reader, headers http.Header, errored bool) error {
+func (c client) send(ctx context.Context, body io.Reader, headers map[string]string, errored bool) error {
 	url := c.url
 	if errored {
 		url = c.errorUrl
@@ -44,11 +47,28 @@ func (c client) send(ctx context.Context, body io.Reader, headers http.Header, e
 		method = c.errorMethod
 	}
 
-	req, err := retryablehttp.NewRequestWithContext(ctx, method, url, body)
+	spanName := fmt.Sprintf("%s Webhook", method)
+	if errored {
+		spanName = fmt.Sprintf("%s Webhook Error", method)
+	}
+
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, spanName,
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(url)),
+	)
+	defer span.End()
+
+	req, err := retryablehttp.NewRequest(method, url, body)
 	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
 		return fmt.Errorf("create '%s' request to '%s': %w", method, url, err)
 	}
 
+	// Inject trace context into outbound request headers.
+	otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))
+
 	req.Header.Set("User-Agent", "Gotenberg")
 
 	// Extra HTTP headers are the custom headers from the user.
@@ -58,55 +78,42 @@ func (c client) send(ctx context.Context, body io.Reader, headers http.Header, e
 
 	// Middleware caller's headers > extra HTTP headers from the user.
 
-	contentLength := headers.Get(echo.HeaderContentLength)
-	// 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,
-	// 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 suboptimal, but hey, at
-	// least it works.
+	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,
+		// 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 suboptimal, 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)
+		bodySize, err := strconv.ParseInt(contentLength, 10, 64)
+		if err != nil {
+			span.RecordError(err)
+			span.SetStatus(codes.Error, err.Error())
+			return fmt.Errorf("parse content length entry: %w", err)
+		}
+
+		req.ContentLength = bodySize
 	}
 
-	req.ContentLength = bodySize
-
-	for key := range headers {
-		req.Header.Set(key, headers.Get(key))
+	for key, value := range headers {
+		req.Header.Set(key, value)
 	}
 
-	// OpenTelemetry.
-	meter := gotenberg.Meter()
-	semconvClient := semconvutil.NewHTTPClient(meter)
-
-	tracer := gotenberg.Tracer()
-	spanName := fmt.Sprintf("%s Webhook", req.Method)
-	if errored {
-		spanName = fmt.Sprintf("%s Webhook Error", req.Method)
-	}
-	ctx, span := tracer.Start(ctx, spanName,
-		trace.WithSpanKind(trace.SpanKindClient),
-		trace.WithAttributes(semconvClient.RequestTraceAttrs(req.Request)...),
-	)
-	defer span.End()
-
-	otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))
-
 	resp, err := c.client.Do(req)
 	if err != nil {
 		span.RecordError(err)
-		span.SetStatus(semconvClient.Status(0))
+		span.SetStatus(codes.Error, err.Error())
 		return fmt.Errorf("send '%s' request to '%s': %w", method, url, err)
 	}
 
-	span.SetAttributes(semconvClient.ResponseTraceAttrs(resp)...)
-	span.SetStatus(semconvClient.Status(resp.StatusCode))
-
 	if resp.StatusCode >= http.StatusBadRequest {
-		return fmt.Errorf("send '%s' request to '%s': got status: '%s'", method, url, resp.Status)
+		err := fmt.Errorf("send '%s' request to '%s': got status: '%s'", method, url, resp.Status)
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
 	}
 
 	defer func() {
@@ -120,18 +127,85 @@ func (c client) send(ctx context.Context, body io.Reader, headers http.Header, e
 	finishTime := time.Now()
 
 	// Now let's log!
-	fields := make([]any, 5)
-	fields[0] = slog.String("webhook_url", url)
-	fields[1] = slog.String("method", method)
-	fields[2] = slog.Int64("latency", int64(finishTime.Sub(c.startTime)))
-	fields[3] = slog.String("latency_human", finishTime.Sub(c.startTime).String())
-	fields[4] = slog.Int64("bytes_out", req.ContentLength)
+	attrs := []any{
+		slog.String("webhook_url", url),
+		slog.String("method", method),
+		slog.Int64("latency", int64(finishTime.Sub(c.startTime))),
+		slog.String("latency_human", finishTime.Sub(c.startTime).String()),
+		slog.Int64("bytes_out", req.ContentLength),
+	}
 
 	if errored {
-		c.logger.WarnContext(ctx, "request to webhook with error details handled", fields...)
+		c.logger.WarnContext(ctx, "request to webhook with error details handled", attrs...)
+		span.SetStatus(codes.Ok, "")
 		return nil
 	}
 
-	c.logger.InfoContext(ctx, "request to webhook handled", fields...)
+	c.logger.InfoContext(ctx, "request to webhook handled", attrs...)
+	span.SetStatus(codes.Ok, "")
+
 	return nil
 }
+
+// sendEvent sends a structured JSON event to the events URL. It is
+// fire-and-forget: failures are logged but do not propagate.
+func (c client) sendEvent(ctx context.Context, correlationIdHeader, correlationId string, event map[string]any) {
+	if c.eventsUrl == "" {
+		return
+	}
+
+	b, err := json.Marshal(event)
+	if err != nil {
+		c.logger.ErrorContext(ctx, fmt.Sprintf("marshal webhook event: %s", err))
+		return
+	}
+
+	tracer := gotenberg.Tracer()
+	ctx, span := tracer.Start(ctx, "POST Webhook Event",
+		trace.WithSpanKind(trace.SpanKindClient),
+		trace.WithAttributes(semconv.ServerAddress(c.eventsUrl)),
+	)
+	defer span.End()
+
+	req, err := retryablehttp.NewRequest(http.MethodPost, c.eventsUrl, b)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		c.logger.ErrorContext(ctx, fmt.Sprintf("create webhook event request: %s", err))
+		return
+	}
+
+	otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))
+
+	req.Header.Set("User-Agent", "Gotenberg")
+	for key, value := range c.extraHttpHeaders {
+		req.Header.Set(key, value)
+	}
+	req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
+	req.Header.Set(correlationIdHeader, correlationId)
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		c.logger.ErrorContext(ctx, fmt.Sprintf("send webhook event to '%s': %s", c.eventsUrl, err))
+		return
+	}
+
+	defer func() {
+		err := resp.Body.Close()
+		if err != nil {
+			c.logger.ErrorContext(ctx, fmt.Sprintf("close response body from '%s': %s", c.eventsUrl, err))
+		}
+	}()
+
+	if resp.StatusCode >= http.StatusBadRequest {
+		span.RecordError(fmt.Errorf("webhook event: got status '%s'", resp.Status))
+		span.SetStatus(codes.Error, resp.Status)
+		c.logger.ErrorContext(ctx, fmt.Sprintf("send webhook event to '%s': got status '%s'", c.eventsUrl, resp.Status))
+		return
+	}
+
+	span.SetStatus(codes.Ok, "")
+	c.logger.InfoContext(ctx, fmt.Sprintf("webhook event sent to '%s'", c.eventsUrl))
+}

pkg/modules/webhook/middleware.go

@@ -15,317 +15,363 @@ import (
 
 	"github.com/hashicorp/go-retryablehttp"
 	"github.com/labstack/echo/v4"
-	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/propagation"
 
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 	"github.com/gotenberg/gotenberg/v8/pkg/modules/api"
 )
 
+type sendOutputFileParams struct {
+	ctx                 *api.Context
+	outputPath          string
+	extraHttpHeaders    map[string]string
+	correlationIdHeader string
+	correlationId       string
+	client              *client
+	handleError         func(error)
+}
+
 func webhookMiddleware(w *Webhook) api.Middleware {
 	return api.Middleware{
 		Stack: api.MultipartStack,
 		Handler: func() echo.MiddlewareFunc {
 			return func(next echo.HandlerFunc) echo.HandlerFunc {
+				sendOutputFile := func(params sendOutputFileParams) {
+					outputFile, err := os.Open(params.outputPath)
+					if err != nil {
+						params.ctx.Log().Error(fmt.Sprintf("open output file: %s", err))
+						params.handleError(err)
+						return
+					}
+					defer func() {
+						err := outputFile.Close()
+						if err != nil {
+							params.ctx.Log().Error(fmt.Sprintf("close output file: %s", err))
+						}
+					}()
+
+					fileHeader := make([]byte, 512)
+					_, err = outputFile.Read(fileHeader)
+					if err != nil {
+						params.ctx.Log().Error(fmt.Sprintf("read header of output file: %s", err))
+						params.handleError(err)
+						return
+					}
+
+					fileStat, err := outputFile.Stat()
+					if err != nil {
+						params.ctx.Log().Error(fmt.Sprintf("get stat from output file: %s", err))
+						params.handleError(err)
+						return
+					}
+
+					_, err = outputFile.Seek(0, 0)
+					if err != nil {
+						params.ctx.Log().Error(fmt.Sprintf("reset output file reader: %s", err))
+						params.handleError(err)
+						return
+					}
+
+					headers := map[string]string{
+						echo.HeaderContentType:     http.DetectContentType(fileHeader),
+						echo.HeaderContentLength:   strconv.FormatInt(fileStat.Size(), 10),
+						params.correlationIdHeader: params.correlationId,
+					}
+					_, ok := params.extraHttpHeaders[echo.HeaderContentDisposition]
+					if !ok {
+						headers[echo.HeaderContentDisposition] = fmt.Sprintf("attachment; filename=%q", params.ctx.OutputFilename(params.outputPath))
+					}
+
+					err = params.client.send(params.ctx, bufio.NewReader(outputFile), headers, false)
+					if err != nil {
+						params.ctx.Log().Error(fmt.Sprintf("send output file to webhook: %s", err))
+						params.handleError(err)
+						return
+					}
+
+					params.client.sendEvent(params.ctx, params.correlationIdHeader, params.correlationId, map[string]any{
+						"event":         "webhook.success",
+						"correlationId": params.correlationId,
+						"timestamp":     time.Now().UTC().Format(time.RFC3339Nano),
+					})
+				}
+
 				return func(c echo.Context) error {
 					webhookUrl := c.Request().Header.Get("Gotenberg-Webhook-Url")
 					if webhookUrl == "" {
+						// No webhook URL, call the next middleware in the chain.
 						return next(c)
 					}
 
 					ctx := c.Get("context").(*api.Context)
 					cancel := c.Get("cancel").(context.CancelFunc)
 
+					// Do we have a webhook error URL in case of... error?
+					webhookErrorUrl := c.Request().Header.Get("Gotenberg-Webhook-Error-Url")
+					if webhookErrorUrl == "" {
+						return api.WrapError(
+							errors.New("empty webhook error URL"),
+							api.NewSentinelHttpError(http.StatusBadRequest, "Invalid 'Gotenberg-Webhook-Error-Url' header: empty value or header not provided"),
+						)
+					}
+
 					deadline, ok := ctx.Deadline()
 					if !ok {
 						return errors.New("context has no deadline")
 					}
 
-					// Parse all configurations.
-					cfg, err := parseWebhookConfig(c, w, deadline, webhookUrl)
+					// Let's check if the webhook URLs are acceptable according to our
+					// allowed/denied lists.
+					err := gotenberg.FilterDeadline(w.allowList, w.denyList, webhookUrl, deadline)
 					if err != nil {
-						return err
+						return fmt.Errorf("filter webhook URL: %w", err)
 					}
 
-					// Set up Headers and Tracing.
+					err = gotenberg.FilterDeadline(w.errorAllowList, w.errorDenyList, webhookErrorUrl, deadline)
+					if err != nil {
+						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 "", api.WrapError(
+							fmt.Errorf("webhook method '%s' is not '%s', '%s' or '%s'", method, http.MethodPost, http.MethodPatch, http.MethodPut),
+							api.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 {
+						return fmt.Errorf("get method to use for webhook: %w", err)
+					}
+
+					webhookErrorMethod, err := methodFromHeader("Gotenberg-Webhook-Error-Method")
+					if err != nil {
+						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 {
+							return api.WrapError(
+								fmt.Errorf("unmarshal webhook extra HTTP headers: %w", err),
+								api.NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Invalid 'Gotenberg-Webhook-Extra-Http-Headers' header value: %s", err.Error())),
+							)
+						}
+					}
+
+					// What about the events URL?
+					webhookEventsUrl := c.Request().Header.Get("Gotenberg-Webhook-Events-Url")
+					if webhookEventsUrl != "" {
+						err = gotenberg.FilterDeadline(w.allowList, w.denyList, webhookEventsUrl, deadline)
+						if err != nil {
+							return fmt.Errorf("filter webhook events URL: %w", err)
+						}
+					}
+
+					// Retrieve values from echo.Context before it gets recycled.
+					// See https://github.com/gotenberg/gotenberg/issues/1000.
 					startTime := c.Get("startTime").(time.Time)
 					correlationIdHeader := c.Get("correlationIdHeader").(string)
 					correlationId := c.Get("correlationId").(string)
 
-					headers := make(http.Header)
-					headers.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
-					headers.Set(correlationIdHeader, correlationId)
-					otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(headers))
-
-					// Initialize the Webhook Client.
-					webhookClient := &client{
-						url:              cfg.URL,
-						method:           cfg.Method,
-						errorUrl:         cfg.ErrorURL,
-						errorMethod:      cfg.ErrorMethod,
-						extraHttpHeaders: cfg.ExtraHTTPHeaders,
+					client := &client{
+						url:              webhookUrl,
+						method:           webhookMethod,
+						errorUrl:         webhookErrorUrl,
+						errorMethod:      webhookErrorMethod,
+						eventsUrl:        webhookEventsUrl,
+						extraHttpHeaders: extraHttpHeaders,
 						startTime:        startTime,
+
 						client: &retryablehttp.Client{
-							HTTPClient:   &http.Client{Timeout: w.clientTimeout},
+							HTTPClient: &http.Client{
+								Timeout: w.clientTimeout,
+							},
 							RetryMax:     w.maxRetry,
 							RetryWaitMin: w.retryMinWait,
 							RetryWaitMax: w.retryMaxWait,
-							Logger:       gotenberg.NewLeveledLogger(ctx.Log()).WithContext(ctx),
+							Logger:       gotenberg.NewLeveledLogger(ctx.Log()),
 							CheckRetry:   retryablehttp.DefaultRetryPolicy,
 							Backoff:      retryablehttp.DefaultBackoff,
 						},
 						logger: ctx.Log(),
 					}
 
-					handleErrFunc := func(err error) {
-						sendWebhookError(ctx, webhookClient, headers, err)
+					// This method parses an "asynchronous" error and sends a
+					// request to the webhook error URL with a JSON body
+					// containing the status and the error message.
+					handleError := func(err error) {
+						status, message := api.ParseError(err)
+
+						body := struct {
+							Status  int    `json:"status"`
+							Message string `json:"message"`
+						}{
+							Status:  status,
+							Message: message,
+						}
+
+						b, err := json.Marshal(body)
+						if err != nil {
+							ctx.Log().Error(fmt.Sprintf("marshal JSON: %s", err.Error()))
+							return
+						}
+
+						headers := map[string]string{
+							echo.HeaderContentType: echo.MIMEApplicationJSON,
+							correlationIdHeader:    correlationId,
+						}
+
+						err = client.send(ctx, bytes.NewReader(b), headers, true)
+						if err != nil {
+							ctx.Log().Error(fmt.Sprintf("send error response to webhook: %s", err.Error()))
+						}
+
+						client.sendEvent(ctx, correlationIdHeader, correlationId, map[string]any{
+							"event":         "webhook.error",
+							"correlationId": correlationId,
+							"timestamp":     time.Now().UTC().Format(time.RFC3339Nano),
+							"error": map[string]any{
+								"status":  status,
+								"message": message,
+							},
+						})
 					}
 
-					// Execute Sync Flow.
 					if w.enableSyncMode {
-						return handleSyncWebhook(c, next, ctx, webhookClient, headers, cfg.ExtraHTTPHeaders, handleErrFunc)
+						err := next(c)
+						if err != nil {
+							if errors.Is(err, api.ErrNoOutputFile) {
+								errNoOutputFile := fmt.Errorf("%w - the webhook middleware cannot handle the result of this route", err)
+								handleError(api.WrapError(
+									errNoOutputFile,
+									api.NewSentinelHttpError(
+										http.StatusBadRequest,
+										"The webhook middleware can only work with multipart/form-data routes that results in output files",
+									),
+								))
+								return nil
+							}
+							ctx.Log().Error(err.Error())
+							handleError(err)
+							return nil
+						}
+
+						outputPath, err := ctx.BuildOutputFile()
+						if err != nil {
+							ctx.Log().Error(fmt.Sprintf("build output file: %s", err))
+							handleError(err)
+							return nil
+						}
+						// No error, let's send the output file to the webhook URL.
+						sendOutputFile(sendOutputFileParams{
+							ctx:                 ctx,
+							outputPath:          outputPath,
+							extraHttpHeaders:    extraHttpHeaders,
+							correlationIdHeader: correlationIdHeader,
+							correlationId:       correlationId,
+							client:              client,
+							handleError:         handleError,
+						})
+						return c.NoContent(http.StatusNoContent)
 					}
 
-					// Execute Async Flow.
-					return handleAsyncWebhook(c, next, w, ctx, cancel, deadline, webhookClient, headers, cfg.ExtraHTTPHeaders, handleErrFunc)
+					if deadline, ok := ctx.Deadline(); ok {
+						// Create a new context derived from Background (detached from Request)
+						// but with the same deadline as the original context.
+						detachedCtx, detachedCancel := context.WithDeadline(context.Background(), deadline)
+
+						// Replace the embedded context in the api.Context struct.
+						// The modules downstream will now use this detached context.
+						ctx.Context = detachedCtx
+
+						// We must wrap the cancel function.
+						// 1. detachedCancel() cleans up our new detached context.
+						// 2. originalCancel() (captured from c.Get("cancel")) cleans up the working directory.
+						originalCancel := cancel
+						cancel = func() {
+							detachedCancel()
+							originalCancel()
+						}
+					} else {
+						// Fallback if no deadline was set (rare, as newContext enforces it).
+						ctx.Context = context.Background()
+					}
+
+					// As a webhook URL has been given, we handle the request in a
+					// goroutine and return immediately.
+					w.asyncCount.Add(1)
+					go func() {
+						defer cancel()
+						defer w.asyncCount.Add(-1)
+
+						// Call the next middleware in the chain.
+						err := next(c)
+						if err != nil {
+							if errors.Is(err, api.ErrNoOutputFile) {
+								errNoOutputFile := fmt.Errorf("%w - the webhook middleware cannot handle the result of this route", err)
+								handleError(api.WrapError(
+									errNoOutputFile,
+									api.NewSentinelHttpError(
+										http.StatusBadRequest,
+										"The webhook middleware can only work with multipart/form-data routes that results in output files",
+									),
+								))
+								return
+							}
+							// The process failed for whatever reason. Let's send the
+							// details to the webhook.
+							ctx.Log().Error(err.Error())
+							handleError(err)
+							return
+						}
+
+						// No error, let's get to build the output file.
+						outputPath, err := ctx.BuildOutputFile()
+						if err != nil {
+							ctx.Log().Error(fmt.Sprintf("build output file: %s", err))
+							handleError(err)
+							return
+						}
+
+						sendOutputFile(sendOutputFileParams{
+							ctx:                 ctx,
+							outputPath:          outputPath,
+							extraHttpHeaders:    extraHttpHeaders,
+							correlationIdHeader: correlationIdHeader,
+							correlationId:       correlationId,
+							client:              client,
+							handleError:         handleError,
+						})
+					}()
+
+					return api.ErrAsyncProcess
 				}
 			}
 		}(),
 	}
 }
-
-func handleSyncWebhook(c echo.Context, next echo.HandlerFunc, ctx *api.Context, client *client, headers http.Header, extraHeaders map[string]string, handleErr func(error)) error {
-	if err := next(c); err != nil {
-		if errors.Is(err, api.ErrNoOutputFile) {
-			handleErr(api.WrapError(
-				fmt.Errorf("%w - the webhook middleware cannot handle the result of this route", err),
-				api.NewSentinelHttpError(http.StatusBadRequest, "The webhook middleware can only work with multipart/form-data routes that results in output files"),
-			))
-			return nil
-		}
-		ctx.Log().ErrorContext(ctx, err.Error())
-		handleErr(err)
-		return nil
-	}
-
-	outputPath, err := ctx.BuildOutputFile()
-	if err != nil {
-		ctx.Log().ErrorContext(ctx, fmt.Sprintf("build output file: %s", err))
-		handleErr(err)
-		return nil
-	}
-
-	sendOutputFile(sendOutputFileParams{
-		ctx:              ctx,
-		outputPath:       outputPath,
-		extraHttpHeaders: extraHeaders,
-		headers:          headers,
-		client:           client,
-		handleError:      handleErr,
-	})
-	return c.NoContent(http.StatusNoContent)
-}
-
-func handleAsyncWebhook(c echo.Context, next echo.HandlerFunc, w *Webhook, ctx *api.Context, cancel context.CancelFunc, deadline time.Time, client *client, headers http.Header, extraHeaders map[string]string, handleErr func(error)) error {
-	// Detach context for async processing.
-	detachedCtx := context.WithoutCancel(ctx.Context)
-	detachedCtx, detachedCancel := context.WithDeadline(detachedCtx, deadline)
-	ctx.Context = detachedCtx
-
-	originalCancel := cancel
-	cancel = func() {
-		detachedCancel()
-		originalCancel()
-	}
-
-	w.asyncCount.Add(1)
-	go func() {
-		defer cancel()
-		defer w.asyncCount.Add(-1)
-
-		if err := next(c); err != nil {
-			if errors.Is(err, api.ErrNoOutputFile) {
-				handleErr(api.WrapError(
-					fmt.Errorf("%w - the webhook middleware cannot handle the result of this route", err),
-					api.NewSentinelHttpError(http.StatusBadRequest, "The webhook middleware can only work with multipart/form-data routes that results in output files"),
-				))
-				return
-			}
-			ctx.Log().ErrorContext(ctx, err.Error())
-			handleErr(err)
-			return
-		}
-
-		outputPath, err := ctx.BuildOutputFile()
-		if err != nil {
-			ctx.Log().ErrorContext(ctx, fmt.Sprintf("build output file: %s", err))
-			handleErr(err)
-			return
-		}
-
-		sendOutputFile(sendOutputFileParams{
-			ctx:              ctx,
-			outputPath:       outputPath,
-			extraHttpHeaders: extraHeaders,
-			headers:          headers,
-			client:           client,
-			handleError:      handleErr,
-		})
-	}()
-
-	return api.ErrAsyncProcess
-}
-
-type webhookConfig struct {
-	URL              string
-	ErrorURL         string
-	Method           string
-	ErrorMethod      string
-	ExtraHTTPHeaders map[string]string
-}
-
-func parseWebhookConfig(c echo.Context, w *Webhook, deadline time.Time, webhookUrl string) (*webhookConfig, error) {
-	errorUrl := c.Request().Header.Get("Gotenberg-Webhook-Error-Url")
-	if errorUrl == "" {
-		return nil, api.WrapError(
-			errors.New("empty webhook error URL"),
-			api.NewSentinelHttpError(http.StatusBadRequest, "Invalid 'Gotenberg-Webhook-Error-Url' header: empty value or header not provided"),
-		)
-	}
-
-	if err := gotenberg.FilterDeadline(w.allowList, w.denyList, webhookUrl, deadline); err != nil {
-		return nil, fmt.Errorf("filter webhook URL: %w", err)
-	}
-	if err := gotenberg.FilterDeadline(w.errorAllowList, w.errorDenyList, errorUrl, deadline); err != nil {
-		return nil, fmt.Errorf("filter webhook error URL: %w", err)
-	}
-
-	method, err := methodFromHeader(c, "Gotenberg-Webhook-Method")
-	if err != nil {
-		return nil, fmt.Errorf("get method to use for webhook: %w", err)
-	}
-
-	errorMethod, err := methodFromHeader(c, "Gotenberg-Webhook-Error-Method")
-	if err != nil {
-		return nil, fmt.Errorf("get method to use for webhook error: %w", err)
-	}
-
-	var extraHeaders map[string]string
-	if extraJson := c.Request().Header.Get("Gotenberg-Webhook-Extra-Http-Headers"); extraJson != "" {
-		if err := json.Unmarshal([]byte(extraJson), &extraHeaders); err != nil {
-			return nil, api.WrapError(
-				fmt.Errorf("unmarshal webhook extra HTTP headers: %w", err),
-				api.NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Invalid 'Gotenberg-Webhook-Extra-Http-Headers' header value: %s", err.Error())),
-			)
-		}
-	}
-
-	return &webhookConfig{
-		URL:              webhookUrl,
-		ErrorURL:         errorUrl,
-		Method:           method,
-		ErrorMethod:      errorMethod,
-		ExtraHTTPHeaders: extraHeaders,
-	}, nil
-}
-
-func methodFromHeader(c echo.Context, 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, http.MethodPatch, http.MethodPut:
-		return method, nil
-	}
-
-	return "", api.WrapError(
-		fmt.Errorf("webhook method '%s' is not '%s', '%s' or '%s'", method, http.MethodPost, http.MethodPatch, http.MethodPut),
-		api.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)),
-	)
-}
-
-func sendWebhookError(ctx *api.Context, c *client, headers http.Header, processErr error) {
-	status, message := api.ParseError(processErr)
-
-	body := struct {
-		Status  int    `json:"status"`
-		Message string `json:"message"`
-	}{
-		Status:  status,
-		Message: message,
-	}
-
-	b, err := json.Marshal(body)
-	if err != nil {
-		ctx.Log().ErrorContext(ctx, fmt.Sprintf("marshal JSON: %s", err.Error()))
-		return
-	}
-
-	headers.Set(echo.HeaderContentLength, strconv.Itoa(len(b)))
-
-	if err := c.send(ctx, bytes.NewReader(b), headers, true); err != nil {
-		ctx.Log().ErrorContext(ctx, fmt.Sprintf("send error response to webhook: %s", err.Error()))
-	}
-}
-
-type sendOutputFileParams struct {
-	ctx              *api.Context
-	outputPath       string
-	extraHttpHeaders map[string]string
-	headers          http.Header
-	client           *client
-	handleError      func(error)
-}
-
-func sendOutputFile(params sendOutputFileParams) {
-	outputFile, err := os.Open(params.outputPath)
-	if err != nil {
-		params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("open output file: %s", err))
-		params.handleError(err)
-		return
-	}
-	defer func() {
-		if err := outputFile.Close(); err != nil {
-			params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("close output file: %s", err))
-		}
-	}()
-
-	fileHeader := make([]byte, 512)
-	_, err = outputFile.Read(fileHeader)
-	if err != nil {
-		params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("read header of output file: %s", err))
-		params.handleError(err)
-		return
-	}
-
-	fileStat, err := outputFile.Stat()
-	if err != nil {
-		params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("get stat from output file: %s", err))
-		params.handleError(err)
-		return
-	}
-
-	_, err = outputFile.Seek(0, 0)
-	if err != nil {
-		params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("reset output file reader: %s", err))
-		params.handleError(err)
-		return
-	}
-
-	params.headers.Set(echo.HeaderContentType, http.DetectContentType(fileHeader))
-	params.headers.Set(echo.HeaderContentLength, strconv.FormatInt(fileStat.Size(), 10))
-
-	_, ok := params.extraHttpHeaders[echo.HeaderContentDisposition]
-	if !ok {
-		params.headers.Set(echo.HeaderContentDisposition, fmt.Sprintf("attachments; filename=%q", params.ctx.OutputFilename(params.outputPath)))
-	}
-
-	err = params.client.send(params.ctx, bufio.NewReader(outputFile), params.headers, false)
-	if err != nil {
-		params.ctx.Log().ErrorContext(params.ctx, fmt.Sprintf("send output file to webhook: %s", err))
-		params.handleError(err)
-	}
-}

pkg/modules/webhook/webhook.go

@@ -19,10 +19,10 @@ func init() {
 // to any destinations in an asynchronous fashion.
 type Webhook struct {
 	enableSyncMode bool
-	allowList      *regexp2.Regexp
-	denyList       *regexp2.Regexp
-	errorAllowList *regexp2.Regexp
-	errorDenyList  *regexp2.Regexp
+	allowList      []*regexp2.Regexp
+	denyList       []*regexp2.Regexp
+	errorAllowList []*regexp2.Regexp
+	errorDenyList  []*regexp2.Regexp
 	maxRetry       int
 	retryMinWait   time.Duration
 	retryMaxWait   time.Duration
@@ -38,10 +38,10 @@ func (w *Webhook) Descriptor() gotenberg.ModuleDescriptor {
 		FlagSet: func() *flag.FlagSet {
 			fs := flag.NewFlagSet("webhook", flag.ExitOnError)
 			fs.Bool("webhook-enable-sync-mode", false, "Enable synchronous mode for the webhook feature")
-			fs.String("webhook-allow-list", "", "Set the allowed URLs for the webhook feature using a regular expression")
-			fs.String("webhook-deny-list", "", "Set the denied URLs for the webhook feature using a regular expression")
-			fs.String("webhook-error-allow-list", "", "Set the allowed URLs in case of an error for the webhook feature using a regular expression")
-			fs.String("webhook-error-deny-list", "", "Set the denied URLs in case of an error for the webhook feature using a regular expression")
+			fs.StringSlice("webhook-allow-list", []string{}, "Set the allowed URLs for the webhook feature using regular expressions - supports multiple values")
+			fs.StringSlice("webhook-deny-list", []string{}, "Set the denied URLs for the webhook feature using regular expressions - supports multiple values")
+			fs.StringSlice("webhook-error-allow-list", []string{}, "Set the allowed URLs in case of an error for the webhook feature using regular expressions - supports multiple values")
+			fs.StringSlice("webhook-error-deny-list", []string{}, "Set the denied URLs in case of an error for the webhook feature using regular expressions - supports multiple values")
 			fs.Int("webhook-max-retry", 4, "Set the maximum number of retries for the webhook feature")
 			fs.Duration("webhook-retry-min-wait", time.Duration(1)*time.Second, "Set the minimum duration to wait before trying to call the webhook again")
 			fs.Duration("webhook-retry-max-wait", time.Duration(30)*time.Second, "Set the maximum duration to wait before trying to call the webhook again")
@@ -58,10 +58,10 @@ func (w *Webhook) Descriptor() gotenberg.ModuleDescriptor {
 func (w *Webhook) Provision(ctx *gotenberg.Context) error {
 	flags := ctx.ParsedFlags()
 	w.enableSyncMode = flags.MustBool("webhook-enable-sync-mode")
-	w.allowList = flags.MustRegexp("webhook-allow-list")
-	w.denyList = flags.MustRegexp("webhook-deny-list")
-	w.errorAllowList = flags.MustRegexp("webhook-error-allow-list")
-	w.errorDenyList = flags.MustRegexp("webhook-error-deny-list")
+	w.allowList = flags.MustRegexpSlice("webhook-allow-list")
+	w.denyList = flags.MustRegexpSlice("webhook-deny-list")
+	w.errorAllowList = flags.MustRegexpSlice("webhook-error-allow-list")
+	w.errorDenyList = flags.MustRegexpSlice("webhook-error-deny-list")
 	w.maxRetry = flags.MustInt("webhook-max-retry")
 	w.retryMinWait = flags.MustDuration("webhook-retry-min-wait")
 	w.retryMaxWait = flags.MustDuration("webhook-retry-max-wait")

pkg/standard/imports.go

@@ -11,6 +11,7 @@ import (
 	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/pdfcpu"
 	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/pdfengines"
 	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/pdftk"
+	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/prometheus"
 	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/qpdf"
 	_ "github.com/gotenberg/gotenberg/v8/pkg/modules/webhook"
 )

test/integration/AGENTS.md

@@ -0,0 +1,78 @@
+# Integration Tests
+
+- **Framework:** Gherkin (BDD) via [Godog](https://github.com/cucumber/godog), with `testcontainers-go` for Docker orchestration.
+- **Feature files:** `test/integration/features/*.feature` — one file per endpoint or capability.
+- **Test infrastructure:** `test/integration/scenario/` — Go step definitions, container management, HTTP helpers, PDF validation.
+- **Entry point:** `test/integration/main_test.go` (build tag: `integration`).
+- **Test data:** `test/integration/testdata/`
+
+## How It Works
+
+Each scenario spins up a fresh Gotenberg Docker container via testcontainers. The step definitions in `scenario/scenario.go` map Gherkin steps to Go functions. An additional `gotenberg/integration-tools` container provides PDF validation tools (`verapdf`, `pdfinfo`, `pdftotext`).
+
+**Important:** Integration tests require a Docker image. Run `make build` before `make test-integration`.
+
+## Selective Test Runs
+
+Use the `TAGS` variable to run only relevant scenarios:
+
+```bash
+make test-integration TAGS=health
+make test-integration TAGS=chromium-convert-html
+make test-integration TAGS="merge,split"
+```
+
+Available tags: `chromium`, `chromium-concurrent`, `chromium-convert-html`, `chromium-convert-markdown`, `chromium-convert-url`, `chromium-screenshot-html`, `chromium-screenshot-markdown`, `chromium-screenshot-url`, `debug`, `health`, `libreoffice`, `libreoffice-convert`, `output-filename`, `pdfengines`, `pdfengines-convert`, `pdfengines-embed`, `embed`, `pdfengines-encrypt`, `encrypt`, `pdfengines-flatten`, `flatten`, `pdfengines-merge`, `merge`, `pdfengines-metadata`, `metadata`, `pdfengines-split`, `split`, `pdfengines-watermark`, `watermark`, `pdfengines-stamp`, `stamp`, `pdfengines-bookmarks`, `bookmarks`, `pdfengines-rotate`, `rotate`, `prometheus-metrics`, `root`, `version`, `webhook`, `download-from`.
+
+Other useful flags:
+
+```bash
+make test-integration NO_CONCURRENCY=true  # Disable parallel scenarios
+make test-integration PLATFORM=linux/arm64 # Force a specific platform
+```
+
+## Writing a New Integration Test
+
+1. Create or update a `.feature` file in `test/integration/features/`.
+2. Tag it appropriately (e.g., `@chromium @chromium-convert-html`).
+3. If the feature requires new tag(s), add them to both the `TAGS` comment block in the `Makefile` and the "Available tags" list above.
+4. If you create a new step definition, add it to `scenario/scenario.go`, register it in `InitializeScenario`, and update the "Available Gherkin Steps" list below.
+5. Test data goes in `test/integration/testdata/`.
+
+## Available Gherkin Steps
+
+**Given (setup):**
+
+- `I have a default Gotenberg container`
+- `I have a Gotenberg container with the following environment variable(s):` (table: key | value)
+- `I have a (webhook|static) server`
+
+**When (action):**
+
+- `I make a "(GET|HEAD)" request to Gotenberg at the "<endpoint>" endpoint`
+- `I make a "(GET|HEAD)" request to Gotenberg at the "<endpoint>" endpoint with the following header(s):` (table: name | value)
+- `I make a "(POST)" request to Gotenberg at the "<endpoint>" endpoint with the following form data and header(s):` (table: name | value | kind — where kind is `file`, `field`, or `header`)
+- `I make <N> concurrent "(POST)" requests to Gotenberg at the "<endpoint>" endpoint with the following form data and header(s):` (same table format)
+- `I wait for the asynchronous request to the webhook`
+
+**Then (assertions):**
+
+- `the response status code should be <code>`
+- `the (response|webhook request) header "<name>" should be "<value>"`
+- `the (response|webhook request) cookie "<name>" should be "<value>"`
+- `the (response|webhook request) body should match string:` (docstring)
+- `the (response|webhook request) body should contain string:` (docstring)
+- `the (response|webhook request) body should match JSON:` (docstring — use `"ignore"` for dynamic values like timestamps)
+- `the webhook event should match JSON:` (docstring — use `"ignore"` for dynamic values; polls for up to 5s)
+- `there should be <N> PDF(s) in the (response|webhook request)`
+- `there should be the following file(s) in the (response|webhook request):` (table of filenames)
+- `the "<name>" PDF should have <N> page(s)`
+- `the "<name>" PDF (should|should NOT) be set to landscape orientation`
+- `the "<name>" PDF (should|should NOT) have the following content at page <N>:` (docstring)
+- `the (response|webhook request) PDF(s) should be valid "<standard>" with a tolerance of <N> failed rule(s)` (standards: `PDF/A-1b`, `PDF/A-2b`, `PDF/A-3b`, `PDF/UA-1`, `PDF/UA-2`)
+- `the (response|webhook request) PDF(s) (should|should NOT) be flatten`
+- `the (response|webhook request) PDF(s) (should|should NOT) be encrypted`
+- `the (response|webhook request) PDF(s) (should|should NOT) have the "<filename>" file embedded`
+- `the Gotenberg container (should|should NOT) log the following entries:` (table of log substrings)
+- `all concurrent response status codes should be <code>`
+- `all concurrent responses should have <N> PDF(s)`

test/integration/features/chromium_convert_html.feature

@@ -401,7 +401,7 @@ Feature: /forms/chromium/convert/html
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then the Gotenberg container should log the following entries:
-      | 'file:///etc/passwd' does not match the expression from the allowed list |
+      | 'file:///etc/passwd' does not match any expression from the allowed list |
 
   Scenario: POST /forms/chromium/convert/html (JavaScript Enabled)
     Given I have a default Gotenberg container
@@ -528,7 +528,29 @@ Feature: /forms/chromium/convert/html
     Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
     Then the response body should match string:
       """
-      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo"); form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty); form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form file 'index.html' is required
+      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo")
+      form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty)
+      form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form file 'index.html' is required
       """
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
       | files          | testdata/page-1-html/index.html | file  |
@@ -989,48 +1011,82 @@ Feature: /forms/chromium/convert/html
     Then there should be 1 PDF(s) in the response
     Then the response PDF(s) should be encrypted
 
-  @attachments
-  Scenario: POST /forms/chromium/convert/html (Attachments)
+  @watermark
+  Scenario: POST /forms/chromium/convert/html (Watermark - Text)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
+      | files               | testdata/page-1-html/index.html | file  |
+      | watermarkSource     | text                            | field |
+      | watermarkExpression | CONFIDENTIAL                    | field |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+
+  @stamp
+  Scenario: POST /forms/chromium/convert/html (Stamp - Text)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
+      | files           | testdata/page-1-html/index.html | file  |
+      | stampSource     | text                            | field |
+      | stampExpression | DRAFT                           | field |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+
+  @rotate
+  Scenario: POST /forms/chromium/convert/html (Rotate 90)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
+      | files       | testdata/page-1-html/index.html | file  |
+      | rotateAngle | 90                              | field |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+
+  @embed
+  Scenario: POST /forms/chromium/convert/html (Embeds)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
       | files                     | testdata/page-1-html/index.html | file   |
-      | attachments               | testdata/attachment_1.xml       | file   |
-      | attachments               | testdata/attachment_2.xml       | file   |
+      | embeds                    | testdata/embed_1.xml            | file   |
+      | embeds                    | testdata/embed_2.xml            | file   |
       | Gotenberg-Output-Filename | foo                             | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the response:
       | foo.pdf |
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
 
   # FIXME: once decrypt is done, add encrypt and check after the content of the PDF.
   @convert
   @metadata
+  @watermark
+  @stamp
   @flatten
-  @attachments
-  Scenario: POST /forms/chromium/convert/html (PDF/A-1b & PDF/UA-1 & Metadata & Flatten & Attachments)
+  @embed
+  Scenario: POST /forms/chromium/convert/html (PDF/A-3b & PDF/UA-1 & Metadata & Watermark & Stamp & Flatten & Embeds)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
       | files                     | testdata/page-1-html/index.html                                                                                                                                                                                                                                                                           | file   |
-      | pdfa                      | PDF/A-1b                                                                                                                                                                                                                                                                                                  | field  |
+      | pdfa                      | PDF/A-3b                                                                                                                                                                                                                                                                                                  | field  |
       | pdfua                     | true                                                                                                                                                                                                                                                                                                      | field  |
       | metadata                  | {"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreateDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"} | field  |
       | flatten                   | true                                                                                                                                                                                                                                                                                                      | field  |
-      | attachments               | testdata/attachment_1.xml                                                                                                                                                                                                                                                                                 | file   |
-      | attachments               | testdata/attachment_2.xml                                                                                                                                                                                                                                                                                 | file   |
+      | embeds                    | testdata/embed_1.xml                                                                                                                                                                                                                                                                                      | file   |
+      | embeds                    | testdata/embed_2.xml                                                                                                                                                                                                                                                                                      | file   |
       | Gotenberg-Output-Filename | foo                                                                                                                                                                                                                                                                                                       | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the response:
       | foo.pdf |
-    Then the response PDF(s) should be valid "PDF/A-1b" with a tolerance of 9 failed rule(s)
-    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 2 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/A-3b" with a tolerance of 5 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 3 failed rule(s)
     Then the response PDF(s) should be flatten
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
     When I make a "POST" request to Gotenberg at the "/forms/pdfengines/metadata/read" endpoint with the following form data and header(s):
       | files | teststore/foo.pdf | file |
     Then the response status code should be 200
@@ -1041,11 +1097,8 @@ Feature: /forms/chromium/convert/html
         "foo.pdf": {
           "Author": "Julien Neuhart",
           "Copyright": "Julien Neuhart",
-          "CreateDate": "2006:09:18 16:27:50-04:00",
           "Creator": "Gotenberg",
-          "Keywords": ["first", "second"],
           "Marked": true,
-          "ModDate": "2006:09:18 16:27:50-04:00",
           "PDFVersion": 1.7,
           "Producer": "Gotenberg",
           "Subject": "Sample",
@@ -1062,19 +1115,16 @@ Feature: /forms/chromium/convert/html
       | files | testdata/page-1-html/index.html | file |
     Then the response status code should be 404
 
-  @telemetry
-  Scenario: POST /forms/chromium/convert/html (Telemetry)
+  Scenario: POST /forms/chromium/convert/html (Gotenberg Trace)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
-      | files            | testdata/page-1-html/index.html                         | file   |
-      | X-Correlation-ID | forms_chromium_convert_html                             | header |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 | header |
+      | files           | testdata/page-1-html/index.html | file   |
+      | Gotenberg-Trace | forms_chromium_convert_html     | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
-    Then the response header "X-Correlation-ID" should be "forms_chromium_convert_html"
+    Then the response header "Gotenberg-Trace" should be "forms_chromium_convert_html"
     Then the Gotenberg container should log the following entries:
       | "correlation_id":"forms_chromium_convert_html" |
-      | "trace_id":"12345678901234567890123456789012"  |
 
   @download-from
   Scenario: POST /forms/chromium/convert/html (Download From)
@@ -1124,3 +1174,27 @@ Feature: /forms/chromium/convert/html
       | files | testdata/page-1-html/index.html | file |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
+
+  # See: https://github.com/gotenberg/gotenberg/issues/1505.
+  Scenario: POST /forms/chromium/convert/html (Asset)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
+      | files                     | testdata/html-with-asset/index.html | file   |
+      | files                     | testdata/html-with-asset/image.png  | file   |
+      | Gotenberg-Output-Filename | foo                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+    Then the "foo.pdf" PDF should have 1 page(s)
+    Then the "foo.pdf" PDF should have 1 image(s)
+
+  # See: https://github.com/gotenberg/gotenberg/issues/1500.
+  Scenario: POST /forms/chromium/convert/html (Long Filename)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+    Then the "foo.pdf" PDF should have 1 page(s)

test/integration/features/chromium_convert_markdown.feature

@@ -357,7 +357,7 @@ Feature: /forms/chromium/convert/markdown
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then the Gotenberg container should log the following entries:
-      | 'file:///etc/passwd' does not match the expression from the allowed list |
+      | 'file:///etc/passwd' does not match any expression from the allowed list |
 
   Scenario: POST /forms/chromium/convert/markdown (JavaScript Enabled)
     Given I have a default Gotenberg container
@@ -459,7 +459,8 @@ Feature: /forms/chromium/convert/markdown
     Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
     Then the response body should match string:
       """
-      Markdown file(s) not found: 'page_2.md'; 'page_3.md'
+      Markdown file(s) not found: 'page_2.md'
+      'page_3.md'
       """
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
       | singlePage                    | foo | field |
@@ -488,7 +489,30 @@ Feature: /forms/chromium/convert/markdown
     Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
     Then the response body should match string:
       """
-      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo"); form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty); form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form file 'index.html' is required; no form file found for extensions: [.md]
+      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo")
+      form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty)
+      form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form file 'index.html' is required
+      no form file found for extensions: [.md]
       """
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
       | files          | testdata/page-1-markdown/index.html | file  |
@@ -991,50 +1015,50 @@ Feature: /forms/chromium/convert/markdown
     Then there should be 1 PDF(s) in the response
     Then the response PDF(s) should be encrypted
 
-  @attachments
-  Scenario: POST /forms/chromium/convert/markdown (Attachments)
+  @embed
+  Scenario: POST /forms/chromium/convert/markdown (Embeds)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
       | files                     | testdata/page-1-markdown/index.html | file   |
       | files                     | testdata/page-1-markdown/page_1.md  | file   |
-      | attachments               | testdata/attachment_1.xml           | file   |
-      | attachments               | testdata/attachment_2.xml           | file   |
+      | embeds                    | testdata/embed_1.xml                | file   |
+      | embeds                    | testdata/embed_2.xml                | file   |
       | Gotenberg-Output-Filename | foo                                 | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the response:
       | foo.pdf |
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
 
   # FIXME: once decrypt is done, add encrypt and check after the content of the PDF.
   @convert
   @metadata
   @flatten
-  @attachments
-  Scenario: POST /forms/chromium/convert/markdown (PDF/A-1b & PDF/UA-1 & Metadata & Flatten & Attachments)
+  @embed
+  Scenario: POST /forms/chromium/convert/markdown (PDF/A-3b & PDF/UA-1 & Metadata & Flatten & Embeds)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
       | files                     | testdata/page-1-markdown/index.html                                                                                                                                                                                                                                                                       | file   |
       | files                     | testdata/page-1-markdown/page_1.md                                                                                                                                                                                                                                                                        | file   |
-      | pdfa                      | PDF/A-1b                                                                                                                                                                                                                                                                                                  | field  |
+      | pdfa                      | PDF/A-3b                                                                                                                                                                                                                                                                                                  | field  |
       | pdfua                     | true                                                                                                                                                                                                                                                                                                      | field  |
       | metadata                  | {"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreateDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"} | field  |
       | flatten                   | true                                                                                                                                                                                                                                                                                                      | field  |
-      | attachments               | testdata/attachment_1.xml                                                                                                                                                                                                                                                                                 | file   |
-      | attachments               | testdata/attachment_2.xml                                                                                                                                                                                                                                                                                 | file   |
+      | embeds                    | testdata/embed_1.xml                                                                                                                                                                                                                                                                                      | file   |
+      | embeds                    | testdata/embed_2.xml                                                                                                                                                                                                                                                                                      | file   |
       | Gotenberg-Output-Filename | foo                                                                                                                                                                                                                                                                                                       | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the response:
       | foo.pdf |
-    Then the response PDF(s) should be valid "PDF/A-1b" with a tolerance of 9 failed rule(s)
-    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 2 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/A-3b" with a tolerance of 5 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 3 failed rule(s)
     Then the response PDF(s) should be flatten
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
     When I make a "POST" request to Gotenberg at the "/forms/pdfengines/metadata/read" endpoint with the following form data and header(s):
       | files | teststore/foo.pdf | file |
     Then the response status code should be 200
@@ -1045,11 +1069,8 @@ Feature: /forms/chromium/convert/markdown
         "foo.pdf": {
           "Author": "Julien Neuhart",
           "Copyright": "Julien Neuhart",
-          "CreateDate": "2006:09:18 16:27:50-04:00",
           "Creator": "Gotenberg",
-          "Keywords": ["first", "second"],
           "Marked": true,
-          "ModDate": "2006:09:18 16:27:50-04:00",
           "PDFVersion": 1.7,
           "Producer": "Gotenberg",
           "Subject": "Sample",
@@ -1067,20 +1088,17 @@ Feature: /forms/chromium/convert/markdown
       | files | testdata/page-1-markdown/page_1.md  | file |
     Then the response status code should be 404
 
-  @telemetry
-  Scenario: POST /forms/chromium/convert/markdown (Telemetry)
+  Scenario: POST /forms/chromium/convert/markdown (Gotenberg Trace)
     Given I have a default Gotenberg container
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
-      | files            | testdata/page-1-markdown/index.html                     | file   |
-      | files            | testdata/page-1-markdown/page_1.md                      | file   |
-      | X-Correlation-ID | forms_chromium_convert_markdown                         | header |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 | header |
+      | files           | testdata/page-1-markdown/index.html | file   |
+      | files           | testdata/page-1-markdown/page_1.md  | file   |
+      | Gotenberg-Trace | forms_chromium_convert_html         | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
-    Then the response header "X-Correlation-ID" should be "forms_chromium_convert_markdown"
+    Then the response header "Gotenberg-Trace" should be "forms_chromium_convert_html"
     Then the Gotenberg container should log the following entries:
-      | "correlation_id":"forms_chromium_convert_markdown" |
-      | "trace_id":"12345678901234567890123456789012"      |
+      | "correlation_id":"forms_chromium_convert_html" |
 
   @download-from
   Scenario: POST /forms/chromium/convert/markdown (Download From)
@@ -1134,3 +1152,15 @@ Feature: /forms/chromium/convert/markdown
       | files | testdata/page-1-markdown/page_1.md  | file |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
+
+  # See: https://github.com/gotenberg/gotenberg/issues/1500.
+  Scenario: POST /forms/chromium/convert/markdown (Long Filename)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/markdown" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-markdown/index.html | file   |
+      | files                     | testdata/page-1-markdown/page_1.md  | file   |
+      | Gotenberg-Output-Filename | foo                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+    Then the "foo.pdf" PDF should have 1 page(s)

test/integration/features/chromium_convert_url.feature

@@ -476,7 +476,7 @@ Feature: /forms/chromium/convert/url
     Then there should be 1 PDF(s) in the response
     Then the Gotenberg container should NOT log the following entries:
       # Modern browsers block file URIs from being loaded into iframes when the parent page is served over HTTP/HTTPS.
-      | 'file:///etc/passwd' does not match the expression from the allowed list |
+      | 'file:///etc/passwd' does not match any expression from the allowed list |
 
   Scenario: POST /forms/chromium/convert/url (JavaScript Enabled)
     Given I have a default Gotenberg container
@@ -598,7 +598,29 @@ Feature: /forms/chromium/convert/url
     Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
     Then the response body should match string:
       """
-      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a')); form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo"); form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty); form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax); form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax); form field 'url' is required
+      Invalid form data: form field 'skipNetworkIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'skipNetworkAlmostIdleEvent' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceHttpStatusCodes' is invalid (got 'foo', resulting to unmarshal failOnResourceHttpStatusCodes: invalid character 'o' in literal false (expecting 'a'))
+      form field 'failOnResourceLoadingFailed' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'failOnConsoleExceptions' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'waitDelay' is invalid (got 'foo', resulting to time: invalid duration "foo")
+      form field 'emulatedMediaType' is invalid (got 'foo', resulting to wrong value, expected either 'screen', 'print' or empty)
+      form field 'omitBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'landscape' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'printBackground' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'scale' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'singlePage' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'paperWidth' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'paperHeight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginTop' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginBottom' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginLeft' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'marginRight' is invalid (got 'foo', resulting to strconv.ParseFloat: parsing "foo": invalid syntax)
+      form field 'preferCssPageSize' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateDocumentOutline' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'generateTaggedPdf' is invalid (got 'foo', resulting to strconv.ParseBool: parsing "foo": invalid syntax)
+      form field 'url' is required
       """
     Given I have a static server
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/url" endpoint with the following form data and header(s):
@@ -1086,50 +1108,50 @@ Feature: /forms/chromium/convert/url
     Then there should be 1 PDF(s) in the response
     Then the response PDF(s) should be encrypted
 
-  @attachments
-  Scenario: POST /foo/forms/chromium/convert/url (Attachments)
+  @embed
+  Scenario: POST /foo/forms/chromium/convert/url (Embeds)
     Given I have a default Gotenberg container
     Given I have a static server
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/url" endpoint with the following form data and header(s):
       | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
-      | attachments               | testdata/attachment_1.xml                                           | file   |
-      | attachments               | testdata/attachment_2.xml                                           | file   |
+      | embeds                    | testdata/embed_1.xml                                                | file   |
+      | embeds                    | testdata/embed_2.xml                                                | file   |
       | Gotenberg-Output-Filename | foo                                                                 | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the webhook request:
       | foo.pdf |
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
 
   # FIXME: once decrypt is done, add encrypt and check after the content of the PDF.
   @convert
   @metadata
   @flatten
-  @attachments
-  Scenario: POST /forms/chromium/convert/url (PDF/A-1b & PDF/UA-1 & Metadata & Flatten)
+  @embed
+  Scenario: POST /forms/chromium/convert/url (PDF/A-3b & PDF/UA-1 & Metadata & Flatten & Embeds)
     Given I have a default Gotenberg container
     Given I have a static server
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/url" endpoint with the following form data and header(s):
       | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html                                                                                                                                                                                                                                       | field  |
-      | pdfa                      | PDF/A-1b                                                                                                                                                                                                                                                                                                  | field  |
+      | pdfa                      | PDF/A-3b                                                                                                                                                                                                                                                                                                  | field  |
       | pdfua                     | true                                                                                                                                                                                                                                                                                                      | field  |
       | metadata                  | {"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreateDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"} | field  |
       | flatten                   | true                                                                                                                                                                                                                                                                                                      | field  |
-      | attachments               | testdata/attachment_1.xml                                                                                                                                                                                                                                                                                 | file   |
-      | attachments               | testdata/attachment_2.xml                                                                                                                                                                                                                                                                                 | file   |
+      | embeds                    | testdata/embed_1.xml                                                                                                                                                                                                                                                                                      | file   |
+      | embeds                    | testdata/embed_2.xml                                                                                                                                                                                                                                                                                      | file   |
       | Gotenberg-Output-Filename | foo                                                                                                                                                                                                                                                                                                       | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
     Then there should be 1 PDF(s) in the response
     Then there should be the following file(s) in the response:
       | foo.pdf |
-    Then the response PDF(s) should be valid "PDF/A-1b" with a tolerance of 9 failed rule(s)
-    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 2 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/A-3b" with a tolerance of 5 failed rule(s)
+    Then the response PDF(s) should be valid "PDF/UA-1" with a tolerance of 3 failed rule(s)
     Then the response PDF(s) should be flatten
-    Then the response PDF(s) should have the "attachment_1.xml" file attached
-    Then the response PDF(s) should have the "attachment_2.xml" file attached
+    Then the response PDF(s) should have the "embed_1.xml" file embedded
+    Then the response PDF(s) should have the "embed_2.xml" file embedded
     When I make a "POST" request to Gotenberg at the "/forms/pdfengines/metadata/read" endpoint with the following form data and header(s):
       | files | teststore/foo.pdf | file |
     Then the response status code should be 200
@@ -1140,11 +1162,8 @@ Feature: /forms/chromium/convert/url
         "foo.pdf": {
           "Author": "Julien Neuhart",
           "Copyright": "Julien Neuhart",
-          "CreateDate": "2006:09:18 16:27:50-04:00",
           "Creator": "Gotenberg",
-          "Keywords": ["first", "second"],
           "Marked": true,
-          "ModDate": "2006:09:18 16:27:50-04:00",
           "PDFVersion": 1.7,
           "Producer": "Gotenberg",
           "Subject": "Sample",
@@ -1162,20 +1181,17 @@ Feature: /forms/chromium/convert/url
       | url | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field |
     Then the response status code should be 404
 
-  @telemetry
-  Scenario: POST /forms/chromium/convert/url (Telemetry)
+  Scenario: POST /forms/chromium/convert/url (Gotenberg Trace)
     Given I have a default Gotenberg container
     Given I have a static server
     When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/url" endpoint with the following form data and header(s):
-      | url              | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
-      | X-Correlation-ID | forms_chromium_convert_url                                          | header |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01             | header |
+      | url             | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | Gotenberg-Trace | forms_chromium_convert_url                                          | header |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
-    Then the response header "X-Correlation-ID" should be "forms_chromium_convert_url"
+    Then the response header "Gotenberg-Trace" should be "forms_chromium_convert_url"
     Then the Gotenberg container should log the following entries:
       | "correlation_id":"forms_chromium_convert_url" |
-      | "trace_id":"12345678901234567890123456789012" |
 
   @webhook
   Scenario: POST /forms/chromium/convert/url (Webhook)
@@ -1217,3 +1233,15 @@ Feature: /forms/chromium/convert/url
       | url | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field |
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/pdf"
+
+  # See: https://github.com/gotenberg/gotenberg/issues/1500.
+  Scenario: POST /forms/chromium/convert/url (Long Filename)
+    Given I have a default Gotenberg container
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/convert/url" endpoint with the following form data and header(s):
+      | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | Gotenberg-Output-Filename | foo                                                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "application/pdf"
+    Then there should be 1 PDF(s) in the response
+    Then the "foo.pdf" PDF should have 1 page(s)

test/integration/features/chromium_screenshot_html.feature

@@ -0,0 +1,151 @@
+@chromium
+@chromium-screenshot-html
+Feature: /forms/chromium/screenshot/html
+
+  Scenario: POST /forms/chromium/screenshot/html (Default)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the response:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/html (JPEG)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | format                    | jpeg                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/jpeg"
+    Then there should be the following file(s) in the response:
+      | foo.jpeg |
+
+  Scenario: POST /forms/chromium/screenshot/html (WebP)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | format                    | webp                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/webp"
+    Then there should be the following file(s) in the response:
+      | foo.webp |
+
+  Scenario: POST /forms/chromium/screenshot/html (Custom Dimensions)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | width                     | 1920                            | field  |
+      | height                    | 1080                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  Scenario: POST /forms/chromium/screenshot/html (Clip)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | clip                      | true                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  Scenario: POST /forms/chromium/screenshot/html (Quality)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | format                    | jpeg                            | field  |
+      | quality                   | 50                              | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/jpeg"
+
+  Scenario: POST /forms/chromium/screenshot/html (Optimize for Speed)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | optimizeForSpeed          | true                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  Scenario: POST /forms/chromium/screenshot/html (Omit Background)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | omitBackground            | true                            | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  Scenario: POST /forms/chromium/screenshot/html (Emulated Media Type)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | emulatedMediaType         | screen                          | field  |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  Scenario: POST /forms/chromium/screenshot/html (Bad Request)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | skipNetworkIdleEvent        | foo | field |
+      | skipNetworkAlmostIdleEvent  | foo | field |
+      | failOnResourceLoadingFailed | foo | field |
+      | failOnConsoleExceptions     | foo | field |
+      | emulatedMediaType           | foo | field |
+      | omitBackground              | foo | field |
+      | width                       | foo | field |
+      | height                      | foo | field |
+      | clip                        | foo | field |
+      | format                      | bar | field |
+      | quality                     | -1  | field |
+      | optimizeForSpeed            | foo | field |
+    Then the response status code should be 400
+    Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
+
+  @webhook
+  Scenario: POST /forms/chromium/screenshot/html (Webhook)
+    Given I have a default Gotenberg container
+    Given I have a webhook server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                       | testdata/page-1-html/index.html              | file   |
+      | Gotenberg-Output-Filename   | foo                                          | header |
+      | Gotenberg-Webhook-Url       | http://host.docker.internal:%d/webhook       | header |
+      | Gotenberg-Webhook-Error-Url | http://host.docker.internal:%d/webhook/error | header |
+    Then the response status code should be 204
+    When I wait for the asynchronous request to the webhook
+    Then the webhook request header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the webhook request:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/html (Basic Auth)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_BASIC_AUTH             | true |
+      | GOTENBERG_API_BASIC_AUTH_USERNAME | foo  |
+      | GOTENBERG_API_BASIC_AUTH_PASSWORD | bar  |
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files | testdata/page-1-html/index.html | file |
+    Then the response status code should be 401
+
+  Scenario: POST /foo/forms/chromium/screenshot/html (Root Path)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_DEBUG_ROUTE | true  |
+      | API_ROOT_PATH          | /foo/ |
+    When I make a "POST" request to Gotenberg at the "/foo/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files | testdata/page-1-html/index.html | file |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+
+  # See: https://github.com/gotenberg/gotenberg/issues/1500.
+  Scenario: POST /forms/chromium/screenshot/html (Long Filename)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/html" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-html/index.html | file   |
+      | Gotenberg-Output-Filename | foo                             | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"

test/integration/features/chromium_screenshot_markdown.feature

@@ -0,0 +1,81 @@
+@chromium
+@chromium-screenshot-markdown
+Feature: /forms/chromium/screenshot/markdown
+
+  Scenario: POST /forms/chromium/screenshot/markdown (Default)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-markdown/index.html | file   |
+      | files                     | testdata/page-1-markdown/page_1.md  | file   |
+      | Gotenberg-Output-Filename | foo                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the response:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/markdown (JPEG)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-markdown/index.html | file   |
+      | files                     | testdata/page-1-markdown/page_1.md  | file   |
+      | format                    | jpeg                                | field  |
+      | Gotenberg-Output-Filename | foo                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/jpeg"
+    Then there should be the following file(s) in the response:
+      | foo.jpeg |
+
+  Scenario: POST /forms/chromium/screenshot/markdown (WebP)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files                     | testdata/page-1-markdown/index.html | file   |
+      | files                     | testdata/page-1-markdown/page_1.md  | file   |
+      | format                    | webp                                | field  |
+      | Gotenberg-Output-Filename | foo                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/webp"
+    Then there should be the following file(s) in the response:
+      | foo.webp |
+
+  Scenario: POST /forms/chromium/screenshot/markdown (Bad Request - Missing Files)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | Gotenberg-Output-Filename | foo | header |
+    Then the response status code should be 400
+    Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
+
+  @webhook
+  Scenario: POST /forms/chromium/screenshot/markdown (Webhook)
+    Given I have a default Gotenberg container
+    Given I have a webhook server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files                       | testdata/page-1-markdown/index.html          | file   |
+      | files                       | testdata/page-1-markdown/page_1.md           | file   |
+      | Gotenberg-Output-Filename   | foo                                          | header |
+      | Gotenberg-Webhook-Url       | http://host.docker.internal:%d/webhook       | header |
+      | Gotenberg-Webhook-Error-Url | http://host.docker.internal:%d/webhook/error | header |
+    Then the response status code should be 204
+    When I wait for the asynchronous request to the webhook
+    Then the webhook request header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the webhook request:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/markdown (Basic Auth)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_BASIC_AUTH             | true |
+      | GOTENBERG_API_BASIC_AUTH_USERNAME | foo  |
+      | GOTENBERG_API_BASIC_AUTH_PASSWORD | bar  |
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files | testdata/page-1-markdown/index.html | file |
+      | files | testdata/page-1-markdown/page_1.md  | file |
+    Then the response status code should be 401
+
+  Scenario: POST /foo/forms/chromium/screenshot/markdown (Root Path)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_DEBUG_ROUTE | true  |
+      | API_ROOT_PATH          | /foo/ |
+    When I make a "POST" request to Gotenberg at the "/foo/forms/chromium/screenshot/markdown" endpoint with the following form data and header(s):
+      | files | testdata/page-1-markdown/index.html | file |
+      | files | testdata/page-1-markdown/page_1.md  | file |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"

test/integration/features/chromium_screenshot_url.feature

@@ -0,0 +1,81 @@
+@chromium
+@chromium-screenshot-url
+Feature: /forms/chromium/screenshot/url
+
+  Scenario: POST /forms/chromium/screenshot/url (Default)
+    Given I have a default Gotenberg container
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | Gotenberg-Output-Filename | foo                                                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the response:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/url (JPEG)
+    Given I have a default Gotenberg container
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | format                    | jpeg                                                                | field  |
+      | Gotenberg-Output-Filename | foo                                                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/jpeg"
+    Then there should be the following file(s) in the response:
+      | foo.jpeg |
+
+  Scenario: POST /forms/chromium/screenshot/url (WebP)
+    Given I have a default Gotenberg container
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url                       | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | format                    | webp                                                                | field  |
+      | Gotenberg-Output-Filename | foo                                                                 | header |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/webp"
+    Then there should be the following file(s) in the response:
+      | foo.webp |
+
+  Scenario: POST /forms/chromium/screenshot/url (Bad Request - Missing URL)
+    Given I have a default Gotenberg container
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | Gotenberg-Output-Filename | foo | header |
+    Then the response status code should be 400
+    Then the response header "Content-Type" should be "text/plain; charset=UTF-8"
+
+  @webhook
+  Scenario: POST /forms/chromium/screenshot/url (Webhook)
+    Given I have a default Gotenberg container
+    Given I have a static server
+    Given I have a webhook server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url                         | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field  |
+      | Gotenberg-Output-Filename   | foo                                                                 | header |
+      | Gotenberg-Webhook-Url       | http://host.docker.internal:%d/webhook                              | header |
+      | Gotenberg-Webhook-Error-Url | http://host.docker.internal:%d/webhook/error                        | header |
+    Then the response status code should be 204
+    When I wait for the asynchronous request to the webhook
+    Then the webhook request header "Content-Type" should be "image/png"
+    Then there should be the following file(s) in the webhook request:
+      | foo.png |
+
+  Scenario: POST /forms/chromium/screenshot/url (Basic Auth)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_BASIC_AUTH             | true |
+      | GOTENBERG_API_BASIC_AUTH_USERNAME | foo  |
+      | GOTENBERG_API_BASIC_AUTH_PASSWORD | bar  |
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field |
+    Then the response status code should be 401
+
+  Scenario: POST /foo/forms/chromium/screenshot/url (Root Path)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_ENABLE_DEBUG_ROUTE | true  |
+      | API_ROOT_PATH          | /foo/ |
+    Given I have a static server
+    When I make a "POST" request to Gotenberg at the "/foo/forms/chromium/screenshot/url" endpoint with the following form data and header(s):
+      | url | http://host.docker.internal:%d/html/testdata/page-1-html/index.html | field |
+    Then the response status code should be 200
+    Then the response header "Content-Type" should be "image/png"

test/integration/features/debug.feature

@@ -28,6 +28,7 @@ Feature: /debug
           "pdfcpu",
           "pdfengines",
           "pdftk",
+          "prometheus",
           "qpdf",
           "webhook"
         ],
@@ -54,14 +55,15 @@ Feature: /debug
         "flags": {
           "api-bind-ip": "",
           "api-body-limit": "",
-          "api-correlation-id-header": "X-Correlation-ID",
-          "api-disable-debug-route-telemetry": "false",
+          "api-correlation-id-header": "Gotenberg-Trace",
           "api-disable-download-from": "false",
-          "api-disable-health-check-route-telemetry": "false",
-          "api-disable-root-route-telemetry": "false",
-          "api-disable-version-route-telemetry": "false",
-          "api-download-from-allow-list": "",
-          "api-download-from-deny-list": "",
+          "api-disable-health-check-logging": "false",
+          "api-disable-debug-route-telemetry": "true",
+          "api-disable-health-check-route-telemetry": "true",
+          "api-disable-root-route-telemetry": "true",
+          "api-disable-version-route-telemetry": "true",
+          "api-download-from-allow-list": "[]",
+          "api-download-from-deny-list": "[]",
           "api-download-from-max-retry": "4",
           "api-enable-basic-auth": "false",
           "api-enable-debug-route": "true",
@@ -72,51 +74,62 @@ Feature: /debug
           "api-timeout": "30s",
           "api-tls-cert-file": "",
           "api-tls-key-file": "",
+          "api-trace-header": "Gotenberg-Trace",
           "chromium-allow-file-access-from-files": "false",
           "chromium-allow-insecure-localhost": "false",
-          "chromium-allow-list": "",
+          "chromium-allow-list": "[]",
           "chromium-auto-start": "false",
           "chromium-clear-cache": "false",
           "chromium-clear-cookies": "false",
-          "chromium-deny-list": "^file:(?!//\\/tmp/).*",
+          "chromium-deny-list": "[^file:(?!//\\/tmp/).*]",
           "chromium-disable-javascript": "false",
           "chromium-disable-routes": "false",
           "chromium-disable-web-security": "false",
           "chromium-host-resolver-rules": "",
           "chromium-ignore-certificate-errors": "false",
-          "chromium-max-queue-size": "0",
+          "chromium-idle-shutdown-timeout": "0s",
+          "chromium-incognito": "false",
           "chromium-max-concurrency": "6",
+          "chromium-max-queue-size": "0",
           "chromium-proxy-server": "",
           "chromium-restart-after": "100",
           "chromium-start-timeout": "20s",
           "gotenberg-build-debug-data": "true",
           "gotenberg-graceful-shutdown-duration": "30s",
-          "gotenberg-hide-banner": "false",
           "libreoffice-auto-start": "false",
           "libreoffice-disable-routes": "false",
+          "libreoffice-idle-shutdown-timeout": "0s",
           "libreoffice-max-queue-size": "0",
           "libreoffice-restart-after": "10",
           "libreoffice-start-timeout": "20s",
+          "log-enable-gcp-fields": "false",
           "log-fields-prefix": "",
+          "log-format": "auto",
           "log-level": "info",
           "log-std-enable-gcp-fields": "false",
           "log-std-format": "auto",
           "pdfengines-convert-engines": "[libreoffice-pdfengine]",
           "pdfengines-disable-routes": "false",
-          "pdfengines-add-attachments-engines": "[pdfcpu]",
-          "pdfengines-encrypt-engines": "[qpdf,pdfcpu,pdftk]",
+          "pdfengines-engines": "[]",
           "pdfengines-flatten-engines": "[qpdf]",
           "pdfengines-merge-engines": "[qpdf,pdfcpu,pdftk]",
+          "pdfengines-read-bookmarks-engines": "[pdfcpu]",
           "pdfengines-read-metadata-engines": "[exiftool]",
           "pdfengines-split-engines": "[pdfcpu,qpdf,pdftk]",
+          "pdfengines-write-bookmarks-engines": "[pdfcpu]",
           "pdfengines-write-metadata-engines": "[exiftool]",
-          "webhook-allow-list": "",
+          "prometheus-collect-interval": "1s",
+          "prometheus-disable-collect": "false",
+          "prometheus-disable-route-logging": "false",
+          "prometheus-disable-route-telemetry": "true",
+          "prometheus-namespace": "gotenberg",
+          "prometheus-metrics-path": "/prometheus/metrics",
+          "webhook-allow-list": "[]",
           "webhook-client-timeout": "30s",
-          "webhook-deny-list": "",
+          "webhook-deny-list": "[]",
           "webhook-disable": "false",
-          "webhook-enable-sync-mode": "false",
-          "webhook-error-allow-list": "",
-          "webhook-error-deny-list": "",
+          "webhook-error-allow-list": "[]",
+          "webhook-error-deny-list": "[]",
           "webhook-max-retry": "4",
           "webhook-retry-max-wait": "30s",
           "webhook-retry-min-wait": "1s"
@@ -124,7 +137,7 @@ Feature: /debug
       }
       """
 
-  Scenario: GET /debug (Environment Based Timezone)
+  Scenario: GET /debug (Environment based timezone)
     Given I have a Gotenberg container with the following environment variable(s):
       | API_ENABLE_DEBUG_ROUTE | true             |
       | TZ                     | America/New_York |
@@ -147,6 +160,7 @@ Feature: /debug
           "pdfcpu",
           "pdfengines",
           "pdftk",
+          "prometheus",
           "qpdf",
           "webhook"
         ],
@@ -173,14 +187,15 @@ Feature: /debug
         "flags": {
           "api-bind-ip": "",
           "api-body-limit": "",
-          "api-correlation-id-header": "X-Correlation-ID",
-          "api-disable-debug-route-telemetry": "false",
+          "api-correlation-id-header": "Gotenberg-Trace",
           "api-disable-download-from": "false",
-          "api-disable-health-check-route-telemetry": "false",
-          "api-disable-root-route-telemetry": "false",
-          "api-disable-version-route-telemetry": "false",
-          "api-download-from-allow-list": "",
-          "api-download-from-deny-list": "",
+          "api-disable-health-check-logging": "false",
+          "api-disable-debug-route-telemetry": "true",
+          "api-disable-health-check-route-telemetry": "true",
+          "api-disable-root-route-telemetry": "true",
+          "api-disable-version-route-telemetry": "true",
+          "api-download-from-allow-list": "[]",
+          "api-download-from-deny-list": "[]",
           "api-download-from-max-retry": "4",
           "api-enable-basic-auth": "false",
           "api-enable-debug-route": "true",
@@ -191,18 +206,21 @@ Feature: /debug
           "api-timeout": "30s",
           "api-tls-cert-file": "",
           "api-tls-key-file": "",
+          "api-trace-header": "Gotenberg-Trace",
           "chromium-allow-file-access-from-files": "false",
           "chromium-allow-insecure-localhost": "false",
-          "chromium-allow-list": "",
+          "chromium-allow-list": "[]",
           "chromium-auto-start": "false",
           "chromium-clear-cache": "false",
           "chromium-clear-cookies": "false",
-          "chromium-deny-list": "^file:(?!//\\/tmp/).*",
+          "chromium-deny-list": "[^file:(?!//\\/tmp/).*]",
           "chromium-disable-javascript": "false",
           "chromium-disable-routes": "false",
           "chromium-disable-web-security": "false",
           "chromium-host-resolver-rules": "",
           "chromium-ignore-certificate-errors": "false",
+          "chromium-idle-shutdown-timeout": "0s",
+          "chromium-incognito": "false",
           "chromium-max-queue-size": "0",
           "chromium-max-concurrency": "6",
           "chromium-proxy-server": "",
@@ -210,32 +228,40 @@ Feature: /debug
           "chromium-start-timeout": "20s",
           "gotenberg-build-debug-data": "true",
           "gotenberg-graceful-shutdown-duration": "30s",
-          "gotenberg-hide-banner": "false",
           "libreoffice-auto-start": "false",
           "libreoffice-disable-routes": "false",
+          "libreoffice-idle-shutdown-timeout": "0s",
           "libreoffice-max-queue-size": "0",
           "libreoffice-restart-after": "10",
           "libreoffice-start-timeout": "20s",
+          "log-enable-gcp-fields": "false",
           "log-fields-prefix": "",
+          "log-format": "auto",
           "log-level": "info",
           "log-std-enable-gcp-fields": "false",
           "log-std-format": "auto",
           "pdfengines-convert-engines": "[libreoffice-pdfengine]",
           "pdfengines-disable-routes": "false",
-          "pdfengines-add-attachments-engines": "[pdfcpu]",
-          "pdfengines-encrypt-engines": "[qpdf,pdfcpu,pdftk]",
+          "pdfengines-engines": "[]",
           "pdfengines-flatten-engines": "[qpdf]",
           "pdfengines-merge-engines": "[qpdf,pdfcpu,pdftk]",
+          "pdfengines-read-bookmarks-engines": "[pdfcpu]",
           "pdfengines-read-metadata-engines": "[exiftool]",
           "pdfengines-split-engines": "[pdfcpu,qpdf,pdftk]",
+          "pdfengines-write-bookmarks-engines": "[pdfcpu]",
           "pdfengines-write-metadata-engines": "[exiftool]",
-          "webhook-allow-list": "",
+          "prometheus-collect-interval": "1s",
+          "prometheus-disable-collect": "false",
+          "prometheus-disable-route-logging": "false",
+          "prometheus-disable-route-telemetry": "true",
+          "prometheus-namespace": "gotenberg",
+          "prometheus-metrics-path": "/prometheus/metrics",
+          "webhook-allow-list": "[]",
           "webhook-client-timeout": "30s",
-          "webhook-deny-list": "",
+          "webhook-deny-list": "[]",
           "webhook-disable": "false",
-          "webhook-enable-sync-mode": "false",
-          "webhook-error-allow-list": "",
-          "webhook-error-deny-list": "",
+          "webhook-error-allow-list": "[]",
+          "webhook-error-deny-list": "[]",
           "webhook-max-retry": "4",
           "webhook-retry-max-wait": "30s",
           "webhook-retry-min-wait": "1s"
@@ -262,31 +288,16 @@ Feature: /debug
       }
       """
 
-  @telemetry
-  Scenario: GET /debug (Telemetry)
+  Scenario: GET /debug (Gotenberg Trace)
     Given I have a Gotenberg container with the following environment variable(s):
-      | API_ENABLE_DEBUG_ROUTE | true |
+      | API_ENABLE_DEBUG_ROUTE            | true  |
+      | API_DISABLE_DEBUG_ROUTE_TELEMETRY | false |
     When I make a "GET" request to Gotenberg at the "/debug" endpoint with the following header(s):
-      | X-Correlation-ID | debug                                                   |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
+      | Gotenberg-Trace | debug |
     Then the response status code should be 200
-    Then the response header "X-Correlation-ID" should be "debug"
+    Then the response header "Gotenberg-Trace" should be "debug"
     Then the Gotenberg container should log the following entries:
-      | "correlation_id":"debug"                      |
-      | "trace_id":"12345678901234567890123456789012" |
-
-  @telemetry
-  Scenario: GET /debug (No Telemetry)
-    Given I have a Gotenberg container with the following environment variable(s):
-      | API_ENABLE_DEBUG_ROUTE            | true |
-      | API_DISABLE_DEBUG_ROUTE_TELEMETRY | true |
-    When I make a "GET" request to Gotenberg at the "/debug" endpoint with the following header(s):
-      | X-Correlation-ID | debug_no_telemetry                                      |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
-    Then the response status code should be 200
-    Then the Gotenberg container should NOT log the following entries:
-      | "correlation_id":"debug_no_telemetry"         |
-      | "trace_id":"12345678901234567890123456789012" |
+      | "correlation_id":"debug" |
 
   Scenario: GET /debug (Basic Auth)
     Given I have a Gotenberg container with the following environment variable(s):

test/integration/features/health.feature

@@ -6,7 +6,8 @@
 Feature: /health
 
   Scenario: GET /health
-    Given I have a default Gotenberg container
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | false |
     When I make a "GET" request to Gotenberg at the "/health" endpoint
     Then the response status code should be 200
     Then the response header "Content-Type" should be "application/json; charset=utf-8"
@@ -29,29 +30,23 @@ Feature: /health
     Then the Gotenberg container should log the following entries:
       | "path":"/health" |
 
-  @telemetry
-  Scenario: GET /health (Telemetry)
-    Given I have a default Gotenberg container
-    When I make a "GET" request to Gotenberg at the "/health" endpoint with the following header(s):
-      | X-Correlation-ID | get_health                                              |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
-    Then the response status code should be 200
-    Then the response header "X-Correlation-ID" should be "get_health"
-    Then the Gotenberg container should log the following entries:
-      | "correlation_id":"get_health"                 |
-      | "trace_id":"12345678901234567890123456789012" |
-
-  @telemetry
-  Scenario: GET /health (No Telemetry)
+  Scenario: GET /health (No Logging)
     Given I have a Gotenberg container with the following environment variable(s):
       | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | true |
-    When I make a "GET" request to Gotenberg at the "/health" endpoint with the following header(s):
-      | X-Correlation-ID | get_health_no_telemetry                                 |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
+    When I make a "GET" request to Gotenberg at the "/health" endpoint
     Then the response status code should be 200
     Then the Gotenberg container should NOT log the following entries:
-      | "correlation_id":"get_health_no_telemetry"    |
-      | "trace_id":"12345678901234567890123456789012" |
+      | "path":"/health" |
+
+  Scenario: GET /health (Gotenberg Trace)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | false |
+    When I make a "GET" request to Gotenberg at the "/health" endpoint with the following header(s):
+      | Gotenberg-Trace | get_health |
+    Then the response status code should be 200
+    Then the response header "Gotenberg-Trace" should be "get_health"
+    Then the Gotenberg container should log the following entries:
+      | "correlation_id":"get_health" |
 
   Scenario: GET /health (Basic Auth)
     Given I have a Gotenberg container with the following environment variable(s):
@@ -68,7 +63,8 @@ Feature: /health
     Then the response status code should be 200
 
   Scenario: HEAD /health
-    Given I have a default Gotenberg container
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | false |
     When I make a "HEAD" request to Gotenberg at the "/health" endpoint
     Then the response status code should be 200
     Then the response body should match string:
@@ -78,29 +74,23 @@ Feature: /health
     Then the Gotenberg container should log the following entries:
       | "path":"/health" |
 
-  @telemetry
-  Scenario: HEAD /health (Telemetry)
-    Given I have a default Gotenberg container
+  Scenario: HEAD /health (Gotenberg Trace)
+    Given I have a Gotenberg container with the following environment variable(s):
+      | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | false |
     When I make a "HEAD" request to Gotenberg at the "/health" endpoint with the following header(s):
-      | X-Correlation-ID | head_health                                             |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
+      | Gotenberg-Trace | head_health |
     Then the response status code should be 200
-    Then the response header "X-Correlation-ID" should be "head_health"
+    Then the response header "Gotenberg-Trace" should be "head_health"
     Then the Gotenberg container should log the following entries:
-      | "correlation_id":"head_health"                |
-      | "trace_id":"12345678901234567890123456789012" |
+      | "correlation_id":"head_health" |
 
-  @telemetry
-  Scenario: HEAD /health (No Telemetry)
+  Scenario: HEAD /health (No Logging)
     Given I have a Gotenberg container with the following environment variable(s):
       | API_DISABLE_HEALTH_CHECK_ROUTE_TELEMETRY | true |
-    When I make a "HEAD" request to Gotenberg at the "/health" endpoint with the following header(s):
-      | X-Correlation-ID | head_health_no_telemetry                                |
-      | traceparent      | 00-12345678901234567890123456789012-1234567890123456-01 |
+    When I make a "HEAD" request to Gotenberg at the "/health" endpoint
     Then the response status code should be 200
     Then the Gotenberg container should NOT log the following entries:
-      | "correlation_id":"head_health_no_telemetry"   |
-      | "trace_id":"12345678901234567890123456789012" |
+      | "path":"/health" |
 
   Scenario: HEAD /health (Basic Auth)
     Given I have a Gotenberg container with the following environment variable(s):