Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

73.9 KB
Raw Blame
"""
Tests for web/services/pdf_service.py

Tests cover:
- PDFService initialization
- Markdown to HTML conversion
- Markdown to PDF conversion
- Error handling
- Singleton pattern
"""

import io
import re
import warnings

import pytest
from unittest.mock import Mock, patch


class TestPDFServiceInit:
    """Tests for PDFService initialization."""

    def test_pdf_service_init(self):
        """Test PDFService initializes with minimal CSS."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()

        assert service.minimal_css is not None

    def test_pdf_service_css_contains_a4(self):
        """Test that CSS sets A4 page size."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()

        # The CSS string should be accessible
        assert service.minimal_css is not None

    def test_minimal_css_excludes_emoji_font_families(self):
        """No font-family stack may list an emoji font explicitly.

        Digits 0-9, '#' and '*' carry the Unicode Emoji property and have
        glyphs in Noto Color Emoji, so Pango routes them to an explicitly
        listed emoji font even when an earlier family in the stack covers
        them — every number in an exported report then renders as wide,
        square emoji glyphs ("2 0 2 6" instead of "2026"). Emoji still
        render via Pango/fontconfig per-character fallback to an installed
        emoji font, so the stacks must not name one. Regression test for
        the digit-capture bug introduced by #4730.
        """
        import re

        from local_deep_research.web.services.pdf_service import MINIMAL_CSS

        font_family_blocks = re.findall(r"font-family:\s*([^;]+);", MINIMAL_CSS)
        assert len(font_family_blocks) >= 2, (
            "expected at least body + code font-family declarations"
        )
        for block in font_family_blocks:
            assert "emoji" not in block.lower(), (
                f"font-family block must not list an emoji font (it would "
                f"capture digits): {block!r}"
            )

    def test_digits_not_rendered_with_emoji_font(self):
        """Digits in a rendered PDF must come from a text font, not an emoji font.

        Functional regression test for the digit-capture bug: with an emoji
        family in the font-family stack, Pango renders 0-9 with Noto Color
        Emoji (wide square glyphs). Renders a digit-heavy document and
        asserts no digit glyph is drawn with an emoji font. On hosts with
        no emoji font installed the assertion passes trivially, which is
        correct — there is no emoji font to capture the digits.
        """
        import io

        pytest.importorskip("pdfminer.high_level")
        from pdfminer.high_level import extract_pages
        from pdfminer.layout import LTChar, LTTextContainer, LTTextLine

        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        pdf_bytes = service.markdown_to_pdf(
            "As of July 11, 2026, plans cost $20/month [21][30]."
        )

        digit_fonts = set()
        for page in extract_pages(io.BytesIO(pdf_bytes)):
            for element in page:
                if not isinstance(element, LTTextContainer):
                    continue
                for line in element:
                    if not isinstance(line, LTTextLine):
                        continue
                    for char in line:
                        if (
                            isinstance(char, LTChar)
                            and char.get_text().isdigit()
                        ):
                            digit_fonts.add(char.fontname)

        assert digit_fonts, "expected the rendered PDF to contain digits"
        emoji_fonts = {f for f in digit_fonts if "emoji" in f.lower()}
        assert not emoji_fonts, (
            f"digits were rendered with an emoji font: {emoji_fonts}"
        )


class TestMarkdownToHTML:
    """Tests for _markdown_to_html method."""

    def test_markdown_to_html_basic(self):
        """Test basic markdown conversion."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "# Hello World\n\nThis is a **test**."

        html = service._markdown_to_html(markdown)

        # h1 may have an id attribute added by markdown TOC extension
        assert "Hello World</h1>" in html
        assert "<strong>test</strong>" in html
        assert "<!DOCTYPE html>" in html
        assert "</html>" in html

    def test_markdown_to_html_with_title(self):
        """Test conversion with title."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "Content here"

        html = service._markdown_to_html(markdown, title="Test Title")

        assert "<title>Test Title</title>" in html

    def test_markdown_to_html_escapes_html_in_title(self):
        """Test that HTML special characters in title are escaped."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()

        html = service._markdown_to_html(
            "content", title='<script>alert("xss")</script>'
        )

        assert "<script>" not in html
        assert "&lt;script&gt;" in html

    def test_markdown_to_html_escapes_html_in_metadata(self):
        """Test that HTML special characters in metadata are escaped."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        metadata = {"<b>key</b>": '<img src="x" onerror="alert(1)">'}

        html = service._markdown_to_html("content", metadata=metadata)

        assert "<b>key</b>" not in html
        assert "&lt;b&gt;key&lt;/b&gt;" in html
        assert 'onerror="alert(1)"' not in html

    def test_markdown_to_html_with_metadata(self):
        """Test conversion with metadata."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "Content"
        metadata = {"author": "Test Author", "date": "2024-01-01"}

        html = service._markdown_to_html(markdown, metadata=metadata)

        assert 'name="author"' in html
        assert 'content="Test Author"' in html
        assert 'name="date"' in html

    def test_markdown_to_html_tables(self):
        """Test table markdown is converted."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = """
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
"""
        html = service._markdown_to_html(markdown)

        assert "<table>" in html
        assert "<th>" in html or "<td>" in html

    def test_markdown_to_html_code_blocks(self):
        """Test fenced code blocks are converted."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = """
```python
def hello():
    print("Hello")
```
"""
        html = service._markdown_to_html(markdown)

        assert "<pre>" in html or "<code>" in html

    def test_markdown_to_html_includes_footer(self):
        """Test that footer with LDR attribution is included."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "Test content"

        html = service._markdown_to_html(markdown)

        assert "Local Deep Research" in html or "LDR" in html


class TestRawHtmlInReportTextIsEscaped:
    """Raw HTML in report text is escaped, matching the on-screen view (#7365).

    The report body (the synthesized answer, and the Sources block whose
    titles come from search-result metadata) is LLM- and web-derived. The
    on-screen report view escapes raw author HTML; PDF export now does the
    same, so tags in report text reach the exported PDF as visible text
    rather than as markup. They must come out escaped in the HTML handed to
    WeasyPrint, while the markdown WeasyPrint should still render keeps
    working.
    """

    # (name, raw-HTML snippet, substrings that must appear ESCAPED in output)
    RAW_TAGS = [
        (
            "style",
            "<style>body::after{content:'style-marker'}</style>",
            "&lt;style&gt;",
        ),
        ("base", '<base href="https://example.invalid/">', "&lt;base"),
        (
            "link_attachment",
            '<link rel="attachment" href="https://example.invalid/linked.txt">',
            "&lt;link",
        ),
        (
            "a_attachment",
            '<a rel="attachment" download="notes.txt" '
            'href="https://example.invalid/anchor.txt">x</a>',
            "&lt;a rel=",
        ),
        (
            "meta_author",
            '<meta name="author" content="Marker Author">',
            '&lt;meta name="author"',
        ),
        (
            "object",
            '<object data="object.txt" type="text/plain">o</object>',
            "&lt;object",
        ),
    ]

    def _service(self):
        from local_deep_research.web.services.pdf_service import PDFService

        return PDFService()

    @pytest.mark.parametrize(
        "name,snippet,escaped",
        RAW_TAGS,
        ids=[t[0] for t in RAW_TAGS],
    )
    def test_raw_tag_in_answer_is_escaped(self, name, snippet, escaped):
        html = self._service()._markdown_to_html(
            f"# Report\n\nIntro paragraph. {snippet} End.\n"
        )

        # The raw tag never survives; it is present only as escaped text.
        assert snippet not in html
        assert escaped in html

    @pytest.mark.parametrize(
        "name,snippet,escaped",
        RAW_TAGS,
        ids=[t[0] for t in RAW_TAGS],
    )
    def test_raw_tag_in_source_title_is_escaped(self, name, snippet, escaped):
        # Source titles are interpolated as plain text into the Sources
        # block, which flows through the same conversion as the answer.
        markdown = (
            "# Report\n\nBody.\n\n## Sources\n\n"
            f"[1] Title {snippet} (source nr: 1)\n"
            "   URL: https://example.org/page\n"
        )

        html = self._service()._markdown_to_html(markdown)

        assert snippet not in html
        assert escaped in html

    def test_style_cannot_add_a_stylesheet_element(self):
        html = self._service()._markdown_to_html(
            "# Report\n\n<style>p{color:red}</style>\n"
        )

        # No real <style> element reaches WeasyPrint from report text.
        assert "<style>" not in html
        assert "&lt;style&gt;" in html

    def test_meta_author_does_not_become_a_meta_element(self):
        html = self._service()._markdown_to_html(
            '# Report\n\n<meta name="author" content="Marker">\n'
        )

        # The only <meta> element is the pipeline's own charset tag.
        assert '<meta name="author" content="Marker">' not in html
        assert html.count("<meta ") == 1
        assert '<meta charset="utf-8">' in html

    def test_svg_block_is_escaped_not_passed_through(self):
        html = self._service()._markdown_to_html(
            '# Report\n\n<svg xmlns="http://www.w3.org/2000/svg">'
            "<rect/></svg>\n"
        )

        assert "<svg" not in html
        assert "&lt;svg" in html

    @pytest.mark.parametrize(
        "block,raw_open,escaped_open",
        [
            (
                '<div class="raw-block-marker">\n'
                "Text inside a raw block.\n"
                "</div>",
                '<div class="raw-block-marker">',
                '&lt;div class="raw-block-marker"&gt;',
            ),
            (
                '<table class="raw-table-marker">\n'
                "<tr><td>raw cell</td></tr>\n"
                "</table>",
                '<table class="raw-table-marker">',
                '&lt;table class="raw-table-marker"&gt;',
            ),
        ],
        ids=["div", "table"],
    )
    def test_block_level_raw_element_is_escaped(
        self, block, raw_open, escaped_open
    ):
        """A block-level element on lines of its own is handled by
        Python-Markdown's ``html_block`` preprocessor, which passes it through
        whole. This pins that handler's deregistration directly, with
        block-level elements other than ``<style>``."""
        html = self._service()._markdown_to_html(
            f"# Report\n\n{block}\n\nAfter.\n"
        )

        assert raw_open not in html
        assert escaped_open in html
        # The markdown after the block still renders as markdown.
        assert "<p>After.</p>" in html

    def test_ordinary_markdown_still_renders(self):
        markdown = (
            "# Heading\n\n"
            "[TOC]\n\n"
            "## Subheading\n\n"
            "Paragraph with **bold**, *italic* and a "
            "[link](https://example.org).\n\n"
            "![alt](https://example.org/image.png)\n\n"
            "| A | B |\n|---|---|\n| 1 | 2 |\n\n"
            "```python\nx = 1\n```\n\n"
            "A claim.[^1]\n\n[^1]: A footnote.\n"
        )

        html = self._service()._markdown_to_html(markdown)

        # Headings + toc
        assert 'id="heading"' in html
        assert 'id="subheading"' in html
        assert 'class="toc"' in html
        # Emphasis
        assert "<strong>bold</strong>" in html
        assert "<em>italic</em>" in html
        # Markdown-generated link and image survive (Markdown emits these,
        # they are not raw author HTML).
        assert '<a href="https://example.org">link</a>' in html
        assert '<img alt="alt" src="https://example.org/image.png"' in html
        # Table
        assert "<table>" in html
        assert "<td>1</td>" in html
        # Fenced code
        assert "language-python" in html
        # Footnote
        assert 'class="footnote-ref"' in html

    def test_export_with_raw_tags_fetches_and_embeds_nothing(self):
        """End to end: a body full of raw tags still produces a PDF, and none
        of the tags acts on it. The render's url_fetcher is replaced by a spy
        that would serve any URL, so a tag passed through as markup would
        show up both as a fetch and in the PDF: a document author from the
        ``<meta>``, an embedded file from the attachment links."""
        from pypdf import PdfReader

        from local_deep_research.web.services import pdf_service

        # Settle the lazy import, so the response type below is populated.
        pdf_service._ensure_weasyprint()
        response_type = pdf_service.URLFetcherResponse
        fetched: list[str] = []

        class _ServesAnything:
            _fail_on_errors = False

            def __call__(self, url):
                fetched.append(url)
                body = b"served body"
                if response_type is not None:
                    return response_type(
                        url, body=body, headers={"Content-Type": "text/plain"}
                    )
                return {"string": body, "mime_type": "text/plain"}

        markdown = "# Report\n\n" + "\n\n".join(
            snippet for _, snippet, _ in self.RAW_TAGS
        )

        with patch.object(pdf_service, "_safe_url_fetcher", _ServesAnything()):
            pdf_bytes = pdf_service.PDFService().markdown_to_pdf(
                markdown, title="t"
            )

        assert pdf_bytes[:4] == b"%PDF"
        # No tag made the renderer fetch anything.
        assert fetched == [], fetched
        reader = PdfReader(io.BytesIO(pdf_bytes))
        # No document author from the <meta> tag ...
        assert (reader.metadata or {}).get("/Author") != "Marker Author"
        # ... and no embedded file, in the name tree or as an annotation.
        assert not reader.attachments
        file_annotations = [
            annotation
            for page in reader.pages
            for annotation in (
                ref.get_object() for ref in page.get("/Annots") or []
            )
            if annotation.get("/Subtype") == "/FileAttachment"
        ]
        assert file_annotations == []
        # The tags were rendered, as visible text.
        text = "\n".join(page.extract_text() or "" for page in reader.pages)
        assert "Marker Author" in text, text[:400]


class TestTableAfterText:
    """A table right under a line of text is a table in the PDF too (#8096).

    The report view (marked, GFM) reads a table that directly follows a
    paragraph line as a table; Python-Markdown only did so after a blank
    line, so the PDF showed the pipes and separator dashes as text.
    """

    TABLE = "| Item | Description |\n|------|-------------|\n| A | First |\n"

    def _html(self, markdown):
        from local_deep_research.web.services.pdf_service import PDFService

        return PDFService()._markdown_to_html(markdown)

    @pytest.mark.parametrize(
        "markdown",
        [
            "## Example\n\nIntroductory text.\n" + TABLE,
            "## Example\n\nIntroductory text.\n\n" + TABLE,
            "Introductory text:\n" + TABLE + "\nAfter the table.\n",
        ],
        ids=["adjacent", "blank_line", "text_after"],
    )
    def test_table_after_text_is_a_table(self, markdown):
        html = self._html(markdown)

        assert "<p>Introductory text" in html
        assert "<th>Item</th>" in html
        assert "<td>First</td>" in html
        assert "|---" not in html

    def test_several_adjacent_tables(self):
        html = self._html(
            "First.\n| A | B |\n|---|---|\n| 1 | 2 |\n\n"
            "Second.\n| C | D |\n|---|---|\n| 3 | 4 |\n"
        )

        assert html.count("<table>") == 2
        assert "<p>First.</p>" in html
        assert "<p>Second.</p>" in html
        assert "<td>4</td>" in html

    def test_dash_only_row_stays_in_its_table(self):
        """A html row of dashes looks like a separator row; it must not be
        read as the start of a second table."""
        html = self._html("Text.\n| A | B |\n|---|---|\n| - | - |\n| 1 | 2 |\n")

        assert html.count("<table>") == 1
        assert "<td>-</td>" in html
        assert "<td>1</td>" in html

    def test_pipes_in_fenced_code_stay_code(self):
        html = self._html("Text.\n```\nIntro.\n| A | B |\n|---|---|\n```\n")

        assert "<table>" not in html
        assert "<code>Intro.\n| A | B |\n|---|---|\n</code>" in html

    def test_indented_code_text_is_unchanged(self):
        """fenced_code does not stash indented code, so a table example in
        it must not get a blank line inserted into the code text."""
        html = self._html("Text.\n\n    Intro.\n    | A | B |\n    |---|---|\n")

        assert "<table>" not in html
        assert "<pre><code>Intro.\n| A | B |\n|---|---|\n</code></pre>" in html

    def test_text_with_pipes_is_not_a_table(self):
        html = self._html("a | b\nc | d\n")

        assert "<table>" not in html
        assert "a | b" in html

    def test_pdf_shows_no_table_markup(self):
        from pypdf import PdfReader

        from local_deep_research.web.services.pdf_service import PDFService

        pdf_bytes = PDFService().markdown_to_pdf(
            "## Example\n\nIntroductory text.\n" + self.TABLE
        )

        reader = PdfReader(io.BytesIO(pdf_bytes))
        text = "\n".join(page.extract_text() or "" for page in reader.pages)
        assert "First" in text, text[:400]
        assert "| Item" not in text, text[:400]
        assert "---" not in text, text[:400]


class TestMarkdownToPDF:
    """Tests for markdown_to_pdf method."""

    def test_markdown_to_pdf_returns_bytes(self):
        """Test that PDF conversion returns bytes."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "# Test Document\n\nThis is a test."

        pdf_bytes = service.markdown_to_pdf(markdown)

        assert isinstance(pdf_bytes, bytes)
        assert len(pdf_bytes) > 0
        # PDF files start with %PDF
        assert pdf_bytes[:4] == b"%PDF"

    def test_markdown_to_pdf_with_title(self):
        """Test PDF conversion with title."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "Content here"

        pdf_bytes = service.markdown_to_pdf(markdown, title="My Document")

        assert isinstance(pdf_bytes, bytes)
        assert len(pdf_bytes) > 0

    def test_markdown_to_pdf_with_metadata(self):
        """Test PDF conversion with metadata."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "Content"
        metadata = {"author": "Test Author"}

        pdf_bytes = service.markdown_to_pdf(markdown, metadata=metadata)

        assert isinstance(pdf_bytes, bytes)

    def test_markdown_to_pdf_with_custom_css(self):
        """Test PDF conversion with custom CSS."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = "# Styled Content"
        custom_css = "body { color: red; }"

        pdf_bytes = service.markdown_to_pdf(markdown, custom_css=custom_css)

        assert isinstance(pdf_bytes, bytes)
        assert len(pdf_bytes) > 0

    def test_custom_css_layers_on_top_of_default(self):
        """custom_css must extend, not replace, the default stylesheet.

        Regression test: previously markdown_to_pdf used an if/else that
        dropped self.minimal_css entirely when custom_css was provided,
        silently losing the CJK font fallbacks. Verify the default
        stylesheet is always passed to WeasyPrint.
        """
        from unittest.mock import patch, MagicMock
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        custom_css = "body { color: red; }"

        with (
            patch(
                "local_deep_research.web.services.pdf_service.CSS",
                side_effect=lambda **kwargs: MagicMock(**kwargs),
            ),
            patch(
                "local_deep_research.web.services.pdf_service.HTML"
            ) as mock_html,
        ):
            mock_html.return_value.write_pdf.return_value = b"%PDF-1.7"

            service.markdown_to_pdf("# x", custom_css=custom_css)

            # write_pdf must receive both the default and the custom CSS.
            call_kwargs = mock_html.return_value.write_pdf.call_args.kwargs
            stylesheets = call_kwargs.get("stylesheets", [])
            assert len(stylesheets) == 2, (
                f"expected [default, custom]; got {len(stylesheets)} sheets"
            )
            assert stylesheets[0] is service.minimal_css, (
                "default MINIMAL_CSS must always be applied first"
            )

    def test_markdown_to_pdf_complex_document(self):
        """Test PDF conversion with complex document."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = """
# Research Report

## Introduction

This is a comprehensive research document.

### Key Findings

1. First finding
2. Second finding
3. Third finding

### Data Table

| Metric | Value |
|--------|-------|
| A      | 100   |
| B      | 200   |

## Conclusion

The research concludes that **testing is important**.

```python
def analyze():
    return True
```
"""
        pdf_bytes = service.markdown_to_pdf(
            markdown,
            title="Research Report",
            metadata={"author": "Research Team", "date": "2024"},
        )

        assert isinstance(pdf_bytes, bytes)
        assert len(pdf_bytes) > 100  # Should be a reasonable size

    def test_markdown_to_pdf_empty_content(self):
        """Test PDF conversion with empty content."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()
        markdown = ""

        pdf_bytes = service.markdown_to_pdf(markdown)

        # Should still generate valid PDF
        assert isinstance(pdf_bytes, bytes)
        assert pdf_bytes[:4] == b"%PDF"


class TestGetPDFService:
    """Tests for get_pdf_service singleton function."""

    def test_get_pdf_service_returns_instance(self):
        """Test that get_pdf_service returns a PDFService instance."""
        # Reset singleton for test
        import local_deep_research.web.services.pdf_service as pdf_module

        pdf_module._pdf_service = None

        from local_deep_research.web.services.pdf_service import get_pdf_service

        service = get_pdf_service()

        assert service is not None
        from local_deep_research.web.services.pdf_service import PDFService

        assert isinstance(service, PDFService)

    def test_get_pdf_service_singleton(self):
        """Test that get_pdf_service returns same instance."""
        # Reset singleton for test
        import local_deep_research.web.services.pdf_service as pdf_module

        pdf_module._pdf_service = None

        from local_deep_research.web.services.pdf_service import get_pdf_service

        service1 = get_pdf_service()
        service2 = get_pdf_service()

        assert service1 is service2


class TestPDFServiceErrorHandling:
    """Tests for error handling in PDF service."""

    def test_markdown_to_pdf_raises_on_error(self):
        """Test that exceptions are propagated."""
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()

        # Mock HTML to raise an exception
        with patch(
            "local_deep_research.web.services.pdf_service.HTML"
        ) as mock_html:
            mock_html.side_effect = Exception("Conversion error")

            with pytest.raises(Exception) as exc_info:
                service.markdown_to_pdf("test")

            assert "Conversion error" in str(exc_info.value)


class TestMissingPDFDependencyError:
    """Tests for MissingPDFDependencyError behavior."""

    def test_is_runtime_error_subclass(self):
        """MissingPDFDependencyError must be a RuntimeError subclass.

        Documents the security boundary: the web route catches this specific
        class (not generic RuntimeError) so that other exporters' RuntimeErrors
        (e.g., pandoc stderr from ODT) don't leak into HTTP responses.
        """
        from local_deep_research.web.services.pdf_service import (
            MissingPDFDependencyError,
        )

        assert issubclass(MissingPDFDependencyError, RuntimeError)

    def test_get_pdf_service_raises_specific_class_when_unavailable(self):
        """get_pdf_service() raises MissingPDFDependencyError, not plain RuntimeError."""
        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import (
            MissingPDFDependencyError,
            get_pdf_service,
        )

        with patch.object(pdf_module, "WEASYPRINT_AVAILABLE", False):
            with pytest.raises(MissingPDFDependencyError):
                get_pdf_service()


class TestSafeUrlFetcher:
    """Tests for the SSRF-guarded WeasyPrint url_fetcher (GHSA-fj2m-qvh9-jq4q).

    The custom fetcher blocks outbound requests to internal/private IPs and
    non-http(s) schemes, so URLs that reach the rendered HTML via the
    markdown body, citations, or any other channel cannot be weaponised
    into SSRF against cloud metadata or internal services.
    """

    def test_blocks_aws_metadata_endpoint(self):
        """AWS metadata IP is always blocked — critical SSRF target."""
        from local_deep_research.web.services.pdf_service import (
            UnsafePDFResourceURLError,
            _safe_url_fetcher,
        )

        with pytest.raises(UnsafePDFResourceURLError):
            _safe_url_fetcher(
                "http://169.254.169.254/latest/meta-data/iam/security-credentials/"
            )

    def test_blocks_loopback_address(self):
        """Loopback addresses are blocked by default."""
        from local_deep_research.web.services.pdf_service import (
            UnsafePDFResourceURLError,
            _safe_url_fetcher,
        )

        with pytest.raises(UnsafePDFResourceURLError):
            _safe_url_fetcher("http://127.0.0.1:8080/admin")

    def test_blocks_rfc1918_private_ip(self):
        """RFC1918 private range is blocked."""
        from local_deep_research.web.services.pdf_service import (
            UnsafePDFResourceURLError,
            _safe_url_fetcher,
        )

        with pytest.raises(UnsafePDFResourceURLError):
            _safe_url_fetcher("http://10.0.0.1/internal-api")

    def test_blocks_non_http_scheme(self):
        """Non-http(s) schemes like file:// are blocked."""
        from local_deep_research.web.services.pdf_service import (
            UnsafePDFResourceURLError,
            _safe_url_fetcher,
        )

        with pytest.raises(UnsafePDFResourceURLError):
            _safe_url_fetcher("file:///etc/passwd")

    def test_unsafe_url_error_subclasses_valueerror(self):
        """UnsafePDFResourceURLError must inherit from ValueError.

        Subclassing ValueError here is a conventional choice, not what
        makes a blocked URL skippable: WeasyPrint's fetch() wraps any
        exception the url_fetcher raises as URLFetchingError regardless
        of its type, and whether that is skipped or aborts the render
        depends on the call site -- @import is fetched inside a
        try/except in css/__init__.py and is skipped; @color-profile is
        fetched outside one, which is why markdown_to_pdf catches the
        error around the custom stylesheet itself.
        """
        from local_deep_research.web.services.pdf_service import (
            UnsafePDFResourceURLError,
        )

        assert issubclass(UnsafePDFResourceURLError, ValueError)

    def test_validated_url_delegates_to_url_fetcher(self):
        """Validated URLs are forwarded to the module's URLFetcher instance.

        The fetch is wrapped in the DNS pin, which resolves the host once;
        the resolver seam is patched to a TEST-NET-1 answer (192.0.2.10,
        which passes the SSRF policy but is not routable), so the cell does
        no real DNS lookup.
        """
        import socket

        from local_deep_research.security import dns_pinning
        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import (
            _safe_url_fetcher,
        )

        def _public(host, port, *args, **kwargs):
            return [
                (
                    socket.AF_INET,
                    socket.SOCK_STREAM,
                    socket.IPPROTO_TCP,
                    "",
                    ("192.0.2.10", port or 0),
                )
            ]

        pdf_module._ensure_weasyprint()  # populate the lazy _URL_FETCHER
        with (
            patch.object(pdf_module, "validate_url", return_value=True),
            patch.object(dns_pinning, "_real_getaddrinfo", _public),
            patch.object(pdf_module._URL_FETCHER, "fetch") as mock_fetch,
        ):
            mock_fetch.return_value = Mock(
                status=200, url="https://example.com/image.png"
            )

            _safe_url_fetcher("https://example.com/image.png")

            mock_fetch.assert_called_once_with("https://example.com/image.png")

    def test_url_fetcher_disables_redirects(self):
        """The module-level URLFetcher must keep allow_redirects=False.

        validate_url only inspects the initial URL string, so a 30x
        response redirecting to the AWS metadata endpoint would bypass
        the SSRF guard if URLFetcher were to follow redirects.
        default_url_fetcher
        hard-coded this; after migrating away from it, we assert the
        posture explicitly.
        """
        from local_deep_research.web.services import pdf_service as pdf_module
        from urllib.request import HTTPRedirectHandler

        pdf_module._ensure_weasyprint()  # populate the lazy _URL_FETCHER
        redirect_handlers = [
            h
            for h in pdf_module._URL_FETCHER.handlers
            if isinstance(h, HTTPRedirectHandler)
        ]
        assert redirect_handlers == []

    def test_pdf_html_passes_fetcher_to_weasyprint(self):
        """markdown_to_pdf must wire _safe_url_fetcher into HTML(...).

        Regression guard: if a refactor drops the url_fetcher= kwarg,
        WeasyPrint silently reverts to its default fetcher and the
        SSRF guard disappears.
        """
        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import PDFService

        service = PDFService()

        with patch.object(pdf_module, "HTML") as mock_html:
            mock_html.return_value.write_pdf.return_value = None
            service.markdown_to_pdf("content")

            mock_html.assert_called_once()
            assert (
                mock_html.call_args.kwargs.get("url_fetcher")
                is pdf_module._safe_url_fetcher
            )

    def test_fetchers_expose_the_fail_on_errors_contract(self):
        """Both fetchers must expose ``_fail_on_errors = False``.

        WeasyPrint 70's ``fetch()`` reads this private attribute off the
        ``url_fetcher`` itself after catching an exception it raised; a
        callable that lost it turns every blocked URL into an
        ``AttributeError`` mid-render. The contract rides on the fetcher
        classes as a class attribute so every instance carries it as part
        of the type -- there is no separate import-time attachment step
        (the bare-function equivalent, ``fn._fail_on_errors = ...``) to
        forget on a rewrite. It can still be lost through a rebind (a
        lambda, ``functools.partial``, or an un-attribute-aware wrapper
        all drop it, and ``functools.wraps`` -- which *does* preserve a
        bare function's own attribute -- does not copy an instance's).
        This test is the actual guard: it asserts the attribute is
        present, ``False``, on the wired module-level ``_safe_url_fetcher``
        and on a ``_SkippingUrlFetcher()`` built the way the retry in
        ``_render_pdf`` builds one -- fresh per retry, since its
        ``skipped`` list is per-render state (#6685, #6588).
        """
        from local_deep_research.web.services.pdf_service import (
            _SafeUrlFetcher,
            _SkippingUrlFetcher,
            _safe_url_fetcher,
        )

        for fetcher in (_safe_url_fetcher, _SkippingUrlFetcher()):
            assert getattr(fetcher, "_fail_on_errors", None) is False
        # Intrinsic to the type, not attached to the callable afterwards.
        assert _SafeUrlFetcher._fail_on_errors is False
        assert _SkippingUrlFetcher._fail_on_errors is False

    def test_installed_weasyprint_still_reads_fail_on_errors(self):
        """Tripwire for the upstream half of the contract (#6685).

        The class attribute exists because WeasyPrint 70's ``fetch()``
        reads ``_fail_on_errors`` off the url_fetcher after catching an
        exception it raised. If a future WeasyPrint renames or drops
        that private lookup, the attribute becomes dead configuration
        and refusal semantics change silently at runtime — this pin
        fails loudly in CI so the contract gets re-derived first.

        Scoped to ``fetch``'s own source, not the whole ``urls`` module:
        ``URLFetcher.__init__`` also assigns ``self._fail_on_errors = ...``
        (it's the constructor argument backing it), so a module-wide
        source scan for the string would still pass even if the lookup
        this test actually cares about -- the one inside ``fetch()`` that
        turns a blocked URL into ``FatalURLFetchingError`` vs.
        ``URLFetchingError`` -- were renamed or dropped.
        """
        import inspect

        weasyprint_urls = pytest.importorskip("weasyprint.urls")

        fetch = getattr(weasyprint_urls, "fetch", None)
        assert inspect.isfunction(fetch), (
            "weasyprint.urls has no module-level fetch() function; "
            "the _fail_on_errors contract this pins may have moved -- "
            "re-derive it against the installed WeasyPrint version."
        )

        assert "_fail_on_errors" in inspect.getsource(fetch)

    def test_render_succeeds_when_body_url_is_blocked(self):
        """End-to-end: a blocked URL in the markdown body doesn't break rendering.

        Covers the chain the SSRF guard relies on: Markdown image ->
        WeasyPrint -> fetcher -> refusal (a ValueError) -> WeasyPrint skips
        the resource -> PDF still renders. A Markdown ``![](url)`` image is
        used because it is what report text can still produce: raw HTML in
        report text is escaped to visible text, while the images Markdown
        itself emits reach the render-time fetcher. ``validate_url`` is
        wrapped, not replaced (the real guard still decides), to record that
        the render asked it about the image. Would fail if the url_fetcher
        got unwired. It would not catch a WeasyPrint upgrade that stopped
        skipping an image whose fetch is refused: ``_render_pdf`` would then
        retry with refusals skipped and the PDF would still render. That
        retry is covered by ``TestRefusedResourceDoesNotAbortTheExport`` in
        tests/web_services/test_pdf_service.py.
        """
        from local_deep_research.web.services import pdf_service

        blocked = "http://169.254.169.254/latest/meta-data/"
        asked: list[str] = []
        real_validate_url = pdf_service.validate_url

        def recording_validate_url(url, *args, **kwargs):
            asked.append(url)
            return real_validate_url(url, *args, **kwargs)

        markdown = f"# Report\n\nBody text.\n\n![x]({blocked})\n"

        with patch.object(pdf_service, "validate_url", recording_validate_url):
            pdf_bytes = pdf_service.PDFService().markdown_to_pdf(markdown)

        assert isinstance(pdf_bytes, bytes)
        assert pdf_bytes[:4] == b"%PDF"
        assert len(pdf_bytes) > 100
        # The render consulted the guard about the image: the fetcher is wired.
        assert blocked in asked, asked


class TestSafeUrlFetcherDnsPin:
    """The PDF resource fetch connects only to an address that passed the
    same policy at connect time.

    ``validate_url`` resolves the host, and urllib would resolve it again
    when it connects. ``_SafeUrlFetcher`` pins the validated answer with
    ``security.dns_pinning`` for the fetch (for ASCII hosts, whose lookup
    key matches the pin), and opens a block-private window so any lookup
    that misses the pin is checked against the same policy on the answer
    actually used. A resolver that changes its answer between the lookups
    therefore cannot steer the connection to a blocked address. The one
    relaxation is the configured forward proxy's exact (host, port), which
    may be private but never metadata.

    The resolver seam ``dns_pinning._real_getaddrinfo`` is driven with
    successive answers per host. Two stub HTTP servers share one port: one
    on 127.0.0.1 (the "validated" address) and one on an internal address
    (127.0.0.2, or ::1 where 127.0.0.2 cannot be bound). A hit on the second
    server means the fetch connected to an address that never passed the
    check. The fetcher uses the default (public-only) policy, which blocks
    every loopback address, so ``ssrf_validator.is_ip_blocked`` is wrapped
    to treat 127.0.0.1 alone as a public stand-in; the internal address and
    everything else keep the real policy.
    """

    HOST = "pdf-pin.example"
    USERINFO_URLS = (
        "http://user@{host}:{port}/x.css",
        "http://@{host}:{port}/x.css",
        "http://u%40v@{host}:{port}/x.css",
    )

    @staticmethod
    def _resolver(answers, default=None):
        """Stand-in for ``dns_pinning._real_getaddrinfo``.

        Each lookup of ``host`` consumes the next answer from
        ``answers[host]``; the last answer then sticks. An IP literal
        resolves to itself. A host with no entry gets ``default`` when one
        is given. ``calls`` records every
        looked-up host, and ``queues`` lets a test change the remaining
        answers mid-fetch.
        """
        import ipaddress
        import socket

        queues = {h: list(v) for h, v in answers.items()}
        calls = []

        def resolve(host, port, family=0, type=0, proto=0, flags=0):
            key = (host or "").lower().rstrip(".")
            calls.append(key)
            seq = queues.get(key)
            try:
                # An IP literal resolves to itself, as the real resolver does.
                ipaddress.ip_address(key)
                seq = [key]
            except ValueError:
                pass
            if seq:
                ip = seq[0] if len(seq) == 1 else seq.pop(0)
            elif default is not None:
                ip = default
            else:
                raise socket.gaierror(socket.EAI_NONAME, "no answer")
            if ":" in ip:
                fam, sockaddr = socket.AF_INET6, (ip, port or 0, 0, 0)
            else:
                fam, sockaddr = socket.AF_INET, (ip, port or 0)
            return [(fam, socket.SOCK_STREAM, socket.IPPROTO_TCP, "", sockaddr)]

        resolve.calls = calls
        resolve.queues = queues
        return resolve

    @staticmethod
    def _start_server(bind_ip, port, marker, hits):
        import socket
        import threading
        from http.server import BaseHTTPRequestHandler, HTTPServer

        class _Handler(BaseHTTPRequestHandler):
            def do_GET(self):
                hits.append(self.path)
                self.send_response(200)
                self.send_header("Content-Type", "text/css")
                self.send_header("Content-Length", str(len(marker)))
                self.end_headers()
                self.wfile.write(marker)

            def log_message(self, *args):
                pass

        class _Server(HTTPServer):
            address_family = (
                socket.AF_INET6 if ":" in bind_ip else socket.AF_INET
            )

        server = _Server((bind_ip, port), _Handler)
        thread = threading.Thread(target=server.serve_forever, daemon=True)
        thread.start()
        return server, thread

    @pytest.fixture
    def servers(self):
        """A server on 127.0.0.1 and one on an internal address, same port.

        Yields ``(port, validated_hits, internal_hits, internal_ip)``.
        """
        validated_hits: list = []
        internal_hits: list = []
        validated, t1 = self._start_server(
            "127.0.0.1", 0, b"VALIDATED", validated_hits
        )
        port = validated.server_address[1]
        internal = None
        errors = []
        for internal_ip in ("127.0.0.2", "::1"):
            try:
                internal = self._start_server(
                    internal_ip, port, b"INTERNAL", internal_hits
                )
                break
            except OSError as exc:
                errors.append(f"{internal_ip}: {exc}")
        if internal is None:
            validated.shutdown()
            validated.server_close()
            t1.join(timeout=5)
            warnings.warn(
                "TestSafeUrlFetcherDnsPin: neither 127.0.0.2 nor ::1 could "
                "be bound, so the PDF fetcher's DNS-pin, block-window and "
                "proxy-exemption tests did NOT run on this host: "
                + "; ".join(errors),
                stacklevel=2,
            )
            pytest.skip(
                "needs a second loopback address on the same port as "
                "127.0.0.1 to tell the validated address from an internal "
                "one; neither could be bound: " + "; ".join(errors)
            )
        try:
            yield port, validated_hits, internal_hits, internal_ip
        finally:
            for server, thread in ((validated, t1), internal):
                server.shutdown()
                server.server_close()
                thread.join(timeout=5)

    @staticmethod
    def _module_fetcher(pdf_module):
        """A fresh URL fetcher from the builder ``_ensure_weasyprint`` uses.

        ``_build_url_fetcher`` turns redirects off and attaches the
        ``_BoundedBodyProcessor`` (#7248), so these pin tests run through
        the same fetcher shape as production, including any handler added
        there later.
        """
        return pdf_module._build_url_fetcher(type(pdf_module._URL_FETCHER))

    @pytest.fixture
    def fetcher_env(self, monkeypatch):
        """Treat 127.0.0.1 as public and use a proxy-free URL fetcher.

        WeasyPrint's ``URLFetcher`` reads proxy settings from the
        environment when it is built, and a proxy would take the target
        lookup off this machine. A fresh fetcher with the module's settings
        (redirects off, size-limiting processor attached; see
        ``_module_fetcher``) is built with the proxy variables cleared.
        """
        from local_deep_research.security import ssrf_validator
        from local_deep_research.web.services import pdf_service as pdf_module

        for var in (
            "http_proxy",
            "https_proxy",
            "all_proxy",
            "HTTP_PROXY",
            "HTTPS_PROXY",
            "ALL_PROXY",
            "no_proxy",
            "NO_PROXY",
        ):
            monkeypatch.delenv(var, raising=False)
        pdf_module._ensure_weasyprint()
        fetcher = TestSafeUrlFetcherDnsPin._module_fetcher(pdf_module)
        monkeypatch.setattr(pdf_module, "_URL_FETCHER", fetcher)

        real_is_ip_blocked = ssrf_validator.is_ip_blocked

        def is_ip_blocked(ip, *args, **kwargs):
            if ip == "127.0.0.1":
                return False
            return real_is_ip_blocked(ip, *args, **kwargs)

        monkeypatch.setattr(ssrf_validator, "is_ip_blocked", is_ip_blocked)
        return pdf_module

    def test_connect_uses_the_validated_address(self, servers, fetcher_env):
        """The resolver answers 127.0.0.1 for validation and the pin, then
        switches to the internal address the moment the URL fetcher starts,
        which is when urllib would look the host up again to connect. The
        fetch must reach the 127.0.0.1 server."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        resolver = self._resolver({self.HOST: ["127.0.0.1"]})
        url_fetcher = fetcher_env._URL_FETCHER
        real_fetch = url_fetcher.fetch

        def fetch_after_rebind(url, *args, **kwargs):
            # Every lookup from here on answers the internal address.
            resolver.queues[self.HOST][:] = [internal_ip]
            return real_fetch(url, *args, **kwargs)

        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            patch.object(url_fetcher, "fetch", fetch_after_rebind),
        ):
            resource = fetcher_env._safe_url_fetcher(
                f"http://{self.HOST}:{port}/style.css"
            )
            try:
                body = resource.read()
            finally:
                resource.close()

        assert internal_hits == [], "the fetch connected to the later answer"
        assert body == b"VALIDATED"
        assert validated_hits == ["/style.css"]

    def test_answer_that_changes_before_the_pin_is_refused(
        self, servers, fetcher_env
    ):
        """Validation sees 127.0.0.1, every later lookup the internal
        address. The pin re-checks its own answer against the same policy
        and refuses it, so nothing is fetched."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        resolver = self._resolver({self.HOST: ["127.0.0.1", internal_ip]})
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            pytest.raises(ValueError, match="possible SSRF"),
        ):
            fetcher_env._safe_url_fetcher(
                f"http://{self.HOST}:{port}/style.css"
            )

        assert internal_hits == [], "the fetch connected to the later answer"
        assert validated_hits == []

    @pytest.mark.parametrize("template", USERINFO_URLS)
    def test_userinfo_url_is_refused(self, servers, fetcher_env, template):
        """A URL with userinfo is refused before any fetch. urllib would
        look up ``user@host``, which the pin (keyed on the host) does not
        cover."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        resolver = self._resolver(
            {self.HOST: ["127.0.0.1"]}, default=internal_ip
        )
        url = template.format(host=self.HOST, port=port)
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            pytest.raises(
                fetcher_env.UnsafePDFResourceURLError, match="userinfo"
            ),
        ):
            fetcher_env._safe_url_fetcher(url)

        assert internal_hits == []
        assert validated_hits == []

    def test_percent_encoded_at_without_userinfo_is_refused(self):
        """An authority with ``%40`` but no literal ``@`` has the escape in
        its host, which ``validate_url`` already refuses before any lookup;
        the ``%40`` branch of ``_has_userinfo`` is defence in depth for it.
        """
        from local_deep_research.web.services import pdf_service as pdf_module

        with pytest.raises(
            pdf_module.UnsafePDFResourceURLError, match="Blocked unsafe URL"
        ):
            pdf_module._safe_url_fetcher(f"http://u%40{self.HOST}/x.css")

    @pytest.mark.parametrize("template", USERINFO_URLS)
    def test_lookup_that_misses_the_pin_is_policy_checked(
        self, servers, fetcher_env, template
    ):
        """With the userinfo check bypassed, urllib's lookup of
        ``user@host`` misses the pin and resolves to the internal address.
        The block-private window must refuse that answer, so nothing is
        fetched. (urllib reports the refused lookup as ``URLError``.)"""
        import urllib.error

        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        resolver = self._resolver(
            {self.HOST: ["127.0.0.1"]}, default=internal_ip
        )
        url = template.format(host=self.HOST, port=port)
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            patch.object(fetcher_env, "_has_userinfo", return_value=False),
            pytest.raises(urllib.error.URLError),
        ):
            fetcher_env._safe_url_fetcher(url)

        assert internal_hits == [], (
            "a lookup that missed the pin connected to an internal address"
        )
        assert validated_hits == []
        assert any("@" in host for host in resolver.calls), resolver.calls

    IDN_HOST = "ü.pdf-pin.example"
    IDN_KEY = "xn--tda.pdf-pin.example"

    @pytest.mark.parametrize(
        ("miss_answer", "expected"),
        [("internal", "refused"), ("127.0.0.1", "fetched")],
    )
    def test_non_ascii_host_lookup_that_misses_the_pin_is_policy_checked(
        self, servers, fetcher_env, miss_answer, expected
    ):
        """A non-ASCII host is validated and pinned under its IDNA form,
        but urllib looks up the Unicode form, which misses the pin. That
        lookup is still checked by the block-private window: an internal
        answer is refused, and an answer that passes the policy is fetched
        as before."""
        import urllib.error

        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        miss_ip = internal_ip if miss_answer == "internal" else miss_answer
        resolver = self._resolver(
            {self.IDN_KEY: ["127.0.0.1"]}, default=miss_ip
        )
        validate = Mock(wraps=fetcher_env.validate_url)
        url = f"http://{self.IDN_HOST}:{port}/x.css"
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            patch.object(fetcher_env, "validate_url", validate),
        ):
            if expected == "refused":
                with pytest.raises(urllib.error.URLError):
                    fetcher_env._safe_url_fetcher(url)
            else:
                assert self._fetch_body(fetcher_env, url) == b"VALIDATED"

        # Normal validation ran on the URL, and resolved the IDNA form.
        validate.assert_called_once_with(url)
        assert self.IDN_KEY in resolver.calls, resolver.calls
        # The lookup urllib made missed the pin and reached the resolver.
        assert self.IDN_HOST in resolver.calls, resolver.calls
        assert internal_hits == [], (
            "a non-ASCII host lookup that missed the pin connected to an "
            "internal address"
        )
        if expected == "refused":
            assert validated_hits == []
        else:
            assert validated_hits == ["/x.css"]

    def test_non_ascii_host_is_refused_by_normal_validation(
        self, servers, fetcher_env
    ):
        """A non-ASCII host whose IDNA form resolves to an internal address
        is refused by ``validate_url`` before any pin or fetch."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        resolver = self._resolver({self.IDN_KEY: [internal_ip]})
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            pytest.raises(
                fetcher_env.UnsafePDFResourceURLError,
                match="Blocked unsafe URL",
            ),
        ):
            fetcher_env._safe_url_fetcher(
                f"http://{self.IDN_HOST}:{port}/x.css"
            )

        assert resolver.calls == [self.IDN_KEY]
        assert internal_hits == []
        assert validated_hits == []

    @staticmethod
    def _use_proxy(monkeypatch, pdf_module, proxy_url):
        """Rebuild the module fetcher with ``http_proxy`` set, so the proxy
        comes from the fetcher's own ``ProxyHandler`` snapshot, as in
        production (size-limiting processor included)."""
        monkeypatch.setenv("http_proxy", proxy_url)
        fetcher = TestSafeUrlFetcherDnsPin._module_fetcher(pdf_module)
        monkeypatch.setattr(pdf_module, "_URL_FETCHER", fetcher)
        return fetcher

    def _fetch_body(self, pdf_module, url):
        resource = pdf_module._safe_url_fetcher(url)
        try:
            return resource.read()
        finally:
            resource.close()

    def test_private_proxy_is_used(self, servers, fetcher_env, monkeypatch):
        """A forward proxy named in ``http_proxy`` that resolves to a
        private/loopback address still carries the fetch. Its lookup misses
        the pin, and the block window must let exactly that one through."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        self._use_proxy(
            monkeypatch, fetcher_env, f"http://proxy.example:{port}"
        )
        resolver = self._resolver(
            {self.HOST: ["127.0.0.1"], "proxy.example": [internal_ip]}
        )
        url = f"http://{self.HOST}:{port}/x.css"
        with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
            body = self._fetch_body(fetcher_env, url)

        # The internal server is the proxy here: it gets the absolute URL.
        assert body == b"INTERNAL"
        assert internal_hits == [url]
        assert validated_hits == []
        # The exemption and the window are restored once the fetch ends.
        assert (
            getattr(dns_pinning._thread_state, "block_exemptions", None) is None
        )
        assert getattr(dns_pinning._thread_state, "block_private", None) is None

    def test_ip_literal_private_proxy_is_used(
        self, servers, fetcher_env, monkeypatch
    ):
        """The same with the proxy given as an IP literal, which is not
        pinned but does pass through the window's lookup."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        literal = f"[{internal_ip}]" if ":" in internal_ip else internal_ip
        self._use_proxy(monkeypatch, fetcher_env, f"http://{literal}:{port}")
        resolver = self._resolver({self.HOST: ["127.0.0.1"]})
        url = f"http://{self.HOST}:{port}/x.css"
        with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
            body = self._fetch_body(fetcher_env, url)

        assert body == b"INTERNAL"
        assert internal_hits == [url]
        assert validated_hits == []

    @pytest.mark.parametrize(
        ("proxy_ip", "allowed"),
        [
            # RFC1918: the exemption must allow private addresses.
            ("10.0.0.5", True),
            # Always-blocked cloud metadata.
            ("169.254.169.254", False),
            # Link-local metadata outside the always-blocked set (Scaleway)
            # and IPv6 link-local: refused only because the exemption keeps
            # ``block_link_local`` on.
            ("169.254.42.42", False),
            ("fe80::1", False),
        ],
    )
    def test_proxy_lookup_policy(
        self, fetcher_env, monkeypatch, proxy_ip, allowed
    ):
        """The proxy exemption relaxes private/loopback only: a proxy name
        that resolves to an RFC1918 address is connected to, one that
        resolves to metadata or link-local is still refused.

        ``socket.create_connection`` is replaced by a stand-in that does
        the same ``getaddrinfo`` call (through the shim and window) and
        records the answer instead of connecting, so the cell never opens a
        socket to any of these addresses, whatever the outcome."""
        import socket
        import urllib.error

        from local_deep_research.security import dns_pinning

        self._use_proxy(monkeypatch, fetcher_env, "http://proxy.example:3128")
        resolver = self._resolver(
            {self.HOST: ["127.0.0.1"], "proxy.example": [proxy_ip]}
        )
        connect_targets = []

        def lookup_only(address, *args, **kwargs):
            host, target_port = address[:2]
            infos = socket.getaddrinfo(host, target_port, 0, socket.SOCK_STREAM)
            connect_targets.extend(info[4][0] for info in infos)
            raise ConnectionRefusedError("connect suppressed in test")

        expected = "connect suppressed" if allowed else "Blocked resolution"
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            patch.object(socket, "create_connection", lookup_only),
            pytest.raises(urllib.error.URLError, match=expected),
        ):
            fetcher_env._safe_url_fetcher(f"http://{self.HOST}:8080/x.css")

        assert connect_targets == ([proxy_ip] if allowed else []), (
            connect_targets
        )

    @pytest.mark.parametrize(
        ("env", "url"),
        [
            # https target tunnelled (CONNECT) through a port-less proxy:
            # HTTPSConnection, so the default port is 443.
            ({"https_proxy": "http://proxy.example"}, "https://t.example/x"),
            # http target through an https:// proxy: also 443.
            ({"http_proxy": "https://proxy.example"}, "http://t.example/x"),
            # Port-less http proxy for an http target: 80.
            ({"http_proxy": "http://proxy.example"}, "http://t.example/x"),
            # Bracketed IPv6 proxy.
            ({"http_proxy": "http://[::1]:3128"}, "http://t.example/x"),
            # Percent-escaped host: urllib unquotes it before connecting.
            ({"http_proxy": "http://pro%78y.corp:3128"}, "http://t.example/x"),
            # Scheme-less proxy with credentials.
            ({"http_proxy": "u:[email protected]:3128"}, "http://t.example/x"),
            # no_proxy bypass: urllib connects to the target directly.
            (
                {
                    "http_proxy": "http://proxy.example:3128",
                    "no_proxy": "t.example",
                },
                "http://t.example/x",
            ),
        ],
    )
    def test_proxy_endpoint_matches_urllib_lookup(
        self, fetcher_env, monkeypatch, env, url
    ):
        """``_proxy_endpoint`` must name exactly the (host, port) urllib
        passes to ``getaddrinfo`` for the proxy, or None when urllib does
        not use one. The lookup is recorded and refused, so nothing
        connects."""
        import socket
        import urllib.error

        for name, value in env.items():
            monkeypatch.setenv(name, value)
        fetcher = self._module_fetcher(fetcher_env)
        monkeypatch.setattr(fetcher_env, "_URL_FETCHER", fetcher)
        seen = []

        def record(host, port, *args, **kwargs):
            seen.append((host, port))
            raise socket.gaierror(socket.EAI_NONAME, "recorded only")

        with patch.object(socket, "getaddrinfo", record):
            with pytest.raises(urllib.error.URLError, match="recorded only"):
                fetcher.fetch(url)

        endpoint = fetcher_env._proxy_endpoint(url)
        target = (url.split("/")[2], 443 if url.startswith("https") else 80)
        if "no_proxy" in env:
            assert endpoint is None
            assert seen == [target], seen
        else:
            assert seen and seen[0] == endpoint, (seen, endpoint)

    def test_other_private_lookups_stay_refused_with_a_proxy(
        self, servers, fetcher_env, monkeypatch
    ):
        """The exemption is the proxy's exact (host, port) only. During a
        proxied fetch, a private answer for another host, for the proxy
        host on another port, or for the proxy's address on another port
        is still refused; the proxied fetch itself still works."""
        import socket

        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, internal_ip = servers
        url_fetcher = self._use_proxy(
            monkeypatch, fetcher_env, f"http://proxy.example:{port}"
        )
        resolver = self._resolver(
            {
                self.HOST: ["127.0.0.1"],
                "proxy.example": [internal_ip],
                "other.example": [internal_ip],
            }
        )
        probes = [
            ("other.example", port),
            ("proxy.example", port + 1),
            (internal_ip, port + 1),
        ]
        outcomes = {}
        real_fetch = url_fetcher.fetch

        def probe_then_fetch(url, *args, **kwargs):
            for host, probe_port in probes:
                try:
                    socket.getaddrinfo(host, probe_port)
                    outcomes[(host, probe_port)] = "resolved"
                except socket.gaierror:
                    outcomes[(host, probe_port)] = "refused"
            return real_fetch(url, *args, **kwargs)

        url = f"http://{self.HOST}:{port}/x.css"
        with (
            patch.object(dns_pinning, "_real_getaddrinfo", resolver),
            patch.object(url_fetcher, "fetch", probe_then_fetch),
        ):
            body = self._fetch_body(fetcher_env, url)

        assert outcomes == dict.fromkeys(probes, "refused"), outcomes
        assert body == b"INTERNAL"
        assert internal_hits == [url]

    def test_public_resource_still_fetches(self, servers, fetcher_env):
        """Positive control: a host with a stable public answer is fetched
        normally through the pin and the block-private window."""
        from local_deep_research.security import dns_pinning

        port, validated_hits, internal_hits, _ = servers
        resolver = self._resolver({self.HOST: ["127.0.0.1"]})
        with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
            resource = fetcher_env._safe_url_fetcher(
                f"http://{self.HOST}:{port}/img.css"
            )
            try:
                body = resource.read()
            finally:
                resource.close()

        assert body == b"VALIDATED"
        assert validated_hits == ["/img.css"]
        assert internal_hits == []

    def test_refuses_when_the_pin_shim_is_not_installed(self):
        """If ``socket.getaddrinfo`` is no longer the pin shim, a pin has no
        effect, so the fetcher refuses instead of fetching unpinned.

        Both resolvers are a fixed public stand-in, so the cell does no
        real DNS even if the refusal is removed."""
        import socket

        from local_deep_research.security import dns_pinning
        from local_deep_research.web.services import pdf_service as pdf_module

        public = self._resolver({}, default="192.0.2.10")
        pdf_module._ensure_weasyprint()
        with (
            patch.object(pdf_module, "validate_url", return_value=True),
            patch.object(pdf_module._URL_FETCHER, "fetch") as mock_fetch,
            patch.object(dns_pinning, "_real_getaddrinfo", public),
            patch.object(socket, "getaddrinfo", public),
        ):
            assert not dns_pinning._shim_installed()
            with pytest.raises(
                pdf_module.UnsafePDFResourceURLError, match="DNS pin"
            ):
                pdf_module._safe_url_fetcher("https://example.com/x.png")

        mock_fetch.assert_not_called()

    def test_module_fetcher_is_built_by_the_shared_builder(self, monkeypatch):
        """``_ensure_weasyprint`` builds ``_URL_FETCHER`` through
        ``_build_url_fetcher``, the builder ``_module_fetcher`` uses, so
        the fetchers these tests build cannot drift from production's."""
        from local_deep_research.web.services import pdf_service as pdf_module

        pdf_module._ensure_weasyprint()
        if not pdf_module.WEASYPRINT_AVAILABLE:
            pytest.skip("WeasyPrint is not available")
        # Rebuild the lazily imported globals; monkeypatch restores them.
        for name in (
            "HTML",
            "CSS",
            "URLFetchingError",
            "URLFetcherResponse",
            "_URL_FETCHER",
        ):
            monkeypatch.setattr(pdf_module, name, getattr(pdf_module, name))
        monkeypatch.setattr(pdf_module, "WEASYPRINT_AVAILABLE", None)
        real_builder = pdf_module._build_url_fetcher
        built = []

        def builder(fetcher_cls):
            built.append(real_builder(fetcher_cls))
            return built[-1]

        monkeypatch.setattr(pdf_module, "_build_url_fetcher", builder)
        pdf_module._ensure_weasyprint()

        assert len(built) == 1
        assert pdf_module._URL_FETCHER is built[0]
        assert any(
            isinstance(handler, pdf_module._BoundedBodyProcessor)
            for handler in built[0].handlers
        )


class TestRenderPdfRetryHardening:
    """Retry-path hardening pins (#6588)."""

    def test_render_error_surfaces_when_error_global_unpopulated(self):
        """`except URLFetchingError:` names a lazily-populated global.

        A caller that reaches ``_render_pdf`` without the lazy import having
        run used to get ``TypeError: catching classes that do not inherit
        from BaseException`` — masking the real render error (#6588). The
        render path now ensures the import first, so the underlying error
        surfaces as itself.
        """
        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import PDFService

        pdf_module._ensure_weasyprint()
        real_error = pdf_module.URLFetchingError
        real_available = pdf_module.WEASYPRINT_AVAILABLE

        class _ExplodingDoc:
            def write_pdf(self, buf, stylesheets=None):
                raise RuntimeError("underlying render failure")

        service = PDFService()
        try:
            # Simulate the unpopulated-module state a direct caller can hit.
            pdf_module.URLFetchingError = None
            pdf_module.WEASYPRINT_AVAILABLE = None
            with pytest.raises(RuntimeError, match="underlying render failure"):
                service._render_pdf("<html></html>", _ExplodingDoc(), [])
        finally:
            pdf_module.URLFetchingError = real_error
            pdf_module.WEASYPRINT_AVAILABLE = real_available
            pdf_module._ensure_weasyprint()

    def test_retry_surfaces_skipped_resources(self):
        """The retry must say WHAT it dropped (#6588).

        A subtly incomplete export (missing figures/styles) is otherwise
        indistinguishable from a correct render: the retry now records the
        resources its fetcher skipped and warns with the (redacted) URLs.
        """
        from loguru import logger as loguru_logger

        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import PDFService

        pdf_module._ensure_weasyprint()
        urlfetch_error = pdf_module.URLFetchingError

        captured: dict = {}

        class _FakeHTML:
            """Serves as both the first-attempt doc (raises) and the retry's
            reconstructed doc (drives the recording fetcher, then writes)."""

            def __init__(self, string=None, url_fetcher=None):
                captured["fetcher"] = url_fetcher

            def write_pdf(self, buf, stylesheets=None):
                if "attempt" not in captured:
                    captured["attempt"] = 1
                    raise urlfetch_error("refused @color-profile")
                # Retry attempt: drive the recording fetcher on a URL the
                # SSRF guard always refuses.
                captured["fetcher"]("http://169.254.169.254/dropped.png")
                buf.write(b"%PDF-partial")

        messages: list[str] = []
        handler = loguru_logger.add(
            lambda m: messages.append(str(m)), level="DEBUG"
        )
        loguru_logger.enable("local_deep_research")
        try:
            with patch.object(pdf_module, "HTML", _FakeHTML):
                out = PDFService()._render_pdf("<html></html>", _FakeHTML(), [])
        finally:
            loguru_logger.disable("local_deep_research")
            loguru_logger.remove(handler)

        assert out.startswith(b"%PDF-partial")
        joined = "\n".join(messages)
        # A plain substring also matches "11 skipped resource(s)" etc.;
        # pin the exact count with a word boundary in front.
        assert re.search(r"\b1 skipped resource", joined), joined[-600:]
        # The surface warning lists the redacted form (scheme://host:port),
        # never the path: "http://169.254.169.254" alone is also a substring
        # of the raw, unredacted URL, so pin that the path is gone too.
        assert "http://169.254.169.254" in joined
        assert "dropped.png" not in joined, joined

    def test_a_failing_retry_does_not_chain_to_the_first_pass_error(self):
        """The retry must run outside the first pass's ``except`` (#6588).

        WeasyPrint builds the first-pass ``URLFetchingError`` from the fetch
        exception's text, which can carry URL material such as secret query
        tokens. The ``InvalidURL: nonnumeric port: '<password>@host'`` text
        used below is fabricated for this test, not a live example: userinfo
        URLs are refused by the guard before urllib parses them
        (``_has_userinfo``), so that exact text cannot arise for a URL the
        guard allows. Were the retry rendered inside that ``except``,
        anything it raised would carry the first-pass error as
        ``__context__``, and ``logger.exception`` in ``markdown_to_pdf``
        would print the secret material.
        """
        import traceback

        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import PDFService

        pdf_module._ensure_weasyprint()
        urlfetch_error = pdf_module.URLFetchingError
        attempts: list[int] = []

        class _FakeHTML:
            def __init__(self, string=None, url_fetcher=None):
                pass

            def write_pdf(self, buf, stylesheets=None):
                attempts.append(1)
                if len(attempts) == 1:
                    raise urlfetch_error(
                        "InvalidURL: nonnumeric port: '[email protected]'"
                    )
                raise RuntimeError("retry layout failure")

        with patch.object(pdf_module, "HTML", _FakeHTML):
            with pytest.raises(
                RuntimeError, match="retry layout failure"
            ) as ei:
                PDFService()._render_pdf("<html></html>", _FakeHTML(), [])

        assert len(attempts) == 2, "the retry must actually have run"
        assert ei.value.__context__ is None, repr(ei.value.__context__)
        assert ei.value.__cause__ is None
        rendered = "".join(traceback.format_exception(ei.value))
        assert "S3CRETPW" not in rendered, rendered

    def test_the_skipped_summary_is_capped(self):
        """A report with many refused resources must not produce one
        unbounded summary line: it lists the first
        ``_SKIPPED_SUMMARY_LIMIT`` (redacted) URLs and counts the rest."""
        from loguru import logger as loguru_logger

        from local_deep_research.web.services import pdf_service as pdf_module
        from local_deep_research.web.services.pdf_service import PDFService

        pdf_module._ensure_weasyprint()
        urlfetch_error = pdf_module.URLFetchingError
        limit = pdf_module._SKIPPED_SUMMARY_LIMIT
        total = limit + 5
        captured: dict = {}

        class _FakeHTML:
            def __init__(self, string=None, url_fetcher=None):
                captured["fetcher"] = url_fetcher

            def write_pdf(self, buf, stylesheets=None):
                if "attempt" not in captured:
                    captured["attempt"] = 1
                    raise urlfetch_error("refused @color-profile")
                for i in range(total):
                    captured["fetcher"](f"http://blocked{i}.invalid/x.png")
                buf.write(b"%PDF-partial")

        messages: list[str] = []
        handler = loguru_logger.add(
            lambda m: messages.append(str(m)), level="DEBUG"
        )
        loguru_logger.enable("local_deep_research")
        try:
            with (
                patch.object(pdf_module, "HTML", _FakeHTML),
                patch.object(pdf_module, "validate_url", return_value=False),
            ):
                PDFService()._render_pdf("<html></html>", _FakeHTML(), [])
        finally:
            loguru_logger.disable("local_deep_research")
            loguru_logger.remove(handler)

        summary = [m for m in messages if "skipped resource(s)" in m]
        assert len(summary) == 1, messages
        line = summary[0]
        assert re.search(rf"\b{total} skipped resource\(s\)", line), line
        assert "(+5 more)" in line, line
        assert f"http://blocked{limit - 1}.invalid" in line, line
        assert f"http://blocked{limit}.invalid" not in line, line