Skip to main content

mysql_replication/
stream.rs

1//! Synchronous replication configuration without CDC schema or checkpoints.
2use crate::{
3    BinlogEvent, BinlogFrame, BinlogParser, Error, FrameDecoder, MAX_EVENT_BYTES, Result,
4    error::invalid, event_type as code, events::BinlogMode, parser::ParserConfig,
5};
6use mysql::{
7    BinlogDumpFlags, BinlogRequest, BinlogStream, Conn, Opts, OptsBuilder, SslOpts,
8    prelude::Queryable,
9};
10use mysql_common::binlog::{
11    consts::BinlogChecksumAlg,
12    events::{BinlogEventHeader, Event as DriverEvent},
13};
14use std::{path::PathBuf, time::Duration};
15
16#[derive(Debug, Clone)]
17pub struct ConnectionConfig {
18    pub url_env: String,
19    pub tls_ca: Option<PathBuf>,
20    pub connect_timeout: Duration,
21    pub read_timeout: Duration,
22}
23impl ConnectionConfig {
24    pub fn new(url_env: impl Into<String>) -> Self {
25        Self {
26            url_env: url_env.into(),
27            tls_ca: None,
28            connect_timeout: Duration::from_secs(10),
29            read_timeout: Duration::from_secs(90),
30        }
31    }
32}
33pub fn connect(config: &ConnectionConfig) -> Result<Conn> {
34    let url = std::env::var(&config.url_env)
35        .map_err(|_| invalid(format!("missing environment variable {}", config.url_env)))?;
36    let opts = Opts::from_url(&url).map_err(|_| invalid("invalid MySQL URL"))?;
37    let mut builder = OptsBuilder::from_opts(opts)
38        .tcp_connect_timeout(Some(config.connect_timeout))
39        .read_timeout(Some(config.read_timeout));
40    if let Some(ca) = &config.tls_ca {
41        builder = builder.ssl_opts(SslOpts::default().with_root_cert_path(Some(ca.clone())));
42    }
43    Ok(Conn::new(builder)?)
44}
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub enum RowImage {
47    Minimal,
48    Full,
49    NoBlob,
50}
51impl RowImage {
52    fn value(self) -> &'static str {
53        match self {
54            Self::Minimal => "MINIMAL",
55            Self::Full => "FULL",
56            Self::NoBlob => "NOBLOB",
57        }
58    }
59}
60#[derive(Debug, Clone)]
61pub struct ReplicationConfig {
62    pub server_id: u32,
63    pub file: String,
64    pub position: u64,
65    pub non_blocking: bool,
66    /// Verifies upstream logging; never changes a global server setting.
67    pub required_row_image: Option<RowImage>,
68    pub parser: ParserConfig,
69}
70impl ReplicationConfig {
71    pub fn new(server_id: u32, file: impl Into<String>, position: u64) -> Self {
72        Self {
73            server_id,
74            file: file.into(),
75            position,
76            non_blocking: false,
77            required_row_image: None,
78            parser: ParserConfig::default(),
79        }
80    }
81}
82
83/// Raw network transport for adapters that own event-body parsing.
84pub struct ReplicationConnection {
85    stream: BinlogStream,
86    current: Option<DriverEvent>,
87    buffer: Vec<u8>,
88    framing: FrameDecoder,
89}
90impl ReplicationConnection {
91    pub fn connect(connection: &ConnectionConfig, replication: ReplicationConfig) -> Result<Self> {
92        Self::from_connection(connect(connection)?, replication)
93    }
94    pub fn from_connection(mut conn: Conn, config: ReplicationConfig) -> Result<Self> {
95        if config.server_id == 0 || config.file.is_empty() || config.position < 4 {
96            return Err(invalid(
97                "replication requires server_id, file and position >= 4",
98            ));
99        }
100        if let Some(image) = config.required_row_image {
101            let actual: Option<String> = conn.query_first("SELECT @@global.binlog_row_image")?;
102            if !actual
103                .as_deref()
104                .is_some_and(|s| s.eq_ignore_ascii_case(image.value()))
105            {
106                return Err(Error::Unsupported(format!(
107                    "requires binlog_row_image={}",
108                    image.value()
109                )));
110            }
111        }
112        conn.query_drop("SET @master_heartbeat_period=30000000000")?;
113        let request = BinlogRequest::new(config.server_id)
114            .with_filename(config.file.as_bytes())
115            .with_pos(config.position)
116            .with_flags(if config.non_blocking {
117                BinlogDumpFlags::BINLOG_DUMP_NON_BLOCK
118            } else {
119                BinlogDumpFlags::empty()
120            });
121        Ok(Self {
122            stream: conn.get_binlog_stream(request)?,
123            current: None,
124            buffer: Vec::new(),
125            framing: FrameDecoder::new(),
126        })
127    }
128    /// CDC's fast path: checksum verification and a borrowed body, with no raw
129    /// frame assembly, GTID metadata decoding or row-value materialization.
130    pub fn next_view(&mut self) -> Result<Option<crate::EventView<'_>>> {
131        self.current = self.stream.next().transpose()?;
132        let Some(event) = &self.current else {
133            return Ok(None);
134        };
135        validate_driver(event)?;
136        if event.header().event_type_raw() == code::FORMAT_DESCRIPTION_EVENT {
137            let algorithm = event
138                .footer()
139                .get_checksum_alg()
140                .map_err(|e| Error::Unsupported(e.to_string()))?;
141            self.framing
142                .set_checksum(algorithm == Some(BinlogChecksumAlg::BINLOG_CHECKSUM_ALG_CRC32));
143        }
144        Ok(Some(crate::EventView {
145            header: header_view(event.header()),
146            body: event.data(),
147        }))
148    }
149    pub fn next_frame(&mut self) -> Result<Option<BinlogFrame<'_>>> {
150        read_frame(&mut self.stream, &mut self.buffer, &mut self.framing)
151    }
152}
153
154/// Typed event subscription; the image mode is explicit and fixed.
155pub struct ReplicationStream<M: BinlogMode> {
156    connection: ReplicationConnection,
157    parser: BinlogParser<M>,
158}
159impl<M: BinlogMode> ReplicationStream<M> {
160    pub fn connect(connection: &ConnectionConfig, config: ReplicationConfig) -> Result<Self> {
161        let config = bind_image_mode::<M>(config)?;
162        Self::from_connection(connect(connection)?, config)
163    }
164    pub fn from_connection(conn: Conn, config: ReplicationConfig) -> Result<Self> {
165        let config = bind_image_mode::<M>(config)?;
166        let parser = BinlogParser::new(config.parser);
167        Ok(Self {
168            connection: ReplicationConnection::from_connection(conn, config)?,
169            parser,
170        })
171    }
172    pub fn next_event(&mut self) -> Result<Option<BinlogEvent<'_, M>>> {
173        let Some(frame) = self.connection.next_frame()? else {
174            return Ok(None);
175        };
176        self.parser.parse(frame).map(Some)
177    }
178}
179
180fn bind_image_mode<M: BinlogMode>(mut config: ReplicationConfig) -> Result<ReplicationConfig> {
181    let expected = M::ROW_IMAGE.into();
182    if config
183        .required_row_image
184        .is_some_and(|mode| mode != expected)
185    {
186        return Err(invalid(
187            "replication configuration conflicts with the generic image mode",
188        ));
189    }
190    config.required_row_image = Some(expected);
191    Ok(config)
192}
193
194fn read_frame<'a>(
195    stream: &mut BinlogStream,
196    buffer: &'a mut Vec<u8>,
197    framing: &mut FrameDecoder,
198) -> Result<Option<BinlogFrame<'a>>> {
199    let Some(event) = stream.next().transpose()? else {
200        return Ok(None);
201    };
202    retain_driver_bytes(&event, buffer)?;
203    framing.decode(buffer).map(Some)
204}
205
206fn header_view(header: BinlogEventHeader) -> crate::EventHeader {
207    crate::EventHeader {
208        timestamp: header.timestamp(),
209        event_type: header.event_type_raw(),
210        server_id: header.server_id(),
211        event_size: header.event_size(),
212        log_pos: header.log_pos(),
213        flags: header.flags_raw(),
214    }
215}
216fn validate_driver(event: &DriverEvent) -> Result<()> {
217    let length = event.header().event_size() as usize;
218    if !(19..=MAX_EVENT_BYTES).contains(&length) {
219        return Err(invalid("event size outside 19..64MiB"));
220    }
221    let algorithm = event
222        .footer()
223        .get_checksum_alg()
224        .map_err(|e| Error::Unsupported(e.to_string()))?;
225    if algorithm == Some(BinlogChecksumAlg::BINLOG_CHECKSUM_ALG_CRC32)
226        && event.checksum().map(u32::from_le_bytes)
227            != Some(event.calc_checksum(BinlogChecksumAlg::BINLOG_CHECKSUM_ALG_CRC32))
228    {
229        return Err(Error::Checksum);
230    }
231    let trailer = usize::from(event.checksum().is_some()) * 4
232        + usize::from(event.header().event_type_raw() == code::FORMAT_DESCRIPTION_EVENT);
233    if 19 + event.data().len() + trailer != length {
234        return Err(invalid("driver did not preserve the complete wire event"));
235    }
236    Ok(())
237}
238
239// The driver splits the wire bytes into header, body, algorithm and checksum.
240// Retain each original value; Event::write must not be used because it recalculates
241// the checksum and can normalize the original trailer.
242fn retain_driver_bytes(event: &DriverEvent, buffer: &mut Vec<u8>) -> Result<()> {
243    let header = event.header();
244    let len = header.event_size() as usize;
245    if !(19..=MAX_EVENT_BYTES).contains(&len) {
246        return Err(invalid("event size outside 19..64MiB"));
247    }
248    buffer.clear();
249    buffer.reserve(len);
250    buffer.extend_from_slice(&header.timestamp().to_le_bytes());
251    buffer.push(header.event_type_raw());
252    buffer.extend_from_slice(&header.server_id().to_le_bytes());
253    buffer.extend_from_slice(&header.event_size().to_le_bytes());
254    buffer.extend_from_slice(&header.log_pos().to_le_bytes());
255    buffer.extend_from_slice(&header.flags_raw().to_le_bytes());
256    buffer.extend_from_slice(event.data());
257    if header.event_type_raw() == code::FORMAT_DESCRIPTION_EVENT {
258        let algorithm = event
259            .footer()
260            .get_checksum_alg()
261            .map_err(|e| Error::Unsupported(e.to_string()))?
262            .ok_or_else(|| invalid("FDE checksum algorithm missing"))?;
263        buffer.push(match algorithm {
264            BinlogChecksumAlg::BINLOG_CHECKSUM_ALG_OFF => 0,
265            BinlogChecksumAlg::BINLOG_CHECKSUM_ALG_CRC32 => 1,
266        });
267    }
268    if let Some(checksum) = event.checksum() {
269        buffer.extend_from_slice(&checksum);
270    }
271    if buffer.len() != len {
272        return Err(invalid("driver did not preserve the complete wire event"));
273    }
274    Ok(())
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280    use mysql_common::binlog::{consts::BinlogVersion, events::FormatDescriptionEvent};
281    #[test]
282    fn driver_trailer_is_retained_instead_of_recalculated() {
283        let mut body = vec![0; 57 + 43];
284        body[..2].copy_from_slice(&4u16.to_le_bytes());
285        body[2..8].copy_from_slice(b"8.4.0\0");
286        body[56] = 19;
287        for algorithm in [0u8, 1] {
288            let mut raw = vec![0; 19];
289            raw[4] = code::FORMAT_DESCRIPTION_EVENT;
290            raw[5..9].copy_from_slice(&123u32.to_le_bytes());
291            raw[17..19].copy_from_slice(&0x8001u16.to_le_bytes());
292            raw.extend_from_slice(&body);
293            raw.push(algorithm);
294            raw.extend_from_slice(&0x12345678u32.to_le_bytes());
295            let length = raw.len() as u32;
296            raw[9..13].copy_from_slice(&length.to_le_bytes());
297            let fde = FormatDescriptionEvent::new(BinlogVersion::Version4);
298            let event = DriverEvent::read(&fde, &raw[..]).unwrap();
299            let mut retained = Vec::new();
300            retain_driver_bytes(&event, &mut retained).unwrap();
301            assert_eq!(retained, raw);
302        }
303    }
304}