rs_matter/dm/clusters/

net_comm.rs

/*
 *
 *    Copyright (c) 2025-2026 Project CHIP Authors
 *
 *    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.
 */

//! This module contains the implementation of the Network Commissioning cluster and its handler.

use core::fmt::{self, Debug};
use core::future::{ready, Future};

use crate::dm::clusters::gen_comm::GenCommHandler;
use crate::dm::clusters::wifi_diag::WirelessDiag;
use crate::dm::networks::wireless::{Thread, ThreadTLV, MAX_WIRELESS_NETWORK_ID_LEN};
use crate::dm::networks::NetChangeNotif;
use crate::dm::{ArrayAttributeRead, Cluster, Dataver, InvokeContext, ReadContext, WriteContext};
use crate::error::{Error, ErrorCode};
use crate::persist::{Persist, NETWORKS_KEY};
use crate::tlv::{
    Nullable, NullableBuilder, Octets, OctetsBuilder, TLVBuilder, TLVBuilderParent, TLVWrite,
    ToTLVArrayBuilder, ToTLVBuilder,
};
use crate::utils::cell::RefCell;
use crate::utils::init::{init, Init};
use crate::utils::sync::blocking::Mutex;
use crate::utils::sync::{DynBase, Notification};
use crate::with;

pub use crate::dm::clusters::decl::network_commissioning::*;

/// Network type supported by the `NetCtl` implementations
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum NetworkType {
    Ethernet,
    Wifi,
    Thread,
}

impl NetworkType {
    /// Return an instance of the Network Commissioning cluster meta-data for the given network type.
    pub const fn cluster(&self) -> Cluster<'static> {
        match self {
            Self::Ethernet => FULL_CLUSTER
                .with_features(Feature::ETHERNET_NETWORK_INTERFACE.bits())
                .with_attrs(with!(required))
                .with_cmds(with!()),
            Self::Wifi => FULL_CLUSTER
                .with_features(Feature::WI_FI_NETWORK_INTERFACE.bits())
                .with_attrs(with!(required; AttributeId::ScanMaxTimeSeconds | AttributeId::ConnectMaxTimeSeconds | AttributeId::SupportedWiFiBands))
                .with_cmds(with!(CommandId::AddOrUpdateWiFiNetwork | CommandId::ScanNetworks | CommandId::RemoveNetwork | CommandId::ConnectNetwork | CommandId::ReorderNetwork)),
            Self::Thread => FULL_CLUSTER
                .with_features(Feature::THREAD_NETWORK_INTERFACE.bits())
                .with_attrs(with!(required; AttributeId::ScanMaxTimeSeconds | AttributeId::ConnectMaxTimeSeconds | AttributeId::ThreadVersion | AttributeId::SupportedThreadFeatures))
                .with_cmds(with!(CommandId::AddOrUpdateThreadNetwork | CommandId::ScanNetworks | CommandId::RemoveNetwork | CommandId::ConnectNetwork | CommandId::ReorderNetwork)),
        }
    }
}

/// Read one entry of the `Networks` attribute into the given builder.
///
/// `connected` is not something the `Networks` store can answer - it is the
/// network *controller* that knows which network is currently up - so it is
/// supplied by the caller (see `NetCommHandler::networks`) rather than carried
/// alongside the network ID.
fn network_read_into<P: TLVBuilderParent>(
    network_id: &[u8],
    connected: bool,
    builder: NetworkInfoStructBuilder<P>,
) -> Result<P, Error> {
    // `NetworkIdentifier` / `ClientIdentifier` are not part of
    // `NetworkInfoStruct` in the Matter 1.6.0 data model: the Wi-Fi
    // per-device-credentials surface moved to the separate
    // `NetworkIdentityManagement` cluster. They exist again in the 1.6.1
    // IDL, so the two lines below are kept, commented, to be restored
    // together with `CSA_STANDARD_CLUSTERS_IDL_V1_6_1_0`.
    builder
        .network_id(Octets::new(network_id))?
        .connected(connected)?
        // .network_identifier(None)?
        // .client_identifier(None)?
        .end()
}

/// Network scan information as returned by the `NetCtl::scan` method
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum NetworkScanInfo<'a> {
    /// WiFi network scan information when the network type is `NetworkType::Wifi`
    Wifi {
        security: WiFiSecurityBitmap,
        ssid: &'a [u8],
        bssid: &'a [u8],
        channel: u16,
        band: WiFiBandEnum,
        rssi: i8,
    },
    /// Thread network scan information when the network type is `NetworkType::Thread`
    Thread {
        pan_id: u16,
        ext_pan_id: u64,
        network_name: &'a str,
        channel: u16,
        version: u8,
        ext_addr: &'a [u8],
        rssi: i8,
        lqi: u8,
    },
}

impl NetworkScanInfo<'_> {
    /// Read the network scan information into the given `NetworkScanInfoStructBuilder`.
    /// If the network type is not `NetworkType::Wifi`, this method will panic.
    pub fn wifi_read_into<P: TLVBuilderParent>(
        &self,
        builder: WiFiInterfaceScanResultStructBuilder<P>,
    ) -> Result<P, Error> {
        let NetworkScanInfo::Wifi {
            security,
            ssid,
            bssid,
            channel,
            band,
            rssi,
        } = self
        else {
            panic!("Wifi scan info expected");
        };

        builder
            .security(*security)?
            .ssid(Octets::new(ssid))?
            .bssid(Octets::new(bssid))?
            .channel(*channel)?
            .wi_fi_band(*band)?
            .rssi(*rssi)?
            .end()
    }

    /// Read the network scan information into the given `ThreadInterfaceScanResultStructBuilder`.
    /// If the network type is not `NetworkType::Thread`, this method will panic.
    pub fn thread_read_into<P: TLVBuilderParent>(
        &self,
        builder: ThreadInterfaceScanResultStructBuilder<P>,
    ) -> Result<P, Error> {
        let NetworkScanInfo::Thread {
            pan_id,
            ext_pan_id: extended_pan_id,
            network_name,
            channel,
            version,
            ext_addr,
            rssi,
            lqi,
        } = self
        else {
            panic!("Thread scan info expected");
        };

        builder
            .pan_id(*pan_id)?
            .extended_pan_id(*extended_pan_id)?
            .network_name(network_name)?
            .channel(*channel)?
            .version(*version)?
            .extended_address(Octets::new(ext_addr))?
            .rssi(*rssi)?
            .lqi(*lqi)?
            .end()
    }
}

/// Wireless credentials used for connecting to a network
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum WirelessCreds<'a> {
    /// WiFi credentials
    Wifi { ssid: &'a [u8], pass: &'a [u8] },
    /// Thread credentials
    Thread { dataset_tlv: &'a [u8] },
}

impl WirelessCreds<'_> {
    /// Return the network ID of the credentials
    /// For Wifi networks, this is the SSID
    /// For Thread networks, this is the extended PAN ID
    pub fn id(&self) -> Result<&[u8], Error> {
        match self {
            WirelessCreds::Wifi { ssid, .. } => Ok(ssid),
            WirelessCreds::Thread { dataset_tlv } => Thread::dataset_ext_pan_id(dataset_tlv),
        }
    }

    /// Check if the credentials match the given network type
    pub fn check_match(&self, net_type: NetworkType) -> Result<(), Error> {
        match self {
            WirelessCreds::Wifi { .. } if matches!(net_type, NetworkType::Wifi) => Ok(()),
            WirelessCreds::Thread { .. } if matches!(net_type, NetworkType::Thread) => Ok(()),
            _ => Err(ErrorCode::InvalidAction.into()),
        }
    }
}

impl fmt::Display for WirelessCreds<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            WirelessCreds::Wifi { ssid, .. } => write!(
                f,
                "SSID({})",
                core::str::from_utf8(ssid).ok().unwrap_or("???")
            ),
            WirelessCreds::Thread { dataset_tlv } => write!(
                f,
                "ExtEpanId({:?})",
                ThreadTLV::new(dataset_tlv).ext_pan_id().ok().unwrap_or(&[])
            ),
        }
    }
}

#[cfg(feature = "defmt")]
impl defmt::Format for WirelessCreds<'_> {
    fn format(&self, fmt: defmt::Formatter) {
        match self {
            WirelessCreds::Wifi { ssid, .. } => defmt::write!(
                fmt,
                "SSID({})",
                core::str::from_utf8(ssid).ok().unwrap_or("???")
            ),
            WirelessCreds::Thread { dataset_tlv } => defmt::write!(
                fmt,
                "ExtEpanId({:?})",
                ThreadTLV::new(dataset_tlv).ext_pan_id().ok().unwrap_or(&[])
            ),
        }
    }
}

/// Network error type for the `Networks` trait
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum NetworksError {
    NetworkIdNotFound,
    DuplicateNetworkId,
    OutOfRange,
    BoundsExceeded,
    Other(Error),
}

impl From<Error> for NetworksError {
    fn from(err: Error) -> Self {
        NetworksError::Other(err)
    }
}

/// Network error type for the `NetCtl` trait
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum NetCtlError {
    NetworkNotFound,
    UnsupportedSecurity,
    AuthFailure,
    OtherConnectionFailure,
    IpBindFailed,
    IpV6Failed,
    Other(Error),
}

impl From<Error> for NetCtlError {
    fn from(err: Error) -> Self {
        NetCtlError::Other(err)
    }
}

impl NetworkCommissioningStatusEnum {
    /// Map the result of a network storage operation to a `NetworkCommissioningStatusEnum` if the operation
    /// failed, or return the index of the network if it succeeded.
    pub fn map<T>(
        result: Result<T, NetworksError>,
    ) -> Result<(NetworkCommissioningStatusEnum, Option<i32>, Option<T>), Error> {
        if let Some((status, err_code)) = NetworkCommissioningStatusEnum::map_status(&result) {
            Ok((status, err_code, result.ok()))
        } else {
            match result {
                Err(NetworksError::Other(e)) => Err(e),
                _ => unreachable!(),
            }
        }
    }

    /// Map the result of a network storage operation to a `NetworkCommissioningStatusEnum` and error code  if the operation
    /// failed, or return the index of the network if it succeeded.
    pub fn map_status<T>(
        result: &Result<T, NetworksError>,
    ) -> Option<(NetworkCommissioningStatusEnum, Option<i32>)> {
        match result {
            Ok(_) => Some((NetworkCommissioningStatusEnum::Success, None)),
            Err(NetworksError::NetworkIdNotFound) => {
                Some((NetworkCommissioningStatusEnum::NetworkIDNotFound, None))
            }
            Err(NetworksError::DuplicateNetworkId) => {
                Some((NetworkCommissioningStatusEnum::DuplicateNetworkID, None))
            }
            Err(NetworksError::OutOfRange) => {
                Some((NetworkCommissioningStatusEnum::OutOfRange, None))
            }
            Err(NetworksError::BoundsExceeded) => {
                Some((NetworkCommissioningStatusEnum::BoundsExceeded, None))
            }
            Err(NetworksError::Other(_)) => None,
        }
    }

    /// Map the result of a network IO operation to a `NetworkCommissioningStatusEnum` if the operation
    /// failed, or return the index of the network if it succeeded.
    pub fn map_ctl<T>(
        result: Result<T, NetCtlError>,
    ) -> Result<(NetworkCommissioningStatusEnum, Option<i32>, Option<T>), Error> {
        if let Some((status, err_code)) = NetworkCommissioningStatusEnum::map_ctl_status(&result) {
            Ok((status, err_code, result.ok()))
        } else {
            match result {
                Err(NetCtlError::Other(e)) => Err(e),
                _ => unreachable!(),
            }
        }
    }

    /// Map the result of a network IO operation to a `NetworkCommissioningStatusEnum` and error code  if the operation
    /// failed, or return the index of the network if it succeeded.
    pub fn map_ctl_status<T>(
        result: &Result<T, NetCtlError>,
    ) -> Option<(NetworkCommissioningStatusEnum, Option<i32>)> {
        match result {
            Ok(_) => Some((NetworkCommissioningStatusEnum::Success, None)),
            Err(NetCtlError::UnsupportedSecurity) => {
                Some((NetworkCommissioningStatusEnum::UnsupportedSecurity, None))
            }
            Err(NetCtlError::AuthFailure) => {
                Some((NetworkCommissioningStatusEnum::AuthFailure, None))
            }
            Err(NetCtlError::IpBindFailed) => {
                Some((NetworkCommissioningStatusEnum::IPBindFailed, None))
            }
            Err(NetCtlError::IpV6Failed) => {
                Some((NetworkCommissioningStatusEnum::IPV6Failed, None))
            }
            Err(NetCtlError::OtherConnectionFailure) => {
                Some((NetworkCommissioningStatusEnum::OtherConnectionFailure, None))
            }
            Err(NetCtlError::NetworkNotFound) => {
                Some((NetworkCommissioningStatusEnum::NetworkNotFound, None))
            }
            Err(NetCtlError::Other(_)) => None,
        }
    }

    /// Read the networking status and the provided optional index into the given `NetworkConfigResponseBuilder`.
    pub fn read_into<P: TLVBuilderParent>(
        &self,
        index: Option<u8>,
        builder: NetworkConfigResponseBuilder<P>,
    ) -> Result<P, Error> {
        // As with `NetworkInfoStruct`, `ClientIdentity` / `PossessionSignature`
        // left `NetworkConfigResponse` in the 1.6.0 data model. Kept commented
        // for the eventual move back to 1.6.1.
        builder
            .networking_status(*self)?
            .debug_text(None)?
            .network_index(index)?
            // .client_identity(None)?
            // .possession_signature(None)?
            .end()
    }
}

/// Trait for managing networks' credentials storage
pub trait Networks {
    /// Return the maximum number of networks supported by the implementation
    ///
    /// For `NetworkType::Ethernet` this method should always return 1
    fn max_networks(&self) -> Result<u8, Error>;

    /// Iterate over the networks recorded in the implementation and call the provided function for each network
    fn networks(&self, f: &mut dyn FnMut(&[u8]) -> Result<(), Error>) -> Result<(), Error>;

    /// Get the credentials for the given network ID by calling the provided function
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    ///
    /// The function will be called with the credentials for the network ID, or an error if the network ID is not found.
    ///
    /// Return the index of the network ID if found, or an error if not found.
    fn creds(
        &self,
        network_id: &[u8],
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<u8, NetworksError>;

    /// Return the next credentials after the ones corresponding to the given network ID by calling the provided function
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    ///
    /// If the network ID is `None` or credentials with the provided network ID cannot be found,
    /// the first credentials will be returned.
    ///
    /// If the credentials corresponding to the network ID are the last ones recorded in the `Netwrks` trait implementation,
    /// the method will wrap-over and will return the first credentials or even the same credentials again if there is only one
    /// recorded network.
    ///
    /// Return `true` if the credentials were found, `false` otherwise.
    fn next_creds(
        &self,
        last_network_id: Option<&[u8]>,
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<bool, Error>;

    /// Return whether the network interface is enabled
    fn enabled(&self) -> Result<bool, Error>;

    /// Set the network interface enabled or disabled
    fn set_enabled(&mut self, enabled: bool) -> Result<(), Error>;

    /// Add or update the credentials for the given network ID
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    ///
    /// The network ID is derived from the credentials.
    ///
    /// Return the index of the network ID if it was added or updated, or an error if the operation failed.
    fn add_or_update(&mut self, creds: &WirelessCreds<'_>) -> Result<u8, NetworksError>;

    /// Reorder the network with the given index
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    ///
    /// The index is the new index of the network ID.
    ///
    /// Return the index of the network ID if it was reordered, or an error if the operation failed.
    fn reorder(&mut self, index: u8, network_id: &[u8]) -> Result<u8, NetworksError>;

    /// Remove the network with the given network ID
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    ///
    /// Return the index of the network ID if it was removed, or an error if the operation failed.
    fn remove(&mut self, network_id: &[u8]) -> Result<u8, NetworksError>;

    /// Return whether the networks store is in "managed" state.
    ///
    /// Managed means: the store holds *committed* operational network
    /// configuration, and the operational connectivity manager
    /// (`WirelessMgr`) may act on it. The store starts unmanaged (never
    /// commissioned, empty), and temporarily *becomes* unmanaged again while
    /// network changes are staged under an armed fail-safe (any successful
    /// `AddOrUpdate*Network` / `RemoveNetwork` / `ReorderNetwork` /
    /// `ConnectNetwork` flips it to `false`) - during such a window the
    /// commissioner drives connectivity explicitly, and the manager must
    /// stand down.
    ///
    /// The state comes back to managed on either exit from the window:
    /// - commit: `CommissioningComplete` calls `set_managed(true)` and
    ///   persists the store;
    /// - revert: the fail-safe expiry reloads the persisted store, which
    ///   always carries the committed - hence managed - state.
    ///
    /// Note that a window which stages no network changes (e.g. opened only
    /// to commission an additional fabric) leaves the store managed, so
    /// connectivity maintenance of the operational network continues
    /// throughout - matching CHIP's behavior.
    fn managed(&self) -> Result<bool, Error>;

    /// Set the managed state of the networks store (see `managed`).
    fn set_managed(&mut self, managed: bool) -> Result<(), Error>;

    /// Reset the networks to the initial state, removing all recorded network credentials
    fn reset(&mut self) -> Result<(), Error>;

    /// Load the networks' credentials from the given data
    fn load(&mut self, data: &[u8]) -> Result<(), Error>;

    /// Save the networks' credentials into the given buffer and return the number of bytes written
    /// or `None` if the networks do not need persistence.
    fn save(&self, buf: &mut [u8]) -> Result<Option<usize>, Error>;
}

impl<T> Networks for &mut T
where
    T: Networks,
{
    fn max_networks(&self) -> Result<u8, Error> {
        (**self).max_networks()
    }

    fn networks(&self, f: &mut dyn FnMut(&[u8]) -> Result<(), Error>) -> Result<(), Error> {
        (**self).networks(f)
    }

    fn creds(
        &self,
        network_id: &[u8],
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<u8, NetworksError> {
        (**self).creds(network_id, f)
    }

    fn next_creds(
        &self,
        last_network_id: Option<&[u8]>,
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<bool, Error> {
        (**self).next_creds(last_network_id, f)
    }

    fn enabled(&self) -> Result<bool, Error> {
        (**self).enabled()
    }

    fn set_enabled(&mut self, enabled: bool) -> Result<(), Error> {
        (*self).set_enabled(enabled)
    }

    fn add_or_update(&mut self, creds: &WirelessCreds<'_>) -> Result<u8, NetworksError> {
        (*self).add_or_update(creds)
    }

    fn reorder(&mut self, index: u8, network_id: &[u8]) -> Result<u8, NetworksError> {
        (*self).reorder(index, network_id)
    }

    fn remove(&mut self, network_id: &[u8]) -> Result<u8, NetworksError> {
        (*self).remove(network_id)
    }

    fn managed(&self) -> Result<bool, Error> {
        (**self).managed()
    }

    fn set_managed(&mut self, managed: bool) -> Result<(), Error> {
        (**self).set_managed(managed)
    }

    fn reset(&mut self) -> Result<(), Error> {
        (**self).reset()
    }

    fn load(&mut self, data: &[u8]) -> Result<(), Error> {
        (**self).load(data)
    }

    fn save(&self, buf: &mut [u8]) -> Result<Option<usize>, Error> {
        (**self).save(buf)
    }
}

impl Networks for &mut dyn Networks {
    fn max_networks(&self) -> Result<u8, Error> {
        (**self).max_networks()
    }

    fn networks(&self, f: &mut dyn FnMut(&[u8]) -> Result<(), Error>) -> Result<(), Error> {
        (**self).networks(f)
    }

    fn creds(
        &self,
        network_id: &[u8],
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<u8, NetworksError> {
        (**self).creds(network_id, f)
    }

    fn next_creds(
        &self,
        last_network_id: Option<&[u8]>,
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<bool, Error> {
        (**self).next_creds(last_network_id, f)
    }

    fn enabled(&self) -> Result<bool, Error> {
        (**self).enabled()
    }

    fn set_enabled(&mut self, enabled: bool) -> Result<(), Error> {
        (**self).set_enabled(enabled)
    }

    fn add_or_update(&mut self, creds: &WirelessCreds<'_>) -> Result<u8, NetworksError> {
        (**self).add_or_update(creds)
    }

    fn reorder(&mut self, index: u8, network_id: &[u8]) -> Result<u8, NetworksError> {
        (**self).reorder(index, network_id)
    }

    fn remove(&mut self, network_id: &[u8]) -> Result<u8, NetworksError> {
        (**self).remove(network_id)
    }

    fn managed(&self) -> Result<bool, Error> {
        (**self).managed()
    }

    fn set_managed(&mut self, managed: bool) -> Result<(), Error> {
        (**self).set_managed(managed)
    }

    fn reset(&mut self) -> Result<(), Error> {
        (**self).reset()
    }

    fn load(&mut self, data: &[u8]) -> Result<(), Error> {
        (**self).load(data)
    }

    fn save(&self, buf: &mut [u8]) -> Result<Option<usize>, Error> {
        (**self).save(buf)
    }
}

pub trait NetworksAccess {
    fn access<F: FnOnce(&mut dyn Networks) -> R, R>(&self, f: F) -> R;
}

impl<T> NetworksAccess for &T
where
    T: NetworksAccess,
{
    fn access<F: FnOnce(&mut dyn Networks) -> R, R>(&self, f: F) -> R {
        (*self).access(f)
    }
}

pub struct DummyNetworkAccess;

impl NetworksAccess for DummyNetworkAccess {
    fn access<F: FnOnce(&mut dyn Networks) -> R, R>(&self, f: F) -> R {
        f(&mut DummyNetworks)
    }
}

pub struct DummyNetworks;

impl Networks for DummyNetworks {
    fn max_networks(&self) -> Result<u8, Error> {
        Ok(0)
    }

    fn networks(&self, _f: &mut dyn FnMut(&[u8]) -> Result<(), Error>) -> Result<(), Error> {
        Ok(())
    }

    fn creds(
        &self,
        _network_id: &[u8],
        _f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<u8, NetworksError> {
        Err(NetworksError::NetworkIdNotFound)
    }

    fn next_creds(
        &self,
        _last_network_id: Option<&[u8]>,
        _f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<bool, Error> {
        Ok(false)
    }

    fn enabled(&self) -> Result<bool, Error> {
        Ok(false)
    }

    fn set_enabled(&mut self, _enabled: bool) -> Result<(), Error> {
        Ok(())
    }

    fn add_or_update(&mut self, _creds: &WirelessCreds<'_>) -> Result<u8, NetworksError> {
        Err(NetworksError::Other(ErrorCode::InvalidAction.into()))
    }

    fn reorder(&mut self, _index: u8, _network_id: &[u8]) -> Result<u8, NetworksError> {
        Err(NetworksError::Other(ErrorCode::InvalidAction.into()))
    }

    fn remove(&mut self, _network_id: &[u8]) -> Result<u8, NetworksError> {
        Err(NetworksError::Other(ErrorCode::InvalidAction.into()))
    }

    fn managed(&self) -> Result<bool, Error> {
        Ok(false)
    }

    fn set_managed(&mut self, _managed: bool) -> Result<(), Error> {
        Ok(())
    }

    fn reset(&mut self) -> Result<(), Error> {
        Ok(())
    }

    fn load(&mut self, _data: &[u8]) -> Result<(), Error> {
        Ok(())
    }

    fn save(&self, _buf: &mut [u8]) -> Result<Option<usize>, Error> {
        Ok(None)
    }
}

/// Trait for managing network connectivity
pub trait NetCtl {
    /// Return the network type of the implementation
    fn net_type(&self) -> NetworkType;

    /// Return the maximum time in seconds for connecting to a network
    ///
    /// Default implementation returns 30 seconds
    fn connect_max_time_seconds(&self) -> u8 {
        30
    }

    /// Return the maximum time in seconds for scanning for networks
    ///
    /// Default implementation returns 30 seconds
    fn scan_max_time_seconds(&self) -> u8 {
        30
    }

    /// Return the supported WiFi bands for the implementation in the provided closure
    ///
    /// Default implementation returns 2.4GHz band only
    ///
    /// NOTE: This method is only relevant when `net_type` is `NetworkType::Wifi`
    fn supported_wifi_bands<F>(&self, mut f: F) -> Result<(), Error>
    where
        F: FnMut(WiFiBandEnum) -> Result<(), Error>,
    {
        f(WiFiBandEnum::V2G4)
    }

    /// Return the supported Thread features for the implementation
    ///
    /// Default implementation returns an empty bitmap
    ///
    /// NOTE: This method is only relevant when `net_type` is `NetworkType::Thread`
    fn supported_thread_features(&self) -> ThreadCapabilitiesBitmap {
        ThreadCapabilitiesBitmap::empty()
    }

    /// Return the Thread version for the implementation
    ///
    /// Default implementation returns 4 (Thread 1.3.0)
    ///
    /// NOTE: This method is only relevant when `net_type` is `NetworkType::Thread`
    fn thread_version(&self) -> u16 {
        4
    }

    /// Scan for networks and call the provided function for each network found
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    async fn scan<F>(&self, network: Option<&[u8]>, f: F) -> Result<(), NetCtlError>
    where
        F: FnMut(&NetworkScanInfo) -> Result<(), Error>;

    /// Connect to the network with the given credentials
    ///
    /// For `NetworkType::Ethernet` this method should always fail with an error.
    async fn connect(&self, creds: &WirelessCreds) -> Result<(), NetCtlError>;
}

impl<T> NetCtl for &T
where
    T: NetCtl,
{
    fn net_type(&self) -> NetworkType {
        (*self).net_type()
    }

    fn connect_max_time_seconds(&self) -> u8 {
        (*self).connect_max_time_seconds()
    }

    fn scan_max_time_seconds(&self) -> u8 {
        (*self).scan_max_time_seconds()
    }

    fn supported_wifi_bands<F>(&self, f: F) -> Result<(), Error>
    where
        F: FnMut(WiFiBandEnum) -> Result<(), Error>,
    {
        (*self).supported_wifi_bands(f)
    }

    fn supported_thread_features(&self) -> ThreadCapabilitiesBitmap {
        (*self).supported_thread_features()
    }

    fn thread_version(&self) -> u16 {
        (*self).thread_version()
    }

    fn scan<F>(&self, network: Option<&[u8]>, f: F) -> impl Future<Output = Result<(), NetCtlError>>
    where
        F: FnMut(&NetworkScanInfo) -> Result<(), Error>,
    {
        (*self).scan(network, f)
    }

    fn connect(&self, creds: &WirelessCreds<'_>) -> impl Future<Output = Result<(), NetCtlError>> {
        (*self).connect(creds)
    }
}

/// Trait for providing the status of the last `scan` / `connect` operation
pub trait NetCtlStatus {
    /// Return the networking status of the last scan or connect operation
    ///
    /// For `NetworkType::Ethernet` this method should always return `Ok(None)`
    fn last_networking_status(&self) -> Result<Option<NetworkCommissioningStatusEnum>, Error>;

    /// Return the network ID of the last connect operation
    ///
    /// For `NetworkType::Ethernet` this method should always return `Ok(None)`
    fn last_network_id<F, R>(&self, f: F) -> Result<R, Error>
    where
        F: FnOnce(Option<&[u8]>) -> Result<R, Error>;

    /// Return the error value of the last connect operation
    ///
    /// For `NetworkType::Ethernet` this method should always return `Ok(None)`
    fn last_connect_error_value(&self) -> Result<Option<i32>, Error>;
}

impl<T> NetCtlStatus for &T
where
    T: NetCtlStatus,
{
    fn last_networking_status(&self) -> Result<Option<NetworkCommissioningStatusEnum>, Error> {
        (*self).last_networking_status()
    }

    fn last_network_id<F, R>(&self, f: F) -> Result<R, Error>
    where
        F: FnOnce(Option<&[u8]>) -> Result<R, Error>,
    {
        (*self).last_network_id(f)
    }

    fn last_connect_error_value(&self) -> Result<Option<i32>, Error> {
        (*self).last_connect_error_value()
    }
}

/// A type providing shared access to a `Networks` implementation with change notification capabilities.
pub struct SharedNetworks<N> {
    state: Mutex<RefCell<N>>,
    state_changed: Notification,
}

impl<N> SharedNetworks<N> {
    /// Create a new instance.
    pub const fn new(networks: N) -> Self {
        Self {
            state: Mutex::new(RefCell::new(networks)),
            state_changed: Notification::new(),
        }
    }

    /// Return an in-place initializer for the struct.
    pub fn init(networks: impl Init<N>) -> impl Init<Self> {
        init!(Self {
            state <- Mutex::init(RefCell::init(networks)),
            state_changed <- Notification::init(),
        })
    }

    /// Get a mutable reference to the inner `Networks` implementation.
    pub fn get_mut(&mut self) -> &mut RefCell<N> {
        self.state.get_mut()
    }

    /// Run a closure with mutable access to the raw inner `Networks`
    /// implementation, without firing a change notification.
    ///
    /// Used by the startup / factory-reset persistence paths, where nothing is
    /// subscribed to changes yet (or the notification is meaningless).
    pub(crate) fn with_raw<F, R>(&self, f: F) -> R
    where
        F: FnOnce(&mut N) -> R,
    {
        self.state.lock(|state| f(&mut state.borrow_mut()))
    }

    /// Wait for the state to change.
    pub fn wait_state_changed(&self) -> impl Future<Output = ()> + '_ {
        self.state_changed.wait()
    }
}

impl<N> DynBase for SharedNetworks<N> where N: Send {}

impl<N> NetworksAccess for SharedNetworks<N>
where
    N: Networks,
{
    fn access<F: FnOnce(&mut dyn Networks) -> R, R>(&self, f: F) -> R {
        self.state.lock(|state| {
            let mut networks = state.borrow_mut();

            let mut instance = SharedNetworksInstance {
                networks: &mut *networks,
                changed: &self.state_changed,
            };

            f(&mut instance)
        })
    }
}

impl<N> NetChangeNotif for SharedNetworks<N> {
    fn wait_changed(&self) -> impl Future<Output = ()> {
        self.state_changed.wait()
    }
}

/// A wrapper around a `Networks` implementation that notifies on changes to the networks state.
pub struct SharedNetworksInstance<'a> {
    networks: &'a mut dyn Networks,
    changed: &'a Notification,
}

impl Networks for SharedNetworksInstance<'_> {
    fn max_networks(&self) -> Result<u8, Error> {
        self.networks.max_networks()
    }

    fn networks(&self, f: &mut dyn FnMut(&[u8]) -> Result<(), Error>) -> Result<(), Error> {
        self.networks.networks(f)
    }

    fn creds(
        &self,
        network_id: &[u8],
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<u8, NetworksError> {
        self.networks.creds(network_id, f)
    }

    fn next_creds(
        &self,
        last_network_id: Option<&[u8]>,
        f: &mut dyn FnMut(&WirelessCreds) -> Result<(), Error>,
    ) -> Result<bool, Error> {
        self.networks.next_creds(last_network_id, f)
    }

    fn enabled(&self) -> Result<bool, Error> {
        self.networks.enabled()
    }

    fn set_enabled(&mut self, enabled: bool) -> Result<(), Error> {
        self.networks.set_enabled(enabled)?;

        self.changed.notify();

        Ok(())
    }

    fn add_or_update(&mut self, creds: &WirelessCreds<'_>) -> Result<u8, NetworksError> {
        let index = self.networks.add_or_update(creds)?;

        self.changed.notify();

        Ok(index)
    }

    fn reorder(&mut self, index: u8, network_id: &[u8]) -> Result<u8, NetworksError> {
        let index = self.networks.reorder(index, network_id)?;

        self.changed.notify();

        Ok(index)
    }

    fn remove(&mut self, network_id: &[u8]) -> Result<u8, NetworksError> {
        let index = self.networks.remove(network_id)?;

        self.changed.notify();

        Ok(index)
    }

    fn managed(&self) -> Result<bool, Error> {
        self.networks.managed()
    }

    fn set_managed(&mut self, managed: bool) -> Result<(), Error> {
        self.networks.set_managed(managed)?;

        self.changed.notify();

        Ok(())
    }

    fn reset(&mut self) -> Result<(), Error> {
        self.networks.reset()?;

        self.changed.notify();

        Ok(())
    }

    fn load(&mut self, data: &[u8]) -> Result<(), Error> {
        self.networks.load(data)?;

        // As for every other mutator: `load` replaces the whole store state.
        // It is notably how the fail-safe expiry *reverts* staged network
        // changes (reloading the committed blob from the KV store) - without
        // the notification, a `WirelessMgr` parked on the store would sleep
        // through the revert and never reconcile connectivity with the
        // restored networks.
        self.changed.notify();

        Ok(())
    }

    fn save(&self, buf: &mut [u8]) -> Result<Option<usize>, Error> {
        let len = self.networks.save(buf)?;

        Ok(len)
    }
}

/// The system implementation of a handler for the Network Commissioning Matter cluster.
#[derive(Clone)]
pub struct NetCommHandler<'a, T> {
    dataver: Dataver,
    net_ctl: T,
    /// Tells whether the node currently has a network up. Combined with the
    /// last-connected network ID from `NetCtlStatus`, this is what the
    /// `Connected` field of each `Networks` entry is derived from - the
    /// `Networks` store itself has no way of knowing.
    wireless_diag: &'a dyn WirelessDiag,
}

impl<'a, T> NetCommHandler<'a, T> {
    /// Create a new instance of `NetCommHandler` with the given `Dataver`,
    /// `NetCtl` and `WirelessDiag`.
    pub const fn new(dataver: Dataver, net_ctl: T, wireless_diag: &'a dyn WirelessDiag) -> Self {
        Self {
            dataver,
            net_ctl,
            wireless_diag,
        }
    }

    /// Apply the `Breadcrumb` field of a Network Commissioning command.
    ///
    /// The field is optional, and only a command that *succeeded* may touch the
    /// `GeneralCommissioning::Breadcrumb` attribute - a failed command has to
    /// leave it exactly as it was.
    fn apply_breadcrumb(
        ctx: &impl InvokeContext,
        status: NetworkCommissioningStatusEnum,
        breadcrumb: Option<u64>,
    ) -> Result<(), Error> {
        if !matches!(status, NetworkCommissioningStatusEnum::Success) {
            return Ok(());
        }

        let Some(breadcrumb) = breadcrumb else {
            return Ok(());
        };

        ctx.exchange().with_state(|state| {
            state.failsafe.set_breadcrumb(breadcrumb);

            Ok(())
        })
    }

    /// Whether the `Networks` attribute currently has any entry.
    ///
    /// `LastNetworkingStatus`, `LastNetworkID` and `LastConnectErrorValue` all
    /// read as null while no network configurations exist, regardless of what
    /// happened before the last one was removed.
    fn has_networks(ctx: &impl ReadContext) -> Result<bool, Error> {
        ctx.networks().access(|networks| {
            let mut any = false;

            networks.networks(&mut |_| {
                any = true;

                Ok(())
            })?;

            Ok(any)
        })
    }

    /// Adapt the handler instance to the generic `rs-matter` `AsyncHandler` trait
    pub const fn adapt(self) -> HandlerAsyncAdaptor<Self> {
        HandlerAsyncAdaptor(self)
    }
}

impl<T> ClusterAsyncHandler for NetCommHandler<'_, T>
where
    T: NetCtl + NetCtlStatus,
{
    const CLUSTER: Cluster<'static> = NetworkType::Ethernet.cluster(); // TODO

    fn dataver(&self) -> u32 {
        self.dataver.get()
    }

    fn dataver_changed(&self) {
        self.dataver.changed();
    }

    fn max_networks(&self, ctx: impl ReadContext) -> impl Future<Output = Result<u8, Error>> {
        ready(ctx.networks().access(|networks| networks.max_networks()))
    }

    fn connect_max_time_seconds(
        &self,
        _ctx: impl ReadContext,
    ) -> impl Future<Output = Result<u8, Error>> {
        ready(Ok(self.net_ctl.connect_max_time_seconds()))
    }

    fn scan_max_time_seconds(
        &self,
        _ctx: impl ReadContext,
    ) -> impl Future<Output = Result<u8, Error>> {
        ready(Ok(self.net_ctl.scan_max_time_seconds()))
    }

    fn supported_wi_fi_bands<P: TLVBuilderParent>(
        &self,
        _ctx: impl ReadContext,
        builder: ArrayAttributeRead<
            ToTLVArrayBuilder<P, WiFiBandEnum>,
            ToTLVBuilder<P, WiFiBandEnum>,
        >,
    ) -> impl Future<Output = Result<P, Error>> {
        ready(match builder {
            ArrayAttributeRead::ReadAll(builder) => builder.with(|builder| {
                let mut builder = Some(builder);

                self.net_ctl.supported_wifi_bands(|band| {
                    builder = Some(unwrap!(builder.take()).push(&band)?);

                    Ok(())
                })?;

                unwrap!(builder.take()).end()
            }),
            ArrayAttributeRead::ReadOne(index, builder) => {
                let mut current = 0;
                let mut builder = Some(builder);
                let mut parent = None;

                match self.net_ctl.supported_wifi_bands(|band| {
                    if current == index {
                        parent = Some(unwrap!(builder.take()).set(&band)?);
                    }

                    current += 1;

                    Ok(())
                }) {
                    Err(e) => Err(e),
                    Ok(()) => {
                        if let Some(parent) = parent {
                            Ok(parent)
                        } else {
                            Err(ErrorCode::ConstraintError.into())
                        }
                    }
                }
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        })
    }

    fn supported_thread_features(
        &self,
        _ctx: impl ReadContext,
    ) -> impl Future<Output = Result<ThreadCapabilitiesBitmap, Error>> {
        ready(Ok(self.net_ctl.supported_thread_features()))
    }

    fn thread_version(&self, _ctx: impl ReadContext) -> impl Future<Output = Result<u16, Error>> {
        ready(Ok(self.net_ctl.thread_version()))
    }

    fn networks<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<NetworkInfoStructArrayBuilder<P>, NetworkInfoStructBuilder<P>>,
    ) -> impl Future<Output = Result<P, Error>> {
        // A network reads as connected when the node has a network up *and* the
        // last network it connected to is this one. The liveness half has to
        // come from the diagnostics hook rather than `LastNetworkingStatus`,
        // which records the last operation and stays `Success` even after the
        // link has since dropped.
        let connected = |network_id: &[u8]| -> Result<bool, Error> {
            if !self.wireless_diag.connected()? {
                return Ok(false);
            }

            self.net_ctl
                .last_network_id(|last| Ok(last == Some(network_id)))
        };

        ready(ctx.networks().access(|networks| match builder {
            ArrayAttributeRead::ReadAll(builder) => builder.with(|builder| {
                let mut builder = Some(builder);

                networks.networks(&mut |network_id| {
                    builder = Some(network_read_into(
                        network_id,
                        connected(network_id)?,
                        unwrap!(builder.take()).push()?,
                    )?);

                    Ok(())
                })?;

                unwrap!(builder.take()).end()
            }),
            ArrayAttributeRead::ReadOne(index, builder) => {
                let mut current = 0;
                let mut builder = Some(builder);
                let mut parent = None;

                networks.networks(&mut |network_id| {
                    if current == index {
                        parent = Some(network_read_into(
                            network_id,
                            connected(network_id)?,
                            unwrap!(builder.take()),
                        )?);
                    }

                    current += 1;

                    Ok(())
                })?;

                if let Some(parent) = parent {
                    Ok(parent)
                } else {
                    Err(ErrorCode::ConstraintError.into())
                }
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        }))
    }

    fn interface_enabled(
        &self,
        ctx: impl ReadContext,
    ) -> impl Future<Output = Result<bool, Error>> {
        ready(ctx.networks().access(|networks| networks.enabled()))
    }

    fn last_networking_status(
        &self,
        ctx: impl ReadContext,
    ) -> impl Future<Output = Result<Nullable<NetworkCommissioningStatusEnum>, Error>> {
        ready((|| {
            if !Self::has_networks(&ctx)? {
                return Ok(Nullable::none());
            }

            self.net_ctl.last_networking_status().map(Nullable::new)
        })())
    }

    fn last_network_id<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: NullableBuilder<P, OctetsBuilder<P>>,
    ) -> impl Future<Output = Result<P, Error>> {
        ready((|| {
            if !Self::has_networks(&ctx)? {
                return builder.null();
            }

            self.net_ctl.last_network_id(|network_id| {
                if let Some(network_id) = network_id {
                    builder.non_null()?.set(Octets::new(network_id))
                } else {
                    builder.null()
                }
            })
        })())
    }

    fn last_connect_error_value(
        &self,
        ctx: impl ReadContext,
    ) -> impl Future<Output = Result<Nullable<i32>, Error>> {
        ready((|| {
            if !Self::has_networks(&ctx)? {
                return Ok(Nullable::none());
            }

            self.net_ctl.last_connect_error_value().map(Nullable::new)
        })())
    }

    async fn set_interface_enabled(
        &self,
        ctx: impl WriteContext,
        value: bool,
    ) -> Result<(), Error> {
        let mut persist = Persist::new(ctx.kv());

        ctx.exchange().with_state(|state| {
            ctx.networks().access(|networks| {
                networks.set_enabled(value)?;

                // NOTE: Not sure this is a spec-compliant behavor:
                // If the failsafe is armed for _any_ fabric, we'll NOT persist the network changes until commissioning is complete.
                // And we'll LOSE those changes if the failsafe times out before commissioning completes.
                if !state.failsafe.is_armed() {
                    persist.store(NETWORKS_KEY, |buf| networks.save(buf))?;
                }

                Ok(())
            })
        })?;

        persist.run()
    }

    async fn handle_scan_networks<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: ScanNetworksRequest<'_>,
        response: ScanNetworksResponseBuilder<P>,
    ) -> Result<P, Error> {
        match self.net_ctl.net_type() {
            NetworkType::Thread => {
                let mut builder = Some(response);
                let mut array_builder = None;

                let (status, _, _) = NetworkCommissioningStatusEnum::map_ctl(
                    self.net_ctl
                        .scan(
                            request
                                .ssid()?
                                .as_ref()
                                .and_then(|ssid| ssid.as_opt_ref())
                                .map(|ssid| ssid.0),
                            |network| {
                                let abuilder = if let Some(builder) = builder.take() {
                                    builder
                                        .networking_status(NetworkCommissioningStatusEnum::Success)?
                                        .debug_text(None)?
                                        .wi_fi_scan_results()?
                                        .none()
                                        .thread_scan_results()?
                                        .some()?
                                } else {
                                    unwrap!(array_builder.take())
                                };

                                array_builder = Some(network.thread_read_into(abuilder.push()?)?);

                                Ok(())
                            },
                        )
                        .await
                        .map(|_| 0),
                )?;

                Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

                if let Some(builder) = builder {
                    builder
                        .networking_status(status)?
                        .debug_text(None)?
                        .wi_fi_scan_results()?
                        .none()
                        .thread_scan_results()?
                        .none()
                        .end()
                } else {
                    unwrap!(array_builder.take()).end()?.end()
                }
            }
            NetworkType::Wifi => {
                let mut builder = Some(response);
                let mut array_builder = None;

                let (status, _, _) = NetworkCommissioningStatusEnum::map_ctl(
                    self.net_ctl
                        .scan(
                            request
                                .ssid()?
                                .as_ref()
                                .and_then(|ssid| ssid.as_opt_ref())
                                .map(|ssid| ssid.0),
                            |network| {
                                let abuilder = if let Some(builder) = builder.take() {
                                    builder
                                        .networking_status(NetworkCommissioningStatusEnum::Success)?
                                        .debug_text(None)?
                                        .wi_fi_scan_results()?
                                        .some()?
                                } else {
                                    unwrap!(array_builder.take())
                                };

                                array_builder = Some(network.wifi_read_into(abuilder.push()?)?);

                                Ok(())
                            },
                        )
                        .await
                        .map(|_| 0),
                )?;

                Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

                if let Some(builder) = builder {
                    builder
                        .networking_status(status)?
                        .debug_text(None)?
                        .wi_fi_scan_results()?
                        .none()
                        .thread_scan_results()?
                        .none()
                        .end()
                } else {
                    unwrap!(array_builder.take())
                        .end()?
                        .thread_scan_results()?
                        .none()
                        .end()
                }
            }
            NetworkType::Ethernet => Err(ErrorCode::InvalidAction.into()),
        }
    }

    async fn handle_add_or_update_wi_fi_network<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: AddOrUpdateWiFiNetworkRequest<'_>,
        response: NetworkConfigResponseBuilder<P>,
    ) -> Result<P, Error> {
        let (status, _, index) = NetworkCommissioningStatusEnum::map(
            GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                ctx.networks().access(|networks| {
                    let index = networks.add_or_update(&WirelessCreds::Wifi {
                        ssid: request.ssid()?.0,
                        pass: request.credentials()?.0,
                    })?;

                    Ok(index)
                })
            }),
        )?;

        Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

        // Networks list mutated
        ctx.notify_own_cluster_changed();

        status.read_into(index, response)
    }

    async fn handle_add_or_update_thread_network<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: AddOrUpdateThreadNetworkRequest<'_>,
        response: NetworkConfigResponseBuilder<P>,
    ) -> Result<P, Error> {
        let (status, _, index) = NetworkCommissioningStatusEnum::map(
            GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                ctx.networks().access(|networks| {
                    let index = networks.add_or_update(&WirelessCreds::Thread {
                        dataset_tlv: request.operational_dataset()?.0,
                    })?;

                    Ok(index)
                })
            }),
        )?;

        Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

        // Networks list mutated
        ctx.notify_own_cluster_changed();

        status.read_into(index, response)
    }

    async fn handle_remove_network<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: RemoveNetworkRequest<'_>,
        response: NetworkConfigResponseBuilder<P>,
    ) -> Result<P, Error> {
        let (status, _, index) = NetworkCommissioningStatusEnum::map(
            GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                ctx.networks().access(|networks| {
                    let index = networks.remove(request.network_id()?.0)?;

                    Ok(index)
                })
            }),
        )?;

        Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

        // Networks list mutated
        ctx.notify_own_cluster_changed();

        status.read_into(index, response)
    }

    async fn handle_connect_network<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: ConnectNetworkRequest<'_>,
        mut response: ConnectNetworkResponseBuilder<P>,
    ) -> Result<P, Error> {
        if request.network_id()?.0.len() > MAX_WIRELESS_NETWORK_ID_LEN {
            return Err(ErrorCode::ConstraintError.into());
        }

        let (status, err_code) = match self.net_ctl.net_type() {
            NetworkType::Thread => {
                let dataset_buf = response.writer().available_space();
                let mut dataset_len = 0;

                let (mut status, mut err_code, _) = NetworkCommissioningStatusEnum::map(
                    GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                        ctx.networks().access(|networks| {
                            let index = networks.creds(request.network_id()?.0, &mut |creds| {
                                let WirelessCreds::Thread { dataset_tlv } = creds else {
                                    error!("Thread creds expected");
                                    return Err(ErrorCode::InvalidAction.into());
                                };

                                if dataset_tlv.len() > dataset_buf.len() {
                                    error!("Dataset too large");
                                    return Err(ErrorCode::ConstraintError.into());
                                }

                                dataset_buf[..dataset_tlv.len()].copy_from_slice(dataset_tlv);
                                dataset_len = dataset_tlv.len();

                                Ok(())
                            })?;

                            // `ConnectNetwork` is a staged, fail-safe-gated
                            // change like the list mutations: flip the store
                            // to unmanaged so the `WirelessMgr` stands down
                            // for the rest of the window instead of racing
                            // the connect we are about to perform.
                            networks.set_managed(false)?;

                            Ok(index)
                        })
                    }),
                )?;

                if matches!(status, NetworkCommissioningStatusEnum::Success) {
                    (status, err_code, _) = NetworkCommissioningStatusEnum::map_ctl(
                        self.net_ctl
                            .connect(&WirelessCreds::Thread {
                                dataset_tlv: &dataset_buf[..dataset_len],
                            })
                            .await,
                    )?;
                }

                (status, err_code)
            }
            NetworkType::Wifi => {
                let buf = response.writer().available_space();
                let (ssid_buf, pass_buf) = buf.split_at_mut(buf.len() / 2);
                let mut ssid_len = 0;
                let mut pass_len = 0;

                let (mut status, mut err_code, _) = NetworkCommissioningStatusEnum::map(
                    GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                        ctx.networks().access(|networks| {
                            let index = networks.creds(request.network_id()?.0, &mut |creds| {
                                let WirelessCreds::Wifi { ssid, pass } = creds else {
                                    error!("Wifi creds expected");
                                    return Err(ErrorCode::InvalidAction.into());
                                };

                                if ssid.len() > ssid_buf.len() {
                                    error!("SSID too large");
                                    return Err(ErrorCode::ConstraintError.into());
                                }

                                if pass.len() > pass_buf.len() {
                                    error!("Password too large");
                                    return Err(ErrorCode::ConstraintError.into());
                                }

                                ssid_buf[..ssid.len()].copy_from_slice(ssid);
                                ssid_len = ssid.len();
                                pass_buf[..pass.len()].copy_from_slice(pass);
                                pass_len = pass.len();

                                Ok(())
                            })?;

                            // As for the Thread branch: `ConnectNetwork` is a
                            // staged, fail-safe-gated change.
                            networks.set_managed(false)?;

                            Ok(index)
                        })
                    }),
                )?;

                if matches!(status, NetworkCommissioningStatusEnum::Success) {
                    (status, err_code, _) = NetworkCommissioningStatusEnum::map_ctl(
                        self.net_ctl
                            .connect(&WirelessCreds::Wifi {
                                ssid: &ssid_buf[..ssid_len],
                                pass: &pass_buf[..pass_len],
                            })
                            .await,
                    )?;
                }

                (status, err_code)
            }
            NetworkType::Ethernet => {
                return Err(ErrorCode::InvalidAction.into());
            }
        };

        Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

        // LastNetworkingStatus / LastNetworkID / LastConnectErrorValue mutated
        ctx.notify_own_cluster_changed();

        response
            .networking_status(status)?
            .debug_text(None)?
            .error_value(Nullable::new(err_code))?
            .end()
    }

    async fn handle_reorder_network<P: TLVBuilderParent>(
        &self,
        ctx: impl InvokeContext,
        request: ReorderNetworkRequest<'_>,
        response: NetworkConfigResponseBuilder<P>,
    ) -> Result<P, Error> {
        let (status, _, index) = NetworkCommissioningStatusEnum::map(
            GenCommHandler::with_armed_failsafe_ex(&ctx, |_, _| {
                ctx.networks().access(|networks| {
                    let index =
                        networks.reorder(request.network_index()? as _, request.network_id()?.0)?;

                    Ok(index)
                })
            }),
        )?;

        Self::apply_breadcrumb(&ctx, status, request.breadcrumb()?)?;

        // Networks order mutated
        ctx.notify_own_cluster_changed();

        status.read_into(index, response)
    }

    // `QueryIdentity` is not a `NetworkCommissioning` command in the Matter
    // 1.6.0 data model - it moved to the new (provisional)
    // `NetworkIdentityManagement` cluster, along with the rest of the Wi-Fi
    // per-device-credentials surface. The 1.6.1 IDL has it back on this
    // cluster, so the implementation is kept here, commented, to be restored
    // together with `CSA_STANDARD_CLUSTERS_IDL_V1_6_1_0`.
    //
    // fn handle_query_identity<P: TLVBuilderParent>(
    //     &self,
    //     _ctx: impl InvokeContext,
    //     _request: QueryIdentityRequest<'_>,
    //     _response: QueryIdentityResponseBuilder<P>,
    // ) -> impl Future<Output = Result<P, Error>> {
    //     ready(Err(ErrorCode::CommandNotFound.into()))
    // }
}

impl<T> Debug for NetCommHandler<'_, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("NetCommHandler")
            .field("dataver", &self.dataver.get())
            .finish()
    }
}

#[cfg(feature = "defmt")]
impl<T> defmt::Format for NetCommHandler<'_, T> {
    fn format(&self, f: defmt::Formatter) {
        defmt::write!(f, "NetCommHandler {{ dataver: {} }}", self.dataver.get());
    }
}