[ADD] Introduce base_report_paper_muncher module with Paper Muncher integration for PDF rendering

base_report_paper_muncher/README.rst

@@ -0,0 +1,199 @@
+============================
+Report Engine: Paper Muncher
+============================
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:b1d3faf687c4a3a6d43429969fc2e2e38e46f4fc707ef22f9d88f4cd9b94cf4a
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
+    :alt: License: LGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
+    :target: https://github.com/OCA/server-tools/tree/17.0/base_report_paper_muncher
+    :alt: OCA/server-tools
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/server-tools-17-0/server-tools-17-0-base_report_paper_muncher
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
+    :target: https://runboat.odoo-community.org/builds?repo=OCA/server-tools&target_branch=17.0
+    :alt: Try me on Runboat
+
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+This module integrates `Paper
+Muncher <https://odoo.github.io/paper-muncher/>`__ as the PDF rendering
+engine for QWeb reports. When the ``paper-muncher`` binary is available
+on the system, it replaces wkhtmltopdf as the default engine for PDF
+generation.
+
+Main features:
+
+- Automatic detection of the ``paper-muncher`` binary in ``PATH`` or in
+  ``/opt/paper-muncher/bin/paper-muncher``
+- Globally configurable PDF engine via the ``report.pdf_engine`` system
+  parameter
+- Multi-page header and footer support and ``report.paperformat``
+  integration
+- Transparent fallback to wkhtmltopdf when Paper Muncher is not
+  installed
+- HTTP-over-pipe communication between Odoo and the Paper Muncher
+  subprocess, so report assets are served with Odoo permissions
+
+This module depends on:
+
+- Odoo modules: ``base``, ``web``
+- Python package: ``h11``
+- System binary: ``paper-muncher`` from `GitHub
+  releases <https://github.com/odoo/paper-muncher/releases>`__
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Installation
+============
+
+Install the ``paper-muncher`` system binary before enabling this module.
+Example for Ubuntu 22.04 (Jammy):
+
+.. code:: bash
+
+   curl -fsSL -o paper-muncher.deb \
+     "https://github.com/odoo/paper-muncher/releases/download/v0.3.1-1/paper-muncher_v0.3.1-1_jammy_amd64.deb"
+   sudo apt install ./paper-muncher.deb
+   paper-muncher --help
+
+If the binary is not installed via the ``.deb`` package, add
+``/opt/paper-muncher/bin`` to the ``PATH`` of the Odoo process.
+
+The Python dependency ``h11`` is declared in the module manifest and
+listed in ``requirements.txt``. Install it in the Odoo Python
+environment if needed:
+
+.. code:: bash
+
+   pip install h11
+
+Then install the module as any other Odoo addon:
+
+.. code:: bash
+
+   odoo -d <database> -i base_report_paper_muncher --stop-after-init
+
+Paper Muncher is only supported on Linux and macOS.
+
+Configuration
+=============
+
+The system parameter ``report.pdf_engine`` controls which PDF engine is
+used:
+
++--------------------+-------------------------------------------------+
+| Value              | Behavior                                        |
++====================+=================================================+
+| ``auto`` (default) | Use Paper Muncher when the binary is available, |
+|                    | otherwise wkhtmltopdf                           |
++--------------------+-------------------------------------------------+
+| ``paper-muncher``  | Force Paper Muncher; raise an error if the      |
+|                    | binary is missing                               |
++--------------------+-------------------------------------------------+
+| ``wkhtmltopdf``    | Always use wkhtmltopdf                          |
++--------------------+-------------------------------------------------+
+
+Change it from code:
+
+.. code:: python
+
+   env["ir.config_parameter"].sudo().set_param("report.pdf_engine", "auto")
+
+Or from **Settings > Technical > Parameters > System Parameters**, key
+``report.pdf_engine``.
+
+Optional environment variables for the Odoo process:
+
+- ``ODOO_PAPER_MUNCHER_FEATURE=1``: pass ``--feature *=on`` to the
+  binary
+- ``ODOO_PAPER_MUNCHER_DEBUG=1``: pass ``--debug http-client`` to the
+  binary. This flag is not sent by default in production. It is also
+  enabled automatically when the module logger is set to ``DEBUG``.
+
+Usage
+=====
+
+Once installed and configured, QWeb PDF reports use Paper Muncher
+automatically when the binary is available and ``report.pdf_engine`` is
+set to ``auto`` or ``paper-muncher``.
+
+Check the engine status:
+
+.. code:: python
+
+   env["ir.actions.report"].get_wkhtmltopdf_state()
+
+Returns ``ok`` when Paper Muncher is available with ``auto`` or
+``paper-muncher``. Returns ``install`` when ``paper-muncher`` is forced
+but the binary is missing.
+
+When generating PDFs, look for log lines prefixed with ``PDF engine:``:
+
+- ``PDF engine: Paper-Muncher (...)``: rendering started with Paper
+  Muncher
+- ``PDF engine: Paper-Muncher completed (...)``: PDF generated
+  successfully
+- ``PDF engine: wkhtmltopdf (...)``: fallback to wkhtmltopdf
+
+Low-level HTTP-over-pipe details are logged at ``DEBUG`` level only.
+
+Known issues / Roadmap
+======================
+
+- Paper Muncher is only supported on Linux and macOS (not Windows).
+- WebSocket requests are rejected by the HTTP-over-pipe server.
+- Rendering timeout: 15 minutes (``SERVE_TIMEOUT``).
+- Pipe write timeout: 15 seconds (``WRITE_TIMEOUT``).
+- The binary must be installed on the system; this module only
+  integrates the communication layer.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/server-tools/issues/new?body=module:%20base_report_paper_muncher%0Aversion:%2017.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Contributors
+------------
+
+- Felix Coca <https://github.com/drkpkg>
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+This module is part of the `OCA/server-tools <https://github.com/OCA/server-tools/tree/17.0/base_report_paper_muncher>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

base_report_paper_muncher/__init__.py

@@ -0,0 +1,3 @@
+# Part of Odoo. See LICENSE file for full copyright and licensing details.
+
+from . import models

base_report_paper_muncher/__manifest__.py

@@ -0,0 +1,27 @@
+# Part of Odoo. See LICENSE file for full copyright and licensing details.
+
+{
+    "name": "Report Engine: Paper Muncher",
+    "summary": (
+        "Paper Muncher PDF rendering engine for QWeb reports, "
+        "replacing wkhtmltopdf when the binary is available"
+    ),
+    "version": "17.0.1.0.0",
+    "development_status": "Beta",
+    "category": "Hidden/Tools",
+    "website": "https://github.com/OCA/server-tools",
+    "author": "Odoo Community Association (OCA)",
+    "depends": [
+        "base",
+        "web",
+    ],
+    "data": [
+        "data/ir_config_parameter_data.xml",
+    ],
+    "external_dependencies": {
+        "python": ["h11"],
+    },
+    "license": "LGPL-3",
+    "installable": True,
+    "application": False,
+}

base_report_paper_muncher/data/ir_config_parameter_data.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<odoo noupdate="1">
+    <record id="ir_config_parameter_report_pdf_engine" model="ir.config_parameter">
+        <field name="key">report.pdf_engine</field>
+        <field name="value">auto</field>
+    </record>
+</odoo>

base_report_paper_muncher/models/__init__.py

@@ -0,0 +1,3 @@
+# Part of Odoo. See LICENSE file for full copyright and licensing details.
+
+from . import ir_actions_report