diff --git a/quest/m2/hang04/null.md b/quest/m2/hang04/null.md deleted file mode 100644 index afd2299da17..00000000000 --- a/quest/m2/hang04/null.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] Rust refuses a null catalog field as JS does - -## Goal - -`rs/hang` refuses a catalog in which a field the hang draft defines is -`null`, as `js/hang` already does and the draft's Root and Malformed -Renditions sections require. Today Rust reads `"bitrate": null`, or any -other optional field set to `null`, as absent, so the two languages accept -different catalogs. - -## Plan - -Found while landing the draft's one strict rule: that PR made every root -section and `sync`'s `clock` and `interval` refuse `null` in Rust -(`deserialize_some` in `rs/hang/src/catalog/mod.rs`), but the -`Option<_>` fields inside renditions, data tracks, includes, and `color` -still take serde's default, where `null` decodes as `None`. JS uses -`z.optional`, which refuses `null`. - -- Pick one mechanism over annotating each field: a field-level - `deserialize_some` breaks the `serde_as` adapters (`MillisCeil`, - `DisplayFromStr`) those fields carry, so prefer a `serde_with` adapter - that wraps them, or a catalog-wide check that walks only the fields the - draft defines. An unknown extension field inside an entry may still be - `null`. -- Add a `null` case per field kind to `rs/hang/fixtures/catalog-parity.json` - so both languages run it. - -Public API: none. Wire: a catalog with a `null` field, which JS already -refuses, is refused by Rust too. diff --git a/rs/hang/fixtures/catalog-parity.json b/rs/hang/fixtures/catalog-parity.json index 6b789fb8728..85e23881c36 100644 --- a/rs/hang/fixtures/catalog-parity.json +++ b/rs/hang/fixtures/catalog-parity.json @@ -4518,6 +4518,1004 @@ }, "refused": true }, + { + "name": "null video broadcast", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "broadcast": null + } + } + } + }, + "refused": true + }, + { + "name": "null video instance", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "instance": null + } + } + } + }, + "refused": true + }, + { + "name": "null video track", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "track": null + } + } + } + }, + "refused": true + }, + { + "name": "null video label", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "label": null + } + } + } + }, + "refused": true + }, + { + "name": "null video container", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "container": null + } + } + } + }, + "refused": true + }, + { + "name": "null video description", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "description": null + } + } + } + }, + "refused": true + }, + { + "name": "null video codedWidth", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "codedWidth": null + } + } + } + }, + "refused": true + }, + { + "name": "null video codedHeight", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "codedHeight": null + } + } + } + }, + "refused": true + }, + { + "name": "null video displayAspectWidth", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "displayAspectWidth": null + } + } + } + }, + "refused": true + }, + { + "name": "null video displayAspectHeight", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "displayAspectHeight": null + } + } + } + }, + "refused": true + }, + { + "name": "null video color", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": null + } + } + } + }, + "refused": true + }, + { + "name": "null video projection", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "projection": null + } + } + } + }, + "refused": true + }, + { + "name": "null video stereo", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "stereo": null + } + } + } + }, + "refused": true + }, + { + "name": "null video interlaced", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "interlaced": null + } + } + } + }, + "refused": true + }, + { + "name": "null video framerate", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "framerate": null + } + } + } + }, + "refused": true + }, + { + "name": "null video reorder", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "reorder": null + } + } + } + }, + "refused": true + }, + { + "name": "null video bitrate", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "bitrate": null + } + } + } + }, + "refused": true + }, + { + "name": "null video enabled", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "enabled": null + } + } + } + }, + "refused": true + }, + { + "name": "null video preference", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "preference": null + } + } + } + }, + "refused": true + }, + { + "name": "null video optimizeForLatency", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "optimizeForLatency": null + } + } + } + }, + "refused": true + }, + { + "name": "null video jitter", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "jitter": null + } + } + } + }, + "refused": true + }, + { + "name": "null video delay", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "delay": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio broadcast", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "broadcast": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio instance", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "instance": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio track", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "track": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio label", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "label": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio container", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio description", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "description": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio layout", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "layout": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio bitrate", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "bitrate": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio enabled", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "enabled": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio jitter", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "jitter": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio warmup", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "warmup": null + } + } + } + }, + "refused": true + }, + { + "name": "null audio delay", + "catalog": { + "audio": { + "renditions": { + "probe": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "delay": null + } + } + } + }, + "refused": true + }, + { + "name": "null text broadcast", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "broadcast": null + } + } + } + }, + "refused": true + }, + { + "name": "null text instance", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "instance": null + } + } + } + }, + "refused": true + }, + { + "name": "null text track", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "track": null + } + } + } + }, + "refused": true + }, + { + "name": "null text role", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "role": null + } + } + } + }, + "refused": true + }, + { + "name": "null text lang", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "lang": null + } + } + } + }, + "refused": true + }, + { + "name": "null text label", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "label": null + } + } + } + }, + "refused": true + }, + { + "name": "null text container", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "container": null + } + } + } + }, + "refused": true + }, + { + "name": "null text jitter", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "jitter": null + } + } + } + }, + "refused": true + }, + { + "name": "null text delay", + "catalog": { + "text": { + "renditions": { + "probe": { + "format": "vtt", + "delay": null + } + } + } + }, + "refused": true + }, + { + "name": "null json broadcast", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "broadcast": null + } + } + } + }, + "refused": true + }, + { + "name": "null json instance", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "instance": null + } + } + } + }, + "refused": true + }, + { + "name": "null json track", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "track": null + } + } + } + }, + "refused": true + }, + { + "name": "null json schema", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "schema": null + } + } + } + }, + "refused": true + }, + { + "name": "null json bitrate", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "bitrate": null + } + } + } + }, + "refused": true + }, + { + "name": "null json jitter", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "jitter": null + } + } + } + }, + "refused": true + }, + { + "name": "null json delay", + "catalog": { + "json": { + "tracks": { + "probe": { + "mode": "snapshot", + "delay": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary broadcast", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "broadcast": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary instance", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "instance": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary track", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "track": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary mime", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "mime": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary bitrate", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "bitrate": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary jitter", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "jitter": null + } + } + } + }, + "refused": true + }, + { + "name": "null binary delay", + "catalog": { + "binary": { + "tracks": { + "probe": { + "mode": "stream", + "delay": null + } + } + } + }, + "refused": true + }, + { + "name": "null video color primaries", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "primaries": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video color transfer", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "transfer": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video color matrix", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "matrix": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video color range", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "range": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video color mastering", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "mastering": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video color contentLight", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "color": { + "contentLight": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video projection fov", + "catalog": { + "video": { + "renditions": { + "probe": { + "codec": "avc1.64001f", + "projection": { + "kind": "equirectangular", + "fov": null + } + } + } + } + }, + "refused": true + }, + { + "name": "null video section display", + "catalog": { + "video": { + "renditions": {}, + "display": null + } + }, + "refused": true + }, + { + "name": "null video section rotation", + "catalog": { + "video": { + "renditions": {}, + "rotation": null + } + }, + "refused": true + }, + { + "name": "null video section flip", + "catalog": { + "video": { + "renditions": {}, + "flip": null + } + }, + "refused": true + }, + { + "name": "null include instance", + "catalog": { + "include": { + "probe": { + "broadcast": "./a.hang", + "instance": null + } + } + }, + "refused": true + }, + { + "name": "null root version", + "catalog": { + "version": null + }, + "refused": true + }, + { + "name": "null unknown rendition field is ignored", + "catalog": { + "video": { + "renditions": { + "ok": { + "codec": "avc1.64001f", + "com.example.tag": null + } + } + } + }, + "video": ["ok"] + }, { "name": "mis-shaped stats null", "catalog": { diff --git a/rs/hang/src/catalog/audio/mod.rs b/rs/hang/src/catalog/audio/mod.rs index fc618432b10..6a7fb6fc593 100644 --- a/rs/hang/src/catalog/audio/mod.rs +++ b/rs/hang/src/catalog/audio/mod.rs @@ -104,6 +104,7 @@ pub struct AudioConfig { /// Resolve it with [`Path::resolve`](moq_net::Path::resolve): a reference that walks /// above the root names no broadcast, so the catalog is rejected. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the @@ -114,6 +115,7 @@ pub struct AudioConfig { /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names @@ -124,11 +126,12 @@ pub struct AudioConfig { /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, /// Human-readable rendition name for track pickers. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub label: Option, /// The codec, see the registry for details: @@ -147,12 +150,12 @@ pub struct AudioConfig { /// /// Live state, like video `color`. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub layout: Option, /// The maximum bitrate of the audio track in bits per second, at most 2^53 - 1. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub bitrate: Option, /// Whether this rendition may be selected. When false, no frames are coming and a consumer @@ -166,7 +169,7 @@ pub struct AudioConfig { /// Some codecs include a description so the decoder can be initialized without extra data. /// If not provided, there may be in-band metadata (marginally higher overhead). #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub description: Option, /// Container format for frame encoding. @@ -192,7 +195,7 @@ pub struct AudioConfig { /// After a non-continuous join, decode from the group start, present at start plus warmup, and join that much earlier. /// Serialized as whole milliseconds, rounded up so presentation never starts early. - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] #[serde(default)] pub warmup: Option, diff --git a/rs/hang/src/catalog/binary.rs b/rs/hang/src/catalog/binary.rs index 914d4a34bcf..a9c3ae3875a 100644 --- a/rs/hang/src/catalog/binary.rs +++ b/rs/hang/src/catalog/binary.rs @@ -70,6 +70,7 @@ pub struct BinaryConfig { /// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same /// broadcast as the catalog. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the @@ -80,6 +81,7 @@ pub struct BinaryConfig { /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names @@ -90,7 +92,7 @@ pub struct BinaryConfig { /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, /// Whether the track is a latest-value blob or an append log. Always stated: see [`Mode`]. @@ -100,10 +102,12 @@ pub struct BinaryConfig { /// An optional media type for each payload (e.g. `image/jpeg`). Purely descriptive: a consumer /// that doesn't recognize it can still read the track. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub mime: Option, /// The maximum bitrate of the track in bits per second, if known. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub bitrate: Option, /// The largest media span the publisher hands to the transport behind a payload's timestamp, diff --git a/rs/hang/src/catalog/include.rs b/rs/hang/src/catalog/include.rs index b38bb913688..d5a33453c7a 100644 --- a/rs/hang/src/catalog/include.rs +++ b/rs/hang/src/catalog/include.rs @@ -26,7 +26,7 @@ pub struct Include { /// instance refuses it, and against one a relay minted it is best effort. A composer leaves it /// out until the include resolves. #[serde(default, skip_serializing_if = "Option::is_none")] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, } diff --git a/rs/hang/src/catalog/json.rs b/rs/hang/src/catalog/json.rs index 6456adf1664..954dc5ad119 100644 --- a/rs/hang/src/catalog/json.rs +++ b/rs/hang/src/catalog/json.rs @@ -68,6 +68,7 @@ pub struct JsonConfig { /// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same /// broadcast as the catalog. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the @@ -78,6 +79,7 @@ pub struct JsonConfig { /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names @@ -88,7 +90,7 @@ pub struct JsonConfig { /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, /// Whether the track is a latest-value document or an append log. Always stated: see [`Mode`]. @@ -98,10 +100,12 @@ pub struct JsonConfig { /// 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)] + #[serde_as(as = "crate::catalog::NotNull")] pub schema: Option, /// The maximum bitrate of the track in bits per second, if known. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub bitrate: Option, /// The largest media span the publisher hands to the transport behind a payload's timestamp, diff --git a/rs/hang/src/catalog/m2ts.rs b/rs/hang/src/catalog/m2ts.rs index 8f2c5ff9952..10b9c2480cb 100644 --- a/rs/hang/src/catalog/m2ts.rs +++ b/rs/hang/src/catalog/m2ts.rs @@ -10,6 +10,7 @@ use serde::{Deserialize, Serialize}; /// /// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major /// version. External callers build one with [`M2ts::new`] and assign the fields they need. +#[serde_with::serde_as] #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] #[serde(rename_all = "camelCase")] @@ -30,6 +31,7 @@ pub struct M2ts { /// The rate the source's PCR paced the whole multiplex at, in bits per second, null packets /// included. Present only while the source holds a constant rate. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub mux_rate: Option, } diff --git a/rs/hang/src/catalog/millis.rs b/rs/hang/src/catalog/millis.rs index 68d33b67725..9c5364d471c 100644 --- a/rs/hang/src/catalog/millis.rs +++ b/rs/hang/src/catalog/millis.rs @@ -14,8 +14,9 @@ use serde_with::{DeserializeAs, SerializeAs}; /// truncating advertises 23; anything under a millisecond truncates to 0, which reads as /// "flushed immediately" rather than "a little". /// -/// The optional implementation is for jitter and delay, where zero decodes as absent and -/// cannot be written. Fields such as warmup, where zero is meaningful, use `Option`. +/// The optional implementation is for jitter and delay, where zero decodes as absent and cannot +/// be written, and `null` is refused. Fields such as warmup, where zero is meaningful, use +/// `NotNull`. /// A `delay` of zero is a publisher stating it trails nothing, so that field skips it with /// [`no_delay`] instead of refusing it. pub(crate) struct MillisCeil; @@ -59,8 +60,9 @@ impl SerializeAs> for MillisCeil { impl<'de> DeserializeAs<'de, Option> for MillisCeil { fn deserialize_as>(deserializer: D) -> Result, D::Error> { - let millis: Option = Option::::deserialize_as(deserializer)?; - Ok(millis.filter(|millis| *millis != 0).map(Duration::from_millis)) + // Zero reads as absent, but `null` is refused like any other field's. + let millis: u64 = crate::snapshot::Number::deserialize_as(deserializer)?; + Ok((millis != 0).then(|| Duration::from_millis(millis))) } } diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index e2b7c76baa3..50e3ad63932 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -100,6 +100,27 @@ where deserialize_object(deserializer).map(Some) } +/// A [`serde_with`] adapter for an optional field that is absent or holds a value, never `null`. +/// +/// serde reads `null` as `None`, but the draft refuses a catalog with a `null` field it defines. +/// Pair it with `#[serde(default)]` so an absent field is still `None`. +pub(crate) struct NotNull(std::marker::PhantomData); + +impl> serde_with::SerializeAs> for NotNull { + fn serialize_as(source: &Option, serializer: S) -> Result { + match source { + Some(value) => U::serialize_as(value, serializer), + None => serializer.serialize_none(), + } + } +} + +impl<'de, T, U: serde_with::DeserializeAs<'de, T>> serde_with::DeserializeAs<'de, Option> for NotNull { + fn deserialize_as>(deserializer: D) -> Result, D::Error> { + U::deserialize_as(deserializer).map(Some) + } +} + /// An entry of a catalog map keyed by ID (a rendition, data track, or include), checked as it /// decodes. pub(crate) trait Entry: serde::de::DeserializeOwned { diff --git a/rs/hang/src/catalog/text/mod.rs b/rs/hang/src/catalog/text/mod.rs index d4fbc8cce58..32224310154 100644 --- a/rs/hang/src/catalog/text/mod.rs +++ b/rs/hang/src/catalog/text/mod.rs @@ -76,6 +76,7 @@ pub struct TextConfig { /// broadcast that served this catalog (e.g. `../source`). If unset, the track lives in the same /// broadcast as the catalog. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the @@ -86,6 +87,7 @@ pub struct TextConfig { /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names @@ -96,7 +98,7 @@ pub struct TextConfig { /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, /// The serialization format of each cue payload. @@ -109,10 +111,14 @@ pub struct TextConfig { pub role: TextRole, /// The BCP-47 language tag of the track (e.g. `en`, `es-419`), if known. + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub lang: Option, /// A human-readable label for a track picker, when `lang` alone is ambiguous (e.g. distinguishing /// "English" from "English (SDH)"). + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub label: Option, /// Container format for frame encoding. Defaults to "legacy" (a microsecond timestamp prefix diff --git a/rs/hang/src/catalog/video/color.rs b/rs/hang/src/catalog/video/color.rs index 3215072d6ac..96227ddb75a 100644 --- a/rs/hang/src/catalog/video/color.rs +++ b/rs/hang/src/catalog/video/color.rs @@ -7,27 +7,34 @@ use serde::{Deserialize, Serialize}; /// unspecified, never a signalled default. /// /// Marked `#[non_exhaustive]`: start from [`Color::default`] and assign the fields you know. +#[serde_with::serde_as] #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] -#[serde(rename_all = "camelCase")] +#[serde(default, rename_all = "camelCase")] #[non_exhaustive] pub struct Color { /// The chromaticities of the source primaries, as H.273 `ColourPrimaries` (1 is BT.709, 9 is BT.2020). + #[serde_as(as = "crate::catalog::NotNull")] pub primaries: Option, /// The transfer function, as H.273 `TransferCharacteristics` (1 is BT.709, 16 is PQ, 18 is HLG). + #[serde_as(as = "crate::catalog::NotNull")] pub transfer: Option, /// The matrix between RGB and Y'CbCr, as H.273 `MatrixCoefficients` (0 is RGB, 1 is BT.709, 9 is BT.2020 NCL). + #[serde_as(as = "crate::catalog::NotNull")] pub matrix: Option, /// The numeric range of the samples. + #[serde_as(as = "crate::catalog::NotNull")] pub range: Option, /// The display the content was mastered on, as SMPTE ST 2086. + #[serde_as(as = "crate::catalog::NotNull")] pub mastering: Option, /// The content's light levels, as CTA-861.3. + #[serde_as(as = "crate::catalog::NotNull")] pub content_light: Option, } diff --git a/rs/hang/src/catalog/video/mod.rs b/rs/hang/src/catalog/video/mod.rs index 20d443bf3dd..6f14e180acd 100644 --- a/rs/hang/src/catalog/video/mod.rs +++ b/rs/hang/src/catalog/video/mod.rs @@ -52,16 +52,19 @@ pub struct Video { /// Render the video at this size in pixels. /// This is separate from the display aspect ratio because it does not require reinitialization. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub display: Option, /// The clockwise rotation of the video in degrees. /// Default: 0 #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub rotation: Option, /// If true, the decoder will flip the video horizontally /// Default: false #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub flip: Option, } @@ -191,6 +194,7 @@ pub struct VideoConfig { /// Resolve it with [`Path::resolve`](moq_net::Path::resolve): a reference that walks /// above the root names no broadcast, so the catalog is rejected. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub broadcast: Option, /// The track's name in its broadcast, when it differs from this entry's ID: its key in the @@ -201,6 +205,7 @@ pub struct VideoConfig { /// [`Reference::track`](crate::catalog::Reference::track); one that predates the /// field subscribes to the ID instead. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub track: Option, /// The instance of the stream the reference names, when the catalog knows it. Absent names @@ -211,11 +216,12 @@ pub struct VideoConfig { /// so there it is best effort. Without [`broadcast`](Self::broadcast), it names the /// catalog's own stream. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub instance: Option, /// Human-readable rendition name for track pickers. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub label: Option, /// The codec, see the registry for details: @@ -228,15 +234,19 @@ pub struct VideoConfig { /// One of the best examples is H264, which needs the sps/pps to function. /// If not provided, this information is (automatically) inserted before each key-frame (marginally higher overhead). #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub description: Option, /// The largest encoded width/height the track carries, fixed for its name, never zero. /// /// The picture resizes in band at a keyframe below these ceilings, unless the /// `description` pins it. Absent means unknown; a publisher may fill it once. + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub coded_width: Option, /// The height counterpart of `coded_width`. + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub coded_height: Option, /// The aspect ratio the whole picture is displayed at, as WebCodecs' @@ -244,27 +254,33 @@ pub struct VideoConfig { /// /// Absent means the decoded picture's own shape. A publisher with non-square /// samples sets the picture's aspect here, never the sample aspect. + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub display_aspect_width: Option, /// The height counterpart of `display_aspect_width`. + #[serde_as(as = "crate::catalog::NotNull")] + #[serde(default)] pub display_aspect_height: Option, /// The colour the decoded pixels carry, so a renderer need not guess or reparse the bitstream. /// /// Live state, not identity: a publisher may fill it in once the bitstream reveals it. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub color: Option, /// How the picture maps onto the viewer's field of view. Absent means rectilinear. /// /// Live state, like [`color`](Self::color). #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub projection: Option, /// How each eye's view is packed into the frame. Absent means mono. /// /// Live state, like [`color`](Self::color). #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub stereo: Option, /// Each picture weaves two fields, so a renderer deinterlaces it. Only written when true. @@ -275,7 +291,7 @@ pub struct VideoConfig { /// The maximum bitrate of the video track, if known, at most 2^53 - 1. #[serde(default)] - #[serde_as(as = "Option")] + #[serde_as(as = "crate::catalog::NotNull")] pub bitrate: Option, /// Whether this rendition may be selected. When false, no frames are coming and a consumer @@ -294,6 +310,7 @@ pub struct VideoConfig { /// The maximum frame rate of the video track, if known. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub framerate: Option, /// The most frames that can precede a frame in decode order and follow it in presentation @@ -303,12 +320,14 @@ pub struct VideoConfig { /// that authors decode times infers them from the timestamps instead. A publisher that /// declares it keeps it for the track's life, and never reorders deeper. #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub reorder: Option, /// If true, the decoder will optimize for latency. /// /// Default: true #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] pub optimize_for_latency: Option, /// Container format for frame encoding. diff --git a/rs/hang/src/catalog/video/projection.rs b/rs/hang/src/catalog/video/projection.rs index 5a038995632..e43c697602d 100644 --- a/rs/hang/src/catalog/video/projection.rs +++ b/rs/hang/src/catalog/video/projection.rs @@ -58,6 +58,7 @@ impl Projection { } /// The projections this build knows, split out so the tagged representation stays derived. +#[serde_with::serde_as] #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize)] #[serde(tag = "kind", rename_all = "camelCase")] @@ -65,6 +66,7 @@ enum Known { Rectilinear, Equirectangular { #[serde(default)] + #[serde_as(as = "crate::catalog::NotNull")] fov: Option, }, }