1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
//! Runtime extension-descriptor registry — open registration of client
//! `descriptor_tag_extension` values.
//!
//! [`ExtensionRegistry`] mirrors [`DescriptorRegistry`][super::super::registry::DescriptorRegistry]
//! for the second-level dispatch inside an extension_descriptor (tag `0x7F`):
//! a registered custom `descriptor_tag_extension` is parsed into a client-supplied
//! owned type and surfaced as [`RegisteredExtension::Custom`]; unregistered
//! extensions fall through to the built-in [`ExtensionDescriptor`] via
//! [`RegisteredExtension::Builtin`].
//!
//! # Owned types only
//!
//! Registered types must be `'static` (i.e. owned — no borrowed slices).
//! This is required because the parsed value is heap-allocated as a
//! `Box<dyn ExtensionObject>` whose concrete type is erased; `dyn Any`
//! downcast demands `'static`. If your wire layout contains borrowed bytes,
//! copy them into a `Vec<u8>` in the struct.
//!
//! [`DescriptorRegistry`]: super::super::registry::DescriptorRegistry
use alloc::boxed::Box;
use alloc::collections::BTreeMap;
use super::{ExtensionBodyDef, ExtensionDescriptor, validate_and_split};
use crate::error::Result;
broadcast_common::declare_object_trait! {
/// Object-safe face of a runtime-registered extension descriptor value.
///
/// Registered types must be owned (`'static`) because the `dyn Any` downcast
/// path requires it. See the [module docs][self] for details.
///
/// Implemented automatically via the blanket impl for any `T` satisfying the
/// supertraits; you do not need to write this by hand.
pub trait ExtensionObject, "extension descriptor"
}
// ---------------------------------------------------------------------------
// Internal parse closure type
// ---------------------------------------------------------------------------
/// A heap-allocated parse closure that takes the selector bytes (everything
/// after `descriptor_tag_extension`) and returns an owned, type-erased
/// extension body value.
pub(crate) type CustomParse =
Box<dyn for<'a> Fn(&'a [u8]) -> Result<Box<dyn ExtensionObject>> + Send + Sync>;
// ---------------------------------------------------------------------------
// ExtensionRegistry
// ---------------------------------------------------------------------------
/// Runtime-configurable extension-descriptor registry.
///
/// By default the registry has no custom parsers; all `descriptor_tag_extension`
/// values fall through to the built-in [`ExtensionDescriptor`]/[`ExtensionBody`]
/// dispatch. Use [`register`][Self::register] to add a custom type.
///
/// Call [`parse`][Self::parse] on a full extension_descriptor (tag `0x7F`)
/// byte slice; it returns a [`RegisteredExtension`].
///
/// [`ExtensionBody`]: super::ExtensionBody
#[derive(Default)]
pub struct ExtensionRegistry {
custom: BTreeMap<u8, CustomParse>,
}
impl ExtensionRegistry {
/// Create an empty registry (built-in dispatch only).
#[must_use]
pub fn new() -> Self {
Self::default()
}
/// Returns `true` if a custom parser is registered for the given
/// `descriptor_tag_extension`.
#[must_use]
pub fn has_custom(&self, tag_extension: u8) -> bool {
self.custom.contains_key(&tag_extension)
}
/// Register an owned custom extension body type for its
/// [`ExtensionBodyDef::TAG_EXTENSION`].
///
/// # Owned types only
///
/// `T` must be `'static` — no borrowed slices. The registered value is
/// type-erased as `Box<dyn ExtensionObject>`; `dyn Any` downcast requires
/// the concrete type to be `'static`.
///
/// Re-registering the same `TAG_EXTENSION` replaces the prior custom
/// parser (last wins).
pub fn register<T>(&mut self) -> &mut Self
where
T: for<'a> ExtensionBodyDef<'a> + ExtensionObject + 'static,
{
let tag_ext = T::TAG_EXTENSION;
self.custom.insert(
tag_ext,
Box::new(|sel| {
Ok(Box::new(<T as broadcast_common::Parse>::parse(sel)?)
as Box<dyn ExtensionObject>)
}),
);
self
}
/// Parse the already-split (tag_extension, selector) pair into a
/// [`RegisteredExtension`], checking for a registered custom parser first
/// and falling back to the built-in dispatch.
pub fn parse_body<'a>(
&self,
tag_extension: u8,
selector: &'a [u8],
) -> Result<RegisteredExtension<'a>> {
if let Some(parse_fn) = self.custom.get(&tag_extension) {
let value = parse_fn(selector)?;
Ok(RegisteredExtension::Custom {
tag_extension,
value,
})
} else {
let body = super::parse_body(tag_extension, selector)?;
Ok(RegisteredExtension::Builtin(ExtensionDescriptor {
tag_extension,
body,
}))
}
}
/// Parse a full extension_descriptor (tag `0x7F`) byte slice.
///
/// Validates the tag, length, and minimum body size (same checks as
/// `ExtensionDescriptor::parse`). If the `descriptor_tag_extension`
/// has a registered custom parser, returns [`RegisteredExtension::Custom`];
/// otherwise returns [`RegisteredExtension::Builtin`] with the standard
/// built-in dispatch.
pub fn parse<'a>(&self, bytes: &'a [u8]) -> Result<RegisteredExtension<'a>> {
let (tag_extension, sel) = validate_and_split(bytes)?;
self.parse_body(tag_extension, sel)
}
}
// ---------------------------------------------------------------------------
// RegisteredExtension
// ---------------------------------------------------------------------------
/// Output of [`ExtensionRegistry::parse`]: built-in or custom extension.
#[derive(Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
#[non_exhaustive]
pub enum RegisteredExtension<'a> {
/// Built-in [`ExtensionDescriptor`] (no custom parser registered for this
/// `descriptor_tag_extension`).
Builtin(super::ExtensionDescriptor<'a>),
/// Custom-registered extension body.
Custom {
/// The `descriptor_tag_extension` byte.
tag_extension: u8,
/// The parsed, type-erased value. Call `downcast_ref` on it (see
/// [`ExtensionObject`]) to recover the concrete type.
#[cfg_attr(feature = "serde", serde(serialize_with = "serialize_erased"))]
value: Box<dyn ExtensionObject>,
},
}
#[cfg(test)]
mod tests {
use super::*;
use crate::descriptors::extension::{ExtensionBodyDef, TAG, TAG_EXTENSION_LEN};
use crate::error::Error;
const TEST_TAG_EXTENSION: u8 = 0x40;
#[derive(Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
struct MyExtBody {
payload: Vec<u8>,
}
impl ExtensionBodyDef<'_> for MyExtBody {
const TAG_EXTENSION: u8 = TEST_TAG_EXTENSION;
const NAME: &'static str = "MY_EXT_BODY";
}
impl<'a> broadcast_common::Parse<'a> for MyExtBody {
type Error = crate::error::Error;
fn parse(sel: &'a [u8]) -> Result<Self> {
Ok(Self {
payload: sel.to_vec(),
})
}
}
fn wrap_ext(tag_ext: u8, sel: &[u8]) -> Vec<u8> {
let mut v = vec![TAG, (sel.len() + TAG_EXTENSION_LEN) as u8, tag_ext];
v.extend_from_slice(sel);
v
}
#[test]
fn custom_extension_parsed_and_downcastable() {
let mut reg = ExtensionRegistry::new();
reg.register::<MyExtBody>();
let sel = [0xDE, 0xAD, 0xBE];
let bytes = wrap_ext(TEST_TAG_EXTENSION, &sel);
let re = reg.parse(&bytes).unwrap();
match re {
RegisteredExtension::Custom {
tag_extension,
value,
} => {
assert_eq!(tag_extension, TEST_TAG_EXTENSION);
let concrete = value
.downcast_ref::<MyExtBody>()
.expect("downcast should succeed");
assert_eq!(concrete.payload, sel);
}
other => panic!("expected Custom, got {other:?}"),
}
}
#[test]
fn unregistered_tag_extension_yields_builtin() {
use crate::descriptors::extension::ExtensionBody;
let reg = ExtensionRegistry::new();
// service_relocated (0x0B) has a fixed 6-byte selector, which is simple.
let d = crate::descriptors::extension::ExtensionDescriptor {
tag_extension: 0x0B,
body: ExtensionBody::ServiceRelocated(
crate::descriptors::extension::ServiceRelocated {
old_original_network_id: 1,
old_transport_stream_id: 2,
old_service_id: 3,
},
),
};
let mut buf = vec![0u8; d.serialized_len()];
use broadcast_common::Serialize;
d.serialize_into(&mut buf).unwrap();
let re = reg.parse(&buf).unwrap();
match re {
RegisteredExtension::Builtin(d) => {
assert_eq!(d.tag_extension, 0x0B);
assert!(matches!(d.body, ExtensionBody::ServiceRelocated(_)));
}
other => panic!("expected Builtin, got {other:?}"),
}
}
#[test]
fn unknown_tag_extension_yields_builtin_raw() {
use crate::descriptors::extension::ExtensionBody;
let reg = ExtensionRegistry::new();
let sel = [0xAA, 0xBB];
let bytes = wrap_ext(0xFE, &sel);
let re = reg.parse(&bytes).unwrap();
match re {
RegisteredExtension::Builtin(d) => {
assert_eq!(d.tag_extension, 0xFE);
assert!(matches!(d.body, ExtensionBody::Raw(b) if b == sel));
}
other => panic!("expected Builtin, got {other:?}"),
}
}
#[test]
fn parse_rejects_wrong_tag() {
let reg = ExtensionRegistry::new();
let raw = [0x43, 1, 0x04];
assert!(matches!(
reg.parse(&raw).unwrap_err(),
Error::InvalidDescriptor { tag: 0x43, .. }
));
}
#[test]
fn parse_rejects_short_buffer() {
let reg = ExtensionRegistry::new();
let raw = [TAG];
assert!(matches!(
reg.parse(&raw).unwrap_err(),
Error::BufferTooShort(..)
));
}
#[test]
fn parse_rejects_empty_body() {
let reg = ExtensionRegistry::new();
let raw = [TAG, 0];
assert!(matches!(
reg.parse(&raw).unwrap_err(),
Error::InvalidDescriptor { tag: TAG, .. }
));
}
#[cfg(feature = "serde")]
#[test]
fn custom_variant_serializes_via_erased_serde() {
let mut reg = ExtensionRegistry::new();
reg.register::<MyExtBody>();
let bytes = wrap_ext(TEST_TAG_EXTENSION, &[0x01, 0x02]);
let re = reg.parse(&bytes).unwrap();
let json = serde_json::to_value(&re).unwrap();
let custom = json.get("custom").expect("expected 'custom' key");
assert_eq!(custom["tag_extension"], TEST_TAG_EXTENSION as u64);
assert_eq!(custom["value"]["payload"], serde_json::json!([1, 2]));
}
}