Skip to main content

mysql_replication/protocol/mysql/
version.rs

1//! Version adapters are statically linked plugins, selected once per connection/FDE.
2//! They are object safe; row values still borrow the input event across this boundary.
3use super::events::{EventParser, MysqlEventParser, RowsEvent, TableMapEvent};
4use super::{decoder::Decoder, event_type as event, file::EventView, wire::Cursor};
5use crate::{Change, Error, Result, TableMeta, error::invalid};
6use std::{collections::BTreeMap, sync::Arc};
7
8#[derive(Debug, Clone, PartialEq, Eq)]
9pub struct ServerVersion {
10    pub raw: String,
11    pub major: u32,
12    pub minor: u32,
13    pub patch: u32,
14}
15impl ServerVersion {
16    pub fn parse(raw: &str) -> Result<Self> {
17        let mut parts = raw.split('.');
18        let mut number = || -> Result<u32> {
19            let part = parts
20                .next()
21                .ok_or_else(|| invalid("incomplete server version"))?;
22            let digits: String = part.chars().take_while(char::is_ascii_digit).collect();
23            digits
24                .parse()
25                .map_err(|_| invalid("invalid server version"))
26        };
27        Ok(Self {
28            raw: raw.into(),
29            major: number()?,
30            minor: number()?,
31            patch: number()?,
32        })
33    }
34}
35
36pub struct FormatDescription<'a> {
37    pub server: ServerVersion,
38    pub binlog_version: u16,
39    pub header_length: u8,
40    pub post_header_lengths: &'a [u8],
41}
42impl<'a> FormatDescription<'a> {
43    pub fn parse(body: &'a [u8]) -> Result<Self> {
44        let mut cursor = Cursor::new(body);
45        let binlog_version = cursor.le(2)? as u16;
46        let version = cursor.take(50)?;
47        let end = version
48            .iter()
49            .position(|&c| c == 0)
50            .unwrap_or(version.len());
51        let server = ServerVersion::parse(std::str::from_utf8(&version[..end])?)?;
52        cursor.take(4)?;
53        let header_length = cursor.byte()?;
54        Ok(Self {
55            server,
56            binlog_version,
57            header_length,
58            post_header_lengths: cursor.remaining(),
59        })
60    }
61}
62
63pub trait RowDecoder: Send {
64    fn clear_table_maps(&mut self);
65    fn table_map_event(&mut self, event: TableMapEvent<'_>) -> Result<()> {
66        self.table_map(event.standard_body.ok_or_else(|| {
67            Error::Unsupported(
68                "custom TABLE_MAP layout requires RowDecoder::table_map_event".into(),
69            )
70        })?)
71    }
72    fn rows_event(
73        &mut self,
74        event: RowsEvent<'_>,
75        emit: &mut dyn FnMut(Change<'_>) -> Result<()>,
76    ) -> Result<()> {
77        let (kind, body) = event.standard_body.ok_or_else(|| {
78            Error::Unsupported("custom ROWS layout requires RowDecoder::rows_event".into())
79        })?;
80        self.rows(kind, body, emit)
81    }
82    fn table_map(&mut self, body: &[u8]) -> Result<()>;
83    fn rows(
84        &mut self,
85        event_type: u8,
86        body: &[u8],
87        emit: &mut dyn FnMut(Change<'_>) -> Result<()>,
88    ) -> Result<()>;
89}
90impl RowDecoder for Decoder {
91    fn table_map_event(&mut self, event: TableMapEvent<'_>) -> Result<()> {
92        Decoder::table_map_event(self, event)
93    }
94    fn rows_event(
95        &mut self,
96        event: RowsEvent<'_>,
97        emit: &mut dyn FnMut(Change<'_>) -> Result<()>,
98    ) -> Result<()> {
99        Decoder::rows_event(self, event, emit)
100    }
101    fn clear_table_maps(&mut self) {
102        self.clear_table_maps();
103    }
104    fn table_map(&mut self, body: &[u8]) -> Result<()> {
105        self.table_map(body)
106    }
107    fn rows(
108        &mut self,
109        event_type: u8,
110        body: &[u8],
111        emit: &mut dyn FnMut(Change<'_>) -> Result<()>,
112    ) -> Result<()> {
113        self.rows(event_type, body, emit)
114    }
115}
116
117#[derive(Debug, PartialEq, Eq)]
118pub enum EventAction<'a> {
119    TableMap,
120    Rows,
121    Begin,
122    Commit,
123    Rollback,
124    GroupStart,
125    Ignore,
126    Rotate { file: &'a str, position: u64 },
127}
128
129pub trait VersionAdapter: Send + Sync {
130    fn name(&self) -> &str;
131    fn supports(&self, version: &ServerVersion) -> bool;
132    fn status_query(&self) -> &str;
133    fn validate_server(
134        &self,
135        variables: &BTreeMap<String, String>,
136        consumer_id: u32,
137    ) -> Result<()> {
138        validate_server_variables(variables, consumer_id)
139    }
140    fn validate_format(&self, format: &FormatDescription<'_>) -> Result<()> {
141        validate_mysql_v4(format)
142    }
143    /// Bind a structural parser once per file, using the file's FDE layout.
144    fn create_event_parser(&self, format: &FormatDescription<'_>) -> Result<Box<dyn EventParser>> {
145        Ok(Box::new(MysqlEventParser::from_format(format)?))
146    }
147    fn create_decoder(
148        &self,
149        tables: Vec<TableMeta>,
150        _format: &FormatDescription<'_>,
151    ) -> Result<Box<dyn RowDecoder>> {
152        Ok(Box::new(Decoder::new(tables)?))
153    }
154    fn classify<'a>(&self, event: EventView<'a>) -> Result<EventAction<'a>> {
155        classify_mysql_event(event)
156    }
157}
158
159#[derive(Clone)]
160pub struct VersionRegistry {
161    adapters: Vec<Arc<dyn VersionAdapter>>,
162}
163impl VersionRegistry {
164    pub fn empty() -> Self {
165        Self {
166            adapters: Vec::new(),
167        }
168    }
169    pub fn register(&mut self, adapter: Arc<dyn VersionAdapter>) -> Result<()> {
170        if adapter.name().is_empty() || self.adapters.iter().any(|a| a.name() == adapter.name()) {
171            return Err(Error::Schema("empty/duplicate version adapter name".into()));
172        }
173        self.adapters.push(adapter);
174        Ok(())
175    }
176    pub fn resolve(
177        &self,
178        version: &ServerVersion,
179        selected: Option<&str>,
180    ) -> Result<Arc<dyn VersionAdapter>> {
181        let matches: Vec<_> = self
182            .adapters
183            .iter()
184            .filter(|a| selected.is_none_or(|name| name == a.name()) && a.supports(version))
185            .collect();
186        match matches.as_slice() {
187            [adapter] => Ok(Arc::clone(adapter)),
188            [] => Err(Error::Unsupported(format!(
189                "server {} / adapter {}; register a matching VersionAdapter{}",
190                version.raw,
191                selected.unwrap_or("auto"),
192                if (version.major, version.minor) == (5, 8) {
193                    "; Oracle MySQL has no 5.8 release series"
194                } else {
195                    ""
196                }
197            ))),
198            _ => Err(Error::Schema(format!(
199                "ambiguous adapters for {}; set source.adapter explicitly",
200                version.raw
201            ))),
202        }
203    }
204}
205impl Default for VersionRegistry {
206    fn default() -> Self {
207        let adapters: Vec<Arc<dyn VersionAdapter>> = [
208            (5, 7, "mysql57"),
209            (8, 0, "mysql80"),
210            (8, 1, "mysql81"),
211            (8, 2, "mysql82"),
212            (8, 3, "mysql83"),
213            (8, 4, "mysql84"),
214            (9, 0, "mysql90"),
215            (9, 7, "mysql97"),
216        ]
217        .into_iter()
218        .map(|(major, minor, name)| {
219            Arc::new(MysqlVersion { major, minor, name }) as Arc<dyn VersionAdapter>
220        })
221        .collect();
222        Self { adapters }
223    }
224}
225struct MysqlVersion {
226    major: u32,
227    minor: u32,
228    name: &'static str,
229}
230impl VersionAdapter for MysqlVersion {
231    fn name(&self) -> &str {
232        self.name
233    }
234    fn supports(&self, version: &ServerVersion) -> bool {
235        version.major == self.major
236            && version.minor == self.minor
237            && !version.raw.to_ascii_lowercase().contains("mariadb")
238    }
239    fn status_query(&self) -> &str {
240        if self.major > 8 || self.major == 8 && self.minor >= 4 {
241            "SHOW BINARY LOG STATUS"
242        } else {
243            "SHOW MASTER STATUS"
244        }
245    }
246}
247
248pub fn validate_server_variables(
249    variables: &BTreeMap<String, String>,
250    consumer_id: u32,
251) -> Result<()> {
252    for (name, expected) in [
253        ("log_bin", "ON"),
254        ("binlog_format", "ROW"),
255        ("binlog_row_image", "MINIMAL"),
256    ] {
257        if !variables
258            .get(name)
259            .is_some_and(|v| v.eq_ignore_ascii_case(expected))
260        {
261            return Err(Error::Unsupported(format!("requires {name}={expected}")));
262        }
263    }
264    if variables
265        .get("binlog_transaction_compression")
266        .is_some_and(|v| !v.eq_ignore_ascii_case("OFF"))
267        || variables
268            .get("binlog_row_value_options")
269            .is_some_and(|v| !v.is_empty())
270    {
271        return Err(Error::Unsupported(
272            "disable binlog_transaction_compression and binlog_row_value_options".into(),
273        ));
274    }
275    let upstream_id: u32 = variables
276        .get("server_id")
277        .and_then(|v| v.parse().ok())
278        .filter(|id| *id > 0)
279        .ok_or_else(|| invalid("missing/invalid upstream server_id"))?;
280    if consumer_id == upstream_id {
281        return Err(Error::Schema(
282            "CDC server_id must differ from source server_id".into(),
283        ));
284    }
285    Ok(())
286}
287
288pub fn validate_mysql_v4(format: &FormatDescription<'_>) -> Result<()> {
289    if format.binlog_version != 4 || format.header_length != 19 {
290        return Err(Error::Unsupported(
291            "requires binlog v4 with 19-byte common header".into(),
292        ));
293    }
294    for (kind, length) in [
295        (event::QUERY_EVENT, 13),
296        (event::TABLE_MAP_EVENT, 8),
297        (event::WRITE_ROWS_EVENT, 10),
298        (event::UPDATE_ROWS_EVENT, 10),
299        (event::DELETE_ROWS_EVENT, 10),
300    ] {
301        if format.post_header_lengths.get(usize::from(kind) - 1) != Some(&length) {
302            return Err(Error::Unsupported(format!(
303                "post-header length for event {kind}"
304            )));
305        }
306    }
307    for kind in [
308        event::WRITE_ROWS_EVENT_V1,
309        event::UPDATE_ROWS_EVENT_V1,
310        event::DELETE_ROWS_EVENT_V1,
311    ] {
312        if !matches!(
313            format.post_header_lengths.get(usize::from(kind) - 1),
314            Some(0 | 8)
315        ) {
316            return Err(Error::Unsupported(format!(
317                "post-header length for legacy event {kind}"
318            )));
319        }
320    }
321    Ok(())
322}
323
324pub fn classify_mysql_event(event: EventView<'_>) -> Result<EventAction<'_>> {
325    Ok(match event.event_type {
326        event::ROTATE_EVENT => super::events::parse_rotate(event.data, 8)?,
327        event::QUERY_EVENT => super::events::parse_query(event.data, 13)?,
328        event::XID_EVENT => {
329            if event.data.len() != 8 {
330                return Err(invalid("XID length != 8"));
331            }
332            EventAction::Commit
333        }
334        event::TABLE_MAP_EVENT => EventAction::TableMap,
335        event::WRITE_ROWS_EVENT_V1
336        | event::UPDATE_ROWS_EVENT_V1
337        | event::DELETE_ROWS_EVENT_V1
338        | event::WRITE_ROWS_EVENT
339        | event::UPDATE_ROWS_EVENT
340        | event::DELETE_ROWS_EVENT => EventAction::Rows,
341        event::GTID_EVENT | event::ANONYMOUS_GTID_EVENT | event::GTID_TAGGED_LOG_EVENT => {
342            EventAction::GroupStart
343        }
344        event::STOP_EVENT
345        | event::HEARTBEAT_EVENT
346        | event::IGNORABLE_EVENT
347        | event::ROWS_QUERY_EVENT
348        | event::PREVIOUS_GTIDS_EVENT
349        | event::HEARTBEAT_LOG_EVENT_V2 => EventAction::Ignore,
350        event::XA_PREPARE_LOG_EVENT => return Err(Error::Unsupported("XA transactions".into())),
351        event::PARTIAL_UPDATE_ROWS_EVENT => {
352            return Err(Error::Unsupported(
353                "partial JSON row images; disable binlog_row_value_options".into(),
354            ));
355        }
356        event::TRANSACTION_PAYLOAD_EVENT => {
357            return Err(Error::Unsupported(
358                "compressed transactions; disable binlog_transaction_compression".into(),
359            ));
360        }
361        _ if event.flags & 0x80 != 0 => EventAction::Ignore,
362        other => {
363            return Err(Error::Unsupported(format!(
364                "non-ignorable binlog event {other}"
365            )));
366        }
367    })
368}