Skip to main content

delta_stream/
adaptive.rs

1use crate::{error::DeltaError, packet::Packet};
2
3/// Selects between raw and compressed snapshot or delta representations.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub enum EncodeMode {
6    Snapshot,
7    Delta,
8    SnapshotZstd,
9    DeltaZstd,
10}
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13pub struct EncodeDecision {
14    pub mode: EncodeMode,
15    pub snapshot_bytes: usize,
16    pub delta_bytes: Option<usize>,
17    pub snapshot_zstd_bytes: Option<usize>,
18    pub delta_zstd_bytes: Option<usize>,
19    pub selected_bytes: usize,
20}
21
22impl EncodeDecision {
23    pub fn initial(
24        snapshot_bytes: usize,
25        snapshot_zstd_bytes: Option<usize>,
26        mode: EncodeMode,
27        selected_bytes: usize,
28    ) -> Self {
29        Self {
30            mode,
31            snapshot_bytes,
32            delta_bytes: None,
33            snapshot_zstd_bytes,
34            delta_zstd_bytes: None,
35            selected_bytes,
36        }
37    }
38}
39
40/// Adaptive codec selection policy.
41///
42/// Evaluates raw and compressed snapshot and delta candidates, then selects the
43/// representation with the lowest configured cost.
44///
45/// A small penalty may be applied to compressed candidates to trade bandwidth
46/// savings for lower CPU usage and latency.
47#[derive(Debug, Clone, Copy, PartialEq)]
48pub struct AdaptivePolicy {
49    pub min_delta_savings_bytes: usize,
50    pub max_delta_ratio: f64,
51    pub enable_zstd: bool,
52    pub zstd_level: i32,
53    pub min_compression_savings_bytes: usize,
54    pub compression_cpu_penalty_bytes: usize,
55}
56
57impl Default for AdaptivePolicy {
58    fn default() -> Self {
59        Self {
60            min_delta_savings_bytes: 1,
61            max_delta_ratio: 0.98,
62            enable_zstd: cfg!(feature = "zstd-compression"),
63            zstd_level: 1,
64            min_compression_savings_bytes: 8,
65            compression_cpu_penalty_bytes: 0,
66        }
67    }
68}
69
70impl AdaptivePolicy {
71    fn score(&self, packet: &Packet) -> usize {
72        packet
73            .encoded_len()
74            .saturating_add(if packet.is_compressed() {
75                self.compression_cpu_penalty_bytes
76            } else {
77                0
78            })
79    }
80
81    pub fn select_initial(&self, snapshot: Packet) -> Result<(Packet, EncodeDecision), DeltaError> {
82        let raw_bytes = snapshot.encoded_len();
83        let compressed = if self.enable_zstd {
84            snapshot.zstd_candidate(self.zstd_level, self.min_compression_savings_bytes)?
85        } else {
86            snapshot.clone()
87        };
88        let compressed_bytes = compressed.encoded_len();
89        let use_compressed = self.enable_zstd
90            && compressed.is_compressed()
91            && self.score(&compressed) < self.score(&snapshot);
92        if use_compressed {
93            Ok((
94                compressed,
95                EncodeDecision::initial(
96                    raw_bytes,
97                    Some(compressed_bytes),
98                    EncodeMode::SnapshotZstd,
99                    compressed_bytes,
100                ),
101            ))
102        } else {
103            Ok((
104                snapshot,
105                EncodeDecision::initial(
106                    raw_bytes,
107                    Some(compressed_bytes),
108                    EncodeMode::Snapshot,
109                    raw_bytes,
110                ),
111            ))
112        }
113    }
114
115    pub fn select(
116        &self,
117        snapshot: Packet,
118        delta: Packet,
119    ) -> Result<(Packet, EncodeDecision), DeltaError> {
120        let snapshot_bytes = snapshot.encoded_len();
121        let delta_bytes = delta.encoded_len();
122
123        let delta_allowed = snapshot_bytes > 0
124            && (delta_bytes as f64 / snapshot_bytes as f64) <= self.max_delta_ratio
125            && delta_bytes.saturating_add(self.min_delta_savings_bytes) <= snapshot_bytes;
126
127        let snapshot_zstd = if self.enable_zstd {
128            snapshot.zstd_candidate(self.zstd_level, self.min_compression_savings_bytes)?
129        } else {
130            snapshot.clone()
131        };
132        let delta_zstd = if self.enable_zstd {
133            delta.zstd_candidate(self.zstd_level, self.min_compression_savings_bytes)?
134        } else {
135            delta.clone()
136        };
137        let snapshot_zstd_bytes = snapshot_zstd.encoded_len();
138        let delta_zstd_bytes = delta_zstd.encoded_len();
139
140        let mut best_packet = snapshot.clone();
141        let mut best_mode = EncodeMode::Snapshot;
142        let mut best_score = self.score(&snapshot);
143
144        if self.enable_zstd
145            && snapshot_zstd.is_compressed()
146            && self.score(&snapshot_zstd) < best_score
147        {
148            best_score = self.score(&snapshot_zstd);
149            best_packet = snapshot_zstd.clone();
150            best_mode = EncodeMode::SnapshotZstd;
151        }
152
153        if delta_allowed && self.score(&delta) < best_score {
154            best_score = self.score(&delta);
155            best_packet = delta.clone();
156            best_mode = EncodeMode::Delta;
157        }
158
159        if self.enable_zstd
160            && delta_allowed
161            && delta_zstd.is_compressed()
162            && self.score(&delta_zstd) < best_score
163        {
164            best_packet = delta_zstd.clone();
165            best_mode = EncodeMode::DeltaZstd;
166        }
167
168        let selected_bytes = best_packet.encoded_len();
169        Ok((
170            best_packet,
171            EncodeDecision {
172                mode: best_mode,
173                snapshot_bytes,
174                delta_bytes: Some(delta_bytes),
175                snapshot_zstd_bytes: Some(snapshot_zstd_bytes),
176                delta_zstd_bytes: Some(delta_zstd_bytes),
177                selected_bytes,
178            },
179        ))
180    }
181}