use std::{
collections::VecDeque,
sync::{Arc, Mutex},
time::{Duration, SystemTime, UNIX_EPOCH},
};
use crate::channel::{ByteChannel, ChannelError, ChannelFuture};
pub const DEFAULT_MAXIMUM_TRACE_BYTES: usize = 16 * 1024 * 1024;
pub const MAXIMUM_TRACE_BYTES: usize = 256 * 1024 * 1024;
pub const MAXIMUM_TRACE_RECORDS: usize = 1_048_576;
pub const DEFAULT_MAXIMUM_REPLAY_STEPS: usize = 65_536;
pub const DEFAULT_MAXIMUM_REPLAY_BYTES: usize = 16 * 1024 * 1024;
pub const MAXIMUM_REPLAY_STEPS: usize = 1_048_576;
pub const MAXIMUM_REPLAY_BYTES: usize = 256 * 1024 * 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TraceLimits {
pub maximum_records: usize,
pub maximum_bytes: usize,
}
impl Default for TraceLimits {
fn default() -> Self {
Self {
maximum_records: 4096,
maximum_bytes: DEFAULT_MAXIMUM_TRACE_BYTES,
}
}
}
impl TraceLimits {
pub const fn with_maximum_records(mut self, maximum_records: usize) -> Self {
self.maximum_records = maximum_records;
self
}
pub const fn with_maximum_bytes(mut self, maximum_bytes: usize) -> Self {
self.maximum_bytes = maximum_bytes;
self
}
pub const fn validate(self) -> Result<(), TraceLimitsError> {
if self.maximum_records == 0 || self.maximum_bytes == 0 {
return Err(TraceLimitsError::ZeroLimit);
}
if self.maximum_records > MAXIMUM_TRACE_RECORDS {
return Err(TraceLimitsError::RecordLimit(self.maximum_records));
}
if self.maximum_bytes > MAXIMUM_TRACE_BYTES {
return Err(TraceLimitsError::ByteLimit(self.maximum_bytes));
}
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub enum TraceLimitsError {
#[error("trace limits must be greater than zero")]
ZeroLimit,
#[error("trace record limit {0} exceeds the supported limit")]
RecordLimit(usize),
#[error("trace byte limit {0} exceeds the supported limit")]
ByteLimit(usize),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TraceDirection {
Outbound,
Inbound,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TraceRecord {
pub direction: TraceDirection,
pub timestamp: SystemTime,
pub bytes: Vec<u8>,
}
#[derive(Debug, Clone)]
pub struct Trace {
records: VecDeque<TraceRecord>,
limits: TraceLimits,
retained_bytes: usize,
dropped_records: u64,
dropped_bytes: u64,
}
impl Trace {
pub fn new(maximum_records: usize) -> Self {
Self::with_limits(TraceLimits {
maximum_records,
..TraceLimits::default()
})
}
pub fn with_limits(limits: TraceLimits) -> Self {
Self {
records: VecDeque::new(),
limits: TraceLimits {
maximum_records: limits.maximum_records.clamp(1, MAXIMUM_TRACE_RECORDS),
maximum_bytes: limits.maximum_bytes.clamp(1, MAXIMUM_TRACE_BYTES),
},
retained_bytes: 0,
dropped_records: 0,
dropped_bytes: 0,
}
}
pub fn try_with_limits(limits: TraceLimits) -> Result<Self, TraceLimitsError> {
limits.validate()?;
Ok(Self::with_limits(limits))
}
pub fn push(&mut self, record: TraceRecord) {
let record_bytes = record.bytes.len();
if record_bytes > self.limits.maximum_bytes {
self.note_dropped(record_bytes);
return;
}
while self.records.len() >= self.limits.maximum_records
|| self.retained_bytes.saturating_add(record_bytes) > self.limits.maximum_bytes
{
let Some(evicted) = self.records.pop_front() else {
break;
};
self.retained_bytes = self.retained_bytes.saturating_sub(evicted.bytes.len());
self.note_dropped(evicted.bytes.len());
}
self.retained_bytes = self.retained_bytes.saturating_add(record_bytes);
self.records.push_back(record);
}
pub fn records(&self) -> impl ExactSizeIterator<Item = &TraceRecord> {
self.records.iter()
}
pub const fn dropped(&self) -> u64 {
self.dropped_records
}
pub const fn retained_bytes(&self) -> usize {
self.retained_bytes
}
pub const fn dropped_bytes(&self) -> u64 {
self.dropped_bytes
}
pub const fn limits(&self) -> TraceLimits {
self.limits
}
pub fn to_pcapng(&self) -> Vec<u8> {
let mut output = Vec::new();
write_section_header(&mut output);
write_interface(&mut output);
for record in &self.records {
write_packet(&mut output, record);
}
output
}
fn note_dropped(&mut self, bytes: usize) {
self.dropped_records = self.dropped_records.saturating_add(1);
self.dropped_bytes = self
.dropped_bytes
.saturating_add(u64::try_from(bytes).unwrap_or(u64::MAX));
}
}
#[derive(Debug)]
pub struct RecordingChannel<C> {
inner: C,
trace: Arc<Mutex<Trace>>,
}
impl<C> RecordingChannel<C> {
pub fn new(inner: C, maximum_records: usize) -> (Self, Arc<Mutex<Trace>>) {
Self::with_limits(
inner,
TraceLimits {
maximum_records,
..TraceLimits::default()
},
)
}
pub fn with_limits(inner: C, limits: TraceLimits) -> (Self, Arc<Mutex<Trace>>) {
let trace = Arc::new(Mutex::new(Trace::with_limits(limits)));
(
Self {
inner,
trace: trace.clone(),
},
trace,
)
}
pub fn try_with_limits(
inner: C,
limits: TraceLimits,
) -> Result<(Self, Arc<Mutex<Trace>>), TraceLimitsError> {
limits.validate()?;
Ok(Self::with_limits(inner, limits))
}
fn record(&self, direction: TraceDirection, bytes: &[u8]) {
if let Ok(mut trace) = self.trace.lock() {
trace.push(TraceRecord {
direction,
timestamp: SystemTime::now(),
bytes: bytes.to_vec(),
});
}
}
}
impl<C: ByteChannel> ByteChannel for RecordingChannel<C> {
fn send<'a>(&'a mut self, bytes: &'a [u8]) -> ChannelFuture<'a, ()> {
Box::pin(async move {
self.inner.send(bytes).await?;
self.record(TraceDirection::Outbound, bytes);
Ok(())
})
}
fn receive<'a>(&'a mut self, buffer: &'a mut [u8]) -> ChannelFuture<'a, usize> {
Box::pin(async move {
let count = self.inner.receive(buffer).await?;
if count > buffer.len() {
return Err(ChannelError::Configuration(
"recorded channel returned more bytes than the receive buffer can hold",
));
}
self.record(TraceDirection::Inbound, &buffer[..count]);
Ok(count)
})
}
fn flush(&mut self) -> ChannelFuture<'_, ()> {
self.inner.flush()
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ReplayStep {
Expect(Vec<u8>),
Provide(Vec<u8>),
Fail,
}
impl ReplayStep {
const fn payload_bytes(&self) -> usize {
match self {
Self::Expect(bytes) | Self::Provide(bytes) => bytes.len(),
Self::Fail => 0,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ReplayLimits {
pub maximum_steps: usize,
pub maximum_bytes: usize,
}
impl Default for ReplayLimits {
fn default() -> Self {
Self {
maximum_steps: DEFAULT_MAXIMUM_REPLAY_STEPS,
maximum_bytes: DEFAULT_MAXIMUM_REPLAY_BYTES,
}
}
}
impl ReplayLimits {
pub const fn with_maximum_steps(mut self, maximum_steps: usize) -> Self {
self.maximum_steps = maximum_steps;
self
}
pub const fn with_maximum_bytes(mut self, maximum_bytes: usize) -> Self {
self.maximum_bytes = maximum_bytes;
self
}
pub const fn validate(self) -> Result<(), ReplayBuildError> {
if self.maximum_steps == 0 || self.maximum_bytes == 0 {
return Err(ReplayBuildError::ZeroLimit);
}
if self.maximum_steps > MAXIMUM_REPLAY_STEPS {
return Err(ReplayBuildError::StepLimit(self.maximum_steps));
}
if self.maximum_bytes > MAXIMUM_REPLAY_BYTES {
return Err(ReplayBuildError::ByteLimit(self.maximum_bytes));
}
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub enum ReplayBuildError {
#[error("replay limits must be greater than zero")]
ZeroLimit,
#[error("replay step limit {0} exceeds the supported limit")]
StepLimit(usize),
#[error("replay byte limit {0} exceeds the supported limit")]
ByteLimit(usize),
#[error("replay scenario exceeds its {0}-step limit")]
ScenarioSteps(usize),
#[error("replay scenario exceeds its {0}-byte limit")]
ScenarioBytes(usize),
}
#[derive(Debug)]
pub struct ReplayChannel {
steps: VecDeque<ReplayStep>,
pending: VecDeque<u8>,
}
impl ReplayChannel {
pub fn new(steps: impl IntoIterator<Item = ReplayStep>) -> Result<Self, ReplayBuildError> {
Self::with_limits(steps, ReplayLimits::default())
}
pub fn with_limits(
steps: impl IntoIterator<Item = ReplayStep>,
limits: ReplayLimits,
) -> Result<Self, ReplayBuildError> {
limits.validate()?;
let mut retained_bytes = 0usize;
let mut bounded = VecDeque::new();
for step in steps {
if bounded.len() >= limits.maximum_steps {
return Err(ReplayBuildError::ScenarioSteps(limits.maximum_steps));
}
retained_bytes = retained_bytes
.checked_add(step.payload_bytes())
.ok_or(ReplayBuildError::ScenarioBytes(limits.maximum_bytes))?;
if retained_bytes > limits.maximum_bytes {
return Err(ReplayBuildError::ScenarioBytes(limits.maximum_bytes));
}
bounded.push_back(step);
}
Ok(Self {
steps: bounded,
pending: VecDeque::new(),
})
}
pub fn is_complete(&self) -> bool {
self.steps.is_empty() && self.pending.is_empty()
}
}
impl ByteChannel for ReplayChannel {
fn send<'a>(&'a mut self, bytes: &'a [u8]) -> ChannelFuture<'a, ()> {
Box::pin(async move {
match self.steps.pop_front() {
Some(ReplayStep::Expect(expected)) if expected == bytes => Ok(()),
Some(ReplayStep::Expect(_)) => Err(ChannelError::Configuration(
"outgoing bytes do not match the scenario",
)),
Some(_) => Err(ChannelError::Configuration(
"scenario expected a read, not a write",
)),
None => Err(ChannelError::Closed),
}
})
}
fn receive<'a>(&'a mut self, buffer: &'a mut [u8]) -> ChannelFuture<'a, usize> {
Box::pin(async move {
if buffer.is_empty() {
return Err(ChannelError::Configuration(
"replay receive buffer cannot be empty",
));
}
if self.pending.is_empty() {
match self.steps.pop_front() {
Some(ReplayStep::Provide(bytes)) => self.pending.extend(bytes),
Some(ReplayStep::Fail) => {
return Err(ChannelError::Configuration("scheduled read failure"));
}
Some(ReplayStep::Expect(_)) => {
return Err(ChannelError::Configuration(
"scenario expected a write, not a read",
));
}
None => return Err(ChannelError::Closed),
}
}
let count = buffer.len().min(self.pending.len());
for destination in &mut buffer[..count] {
*destination = self.pending.pop_front().unwrap_or_default();
}
Ok(count)
})
}
fn flush(&mut self) -> ChannelFuture<'_, ()> {
Box::pin(async { Ok(()) })
}
}
fn write_section_header(output: &mut Vec<u8>) {
push_u32(output, 0x0a0d_0d0a);
push_u32(output, 28);
push_u32(output, 0x1a2b_3c4d);
output.extend_from_slice(&1u16.to_le_bytes());
output.extend_from_slice(&0u16.to_le_bytes());
output.extend_from_slice(&u64::MAX.to_le_bytes());
push_u32(output, 28);
}
fn write_interface(output: &mut Vec<u8>) {
push_u32(output, 1);
push_u32(output, 20);
output.extend_from_slice(&147u16.to_le_bytes());
output.extend_from_slice(&0u16.to_le_bytes());
push_u32(output, 65_535);
push_u32(output, 20);
}
fn write_packet(output: &mut Vec<u8>, record: &TraceRecord) {
let mut packet = Vec::with_capacity(record.bytes.len() + 1);
packet.push(match record.direction {
TraceDirection::Outbound => 0,
TraceDirection::Inbound => 1,
});
packet.extend_from_slice(&record.bytes);
let padded = (packet.len() + 3) & !3;
let total = 32 + padded;
let timestamp = u64::try_from(
record
.timestamp
.duration_since(UNIX_EPOCH)
.unwrap_or(Duration::ZERO)
.as_micros(),
)
.unwrap_or(u64::MAX);
let timestamp_bytes = timestamp.to_be_bytes();
push_u32(output, 6);
push_u32(output, u32::try_from(total).unwrap_or(u32::MAX));
push_u32(output, 0);
push_u32(
output,
u32::from_be_bytes(timestamp_bytes[..4].try_into().unwrap_or_default()),
);
push_u32(
output,
u32::from_be_bytes(timestamp_bytes[4..].try_into().unwrap_or_default()),
);
push_u32(output, u32::try_from(packet.len()).unwrap_or(u32::MAX));
push_u32(output, u32::try_from(packet.len()).unwrap_or(u32::MAX));
output.extend_from_slice(&packet);
output.resize(output.len() + padded - packet.len(), 0);
push_u32(output, u32::try_from(total).unwrap_or(u32::MAX));
}
fn push_u32(output: &mut Vec<u8>, value: u32) {
output.extend_from_slice(&value.to_le_bytes());
}