Skip to main content

Service

Struct Service 

Source
pub struct Service {
    services: Arc<OnceServices>,
    db: Data,
    device_list_mutex: MutexMap<OwnedUserId, ()>,
    login_token_mutex: MutexMap<SmallString<[u8; 48]>, ()>,
    changing_password: MutexMap<OwnedUserId, ()>,
    claiming_one_time_keys: MutexMap<(OwnedUserId, OwnedDeviceId), ()>,
    updating_device: MutexMap<(OwnedUserId, OwnedDeviceId), ()>,
}

Fields§

§services: Arc<OnceServices>§db: Data§device_list_mutex: MutexMap<OwnedUserId, ()>§login_token_mutex: MutexMap<SmallString<[u8; 48]>, ()>§changing_password: MutexMap<OwnedUserId, ()>§claiming_one_time_keys: MutexMap<(OwnedUserId, OwnedDeviceId), ()>§updating_device: MutexMap<(OwnedUserId, OwnedDeviceId), ()>

Serializes the writers of one device and of each of a user’s key rows.

Entries live only while held or awaited: by a device’s creation, token issuance, metadata update (each presence ping’s last-seen) or removal, a device key upload, a signature merge, or a cross-signing key write (one per key row).

Implementations§

Source§

impl Service

Source

pub async fn create_browser_session( &self, user_id: &UserId, verified: Option<&str>, replaces: Option<&str>, ) -> Option<BrowserSession>

Starts a browser session for a user who just signed in with a password.

verified is the password hash the sign-in checked, None when it could not be read. The session is minted only while that hash is still the account’s, read under the password lock, so a new password either lands first and refuses the session or lands after and ends it. Disabling a password ends no session, but a deactivated account’s sessions are refused at use. The session named by replaces ends first, whoever it belongs to, so each sign-in mints a fresh session id and never adopts one the browser already carried. Returns None while browser sessions are turned off, without a verified hash, or once the stored hash differs or cannot be read.

Source§

impl Service

Source

pub(super) fn mint_browser_session( &self, user_id: &UserId, ) -> Option<BrowserSession>

Stores a new browser session for a user and returns its cookie.

It checks no password, so a sign-in goes through create_browser_session. Returns None while browser sessions are turned off.

Source§

impl Service

Source

pub async fn find_browser_session<'a>( &self, token: &'a str, ) -> Option<&'a UserId>

Returns the user a browser session belongs to while the session lasts.

A garbled, unknown, ended or expired token answers None, as does any token while browser sessions are turned off. A read failure other than a missing row is logged and answers None as well.

Source§

impl Service

Source

pub fn end_browser_session(&self, token: &str, user_id: &UserId)

Ends a browser session when it belongs to user_id.

A token naming another user is left alone, so a request authenticated as one account never signs the browser out of a different one.

Source§

impl Service

Source

pub async fn end_browser_sessions(&self, user_id: &UserId) -> Result

Ends every browser session of a user.

Password writes, deactivation and signing out of all devices call it. A failed scan is returned rather than skipped, so no caller reports the sessions ended while one survives. The scan stops at the user ID’s separator, so a longer user ID sharing its bytes keeps its sessions.

Source§

impl Service

Source

fn remove_browser_session(&self, user_id: &UserId, secret: &str)

Source§

impl Service

Source§

impl Service

Source

pub(super) fn create_disabled(&self, user_id: &UserId, origin: &str)

Source§

impl Service

Source

pub async fn set_dehydrated_device( &self, user_id: &UserId, request: Request, ) -> Result

Creates or recreates the user’s dehydrated device.

Source§

impl Service

Source

pub(super) async fn remove_dehydrated_device( &self, user_id: &UserId, maybe_device_id: Option<&DeviceId>, ) -> Result<OwnedDeviceId>

Removes a user’s dehydrated device.

Calling this directly will remove the dehydrated data but leak the frontage device. Thus this is called by the regular device interface such that the dehydrated data will not leak instead.

If device_id is given, the user’s dehydrated device must match or this is a no-op, but an Err is still returned to indicate that. Otherwise returns the removed dehydrated device_id.

Source§

impl Service

Source

pub async fn get_dehydrated_device_id( &self, user_id: &UserId, ) -> Result<OwnedDeviceId>

Get the device_id of the user’s dehydrated device.

Source§

impl Service

Source

pub async fn get_dehydrated_device( &self, user_id: &UserId, ) -> Result<DehydratedDevice>

Get the dehydrated device private data

Source§

impl Service

Source

pub async fn create_device( &self, user_id: &UserId, device_id: Option<&DeviceId>, __arg3: (Option<&str>, Option<Duration>), refresh_token: Option<&str>, initial_device_display_name: Option<&str>, client_ip: Option<IpAddr>, ) -> Result<OwnedDeviceId>

Adds a new device to a user.

Without a device ID one is generated. A chosen ID is refused when longer than MAX_DEVICE_ID_LENGTH bytes or when it matches one of the user’s cross-signing key IDs. The device is written and given its tokens under the device lock, where an expiring token without a refresh token retires any the ID already holds.

Source§

impl Service

Source

pub async fn check_device_id( &self, user_id: &UserId, device_id: Option<&DeviceId>, ) -> Result

Refuses a device ID the user may not take.

An ID longer than MAX_DEVICE_ID_LENGTH bytes is refused. So is one coinciding with one of the user’s cross-signing key IDs, since both share the device key row space. Without an ID nothing is refused.

Source§

impl Service

Source

pub(super) async fn lock_device( &self, user_id: &UserId, device_id: &DeviceId, ) -> MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>

Locks one device against concurrent creation, token issuance, metadata and key updates, and removal.

A refresh token is rotated by reading the one the device points at and replacing it, so issuers run one after another to leave the device a single refresh token. An issuer, or a metadata or key update, that runs after removal finds no device rather than writing for one already gone.

Source§

impl Service

Source

async fn open_session( &self, lock: &MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &UserId, device_id: &DeviceId, access: (&str, Option<Duration>), refresh_token: Option<&str>, ) -> Result

Issues the tokens that open a session on one device.

An expiring token given without a refresh token ends the session at its expiry, so any refresh token the device holds retires first. A rotation continues a session and keeps its refresh token on the grace path, so it never comes through here.

Source§

impl Service

Source

pub async fn remove_devices(&self, user_id: &UserId, keep: Option<&DeviceId>)

Removes every device of a user except the one to keep, if any.

Each device is removed as by remove_device, so its access token stops working. Removals run concurrently, in no particular order.

Source§

impl Service

Source

pub async fn remove_device(&self, user_id: &UserId, device_id: &DeviceId)

Removes a device from a user.

Everything keyed by the device goes with it except its sync connections, so a later session under the same ID starts with no keys, identity keys included, and resumes its sync position.

Source§

impl Service

Source

fn remove_device_locked<'a>( &'a self, __arg1: &'a MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, __arg2: &'a UserId, __arg3: &'a DeviceId, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>

Source

async fn __remove_device_locked<'a>( &'a self, _lock: &'a MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &'a UserId, device_id: &'a DeviceId, )

Source§

impl Service

Source

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

Returns an iterator over all device ids of this user.

Source§

impl Service

Source

pub async fn find_from_unexpired_token( &self, token: &str, ) -> Option<(OwnedUserId, OwnedDeviceId)>

Find out which user a token belongs to, unless the token has expired.

An expired token stays recorded until its device moves on from it, so its client keeps reading a soft logout and a route granting access needs this rather than the plain lookup.

Source§

impl Service

Source

pub async fn find_from_token( &self, token: &str, ) -> Result<(OwnedUserId, OwnedDeviceId, Option<SystemTime>)>

Find out which user an access or refresh token belongs to.

Source§

impl Service

Source

pub async fn remove_tokens(&self, user_id: &UserId, device_id: &DeviceId)

Source§

impl Service

Source

pub async fn set_access_token( &self, user_id: &UserId, device_id: &DeviceId, access_token: &str, expires_in: Option<Duration>, refresh_token: Option<&str>, ) -> Result

Replaces the access token of one device, and its refresh token when one is given.

The tokens are issued under the device lock, and refused when the device no longer exists. An expiring token given without a refresh token is meant to end the session, so the device’s own refresh token retires under that lock.

Source§

impl Service

Source

pub async fn rotate_refresh_token<Gate>( &self, seen: &RefreshToken, presented: &str, access: (&str, Option<Duration>), gate: Gate, ) -> Result<String>
where Gate: Future<Output = Result> + Send,

Exchanges a presented refresh token for a new access token of its device, returning the refresh token for the client to keep.

Reuse is judged by seen, the caller’s classification when the request arrived: a token already spent outside the reuse grace window is refused, and its device revoked when so configured. Otherwise the token is classified again under the device lock, where a current one rotates and a spent one inside the grace window keeps its successor, each once gate, the caller’s account check, passes. One found expired, or spent inside the grace window with an expired successor, is refused with the configured logout, and one spent meanwhile by a concurrent exchange is refused alone.

Source§

impl Service

Source

async fn expire_refresh_token( &self, lock: &MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &UserId, device_id: &DeviceId, ) -> Error

Refuses an expired refresh token, retiring it first.

With hard logout the whole device is removed, otherwise only its refresh token, leaving the session to log in again on the same device.

Source§

impl Service

Source

async fn revoke_reused_refresh_token( &self, lock: &MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &UserId, device_id: &DeviceId, ) -> Error

Refuses a refresh token presented again after its rotation.

Reuse outside the grace window suggests the token was copied, so the device is removed when authentication.refresh_token.reuse_revoke is set.

Source§

impl Service

Source

async fn issue_tokens( &self, lock: &MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &UserId, device_id: &DeviceId, __arg4: (&str, Option<Duration>), refresh_token: Option<&str>, ) -> Result

Issues an access token, and a refresh token when one is given, to one device.

A device removed before its lock was taken gets none.

Source§

impl Service

Source

fn write_access_token( &self, user_id: &UserId, device_id: &DeviceId, (access_token, expires_at): (&str, Option<u64>), previous: Option<&str>, superseded: impl Iterator<Item = SmallString<[u8; 32]>>, )

Stores an access token in one write, with the index rows of the token it replaces and the removal of the superseded tokens.

The token being replaced stays whatever its expiry, since requests may still carry it.

Source§

impl Service

Source

async fn superseded_access_tokens( &self, user_id: &UserId, device_id: &DeviceId, ) -> impl Iterator<Item = SmallString<[u8; 32]>>

Finds the expired access tokens of one device, except those with the latest expiry.

Issuing a token forgets these, which keeps the device’s rows from growing. A later token having expired shows the client moved on, so forgetting the older one should not turn a request still in flight into a hard logout. A token with no expiry, or whose row cannot be read, is never included.

Source§

impl Service

Source

pub async fn remove_access_token( &self, user_id: &UserId, device_id: &DeviceId, ) -> Result

Revoke every access token of one device, without deleting the device. Take care to not leave dangling devices if using this method.

Source§

impl Service

Source

pub fn generate_access_token(&self, expires: bool) -> (String, Option<Duration>)

Source§

impl Service

Source

async fn set_refresh_token( &self, _lock: &MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>, user_id: &UserId, device_id: &DeviceId, refresh_token: &str, ) -> Result

Replaces the refresh token of one device in a single write.

The outgoing token is retired in the same batch that stores its successor, so a token presented meanwhile classifies as current or as spent, never as unknown. Absolute expiry carries the prior deadline forward.

Source§

impl Service

Source

async fn find_refresh_token_expires_at( &self, token: &[u8], ) -> Option<SystemTime>

Looks up the expiry stored alongside a refresh token.

Pre-rotation entries carry no expiry and return None.

Source§

impl Service

Source

pub async fn remove_refresh_token( &self, user_id: &UserId, device_id: &DeviceId, ) -> Result

Revoke the refresh token without deleting the device. Take care to not leave dangling devices if using this method.

Source§

impl Service

Source

async fn forget_spent_refresh_token( &self, user_id: &UserId, device_id: &DeviceId, txn: &mut Txn, )

Drop the spent (previous-generation) refresh token retained for reuse detection, if any.

Source§

impl Service

Source

pub async fn classify_refresh_token(&self, presented: &str) -> RefreshToken

Classify a presented refresh token for the token-endpoint rotation path.

A current token carries its own expiry, and the one retained spent token its successor, with that successor’s expiry when grace is set. A grace replay whose successor no longer resolves is unknown, as is anything else.

Source§

impl Service

Source

pub fn add_to_device_event( &self, sender: &UserId, target_user_id: &UserId, target_device_id: &DeviceId, event_type: &str, content: &Value, ) -> u64

Source§

impl Service

Source

pub fn get_to_device_events<'a>( &'a self, user_id: &'a UserId, device_id: &'a DeviceId, since: Option<u64>, to: Option<u64>, ) -> impl Stream<Item = (u64, Raw<AnyToDeviceEvent>)> + Send + 'a

Source§

impl Service

Source

pub async fn remove_to_device_events<Until>( &self, user_id: &UserId, device_id: &DeviceId, until: Until, )
where Until: Into<Option<u64>> + Send,

Source§

impl Service

Source

pub async fn update_device_last_seen( &self, user_id: &UserId, device_id: &DeviceId, last_seen_ip: Option<IpAddr>, last_seen_ts: Option<MilliSecondsSinceUnixEpoch>, ) -> Result

Records when and from where a device was last seen.

An address is kept from an earlier sighting when none is given, and the time defaults to now. The device list is not notified.

Source§

impl Service

Source

pub async fn rename_device( &self, user_id: &UserId, device_id: &DeviceId, display_name: &str, ) -> Result

Renames an existing device, notifying its device list only when the name changes.

The rename holds the device lock like any other metadata update.

Source§

impl Service

Source

pub async fn update_device_metadata<Update>( &self, user_id: &UserId, device_id: &DeviceId, update: Update, ) -> Result
where Update: FnOnce(Device) -> (Device, bool) + Send,

Rewrites the metadata of an existing device, notifying its device list when update says so.

The read and the write hold the device lock, so a device removed in between is not written back, and two updates never lose one another’s fields. A missing device is an error and update does not run. update must keep the device ID; changing it panics.

Source§

impl Service

Source

async fn put_device_metadata( &self, user_id: &UserId, notify: bool, device: &Device, )

Persists device metadata and optionally announces the changed device.

Silent updates leave the device-list version and notification rows unchanged.

Source§

impl Service

Source

pub async fn get_device_metadata( &self, user_id: &UserId, device_id: &DeviceId, ) -> Result<Device>

Get device metadata.

Source§

impl Service

Source

pub async fn device_exists( &self, user_id: &UserId, device_id: &DeviceId, ) -> bool

Source§

impl Service

Source

pub async fn try_device_exists( &self, user_id: &UserId, device_id: &DeviceId, ) -> Result<bool>

Whether a device exists, returning a failed read instead of taking it for absence.

Callers that act on a device’s absence use this, since device_exists reports a device it cannot read as absent.

Source§

impl Service

Source

pub async fn is_oidc_device( &self, user_id: &UserId, device_id: &DeviceId, ) -> bool

Source§

impl Service

Source

pub async fn get_oidc_device_idp( &self, user_id: &UserId, device_id: &DeviceId, ) -> Option<String>

Returns the IdP that originally authenticated this device, if known. Returns None for devices predating the idp_id field or non-OIDC devices.

Source§

impl Service

Source

pub fn mark_oidc_device( &self, user_id: &UserId, device_id: &DeviceId, idp_id: &str, )

Source§

impl Service

Source

pub fn allow_cross_signing_replacement(&self, user_id: &UserId) -> SystemTime

Allow cross-signing key replacement without UIAA for the next 10 minutes. Returns the expiry timestamp in milliseconds.

Source§

impl Service

Source

pub async fn can_replace_cross_signing_keys(&self, user_id: &UserId) -> bool

Check if the user is allowed to replace cross-signing keys without UIAA.

Source§

impl Service

Source

pub async fn get_devicelist_version(&self, user_id: &UserId) -> Result<u64>

Source§

impl Service

Source

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

Source§

impl Service

Source

pub async fn invite_filter(&self, recipient: &UserId) -> InviteFilter

Fetch the invite filtering state a recipient has configured.

The four account data slots are read concurrently, and a slot that is absent or malformed drops out rather than failing the others.

Source§

impl Service

Source

async fn stable_config( &self, recipient: &UserId, ) -> Option<InvitePermissionConfigEventContent>

The stable slot, keeping its blanket switch even when its lists are not.

MSC4155 invalidates the whole event when a rule list is not an array, but the blanket block is stable spec and outranks the lists, so it is read back on its own rather than lost with them.

Source§

impl Service

Source

pub async fn invite_permission( &self, sender: &UserId, recipient: &UserId, ) -> InvitePermission

The recipient’s verdict on a single invite from one sender.

Fetches the filtering state and discards it, so a caller judging several senders should hold an InviteFilter instead.

Source§

impl Service

Source

pub async fn add_one_time_keys( &self, user_id: &UserId, device_id: &DeviceId, keys: &BTreeMap<OwnedOneTimeKeyId, Raw<OneTimeKey>>, limit: usize, ) -> Result

Source§

impl Service

Source

pub async fn add_one_time_key( &self, user_id: &UserId, device_id: &DeviceId, one_time_key_key: &KeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, one_time_key_value: &Raw<OneTimeKey>, txn: &mut Txn, ) -> Result<Option<impl Deref<Target = u64> + Send + use<>>>

Source§

impl Service

Source

pub async fn add_fallback_keys<'a, Keys>( &self, user_id: &UserId, device_id: &DeviceId, keys: Keys, ) -> Result
where Keys: Iterator<Item = (&'a OneTimeKeyId, &'a Raw<OneTimeKey>)> + Send + 'a,

Source§

impl Service

Source

pub async fn add_fallback_key( &self, user_id: &UserId, device_id: &DeviceId, one_time_key_key: &KeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, one_time_key_value: &Raw<OneTimeKey>, txn: &mut Txn, ) -> Result<impl Deref<Target = u64> + Send + use<>>

Source§

impl Service

Source

pub async fn take_fallback_key( &self, user_id: &UserId, device_id: &DeviceId, algorithm: &OneTimeKeyAlgorithm, ) -> Result<(OwnedKeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, Raw<OneTimeKey>)>

Source§

impl Service

Source

pub fn unused_fallback_key_algorithms<'a>( &'a self, user_id: &'a UserId, device_id: &'a DeviceId, ) -> impl Stream<Item = OneTimeKeyAlgorithm> + Send + 'a

Streams the algorithms of a device’s fallback keys that no claim has used.

The scan ends at the device’s own rows, so a device whose ID extends this one’s contributes none.

Source§

impl Service

Source

pub async fn last_one_time_keys_update(&self, user_id: &UserId) -> u64

Source§

impl Service

Source

pub async fn take_one_time_key( &self, user_id: &UserId, device_id: &DeviceId, key_algorithm: &OneTimeKeyAlgorithm, ) -> Result<(OwnedKeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, Raw<OneTimeKey>)>

Source§

impl Service

Source

pub async fn count_one_time_keys( &self, user_id: &UserId, device_id: &DeviceId, ) -> BTreeMap<OneTimeKeyAlgorithm, UInt>

Source§

impl Service

Source

pub async fn prune_one_time_keys( &self, user_id: &UserId, device_id: &DeviceId, excess: usize, )

MSC4225: drop the excess oldest rows for this (user, device). Forward iteration over the prefix runs in count_be ascending order, so take(excess) yields the earliest-uploaded rows.

Source§

impl Service

Source

pub async fn remove_one_time_keys(&self, user_id: &UserId, device_id: &DeviceId)

Drops every one-time key still outstanding for this (user, device).

Device removal has to reach the pool as well as the MSC2732 fallback key, or a claim against the deleted device still succeeds from the rows left behind.

Source§

impl Service

Source

pub async fn clear_one_time_keys( &self, user_id: Option<&UserId>, ) -> Result<(usize, usize)>

Drops the one-time keys of every local device, or of one user’s devices, and returns how many keys it dropped and from how many devices.

A database restored from an older backup again holds the keys claimed since the backup was taken, and /keys/claim would issue them a second time. Their devices discarded the private halves on first use, so a session opened with one of them cannot be decrypted. An empty pool issues none: a client sees a count of zero at its next sync and uploads new keys, and a claim before then is served the device’s fallback key, which this leaves in place. A device that never syncs, such as a dehydrated device, keeps only that fallback key until it is replaced. Removing the fallback key would leave the device unreachable for new sessions until it uploads again, so it stays even though a restored one can itself be stale: some clients rotate it on a timer, and a backup older than the last rotation restores a key the device no longer holds.

Every row of the pool goes, including one whose device is gone and one that does not parse as a key. The scan’s own errors are returned rather than skipped, so a clearing that did not see the whole pool is never reported as done. Each user whose keys went is marked as changed, which wakes their syncs, in the same atomic batch as the removal; a clearing cut short therefore leaves the whole pool for a retry rather than an empty one whose clients were never told.

Source§

impl Service

Source

fn clear_txn<'a, Users>( &self, otk: &Map, rows: &[Vec<u8>], users: Users, count: u64, ) -> Txn
where Users: Iterator<Item = &'a UserId>,

Source§

impl Service

Source

pub async fn add_device_keys( &self, user_id: &UserId, device_id: &DeviceId, device_keys: &Raw<DeviceKeys>, ) -> Result

Stores a device’s identity keys in place of any it had.

The write holds the device lock and is skipped for a device already removed, so it neither races a signature merge on the same row nor writes back keys the removal deleted. A device that cannot be read fails the call.

Source§

impl Service

Source

pub async fn add_cross_signing_keys( &self, user_id: &UserId, master_key: &Option<Raw<CrossSigningKey>>, self_signing_key: &Option<Raw<CrossSigningKey>>, user_signing_key: &Option<Raw<CrossSigningKey>>, notify: bool, ) -> Result

Stores a user’s cross-signing keys and points the user at them.

Every key given is parsed before any is written, and a key not given keeps the one stored. notify announces the keys on the device list once written.

Source§

impl Service

Source

pub async fn store_remote_master_key( &self, user_id: &UserId, master_key: &Raw<CrossSigningKey>, ) -> Result

Stores a remote user’s master key, keeping the signatures our copy carries.

The row stays locked from reading our copy to writing the merged key, so a signature merged meanwhile is kept, and our copy is read unfiltered, so none of its signatures is dropped. Nothing is announced, since a notification would prompt another key query without end.

Source§

impl Service

Source

async fn store_cross_signing_keys( &self, user_id: &UserId, keys: &[(&'_ Raw<CrossSigningKey>, String, &'_ Arc<Map>)], )

Writes parsed cross-signing keys while their rows are locked.

The rows are locked against signature merges, in public key order, until the keys are written.

Source§

impl Service

Source

async fn lock_keys<'a, PublicKeys>( &self, user_id: &UserId, public_keys: PublicKeys, ) -> SmallVec<[MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>; 3]> ⓘ
where PublicKeys: Iterator<Item = &'a str> + Send,

Locks one user’s cross-signing key rows, named by their public keys.

The rows are taken in one order for every caller, so writers sharing rows wait for one another instead of deadlocking.

Source§

impl Service

Source

fn put_cross_signing_keys( &self, user_id: &UserId, keys: &[(&'_ Raw<CrossSigningKey>, String, &'_ Arc<Map>)], )

Writes cross-signing keys at their rows and points the user at each.

Each row is keyed by user and public key, and the keys and pointers are written in one transaction.

Source§

impl Service

Source

pub async fn sign_key( &self, target_id: &UserId, key_id: &str, signatures: SmallVec<[(String, String); 1]>, sender_id: &UserId, ) -> Result

Merges the sender’s signatures into a stored key after verifying them.

A signature the signer’s and the target’s roles do not allow is ignored or refused, the call fails unless one is accepted, and a merge changing nothing writes nothing. The read and the write hold the key’s row lock, so concurrent merges keep one another’s signatures and never write stale contents over a key replaced or removed meanwhile.

Source§

impl Service

Source

async fn lock_key( &self, user_id: &UserId, key_id: &str, ) -> MutexMapGuard<(OwnedUserId, OwnedDeviceId), ()>

Locks one key row against its other writers.

Device and cross-signing keys share one row space keyed by user and key ID, so the device lock serves both, and a device’s removal and every write to its keys contend on that one lock.

Source§

impl Service

Source

async fn uploaded_key_role( &self, user_id: &UserId, key_id: &str, ) -> Result<Option<KeyRole>>

Source§

impl Service

Source

pub(super) async fn is_cross_signing_key_id( &self, user_id: &UserId, key_id: &str, ) -> Result<bool>

Source§

impl Service

Source

async fn cross_signing_pointers( &self, user_id: &UserId, row_key: &[u8], ) -> Result<[bool; 3]>

Source§

impl Service

Source

async fn verify_key_signature( &self, sender_id: &UserId, key_id: &SigningKeyId<AnyKeyName>, role: KeyRole, signature: &str, canonical: &[u8], ) -> Result<Base64>

Source§

impl Service

Source

pub fn keys_changed<'a>( &'a self, user_id: &'a UserId, from: u64, to: Option<u64>, ) -> impl Stream<Item = &UserId> + Send + 'a

Source§

impl Service

Source

pub fn room_keys_changed<'a>( &'a self, room_id: &'a RoomId, from: u64, to: Option<u64>, ) -> impl Stream<Item = (&UserId, u64)> + Send + 'a

Source§

impl Service

Source

fn keys_changed_user_or_room<'a>( &'a self, user_or_room_id: &'a str, from: u64, to: Option<u64>, ) -> impl Stream<Item = (&UserId, u64)> + Send + 'a

Source§

impl Service

Source

pub async fn mark_device_key_update( &self, user_id: &UserId, change: DeviceListChange<&DeviceId>, )

Records a device-list change for a user and pushes it to interested peers.

The change is durable before any peer is contacted, and the unbounded sender channels refuse only once closed, so a refused flush is a shutdown race rather than a fault.

Source§

impl Service

Source

pub async fn device_list_change(&self, count: u64) -> Result<DeviceListRecord>

Reads the mutation recorded for a local device-list notification.

Missing records return NotFound; unknown kind tags request a snapshot resync.

Source§

impl Service

Source

pub async fn get_device_keys<'a>( &'a self, user_id: &'a UserId, device_id: &DeviceId, ) -> Result<Raw<DeviceKeys>>

Source§

impl Service

Source

pub async fn get_key<F>( &self, row_key: &[u8], sender_user: Option<&UserId>, user_id: &UserId, allowed_signatures: &F, ) -> Result<Raw<CrossSigningKey>>
where F: Fn(&UserId) -> bool + Send + Sync,

Reads the cross-signing key stored at one row of the key table.

row_key is the serialized user ID and public key naming the row, the form the user’s pointer rows store, never a key ID. The sender sees every signature on their own key; anyone else sees only the owner’s and those allowed_signatures accepts.

Source§

impl Service

Source

pub async fn get_master_key<F>( &self, sender_user: Option<&UserId>, user_id: &UserId, allowed_signatures: &F, ) -> Result<Raw<CrossSigningKey>>
where F: Fn(&UserId) -> bool + Send + Sync,

Reads a user’s master key through its pointer row.

An absent pointer errs as not found. Signatures narrow as in get_key.

Source§

impl Service

Source

pub async fn get_self_signing_key<F>( &self, sender_user: Option<&UserId>, user_id: &UserId, allowed_signatures: &F, ) -> Result<Raw<CrossSigningKey>>
where F: Fn(&UserId) -> bool + Send + Sync,

Reads a user’s self-signing key through its pointer row.

An absent pointer errs as not found. Signatures narrow as in get_key.

Source§

impl Service

Source

pub async fn get_user_signing_key( &self, user_id: &UserId, ) -> Result<Raw<CrossSigningKey>>

Reads a user’s user-signing key through its pointer row.

An absent pointer errs as not found. The stored signatures come back whole, unlike the master and self-signing readers.

Source§

impl Service

Source

pub async fn search_ldap(&self, user_id: &UserId) -> Result<Vec<(String, bool)>>

Performs a LDAP search for the given user.

Returns the list of matching users, with a boolean for each result set to true if the user is an admin.

Source§

impl Service

Source

pub async fn auth_ldap(&self, user_dn: &str, password: &str) -> Result

Source§

impl Service

Source

async fn ldap_connect(&self, principal: &str) -> Result<(JoinHandle<()>, Ldap)>

Source§

impl Service

Source

pub fn ldap_bind_dn(&self, localpart: &str) -> Option<String>

Builds the user bind DN by substituting the escaped localpart into the configured bind_dn template, or None when no {username} template is set.

Source§

impl Service

Source

pub async fn full_register(&self, __arg1: Register<'_>) -> Result

Fully register a local user

Returns a device id and access token for the registered user

Source§

impl Service

Source

pub async fn validate_server_user(&self) -> Result

Rejects changes to the server identity recorded by an existing database.

The localpart is stamped on the first boot and compared exactly afterwards. A database from before the stamp is backfilled from its admin room.

Source§

impl Service

Source

async fn backfill_server_user(&self, configured: &str) -> Result

Stamps the identity on a database that pre-dates SERVER_USER_KEY.

Membership of the admin room establishes the identity, or an empty user table when there is no admin room; room creation does not, since a rebuilt admin room has a human creator. The legacy identity otherwise boots unstamped and any other is refused. A read-only database is validated but never stamped.

Source§

impl Service

Source

async fn admin_room_joined(&self) -> Result<Option<bool>>

Reports whether the server user is joined to the admin room, or nothing without an admin alias.

An unjoined server user also means admin commands cannot work.

Source§

impl Service

Source

pub async fn user_is_ignored( &self, sender_user: &UserId, recipient_user: &UserId, ) -> bool

Returns true/false based on whether the recipient/receiving user has blocked the sender

Source

pub async fn ignored_users( &self, user_id: &UserId, ) -> Option<IgnoredUserListEventContent>

The users a user ignores account-wide.

Callers testing one list against many users take this rather than Self::user_is_ignored, which re-reads the list per test.

Source

pub async fn create( &self, user_id: &UserId, password: Option<&str>, origin: Option<&str>, ) -> Result

Create a new user account on this homeserver.

User origin is by default “password” (meaning that it will login using its user_id/password). Users with other origins (currently only “ldap” is available) have special login processes.

Source

pub async fn check_creation(&self, user_id: &UserId) -> Result

Refuses a local user ID that once joined the admin room but has no account.

Refusals return M_USER_IN_USE and log the user ID without changing account or membership state. Existing accounts and the server user remain eligible.

Source

pub async fn deactivate_account(&self, user_id: &UserId) -> Result

Deactivate account

Source

pub async fn exists(&self, user_id: &UserId) -> bool

Check if a user has an account on this homeserver.

Source

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

Check if account is deactivated

Source

pub async fn is_active(&self, user_id: &UserId) -> bool

Check if account is active, infallible

Source

pub async fn is_active_local(&self, user_id: &UserId) -> bool

Check if account is active, infallible

Source

pub async fn is_guest(&self, user_id: &UserId) -> bool

Whether the account is a guest; a missing or unreadable one is not.

Guests share the empty password marker with the passwordless users an appservice registers. A user in an appservice’s exclusive namespace, or the appservice’s own sender, belongs to that appservice and is never a guest, whatever token it acts with.

Source

pub async fn check_ldap_login(&self, user_id: &UserId) -> Result

Gate an LDAP-authenticated login into an existing local account.

Only a deactivated account is rejected. A password-origin account passes, since a successful bind establishes the caller’s identity however their account was created, and a localpart with no local account passes on its way to registration.

Source

pub async fn deactivated_check(&self, user_id: &UserId) -> Result

Reject a deactivated account with 403 M_USER_DEACTIVATED.

An account that does not exist is not deactivated, as in Synapse. One created without a password, as an appservice’s users often are, reads as deactivated, since both store an empty password.

Source

pub async fn is_suspended(&self, user_id: &UserId) -> bool

MSC3823: account is suspended (read-mostly mode, sessions retained).

Source

pub async fn locked_check(&self, user_id: &UserId) -> Result

MSC3939: reject a request from a locked account.

The rejection maps to 401 M_USER_LOCKED with soft_logout: true, so the client retains its session and polls for the unlock. The login and refresh routes and the request middleware share this gate.

Source

pub async fn is_locked(&self, user_id: &UserId) -> bool

MSC3939: account is locked (401 + soft_logout, sessions retained).

The row’s presence is the entire state, and locking never invalidates access tokens, so clearing the row restores every session intact. Both locked_check and the admin lock surfaces read it.

Source

pub async fn is_erased(&self, user_id: &UserId) -> bool

MSC4025: the user’s events serve as pruned copies to recipients not joined at the event. Presence-only for the serving gate.

Source

pub async fn erasure_count(&self, user_id: &UserId) -> Option<PduCount>

MSC4025: the global count recorded at erasure, for admin surfacing; the serving gate never reads it.

Source

pub async fn get_suspension(&self, user_id: &UserId) -> Option<Moderation>

MSC3823: forensic record for the active suspension, if any.

Source

pub async fn get_lock(&self, user_id: &UserId) -> Option<Moderation>

MSC3939: forensic record for the active lock, if any.

Source

pub fn set_suspended(&self, user_id: &UserId, by: &UserId)

Source

pub fn clear_suspended(&self, user_id: &UserId)

Source

pub fn set_erased(&self, user_id: &UserId)

MSC4025: mark the user erased, recording the current global count.

Source

pub fn clear_erased(&self, user_id: &UserId)

MSC4025: erasure is reversible; clearing the marker restores the unredacted view.

Source

pub fn set_locked(&self, user_id: &UserId, by: &UserId)

Source

pub fn clear_locked(&self, user_id: &UserId)

Source

pub async fn count(&self) -> usize

Returns the number of users registered on this server.

Source

pub async fn is_empty(&self) -> Result<bool>

Returns whether the user table contains no accounts.

The lookup stops after the first account and propagates storage errors.

Source

pub fn stream(&self) -> impl Stream<Item = &UserId> + Send

Returns an iterator over all users on this homeserver.

Source

pub fn list_local_users(&self) -> impl Stream<Item = &UserId> + Send + '_

Returns a list of local users as list of usernames.

A user account is considered local if the length of it’s password is greater then zero.

Source

pub async fn origin(&self, user_id: &UserId) -> Result<String>

Returns the origin of the user (password/LDAP/…).

Source

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

Returns whether the user has a password. Disabled accounts and registrations setting a sentinel password will return false here.

Source

pub async fn password_hash(&self, user_id: &UserId) -> Result<String>

Returns the password hash for the given user.

Source

pub async fn set_password( &self, user_id: &UserId, password: Option<&str>, ) -> Result

Hashes and stores the user’s password.

A real password is hashed at the configured Argon2id cost and marks the account as password-origin. None stores the disabled marker and the sentinel is stored verbatim; neither is hashed. Changing the password of an account whose origin is neither password nor SSO is rejected. Setting a password or the sentinel first ends the user’s browser sessions, and failing to end them fails the call; disabling leaves them to be refused at use.

Source

pub async fn set_password_if_active( &self, user_id: &UserId, password: Option<&str>, ) -> Result

Changes the password only while the account is active.

The active-state check and password write are serialized with account deactivation for this user.

Source

pub fn create_filter( &self, user_id: &UserId, filter: &FilterDefinition, ) -> String

Creates a new sync filter. Returns the filter id.

Source

pub async fn get_filter( &self, user_id: &UserId, filter_id: &str, ) -> Result<FilterDefinition>

Source

pub fn create_openid_token(&self, user_id: &UserId, token: &str) -> Result<u64>

Creates an OpenID token, which can be used to prove that a user has access to an account (primarily for integrations)

Source

pub async fn find_from_openid_token(&self, token: &str) -> Result<OwnedUserId>

Find out which user an OpenID access token belongs to.

Source

pub fn create_login_token(&self, user_id: &UserId, token: &str) -> u64

Creates a short-lived login token, which can be used to log in using the m.login.token mechanism.

Source

pub fn create_login_token_with_provider( &self, user_id: &UserId, token: &str, idp_id: Option<&str>, ) -> u64

Creates a short-lived login token carrying authenticated SSO provenance.

Native authentication passes no provider. SSO callers preserve the provider selected in the server-side SSO session.

Source

pub async fn peek_login_token(&self, token: &str) -> Result<OwnedUserId>

Verify a login token is valid and return its owner without consuming it. Unlike find_from_login_token, the token remains in the database after this call and can still be consumed later.

Source

pub async fn peek_login_token_with_provider( &self, token: &str, ) -> Result<LoginToken>

Verify a login token and its provider without consuming it.

The token remains available for the later consent submission.

Source

pub async fn find_from_login_token(&self, token: &str) -> Result<OwnedUserId>

Find out which user a login token belongs to. Removes the token to prevent double-use attacks.

Source

pub async fn find_login_token_with_provider( &self, token: &str, ) -> Result<LoginToken>

Consume a login token and return its owner and authenticated provider.

The token is removed before its authenticated identity is returned.

Source§

impl Service

Source

async fn set_password_if_active_after( &self, user_id: &UserId, password: Option<&str>, after_check: impl Future<Output = ()>, ) -> Result

Source§

impl Service

Source

async fn set_password_locked( &self, user_id: &UserId, password: Option<&str>, ) -> Result

Trait Implementations§

Source§

impl Service for Service

Source§

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.
Source§

fn name(&self) -> &str

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

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.
Source§

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.
Source§

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.
Source§

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.
Source§

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.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> DropFlavorWrapper<T> for T

§

type Flavor = MayDrop

The DropFlavor that [wrap]s T into Self
Source§

impl<T> ExpectInto for T

Source§

fn expect_into<Dst>(self) -> Dst
where Dst: TryFrom<Self>, Self: Sized,

Converts the value into Dst and returns the successful result. Read more
Source§

impl<T> Expected for T

Source§

fn expected_add(self, rhs: Self) -> Self
where Self: Sized + CheckedAdd,

Adds rhs with an expectation that the operation is valid. Read more
Source§

fn expected_sub(self, rhs: Self) -> Self
where Self: Sized + CheckedSub,

Subtracts rhs with an expectation that the operation is valid. Read more
Source§

fn expected_mul(self, rhs: Self) -> Self
where Self: Sized + CheckedMul,

Multiplies by rhs with an expectation that the operation is valid. Read more
Source§

fn expected_div(self, rhs: Self) -> Self
where Self: Sized + CheckedDiv,

Divides by rhs with an expectation that the operation is valid. Read more
Source§

fn expected_rem(self, rhs: Self) -> Self
where Self: Sized + CheckedRem,

Computes the remainder with an expectation that the operation is valid. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

§

const WITNESS: W = W::MAKE

A constant of the type witness
§

impl<T> Identity for T
where T: ?Sized,

§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> JsonCastable<CanonicalJsonValue> for T

§

impl<T> JsonCastable<Value> for T

§

impl<T> Paint for T
where T: ?Sized,

§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Primary].

§Example
println!("{}", value.primary());
§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Fixed].

§Example
println!("{}", value.fixed(color));
§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Rgb].

§Example
println!("{}", value.rgb(r, g, b));
§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Black].

§Example
println!("{}", value.black());
§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Red].

§Example
println!("{}", value.red());
§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Green].

§Example
println!("{}", value.green());
§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Yellow].

§Example
println!("{}", value.yellow());
§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Blue].

§Example
println!("{}", value.blue());
§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Magenta].

§Example
println!("{}", value.magenta());
§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Cyan].

§Example
println!("{}", value.cyan());
§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: White].

§Example
println!("{}", value.white());
§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlack].

§Example
println!("{}", value.bright_black());
§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightRed].

§Example
println!("{}", value.bright_red());
§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightGreen].

§Example
println!("{}", value.bright_green());
§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightYellow].

§Example
println!("{}", value.bright_yellow());
§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlue].

§Example
println!("{}", value.bright_blue());
§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.bright_magenta());
§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightCyan].

§Example
println!("{}", value.bright_cyan());
§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightWhite].

§Example
println!("{}", value.bright_white());
§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Primary].

§Example
println!("{}", value.on_primary());
§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Fixed].

§Example
println!("{}", value.on_fixed(color));
§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Rgb].

§Example
println!("{}", value.on_rgb(r, g, b));
§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Black].

§Example
println!("{}", value.on_black());
§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Red].

§Example
println!("{}", value.on_red());
§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Green].

§Example
println!("{}", value.on_green());
§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Yellow].

§Example
println!("{}", value.on_yellow());
§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Blue].

§Example
println!("{}", value.on_blue());
§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Magenta].

§Example
println!("{}", value.on_magenta());
§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Cyan].

§Example
println!("{}", value.on_cyan());
§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: White].

§Example
println!("{}", value.on_white());
§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlack].

§Example
println!("{}", value.on_bright_black());
§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightRed].

§Example
println!("{}", value.on_bright_red());
§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightGreen].

§Example
println!("{}", value.on_bright_green());
§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightYellow].

§Example
println!("{}", value.on_bright_yellow());
§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlue].

§Example
println!("{}", value.on_bright_blue());
§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.on_bright_magenta());
§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightCyan].

§Example
println!("{}", value.on_bright_cyan());
§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightWhite].

§Example
println!("{}", value.on_bright_white());
§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling [Attribute] value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Bold].

§Example
println!("{}", value.bold());
§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Dim].

§Example
println!("{}", value.dim());
§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Italic].

§Example
println!("{}", value.italic());
§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Underline].

§Example
println!("{}", value.underline());

Returns self with the attr() set to [Attribute :: Blink].

§Example
println!("{}", value.blink());

Returns self with the attr() set to [Attribute :: RapidBlink].

§Example
println!("{}", value.rapid_blink());
§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Invert].

§Example
println!("{}", value.invert());
§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Conceal].

§Example
println!("{}", value.conceal());
§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Strike].

§Example
println!("{}", value.strike());
§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi [Quirk] value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Mask].

§Example
println!("{}", value.mask());
§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Wrap].

§Example
println!("{}", value.wrap());
§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Linger].

§Example
println!("{}", value.linger());
§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1:

renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to [Quirk :: Clear].

§Example
println!("{}", value.clear());
§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Resetting].

§Example
println!("{}", value.resetting());
§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Bright].

§Example
println!("{}", value.bright());
§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: OnBright].

§Example
println!("{}", value.on_bright());
§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the [Condition] value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new [Painted] with a default [Style]. Read more
§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn add_extension<T>(self, value: T) -> AddExtension<Self, T>
where Self: Sized,

Add some shareable value to request extensions. Read more
§

fn compression(self) -> Compression<Self>
where Self: Sized,

Compresses response bodies. Read more
§

fn decompression(self) -> Decompression<Self>
where Self: Sized,

Decompress response bodies. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
§

fn sensitive_headers( self, headers: impl IntoIterator<Item = HeaderName>, ) -> SetSensitiveRequestHeaders<SetSensitiveResponseHeaders<Self>>
where Self: Sized,

Mark headers as sensitive on both requests and responses. Read more
§

fn sensitive_request_headers( self, headers: impl IntoIterator<Item = HeaderName>, ) -> SetSensitiveRequestHeaders<Self>
where Self: Sized,

Mark headers as sensitive on requests. Read more
§

fn sensitive_response_headers( self, headers: impl IntoIterator<Item = HeaderName>, ) -> SetSensitiveResponseHeaders<Self>
where Self: Sized,

Mark headers as sensitive on responses. Read more
§

fn override_request_header<M>( self, header_name: HeaderName, make: M, ) -> SetRequestHeader<Self, M>
where Self: Sized,

Insert a header into the request. Read more
§

fn append_request_header<M>( self, header_name: HeaderName, make: M, ) -> SetRequestHeader<Self, M>
where Self: Sized,

Append a header into the request. Read more
§

fn insert_request_header_if_not_present<M>( self, header_name: HeaderName, make: M, ) -> SetRequestHeader<Self, M>
where Self: Sized,

Insert a header into the request, if the header is not already present. Read more
§

fn override_response_header<M>( self, header_name: HeaderName, make: M, ) -> SetResponseHeader<Self, M>
where Self: Sized,

Insert a header into the response. Read more
§

fn append_response_header<M>( self, header_name: HeaderName, make: M, ) -> SetResponseHeader<Self, M>
where Self: Sized,

Append a header into the response. Read more
§

fn insert_response_header_if_not_present<M>( self, header_name: HeaderName, make: M, ) -> SetResponseHeader<Self, M>
where Self: Sized,

Insert a header into the response, if the header is not already present. Read more
§

fn catch_panic(self) -> CatchPanic<Self, DefaultResponseForPanic>
where Self: Sized,

Catch panics and convert them into 500 Internal Server responses. Read more
Source§

impl<T> Tried for T

Source§

fn try_add(self, rhs: Self) -> Result<Self, Error>
where Self: Sized + CheckedAdd,

Adds rhs with checked arithmetic. Read more
Source§

fn try_sub(self, rhs: Self) -> Result<Self, Error>
where Self: Sized + CheckedSub,

Subtracts rhs with checked arithmetic. Read more
Source§

fn try_mul(self, rhs: Self) -> Result<Self, Error>
where Self: Sized + CheckedMul,

Multiplies by rhs with checked arithmetic. Read more
Source§

fn try_div(self, rhs: Self) -> Result<Self, Error>
where Self: Sized + CheckedDiv,

Divides by rhs with checked arithmetic. Read more
Source§

fn try_rem(self, rhs: Self) -> Result<Self, Error>
where Self: Sized + CheckedRem,

Computes the remainder by rhs with checked arithmetic. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more