Skip to main content

delta_stream/
sync.rs

1use std::marker::PhantomData;
2
3use crate::{
4    adaptive::{AdaptivePolicy, EncodeDecision},
5    binary::{
6        decode_agent_delta, decode_agent_state, encode_agent_delta, encode_agent_state, AgentDelta,
7    },
8    error::DeltaError,
9    packet::{DecodeConfig, Packet, PacketKind},
10    replay::ReplayWindow,
11    schema::{
12        decode_generic_delta, decode_generic_snapshot, encode_generic_delta,
13        encode_generic_snapshot, DeltaState, JsonFieldDelta,
14    },
15    state::AgentState,
16};
17
18pub const AGENT_SCHEMA_NAME: &str = "delta-stream/AgentState/v2";
19
20pub fn agent_schema_hash() -> u64 {
21    fnv1a64(AGENT_SCHEMA_NAME.as_bytes())
22}
23
24pub fn state_hash(state: &AgentState) -> Result<u64, DeltaError> {
25    Ok(fnv1a64(&encode_agent_state(state)?))
26}
27
28pub fn fnv1a64(bytes: &[u8]) -> u64 {
29    let mut hash = 0xcbf29ce484222325u64;
30    for &b in bytes {
31        hash ^= b as u64;
32        hash = hash.wrapping_mul(0x100000001b3);
33    }
34    hash
35}
36
37fn raw_snapshot(sequence: u64, state: &AgentState) -> Result<Packet, DeltaError> {
38    Ok(Packet::snapshot(
39        sequence,
40        state_hash(state)?,
41        agent_schema_hash(),
42        encode_agent_state(state)?,
43    ))
44}
45
46#[derive(Debug, Default)]
47pub struct Encoder {
48    sequence: u64,
49    last_state: Option<AgentState>,
50    policy: AdaptivePolicy,
51    last_decision: Option<EncodeDecision>,
52}
53
54impl Encoder {
55    pub fn with_policy(policy: AdaptivePolicy) -> Self {
56        Self {
57            policy,
58            ..Self::default()
59        }
60    }
61
62    /// Builds safe snapshot and delta candidates and lets the configured policy
63    /// policy choose raw or zstd-compressed representation.
64    pub fn encode(&mut self, state: &AgentState) -> Result<Packet, DeltaError> {
65        self.sequence = self.sequence.saturating_add(1);
66        let sequence = self.sequence;
67        let snapshot = raw_snapshot(sequence, state)?;
68
69        let packet = match &self.last_state {
70            None => {
71                let (selected, decision) = self.policy.select_initial(snapshot)?;
72                self.last_decision = Some(decision);
73                selected
74            }
75            Some(previous) => {
76                let delta = AgentDelta::between(previous, state);
77                let delta = Packet::delta(
78                    sequence,
79                    sequence - 1,
80                    state_hash(previous)?,
81                    agent_schema_hash(),
82                    encode_agent_delta(&delta)?,
83                );
84                let (selected, decision) = self.policy.select(snapshot, delta)?;
85                self.last_decision = Some(decision);
86                selected
87            }
88        };
89
90        self.last_state = Some(state.clone());
91        Ok(packet)
92    }
93
94    pub fn force_snapshot(&mut self, state: &AgentState) -> Result<Packet, DeltaError> {
95        self.sequence = self.sequence.saturating_add(1);
96        self.last_state = Some(state.clone());
97        let snapshot = raw_snapshot(self.sequence, state)?;
98        let (packet, decision) = self.policy.select_initial(snapshot)?;
99        self.last_decision = Some(decision);
100        Ok(packet)
101    }
102
103    /// Build an authoritative recovery snapshot at the current stream sequence.
104    /// Unlike `force_snapshot`, this does not advance the publisher sequence,
105    /// preventing one client's recovery from creating gaps for every other client.
106    pub fn recovery_snapshot(&self, state: &AgentState) -> Result<Packet, DeltaError> {
107        let snapshot = raw_snapshot(self.sequence, state)?;
108        Ok(self.policy.select_initial(snapshot)?.0)
109    }
110
111    pub fn sequence(&self) -> u64 {
112        self.sequence
113    }
114    pub fn last_decision(&self) -> Option<EncodeDecision> {
115        self.last_decision
116    }
117    pub fn policy(&self) -> AdaptivePolicy {
118        self.policy
119    }
120}
121
122#[derive(Debug, Clone, PartialEq)]
123pub enum ApplyResult {
124    Applied {
125        sequence: u64,
126        state: AgentState,
127    },
128    NeedSnapshot {
129        local_sequence: Option<u64>,
130        required_sequence: u64,
131    },
132    Duplicate {
133        sequence: u64,
134    },
135}
136
137#[derive(Debug, Default)]
138pub struct Decoder {
139    sequence: Option<u64>,
140    state: Option<AgentState>,
141    replay: ReplayWindow,
142}
143
144impl Decoder {
145    pub fn apply_packet(&mut self, packet: Packet) -> Result<ApplyResult, DeltaError> {
146        if packet.schema_hash != agent_schema_hash() {
147            return Err(DeltaError::SchemaMismatch {
148                expected: agent_schema_hash(),
149                received: packet.schema_hash,
150            });
151        }
152        if self.replay.contains(packet.sequence) {
153            return Ok(ApplyResult::Duplicate {
154                sequence: packet.sequence,
155            });
156        }
157        if self.sequence.is_some_and(|local| packet.sequence < local) {
158            return Ok(ApplyResult::Duplicate {
159                sequence: packet.sequence,
160            });
161        }
162
163        let result = match packet.kind {
164            PacketKind::Snapshot => {
165                let payload = packet.logical_payload_with_config(&DecodeConfig::default())?;
166                let state = decode_agent_state(&payload)?;
167                if state_hash(&state)? != packet.base_hash {
168                    return Err(DeltaError::InvalidState("snapshot hash mismatch"));
169                }
170                self.sequence = Some(packet.sequence);
171                self.state = Some(state.clone());
172                ApplyResult::Applied {
173                    sequence: packet.sequence,
174                    state,
175                }
176            }
177            PacketKind::Delta => {
178                if self.sequence != Some(packet.base_sequence) {
179                    return Ok(ApplyResult::NeedSnapshot {
180                        local_sequence: self.sequence,
181                        required_sequence: packet.base_sequence,
182                    });
183                }
184                let current = self
185                    .state
186                    .as_ref()
187                    .ok_or(DeltaError::InvalidState("decoder has no base state"))?;
188                if state_hash(current)? != packet.base_hash {
189                    return Ok(ApplyResult::NeedSnapshot {
190                        local_sequence: self.sequence,
191                        required_sequence: packet.base_sequence,
192                    });
193                }
194                let payload = packet.logical_payload_with_config(&DecodeConfig::default())?;
195                let delta = decode_agent_delta(&payload)?;
196                let next = delta.apply(current)?;
197                self.sequence = Some(packet.sequence);
198                self.state = Some(next.clone());
199                ApplyResult::Applied {
200                    sequence: packet.sequence,
201                    state: next,
202                }
203            }
204        };
205
206        self.replay.record(packet.sequence);
207        Ok(result)
208    }
209
210    pub fn state(&self) -> Option<&AgentState> {
211        self.state.as_ref()
212    }
213    pub fn sequence(&self) -> Option<u64> {
214        self.sequence
215    }
216    pub fn reset(&mut self) {
217        self.sequence = None;
218        self.state = None;
219        self.replay.clear();
220    }
221}
222
223pub struct GenericEncoder<T: DeltaState> {
224    sequence: u64,
225    last_state: Option<T>,
226    policy: AdaptivePolicy,
227    last_decision: Option<EncodeDecision>,
228}
229
230impl<T: DeltaState> Default for GenericEncoder<T> {
231    fn default() -> Self {
232        Self {
233            sequence: 0,
234            last_state: None,
235            policy: AdaptivePolicy::default(),
236            last_decision: None,
237        }
238    }
239}
240
241impl<T: DeltaState> GenericEncoder<T> {
242    pub fn with_policy(policy: AdaptivePolicy) -> Self {
243        Self {
244            policy,
245            ..Self::default()
246        }
247    }
248
249    pub fn encode(&mut self, state: &T) -> Result<Packet, DeltaError> {
250        self.sequence = self.sequence.saturating_add(1);
251        let sequence = self.sequence;
252        let bytes = encode_generic_snapshot(state)?;
253        let snapshot = Packet::snapshot(sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
254
255        let packet = match &self.last_state {
256            None => {
257                let (selected, decision) = self.policy.select_initial(snapshot)?;
258                self.last_decision = Some(decision);
259                selected
260            }
261            Some(previous) => {
262                let old = encode_generic_snapshot(previous)?;
263                let delta = JsonFieldDelta::between(previous, state)?;
264                let delta = Packet::delta(
265                    sequence,
266                    sequence - 1,
267                    fnv1a64(&old),
268                    T::schema_hash(),
269                    encode_generic_delta(&delta)?,
270                );
271                let (selected, decision) = self.policy.select(snapshot, delta)?;
272                self.last_decision = Some(decision);
273                selected
274            }
275        };
276
277        self.last_state = Some(state.clone());
278        Ok(packet)
279    }
280
281    pub fn force_snapshot(&mut self, state: &T) -> Result<Packet, DeltaError> {
282        self.sequence = self.sequence.saturating_add(1);
283        let bytes = encode_generic_snapshot(state)?;
284        self.last_state = Some(state.clone());
285        let snapshot = Packet::snapshot(self.sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
286        let (packet, decision) = self.policy.select_initial(snapshot)?;
287        self.last_decision = Some(decision);
288        Ok(packet)
289    }
290
291    pub fn recovery_snapshot(&self, state: &T) -> Result<Packet, DeltaError> {
292        let bytes = encode_generic_snapshot(state)?;
293        let snapshot = Packet::snapshot(self.sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
294        Ok(self.policy.select_initial(snapshot)?.0)
295    }
296
297    pub fn last_decision(&self) -> Option<EncodeDecision> {
298        self.last_decision
299    }
300    pub fn sequence(&self) -> u64 {
301        self.sequence
302    }
303}
304
305pub struct GenericDecoder<T: DeltaState> {
306    sequence: Option<u64>,
307    state: Option<T>,
308    replay: ReplayWindow,
309    decode_config: DecodeConfig,
310    _marker: PhantomData<T>,
311}
312
313impl<T: DeltaState> Default for GenericDecoder<T> {
314    fn default() -> Self {
315        Self {
316            sequence: None,
317            state: None,
318            replay: ReplayWindow::default(),
319            decode_config: DecodeConfig::default(),
320            _marker: PhantomData,
321        }
322    }
323}
324
325/// Result of applying a packet to a subscriber.
326///
327/// `Applied` contains the committed state after a snapshot or delta. `Duplicate` means
328/// the packet was already seen or is stale. `NeedSnapshot` means the subscriber could
329/// not safely apply a delta because its required base sequence or base hash is missing.
330#[derive(Debug, Clone, PartialEq)]
331pub enum GenericApplyResult<T> {
332    Applied {
333        sequence: u64,
334        state: T,
335    },
336    NeedSnapshot {
337        local_sequence: Option<u64>,
338        required_sequence: u64,
339    },
340    Duplicate {
341        sequence: u64,
342    },
343}
344
345impl<T: DeltaState> GenericDecoder<T> {
346    pub fn with_decode_config(decode_config: DecodeConfig) -> Self {
347        Self {
348            decode_config,
349            ..Self::default()
350        }
351    }
352
353    pub fn apply_packet(&mut self, packet: Packet) -> Result<GenericApplyResult<T>, DeltaError> {
354        if packet.schema_hash != T::schema_hash() {
355            return Err(DeltaError::SchemaMismatch {
356                expected: T::schema_hash(),
357                received: packet.schema_hash,
358            });
359        }
360        if self.replay.contains(packet.sequence) {
361            return Ok(GenericApplyResult::Duplicate {
362                sequence: packet.sequence,
363            });
364        }
365        if self.sequence.is_some_and(|local| packet.sequence < local) {
366            return Ok(GenericApplyResult::Duplicate {
367                sequence: packet.sequence,
368            });
369        }
370
371        let result = match packet.kind {
372            PacketKind::Snapshot => {
373                let payload = packet.logical_payload_with_config(&self.decode_config)?;
374                if fnv1a64(&payload) != packet.base_hash {
375                    return Err(DeltaError::InvalidState("snapshot hash mismatch"));
376                }
377                let state = decode_generic_snapshot::<T>(&payload)?;
378                self.sequence = Some(packet.sequence);
379                self.state = Some(state.clone());
380                GenericApplyResult::Applied {
381                    sequence: packet.sequence,
382                    state,
383                }
384            }
385            PacketKind::Delta => {
386                if self.sequence != Some(packet.base_sequence) {
387                    return Ok(GenericApplyResult::NeedSnapshot {
388                        local_sequence: self.sequence,
389                        required_sequence: packet.base_sequence,
390                    });
391                }
392                let current = self
393                    .state
394                    .as_ref()
395                    .ok_or(DeltaError::InvalidState("decoder has no base state"))?;
396                let current_bytes = encode_generic_snapshot(current)?;
397                if fnv1a64(&current_bytes) != packet.base_hash {
398                    return Ok(GenericApplyResult::NeedSnapshot {
399                        local_sequence: self.sequence,
400                        required_sequence: packet.base_sequence,
401                    });
402                }
403                let payload = packet.logical_payload_with_config(&self.decode_config)?;
404                let delta = decode_generic_delta(&payload)?;
405                let next = delta.apply(current)?;
406                self.sequence = Some(packet.sequence);
407                self.state = Some(next.clone());
408                GenericApplyResult::Applied {
409                    sequence: packet.sequence,
410                    state: next,
411                }
412            }
413        };
414
415        self.replay.record(packet.sequence);
416        Ok(result)
417    }
418    pub fn apply_packet_with_migrations(
419        &mut self,
420        packet: Packet,
421        migrations: &crate::migration::MigrationRegistry,
422    ) -> Result<GenericApplyResult<T>, DeltaError> {
423        if packet.schema_hash == T::schema_hash() {
424            return self.apply_packet(packet);
425        }
426        if packet.kind != PacketKind::Snapshot {
427            return Ok(GenericApplyResult::NeedSnapshot {
428                local_sequence: self.sequence,
429                required_sequence: packet.base_sequence,
430            });
431        }
432        if self.replay.contains(packet.sequence) {
433            return Ok(GenericApplyResult::Duplicate {
434                sequence: packet.sequence,
435            });
436        }
437        if self.sequence.is_some_and(|local| packet.sequence < local) {
438            return Ok(GenericApplyResult::Duplicate {
439                sequence: packet.sequence,
440            });
441        }
442        let payload = packet.logical_payload_with_config(&self.decode_config)?;
443        if fnv1a64(&payload) != packet.base_hash {
444            return Err(DeltaError::InvalidState("snapshot hash mismatch"));
445        }
446        let value: serde_json::Value = serde_json::from_slice(&payload)?;
447        let migrated = migrations.migrate(packet.schema_hash, T::schema_hash(), value)?;
448        let state: T = serde_json::from_value(migrated)?;
449        self.sequence = Some(packet.sequence);
450        self.state = Some(state.clone());
451        self.replay.record(packet.sequence);
452        Ok(GenericApplyResult::Applied {
453            sequence: packet.sequence,
454            state,
455        })
456    }
457
458    pub fn state(&self) -> Option<&T> {
459        self.state.as_ref()
460    }
461    pub fn sequence(&self) -> Option<u64> {
462        self.sequence
463    }
464    pub fn reset(&mut self) {
465        self.sequence = None;
466        self.state = None;
467        self.replay.clear();
468    }
469}