Skip to main content

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}