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
//! The `@rpc` surface: the driver's whole admin API.
//!
//! This replaces the withdrawn ICD's HELLO/capability exchange and its two
//! snapshot protocols, and the difference is not cosmetic. A handshake answers
//! once, to one party, at a moment that party had to be present for. A
//! queryable answers whoever asks, whenever they ask, including a tool that
//! started an hour later — which is the ordinary case for an operator
//! diagnosing a link that is already misbehaving.
//!
//! `introspect` replies with the registry TOML verbatim (RFC 08 §6), which is
//! the same text `zenkey-build` linted at compile time. That is the honest
//! version of capability negotiation: the contract a consumer reads is
//! literally the contract the build enforced.

use std::sync::Arc;

use anyhow::Context as _;
use modem_contract::registry::modem as reg;
use zenoh::Session;

use crate::host::{Host, Plane};
use crate::plane::SduPlane;

/// A queryable with Zenoh's default handler, spelled once.
type Qbl = zenoh::query::Queryable<zenoh::handlers::FifoChannelHandler<zenoh::query::Query>>;

/// Declare every procedure this driver serves, and start answering.
///
/// **Every declaration is awaited before this returns**, and that ordering is
/// the whole of #42. `Mgmt::start` declares the liveliness token after this,
/// so by the time a roster shows this producer the queryables are on the
/// network and a tool that asks immediately gets an answer. Before, `serve`
/// spawned three tasks and each declared inside its own — so `alive` was true
/// while `introspect` returned nothing, and a declaration that *failed* logged
/// and returned while the token stayed held for ever.
///
/// A failure here is an ordinary startup error for the same reason
/// `schema::verify_total` is: RFC 08 §6.1 says an implementation must not
/// report itself alive while what it declares and what it serves disagree, and
/// refusing to start is the only honest response to a producer that cannot
/// answer.
///
/// Returns the answering tasks; dropping them withdraws the declarations.
pub(super) async fn serve(
    session: Session,
    host: Arc<Host>,
    configs: &[Arc<crate::config::ConfigState>],
    actions: &[Arc<crate::action::ActionState>],
) -> anyhow::Result<Vec<tokio::task::JoinHandle<()>>> {
    // Built by the generated registry rather than spelled here. Two things
    // follow: the builders are infallible, because every chunk was validated
    // when the registry was linted; and a procedure served here is one the
    // registry declares, by construction. The three `&["..."]` arrays these
    // replace had to be *trusted* to match the contract instead.
    let origin = super::PROFILE.local_origin();

    let introspect_key = reg::introspect_key(&origin);
    let introspect_qbl = declare(&session, &introspect_key).await?;

    let describe_key = reg::describe_key(&origin);
    let describe_qbl = declare(&session, &describe_key).await?;

    let mut tasks = vec![
        tokio::spawn(introspect(introspect_qbl, introspect_key)),
        tokio::spawn(describe(describe_qbl, describe_key)),
    ];

    // The device is a path chunk, not a selector parameter: sub-host authority
    // ("this principal may configure rf0 but not sat0") is only expressible if
    // the actuated resource is in the path (zenkey RFC 09 §3). Concrete rather
    // than `rpc_serve_key`'s wildcard, so this daemon answers for the devices
    // it owns and stays silent about one it does not — and one key per device
    // (#118), because the host serves every device on it.
    //
    // A netdev has no lanes, and its `lanes` is declared all the same: RFC 08
    // §6.1 says a procedure that exists only on some devices is declared
    // regardless and answers `error/gated` where its predicate is false, so a
    // caller learns *why* rather than hearing silence. #124 writes the
    // predicate into the registry as `when`; the answer is the same.
    for node in host.nodes() {
        // The configuration plane (RFC 05 §5.1), declared for every device:
        // the read answers the read-back for a device that declares a
        // configuration resource (#125) and `error/gated` for one that does
        // not; the writes answer `error/gated` until #126. The keys are
        // settled with the keyspace (#120), the behaviour arrives with the
        // devices that have it.
        let read_key = reg::config_device_key(&origin, node.name());
        let read_qbl = declare(&session, &read_key).await?;
        tasks.push(
            match configs.iter().find(|c| c.device == node.name()).cloned() {
                Some(state) => tokio::spawn(config_read(read_qbl, read_key, state)),
                None => tokio::spawn(gated(
                    read_qbl,
                    "config",
                    Some(node.name().to_string()),
                    "config",
                )),
            },
        );
        // The confirmed commit's three verbs (#127), real for a device with
        // a configuration plane.
        let state = configs.iter().find(|c| c.device == node.name()).cloned();
        for (key, verb) in [
            (
                reg::config_device_confirm_key(&origin, node.name()),
                "confirm",
            ),
            (
                reg::config_device_cancel_key(&origin, node.name()),
                "cancel",
            ),
            (
                reg::config_device_extend_key(&origin, node.name()),
                "extend",
            ),
        ] {
            let qbl = declare(&session, &key).await?;
            tasks.push(match state.clone() {
                Some(state) => tokio::spawn(config_control(qbl, key, state, verb)),
                None => tokio::spawn(gated(qbl, verb, Some(node.name().to_string()), "config")),
            });
        }
        // `persist` (#128), on its own key so an ACL can deny it alone.
        let persist_key = reg::config_device_persist_key(&origin, node.name());
        let persist_qbl = declare(&session, &persist_key).await?;
        tasks.push(match state.clone() {
            Some(state) => tokio::spawn(config_control(persist_qbl, persist_key, state, "persist")),
            None => tokio::spawn(gated(
                persist_qbl,
                "persist",
                Some(node.name().to_string()),
                "config",
            )),
        });
        let lanes_key = reg::device_device_sdu_lanes_key(&origin, node.name());
        let lanes_qbl = declare(&session, &lanes_key).await?;
        tasks.push(match node.plane() {
            Plane::Sdu(plane) => tokio::spawn(lanes(lanes_qbl, lanes_key, plane.clone())),
            Plane::Netdev(_) => tokio::spawn(gated(
                lanes_qbl,
                "lanes",
                Some(node.name().to_string()),
                "sdu",
            )),
        });
    }
    // `config/{device}/{group}/set` has a variable the host cannot enumerate,
    // so it is served on the wildcard selector the registry generates for a
    // procedure's own queryable, and the device is read off each query's key.
    let set_selector = reg::rpc_serve_key(&origin, reg::ProcedureId::ConfigDeviceGroupSet);
    let set_qbl = session
        .declare_queryable(set_selector.as_keyexpr())
        .await
        .map_err(|e| anyhow::anyhow!("{e}"))
        .with_context(|| format!("declare queryable {set_selector}"))?;
    tasks.push(tokio::spawn(config_set(
        set_qbl,
        origin.clone(),
        configs.to_vec(),
    )));
    // `device/{device}/action/{name}` (#129): the same shape, the same guards.
    let action_selector = reg::rpc_serve_key(&origin, reg::ProcedureId::DeviceDeviceActionName);
    let action_qbl = session
        .declare_queryable(action_selector.as_keyexpr())
        .await
        .map_err(|e| anyhow::anyhow!("{e}"))
        .with_context(|| format!("declare queryable {action_selector}"))?;
    tasks.push(tokio::spawn(action_run(
        action_qbl,
        origin.clone(),
        actions.to_vec(),
    )));
    Ok(tasks)
}

/// `device/{device}/action/{name}` (#129): the concrete key or nothing, the
/// device's own list, the startup allowlist, one at a time, the minimum
/// interval, the arguments — then the device, and the reply is what it did
/// and what it cost. Every call is an event, refused or not.
async fn action_run(
    qbl: Qbl,
    origin: zenkey::origin::LocalOrigin,
    actions: Vec<Arc<crate::action::ActionState>>,
) {
    while let Ok(query) = qbl.recv_async().await {
        let chunks: Vec<&str> = query.key_expr().as_str().split('/').collect();
        let at = chunks.iter().position(|c| *c == "device");
        let (device, name) = match at {
            Some(i) if chunks.len() > i + 3 && chunks[i + 2] == "action" => {
                (chunks[i + 1].to_string(), chunks[i + 3].to_string())
            }
            _ => {
                refuse(
                    &query,
                    "error/invalid-args",
                    "the key is not device/{device}/action/{name}",
                )
                .await;
                continue;
            }
        };
        let own = reg::device_device_action_name_key(&origin, &device, &name);
        if let Err(e) = zenkey::require_exact(query.key_expr(), own.as_keyexpr()) {
            refuse(&query, "error/fanout-forbidden", &e.to_string()).await;
            continue;
        }
        let Some(state) = actions.iter().find(|a| a.device == device) else {
            refuse(
                &query,
                "error/gated",
                &format!(
                    "action needs capability:actions, which device {device:?} does not have \
                     (RFC 08 §6.1)"
                ),
            )
            .await;
            continue;
        };
        let request: super::ActionRequest = match query
            .payload()
            .map(|p| p.try_to_string().map(|s| s.into_owned()))
            .transpose()
        {
            Ok(Some(body)) if !body.trim().is_empty() => match serde_json::from_str(&body) {
                Ok(r) => r,
                Err(e) => {
                    refuse(
                        &query,
                        "error/invalid-args",
                        &format!("the request did not parse: {e}"),
                    )
                    .await;
                    continue;
                }
            },
            _ => super::ActionRequest::default(),
        };
        let who = crate::config::Attribution {
            actor: query.parameters().get("actor").map(str::to_string),
            request_id: query.parameters().get("request_id").map(str::to_string),
            claimed_source: None,
        };
        match state.invoke(&name, request.arguments, who).await {
            Ok(reply) => {
                let r = query
                    .reply(own.as_keyexpr(), reply)
                    .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
                if let Err(e) = r.await {
                    tracing::debug!(error = %e, "action reply failed");
                }
            }
            Err(refusal) => refuse(&query, &refusal.error, &refusal.message).await,
        }
    }
}

/// `config/{device}/{group}/set` (#126): the server's own guards, in the
/// order RFC 05 §5.1 lists them, and the read-back as the reply.
///
/// Served on the wildcard selector, so a query whose key is not this
/// device's concrete key reaches here — and is refused first of all
/// (`error/fanout-forbidden`, RFC 05 §2.1): the ACL cannot filter a wildcard
/// (#113), and a write that answered one would be the fan-out the
/// convention forbids.
async fn config_set(
    qbl: Qbl,
    origin: zenkey::origin::LocalOrigin,
    configs: Vec<Arc<crate::config::ConfigState>>,
) {
    while let Ok(query) = qbl.recv_async().await {
        let chunks: Vec<&str> = query.key_expr().as_str().split('/').collect();
        let at = chunks.iter().position(|c| *c == "config");
        let (device, group) = match at {
            Some(i) if chunks.len() > i + 3 && chunks[i + 3] == "set" => {
                (chunks[i + 1].to_string(), chunks[i + 2].to_string())
            }
            _ => {
                refuse(
                    &query,
                    "error/invalid-args",
                    "the key is not config/{device}/{group}/set",
                )
                .await;
                continue;
            }
        };
        // 1. The concrete key, or nothing.
        let own = reg::config_device_group_set_key(&origin, &device, &group);
        if let Err(e) = zenkey::require_exact(query.key_expr(), own.as_keyexpr()) {
            refuse(&query, "error/fanout-forbidden", &e.to_string()).await;
            continue;
        }
        let Some(state) = configs.iter().find(|c| c.device == device) else {
            refuse(
                &query,
                "error/gated",
                &format!(
                    "set needs capability:config, which device {device:?} does not have (RFC 08 \
                     §6.1)"
                ),
            )
            .await;
            continue;
        };
        let change: zenkey::config::ConfigChange = match query
            .payload()
            .map(|p| p.try_to_string().map(|s| s.into_owned()))
            .transpose()
        {
            Ok(Some(body)) => match serde_json::from_str(&body) {
                Ok(c) => c,
                Err(e) => {
                    refuse(
                        &query,
                        "error/invalid-args",
                        &format!("the change did not parse: {e}"),
                    )
                    .await;
                    continue;
                }
            },
            _ => {
                refuse(
                    &query,
                    "error/invalid-args",
                    "a set carries a change request as its body",
                )
                .await;
                continue;
            }
        };
        let who = crate::config::Attribution {
            actor: query.parameters().get("actor").map(str::to_string),
            request_id: query.parameters().get("request_id").map(str::to_string),
            claimed_source: query.source_info().map(|s| format!("{:?}", s.source_id())),
        };
        match state.set(&group, change, who).await {
            Ok(reply) => {
                let r = query
                    .reply(own.as_keyexpr(), reply)
                    .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
                if let Err(e) = r.await {
                    tracing::debug!(error = %e, "set reply failed");
                }
            }
            Err(refusal) => refuse(&query, &refusal.error, &refusal.message).await,
        }
    }
}

/// `config/{device}/{confirm,cancel,extend}` (#127): the pending change's
/// token, and for `extend` the new window; the reply is the read-back.
async fn config_control(
    qbl: Qbl,
    key: zenkey::Key,
    state: Arc<crate::config::ConfigState>,
    verb: &'static str,
) {
    while let Ok(query) = qbl.recv_async().await {
        let request: zenkey::config::ControlRequest = match query
            .payload()
            .map(|p| p.try_to_string().map(|s| s.into_owned()))
            .transpose()
        {
            Ok(Some(body)) => match serde_json::from_str(&body) {
                Ok(r) => r,
                Err(e) => {
                    refuse(
                        &query,
                        "error/invalid-args",
                        &format!("the control request did not parse: {e}"),
                    )
                    .await;
                    continue;
                }
            },
            _ => {
                refuse(
                    &query,
                    "error/invalid-args",
                    &format!("{verb} carries the pending change's token as its body"),
                )
                .await;
                continue;
            }
        };
        let outcome = match verb {
            "confirm" => state.confirm(&request).await,
            "cancel" => state.cancel(&request).await,
            "persist" => state.persist(&request).await,
            _ => state.extend(&request).await,
        };
        match outcome {
            Ok(reply) => {
                let r = query
                    .reply(key.as_keyexpr(), reply)
                    .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
                if let Err(e) = r.await {
                    tracing::debug!(error = %e, "{verb} reply failed");
                }
            }
            Err(refusal) => refuse(&query, &refusal.error, &refusal.message).await,
        }
    }
}

async fn refuse(query: &zenoh::query::Query, error: &str, message: &str) {
    let envelope = crate::config::Refusal::new(error, message).envelope();
    let reply = query
        .reply_err(envelope)
        .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
    if let Err(e) = reply.await {
        tracing::debug!(error = %e, "{error} reply failed");
    }
}

/// Answer every query with `error/gated`, naming the predicate (RFC 08 §6.1).
///
/// The error envelope is RFC 05 §3's: `{error, message}`, on `reply_err`, so
/// a caller can branch on the name and an operator can read the reason.
///
/// `device` is the node the queryable was declared for, or `None` for a
/// queryable on a wildcard selector, where it is read off the query's key —
/// the chunk after `config` or `device`.
async fn gated(
    qbl: Qbl,
    procedure: &'static str,
    device: Option<String>,
    capability: &'static str,
) {
    while let Ok(query) = qbl.recv_async().await {
        let device = device.clone().unwrap_or_else(|| {
            let chunks: Vec<&str> = query.key_expr().as_str().split('/').collect();
            chunks
                .iter()
                .position(|c| *c == "config" || *c == "device")
                .and_then(|i| chunks.get(i + 1))
                .map_or_else(|| "?".to_string(), |d| (*d).to_string())
        });
        let envelope = serde_json::json!({
            "error": "error/gated",
            "message": format!(
                "{procedure} needs capability:{capability}, which device {device:?} does not \
                 have (RFC 08 §6.1)"
            ),
        });
        let reply = query
            .reply_err(envelope.to_string())
            .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
        if let Err(e) = reply.await {
            tracing::debug!(error = %e, "gated reply failed");
        }
    }
}

async fn declare(session: &Session, key: &zenkey::Key) -> anyhow::Result<Qbl> {
    session
        .declare_queryable(key.as_keyexpr())
        .await
        .map_err(|e| anyhow::anyhow!("{e}"))
        .with_context(|| format!("declare queryable {key}"))
}

async fn introspect(qbl: Qbl, key: zenkey::Key) {
    // A `read` procedure, so it must never have side effects and must be safe
    // to call repeatedly — which is why it is declared idempotent in the
    // registry and answers from a compile-time constant.
    while let Ok(query) = qbl.recv_async().await {
        // The file as written, declared in the spelling it is written in
        // (RFC 08 §6, v1.44): `application/toml` today, and it follows the
        // file if the registry ever moves to KDL.
        let reply = query
            .reply(key.as_keyexpr(), reg::REGISTRY_SOURCE)
            .encoding(zenoh::bytes::Encoding::from(reg::REGISTRY_ENCODING));
        if let Err(e) = reply.await {
            tracing::debug!(error = %e, "introspect reply failed");
        }
    }
}

/// Every payload type this producer serves, described (RFC 08 §7).
///
/// The sibling of `introspect`, and the difference between them is the point:
/// `introspect` says what this driver serves, `describe` says what those
/// payloads are. Without it a generic tool can see that a sample claims to be a
/// `Counter` and cannot check that it is one.
///
/// The key is `registry::modem::describe_key`, generated from the registry
/// entry rather than spelled here. It used to be `ctx.rpc_key(&["describe"])`
/// with a note that zenkey ships no `describe_key()` helper — true of the
/// library, and beside the point: `zenkey-build` generates one per declared
/// procedure, and this crate had been ignoring them.
async fn describe(qbl: Qbl, key: zenkey::Key) {
    // A `read` procedure, answered from a value built once at startup: the
    // schemas cannot change while the process runs, and re-rendering them per
    // query would be work on a path an operator may hit repeatedly.
    while let Ok(query) = qbl.recv_async().await {
        let reply = query
            .reply(key.as_keyexpr(), modem_contract::schema::describe_json())
            .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
        if let Err(e) = reply.await {
            tracing::debug!(error = %e, "describe reply failed");
        }
    }
}

/// `config/{device}` (#125): the read-back, as the convention spells it
/// (zenkey RFC 05 §5.1) — the schema, every non-sensitive value with where
/// it came from and what it was at start, the revision, and any pending
/// change once #127 has one.
async fn config_read(qbl: Qbl, key: zenkey::Key, state: Arc<crate::config::ConfigState>) {
    while let Ok(query) = qbl.recv_async().await {
        let payload = match serde_json::to_string(&state.view()) {
            Ok(p) => p,
            Err(e) => {
                tracing::error!(error = %e, "the configuration view did not serialize");
                continue;
            }
        };
        let reply = query
            .reply(key.as_keyexpr(), payload)
            .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
        if let Err(e) = reply.await {
            tracing::debug!(error = %e, "config reply failed");
        }
    }
}

async fn lanes(qbl: Qbl, key: zenkey::Key, plane: Arc<dyn SduPlane>) {
    while let Ok(query) = qbl.recv_async().await {
        let table = super::LaneTable::of(
            plane.device(),
            &plane.capabilities(),
            plane
                .lanes()
                .iter()
                .map(|l| super::Lane::of(&l.key, &l.path, l.connected, l.backlog_bytes))
                .collect(),
        );
        let payload = match serde_json::to_string(&table) {
            Ok(p) => p,
            Err(e) => {
                tracing::error!(error = %e, "lane table did not serialize");
                continue;
            }
        };
        let reply = query
            .reply(key.as_keyexpr(), payload)
            .encoding(zenoh::bytes::Encoding::APPLICATION_JSON);
        if let Err(e) = reply.await {
            tracing::debug!(error = %e, "lanes reply failed");
        }
    }
}