config_it/shared/
meta.rs

1use std::borrow::Cow;
2
3bitflags::bitflags! {
4    /// Represents metadata flags for a configuration entity.
5    ///
6    /// These flags provide hints and directives to the config system (`config-it`)
7    /// about how to treat and interact with the associated configuration variable.
8    #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, Copy, PartialEq, Eq)]
9    pub struct MetaFlag: u32 {
10        /// Prevents the variable from being included in `import` operations.
11        const NO_IMPORT = 1 << 0;
12
13        /// Prevents the variable from being included in `export` operations.
14        const NO_EXPORT = 1 << 1;
15
16        /// Advises the monitor to hide this variable from non-admin users.
17        const HIDDEN_NON_ADMIN = 1 << 2;
18
19        /// Advises the monitor to hide this variable from all users, regardless of role.
20        const HIDDEN = 1 << 6;
21
22        /// Indicates that only admin users should be allowed to read this variable.
23        const ADMIN_READ = 1 << 3;
24
25        /// Indicates that only admin users should be allowed to write to this variable. Implicitly
26        /// includes the `ADMIN_READ` permission.
27        const ADMIN_WRITE = 1 << 4 | Self::ADMIN_READ.bits();
28
29        /// Designates the variable as read-only, ensuring that no user, even admins, can modify its
30        /// value.
31        const READONLY = 1 << 5;
32
33        /// Marks the variable as write-only. This means its value cannot be read or accessed
34        /// (useful for secrets, where the value might be set but not retrieved).
35        const WRITEONLY = 1 << 7;
36
37        /// Ensures that the variable's value is encrypted when stored. Implicitly includes the
38        /// `WRITEONLY` property, reflecting the sensitive nature of the data.
39        const SECRET = 1 << 8 | Self::WRITEONLY.bits();
40
41        /// Designates the variable as exclusive to admin users for both reading and writing.
42        const ADMIN = Self::ADMIN_READ.bits() | Self::ADMIN_WRITE.bits();
43
44        /// Informs the monitor that this variable is transient, implying that it shouldn't be
45        /// persisted to storage. This combines both `NO_EXPORT` and `NO_IMPORT` properties.
46        const TRANSIENT = MetaFlag::NO_EXPORT.bits() | MetaFlag::NO_IMPORT.bits();
47    }
48}
49
50/// Hint for backend editor. This is not used by config-it itself.
51///
52/// This is used by remote monitor to determine how to edit this variable.
53#[derive(Debug, serde::Serialize, serde::Deserialize)]
54#[serde(rename_all = "snake_case")]
55#[non_exhaustive]
56pub enum MetadataEditorHint {
57    /// For color in range [0.0, 1.0]
58    ///
59    /// - [number; 3] -> RGB
60    /// - [number; 4] -> RGBA
61    ColorRgba255,
62
63    /// For color in range [0, 255]
64    ///
65    /// - [number; 3] -> RGB
66    /// - [number; 4] -> RGBA
67    /// - string -> hex color
68    /// - integer -> 32 bit hex color `[r,g,b,a] = [0,8,16,24].map(|x| 0xff & (color >> x))`
69    ColorRgbaReal,
70
71    /// Any string type will be treated as multiline text.
72    MultilineText,
73
74    /// Any string type will be treated as code, with given language hint.
75    Code(Cow<'static, str>),
76}
77
78/// Describes metadata for a configuration entity, intended for utilization by external tools.
79#[derive(Debug, serde::Serialize, serde::Deserialize)]
80#[non_exhaustive]
81pub struct Metadata {
82    /// Unique identifier for this configuration entity.
83    pub name: &'static str,
84
85    /// Source variable name from the configuration definition. It's typically identical to 'name'
86    /// unless an alternative name is explicitly set.
87    pub varname: &'static str,
88
89    /// String representation of the type for this configuration entity.
90    pub type_name: &'static str,
91
92    /// Flags that denote various behaviors and hints associated with the configuration entity.
93    pub flags: MetaFlag,
94
95    /// Provides guidance for a monitoring editor on how to interact with this variable. While this
96    /// crate doesn't use this hint directly, it helps external monitors understand the preferred
97    /// method to edit the variable.
98    pub editor_hint: Option<MetadataEditorHint>,
99
100    /// If enabled, provides a schema that remote monitors can leverage to manage this variable
101    /// effectively.
102    #[cfg(feature = "jsonschema")]
103    pub schema: Option<crate::Schema>,
104
105    /// A brief description that elaborates on the purpose or role of the configuration entity.
106    pub description: &'static str,
107
108    /// Corresponding environment variable name, if any, that maps to this configuration entity.
109    pub env: Option<&'static str>,
110}
111
112impl Metadata {
113    #[doc(hidden)]
114    pub fn __macro_new(
115        name: &'static str,
116        varname: &'static str,
117        type_name: &'static str,
118        flags: MetaFlag,
119        editor_hint: Option<MetadataEditorHint>,
120        description: &'static str,
121        env: Option<&'static str>,
122        #[cfg(feature = "jsonschema")] schema: Option<crate::Schema>,
123    ) -> Self {
124        Self {
125            name,
126            varname,
127            type_name,
128            flags,
129            editor_hint,
130            #[cfg(feature = "jsonschema")]
131            schema,
132            description,
133            env,
134        }
135    }
136}
config_it/shared/meta.rs

config_it/shared/
meta.rs
