use crate::error::{WireError, WireResult};
use crate::frame::{Frame, FrameHeader, FrameLimits, FrameView, HEADER_LEN, decode_frame_prefix};
pub const DEFAULT_BUFFER_CAPACITY: usize = 64 * 1024;
#[derive(Debug)]
pub struct FrameBuffer {
storage: Vec<u8>,
start: usize,
end: usize,
pending: usize,
limits: FrameLimits,
}
impl FrameBuffer {
#[must_use]
pub fn new(limits: FrameLimits) -> Self {
Self::with_capacity(limits, DEFAULT_BUFFER_CAPACITY)
}
#[must_use]
pub fn with_capacity(limits: FrameLimits, capacity: usize) -> Self {
Self {
storage: vec![0; capacity.max(HEADER_LEN)],
start: 0,
end: 0,
pending: 0,
limits,
}
}
#[must_use]
pub const fn limits(&self) -> &FrameLimits {
&self.limits
}
pub const fn set_limits(&mut self, limits: FrameLimits) {
self.limits = limits;
}
#[must_use]
pub const fn buffered(&self) -> usize {
self.end - self.start
}
#[must_use]
pub const fn is_empty(&self) -> bool {
self.buffered() == 0
}
#[must_use]
pub fn capacity(&self) -> usize {
self.storage.len()
}
pub const fn clear(&mut self) {
self.start = 0;
self.end = 0;
self.pending = 0;
}
#[must_use]
pub fn filled(&self) -> &[u8] {
self.storage.get(self.start..self.end).unwrap_or(&[])
}
pub fn needed(&self) -> WireResult<usize> {
let buffered = self.buffered();
if buffered < HEADER_LEN {
return Ok(HEADER_LEN - buffered);
}
let header = FrameHeader::parse(self.filled())?;
let payload_len = header.payload_len_usize()?;
self.limits.check_payload_len(payload_len)?;
Ok(header.total_len().saturating_sub(buffered).max(1))
}
pub fn push(&mut self, bytes: &[u8]) {
self.reserve(bytes.len());
let end = self.end;
if let Some(slot) = self.storage.get_mut(end..end + bytes.len()) {
slot.copy_from_slice(bytes);
self.end += bytes.len();
}
}
pub fn reserve(&mut self, additional: usize) {
if self.storage.len() - self.end >= additional {
return;
}
self.compact();
let required = self.end + additional;
if self.storage.len() < required {
let target = required.max(self.storage.len().saturating_mul(2));
self.storage.resize(target, 0);
}
}
pub fn spare_mut(&mut self, at_least: usize) -> &mut [u8] {
self.reserve(at_least.max(1));
let end = self.end;
self.storage.get_mut(end..).unwrap_or(&mut [])
}
pub const fn commit(&mut self, written: usize) {
let available = self.storage.len() - self.end;
self.end += if written > available {
available
} else {
written
};
}
pub const fn advance(&mut self) {
if self.pending == 0 {
return;
}
self.start += self.pending;
self.pending = 0;
if self.start == self.end {
self.start = 0;
self.end = 0;
}
}
pub fn frame_ready(&self) -> WireResult<bool> {
let buffered = self.buffered();
if buffered < HEADER_LEN {
return Ok(false);
}
let header = FrameHeader::parse(self.filled())?;
let payload_len = header.payload_len_usize()?;
self.limits.check_payload_len(payload_len)?;
if self.limits.require_crc() && !header.has_crc() {
return Err(WireError::MissingCrc);
}
Ok(buffered >= header.total_len())
}
pub fn next_frame(&mut self) -> WireResult<Option<FrameView<'_>>> {
self.advance();
if !self.frame_ready()? {
return Ok(None);
}
let buffered = self.buffered();
let total = FrameHeader::parse(self.filled())?.total_len();
self.pending = total;
let bytes =
self.storage
.get(self.start..self.start + total)
.ok_or(WireError::Truncated {
expected: total,
found: buffered,
})?;
decode_frame_prefix(bytes, &self.limits).map(Some)
}
pub fn next_owned_frame(&mut self) -> WireResult<Option<Frame>> {
Ok(self.next_frame()?.map(|view| view.to_owned_frame()))
}
fn compact(&mut self) {
if self.start == 0 {
return;
}
let buffered = self.buffered();
if buffered > 0 {
self.storage.copy_within(self.start..self.end, 0);
}
self.start = 0;
self.end = buffered;
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::frame::{FrameFlags, FrameKind, encode_frame};
fn frame(payload: &[u8]) -> Vec<u8> {
encode_frame(
FrameKind::Data,
FrameFlags::CRC,
payload,
&FrameLimits::uds(),
)
.unwrap()
}
#[test]
fn an_empty_buffer_yields_nothing() {
let mut buffer = FrameBuffer::new(FrameLimits::uds());
assert!(buffer.is_empty());
assert!(buffer.next_frame().unwrap().is_none());
assert_eq!(buffer.needed().unwrap(), HEADER_LEN);
}
#[test]
fn a_frame_split_byte_by_byte_reassembles() {
let bytes = frame(b"hello world");
let mut buffer = FrameBuffer::new(FrameLimits::uds());
for (index, byte) in bytes.iter().enumerate() {
buffer.push(&[*byte]);
let complete = buffer.next_frame().unwrap().is_some();
assert_eq!(complete, index + 1 == bytes.len(), "at byte {index}");
}
}
#[test]
fn needed_shrinks_as_bytes_arrive() {
let bytes = frame(b"payload");
let mut buffer = FrameBuffer::new(FrameLimits::uds());
assert_eq!(buffer.needed().unwrap(), HEADER_LEN);
buffer.push(&bytes[..HEADER_LEN]);
assert_eq!(buffer.needed().unwrap(), bytes.len() - HEADER_LEN);
buffer.push(&bytes[HEADER_LEN..bytes.len() - 1]);
assert_eq!(buffer.needed().unwrap(), 1);
}
#[test]
fn several_frames_in_one_push_come_out_in_order() {
let mut stream = Vec::new();
for payload in [b"one".as_slice(), b"two", b"three"] {
stream.extend_from_slice(&frame(payload));
}
let mut buffer = FrameBuffer::new(FrameLimits::uds());
buffer.push(&stream);
for expected in [b"one".as_slice(), b"two", b"three"] {
let view = buffer.next_frame().unwrap().expect("a complete frame");
assert_eq!(view.payload(), expected);
}
assert!(buffer.next_frame().unwrap().is_none());
assert!(buffer.is_empty(), "a drained buffer resets its cursors");
}
#[test]
fn owned_frames_outlive_the_next_read() {
let mut buffer = FrameBuffer::new(FrameLimits::uds());
buffer.push(&frame(b"first"));
let owned = buffer.next_owned_frame().unwrap().expect("complete");
buffer.push(&frame(b"second"));
let second = buffer.next_owned_frame().unwrap().expect("complete");
assert_eq!(owned.payload(), b"first");
assert_eq!(second.payload(), b"second");
}
#[test]
fn the_spare_region_is_writable_and_committed() {
let bytes = frame(b"direct");
let mut buffer = FrameBuffer::new(FrameLimits::uds());
let spare = buffer.spare_mut(bytes.len());
assert!(spare.len() >= bytes.len());
spare[..bytes.len()].copy_from_slice(&bytes);
buffer.commit(bytes.len());
assert_eq!(
buffer
.next_frame()
.unwrap()
.map(|view| view.payload().to_vec()),
Some(b"direct".to_vec())
);
}
#[test]
fn committing_more_than_the_capacity_is_clamped_not_fatal() {
let mut buffer = FrameBuffer::with_capacity(FrameLimits::uds(), 16);
buffer.commit(1_000_000);
assert!(buffer.buffered() <= buffer.capacity());
}
#[test]
fn the_buffer_grows_for_a_frame_larger_than_its_capacity() {
let payload = vec![0x5A; 100_000];
let bytes = frame(&payload);
let mut buffer = FrameBuffer::with_capacity(FrameLimits::uds(), 64);
buffer.push(&bytes);
let view = buffer.next_frame().unwrap().expect("complete");
assert_eq!(view.payload().len(), payload.len());
assert!(buffer.capacity() >= bytes.len());
}
#[test]
fn compaction_keeps_a_partial_frame_intact() {
let first = frame(b"first frame");
let second = frame(b"second frame");
let mut buffer = FrameBuffer::with_capacity(FrameLimits::uds(), first.len() + 4);
buffer.push(&first);
buffer.push(&second[..4]);
assert!(buffer.next_frame().unwrap().is_some());
buffer.push(&second[4..]);
let view = buffer.next_frame().unwrap().expect("complete");
assert_eq!(view.payload(), b"second frame");
}
#[test]
fn a_corrupt_header_is_an_error_not_a_stall() {
let mut buffer = FrameBuffer::new(FrameLimits::uds());
buffer.push(b"NOTASTRSFRAME");
assert!(matches!(
buffer.next_frame(),
Err(WireError::BadMagic { .. })
));
}
#[test]
fn an_oversize_declared_length_is_refused_before_it_is_buffered() {
let tight = FrameLimits::uds().with_max_payload_bytes(8);
let header = crate::frame::FrameHeader::new(FrameKind::Data, FrameFlags::EMPTY, u32::MAX);
let mut buffer = FrameBuffer::new(tight);
buffer.push(&header.to_bytes());
assert!(matches!(
buffer.next_frame(),
Err(WireError::FrameTooLarge { .. })
));
assert!(matches!(
buffer.needed(),
Err(WireError::FrameTooLarge { .. })
));
assert!(
buffer.capacity() < 1 << 20,
"the buffer must not have grown to the forged length"
);
}
#[test]
fn a_missing_checksum_is_refused_when_the_policy_requires_one() {
let bytes = encode_frame(
FrameKind::Data,
FrameFlags::EMPTY,
b"x",
&FrameLimits::uds(),
)
.unwrap();
let mut buffer = FrameBuffer::new(FrameLimits::network());
buffer.push(&bytes);
assert!(matches!(buffer.next_frame(), Err(WireError::MissingCrc)));
}
#[test]
fn a_corrupt_payload_is_caught_by_the_checksum() {
let mut bytes = frame(b"integrity");
let last = bytes.len() - 5;
bytes[last] ^= 0xFF;
let mut buffer = FrameBuffer::new(FrameLimits::uds());
buffer.push(&bytes);
assert!(matches!(
buffer.next_frame(),
Err(WireError::CrcMismatch { .. })
));
}
#[test]
fn limits_can_be_tightened_after_the_handshake() {
let mut buffer = FrameBuffer::new(FrameLimits::default());
buffer.set_limits(FrameLimits::uds().with_max_payload_bytes(4));
assert_eq!(buffer.limits().max_payload_bytes(), 4);
buffer.push(&frame(b"too long"));
assert!(matches!(
buffer.next_frame(),
Err(WireError::FrameTooLarge { .. })
));
}
#[test]
fn clearing_drops_everything() {
let mut buffer = FrameBuffer::new(FrameLimits::uds());
buffer.push(&frame(b"x"));
buffer.clear();
assert!(buffer.is_empty());
assert!(buffer.next_frame().unwrap().is_none());
}
}