devnomads 0.2.5__tar.gz → 0.3.0__tar.gz

{devnomads-0.2.5 → devnomads-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devnomads
-Version: 0.2.5
+Version: 0.3.0
 Summary: Python client library for the DevNomads API (transport, DNS, ACME)
 Project-URL: Homepage, https://devnomads.nl
 Author-email: DevNomads <support@devnomads.nl>
@@ -13,6 +13,7 @@ Requires-Dist: acme>=2.11; extra == 'acme'
 Requires-Dist: cryptography>=42; extra == 'acme'
 Requires-Dist: dnspython>=2.6; extra == 'acme'
 Requires-Dist: josepy>=1.14; extra == 'acme'
+Requires-Dist: requests>=2.31; extra == 'acme'
 Description-Content-Type: text/markdown
 
 # devnomads

{devnomads-0.2.5 → devnomads-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devnomads"
-version = "0.2.5"
+version = "0.3.0"
 description = "Python client library for the DevNomads API (transport, DNS, ACME)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,13 @@ dependencies = ["httpx>=0.27"]
 # The ACME client pulls in the only heavy dependencies in the project, so
 # it lives behind an extra: `pip install devnomads[acme]`. Without it,
 # `import devnomads.acme` raises a clear, actionable ImportError.
-acme = ["acme>=2.11", "josepy>=1.14", "cryptography>=42", "dnspython>=2.6"]
+acme = [
+    "acme>=2.11",
+    "josepy>=1.14",
+    "cryptography>=42",
+    "dnspython>=2.6",
+    "requests>=2.31",
+]
 
 [project.urls]
 Homepage = "https://devnomads.nl"

{devnomads-0.2.5 → devnomads-0.3.0}/src/devnomads/acme/__init__.py

@@ -26,7 +26,7 @@ try:
         AcmeClient,
     )
     from .dns01 import DevNomadsDnsProvider, DnsProvider
-    from .errors import AcmeError
+    from .errors import AcmeError, TransientAcmeError
     from .http01 import Http01Solver, StandaloneSolver, WebrootSolver
     from .keys import (
         build_csr,
@@ -52,6 +52,7 @@ __all__ = [
     "ZEROSSL_DIRECTORY_URL",
     "CA_DIRECTORIES",
     "AcmeError",
+    "TransientAcmeError",
     "DnsProvider",
     "DevNomadsDnsProvider",
     "Http01Solver",

{devnomads-0.2.5 → devnomads-0.3.0}/src/devnomads/acme/client.py

@@ -3,16 +3,18 @@
 from __future__ import annotations
 
 import logging
+from contextlib import contextmanager
 from datetime import datetime, timedelta
 from time import sleep, time
 
+import requests
 from acme import challenges
 from acme import client as acme_client
 from acme import errors as acme_errors
 from acme import messages
 
 from .dns01 import DnsProvider
-from .errors import AcmeError
+from .errors import AcmeError, TransientAcmeError
 from .http01 import Http01Solver
 from .keys import (
     PrivateKey,
@@ -45,6 +47,35 @@ CA_DIRECTORIES = {
 # account registration.
 _EAB_REQUIRED_PROVIDERS = frozenset({"zerossl"})
 
+# ACME problem-document codes that mean "the CA had a problem", not "the
+# subject is broken". These are retry-safe: back off and try again later.
+_TRANSIENT_ACME_CODES = {"serverInternal", "rateLimited", "badNonce"}
+
+
+@contextmanager
+def _reraise_transient(step: str):
+    """Re-raise infrastructure-level failures as :class:`TransientAcmeError`.
+
+    Wraps a network-facing ACME step. Structural ACME errors (validation
+    failures, unauthorized, CAA, ...) pass through untouched so callers can
+    still treat them as permanent.
+    """
+
+    try:
+        yield
+    except requests.exceptions.RequestException as exc:
+        raise TransientAcmeError(f"{step}: CA unreachable: {exc}") from exc
+    except messages.Error as exc:
+        if exc.code in _TRANSIENT_ACME_CODES:
+            raise TransientAcmeError(f"{step}: {exc}", code=exc.code) from exc
+        raise
+    except (
+        acme_errors.TimeoutError,
+        acme_errors.PollError,
+        acme_errors.NonceError,
+    ) as exc:
+        raise TransientAcmeError(f"{step}: {exc}") from exc
+
 
 def _challenge_for_authz(challenge_types_map: dict[str, str], authz_body) -> str | None:
     """Resolve the configured challenge type for one authorization.
@@ -139,7 +170,8 @@ class AcmeClient:
         net = acme_client.ClientNetwork(
             account_key, alg=jws_alg(account_key), user_agent=self.user_agent
         )
-        directory = messages.Directory.from_json(net.get(self.directory_url).json())
+        with _reraise_transient("directory fetch"):
+            directory = messages.Directory.from_json(net.get(self.directory_url).json())
         client = acme_client.ClientV2(directory, net)
 
         registration_kwargs = dict(
@@ -161,14 +193,15 @@ class AcmeClient:
         new_account = messages.NewRegistration(**registration_kwargs)
 
         account = None
-        try:
-            account = client.new_account(new_account)
-        except acme_errors.ConflictError as exc:
-            uri = getattr(exc, "location", None) or getattr(
-                getattr(exc, "response", None), "headers", {}
-            ).get("Location")
-            if uri:
-                account = messages.RegistrationResource(body=None, uri=uri)
+        with _reraise_transient("account registration"):
+            try:
+                account = client.new_account(new_account)
+            except acme_errors.ConflictError as exc:
+                uri = getattr(exc, "location", None) or getattr(
+                    getattr(exc, "response", None), "headers", {}
+                ).get("Location")
+                if uri:
+                    account = messages.RegistrationResource(body=None, uri=uri)
 
         if account is None:
             account = getattr(client.net, "account", None)
@@ -183,13 +216,14 @@ class AcmeClient:
     def _wait_for_authz(self, client, authz, timeout: int = 300):
         deadline = time() + timeout
         while time() < deadline:
-            authz, _ = client.poll(authz)
+            with _reraise_transient("authorization poll"):
+                authz, _ = client.poll(authz)
             if authz.body.status == messages.STATUS_VALID:
                 return authz
             if authz.body.status == messages.STATUS_INVALID:
                 raise AcmeError(_authz_failure(authz.body))
             sleep(2)
-        raise AcmeError("authorization polling timed out")
+        raise TransientAcmeError("authorization polling timed out")
 
     def _fetch_order_authorizations(self, client, order):
         raw = getattr(order, "authorizations", None) or []
@@ -235,7 +269,8 @@ class AcmeClient:
         csr_pem = build_csr(domain_key, identifiers)
         log.info("requesting certificate for: %s", ", ".join(identifiers))
 
-        order = client.new_order(csr_pem)
+        with _reraise_transient("new order"):
+            order = client.new_order(csr_pem)
         authzs = self._fetch_order_authorizations(client, order)
 
         http_tokens: list[str] = []
@@ -258,9 +293,10 @@ class AcmeClient:
                     client, dns_challenges, dns_propagation_delay
                 )
 
-            order = client.poll_and_finalize(
-                order, deadline=datetime.now() + timedelta(seconds=300)
-            )
+            with _reraise_transient("finalize order"):
+                order = client.poll_and_finalize(
+                    order, deadline=datetime.now() + timedelta(seconds=300)
+                )
         finally:
             self._cleanup(http01_solver, http_tokens, dns_provider, dns_challenges)
 
@@ -308,7 +344,12 @@ class AcmeClient:
             if dns_challenges:
                 sleep(1)  # space out API calls to avoid rate limiting
             log.info("planting dns-01 challenge for %s", fqdn)
-            dns_provider.create_challenge(fqdn, validation)
+            try:
+                dns_provider.create_challenge(fqdn, validation)
+            except Exception as exc:  # noqa: BLE001
+                raise TransientAcmeError(
+                    f"dns provider failed to create challenge for {fqdn}: {exc}"
+                ) from exc
             dns_challenges.append((fqdn, challb, response, authz, validation))
         else:
             if not http01_solver:
@@ -317,7 +358,8 @@ class AcmeClient:
             log.info("serving http-01 challenge for %s", ident)
             http01_solver.set(token, validation)
             http_tokens.append(token)
-            client.answer_challenge(challb, response)
+            with _reraise_transient("answer challenge"):
+                client.answer_challenge(challb, response)
             self._wait_for_authz(client, authz)
 
     def _answer_dns_challenges(self, client, dns_challenges, delay: int) -> None:
@@ -329,13 +371,14 @@ class AcmeClient:
             if not verify_txt_record(
                 fqdn, validation, nameservers=self.recursive_nameservers
             ):
-                raise AcmeError(
+                raise TransientAcmeError(
                     f"DNS challenge verification failed for {fqdn}: "
                     "TXT record not found at authoritative nameservers"
                 )
         for fqdn, challb, response, authz, _ in dns_challenges:
             log.info("answering dns-01 challenge for %s", fqdn)
-            client.answer_challenge(challb, response)
+            with _reraise_transient("answer challenge"):
+                client.answer_challenge(challb, response)
             self._wait_for_authz(client, authz)
 
     def _cleanup(

devnomads-0.3.0/src/devnomads/acme/errors.py

@@ -0,0 +1,27 @@
+"""ACME-specific exceptions."""
+
+from __future__ import annotations
+
+from ..api.errors import DevNomadsError
+
+
+class AcmeError(DevNomadsError):
+    """An ACME issuance step failed."""
+
+
+class TransientAcmeError(AcmeError):
+    """A retry-safe ACME failure (CA unreachable, rate limit,
+    propagation timeout, DNS provider outage). The operation may
+    succeed if simply retried later; callers should back off and
+    retry rather than treat the subject as permanently broken.
+
+    ``code`` carries the bare ACME error code when one is known
+    (e.g. ``"rateLimited"``, ``"serverInternal"``) so callers can
+    apply per-code retry policy without string-matching the
+    message. None when the failure was not an ACME problem
+    document (network error, propagation timeout, ...).
+    """
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code

{devnomads-0.2.5 → devnomads-0.3.0}/tests/test_acme_client.py

@@ -6,11 +6,12 @@ from types import SimpleNamespace
 
 import pytest
 
-from devnomads.acme import AcmeError
+from devnomads.acme import AcmeError, TransientAcmeError
 from devnomads.acme.client import (
     _challenge_for_authz,
     _normalize_challenge_types,
     _normalize_identifiers,
+    _reraise_transient,
     _split_fullchain,
 )
 
@@ -227,3 +228,132 @@ def test_partial_eab_credentials_raise(tmp_path):
 
     with pytest.raises(AcmeError):
         client_mod.AcmeClient(str(tmp_path / "a.pem"), eab_kid="kid-only")
+
+
+# -- WI-1: transient/structural ACME failure classification ---------------
+
+
+def test_transient_error_is_acme_error_subclass():
+    """Callers that catch AcmeError must still catch the transient variant,
+    so the outer 'blacklist everything' net keeps working if a caller has
+    not yet special-cased transients."""
+
+    assert issubclass(TransientAcmeError, AcmeError)
+    exc = TransientAcmeError("boom", code="rateLimited")
+    assert exc.code == "rateLimited"
+    assert TransientAcmeError("boom").code is None
+
+
+def test_reraise_transient_wraps_request_exception():
+    import requests
+
+    with pytest.raises(TransientAcmeError) as ei:
+        with _reraise_transient("directory fetch"):
+            raise requests.exceptions.ConnectTimeout("no route to CA")
+    assert ei.value.code is None
+    assert "directory fetch" in str(ei.value)
+
+
+@pytest.mark.parametrize("code", ["serverInternal", "rateLimited", "badNonce"])
+def test_reraise_transient_wraps_transient_acme_codes(code):
+    from acme import messages
+
+    with pytest.raises(TransientAcmeError) as ei:
+        with _reraise_transient("new order"):
+            raise messages.Error.with_code(code)
+    assert ei.value.code == code
+
+
+@pytest.mark.parametrize("code", ["unauthorized", "caa", "rejectedIdentifier"])
+def test_reraise_transient_passes_structural_acme_codes(code):
+    """Structural ACME problem documents must escape as plain messages.Error
+    (not TransientAcmeError) so the caller still blacklists the domain."""
+
+    from acme import messages
+
+    err = messages.Error.with_code(code)
+    with pytest.raises(messages.Error) as ei:
+        with _reraise_transient("new order"):
+            raise err
+    assert not isinstance(ei.value, TransientAcmeError)
+    assert ei.value is err
+
+
+@pytest.mark.parametrize("exc_name", ["TimeoutError", "PollError", "NonceError"])
+def test_reraise_transient_wraps_acme_poll_errors(exc_name):
+    from acme import errors as acme_errors
+
+    exc_cls = getattr(acme_errors, exc_name)
+    try:
+        raised = exc_cls("boom")
+    except TypeError:
+        # PollError's constructor signature differs across acme versions.
+        raised = exc_cls(set(), {})
+
+    with pytest.raises(TransientAcmeError):
+        with _reraise_transient("authorization poll"):
+            raise raised
+
+
+def test_reraise_transient_passes_unrelated_exceptions():
+    with pytest.raises(ValueError):
+        with _reraise_transient("new order"):
+            raise ValueError("not an acme failure")
+
+
+def _dns01_authz(ident):
+    from acme import challenges
+
+    challb = SimpleNamespace(
+        chall=challenges.DNS01(token=b"\x00" * 32),
+        response_and_validation=lambda key: (SimpleNamespace(), "validation-string"),
+    )
+    body = SimpleNamespace(
+        identifier=SimpleNamespace(value=ident),
+        status=SimpleNamespace(name="pending"),
+        challenges=[challb],
+        wildcard=False,
+    )
+    return SimpleNamespace(body=body)
+
+
+def test_setup_authz_dns_provider_failure_is_transient(tmp_path):
+    """A DNS provider outage (API down, bad credentials, network) is an
+    infrastructure problem, never a statement about the domain."""
+
+    from devnomads.acme import client as client_mod
+
+    class BadProvider:
+        def create_challenge(self, fqdn, validation):
+            raise RuntimeError("dns api down")
+
+    ac = client_mod.AcmeClient(str(tmp_path / "a.pem"))
+    authz = _dns01_authz("example.com")
+
+    with pytest.raises(TransientAcmeError) as ei:
+        ac._setup_authz(
+            client=None,
+            account_key=None,
+            authz=authz,
+            types_map={"example.com": "dns-01"},
+            dns_provider=BadProvider(),
+            http01_solver=None,
+            http_tokens=[],
+            dns_challenges=[],
+        )
+    assert "dns provider failed" in str(ei.value)
+
+
+def test_answer_dns_challenges_txt_timeout_is_transient(monkeypatch, tmp_path):
+    """Slow TXT propagation is retry-safe, not a permanent failure."""
+
+    from devnomads.acme import client as client_mod
+
+    monkeypatch.setattr(client_mod, "verify_txt_record", lambda *a, **k: False)
+
+    ac = client_mod.AcmeClient(str(tmp_path / "a.pem"))
+    dns_challenges = [("example.com", object(), object(), object(), "validation")]
+
+    with pytest.raises(TransientAcmeError) as ei:
+        ac._answer_dns_challenges(client=None, dns_challenges=dns_challenges, delay=0)
+    assert "TXT record not found" in str(ei.value)

{devnomads-0.2.5 → devnomads-0.3.0}/uv.lock

@@ -468,7 +468,7 @@ wheels = [
 
 [[package]]
 name = "devnomads"
-version = "0.2.4"
+version = "0.2.5"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -480,6 +480,7 @@ acme = [
     { name = "cryptography" },
     { name = "dnspython" },
     { name = "josepy" },
+    { name = "requests" },
 ]
 
 [package.dev-dependencies]
@@ -502,6 +503,7 @@ requires-dist = [
     { name = "dnspython", marker = "extra == 'acme'", specifier = ">=2.6" },
     { name = "httpx", specifier = ">=0.27" },
     { name = "josepy", marker = "extra == 'acme'", specifier = ">=1.14" },
+    { name = "requests", marker = "extra == 'acme'", specifier = ">=2.31" },
 ]
 
 [package.metadata.requires-dev]

devnomads-0.2.5/src/devnomads/acme/errors.py

@@ -1,9 +0,0 @@
-"""ACME-specific exceptions."""
-
-from __future__ import annotations
-
-from ..api.errors import DevNomadsError
-
-
-class AcmeError(DevNomadsError):
-    """An ACME issuance step failed."""