rivet/config/
source.rs

1//! Source-database connection config: URL/structured fields, TLS, environment hints.
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6use super::resolve::resolve_env_vars;
7use crate::tuning::{TuningConfig, TuningProfile};
8
9#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone)]
10#[serde(deny_unknown_fields)]
11pub struct SourceConfig {
12    #[serde(rename = "type")]
13    pub source_type: SourceType,
14
15    pub url: Option<String>,
16    pub url_env: Option<String>,
17    pub url_file: Option<String>,
18
19    pub host: Option<String>,
20    pub port: Option<u16>,
21    pub user: Option<String>,
22    pub password: Option<String>,
23    pub password_env: Option<String>,
24    pub database: Option<String>,
25
26    /// Operational profile of the source database.
27    ///
28    /// Selects the **default** tuning profile when none is explicitly set in
29    /// `source.tuning.profile` or `export.tuning.profile`:
30    ///
31    /// | `environment`           | default profile |
32    /// |-------------------------|------------------|
33    /// | `production` (default)  | `balanced` (50 ms throttle, 10 k batch, retries) |
34    /// | `replica`               | `balanced` |
35    /// | `local`                 | `fast` (no throttle, 50 k batch — saves ~30% wall on localhost) |
36    ///
37    /// Explicit `tuning.profile:` always wins over this hint.
38    #[serde(default)]
39    pub environment: Option<SourceEnvironment>,
40
41    #[serde(default)]
42    pub tuning: Option<TuningConfig>,
43
44    /// Transport security settings (ADR: SecOps). When absent, Rivet connects
45    /// without TLS — a warning is emitted so operators are aware. See [`TlsConfig`].
46    #[serde(default)]
47    pub tls: Option<TlsConfig>,
48}
49
50/// Operational environment of the source database — drives the default tuning
51/// profile when none is explicitly set. Opt-in: existing configs without
52/// `environment:` continue to use `balanced` as today.
53#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
54#[serde(rename_all = "lowercase")]
55pub enum SourceEnvironment {
56    /// Localhost / Docker compose / read-only container — no throttle by default
57    /// (compiles to `fast` profile defaults). Use when DB load is not a concern.
58    Local,
59    /// Read replica — `balanced` default. Same throttle as production, but free
60    /// to dial up `tuning.batch_size`.
61    Replica,
62    /// Live production primary — `balanced` default. Bias toward source-safety.
63    Production,
64}
65
66impl SourceEnvironment {
67    /// Default tuning profile selected by this environment when the user has
68    /// not set `tuning.profile:` explicitly.
69    pub fn default_profile(self) -> TuningProfile {
70        match self {
71            SourceEnvironment::Local => TuningProfile::Fast,
72            SourceEnvironment::Replica | SourceEnvironment::Production => TuningProfile::Balanced,
73        }
74    }
75}
76
77/// Transport security for the source database connection.
78///
79/// Credentials and exported data cross the wire on every connection; without TLS
80/// they are visible to anyone on the network path (cloud inter-VPC, cross-AZ, or
81/// a compromised upstream). The default for all new connections is
82/// [`TlsMode::Require`] when `tls:` is present; setting `tls: { mode: disable }`
83/// is explicit opt-out.
84///
85/// ```yaml
86/// source:
87///   type: postgres
88///   url_env: DATABASE_URL
89///   tls:
90///     mode: verify-full
91///     ca_file: /etc/ssl/certs/rds-ca-2019-root.pem
92/// ```
93#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Default)]
94#[serde(deny_unknown_fields)]
95pub struct TlsConfig {
96    /// Enforcement level. See [`TlsMode`].
97    #[serde(default)]
98    pub mode: TlsMode,
99    /// PEM-encoded CA certificate to trust for server verification. Required
100    /// for [`TlsMode::VerifyCa`] and [`TlsMode::VerifyFull`] against a private CA.
101    pub ca_file: Option<String>,
102    /// Accept certificates not chained to a trusted CA. Dangerous — disables
103    /// server authentication — and only honored when explicitly `true`.
104    #[serde(default)]
105    pub accept_invalid_certs: bool,
106    /// Accept certificates whose subjectAltName does not match the connection
107    /// hostname. Dangerous — disables hostname verification.
108    #[serde(default)]
109    pub accept_invalid_hostnames: bool,
110}
111
112/// TLS enforcement mode, mirroring libpq's `sslmode` semantics where possible.
113#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq, Default)]
114#[serde(rename_all = "kebab-case")]
115pub enum TlsMode {
116    /// Plaintext. Use only inside trusted networks (loopback, cgroup-private).
117    Disable,
118    /// Require a TLS handshake; accept the server certificate without verifying
119    /// issuer or hostname. Protects against passive sniffing, not MITM.
120    Require,
121    /// TLS + verify certificate chains to the configured / system trust store.
122    /// Does not check hostname (useful for IP-addressed or internal names).
123    VerifyCa,
124    /// TLS + verify chain **and** hostname against the server cert's SAN/CN.
125    /// Recommended default for production.
126    #[default]
127    VerifyFull,
128}
129
130impl TlsMode {
131    pub fn is_enforced(self) -> bool {
132        !matches!(self, TlsMode::Disable)
133    }
134}
135
136impl SourceConfig {
137    /// Return a copy of this config with **all plaintext credential material stripped**,
138    /// safe to embed in a persisted [`crate::plan::PlanArtifact`] (ADR-0005 PA9).
139    ///
140    /// Redaction rules:
141    /// - `password` → always `None` (plaintext password never leaves the process).
142    /// - `url` containing `user[:password]@` → userinfo segment replaced with `"REDACTED"`.
143    /// - `url_env`, `url_file`, `password_env` — kept (env var **names** and file paths
144    ///   are references, not secrets; `apply` needs them to re-resolve credentials).
145    /// - `host`, `port`, `user`, `database` — kept (structured connection metadata).
146    ///
147    /// If a plaintext `password` or `url` is redacted, callers should surface a warning
148    /// to the operator so env/file-based auth is available at apply time.
149    pub fn redact_for_artifact(&self) -> (Self, bool) {
150        let mut out = self.clone();
151        let mut redacted = false;
152
153        if out.password.is_some() {
154            out.password = None;
155            redacted = true;
156        }
157
158        if let Some(ref raw) = out.url
159            && let Some((userinfo_end, scheme_end)) = find_userinfo(raw)
160        {
161            let mut s = String::with_capacity(raw.len());
162            s.push_str(&raw[..scheme_end]); // "postgresql://"
163            s.push_str("REDACTED");
164            s.push_str(&raw[userinfo_end..]); // "@host:port/db…"
165            out.url = Some(s);
166            redacted = true;
167        }
168
169        (out, redacted)
170    }
171
172    pub(crate) fn has_structured_fields(&self) -> bool {
173        self.host.is_some()
174            || self.user.is_some()
175            || self.database.is_some()
176            || self.password.is_some()
177            || self.password_env.is_some()
178    }
179
180    pub(crate) fn has_url_fields(&self) -> bool {
181        self.url.is_some() || self.url_env.is_some() || self.url_file.is_some()
182    }
183
184    fn build_url_from_fields(&self) -> crate::error::Result<String> {
185        // First-user-friendly errors: name the missing field, suggest a
186        // concrete value, and remind the operator that `url_env` is the
187        // alternative path so they don't bounce.  See
188        // `docs/getting-started.md` for the full onboarding flow.
189        let host = self.host.as_deref().ok_or_else(|| {
190            anyhow::anyhow!(
191                "source: structured config is missing 'host'.\n  Hint: add `host: localhost` (or your DB host) under `source:` in rivet.yaml.\n  Or switch to URL-based config: `url_env: DATABASE_URL`."
192            )
193        })?;
194        let user = self.user.as_deref().ok_or_else(|| {
195            anyhow::anyhow!(
196                "source: structured config is missing 'user'.\n  Hint: add `user: <username>` under `source:` in rivet.yaml."
197            )
198        })?;
199        let database = self.database.as_deref().ok_or_else(|| {
200            anyhow::anyhow!(
201                "source: structured config is missing 'database'.\n  Hint: add `database: <dbname>` under `source:` in rivet.yaml."
202            )
203        })?;
204
205        // SecOps: keep the plaintext password inside a `Zeroizing<String>` until it
206        // is spliced into the final URL, so the standalone password buffer is
207        // wiped on drop (the final URL still lives as a plain String but is
208        // shorter-lived and dropped by the driver constructor).
209        let password: zeroize::Zeroizing<String> =
210            zeroize::Zeroizing::new(match (&self.password, &self.password_env) {
211                (Some(_), Some(_)) => {
212                    anyhow::bail!("source: specify 'password' or 'password_env', not both");
213                }
214                (Some(p), None) => {
215                    static WARNED: std::sync::Once = std::sync::Once::new();
216                    WARNED.call_once(|| {
217                        log::warn!(
218                            "source config contains plaintext password -- consider using password_env"
219                        );
220                    });
221                    resolve_env_vars(p)?
222                }
223                (None, Some(env)) => std::env::var(env).map_err(|_| {
224                    anyhow::anyhow!(
225                        "source: env var '{0}' is not set (referenced by password_env).\n  Hint: export the value before running, e.g.\n      export {0}='your-database-password'",
226                        env
227                    )
228                })?,
229                (None, None) => String::new(),
230            });
231
232        let default_port = match self.source_type {
233            SourceType::Postgres => 5432,
234            SourceType::Mysql => 3306,
235            SourceType::Mssql => 1433,
236        };
237        let port = self.port.unwrap_or(default_port);
238
239        let scheme = match self.source_type {
240            SourceType::Postgres => "postgresql",
241            SourceType::Mysql => "mysql",
242            SourceType::Mssql => "sqlserver",
243        };
244
245        if password.is_empty() {
246            Ok(format!(
247                "{}://{}@{}:{}/{}",
248                scheme, user, host, port, database
249            ))
250        } else {
251            Ok(format!(
252                "{}://{}:{}@{}:{}/{}",
253                scheme,
254                user,
255                password.as_str(),
256                host,
257                port,
258                database
259            ))
260        }
261    }
262
263    pub fn resolve_url(&self) -> crate::error::Result<String> {
264        if self.has_url_fields() && self.has_structured_fields() {
265            anyhow::bail!(
266                "source: pick either URL-based config (url/url_env/url_file) OR structured fields (host/user/database/port/password_env), not both.\n  Hint: remove whichever block you don't want; mixing the two is ambiguous."
267            );
268        }
269
270        if self.has_structured_fields() {
271            return self.build_url_from_fields();
272        }
273
274        // Capture *where* the URL came from so the password warning below
275        // can be specific: scolding an operator who already used
276        // `url_env:` (the recommendation!) for "considering url_env" is
277        // misleading and trains them to tune out our warnings.
278        //
279        // The `EnvVar(&str)` / `File(&str)` payloads are retained for
280        // future use (e.g. mentioning the env-var name in a richer
281        // diagnostic later) — `#[allow(dead_code)]` keeps clippy quiet
282        // while we keep the slot open. Renaming the variants to unit
283        // would lose the documentation that "this came from <name>".
284        #[allow(dead_code)]
285        enum UrlSource<'a> {
286            InlineYaml,
287            EnvVar(&'a str),
288            File(&'a str),
289        }
290        let (raw, source) = match (&self.url, &self.url_env, &self.url_file) {
291            (Some(u), None, None) => (u.clone(), UrlSource::InlineYaml),
292            (None, Some(env), None) => (
293                std::env::var(env).map_err(|_| {
294                    anyhow::anyhow!(
295                        "source: env var '{0}' is not set (referenced by url_env).\n  Hint: export the value before running, e.g.\n      export {0}='postgresql://user:pass@host:5432/dbname'\n  Or change `url_env: {0}` in your config to a different env var name.",
296                        env
297                    )
298                })?,
299                UrlSource::EnvVar(env),
300            ),
301            (None, None, Some(file)) => (
302                std::fs::read_to_string(file)
303                    .map_err(|e| {
304                        anyhow::anyhow!(
305                            "source: cannot read url_file '{}': {}.\n  Hint: ensure the file exists and is readable; the file should contain only the URL on a single line.",
306                            file,
307                            e
308                        )
309                    })?
310                    .trim()
311                    .to_string(),
312                UrlSource::File(file),
313            ),
314            _ => anyhow::bail!(
315                "source: configure exactly one connection method:\n  url_env: DATABASE_URL                          (URL from env var — recommended)\n  url: 'postgresql://user:pass@host:5432/db'      (inline — not recommended for committed configs)\n  url_file: /etc/rivet/source.url                 (URL from file — rotation-friendly)\n  host/user/database/...                          (structured fields under `source:`)"
316            ),
317        };
318
319        let resolved = resolve_env_vars(&raw)?;
320
321        if resolved.contains('@')
322            && resolved.contains(':')
323            && let Some(userinfo) = resolved.split('@').next()
324            && userinfo.contains(':')
325            && !userinfo.ends_with(':')
326        {
327            // `resolve_url` is called from many places per run (plan build,
328            // doctor, every export, every chunk worker). Fire each variant
329            // of this warning exactly once per process so operators see
330            // one clean nudge, not 3-4 stacked copies in stderr.
331            //
332            // Only the InlineYaml case is a real misconfiguration to flag:
333            // the password is sitting in a committed file. EnvVar / File
334            // sources are explicitly the recommended forms — scolding an
335            // operator who already uses them for "considering url_env"
336            // would be a false alarm.
337            match source {
338                UrlSource::InlineYaml => {
339                    static WARNED: std::sync::Once = std::sync::Once::new();
340                    WARNED.call_once(|| {
341                        log::warn!(
342                            "source: inline `url:` in YAML contains a plaintext password — \
343                             move it to `url_env: DATABASE_URL` (or `url_file:`) to keep \
344                             credentials out of committed configs"
345                        );
346                    });
347                }
348                UrlSource::EnvVar(_) | UrlSource::File(_) => {
349                    // The recommended forms — no warning. Operator hygiene
350                    // for shell history / file permissions is out of scope.
351                }
352            }
353        }
354
355        Ok(resolved)
356    }
357}
358
359#[derive(Debug, Deserialize, Serialize, JsonSchema, Clone, Copy, PartialEq, Eq)]
360#[serde(rename_all = "lowercase")]
361pub enum SourceType {
362    Postgres,
363    Mysql,
364    Mssql,
365}
366
367/// Locate `user[:password]@` userinfo inside a standard URL.
368///
369/// Returns `(userinfo_end_index, scheme_end_index)` where:
370/// - `scheme_end_index` points right after `"://"` (start of userinfo)
371/// - `userinfo_end_index` points at the `@` separator (exclusive of `@`)
372///
373/// Returns `None` if the URL has no userinfo segment.
374fn find_userinfo(raw: &str) -> Option<(usize, usize)> {
375    let scheme = raw.find("://")? + 3;
376    let rest = &raw[scheme..];
377    let at = rest.find('@')?;
378    // `@` must appear before the path/query start so we don't match `?foo=a@b` etc.
379    if let Some(path) = rest.find('/')
380        && path < at
381    {
382        return None;
383    }
384    Some((scheme + at, scheme))
385}
386
387#[cfg(test)]
388mod tests {
389    use super::*;
390
391    // ── TlsMode::is_enforced ────────────────────────────────────────────────
392
393    #[test]
394    fn tls_mode_disable_not_enforced() {
395        assert!(!TlsMode::Disable.is_enforced());
396    }
397
398    #[test]
399    fn tls_mode_require_is_enforced() {
400        assert!(TlsMode::Require.is_enforced());
401        assert!(TlsMode::VerifyCa.is_enforced());
402        assert!(TlsMode::VerifyFull.is_enforced());
403    }
404
405    // ── SourceConfig::redact_for_artifact ───────────────────────────────────
406
407    fn make_source(source_type: SourceType) -> SourceConfig {
408        SourceConfig {
409            source_type,
410            url: None,
411            url_env: None,
412            url_file: None,
413            host: None,
414            port: None,
415            user: None,
416            password: None,
417            password_env: None,
418            database: None,
419            environment: None,
420            tuning: None,
421            tls: None,
422        }
423    }
424
425    #[test]
426    fn redact_plaintext_password() {
427        let mut src = make_source(SourceType::Postgres);
428        src.password = Some("s3cr3t".into());
429        let (redacted, flag) = src.redact_for_artifact();
430        assert!(flag, "redaction should be flagged");
431        assert!(
432            redacted.password.is_none(),
433            "plaintext password must be stripped"
434        );
435    }
436
437    #[test]
438    fn redact_url_with_password() {
439        let mut src = make_source(SourceType::Postgres);
440        src.url = Some("postgresql://user:hunter2@db.example.com:5432/app".into());
441        let (redacted, flag) = src.redact_for_artifact();
442        assert!(flag, "URL redaction flagged");
443        let url = redacted.url.unwrap();
444        assert!(!url.contains("hunter2"), "password must not appear: {url}");
445        assert!(url.contains("REDACTED"), "placeholder must appear: {url}");
446        assert!(url.contains("@db.example.com"), "host retained: {url}");
447    }
448
449    #[test]
450    fn redact_url_without_at_sign_not_flagged() {
451        let mut src = make_source(SourceType::Postgres);
452        src.url = Some("postgresql://db.example.com:5432/app".into());
453        let (_, flag) = src.redact_for_artifact();
454        assert!(!flag, "URL with no userinfo must not be flagged");
455    }
456
457    #[test]
458    fn redact_url_with_user_but_no_password_is_flagged() {
459        let mut src = make_source(SourceType::Postgres);
460        src.url = Some("postgresql://user@db.example.com:5432/app".into());
461        let (redacted, flag) = src.redact_for_artifact();
462        assert!(flag, "bare user@ is still userinfo and gets redacted");
463        let url = redacted.url.unwrap();
464        assert!(url.contains("REDACTED"), "userinfo replaced: {url}");
465        assert!(!url.contains("user@"), "bare username removed: {url}");
466    }
467
468    #[test]
469    fn redact_env_var_reference_kept_intact() {
470        let mut src = make_source(SourceType::Mysql);
471        src.url_env = Some("DB_URL".into());
472        src.password_env = Some("DB_PASS".into());
473        let (redacted, flag) = src.redact_for_artifact();
474        assert!(!flag, "env var references are not secrets");
475        assert_eq!(redacted.url_env.as_deref(), Some("DB_URL"));
476        assert_eq!(redacted.password_env.as_deref(), Some("DB_PASS"));
477    }
478
479    #[test]
480    fn redact_mysql_url_with_password() {
481        let mut src = make_source(SourceType::Mysql);
482        src.url = Some("mysql://root:pass@127.0.0.1:3306/mydb".into());
483        let (redacted, flag) = src.redact_for_artifact();
484        assert!(flag);
485        let url = redacted.url.unwrap();
486        assert!(url.contains("REDACTED"), "{url}");
487        assert!(!url.contains("pass"), "{url}");
488    }
489
490    // ── SourceConfig::resolve_url (structured fields) ───────────────────────
491
492    #[test]
493    fn resolve_url_from_structured_fields_postgres() {
494        let mut src = make_source(SourceType::Postgres);
495        src.host = Some("pg.internal".into());
496        src.user = Some("alice".into());
497        src.database = Some("warehouse".into());
498        src.port = Some(5433);
499        let url = src.resolve_url().unwrap();
500        assert_eq!(url, "postgresql://alice@pg.internal:5433/warehouse");
501    }
502
503    #[test]
504    fn resolve_url_from_structured_fields_defaults_port() {
505        let mut src = make_source(SourceType::Mysql);
506        src.host = Some("my.internal".into());
507        src.user = Some("bob".into());
508        src.database = Some("orders".into());
509        let url = src.resolve_url().unwrap();
510        assert_eq!(url, "mysql://bob@my.internal:3306/orders");
511    }
512
513    #[test]
514    fn resolve_url_direct_url_passthrough() {
515        let mut src = make_source(SourceType::Postgres);
516        src.url = Some("postgresql://carol@pg.example.com:5432/db".into());
517        let url = src.resolve_url().unwrap();
518        assert_eq!(url, "postgresql://carol@pg.example.com:5432/db");
519    }
520
521    #[test]
522    fn resolve_url_rejects_mixed_url_and_structured() {
523        let mut src = make_source(SourceType::Postgres);
524        src.url = Some("postgresql://carol@pg.example.com/db".into());
525        src.host = Some("other".into());
526        let err = src.resolve_url().unwrap_err();
527        let msg = format!("{err:#}");
528        assert!(
529            msg.contains("URL-based") || msg.contains("structured"),
530            "{msg}"
531        );
532    }
533
534    #[test]
535    fn resolve_url_rejects_missing_host() {
536        let mut src = make_source(SourceType::Postgres);
537        src.user = Some("alice".into());
538        src.database = Some("warehouse".into());
539        let err = src.resolve_url().unwrap_err();
540        let msg = format!("{err:#}");
541        assert!(msg.contains("host"), "{msg}");
542    }
543
544    // ── find_userinfo ────────────────────────────────────────────────────────
545
546    #[test]
547    fn find_userinfo_detects_password_in_url() {
548        let url = "postgresql://user:pass@host/db";
549        let result = find_userinfo(url);
550        assert!(result.is_some(), "should detect user:pass@");
551    }
552
553    #[test]
554    fn find_userinfo_no_password_no_at_returns_none() {
555        assert!(find_userinfo("postgresql://host/db").is_none());
556    }
557
558    #[test]
559    fn find_userinfo_user_only_at_sign_matches() {
560        let url = "postgresql://user@host/db";
561        assert!(find_userinfo(url).is_some(), "bare user@ should match");
562    }
563
564    #[test]
565    fn find_userinfo_no_at_sign_returns_none() {
566        assert!(find_userinfo("postgresql://db.example.com:5432/app").is_none());
567    }
568}
rivet/config/source.rs

rivet/config/
source.rs
