Skip to main content

mysql_replication/events/
rows.rs

1use super::{BinlogMode, Event, Minimal};
2use crate::{Result, error::invalid, wire::Cursor};
3use std::{io::Write, marker::PhantomData};
4
5mod decoder;
6mod metadata;
7mod typed;
8mod value;
9
10pub use decoder::{ColumnDefinition, Fields, OwnedRowImage, RowImage, RowsDecoder};
11pub use metadata::{ColumnInfo, TableDefinition};
12pub use mysql_common::constants::ColumnType;
13pub use typed::{
14    CompleteImage, Field, ProjectedOperation, Row, RowOperation, RowReadError, Rows, SparseImage,
15};
16pub use value::{DecimalValue, IntegerValue, RowValue};
17
18/// Protocol operation, independent from a CDC change or table whitelist.
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum RowsKind {
21    Write,
22    Update,
23    Delete,
24}
25
26/// Recognizes the reserved marker shape in a v1/v2 ROWS envelope.
27/// A regular mapped table may have the same numeric ID and statement-end flag.
28pub fn is_rows_statement_end_marker(id: u64, flags: u16, v2: bool, payload: &[u8]) -> bool {
29    if id != 0x00ff_ffff || flags & 1 == 0 {
30        return false;
31    }
32    if payload.is_empty() {
33        return true;
34    }
35    let image = if v2 {
36        let Some([a, b, ..]) = payload.get(..2) else {
37            return false;
38        };
39        let extra_len = usize::from(u16::from_le_bytes([*a, *b]));
40        if extra_len < 2 {
41            return false;
42        }
43        payload.get(extra_len..)
44    } else {
45        Some(payload)
46    };
47    matches!(image, Some([] | [0]))
48}
49
50/// A borrowed ROWS body. Typed parsers bind its historical TABLE_MAP plan.
51/// `Minimal::Image` is sparse and `Full::Image` is complete; `rows()` selects
52/// these types statically without an external decoder registry. Raw
53/// frames and views remain available for custom adapters.
54#[derive(Debug, Clone)]
55pub struct RowsEvent<'a, M: BinlogMode> {
56    /// TABLE_MAP identifier, independent from the common header's server ID.
57    pub table_id: u64,
58    /// ROWS-body flags, independent from the common header's flags.
59    pub flags: u16,
60    pub kind: RowsKind,
61    /// Extra data, bitmaps and values are delayed until after table selection.
62    pub encoded_images: &'a [u8],
63    pub(crate) post_header: usize,
64    pub(crate) v2: bool,
65    pub(crate) decoder: Option<std::sync::Arc<RowsDecoder<M>>>,
66    mode: PhantomData<M>,
67}
68impl<'a, M: BinlogMode> RowsEvent<'a, M> {
69    /// True for a statement-end marker carrying no encoded row image.
70    pub fn is_statement_end(&self) -> bool {
71        is_rows_statement_end_marker(self.table_id, self.flags, self.v2, self.encoded_images)
72    }
73    pub fn with_layout(kind: RowsKind, post_header: usize, v2: bool) -> Self {
74        Self {
75            table_id: 0,
76            flags: 0,
77            kind,
78            encoded_images: &[],
79            post_header,
80            v2,
81            decoder: None,
82            mode: PhantomData,
83        }
84    }
85    pub fn images(&self) -> Result<RowImages<'a>> {
86        let mut input = Cursor::new(self.encoded_images);
87        let extra_data = if self.v2 {
88            let length = input.le(2)? as usize;
89            input.take(
90                length
91                    .checked_sub(2)
92                    .ok_or_else(|| invalid("extra-data length < 2"))?,
93            )?
94        } else {
95            &[]
96        };
97        let column_count = input.lenenc()?;
98        if column_count == 0 || column_count > 4096 {
99            return Err(invalid("ROWS column count outside 1..4096"));
100        }
101        let first = input.take(column_count.div_ceil(8))?;
102        let second = if self.kind == RowsKind::Update {
103            input.take(column_count.div_ceil(8))?
104        } else {
105            first
106        };
107        let images = RowImages {
108            extra_data,
109            column_count,
110            before_columns: first,
111            after_columns: second,
112            rows: input.remaining(),
113        };
114        M::validate_images(&images)?;
115        Ok(images)
116    }
117}
118
119/// A statement-end sentinel with no TABLE_MAP or row images.
120#[derive(Debug, Clone)]
121pub struct RowsStatementEndEvent<'a> {
122    event: RowsEvent<'a, Minimal>,
123}
124impl<'a> RowsStatementEndEvent<'a> {
125    pub(crate) fn new(event: RowsEvent<'a, Minimal>) -> Self {
126        Self { event }
127    }
128    pub fn table_id(&self) -> u64 {
129        self.event.table_id
130    }
131    pub fn flags(&self) -> u16 {
132        self.event.flags
133    }
134    pub fn kind(&self) -> RowsKind {
135        self.event.kind
136    }
137    pub(crate) fn layout(&self) -> RowsStatementEndEvent<'static> {
138        RowsStatementEndEvent::new(RowsEvent::with_layout(
139            self.event.kind,
140            self.event.post_header,
141            self.event.v2,
142        ))
143    }
144}
145impl<'a> Event<'a> for RowsStatementEndEvent<'a> {
146    fn decode(&mut self, data: &'a [u8]) -> Result<()> {
147        self.event.decode(data)?;
148        if !self.event.is_statement_end() {
149            return Err(invalid("invalid ROWS statement-end sentinel"));
150        }
151        Ok(())
152    }
153    fn dump(&self, writer: &mut dyn Write) -> Result<()> {
154        self.event.dump(writer)
155    }
156}
157impl<'a, M: BinlogMode> RowsEvent<'a, M> {
158    /// The TABLE_MAP definition bound by this mode's parser.
159    pub fn table(&self) -> Result<&TableDefinition> {
160        Ok(self.bound_decoder()?.table())
161    }
162    pub fn columns(&self) -> Result<&[ColumnInfo]> {
163        Ok(&self.table()?.columns)
164    }
165    fn bound_decoder(&self) -> Result<&RowsDecoder<M>> {
166        self.decoder
167            .as_deref()
168            .ok_or_else(|| invalid("ROWS without bound TABLE_MAP"))
169    }
170    /// Returns sparse or complete images without an external decoder registry.
171    pub fn rows(&self) -> Result<Rows<'a, M>> {
172        self.bound_decoder()?.rows(self)
173    }
174}
175impl<'a, M: BinlogMode> Event<'a> for RowsEvent<'a, M> {
176    fn dump(&self, writer: &mut dyn Write) -> Result<()> {
177        writeln!(writer, "Table ID: {}", self.table_id)?;
178        writeln!(writer, "Flags: {}", self.flags)?;
179        writeln!(writer, "Kind: {:?}", self.kind)?;
180        writeln!(writer, "Encoded images: {:02x?}", self.encoded_images)?;
181        writeln!(writer)?;
182        Ok(())
183    }
184
185    fn decode(&mut self, data: &'a [u8]) -> Result<()> {
186        let width = self
187            .post_header
188            .checked_sub(if self.v2 { 4 } else { 2 })
189            .ok_or_else(|| invalid("short ROWS post-header"))?;
190        if !matches!(width, 4 | 6) {
191            return Err(invalid("unsupported ROWS table ID width"));
192        }
193        let mut input = Cursor::new(data);
194        let table_id = input.le(width)?;
195        let flags = input.le(2)? as u16;
196        self.table_id = table_id;
197        self.flags = flags;
198        self.encoded_images = input.remaining();
199        M::validate_event(self)
200    }
201}
202#[derive(Debug, Clone, Copy)]
203pub struct RowImages<'a> {
204    pub extra_data: &'a [u8],
205    pub column_count: usize,
206    /// First wire bitmap; for WRITE this describes the after image.
207    pub before_columns: &'a [u8],
208    /// Second UPDATE bitmap, otherwise the same first wire bitmap.
209    pub after_columns: &'a [u8],
210    pub rows: &'a [u8],
211}