pgwire_replication/config.rs
1//! Configuration types for PostgreSQL replication connections.
2//!
3//! This module provides configuration structures for establishing replication
4//! connections to PostgreSQL, including TLS settings and replication parameters.
5
6use std::path::PathBuf;
7use std::time::Duration;
8
9use crate::lsn::Lsn;
10
11/// SSL/TLS connection mode.
12///
13/// These modes match PostgreSQL's `sslmode` connection parameter.
14/// See [PostgreSQL SSL Support](https://www.postgresql.org/docs/current/libpq-ssl.html)
15/// for detailed documentation.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
17pub enum SslMode {
18 /// Never use TLS. Connection will fail if server requires TLS.
19 #[default]
20 Disable,
21
22 /// Try TLS first, fall back to unencrypted if server doesn't support it.
23 ///
24 /// **Warning**: Vulnerable to downgrade attacks. Not recommended for production.
25 Prefer,
26
27 /// Require TLS but don't verify the server certificate.
28 ///
29 /// Protects against passive eavesdropping but not active MITM attacks.
30 Require,
31
32 /// Require TLS and verify the server certificate chain against trusted CAs.
33 ///
34 /// Does NOT verify that the certificate hostname matches the connection target.
35 VerifyCa,
36
37 /// Require TLS, verify certificate chain, AND verify hostname matches.
38 ///
39 /// **Recommended for production**. Provides full protection against MITM attacks.
40 VerifyFull,
41}
42
43impl SslMode {
44 /// Returns `true` if this mode requires TLS (won't fall back to plain).
45 #[inline]
46 pub fn requires_tls(&self) -> bool {
47 !matches!(self, SslMode::Disable | SslMode::Prefer)
48 }
49
50 /// Returns `true` if this mode verifies the certificate chain.
51 #[inline]
52 pub fn verifies_certificate(&self) -> bool {
53 matches!(self, SslMode::VerifyCa | SslMode::VerifyFull)
54 }
55
56 /// Returns `true` if this mode verifies the server hostname.
57 #[inline]
58 pub fn verifies_hostname(&self) -> bool {
59 matches!(self, SslMode::VerifyFull)
60 }
61}
62
63/// TLS/SSL configuration for PostgreSQL connections.
64#[derive(Debug, Clone, Default, PartialEq, Eq)]
65pub struct TlsConfig {
66 /// SSL mode controlling connection security level.
67 pub mode: SslMode,
68
69 /// Path to PEM file containing trusted CA certificates.
70 ///
71 /// If `None` and verification is enabled (`VerifyCa`/`VerifyFull`),
72 /// the Mozilla root certificates (webpki-roots) are used.
73 pub ca_pem_path: Option<PathBuf>,
74
75 /// Override SNI hostname sent during TLS handshake.
76 ///
77 /// Useful when:
78 /// - Connecting via IP address but certificate has a DNS name
79 /// - Using a load balancer with different internal/external names
80 ///
81 /// If `None`, the connection `host` is used for SNI.
82 pub sni_hostname: Option<String>,
83
84 /// Path to PEM file containing client certificate chain.
85 ///
86 /// Required for mutual TLS (mTLS) authentication.
87 /// Must be paired with `client_key_pem_path`.
88 pub client_cert_pem_path: Option<PathBuf>,
89
90 /// Path to PEM file containing client private key.
91 ///
92 /// Required for mutual TLS (mTLS) authentication.
93 /// Must be paired with `client_cert_pem_path`.
94 /// Supports PKCS#8, PKCS#1 (RSA), and SEC1 (EC) formats.
95 pub client_key_pem_path: Option<PathBuf>,
96}
97
98impl TlsConfig {
99 /// Create a configuration with TLS disabled.
100 ///
101 /// # Example
102 /// ```
103 /// use pgwire_replication::config::TlsConfig;
104 ///
105 /// let tls = TlsConfig::disabled();
106 /// assert!(!tls.mode.requires_tls());
107 /// ```
108 pub fn disabled() -> Self {
109 Self::default()
110 }
111
112 /// Create a configuration requiring TLS without certificate verification.
113 ///
114 /// **Warning**: This mode is vulnerable to MITM attacks.
115 /// Use `verify_ca()` or `verify_full()` for production.
116 ///
117 /// # Example
118 /// ```
119 /// use pgwire_replication::config::TlsConfig;
120 ///
121 /// let tls = TlsConfig::require();
122 /// assert!(tls.mode.requires_tls());
123 /// assert!(!tls.mode.verifies_certificate());
124 /// ```
125 pub fn require() -> Self {
126 Self {
127 mode: SslMode::Require,
128 ..Default::default()
129 }
130 }
131
132 /// Create a configuration with certificate chain verification.
133 ///
134 /// # Arguments
135 /// * `ca_path` - Path to CA certificate PEM file, or `None` for system roots
136 ///
137 /// # Example
138 /// ```
139 /// use pgwire_replication::config::TlsConfig;
140 ///
141 /// // Using system/Mozilla roots
142 /// let tls = TlsConfig::verify_ca(None);
143 ///
144 /// // Using custom CA
145 /// let tls = TlsConfig::verify_ca(Some("/path/to/ca.pem".into()));
146 /// ```
147 pub fn verify_ca(ca_path: Option<PathBuf>) -> Self {
148 Self {
149 mode: SslMode::VerifyCa,
150 ca_pem_path: ca_path,
151 ..Default::default()
152 }
153 }
154
155 /// Create a configuration with full verification (chain + hostname).
156 ///
157 /// **Recommended for production**.
158 ///
159 /// # Arguments
160 /// * `ca_path` - Path to CA certificate PEM file, or `None` for system roots
161 ///
162 /// # Example
163 /// ```
164 /// use pgwire_replication::config::TlsConfig;
165 ///
166 /// let tls = TlsConfig::verify_full(Some("/etc/ssl/certs/ca.pem".into()));
167 /// assert!(tls.mode.verifies_hostname());
168 /// ```
169 pub fn verify_full(ca_path: Option<PathBuf>) -> Self {
170 Self {
171 mode: SslMode::VerifyFull,
172 ca_pem_path: ca_path,
173 ..Default::default()
174 }
175 }
176
177 /// Set SNI hostname override.
178 ///
179 /// # Example
180 /// ```
181 /// use pgwire_replication::config::TlsConfig;
182 ///
183 /// let tls = TlsConfig::verify_full(None)
184 /// .with_sni_hostname("db.example.com");
185 /// ```
186 pub fn with_sni_hostname(mut self, hostname: impl Into<String>) -> Self {
187 self.sni_hostname = Some(hostname.into());
188 self
189 }
190
191 /// Configure client certificate for mutual TLS.
192 ///
193 /// # Example
194 /// ```
195 /// use pgwire_replication::config::TlsConfig;
196 ///
197 /// let tls = TlsConfig::verify_full(Some("/ca.pem".into()))
198 /// .with_client_cert("/client.pem", "/client.key");
199 /// ```
200 pub fn with_client_cert(
201 mut self,
202 cert_path: impl Into<PathBuf>,
203 key_path: impl Into<PathBuf>,
204 ) -> Self {
205 self.client_cert_pem_path = Some(cert_path.into());
206 self.client_key_pem_path = Some(key_path.into());
207 self
208 }
209
210 /// Returns `true` if mutual TLS (client certificate) is configured.
211 #[inline]
212 pub fn is_mtls(&self) -> bool {
213 self.client_cert_pem_path.is_some() && self.client_key_pem_path.is_some()
214 }
215}
216
217/// Configuration for PostgreSQL logical replication connections.
218///
219/// # Example
220///
221/// ```
222/// use pgwire_replication::config::{ReplicationConfig, TlsConfig, SslMode};
223/// use pgwire_replication::lsn::Lsn;
224/// use std::time::Duration;
225///
226/// let config = ReplicationConfig {
227/// host: "db.example.com".into(),
228/// port: 5432,
229/// user: "replicator".into(),
230/// password: "secret".into(),
231/// database: "mydb".into(),
232/// slot: "my_slot".into(),
233/// publication: "my_publication".into(),
234/// tls: TlsConfig::verify_full(Some("/path/to/ca.pem".into())),
235/// start_lsn: Lsn(0), // Start from slot's confirmed position
236/// ..Default::default()
237/// };
238/// ```
239#[derive(Debug, Clone, PartialEq, Eq)]
240pub struct ReplicationConfig {
241 /// PostgreSQL server hostname or IP address.
242 pub host: String,
243
244 /// PostgreSQL server port (default: 5432).
245 pub port: u16,
246
247 /// PostgreSQL username with replication privileges.
248 ///
249 /// The user must have the `REPLICATION` attribute or be a superuser.
250 pub user: String,
251
252 /// Password for authentication.
253 pub password: String,
254
255 /// Database name to connect to.
256 pub database: String,
257
258 /// TLS/SSL configuration.
259 pub tls: TlsConfig,
260
261 /// Name of the replication slot to use.
262 ///
263 /// The slot must already exist and be a logical replication slot
264 /// using the `pgoutput` plugin.
265 pub slot: String,
266
267 /// Name of the publication to subscribe to.
268 ///
269 /// The publication must exist and include the tables you want to replicate.
270 pub publication: String,
271
272 /// LSN position to start replication from.
273 ///
274 /// - `Lsn(0)`: Start from slot's `confirmed_flush_lsn`
275 /// - Specific LSN: Resume from that position (must be >= slot's restart_lsn)
276 pub start_lsn: Lsn,
277
278 /// Exact PostgreSQL recovery identity required before streaming starts.
279 ///
280 /// When present, the replication connection validates this identity with
281 /// `IDENTIFY_SYSTEM` and verifies the slot cursor on the same authenticated
282 /// socket before issuing `START_REPLICATION`.
283 pub expected_recovery_identity: Option<ExpectedRecoveryIdentity>,
284
285 /// Optional LSN to stop replication at.
286 ///
287 /// When set, replication will stop once a commit with `end_lsn >= stop_at_lsn`
288 /// is received. Useful for:
289 /// - Bounded replay (e.g., point-in-time recovery)
290 /// - Testing with known data ranges
291 ///
292 /// If `None`, replication continues indefinitely (normal CDC mode).
293 pub stop_at_lsn: Option<Lsn>,
294
295 /// Interval for sending standby status updates to the server.
296 ///
297 /// Status updates inform PostgreSQL of the client's replay position,
298 /// allowing the server to release WAL segments. Too infrequent updates
299 /// may cause WAL accumulation; too frequent updates add overhead.
300 ///
301 /// Default: 1 second (matches pg_recvlogical)
302 pub status_interval: Duration,
303
304 /// Maximum time to wait for server messages before waking up.
305 ///
306 /// Silence is normal during logical replication. When this interval elapses
307 /// with no incoming messages, the client will send a standby status update
308 /// (feedback) and continue waiting.
309 ///
310 /// This effectively bounds how long the worker can stay blocked in a read
311 /// while idle.
312 ///
313 /// Default: 10 seconds
314 pub idle_wakeup_interval: Duration,
315
316 /// Size of the bounded event buffer between replication worker and consumer.
317 ///
318 /// Larger buffers can smooth out processing latency spikes but use more memory.
319 /// Each event is typically 100-1000 bytes depending on row size.
320 ///
321 /// Default: 8192 events
322 pub buffer_events: usize,
323
324 /// Maximum payload bytes accepted for one PostgreSQL backend message.
325 ///
326 /// The limit is checked before allocating the payload buffer. This is a
327 /// per-message protocol limit, not an aggregate queue limit.
328 pub max_message_bytes: usize,
329
330 /// Value of the libpq `options` startup parameter (for example
331 /// `-c DateStyle=ISO`). Session settings govern how output plugins render values.
332 pub session_options: Option<String>,
333
334 /// `application_name` startup parameter, shown in `pg_stat_activity` and
335 /// `pg_stat_replication`. A value in `options` cannot override it.
336 pub application_name: String,
337
338 /// Aggregate raw backend-message payload bytes allowed in flight.
339 ///
340 /// Reservations are retained while a frame is being read, buffered in the
341 /// event channel, and held by the consumer. The event-count limit remains
342 /// a secondary bound for zero/small-payload control events. The connection
343 /// also owns one fixed 128 KiB socket read-ahead buffer outside this limit.
344 pub max_in_flight_bytes: usize,
345}
346
347impl Default for ReplicationConfig {
348 fn default() -> Self {
349 Self {
350 host: "127.0.0.1".into(),
351 port: 5432,
352 user: "postgres".into(),
353 password: "postgres".into(),
354 database: "postgres".into(),
355 tls: TlsConfig::default(),
356 slot: "slot".into(),
357 publication: "pub".into(),
358 start_lsn: Lsn(0),
359 expected_recovery_identity: None,
360 stop_at_lsn: None,
361 status_interval: Duration::from_secs(10),
362 idle_wakeup_interval: Duration::from_secs(10),
363 buffer_events: 8192,
364 max_message_bytes: 64 * 1024 * 1024,
365 session_options: None,
366 application_name: "pgwire-replication".into(),
367 max_in_flight_bytes: 256 * 1024 * 1024,
368 }
369 }
370}
371
372/// PostgreSQL cluster incarnation expected by a durable recovery checkpoint.
373#[derive(Debug, Clone, Copy, PartialEq, Eq)]
374pub struct ExpectedRecoveryIdentity {
375 /// Physical PostgreSQL cluster identifier.
376 pub system_identifier: u64,
377 /// Exact WAL timeline admitted by the checkpoint.
378 pub timeline_id: u32,
379}
380
381impl ReplicationConfig {
382 /// Create a new configuration with required fields.
383 ///
384 /// Other fields use defaults and can be customized with builder methods.
385 ///
386 /// # Example
387 /// ```
388 /// use pgwire_replication::config::ReplicationConfig;
389 ///
390 /// let config = ReplicationConfig::new(
391 /// "db.example.com",
392 /// "replicator",
393 /// "secret",
394 /// "mydb",
395 /// "my_slot",
396 /// "my_pub",
397 /// );
398 /// ```
399 pub fn new(
400 host: impl Into<String>,
401 user: impl Into<String>,
402 password: impl Into<String>,
403 database: impl Into<String>,
404 slot: impl Into<String>,
405 publication: impl Into<String>,
406 ) -> Self {
407 Self {
408 host: host.into(),
409 user: user.into(),
410 password: password.into(),
411 database: database.into(),
412 slot: slot.into(),
413 publication: publication.into(),
414 ..Default::default()
415 }
416 }
417
418 /// Returns `true` if `host` refers to a Unix domain socket directory.
419 ///
420 /// Following libpq convention, a host starting with `/` is treated as
421 /// the directory containing the PostgreSQL Unix socket file.
422 #[inline]
423 pub fn is_unix_socket(&self) -> bool {
424 self.host.starts_with('/')
425 }
426
427 /// Returns the full Unix socket path: `{host}/.s.PGSQL.{port}`.
428 ///
429 /// # Panics
430 ///
431 /// Panics if `host` does not start with `/` (i.e. `is_unix_socket()` is false).
432 pub fn unix_socket_path(&self) -> std::path::PathBuf {
433 assert!(
434 self.is_unix_socket(),
435 "unix_socket_path() called but host is not a socket directory: {:?}",
436 self.host
437 );
438 std::path::Path::new(&self.host).join(format!(".s.PGSQL.{}", self.port))
439 }
440
441 /// Create a configuration for connecting via Unix domain socket.
442 ///
443 /// `socket_dir` is the directory containing the PostgreSQL socket file
444 /// (e.g. `/var/run/postgresql`). The actual socket path will be
445 /// `{socket_dir}/.s.PGSQL.{port}`.
446 ///
447 /// TLS is automatically disabled for Unix socket connections.
448 ///
449 /// # Example
450 /// ```
451 /// use pgwire_replication::config::ReplicationConfig;
452 ///
453 /// let config = ReplicationConfig::unix(
454 /// "/var/run/postgresql",
455 /// 5432,
456 /// "replicator",
457 /// "secret",
458 /// "mydb",
459 /// "my_slot",
460 /// "my_pub",
461 /// );
462 /// assert!(config.is_unix_socket());
463 /// ```
464 pub fn unix(
465 socket_dir: impl Into<String>,
466 port: u16,
467 user: impl Into<String>,
468 password: impl Into<String>,
469 database: impl Into<String>,
470 slot: impl Into<String>,
471 publication: impl Into<String>,
472 ) -> Self {
473 Self {
474 host: socket_dir.into(),
475 port,
476 user: user.into(),
477 password: password.into(),
478 database: database.into(),
479 tls: TlsConfig::disabled(),
480 slot: slot.into(),
481 publication: publication.into(),
482 ..Default::default()
483 }
484 }
485
486 /// Set the server port.
487 pub fn with_port(mut self, port: u16) -> Self {
488 self.port = port;
489 self
490 }
491
492 /// Set TLS configuration.
493 pub fn with_tls(mut self, tls: TlsConfig) -> Self {
494 self.tls = tls;
495 self
496 }
497
498 /// Set the starting LSN.
499 pub fn with_start_lsn(mut self, lsn: Lsn) -> Self {
500 self.start_lsn = lsn;
501 self
502 }
503
504 /// Set an optional stop LSN for bounded replay.
505 pub fn with_stop_lsn(mut self, lsn: Lsn) -> Self {
506 self.stop_at_lsn = Some(lsn);
507 self
508 }
509
510 /// Set the status update interval.
511 pub fn with_status_interval(mut self, interval: Duration) -> Self {
512 self.status_interval = interval;
513 self
514 }
515
516 /// Set the idle wakeup interval.
517 pub fn with_wakeup_interval(mut self, timeout: Duration) -> Self {
518 self.idle_wakeup_interval = timeout;
519 self
520 }
521
522 /// Set the event buffer size.
523 pub fn with_buffer_size(mut self, size: usize) -> Self {
524 self.buffer_events = size;
525 self
526 }
527
528 /// Returns the connection string for display (password masked).
529 ///
530 /// Useful for logging without exposing credentials.
531 pub fn display_connection(&self) -> String {
532 if self.is_unix_socket() {
533 format!(
534 "postgresql://{}:***@[{}]:{}/{}",
535 self.user,
536 self.unix_socket_path().display(),
537 self.port,
538 self.database
539 )
540 } else {
541 format!(
542 "postgresql://{}:***@{}:{}/{}",
543 self.user, self.host, self.port, self.database
544 )
545 }
546 }
547}