rs-matter 0.3.0

/*
 *
 *    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 Descriptor cluster and its handler.

use core::fmt::Debug;

use crate::dm::{
    ArrayAttributeRead, Cluster, Dataver, Endpoint, EndptId, Metadata, ReadContext, SemanticTag,
};
use crate::error::{Error, ErrorCode};
use crate::tlv::{Nullable, TLVBuilderParent, ToTLVArrayBuilder, ToTLVBuilder, Utf8StrBuilder};
use crate::utils::sync::DynBase;
use crate::with;

pub use crate::dm::clusters::decl::descriptor::*;
pub use crate::dm::clusters::decl::globals::{
    SemanticTagStructArrayBuilder, SemanticTagStructBuilder,
};

/// A parts matcher suitable for regular Matter devices
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
struct StandardPartsMatcher;

impl DynBase for StandardPartsMatcher {}

impl PartsMatcher for StandardPartsMatcher {
    fn matches(&self, our_endpoint: EndptId, endpoint: EndptId) -> bool {
        our_endpoint == 0 && endpoint != our_endpoint
    }
}

/// A parts matcher suitable for the aggregator endpoints of bridged Matter devices
///
/// This matcher matches ALL endpoints that are not the root endpoint (0) and not the aggregator endpoint itself.
///
/// For more complex scenarios, where the node needs to contain multiple aggregators, or where the node
/// might contain non-bridged endpoints, user needs to supply its own `PartsMatcher` implementation.
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
struct AggregatorPartsMatcher;

impl DynBase for AggregatorPartsMatcher {}

impl PartsMatcher for AggregatorPartsMatcher {
    fn matches(&self, our_endpoint: EndptId, endpoint: EndptId) -> bool {
        endpoint != our_endpoint && endpoint != 0
    }
}

/// A trait for describing which endpoints (parts) should be returned
/// from the POV of our endpoint
///
/// For standard Matter devices, all endpoints should be returned as parts.
/// However - for queries on aggregator endpoints (i.e. those present in Matter bridges) -
/// only endpoints different from the aggregator and from the root endpoint should be returned.
pub trait PartsMatcher: DynBase + Debug {
    /// Return `true` if the endpoint should be returned as a part
    ///
    /// # Arguments
    /// - `our_endpoint`: The endpoint ID of the endpoint that is being queried
    /// - `endpoint`: The endpoint ID of the endpoint that is being checked
    fn matches(&self, our_endpoint: EndptId, endpoint: EndptId) -> bool;
}

impl<T> PartsMatcher for &T
where
    T: PartsMatcher,
{
    fn matches(&self, our_endpoint: EndptId, endpoint: EndptId) -> bool {
        (**self).matches(our_endpoint, endpoint)
    }
}

/// The system implementation of a handler for the Descriptor Matter cluster.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct DescHandler<'a> {
    dataver: Dataver,
    matcher: &'a dyn PartsMatcher,
}

impl DescHandler<'static> {
    /// Create a new instance of `DescHandler` with the given `Dataver`
    /// and a matcher suitable for regular Matter devices
    pub const fn new(dataver: Dataver) -> Self {
        Self::new_matching(dataver, &StandardPartsMatcher)
    }

    /// Create a new instance of `DescHandler` with the given `Dataver`
    /// and a matcher suitable for aggregator endpoints
    pub const fn new_aggregator(dataver: Dataver) -> Self {
        Self::new_matching(dataver, &AggregatorPartsMatcher)
    }
}

impl<'a> DescHandler<'a> {
    /// Create a new instance of `DescHandler` with the given `Dataver`
    /// and a custom matcher
    pub const fn new_matching(dataver: Dataver, matcher: &'a dyn PartsMatcher) -> DescHandler<'a> {
        Self { dataver, matcher }
    }

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

    /// Emit a single `SemanticTagStruct` into `builder`.
    fn push_tag<P: TLVBuilderParent>(
        builder: SemanticTagStructBuilder<P>,
        tag: &SemanticTag<'_>,
    ) -> Result<P, Error> {
        builder
            .mfg_code(Nullable::new(tag.mfg_code))?
            .namespace_id(tag.namespace_id)?
            .tag(tag.tag)?
            .label(tag.label.map(Nullable::some))?
            .end()
    }

    fn with_endpoint<F, R>(ctx: impl ReadContext, f: F) -> Result<R, Error>
    where
        F: FnOnce(&Endpoint) -> Result<R, Error>,
    {
        let metadata = ctx.metadata();

        metadata.access(|node| {
            let endpoint = node
                .endpoint(ctx.attr().endpoint_id)
                .ok_or_else(|| Error::new(ErrorCode::EndpointNotFound))?;

            f(endpoint)
        })
    }
}

/// `Descriptor` cluster metadata that additionally advertises the optional
/// `TagList` attribute and the `TagList` feature.
///
/// Use this in place of [`DescHandler::CLUSTER`] on endpoints carrying
/// [`Endpoint::semantic_tags`]. It is required whenever a node exposes two or
/// more endpoints with the same device type under one parent: Matter Core spec
/// 9.5 then demands each of them report a non-empty, mutually distinct
/// `TagList`, and `TC_DESC_2_2` checks precisely that (it fails an endpoint
/// whose `TagList` is absent *or* empty, and separately flags a missing
/// feature bit).
///
/// It is deliberately not the default: on a node with no duplicated device
/// types the attribute is optional, and advertising an always-empty `TagList`
/// would be worse than not advertising it at all.
pub const CLUSTER_TAG_LIST: Cluster<'static> = FULL_CLUSTER
    .with_attrs(with!(required; AttributeId::TagList))
    .with_cmds(with!())
    .with_features(Feature::TAG_LIST.bits());

/// `Descriptor` cluster metadata that additionally advertises the optional
/// `EndpointUniqueID` attribute.
///
/// Use this in place of [`DescHandler::CLUSTER`] on endpoints carrying
/// [`Endpoint::unique_id`]. It is deliberately not the default: the attribute
/// is optional, and advertising it on an endpoint whose [`Endpoint::unique_id`]
/// is `None` would turn every read into an error.
pub const CLUSTER_ENDPOINT_UNIQUE_ID: Cluster<'static> = FULL_CLUSTER
    .with_attrs(with!(required; AttributeId::EndpointUniqueID))
    .with_cmds(with!());

impl ClusterHandler for DescHandler<'_> {
    const CLUSTER: Cluster<'static> = FULL_CLUSTER.with_attrs(with!(required)).with_cmds(with!());

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

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

    fn device_type_list<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<DeviceTypeStructArrayBuilder<P>, DeviceTypeStructBuilder<P>>,
    ) -> Result<P, Error> {
        Self::with_endpoint(ctx, |endpoint| match builder {
            ArrayAttributeRead::ReadAll(mut builder) => {
                for dev_type in endpoint.device_types {
                    builder = builder
                        .push()?
                        .device_type(dev_type.dtype as _)?
                        .revision(dev_type.drev)?
                        .end()?;
                }

                builder.end()
            }
            ArrayAttributeRead::ReadOne(index, builder) => {
                let Some(dev_type) = endpoint.device_types.get(index as usize) else {
                    return Err(ErrorCode::ConstraintError.into());
                };

                builder
                    .device_type(dev_type.dtype as _)?
                    .revision(dev_type.drev)?
                    .end()
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        })
    }

    fn server_list<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<ToTLVArrayBuilder<P, u32>, ToTLVBuilder<P, u32>>,
    ) -> Result<P, Error> {
        Self::with_endpoint(ctx, |endpoint| match builder {
            ArrayAttributeRead::ReadAll(mut builder) => {
                for cluster in endpoint.clusters {
                    builder = builder.push(&cluster.id)?;
                }

                builder.end()
            }
            ArrayAttributeRead::ReadOne(index, builder) => {
                let Some(cluster) = endpoint.clusters.get(index as usize) else {
                    return Err(ErrorCode::ConstraintError.into());
                };

                builder.set(&cluster.id)
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        })
    }

    fn client_list<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<ToTLVArrayBuilder<P, u32>, ToTLVBuilder<P, u32>>,
    ) -> Result<P, Error> {
        Self::with_endpoint(ctx, |endpoint| match builder {
            ArrayAttributeRead::ReadAll(mut builder) => {
                for client_id in endpoint.client_clusters {
                    builder = builder.push(client_id)?;
                }
                builder.end()
            }
            ArrayAttributeRead::ReadOne(index, builder) => {
                let Some(client_id) = endpoint.client_clusters.get(index as usize) else {
                    return Err(ErrorCode::ConstraintError.into());
                };
                builder.set(client_id)
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        })
    }

    fn tag_list<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<SemanticTagStructArrayBuilder<P>, SemanticTagStructBuilder<P>>,
    ) -> Result<P, Error> {
        Self::with_endpoint(ctx, |endpoint| match builder {
            ArrayAttributeRead::ReadAll(mut builder) => {
                for tag in endpoint.semantic_tags {
                    builder = Self::push_tag(builder.push()?, tag)?;
                }

                builder.end()
            }
            ArrayAttributeRead::ReadOne(index, builder) => {
                let Some(tag) = endpoint.semantic_tags.get(index as usize) else {
                    return Err(ErrorCode::ConstraintError.into());
                };

                Self::push_tag(builder, tag)
            }
            ArrayAttributeRead::ReadNone(builder) => builder.end(),
        })
    }

    // Deliberately outlined (`inline(never)`): inlining duplicates the body
    // in every read-dispatch instantiation (flash size)
    #[inline(never)]
    fn endpoint_unique_id<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: Utf8StrBuilder<P>,
    ) -> Result<P, Error> {
        Self::with_endpoint(ctx, |endpoint| {
            // Reaching here means the endpoint's `Descriptor` metadata
            // advertises the attribute (`CLUSTER_ENDPOINT_UNIQUE_ID`), so a
            // missing `Endpoint::unique_id` is a composition error.
            let unique_id = endpoint
                .unique_id
                .ok_or_else(|| Error::new(ErrorCode::AttributeNotFound))?;

            builder.set(unique_id)
        })
    }

    fn parts_list<P: TLVBuilderParent>(
        &self,
        ctx: impl ReadContext,
        builder: ArrayAttributeRead<ToTLVArrayBuilder<P, u16>, ToTLVBuilder<P, u16>>,
    ) -> Result<P, Error> {
        let metadata = ctx.metadata();

        metadata.access(|node| {
            let mut ep_ids = node
                .endpoints
                .iter()
                .map(|e| e.id)
                .filter(|e| self.matcher.matches(ctx.attr().endpoint_id, *e));

            match builder {
                ArrayAttributeRead::ReadAll(mut builder) => {
                    for id in ep_ids {
                        builder = builder.push(&id)?;
                    }

                    builder.end()
                }
                ArrayAttributeRead::ReadOne(index, builder) => {
                    let Some(ep_id) = ep_ids.nth(index as usize) else {
                        return Err(ErrorCode::ConstraintError.into());
                    };

                    builder.set(&ep_id)
                }
                ArrayAttributeRead::ReadNone(builder) => builder.end(),
            }
        })
    }
}