Skip to main content

mysql_replication/events/rows/
typed.rs

1//! Typed, borrowed image views over the common ROWS wire layout.
2use super::{ColumnInfo, Fields, RowImage, RowValue, TableDefinition, decoder::DecodedRows};
3use crate::{Error, Result, error::invalid, events::BinlogMode};
4use std::{iter::FusedIterator, marker::PhantomData};
5
6/// A borrowed sparse image. A missing field is distinct from SQL NULL.
7///
8/// An image cannot outlive its input bytes, even after its decoder is dropped.
9///
10/// ```compile_fail
11/// use mysql_replication::events::SparseImage;
12/// fn retain_forever<'a>(image: SparseImage<'a>) -> SparseImage<'static> {
13///     image
14/// }
15/// ```
16#[derive(Debug, Clone)]
17pub struct SparseImage<'a> {
18    image: RowImage<'a>,
19}
20impl<'a> SparseImage<'a> {
21    pub fn column_count(&self) -> usize {
22        self.image.column_count()
23    }
24    pub fn column_indices(&self) -> &[u16] {
25        self.image.column_indices()
26    }
27    pub fn table(&self) -> &TableDefinition {
28        self.image.table()
29    }
30    pub fn columns(&self) -> &[ColumnInfo] {
31        self.image.columns()
32    }
33    pub fn fields(&self) -> Fields<'_, 'a> {
34        self.image.fields()
35    }
36    /// Reads through present fields up to this absolute index, without allocating.
37    /// Returns `None` only for an absent column; out-of-range indices are errors.
38    pub fn field(&self, column_index: usize) -> Result<Option<Field<'_, 'a>>> {
39        field(&self.image, column_index)
40    }
41}
42impl<'a> TryFrom<RowImage<'a>> for SparseImage<'a> {
43    type Error = Error;
44    fn try_from(image: RowImage<'a>) -> Result<Self> {
45        Ok(Self { image })
46    }
47}
48impl<'a> From<SparseImage<'a>> for RowImage<'a> {
49    fn from(image: SparseImage<'a>) -> Self {
50        image.image
51    }
52}
53impl<'a> AsRef<RowImage<'a>> for SparseImage<'a> {
54    fn as_ref(&self) -> &RowImage<'a> {
55        &self.image
56    }
57}
58
59/// A borrowed image whose columns have all been validated as present.
60///
61/// Construction is checked; converting a sparse prefix cannot claim completeness.
62/// This does not allocate a full row or interpret SQL signedness/character sets.
63#[derive(Debug, Clone)]
64pub struct CompleteImage<'a> {
65    image: RowImage<'a>,
66}
67impl<'a> CompleteImage<'a> {
68    pub fn column_count(&self) -> usize {
69        self.image.column_count()
70    }
71    pub fn table(&self) -> &TableDefinition {
72        self.image.table()
73    }
74    pub fn columns(&self) -> &[ColumnInfo] {
75        self.image.columns()
76    }
77    pub fn fields(&self) -> Fields<'_, 'a> {
78        self.image.fields()
79    }
80    /// Reads through fields up to this absolute index, without allocating.
81    /// Every in-range column exists; SQL NULL is `RowValue::Null`.
82    pub fn field(&self, column_index: usize) -> Result<Field<'_, 'a>> {
83        if column_index >= self.column_count() {
84            return Err(invalid("column index outside complete row image"));
85        }
86        field(&self.image, column_index)?.ok_or_else(|| invalid("incomplete FULL row image"))
87    }
88}
89impl<'a> TryFrom<RowImage<'a>> for CompleteImage<'a> {
90    type Error = Error;
91    fn try_from(image: RowImage<'a>) -> Result<Self> {
92        if image.column_indices().len() != image.column_count() {
93            return Err(Error::Unsupported(
94                "FULL row images must contain every table column".into(),
95            ));
96        }
97        Ok(Self { image })
98    }
99}
100impl<'a> From<CompleteImage<'a>> for RowImage<'a> {
101    fn from(image: CompleteImage<'a>) -> Self {
102        image.image
103    }
104}
105impl<'a> AsRef<RowImage<'a>> for CompleteImage<'a> {
106    fn as_ref(&self) -> &RowImage<'a> {
107        &self.image
108    }
109}
110
111/// A present field, borrowing its column definition and original event value.
112///
113/// ```compile_fail
114/// use mysql_replication::events::{CompleteImage, Field};
115/// fn retain_metadata<'a>(image: CompleteImage<'a>) -> Field<'static, 'a> {
116///     image.field(0).unwrap()
117/// }
118/// ```
119#[derive(Debug, Clone, Copy, PartialEq)]
120pub struct Field<'meta, 'event> {
121    pub column: &'meta ColumnInfo,
122    pub value: RowValue<'event>,
123}
124
125fn field<'image, 'event>(
126    image: &'image RowImage<'event>,
127    index: usize,
128) -> Result<Option<Field<'image, 'event>>> {
129    let column = image
130        .columns()
131        .get(index)
132        .ok_or_else(|| invalid("column index outside row image"))?;
133    for field in image.fields() {
134        let field = field?;
135        let column_index = usize::from(field.column.index);
136        if column_index == index {
137            return Ok(Some(Field {
138                column,
139                value: field.value,
140            }));
141        }
142        if column_index > index {
143            break;
144        }
145    }
146    Ok(None)
147}
148
149/// An operation whose shape cannot contain missing required images.
150#[derive(Debug, Clone)]
151pub enum RowOperation<I> {
152    Insert { after: I },
153    Update { before: I, after: I },
154    Delete { before: I },
155}
156impl<I> RowOperation<I> {
157    pub fn before(&self) -> Option<&I> {
158        match self {
159            Self::Insert { .. } => None,
160            Self::Update { before, .. } | Self::Delete { before } => Some(before),
161        }
162    }
163    pub fn after(&self) -> Option<&I> {
164        match self {
165            Self::Delete { .. } => None,
166            Self::Update { after, .. } | Self::Insert { after } => Some(after),
167        }
168    }
169    pub fn into_images(self) -> (Option<I>, Option<I>) {
170        match self {
171            Self::Insert { after } => (None, Some(after)),
172            Self::Update { before, after } => (Some(before), Some(after)),
173            Self::Delete { before } => (Some(before), None),
174        }
175    }
176}
177
178/// A statically selected operation; FULL and MINIMAL remain distinct types.
179///
180/// ```compile_fail
181/// use mysql_replication::events::{Full, Minimal, Row};
182/// fn sparse(row: Row<'_, Full>) -> Row<'_, Minimal> { row }
183/// ```
184#[derive(Debug, Clone)]
185pub struct Row<'a, M: BinlogMode> {
186    pub operation: RowOperation<M::Image<'a>>,
187}
188
189/// Row decoding failure with the absolute ordinal for a violated NOT NULL constraint.
190#[derive(Debug, thiserror::Error)]
191pub enum RowReadError {
192    #[error(transparent)]
193    Protocol(#[from] Error),
194    #[error("NULL in NOT NULL column {0}")]
195    UnexpectedNull(u16),
196}
197
198/// A typed image and the selected column value, or None when it was not logged.
199pub type ProjectedOperation<'a, M> =
200    RowOperation<(<M as BinlogMode>::Image<'a>, Option<RowValue<'a>>)>;
201
202/// A mode-specific streaming iterator. It yields one error and then stops.
203pub struct Rows<'a, M: BinlogMode> {
204    rows: DecodedRows<'a>,
205    done: bool,
206    mode: PhantomData<M>,
207}
208impl<'a, M: BinlogMode> Rows<'a, M> {
209    pub(crate) fn new(rows: DecodedRows<'a>) -> Self {
210        Self {
211            rows,
212            done: false,
213            mode: PhantomData,
214        }
215    }
216    /// Reads one operation and captures a selected value while validating each image.
217    /// The row iterator is exhausted after an error, just as for Iterator::next.
218    pub fn next_with_column(
219        &mut self,
220        index: u16,
221    ) -> Option<std::result::Result<ProjectedOperation<'a, M>, RowReadError>> {
222        self.read(Some(index), |image, value| {
223            Ok((M::Image::try_from(image)?, value))
224        })
225    }
226    fn read<T>(
227        &mut self,
228        selected: Option<u16>,
229        map: impl Fn(RowImage<'a>, Option<RowValue<'a>>) -> Result<T>,
230    ) -> Option<std::result::Result<RowOperation<T>, RowReadError>> {
231        if self.done {
232            return None;
233        }
234        let result = self.rows.read(selected, map)?;
235        self.done = result.is_err();
236        Some(result)
237    }
238}
239impl<'a, M: BinlogMode> Iterator for Rows<'a, M> {
240    type Item = Result<Row<'a, M>>;
241    fn next(&mut self) -> Option<Self::Item> {
242        self.read(None, |image, _| M::Image::try_from(image))
243            .map(|result| {
244                result
245                    .map(|operation| Row { operation })
246                    .map_err(|err| match err {
247                        RowReadError::Protocol(error) => error,
248                        RowReadError::UnexpectedNull(_) => invalid("NULL in a NOT NULL column"),
249                    })
250            })
251    }
252}
253impl<M: BinlogMode> FusedIterator for Rows<'_, M> {}