modem-device 0.3.0

The seam between the zenoh-modem driver and a physical or simulated medium
Documentation

modem-device

The seam between the driver and a device: trait Device, trait Medium: Device and the types they speak in. Was modem-backend with one trait Backend until #117, which split the seam along the planes of docs/design/device-planes.md and changed no behaviour.

This crate deliberately depends on nothing but async-trait, thiserror and optional serde — and in particular no Zenoh and no tokio. CI holds the first with a dependency-graph guard, because the moment this could parse a key expression the second policy plane invariant I1 forbids would exist. The absence of tokio is why DeviceEvent is a plain struct rather than a channel: putting a watch::Receiver on the trait would drag a runtime into the crate whose entire job is to be the seam.

An out-of-tree backend needs this and nothing else. It is published together with modem-contract and modem-mgmt, one version for the three (#97); the history is in CHANGELOG.md.

What an implementor does first

  1. Pick the plane. A device whose bytes you carry is a Medium; a device whose bytes the kernel carries is a Netdev. Both are a Device.
  2. Implement the four required Medium methods (capabilities, send, recv, metrics) and say the truth in Capabilities: reliable only if the hardware never loses (I2), and the SDU sizes the frame really holds. send blocks to apply backpressure and never splits an SDU (I3, I4).
  3. Run the conformance kit from your own tests: conformance::device, and conformance::netdev for a netdev, then assert_clean. Passing it is what conforming means; udp-medium/tests/conformance.rs is a ten-line example.
  4. Then the defaulted methods, as the device has them: report, oper, identity, next_event, configuration, actions, close. A device that says nothing about itself is still a legitimate device.

Two things it must never do: retry on its own initiative (I1: there is no reset, and recovery is a restart, of the device or of the daemon), and publish a reading it does not have (an absent value, never a zero).

The traits

Device is what the management plane serves — every method defaulted, so a device that says nothing about itself is a legitimate device. Medium: Device is the SDU data plane: implementations own everything below the driver — framing on the air, vendor APIs, contact scheduling, radio state — and nothing above it. A device whose data plane is the kernel's is a Netdev: Device — it names its interface, and the lanes never see it (#118, #130).

Device method
report() defaulted Sync on purpose — answer from a cache, never from I/O (#49)
oper() defaulted RFC 2863's operational status, with a reason and whether it is recoverable (#121)
identity() defaulted RFC 8348's fields and the equipment identifier; never a subscriber's (#122, I5)
next_event() defaulted Edge-triggered: one Raised, one Cleared, never a repeat (#51)
close() defaulted Called once, on the way down (#50)
configuration() defaulted The configuration plane (config::Configure: schema, read-back, apply), None for a device with nothing to configure; the Iridium terminal and the LoRa simulator declare one (#125)
actions() defaulted Operator actions: explicit, costed, never scheduled (#129)
security() defaulted What the device guarantees about the bytes it carries, as SecurityProperties — never a boolean (I6, #164)
counters() defaulted Named counters beyond the fixed vocabulary; published only under subjects the registry declares (#157, #164)
Medium method
capabilities() required Read once at startup to size lanes
send(lane, sdu) required Must block rather than queue. Backpressure by not returning is what invariant I3 asks for
recv() required Returns the lane it arrived on, so the driver routes without inspecting the payload
metrics() required
configure_lanes(lanes) defaulted What lanes exist, so recv need not guess (#52)
Netdev method
interface() required The interface name, as the kernel spells it (#118)
statistics() defaulted The kernel's counters, RFC 8343's names where Linux keeps exactly that counter (#130)
epoch() defaulted The presence epoch: moves on a re-enumeration or a counter seen to decrease (#130)
destinations() defaulted The neighbours the radio reports it can reach, None for a device with no such notion (#137)

The defaults are why the conformance kit's decorator check exists: a decorator that forgets one no longer fails to compile, it silently answers for itself.

There is no reset, and that is a decision. A medium that reopened itself would need a policy for when to retry and when to give up, and a policy inside the driver is the second policy plane I1 forbids. Recovery is a restart, and next_event is what tells a supervisor to perform one.

Layers

A layer (#157, docs/design/sdu-layers.md) is what sits between the driver's scheduler and a Medium when a deployment wants encryption, a peer address on a shared channel, or fragmentation below Zenoh's handshake: the layer::Layer trait, a synchronous transform over opaque SDUs with no I/O of its own. One SDU going down becomes zero or more frames (encode), one frame coming up zero or more SDUs or a counted refusal (decode), time passing whatever its timers owe (tick, with the next deadline). It declares what it does to the capabilities below it, maps the lanes asked of it onto the lanes it asks below, says what it guarantees in SecurityProperties terms given what is below, and keeps counters under its own kind. The driver's Stack owns every piece of I/O around a stack of them and is the only Medium the scheduler sees; a layer never awaits, never owns a task or a socket, and is never a Medium. Instant is std::time::Instant, handed in, so a test drives a layer with a clock it advances by hand and this crate still links no tokio.

A layer is its own crate, [package.metadata.zenoh-modem] layer = true, behind a cargo feature of the driver, off by default. conformance::layer holds it to the rules below.

Implementors

In this workspace: fake-medium (the null cable, the simulator, the radio cell, and a netdev stub), sbd-medium, sbd-gateway, udp-medium, sx1262-medium, netdev-modem, dlep-modem and mm-modem. sbd-medium was the first to implement close and next_event for real.

Which types are #[non_exhaustive], and the rule

Since 0.3 (#164) the seam follows one rule, so that a new fact a device can state is not a breaking change for every device that cannot:

  • A struct an implementor constructs is #[non_exhaustive], with a constructor taking the facts every implementor has and self-returning setters for the rest. The fields stay pub, for reading and for assignment. Capabilities::new(..).arq(..).framing(..), Metrics::new().tx_sdus(..), NetdevStats::new().in_octets(..), Report::new().rssi(..), Counter::new(..), SecurityProperties::new(..).guarantee(..).
  • An enum a consumer must match exhaustively to stay correct is exhaustive on purpose. A new Duplex or a new Arq changes what every scheduler, simulator and reliability claim must do, and should break their builds (#97).
  • Freshness is the device's. A device withholds a reading it no longer trusts (returns None) rather than reporting it with an age; Report::age_ms is the age of the whole snapshot, which the management plane applies as one rule (STALE_AFTER). There is no per-reading age, and there will not be one until a device needs it.

Conformance

modem_device::conformance (#131) is the tests that kept this workspace's implementors honest, with the medium taken out, so an implementor written elsewhere runs them from its own suite. Every check returns the Failures it found rather than panicking — the kit's own tests hand it one deliberately broken implementor per check — and assert_clean is the one-line form:

let mut f = conformance::device(&my_device, tokio::time::sleep(window)).await;
f.extend(conformance::netdev(&my_device, 3, || tokio::time::sleep(poll)).await);
conformance::assert_clean("MyDevice", &f);
Check What it holds a device to
device_decorator_forwards, medium_decorator_forwards, netdev_decorator_forwards every method of the trait reaches the wrapped device and its answer comes back unchanged
core report, oper, identity agree across two calls; a report with a reading says its age
events_are_edge_triggered the same words with the same edge twice in a row is a repeat, not an edge
schema_is_valid, effective_within_schema names that can be spelled in a key, bounds that do not cross, a read-back inside the schema, no sensitive value in it
contract_refused a contract group answers ConfigError::Contract, naming the restart
read_back_and_undo after apply, effective shows the change; after the Undo, the previous values
sensitive_never_read_back a value written to a sensitive parameter is in no read-back and no Debug
netdev within one presence epoch no counter goes backwards
layer::layer, layer::pair a layer, or a pair of them (directional keys, addresses): a round trip is the identity; the declared overhead is the observed one at every size; a flipped bit and a truncation are refused where integrity is claimed, a repeat where anti-replay is, and every refusal moves a counter; a deadline announced is kept and nothing is owed unannounced; counters are scoped by kind; an SDU sent on a lane arrives on the matching lane. Synchronous, no runtime; with the reference layers Identity, Overhead, Split (#157)

Nothing here needs a runtime: the timed checks take a deadline or a tick future from the caller. What the kit cannot check is that the sync methods do no I/O; it checks what follows from the contract instead. The wire-level half — against a running plane — is modem_mgmt::conformance.

Where the rules are

Descriptive; ../docs/architecture.md is normative — §4.8 for the seam, §2 for the invariants the doc comments cite by number.