modem-contract 0.3.0

The management-plane contract of zenoh-modem: the registry, its payload types and their schemas, compiled once for every driver that serves it
Documentation
//! The configuration plane's documents (#125): a device's schema and
//! read-back, in the convention's own types (zenkey RFC 05 §5.1).
//!
//! `modem-device` declares a schema in its own words, because it links no
//! zenkey; the convention's types are the same shape with the same names,
//! so what happens here is a rename — and the one decision the convention
//! leaves to the producer, where a value came from, which the driver knows
//! from the startup file and the device does not.

use std::collections::BTreeSet;

use modem_device::config::{
    ConfigGroup, ConfigValue, Effective, ParamClass, ParamKind, ParamSpec, Schema,
};
use zenkey::config::{ConfigSchema, ConfigView, ParamValue, ValueSource};

/// The convention's kind for a device's.
#[must_use]
pub fn kind(k: &ParamKind) -> zenkey::config::ParamKind {
    match k {
        ParamKind::Bool => zenkey::config::ParamKind::Bool,
        ParamKind::Integer { min, max, unit } => zenkey::config::ParamKind::Integer {
            min: *min,
            max: *max,
            unit: unit.map(str::to_string),
        },
        ParamKind::Text => zenkey::config::ParamKind::Text,
        _ => zenkey::config::ParamKind::Text,
    }
}

/// The convention's class for a device's.
#[must_use]
pub fn class(c: ParamClass) -> zenkey::config::ParamClass {
    match c {
        ParamClass::Hot => zenkey::config::ParamClass::Hot,
        ParamClass::Reach => zenkey::config::ParamClass::Reach,
        ParamClass::Contract => zenkey::config::ParamClass::Contract,
        _ => zenkey::config::ParamClass::Contract,
    }
}

/// The convention's parameter for a device's.
#[must_use]
pub fn spec(p: &ParamSpec) -> zenkey::config::ParamSpec {
    let s = zenkey::config::ParamSpec::new(p.name, kind(&p.kind), p.description);
    if p.sensitive { s.sensitive() } else { s }
}

/// The convention's group for a device's.
#[must_use]
pub fn group(g: &ConfigGroup) -> zenkey::config::ConfigGroup {
    g.parameters.iter().fold(
        zenkey::config::ConfigGroup::new(g.name, class(g.class), g.description),
        |acc, p| acc.with(spec(p)),
    )
}

/// The convention's schema for a device's.
#[must_use]
pub fn schema(s: &Schema) -> ConfigSchema {
    s.groups
        .iter()
        .fold(ConfigSchema::new(), |acc, g| acc.with(group(g)))
}

/// The convention's value for a device's.
#[must_use]
pub fn value(v: &ConfigValue) -> ParamValue {
    match v {
        ConfigValue::Bool(b) => ParamValue::Bool(*b),
        ConfigValue::Integer(i) => ParamValue::Integer(*i),
        ConfigValue::Text(t) => ParamValue::Text(t.clone()),
        _ => ParamValue::Text(v.to_string()),
    }
}

/// A device's value for the convention's (#126): a change's values, as the
/// device takes them.
#[must_use]
pub fn value_of(v: &ParamValue) -> ConfigValue {
    match v {
        ParamValue::Bool(b) => ConfigValue::Bool(*b),
        ParamValue::Integer(i) => ConfigValue::Integer(*i),
        ParamValue::Text(t) => ConfigValue::Text(t.clone()),
        _ => ConfigValue::Text(v.to_string()),
    }
}

/// What the plane knows about a device's configuration that the device does
/// not (#125, #126): what it was at start, which values the file named,
/// which a remote writer set, the revision, and the pending change.
#[derive(Clone, Debug, Default)]
pub struct Provenance<'a> {
    /// What the device ran with when the plane started.
    pub startup: Option<&'a Effective>,
    /// The dotted keys the startup file's device section named.
    pub file_keys: Option<&'a BTreeSet<String>>,
    /// `group/name` of every parameter a remote writer set.
    pub runtime_keys: Option<&'a BTreeSet<String>>,
    /// `group/name` of every parameter the overlay set at boot (#128).
    pub overlay_keys: Option<&'a BTreeSet<String>>,
    /// How many changes have landed.
    pub revision: u64,
    /// The pending change, if one is armed (#127).
    pub pending: Option<zenkey::config::PendingChange>,
}

/// The read-back document (#125): the schema, and for every non-sensitive
/// parameter its value, where it came from, and what it was at start.
///
/// A value the startup file named is `file`, any other is `default`; one a
/// remote writer set (#126) is `runtime`, one the overlay set at boot (#128)
/// is `overlay`.
/// A sensitive parameter appears with no value at all.
#[must_use]
pub fn view(
    device: &str,
    schema_: &Schema,
    effective: &Effective,
    facts: &Provenance<'_>,
) -> ConfigView {
    let empty_keys = BTreeSet::new();
    let empty = Effective::default();
    let startup = facts.startup.unwrap_or(&empty);
    let file_keys = facts.file_keys.unwrap_or(&empty_keys);
    let runtime_keys = facts.runtime_keys.unwrap_or(&empty_keys);
    let overlay_keys = facts.overlay_keys.unwrap_or(&empty_keys);
    let mut view = ConfigView::of(device, &schema(schema_));
    view.revision = facts.revision;
    view.pending = facts.pending.clone();
    for g in &mut view.groups {
        for p in &mut g.parameters {
            if p.spec.sensitive {
                continue;
            }
            let now = effective.get(&g.name).and_then(|m| m.get(&p.spec.name));
            let then = startup.get(&g.name).and_then(|m| m.get(&p.spec.name));
            p.value = now.map(value);
            p.startup = then.map(value);
            let in_file = schema_
                .group(&g.name)
                .and_then(|dg| dg.parameter(&p.spec.name))
                .is_some_and(|dp| file_keys.contains(dp.key_in_file()));
            let key = format!("{}/{}", g.name, p.spec.name);
            let set_remotely = runtime_keys.contains(&key);
            let from_overlay = overlay_keys.contains(&key);
            p.source = now.map(|_| {
                if set_remotely {
                    ValueSource::Runtime
                } else if from_overlay {
                    ValueSource::Overlay
                } else if in_file {
                    ValueSource::File
                } else {
                    ValueSource::Default
                }
            });
        }
    }
    view
}