use std::collections::{BTreeMap, btree_map}; use serde::{Deserialize, Serialize}; use crate::catalog::Mode; use crate::catalog::millis::MillisCeil; /// The JSON tracks a broadcast publishes, keyed by track name. /// /// These are application data tracks, not media: a chat log, a telemetry feed, a status document. /// Each entry says how to read the track (its [`mode`](JsonConfig::mode)) without a consumer having to /// know the application. /// /// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major /// version. External callers start from [`Json::default`] and fill in what they need /// ([`insert`](Self::insert)); struct-literal construction is not available outside this crate. #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct Json { /// A map of track name to configuration. /// /// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are /// sorted for *some* deterministic behavior. #[serde(deserialize_with = "crate::catalog::deserialize_entries")] pub tracks: BTreeMap, } impl crate::catalog::Entry for JsonConfig {} impl Json { /// Insert a track config, returning an error if the name already exists. pub fn insert(&mut self, name: &str, config: JsonConfig) -> crate::Result<()> { let btree_map::Entry::Vacant(entry) = self.tracks.entry(name.to_string()) else { return Err(crate::Error::Duplicate(name.to_string())); }; entry.insert(config); Ok(()) } /// Remove the track from the catalog and return its configuration if found. pub fn remove(&mut self, name: &str) -> Option { self.tracks.remove(name) } /// Whether there are no JSON tracks, in which case the section is left off the wire. pub fn is_empty(&self) -> bool { self.tracks.is_empty() } } /// How to read one JSON track. /// /// Each frame is a UTF-8 JSON value; [`mode`](Self::mode) says how the track's groups compose /// those frames into the value a consumer sees. /// /// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major /// version. External callers build one with [`JsonConfig::new`] and assign the optional fields they /// need; struct-literal construction is not available outside this crate. #[serde_with::serde_as] #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct JsonConfig { /// Optional reference to another broadcast that publishes this track, expressed relative to the /// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same /// broadcast as the catalog. #[serde(default)] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the /// catalog. Absent means the ID is the track name, as in every catalog before this field. /// /// Set it only when the ID can't be the name, such as two renditions of same-named tracks /// from different broadcasts. Readers resolve the name with /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names /// whichever stream the reader resolves first, as in every catalog before this field. /// /// A reader refuses a broadcast of another instance rather than fall back to it. A route /// over a wire that carries no instance has one its session minted, which proves nothing, /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] #[serde_as(as = "Option")] pub instance: Option, /// Whether the track is a latest-value document or an append log. Always stated: see [`Mode`]. #[serde_as(as = "serde_with::DisplayFromStr")] pub mode: Mode, /// An optional identifier for the shape of each value, typically a JSON Schema URL. Purely /// descriptive: a consumer that doesn't recognize it can still read the track. #[serde(default)] pub schema: Option, /// The maximum bitrate of the track in bits per second, if known. #[serde(default)] pub bitrate: Option, /// The largest media span the publisher hands to the transport behind a payload's timestamp, /// with the same meaning and whole-millisecond encoding as /// [`VideoConfig::jitter`](crate::catalog::VideoConfig::jitter). #[serde_as(as = "MillisCeil")] #[serde(default)] pub jitter: Option, /// How far this track's payloads persistently trail what the broadcast's other tracks already /// wrote, with the same meaning and encoding as /// [`VideoConfig::delay`](crate::catalog::VideoConfig::delay). Only measured for payloads that /// carry a capture time. #[serde_as(as = "MillisCeil")] #[serde(default, skip_serializing_if = "crate::catalog::millis::no_delay")] pub delay: Option, /// Fields this build doesn't recognize, kept so the entry round-trips. /// /// A future [`Mode`] almost certainly comes with fields describing it, and /// preserving the discriminant without them would leave a relay republishing an entry nothing /// can act on. Same reason [`Container`](crate::catalog::Container) keeps an unknown container /// verbatim. #[serde(flatten)] pub extra: serde_json::Map, } impl JsonConfig { /// A config for a track read in `mode`, with no optional fields set. pub fn new(mode: Mode) -> Self { Self { broadcast: None, track: None, instance: None, mode, schema: None, bitrate: None, jitter: None, delay: None, extra: Default::default(), } } } /// The config itself, so a data producer takes it wherever it takes an entry embedding one. impl AsMut for JsonConfig { fn as_mut(&mut self) -> &mut Self { self } }