From c51b9721c23a7e03a874bb761c38dba1133570d6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 15:40:38 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m2/hang04/null.md Quest-Claim: 081e370a065e0fba From 6f6566fb646e778103050eb489aa67a570465020 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 16:12:39 -0800 Subject: [PATCH 2/2] fix(hang): Rust refuses null in an optional catalog field, as JS does Every optional field the hang draft defines in renditions, data tracks, includes, color, projection, and the video section now goes through a NotNull serde_with adapter, so null is refused instead of read as absent. MillisCeil's optional form refuses null too. The shared parity fixture gains a null case per field, generated from the JS schemas. Co-Authored-By: Claude Opus 5.5 --- quest/m2/hang04/null.md | 30 - rs/hang/fixtures/catalog-parity.json | 998 ++++++++++++++++++++++++ rs/hang/src/catalog/audio/mod.rs | 13 +- rs/hang/src/catalog/binary.rs | 6 +- rs/hang/src/catalog/include.rs | 2 +- rs/hang/src/catalog/json.rs | 6 +- rs/hang/src/catalog/m2ts.rs | 2 + rs/hang/src/catalog/millis.rs | 10 +- rs/hang/src/catalog/mod.rs | 21 + rs/hang/src/catalog/text/mod.rs | 8 +- rs/hang/src/catalog/video/color.rs | 9 +- rs/hang/src/catalog/video/mod.rs | 27 +- rs/hang/src/catalog/video/projection.rs | 2 + 13 files changed, 1086 insertions(+), 48 deletions(-) delete mode 100644 quest/m2/hang04/null.md diff --git a/quest/m2/hang04/null.md b/quest/m2/hang04/null.md deleted file mode 100644 index 60e3f4e8699..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 `media`'s `clock` and `join` 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 52a775da9a5..97c19e26532 100644 --- a/rs/hang/fixtures/catalog-parity.json +++ b/rs/hang/fixtures/catalog-parity.json @@ -4522,6 +4522,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 f8ce0df7487..a7d70a6a0d4 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 fb4d94b2120..70848eade59 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, }, }