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}