laminar_connectors/postgres/cdc/lsn/
mod.rs

1//! `PostgreSQL` Log Sequence Number (LSN) type.
2//!
3//! An LSN is a 64-bit integer representing a byte position in the WAL stream.
4//! `PostgreSQL` displays LSNs in the format `X/Y` where X is the upper 32 bits
5//! and Y is the lower 32 bits, both in hexadecimal.
6
7use std::fmt;
8use std::str::FromStr;
9
10/// A `PostgreSQL` Log Sequence Number (LSN).
11///
12/// Represents a byte offset in the write-ahead log. Used to track
13/// replication progress and checkpoint positions.
14///
15/// # Format
16///
17/// LSNs are displayed as `X/YYYYYYYY` where X and Y are hex values.
18/// For example: `0/1234ABCD`, `1/0`, `FF/FFFFFFFF`.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
20pub struct Lsn(u64);
21
22impl Lsn {
23    /// The zero LSN, representing the start of the WAL.
24    pub const ZERO: Lsn = Lsn(0);
25
26    /// The maximum possible LSN.
27    pub const MAX: Lsn = Lsn(u64::MAX);
28
29    /// Creates a new LSN from a raw 64-bit value.
30    #[must_use]
31    pub const fn new(value: u64) -> Self {
32        Lsn(value)
33    }
34
35    /// Returns the raw 64-bit value.
36    #[must_use]
37    pub const fn as_u64(self) -> u64 {
38        self.0
39    }
40
41    /// Returns the upper 32 bits (segment number).
42    #[must_use]
43    pub const fn segment(self) -> u32 {
44        let bytes = self.0.to_be_bytes();
45        u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])
46    }
47
48    /// Returns the lower 32 bits (offset within segment).
49    #[must_use]
50    pub const fn offset(self) -> u32 {
51        let bytes = self.0.to_be_bytes();
52        u32::from_be_bytes([bytes[4], bytes[5], bytes[6], bytes[7]])
53    }
54
55    /// Returns the byte difference between two LSNs.
56    ///
57    /// Returns 0 if `other` is ahead of `self`.
58    #[must_use]
59    pub const fn diff(self, other: Lsn) -> u64 {
60        self.0.saturating_sub(other.0)
61    }
62
63    /// Advances the LSN by the given number of bytes.
64    #[must_use]
65    pub const fn advance(self, bytes: u64) -> Lsn {
66        Lsn(self.0.saturating_add(bytes))
67    }
68
69    /// Returns `true` if this is the zero LSN.
70    #[must_use]
71    pub const fn is_zero(self) -> bool {
72        self.0 == 0
73    }
74}
75
76impl fmt::Display for Lsn {
77    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
78        write!(f, "{:X}/{:X}", self.segment(), self.offset())
79    }
80}
81
82impl FromStr for Lsn {
83    type Err = LsnParseError;
84
85    fn from_str(s: &str) -> Result<Self, Self::Err> {
86        let (high, low) = s
87            .split_once('/')
88            .ok_or_else(|| LsnParseError::InvalidFormat(s.to_string()))?;
89
90        let high = u32::from_str_radix(high, 16)
91            .map_err(|_| LsnParseError::InvalidHex(high.to_string()))?;
92        let low =
93            u32::from_str_radix(low, 16).map_err(|_| LsnParseError::InvalidHex(low.to_string()))?;
94
95        Ok(Lsn((u64::from(high) << 32) | u64::from(low)))
96    }
97}
98
99impl From<u64> for Lsn {
100    fn from(value: u64) -> Self {
101        Lsn(value)
102    }
103}
104
105impl From<Lsn> for u64 {
106    fn from(lsn: Lsn) -> Self {
107        lsn.0
108    }
109}
110
111/// Errors that can occur when parsing an LSN string.
112#[derive(Debug, Clone, thiserror::Error)]
113pub enum LsnParseError {
114    /// The string does not contain the expected `X/Y` format.
115    #[error("invalid LSN format (expected X/Y): {0}")]
116    InvalidFormat(String),
117
118    /// A hex component could not be parsed.
119    #[error("invalid hex in LSN: {0}")]
120    InvalidHex(String),
121}
122
123#[cfg(test)]
124mod tests;
laminar_connectors/postgres/cdc/lsn/mod.rs

laminar_connectors/postgres/cdc/lsn/
mod.rs
