Struct Service 

pub struct Service {
    db: Data,
    pending_mutex: MutexMap<String, ()>,
    claim_mutex: MutexMap<UiaaKey, ()>,
    ip_ratelimiter: Mutex<HashMap<IpAddr, (Instant, f64)>>,
    address_ratelimiter: Mutex<HashMap<SmallString<[u8; 48]>, (Instant, f64)>>,
}

Manages email threepid bindings, verification sessions, and request limits.

Persistent maps provide lookups from user to email and email to user. In-memory token buckets limit requestToken calls by caller IP and canonical address.

Fields

db: Data

pending_mutex: MutexMap<String, ()>

claim_mutex: MutexMap<UiaaKey, ()>

ip_ratelimiter: Mutex<HashMap<IpAddr, (Instant, f64)>>

address_ratelimiter: Mutex<HashMap<SmallString<[u8; 48]>, (Instant, f64)>>

Implementations

impl Service

pub async fn put_binding( &self, user_id: &UserId, email_canon: &str, medium: Medium, validated_at: MilliSecondsSinceUnixEpoch, added_at: MilliSecondsSinceUnixEpoch, )

Persist a binding in both directions: the forward (user, email) row with its metadata, and the reverse email -> user lookup.

impl Service

pub fn get_bindings<'a>( &'a self, user_id: &'a UserId, ) -> impl Stream<Item = ThirdPartyIdentifier> + Send + 'a

All third-party identifiers bound to user_id, lazily decoded from the (user, email) prefix scan.

impl Service

pub async fn del_binding(&self, user_id: &UserId, email_canon: &str)

Remove a binding in both directions; blind-delete, tolerant of an absent row. The reverse lookup is removed only when it still maps to this user, so one user’s delete cannot wipe another’s reverse row.

impl Service

pub async fn bound_elsewhere( &self, user_id: &UserId, email_canon: &str, ) -> Result<bool>

Whether a canonical email address is bound to an account other than this one.

Separates rebinding an address a user already holds, which is permitted, from claiming one another account owns, which is not. The lookup’s own error handling decides what an unreadable row does.

impl Service

pub async fn user_id_for_email( &self, email_canon: &str, ) -> Result<Option<OwnedUserId>>

The user bound to a canonical email address, if any.

impl Service

pub async fn address_in_use(&self, email_canon: &str) -> bool

Whether a canonical email address is already bound to some user.

impl Service

pub async fn create_or_reuse_pending( &self, client_secret: &str, medium: Medium, address: &str, send_attempt: u64, ttl: Duration, ) -> Result<PendingOutcome>

Open a pending verification, or reuse an in-flight one for the same request identity. The session id is derived from (medium, address, client_secret), so a resubmit collides on the same row: a non-validated session whose send_attempt did not advance returns the same sid with no new token (and thus no new mail), per the send-attempt dedup rule.

impl Service

pub async fn validate_pending_token( &self, sid: &str, client_secret: &str, token: &str, ) -> Result<()>

Validate a submitted token against a pending session. A wrong client_secret or token counts toward the attempt ceiling and burns the session once exceeded; the caller learns nothing about session or token liveness beyond pass or fail.

impl Service

pub async fn claim_validated( &self, sid: &str, client_secret: &str, claim: UiaaKey, ) -> Result<bool>

Exclusively claim a validated pending session for one UIAA transaction.

Invalid or unavailable proofs return false; storage and decoding failures remain errors so registration cannot silently continue through them.

impl Service

pub async fn refresh_claim(&self, claim: &UiaaKey) -> Result<bool>

Refresh a claim that is still owned by one UIAA transaction.

Rewriting both rows keeps their persistence lifetime aligned with later successful stages that refresh the owning UIAA session.

impl Service

pub async fn redeem_claim(&self, claim: &UiaaKey) -> Result<Association>

Spends the validated threepid owned by one UIAA transaction.

Redemption atomically records the pending proof as spent and removes the claim index, so retries cannot yield the association again.

impl Service

pub async fn redeem_validated( &self, sid: &str, client_secret: &str, ) -> Result<Association>

Spends an unclaimed validated session directly, returning its association.

The pending row remains as a spent tombstone until expiry so replayed requests fail closed instead of reusing a previously accepted proof.

impl Service

pub async fn session_validated(&self, sid: &str, client_secret: &str) -> bool

Reports whether an unclaimed pending session is ready for UIAA.

This non-consuming gate maps wrong secrets, expired or unknown sessions, spent proofs, and storage failures to false, revealing no extra liveness.

impl Service

fn persist_pending(&self, sid: &str, pending: &Pending)

impl Service

async fn delete_pending_state(&self, sid: &str, pending: &Pending) -> Result<()>

impl Service

fn delete_pending_rows(&self, sid: &str, claim: Option<&UiaaKey>)

impl Service

fn delete_claim_index(&self, claim: &UiaaKey)

impl Service

async fn claim_sid( &self, claim: &UiaaKey, ) -> Result<Option<SmallString<[u8; 43]>>>

impl Service

async fn get_pending(&self, sid: &str) -> Result<Pending>

impl Service

pub fn check_ip_rate_limit(&self, client: IpAddr) -> Result

Per-caller-IP requestToken throttle, the axis bounding one source spraying many addresses.

impl Service

pub fn check_address_rate_limit(&self, address: &str) -> Result

Per-target-address requestToken throttle, the axis bounding many sources spraying one address.

Trait Implementations

impl Service for Service

fn build(args: &Args<'_>) -> Result<Arc<Self>>

Implement the construction of the service instance. Services are generally singletons so expect this to only be called once for a service type. Note that it may be called again after a server reload, but the prior instance will have been dropped first. Failure will shutdown the server with an error.

fn name(&self) -> &str

Return the name of the service. i.e. crate::service::make_name(std::module_path!())

fn worker<'async_trait>( self: Arc<Self>, ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait,

Implement the service’s worker loop. The service manager spawns a task and calls this function after all services have been built.

fn interrupt<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Interrupt the service. This is sent to initiate a graceful shutdown. The service worker should return from its work loop.

fn clear_cache<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Clear any caches or similar runtime state.

fn memory_usage<'life0, 'life1, 'async_trait>( &'life0 self, _out: &'life1 mut (dyn Write + Send), ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Memory usage report in a markdown string.

fn unconstrained(&self) -> bool

Return true if the service worker opts out of the tokio cooperative budgeting. This can reduce tail latency at the risk of event loop starvation.