Improving handling of TXT values (#57)

* Add TXT value conversion facilities.

* Improve error message handling.

* Make WSDL encoder to handle all string types.

* Use unicode instead of native strings for TXT entries.

* Allow to not use octal encoding for TXT records.

* Implement TXT value conversion.

* Fix tests for Python 2 (encoding issues).

* Fix tests.

* Improve formulation.

* Add more tests.

* Improve unit tests by moving common code into helper.

* Improve and test conversion error handling.

* Replace normalized/dns -> unquoted/quoted.

Author: felixfontein

plugins/doc_fragments/options.py

@@ -20,3 +20,34 @@ class ModuleDocFragment(object):
         type: int
         default: 2
 '''
+
+    TXT_TRANSFORMATION = r'''
+options:
+    txt_transformation:
+        description:
+            - Determines how TXT entry values are converted between the API and this module's
+              input and output.
+            - The value C(api) means that values are returned from this module as they are returned
+              from the API, and pushed to the API as they have been passed to this module. For
+              idempotency checks, the input string will be compared to the strings returned by the
+              API. The API might automatically transform some values, like splitting long values or
+              adding quotes, which can cause problems with idempotency.
+            - The value C(unquoted) automatically transforms values so that you can pass in unquoted
+              values, and the module will return unquoted values. If you pass in quoted values, they
+              will be double-quoted.
+            - The value C(quoted) automatically transforms values so that you must use quoting for values
+              that contain spaces, characters such as quotation marks and backslashes, and that are
+              longer than 255 bytes. It also makes sure to return values from the API in a normalized
+              encoding.
+            - The default value, C(unquoted), ensures that you can work with values without having
+              to care about how to correctly quote for DNS. Most users should use one of C(unquoted)
+              or C(quoted), but not C(api).
+            - B(Note:) the conversion code assumes UTF-8 encoding for values. If you need another
+              encoding use I(txt_transformation=api) and handle the encoding yourself.
+        type: str
+        choices:
+            - api
+            - quoted
+            - unquoted
+        default: unquoted
+'''

plugins/module_utils/conversion/base.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2021 Felix Fontein
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class DNSConversionError(Exception):
+    def __init__(self, message):
+        super(DNSConversionError, self).__init__(message)
+        self.error_message = message

plugins/module_utils/conversion/converter.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2021 Felix Fontein
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+from ansible.module_utils.common.text.converters import to_text
+from ansible.module_utils.six import raise_from
+
+from ansible_collections.community.dns.plugins.module_utils.record import (
+    DNSRecord,
+)
+
+from ansible_collections.community.dns.plugins.module_utils.conversion.base import (
+    DNSConversionError,
+)
+
+from ansible_collections.community.dns.plugins.module_utils.conversion.txt import (
+    decode_txt_value,
+    encode_txt_value,
+)
+
+
+class RecordConverter(object):
+    def __init__(self, provider_information, option_provider):
+        """
+        Create a record converter.
+        """
+        self._provider_information = provider_information
+        self._option_provider = option_provider
+
+        self._txt_api_handling = self._provider_information.txt_record_handling()  # 'decoded', 'encoded', 'encoded-no-octal'
+        self._txt_transformation = self._option_provider.get_option('txt_transformation')  # 'api', 'quoted', 'unquoted'
+
+    def _handle_txt_api(self, to_api, record):
+        """
+        Handle TXT records for sending to/from the API.
+        """
+        if self._txt_transformation == 'api':
+            # Do not touch record values
+            return
+
+        # We assume that records internally use decoded values
+        if self._txt_api_handling in ('encoded', 'encoded-no-octal'):
+            if to_api:
+                record.target = encode_txt_value(record.target, use_octal=self._txt_api_handling == 'encoded')
+            else:
+                record.target = decode_txt_value(record.target)
+
+    def _handle_txt_user(self, to_user, record):
+        """
+        Handle TXT records for sending to/from the user.
+        """
+        if self._txt_transformation == 'api':
+            # Do not touch record values
+            return
+
+        # We assume that records internally use decoded values
+        if self._txt_transformation == 'quoted':
+            if to_user:
+                record.target = encode_txt_value(record.target)
+            else:
+                record.target = decode_txt_value(record.target)
+
+    def process_from_api(self, record):
+        """
+        Process a record object (DNSRecord) after receiving from API.
+        Modifies the record in-place.
+        """
+        try:
+            record.target = to_text(record.target)
+            if record.type == 'TXT':
+                self._handle_txt_api(False, record)
+            return record
+        except DNSConversionError as e:
+            raise_from(DNSConversionError(u'While processing record from API: {0}'.format(e.error_message)), e)
+
+    def process_to_api(self, record):
+        """
+        Process a record object (DNSRecord) for sending to API.
+        Modifies the record in-place.
+        """
+        try:
+            if record.type == 'TXT':
+                self._handle_txt_api(True, record)
+            return record
+        except DNSConversionError as e:
+            raise_from(DNSConversionError(u'While processing record for the API: {0}'.format(e.error_message)), e)
+
+    def process_from_user(self, record):
+        """
+        Process a record object (DNSRecord) after receiving from the user.
+        Modifies the record in-place.
+        """
+        try:
+            record.target = to_text(record.target)
+            if record.type == 'TXT':
+                self._handle_txt_user(False, record)
+            return record
+        except DNSConversionError as e:
+            raise_from(DNSConversionError(u'While processing record from the user: {0}'.format(e.error_message)), e)
+
+    def process_to_user(self, record):
+        """
+        Process a record object (DNSRecord) for sending to the user.
+        Modifies the record in-place.
+        """
+        try:
+            if record.type == 'TXT':
+                self._handle_txt_user(True, record)
+            return record
+        except DNSConversionError as e:
+            raise_from(DNSConversionError(u'While processing record for the user: {0}'.format(e.error_message)), e)
+
+    def clone_from_api(self, record):
+        """
+        Process a record object (DNSRecord) after receiving from API.
+        Return a modified clone of the record; the original will not be modified.
+        """
+        record = record.clone()
+        self.process_from_api(record)
+        return record
+
+    def clone_to_api(self, record):
+        """
+        Process a record object (DNSRecord) for sending to API.
+        Return a modified clone of the record; the original will not be modified.
+        """
+        record = record.clone()
+        self.process_to_api(record)
+        return record
+
+    def clone_multiple_from_api(self, records):
+        """
+        Process a list of record object (DNSRecord) after receiving from API.
+        Return a list of modified clones of the records; the originals will not be modified.
+        """
+        return [self.clone_from_api(record) for record in records]
+
+    def clone_multiple_to_api(self, records):
+        """
+        Process a list of record objects (DNSRecord) for sending to API.
+        Return a list of modified clones of the records; the originals will not be modified.
+        """
+        return [self.clone_to_api(record) for record in records]
+
+    def process_multiple_from_api(self, records):
+        """
+        Process a list of record object (DNSRecord) after receiving from API.
+        Modifies the records in-place.
+        """
+        for record in records:
+            self.process_from_api(record)
+        return records
+
+    def process_multiple_to_api(self, records):
+        """
+        Process a list of record objects (DNSRecord) for sending to API.
+        Modifies the records in-place.
+        """
+        for record in records:
+            self.process_to_api(record)
+        return records
+
+    def process_multiple_from_user(self, records):
+        """
+        Process a list of record object (DNSRecord) after receiving from the user.
+        Modifies the records in-place.
+        """
+        for record in records:
+            self.process_from_user(record)
+        return records
+
+    def process_multiple_to_user(self, records):
+        """
+        Process a list of record objects (DNSRecord) for sending to the user.
+        Modifies the records in-place.
+        """
+        for record in records:
+            self.process_to_user(record)
+        return records
+
+    def process_value_from_user(self, record_type, value):
+        """
+        Process a record value (string) after receiving from the user.
+        """
+        record = DNSRecord()
+        record.type = record_type
+        record.target = value
+        self.process_from_user(record)
+        return record.target
+
+    def process_values_from_user(self, record_type, values):
+        """
+        Process a list of record values (strings) after receiving from the user.
+        """
+        return [self.process_value_from_user(record_type, value) for value in values]
+
+    def process_value_to_user(self, record_type, value):
+        """
+        Process a record value (string) for sending to the user.
+        """
+        record = DNSRecord()
+        record.type = record_type
+        record.target = value
+        self.process_to_user(record)
+        return record.target
+
+    def process_values_to_user(self, record_type, values):
+        """
+        Process a list of record values (strings) for sending to the user.
+        """
+        return [self.process_value_to_user(record_type, value) for value in values]