Configuration

The box office is about to send emails: order confirmations, and later sign-in links. Staging must never email real fans, so the mail settings change with every deployment.

In Margaret, a setting lives in the constructor that needs it. There's no central configuration file to keep in sync.

Command line flags and environment variables

A singleton asks for a command line flag with #[console_argument], and for an environment variable with #[environment_variable]. The Mailer needs both:

#[singleton]
pub struct Mailer {
    api_url: Url,
    api_token: String,
    http: Client,
    sandbox: bool,
    sender: String,
}

impl Mailer {
    #[constructor]
    pub fn create(
        #[console_argument(from = "mail-api-url")] api_url: Url,
        #[console_argument(from = "mail-sender")] sender: String,
        #[console_argument(from = "mail-sandbox")] sandbox: bool,
        #[environment_variable(from = "MAIL_API_TOKEN")] api_token: String,
    ) -> anyhow::Result<Self> {
        Ok(Self {
            api_url,
            api_token,
            http: Client::new(),
            sandbox,
            sender,
        })
    }

    pub async fn send(&self, email: &Email) -> anyhow::Result<()> {
        if self.sandbox {
            println!("[sandbox] to {}: {}", email.to, email.subject);

            return Ok(());
        }

        self.http
            .post(self.api_url.clone())
            .bearer_auth(&self.api_token)
            .json(&json!({
                "from": self.sender,
                "to": email.to,
                "subject": email.subject,
                "text": email.body,
            }))
            .send()
            .await?
            .error_for_status()?;

        Ok(())
    }
}

The API URL and the sender are ordinary settings, so they're flags. The token is a secret, so it comes from the environment. A bool becomes a flag without a value: on staging, --mail-sandbox prints emails instead of sending them.

Client and Url come from margaret::framework::reqwest, the HTTP client Margaret ships with.

Using the mailer

Nothing sends email yet, and Margaret refuses to build a singleton that nothing uses. A small command lets the staff check the mail settings of a fresh deployment:

#[singleton]
#[console_command(
    name = "send-test-email",
    description = "Sends a test email to check the mail settings"
)]
pub struct SendTestEmail {
    mailer: Arc<Mailer>,
    recipient: String,
}

impl SendTestEmail {
    #[constructor]
    pub fn create(
        mailer: Arc<Mailer>,
        #[console_argument(positional)] recipient: String,
    ) -> anyhow::Result<Self> {
        Ok(Self { mailer, recipient })
    }

    #[process]
    pub async fn run(&self) -> anyhow::Result<CommandOutcome> {
        self.mailer
            .send(&Email {
                to: self.recipient.clone(),
                subject: "Box office test email".to_string(),
                body: "If you can read this, the mail settings work.".to_string(),
            })
            .await?;

        Ok(CommandOutcome::Succeeded)
    }
}

#[console_argument(positional)] takes the recipient without a flag name. The help text is generated:

$ box_office send-test-email --help
Sends a test email to check the mail settings

Usage: box_office send-test-email [OPTIONS] --mail-api-url <mail-api-url> --mail-sender <mail-sender> <recipient>

Arguments:
  <recipient>

Options:
      --mail-api-url <mail-api-url>
      --mail-sender <mail-sender>
      --mail-sandbox
  -h, --help                         Print help

The from value becomes the flag's name, exactly as written. Values are parsed into their Rust types, like Url, before any constructor runs, and an Option makes a setting optional:

$ box_office send-test-email staff@example.com --mail-api-url not-a-url --mail-sender tickets@example.com
error: invalid value 'not-a-url' for '--mail-api-url <mail-api-url>': relative URL without a base

A missing environment variable stops the command before it starts:

$ box_office send-test-email staff@example.com --mail-api-url https://mail.example.com/send --mail-sender tickets@example.com
the environment variable 'MAIL_API_TOKEN' is not set

Which commands accept a setting

A setting belongs to the singletons that ask for it, so it appears only on the commands that need them. send-test-email reaches the Mailer, so it accepts the mail flags. lineup doesn't, so it doesn't ask for them.

serve accepts a setting once something it serves reaches the singleton. Right now, nothing served sends email, so serve doesn't ask for the mail settings yet. That changes in Background services, where the box office starts sending confirmations.