Skip to main content

shared/extensions/email_templates/
variables.rs

1use super::EmailTemplateManager;
2use crate::prelude::*;
3use garde::Validate;
4use indexmap::IndexMap;
5use serde::{Deserialize, Serialize};
6use sqlx::Row;
7use std::collections::BTreeMap;
8use utoipa::ToSchema;
9
10const VARIABLES_DIR: include_dir::Dir<'_> =
11    include_dir::include_dir!("$CARGO_MANIFEST_DIR/mails/variables");
12
13pub fn validate_variable_name(
14    name: &compact_str::CompactString,
15    _context: &(),
16) -> Result<(), garde::Error> {
17    let mut chars = name.chars();
18
19    let valid = matches!(chars.next(), Some('a'..='z'))
20        && chars.all(|c| matches!(c, 'a'..='z' | '0'..='9' | '_'))
21        && name.len() <= 64;
22
23    if !valid {
24        return Err(garde::Error::new(
25            "variable name must start with a lowercase letter and only contain lowercase letters, digits and underscores (max 64 characters)",
26        ));
27    }
28
29    Ok(())
30}
31
32pub fn validate_variable_translations(
33    translations: &BTreeMap<compact_str::CompactString, String>,
34    _context: &(),
35) -> Result<(), garde::Error> {
36    for (language, value) in translations {
37        crate::utils::validate_language(language, &())?;
38
39        if value.is_empty() || value.len() > 8192 {
40            return Err(garde::Error::new(format!(
41                "translation for language '{language}' must be between 1 and 8192 characters"
42            )));
43        }
44    }
45
46    Ok(())
47}
48
49#[derive(Clone)]
50pub struct EmailVariable {
51    pub template_identifier: Option<compact_str::CompactString>,
52    pub name: compact_str::CompactString,
53    pub default_value: String,
54    pub default_translations: BTreeMap<compact_str::CompactString, String>,
55}
56
57impl EmailVariable {
58    pub(super) fn matches(&self, template_identifier: Option<&str>, name: &str) -> bool {
59        self.template_identifier.as_deref() == template_identifier && self.name == name
60    }
61}
62
63#[derive(ToSchema, Validate, Deserialize)]
64pub struct CreateEmailVariable {
65    #[garde(custom(validate_variable_name))]
66    #[schema(pattern = "^[a-z][a-z0-9_]{0,63}$", max_length = 64)]
67    pub name: compact_str::CompactString,
68    #[garde(length(chars, min = 1, max = 8192))]
69    #[schema(min_length = 1, max_length = 8192)]
70    pub value: String,
71    #[garde(custom(validate_variable_translations))]
72    #[serde(default)]
73    pub value_translations: BTreeMap<compact_str::CompactString, String>,
74}
75
76#[derive(ToSchema, Validate, Deserialize)]
77pub struct UpdateEmailVariable {
78    #[garde(length(chars, min = 1, max = 8192))]
79    #[schema(min_length = 1, max_length = 8192)]
80    #[serde(default, with = "::serde_with::rust::double_option")]
81    pub value: Option<Option<String>>,
82    #[garde(inner(custom(validate_variable_translations)))]
83    pub value_translations: Option<BTreeMap<compact_str::CompactString, String>>,
84}
85
86#[derive(Serialize, Deserialize)]
87struct EmailVariableRow {
88    name: compact_str::CompactString,
89    value: Option<String>,
90    value_translations: BTreeMap<compact_str::CompactString, String>,
91}
92
93pub struct FetchedEmailVariable {
94    pub template_identifier: Option<compact_str::CompactString>,
95    pub name: compact_str::CompactString,
96    pub default_value: Option<String>,
97    pub default_translations: BTreeMap<compact_str::CompactString, String>,
98    pub value: Option<String>,
99    pub value_translations: BTreeMap<compact_str::CompactString, String>,
100}
101
102#[schema_extension_derive::extendible]
103#[init_args(FetchedEmailVariable, crate::State)]
104#[hook_args(crate::State)]
105#[derive(ToSchema, Serialize)]
106#[schema(title = "EmailVariable")]
107pub struct AdminApiEmailVariable {
108    pub template_identifier: Option<compact_str::CompactString>,
109    pub name: compact_str::CompactString,
110    pub system: bool,
111    pub default_value: Option<String>,
112    pub default_translations: BTreeMap<compact_str::CompactString, String>,
113    pub value: Option<String>,
114    pub value_translations: BTreeMap<compact_str::CompactString, String>,
115}
116
117impl FetchedEmailVariable {
118    pub fn is_system(&self) -> bool {
119        self.default_value.is_some()
120    }
121
122    pub fn resolve(&self, language: &str) -> &str {
123        self.value_translations
124            .get(language)
125            .map(String::as_str)
126            .or(self.value.as_deref())
127            .or_else(|| self.default_translations.get(language).map(String::as_str))
128            .or(self.default_value.as_deref())
129            .unwrap_or_default()
130    }
131}
132
133#[async_trait::async_trait]
134impl IntoAdminApiObject for FetchedEmailVariable {
135    type AdminApiObject = AdminApiEmailVariable;
136    type ExtraArgs<'a> = ();
137
138    async fn into_admin_api_object<'a>(
139        self,
140        state: &crate::State,
141        _args: Self::ExtraArgs<'a>,
142    ) -> Result<Self::AdminApiObject, crate::database::DatabaseError> {
143        let api_object = AdminApiEmailVariable::init_hooks(&self, state).await?;
144        let system = self.is_system();
145
146        let api_object = finish_extendible!(
147            AdminApiEmailVariable {
148                template_identifier: self.template_identifier,
149                name: self.name,
150                system,
151                default_value: self.default_value,
152                default_translations: self.default_translations,
153                value: self.value,
154                value_translations: self.value_translations,
155            },
156            api_object,
157            state
158        )?;
159
160        Ok(api_object)
161    }
162}
163
164type VariablesFile =
165    IndexMap<compact_str::CompactString, IndexMap<compact_str::CompactString, String>>;
166
167pub(super) fn load_variables(directory: &include_dir::Dir<'_>, variables: &mut Vec<EmailVariable>) {
168    let mut files: Vec<_> = directory.files().collect();
169    files.sort_by_key(|file| file.path().file_stem() != Some(std::ffi::OsStr::new("en")));
170
171    for file in files {
172        let Some(language) = file.path().file_stem().and_then(|s| s.to_str()) else {
173            continue;
174        };
175
176        let entries: VariablesFile = match serde_json::from_slice(file.contents()) {
177            Ok(entries) => entries,
178            Err(err) => {
179                tracing::error!(
180                    "failed to parse email variables file '{}': {:#?}",
181                    file.path().display(),
182                    err
183                );
184                continue;
185            }
186        };
187
188        for (template_identifier, entries) in entries {
189            for (name, value) in entries {
190                if let Some(variable) = variables
191                    .iter_mut()
192                    .find(|v| v.matches(Some(&template_identifier), &name))
193                {
194                    if language != "en" {
195                        variable.default_translations.insert(language.into(), value);
196                    }
197                } else if language == "en" {
198                    if let Err(err) = validate_variable_name(&name, &()) {
199                        tracing::error!(
200                            "ignoring email variable '{}.{}': {}",
201                            template_identifier,
202                            name,
203                            err
204                        );
205                        continue;
206                    }
207
208                    variables.push(EmailVariable {
209                        template_identifier: Some(template_identifier.clone()),
210                        name,
211                        default_value: value,
212                        default_translations: BTreeMap::new(),
213                    });
214                } else {
215                    tracing::warn!(
216                        "email variable translation '{}.{}' in '{}' has no English definition",
217                        template_identifier,
218                        name,
219                        file.path().display()
220                    );
221                }
222            }
223        }
224    }
225}
226
227pub(super) fn core_variables() -> Vec<EmailVariable> {
228    let mut variables = Vec::new();
229    load_variables(&VARIABLES_DIR, &mut variables);
230    variables
231}
232
233impl EmailTemplateManager {
234    fn variables_cache_key(template_identifier: Option<&str>) -> String {
235        format!(
236            "email_variables::{}",
237            template_identifier.unwrap_or_default()
238        )
239    }
240
241    pub async fn get_variables(
242        &self,
243        state: &crate::State,
244        template_identifier: Option<&str>,
245    ) -> Result<Vec<FetchedEmailVariable>, anyhow::Error> {
246        let rows: Vec<EmailVariableRow> = state
247            .cache
248            .cached(
249                &Self::variables_cache_key(template_identifier),
250                15,
251                || async {
252                    let rows = sqlx::query(
253                        "SELECT name, value, value_translations FROM email_variables
254                        WHERE template_identifier = $1
255                        ORDER BY name",
256                    )
257                    .bind(template_identifier.unwrap_or_default())
258                    .fetch_all(state.database.read())
259                    .await?;
260
261                    rows.into_iter()
262                        .map(|row| {
263                            Ok(EmailVariableRow {
264                                name: row.try_get("name")?,
265                                value: row.try_get("value")?,
266                                value_translations: serde_json::from_value(
267                                    row.try_get("value_translations")?,
268                                )?,
269                            })
270                        })
271                        .collect::<Result<Vec<_>, anyhow::Error>>()
272                },
273            )
274            .await?;
275
276        let mut rows: BTreeMap<compact_str::CompactString, EmailVariableRow> = rows
277            .into_iter()
278            .map(|row| (row.name.clone(), row))
279            .collect();
280
281        let mut variables: Vec<FetchedEmailVariable> = self
282            .variables
283            .read()
284            .iter()
285            .filter(|v| v.template_identifier.as_deref() == template_identifier)
286            .map(|definition| {
287                let (value, value_translations) = rows
288                    .remove(&definition.name)
289                    .map(|row| (row.value, row.value_translations))
290                    .unwrap_or_default();
291
292                FetchedEmailVariable {
293                    template_identifier: definition.template_identifier.clone(),
294                    name: definition.name.clone(),
295                    default_value: Some(definition.default_value.clone()),
296                    default_translations: definition.default_translations.clone(),
297                    value,
298                    value_translations,
299                }
300            })
301            .collect();
302
303        for (name, row) in rows {
304            variables.push(FetchedEmailVariable {
305                template_identifier: template_identifier.map(Into::into),
306                name,
307                default_value: None,
308                default_translations: BTreeMap::new(),
309                value: row.value,
310                value_translations: row.value_translations,
311            });
312        }
313
314        Ok(variables)
315    }
316
317    pub async fn resolve_variables(
318        &self,
319        state: &crate::State,
320        template_identifier: &str,
321        language: &str,
322    ) -> Result<BTreeMap<compact_str::CompactString, String>, anyhow::Error> {
323        let mut resolved = BTreeMap::new();
324
325        for variable in self
326            .get_variables(state, None)
327            .await?
328            .into_iter()
329            .chain(self.get_variables(state, Some(template_identifier)).await?)
330        {
331            let value = variable.resolve(language).to_string();
332            resolved.insert(variable.name, value);
333        }
334
335        Ok(resolved)
336    }
337
338    pub async fn create_variable(
339        &self,
340        state: &crate::State,
341        template_identifier: Option<&str>,
342        data: CreateEmailVariable,
343    ) -> Result<(), crate::database::DatabaseError> {
344        sqlx::query(
345            "INSERT INTO email_variables (template_identifier, name, value, value_translations)
346            VALUES ($1, $2, $3, $4)",
347        )
348        .bind(template_identifier.unwrap_or_default())
349        .bind(&data.name)
350        .bind(&data.value)
351        .bind(serde_json::to_value(&data.value_translations)?)
352        .execute(state.database.write())
353        .await?;
354
355        state
356            .cache
357            .invalidate(&Self::variables_cache_key(template_identifier))
358            .await?;
359
360        Ok(())
361    }
362
363    pub async fn update_variable(
364        &self,
365        state: &crate::State,
366        variable: &FetchedEmailVariable,
367        data: UpdateEmailVariable,
368    ) -> Result<(), anyhow::Error> {
369        let (value_set, value) = match data.value {
370            None => (false, None),
371            Some(inner) => (true, inner),
372        };
373        let value_translations = data
374            .value_translations
375            .as_ref()
376            .map(serde_json::to_value)
377            .transpose()?;
378
379        sqlx::query(
380            "INSERT INTO email_variables (template_identifier, name, value, value_translations)
381            VALUES ($1, $2, $3, COALESCE($5, '{}'::jsonb))
382            ON CONFLICT (template_identifier, name) DO UPDATE SET
383                value = CASE
384                    WHEN $4 THEN $3
385                    ELSE email_variables.value
386                END,
387                value_translations = COALESCE($5, email_variables.value_translations)",
388        )
389        .bind(variable.template_identifier.as_deref().unwrap_or_default())
390        .bind(&variable.name)
391        .bind(value.as_deref())
392        .bind(value_set)
393        .bind(value_translations)
394        .execute(state.database.write())
395        .await?;
396
397        if variable.is_system() {
398            sqlx::query(
399                "DELETE FROM email_variables
400                WHERE template_identifier = $1 AND name = $2
401                AND value IS NULL AND value_translations = '{}'::jsonb",
402            )
403            .bind(variable.template_identifier.as_deref().unwrap_or_default())
404            .bind(&variable.name)
405            .execute(state.database.write())
406            .await?;
407        }
408
409        state
410            .cache
411            .invalidate(&Self::variables_cache_key(
412                variable.template_identifier.as_deref(),
413            ))
414            .await?;
415
416        Ok(())
417    }
418
419    pub async fn delete_variable(
420        &self,
421        state: &crate::State,
422        variable: &FetchedEmailVariable,
423    ) -> Result<(), anyhow::Error> {
424        sqlx::query(
425            "DELETE FROM email_variables
426            WHERE template_identifier = $1 AND name = $2",
427        )
428        .bind(variable.template_identifier.as_deref().unwrap_or_default())
429        .bind(&variable.name)
430        .execute(state.database.write())
431        .await?;
432
433        state
434            .cache
435            .invalidate(&Self::variables_cache_key(
436                variable.template_identifier.as_deref(),
437            ))
438            .await?;
439
440        Ok(())
441    }
442}
443
444#[cfg(test)]
445mod tests {
446    use super::{super::ExtensionEmailTemplateBuilder, *};
447
448    fn placeholders(value: &str) -> Vec<&str> {
449        let mut found = Vec::new();
450        let mut rest = value;
451
452        while let Some(start) = rest.find("{{") {
453            let Some(len) = rest[start..].find("}}") else {
454                break;
455            };
456            found.push(rest[start..start + len + 2].trim());
457            rest = &rest[start + len + 2..];
458        }
459
460        found.sort_unstable();
461        found
462    }
463
464    fn variables_file(name: &str) -> VariablesFile {
465        serde_json::from_slice(
466            VARIABLES_DIR
467                .get_file(name)
468                .unwrap_or_else(|| panic!("{name} missing"))
469                .contents(),
470        )
471        .unwrap_or_else(|err| panic!("{name} is invalid: {err}"))
472    }
473
474    #[test]
475    fn translated_defaults_match_english_keys_and_placeholders() {
476        let base = variables_file("en.json");
477
478        for file in VARIABLES_DIR.files() {
479            let name = file.path().file_name().unwrap().to_str().unwrap();
480            if name == "en.json" {
481                continue;
482            }
483
484            let translations = variables_file(name);
485            for (template_identifier, entries) in &translations {
486                for (variable, value) in entries {
487                    let base_value = base
488                        .get(template_identifier)
489                        .and_then(|e| e.get(variable))
490                        .unwrap_or_else(|| {
491                            panic!("{name}: unknown variable '{template_identifier}.{variable}'")
492                        });
493                    assert_eq!(
494                        placeholders(value),
495                        placeholders(base_value),
496                        "{name}: placeholder mismatch in '{template_identifier}.{variable}'"
497                    );
498                    assert!(
499                        !value.is_empty(),
500                        "{name}: '{template_identifier}.{variable}' is empty"
501                    );
502                }
503            }
504        }
505    }
506
507    #[test]
508    fn directory_loading_matches_core_and_skips_unknown_translations() {
509        let builder = ExtensionEmailTemplateBuilder {
510            templates: vec![],
511            variables: vec![],
512        }
513        .add_template_variables(&VARIABLES_DIR);
514        let core = ExtensionEmailTemplateBuilder::default();
515
516        assert_eq!(builder.variables.len(), core.variables.len());
517        assert!(
518            builder
519                .variables
520                .iter()
521                .all(|v| v.default_translations.contains_key("de"))
522        );
523
524        let again = builder.add_template_variables(&VARIABLES_DIR);
525        assert_eq!(again.variables.len(), core.variables.len());
526    }
527
528    #[test]
529    fn extension_directory_adds_languages_to_its_own_and_core_variables() {
530        const EN: &str = r#"{ "dev.example.welcome": { "subject": "Welcome", "Bad Name": "x" } }"#;
531        const DE: &str = r#"{ "dev.example.welcome": { "subject": "Willkommen" }, "password_reset": { "subject": "Passwort neu" } }"#;
532        const FR: &str = r#"{ "dev.example.welcome": { "subject": "Bienvenue", "unknown": "?" } }"#;
533        const EXTENSION_DIR: include_dir::Dir<'_> = include_dir::Dir::new(
534            "mails/variables",
535            &[
536                include_dir::DirEntry::File(include_dir::File::new(
537                    "mails/variables/fr.json",
538                    FR.as_bytes(),
539                )),
540                include_dir::DirEntry::File(include_dir::File::new(
541                    "mails/variables/en.json",
542                    EN.as_bytes(),
543                )),
544                include_dir::DirEntry::File(include_dir::File::new(
545                    "mails/variables/de.json",
546                    DE.as_bytes(),
547                )),
548            ],
549        );
550
551        let builder =
552            ExtensionEmailTemplateBuilder::default().add_template_variables(&EXTENSION_DIR);
553
554        let welcome = builder
555            .variables
556            .iter()
557            .find(|v| v.matches(Some("dev.example.welcome"), "subject"))
558            .expect("extension variable registered");
559        assert_eq!(welcome.default_value, "Welcome");
560        assert_eq!(
561            welcome.default_translations.get("de").map(String::as_str),
562            Some("Willkommen")
563        );
564        assert_eq!(
565            welcome.default_translations.get("fr").map(String::as_str),
566            Some("Bienvenue")
567        );
568
569        assert!(builder.variables.iter().all(|v| v.name != "Bad Name"));
570        assert!(builder.variables.iter().all(|v| v.name != "unknown"));
571
572        let core_subject = builder
573            .variables
574            .iter()
575            .find(|v| v.matches(Some("password_reset"), "subject"))
576            .unwrap();
577        assert_eq!(
578            core_subject
579                .default_translations
580                .get("de")
581                .map(String::as_str),
582            Some("Passwort neu")
583        );
584    }
585
586    #[test]
587    fn variable_names_are_validated() {
588        for valid in ["subject", "ip_label", "a1", "footer_2"] {
589            assert!(
590                validate_variable_name(&valid.into(), &()).is_ok(),
591                "{valid}"
592            );
593        }
594        for invalid in [
595            "",
596            "Subject",
597            "1abc",
598            "with-dash",
599            "with space",
600            "_leading",
601            "über",
602        ] {
603            assert!(
604                validate_variable_name(&invalid.into(), &()).is_err(),
605                "{invalid}"
606            );
607        }
608    }
609
610    #[test]
611    fn resolution_prefers_operator_values_over_shipped_translations() {
612        let variable = FetchedEmailVariable {
613            template_identifier: None,
614            name: "greeting".into(),
615            default_value: Some("Hello".into()),
616            default_translations: BTreeMap::from([("de".into(), "Hallo".into())]),
617            value: None,
618            value_translations: BTreeMap::new(),
619        };
620        assert_eq!(variable.resolve("de"), "Hallo");
621        assert_eq!(variable.resolve("fr"), "Hello");
622
623        let customised = FetchedEmailVariable {
624            value: Some("Hi there".into()),
625            ..variable
626        };
627        assert_eq!(customised.resolve("de"), "Hi there");
628
629        let translated = FetchedEmailVariable {
630            value_translations: BTreeMap::from([("de".into(), "Servus".into())]),
631            ..customised
632        };
633        assert_eq!(translated.resolve("de"), "Servus");
634        assert_eq!(translated.resolve("en"), "Hi there");
635    }
636}