Skip to main content

nautilus_common/cache/
position.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Position snapshot storage for the platform [`Cache`].
17//!
18//! Three mechanisms share the "position snapshot" name and live here together:
19//!
20//! - The NETTING archive ([`Cache::snapshot_position`]), which preserves each closed position
21//!   cycle before its ID is reused, and backs cross-cycle realized PnL.
22//! - The durable correction boundary ([`Cache::snapshot_position_encoded`],
23//!   [`Cache::restore_snapshot_blob`]), which produces and restores the encoded frames an event
24//!   store anchors.
25//! - The routine state snapshot ([`Cache::snapshot_position_state`]), which writes position state
26//!   to the backing database, defaulting to open positions.
27
28use std::{cell::OnceCell, str::FromStr};
29
30use ahash::AHashSet;
31use bytes::Bytes;
32use nautilus_core::{UUID4, UnixNanos};
33use nautilus_model::{
34    identifiers::{AccountId, InstrumentId, PositionId},
35    position::Position,
36    types::Money,
37};
38
39use super::{Cache, handle_persistence_result};
40
41/// Cache-owned reference to a snapshot blob.
42///
43/// The cache writes and later fetches the blob; external systems persist this opaque reference
44/// and may hash the bytes before recording a durable anchor.
45#[derive(Clone, Debug, PartialEq, Eq)]
46pub struct CacheSnapshotRef {
47    /// Opaque cache-owned snapshot location.
48    pub blob_ref: String,
49    /// Snapshot bytes stored under [`Self::blob_ref`].
50    pub blob: Bytes,
51}
52
53impl CacheSnapshotRef {
54    /// Prefix for durable position snapshot locations.
55    pub const POSITION_PREFIX: &str = "cache://position-snapshots/";
56
57    /// Creates a new [`CacheSnapshotRef`].
58    #[must_use]
59    pub fn new(blob_ref: impl Into<String>, blob: impl Into<Bytes>) -> Self {
60        Self {
61            blob_ref: blob_ref.into(),
62            blob: blob.into(),
63        }
64    }
65
66    /// Reads the instrument ID without resolving the snapshot's currency definitions.
67    ///
68    /// # Errors
69    ///
70    /// Returns an error if the JSON is malformed or the instrument ID is missing or invalid.
71    #[cfg(feature = "defi")]
72    pub fn position_instrument_id(blob: &[u8]) -> anyhow::Result<InstrumentId> {
73        #[derive(serde::Deserialize)]
74        struct Identity {
75            instrument_id: InstrumentId,
76        }
77
78        Ok(serde_json::from_slice::<Identity>(blob)?.instrument_id)
79    }
80}
81
82/// One frame in a position's NETTING snapshot history.
83///
84/// A frame keeps the archived position and encodes it only when a consumer asks for the bytes,
85/// so a run with no durable snapshot sink never pays the encode on the order path. A frame
86/// restored from durable bytes keeps those exact bytes, since anchors record their content hash.
87#[derive(Debug)]
88pub(super) struct PositionSnapshotFrame {
89    position: Position,
90    encoded: OnceCell<Bytes>,
91}
92
93impl PositionSnapshotFrame {
94    fn new(position: Position, encoded: Option<Bytes>) -> Self {
95        Self {
96            position,
97            encoded: encoded.map_or_else(OnceCell::new, OnceCell::from),
98        }
99    }
100
101    fn encoded(&self) -> anyhow::Result<Bytes> {
102        if let Some(encoded) = self.encoded.get() {
103            return Ok(encoded.clone());
104        }
105
106        let encoded = Bytes::from(serde_json::to_vec(&self.position)?);
107        let _ = self.encoded.set(encoded.clone());
108
109        Ok(encoded)
110    }
111}
112
113impl Cache {
114    #[cfg(feature = "defi")]
115    pub(crate) fn has_position_history(
116        &self,
117        instrument_id: &InstrumentId,
118    ) -> anyhow::Result<bool> {
119        if self
120            .positions
121            .values()
122            .any(|position| position.borrow().instrument_id == *instrument_id)
123            || self
124                .position_snapshots
125                .values()
126                .flatten()
127                .any(|frame| frame.position.instrument_id == *instrument_id)
128        {
129            return Ok(true);
130        }
131
132        for (key, blob) in &self.general {
133            if key.starts_with(CacheSnapshotRef::POSITION_PREFIX)
134                && CacheSnapshotRef::position_instrument_id(blob)? == *instrument_id
135            {
136                return Ok(true);
137            }
138        }
139
140        Ok(false)
141    }
142
143    /// Creates a snapshot of the `position` by cloning it, assigning a new ID, and storing it
144    /// in the position snapshots.
145    ///
146    /// The copy excludes `replay_events` and `fill_voids`, which no snapshot consumer reads,
147    /// so snapshot size stays independent of the fills applied to the position ID. The copy
148    /// encodes only when a consumer asks for the bytes, so this call stays off the encode path
149    /// unless a backing database has to persist the frame.
150    ///
151    /// Persistence failures are logged without failing the operation.
152    ///
153    /// # Errors
154    ///
155    /// Returns an error if serializing the snapshot or validating its cache entry fails, or the
156    /// backing reports a DeFi currency integrity error.
157    pub fn snapshot_position(&mut self, position: &Position) -> anyhow::Result<()> {
158        let (blob_ref, snapshot) = self.build_position_snapshot(position);
159
160        let encoded = if self.database.is_some() {
161            Some(self.persist_position_snapshot(&blob_ref, &snapshot)?)
162        } else {
163            None
164        };
165        self.store_position_snapshot(position.id, snapshot, encoded);
166
167        Ok(())
168    }
169
170    /// Creates a snapshot of the `position` and returns its encoded cache-owned reference.
171    ///
172    /// Behaves as [`Self::snapshot_position`] but encodes the frame eagerly, for callers that
173    /// record the bytes or their content hash against a durable anchor.
174    ///
175    /// Returning the reference does not confirm that its blob has been persisted. A durable
176    /// recovery anchor requires separate confirmation of blob storage.
177    ///
178    /// Persistence failures are logged without failing the operation.
179    ///
180    /// # Errors
181    ///
182    /// Returns an error if serializing the snapshot or validating its cache entry fails, or the
183    /// backing reports a DeFi currency integrity error.
184    pub fn snapshot_position_encoded(
185        &mut self,
186        position: &Position,
187    ) -> anyhow::Result<CacheSnapshotRef> {
188        let (blob_ref, snapshot) = self.build_position_snapshot(position);
189        let encoded = self.persist_position_snapshot(&blob_ref, &snapshot)?;
190
191        self.store_position_snapshot(position.id, snapshot, Some(encoded.clone()));
192
193        Ok(CacheSnapshotRef::new(blob_ref, encoded))
194    }
195
196    /// Replaces every NETTING archive frame held for `position` with the cycles a correction
197    /// rebuilt, worth `closed_cycles_pnl`.
198    ///
199    /// A correction that reaches an earlier cycle moves the boundaries the existing frames
200    /// describe, so they cannot be reconciled and are settled into one frame instead. Pass
201    /// `None` when no closed cycle precedes the current one, which leaves no archived cycle.
202    /// As with [`Self::purge_position`], the durable `cache://position-snapshots/...` entries
203    /// stay in general cache state.
204    ///
205    /// The settled frame drops the fills it copies from `position`, which belong to the current
206    /// cycle rather than the settled ones, since consumers match frames to cycles by their fills.
207    /// It keeps the current cycle's `position.trade_ids`. Earlier cycles' trade history remains
208    /// in `position.replay_events`.
209    ///
210    /// Requires `closed_cycles_pnl` to account for every frame held, since this removes all of
211    /// them. The position's replay log must therefore span every archived cycle for the ID. Any
212    /// future retention cap on the log has to preserve that at trim time, either by folding the
213    /// trimmed cycles' realized PnL into a baseline the rebuild adds to its banked total, or by
214    /// purging the frames those cycles produced in the same operation. Settling cannot detect the
215    /// shortfall, because frames carry no cycle identity to match against the retained log.
216    ///
217    /// Known limitation, shared with [`Self::purge_position`]: frame indices restart from zero,
218    /// so a later cycle can overwrite bytes an event store anchor already recorded, failing its
219    /// content-hash check on restore. Frames need an identity independent of their vector
220    /// position to fix it.
221    pub fn settle_position_snapshots(
222        &mut self,
223        position: &Position,
224        closed_cycles_pnl: Option<Money>,
225    ) {
226        self.position_snapshots.remove(&position.id);
227        self.bump_position_snapshot_revision(position.id);
228
229        if let Some(closed_cycles_pnl) = closed_cycles_pnl {
230            let (_, mut settled) = self.build_position_snapshot(position);
231            settled.realized_pnl = Some(closed_cycles_pnl);
232            settled.events.clear();
233            self.store_position_snapshot(position.id, settled, None);
234        }
235    }
236
237    /// Records that the frames held for `position_id` were replaced rather than appended to.
238    ///
239    /// Consumers cache per-position aggregates keyed off the frame count, which settling and
240    /// purging can leave unchanged while the frames behind it differ.
241    pub(super) fn bump_position_snapshot_revision(&mut self, position_id: PositionId) {
242        *self
243            .position_snapshot_revisions
244            .entry(position_id)
245            .or_default() += 1;
246    }
247
248    fn build_position_snapshot(&self, position: &Position) -> (String, Position) {
249        let position_id = position.id;
250
251        let mut copied_position = position.clone_for_snapshot();
252        let new_id = format!("{}-{}", position_id.as_str(), UUID4::new());
253        copied_position.id = PositionId::new(new_id);
254
255        let blob_ref = format!(
256            "{}{}/{}",
257            CacheSnapshotRef::POSITION_PREFIX,
258            position_id.as_str(),
259            self.position_snapshot_count(&position_id),
260        );
261
262        (blob_ref, copied_position)
263    }
264
265    fn persist_position_snapshot(
266        &mut self,
267        blob_ref: &str,
268        snapshot: &Position,
269    ) -> anyhow::Result<Bytes> {
270        let encoded = Bytes::from(serde_json::to_vec(snapshot)?);
271        self.add(blob_ref, encoded.clone())?;
272
273        Ok(encoded)
274    }
275
276    // Stores the frame after encoding and any best-effort backing write
277    fn store_position_snapshot(
278        &mut self,
279        position_id: PositionId,
280        snapshot: Position,
281        encoded: Option<Bytes>,
282    ) {
283        log::debug!("Snapshot {snapshot}");
284
285        self.position_snapshots
286            .entry(position_id)
287            .or_default()
288            .push(PositionSnapshotFrame::new(snapshot, encoded));
289    }
290
291    fn position_snapshot_frame(&self, blob_ref: &str) -> Option<&PositionSnapshotFrame> {
292        let (position_id, snapshot_index) = parse_position_snapshot_blob_ref(blob_ref).ok()?;
293
294        self.position_snapshots
295            .get(&position_id)
296            .and_then(|frames| frames.get(snapshot_index))
297    }
298
299    /// Loads the cache-owned snapshot blob stored under `blob_ref`.
300    ///
301    /// The cache first checks in-memory snapshot state. When the blob is not present and a
302    /// database adapter exists, the generic cache entries are loaded and checked for the same
303    /// opaque reference.
304    ///
305    /// # Errors
306    ///
307    /// Returns an error if loading generic cache entries from the backing database fails.
308    pub fn load_snapshot_blob(&mut self, blob_ref: &str) -> anyhow::Result<Option<Bytes>> {
309        if let Some(blob) = self.snapshot_blob(blob_ref) {
310            return Ok(Some(blob));
311        }
312
313        if self.database.is_some() {
314            self.cache_general()?;
315        }
316
317        Ok(self.snapshot_blob(blob_ref))
318    }
319
320    /// Restores the cache-owned snapshot blob stored under `blob_ref`.
321    ///
322    /// Only cache-owned `cache://position-snapshots/...` blobs are currently supported.
323    ///
324    /// # Errors
325    ///
326    /// Returns an error if the blob reference is unsupported, malformed, skips earlier
327    /// snapshot frames, conflicts with an existing frame, or does not decode to the expected
328    /// position snapshot.
329    pub fn restore_snapshot_blob(&mut self, blob_ref: &str, blob: Bytes) -> anyhow::Result<()> {
330        let (position_id, snapshot_index) = parse_position_snapshot_blob_ref(blob_ref)?;
331        let restored = decode_position_snapshot_blob(&position_id, blob.as_ref())?;
332
333        let frames = self.position_snapshots.entry(position_id).or_default();
334        match frames.get(snapshot_index) {
335            Some(existing) if existing.encoded()? == blob => {}
336            Some(_) => {
337                anyhow::bail!(
338                    "position snapshot frame {snapshot_index} for {position_id} already exists with different bytes"
339                );
340            }
341            None if frames.len() == snapshot_index => {
342                frames.push(PositionSnapshotFrame::new(restored, Some(blob.clone())));
343            }
344            None => {
345                anyhow::bail!(
346                    "position snapshot blob_ref {blob_ref} skips missing frame {}",
347                    frames.len()
348                );
349            }
350        }
351
352        self.general.insert(blob_ref.to_string(), blob);
353        Ok(())
354    }
355
356    fn snapshot_blob(&self, blob_ref: &str) -> Option<Bytes> {
357        if let Some(blob) = self.general.get(blob_ref) {
358            return Some(blob.clone());
359        }
360
361        self.position_snapshot_frame(blob_ref)?
362            .encoded()
363            .inspect_err(|e| log::warn!("Failed to encode position snapshot {blob_ref}: {e}"))
364            .ok()
365    }
366
367    /// Creates a snapshot of the `position` state in the database.
368    ///
369    /// Persistence failures are logged without failing the operation.
370    ///
371    /// # Errors
372    ///
373    /// Returns an error if the backing reports a DeFi currency integrity error.
374    pub fn snapshot_position_state(
375        &mut self,
376        position: &Position,
377        ts_snapshot: UnixNanos,
378        unrealized_pnl: Option<Money>,
379        open_only: Option<bool>,
380    ) -> anyhow::Result<()> {
381        let open_only = open_only.unwrap_or(true);
382
383        if open_only && !position.is_open() {
384            return Ok(());
385        }
386
387        if let Some(database) = &mut self.database {
388            handle_persistence_result(
389                format_args!("snapshot position {}", position.id),
390                database.snapshot_position_state(position, ts_snapshot, unrealized_pnl),
391            )?;
392        } else {
393            log::warn!(
394                "Cannot snapshot position state for {} (no database configured)",
395                position.id
396            );
397        }
398
399        Ok(())
400    }
401
402    /// Gets the serialized position snapshot frames for the `position_id`.
403    ///
404    /// Each element in the returned vector is one JSON-encoded [`Position`] snapshot,
405    /// in the order they were taken. Frames that fail to serialize are skipped with a warning.
406    #[must_use]
407    pub fn position_snapshot_bytes(&self, position_id: &PositionId) -> Option<Vec<Vec<u8>>> {
408        self.position_snapshots.get(position_id).map(|frames| {
409            frames
410                .iter()
411                .filter_map(|frame| match frame.encoded() {
412                    Ok(encoded) => Some(encoded.to_vec()),
413                    Err(e) => {
414                        log::warn!("Failed to encode position snapshot: {e}");
415                        None
416                    }
417                })
418                .collect()
419        })
420    }
421
422    /// Returns the number of stored snapshot frames for the `position_id`.
423    ///
424    /// Returns `0` when no frames are stored. Does not allocate or copy frame bytes.
425    #[must_use]
426    pub fn position_snapshot_count(&self, position_id: &PositionId) -> usize {
427        self.position_snapshots.get(position_id).map_or(0, Vec::len)
428    }
429
430    /// Returns how many times the frames stored for the `position_id` were replaced.
431    ///
432    /// Pair this with [`Self::position_snapshot_count`] to detect frame changes: settling or
433    /// purging can replace the frames without moving the count, so the count alone is not
434    /// enough to tell whether cached per-position aggregates are still current.
435    #[must_use]
436    pub fn position_snapshot_revision(&self, position_id: &PositionId) -> u64 {
437        self.position_snapshot_revisions
438            .get(position_id)
439            .copied()
440            .unwrap_or(0)
441    }
442
443    /// Returns all position snapshots with the given optional filters.
444    ///
445    /// When `position_id` is `Some`, only snapshots for that position are returned.
446    /// When `account_id` is `Some`, snapshots are filtered to that account.
447    #[must_use]
448    pub fn position_snapshots(
449        &self,
450        position_id: Option<&PositionId>,
451        account_id: Option<&AccountId>,
452    ) -> Vec<Position> {
453        let frames: Box<dyn Iterator<Item = &PositionSnapshotFrame> + '_> = match position_id {
454            Some(pid) => match self.position_snapshots.get(pid) {
455                Some(v) => Box::new(v.iter()),
456                None => Box::new(std::iter::empty()),
457            },
458            None => Box::new(self.position_snapshots.values().flat_map(|v| v.iter())),
459        };
460
461        let mut results: Vec<Position> = frames.map(|frame| frame.position.clone()).collect();
462
463        if let Some(aid) = account_id {
464            results.retain(|p| p.account_id == *aid);
465        }
466
467        results
468    }
469
470    /// Returns position snapshots for `position_id` starting from the `skip`th frame.
471    ///
472    /// Use this to read only newly appended snapshots when the caller already processed
473    /// earlier frames. Returns an empty vector when at most `skip` frames are stored.
474    #[must_use]
475    pub fn position_snapshots_from(&self, position_id: &PositionId, skip: usize) -> Vec<Position> {
476        let Some(frames) = self.position_snapshots.get(position_id) else {
477            return Vec::new();
478        };
479
480        frames
481            .iter()
482            .skip(skip)
483            .map(|frame| frame.position.clone())
484            .collect()
485    }
486
487    /// Gets position snapshot IDs for the `instrument_id`.
488    #[must_use]
489    pub fn position_snapshot_ids(&self, instrument_id: &InstrumentId) -> AHashSet<PositionId> {
490        self.position_snapshots
491            .keys()
492            .filter(|position_id| {
493                self.positions
494                    .get(position_id)
495                    .is_some_and(|position| position.borrow().instrument_id == *instrument_id)
496            })
497            .copied()
498            .collect()
499    }
500}
501
502fn parse_position_snapshot_blob_ref(blob_ref: &str) -> anyhow::Result<(PositionId, usize)> {
503    let Some(rest) = blob_ref.strip_prefix(CacheSnapshotRef::POSITION_PREFIX) else {
504        anyhow::bail!("unsupported cache snapshot blob_ref {blob_ref}");
505    };
506
507    let Some((position_id, snapshot_index)) = rest.rsplit_once('/') else {
508        anyhow::bail!("malformed position snapshot blob_ref {blob_ref}");
509    };
510
511    if position_id.is_empty() {
512        anyhow::bail!("position snapshot blob_ref {blob_ref} has empty position id");
513    }
514
515    let snapshot_index = snapshot_index.parse::<usize>().map_err(|e| {
516        anyhow::anyhow!("position snapshot blob_ref {blob_ref} has invalid frame index: {e}")
517    })?;
518
519    Ok((PositionId::new(position_id), snapshot_index))
520}
521
522fn decode_position_snapshot_blob(
523    position_id: &PositionId,
524    blob: &[u8],
525) -> anyhow::Result<Position> {
526    let snapshot = serde_json::from_slice::<Position>(blob)?;
527    let expected_prefix = format!("{}-", position_id.as_str());
528
529    let Some(snapshot_uuid) = snapshot.id.as_str().strip_prefix(&expected_prefix) else {
530        anyhow::bail!(
531            "position snapshot id {} does not match blob_ref position {position_id}",
532            snapshot.id
533        );
534    };
535
536    if UUID4::from_str(snapshot_uuid).is_err() {
537        anyhow::bail!(
538            "position snapshot id {} does not match blob_ref position {position_id}",
539            snapshot.id
540        );
541    }
542
543    Ok(snapshot)
544}