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> AsRef<RowImage<'a>> for SparseImage<'a> {
49    fn as_ref(&self) -> &RowImage<'a> {
50        &self.image
51    }
52}
53
54/// A borrowed image whose columns have all been validated as present.
55///
56/// Construction is checked; converting a sparse prefix cannot claim completeness.
57/// This does not allocate a full row or interpret SQL signedness/character sets.
58#[derive(Debug, Clone)]
59pub struct CompleteImage<'a> {
60    image: RowImage<'a>,
61}
62impl<'a> CompleteImage<'a> {
63    pub fn column_count(&self) -> usize {
64        self.image.column_count()
65    }
66    pub fn table(&self) -> &TableDefinition {
67        self.image.table()
68    }
69    pub fn columns(&self) -> &[ColumnInfo] {
70        self.image.columns()
71    }
72    pub fn fields(&self) -> Fields<'_, 'a> {
73        self.image.fields()
74    }
75    /// Reads through fields up to this absolute index, without allocating.
76    /// Every in-range column exists; SQL NULL is `RowValue::Null`.
77    pub fn field(&self, column_index: usize) -> Result<Field<'_, 'a>> {
78        if column_index >= self.column_count() {
79            return Err(invalid("column index outside complete row image"));
80        }
81        field(&self.image, column_index)?.ok_or_else(|| invalid("incomplete FULL row image"))
82    }
83}
84impl<'a> TryFrom<RowImage<'a>> for CompleteImage<'a> {
85    type Error = Error;
86    fn try_from(image: RowImage<'a>) -> Result<Self> {
87        if image.column_indices().len() != image.column_count() {
88            return Err(Error::Unsupported(
89                "FULL row images must contain every table column".into(),
90            ));
91        }
92        Ok(Self { image })
93    }
94}
95impl<'a> AsRef<RowImage<'a>> for CompleteImage<'a> {
96    fn as_ref(&self) -> &RowImage<'a> {
97        &self.image
98    }
99}
100
101/// A present field, borrowing its column definition and original event value.
102///
103/// ```compile_fail
104/// use mysql_replication::events::{CompleteImage, Field};
105/// fn retain_metadata<'a>(image: CompleteImage<'a>) -> Field<'static, 'a> {
106///     image.field(0).unwrap()
107/// }
108/// ```
109#[derive(Debug, Clone, Copy, PartialEq)]
110pub struct Field<'meta, 'event> {
111    pub column: &'meta ColumnInfo,
112    pub value: RowValue<'event>,
113}
114
115fn field<'image, 'event>(
116    image: &'image RowImage<'event>,
117    index: usize,
118) -> Result<Option<Field<'image, 'event>>> {
119    let column = image
120        .columns()
121        .get(index)
122        .ok_or_else(|| invalid("column index outside row image"))?;
123    for field in image.fields() {
124        let field = field?;
125        let column_index = usize::from(field.column.index);
126        if column_index == index {
127            return Ok(Some(Field {
128                column,
129                value: field.value,
130            }));
131        }
132        if column_index > index {
133            break;
134        }
135    }
136    Ok(None)
137}
138
139/// An operation whose shape cannot contain missing required images.
140#[derive(Debug, Clone)]
141pub enum RowOperation<I> {
142    Insert { after: I },
143    Update { before: I, after: I },
144    Delete { before: I },
145}
146impl<I> RowOperation<I> {
147    pub fn before(&self) -> Option<&I> {
148        match self {
149            Self::Insert { .. } => None,
150            Self::Update { before, .. } | Self::Delete { before } => Some(before),
151        }
152    }
153    pub fn after(&self) -> Option<&I> {
154        match self {
155            Self::Delete { .. } => None,
156            Self::Update { after, .. } | Self::Insert { after } => Some(after),
157        }
158    }
159    pub fn into_images(self) -> (Option<I>, Option<I>) {
160        match self {
161            Self::Insert { after } => (None, Some(after)),
162            Self::Update { before, after } => (Some(before), Some(after)),
163            Self::Delete { before } => (Some(before), None),
164        }
165    }
166}
167
168/// A statically selected operation; FULL and MINIMAL remain distinct types.
169///
170/// ```compile_fail
171/// use mysql_replication::events::{Full, Minimal, Row};
172/// fn sparse(row: Row<'_, Full>) -> Row<'_, Minimal> { row }
173/// ```
174#[derive(Debug, Clone)]
175pub struct Row<'a, M: BinlogMode> {
176    pub operation: RowOperation<M::Image<'a>>,
177}
178
179/// A mode-specific streaming iterator. It yields one error and then stops.
180pub struct Rows<'a, M: BinlogMode> {
181    rows: DecodedRows<'a>,
182    done: bool,
183    mode: PhantomData<M>,
184}
185impl<'a, M: BinlogMode> Rows<'a, M> {
186    pub(crate) fn new(rows: DecodedRows<'a>) -> Self {
187        Self {
188            rows,
189            done: false,
190            mode: PhantomData,
191        }
192    }
193}
194impl<'a, M: BinlogMode> Iterator for Rows<'a, M> {
195    type Item = Result<Row<'a, M>>;
196    fn next(&mut self) -> Option<Self::Item> {
197        if self.done {
198            return None;
199        }
200        let result = self.rows.next()?.and_then(|row| {
201            let operation = match (row.before, row.after) {
202                (None, Some(after)) => RowOperation::Insert {
203                    after: M::Image::try_from(after)?,
204                },
205                (Some(before), Some(after)) => RowOperation::Update {
206                    before: M::Image::try_from(before)?,
207                    after: M::Image::try_from(after)?,
208                },
209                (Some(before), None) => RowOperation::Delete {
210                    before: M::Image::try_from(before)?,
211                },
212                (None, None) => return Err(invalid("row operation has no images")),
213            };
214            Ok(Row { operation })
215        });
216        self.done = result.is_err();
217        Some(result)
218    }
219}
220impl<M: BinlogMode> FusedIterator for Rows<'_, M> {}