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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
//! The management plane: everything the ICD's control channel used to carry —
//! as a library, for any driver that links the contract (#119).
//!
//! Decision D2 deleted that channel entirely — HELLO, capability negotiation,
//! both snapshot protocols, TX delivery states, the security state model — on
//! the claim that all of it is better expressed as ordinary Zenoh traffic under
//! the keyspace-v2 convention. This module is that claim, in code.
//!
//! Two planes, kept apart deliberately (`docs/architecture.md` §4.1, §4.6):
//!
//! - The **data plane** carries opaque batches and never links against `zenoh`.
//!   CI holds that with a dependency guard.
//! - The **management plane** is an ordinary Zenoh client surface on the
//!   driver's *own* session. It is feature-gated, so a driver built without it
//!   still moves data and the data-path tests never need it.
//!
//! What that buys, beyond tidiness: an operator gets `zenctl` on day one, the
//! contract is linted at build time by `zenkey-build` rather than written prose,
//! and capability negotiation becomes a query anyone can make instead of a
//! handshake only the link can perform.

mod action;
mod clock;
mod config;
pub mod conformance;
mod destination;
mod events;
pub mod host;
mod identity;
mod oper;
mod overlay;
pub mod plane;
mod radio;
mod rpc;
mod security;
mod sensor;
mod state;
pub mod telemetry;

use std::sync::Arc;

use anyhow::Context as _;
use zenkey::V1Context;
use zenoh::Session;

pub use host::{Host, Node, Plane};
pub use modem_contract::documents::{
    Ack, ActionEvent, ActionOutcome, ActionRequest, Capabilities, DestinationState, DeviceFault,
    Duplex, EndpointLane, EndpointState, Identity, IdentityChange, Lane, LaneTable, LinkState,
    Oper, OperChange, RadioState, SecurityState, Sensor,
};
pub use modem_contract::{PRODUCER, PROFILE};
pub use plane::{LaneView, SchedulerCounters, SduPlane};
pub use telemetry::subjects as telemetry_subjects;

/// How to reach the local bus.
#[derive(Clone, Debug, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MgmtConfig {
    /// Endpoints to connect to, e.g. `["tcp/127.0.0.1:7447"]`.
    #[serde(default)]
    pub connect: Vec<String>,
    /// Endpoints to listen on, if this driver should accept instead.
    #[serde(default)]
    pub listen: Vec<String>,
    /// Whether to allow multicast scouting.
    ///
    /// Off by default. On a node whose uplink is a radio, scouting is pure
    /// cost, and a driver that joined whatever mesh it found would be a
    /// surprise rather than a feature.
    #[serde(default)]
    pub scouting: bool,
    /// The management session's Zenoh mode: `client`, `peer` or `router`.
    ///
    /// Unset, it is **`client` when the session only connects** and `peer`
    /// when it listens (#152). A session that connects is attaching to the
    /// node's own `zenohd`, as any local application does, and a client is
    /// what that router serves without gossip. The shipped routers disable
    /// gossip, because on a 2400 bit/s link it is pure cost, and a *peer*
    /// attached to such a router is invisible to everything else on it:
    /// `zenctl node list` through `zenohd-rf0.json5` found no producer at
    /// all until this was a client.
    #[serde(default)]
    pub mode: Option<String>,
    /// Credentials the session presents, for a router that authenticates
    /// (#98). A router holding a `usrpwd` dictionary refuses *every* link
    /// without credentials, this one included (`auth_face.rs`).
    ///
    /// The password is read from a file, so it never sits in this one, and
    /// is never logged.
    #[serde(default)]
    pub usrpwd: Option<UsrPwd>,
    /// Seconds a `state` document stays fresh. Refreshed at half this.
    ///
    /// zenkey requires every `state` subject to carry one: a reader must be
    /// able to tell "unchanged" from "gone".
    ///
    /// The default is **the registry's**, not a number written here, because a
    /// document that advertises a freshness the contract does not declare is a
    /// document a consumer cannot trust. An operator may lower it — refreshing
    /// more often than promised is safe, and the tests do exactly that — but
    /// [`Mgmt::start`] refuses to raise it above the declared bound.
    #[serde(default = "default_ttl")]
    pub ttl_s: u64,
    /// Milliseconds between telemetry sweeps.
    ///
    /// **A cost knob, and §4.6 is the argument for having one.** Seventeen
    /// counters every five seconds is 3.6 publications a second for ever, which
    /// is why both shipped routers deny the management plane on the radio. An
    /// operator whose bus is a 2400 bit/s channel wants sixty seconds; one
    /// watching a bring-up wants one. Five seconds is a default, not a law, and
    /// it was previously a `const` nobody could reach.
    ///
    /// Milliseconds rather than seconds because the tests that read counters
    /// off the wire should not each wait out a production cadence — that alone
    /// was 96 s of a 244 s suite.
    #[serde(default = "default_telemetry_interval_ms")]
    pub telemetry_interval_ms: u64,
    /// Where `persist` keeps a confirmed change across restarts (#128): one
    /// `<device>.overlay.toml` per device, `0600`. Unset, the unit's
    /// `StateDirectory` (`$STATE_DIRECTORY`) is used when systemd provides
    /// one; with neither, nothing persists and `persist` says so.
    #[serde(default)]
    pub state_dir: Option<std::path::PathBuf>,
    /// The provisional boot (#128): seconds after boot by which a device
    /// started under an overlay must be `up`, or the overlay is set aside
    /// and the startup file alone applies — once, with an event. Unset,
    /// an overlay is trusted. A persisted change that cuts a remote node
    /// off must not survive a power cycle; this is the operator's deadline
    /// for that, in the operator's file (I1).
    #[serde(default)]
    pub provisional_boot_s: Option<u64>,
}

/// A `usrpwd` identity for the management session (#98).
#[derive(Clone, Debug, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UsrPwd {
    /// The user name, which the router's ACL may grant by (`usernames`).
    pub user: String,
    /// A file holding the password and nothing else; a trailing newline is
    /// ignored. Readable by the daemon only (`0600`).
    pub password_file: std::path::PathBuf,
}

fn default_telemetry_interval_ms() -> u64 {
    // The constant is the source, so the default and the cost argument §4.6 is
    // written in cannot drift apart.
    telemetry::DEFAULT_INTERVAL.as_millis() as u64
}

fn default_ttl() -> u64 {
    state::declared_ttl_s()
}

impl Default for MgmtConfig {
    fn default() -> Self {
        Self {
            connect: Vec::new(),
            listen: Vec::new(),
            scouting: false,
            mode: None,
            usrpwd: None,
            ttl_s: default_ttl(),
            telemetry_interval_ms: default_telemetry_interval_ms(),
            state_dir: None,
            provisional_boot_s: None,
        }
    }
}

/// A running management plane.
///
/// Holds the liveliness token: dropping this makes the driver disappear from
/// every roster, which is the intended way to say "gone" rather than "quiet".
pub struct Mgmt {
    session: Session,
    ctx: V1Context,
    tasks: Vec<tokio::task::JoinHandle<()>>,
    _alive: zenoh::liveliness::LivelinessToken,
    /// One per device the host serves (RFC 04 §5).
    _device_alive: Arc<
        std::sync::Mutex<std::collections::BTreeMap<String, zenoh::liveliness::LivelinessToken>>,
    >,
}

/// Serve every device on the host: open the session, declare presence, and
/// start publishing. The one call a driver makes (#119); [`Mgmt::start`] is
/// the same function under the name the daemon has always used.
pub async fn serve(cfg: &MgmtConfig, host: Arc<Host>) -> anyhow::Result<Mgmt> {
    Mgmt::start(cfg, host).await
}

impl Mgmt {
    /// Open the local session, declare presence, and start publishing — for
    /// every device the host serves (#118).
    ///
    /// One session, one presence token, one `introspect`: the origin is the
    /// host and the producer is `modem`, so the bus sees one producer however
    /// many devices stand behind it. Each device gets its own `lanes`, its own
    /// telemetry, state and event loops, and its own `{device}` chunk.
    /// Everything [`Mgmt::start`] can decide without I/O, so a daemon can
    /// refuse a bad configuration before it says it is running, and then
    /// bring the plane up behind it (#152).
    ///
    /// # Errors
    ///
    /// The first problem found.
    pub fn check(cfg: &MgmtConfig, host: &Host) -> anyhow::Result<()> {
        anyhow::ensure!(
            !host.nodes().is_empty(),
            "a management plane with no device to serve would declare itself alive for nothing"
        );
        V1Context::for_producer(&PROFILE, PRODUCER)
            .context("the producer context is not a valid zenkey context")?;
        // RFC 08 §6.1: an implementation must not report itself alive while the
        // types it declares and the types it describes disagree. Checked here,
        // on the way up, rather than by `build_verified` — that panics, and a
        // panic inside a `LazyLock` inside a spawned queryable is the worst
        // available place for this to go wrong.
        modem_contract::schema::verify_total()
            .context("the describe surface does not cover every declared type (RFC 08 §7)")?;
        // Refreshing faster than the declared bound is fine and is what the
        // tests do; advertising a *longer* freshness than the registry declares
        // is a document a consumer cannot trust, and RFC 08 §6.1 is unambiguous
        // that the registry must not lie.
        anyhow::ensure!(
            cfg.ttl_s <= state::declared_ttl_s(),
            "[management] ttl_s = {} exceeds the {} s the registry declares for \
             this producer's state subjects; lower it, or change the registry \
             and re-run `just registry-lock`",
            cfg.ttl_s,
            state::declared_ttl_s(),
        );
        session_mode(cfg)?;
        if let Some(id) = &cfg.usrpwd {
            anyhow::ensure!(!id.user.is_empty(), "[management] usrpwd user is empty");
            std::fs::metadata(&id.password_file).with_context(|| {
                format!(
                    "[management] usrpwd password_file {}",
                    id.password_file.display()
                )
            })?;
        }
        Ok(())
    }

    pub async fn start(cfg: &MgmtConfig, host: Arc<Host>) -> anyhow::Result<Self> {
        // Everything that can be decided without I/O is decided first, so a
        // misconfigured or self-inconsistent driver refuses to start before it
        // has opened a socket or bound a key.
        Self::check(cfg, &host)?;
        let ctx = V1Context::for_producer(&PROFILE, PRODUCER)
            .context("the producer context is not a valid zenkey context")?;
        // Every SDU device's state keys, resolved before anything is declared:
        // a roster that calls this host alive is entitled to its documents.
        let state_keys: Vec<(Arc<dyn SduPlane>, state::StateKeys)> = host
            .sdu_planes()
            .map(|p| {
                (
                    p.clone(),
                    state::StateKeys::of(&PROFILE.local_origin(), p.as_ref()),
                )
            })
            .collect();

        let session = open_session(cfg).await?;

        // The anti-twin probe (#118, zenkey RFC 03 §1.5): one daemon per host,
        // and the roster is where a second one shows. Asked before anything is
        // declared, so a twin refuses to start rather than answering beside
        // the first — the lock files keep two processes off one *device*; this
        // keeps two processes off one *producer*. Not an interlock: a bus
        // partition could let two claimants coexist, which is why the device
        // lock is taken outside the bus and this is only the early refusal.
        if let Some(twin) = twin_alive(&session, &ctx).await {
            let _ = session.close().await;
            anyhow::bail!(
                "another daemon already declares {twin} on this host: one daemon serves \
                 every device on a host (#118) — stop it, or add this device to its config"
            );
        }

        // The `@rpc` surface first, and every declaration awaited: the token
        // below is what a roster reads, and it must not appear before the
        // procedures it implies are answering (RFC 08 §6.1, #42). `rpc::serve`
        // used to be synchronous and declared inside three spawned tasks, so
        // this comment described an ordering the code did not have.
        // The configuration plane's read side (#125), for every node that
        // declares one: what it was at start is captured here, once.
        let state_dir = cfg
            .state_dir
            .clone()
            .or_else(|| std::env::var_os("STATE_DIRECTORY").map(std::path::PathBuf::from));
        let configs: Vec<Arc<config::ConfigState>> = host
            .nodes()
            .iter()
            .filter_map(|node| {
                config::ConfigState::of(
                    node.name(),
                    oper::Source::of(node),
                    node.file_keys().clone(),
                    node.writable().clone(),
                    state_dir
                        .as_ref()
                        .map(|d| d.join(format!("{}.overlay.toml", node.name()))),
                )
            })
            .map(Arc::new)
            .collect();
        // Boot reconciles (#128): the overlay, checked and applied, before
        // anything is served — and set aside if the device is not up by
        // the operator's deadline.
        let mut provisional = Vec::new();
        for state in &configs {
            if state.boot().await > 0
                && let Some(s) = cfg.provisional_boot_s
            {
                provisional.push(state.provisional(std::time::Duration::from_secs(s)));
            }
        }

        // Operator actions (#129), for every node whose device offers any.
        let actions: Vec<Arc<action::ActionState>> = host
            .nodes()
            .iter()
            .filter_map(|node| {
                action::ActionState::of(
                    node.name(),
                    oper::Source::of(node),
                    node.actions().clone(),
                    node.action_intervals().clone(),
                )
            })
            .map(Arc::new)
            .collect();

        let mut tasks = rpc::serve(session.clone(), host.clone(), &configs, &actions)
            .await
            .context("the @rpc surface could not be declared (RFC 08 §6.1)")?;

        // Only now: present, and able to answer.
        let alive = session
            .liveliness()
            .declare_token(ctx.alive_key().as_keyexpr())
            .await
            .map_err(|e| anyhow::anyhow!("declare liveliness token: {e}"))?;
        // And one per device (RFC 04 §5, #120): `state/modem/device/<device>/
        // alive`, the token that cycles when *that* device restarts — a modem
        // re-enumerating under a driver that never did (RFC v1.39) — so a
        // counter reset under its subject is excused for it and no other. The
        // cycling itself arrives with the detection (#121, #130); the token
        // is declared now, so the roster shows every device the host serves.
        let mut device_alive = std::collections::BTreeMap::new();
        for node in host.nodes() {
            let key = ctx.device_alive_key(node.name());
            let token = session
                .liveliness()
                .declare_token(key.as_keyexpr())
                .await
                .map_err(|e| anyhow::anyhow!("declare device liveliness token {key}: {e}"))?;
            device_alive.insert(node.name().to_string(), token);
        }
        let device_alive = Arc::new(std::sync::Mutex::new(device_alive));

        let devices: Vec<&str> = host.nodes().iter().map(|n| n.name()).collect();
        tracing::info!(
            origin = %PROFILE.host_id(),
            producer = PRODUCER,
            devices = ?devices,
            "management plane up"
        );

        let interval = std::time::Duration::from_millis(cfg.telemetry_interval_ms);
        for node in host.nodes() {
            let name = node.name().to_string();
            // Every device has an operational status, whatever moves its
            // bytes (#121); polled at the telemetry cadence, refreshed at
            // the state one.
            tasks.push(tokio::spawn(oper::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                host.clone(),
                name.clone(),
                oper::Source::of(node),
                cfg.ttl_s,
                interval,
            )));
            // And an identity (#122), polled at the state cadence: what it
            // is changes when a terminal is swapped, not every tick.
            tasks.push(tokio::spawn(identity::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                name.clone(),
                oper::Source::of(node),
                cfg.ttl_s,
            )));
            // And what it guarantees about the bytes it carries (I6): for
            // every device, because the subject is unconditional.
            tasks.push(tokio::spawn(security::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                name.clone(),
                oper::Source::of(node),
                cfg.ttl_s,
            )));
            // And, for a bearer that registers with a network, where it
            // stands with it (#123); silent for one that does not.
            tasks.push(tokio::spawn(radio::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                name.clone(),
                oper::Source::of(node),
                cfg.ttl_s,
            )));
            match node.plane() {
                Plane::Sdu(plane) => {
                    tasks.push(tokio::spawn(telemetry::publish_loop(
                        session.clone(),
                        PROFILE.local_origin(),
                        name,
                        telemetry::Source::Sdu(plane.clone()),
                        interval,
                    )));
                    // The events plane. Spawned like the other two and, unlike
                    // them, silent unless something happens — which is what
                    // `rate = "rare"` declares and what makes it affordable on
                    // a metered link.
                    tasks.push(tokio::spawn(events::publish_loop(
                        session.clone(),
                        PROFILE.local_origin(),
                        plane.clone(),
                    )));
                }
                Plane::Netdev(dev) => {
                    // No lanes, no scheduler, no medium: what a netdev has to
                    // say is its report, the kernel's counters (#130) and its
                    // faults, and nothing else is published for it — absent,
                    // never zero (#115). Its presence epoch cycles its token
                    // when the interface is re-enumerated or a counter is
                    // seen to go backwards (zenkey RFC 04 §5, v1.39).
                    tasks.push(tokio::spawn(presence_loop(
                        session.clone(),
                        ctx.device_alive_key(&name),
                        name.clone(),
                        dev.clone(),
                        device_alive.clone(),
                        interval,
                    )));
                    tasks.push(tokio::spawn(telemetry::publish_loop(
                        session.clone(),
                        PROFILE.local_origin(),
                        name.clone(),
                        telemetry::Source::Netdev(dev.clone()),
                        interval,
                    )));
                    // A radio with a neighbour table publishes it (#137);
                    // a netdev with no such notion has no loop to run.
                    if dev.destinations().is_some() {
                        tasks.push(tokio::spawn(destination::publish_loop(
                            session.clone(),
                            PROFILE.local_origin(),
                            name.clone(),
                            dev.clone(),
                            cfg.ttl_s,
                        )));
                    }
                    let dev: Arc<dyn modem_device::Device> = dev.clone();
                    tasks.push(tokio::spawn(events::publish_device_loop(
                        session.clone(),
                        PROFILE.local_origin(),
                        name,
                        dev,
                    )));
                }
            }
        }
        // Every action invocation is an event (#129).
        for state in &actions {
            tasks.push(tokio::spawn(action::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                state.clone(),
            )));
        }
        // The configuration echo (#125): the read-back, on transition QoS.
        for state in &configs {
            tasks.push(tokio::spawn(config::publish_loop(
                session.clone(),
                PROFILE.local_origin(),
                state.clone(),
                cfg.ttl_s,
            )));
        }
        // The registration document (zenkey RFC 04 §5): versions, and per
        // device the capability predicates that hold here (#122).
        tasks.push(tokio::spawn(sensor::publish_loop(
            session.clone(),
            PROFILE.local_origin(),
            host.clone(),
            cfg.ttl_s,
        )));
        for (plane, keys) in state_keys {
            tasks.push(tokio::spawn(state::publish_loop(
                session.clone(),
                keys,
                plane,
                cfg.ttl_s,
            )));
        }

        tasks.extend(provisional);

        Ok(Self {
            session,
            ctx,
            tasks,
            _alive: alive,
            _device_alive: device_alive,
        })
    }

    /// The session this plane runs on, for tests and for the RPC surface.
    pub fn session(&self) -> &Session {
        &self.session
    }

    /// The key context, for tests that need to spell a key.
    pub fn context(&self) -> &V1Context {
        &self.ctx
    }

    /// Stop publishing and withdraw presence.
    pub async fn shutdown(self) {
        for t in &self.tasks {
            t.abort();
        }
        // Dropping the token withdraws it; closing the session makes that
        // visible to the network promptly rather than at lease expiry.
        let _ = self.session.close().await;
    }
}

/// The key of a twin's token, if any daemon on this host already holds one.
///
/// A liveliness query with a short wait: the token is either on the router
/// now or it is not, and a daemon starting on a host with no router at all
/// waits out the timeout and proceeds — the lock files are the interlock.
async fn twin_alive(session: &Session, ctx: &V1Context) -> Option<String> {
    let key = ctx.alive_key();
    let replies = session
        .liveliness()
        .get(key.as_keyexpr())
        .timeout(std::time::Duration::from_secs(2))
        .await
        .ok()?;
    while let Ok(reply) = replies.recv_async().await {
        if let Ok(sample) = reply.result() {
            return Some(sample.key_expr().to_string());
        }
    }
    None
}

/// The management session's mode: as configured, or `client` when it only
/// connects and `peer` when it listens (#152).
fn session_mode(cfg: &MgmtConfig) -> anyhow::Result<String> {
    let mode = cfg.mode.clone().unwrap_or_else(|| {
        if cfg.listen.is_empty() && !cfg.connect.is_empty() {
            "client".to_string()
        } else {
            "peer".to_string()
        }
    });
    anyhow::ensure!(
        matches!(mode.as_str(), "client" | "peer" | "router"),
        "[management] mode {mode:?}: one of client, peer, router"
    );
    Ok(mode)
}

async fn open_session(cfg: &MgmtConfig) -> anyhow::Result<Session> {
    let mode = session_mode(cfg)?;
    let mut config = zenoh::Config::default();
    let list = |v: &[String]| {
        let items: Vec<String> = v.iter().map(|e| format!("{e:?}")).collect();
        format!("[{}]", items.join(","))
    };
    for (path, value) in [
        ("mode", format!("{mode:?}")),
        ("scouting/multicast/enabled", cfg.scouting.to_string()),
        ("connect/endpoints", list(&cfg.connect)),
        ("listen/endpoints", list(&cfg.listen)),
    ] {
        config
            .insert_json5(path, &value)
            .map_err(|e| anyhow::anyhow!("management session config {path}: {e}"))?;
    }
    if let Some(id) = &cfg.usrpwd {
        let password = std::fs::read_to_string(&id.password_file).with_context(|| {
            format!(
                "[management] usrpwd password_file {}",
                id.password_file.display()
            )
        })?;
        for (path, value) in [
            ("transport/auth/usrpwd/user", id.user.as_str()),
            (
                "transport/auth/usrpwd/password",
                password.trim_end_matches(['\n', '\r']),
            ),
        ] {
            config
                .insert_json5(path, &serde_json::to_string(value)?)
                .map_err(|e| anyhow::anyhow!("management session config {path}: {e}"))?;
        }
    }
    if mode != "client" {
        return zenoh::open(config)
            .await
            .map_err(|e| anyhow::anyhow!("{e}"));
    }
    // A Zenoh client cannot open without its router, and has no background
    // redial of its own. This loop is that redial: the supervisor's contract
    // is that start order does not matter (#96), and the daemon brings this
    // plane up behind its data path rather than waiting on it (#152).
    let mut backoff = std::time::Duration::from_secs(1);
    let mut said = false;
    loop {
        match zenoh::open(config.clone()).await {
            Ok(session) => return Ok(session),
            Err(e) => {
                if !said {
                    tracing::warn!(error = %e, "the management router is not reachable yet; retrying");
                    said = true;
                }
                tokio::time::sleep(backoff).await;
                backoff = (backoff * 2).min(std::time::Duration::from_secs(10));
            }
        }
    }
}

/// Cycle a netdev's presence token when its epoch moves (#130): drop the
/// token, which withdraws it, and declare it again. A reader that saw the
/// token go and come reads the counters under it as restarted, which the
/// registry sanctions and a counter that went backwards would otherwise
/// contradict.
async fn presence_loop(
    session: Session,
    key: zenkey::Key,
    device: String,
    dev: Arc<dyn modem_device::Netdev>,
    tokens: Arc<
        std::sync::Mutex<std::collections::BTreeMap<String, zenoh::liveliness::LivelinessToken>>,
    >,
    interval: std::time::Duration,
) {
    let mut seen = dev.epoch();
    loop {
        tokio::time::sleep(interval).await;
        let now = dev.epoch();
        if now == seen {
            continue;
        }
        seen = now;
        // Withdraw first, then re-declare: two declarations of one key would
        // leave the roster showing the device present throughout.
        drop(tokens.lock().expect("not poisoned").remove(&device));
        match session.liveliness().declare_token(key.as_keyexpr()).await {
            Ok(token) => {
                tokens
                    .lock()
                    .expect("not poisoned")
                    .insert(device.clone(), token);
                tracing::info!(device = %device, epoch = now, "the device's presence token cycled");
            }
            Err(e) => {
                tracing::warn!(device = %device, error = %e, "the device's presence token could not be re-declared");
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn cfg(connect: &[&str], listen: &[&str], mode: Option<&str>) -> MgmtConfig {
        MgmtConfig {
            connect: connect.iter().map(|s| (*s).to_string()).collect(),
            listen: listen.iter().map(|s| (*s).to_string()).collect(),
            mode: mode.map(str::to_string),
            ..MgmtConfig::default()
        }
    }

    #[test]
    fn a_session_that_only_connects_is_a_client_of_its_router() {
        // #152: a peer behind a gossip-less router is seen by nothing.
        let mode = session_mode(&cfg(&["tcp/127.0.0.1:7447"], &[], None)).unwrap();
        assert_eq!(mode, "client");
    }

    #[test]
    fn a_session_that_listens_is_a_peer_unless_told() {
        assert_eq!(
            session_mode(&cfg(&[], &["tcp/127.0.0.1:7447"], None)).unwrap(),
            "peer"
        );
        assert_eq!(
            session_mode(&cfg(&["tcp/a:1"], &["tcp/b:2"], None)).unwrap(),
            "peer",
            "a session that both connects and listens is not anybody's client"
        );
        assert_eq!(
            session_mode(&cfg(&["tcp/a:1"], &[], Some("peer"))).unwrap(),
            "peer",
            "an explicit mode wins"
        );
    }

    #[test]
    fn an_unknown_mode_is_refused() {
        let err = session_mode(&cfg(&["tcp/a:1"], &[], Some("hub"))).unwrap_err();
        assert!(err.to_string().contains("client, peer, router"), "{err}");
    }
}