modem_contract/lib.rs
1//! The management-plane contract of zenoh-modem (#119): the registry, its
2//! payload types, and the schemas `describe` serves — compiled once, for
3//! every driver that serves it.
4//!
5//! No Zenoh runtime. `zenkey` is linked without its `zenoh` feature, so what
6//! is here is the key grammar, the registry slice type and the RFC 08 §7
7//! schema envelope: pure data. A driver that links this crate — this
8//! repository's, or one for a device the kernel drives — gets the contract
9//! and nothing that could open a session; `modem-mgmt` is where the session
10//! is.
11//!
12//! Nothing here knows how a value is produced. `LinkState::of` and its
13//! siblings take the facts, not the driver, which is what lets a second
14//! driver serve the same documents from a different plane.
15
16use zenkey::{AppName, AppProfile, OriginSalt};
17
18pub mod config;
19pub mod documents;
20
21/// The zenkey this contract was compiled against, as `Cargo.lock` pins it —
22/// read by `build.rs`, published in `state/modem/sensor` (#122).
23pub const ZENKEY_VERSION: &str = env!("ZENKEY_VERSION");
24pub mod schema;
25
26/// Typed key builders generated from `registry/` by `zenkey-build`.
27///
28/// The registry is the management plane's contract, linted at build time and
29/// served verbatim by `@rpc/modem/introspect`, so what a consumer reads is
30/// literally what the build enforced.
31// Generated code is not ours to lint: it is regenerated from the registry
32// on every build, so a warning here is not actionable.
33#[allow(dead_code, unused_imports, clippy::all)]
34pub mod registry {
35 include!(concat!(env!("OUT_DIR"), "/zenkey_registry.rs"));
36}
37
38/// The application identity every key is minted under.
39///
40/// A `static` because `AppProfile::local_origin` takes `&'static self` — the
41/// origin is cached in a `OnceLock` and handed out by reference, so the profile
42/// has to outlive every key built from it.
43///
44/// The salt is an application constant, compiled in, identical across every
45/// deployment. Changing it re-keys every fleet.
46///
47/// The two arguments are newtypes since zenkey 0.7, which is worth more here
48/// than it looks: they are both `&'static str`, they are adjacent, and
49/// transposing them would have compiled and silently re-keyed the fleet.
50pub static PROFILE: AppProfile = AppProfile::new(
51 AppName::new("zenoh-modem"),
52 OriginSalt::new("zenoh-modem-host-id-v1"),
53);
54
55/// The producer name every driver of this contract publishes under.
56///
57/// Not the device. The origin is the *host* and the producer is the *component*
58/// — the modem itself is a subject chunk, because zenkey RFC 12 §2 decided
59/// device-origins never, and because a host may carry more than one device.
60pub const PRODUCER: &str = "modem";