Struct Service 

pub struct Service {
    keypair: Box<Ed25519KeyPair>,
    verify_keys: VerifyKeys,
    minimum_valid: Duration,
    services: Arc<OnceServices>,
    db: Data,
}

Manages the local signing identity and cached remote verification keys.

Cached keys are retained by key ID without enforcing valid_until_ts on reads. Missing keys can be acquired from remote origins or trusted notaries.

Fields

keypair: Box<Ed25519KeyPair>

verify_keys: VerifyKeys

minimum_valid: Duration

services: Arc<OnceServices>

db: Data

Implementations

impl Service

pub async fn acquire_events_pubkeys<'a, I>(&self, events: I)

where I: Iterator<Item = &'a Box<RawJsonValue>> + Send,

Acquires the signing keys referenced by a collection of raw events.

Signature maps are grouped and deduplicated before acquisition. Events with malformed JSON or unreadable signature fields are silently skipped.

impl Service

pub async fn acquire_pubkeys<'a, S, K>(&self, batch: S)

where S: Iterator<Item = (&'a ServerName, K)> + Send + Clone, K: Iterator<Item = &'a ServerSigningKeyId> + Send + Clone,

Best-effort acquires a batch of server signing keys into the local cache.

Local storage is checked first, then origins and trusted notaries are tried according to configuration. The method returns no status; keys still missing after all allowed sources are logged.

impl Service

async fn acquire_locals<'a, S, K>( &self, batch: S, ) -> BTreeMap<OwnedServerName, Vec<OwnedServerSigningKeyId>>

where S: Iterator<Item = (&'a ServerName, K)> + Send, K: Iterator<Item = &'a ServerSigningKeyId> + Send,

impl Service

async fn acquire_origins<I>( &self, batch: I, ) -> BTreeMap<OwnedServerName, Vec<OwnedServerSigningKeyId>>

where I: Iterator<Item = (OwnedServerName, Vec<OwnedServerSigningKeyId>)> + Send,

impl Service

async fn acquire_origin( &self, origin: OwnedServerName, key_ids: Vec<OwnedServerSigningKeyId>, timeout: Instant, ) -> (OwnedServerName, Vec<OwnedServerSigningKeyId>)

impl Service

async fn acquire_notary<I>( &self, batch: I, ) -> BTreeMap<OwnedServerName, Vec<OwnedServerSigningKeyId>>

where I: Iterator<Item = (OwnedServerName, Vec<OwnedServerSigningKeyId>)> + Send,

impl Service

async fn acquire_notary_result( &self, missing: &mut BTreeMap<OwnedServerName, Vec<OwnedServerSigningKeyId>>, server_keys: ServerSigningKeys, )

impl Service

pub async fn get_event_keys( &self, object: &CanonicalJsonObject, version: &RoomVersionRules, ) -> Result<PubKeyMap>

Resolves the public keys required to verify an event.

Invalid signature metadata returns an error. Fetch failures for individual keys are omitted, so a successful result can still be a partial key map.

impl Service

pub async fn get_pubkeys<'a, S, K>(&self, batch: S) -> PubKeyMap

where S: Iterator<Item = (&'a ServerName, K)> + Send, K: Iterator<Item = &'a ServerSigningKeyId> + Send,

Resolves public-key sets for a batch of servers and key IDs.

Every requested server is inserted, even when its key set is empty. Individual key errors are suppressed by Self::get_pubkeys_for.

impl Service

pub async fn get_pubkeys_for<'a, I>( &self, origin: &ServerName, key_ids: I, ) -> PubKeys

where I: Iterator<Item = &'a ServerSigningKeyId> + Send,

Resolves the requested public keys for one server.

Keys that cannot be loaded or fetched are omitted, making the returned set intentionally partial rather than failing the whole request.

impl Service

pub async fn get_verify_key( &self, origin: &ServerName, key_id: &ServerSigningKeyId, ) -> Result<VerifyKey>

Retrieves one current or retired verify key for a server.

The cache is checked first. Trusted notaries and the origin are then queried in configured order, with origin requests disabled in notary-only mode.

impl Service

async fn get_verify_key_from_notaries( &self, origin: &ServerName, key_id: &ServerSigningKeyId, ) -> Result<VerifyKey>

impl Service

async fn get_verify_key_from_origin( &self, origin: &ServerName, key_id: &ServerSigningKeyId, ) -> Result<VerifyKey>

impl Service

pub(super) async fn batch_notary_request<'a, S, K>( &self, notary: &ServerName, batch: S, ) -> Result<Vec<ServerSigningKeys>>

where S: Iterator<Item = (&'a ServerName, K)> + Send, K: Iterator<Item = &'a ServerSigningKeyId> + Send,

Requests a batch of signing-key documents from one trusted notary.

The request is split by configured batch size and concurrency. Malformed individual documents are skipped, while a failed batch aborts the operation.

impl Service

pub async fn notary_request( &self, notary: &ServerName, target: &ServerName, ) -> Result<impl Iterator<Item = ServerSigningKeys> + Clone + Debug + Send + use<>>

Requests signing-key documents for one target from a trusted notary.

The query requires the configured minimum validity horizon. Malformed documents in an otherwise successful response are omitted from the iterator.

impl Service

pub async fn server_request( &self, target: &ServerName, ) -> Result<ServerSigningKeys>

Requests the current signing-key document directly from its origin server.

The response must deserialize and name the requested target; a mismatched server_name is rejected as a bad server response.

impl Service

pub fn gen_id_hash_and_sign_event( &self, object: &mut CanonicalJsonObject, room_version_id: &RoomVersionId, ) -> Result<OwnedEventId>

Generates an event ID, content hash, and local signature in place.

Any existing event_id is removed first. Legacy room versions generate and insert the ID before signing; newer versions derive it after signing and then insert it into the returned object.

impl Service

fn gen_id_hash_and_sign_event_v1( &self, object: &mut CanonicalJsonObject, room_version_id: &RoomVersionId, ) -> Result<OwnedEventId>

Generates and inserts an event ID before signing a legacy-format event.

The explicit ID participates in the content hash and signature for room versions whose event format requires it.

impl Service

fn gen_id_hash_and_sign_event_v3( &self, object: &mut CanonicalJsonObject, room_version_id: &RoomVersionId, ) -> Result<OwnedEventId>

Signs a modern-format event before deriving and inserting its event ID.

The derived ID therefore reflects the signed event representation used by room versions that omit an explicit ID during signing.

impl Service

pub fn hash_and_sign_event( &self, object: &mut CanonicalJsonObject, room_version_id: &RoomVersionId, ) -> Result

Adds a content hash and local server signature to an event object.

Signing uses the room version’s redaction rules. Oversized PDUs are mapped to a request-too-large error and other signing failures to an unknown request error.

impl Service

pub fn sign_json(&self, object: &mut CanonicalJsonObject) -> Result

Signs an arbitrary canonical JSON object with the local server key.

The signature is inserted under the configured local server name without adding an event content hash.

impl Service

pub async fn validate_and_add_event_id( &self, pdu: &RawJsonValue, room_version_id: &RoomVersionId, ) -> Result<(OwnedEventId, CanonicalJsonObject)>

Derives an event ID, runs event verification, and returns canonical JSON.

Missing verification keys may be fetched. Newer room versions receive the derived event_id after any successful [Verified] result, including the signatures-only classification produced for a content-hash mismatch.

impl Service

pub async fn validate_and_add_event_id_no_fetch( &self, pdu: &RawJsonValue, room_version_id: &RoomVersionId, ) -> Result<(OwnedEventId, CanonicalJsonObject)>

Derives and checks an event using only keys already in local storage.

The method rejects the event before verification when any required key is absent. Any successful [Verified] classification is accepted, including a signatures-only result after a content-hash mismatch.

impl Service

pub async fn verify_event( &self, event: &CanonicalJsonObject, room_version_id: Option<&RoomVersionId>, ) -> Result<Verified>

Verifies an event and returns ruma’s verification classification.

Required keys are loaded or fetched through Self::get_event_keys. When no room version is supplied, version 11 rules are used. Callers must inspect [Verified] to distinguish complete verification from signatures only.

impl Service

pub async fn verify_json( &self, event: &CanonicalJsonObject, room_version_id: Option<&RoomVersionId>, ) -> Result

Verifies signatures on a canonical JSON object.

Unlike Self::verify_event, this does not verify an event content hash. Version 11 signature rules are used when no room version is supplied.

impl Service

pub fn keypair(&self) -> &Ed25519KeyPair

Returns the local Ed25519 signing keypair.

The keypair is loaded or generated when the service is built and remains fixed for the service lifetime.

impl Service

pub fn active_key_id(&self) -> &ServerSigningKeyId

Returns the signing-key ID for the active local verify key.

This delegates to Self::active_verify_key and therefore panics if the service was initialized without an active key.

impl Service

pub fn active_verify_key(&self) -> (&ServerSigningKeyId, &VerifyKey)

Returns the active local signing-key ID and verify key.

Initialization normally supplies exactly one entry. A missing entry panics, and debug builds also assert that no second active key exists.

impl Service

async fn add_signing_keys(&self, new_keys: ServerSigningKeys)

Merges a fetched signing-key document into the local cache.

Only current and old verify-key maps are retained from the incoming document; its signatures and validity timestamp are not preserved. The read, merge, and write sequence is not atomic.

impl Service

pub async fn required_keys_exist( &self, object: &CanonicalJsonObject, rules: &RoomVersionRules, ) -> bool

Checks whether every signature key required by an event is cached.

Invalid signature metadata, database errors, and malformed stored key data all produce false; this method never fetches missing keys.

impl Service

pub async fn verify_key_exists( &self, origin: &ServerName, key_id: &ServerSigningKeyId, ) -> bool

Checks whether one current or retired verify key is cached for a server.

The check is based on key-ID presence only and does not evaluate the stored key document’s validity interval. Read or decoding errors produce false.

impl Service

pub async fn verify_keys_for(&self, origin: &ServerName) -> VerifyKeys

Returns all cached verify keys usable for a server.

Retired keys are converted and merged with current keys. Storage errors are suppressed to an empty map, and the local active key is added for our names.

impl Service

pub async fn signing_keys_for( &self, origin: &ServerName, ) -> Result<ServerSigningKeys>

Loads the cached signing-key document for a server.

The returned document reflects the service’s merged cache representation; reads do not enforce valid_until_ts. Acquisition currently preserves key maps but not incoming document signatures or validity metadata.

impl Service

fn minimum_valid_ts(&self) -> MilliSecondsSinceUnixEpoch

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.