mkdocs2confluence 0.6.2__tar.gz → 0.6.3__tar.gz

{mkdocs2confluence-0.6.2/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.6.2
+Version: 0.6.3
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.6.2"
+version = "0.6.3"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.3/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.6.2
+Version: 0.6.3
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.3}/src/mkdocs_to_confluence/transforms/mermaid.py

@@ -18,6 +18,7 @@ import dataclasses
 import hashlib
 import sys
 import threading
+import time
 import urllib.error
 import urllib.request
 from concurrent.futures import ThreadPoolExecutor, as_completed
@@ -33,6 +34,9 @@ _TIMEOUT = 30  # seconds — fail fast when Kroki is down
 _MIN_PNG_BYTES = 67  # smallest valid PNG (1×1 px) is 67 bytes
 _CACHE_LOCK = threading.Lock()
 _MAX_WORKERS = 8
+_RETRY_ATTEMPTS = 3
+_RETRY_BACKOFF = 1.0  # seconds; doubles each attempt
+_RETRYABLE_HTTP = {429, 500, 502, 503, 504}
 
 
 def _kroki_png(source: str, kroki_url: str) -> bytes:
@@ -63,25 +67,45 @@ def _warn(msg: str) -> None:
 
 
 def _render_one(source: str, kroki_url: str) -> Path | None:
-    """Render a single diagram to cache. Returns cache path on success, None on failure."""
+    """Render a single diagram to cache. Returns cache path on success, None on failure.
+
+    Transient HTTP errors (429, 5xx) and network blips are retried up to
+    ``_RETRY_ATTEMPTS`` times with exponential backoff.
+    """
     path = _cache_path(source)
     if path.exists():
         print("        rendering  mermaid diagram (cached)")
         return path
-    try:
-        print(f"        rendering  mermaid diagram via Kroki ({kroki_url})")
-        png = _kroki_png(source, kroki_url)
-        if len(png) < _MIN_PNG_BYTES:
-            raise ValueError(f"Kroki returned {len(png)} bytes (expected a valid PNG)")
-        with _CACHE_LOCK:
-            path.write_bytes(png)
-        return path
-    except urllib.error.HTTPError as exc:
-        _warn(f"mermaid diagram: Kroki returned HTTP {exc.code} {exc.reason} — falling back to code block")
-    except urllib.error.URLError as exc:
-        _warn(f"mermaid diagram: Kroki unreachable ({exc.reason}) — falling back to code block")
-    except (OSError, ValueError) as exc:
-        _warn(f"mermaid diagram: {exc} — falling back to code block")
+
+    last_exc: Exception | None = None
+    for attempt in range(_RETRY_ATTEMPTS):
+        if attempt > 0:
+            delay = _RETRY_BACKOFF * (2 ** (attempt - 1))
+            _warn(f"mermaid diagram: retrying in {delay:.0f}s (attempt {attempt + 1}/{_RETRY_ATTEMPTS})")
+            time.sleep(delay)
+        try:
+            print(f"        rendering  mermaid diagram via Kroki ({kroki_url})")
+            png = _kroki_png(source, kroki_url)
+            if len(png) < _MIN_PNG_BYTES:
+                raise ValueError(f"Kroki returned {len(png)} bytes (expected a valid PNG)")
+            with _CACHE_LOCK:
+                path.write_bytes(png)
+            return path
+        except urllib.error.HTTPError as exc:
+            if exc.code in _RETRYABLE_HTTP:
+                last_exc = exc
+                continue  # retry
+            _warn(f"mermaid diagram: Kroki returned HTTP {exc.code} {exc.reason} — falling back to code block")
+            return None
+        except urllib.error.URLError as exc:
+            last_exc = exc
+            continue  # retry — network blip
+        except (OSError, ValueError) as exc:
+            _warn(f"mermaid diagram: {exc} — falling back to code block")
+            return None
+
+    # All retries exhausted
+    _warn(f"mermaid diagram: failed after {_RETRY_ATTEMPTS} attempts ({last_exc}) — falling back to code block")
     return None
 
 

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.3}/tests/test_mermaid.py

@@ -109,6 +109,7 @@ def test_render_fallback_on_network_error(tmp_path, capsys):
 
     with (
         patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path),
+        patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"),
         patch(
             "mkdocs_to_confluence.transforms.mermaid._kroki_png",
             side_effect=urllib.error.URLError("timed out"),
@@ -119,7 +120,6 @@ def test_render_fallback_on_network_error(tmp_path, capsys):
     assert len(attachments) == 0
     assert updated_nodes[0].attachment_name is None  # type: ignore[union-attr]
     err = capsys.readouterr().err
-    assert "Kroki unreachable" in err
     assert "falling back to code block" in err
 
 
@@ -131,6 +131,7 @@ def test_render_fallback_on_http_error(tmp_path, capsys):
 
     with (
         patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path),
+        patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"),
         patch(
             "mkdocs_to_confluence.transforms.mermaid._kroki_png",
             side_effect=urllib.error.HTTPError(
@@ -143,7 +144,6 @@ def test_render_fallback_on_http_error(tmp_path, capsys):
     assert len(attachments) == 0
     assert updated_nodes[0].attachment_name is None  # type: ignore[union-attr]
     err = capsys.readouterr().err
-    assert "HTTP 503" in err
     assert "falling back to code block" in err
 
 
@@ -258,14 +258,71 @@ def test_render_one_cached(tmp_path):
 
 
 def test_render_one_network_failure_returns_none(tmp_path):
-    """_render_one returns None on network failure."""
+    """_render_one returns None after all retries on persistent network failure."""
     import urllib.error
     from mkdocs_to_confluence.transforms.mermaid import _render_one
 
     with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
          patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
                side_effect=urllib.error.URLError("connection refused")):
         result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
 
     assert result is None
 
+
+# ── Retry behaviour ───────────────────────────────────────────────────────────
+
+
+def test_render_one_retries_on_503_then_succeeds(tmp_path):
+    """_render_one retries on HTTP 503 and succeeds on the second attempt."""
+    import urllib.error
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    calls = [urllib.error.HTTPError("url", 503, "Service Unavailable", {}, None), _FAKE_PNG]
+
+    def fake_kroki(source: str, url: str) -> bytes:
+        result = calls.pop(0)
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep") as mock_sleep, \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png", side_effect=fake_kroki):
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is not None
+    assert result.exists()
+    mock_sleep.assert_called_once_with(1.0)  # backed off once
+
+
+def test_render_one_non_retryable_http_error_returns_none(tmp_path):
+    """_render_one does not retry on HTTP 400 (bad input) — returns None immediately."""
+    import urllib.error
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep") as mock_sleep, \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.HTTPError("url", 400, "Bad Request", {}, None)):
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is None
+    mock_sleep.assert_not_called()  # no retry for 400
+
+
+def test_render_one_exhausts_retries_on_persistent_503(tmp_path):
+    """_render_one returns None after all attempts on persistent 503."""
+    import urllib.error
+    from mkdocs_to_confluence.transforms.mermaid import _render_one, _RETRY_ATTEMPTS
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.HTTPError("url", 503, "Service Unavailable", {}, None)) as mock_fetch:
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is None
+    assert mock_fetch.call_count == _RETRY_ATTEMPTS
+