Skip to main content

delta_stream/
packet.rs

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/// Packet decoding limits used for untrusted transport bytes.
14///
15/// [`Packet::from_bytes`] uses [`DecodeConfig::default`]. Use
16/// [`Packet::from_bytes_with_config`] when an integration needs tighter limits.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct DecodeConfig {
19    /// Maximum total encoded packet size, including the wire header.
20    pub max_packet_bytes: usize,
21    /// Maximum logical payload size after decompression.
22    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/// Identifies whether a packet carries a full snapshot or a delta from a prior sequence.
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36#[repr(u8)]
37pub enum PacketKind {
38    Snapshot = 1,
39    Delta = 2,
40}
41
42/// A DeltaStream wire packet.
43///
44/// Packets are produced by [`crate::Publisher::update`] or [`crate::Publisher::encode`]
45/// and consumed by [`crate::Subscriber::apply`] or [`crate::Subscriber::receive`]. A
46/// packet is either a self-contained snapshot or a delta that names the sequence and
47/// state hash it depends on.
48#[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    /// Return a zstd-compressed copy when it is materially smaller.
103    /// The original packet is returned when compression does not pay for itself.
104    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    /// Serializes this packet into the DeltaStream wire format.
141    ///
142    /// The returned bytes are transport-independent and include the packet header,
143    /// payload length, and CRC32 payload checksum.
144    pub fn to_bytes(&self) -> Result<Vec<u8>, DeltaError> {
145        self.encode()
146    }
147
148    /// Decodes a packet from the DeltaStream wire format with safe default limits.
149    ///
150    /// This validates the magic bytes, wire version, packet kind, flags, payload length,
151    /// and CRC32 checksum before returning a packet.
152    pub fn from_bytes(bytes: &[u8]) -> Result<Self, DeltaError> {
153        Self::decode_with_config(bytes, &DecodeConfig::default())
154    }
155
156    /// Decodes a packet from bytes with caller-provided size limits.
157    pub fn from_bytes_with_config(bytes: &[u8], config: &DecodeConfig) -> Result<Self, DeltaError> {
158        Self::decode_with_config(bytes, config)
159    }
160
161    /// Serializes this packet into the DeltaStream wire format.
162    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}