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}