# 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`](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 `Failure`s 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:
```rust,ignore
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.