use std::fmt;
pub mod action;
pub mod config;
pub mod conformance;
pub use action::Actions;
pub use config::Configure;
pub const LENGTH_PREFIX: usize = 2;
pub type Sdu = Vec<u8>;
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct EndpointId(String);
impl EndpointId {
pub fn new(name: impl Into<String>) -> Self {
Self(name.into())
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for EndpointId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct LaneKey {
pub endpoint: EndpointId,
pub reliable: bool,
pub rank: u8,
}
impl fmt::Display for LaneKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{}/{}#{}",
self.endpoint,
if self.reliable { "rel" } else { "be" },
self.rank
)
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
pub enum Duplex {
#[default]
Full,
Half,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Capabilities {
pub tx_max_sdu: u16,
pub rx_max_sdu: u16,
pub duplex: Duplex,
pub reliable: bool,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Metrics {
pub tx_sdus: u64,
pub tx_bytes: u64,
pub rx_sdus: u64,
pub rx_bytes: u64,
pub dropped: u64,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct Report {
pub age_ms: Option<u64>,
pub time_on_air_ms: Option<u64>,
pub retransmits: Option<u64>,
pub bytes_wasted: Option<u64>,
pub rx_errors: Option<u64>,
pub duty_cycle: Option<DutyCycle>,
pub signal_bars: Option<u8>,
pub rssi: Option<i32>,
pub rsrp: Option<i32>,
pub rsrq: Option<i32>,
pub snr: Option<i32>,
pub error_rate: Option<i32>,
pub rx_rate: Option<u64>,
pub tx_rate: Option<u64>,
pub rx_max_rate: Option<u64>,
pub tx_max_rate: Option<u64>,
pub latency: Option<u64>,
pub resources: Option<i32>,
pub rx_quality: Option<i32>,
pub tx_quality: Option<i32>,
pub registration: Option<Registration>,
pub access_technology: Option<AccessTechnology>,
}
impl Report {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn age_ms(mut self, ms: u64) -> Self {
self.age_ms = Some(ms);
self
}
#[must_use]
pub fn time_on_air_ms(mut self, ms: u64) -> Self {
self.time_on_air_ms = Some(ms);
self
}
#[must_use]
pub fn retransmits(mut self, n: u64) -> Self {
self.retransmits = Some(n);
self
}
#[must_use]
pub fn bytes_wasted(mut self, n: u64) -> Self {
self.bytes_wasted = Some(n);
self
}
#[must_use]
pub fn rx_errors(mut self, n: u64) -> Self {
self.rx_errors = Some(n);
self
}
#[must_use]
pub fn duty_cycle(mut self, duty: DutyCycle) -> Self {
self.duty_cycle = Some(duty);
self
}
#[must_use]
pub fn signal_bars(mut self, bars: u8) -> Self {
self.signal_bars = Some(bars);
self
}
#[must_use]
pub fn rssi(mut self, milli_dbm: i32) -> Self {
self.rssi = Some(milli_dbm);
self
}
#[must_use]
pub fn rsrp(mut self, milli_dbm: i32) -> Self {
self.rsrp = Some(milli_dbm);
self
}
#[must_use]
pub fn rsrq(mut self, milli_db: i32) -> Self {
self.rsrq = Some(milli_db);
self
}
#[must_use]
pub fn snr(mut self, milli_db: i32) -> Self {
self.snr = Some(milli_db);
self
}
#[must_use]
pub fn error_rate(mut self, milli_percent: i32) -> Self {
self.error_rate = Some(milli_percent);
self
}
#[must_use]
pub fn rx_rate(mut self, bps: u64) -> Self {
self.rx_rate = Some(bps);
self
}
#[must_use]
pub fn tx_rate(mut self, bps: u64) -> Self {
self.tx_rate = Some(bps);
self
}
#[must_use]
pub fn rx_max_rate(mut self, bps: u64) -> Self {
self.rx_max_rate = Some(bps);
self
}
#[must_use]
pub fn tx_max_rate(mut self, bps: u64) -> Self {
self.tx_max_rate = Some(bps);
self
}
#[must_use]
pub fn latency(mut self, us: u64) -> Self {
self.latency = Some(us);
self
}
#[must_use]
pub fn resources(mut self, milli_percent: i32) -> Self {
self.resources = Some(milli_percent);
self
}
#[must_use]
pub fn rx_quality(mut self, milli_percent: i32) -> Self {
self.rx_quality = Some(milli_percent);
self
}
#[must_use]
pub fn tx_quality(mut self, milli_percent: i32) -> Self {
self.tx_quality = Some(milli_percent);
self
}
#[must_use]
pub fn registration(mut self, r: Registration) -> Self {
self.registration = Some(r);
self
}
#[must_use]
pub fn access_technology(mut self, t: AccessTechnology) -> Self {
self.access_technology = Some(t);
self
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Registration {
Idle,
Home,
Searching,
Denied,
Roaming,
Unknown,
}
impl Registration {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Idle => "idle",
Self::Home => "home",
Self::Searching => "searching",
Self::Denied => "denied",
Self::Roaming => "roaming",
Self::Unknown => "unknown",
}
}
}
impl fmt::Display for Registration {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum AccessTechnology {
Gsm,
Gprs,
Edge,
Umts,
Hspa,
Lte,
Nr5g,
Iridium,
}
impl AccessTechnology {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Gsm => "gsm",
Self::Gprs => "gprs",
Self::Edge => "edge",
Self::Umts => "umts",
Self::Hspa => "hspa",
Self::Lte => "lte",
Self::Nr5g => "5gnr",
Self::Iridium => "iridium",
}
}
}
impl fmt::Display for AccessTechnology {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct DutyCycle {
pub available: bool,
pub next_available_in_ms: u64,
}
impl DutyCycle {
#[must_use]
pub fn ready() -> Self {
Self {
available: true,
next_available_in_ms: 0,
}
}
#[must_use]
pub fn wait_ms(ms: u64) -> Self {
Self {
available: false,
next_available_in_ms: ms,
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct DeviceEvent {
pub lane: Option<LaneKey>,
pub edge: Edge,
pub detail: String,
}
impl DeviceEvent {
#[must_use]
pub fn raised(detail: impl Into<String>) -> Self {
Self {
lane: None,
edge: Edge::Raised,
detail: detail.into(),
}
}
#[must_use]
pub fn cleared(detail: impl Into<String>) -> Self {
Self {
lane: None,
edge: Edge::Cleared,
detail: detail.into(),
}
}
#[must_use]
pub fn on_lane(mut self, lane: LaneKey) -> Self {
self.lane = Some(lane);
self
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Edge {
Raised,
Cleared,
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum DeviceError {
#[error(
"sdu of {got} bytes exceeds the medium's tx_max_sdu of {max}: \
lower zenoh's batch_size to at most {} (architecture I4, §4.5)", *max as usize + 2
)]
SduTooLarge { got: usize, max: u16 },
#[error("unknown lane {0} (architecture §4.1)")]
UnknownLane(LaneKey),
#[error("medium cannot transmit at present")]
TxUnavailable,
#[error("medium is closed")]
Closed,
#[error("medium error: {0}")]
Device(String),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum OperState {
Up,
Down,
NotPresent,
Unknown,
}
impl OperState {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Up => "up",
Self::Down => "down",
Self::NotPresent => "notPresent",
Self::Unknown => "unknown",
}
}
}
impl fmt::Display for OperState {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum AdminState {
#[default]
Up,
Down,
}
impl AdminState {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Up => "up",
Self::Down => "down",
}
}
}
impl fmt::Display for AdminState {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct OperStatus {
pub status: OperState,
pub admin: AdminState,
pub reason: Option<String>,
pub recoverable: bool,
pub since: Option<std::time::SystemTime>,
}
impl Default for OperStatus {
fn default() -> Self {
Self::unknown()
}
}
impl OperStatus {
fn with(status: OperState, reason: Option<String>, recoverable: bool) -> Self {
Self {
status,
admin: AdminState::Up,
reason,
recoverable,
since: None,
}
}
#[must_use]
pub fn unknown() -> Self {
Self::with(OperState::Unknown, None, true)
}
#[must_use]
pub fn up() -> Self {
Self::with(OperState::Up, None, true)
}
#[must_use]
pub fn down(reason: impl Into<String>, recoverable: bool) -> Self {
Self::with(OperState::Down, Some(reason.into()), recoverable)
}
#[must_use]
pub fn not_present(reason: impl Into<String>) -> Self {
Self::with(OperState::NotPresent, Some(reason.into()), false)
}
#[must_use]
pub fn since(mut self, at: std::time::SystemTime) -> Self {
self.since = Some(at);
self
}
#[must_use]
pub fn admin(mut self, admin: AdminState) -> Self {
self.admin = admin;
self
}
#[must_use]
pub fn is_up(&self) -> bool {
self.status == OperState::Up
}
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct Identity {
pub mfg_name: Option<String>,
pub model_name: Option<String>,
pub serial_num: Option<String>,
pub hardware_rev: Option<String>,
pub firmware_rev: Option<String>,
pub software_rev: Option<String>,
pub imei: Option<String>,
}
impl Identity {
#[must_use]
pub fn unknown() -> Self {
Self::default()
}
#[must_use]
pub fn is_empty(&self) -> bool {
*self == Self::default()
}
fn set(mut self, field: fn(&mut Self) -> &mut Option<String>, v: impl Into<String>) -> Self {
*field(&mut self) = Some(v.into());
self
}
#[must_use]
pub fn mfg_name(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.mfg_name, v)
}
#[must_use]
pub fn model_name(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.model_name, v)
}
#[must_use]
pub fn serial_num(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.serial_num, v)
}
#[must_use]
pub fn hardware_rev(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.hardware_rev, v)
}
#[must_use]
pub fn firmware_rev(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.firmware_rev, v)
}
#[must_use]
pub fn software_rev(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.software_rev, v)
}
#[must_use]
pub fn imei(self, v: impl Into<String>) -> Self {
self.set(|i| &mut i.imei, v)
}
}
#[async_trait::async_trait]
pub trait Device: Send + Sync {
fn report(&self) -> Report {
Report::default()
}
fn oper(&self) -> OperStatus {
OperStatus::default()
}
fn identity(&self) -> Identity {
Identity::default()
}
async fn next_event(&self) -> Result<DeviceEvent, DeviceError> {
std::future::pending().await
}
async fn close(&self) -> Result<(), DeviceError> {
Ok(())
}
fn configuration(&self) -> Option<&dyn Configure> {
None
}
fn actions(&self) -> Option<&dyn Actions> {
None
}
}
#[async_trait::async_trait]
pub trait Medium: Device {
fn capabilities(&self) -> Capabilities;
async fn send(&self, lane: &LaneKey, sdu: &[u8]) -> Result<(), DeviceError>;
async fn recv(&self) -> Result<(LaneKey, Sdu), DeviceError>;
fn metrics(&self) -> Metrics;
async fn configure_lanes(&self, lanes: &[LaneKey]) -> Result<(), DeviceError> {
let _ = lanes;
Ok(())
}
}
pub trait Netdev: Device {
fn interface(&self) -> &str;
fn statistics(&self) -> NetdevStats {
NetdevStats::default()
}
fn epoch(&self) -> u64 {
0
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct NetdevStats {
pub in_octets: Option<u64>,
pub out_octets: Option<u64>,
pub in_errors: Option<u64>,
pub out_errors: Option<u64>,
pub in_discards: Option<u64>,
pub out_discards: Option<u64>,
pub in_multicast_pkts: Option<u64>,
pub in_pkts: Option<u64>,
pub out_pkts: Option<u64>,
pub qdisc_backlog_bytes: Option<u64>,
pub qdisc_backlog_pkts: Option<u64>,
}
#[cfg(test)]
mod tests {
use super::*;
fn lane(rank: u8, reliable: bool) -> LaneKey {
LaneKey {
endpoint: EndpointId::new("peer-b"),
reliable,
rank,
}
}
#[test]
fn the_operational_states_spell_themselves_as_rfc_2863_does() {
assert_eq!(OperState::Up.as_str(), "up");
assert_eq!(OperState::Down.as_str(), "down");
assert_eq!(OperState::NotPresent.as_str(), "notPresent");
assert_eq!(OperState::Unknown.as_str(), "unknown");
assert_eq!(AdminState::Down.to_string(), "down");
}
#[test]
fn a_device_that_says_nothing_is_unknown_and_not_a_reason_to_restart() {
let s = OperStatus::default();
assert_eq!(s.status, OperState::Unknown);
assert_eq!(s.admin, AdminState::Up);
assert!(s.recoverable, "unknown is not a reason to restart");
assert!(s.reason.is_none());
assert!(!s.is_up());
assert!(!OperStatus::down("dead", false).recoverable);
assert!(OperStatus::down("no coverage", true).recoverable);
assert!(!OperStatus::not_present("port unplugged").recoverable);
assert!(OperStatus::up().is_up());
}
#[test]
fn an_identity_says_only_what_the_device_knows() {
assert!(Identity::unknown().is_empty());
let id = Identity::unknown()
.model_name("IRIDIUM 9603")
.imei("300234060000000");
assert!(!id.is_empty());
assert_eq!(id.model_name.as_deref(), Some("IRIDIUM 9603"));
assert_eq!(id.mfg_name, None, "unasked is absent, not empty");
}
#[test]
fn the_vocabulary_keeps_the_report_copy_and_eq_at_fixed_point() {
let r = Report::new()
.rssi(-97_500)
.rsrq(-10_500)
.snr(12_000)
.rx_rate(1_000_000)
.latency(45_000)
.registration(Registration::Home)
.access_technology(AccessTechnology::Lte);
assert_eq!(r, r, "Eq");
let copy = r;
assert_eq!(copy.rssi, Some(-97_500));
assert_eq!(r.rsrp, None, "unmeasured is absent");
assert_eq!(Registration::Home.as_str(), "home");
assert_eq!(AccessTechnology::Nr5g.as_str(), "5gnr");
}
#[test]
fn a_lane_renders_as_endpoint_reliability_and_rank() {
assert_eq!(lane(0, true).to_string(), "peer-b/rel#0");
assert_eq!(lane(5, false).to_string(), "peer-b/be#5");
}
#[test]
fn lanes_differing_only_in_reliability_are_distinct() {
assert_ne!(lane(0, true), lane(0, false));
}
#[test]
fn capabilities_may_be_asymmetric() {
let caps = Capabilities {
tx_max_sdu: 340,
rx_max_sdu: 270,
duplex: Duplex::Full,
reliable: true,
};
assert_ne!(caps.tx_max_sdu, caps.rx_max_sdu);
}
#[test]
fn an_oversized_sdu_names_the_batch_size_that_would_fit() {
let e = DeviceError::SduTooLarge { got: 300, max: 218 };
assert_eq!(
e.to_string(),
"sdu of 300 bytes exceeds the medium's tx_max_sdu of 218: \
lower zenoh's batch_size to at most 220 (architecture I4, §4.5)"
);
}
}