rullst 12.3.0

The AI-Native Full-Stack, SaaS & Edge/IoT Framework for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

//! Account mail bridge: Auth owns the transaction, Mail owns rendering/transport.

use crate::{
    auth::recovery::{
        RecoveryDeliveryFailure, RecoveryError, RecoveryNoticeKind, SqlRecoveryStore,
    },
    mail::{AccountEvent, AccountMail, ActionLink, MailDriver, MailFailureClass, MailLocale},
};

/// Immutable server-owned delivery configuration. Provider/domain tracking must
/// be disabled independently, including settings that override per-message flags.
pub struct AccountMailConfig {
    origin: String,
    reset_endpoint: String,
    application_name: String,
    sender: String,
    locale: MailLocale,
}

impl AccountMailConfig {
    pub fn new(
        origin: impl Into<String>,
        reset_endpoint: impl Into<String>,
        application_name: impl Into<String>,
        sender: impl Into<String>,
        locale: MailLocale,
    ) -> Result<Self, RecoveryError> {
        let origin = origin.into();
        let reset_endpoint = reset_endpoint.into();
        ActionLink::new(&reset_endpoint, &origin).map_err(|_| RecoveryError::Configuration)?;
        if reset_endpoint.contains(['?', '#']) {
            return Err(RecoveryError::Configuration);
        }
        let application_name = application_name.into();
        let sender = sender.into();
        let test = AccountMail::new(
            "validation@example.com",
            &application_name,
            locale,
            AccountEvent::Welcome,
        )
        .map_err(|_| RecoveryError::Configuration)?
        .from(&sender)
        .into_message();
        crate::mail::DeliveryPipeline::prepare(&test).map_err(|_| RecoveryError::Configuration)?;
        Ok(Self {
            origin,
            reset_endpoint,
            application_name,
            sender,
            locale,
        })
    }
}

/// Low-cardinality worker result; no recipient or action URL is exposed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AccountMailOutcome {
    Idle,
    Delivered,
    RetryScheduled,
    Failed,
}

/// Sends one leased encrypted notice with a 30-second timeout. Run under a
/// bounded worker loop, separate from the password-reset request handler.
/// Delivery retries can duplicate mail on transports without native idempotency.
pub async fn deliver_next_account_mail(
    store: &SqlRecoveryStore,
    driver: &impl MailDriver,
    config: &AccountMailConfig,
) -> Result<AccountMailOutcome, RecoveryError> {
    let now = unix_now()?;
    let Some(claim) = store.claim_notice(now).await? else {
        return Ok(AccountMailOutcome::Idle);
    };
    let notice = claim.notice();
    let event = match notice.kind() {
        RecoveryNoticeKind::Welcome => AccountEvent::Welcome,
        RecoveryNoticeKind::PasswordChanged => AccountEvent::PasswordChanged,
        RecoveryNoticeKind::PasswordReset => {
            let token = notice.token().ok_or(RecoveryError::InvalidAction)?;
            let link = ActionLink::new(
                format!("{}?token={}", config.reset_endpoint, token.expose()),
                &config.origin,
            )
            .map_err(|_| RecoveryError::Configuration)?;
            let expires_at = chrono::DateTime::from_timestamp(notice.expires_at(), 0)
                .ok_or(RecoveryError::InvalidAction)?;
            AccountEvent::PasswordResetAt { link, expires_at }
        }
        _ => return Err(RecoveryError::InvalidAction),
    };
    let message = AccountMail::new(
        notice.recipient(),
        &config.application_name,
        notice.locale().map_or(config.locale, |locale| {
            MailLocale::from_preference(locale.as_str())
        }),
        event,
    )
    .map_err(|_| RecoveryError::Configuration)?
    .from(&config.sender)
    .into_message();
    let sent = tokio::time::timeout(
        std::time::Duration::from_secs(30),
        driver.send_with_delivery_id(&message, claim.delivery_id()),
    )
    .await;
    match sent {
        Ok(Ok(())) => {
            store.complete_notice(&claim, unix_now()?).await?;
            Ok(AccountMailOutcome::Delivered)
        }
        result => {
            let transient = match result {
                Err(_) => true,
                Ok(Err(error)) => matches!(
                    error.failure_class(),
                    MailFailureClass::Transient | MailFailureClass::RateLimited
                ),
                Ok(Ok(())) => false,
            };
            store
                .fail_notice(
                    &claim,
                    if transient {
                        RecoveryDeliveryFailure::Transient
                    } else {
                        RecoveryDeliveryFailure::Permanent
                    },
                    unix_now()?,
                )
                .await?;
            Ok(if transient {
                AccountMailOutcome::RetryScheduled
            } else {
                AccountMailOutcome::Failed
            })
        }
    }
}

fn unix_now() -> Result<u64, RecoveryError> {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|time| time.as_secs())
        .map_err(|_| RecoveryError::Configuration)
}