certapi 1.1.3__tar.gz → 1.1.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certapi
-Version: 1.1.3
+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.3 → certapi-1.1.5}/setup.py

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

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

@@ -2,7 +2,7 @@ import os
 import threading
 import time
 from datetime import datetime, timezone, timedelta
-from typing import Callable, Dict, Optional, Set, Any, List
+from typing import Callable, Dict, Optional, Set, Any, List, Literal
 
 from certapi.crypto import Key, certs_from_pem
 from certapi.client.cert_manager_client import CertManagerClient
@@ -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__(
@@ -42,9 +58,71 @@ class RenewalManager:
         remote_poll_interval_seconds: int = 30,
         clock_fn: Optional[Callable[[], datetime]] = None,
         sleep_fn: Optional[Callable[[float], None]] = None,
+        key_type: Literal["rsa", "ecdsa", "ed25519"] = "ecdsa",
+        expiry_days: int = 90,
+        batch_domains: bool = False,
+        self_verify: bool = True,
+        country: Optional[str] = None,
+        state: Optional[str] = None,
+        locality: Optional[str] = None,
+        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
+        self.expiry_days = expiry_days
+        self.batch_domains = batch_domains
+        self.self_verify = self_verify
+        self.country = country
+        self.state = state
+        self.locality = locality
+        self.organization = organization
+        self.user_id = user_id
         self.sleep_slack_seconds = sleep_slack_seconds
         self.max_sleep_seconds = max_sleep_seconds
         self.renew_retry_interval_seconds = renew_retry_interval_seconds
@@ -71,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
@@ -109,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 {
@@ -139,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)
@@ -146,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())
 
@@ -215,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:
@@ -293,20 +441,24 @@ class RenewalManager:
 
         try:
             renew_threshold_days = self.cert_min_renew_threshold_secs // (24 * 3600)
-            obtain_fn = getattr(self.cert_manager_client, "obtain", None)
-            if callable(obtain_fn):
-                res = self._call_certificate_backend(
-                    obtain_fn,
-                    [domain],
-                    {"renew_threshold_days": renew_threshold_days, "skip_failing": False},
-                )
-            else:
-                # Backward compatibility for clients that only implement issue_certificate.
-                res = self._call_certificate_backend(
-                    self.cert_manager_client.issue_certificate,
-                    [domain],
-                    {"renew_threshold_days": renew_threshold_days},
-                )
+            obtain_options = {
+                "key_type": self.key_type,
+                "expiry_days": self.expiry_days,
+                "renew_threshold_days": renew_threshold_days,
+                "skip_failing": False,
+                "batch_domains": self.batch_domains,
+                "self_verify": self.self_verify,
+                "country": self.country,
+                "state": self.state,
+                "locality": self.locality,
+                "organization": self.organization,
+                "user_id": self.user_id,
+            }
+            res = self._call_certificate_backend(
+                self.cert_manager_client.obtain,
+                [domain],
+                obtain_options,
+            )
             if res is None:
                 return
             self._update_expiry_cache(res.issued + res.existing)

{certapi-1.1.3 → certapi-1.1.5}/src/certapi/manager/acme_cert_manager.py

@@ -75,6 +75,8 @@ class AcmeCertManager:
         organization: Optional[str] = None,
         user_id: Optional[str] = None,
         renew_threshold_days: Optional[int] = None,
+        skip_failing: bool = True,
+        batch_domains: bool = False,
         self_verify: bool = True,
     ) -> CertificateResponse:
         return self.obtain(
@@ -87,6 +89,8 @@ class AcmeCertManager:
             organization=organization,
             user_id=user_id,
             renew_threshold_days=renew_threshold_days,
+            skip_failing=skip_failing,
+            batch_domains=batch_domains,
             self_verify=self_verify,
         )
 
@@ -101,6 +105,8 @@ class AcmeCertManager:
         organization: Optional[str] = None,
         user_id: Optional[str] = None,
         renew_threshold_days: Optional[int] = None,
+        skip_failing: bool = True,
+        batch_domains: bool = False,
         self_verify: bool = True,
     ) -> CertificateResponse:
         return self._issue_certificate_internal(
@@ -113,7 +119,8 @@ class AcmeCertManager:
             organization=organization,
             user_id=user_id,
             renew_threshold_days=renew_threshold_days,
-            batch_generator=None,
+            batch_generator=create_safe_domain_batches if batch_domains else None,
+            skip_failing=skip_failing,
             self_verify=self_verify,
         )
 
@@ -129,6 +136,7 @@ class AcmeCertManager:
         user_id: Optional[str] = None,
         renew_threshold_days: Optional[int] = None,
         batch_generator: Callable[[List[str]], List[List[str]]] = create_safe_domain_batches,
+        skip_failing: bool = True,
         self_verify: bool = True,
     ) -> CertificateResponse:
         return self._issue_certificate_internal(
@@ -142,6 +150,7 @@ class AcmeCertManager:
             user_id=user_id,
             renew_threshold_days=renew_threshold_days,
             batch_generator=batch_generator,
+            skip_failing=skip_failing,
             self_verify=self_verify,
         )
 
@@ -157,6 +166,7 @@ class AcmeCertManager:
         user_id: Optional[str] = None,
         renew_threshold_days: Optional[int] = None,
         batch_generator: Optional[Callable[[List[str]], List[List[str]]]] = None,
+        skip_failing: bool = True,
         self_verify: bool = True,
     ) -> CertificateResponse:
         if isinstance(hosts, str):
@@ -196,6 +206,9 @@ class AcmeCertManager:
                 else:
                     print(f"Warning: No challenge solver found that supports domain: {host}. Skipping.")
 
+            if len(domains_by_store) == 0 and not skip_failing:
+                raise ValueError("None of the domains are owned by this machine or could be verified")
+
             for store, domains_to_issue in domains_by_store.items():
                 issuance_batches = (
                     batch_generator(domains_to_issue) if batch_generator is not None else [domains_to_issue]

{certapi-1.1.3 → certapi-1.1.5}/src/certapi/server/api.py

@@ -122,43 +122,25 @@ def create_api_resources(api_ns, cert_manager: AcmeCertManager, renew_queue_size
         def get(self):
             args = obtain_parser.parse_args()
             hostnames = args["hostname"]
-            skip_failing = args.get("skip_failing", False)
-            self_verify = args.get("self_verify", True)
 
             with lock_manager:
-                if self_verify:
-                    verified_hostnames = []
-                    for h in hostnames:
-                        # Find the first solver that supports and can verify this domain.
-                        for solver in reversed(cert_manager.challenge_solvers):
-                            if solver.supports_domain_strict(h):
-                                verified_hostnames.append(h)
-
-                    hostnames = verified_hostnames
-
-                if not hostnames and not skip_failing:
-                    api_ns.abort(400, message="None of the domains are owned by this machine or could be verified")
-
-                if not hostnames:
-                    return CertificateResponse().to_json()
-
-                issue_fn = (
-                    cert_manager.issue_certificate_in_batches
-                    if args.get("batch_domains")
-                    else cert_manager.issue_certificate
-                )
-                data = issue_fn(
-                    hostnames,
-                    key_type=args["key_type"],
-                    expiry_days=args["expiry_days"],
-                    country=args["country"],
-                    state=args["state"],
-                    locality=args["locality"],
-                    organization=args["organization"],
-                    user_id=args["user_id"],
-                    renew_threshold_days=args.get("renew_threshold_days"),
-                    self_verify=False,
-                )
+                try:
+                    data = cert_manager.obtain(
+                        hostnames,
+                        key_type=args["key_type"],
+                        expiry_days=args["expiry_days"],
+                        country=args["country"],
+                        state=args["state"],
+                        locality=args["locality"],
+                        organization=args["organization"],
+                        user_id=args["user_id"],
+                        renew_threshold_days=args.get("renew_threshold_days"),
+                        skip_failing=args.get("skip_failing", False),
+                        batch_domains=args.get("batch_domains", False),
+                        self_verify=args.get("self_verify", True),
+                    )
+                except ValueError as e:
+                    api_ns.abort(400, message=str(e))
 
                 print(data)
                 if data:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certapi
-Version: 1.1.3
+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.3 → certapi-1.1.5}/tests/test_acme_cert_manager_batching.py

@@ -98,6 +98,26 @@ def test_issue_certificate_in_batches_uses_custom_batch_generator():
     assert [issued.domains for issued in response.issued] == issuer.calls
 
 
+def test_obtain_batch_domains_uses_safe_batches():
+    key_store = DummyKeyStore()
+    issuer = DummyIssuer()
+    solver = DummySolver()
+    manager = AcmeCertManager(key_store=key_store, cert_issuer=issuer, challenge_solvers=[solver])
+
+    domains = [
+        "x.abc.def.ghi.example.com",
+        "root.example.com",
+    ]
+    response = manager.obtain(hosts=domains, batch_domains=True)
+
+    assert issuer.calls == [
+        ["root.example.com"],
+        ["x.abc.def"],
+        ["ghi.example.com"],
+    ]
+    assert len(response.issued) == 3
+
+
 def test_issue_certificate_self_verify_false_skips_strict_solver_check():
     class StrictFailingSolver(DummySolver):
         def supports_domain_strict(self, _domain):
@@ -127,3 +147,23 @@ def test_issue_certificate_self_verify_true_uses_strict_solver_check():
 
     assert issuer.calls == []
     assert response.issued == []
+
+
+def test_obtain_self_verify_true_raises_when_all_domains_fail_and_skip_failing_false():
+    class StrictFailingSolver(DummySolver):
+        def supports_domain_strict(self, _domain):
+            return False
+
+    key_store = DummyKeyStore()
+    issuer = DummyIssuer()
+    solver = StrictFailingSolver()
+    manager = AcmeCertManager(key_store=key_store, cert_issuer=issuer, challenge_solvers=[solver])
+
+    try:
+        manager.obtain(hosts=["force.example.com"], skip_failing=False)
+    except ValueError as e:
+        assert "None of the domains are owned" in str(e)
+    else:
+        raise AssertionError("expected strict obtain failure")
+
+    assert issuer.calls == []

{certapi-1.1.3 → certapi-1.1.5}/tests/test_obtain_interface.py

@@ -4,6 +4,7 @@ from flask import Flask
 from flask_restx import Api, Namespace
 
 from certapi.client.cert_manager_client import CertManagerClient
+from certapi.domain_batching import create_safe_domain_batches
 from certapi.http.types import CertificateResponse
 from certapi.manager.acme_cert_manager import AcmeCertManager
 from certapi.server.api import create_api_resources
@@ -29,6 +30,8 @@ def test_acme_cert_manager_issue_certificate_delegates_to_obtain(monkeypatch):
         organization="Org",
         user_id="u1",
         renew_threshold_days=25,
+        skip_failing=False,
+        batch_domains=True,
         self_verify=False,
     )
 
@@ -42,6 +45,8 @@ def test_acme_cert_manager_issue_certificate_delegates_to_obtain(monkeypatch):
     assert captured["organization"] == "Org"
     assert captured["user_id"] == "u1"
     assert captured["renew_threshold_days"] == 25
+    assert captured["skip_failing"] is False
+    assert captured["batch_domains"] is True
     assert captured["self_verify"] is False
 
 
@@ -60,6 +65,8 @@ def test_acme_cert_manager_obtain_uses_internal_issue_path(monkeypatch):
         key_type="ecdsa",
         expiry_days=90,
         renew_threshold_days=30,
+        skip_failing=False,
+        batch_domains=True,
         self_verify=False,
     )
 
@@ -68,7 +75,8 @@ def test_acme_cert_manager_obtain_uses_internal_issue_path(monkeypatch):
     assert captured["key_type"] == "ecdsa"
     assert captured["expiry_days"] == 90
     assert captured["renew_threshold_days"] == 30
-    assert captured["batch_generator"] is None
+    assert captured["batch_generator"] is create_safe_domain_batches
+    assert captured["skip_failing"] is False
     assert captured["self_verify"] is False
 
 
@@ -157,7 +165,7 @@ def test_remote_obtain_self_verify_false_skips_server_prefilter():
         def __init__(self):
             self.calls = []
 
-        def issue_certificate(self, hosts, **kwargs):
+        def obtain(self, hosts, **kwargs):
             self.calls.append({"hosts": hosts, "kwargs": kwargs})
             return CertificateResponse()
 
@@ -171,7 +179,7 @@ def test_remote_obtain_self_verify_false_skips_server_prefilter():
     assert manager.calls[0]["kwargs"]["self_verify"] is False
 
 
-def test_remote_obtain_self_verify_true_keeps_server_prefilter():
+def test_remote_obtain_self_verify_true_delegates_strict_failure_to_manager():
     app = Flask(__name__)
     api = Api(app)
     api_ns = Namespace("api")
@@ -184,8 +192,10 @@ def test_remote_obtain_self_verify_true_keeps_server_prefilter():
     class Manager:
         challenge_solvers = [Solver()]
 
-        def issue_certificate(self, hosts, **kwargs):
-            raise AssertionError("unverified host should not reach manager")
+        def obtain(self, hosts, **kwargs):
+            assert hosts == ["force.example.com"]
+            assert kwargs["self_verify"] is True
+            raise ValueError("None of the domains are owned by this machine or could be verified")
 
     create_api_resources(api_ns, Manager())
 

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

@@ -23,7 +23,7 @@ class DummyClient:
     def set_handler(self, domain, handler):
         self._handlers[domain] = handler
 
-    def issue_certificate(self, hosts, **kwargs):
+    def obtain(self, hosts, **kwargs):
         host = hosts[0] if isinstance(hosts, list) else hosts
         self.calls.append({"host": host, "kwargs": kwargs})
         handler = self._handlers.get(host)
@@ -35,6 +35,9 @@ class DummyClient:
             return handler(host, kwargs)
         return handler
 
+    def issue_certificate(self, hosts, **kwargs):
+        return self.obtain(hosts, **kwargs)
+
 
 class DummyClientWithObtain(DummyClient):
     def __init__(self):
@@ -45,12 +48,12 @@ class DummyClientWithObtain(DummyClient):
     def obtain(self, hosts, **kwargs):
         host = hosts[0] if isinstance(hosts, list) else hosts
         self.obtain_calls.append({"host": host, "kwargs": kwargs})
-        return super().issue_certificate(hosts, **kwargs)
+        return super().obtain(hosts, **kwargs)
 
     def issue_certificate(self, hosts, **kwargs):
         host = hosts[0] if isinstance(hosts, list) else hosts
         self.issue_calls.append({"host": host, "kwargs": kwargs})
-        return super().issue_certificate(hosts, **kwargs)
+        return super().obtain(hosts, **kwargs)
 
 
 class DummyRemoteClient(CertManagerClient):
@@ -155,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)
@@ -184,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()
@@ -219,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)
 
@@ -252,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:
@@ -290,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
@@ -309,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)
 
@@ -337,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
 
@@ -375,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)
@@ -401,13 +401,39 @@ 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
 
 
+def test_renewal_manager_passes_typed_obtain_options_into_renewal_calls():
+    now = datetime(2026, 1, 1, tzinfo=UTC)
+    client = DummyClient()
+    cert = _make_cert_pem("batch.example.com", now, valid_for_days=60)
+    client.set_handler(
+        "batch.example.com",
+        CertificateResponse(issued=[IssuedCert(cert=cert, domains=["batch.example.com"])], existing=[]),
+    )
+
+    mgr = RenewalManager(
+        client,
+        renew_threshold_days=30,
+        clock_fn=lambda: now,
+        batch_domains=True,
+        self_verify=False,
+        organization="certapi-tests",
+    )
+    mgr.update_watch_domains(["batch.example.com"])
+
+    assert len(client.calls) == 1
+    assert client.calls[0]["kwargs"]["batch_domains"] is True
+    assert client.calls[0]["kwargs"]["self_verify"] is False
+    assert client.calls[0]["kwargs"]["skip_failing"] is False
+    assert client.calls[0]["kwargs"]["renew_threshold_days"] == 30
+    assert client.calls[0]["kwargs"]["organization"] == "certapi-tests"
+
+
 def test_local_keystore_seed_prevents_remote_call_when_fresh():
     now = datetime(2026, 1, 1, tzinfo=UTC)
     key = Key.generate("ecdsa")
@@ -430,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
@@ -465,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:
@@ -486,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"
@@ -519,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)
+
+    def slow_handler(host, kwargs):
+        started.set()
+        release.wait(timeout=2)
+        return CertificateResponse(issued=[IssuedCert(cert=cert, domains=[host])], existing=[])
 
-    mgr.set_watch_domains(["requested.example.com"])
+    client.set_handler("requested.example.com", slow_handler)
+    mgr = RenewalManager(client, clock_fn=lambda: now)
+    mgr.start()
 
-    with mgr._lock:
-        assert mgr._force_trigger is True
+    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)
@@ -542,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:
@@ -552,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()
@@ -569,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()
@@ -599,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()
@@ -620,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
@@ -637,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)