rifts 0.3.3

Rift Realtime Protocol / 1.0 — server-side implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

//! # Persistent Storage Abstraction Layer
//!
//! This module provides a unified abstraction layer for all storage subsystems
//! used by the Rift broker. Every broker component -- offset allocation, log
//! append, deduplication, and snapshot capture -- is backed by a single
//! [`StorageEngine`] that operates on opaque byte keys and values.
//!
//! ## Architecture Overview
//!
//! ```text
//! StorageEngine          -- low-level byte-oriented key-value store (get/put/delete/scan_prefix)
//!   +-- OffsetStore      -- per-topic monotonic offset allocation (spec section 13.1)
//!   +-- LogStore         -- topic message log append, range query, and retention
//!   +-- DedupeStore      -- message deduplication (spec section 11.2)
//!   +-- SnapshotStore    -- topic state snapshot capture and retrieval (spec section 13.4)
//! ```
//!
//! ## Storage Engines
//!
//! This crate ships two engine implementations:
//!
//! - [`MemoryEngine`] -- an in-memory engine backed by `DashMap`. Requires no
//!   configuration and provides no persistence; ideal for development, testing,
//!   and single-process deployments.
//! - [`SledEngine`] -- a durable engine backed by the embedded B+ tree
//!   database [sled](https://docs.rs/sled). Requires the `sled` Cargo feature
//!   and is suitable for production use.
//!
//! ## Key Encoding
//!
//! Higher-level stores delegate key construction to the [`encode`] module.
//! Every key follows a two-level namespace of the form
//! `<topic_name>\x00<sub_key>`, where `\x00` is the [`encode::SEP`]
//! separator. This guarantees that scanning entries for topic `"room/5"`
//! never accidentally matches entries belonging to `"room/50"`.
//!
//! ## Choosing an Engine
//!
//! | Concern | `MemoryEngine` | `SledEngine` |
//! |---------|---------------|--------------|
//! | Persistence | None (lost on restart) | Disk-backed |
//! | Latency | Sub-microsecond | Low millisecond |
//! | Setup | Zero configuration | Requires a `sled::Db` path |
//! | Feature gate | Always available | `sled` Cargo feature |

/// The deduplication sub-module, which detects and discards duplicate
/// messages within a configurable time window (specification section 11.2).
///
/// See [`dedupe`] for details on the trait and its implementations.
pub mod dedupe;
/// Key-encoding helpers that construct byte-level keys for every
/// higher-level store (offset, log, deduplication, snapshot).
///
/// See [`encode`] for the full key format table.
pub mod encode;
/// The low-level byte-oriented key-value storage engine abstraction.
///
/// Provides [`StorageEngine`] and the two built-in backends
/// ([`MemoryEngine`] and `SledEngine`).
pub mod engine;
/// The topic message log store, supporting append, range queries, and
/// retention enforcement.
///
/// See [`log`] for the trait contract and implementation details.
pub mod log;
/// The per-topic monotonic offset allocation store (specification section 13.1).
///
/// See [`offset`] for the trait contract and implementation details.
pub mod offset;
/// The topic state snapshot store, capturing and retrieving snapshots
/// (specification section 13.4).
///
/// See [`snapshot`] for the trait contract and implementation details.
pub mod snapshot;

// ── Memory-backed re-exports (always available) ───────────────

pub use dedupe::{DedupeStore, MemoryDedupeStore};
pub use encode::{
    dedupe_key, dedupe_prefix, log_key, log_prefix, log_range_end, log_range_start, offset_key,
    offset_prefix, snapshot_key, snapshot_prefix,
};
pub use engine::{MemoryEngine, SharedEngine, StorageEngine};
pub use log::{LogStore, MemoryLogStore};
pub use offset::{MemoryOffsetStore, OffsetStore};
pub use snapshot::{MemorySnapshotStore, SnapshotStore, StoredSnapshot};

// ── Sled-backed re-exports (feature-gated) ────────────────────

/// Sled-backed deduplication store. Requires the `sled` Cargo feature.
#[cfg(feature = "sled")]
pub use dedupe::SledDedupeStore;
/// Sled-backed storage engine. Requires the `sled` Cargo feature.
#[cfg(feature = "sled")]
pub use engine::SledEngine;
/// Sled-backed log store. Requires the `sled` Cargo feature.
#[cfg(feature = "sled")]
pub use log::SledLogStore;
/// Sled-backed offset store. Requires the `sled` Cargo feature.
#[cfg(feature = "sled")]
pub use offset::SledOffsetStore;
/// Sled-backed snapshot store. Requires the `sled` Cargo feature.
#[cfg(feature = "sled")]
pub use snapshot::SledSnapshotStore;