modem-mgmt 0.3.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
//! What each device is, as `state` and as `events` (#122).
//!
//! `state/modem/device/{device}/identity` carries RFC 8348's fields and the
//! bearer's equipment identifier, as much as the device knows — a document
//! with only the device's name is a legitimate answer, and says the device
//! was asked. `events/modem/device/{device}/identity_change/{event_id}` is
//! the transition: a terminal swapped under a running driver, a firmware
//! updated. Polled at the **state** cadence rather than the telemetry one,
//! because an identity changes when somebody changes the hardware, and a
//! document is published on every poll anyway. Damped like `oper_change`,
//! not because an identity flaps but because a rate the registry declares is
//! one the producer has to be able to keep.

use std::sync::atomic::AtomicU64;
use std::time::Duration;

use modem_contract::registry::modem::{Subject, key};
use tokio::time::Instant;
use zenkey::origin::LocalOrigin;
use zenoh::Session;

use crate::clock::{now_ms, ulid};
use crate::oper::{Damper, FLOOR, Source};

pub(super) async fn publish_loop(
    session: Session,
    origin: LocalOrigin,
    device: String,
    source: Source,
    ttl_s: u64,
) {
    let subject = Subject::device_identity(&device);
    let doc_key = key(&origin, &subject);
    let qos = subject.qos();
    let refresh = Duration::from_secs((ttl_s / 2).max(1));
    let counter = AtomicU64::new(0);
    let mut damper = Damper::new(FLOOR);

    let mut current = source.identity();
    // What the last event said the device *is*, so a trailing event after
    // folded changes still names the identity it started from.
    let mut announced = current.clone();
    crate::state::put(
        &session,
        &doc_key,
        &super::Identity::of(&device, &current),
        qos,
    )
    .await;

    loop {
        let wake = damper.deadline().map_or(Instant::now() + refresh, |d| {
            d.min(Instant::now() + refresh)
        });
        tokio::time::sleep_until(wake).await;

        let now = Instant::now();
        let observed = source.identity();
        if observed != current {
            current = observed;
            if let Some(n) = damper.observe(now) {
                let event_id = ulid(&counter);
                let subject = Subject::device_identity_change(&device, &event_id);
                let doc =
                    super::IdentityChange::of(&device, event_id, now_ms(), &announced, &current, n);
                announced = current.clone();
                crate::events::publish(&session, &origin, &subject, &doc, "identity_change").await;
            }
        }
        crate::state::put(
            &session,
            &doc_key,
            &super::Identity::of(&device, &current),
            qos,
        )
        .await;
        if let Some(n) = damper.flush(now) {
            let event_id = ulid(&counter);
            let subject = Subject::device_identity_change(&device, &event_id);
            let doc =
                super::IdentityChange::of(&device, event_id, now_ms(), &announced, &current, n);
            announced = current.clone();
            crate::events::publish(&session, &origin, &subject, &doc, "identity_change").await;
        }
    }
}