1use alloc::{collections::VecDeque, vec::Vec};
2
3use crate::wire::{Address, Frame, FrameKind, FrameRepair, PhysicalLayer, WireError, xor_checksum};
4
5pub const MAXIMUM_DECODE_BUFFER_CAPACITY: usize = 16 * 1024 * 1024;
7pub const MAXIMUM_DECODE_EVENTS_PER_PUSH: usize = 4096;
9
10#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
12pub enum ChecksumPolicy {
13 #[default]
15 Strict,
16 KnownGateway {
18 delimiter_bit: bool,
20 checksum_source_node: Option<u8>,
22 },
23}
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub struct DecodeLimits {
28 pub buffer_capacity: usize,
30 pub minimum_preambles: u8,
32 pub checksum_policy: ChecksumPolicy,
34}
35
36impl Default for DecodeLimits {
37 fn default() -> Self {
38 Self {
39 buffer_capacity: 4096,
40 minimum_preambles: 2,
41 checksum_policy: ChecksumPolicy::Strict,
42 }
43 }
44}
45
46impl DecodeLimits {
47 pub const fn with_buffer_capacity(mut self, buffer_capacity: usize) -> Self {
49 self.buffer_capacity = buffer_capacity;
50 self
51 }
52
53 pub const fn with_minimum_preambles(mut self, minimum_preambles: u8) -> Self {
55 self.minimum_preambles = minimum_preambles;
56 self
57 }
58
59 pub const fn with_checksum_policy(mut self, checksum_policy: ChecksumPolicy) -> Self {
61 self.checksum_policy = checksum_policy;
62 self
63 }
64
65 pub const fn validate(self) -> Result<(), DecodeLimitsError> {
67 if self.buffer_capacity == 0 {
68 return Err(DecodeLimitsError::EmptyBuffer);
69 }
70 if self.buffer_capacity > MAXIMUM_DECODE_BUFFER_CAPACITY {
71 return Err(DecodeLimitsError::BufferLimit(self.buffer_capacity));
72 }
73 if self.minimum_preambles == 0 {
74 return Err(DecodeLimitsError::NoPreambles);
75 }
76 if let ChecksumPolicy::KnownGateway {
77 checksum_source_node: Some(node),
78 ..
79 } = self.checksum_policy
80 && node > 63
81 {
82 return Err(DecodeLimitsError::ChecksumSourceNode(node));
83 }
84 Ok(())
85 }
86}
87
88#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
90pub enum DecodeLimitsError {
91 #[error("decoder buffer_capacity must be greater than zero")]
93 EmptyBuffer,
94 #[error("decoder buffer_capacity {0} exceeds the supported limit")]
96 BufferLimit(usize),
97 #[error("decoder minimum_preambles must be greater than zero")]
99 NoPreambles,
100 #[error("checksum source node {0} is outside 0..=63")]
102 ChecksumSourceNode(u8),
103}
104
105#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
107pub struct DecodeStatistics {
108 pub frames: u64,
110 pub discarded_bytes: u64,
112 pub checksum_failures: u64,
114 pub overflow_bytes: u64,
116 pub repaired_frames: u64,
118 pub event_limit_hits: u64,
120}
121
122#[derive(Debug, Clone, PartialEq, Eq)]
124pub enum DecodeEvent {
125 Frame(Frame),
127 Rejected(WireError),
129}
130
131#[derive(Debug, Clone)]
133pub struct FrameDecoder {
134 bytes: VecDeque<u8>,
135 limits: DecodeLimits,
136 statistics: DecodeStatistics,
137}
138
139enum DecoderStep {
140 NoCandidate,
141 NeedMore,
142 Discard(usize),
143 Rejected {
144 error: WireError,
145 consumed: usize,
146 checksum_failure: bool,
147 },
148 Frame {
149 frame: Frame,
150 consumed: usize,
151 repaired: bool,
152 },
153}
154
155impl FrameDecoder {
156 pub fn new(limits: DecodeLimits) -> Self {
158 let limits = DecodeLimits {
159 buffer_capacity: limits
160 .buffer_capacity
161 .clamp(1, MAXIMUM_DECODE_BUFFER_CAPACITY),
162 minimum_preambles: limits.minimum_preambles.max(1),
163 checksum_policy: limits.checksum_policy,
164 };
165 Self {
166 bytes: VecDeque::new(),
167 limits,
168 statistics: DecodeStatistics::default(),
169 }
170 }
171
172 pub fn try_new(limits: DecodeLimits) -> Result<Self, DecodeLimitsError> {
174 limits.validate()?;
175 Ok(Self::new(limits))
176 }
177
178 pub const fn limits(&self) -> DecodeLimits {
180 self.limits
181 }
182
183 pub fn push(&mut self, fragment: &[u8]) -> Vec<DecodeEvent> {
185 self.append_bounded(fragment);
186 let mut events = Vec::new();
187 while events.len() < MAXIMUM_DECODE_EVENTS_PER_PUSH
188 && let Some(event) = self.next_event()
189 {
190 events.push(event);
191 }
192 if events.len() == MAXIMUM_DECODE_EVENTS_PER_PUSH && !self.bytes.is_empty() {
193 self.statistics.event_limit_hits = self.statistics.event_limit_hits.saturating_add(1);
194 self.retain_possible_preambles();
195 }
196 events
197 }
198
199 pub const fn statistics(&self) -> DecodeStatistics {
201 self.statistics
202 }
203
204 pub fn buffered_len(&self) -> usize {
206 self.bytes.len()
207 }
208
209 pub fn clear(&mut self) {
211 self.bytes.clear();
212 }
213
214 fn append_bounded(&mut self, fragment: &[u8]) {
215 let overflow = self
216 .bytes
217 .len()
218 .saturating_add(fragment.len())
219 .saturating_sub(self.limits.buffer_capacity);
220 if overflow == 0 {
221 self.bytes.extend(fragment.iter().copied());
222 return;
223 }
224
225 let from_buffer = overflow.min(self.bytes.len());
226 self.bytes.drain(..from_buffer);
227 let from_fragment = overflow.saturating_sub(from_buffer).min(fragment.len());
228 self.bytes.extend(fragment[from_fragment..].iter().copied());
229 self.statistics.overflow_bytes = self
230 .statistics
231 .overflow_bytes
232 .saturating_add(u64::try_from(overflow).unwrap_or(u64::MAX));
233 }
234
235 fn next_event(&mut self) -> Option<DecodeEvent> {
236 loop {
237 let limits = self.limits;
238 let step = Self::analyze(self.bytes.make_contiguous(), limits);
239 match step {
240 DecoderStep::NoCandidate => {
241 self.retain_possible_preambles();
242 return None;
243 }
244 DecoderStep::NeedMore => return None,
245 DecoderStep::Discard(count) => self.discard(count),
246 DecoderStep::Rejected {
247 error,
248 consumed,
249 checksum_failure,
250 } => {
251 if checksum_failure {
252 self.statistics.checksum_failures =
253 self.statistics.checksum_failures.saturating_add(1);
254 }
255 self.discard(consumed);
256 return Some(DecodeEvent::Rejected(error));
257 }
258 DecoderStep::Frame {
259 frame,
260 consumed,
261 repaired,
262 } => {
263 self.bytes.drain(..consumed);
264 self.statistics.frames = self.statistics.frames.saturating_add(1);
265 if repaired {
266 self.statistics.repaired_frames =
267 self.statistics.repaired_frames.saturating_add(1);
268 }
269 return Some(DecodeEvent::Frame(frame));
270 }
271 }
272 }
273 }
274
275 fn analyze(bytes: &[u8], limits: DecodeLimits) -> DecoderStep {
276 let Some((delimiter_index, preamble_start, preamble_count)) =
277 Self::find_candidate(bytes, limits)
278 else {
279 return DecoderStep::NoCandidate;
280 };
281 if preamble_start > 0 {
282 return DecoderStep::Discard(preamble_start);
283 }
284
285 let mut delimiter = bytes[delimiter_index];
286 let mut repair = None;
287 if FrameKind::from_delimiter(delimiter).is_none()
288 && Self::allow_delimiter_repair(limits.checksum_policy)
289 && FrameKind::from_delimiter(delimiter ^ 0x10).is_some()
290 {
291 delimiter ^= 0x10;
292 repair = Some(FrameRepair::DelimiterBit);
293 }
294 let long = delimiter & 0x80 != 0;
295 let address_len = if long { 5 } else { 1 };
296 let expansion_len = usize::from((delimiter >> 5) & 0x03);
297 let command_index = delimiter_index + 1 + address_len + expansion_len;
298 let count_index = command_index + 1;
299 if bytes.len() <= count_index {
300 return DecoderStep::NeedMore;
301 }
302 let payload_len = usize::from(bytes[count_index]);
303 let checksum_index = count_index + 1 + payload_len;
304 if bytes.len() <= checksum_index {
305 return DecoderStep::NeedMore;
306 }
307
308 let expected = xor_checksum(&bytes[delimiter_index..checksum_index]);
309 let actual = bytes[checksum_index];
310 let delimiter_checksum_matches =
311 Self::allow_delimiter_repair(limits.checksum_policy) && expected ^ 0x10 == actual;
312 let address_repair = if expected != actual && !delimiter_checksum_matches && !long {
313 Self::short_address_repair(
314 limits.checksum_policy,
315 bytes[delimiter_index + 1],
316 expected,
317 actual,
318 )
319 } else {
320 None
321 };
322 if expected != actual && !delimiter_checksum_matches && address_repair.is_none() {
323 return DecoderStep::Rejected {
324 error: WireError::Checksum { expected, actual },
325 consumed: delimiter_index + 1,
326 checksum_failure: true,
327 };
328 }
329 if delimiter_checksum_matches {
330 repair = Some(FrameRepair::DelimiterBit);
331 }
332 if let Some(address_repair) = address_repair {
333 repair = Some(address_repair);
334 }
335
336 let address_start = delimiter_index + 1;
337 let address_end = address_start + address_len;
338 let address = match Address::read_from(&bytes[address_start..address_end], long) {
339 Ok(address) => address,
340 Err(error) => {
341 return DecoderStep::Rejected {
342 error,
343 consumed: checksum_index + 1,
344 checksum_failure: false,
345 };
346 }
347 };
348 let Some(kind) = FrameKind::from_delimiter(delimiter) else {
349 return DecoderStep::Rejected {
350 error: WireError::Delimiter(delimiter),
351 consumed: delimiter_index + 1,
352 checksum_failure: false,
353 };
354 };
355 DecoderStep::Frame {
356 frame: Frame {
357 preambles: u8::try_from(preamble_count).unwrap_or(u8::MAX),
358 kind,
359 physical_layer: PhysicalLayer::from_delimiter(delimiter),
360 address,
361 expansion: bytes[address_end..command_index].to_vec(),
362 wire_command: bytes[command_index],
363 payload: bytes[count_index + 1..checksum_index].to_vec(),
364 repair,
365 },
366 consumed: checksum_index + 1,
367 repaired: repair.is_some(),
368 }
369 }
370
371 fn find_candidate(bytes: &[u8], limits: DecodeLimits) -> Option<(usize, usize, usize)> {
372 let minimum_preambles = usize::from(limits.minimum_preambles);
373 bytes.iter().enumerate().find_map(|(index, byte)| {
374 if !Self::is_possible_delimiter(*byte, limits.checksum_policy) {
375 return None;
376 }
377 let preamble_start = bytes[..index]
378 .iter()
379 .rposition(|value| *value != 0xff)
380 .map_or(0, |position| position + 1);
381 let preamble_count = index - preamble_start;
382 let retained_count = preamble_count.min(usize::from(u8::MAX));
383 let retained_start = index - retained_count;
384 (preamble_count >= minimum_preambles).then_some((index, retained_start, retained_count))
385 })
386 }
387
388 fn retain_possible_preambles(&mut self) {
389 let keep = self
390 .bytes
391 .iter()
392 .rev()
393 .take_while(|byte| **byte == 0xff)
394 .count()
395 .min(usize::from(u8::MAX));
396 let discarded = self.bytes.len().saturating_sub(keep);
397 self.discard(discarded);
398 }
399
400 fn discard(&mut self, count: usize) {
401 self.bytes.drain(..count.min(self.bytes.len()));
402 self.statistics.discarded_bytes = self
403 .statistics
404 .discarded_bytes
405 .saturating_add(u64::try_from(count).unwrap_or(u64::MAX));
406 }
407
408 fn is_possible_delimiter(byte: u8, policy: ChecksumPolicy) -> bool {
409 FrameKind::from_delimiter(byte).is_some()
410 || (Self::allow_delimiter_repair(policy)
411 && FrameKind::from_delimiter(byte ^ 0x10).is_some())
412 }
413
414 const fn allow_delimiter_repair(policy: ChecksumPolicy) -> bool {
415 matches!(
416 policy,
417 ChecksumPolicy::KnownGateway {
418 delimiter_bit: true,
419 ..
420 }
421 )
422 }
423
424 fn short_address_repair(
425 policy: ChecksumPolicy,
426 received_address: u8,
427 expected: u8,
428 actual: u8,
429 ) -> Option<FrameRepair> {
430 let ChecksumPolicy::KnownGateway {
431 checksum_source_node: Some(source),
432 ..
433 } = policy
434 else {
435 return None;
436 };
437 if source > 63 {
438 return None;
439 }
440 let reconstructed = received_address ^ expected ^ actual;
441 (reconstructed & 0xc0 == received_address & 0xc0 && reconstructed & 0x3f == source)
442 .then_some(FrameRepair::ShortAddressRewrite {
443 checksum_source_node: source,
444 })
445 }
446}
447
448impl Default for FrameDecoder {
449 fn default() -> Self {
450 Self::new(DecodeLimits::default())
451 }
452}