Skip to main content

pgwire_replication/client/
worker.rs

1use bytes::Bytes;
2use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
3use std::sync::Arc;
4use tokio::io::{AsyncRead, AsyncWrite, BufReader};
5use tokio::sync::{mpsc, oneshot, watch, Notify, OwnedSemaphorePermit, Semaphore};
6use tokio::time::Instant;
7
8use crate::config::ReplicationConfig;
9use crate::error::{PgWireError, Result};
10use crate::lsn::Lsn;
11use crate::protocol::framing::{
12    read_backend_message_with_limit, write_copy_data, write_copy_done, write_password_message,
13    write_query, write_startup_message, MessageReader,
14};
15use crate::protocol::messages::{parse_auth_request, parse_error_response};
16use crate::protocol::replication::{
17    encode_standby_status_update, parse_copy_data, ReplicationCopyData, PG_EPOCH_MICROS,
18};
19
20const SOCKET_READ_AHEAD_BYTES: usize = 128 * 1024;
21
22/// Shared replication progress updated by the consumer and read by the worker.
23///
24/// Stored as an AtomicU64 so progress updates are cheap and monotonic
25/// without async backpressure.
26pub struct SharedProgress {
27    applied: AtomicU64,
28    keepalive_requested: AtomicBool,
29    keepalive_wake: Notify,
30}
31
32/// Reservation for the raw backend allocation retained by an event.
33///
34/// Clones share one reservation because cloned [`Bytes`] values share the same
35/// backing allocation. Dropping the final guard returns the bytes to the
36/// connection-wide in-flight budget.
37#[derive(Clone)]
38pub struct WireBytesGuard {
39    inner: Arc<WireBytesReservation>,
40}
41
42struct WireBytesReservation {
43    _permit: OwnedSemaphorePermit,
44    retained_bytes: usize,
45}
46
47impl WireBytesGuard {
48    fn new(permit: OwnedSemaphorePermit) -> Self {
49        let retained_bytes = permit.num_permits();
50        Self {
51            inner: Arc::new(WireBytesReservation {
52                _permit: permit,
53                retained_bytes,
54            }),
55        }
56    }
57
58    /// Declared backend payload bytes covered by this reservation.
59    #[inline]
60    pub fn retained_bytes(&self) -> usize {
61        self.inner.retained_bytes
62    }
63}
64
65impl std::fmt::Debug for WireBytesGuard {
66    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67        formatter
68            .debug_struct("WireBytesGuard")
69            .field("retained_bytes", &self.retained_bytes())
70            .finish_non_exhaustive()
71    }
72}
73
74impl SharedProgress {
75    pub fn new(start: Lsn) -> Self {
76        Self {
77            applied: AtomicU64::new(start.as_u64()),
78            keepalive_requested: AtomicBool::new(false),
79            keepalive_wake: Notify::new(),
80        }
81    }
82
83    /// Ask the worker to send a status update that requests an immediate server keepalive.
84    pub fn request_keepalive(&self) {
85        self.keepalive_requested.store(true, Ordering::Release);
86        self.keepalive_wake.notify_one();
87    }
88
89    fn take_keepalive_request(&self) -> bool {
90        self.keepalive_requested.swap(false, Ordering::AcqRel)
91    }
92
93    #[inline]
94    pub fn load_applied(&self) -> Lsn {
95        Lsn::from_u64(self.applied.load(Ordering::Acquire))
96    }
97
98    /// Monotonic update: if `lsn` is lower than the currently stored applied LSN,
99    /// this is a no-op.
100    #[inline]
101    pub fn update_applied(&self, lsn: Lsn) {
102        let new = lsn.as_u64();
103        let mut cur = self.applied.load(Ordering::Relaxed);
104
105        while new > cur {
106            match self
107                .applied
108                .compare_exchange_weak(cur, new, Ordering::Release, Ordering::Relaxed)
109            {
110                Ok(_) => break,
111                Err(observed) => cur = observed,
112            }
113        }
114    }
115}
116
117/// Events emitted by the replication worker.
118#[derive(Debug, Clone)]
119pub enum ReplicationEvent {
120    /// Server heartbeat message.
121    KeepAlive {
122        /// Current server WAL end position
123        wal_end: Lsn,
124        /// Whether server requested a reply (already handled internally)
125        reply_requested: bool,
126        /// Server timestamp (microseconds since 2000-01-01)
127        server_time_micros: i64,
128    },
129
130    /// Start of a transaction (pgoutput Begin message).
131    Begin {
132        final_lsn: Lsn,
133        xid: u32,
134        commit_time_micros: i64,
135    },
136
137    /// WAL data containing transaction changes.
138    XLogData {
139        /// WAL position where this data starts
140        wal_start: Lsn,
141        /// WAL end position (may be 0 for mid-transaction messages)
142        wal_end: Lsn,
143        /// Server timestamp (microseconds since 2000-01-01)
144        server_time_micros: i64,
145        /// pgoutput-encoded change data
146        data: Bytes,
147        /// Aggregate byte-budget reservation for `data`'s backing wire frame.
148        wire_bytes: WireBytesGuard,
149    },
150
151    /// End of a transaction (pgoutput Commit message).
152    Commit {
153        lsn: Lsn,
154        end_lsn: Lsn,
155        commit_time_micros: i64,
156    },
157
158    /// Logical decoding message emitted via `pg_logical_emit_message()`.
159    ///
160    /// Transactional messages are delivered only after the enclosing
161    /// transaction commits. Non-transactional messages are delivered
162    /// immediately.
163    Message {
164        /// Whether the message was emitted inside a transaction.
165        transactional: bool,
166        /// LSN of the message in the WAL.
167        lsn: Lsn,
168        /// UTF-8 application-defined message prefix, sliced from the wire frame.
169        prefix: Bytes,
170        /// Raw message content bytes.
171        content: Bytes,
172        /// Aggregate byte-budget reservation for the retained wire frame.
173        wire_bytes: WireBytesGuard,
174    },
175
176    /// Emitted when `stop_at_lsn` has been reached.
177    ///
178    /// After this event, no more events will be emitted and the
179    /// replication stream will be closed.
180    StoppedAt {
181        /// The LSN that triggered the stop condition
182        reached: Lsn,
183    },
184}
185
186/// Channel receiver type for replication events.
187pub type ReplicationEventReceiver =
188    mpsc::Receiver<std::result::Result<ReplicationEvent, PgWireError>>;
189
190/// Internal worker state.
191pub struct WorkerState {
192    cfg: ReplicationConfig,
193    progress: Arc<SharedProgress>,
194    stop_rx: watch::Receiver<bool>,
195    out: mpsc::Sender<std::result::Result<ReplicationEvent, PgWireError>>,
196    wire_byte_budget: Arc<Semaphore>,
197    startup_tx: Option<oneshot::Sender<Result<()>>>,
198}
199
200impl WorkerState {
201    pub fn new(
202        cfg: ReplicationConfig,
203        progress: Arc<SharedProgress>,
204        stop_rx: watch::Receiver<bool>,
205        out: mpsc::Sender<std::result::Result<ReplicationEvent, PgWireError>>,
206        wire_byte_budget: Arc<Semaphore>,
207    ) -> Self {
208        Self {
209            cfg,
210            progress,
211            stop_rx,
212            out,
213            wire_byte_budget,
214            startup_tx: None,
215        }
216    }
217
218    pub(super) fn install_startup_notifier(&mut self, tx: oneshot::Sender<Result<()>>) {
219        debug_assert!(self.startup_tx.is_none());
220        self.startup_tx = Some(tx);
221    }
222
223    pub(super) fn report_startup_failure(&mut self, error: &PgWireError) {
224        self.publish_startup(Err(error.clone()));
225    }
226
227    fn publish_startup(&mut self, result: Result<()>) {
228        if let Some(tx) = self.startup_tx.take() {
229            let _ = tx.send(result);
230        }
231    }
232
233    /// Run the replication protocol on the given stream.
234    pub async fn run_on_stream<S: AsyncRead + AsyncWrite + Unpin>(
235        &mut self,
236        stream: &mut S,
237    ) -> Result<()> {
238        // Wrap in a 128KB read buffer to batch multiple WAL messages into fewer
239        // recv() syscalls. BufReader delegates AsyncWrite to the inner stream,
240        // so writes (standby status replies, etc.) are unaffected.
241        let mut stream = BufReader::with_capacity(SOCKET_READ_AHEAD_BYTES, stream);
242        let startup = async {
243            startup(&self.cfg, &mut stream).await?;
244            authenticate(&self.cfg, &mut stream).await?;
245            self.validate_recovery_identity(&mut stream).await?;
246            self.start_replication(&mut stream).await
247        }
248        .await;
249        if let Err(error) = startup {
250            self.report_startup_failure(&error);
251            return Err(error);
252        }
253        // CopyBothResponse is PostgreSQL's acceptance point for
254        // START_REPLICATION. Do not let the public connect future return before
255        // this exact protocol boundary.
256        self.publish_startup(Ok(()));
257        self.stream_loop(&mut stream).await
258    }
259
260    /// Start the logical replication stream.
261    async fn start_replication<S: AsyncRead + AsyncWrite + Unpin>(
262        &self,
263        stream: &mut S,
264    ) -> Result<()> {
265        let sql = start_replication_query(&self.cfg);
266        write_query(stream, &sql).await?;
267
268        // Wait for CopyBothResponse
269        loop {
270            let msg = read_backend_message_with_limit(stream, self.cfg.max_message_bytes).await?;
271            match msg.tag {
272                b'W' => return Ok(()), // CopyBothResponse - ready to stream
273                b'E' => return Err(PgWireError::Server(parse_error_response(&msg.payload))),
274                b'N' | b'S' | b'K' => continue, // Notice, ParameterStatus, BackendKeyData
275                _ => continue,
276            }
277        }
278    }
279
280    async fn validate_recovery_identity<S: AsyncRead + AsyncWrite + Unpin>(
281        &self,
282        stream: &mut S,
283    ) -> Result<()> {
284        if self.cfg.expected_recovery_identity.is_none() {
285            return Ok(());
286        }
287
288        let identity =
289            query_single_text_row(&self.cfg, stream, "IDENTIFY_SYSTEM", "IDENTIFY_SYSTEM").await?;
290        validate_identify_system(&self.cfg, &identity)?;
291
292        let slot = escape_string_literal(&self.cfg.slot);
293        let sql = format!(
294            "SELECT confirmed_flush_lsn::text FROM pg_catalog.pg_replication_slots \
295             WHERE slot_name = {slot}"
296        );
297        let slot_row =
298            query_single_text_row(&self.cfg, stream, &sql, "replication-slot recovery cursor")
299                .await?;
300        validate_slot_cursor(&self.cfg, &slot_row)
301    }
302
303    /// Main replication streaming loop.
304    ///
305    /// Uses a two-phase approach for throughput:
306    /// 1. **Drain phase**: while the BufReader has buffered data, read messages
307    ///    in a tight loop without `select!` or timeout overhead.
308    /// 2. **Wait phase**: when the buffer is empty, fall back to `select!` with
309    ///    timeout + stop signal to handle idle keepalives and graceful shutdown.
310    ///
311    /// Reads use [`MessageReader`], which preserves partial-read state across
312    /// dropped futures so the wait-phase `select!` is cancellation-safe.
313    async fn stream_loop<S: AsyncRead + AsyncWrite + Unpin>(
314        &mut self,
315        stream: &mut BufReader<S>,
316    ) -> Result<()> {
317        let mut last_status_sent = Instant::now() - self.cfg.status_interval;
318        let mut last_applied = self.progress.load_applied();
319        // Cancellation-safe message reader, partial reads survive dropped futures.
320        // Start with no payload allocation: each declared payload is reserved
321        // from `wire_byte_budget` before the reader grows this buffer.
322        let mut reader = MessageReader::with_capacity_and_limit(0, self.cfg.max_message_bytes);
323        // How many messages to process in the tight loop before checking
324        // stop signal and sending periodic status feedback.
325        const DRAIN_BATCH: usize = 256;
326
327        loop {
328            // Update applied LSN from client
329            let current_applied = self.progress.load_applied();
330            if current_applied != last_applied {
331                last_applied = current_applied;
332            }
333
334            // Send periodic status feedback
335            if last_status_sent.elapsed() >= self.cfg.status_interval {
336                self.send_feedback(stream, last_applied, false).await?;
337                last_status_sent = Instant::now();
338            }
339            if self.progress.take_keepalive_request() {
340                last_applied = self.progress.load_applied();
341                self.send_feedback(stream, last_applied, true).await?;
342                last_status_sent = Instant::now();
343            }
344
345            // ── Drain phase: tight loop while BufReader has buffered data ──
346            // The BufReader has a 128KB internal buffer. When the kernel delivers
347            // a large TCP segment, many WAL messages are available without syscalls.
348            // Drain in batches, while keeping stop and feedback deadlines live
349            // if either socket input or the wire-byte budget stalls.
350            let mut drained = 0usize;
351            while stream.buffer().len() >= 5 && drained < DRAIN_BATCH {
352                let feedback_deadline = last_status_sent + self.cfg.status_interval;
353                let (msg, wire_permit) = tokio::select! {
354                    biased;
355
356                    changed = self.stop_rx.changed() => {
357                        if changed.is_err() || *self.stop_rx.borrow() {
358                            let _ = write_copy_done(stream).await;
359                            return Ok(());
360                        }
361                        continue;
362                    }
363
364                    result = reader.read_with_budget(stream, &self.wire_byte_budget) => result?,
365
366                    _ = tokio::time::sleep_until(feedback_deadline) => {
367                        let applied = self.progress.load_applied();
368                        last_applied = applied;
369                        self.send_feedback(stream, applied, false).await?;
370                        last_status_sent = Instant::now();
371                        continue;
372                    }
373                };
374                drained += 1;
375                if msg.tag == b'E' {
376                    return Err(PgWireError::Server(parse_error_response(&msg.payload)));
377                }
378                if msg.tag == b'd'
379                    && self
380                        .handle_copy_data(
381                            stream,
382                            msg.payload,
383                            wire_permit,
384                            &mut last_applied,
385                            &mut last_status_sent,
386                        )
387                        .await?
388                {
389                    return Ok(());
390                }
391            }
392
393            // If we drained messages, loop back to check stop/status before
394            // potentially blocking on the next read.
395            if drained > 0 {
396                // Check stop signal without blocking
397                if self.stop_rx.has_changed().unwrap_or(false) && *self.stop_rx.borrow() {
398                    let _ = write_copy_done(stream).await;
399                    return Ok(());
400                }
401                continue;
402            }
403
404            // ── Wait phase: buffer empty, need to wait for socket data ──
405            //
406            // Both `stop_rx.changed()` and the timeout can drop the read future
407            // mid-message. `MessageReader::read` is cancellation-safe — partial
408            // header/payload state lives on `reader` and is preserved across the
409            // drop, so the next iteration resumes the read without losing bytes.
410            let feedback_after = self
411                .cfg
412                .status_interval
413                .saturating_sub(last_status_sent.elapsed());
414            let wake_after = self.cfg.idle_wakeup_interval.min(feedback_after);
415            let (msg, wire_permit) = tokio::select! {
416                biased;
417
418                _ = self.stop_rx.changed() => {
419                    if *self.stop_rx.borrow() {
420                        let _ = write_copy_done(stream).await;
421                        return Ok(());
422                    }
423                    continue;
424                }
425
426                () = self.progress.keepalive_wake.notified() => continue,
427
428                msg_result = tokio::time::timeout(
429                    wake_after,
430                    reader.read_with_budget(stream, &self.wire_byte_budget),
431                ) => {
432                    match msg_result {
433                        Ok(res) => res?,
434                        Err(_) => {
435                            let applied = self.progress.load_applied();
436                            last_applied = applied;
437                            self.send_feedback(stream, applied, false).await?;
438                            last_status_sent = Instant::now();
439                            continue;
440                        }
441                    }
442                }
443            };
444
445            if msg.tag == b'E' {
446                return Err(PgWireError::Server(parse_error_response(&msg.payload)));
447            }
448            if msg.tag == b'd'
449                && self
450                    .handle_copy_data(
451                        stream,
452                        msg.payload,
453                        wire_permit,
454                        &mut last_applied,
455                        &mut last_status_sent,
456                    )
457                    .await?
458            {
459                return Ok(());
460            }
461        }
462    }
463
464    /// Handle a CopyData message. Returns true if we should stop.
465    async fn handle_copy_data<S: AsyncRead + AsyncWrite + Unpin>(
466        &mut self,
467        stream: &mut BufReader<S>,
468        payload: Bytes,
469        wire_permit: OwnedSemaphorePermit,
470        last_applied: &mut Lsn,
471        last_status_sent: &mut Instant,
472    ) -> Result<bool> {
473        let cd = parse_copy_data(payload)?;
474
475        match cd {
476            ReplicationCopyData::KeepAlive {
477                wal_end,
478                server_time_micros,
479                reply_requested,
480            } => {
481                // KeepAlive contains no retained raw slice.
482                drop(wire_permit);
483                // Respond immediately if server requests it
484                if reply_requested {
485                    let applied = self.progress.load_applied();
486                    *last_applied = applied;
487                    self.send_feedback(stream, applied, true).await?;
488                    *last_status_sent = Instant::now();
489                }
490
491                if !self
492                    .send_event_with_feedback(
493                        stream,
494                        ReplicationEvent::KeepAlive {
495                            wal_end,
496                            reply_requested,
497                            server_time_micros,
498                        },
499                        last_applied,
500                        last_status_sent,
501                    )
502                    .await?
503                {
504                    return Ok(true);
505                }
506
507                Ok(false)
508            }
509            ReplicationCopyData::XLogData {
510                wal_start,
511                wal_end,
512                server_time_micros,
513                data,
514            } => {
515                let wire_bytes = WireBytesGuard::new(wire_permit);
516                // If the payload is a pgoutput Begin/Commit message, emit only the boundary event.
517                let (boundary_ev, wire_bytes) = match data.first().copied() {
518                    Some(b'B' | b'C') => (parse_pgoutput_boundary(&data, None)?, None),
519                    Some(b'M') => (parse_pgoutput_boundary(&data, Some(wire_bytes))?, None),
520                    _ => (None, Some(wire_bytes)),
521                };
522                if let Some(boundary_ev) = boundary_ev {
523                    let reached_lsn = match boundary_ev {
524                        ReplicationEvent::Begin { final_lsn, .. } => final_lsn,
525                        ReplicationEvent::Commit { end_lsn, .. } => end_lsn,
526                        _ => wal_end, // should never happen if parser only returns Begin/Commit
527                    };
528
529                    if !self
530                        .send_event_with_feedback(
531                            stream,
532                            boundary_ev,
533                            last_applied,
534                            last_status_sent,
535                        )
536                        .await?
537                    {
538                        return Ok(true);
539                    }
540
541                    // Stop condition (prefer boundary LSN semantics when available)
542                    if let Some(stop_lsn) = self.cfg.stop_at_lsn {
543                        if reached_lsn >= stop_lsn {
544                            if !self
545                                .send_event_with_feedback(
546                                    stream,
547                                    ReplicationEvent::StoppedAt {
548                                        reached: reached_lsn,
549                                    },
550                                    last_applied,
551                                    last_status_sent,
552                                )
553                                .await?
554                            {
555                                return Ok(true);
556                            }
557                            let _ = write_copy_done(stream).await;
558                            return Ok(true); // should stop.
559                        }
560                    }
561
562                    return Ok(false);
563                }
564                // Otherwise, emit raw payload
565                let wire_bytes = wire_bytes.expect("raw XLogData retains its wire reservation");
566                // Check stop condition
567                if let Some(stop_lsn) = self.cfg.stop_at_lsn {
568                    if wal_end >= stop_lsn {
569                        // Send final event, then stop signal
570                        if !self
571                            .send_event_with_feedback(
572                                stream,
573                                ReplicationEvent::XLogData {
574                                    wal_start,
575                                    wal_end,
576                                    server_time_micros,
577                                    data,
578                                    wire_bytes,
579                                },
580                                last_applied,
581                                last_status_sent,
582                            )
583                            .await?
584                        {
585                            return Ok(true);
586                        }
587
588                        if !self
589                            .send_event_with_feedback(
590                                stream,
591                                ReplicationEvent::StoppedAt { reached: wal_end },
592                                last_applied,
593                                last_status_sent,
594                            )
595                            .await?
596                        {
597                            return Ok(true);
598                        }
599
600                        let _ = write_copy_done(stream).await;
601                        return Ok(true);
602                    }
603                }
604
605                if !self
606                    .send_event_with_feedback(
607                        stream,
608                        ReplicationEvent::XLogData {
609                            wal_start,
610                            wal_end,
611                            server_time_micros,
612                            data,
613                            wire_bytes,
614                        },
615                        last_applied,
616                        last_status_sent,
617                    )
618                    .await?
619                {
620                    return Ok(true);
621                }
622
623                Ok(false)
624            }
625        }
626    }
627
628    /// Sends an event without starving feedback while downstream is backpressured.
629    async fn send_event_with_feedback<S: AsyncRead + AsyncWrite + Unpin>(
630        &mut self,
631        stream: &mut BufReader<S>,
632        event: ReplicationEvent,
633        last_applied: &mut Lsn,
634        last_status_sent: &mut Instant,
635    ) -> Result<bool> {
636        let send = self.out.send(Ok(event));
637        tokio::pin!(send);
638
639        loop {
640            let feedback_deadline = *last_status_sent + self.cfg.status_interval;
641            tokio::select! {
642                biased;
643
644                changed = self.stop_rx.changed() => {
645                    if changed.is_err() || *self.stop_rx.borrow() {
646                        let _ = write_copy_done(stream).await;
647                        return Ok(false);
648                    }
649                }
650
651                result = &mut send => {
652                    if result.is_err() {
653                        tracing::debug!("event channel closed, stopping replication worker");
654                        let _ = write_copy_done(stream).await;
655                        return Ok(false);
656                    }
657                    return Ok(true);
658                }
659
660                () = self.progress.keepalive_wake.notified() => {
661                    if self.progress.take_keepalive_request() {
662                        *last_applied = self.progress.load_applied();
663                        self.send_feedback(stream, *last_applied, true).await?;
664                        *last_status_sent = Instant::now();
665                    }
666                }
667
668                _ = tokio::time::sleep_until(feedback_deadline) => {
669                    let applied = self.progress.load_applied();
670                    *last_applied = applied;
671                    self.send_feedback(stream, applied, false).await?;
672                    *last_status_sent = Instant::now();
673                }
674            }
675        }
676    }
677
678    /// Send standby status update to server.
679    async fn send_feedback<S: AsyncWrite + Unpin>(
680        &self,
681        stream: &mut S,
682        applied: Lsn,
683        reply_requested: bool,
684    ) -> Result<()> {
685        let client_time = current_pg_timestamp();
686        let payload = encode_standby_status_update(applied, client_time, reply_requested);
687        write_copy_data(stream, &payload).await
688    }
689}
690
691/// Send startup message with replication parameters.
692pub(super) async fn startup<S: AsyncWrite + Unpin>(
693    cfg: &ReplicationConfig,
694    stream: &mut S,
695) -> Result<()> {
696    let mut params = vec![
697        ("user", cfg.user.as_str()),
698        ("database", cfg.database.as_str()),
699        ("replication", "database"),
700        ("client_encoding", "UTF8"),
701        ("application_name", cfg.application_name.as_str()),
702    ];
703    if let Some(options) = cfg.session_options.as_deref() {
704        params.push(("options", options));
705    }
706    write_startup_message(stream, 196608, &params).await
707}
708
709/// Handle PostgreSQL authentication exchange.
710pub(super) async fn authenticate<S: AsyncRead + AsyncWrite + Unpin>(
711    cfg: &ReplicationConfig,
712    stream: &mut S,
713) -> Result<()> {
714    loop {
715        let msg = read_backend_message_with_limit(stream, cfg.max_message_bytes).await?;
716        match msg.tag {
717            b'R' => {
718                let (code, rest) = parse_auth_request(&msg.payload)?;
719                handle_auth_request(cfg, stream, code, rest).await?;
720            }
721            b'E' => return Err(PgWireError::Server(parse_error_response(&msg.payload))),
722            b'S' | b'K' => {}      // ParameterStatus, BackendKeyData - ignore
723            b'Z' => return Ok(()), // ReadyForQuery - auth complete
724            _ => {}
725        }
726    }
727}
728
729/// Handle a specific authentication request.
730async fn handle_auth_request<S: AsyncRead + AsyncWrite + Unpin>(
731    cfg: &ReplicationConfig,
732    stream: &mut S,
733    code: i32,
734    data: &[u8],
735) -> Result<()> {
736    match code {
737        0 => Ok(()), // AuthenticationOk
738        3 => {
739            // Cleartext password
740            let mut payload = Vec::from(cfg.password.as_bytes());
741            payload.push(0);
742            write_password_message(stream, &payload).await
743        }
744        10 => {
745            // SASL (SCRAM-SHA-256)
746            auth_scram(cfg, stream, data).await
747        }
748        #[cfg(feature = "md5")]
749        5 => {
750            // MD5 password
751            if data.len() != 4 {
752                return Err(PgWireError::Protocol(
753                    "MD5 auth: expected 4-byte salt".into(),
754                ));
755            }
756            let mut salt = [0u8; 4];
757            salt.copy_from_slice(&data[..4]);
758
759            let hash = postgres_md5(&cfg.password, &cfg.user, &salt);
760            let mut payload = hash.into_bytes();
761            payload.push(0);
762            write_password_message(stream, &payload).await
763        }
764        _ => Err(PgWireError::Auth(format!(
765            "unsupported auth method code: {code}"
766        ))),
767    }
768}
769
770/// Perform SCRAM-SHA-256 authentication.
771async fn auth_scram<S: AsyncRead + AsyncWrite + Unpin>(
772    cfg: &ReplicationConfig,
773    stream: &mut S,
774    mechanisms_data: &[u8],
775) -> Result<()> {
776    // Parse offered mechanisms
777    let mechanisms = parse_sasl_mechanisms(mechanisms_data);
778
779    if !mechanisms.iter().any(|m| m == "SCRAM-SHA-256") {
780        return Err(PgWireError::Auth(format!(
781            "server doesn't offer SCRAM-SHA-256, available: {mechanisms:?}"
782        )));
783    }
784
785    #[cfg(not(feature = "scram"))]
786    return Err(PgWireError::Auth(
787        "SCRAM authentication required but 'scram' feature not enabled".into(),
788    ));
789
790    #[cfg(feature = "scram")]
791    {
792        use crate::auth::scram::ScramClient;
793
794        let scram = ScramClient::new(&cfg.user);
795
796        // Send SASLInitialResponse
797        let mut init = Vec::new();
798        init.extend_from_slice(b"SCRAM-SHA-256\0");
799        init.extend_from_slice(&(scram.client_first.len() as i32).to_be_bytes());
800        init.extend_from_slice(scram.client_first.as_bytes());
801        write_password_message(stream, &init).await?;
802
803        // Receive AuthenticationSASLContinue (code 11)
804        let server_first = read_auth_data(stream, 11, cfg.max_message_bytes).await?;
805        let server_first_str = String::from_utf8_lossy(&server_first);
806
807        // Compute and send client-final
808        let (client_final, auth_message, salted_password) =
809            scram.client_final(&cfg.password, &server_first_str)?;
810        write_password_message(stream, client_final.as_bytes()).await?;
811
812        // Receive and verify AuthenticationSASLFinal (code 12)
813        let server_final = read_auth_data(stream, 12, cfg.max_message_bytes).await?;
814        let server_final_str = String::from_utf8_lossy(&server_final);
815        ScramClient::verify_server_final(&server_final_str, &salted_password, &auth_message)?;
816
817        Ok(())
818    }
819}
820
821pub(super) async fn query_single_text_row<S: AsyncRead + AsyncWrite + Unpin>(
822    cfg: &ReplicationConfig,
823    stream: &mut S,
824    sql: &str,
825    context: &str,
826) -> Result<Vec<Option<String>>> {
827    write_query(stream, sql).await?;
828    let mut row = None;
829    loop {
830        let message = read_backend_message_with_limit(stream, cfg.max_message_bytes).await?;
831        match message.tag {
832            b'D' => {
833                if row.is_some() {
834                    return Err(PgWireError::Protocol(format!(
835                        "{context} returned more than one row"
836                    )));
837                }
838                row = Some(parse_text_data_row(&message.payload, context)?);
839            }
840            b'E' => return Err(PgWireError::Server(parse_error_response(&message.payload))),
841            b'Z' => {
842                return row.ok_or_else(|| {
843                    PgWireError::Configuration(format!("{context} returned no rows"))
844                });
845            }
846            b'T' | b'C' | b'N' | b'S' | b'A' => {}
847            tag => {
848                return Err(PgWireError::Protocol(format!(
849                    "unexpected backend message 0x{tag:02X} while reading {context}"
850                )));
851            }
852        }
853    }
854}
855
856/// Run a simple-query command that returns no rows, such as `BEGIN` or `COMMIT`.
857pub(super) async fn execute_command<S: AsyncRead + AsyncWrite + Unpin>(
858    cfg: &ReplicationConfig,
859    stream: &mut S,
860    sql: &str,
861    context: &str,
862) -> Result<()> {
863    write_query(stream, sql).await?;
864    let mut failure = None;
865    loop {
866        let message = read_backend_message_with_limit(stream, cfg.max_message_bytes).await?;
867        match message.tag {
868            b'E' => failure = Some(PgWireError::Server(parse_error_response(&message.payload))),
869            b'Z' => return failure.map_or(Ok(()), Err),
870            b'C' | b'N' | b'S' => {}
871            tag => {
872                return Err(PgWireError::Protocol(format!(
873                    "unexpected backend message 0x{tag:02X} while running {context}"
874                )));
875            }
876        }
877    }
878}
879
880fn escape_string_literal(value: &str) -> String {
881    format!("E'{}'", value.replace('\\', "\\\\").replace('\'', "''"))
882}
883
884fn parse_text_data_row(payload: &[u8], context: &str) -> Result<Vec<Option<String>>> {
885    if payload.len() < 2 {
886        return Err(PgWireError::Protocol(format!(
887            "{context} returned a truncated DataRow"
888        )));
889    }
890    let column_count = i16::from_be_bytes([payload[0], payload[1]]);
891    let column_count = usize::try_from(column_count).map_err(|_| {
892        PgWireError::Protocol(format!(
893            "{context} returned a negative DataRow column count"
894        ))
895    })?;
896    let mut cursor = 2_usize;
897    let mut columns = Vec::with_capacity(column_count);
898    for _ in 0..column_count {
899        let length_end = cursor
900            .checked_add(4)
901            .ok_or_else(|| PgWireError::Protocol(format!("{context} DataRow length overflow")))?;
902        let length_bytes = payload.get(cursor..length_end).ok_or_else(|| {
903            PgWireError::Protocol(format!("{context} returned a truncated DataRow length"))
904        })?;
905        cursor = length_end;
906        let length = i32::from_be_bytes(length_bytes.try_into().expect("four bytes checked"));
907        if length == -1 {
908            columns.push(None);
909            continue;
910        }
911        let length = usize::try_from(length).map_err(|_| {
912            PgWireError::Protocol(format!("{context} returned an invalid DataRow length"))
913        })?;
914        let value_end = cursor.checked_add(length).ok_or_else(|| {
915            PgWireError::Protocol(format!("{context} DataRow value length overflow"))
916        })?;
917        let value = payload.get(cursor..value_end).ok_or_else(|| {
918            PgWireError::Protocol(format!("{context} returned a truncated DataRow value"))
919        })?;
920        let value = std::str::from_utf8(value).map_err(|error| {
921            PgWireError::Protocol(format!("{context} returned non-UTF-8 text: {error}"))
922        })?;
923        columns.push(Some(value.to_owned()));
924        cursor = value_end;
925    }
926    if cursor != payload.len() {
927        return Err(PgWireError::Protocol(format!(
928            "{context} DataRow contains trailing bytes"
929        )));
930    }
931    Ok(columns)
932}
933
934pub(super) fn required_text_column<'a>(
935    row: &'a [Option<String>],
936    index: usize,
937    label: &str,
938) -> Result<&'a str> {
939    row.get(index)
940        .and_then(Option::as_deref)
941        .ok_or_else(|| PgWireError::Configuration(format!("PostgreSQL {label} is NULL or missing")))
942}
943
944fn validate_identify_system(config: &ReplicationConfig, row: &[Option<String>]) -> Result<Lsn> {
945    if row.len() != 4 {
946        return Err(PgWireError::Protocol(format!(
947            "IDENTIFY_SYSTEM returned {} columns, expected 4",
948            row.len()
949        )));
950    }
951    let expected = config.expected_recovery_identity.ok_or_else(|| {
952        PgWireError::Internal("recovery identity validation was not configured".into())
953    })?;
954    let system_identifier = required_text_column(row, 0, "system identifier")?
955        .parse::<u64>()
956        .map_err(|error| PgWireError::Protocol(format!("invalid system identifier: {error}")))?;
957    let timeline_id = required_text_column(row, 1, "timeline")?
958        .parse::<u32>()
959        .map_err(|error| PgWireError::Protocol(format!("invalid timeline: {error}")))?;
960    let wal_end = required_text_column(row, 2, "WAL flush position")?
961        .parse::<Lsn>()
962        .map_err(|error| PgWireError::Protocol(format!("invalid WAL flush position: {error}")))?;
963    let database = required_text_column(row, 3, "database name")?;
964
965    if system_identifier != expected.system_identifier {
966        return Err(PgWireError::Configuration(format!(
967            "PostgreSQL system identifier drifted: expected {}, got {system_identifier}",
968            expected.system_identifier
969        )));
970    }
971    if timeline_id != expected.timeline_id {
972        return Err(PgWireError::Configuration(format!(
973            "PostgreSQL timeline drifted: expected {}, got {timeline_id}; failover and timeline ancestry are not certified",
974            expected.timeline_id
975        )));
976    }
977    if database != config.database {
978        return Err(PgWireError::Configuration(format!(
979            "PostgreSQL replication socket connected to database '{database}', expected '{}'",
980            config.database
981        )));
982    }
983    if config.start_lsn > wal_end {
984        return Err(PgWireError::Configuration(format!(
985            "PostgreSQL recovery LSN {} is ahead of the exact server WAL flush position {wal_end}",
986            config.start_lsn
987        )));
988    }
989    Ok(wal_end)
990}
991
992fn validate_slot_cursor(config: &ReplicationConfig, row: &[Option<String>]) -> Result<()> {
993    if row.len() != 1 {
994        return Err(PgWireError::Protocol(format!(
995            "replication-slot recovery cursor returned {} columns, expected 1",
996            row.len()
997        )));
998    }
999    let confirmed = required_text_column(row, 0, "slot confirmed_flush_lsn")?
1000        .parse::<Lsn>()
1001        .map_err(|error| {
1002            PgWireError::Protocol(format!("invalid slot confirmed_flush_lsn: {error}"))
1003        })?;
1004    if confirmed > config.start_lsn {
1005        return Err(PgWireError::Configuration(format!(
1006            "PostgreSQL slot '{}' has advanced to {confirmed}, beyond recovery LSN {}; required WAL is unavailable",
1007            config.slot, config.start_lsn
1008        )));
1009    }
1010    Ok(())
1011}
1012
1013fn start_replication_query(config: &ReplicationConfig) -> String {
1014    format!(
1015        "START_REPLICATION SLOT {} LOGICAL {} \
1016         (proto_version '1', publication_names '{}', messages 'false')",
1017        config.slot, config.start_lsn, config.publication
1018    )
1019}
1020
1021/// Parse SASL mechanism list from auth data.
1022fn parse_sasl_mechanisms(data: &[u8]) -> Vec<String> {
1023    let mut mechanisms = Vec::new();
1024    let mut remaining = data;
1025
1026    while !remaining.is_empty() {
1027        if let Some(pos) = remaining.iter().position(|&x| x == 0) {
1028            if pos == 0 {
1029                break; // Empty string terminates list
1030            }
1031            mechanisms.push(String::from_utf8_lossy(&remaining[..pos]).to_string());
1032            remaining = &remaining[pos + 1..];
1033        } else {
1034            break;
1035        }
1036    }
1037
1038    mechanisms
1039}
1040
1041fn parse_pgoutput_boundary(
1042    data: &Bytes,
1043    wire_bytes: Option<WireBytesGuard>,
1044) -> Result<Option<ReplicationEvent>> {
1045    if data.is_empty() {
1046        return Ok(None);
1047    }
1048
1049    let tag = data[0];
1050    let mut p = &data[1..];
1051
1052    fn take_i8(p: &mut &[u8]) -> Result<i8> {
1053        if p.is_empty() {
1054            return Err(PgWireError::Protocol("pgoutput: truncated i8".into()));
1055        }
1056        let v = p[0] as i8;
1057        *p = &p[1..];
1058        Ok(v)
1059    }
1060
1061    fn take_i32(p: &mut &[u8]) -> Result<i32> {
1062        if p.len() < 4 {
1063            return Err(PgWireError::Protocol("pgoutput: truncated i32".into()));
1064        }
1065        let (head, tail) = p.split_at(4);
1066        *p = tail;
1067        Ok(i32::from_be_bytes(head.try_into().unwrap()))
1068    }
1069
1070    fn take_i64(p: &mut &[u8]) -> Result<i64> {
1071        if p.len() < 8 {
1072            return Err(PgWireError::Protocol("pgoutput: truncated i64".into()));
1073        }
1074        let (head, tail) = p.split_at(8);
1075        *p = tail;
1076        Ok(i64::from_be_bytes(head.try_into().unwrap()))
1077    }
1078
1079    fn require_end(p: &[u8], message: &str) -> Result<()> {
1080        if p.is_empty() {
1081            Ok(())
1082        } else {
1083            Err(PgWireError::Protocol(format!(
1084                "pgoutput {message}: {} trailing bytes",
1085                p.len()
1086            )))
1087        }
1088    }
1089
1090    match tag {
1091        b'B' => {
1092            let final_lsn = Lsn::from_u64(take_i64(&mut p)? as u64);
1093            let commit_time_micros = take_i64(&mut p)?;
1094            let xid = take_i32(&mut p)? as u32;
1095            require_end(p, "Begin")?;
1096
1097            Ok(Some(ReplicationEvent::Begin {
1098                final_lsn,
1099                commit_time_micros,
1100                xid,
1101            }))
1102        }
1103        b'C' => {
1104            let flags = take_i8(&mut p)?;
1105            if flags != 0 {
1106                return Err(PgWireError::Protocol(format!(
1107                    "pgoutput Commit: unsupported flags {flags}"
1108                )));
1109            }
1110            let lsn = Lsn::from_u64(take_i64(&mut p)? as u64);
1111            let end_lsn = Lsn::from_u64(take_i64(&mut p)? as u64);
1112            let commit_time_micros = take_i64(&mut p)?;
1113            require_end(p, "Commit")?;
1114
1115            Ok(Some(ReplicationEvent::Commit {
1116                lsn,
1117                end_lsn,
1118                commit_time_micros,
1119            }))
1120        }
1121        b'M' => {
1122            // Logical decoding message (pg_logical_emit_message)
1123            // Wire: flags(1) + lsn(8) + prefix(null-terminated) + content_len(4) + content(n)
1124            let flags = take_i8(&mut p)?;
1125            if flags & !1 != 0 {
1126                return Err(PgWireError::Protocol(format!(
1127                    "pgoutput Message: unsupported flags {flags}"
1128                )));
1129            }
1130            let transactional = (flags & 1) != 0;
1131            let lsn = Lsn::from_u64(take_i64(&mut p)? as u64);
1132
1133            // Read null-terminated prefix string
1134            let prefix_end = p.iter().position(|&b| b == 0).ok_or_else(|| {
1135                PgWireError::Protocol("pgoutput Message: missing null terminator for prefix".into())
1136            })?;
1137            let prefix_start = data.len().saturating_sub(p.len());
1138            let prefix = data.slice(prefix_start..prefix_start + prefix_end);
1139            std::str::from_utf8(&prefix).map_err(|error| {
1140                PgWireError::Protocol(format!(
1141                    "pgoutput Message: prefix is not valid UTF-8: {error}"
1142                ))
1143            })?;
1144            p = &p[prefix_end + 1..]; // advance past null byte
1145
1146            let content_len_raw = take_i32(&mut p)?;
1147            let content_len = usize::try_from(content_len_raw).map_err(|_| {
1148                PgWireError::Protocol(format!(
1149                    "pgoutput Message: negative content length {content_len_raw}"
1150                ))
1151            })?;
1152            if p.len() != content_len {
1153                return Err(PgWireError::Protocol(format!(
1154                    "pgoutput Message: expected exactly {} content bytes, got {}",
1155                    content_len,
1156                    p.len()
1157                )));
1158            }
1159            let content_start = data.len().saturating_sub(p.len());
1160            let content = data.slice(content_start..content_start + content_len);
1161
1162            Ok(Some(ReplicationEvent::Message {
1163                transactional,
1164                lsn,
1165                prefix,
1166                content,
1167                wire_bytes: wire_bytes.ok_or_else(|| {
1168                    PgWireError::Internal(
1169                        "logical decoding message is missing its wire-byte reservation".into(),
1170                    )
1171                })?,
1172            }))
1173        }
1174        _ => Ok(None),
1175    }
1176}
1177
1178/// Read authentication response data for a specific auth code.
1179async fn read_auth_data<S: AsyncRead + AsyncWrite + Unpin>(
1180    stream: &mut S,
1181    expected_code: i32,
1182    max_message_bytes: usize,
1183) -> Result<Vec<u8>> {
1184    loop {
1185        let msg = read_backend_message_with_limit(stream, max_message_bytes).await?;
1186        match msg.tag {
1187            b'R' => {
1188                let (code, data) = parse_auth_request(&msg.payload)?;
1189                if code == expected_code {
1190                    return Ok(data.to_vec());
1191                }
1192                return Err(PgWireError::Auth(format!(
1193                    "unexpected auth code {code}, expected {expected_code}"
1194                )));
1195            }
1196            b'E' => return Err(PgWireError::Server(parse_error_response(&msg.payload))),
1197            _ => {} // Skip other messages
1198        }
1199    }
1200}
1201
1202/// Get current time as PostgreSQL timestamp (microseconds since 2000-01-01).
1203fn current_pg_timestamp() -> i64 {
1204    use std::time::{SystemTime, UNIX_EPOCH};
1205
1206    let now = SystemTime::now()
1207        .duration_since(UNIX_EPOCH)
1208        .unwrap_or_default();
1209
1210    let unix_micros = (now.as_secs() as i64) * 1_000_000 + (now.subsec_micros() as i64);
1211    unix_micros - PG_EPOCH_MICROS
1212}
1213
1214/// Compute PostgreSQL MD5 password hash.
1215#[cfg(feature = "md5")]
1216fn postgres_md5(password: &str, user: &str, salt: &[u8; 4]) -> String {
1217    fn md5_hex(data: &[u8]) -> String {
1218        format!("{:x}", md5::compute(data))
1219    }
1220
1221    // First hash: md5(password + username)
1222    let inner = md5_hex(format!("{password}{user}").as_bytes());
1223
1224    // Second hash: md5(inner_hash + salt)
1225    let mut outer_input = inner.into_bytes();
1226    outer_input.extend_from_slice(salt);
1227
1228    format!("md5{}", md5_hex(&outer_input))
1229}
1230
1231#[cfg(test)]
1232mod tests {
1233    use super::*;
1234
1235    async fn read_frontend_message(peer: &mut tokio::io::DuplexStream, tagged: bool) -> Vec<u8> {
1236        use tokio::io::AsyncReadExt;
1237
1238        if tagged {
1239            let mut tag = [0_u8; 1];
1240            peer.read_exact(&mut tag).await.unwrap();
1241        }
1242        let mut length = [0_u8; 4];
1243        peer.read_exact(&mut length).await.unwrap();
1244        let length = i32::from_be_bytes(length);
1245        assert!(length >= 4);
1246        let mut payload = vec![0_u8; usize::try_from(length - 4).unwrap()];
1247        peer.read_exact(&mut payload).await.unwrap();
1248        payload
1249    }
1250
1251    async fn write_backend_message(peer: &mut tokio::io::DuplexStream, tag: u8, payload: &[u8]) {
1252        use tokio::io::AsyncWriteExt;
1253
1254        peer.write_all(&[tag]).await.unwrap();
1255        let length = i32::try_from(payload.len() + 4).unwrap();
1256        peer.write_all(&length.to_be_bytes()).await.unwrap();
1257        peer.write_all(payload).await.unwrap();
1258        peer.flush().await.unwrap();
1259    }
1260
1261    fn text_data_row(values: &[Option<&str>]) -> Vec<u8> {
1262        let mut payload = Vec::new();
1263        payload.extend_from_slice(&i16::try_from(values.len()).unwrap().to_be_bytes());
1264        for value in values {
1265            match value {
1266                Some(value) => {
1267                    payload.extend_from_slice(&i32::try_from(value.len()).unwrap().to_be_bytes());
1268                    payload.extend_from_slice(value.as_bytes());
1269                }
1270                None => payload.extend_from_slice(&(-1_i32).to_be_bytes()),
1271            }
1272        }
1273        payload
1274    }
1275
1276    fn startup_worker_with_config(
1277        config: ReplicationConfig,
1278        startup_tx: oneshot::Sender<Result<()>>,
1279    ) -> (WorkerState, watch::Sender<bool>) {
1280        let (out, _rx) = mpsc::channel(1);
1281        let (stop_tx, stop_rx) = watch::channel(false);
1282        let progress = Arc::new(SharedProgress::new(config.start_lsn));
1283        let budget = Arc::new(Semaphore::new(config.max_in_flight_bytes));
1284        let mut worker = WorkerState::new(config, progress, stop_rx, out, budget);
1285        worker.install_startup_notifier(startup_tx);
1286        (worker, stop_tx)
1287    }
1288
1289    fn startup_worker(
1290        startup_tx: oneshot::Sender<Result<()>>,
1291    ) -> (WorkerState, watch::Sender<bool>) {
1292        startup_worker_with_config(ReplicationConfig::default(), startup_tx)
1293    }
1294
1295    #[tokio::test]
1296    async fn strict_startup_validates_exact_socket_before_copy_both_readiness() {
1297        let (startup_tx, mut startup_rx) = oneshot::channel();
1298        let mut config = ReplicationConfig::default();
1299        config.database = "orders".into();
1300        config.slot = "orders_slot".into();
1301        config.start_lsn = Lsn::from_u64(0x100);
1302        config.expected_recovery_identity = Some(crate::config::ExpectedRecoveryIdentity {
1303            system_identifier: 42,
1304            timeline_id: 7,
1305        });
1306        let (mut worker, stop_tx) = startup_worker_with_config(config, startup_tx);
1307        let (mut worker_stream, mut peer) = tokio::io::duplex(4096);
1308        let worker_task =
1309            tokio::spawn(async move { worker.run_on_stream(&mut worker_stream).await });
1310
1311        read_frontend_message(&mut peer, false).await;
1312        write_backend_message(&mut peer, b'R', &0_i32.to_be_bytes()).await;
1313        write_backend_message(&mut peer, b'Z', b"I").await;
1314
1315        let identify = read_frontend_message(&mut peer, true).await;
1316        assert_eq!(&identify[..identify.len() - 1], b"IDENTIFY_SYSTEM");
1317        write_backend_message(
1318            &mut peer,
1319            b'D',
1320            &text_data_row(&[Some("42"), Some("7"), Some("0/200"), Some("orders")]),
1321        )
1322        .await;
1323        write_backend_message(&mut peer, b'C', b"IDENTIFY_SYSTEM\0").await;
1324        write_backend_message(&mut peer, b'Z', b"I").await;
1325
1326        let slot_query = read_frontend_message(&mut peer, true).await;
1327        let slot_query = std::str::from_utf8(&slot_query[..slot_query.len() - 1]).unwrap();
1328        assert!(slot_query.contains("confirmed_flush_lsn"), "{slot_query}");
1329        assert!(slot_query.contains("orders_slot"), "{slot_query}");
1330        write_backend_message(&mut peer, b'D', &text_data_row(&[Some("0/F0")])).await;
1331        write_backend_message(&mut peer, b'C', b"SELECT 1\0").await;
1332        write_backend_message(&mut peer, b'Z', b"I").await;
1333
1334        let start = read_frontend_message(&mut peer, true).await;
1335        let start = std::str::from_utf8(&start[..start.len() - 1]).unwrap();
1336        assert!(start.starts_with("START_REPLICATION"), "{start}");
1337        assert!(start.contains("messages 'false'"), "{start}");
1338        assert!(matches!(
1339            startup_rx.try_recv(),
1340            Err(oneshot::error::TryRecvError::Empty)
1341        ));
1342        write_backend_message(&mut peer, b'W', &[]).await;
1343        startup_rx.await.unwrap().unwrap();
1344
1345        stop_tx.send(true).unwrap();
1346        tokio::time::timeout(std::time::Duration::from_secs(1), worker_task)
1347            .await
1348            .expect("replication worker must stop")
1349            .unwrap()
1350            .unwrap();
1351    }
1352
1353    #[test]
1354    fn exact_socket_identity_and_lsn_mismatches_fail_closed() {
1355        let mut config = ReplicationConfig::default();
1356        config.database = "orders".into();
1357        config.slot = "orders_slot".into();
1358        config.start_lsn = Lsn::from_u64(0x100);
1359        config.expected_recovery_identity = Some(crate::config::ExpectedRecoveryIdentity {
1360            system_identifier: 42,
1361            timeline_id: 7,
1362        });
1363        let valid = vec![
1364            Some("42".into()),
1365            Some("7".into()),
1366            Some("0/200".into()),
1367            Some("orders".into()),
1368        ];
1369        validate_identify_system(&config, &valid).unwrap();
1370
1371        for (index, value, expected) in [
1372            (0, "43", "system identifier drifted"),
1373            (1, "8", "timeline drifted"),
1374            (3, "other", "connected to database"),
1375        ] {
1376            let mut row = valid.clone();
1377            row[index] = Some(value.into());
1378            let error = validate_identify_system(&config, &row).unwrap_err();
1379            assert!(error.to_string().contains(expected), "{error}");
1380        }
1381
1382        let mut future = valid;
1383        future[2] = Some("0/FF".into());
1384        let error = validate_identify_system(&config, &future).unwrap_err();
1385        assert!(error.to_string().contains("ahead"), "{error}");
1386
1387        validate_slot_cursor(&config, &[Some("0/100".into())]).unwrap();
1388        let error = validate_slot_cursor(&config, &[Some("0/101".into())]).unwrap_err();
1389        assert!(error.to_string().contains("advanced"), "{error}");
1390        let error = validate_slot_cursor(&config, &[None]).unwrap_err();
1391        assert!(error.to_string().contains("NULL"), "{error}");
1392    }
1393
1394    #[tokio::test]
1395    async fn startup_readiness_waits_for_copy_both_response() {
1396        let (startup_tx, mut startup_rx) = oneshot::channel();
1397        let (mut worker, stop_tx) = startup_worker(startup_tx);
1398        let (mut worker_stream, mut peer) = tokio::io::duplex(4096);
1399        let worker_task =
1400            tokio::spawn(async move { worker.run_on_stream(&mut worker_stream).await });
1401
1402        read_frontend_message(&mut peer, false).await;
1403        write_backend_message(&mut peer, b'R', &0_i32.to_be_bytes()).await;
1404        write_backend_message(&mut peer, b'Z', b"I").await;
1405        read_frontend_message(&mut peer, true).await;
1406
1407        assert!(matches!(
1408            startup_rx.try_recv(),
1409            Err(oneshot::error::TryRecvError::Empty)
1410        ));
1411        write_backend_message(&mut peer, b'W', &[]).await;
1412        startup_rx.await.unwrap().unwrap();
1413
1414        stop_tx.send(true).unwrap();
1415        tokio::time::timeout(std::time::Duration::from_secs(1), worker_task)
1416            .await
1417            .expect("replication worker must stop")
1418            .unwrap()
1419            .unwrap();
1420    }
1421
1422    #[tokio::test]
1423    async fn startup_server_error_is_published_before_copy_both_response() {
1424        let (startup_tx, startup_rx) = oneshot::channel();
1425        let (mut worker, _stop_tx) = startup_worker(startup_tx);
1426        let (mut worker_stream, mut peer) = tokio::io::duplex(4096);
1427        let worker_task =
1428            tokio::spawn(async move { worker.run_on_stream(&mut worker_stream).await });
1429
1430        read_frontend_message(&mut peer, false).await;
1431        write_backend_message(&mut peer, b'R', &0_i32.to_be_bytes()).await;
1432        write_backend_message(&mut peer, b'Z', b"I").await;
1433        read_frontend_message(&mut peer, true).await;
1434        write_backend_message(
1435            &mut peer,
1436            b'E',
1437            b"Mpublication missing_publication does not exist\0C42704\0\0",
1438        )
1439        .await;
1440
1441        let startup_error = startup_rx.await.unwrap().unwrap_err();
1442        let worker_error = worker_task.await.unwrap().unwrap_err();
1443        assert!(startup_error.is_server());
1444        assert_eq!(startup_error.to_string(), worker_error.to_string());
1445        assert!(startup_error.to_string().contains("SQLSTATE 42704"));
1446    }
1447
1448    #[test]
1449    fn parse_sasl_mechanisms_single() {
1450        let data = b"SCRAM-SHA-256\0\0";
1451        let mechs = parse_sasl_mechanisms(data);
1452        assert_eq!(mechs, vec!["SCRAM-SHA-256"]);
1453    }
1454
1455    #[test]
1456    fn parse_sasl_mechanisms_multiple() {
1457        let data = b"SCRAM-SHA-256\0SCRAM-SHA-256-PLUS\0\0";
1458        let mechs = parse_sasl_mechanisms(data);
1459        assert_eq!(mechs, vec!["SCRAM-SHA-256", "SCRAM-SHA-256-PLUS"]);
1460    }
1461
1462    #[test]
1463    fn parse_sasl_mechanisms_empty() {
1464        let mechs = parse_sasl_mechanisms(b"\0");
1465        assert!(mechs.is_empty());
1466    }
1467
1468    #[test]
1469    fn pgoutput_boundaries_reject_trailing_bytes_and_unknown_flags() {
1470        let mut begin = Vec::from([b'B']);
1471        begin.extend_from_slice(&1_i64.to_be_bytes());
1472        begin.extend_from_slice(&2_i64.to_be_bytes());
1473        begin.extend_from_slice(&3_i32.to_be_bytes());
1474        assert!(parse_pgoutput_boundary(&Bytes::from(begin.clone()), None).is_ok());
1475        begin.push(0);
1476        assert!(parse_pgoutput_boundary(&Bytes::from(begin), None).is_err());
1477
1478        let mut commit = Vec::from([b'C', 0]);
1479        commit.extend_from_slice(&1_i64.to_be_bytes());
1480        commit.extend_from_slice(&2_i64.to_be_bytes());
1481        commit.extend_from_slice(&3_i64.to_be_bytes());
1482        assert!(parse_pgoutput_boundary(&Bytes::from(commit.clone()), None).is_ok());
1483        commit[1] = 1;
1484        assert!(parse_pgoutput_boundary(&Bytes::from(commit), None).is_err());
1485
1486        let mut message = Vec::from([b'M', 0]);
1487        message.extend_from_slice(&1_i64.to_be_bytes());
1488        message.extend_from_slice(b"prefix\0");
1489        message.extend_from_slice(&3_i32.to_be_bytes());
1490        message.extend_from_slice(b"abc");
1491        let permit = Arc::new(Semaphore::new(message.len()))
1492            .try_acquire_many_owned(message.len() as u32)
1493            .unwrap();
1494        let parsed = parse_pgoutput_boundary(
1495            &Bytes::from(message.clone()),
1496            Some(WireBytesGuard::new(permit)),
1497        );
1498        assert!(parsed.is_ok(), "{parsed:?}");
1499        message.push(0);
1500        assert!(parse_pgoutput_boundary(&Bytes::from(message.clone()), None).is_err());
1501        message[1] = 2;
1502        assert!(parse_pgoutput_boundary(&Bytes::from(message), None).is_err());
1503    }
1504
1505    #[test]
1506    #[cfg(feature = "md5")]
1507    fn postgres_md5_known_value() {
1508        // Test vector: user="md5_user", password="md5_pass", salt=[0x01, 0x02, 0x03, 0x04]
1509        // Can verify with: SELECT 'md5' || md5(md5('md5_passmd5_user') || E'\\x01020304');
1510        let hash = postgres_md5("md5_pass", "md5_user", &[0x01, 0x02, 0x03, 0x04]);
1511        assert!(hash.starts_with("md5"));
1512        assert_eq!(hash.len(), 35); // "md5" + 32 hex chars
1513    }
1514
1515    #[test]
1516    fn current_pg_timestamp_is_positive() {
1517        // Any time after 2000-01-01 should be positive
1518        let ts = current_pg_timestamp();
1519        assert!(ts > 0);
1520    }
1521
1522    #[test]
1523    fn replication_query_uses_validated_replication_identifiers() {
1524        let config = ReplicationConfig::default();
1525        let query = start_replication_query(&config);
1526
1527        assert!(query.contains("SLOT slot LOGICAL"), "{query}");
1528        assert!(query.contains("publication_names 'pub'"), "{query}");
1529        assert!(query.contains("messages 'false'"), "{query}");
1530    }
1531
1532    #[tokio::test]
1533    async fn raw_event_reservation_survives_channel_receive_and_clone() {
1534        let budget = Arc::new(Semaphore::new(4));
1535        let permit = Arc::clone(&budget).acquire_many_owned(4).await.unwrap();
1536        let guard = WireBytesGuard::new(permit);
1537        let event = ReplicationEvent::XLogData {
1538            wal_start: Lsn::ZERO,
1539            wal_end: Lsn::ZERO,
1540            server_time_micros: 0,
1541            data: Bytes::from_static(b"data"),
1542            wire_bytes: guard,
1543        };
1544        let (tx, mut rx) = mpsc::channel::<Result<ReplicationEvent>>(1);
1545
1546        tx.send(Ok(event)).await.unwrap();
1547        assert_eq!(budget.available_permits(), 0, "queued event owns bytes");
1548        let received = rx.recv().await.unwrap().unwrap();
1549        assert_eq!(budget.available_permits(), 0, "consumer owns bytes");
1550        let cloned = received.clone();
1551        drop(received);
1552        assert_eq!(
1553            budget.available_permits(),
1554            0,
1555            "shared backing allocation keeps one reservation"
1556        );
1557        drop(cloned);
1558        assert_eq!(budget.available_permits(), 4);
1559    }
1560
1561    #[tokio::test]
1562    async fn full_event_channel_does_not_starve_standby_feedback() {
1563        use tokio::io::AsyncReadExt;
1564
1565        let mut config = ReplicationConfig::default();
1566        config.status_interval = std::time::Duration::from_millis(10);
1567        let (tx, mut rx) = mpsc::channel(1);
1568        tx.send(Ok(ReplicationEvent::KeepAlive {
1569            wal_end: Lsn::ZERO,
1570            reply_requested: false,
1571            server_time_micros: 0,
1572        }))
1573        .await
1574        .unwrap();
1575        let (_stop_tx, stop_rx) = watch::channel(false);
1576        let progress = Arc::new(SharedProgress::new(Lsn::ZERO));
1577        let budget = Arc::new(Semaphore::new(config.max_in_flight_bytes));
1578        let mut worker = WorkerState::new(config, progress, stop_rx, tx, budget);
1579        let (worker_stream, mut peer) = tokio::io::duplex(128);
1580
1581        let handle = tokio::spawn(async move {
1582            let mut stream = BufReader::new(worker_stream);
1583            let mut applied = Lsn::ZERO;
1584            let mut last_status = Instant::now();
1585            worker
1586                .send_event_with_feedback(
1587                    &mut stream,
1588                    ReplicationEvent::KeepAlive {
1589                        wal_end: Lsn::ZERO,
1590                        reply_requested: false,
1591                        server_time_micros: 1,
1592                    },
1593                    &mut applied,
1594                    &mut last_status,
1595                )
1596                .await
1597        });
1598
1599        let mut feedback = [0_u8; 39];
1600        tokio::time::timeout(
1601            std::time::Duration::from_millis(250),
1602            peer.read_exact(&mut feedback),
1603        )
1604        .await
1605        .expect("feedback must not wait for event-channel capacity")
1606        .unwrap();
1607        assert_eq!(feedback[0], b'd');
1608        assert_eq!(feedback[5], b'r');
1609
1610        drop(rx.recv().await.unwrap());
1611        assert!(handle.await.unwrap().unwrap());
1612    }
1613
1614    async fn read_status_update(peer: &mut tokio::io::DuplexStream) -> [u8; 39] {
1615        use tokio::io::AsyncReadExt;
1616
1617        let mut update = [0_u8; 39];
1618        tokio::time::timeout(
1619            std::time::Duration::from_millis(250),
1620            peer.read_exact(&mut update),
1621        )
1622        .await
1623        .expect("a requested keepalive is sent at once")
1624        .unwrap();
1625        assert_eq!((update[0], update[5]), (b'd', b'r'));
1626        update
1627    }
1628
1629    #[tokio::test]
1630    async fn a_keepalive_request_sends_a_reply_requested_status_update_at_once() {
1631        let config = ReplicationConfig {
1632            status_interval: std::time::Duration::from_secs(3_600),
1633            idle_wakeup_interval: std::time::Duration::from_secs(3_600),
1634            ..ReplicationConfig::default()
1635        };
1636        let (tx, _rx) = mpsc::channel(1);
1637        let (_stop_tx, stop_rx) = watch::channel(false);
1638        let progress = Arc::new(SharedProgress::new(Lsn::from_u64(0x40)));
1639        let budget = Arc::new(Semaphore::new(config.max_in_flight_bytes));
1640        let mut worker = WorkerState::new(config, Arc::clone(&progress), stop_rx, tx, budget);
1641        let (worker_stream, mut peer) = tokio::io::duplex(1024);
1642        let loop_task = tokio::spawn(async move {
1643            let mut stream = BufReader::new(worker_stream);
1644            worker.stream_loop(&mut stream).await
1645        });
1646
1647        let initial = read_status_update(&mut peer).await;
1648        assert_eq!(initial[38], 0, "periodic feedback requests no reply");
1649        progress.request_keepalive();
1650        let requested = read_status_update(&mut peer).await;
1651        assert_eq!(requested[38], 1, "the reply-requested flag is set");
1652        assert_eq!(
1653            &requested[6..14],
1654            &0x40_u64.to_be_bytes(),
1655            "reports the applied LSN"
1656        );
1657        loop_task.abort();
1658    }
1659}