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, )

Persists a canonical email binding in both index directions.

The forward row stores the medium and timestamps, while the reverse row stores the owning user. These are separate map writes, so callers must not treat the two rows as one atomic snapshot.

impl Service

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

Streams all third-party identifiers bound to user_id.

Entries are decoded lazily from the user’s forward-index prefix. Storage or decoding failures are skipped, and each yielded identifier owns its data.

impl Service

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

Removes a canonical email binding from both index directions.

The forward row is deleted even when absent. The reverse row is removed only when a successful lookup still names this user, so a read failure or a different owner leaves that row untouched.

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.

No binding or a binding to user_id returns false. Storage and decoding failures from the reverse lookup are propagated.

impl Service

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

Returns the user bound to a canonical email address.

An absent reverse row returns None. Storage and user-ID decoding failures are propagated.

impl Service

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

Tests whether a canonical email address has a readable reverse row.

Any successful raw lookup returns true without decoding the stored user. Absence and all storage failures are both collapsed to false.

impl Service

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

Opens or reuses a pending verification for one request identity.

The session identifier is derived from the medium, address, and client secret. A live unvalidated session with no greater send attempt is reused without minting another token; other accepted attempts replace the pending proof and restart its expiry.

impl Service

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

Validates a submitted secret and token against a pending session.

Each mismatch increments the durable attempt count, and the fifth mismatch deletes the session. Failure responses avoid distinguishing the secret from the token, while expired and already-used sessions remain separate errors.

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. Repeating the same claim is accepted, while a different owner or existing session for that claim is rejected.

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. Missing, expired, or inconsistent rows return false after stale indexes are removed where possible.

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. Expired, missing, changed, or differently owned claims return an error.

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 so replayed requests fail closed instead of reusing a previously accepted proof. An expiry-aware later operation removes the tombstone after observing expiry; passage of time alone does not delete it. Claimed sessions must instead be consumed through Service::redeem_claim.

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. It does not refresh, claim, redeem, or delete the pending row.

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

Applies the verification-request limit for one caller IP address.

This axis bounds one source attempting many target addresses. Exhausted buckets return a rate-limit error without a retry interval.

impl Service

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

Applies the verification-request limit for one target address.

This axis bounds many sources attempting the same exact address key. Exhausted buckets return a rate-limit error without a retry interval.

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.