1use crate::error::DeltaError;
2
3const MAGIC: [u8; 2] = *b"DS";
4pub const MIN_WIRE_VERSION: u8 = 2;
5pub const WIRE_VERSION: u8 = 3;
6const HEADER_LEN: usize = 46;
7
8pub const FLAG_COMPRESSED_ZSTD: u16 = 1 << 0;
9pub const KNOWN_FLAGS: u16 = FLAG_COMPRESSED_ZSTD;
10pub const MAX_WIRE_PAYLOAD: usize = 64 * 1024 * 1024;
11pub const MAX_LOGICAL_PAYLOAD: usize = 64 * 1024 * 1024;
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct DecodeConfig {
19 pub max_packet_bytes: usize,
21 pub max_decompressed_bytes: usize,
23}
24
25impl Default for DecodeConfig {
26 fn default() -> Self {
27 Self {
28 max_packet_bytes: HEADER_LEN + MAX_WIRE_PAYLOAD,
29 max_decompressed_bytes: MAX_LOGICAL_PAYLOAD,
30 }
31 }
32}
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36#[repr(u8)]
37pub enum PacketKind {
38 Snapshot = 1,
39 Delta = 2,
40}
41
42#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct Packet {
50 pub kind: PacketKind,
51 pub flags: u16,
52 pub sequence: u64,
53 pub base_sequence: u64,
54 pub base_hash: u64,
55 pub schema_hash: u64,
56 pub payload: Vec<u8>,
57}
58
59impl Packet {
60 pub fn snapshot(sequence: u64, state_hash: u64, schema_hash: u64, payload: Vec<u8>) -> Self {
61 Self {
62 kind: PacketKind::Snapshot,
63 flags: 0,
64 sequence,
65 base_sequence: 0,
66 base_hash: state_hash,
67 schema_hash,
68 payload,
69 }
70 }
71
72 pub fn delta(
73 sequence: u64,
74 base_sequence: u64,
75 base_hash: u64,
76 schema_hash: u64,
77 payload: Vec<u8>,
78 ) -> Self {
79 Self {
80 kind: PacketKind::Delta,
81 flags: 0,
82 sequence,
83 base_sequence,
84 base_hash,
85 schema_hash,
86 payload,
87 }
88 }
89
90 pub fn encoded_len(&self) -> usize {
91 HEADER_LEN + self.payload.len()
92 }
93
94 pub fn is_compressed(&self) -> bool {
95 self.flags & FLAG_COMPRESSED_ZSTD != 0
96 }
97
98 pub fn payload_checksum(&self) -> u32 {
99 crc32fast::hash(&self.payload)
100 }
101
102 pub fn zstd_candidate(&self, level: i32, min_savings: usize) -> Result<Self, DeltaError> {
105 if self.is_compressed() || self.payload.len() < 64 {
106 return Ok(self.clone());
107 }
108 let compressed = zstd::bulk::compress(&self.payload, level)
109 .map_err(|e| DeltaError::Compression(e.to_string()))?;
110 if compressed.len().saturating_add(min_savings) >= self.payload.len() {
111 return Ok(self.clone());
112 }
113 let mut packet = self.clone();
114 packet.payload = compressed;
115 packet.flags |= FLAG_COMPRESSED_ZSTD;
116 Ok(packet)
117 }
118
119 pub fn logical_payload(&self) -> Result<Vec<u8>, DeltaError> {
120 self.logical_payload_with_config(&DecodeConfig::default())
121 }
122
123 pub fn logical_payload_with_config(
124 &self,
125 config: &DecodeConfig,
126 ) -> Result<Vec<u8>, DeltaError> {
127 if !self.is_compressed() {
128 if self.payload.len() > config.max_decompressed_bytes {
129 return Err(DeltaError::DecompressedPayloadTooLarge {
130 limit: config.max_decompressed_bytes,
131 actual: Some(self.payload.len()),
132 });
133 }
134 return Ok(self.payload.clone());
135 }
136 zstd::bulk::decompress(&self.payload, config.max_decompressed_bytes)
137 .map_err(|e| DeltaError::Compression(e.to_string()))
138 }
139
140 pub fn to_bytes(&self) -> Result<Vec<u8>, DeltaError> {
145 self.encode()
146 }
147
148 pub fn from_bytes(bytes: &[u8]) -> Result<Self, DeltaError> {
153 Self::decode_with_config(bytes, &DecodeConfig::default())
154 }
155
156 pub fn from_bytes_with_config(bytes: &[u8], config: &DecodeConfig) -> Result<Self, DeltaError> {
158 Self::decode_with_config(bytes, config)
159 }
160
161 pub fn encode(&self) -> Result<Vec<u8>, DeltaError> {
163 if self.flags & !KNOWN_FLAGS != 0 {
164 return Err(DeltaError::InvalidPacket("unknown packet flags".into()));
165 }
166 if self.payload.len() > MAX_WIRE_PAYLOAD {
167 return Err(DeltaError::PacketTooLarge {
168 limit: MAX_WIRE_PAYLOAD,
169 actual: self.payload.len(),
170 });
171 }
172 let payload_len = u32::try_from(self.payload.len())
173 .map_err(|_| DeltaError::InvalidPacket("payload too large".into()))?;
174 let mut out = Vec::with_capacity(self.encoded_len());
175 out.extend_from_slice(&MAGIC);
176 out.push(WIRE_VERSION);
177 out.push(self.kind as u8);
178 out.extend_from_slice(&self.flags.to_le_bytes());
179 out.extend_from_slice(&self.sequence.to_le_bytes());
180 out.extend_from_slice(&self.base_sequence.to_le_bytes());
181 out.extend_from_slice(&self.base_hash.to_le_bytes());
182 out.extend_from_slice(&self.schema_hash.to_le_bytes());
183 out.extend_from_slice(&self.payload_checksum().to_le_bytes());
184 out.extend_from_slice(&payload_len.to_le_bytes());
185 out.extend_from_slice(&self.payload);
186 Ok(out)
187 }
188
189 pub fn decode(bytes: &[u8]) -> Result<Self, DeltaError> {
190 Self::decode_with_config(bytes, &DecodeConfig::default())
191 }
192
193 pub fn decode_with_config(bytes: &[u8], config: &DecodeConfig) -> Result<Self, DeltaError> {
194 if bytes.len() > config.max_packet_bytes {
195 return Err(DeltaError::PacketTooLarge {
196 limit: config.max_packet_bytes,
197 actual: bytes.len(),
198 });
199 }
200 if bytes.len() < HEADER_LEN {
201 return Err(DeltaError::InvalidPacket(
202 "packet shorter than header".into(),
203 ));
204 }
205 if bytes[0..2] != MAGIC {
206 return Err(DeltaError::InvalidPacket("bad magic".into()));
207 }
208 let version = bytes[2];
209 if !(MIN_WIRE_VERSION..=WIRE_VERSION).contains(&version) {
210 return Err(DeltaError::ProtocolVersionRange {
211 received: version,
212 min_supported: MIN_WIRE_VERSION,
213 max_supported: WIRE_VERSION,
214 });
215 }
216 let kind = match bytes[3] {
217 1 => PacketKind::Snapshot,
218 2 => PacketKind::Delta,
219 value => {
220 return Err(DeltaError::InvalidPacket(format!(
221 "unknown packet kind {value}"
222 )))
223 }
224 };
225 let flags = u16::from_le_bytes(
226 bytes[4..6]
227 .try_into()
228 .map_err(|_| DeltaError::InvalidPacket("truncated flags".into()))?,
229 );
230 if flags & !KNOWN_FLAGS != 0 {
231 return Err(DeltaError::InvalidPacket("unknown packet flags".into()));
232 }
233 let sequence = u64::from_le_bytes(
234 bytes[6..14]
235 .try_into()
236 .map_err(|_| DeltaError::InvalidPacket("truncated sequence".into()))?,
237 );
238 let base_sequence = u64::from_le_bytes(
239 bytes[14..22]
240 .try_into()
241 .map_err(|_| DeltaError::InvalidPacket("truncated base sequence".into()))?,
242 );
243 let base_hash = u64::from_le_bytes(
244 bytes[22..30]
245 .try_into()
246 .map_err(|_| DeltaError::InvalidPacket("truncated base hash".into()))?,
247 );
248 let schema_hash = u64::from_le_bytes(
249 bytes[30..38]
250 .try_into()
251 .map_err(|_| DeltaError::InvalidPacket("truncated schema hash".into()))?,
252 );
253 let checksum = u32::from_le_bytes(
254 bytes[38..42]
255 .try_into()
256 .map_err(|_| DeltaError::InvalidPacket("truncated checksum".into()))?,
257 );
258 let payload_len = u32::from_le_bytes(
259 bytes[42..46]
260 .try_into()
261 .map_err(|_| DeltaError::InvalidPacket("truncated payload length".into()))?,
262 ) as usize;
263 let expected_len = HEADER_LEN
264 .checked_add(payload_len)
265 .ok_or_else(|| DeltaError::InvalidPacket("packet length arithmetic overflow".into()))?;
266 if payload_len > MAX_WIRE_PAYLOAD || expected_len > config.max_packet_bytes {
267 return Err(DeltaError::PacketTooLarge {
268 limit: config.max_packet_bytes,
269 actual: expected_len,
270 });
271 }
272 if bytes.len() != expected_len {
273 return Err(DeltaError::InvalidPacket("payload length mismatch".into()));
274 }
275 let payload = bytes[HEADER_LEN..].to_vec();
276 let actual = crc32fast::hash(&payload);
277 if actual != checksum {
278 return Err(DeltaError::ChecksumMismatch {
279 expected: checksum,
280 actual,
281 });
282 }
283 Ok(Self {
284 kind,
285 flags,
286 sequence,
287 base_sequence,
288 base_hash,
289 schema_hash,
290 payload,
291 })
292 }
293}