# Copyright (c) 2017-2021 Felix Fontein
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
# Do not use this from other collections or standalone plugins/modules!

from __future__ import annotations

import abc
import typing as t

from ansible.module_utils.common.validation import (
    check_type_bool,
    check_type_dict,
    check_type_float,
    check_type_int,
    check_type_list,
    check_type_str,
)

if t.TYPE_CHECKING:
    AnsibleType = t.Literal["int", "str", "float", "bool"]  # pragma: no cover


def ensure_type(value: t.Any, type_name: str) -> t.Any:
    if type_name == "str":
        return check_type_str(value)
    if type_name == "list":
        return check_type_list(value)
    if type_name == "dict":
        return check_type_dict(value)
    if type_name == "bool":
        return check_type_bool(value)
    if type_name == "int":
        return check_type_int(value)
    if type_name == "float":
        return check_type_float(value)
    return value


class ProviderInformation(metaclass=abc.ABCMeta):
    @abc.abstractmethod
    def get_zone_id_type(self) -> AnsibleType:
        """
        Return the (short) type for zone IDs, like ``'int'`` or ``'str'``.
        """

    @abc.abstractmethod
    def get_record_id_type(self) -> AnsibleType:
        """
        Return the (short) type for record IDs, like ``'int'`` or ``'str'``.
        """

    @abc.abstractmethod
    def get_record_default_ttl(self) -> int | None:
        """
        Return the default TTL for records, like 300, 3600 or None.
        None means that some other TTL (usually from the zone) will be used.
        """

    @abc.abstractmethod
    def get_supported_record_types(self) -> list[str]:
        """
        Return a list of supported record types.
        """

    def normalize_prefix(self, prefix: str | None) -> str | None:
        """
        Given a prefix (string or ``None``), return its normalized form.

        The result should always be None for the trivial prefix, and a non-zero length DNS name
        for a non-trivial prefix.

        If a provider supports other identifiers for the trivial prefix, such as '@', this
        function needs to convert them to ``None`` as well.
        """
        return prefix or None

    def supports_bulk_actions(self) -> bool:
        """
        Return whether the API supports some kind of bulk actions.
        """
        return False

    @abc.abstractmethod
    def txt_record_handling(
        self,
    ) -> t.Literal["decoded", "encoded", "encoded-no-char-encoding"]:
        """
        Return how the API handles TXT records.

        Returns one of the following strings:
        * 'decoded' - the API works with unencoded values
        * 'encoded' - the API works with encoded values
        * 'encoded-no-char-encoding' - the API works with encoded values, but without character encoding
        """

    def txt_character_encoding(self) -> t.Literal["decimal", "octal"]:
        """
        Return how the API handles escape sequences in TXT records.

        Returns one of the following strings:
        * 'octal' - the API works with octal escape sequences
        * 'decimal' - the API works with decimal escape sequences

        This return value is only used if txt_record_handling returns 'encoded'.

        Note: the default return value changed from 'octal' to 'decimal' in community.dns 3.0.0.
        """
        return "decimal"

    def txt_always_quote(self) -> bool:
        """
        Return whether TXT records sent to the API should always be quoted.

        Returns a boolean.

        This return value is only used if txt_record_handling does not return 'decoded'.
        """
        return False
