acme_certificate and acme_certificate_create_order: add order_creation_error_strategy and order_creation_max_retries options (#842)

* Provide error information.

* Add helper function for order creation retrying.

* Improve existing documentation.

* Document 'replaces' return value.

* Add order_creation_error_strategy and order_creation_max_retries options.

* Add changelog fragment.

* Fix authz deactivation for finalizing step.

* Fix profile handling on order creation.

* Improve existing tests.

* Add ARI and profile tests.

* Warn when 'replaces' is removed when retrying to create an order.

plugins/module_utils/acme/certificate.py

@@ -19,6 +19,7 @@ from ansible_collections.community.crypto.plugins.module_utils.acme.account impo
 )
 
 from ansible_collections.community.crypto.plugins.module_utils.acme.challenges import (
+    Authorization,
     wait_for_validation,
 )
 
@@ -63,6 +64,8 @@ class ACMECertificateClient(object):
             account = ACMEAccount(self.client)
         self.account = account
         self.order_uri = module.params.get('order_uri')
+        self.order_creation_error_strategy = module.params.get('order_creation_error_strategy', 'auto')
+        self.order_creation_max_retries = module.params.get('order_creation_max_retries', 3)
 
         # Make sure account exists
         dummy, account_data = self.account.setup_account(allow_creation=False)
@@ -102,7 +105,15 @@ class ACMECertificateClient(object):
         '''
         if self.identifiers is None:
             raise ModuleFailException('No identifiers have been provided')
-        order = Order.create(self.client, self.identifiers, replaces_cert_id=replaces_cert_id, profile=profile)
+        order = Order.create_with_error_handling(
+            self.client,
+            self.identifiers,
+            error_strategy=self.order_creation_error_strategy,
+            error_max_retries=self.order_creation_max_retries,
+            replaces_cert_id=replaces_cert_id,
+            profile=profile,
+            message_callback=self.module.warn,
+        )
         self.order_uri = order.url
         order.load_authorizations(self.client)
         return order
@@ -248,11 +259,22 @@ class ACMECertificateClient(object):
         https://community.letsencrypt.org/t/authorization-deactivation/19860/2
         https://tools.ietf.org/html/rfc8555#section-7.5.2
         '''
-        for authz in order.authorizations.values():
-            try:
-                authz.deactivate(self.client)
-            except Exception:
-                # ignore errors
-                pass
-            if authz.status != 'deactivated':
-                self.module.warn(warning='Could not deactivate authz object {0}.'.format(authz.url))
+        if len(order.authorization_uris) > len(order.authorizations):
+            for authz_uri in order.authorization_uris:
+                authz = None
+                try:
+                    authz = Authorization.deactivate_url(self.client, authz_uri)
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz is None or authz.status != 'deactivated':
+                    self.module.warn(warning='Could not deactivate authz object {0}.'.format(authz_uri))
+        else:
+            for authz in order.authorizations.values():
+                try:
+                    authz.deactivate(self.client)
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz.status != 'deactivated':
+                    self.module.warn(warning='Could not deactivate authz object {0}.'.format(authz.url))

plugins/module_utils/acme/challenges.py

@@ -322,6 +322,23 @@ class Authorization(object):
             return True
         return False
 
+    @classmethod
+    def deactivate_url(cls, client, url):
+        '''
+        Deactivates this authorization.
+        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
+        https://tools.ietf.org/html/rfc8555#section-7.5.2
+        '''
+        authz = cls(url)
+        authz_deactivate = {
+            'status': 'deactivated'
+        }
+        if client.version == 1:
+            authz_deactivate['resource'] = 'authz'
+        result, info = client.send_signed_request(url, authz_deactivate, fail_on_error=True)
+        authz._setup(client, result)
+        return authz
+
 
 def wait_for_validation(authzs, client):
     '''

plugins/module_utils/acme/errors.py

@@ -84,6 +84,8 @@ class ACMEProtocolException(ModuleFailException):
                 pass
 
         extras = extras or dict()
+        error_code = None
+        error_type = None
 
         if msg is None:
             msg = 'ACME request failed'
@@ -94,7 +96,9 @@ class ACMEProtocolException(ModuleFailException):
             code = info['status']
             extras['http_url'] = url
             extras['http_status'] = code
+            error_code = code
             if code is not None and code >= 400 and content_json is not None and 'type' in content_json:
+                error_type = content_json['type']
                 if 'status' in content_json and content_json['status'] != code:
                     code_msg = 'status {problem_code} (HTTP status: {http_code})'.format(
                         http_code=format_http_status(code), problem_code=content_json['status'])
@@ -134,6 +138,8 @@ class ACMEProtocolException(ModuleFailException):
         )
         self.problem = {}
         self.subproblems = []
+        self.error_code = error_code
+        self.error_type = error_type
         for k, v in extras.items():
             setattr(self, k, v)
 

plugins/module_utils/acme/orders.py

@@ -87,6 +87,55 @@ class Order(object):
             client.directory['newOrder'], new_order, error_msg='Failed to start new order', expected_status_codes=[201])
         return cls.from_json(client, result, info['location'])
 
+    @classmethod
+    def create_with_error_handling(
+        cls,
+        client,
+        identifiers,
+        error_strategy='auto',
+        error_max_retries=3,
+        replaces_cert_id=None,
+        profile=None,
+        message_callback=None,
+    ):
+        """
+        error_strategy can be one of the following strings:
+
+        * ``fail``: simply fail. (Same behavior as ``Order.create()``.)
+        * ``retry_without_replaces_cert_id``: if ``replaces_cert_id`` is not ``None``, set it to ``None`` and retry.
+          The only exception is an error of type ``urn:ietf:params:acme:error:alreadyReplaced``, that indicates that
+          the certificate was already replaced.
+        * ``auto``: try to be clever. Right now this is identical to ``retry_without_replaces_cert_id``, but that can
+          change at any time in the future.
+        * ``always``: always retry until ``error_max_retries`` has been reached.
+        """
+        tries = 0
+        while True:
+            tries += 1
+            try:
+                return cls.create(client, identifiers, replaces_cert_id=replaces_cert_id, profile=profile)
+            except ACMEProtocolException as exc:
+                if tries <= error_max_retries + 1 and error_strategy != 'fail':
+                    if error_strategy == 'always':
+                        continue
+
+                    if (
+                        error_strategy in ('auto', 'retry_without_replaces_cert_id') and
+                        replaces_cert_id is not None and
+                        not (exc.error_code == 409 and exc.error_type == 'urn:ietf:params:acme:error:alreadyReplaced')
+                    ):
+                        replaces_cert_id = None
+                        if message_callback:
+                            message_callback(
+                                'Stop passing `replaces` due to error {code} {type} when creating ACME order'.format(
+                                    code=exc.error_code,
+                                    type=exc.error_type,
+                                )
+                            )
+                        continue
+
+                raise
+
     def refresh(self, client):
         result, dummy = client.get_request(self.url)
         changed = self.data != result