Skip to main content

mysql_replication/
replication.rs

1//! Configuration-driven replication and committed event listeners.
2
3use crate::{
4    Error, OwnedChange, Result,
5    config::AppConfig,
6    engine::{Runtime, checkpoint::State},
7    sink::TransactionSink,
8};
9use std::sync::{Arc, Mutex};
10
11/// A normalized, committed transaction. Row values are not materialized.
12///
13/// The data is borrowed from the transaction buffer and is valid only during
14/// the callback. Clone changes only when retaining them beyond the callback.
15#[derive(Clone, Copy, Debug)]
16pub struct Event<'a> {
17    pub source_id: &'a str,
18    /// The commit boundary, persisted only after every handler succeeds.
19    pub checkpoint: &'a State,
20    /// Changes in binlog order; empty for a fully filtered transaction.
21    pub changes: &'a [OwnedChange],
22}
23
24/// Handles converted events synchronously, applying backpressure to consumption.
25///
26/// Handlers run in registration order, with no interleaving across sources.
27/// An error stops consumption without acknowledging this transaction. Earlier
28/// handlers may already have produced side effects, so retries must tolerate
29/// replay. Panics also stop consumption; they do not acknowledge the event.
30pub trait EventHandler: Send + Sync {
31    fn handle(&self, event: Event<'_>) -> Result<()>;
32}
33
34impl<F> EventHandler for F
35where
36    F: Fn(Event<'_>) -> Result<()> + Send + Sync,
37{
38    fn handle(&self, event: Event<'_>) -> Result<()> {
39        self(event)
40    }
41}
42
43/// Replicates the configured sources and delivers committed changes to handlers.
44///
45/// There is no default handler. Register at least one before starting, to avoid
46/// advancing checkpoints without a consumer. Use `with_runtime` to register
47/// custom source plugins or version adapters.
48pub struct Replication {
49    config: AppConfig,
50    runtime: Runtime,
51    handlers: Vec<Box<dyn EventHandler>>,
52}
53
54impl Replication {
55    pub fn new(config: AppConfig) -> Result<Self> {
56        Self::with_runtime(config, Runtime::default())
57    }
58
59    pub fn with_runtime(config: AppConfig, runtime: Runtime) -> Result<Self> {
60        config.validate()?;
61        Ok(Self {
62            config,
63            runtime,
64            handlers: Vec::new(),
65        })
66    }
67
68    /// Registers a handler or a `Fn(Event<'_>) -> Result<()>` closure.
69    pub fn add_handle(&mut self, handler: impl EventHandler + 'static) -> &mut Self {
70        self.handlers.push(Box::new(handler));
71        self
72    }
73
74    /// Validates the upstream settings and whitelist without consuming events.
75    pub fn check(&self) -> Result<()> {
76        self.runtime.check(&self.config)
77    }
78
79    /// Creates initial checkpoints without consuming events.
80    pub fn initialize(self) -> Result<()> {
81        self.runtime.initialize(self.config)
82    }
83
84    /// Consumes continuously until a source or handler fails.
85    pub fn run(self) -> Result<()> {
86        self.start(false)
87    }
88
89    /// Consumes the currently available binlog and returns at its end.
90    pub fn run_once(self) -> Result<()> {
91        self.start(true)
92    }
93
94    fn start(self, once: bool) -> Result<()> {
95        if self.handlers.is_empty() {
96            return Err(Error::Sink("register at least one event handler".into()));
97        }
98        self.runtime.run(
99            self.config,
100            once,
101            Arc::new(Handlers {
102                handlers: self.handlers,
103                failed: Mutex::new(false),
104            }),
105        )
106    }
107}
108
109struct Handlers {
110    handlers: Vec<Box<dyn EventHandler>>,
111    failed: Mutex<bool>,
112}
113
114impl TransactionSink for Handlers {
115    fn commit(&self, source_id: &str, state: &State, changes: &[OwnedChange]) -> Result<()> {
116        // Serialize whole transactions, including all registered callbacks.
117        let mut failed = self
118            .failed
119            .lock()
120            .map_err(|_| Error::Sink("event handler lock poisoned".into()))?;
121        if *failed {
122            return Err(Error::Sink("an event handler failed previously".into()));
123        }
124        let event = Event {
125            source_id,
126            checkpoint: state,
127            changes,
128        };
129        for handler in &self.handlers {
130            if let Err(error) = handler.handle(event) {
131                *failed = true;
132                return Err(error);
133            }
134        }
135        Ok(())
136    }
137}