modem-mgmt 0.2.0

The management plane of zenoh-modem as a library: serve every device on a host over Zenoh, for any driver that links the contract
Documentation
//! The SDU plane as the management plane reads it (#119).
//!
//! `modem-mgmt` serves any driver that links it, and the owner's IP driver
//! has no lanes at all — so the management plane must not depend on
//! `modem-driver`'s `Driver`. This trait is what it reads instead: the facts
//! a lane driver has and a netdev does not, as values, with nothing about
//! how they are produced. `modem-driver`'s `Driver` implements it; a test
//! double in `modem-mgmt` implements it too, which is what lets the plane be
//! tested without a single lane socket.

use std::path::PathBuf;

use modem_device::{Capabilities, DeviceEvent, LaneKey, Metrics, Report};

/// One lane, as the documents describe it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct LaneView {
    /// Endpoint, reliability and rank.
    pub key: LaneKey,
    /// Where its socket lives.
    pub path: PathBuf,
    /// Whether Zenoh is attached to it right now.
    pub connected: bool,
}

/// What the scheduler counts, at one instant.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct SchedulerCounters {
    pub submitted: u64,
    pub sent: u64,
    pub dropped: u64,
    pub stale: u64,
    pub peerless: u64,
    pub tx_failed: u64,
    pub unroutable: u64,
    pub rx_oversize: u64,
    pub tx_oversize: u64,
}

impl SchedulerCounters {
    /// Batches accepted and not yet transmitted.
    #[must_use]
    pub fn queue_depth(&self) -> u64 {
        self.submitted.saturating_sub(self.sent)
    }
}

/// A device's SDU plane: the lanes, the scheduler and the medium behind them.
///
/// Every method is a snapshot, sync and cheap — the telemetry loop calls
/// them every tick — except the two streams, which hand back their own
/// receivers, and `shutdown`, which is the one thing the host asks a plane
/// to *do*.
#[async_trait::async_trait]
pub trait SduPlane: Send + Sync {
    /// The device's name — the `{device}` chunk of every key about it.
    fn device(&self) -> &str;
    /// What the medium can carry.
    fn capabilities(&self) -> Capabilities;
    /// Every lane, in configuration order.
    fn lanes(&self) -> Vec<LaneView>;
    /// The scheduler's counters, now.
    fn scheduler(&self) -> SchedulerCounters;
    /// The medium's counters, now.
    fn medium_metrics(&self) -> Metrics;
    /// What the device says about itself, now.
    fn report(&self) -> Report;
    /// Whether the medium was usable a moment ago, and a way to be told when
    /// that changes. A failed medium stays failed, but the device can come
    /// back: an operator's `reopen` builds a new one, and this watch goes up
    /// again (#96).
    fn health(&self) -> tokio::sync::watch::Receiver<bool>;
    /// Whether the device is working, as the driver sees it: the device's
    /// own [`Device::oper`](modem_device::Device::oper), overlaid with
    /// `down` and `recoverable: false` once the medium has failed (#121).
    fn oper(&self) -> modem_device::OperStatus;
    /// What the device says it is (#122).
    fn identity(&self) -> modem_device::Identity;
    /// The device's configuration plane, if it declares one (#125): the
    /// `capability:config` predicate of the registration document, and what
    /// `config/{device}` reads.
    fn configuration(&self) -> Option<&dyn modem_device::Configure>;
    /// The operator actions the device offers, if any (#129): the
    /// `capability:actions` predicate.
    fn actions(&self) -> Option<&dyn modem_device::Actions>;
    /// The device's faults, as the scheduler raised them.
    fn events(&self) -> tokio::sync::broadcast::Receiver<DeviceEvent>;
    /// Stop the lanes and close the medium. Idempotent.
    async fn shutdown(&self);
}