Struct Service 

pub struct Service {
    appservice_in_room_cache: RwLock<HashMap<OwnedRoomId, HashMap<String, bool>>>,
    services: Arc<OnceServices>,
    db: Data,
}

Persistent room-membership cache and derived-index service.

Paired indexes answer membership queries in either direction, while room aggregates track counts and participating servers. A process-local cache memoizes appservice membership decisions.

Fields

appservice_in_room_cache: RwLock<HashMap<OwnedRoomId, HashMap<String, bool>>>

services: Arc<OnceServices>

db: Data

Implementations

impl Service

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

Applies one membership transition to the derived cache indexes.

Remote users are created before their transition is recorded, and paired forward and reverse rows change together. Joins can copy predecessor-room account data, while leaves can trigger push-badge refresh and configured forget behavior. Aggregate room counts are rebuilt only when requested by the update descriptor.

impl Service

pub async fn update_joined_count(&self, room_id: &RoomId)

Rebuilds a room’s aggregate membership and server indexes.

Current join, invite, and knock rows are counted, and participating servers are reconciled in one database transaction. Source-stream errors are skipped, and the room’s appservice membership cache is invalidated after the transaction executes.

impl Service

fn joined_count<'a>( &'a self, room_id: &'a RoomId, ) -> impl Future<Output = (u64, HashSet<OwnedServerName>)> + Send + 'a

impl Service

pub(crate) fn mark_as_joined( &self, user_id: &UserId, room_id: &RoomId, count: PduCount, )

Writes the paired indexes for a current join transition.

Invite, leave, and knock rows for the same user and room are removed in the same transaction. This low-level helper skips once-joined bookkeeping, predecessor copying, and aggregate rebuilding performed by super::Service::update_membership.

impl Service

pub(crate) fn mark_as_left( &self, user_id: &UserId, room_id: &RoomId, count: PduCount, )

Writes the paired indexes for a current leave transition.

The leave state starts as an empty event array, and join, invite, and knock rows are removed in the same transaction. This low-level helper skips leave policy and aggregate rebuilding performed by super::Service::update_membership.

impl Service

pub(crate) fn mark_as_knocked( &self, user_id: &UserId, room_id: &RoomId, count: PduCount, knocked_state: StrippedRoomState, )

Writes the paired indexes for a current knock transition.

Missing stripped state is stored as an empty array, and join, invite, and leave rows are removed in the same transaction. This low-level helper skips aggregate rebuilding performed by super::Service::update_membership.

impl Service

pub fn forget(&self, room_id: &RoomId, user_id: &UserId)

Forgets a user’s retained leave state for a room.

Only the paired leave rows are deleted; once-joined history and other room data remain untouched. Without a separate forget marker, absence of these rows is the durable forgotten state.

impl Service

fn mark_as_once_joined(&self, user_id: &UserId, room_id: &RoomId)

impl Service

pub(crate) async fn mark_as_invited( &self, user_id: &UserId, room_id: &RoomId, count: PduCount, last_state: StrippedRoomState, invite_via: Option<Vec<OwnedServerName>>, ) -> Result

Writes the paired indexes for a current invite transition.

Missing or empty stripped state preserves an existing nonempty invite row, while a new state replaces it. Nonempty routing hints are merged into the room’s aggregate hint row and committed with the membership indexes; other membership rows are removed in the same transaction.

impl Service

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

impl Service

async fn handle_join( &self, room_id: &RoomId, user_id: &UserId, count: PduCount, ) -> Result

impl Service

async fn copy_predecessor_data( &self, room_id: &RoomId, user_id: &UserId, ) -> Result

impl Service

async fn copy_predecessor_tags( &self, room_id: &RoomId, user_id: &UserId, predecessor: &RoomId, )

impl Service

async fn copy_predecessor_direct( &self, room_id: &RoomId, user_id: &UserId, predecessor: &RoomId, ) -> Result

impl Service

async fn handle_leave( &self, room_id: &RoomId, user_id: &UserId, count: PduCount, )

impl Service

pub(crate) async fn add_servers_invite_via( &self, txn: &mut Txn, room_id: &RoomId, servers: Vec<OwnedServerName>, )

Merges invitation routing hints into the caller’s membership transaction.

The existing reader exposes only the aggregate row’s final server, so older hints before that tail are not retained by this rewrite. Concurrent callers are not serialized and can overwrite one another’s read-modify-write result.

impl Service

pub async fn servers_route_via( &self, room_id: &RoomId, ) -> Result<Vec<OwnedServerName>>

Selects up to five servers likely to remain useful for room routing.

The highest-power user’s server is considered first, followed by servers in descending joined-user count. The two sources are not deduplicated, and a missing power-level event simply omits the first candidate.

See https://spec.matrix.org/latest/appendices/#routing.

impl Service

pub async fn most_powerful_user_server( &self, room_id: &RoomId, ) -> Option<OwnedServerName>

Returns the highest-power user’s server when its level is at least 50.

Missing, unreadable, or malformed power-level state returns None. Equal-power ties follow the underlying users map’s iteration order.

impl Service

pub async fn popular_servers(&self, room_id: &RoomId) -> Vec<OwnedServerName>

Returns participating servers ordered by descending joined-user count.

Joined members are counted per server and the resulting servers are sorted. Read failures skipped by the membership stream can reduce the observed counts, and equal-count ordering is unspecified.

impl Service

pub fn servers_invite_via<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &ServerName> + Send + 'a

Streams the final routing hint from each matching aggregate row.

The current room-keyed representation stores several servers in one value, but this accessor exposes only the last decoded server and therefore at most one item per room. Storage and decoding failures are skipped. Yielded names borrow the cursor and are invalid after the next poll; consume or own each item before advancing.

impl Service

pub async fn appservice_in_room( &self, room_id: &RoomId, appservice: &RegistrationInfo, ) -> bool

Tests whether an appservice participates in a room.

A registration participates when its sender or a namespace-matching user is joined. Results are memoized by room and registration identifier. Membership rebuilds and explicit clears remove cached entries, but do not fence an in-flight lookup from republishing an older result. Deleting a room’s membership indexes does not invalidate this cache.

impl Service

pub fn get_appservice_in_room_cache_usage(&self) -> (usize, usize)

Returns the appservice membership cache’s room count and capacity.

The first value counts room-level map entries rather than individual registrations. The second reports the backing map’s current allocation capacity.

impl Service

pub fn clear_appservice_in_room_cache(&self)

Clears every memoized appservice membership decision.

Persistent membership indexes are not changed. Later uncached lookups recompute and cache their answers from current joined membership, but a lookup already in flight can republish an older result after the clear.

impl Service

pub fn remote_room_servers<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &ServerName> + Send + 'a

Returns a stream of the remote servers participating in this room.

Our own server is filtered out, so the result is the federation fan-out set for the room. Items borrow the database cursor and are invalid after the next poll; consume or own each item before advancing. Storage errors are skipped as in Self::room_servers.

impl Service

pub fn room_servers<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &ServerName> + Send + 'a

Streams all servers recorded as participating in a room.

Storage and key-decoding failures are skipped. Each server name borrows the cursor and must be consumed or owned before the stream advances.

impl Service

pub async fn server_in_room<'a>( &'a self, server: &'a ServerName, room_id: &'a RoomId, ) -> bool

Tests whether a server is recorded as participating in a room.

The reverse server-to-room index supplies the answer. Missing rows and storage failures both return false.

impl Service

pub fn server_rooms<'a>( &'a self, server: &'a ServerName, ) -> impl Stream<Item = &RoomId> + Send + 'a

Streams all rooms recorded for a participating server.

Storage and key-decoding failures are skipped. Each room identifier borrows the cursor and must be consumed or owned before the stream advances.

impl Service

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

Streams each server participating in at least one known room.

Adjacent duplicate prefixes are collapsed, yielding server names in ascending key order. Storage and decoding failures are skipped, and each item borrows the cursor until its next poll.

impl Service

pub async fn server_shares_room(&self, server: &ServerName) -> bool

Tests whether a server participates in any known room.

The check stops at the first reverse-index row. Errors skipped by Self::server_rooms are indistinguishable from absence.

impl Service

pub async fn server_sees_user( &self, server: &ServerName, user_id: &UserId, ) -> bool

Tests whether a server shares a joined room with a user.

The check searches rooms recorded for the server for any current user join. Index errors are treated as absent rows by the underlying helpers.

impl Service

pub async fn user_sees_user(&self, user_a: &UserId, user_b: &UserId) -> bool

Tests whether two users share a currently joined room.

The check consumes only the first intersection result. Storage or decoding failures skipped by the joined-room streams can produce false.

impl Service

pub fn get_shared_rooms<'a>( &'a self, user_a: &'a UserId, user_b: &'a UserId, ) -> impl Stream<Item = &RoomId> + Send + 'a

Streams rooms in which both users are currently joined.

The two key-ordered joined-room streams are intersected without materializing either set. Items borrow their source database cursor and are invalid after the next poll; consume or own each item before advancing. Read failures are skipped by the source streams.

impl Service

pub fn room_members<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams all users currently indexed as joined to a room.

Storage and key-decoding failures are skipped. Each user identifier borrows the cursor and must be consumed or owned before the stream advances.

impl Service

pub fn room_members_checked<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = Result<&'a UserId>> + Send + 'a

Streams joined users within the room’s exact encoded prefix.

Storage and user-key decoding failures are surfaced as error items rather than dropped. User IDs borrow the cursor and must be consumed or owned before advancing it.

impl Service

pub async fn room_joined_count(&self, room_id: &RoomId) -> Result<u64>

Returns the stored number of users currently joined to a room.

The aggregate is rebuilt from membership indexes by Self::update_joined_count. Missing or malformed count rows return an error.

impl Service

pub async fn room_invited_count(&self, room_id: &RoomId) -> Result<u64>

Returns the stored number of users currently invited to a room.

The aggregate is rebuilt from membership indexes by Self::update_joined_count. Missing or malformed count rows return an error.

impl Service

pub async fn room_knocked_count(&self, room_id: &RoomId) -> Result<u64>

Returns the stored number of users currently knocking on a room.

The aggregate is rebuilt from membership indexes by Self::update_joined_count. Missing or malformed count rows return an error.

impl Service

pub fn active_local_users_in_room<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams active local users currently joined to a room.

Local joined users are filtered through the user service, excluding guests and deactivated accounts. The stream otherwise inherits Self::room_members’s cursor lifetime and error policy.

impl Service

pub fn local_users_in_room<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams all local users currently joined to a room.

Guest and deactivated accounts remain included. The stream otherwise inherits Self::room_members’s cursor lifetime and error policy.

impl Service

pub fn local_users_invited_to_room<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams local users currently invited to a room.

Remote invitees are filtered out by server name. The stream otherwise inherits Self::room_members_invited’s cursor lifetime and error policy.

impl Service

pub fn room_useroncejoined<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams user identifiers from the once-joined index under a room prefix.

Once-joined rows are currently written with user-first keys, while this accessor probes a room-first prefix, so the stored layout can yield no matches. Yielded user identifiers borrow the database cursor and are invalid after the next poll; consume or own each item before advancing. Storage and decoding failures are skipped.

impl Service

pub fn room_members_invited<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams all users currently indexed as invited to a room.

Storage and key-decoding failures are skipped. Each user identifier borrows the cursor and must be consumed or owned before the stream advances.

impl Service

pub fn room_members_knocked<'a>( &'a self, room_id: &'a RoomId, ) -> impl Stream<Item = &UserId> + Send + 'a

Streams all users currently indexed as knocking on a room.

Storage and key-decoding failures are skipped. Each user identifier borrows the cursor and must be consumed or owned before the stream advances.

impl Service

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

Returns the stream position associated with a user’s current invite.

This value identifies the membership transition rather than counting invitations. Missing or malformed index rows return an error.

impl Service

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

Returns the stream position associated with a user’s current knock.

This value identifies the membership transition rather than counting knocks. Missing or malformed index rows return an error.

impl Service

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

Returns the stream position associated with a user’s current leave row.

This value identifies the membership transition rather than counting leaves. Missing or malformed index rows return an error.

impl Service

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

Returns the stream position associated with a user’s current join.

This value identifies the membership transition rather than counting joins. A join recorded before positions were stored holds an empty value and reads as zero. Missing or malformed index rows return an error.

impl Service

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

Streams every cached membership category for a user.

Join, leave, invite, and knock indexes are combined without a global ordering guarantee. Yielded room identifiers borrow their source database cursor and are invalid after the next poll; consume or own each item before advancing. Source-stream errors are skipped.

impl Service

pub fn user_memberships<'a>( &'a self, user_id: &'a UserId, mask: Option<&[MembershipState]>, ) -> impl Stream<Item = (MembershipState, &RoomId)> + Send + 'a

Streams selected cached membership categories for a user.

A missing mask selects join, leave, invite, and knock; an empty mask selects none. Category streams are interleaved without a global ordering guarantee, and their storage errors are skipped. Yielded room identifiers borrow their source database cursor and are invalid after the next poll; consume or own each item before advancing.

impl Service

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

Streams rooms in which a user is currently indexed as joined.

The raw user prefix preserves the established key scan. Storage and decoding failures are skipped, and each room identifier borrows the cursor until its next poll.

impl Service

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

Streams joined rooms within the user’s exact encoded prefix.

Storage and room-key decoding failures are surfaced as error items rather than dropped. Room IDs borrow the cursor and must be consumed or owned before advancing it.

impl Service

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

Streams rooms in which a user is currently indexed as invited.

The raw user prefix preserves the established key scan. Storage and decoding failures are skipped, and each room identifier borrows the cursor until its next poll.

impl Service

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

Streams rooms in which a user is currently indexed as knocking.

The raw user prefix preserves the established key scan. Storage and decoding failures are skipped, and each room identifier borrows the cursor until its next poll.

impl Service

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

Streams rooms for which a user’s leave state is retained.

Forgotten rooms have no leave row and therefore do not appear. Storage and decoding failures are skipped, and each room identifier borrows the cursor until its next poll.

impl Service

pub fn rooms_invited_state<'a>( &'a self, user_id: &'a UserId, ) -> impl Stream<Item = (OwnedRoomId, Vec<Raw<AnyStrippedStateEvent>>)> + Send + 'a

Streams stored stripped state for a user’s current invitations.

Each item owns its room identifier and decoded state vector. Storage, key-decoding, and state-deserialization failures are skipped.

impl Service

pub fn rooms_knocked_state<'a>( &'a self, user_id: &'a UserId, ) -> impl Stream<Item = (OwnedRoomId, Vec<Raw<AnyStrippedStateEvent>>)> + Send + 'a

Streams stored stripped state for a user’s current knocks.

Each item owns its room identifier and decoded state vector. Storage, key-decoding, and state-deserialization failures are skipped.

impl Service

pub fn rooms_left_state<'a>( &'a self, user_id: &'a UserId, ) -> impl Stream<Item = (OwnedRoomId, Vec<Raw<AnySyncStateEvent>>)> + Send + 'a

Streams stored state for rooms a user has left but not forgotten.

Both native state arrays and compatible single-event rows are accepted. Storage and key-decoding failures are skipped, while unusable state values yield an empty event vector for their room.

impl Service

pub async fn invite_state( &self, user_id: &UserId, room_id: &RoomId, ) -> Result<Vec<Raw<AnyStrippedStateEvent>>>

Returns the stripped state stored for a user’s current invitation.

The value is decoded as an array of stripped state events. Missing rows, storage failures, and malformed state return an error.

impl Service

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

Whether the user’s stored invite carries any stripped state.

The row is probed raw rather than decoded through Self::invite_state, so no stripped state is materialized to answer it. A failed read is an error rather than an absent row.

impl Service

pub async fn knock_state( &self, user_id: &UserId, room_id: &RoomId, ) -> Result<Vec<Raw<AnyStrippedStateEvent>>>

Returns the stripped state stored for a user’s current knock.

The value is decoded as an array of stripped state events. Missing rows, storage failures, and malformed state return an error.

impl Service

pub async fn left_state( &self, user_id: &UserId, room_id: &RoomId, ) -> Result<Vec<Raw<AnyStrippedStateEvent>>>

Returns the cached state for a room a user has left.

Native state arrays and compatible single-event rows are normalized into one vector. Missing or unreadable rows return an error, while an unusable stored JSON shape is logged and becomes an empty vector.

impl Service

pub async fn user_membership( &self, user_id: &UserId, room_id: &RoomId, ) -> Option<MembershipState>

Infers a user’s cached membership state for one room.

Current indexes take precedence in join, leave, knock, then invite order. When none exists, a once-joined marker is reported as Ban; no marker returns None. Read failures from the boolean probes are treated as absence.

impl Service

pub async fn once_joined(&self, user_id: &UserId, room_id: &RoomId) -> bool

Tests whether a user has ever been marked as joined to a room.

The durable marker survives later membership transitions and explicit forget operations. Missing rows and storage failures both return false.

impl Service

pub async fn is_joined_any<'a, Rooms>( &self, user_id: &UserId, room_ids: Rooms, ) -> bool

where Rooms: IntoIterator<Item = &'a RoomId> + Send, Rooms::IntoIter: Send,

Tests whether a user is currently joined to any of the given rooms.

The rooms are probed concurrently and the first joined room decides the answer; an empty set of rooms answers false. A probe that fails counts as not joined, as it does for Self::is_joined.

impl Service

pub async fn is_joined<'a>( &'a self, user_id: &'a UserId, room_id: &'a RoomId, ) -> bool

Tests whether a user is currently indexed as joined to a room.

The user-to-room join index supplies the answer. Missing rows and storage failures both return false.

impl Service

pub async fn is_knocked<'a>( &'a self, user_id: &'a UserId, room_id: &'a RoomId, ) -> bool

Tests whether a user is currently indexed as knocking on a room.

The stored knock-state row supplies the answer. Missing rows and storage failures both return false.

impl Service

pub async fn is_invited(&self, user_id: &UserId, room_id: &RoomId) -> bool

Tests whether a user is currently indexed as invited to a room.

The stored invite-state row supplies the answer. Missing rows and storage failures both return false.

impl Service

pub async fn is_left(&self, user_id: &UserId, room_id: &RoomId) -> bool

Tests whether a user’s leave state is currently retained for a room.

Explicitly forgotten rooms have no row and return false. Missing rows and storage failures are otherwise indistinguishable.

impl Service

pub async fn delete_room_join_counts( &self, room_id: &RoomId, force: bool, ) -> Result

Deletes a room’s aggregate and paired membership indexes.

Aggregate rows and every paired index row found during enumeration are deleted in one database transaction. Local users’ leave rows survive unless force is true, while remote leave rows are always removed. Once-joined markers and appservice membership-cache entries are untouched. Storage errors encountered during enumeration are skipped and can leave index rows behind.

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.