astarte_interfaces/mapping/
mod.rs

1// This file is part of Astarte.
2//
3// Copyright 2023 - 2025 SECO Mind Srl
4//
5// Licensed under the Apache License, Version 2.0 (the "License");
6// you may not use this file except in compliance with the License.
7// You may obtain a copy of the License at
8//
9//    http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the License for the specific language governing permissions and
15// limitations under the License.
16//
17// SPDX-License-Identifier: Apache-2.0
18
19//! Mapping of an interface.
20
21use endpoint::EndpointError;
22
23use self::endpoint::Endpoint;
24
25use crate::interface::MAX_INTERFACE_MAPPINGS;
26use crate::schema::{MappingType, SchemaError};
27
28pub mod collection;
29pub mod datastream;
30pub mod endpoint;
31pub mod path;
32pub mod properties;
33
34/// Error returned by the interface mappings.
35#[derive(Debug, thiserror::Error)]
36pub enum MappingError {
37    /// An interface must have at least one mapping.
38    #[error("an interface must have at lease one mapping")]
39    Empty,
40    /// An interface can have at max [`MAX_INTERFACE_MAPPINGS`] mappings.
41    #[error(
42        "too many mappings {0}, interfaces can have a max of {max} mappings",
43        max = MAX_INTERFACE_MAPPINGS
44    )]
45    TooMany(usize),
46    /// The endpoint of all the mappings of an interface must have an unique endpoint.
47    ///
48    /// This includes the parameters.
49    #[error("the mappings has a duplicated endpoint {endpoint}")]
50    Duplicated {
51        /// The first duplicated endpoint
52        endpoint: String,
53    },
54    /// Couldn't parse the mapping's endpoint
55    #[error("couldn't parse the mapping's endpoint")]
56    Endpoint(#[from] EndpointError),
57    /// The object interface endpoints should have at least 2 levels.
58    #[error("object endpoint should have at least 2 levels: '{0}'")]
59    TooShortForObject(String),
60    /// The interface schema is invalid for mapping.
61    #[error("invalid schema for mapping")]
62    Schema(#[from] SchemaError),
63    /// A filed is set on an interface of an invalid type.
64    #[cfg(feature = "strict")]
65    #[cfg_attr(docsrs, doc(cfg(feature = "strict")))]
66    #[error("{field} is set for a {interface_type} interface")]
67    InvalidField {
68        /// The field that is invalid.
69        field: &'static str,
70        /// The type of the interface that doesn't support the field
71        interface_type: crate::schema::InterfaceType,
72    },
73}
74
75/// Returns an error when an invalid optional field is set in strict mode
76macro_rules! invalid_filed {
77    (properties, $field:literal) => {
78        cfg_if::cfg_if! {
79            if #[cfg(feature = "strict")] {
80                return Err($crate::mapping::MappingError::InvalidField{
81                    field: $field,
82                    interface_type: $crate::schema::InterfaceType::Properties
83                });
84            } else {
85                tracing::warn!("property cannot have $field, ignoring");
86            }
87        }
88    };
89    (datastream, $field:literal) => {
90        cfg_if::cfg_if! {
91            if #[cfg(feature = "strict")] {
92                return Err($crate::mapping::MappingError::InvalidField{
93                    field: $field,
94                    interface_type: $crate::schema::InterfaceType::Datastream,
95                });
96            } else {
97                tracing::warn!("property cannot have $field, ignoring");
98            }
99        }
100    };
101}
102
103pub(crate) use invalid_filed;
104
105/// Mapping of an interface.
106pub trait InterfaceMapping {
107    /// Returns a reference to the endpoint of an interface.
108    fn endpoint(&self) -> &Endpoint<String>;
109    /// Returns the mapping type.
110    fn mapping_type(&self) -> MappingType;
111    /// Returns the description of the mapping.
112    #[cfg(feature = "doc-fields")]
113    #[cfg_attr(docsrs, doc(cfg(feature = "doc-fields")))]
114    fn description(&self) -> Option<&str>;
115    /// Returns the documentation of the mapping.
116    #[cfg(feature = "doc-fields")]
117    #[cfg_attr(docsrs, doc(cfg(feature = "doc-fields")))]
118    fn doc(&self) -> Option<&str>;
119}
astarte_interfaces/mapping/mod.rs

astarte_interfaces/mapping/
mod.rs
