hecks 3.14.0 → 4.0.0

data/rust/host/src/resend.rs

@@ -1,5 +1,5 @@
-//! Sends one newsletter email through Resend's REST API. The Ruby adapter answers the
-//! same `deliver` question, so the send loop never knows which provider is live.
+//! Sends one newsletter email through Resend's REST API. The Rust host is the only
+//! implementation of this `deliver` answer; there is no Ruby adapter or mock beside it.
 
 use serde_json::{json, Value};
 use std::time::Duration;
@@ -10,7 +10,7 @@ const MAX_ATTEMPTS: u32 = 4;
 const DEFAULT_RETRY_SECS: u64 = 1;
 const MAX_RETRY_SECS: u64 = 5;
 /// The address the mock refuses, and (in `mock_deliver`) the reason it gives. Adapter-side test
-/// vocabulary: the domain names neither, and the Ruby mock keeps its own copy (ADR 0099).
+/// vocabulary: the domain names neither (ADR 0099).
 const MOCK_BOUNCE_ADDRESS: &str = "bounce@example.com";
 
 /// One email to one recipient.
@@ -26,7 +26,7 @@ pub struct Email<'a> {
 
 /// What handing an email to the provider came to. A refusal or outage for one
 /// recipient is `ok: false` with a reason (never an `Err`), so a fan-out can carry on.
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Eq)]
 pub struct Delivery {
     pub ok: bool,
     pub message_id: Option<String>,
@@ -34,31 +34,49 @@ pub struct Delivery {
 }
 
 impl Delivery {
-    fn sent(message_id: String) -> Self {
-        Delivery { ok: true, message_id: Some(message_id), reason: None }
+    const fn sent(message_id: String) -> Self {
+        Self {
+            ok: true,
+            message_id: Some(message_id),
+            reason: None,
+        }
     }
 
     fn failed(reason: impl Into<String>) -> Self {
-        Delivery { ok: false, message_id: None, reason: Some(reason.into()) }
+        Self {
+            ok: false,
+            message_id: None,
+            reason: Some(reason.into()),
+        }
     }
 }
 
 /// How email leaves the host: really, through Resend, or logged and dropped.
 pub enum Mailer {
-    Live { http: reqwest::Client, api_key: String, from: String, reply_to: Option<String>, base_url: String },
+    Live {
+        http: reqwest::Client,
+        api_key: String,
+        from: String,
+        reply_to: Option<String>,
+        base_url: String,
+    },
     Mock,
 }
 
 impl Mailer {
     /// `Ok(None)` when nothing is configured; `Err` when a key is set without `RESEND_FROM` —
     /// marking an issue sent is irreversible, so a missing key must refuse before that happens.
-    pub fn from_env() -> Result<Option<Mailer>, String> {
-        let var = |name: &str| std::env::var(name).unwrap_or_default();
-        Self::configured(&var("RESEND_API_KEY"), &var("RESEND_FROM"), &var("RESEND_MOCK"))
-            .map(|mailer| mailer.map(|mailer| mailer.replying_to(&var("RESEND_REPLY_TO"))))
+    pub fn from_env() -> Result<Option<Self>, String> {
+        let var = |name: &str| crate::secrets::var(name).unwrap_or_default();
+        Self::configured(
+            &var("RESEND_API_KEY"),
+            &var("RESEND_FROM"),
+            &var("RESEND_MOCK"),
+        )
+        .map(|mailer| mailer.map(|mailer| mailer.replying_to(&var("RESEND_REPLY_TO"))))
     }
 
-    fn configured(api_key: &str, from: &str, mock: &str) -> Result<Option<Mailer>, String> {
+    fn configured(api_key: &str, from: &str, mock: &str) -> Result<Option<Self>, String> {
         if !api_key.is_empty() {
             if from.is_empty() {
                 return Err("RESEND_API_KEY is set but RESEND_FROM is not — Resend needs a from address on a verified domain".to_string());
@@ -66,36 +84,64 @@ impl Mailer {
             return Ok(Some(Self::live(api_key, from, API_BASE)));
         }
         // Mock requires an explicit opt-in, unlike checkout's mock-by-default.
-        Ok((mock == "1").then_some(Mailer::Mock))
+        Ok((mock == "1").then_some(Self::Mock))
     }
 
     /// A mailer that posts to `base_url` (Resend's API, or a stand-in in tests).
-    pub fn live(api_key: &str, from: &str, base_url: &str) -> Mailer {
-        let http = reqwest::Client::builder().timeout(TIMEOUT).build().expect("a reqwest client with a timeout always builds");
-        Mailer::Live { http, api_key: api_key.to_string(), from: from.to_string(), reply_to: None, base_url: base_url.to_string() }
+    #[allow(clippy::expect_used)] // reason: startup config; a client with only a timeout set always builds
+    pub fn live(api_key: &str, from: &str, base_url: &str) -> Self {
+        let http = reqwest::Client::builder()
+            .timeout(TIMEOUT)
+            .build()
+            .expect("a reqwest client with a timeout always builds");
+        Self::Live {
+            http,
+            api_key: api_key.to_string(),
+            from: from.to_string(),
+            reply_to: None,
+            base_url: base_url.to_string(),
+        }
     }
 
     /// Sets where replies go (`Reply-To`), when the address people reply to is not the one the mail
     /// is sent from. Blank leaves replies going to the From address. A mock mailer has no replies.
-    pub fn replying_to(self, reply_to: &str) -> Mailer {
+    pub fn replying_to(self, reply_to: &str) -> Self {
         match self {
-            Mailer::Live { http, api_key, from, base_url, .. } => {
+            Self::Live {
+                http,
+                api_key,
+                from,
+                base_url,
+                ..
+            } => {
                 let reply_to = (!reply_to.trim().is_empty()).then(|| reply_to.trim().to_string());
-                Mailer::Live { http, api_key, from, reply_to, base_url }
+                Self::Live {
+                    http,
+                    api_key,
+                    from,
+                    reply_to,
+                    base_url,
+                }
             }
-            mock => mock,
+            mock @ Self::Mock => mock,
         }
     }
 
     #[cfg(test)]
-    pub fn is_mock(&self) -> bool {
-        matches!(self, Mailer::Mock)
+    pub const fn is_mock(&self) -> bool {
+        matches!(self, Self::Mock)
     }
 
     pub async fn deliver(&self, email: &Email<'_>) -> Delivery {
         match self {
-            Mailer::Mock => mock_deliver(email),
-            Mailer::Live { http, api_key, from, reply_to, base_url } => live_deliver(http, api_key, from, reply_to.as_deref(), base_url, email).await,
+            Self::Mock => mock_deliver(email),
+            Self::Live {
+                http,
+                api_key,
+                from,
+                reply_to,
+                base_url,
+            } => live_deliver(http, api_key, from, reply_to.as_deref(), base_url, email).await,
         }
     }
 }
@@ -104,7 +150,10 @@ fn mock_deliver(email: &Email<'_>) -> Delivery {
     if email.to == MOCK_BOUNCE_ADDRESS {
         return Delivery::failed("bounced");
     }
-    println!("[mock resend] to={} subject={:?}\n{}", email.to, email.subject, email.body);
+    println!(
+        "[mock resend] to={} subject={:?}\n{}",
+        email.to, email.subject, email.body
+    );
     Delivery::sent(format!("re_{}", uuid::Uuid::new_v4().simple()))
 }
 
@@ -113,7 +162,11 @@ fn payload(from: &str, reply_to: Option<&str>, email: &Email<'_>) -> Value {
     if let Some(reply_to) = reply_to {
         payload["reply_to"] = json!(reply_to);
     }
-    let content_key = if email.body.trim_start().starts_with('<') { "html" } else { "text" };
+    let content_key = if email.body.trim_start().starts_with('<') {
+        "html"
+    } else {
+        "text"
+    };
     payload[content_key] = json!(email.body);
     if let Some(url) = email.unsubscribe_url {
         payload["headers"] = json!({ "List-Unsubscribe": format!("<{url}>") });
@@ -131,10 +184,23 @@ fn retry_delay(response: &reqwest::Response) -> Duration {
     Duration::from_secs(secs.min(MAX_RETRY_SECS))
 }
 
-async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, reply_to: Option<&str>, base_url: &str, email: &Email<'_>) -> Delivery {
+async fn live_deliver(
+    http: &reqwest::Client,
+    api_key: &str,
+    from: &str,
+    reply_to: Option<&str>,
+    base_url: &str,
+    email: &Email<'_>,
+) -> Delivery {
     let body = payload(from, reply_to, email);
     for attempt in 1..=MAX_ATTEMPTS {
-        let response = match http.post(format!("{base_url}/emails")).bearer_auth(api_key).json(&body).send().await {
+        let response = match http
+            .post(format!("{base_url}/emails"))
+            .bearer_auth(api_key)
+            .json(&body)
+            .send()
+            .await
+        {
             Ok(r) => r,
             Err(e) => return Delivery::failed(format!("resend unreachable: {}", e.without_url())),
         };
@@ -145,12 +211,15 @@ async fn live_deliver(http: &reqwest::Client, api_key: &str, from: &str, reply_t
         }
         let answer: Value = response.json().await.unwrap_or(Value::Null);
         if status.is_success() {
-            return match answer.get("id").and_then(|v| v.as_str()) {
-                Some(id) => Delivery::sent(id.to_string()),
-                None => Delivery::failed("resend accepted the email but returned no id"),
-            };
+            return answer.get("id").and_then(|v| v.as_str()).map_or_else(
+                || Delivery::failed("resend accepted the email but returned no id"),
+                |id| Delivery::sent(id.to_string()),
+            );
         }
-        let message = answer.get("message").and_then(|v| v.as_str()).map(String::from);
+        let message = answer
+            .get("message")
+            .and_then(|v| v.as_str())
+            .map(String::from);
         return Delivery::failed(message.unwrap_or_else(|| format!("resend answered {status}")));
     }
     Delivery::failed("resend kept rate limiting this email")
@@ -185,7 +254,7 @@ mod tests {
                     stream.write_all(response.as_bytes()).unwrap();
                 }
             });
-            FakeResend { base, requests }
+            Self { base, requests }
         }
 
         fn requests(&self) -> Vec<String> {
@@ -203,7 +272,11 @@ mod tests {
             if let Some((head, body)) = text.split_once("\r\n\r\n") {
                 let length = head
                     .lines()
-                    .find_map(|l| l.to_lowercase().strip_prefix("content-length:").and_then(|v| v.trim().parse::<usize>().ok()))
+                    .find_map(|l| {
+                        l.to_lowercase()
+                            .strip_prefix("content-length:")
+                            .and_then(|v| v.trim().parse::<usize>().ok())
+                    })
                     .unwrap_or(0);
                 if body.len() >= length {
                     return text;
@@ -216,7 +289,14 @@ mod tests {
     }
 
     fn email<'a>(to: &'a str, body: &'a str) -> Email<'a> {
-        Email { to, subject: "Spring news", body, unsubscribe_url: Some("https://example.com/newsletter-unsubscribed.html?email=a%40b.com") }
+        Email {
+            to,
+            subject: "Spring news",
+            body,
+            unsubscribe_url: Some(
+                "https://example.com/newsletter-unsubscribed.html?email=a%40b.com",
+            ),
+        }
     }
 
     #[test]
@@ -231,7 +311,9 @@ mod tests {
 
     #[test]
     fn a_key_and_from_is_live_even_when_mock_is_also_set() {
-        let mailer = Mailer::configured("re_x", "News <n@mail.example.com>", "1").unwrap().unwrap();
+        let mailer = Mailer::configured("re_x", "News <n@mail.example.com>", "1")
+            .unwrap()
+            .unwrap();
         assert!(!mailer.is_mock());
     }
 
@@ -243,7 +325,9 @@ mod tests {
 
     #[test]
     fn an_html_body_goes_as_html_and_a_plain_one_as_text() {
-        assert!(payload("f", None, &email("a@b.com", "  <p>hi</p>")).get("html").is_some());
+        assert!(payload("f", None, &email("a@b.com", "  <p>hi</p>"))
+            .get("html")
+            .is_some());
         let plain = payload("f", None, &email("a@b.com", "just a link"));
         assert!(plain.get("text").is_some() && plain.get("html").is_none());
     }
@@ -251,8 +335,20 @@ mod tests {
     #[test]
     fn the_unsubscribe_url_rides_as_a_list_unsubscribe_header() {
         let with = payload("f", None, &email("a@b.com", "x"));
-        assert_eq!(with["headers"]["List-Unsubscribe"], "<https://example.com/newsletter-unsubscribed.html?email=a%40b.com>");
-        let without = payload("f", None, &Email { to: "a@b.com", subject: "s", body: "x", unsubscribe_url: None });
+        assert_eq!(
+            with["headers"]["List-Unsubscribe"],
+            "<https://example.com/newsletter-unsubscribed.html?email=a%40b.com>"
+        );
+        let without = payload(
+            "f",
+            None,
+            &Email {
+                to: "a@b.com",
+                subject: "s",
+                body: "x",
+                unsubscribe_url: None,
+            },
+        );
         assert!(without.get("headers").is_none());
     }
 
@@ -260,33 +356,47 @@ mod tests {
     fn a_reply_to_address_rides_in_the_payload_and_is_absent_without_one() {
         let with = payload("f", Some("replies@example.com"), &email("a@b.com", "x"));
         assert_eq!(with["reply_to"], "replies@example.com");
-        assert!(payload("f", None, &email("a@b.com", "x")).get("reply_to").is_none());
+        assert!(payload("f", None, &email("a@b.com", "x"))
+            .get("reply_to")
+            .is_none());
     }
 
     #[test]
     fn replying_to_trims_the_address_and_a_blank_one_sets_none() {
-        let set = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("  me@example.com ");
+        let set =
+            Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("  me@example.com ");
         assert!(matches!(&set, Mailer::Live { reply_to: Some(r), .. } if r == "me@example.com"));
         let blank = Mailer::live("re_x", "n@mail.example.com", "http://x").replying_to("   ");
         assert!(matches!(&blank, Mailer::Live { reply_to: None, .. }));
-        assert!(Mailer::Mock.replying_to("me@example.com").is_mock(), "a mock mailer has no replies");
+        assert!(
+            Mailer::Mock.replying_to("me@example.com").is_mock(),
+            "a mock mailer has no replies"
+        );
     }
 
     #[tokio::test]
     async fn a_live_send_carries_the_reply_to_address_to_resend() {
         let fake = FakeResend::start(vec![("200 OK", "", r#"{"id":"em_9"}"#)]);
-        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base).replying_to("replies@example.com");
+        let mailer = Mailer::live("re_x", "News <n@mail.example.com>", &fake.base)
+            .replying_to("replies@example.com");
 
         mailer.deliver(&email("a@b.com", "x")).await;
 
-        assert!(fake.requests()[0].contains(r#""reply_to":"replies@example.com""#), "{}", fake.requests()[0]);
+        assert!(
+            fake.requests()[0].contains(r#""reply_to":"replies@example.com""#),
+            "{}",
+            fake.requests()[0]
+        );
     }
 
     #[test]
     fn the_mock_logs_instead_of_sending_and_bounces_the_test_address() {
         let sent = mock_deliver(&email("a@b.com", "x"));
         assert!(sent.ok && sent.message_id.unwrap().starts_with("re_"));
-        assert_eq!(mock_deliver(&email(MOCK_BOUNCE_ADDRESS, "x")), Delivery::failed("bounced"));
+        assert_eq!(
+            mock_deliver(&email(MOCK_BOUNCE_ADDRESS, "x")),
+            Delivery::failed("bounced")
+        );
     }
 
     #[tokio::test]
@@ -301,26 +411,49 @@ mod tests {
         assert_eq!(requests.len(), 1);
         let request = requests[0].to_lowercase();
         assert!(request.starts_with("post /emails "), "{request}");
-        assert!(request.contains("authorization: bearer re_secret"), "{request}");
-        assert!(requests[0].contains(r#""to":["a@b.com"]"#) && requests[0].contains(r#""from":"News <n@mail.example.com>""#), "{}", requests[0]);
+        assert!(
+            request.contains("authorization: bearer re_secret"),
+            "{request}"
+        );
+        assert!(
+            requests[0].contains(r#""to":["a@b.com"]"#)
+                && requests[0].contains(r#""from":"News <n@mail.example.com>""#),
+            "{}",
+            requests[0]
+        );
     }
 
     #[tokio::test]
     async fn a_refusal_from_resend_is_a_failed_delivery_carrying_its_message() {
-        let fake = FakeResend::start(vec![("403 Forbidden", "", r#"{"message":"The mail.example.com domain is not verified.","name":"validation_error"}"#)]);
-        let delivery = Mailer::live("re_x", "n@mail.example.com", &fake.base).deliver(&email("a@b.com", "x")).await;
+        let fake = FakeResend::start(vec![(
+            "403 Forbidden",
+            "",
+            r#"{"message":"The mail.example.com domain is not verified.","name":"validation_error"}"#,
+        )]);
+        let delivery = Mailer::live("re_x", "n@mail.example.com", &fake.base)
+            .deliver(&email("a@b.com", "x"))
+            .await;
 
         assert!(!delivery.ok);
-        assert_eq!(delivery.reason.as_deref(), Some("The mail.example.com domain is not verified."));
+        assert_eq!(
+            delivery.reason.as_deref(),
+            Some("The mail.example.com domain is not verified.")
+        );
     }
 
     #[tokio::test]
     async fn a_rate_limited_send_waits_and_is_retried() {
         let fake = FakeResend::start(vec![
-            ("429 Too Many Requests", "retry-after: 0\r\n", r#"{"message":"Too many requests"}"#),
+            (
+                "429 Too Many Requests",
+                "retry-after: 0\r\n",
+                r#"{"message":"Too many requests"}"#,
+            ),
             ("200 OK", "", r#"{"id":"em_after_retry"}"#),
         ]);
-        let delivery = Mailer::live("re_x", "n@mail.example.com", &fake.base).deliver(&email("a@b.com", "x")).await;
+        let delivery = Mailer::live("re_x", "n@mail.example.com", &fake.base)
+            .deliver(&email("a@b.com", "x"))
+            .await;
 
         assert_eq!(delivery, Delivery::sent("em_after_retry".to_string()));
         assert_eq!(fake.requests().len(), 2);
@@ -332,7 +465,9 @@ mod tests {
         let base = format!("http://{}", unused.local_addr().unwrap());
         drop(unused);
 
-        let delivery = Mailer::live("re_x", "n@mail.example.com", &base).deliver(&email("a@b.com", "x")).await;
+        let delivery = Mailer::live("re_x", "n@mail.example.com", &base)
+            .deliver(&email("a@b.com", "x"))
+            .await;
 
         assert!(!delivery.ok);
         assert!(delivery.reason.unwrap().starts_with("resend unreachable"));

data/rust/host/src/secrets.rs

@@ -1,6 +1,36 @@
 //! Fetches secrets from Secrets Manager at runtime, not via CloudFormation dynamic references.
 //! A resolved reference lands decrypted in function configuration, readable account-wide.
 
+use std::collections::HashMap;
+use std::sync::{OnceLock, RwLock};
+
+// Secrets fetched at boot live here instead of in the process environment: `std::env::set_var` is
+// unsound once tokio's worker and blocking threads exist, since any of them may read the
+// environment (a DNS lookup does) at the same moment.
+static FETCHED: OnceLock<RwLock<HashMap<&'static str, String>>> = OnceLock::new();
+
+fn fetched() -> &'static RwLock<HashMap<&'static str, String>> {
+    FETCHED.get_or_init(RwLock::default)
+}
+
+/// Records a secret fetched at boot under the environment variable name it stands in for.
+pub fn provide(name: &'static str, value: String) {
+    fetched()
+        .write()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+        .insert(name, value);
+}
+
+/// The value of `name`: a secret fetched at boot when there is one, else the process environment.
+pub fn var(name: &str) -> Result<String, std::env::VarError> {
+    let provided = fetched()
+        .read()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+        .get(name)
+        .cloned();
+    provided.map_or_else(|| std::env::var(name), Ok)
+}
+
 pub struct AwsSecretFetcher {
     client: aws_sdk_secretsmanager::Client,
 }
@@ -10,10 +40,17 @@ impl AwsSecretFetcher {
     // default features would wire in aws-lc-rs instead (see Cargo.toml).
     pub async fn from_env() -> Self {
         let http_client = aws_smithy_http_client::Builder::new()
-            .tls_provider(aws_smithy_http_client::tls::Provider::Rustls(aws_smithy_http_client::tls::rustls_provider::CryptoMode::Ring))
+            .tls_provider(aws_smithy_http_client::tls::Provider::Rustls(
+                aws_smithy_http_client::tls::rustls_provider::CryptoMode::Ring,
+            ))
             .build_https();
-        let config = aws_config::defaults(aws_config::BehaviorVersion::latest()).http_client(http_client).load().await;
-        Self { client: aws_sdk_secretsmanager::Client::new(&config) }
+        let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
+            .http_client(http_client)
+            .load()
+            .await;
+        Self {
+            client: aws_sdk_secretsmanager::Client::new(&config),
+        }
     }
 
     /// The secret's whole `SecretString`, undecoded. `secret_id` is a full ARN or a name.
@@ -27,17 +64,31 @@ impl AwsSecretFetcher {
             .map_err(|e| anyhow::anyhow!("fetching secret {secret_id}: {e:?}"))?;
         response
             .secret_string()
-            .map(|s| s.to_string())
+            .map(std::string::ToString::to_string)
             .ok_or_else(|| anyhow::anyhow!("secret {secret_id} has no SecretString"))
     }
 
     /// Like `fetch_secret_string`, but a secret that does not exist yet is
     /// `None`, not an error: the payment keys' secret is only created by the
     /// first save.
-    pub async fn fetch_secret_string_if_present(&self, secret_id: &str) -> anyhow::Result<Option<String>> {
-        match self.client.get_secret_value().secret_id(secret_id).send().await {
-            Ok(response) => Ok(response.secret_string().map(|s| s.to_string())),
-            Err(e) if e.as_service_error().is_some_and(|service| service.is_resource_not_found_exception()) => Ok(None),
+    pub async fn fetch_secret_string_if_present(
+        &self,
+        secret_id: &str,
+    ) -> anyhow::Result<Option<String>> {
+        match self
+            .client
+            .get_secret_value()
+            .secret_id(secret_id)
+            .send()
+            .await
+        {
+            Ok(response) => Ok(response.secret_string().map(std::string::ToString::to_string)),
+            Err(e)
+                if e.as_service_error()
+                    .is_some_and(aws_sdk_secretsmanager::operation::get_secret_value::GetSecretValueError::is_resource_not_found_exception) =>
+            {
+                Ok(None)
+            }
             Err(_) => Err(anyhow::anyhow!("reading secret {secret_id} failed")),
         }
     }
@@ -45,9 +96,19 @@ impl AwsSecretFetcher {
     /// Replaces the secret's `SecretString`, creating the secret the first time.
     /// The errors name the secret and never carry the value.
     pub async fn put_secret_string(&self, secret_id: &str, value: &str) -> anyhow::Result<()> {
-        match self.client.put_secret_value().secret_id(secret_id).secret_string(value).send().await {
+        match self
+            .client
+            .put_secret_value()
+            .secret_id(secret_id)
+            .secret_string(value)
+            .send()
+            .await
+        {
             Ok(_) => Ok(()),
-            Err(e) if e.as_service_error().is_some_and(|service| service.is_resource_not_found_exception()) => {
+            Err(e)
+                if e.as_service_error()
+                    .is_some_and(aws_sdk_secretsmanager::operation::put_secret_value::PutSecretValueError::is_resource_not_found_exception) =>
+            {
                 self.client
                     .create_secret()
                     .name(secret_id)
@@ -66,19 +127,21 @@ impl AwsSecretFetcher {
 ///
 /// Pure, so it is tested without a client.
 pub fn extract_field(secret_json: &str, field: &str) -> Result<String, String> {
-    let value: serde_json::Value =
-        serde_json::from_str(secret_json).map_err(|e| format!("secret's SecretString isn't valid JSON: {e}"))?;
+    let value: serde_json::Value = serde_json::from_str(secret_json)
+        .map_err(|e| format!("secret's SecretString isn't valid JSON: {e}"))?;
     value
         .get(field)
         .and_then(|p| p.as_str())
-        .map(|s| s.to_string())
+        .map(std::string::ToString::to_string)
         .ok_or_else(|| format!("secret's SecretString has no string {field:?} field"))
 }
 
 /// One named string field out of a secret's JSON `SecretString`, or `None` when the secret does not
 /// carry it (or is not JSON, or the field is blank). For a field a secret may have and may not.
 pub fn optional_field(secret_json: &str, field: &str) -> Option<String> {
-    extract_field(secret_json, field).ok().filter(|value| !value.trim().is_empty())
+    extract_field(secret_json, field)
+        .ok()
+        .filter(|value| !value.trim().is_empty())
 }
 
 /// The `postgres://` URL for a database secret.
@@ -93,9 +156,16 @@ pub fn database_url(secret_json: &str, host: &str, database: &str) -> Result<Str
     let user = extract_field(secret_json, "username").unwrap_or_else(|_| "postgres".to_string());
     let port = serde_json::from_str::<serde_json::Value>(secret_json)
         .ok()
-        .and_then(|v| v.get("port").and_then(|p| p.as_u64().or_else(|| p.as_str().and_then(|s| s.parse().ok()))))
+        .and_then(|v| {
+            v.get("port").and_then(|p| {
+                p.as_u64()
+                    .or_else(|| p.as_str().and_then(|s| s.parse().ok()))
+            })
+        })
         .unwrap_or(5432);
-    Ok(format!("postgres://{user}:{password}@{host}:{port}/{database}"))
+    Ok(format!(
+        "postgres://{user}:{password}@{host}:{port}/{database}"
+    ))
 }
 
 #[cfg(test)]
@@ -105,7 +175,10 @@ mod tests {
     #[test]
     fn an_optional_field_is_read_when_present_and_none_when_absent_blank_or_not_json() {
         let json = r#"{"api_key":"re_1","webhook_secret":"whsec_abc","blank":"  "}"#;
-        assert_eq!(optional_field(json, "webhook_secret").as_deref(), Some("whsec_abc"));
+        assert_eq!(
+            optional_field(json, "webhook_secret").as_deref(),
+            Some("whsec_abc")
+        );
         assert_eq!(optional_field(json, "missing"), None);
         assert_eq!(optional_field(json, "blank"), None);
         assert_eq!(optional_field("not json", "webhook_secret"), None);
@@ -114,23 +187,35 @@ mod tests {
     #[test]
     fn a_master_secret_logs_in_as_postgres_on_the_default_port() {
         let json = r#"{"username":"postgres","password":"abc123"}"#;
-        assert_eq!(database_url(json, "db.example", "app").unwrap(), "postgres://postgres:abc123@db.example:5432/app");
+        assert_eq!(
+            database_url(json, "db.example", "app").unwrap(),
+            "postgres://postgres:abc123@db.example:5432/app"
+        );
     }
 
     #[test]
     fn a_clients_own_secret_logs_in_as_its_role() {
         let json = r#"{"username":"acme","password":"s3cr3t","host":"db.example","port":5433,"dbname":"acme"}"#;
-        assert_eq!(database_url(json, "db.example", "acme").unwrap(), "postgres://acme:s3cr3t@db.example:5433/acme");
+        assert_eq!(
+            database_url(json, "db.example", "acme").unwrap(),
+            "postgres://acme:s3cr3t@db.example:5433/acme"
+        );
     }
 
     #[test]
     fn a_secret_with_no_username_is_read_as_postgres() {
-        assert_eq!(database_url(r#"{"password":"pw"}"#, "h", "d").unwrap(), "postgres://postgres:pw@h:5432/d");
+        assert_eq!(
+            database_url(r#"{"password":"pw"}"#, "h", "d").unwrap(),
+            "postgres://postgres:pw@h:5432/d"
+        );
     }
 
     #[test]
     fn a_port_written_as_text_is_read() {
-        assert_eq!(database_url(r#"{"password":"pw","port":"6000"}"#, "h", "d").unwrap(), "postgres://postgres:pw@h:6000/d");
+        assert_eq!(
+            database_url(r#"{"password":"pw","port":"6000"}"#, "h", "d").unwrap(),
+            "postgres://postgres:pw@h:6000/d"
+        );
     }
 
     #[test]
@@ -162,4 +247,14 @@ mod tests {
     fn refuses_invalid_json() {
         assert!(extract_field("not json", "password").is_err());
     }
+
+    #[test]
+    fn a_provided_secret_is_read_back_and_an_unprovided_one_falls_back_to_the_environment() {
+        provide("HECKS_SECRETS_SPEC_PROVIDED", "from-boot".to_string());
+        assert_eq!(
+            var("HECKS_SECRETS_SPEC_PROVIDED").as_deref(),
+            Ok("from-boot")
+        );
+        assert!(var("HECKS_SECRETS_SPEC_NEVER_SET").is_err());
+    }
 }