# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

import collections
import enum
import typing as ty
import warnings

from keystoneauth1 import adapter

from openstack.baremetal.v1 import _common
from openstack import exceptions
from openstack import resource
from openstack import utils
from openstack import warnings as os_warnings


class ValidationResult:
    """Result of a single interface validation.

    :ivar result: Result of a validation, ``True`` for success, ``False`` for
        failure, ``None`` for unsupported interface.
    :ivar reason: If ``result`` is ``False`` or ``None``, explanation of
        the result.
    """

    def __init__(self, result, reason):
        self.result = result
        self.reason = reason


class PowerAction(enum.Enum):
    """Mapping from an action to a target power state."""

    POWER_ON = 'power on'
    """Power on the node."""

    POWER_OFF = 'power off'
    """Power off the node (using hard power off)."""
    REBOOT = 'rebooting'
    """Reboot the node (using hard power off)."""

    SOFT_POWER_OFF = 'soft power off'
    """Power off the node using soft power off."""

    SOFT_REBOOT = 'soft rebooting'
    """Reboot the node using soft power off."""


class WaitResult(
    collections.namedtuple('WaitResult', ['success', 'failure', 'timeout'])
):
    """A named tuple representing a result of waiting for several nodes.

    Each component is a list of :class:`~openstack.baremetal.v1.node.Node`
    objects:

    :ivar ~.success: a list of :class:`~openstack.baremetal.v1.node.Node`
        objects that reached the state.
    :ivar ~.timeout: a list of :class:`~openstack.baremetal.v1.node.Node`
        objects that reached timeout.
    :ivar ~.failure: a list of :class:`~openstack.baremetal.v1.node.Node`
        objects that hit a failure.
    """

    __slots__ = ()


class Node(_common.Resource):
    resources_key = 'nodes'
    base_path = '/nodes'

    # capabilities
    allow_create = True
    allow_fetch = True
    allow_commit = True
    allow_delete = True
    allow_list = True
    allow_patch = True
    commit_method = 'PATCH'
    commit_jsonpatch = True

    _query_mapping = resource.QueryParameters(
        'associated',
        'conductor_group',
        'driver',
        'fault',
        'include_children',
        'parent_node',
        'provision_state',
        'resource_class',
        'shard',
        fields={'type': _common.fields_type},
        instance_id='instance_uuid',
        is_maintenance='maintenance',
    )

    # Ability to run predefined sets of steps on a node using runbooks.
    _max_microversion = '1.92'

    # Properties
    #: The UUID of the allocation associated with this node. Added in API
    #: microversion 1.52.
    allocation_id = resource.Body("allocation_uuid")
    #: A string or UUID of the tenant who owns the baremetal node. Added in API
    #: microversion 1.50.
    owner = resource.Body("owner")
    #: The current boot mode state (uefi/bios). Added in API microversion 1.75.
    boot_mode = resource.Body("boot_mode")
    #: The UUID of the chassis associated wit this node. Can be empty or None.
    chassis_id = resource.Body("chassis_uuid")
    #: The current clean step.
    clean_step = resource.Body("clean_step")
    #: Hostname of the conductor currently handling this node. Added in API
    # microversion 1.49.
    conductor = resource.Body("conductor")
    #: Conductor group this node is managed by. Added in API microversion 1.46.
    conductor_group = resource.Body("conductor_group")
    #: Timestamp at which the node was last updated.
    created_at = resource.Body("created_at")
    #: The current deploy step. Added in API microversion 1.44.
    deploy_step = resource.Body("deploy_step")
    #: The description of the node. Added in API microversion 1.51.
    description = resource.Body("description")
    #: The name of the driver.
    driver = resource.Body("driver")
    #: All the metadata required by the driver to manage this node. List of
    #: fields varies between drivers, and can be retrieved from the
    #: :class:`openstack.baremetal.v1.driver.Driver` resource.
    driver_info = resource.Body("driver_info", type=dict)
    #: Internal metadata set and stored by node's driver. This is read-only.
    driver_internal_info = resource.Body("driver_internal_info", type=dict)
    #: A set of one or more arbitrary metadata key and value pairs.
    extra = resource.Body("extra")
    #: Fault type that caused the node to enter maintenance mode.
    #: Introduced in API microversion 1.42.
    fault = resource.Body("fault")
    #: The UUID of the node resource.
    id = resource.Body("uuid", alternate_id=True)
    #: Information used to customize the deployed image, e.g. size of root
    #: partition, config drive in the form of base64 encoded string and other
    #: metadata.
    instance_info = resource.Body("instance_info")
    #: UUID of the nova instance associated with this node.
    instance_id = resource.Body("instance_uuid")
    #: Override enabling of automated cleaning. Added in API microversion 1.47.
    is_automated_clean_enabled = resource.Body("automated_clean", type=bool)
    #: Whether console access is enabled on this node.
    is_console_enabled = resource.Body("console_enabled", type=bool)
    #: Whether node is currently in "maintenance mode". Nodes put into
    #: maintenance mode are removed from the available resource pool.
    is_maintenance = resource.Body("maintenance", type=bool)
    # Whether the node is protected from undeploying. Added in API microversion
    # 1.48.
    is_protected = resource.Body("protected", type=bool)
    #: Whether the node is marked for retirement. Added in API microversion
    #: 1.61.
    is_retired = resource.Body("retired", type=bool)
    #: Whether the node is currently booted with secure boot turned on.
    #: Added in API microversion 1.75.
    is_secure_boot = resource.Body("secure_boot", type=bool)
    #: Any error from the most recent transaction that started but failed to
    #: finish.
    last_error = resource.Body("last_error")
    #: Field indicating if the node is leased to a specific project.
    #: Added in API version 1.65
    lessee = resource.Body("lessee")
    #: A list of relative links, including self and bookmark links.
    links = resource.Body("links", type=list)
    #: user settable description of the reason why the node was placed into
    #: maintenance mode.
    maintenance_reason = resource.Body("maintenance_reason")
    #: Human readable identifier for the node. May be undefined. Certain words
    #: are reserved. Added in API microversion 1.5
    name = resource.Body("name")
    #: The node which serves as the parent_node for this node.
    #: Added in API version 1.83
    parent_node = resource.Body("parent_node")
    #: Links to the collection of ports on this node.
    ports = resource.Body("ports", type=list)
    #: Links to the collection of portgroups on this node. Available since
    #: API microversion 1.24.
    port_groups = resource.Body("portgroups", type=list)
    #: The current power state. Usually "power on" or "power off", but may be
    #: "None" if service is unable to determine the power state.
    power_state = resource.Body("power_state")
    #: Physical characteristics of the node. Content populated by the service
    #: during inspection.
    properties = resource.Body("properties", type=dict)
    # The reason why this node is protected. Added in API microversion 1.48.
    protected_reason = resource.Body("protected_reason")
    #: The current provisioning state of the node.
    provision_state = resource.Body("provision_state")
    #: The reason why the node is marked for retirement. Added in API
    #: microversion 1.61.
    retired_reason = resource.Body("retired_reason")
    #: The current RAID configuration of the node.
    raid_config = resource.Body("raid_config")
    #: The name of an service conductor host which is holding a lock on this
    #: node, if a lock is held.
    reservation = resource.Body("reservation")
    #: A string to be used by external schedulers to identify this node as a
    #: unit of a specific type of resource. Added in API microversion 1.21.
    resource_class = resource.Body("resource_class")
    #: A string representing the current service step being executed upon.
    #: Added in API microversion 1.87.
    service_step = resource.Body("service_step")
    #: A string representing the uuid or logical name of a runbook as an
    #: alternative to providing ``clean_steps`` or ``service_steps``.
    #: Added in API microversion 1.92.
    runbook = resource.Body("runbook")
    #: A string indicating the shard this node belongs to. Added in API
    #: microversion 1,82.
    shard = resource.Body("shard")
    #: Links to the collection of states.
    states = resource.Body("states", type=list)
    #: The requested state if a provisioning action has been requested. For
    #: example, ``AVAILABLE``, ``DEPLOYING``, ``DEPLOYWAIT``, ``DEPLOYING``,
    #: ``ACTIVE`` etc.
    target_provision_state = resource.Body("target_provision_state")
    #: The requested state during a state transition.
    target_power_state = resource.Body("target_power_state")
    #: The requested RAID configuration of the node which will be applied when
    #: the node next transitions through the CLEANING state.
    target_raid_config = resource.Body("target_raid_config")
    #: Traits of the node. Introduced in API microversion 1.37.
    traits = resource.Body("traits", type=list)
    #: Timestamp at which the node was last updated.
    updated_at = resource.Body("updated_at")

    # Hardware interfaces grouped together for convenience.

    #: BIOS interface to use when setting BIOS properties of the node.
    #: Introduced in API microversion 1.40.
    bios_interface = resource.Body("bios_interface")
    #: Boot interface to use when configuring boot of the node.
    #: Introduced in API microversion 1.31.
    boot_interface = resource.Body("boot_interface")
    #: Console interface to use when working with serial console.
    #: Introduced in API microversion 1.31.
    console_interface = resource.Body("console_interface")
    #: Deploy interface to use when deploying the node.
    #: Introduced in API microversion 1.31.
    deploy_interface = resource.Body("deploy_interface")
    #: Firmware interface to be used when managing the node.
    #: Introduced in API microversion 1.86
    firmware_interface = resource.Body("firmware_interface")
    #: Inspect interface to use when inspecting the node.
    #: Introduced in API microversion 1.31.
    inspect_interface = resource.Body("inspect_interface")
    #: Management interface to use for management actions on the node.
    #: Introduced in API microversion 1.31.
    management_interface = resource.Body("management_interface")
    #: Network interface provider to use when plumbing the network connections
    #: for this node. Introduced in API microversion 1.20.
    network_interface = resource.Body("network_interface")
    #: Power interface to use for power actions on the node.
    #: Introduced in API microversion 1.31.
    power_interface = resource.Body("power_interface")
    #: RAID interface to use for configuring RAID on the node.
    #: Introduced in API microversion 1.31.
    raid_interface = resource.Body("raid_interface")
    #: Rescue interface to use for rescuing of the node.
    #: Introduced in API microversion 1.38.
    rescue_interface = resource.Body("rescue_interface")
    #: Storage interface to use when attaching remote storage.
    #: Introduced in API microversion 1.33.
    storage_interface = resource.Body("storage_interface")
    #: Vendor interface to use for vendor-specific actions on the node.
    #: Introduced in API microversion 1.31.
    vendor_interface = resource.Body("vendor_interface")

    def _consume_body_attrs(self, attrs):
        if 'provision_state' in attrs and attrs['provision_state'] is None:
            # API version 1.1 uses None instead of "available". Make it
            # consistent.
            attrs['provision_state'] = 'available'
        return super()._consume_body_attrs(attrs)

    def create(self, session, *args, **kwargs):
        """Create a remote resource based on this instance.

        The overridden version is capable of handling the populated
        ``provision_state`` field of one of three values: ``enroll``,
        ``manageable`` or ``available``. If not provided, the server default
        is used (``enroll`` in newer versions of Ironic).

        This call does not cause a node to go through automated cleaning.
        If you need it, use ``provision_state=manageable`` followed by
        a call to :meth:`set_provision_state`.

        Note that Bare Metal API 1.4 is required for ``manageable`` and
        1.11 is required for ``enroll``.

        .. warning::
            Using ``provision_state=available`` is only possible with API
            versions 1.1 to 1.10 and thus is incompatible with setting any
            fields that appeared after 1.11.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`

        :return: This :class:`Resource` instance.
        :raises: ValueError if the Node's ``provision_state`` is not one of
            ``None``, ``enroll``, ``manageable`` or ``available``.
        :raises: :exc:`~openstack.exceptions.NotSupported` if
            the ``provision_state`` cannot be reached with any API version
            supported by the server.
        """
        expected_provision_state = self.provision_state

        session = self._get_session(session)
        if expected_provision_state is not None:
            # Verify that the requested provision state is reachable with
            # the API version we are going to use.
            try:
                microversion = _common.STATE_VERSIONS[expected_provision_state]
            except KeyError:
                raise ValueError(
                    "Node's provision_state must be one of {} for creation, "
                    "got {}".format(
                        ', '.join(_common.STATE_VERSIONS),
                        expected_provision_state,
                    )
                )
            else:
                error_message = (
                    "Cannot create a node with initial provision "
                    f"state {expected_provision_state}"
                )
                # Nodes cannot be created as available using new API versions
                maximum = (
                    '1.10' if expected_provision_state == 'available' else None
                )
                microversion = self._assert_microversion_for(
                    session,
                    'create',
                    microversion,
                    maximum=maximum,
                    error_message=error_message,
                )
        else:
            microversion = None  # use the base negotiation

        # Ironic cannot set provision_state itself, so marking it as unchanged
        self._clean_body_attrs({'provision_state'})

        super().create(session, *args, microversion=microversion, **kwargs)

        if (
            expected_provision_state == 'manageable'
            and self.provision_state != 'manageable'
        ):
            # Manageable is not reachable directly
            self.set_provision_state(session, 'manage', wait=True)

        return self

    def commit(self, session, *args, **kwargs):
        """Commit the state of the instance to the remote resource.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`

        :return: This :class:`Node` instance.
        """
        # These fields have to be set through separate API.
        if (
            'maintenance_reason' in self._body.dirty
            or 'maintenance' in self._body.dirty
        ):
            if not self.is_maintenance and self.maintenance_reason:
                if 'maintenance' in self._body.dirty:
                    self.maintenance_reason = None
                else:
                    raise ValueError(
                        'Maintenance reason cannot be set when '
                        'maintenance is False'
                    )
            if self.is_maintenance:
                self._do_maintenance_action(
                    session, 'put', {'reason': self.maintenance_reason}
                )
            else:
                # This corresponds to setting maintenance=False and
                # maintenance_reason=None in the same request.
                self._do_maintenance_action(session, 'delete')

            self._clean_body_attrs({'maintenance', 'maintenance_reason'})
            if not self.requires_commit:
                # Other fields are not updated, re-fetch the node to reflect
                # the new status.
                return self.fetch(session)

        return super().commit(session, *args, **kwargs)

    def set_provision_state(
        self,
        session,
        target,
        config_drive=None,
        clean_steps=None,
        rescue_password=None,
        wait=False,
        timeout=None,
        deploy_steps=None,
        service_steps=None,
        runbook=None,
    ):
        """Run an action modifying this node's provision state.

        This call is asynchronous, it will return success as soon as the Bare
        Metal service acknowledges the request.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param target: Provisioning action, e.g. ``active``, ``provide``.
            See the Bare Metal service documentation for available actions.
        :param config_drive: Config drive to pass to the node, only valid
            for ``active` and ``rebuild`` targets. You can use functions from
            :mod:`openstack.baremetal.configdrive` to build it.
        :param clean_steps: Clean steps to execute, only valid for ``clean``
            target.
        :param rescue_password: Password for the rescue operation, only valid
            for ``rescue`` target.
        :param wait: Whether to wait for the target state to be reached.
        :param timeout: Timeout (in seconds) to wait for the target state to be
            reached. If ``None``, wait without timeout.
        :param deploy_steps: Deploy steps to execute, only valid for ``active``
            and ``rebuild`` target.
        :param service_steps: Service steps to execute, only valid for
            ``service`` target.
        :param ``runbook``: UUID or logical name of a runbook.

        :return: This :class:`Node` instance.
        :raises: ValueError if ``config_drive``, ``clean_steps``,
            ``deploy_steps`` or ``rescue_password`` are provided with an
            invalid ``target``.
        :raises: :class:`~openstack.exceptions.ResourceFailure` if the node
            reaches an error state while waiting for the state.
        :raises: :class:`~openstack.exceptions.ResourceTimeout` if timeout
            is reached while waiting for the state.
        """
        session = self._get_session(session)

        version = None
        if target in _common.PROVISIONING_VERSIONS:
            version = f'1.{_common.PROVISIONING_VERSIONS[target]}'

        if config_drive:
            # Some config drive actions require a higher version.
            if isinstance(config_drive, dict):
                version = _common.CONFIG_DRIVE_DICT_VERSION
            elif target == 'rebuild':
                version = _common.CONFIG_DRIVE_REBUILD_VERSION

        if deploy_steps:
            version = _common.DEPLOY_STEPS_VERSION

        version = self._assert_microversion_for(session, 'commit', version)

        body = {'target': target}
        if runbook:
            version = self._assert_microversion_for(
                session, 'commit', _common.RUNBOOKS_VERSION
            )

            if clean_steps is not None:
                raise ValueError(
                    'Please provide either clean steps or a '
                    'runbook, but not both.'
                )
            if service_steps is not None:
                raise ValueError(
                    'Please provide either service steps or a '
                    'runbook, but not both.'
                )

            if target != 'clean' and target != 'service':
                msg = (
                    'A runbook can only be provided when setting target '
                    'provision state to any of "[clean, service]"'
                )
                raise ValueError(msg)

            body['runbook'] = runbook

        if config_drive:
            if target not in ('active', 'rebuild'):
                raise ValueError(
                    'Config drive can only be provided with '
                    '"active" and "rebuild" targets'
                )
            if isinstance(config_drive, bytes):
                try:
                    config_drive = config_drive.decode('utf-8')
                except UnicodeError:
                    raise ValueError(
                        'Config drive must be a dictionary or a base64 '
                        'encoded string'
                    )
            # Not a typo - ironic accepts "configdrive" (without underscore)
            body['configdrive'] = config_drive

        if clean_steps is not None:
            if target != 'clean':
                raise ValueError(
                    'Clean steps can only be provided with "clean" target'
                )
            body['clean_steps'] = clean_steps

        if deploy_steps is not None:
            if target not in ('active', 'rebuild'):
                raise ValueError(
                    'Deploy steps can only be provided with '
                    '"deploy" and "rebuild" target'
                )
            body['deploy_steps'] = deploy_steps

        if service_steps is not None:
            if target != 'service':
                raise ValueError(
                    'Service steps can only be provided with "service" target'
                )
            body['service_steps'] = service_steps

        if rescue_password is not None:
            if target != 'rescue':
                raise ValueError(
                    'Rescue password can only be provided with "rescue" target'
                )
            body['rescue_password'] = rescue_password

        if wait:
            try:
                expected_state = _common.EXPECTED_STATES[target]
            except KeyError:
                raise ValueError(
                    f'For target {target} the expected state is not '
                    'known, cannot wait for it'
                )

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'provision')
        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = (
            f"Failed to set provision state for bare metal node {self.id} "
            f"to {target}"
        )
        exceptions.raise_from_response(response, error_message=msg)

        if wait:
            return self.wait_for_provision_state(
                session, expected_state, timeout=timeout
            )
        else:
            return self.fetch(session)

    def wait_for_power_state(self, session, expected_state, timeout=None):
        """Wait for the node to reach the expected power state.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param expected_state: The expected power state to reach.
        :param timeout: If ``wait`` is set to ``True``, specifies how much (in
            seconds) to wait for the expected state to be reached. The value of
            ``None`` (the default) means no client-side timeout.

        :return: This :class:`Node` instance.
        :raises: :class:`~openstack.exceptions.ResourceTimeout` on timeout.
        """
        for count in utils.iterate_timeout(
            timeout,
            f"Timeout waiting for node {self.id} to reach "
            f"power state '{expected_state}'",
        ):
            self.fetch(session)
            if self.power_state == expected_state:
                return self

            session.log.debug(
                'Still waiting for node %(node)s to reach power state '
                '"%(target)s", the current state is "%(state)s"',
                {
                    'node': self.id,
                    'target': expected_state,
                    'state': self.power_state,
                },
            )

    def wait_for_provision_state(
        self, session, expected_state, timeout=None, abort_on_failed_state=True
    ):
        """Wait for the node to reach the expected state.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param expected_state: The expected provisioning state to reach.
        :param timeout: If ``wait`` is set to ``True``, specifies how much (in
            seconds) to wait for the expected state to be reached. The value of
            ``None`` (the default) means no client-side timeout.
        :param abort_on_failed_state: If ``True`` (the default), abort waiting
            if the node reaches a failure state which does not match the
            expected one. Note that the failure state for ``enroll`` ->
            ``manageable`` transition is ``enroll`` again.

        :return: This :class:`Node` instance.
        :raises: :class:`~openstack.exceptions.ResourceFailure` if the node
            reaches an error state and ``abort_on_failed_state`` is ``True``.
        :raises: :class:`~openstack.exceptions.ResourceTimeout` on timeout.
        """
        for count in utils.iterate_timeout(
            timeout,
            f"Timeout waiting for node {self.id} to reach "
            f"target state '{expected_state}'",
        ):
            self.fetch(session)
            if self._check_state_reached(
                session, expected_state, abort_on_failed_state
            ):
                return self

            session.log.debug(
                'Still waiting for node %(node)s to reach state '
                '"%(target)s", the current state is "%(state)s"',
                {
                    'node': self.id,
                    'target': expected_state,
                    'state': self.provision_state,
                },
            )

    def wait_for_reservation(self, session, timeout=None):
        """Wait for a lock on the node to be released.

        Bare metal nodes in ironic have a reservation lock that
        is used to represent that a conductor has locked the node
        while performing some sort of action, such as changing
        configuration as a result of a machine state change.

        This lock can occur during power syncronization, and prevents
        updates to objects attached to the node, such as ports.

        Note that nothing prevents a conductor from acquiring the lock again
        after this call returns, so it should be treated as best effort.

        Returns immediately if there is no reservation on the node.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param timeout: How much (in seconds) to wait for the lock to be
            released. The value of ``None`` (the default) means no timeout.

        :return: This :class:`Node` instance.
        """
        if self.reservation is None:
            return self

        for count in utils.iterate_timeout(
            timeout,
            f"Timeout waiting for the lock to be released on node {self.id}",
        ):
            self.fetch(session)
            if self.reservation is None:
                return self

            session.log.debug(
                'Still waiting for the lock to be released on node '
                '%(node)s, currently locked by conductor %(host)s',
                {'node': self.id, 'host': self.reservation},
            )

    def _check_state_reached(
        self, session, expected_state, abort_on_failed_state=True
    ):
        """Wait for the node to reach the expected state.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param expected_state: The expected provisioning state to reach.
        :param abort_on_failed_state: If ``True`` (the default), abort waiting
            if the node reaches a failure state which does not match the
            expected one. Note that the failure state for ``enroll`` ->
            ``manageable`` transition is ``enroll`` again.

        :return: ``True`` if the target state is reached
        :raises: :class:`~openstack.exceptions.ResourceFailure` if the node
            reaches an error state and ``abort_on_failed_state`` is ``True``.
        """
        # NOTE(dtantsur): microversion 1.2 changed None to available
        if self.provision_state == expected_state or (
            expected_state == 'available' and self.provision_state is None
        ):
            return True
        elif not abort_on_failed_state:
            return False

        if (
            self.provision_state.endswith(' failed')
            or self.provision_state == 'error'
        ):
            raise exceptions.ResourceFailure(
                f"Node {self.id} reached failure state \"{self.provision_state}\"; "
                f"the last error is {self.last_error}"
            )
        # Special case: a failure state for "manage" transition can be
        # "enroll"
        elif (
            expected_state == 'manageable'
            and self.provision_state == 'enroll'
            and self.last_error
        ):
            raise exceptions.ResourceFailure(
                f"Node {self.id} could not reach state manageable: "
                "failed to verify management credentials; "
                f"the last error is {self.last_error}"
            )

    def inject_nmi(self, session):
        """Inject NMI.

        :param session: The session to use for making this request.
        :return: None
        """
        session = self._get_session(session)
        version = self._assert_microversion_for(
            session,
            'commit',
            _common.INJECT_NMI_VERSION,
        )
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'management', 'inject_nmi')

        response = session.put(
            request.url,
            json={},
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to inject NMI to node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def set_power_state(self, session, target, wait=False, timeout=None):
        """Run an action modifying this node's power state.

        This call is asynchronous, it will return success as soon as the Bare
        Metal service acknowledges the request.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param target: Target power state, as a :class:`PowerAction` or
            a string.
        :param wait: Whether to wait for the expected power state to be
            reached.
        :param timeout: Timeout (in seconds) to wait for the target state to be
            reached. If ``None``, wait without timeout.
        """
        if isinstance(target, PowerAction):
            target = target.value
        if wait:
            try:
                expected = _common.EXPECTED_POWER_STATES[target]
            except KeyError:
                raise ValueError(
                    f"Cannot use target power state {target} with wait, "
                    "the expected state is not known"
                )

        session = self._get_session(session)

        if target.startswith("soft "):
            version = '1.27'
        else:
            version = None

        version = self._assert_microversion_for(session, 'commit', version)

        # TODO(dtantsur): server timeout support
        body = {'target': target}

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'power')
        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = (
            f"Failed to set power state for bare metal node {self.id} "
            f"to {target}"
        )
        exceptions.raise_from_response(response, error_message=msg)

        if wait:
            self.wait_for_power_state(session, expected, timeout=timeout)

    def attach_vif(
        self,
        session: adapter.Adapter,
        vif_id: str,
        retry_on_conflict: bool = True,
        *,
        port_id: ty.Optional[str] = None,
        port_group_id: ty.Optional[str] = None,
    ) -> None:
        """Attach a VIF to the node.

        The exact form of the VIF ID depends on the network interface used by
        the node. In the most common case it is a Network service port
        (NOT a Bare Metal port) ID. A VIF can only be attached to one node
        at a time.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param vif_id: Backend-specific VIF ID.
        :param retry_on_conflict: Whether to retry HTTP CONFLICT errors.
            This can happen when either the VIF is already used on a node or
            the node is locked. Since the latter happens more often, the
            default value is True.
        :param port_id: The UUID of the port to attach the VIF to. Only one of
            port_id or port_group_id can be provided.
        :param port_group_id: The UUID of the portgroup to attach to. Only one
            of port_group_id or port_id can be provided.
        :return: None
        :raises: :exc:`~openstack.exceptions.NotSupported` if the server
            does not support the VIF API.
        :raises: :exc:`~openstack.exceptions.InvalidRequest` if both port_id
            and port_group_id are provided.
        """
        if port_id and port_group_id:
            msg = (
                'Only one of vif_port_id and vif_portgroup_id can be provided'
            )
            raise exceptions.InvalidRequest(msg)

        session = self._get_session(session)
        if port_id or port_group_id:
            required_version = _common.VIF_OPTIONAL_PARAMS_VERSION
        else:
            required_version = _common.VIF_VERSION
        version = self._assert_microversion_for(
            session,
            'commit',
            required_version,
            error_message=("Cannot use VIF attachment API"),
        )

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'vifs')
        body = {'id': vif_id}
        if port_id:
            body['port_uuid'] = port_id
        elif port_group_id:
            body['portgroup_uuid'] = port_group_id
        retriable_status_codes = _common.RETRIABLE_STATUS_CODES
        if not retry_on_conflict:
            retriable_status_codes = list(set(retriable_status_codes) - {409})
        response = session.post(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=retriable_status_codes,
        )

        msg = f"Failed to attach VIF {vif_id} to bare metal node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def detach_vif(self, session, vif_id, ignore_missing=True):
        """Detach a VIF from the node.

        The exact form of the VIF ID depends on the network interface used by
        the node. In the most common case it is a Network service port
        (NOT a Bare Metal port) ID.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param string vif_id: Backend-specific VIF ID.
        :param bool ignore_missing: When set to ``False``
                    :class:`~openstack.exceptions.NotFoundException` will be
                    raised when the VIF does not exist. Otherwise, ``False``
                    is returned.
        :return: ``True`` if the VIF was detached, otherwise ``False``.
        :raises: :exc:`~openstack.exceptions.NotSupported` if the server
            does not support the VIF API.
        """
        session = self._get_session(session)
        version = self._assert_microversion_for(
            session,
            'commit',
            _common.VIF_VERSION,
            error_message=("Cannot use VIF attachment API"),
        )

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'vifs', vif_id)
        response = session.delete(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        if ignore_missing and response.status_code == 400:
            session.log.debug(
                'VIF %(vif)s was already removed from node %(node)s',
                {'vif': vif_id, 'node': self.id},
            )
            return False

        msg = f"Failed to detach VIF {vif_id} from bare metal node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)
        return True

    def list_vifs(self, session):
        """List IDs of VIFs attached to the node.

        The exact form of the VIF ID depends on the network interface used by
        the node. In the most common case it is a Network service port
        (NOT a Bare Metal port) ID.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :return: List of VIF IDs as strings.
        :raises: :exc:`~openstack.exceptions.NotSupported` if the server
            does not support the VIF API.
        """
        session = self._get_session(session)
        version = self._assert_microversion_for(
            session,
            'fetch',
            _common.VIF_VERSION,
            error_message=("Cannot use VIF attachment API"),
        )

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'vifs')
        response = session.get(
            request.url, headers=request.headers, microversion=version
        )

        msg = f"Failed to list VIFs attached to bare metal node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)
        return [vif['id'] for vif in response.json()['vifs']]

    def validate(self, session, required=('boot', 'deploy', 'power')):
        """Validate required information on the node.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param required: List of interfaces that are required to pass
            validation. The default value is the list of minimum required
            interfaces for provisioning.

        :return: dict mapping interface names to :class:`ValidationResult`
            objects.
        :raises: :exc:`~openstack.exceptions.ValidationException` if validation
            fails for a required interface.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'validate')
        response = session.get(
            request.url, headers=request.headers, microversion=version
        )

        msg = f"Failed to validate node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)
        result = response.json()

        if required:
            failed = [
                '{} ({})'.format(key, value.get('reason', 'no reason'))
                for key, value in result.items()
                if key in required and not value.get('result')
            ]

            if failed:
                raise exceptions.ValidationException(
                    'Validation failed for required interfaces of node '
                    '{node}: {failures}'.format(
                        node=self.id, failures=', '.join(failed)
                    )
                )

        return {
            key: ValidationResult(value.get('result'), value.get('reason'))
            for key, value in result.items()
        }

    def set_maintenance(self, session, reason=None):
        """Enable maintenance mode on the node.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :param reason: Optional reason for maintenance.
        :return: This :class:`Node` instance.
        """
        self._do_maintenance_action(session, 'put', {'reason': reason})
        return self.fetch(session)

    def unset_maintenance(self, session):
        """Disable maintenance mode on the node.

        :param session: The session to use for making this request.
        :type session: :class:`~keystoneauth1.adapter.Adapter`
        :return: This :class:`Node` instance.
        """
        self._do_maintenance_action(session, 'delete')
        return self.fetch(session)

    def _do_maintenance_action(self, session, verb, body=None):
        session = self._get_session(session)
        version = self._get_microversion(session, action='commit')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'maintenance')
        response = getattr(session, verb)(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
        )
        msg = f"Failed to change maintenance mode for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def get_boot_device(self, session):
        """Get node boot device.

        :param session: The session to use for making this request.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'management', 'boot_device')

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to get boot device for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        return response.json()

    def set_boot_device(self, session, boot_device, persistent=False):
        """Set node boot device

        :param session: The session to use for making this request.
        :param boot_device: Boot device to assign to the node.
        :param persistent: If the boot device change is maintained after node
            reboot
        :returns: ``None``
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='commit')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'management', 'boot_device')

        body = {'boot_device': boot_device, 'persistent': persistent}

        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to set boot device for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def get_supported_boot_devices(self, session):
        """Get supported boot devices for the node.

        :param session: The session to use for making this request.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(
            request.url,
            'management',
            'boot_device',
            'supported',
        )

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to get supported boot devices for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        return response.json()

    def set_boot_mode(self, session, target):
        """Make a request to change node's boot mode

        This call is asynchronous, it will return success as soon as the Bare
        Metal service acknowledges the request.

        :param session: The session to use for making this request.
        :param target: Boot mode to set for node, one of either 'uefi'/'bios'.
        :returns: ``None``
        :raises: ValueError if ``target`` is not one of 'uefi or 'bios'.
        """
        session = self._get_session(session)
        version = utils.pick_microversion(
            session, _common.CHANGE_BOOT_MODE_VERSION
        )
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'boot_mode')
        if target not in ('uefi', 'bios'):
            raise ValueError(
                f"Unrecognized boot mode {target}."
                "Boot mode should be one of 'uefi' or 'bios'."
            )
        body = {'target': target}

        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to change boot mode for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def set_secure_boot(self, session, target):
        """Make a request to change node's secure boot state

        This call is asynchronous, it will return success as soon as the Bare
        Metal service acknowledges the request.

        :param session: The session to use for making this request.
        :param bool target: Boolean indicating secure boot state to set.
            True/False corresponding to 'on'/'off' respectively.
        :returns: ``None``
        :raises: ValueError if ``target`` is not boolean.
        """
        session = self._get_session(session)
        version = utils.pick_microversion(
            session, _common.CHANGE_BOOT_MODE_VERSION
        )
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'secure_boot')
        if not isinstance(target, bool):
            raise ValueError(
                f"Invalid target {target}. It should be True or False "
                "corresponding to secure boot state 'on' or 'off'"
            )
        body = {'target': target}

        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to change secure boot state for {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def add_trait(self, session, trait):
        """Add a trait to the node.

        :param session: The session to use for making this request.
        :param trait: The trait to add to the node.
        :returns: ``None``
        """
        session = self._get_session(session)
        version = utils.pick_microversion(session, '1.37')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'traits', trait)
        response = session.put(
            request.url,
            json=None,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to add trait {trait} for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        self.traits = list(set(self.traits or ()) | {trait})

    def remove_trait(self, session, trait, ignore_missing=True):
        """Remove a trait from the node.

        :param session: The session to use for making this request.
        :param trait: The trait to remove from the node.
        :param bool ignore_missing: When set to ``False``
            :class:`~openstack.exceptions.NotFoundException` will be
            raised when the trait does not exist.
            Otherwise, ``False`` is returned.
        :returns bool: True on success removing the trait.
            False when the trait does not exist already.
        """
        session = self._get_session(session)
        version = utils.pick_microversion(session, '1.37')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'traits', trait)

        response = session.delete(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        if ignore_missing and response.status_code == 400:
            session.log.debug(
                'Trait %(trait)s was already removed from node %(node)s',
                {'trait': trait, 'node': self.id},
            )
            return False

        msg = "Failed to remove trait {trait} from bare metal node {node}"
        exceptions.raise_from_response(
            response,
            error_message=msg.format(node=self.id, trait=trait),
        )

        if self.traits:
            self.traits = list(set(self.traits) - {trait})

        return True

    def set_traits(self, session, traits):
        """Set traits for the node.

        Removes any existing traits and adds the traits passed in to this
        method.

        :param session: The session to use for making this request.
        :param traits: list of traits to add to the node.
        :returns: ``None``
        """
        session = self._get_session(session)
        version = utils.pick_microversion(session, '1.37')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'traits')

        body = {'traits': traits}

        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to set traits for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        self.traits = traits

    def call_vendor_passthru(self, session, verb, method, body=None):
        """Call a vendor passthru method.

        :param session: The session to use for making this request.
        :param verb: The HTTP verb, one of GET, SET, POST, DELETE.
        :param method: The method to call using vendor_passthru.
        :param body: The JSON body in the HTTP call.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='commit')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(
            request.url, f'vendor_passthru?method={method}'
        )

        call = getattr(session, verb.lower())
        response = call(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = (
            f"Failed to call vendor_passthru for node {self.id}, verb {verb} "
            f"and method {method}"
        )
        exceptions.raise_from_response(response, error_message=msg)

        return response

    def list_vendor_passthru(self, session):
        """List vendor passthru methods for the node.

        :param session: The session to use for making this request.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'vendor_passthru/methods')

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to list vendor_passthru methods for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        return response.json()

    def get_console(self, session):
        """Get the node console.

        :param session: The session to use for making this request.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'console')

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to get console for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        return response.json()

    def set_console_mode(self, session, enabled):
        """Set the node console mode.

        :param session: The session to use for making this request.
        :param enabled: Whether the console should be enabled or not.
        :return: ``None``
        """
        session = self._get_session(session)
        version = self._get_microversion(session, action='commit')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'states', 'console')
        if not isinstance(enabled, bool):
            raise ValueError(
                f"Invalid enabled {enabled}. It should be True or False "
                "corresponding to console enabled or disabled"
            )
        body = {'enabled': enabled}

        response = session.put(
            request.url,
            json=body,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to change console mode for {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

    def get_node_inventory(self, session, node_id):
        """Get a node's inventory.

        :param session: The session to use for making this request.
        :param node_id: **DEPRECATED** The ID of the node.
        :returns: The HTTP response.
        """
        if node_id is not None:
            warnings.warn(
                "The 'node_id' field is unnecessary and will be removed in "
                "a future release.",
                os_warnings.RemovedInSDK60Warning,
            )
        session = self._get_session(session)
        version = self._get_microversion(session, action='fetch')
        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'inventory')

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to get inventory for node {node_id}"
        exceptions.raise_from_response(response, error_message=msg)
        return response.json()

    def list_firmware(self, session):
        """List firmware components associated with the node.

        :param session: The session to use for making this request.
        :returns: The HTTP response.
        """
        session = self._get_session(session)
        version = self._assert_microversion_for(
            session,
            'fetch',
            _common.FIRMWARE_VERSION,
            error_message=("Cannot use node list firmware components API"),
        )

        request = self._prepare_request(requires_id=True)
        request.url = utils.urljoin(request.url, 'firmware')

        response = session.get(
            request.url,
            headers=request.headers,
            microversion=version,
            retriable_status_codes=_common.RETRIABLE_STATUS_CODES,
        )

        msg = f"Failed to list firmware components for node {self.id}"
        exceptions.raise_from_response(response, error_message=msg)

        return response.json()

    def patch(
        self,
        session,
        patch=None,
        prepend_key=True,
        has_body=True,
        retry_on_conflict=None,
        base_path=None,
        *,
        microversion=None,
        reset_interfaces=None,
    ):
        if reset_interfaces is not None:
            # The id cannot be dirty for an commit
            self._body._dirty.discard("id")

            # Only try to update if we actually have anything to commit.
            if not patch and not self.requires_commit:
                return self

            if not self.allow_patch:
                raise exceptions.MethodNotSupported(self, "patch")

            session = self._get_session(session)
            microversion = self._assert_microversion_for(
                session, 'commit', _common.RESET_INTERFACES_VERSION
            )
            params = [('reset_interfaces', reset_interfaces)]

            request = self._prepare_request(
                requires_id=True,
                prepend_key=prepend_key,
                base_path=base_path,
                patch=True,
                params=params,
            )

            if patch:
                request.body += self._convert_patch(patch)

            return self._commit(
                session,
                request,
                'PATCH',
                microversion,
                has_body=has_body,
                retry_on_conflict=retry_on_conflict,
            )

        else:
            return super().patch(
                session, patch=patch, retry_on_conflict=retry_on_conflict
            )


NodeDetail = Node