Fix: keep counter and extension when shortening long public filenames (#14472)

get_public_filename relied on sanitize_filename to truncate, which cuts
from the end and so dropped the counter and extension of long titles.
Multi-byte titles could also exceed the 255 byte filesystem limit.

Shorten the title by UTF-8 bytes before appending the counter and
extension. The exporter reserves room for its longer derived thumbnail
and archive suffixes.

src/documents/tests/test_document_model.py

@@ -4,13 +4,16 @@ from datetime import date
 from pathlib import Path
 from unittest import mock
 
+import pytest
 from django.test import TestCase
 from django.test import override_settings
 from faker import Faker
+from pytest_mock import MockerFixture
 
 from documents.models import Correspondent
 from documents.models import Document
 from documents.tasks import empty_trash
+from paperless_testing.factories import DocumentFactory
 
 
 class TestDocument(TestCase):
@@ -257,3 +260,72 @@ def test_suggestion_content() -> None:
     )
     doc.content = content_over_limit
     assert doc.suggestion_content == expected_cropped_content
+
+
+class TestPublicFilenameLength:
+    @pytest.fixture(autouse=True)
+    def _no_parser_registry(self, mocker: MockerFixture) -> None:
+        # The parser registry reads ApplicationConfiguration from the database
+        extensions = {"application/pdf": ".pdf", "image/jpeg": ".jpg"}
+        mocker.patch(
+            "documents.models.get_default_file_extension",
+            side_effect=extensions.__getitem__,
+        )
+
+    LIMIT = Document.MAX_PUBLIC_FILENAME_BYTES
+
+    @pytest.mark.parametrize(
+        ("title", "archive", "counter", "max_bytes", "tail"),
+        [
+            pytest.param("a" * 300, False, 0, LIMIT, ".jpg", id="ascii"),
+            pytest.param("a" * 300, True, 0, LIMIT, ".pdf", id="archive"),
+            pytest.param("ä" * 200, False, 0, LIMIT, ".jpg", id="umlaut"),
+            pytest.param("ä" * 200, False, 1, LIMIT, "_01.jpg", id="count"),
+            pytest.param("a" * 300, False, 1, 100, "_01.jpg", id="max"),
+        ],
+    )
+    def test_long_title_keeps_tail_within_limit(
+        self,
+        title: str,
+        *,
+        archive: bool,
+        counter: int,
+        max_bytes: int,
+        tail: str,
+    ) -> None:
+        """
+        GIVEN:
+            - A document whose title alone is longer than the byte limit
+        WHEN:
+            - The public file name is generated
+        THEN:
+            - The name ends with the counter and extension
+            - The name fits in the limit
+        """
+        name = DocumentFactory.build(
+            title=title,
+            mime_type="image/jpeg",
+        ).get_public_filename(
+            archive=archive,
+            counter=counter,
+            max_bytes=max_bytes,
+        )
+
+        assert name.endswith(tail)
+        assert len(name.encode()) <= max_bytes
+
+    def test_long_title_counters_give_distinct_names(self) -> None:
+        """
+        GIVEN:
+            - A document whose title alone is longer than the byte limit
+        WHEN:
+            - Public file names are generated with increasing counters
+        THEN:
+            - Each counter produces a distinct name
+        """
+        doc = DocumentFactory.build(title="ä" * 200, mime_type="application/pdf")
+
+        names = [doc.get_public_filename(counter=counter) for counter in range(3)]
+
+        assert len(set(names)) == 3
+        assert all(len(n.encode()) <= self.LIMIT for n in names)

src/documents/tests/test_management_exporter.py

@@ -1537,3 +1537,70 @@ class TestExportDerivedFileNameCollisions:
             assert (
                 target / record[EXPORTER_ARCHIVE_NAME]
             ).read_text() == f"archive {pk}"
+
+    def test_long_titles_export_within_file_name_limit(
+        self,
+        paperless_dirs: PaperlessDirs,
+        tmp_path: Path,
+    ) -> None:
+        """
+        GIVEN:
+            - Two documents with the same created date and the same title
+            - The title alone is longer than 255 bytes and contains umlauts
+        WHEN:
+            - The exporter runs
+        THEN:
+            - The export finishes with distinct original, thumbnail and archive names
+            - Every exported file name fits in the byte limit
+            - Each exported file holds its own document's content
+        """
+        for pk in (1, 2):
+            (paperless_dirs.originals_dir / f"{pk:07}.pdf").write_bytes(
+                f"original {pk}".encode(),
+            )
+            (paperless_dirs.archive_dir / f"{pk:07}.pdf").write_bytes(
+                f"archive {pk}".encode(),
+            )
+            (paperless_dirs.thumbnail_dir / f"{pk:07}.webp").write_bytes(
+                f"thumbnail {pk}".encode(),
+            )
+            DocumentFactory(
+                pk=pk,
+                title="Bestellbestätigung " * 15,
+                created=date(2026, 10, 15),
+                filename=f"{pk:07}.pdf",
+                archive_filename=f"{pk:07}.pdf",
+                mime_type="application/pdf",
+            )
+
+        target = tmp_path / "export"
+        target.mkdir()
+        call_command(
+            "document_exporter",
+            str(target),
+            "--no-progress-bar",
+            skip_checks=True,
+        )
+
+        manifest = json.loads((target / "manifest.json").read_text())
+        records = {r["pk"]: r for r in manifest if r["model"] == "documents.document"}
+
+        for key in (
+            EXPORTER_FILE_NAME,
+            EXPORTER_THUMBNAIL_NAME,
+            EXPORTER_ARCHIVE_NAME,
+        ):
+            assert records[1][key] != records[2][key]
+
+        for pk in (1, 2):
+            record = records[pk]
+            for key, content in (
+                (EXPORTER_FILE_NAME, f"original {pk}"),
+                (EXPORTER_THUMBNAIL_NAME, f"thumbnail {pk}"),
+                (EXPORTER_ARCHIVE_NAME, f"archive {pk}"),
+            ):
+                assert (
+                    len(Path(record[key]).name.encode())
+                    <= Document.MAX_PUBLIC_FILENAME_BYTES
+                )
+                assert (target / record[key]).read_text() == content