certapi 1.1.4__tar.gz → 1.1.5__tar.gz

{certapi-1.1.4/src/certapi.egg-info → certapi-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certapi
-Version: 1.1.4
+Version: 1.1.5
 Summary: Python Package for managing keys, request SSL certificates from ACME.
 Home-page: https://github.com/mesudip/certapi
 Author: Sudip Bhattarai

{certapi-1.1.4 → certapi-1.1.5}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="certapi",
-    version="1.1.4",
+    version="1.1.5",
     packages=find_packages(where="src"),
     package_dir={"": "src"},
     install_requires=[

{certapi-1.1.4 → certapi-1.1.5}/src/certapi/client/renewal_manager.py

@@ -12,7 +12,15 @@ from certapi.manager.acme_cert_manager import DEFAULT_RENEW_THRESHOLD_DAYS
 
 class RenewalManager:
     """
-    Background certificate refresh manager.
+    Keep certificates fresh for a changing set of watched domains.
+
+    RenewalManager can run as a background worker with :meth:`start`, while
+    callers publish the complete desired domain set through
+    :meth:`update_watch_domains`. Publishing a domain set is synchronous: the call
+    returns after certapi has processed the set and attempted any due
+    obtain/renew work. Each renewal pass first calls the optional
+    ``sync_watch_domains`` callback so integrations can republish the latest
+    domain list before certapi decides what to obtain or renew.
 
     Algorithm:
     - Maintain a watched domain set and cache each domain's certificate expiry.
@@ -27,6 +35,14 @@ class RenewalManager:
     - On failure for renewal, where a cached or local certificate exists, keep reusing
       that existing certificate even if it is expired, defer the next retry, and do not
       replace it with a self-signed certificate.
+
+    The manager keeps an in-memory expiry cache, bootstraps that cache from the
+    backend keystore when possible, renews missing or soon-expiring
+    certificates, and records failures in :meth:`get_state`. New domains that
+    fail issuance receive a short-lived retry blacklist and, when the backend
+    exposes a keystore, a local self-signed fallback certificate. Renewal
+    failures for domains with an existing certificate keep using that
+    certificate and schedule a later retry.
     """
 
     def __init__(
@@ -52,6 +68,50 @@ class RenewalManager:
         organization: Optional[str] = None,
         user_id: Optional[str] = None,
     ):
+        """
+        Create a renewal manager for a certificate backend.
+
+        Args:
+            cert_manager_client: Backend object with an ``obtain(domains,
+                **kwargs)`` method. Local managers and ``CertManagerClient`` are
+                both supported.
+            sync_watch_domains: Optional callback invoked at the start of each
+                renewal pass. The callback should call :meth:`update_watch_domains`
+                with the latest desired domain list. Calls made from this
+                callback only update the in-progress cycle and do not start a
+                nested renewal pass.
+            renew_threshold_days: Renew certificates when they expire within
+                this many days. Defaults to ``CERT_RENEW_THRESHOLD_DAYS`` or the
+                certapi default.
+            min_renew_threshold_days: Lower bound for renewal attempts, used to
+                avoid renewing too close to expiry even when a smaller threshold
+                is configured.
+            sleep_slack_seconds: Extra delay added after the calculated next
+                renewal time to avoid waking exactly on the threshold boundary.
+            max_sleep_seconds: Maximum time the background worker sleeps between
+                checks.
+            renew_retry_interval_seconds: Delay before retrying renewal for a
+                domain that already has a local certificate.
+            blacklist_duration_seconds: Delay before retrying issuance for a
+                domain that had no usable local certificate.
+            remote_poll_interval_seconds: Poll interval while waiting for remote
+                ``CertManagerClient`` requests.
+            clock_fn: Optional clock override for deterministic tests.
+            sleep_fn: Optional sleep override for deterministic tests.
+            key_type: Private key type requested from the backend.
+            expiry_days: Requested certificate lifetime when the backend
+                supports it.
+            batch_domains: Forwarded to the backend to enable domain batching.
+            self_verify: Forwarded to the backend to enable or disable
+                ownership self-verification.
+            country: Optional subject country for issued or fallback certs.
+            state: Optional subject state for issued or fallback certs.
+            locality: Optional subject locality for issued or fallback certs.
+            organization: Optional subject organization for issued or fallback
+                certs.
+            user_id: Optional subject/user identifier for issued or fallback
+                certs.
+        """
         self.cert_manager_client = cert_manager_client
         self.sync_watch_domains = sync_watch_domains
         self.key_type = key_type
@@ -89,34 +149,73 @@ class RenewalManager:
         self._lock = threading.Condition()
         self._thread: Optional[threading.Thread] = None
         self._running = False
+        self._cycle_requested = False
         self._force_trigger = False
         self._cycle_running = False
         self._cycle_thread_id: Optional[int] = None
+        self._cycle_generation = 0
         self._blacklist: Dict[str, datetime] = {}
         self._last_error_message: Optional[str] = None
         self._last_error_timestamp: Optional[datetime] = None
         self._self_signer: Optional[SelfCertIssuer] = None
 
-    def set_watch_domains(self, domains: List[str]):
+    def update_watch_domains(self, domains: List[str]):
+        """
+        Replace the complete set of domains and process it before returning.
+
+        Empty values are ignored. Cache and blacklist entries for domains no
+        longer being watched are dropped.
+
+        When called outside an active renewal cycle, this method immediately
+        runs or wakes a renewal pass and blocks until certapi has attempted any
+        due obtain/renew work for the published set. When called from
+        ``sync_watch_domains`` during a renewal cycle, it only updates the set
+        being processed and returns immediately to avoid recursive cycles.
+        """
         new_watch_set = {x for x in domains if x}
         with self._lock:
             self._watch_domains = new_watch_set
             self._cache = {d: expiry for d, expiry in self._cache.items() if d in self._watch_domains}
             self._blacklist = {d: exp for d, exp in self._blacklist.items() if d in self._watch_domains}
-            if self._running and self._cycle_thread_id != threading.get_ident():
-                self._force_trigger = True
+            if self._cycle_thread_id == threading.get_ident():
+                self._lock.notify_all()
+                return
+            if self._running:
+                target_generation = self._cycle_generation + (2 if self._cycle_running else 1)
+                self._cycle_requested = True
+                self._lock.notify_all()
+                while self._running and self._cycle_generation < target_generation:
+                    self._lock.wait()
+                return
             self._lock.notify_all()
 
+        self._run_cycle(force=False)
+
     def start(self):
+        """
+        Start the background renewal worker.
+
+        The worker immediately performs a forced renewal pass, then sleeps until
+        the next watched certificate approaches the renewal threshold or until
+        another thread publishes a new set with :meth:`update_watch_domains`.
+        Calling ``start`` while already running is a no-op.
+        """
         with self._lock:
             if self._running:
                 return
             self._running = True
-            self._force_trigger = True
+            self._cycle_requested = True
             self._thread = threading.Thread(target=self._worker, name="CertApi-RenewalManager", daemon=True)
             self._thread.start()
 
     def stop(self):
+        """
+        Stop the background renewal worker and wait briefly for it to exit.
+
+        In-flight remote certificate requests run in daemon helper threads and
+        are not waited on indefinitely; the manager stops scheduling new work
+        and joins the worker thread for up to two seconds.
+        """
         thread = None
         with self._lock:
             self._running = False
@@ -127,14 +226,43 @@ class RenewalManager:
             thread.join(timeout=2)
 
     def trigger_now(self):
+        """
+        Run a renewal pass immediately.
+
+        When the background worker is not running, this method performs the
+        renewal pass in the caller's thread and returns after it completes. When
+        the worker is running, this method wakes it and blocks until the
+        requested renewal pass has completed.
+
+        Most integrations should call :meth:`update_watch_domains` instead. This
+        method is for forcing a pass without changing the watched domain set.
+
+        If called from inside the renewal cycle itself, the method only requests
+        a follow-up pass and returns immediately to avoid deadlock.
+        """
         with self._lock:
             if self._running:
+                if self._cycle_thread_id == threading.get_ident():
+                    self._force_trigger = True
+                    self._lock.notify_all()
+                    return
+                target_generation = self._cycle_generation + (2 if self._cycle_running else 1)
                 self._force_trigger = True
                 self._lock.notify_all()
+                while self._running and self._cycle_generation < target_generation:
+                    self._lock.wait()
                 return
         self._run_cycle(force=True)
 
     def get_state(self) -> Dict[str, Any]:
+        """
+        Return a snapshot of renewal-manager state for diagnostics.
+
+        The returned dictionary includes watched domains, cache size, active
+        blacklisted domains, next cached expiry time, whether the background
+        worker is running, and the most recent error message/timestamp recorded
+        by the manager.
+        """
         with self._lock:
             next_renewal_time = min(self._cache.values()).isoformat() if self._cache else None
             return {
@@ -157,6 +285,7 @@ class RenewalManager:
                 if not self._running:
                     return
                 force = self._force_trigger
+                self._cycle_requested = False
                 self._force_trigger = False
 
             attempt_count = self._run_cycle(force=force)
@@ -164,7 +293,7 @@ class RenewalManager:
             with self._lock:
                 if not self._running:
                     return
-                if self._force_trigger:
+                if self._force_trigger or self._cycle_requested:
                     continue
                 wait_seconds = self._compute_wait_seconds(self.clock_fn())
 
@@ -233,6 +362,7 @@ class RenewalManager:
             with self._lock:
                 self._cycle_running = False
                 self._cycle_thread_id = None
+                self._cycle_generation += 1
                 self._lock.notify_all()
 
     def _run_cycle_body(self, force: bool = False) -> int:

{certapi-1.1.4 → certapi-1.1.5/src/certapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certapi
-Version: 1.1.4
+Version: 1.1.5
 Summary: Python Package for managing keys, request SSL certificates from ACME.
 Home-page: https://github.com/mesudip/certapi
 Author: Sudip Bhattarai

{certapi-1.1.4 → certapi-1.1.5}/tests/test_renewal_manager.py

@@ -158,7 +158,7 @@ def test_default_threshold_and_min_floor(monkeypatch):
 def test_sleep_computation_slack_and_cap():
     now = datetime(2026, 1, 1, tzinfo=UTC)
     mgr = RenewalManager(DummyClient(), renew_threshold_days=30)
-    mgr.set_watch_domains(["example.com"])
+    mgr.update_watch_domains(["example.com"])
 
     with mgr._lock:
         mgr._cache["example.com"] = now + timedelta(days=60)
@@ -187,8 +187,8 @@ def test_existing_cert_failure_sets_threshold_plus_24h_retry():
         renew_threshold_days=30,
         clock_fn=lambda: clock["now"],
     )
-    mgr.set_watch_domains(["example.com"])
     with mgr._lock:
+        mgr._watch_domains = {"example.com"}
         mgr._cache["example.com"] = now - timedelta(hours=1)
 
     mgr.trigger_now()
@@ -222,7 +222,7 @@ def test_existing_cert_failure_does_not_selfsign():
     client.set_handler("existing.example.com", RuntimeError("renew failed"))
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["existing.example.com"])
+    mgr.update_watch_domains(["existing.example.com"])
     with mgr._lock:
         mgr._cache["existing.example.com"] = now - timedelta(hours=1)
 
@@ -255,9 +255,7 @@ def test_expired_local_cert_failure_keeps_existing_cert_and_defers_retry():
     client.set_handler("expired.example.com", RuntimeError("renew failed"))
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["expired.example.com"])
-
-    mgr.trigger_now()
+    mgr.update_watch_domains(["expired.example.com"])
 
     expected = now + timedelta(seconds=mgr.update_threshold_secs + mgr.renew_retry_interval_seconds)
     with mgr._lock:
@@ -293,8 +291,7 @@ def test_expired_sqlite_cert_failure_does_not_seed_selfsigned_as_fresh():
         client.set_handler("sqlite-expired.example.com", RuntimeError("renew failed"))
 
         mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-        mgr.set_watch_domains(["sqlite-expired.example.com"])
-        mgr.trigger_now()
+        mgr.update_watch_domains(["sqlite-expired.example.com"])
 
         with mgr._lock:
             assert "sqlite-expired.example.com" in mgr._cache
@@ -312,7 +309,7 @@ def test_retry_deferral_suppresses_immediate_retry_and_force_when_blacklisted():
     client.set_handler("retry.example.com", RuntimeError("renew failed"))
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: clock["now"])
-    mgr.set_watch_domains(["retry.example.com"])
+    mgr.update_watch_domains(["retry.example.com"])
     with mgr._lock:
         mgr._cache["retry.example.com"] = now - timedelta(minutes=1)
 
@@ -340,15 +337,15 @@ def test_watch_domain_replacement_drops_unwatched_cache_and_sync_callback_replac
     mgr = None
 
     def sync_watch_domains():
-        mgr.set_watch_domains(["c.example.com"])
+        mgr.update_watch_domains(["c.example.com"])
 
     mgr = RenewalManager(client, sync_watch_domains=sync_watch_domains, clock_fn=lambda: now)
-    mgr.set_watch_domains(["a.example.com", "b.example.com"])
+    mgr.update_watch_domains(["a.example.com", "b.example.com"])
     with mgr._lock:
         mgr._cache["a.example.com"] = now + timedelta(days=20)
         mgr._cache["b.example.com"] = now + timedelta(days=20)
 
-    mgr.set_watch_domains(["a.example.com"])
+    mgr.update_watch_domains(["a.example.com"])
     with mgr._lock:
         assert "b.example.com" not in mgr._cache
 
@@ -378,7 +375,7 @@ def test_bootstrap_and_cache_update_from_issued_and_existing():
     )
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["issued.example.com", "existing.example.com"])
+    mgr.update_watch_domains(["issued.example.com", "existing.example.com"])
 
     # No cache initially; both should be obtained immediately to bootstrap.
     mgr._run_cycle(force=False)
@@ -404,8 +401,7 @@ def test_renewal_manager_prefers_obtain_when_available():
     )
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["prefer-obtain.example.com"])
-    mgr._run_cycle(force=False)
+    mgr.update_watch_domains(["prefer-obtain.example.com"])
 
     assert len(client.obtain_calls) == 1
     assert len(client.issue_calls) == 0
@@ -428,8 +424,7 @@ def test_renewal_manager_passes_typed_obtain_options_into_renewal_calls():
         self_verify=False,
         organization="certapi-tests",
     )
-    mgr.set_watch_domains(["batch.example.com"])
-    mgr.trigger_now()
+    mgr.update_watch_domains(["batch.example.com"])
 
     assert len(client.calls) == 1
     assert client.calls[0]["kwargs"]["batch_domains"] is True
@@ -461,8 +456,7 @@ def test_local_keystore_seed_prevents_remote_call_when_fresh():
     client.key_store.set_domain_cert("fresh.example.com", [cert])
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["fresh.example.com"])
-    mgr._run_cycle(force=False)
+    mgr.update_watch_domains(["fresh.example.com"])
 
     with mgr._lock:
         assert "fresh.example.com" in mgr._cache
@@ -496,8 +490,7 @@ def test_local_keystore_seed_stale_cert_still_renews():
     )
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["stale.example.com"])
-    mgr._run_cycle(force=False)
+    mgr.update_watch_domains(["stale.example.com"])
 
     assert len(client.calls) == 1
     with mgr._lock:
@@ -517,9 +510,8 @@ def test_new_domain_failure_selfsigns_and_blacklists():
         blacklist_duration_seconds=180,
         clock_fn=lambda: clock["now"],
     )
-    mgr.set_watch_domains(["new.example.com"])
+    mgr.update_watch_domains(["new.example.com"])
 
-    mgr._run_cycle(force=False)
     assert len(client.calls) == 1
     assert len(client.key_store.saved_certs) == 1
     assert client.key_store.saved_certs[0][2] == "new.example.com.selfsigned"
@@ -550,19 +542,37 @@ def test_sync_callback_exception_sets_state_error():
     assert state["last_error_timestamp"] == now.isoformat()
 
 
-def test_set_watch_domains_external_update_requests_followup_cycle_when_running():
+def test_update_watch_domains_blocks_until_running_worker_processes_domains():
+    now = datetime(2026, 1, 1, tzinfo=UTC)
+    started = threading.Event()
+    release = threading.Event()
     client = DummyClient()
-    mgr = RenewalManager(client)
-    with mgr._lock:
-        mgr._running = True
+    cert = _make_cert_pem("requested.example.com", now, valid_for_days=90)
 
-    mgr.set_watch_domains(["requested.example.com"])
+    def slow_handler(host, kwargs):
+        started.set()
+        release.wait(timeout=2)
+        return CertificateResponse(issued=[IssuedCert(cert=cert, domains=[host])], existing=[])
 
-    with mgr._lock:
-        assert mgr._force_trigger is True
+    client.set_handler("requested.example.com", slow_handler)
+    mgr = RenewalManager(client, clock_fn=lambda: now)
+    mgr.start()
+
+    update_thread = threading.Thread(target=lambda: mgr.update_watch_domains(["requested.example.com"]))
+    update_thread.start()
+
+    assert started.wait(timeout=2)
+    assert update_thread.is_alive()
+    release.set()
+    update_thread.join(timeout=2)
+    mgr.stop()
+
+    assert not update_thread.is_alive()
+    assert len(client.calls) == 1
+    assert client.calls[0]["host"] == "requested.example.com"
 
 
-def test_set_watch_domains_from_cycle_thread_does_not_request_extra_cycle():
+def test_update_watch_domains_from_cycle_thread_does_not_request_extra_cycle():
     now = datetime(2026, 1, 1, tzinfo=UTC)
     client = DummyClient()
     cert = _make_cert_pem("from-callback.example.com", now, valid_for_days=60)
@@ -573,7 +583,7 @@ def test_set_watch_domains_from_cycle_thread_does_not_request_extra_cycle():
     mgr = None
 
     def sync_watch_domains():
-        mgr.set_watch_domains(["from-callback.example.com"])
+        mgr.update_watch_domains(["from-callback.example.com"])
 
     mgr = RenewalManager(client, sync_watch_domains=sync_watch_domains, clock_fn=lambda: now)
     with mgr._lock:
@@ -583,9 +593,55 @@ def test_set_watch_domains_from_cycle_thread_does_not_request_extra_cycle():
 
     with mgr._lock:
         assert mgr._force_trigger is False
+        assert mgr._cycle_requested is False
     assert len(client.calls) == 1
 
 
+def test_running_trigger_now_blocks_until_synced_cycle_finishes():
+    now = datetime(2026, 1, 1, tzinfo=UTC)
+    sync_count = 0
+    sync_ready = threading.Event()
+    sync_enabled = threading.Event()
+    obtain_started = threading.Event()
+    release_obtain = threading.Event()
+    client = DummyClient()
+    cert = _make_cert_pem("blocking.example.com", now, valid_for_days=90)
+    mgr = None
+
+    def slow_handler(host, kwargs):
+        obtain_started.set()
+        release_obtain.wait(timeout=2)
+        return CertificateResponse(issued=[IssuedCert(cert=cert, domains=[host])], existing=[])
+
+    def sync_watch_domains():
+        nonlocal sync_count
+        sync_count += 1
+        sync_ready.set()
+        if sync_enabled.is_set():
+            mgr.update_watch_domains(["blocking.example.com"])
+
+    client.set_handler("blocking.example.com", slow_handler)
+    mgr = RenewalManager(client, sync_watch_domains=sync_watch_domains, clock_fn=lambda: now)
+
+    mgr.start()
+    assert sync_ready.wait(timeout=2)
+
+    sync_enabled.set()
+    trigger_thread = threading.Thread(target=mgr.trigger_now)
+    trigger_thread.start()
+
+    assert obtain_started.wait(timeout=2)
+    assert trigger_thread.is_alive()
+    release_obtain.set()
+    trigger_thread.join(timeout=2)
+
+    mgr.stop()
+    assert not trigger_thread.is_alive()
+    assert sync_count >= 2
+    assert len(client.calls) == 1
+    assert client.calls[0]["host"] == "blocking.example.com"
+
+
 def test_singleflight_suppresses_concurrent_manual_cycles():
     now = datetime(2026, 1, 1, tzinfo=UTC)
     started = threading.Event()
@@ -600,7 +656,8 @@ def test_singleflight_suppresses_concurrent_manual_cycles():
 
     client.set_handler("singleflight.example.com", slow_handler)
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["singleflight.example.com"])
+    with mgr._lock:
+        mgr._watch_domains = {"singleflight.example.com"}
 
     first = threading.Thread(target=lambda: mgr.trigger_now())
     first.start()
@@ -630,7 +687,8 @@ def test_remote_certapi_polling_prints_waiting_message(capsys):
         remote_poll_interval_seconds=0.01,
         clock_fn=lambda: now,
     )
-    mgr.set_watch_domains(["remote.example.com"])
+    with mgr._lock:
+        mgr._watch_domains = {"remote.example.com"}
 
     thread = threading.Thread(target=lambda: mgr.trigger_now())
     thread.start()
@@ -651,9 +709,7 @@ def test_remote_renewal_disables_skip_failing_so_unverified_domain_fails():
     client.key_store = DummyKeyStore()
 
     mgr = RenewalManager(client, renew_threshold_days=30, clock_fn=lambda: now)
-    mgr.set_watch_domains(["missing.example.com"])
-
-    mgr.trigger_now()
+    mgr.update_watch_domains(["missing.example.com"])
 
     assert len(client.obtain_calls) == 1
     assert client.obtain_calls[0]["kwargs"]["skip_failing"] is False
@@ -668,7 +724,8 @@ def test_stop_does_not_wait_for_hung_remote_request_thread():
     release = threading.Event()
     client = DummyRemoteClient(started=started, release=release)
     mgr = RenewalManager(client, remote_poll_interval_seconds=0.01)
-    mgr.set_watch_domains(["hung.example.com"])
+    with mgr._lock:
+        mgr._watch_domains = {"hung.example.com"}
 
     mgr.start()
     assert started.wait(timeout=2)