Struct Service 

pub struct Service {
    services: Arc<OnceServices>,
    statuses: Arc<Map>,
    window_secs: u64,
    n_max: u32,
    grace: Duration,
}

Executes outbound federation traffic and maintains peer status.

Request entry points choose whether to consult or update reachability state. Fanout and candidate-ranking helpers build on the same transport policy.

Fields

services: Arc<OnceServices>

statuses: Arc<Map>

window_secs: u64

Width of one peer-status bucket in seconds, aligned with sender_timeout so the streak (the window span between a peer’s oldest and newest recorded failure) tracks the sender’s consecutive_failures notion at the cutover.

n_max: u32

Streak cap = ceil(sqrt(MAX_BACKOFF / window_secs)). Past this span the quadratic curve window * n² saturates at MAX_BACKOFF, so a longer streak cannot change the verdict.

grace: Duration

Grace before the first retry of a once-failed peer, snapshot from sender_retry_grace. Zero disables the grace tier so the plain bucket curve governs from the first failure.

Implementations

impl Service

pub async fn execute<T>( &self, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Debug + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Sends a federation request with the standard federation client.

The destination is validated and resolved before the request is signed and sent. Success clears peer failures and classifiable errors record a failure; this entry point does not itself consult peer backoff.

impl Service

pub async fn execute_keys<T>( &self, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Debug + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Sends a bounded, backoff-aware client key lookup over federation.

/keys/query and /keys/claim requests skip servers already in backoff and are limited by federation_keys_timeout. The uncounted send path deliberately records neither success, failure, nor timeout, so a slow key lookup does not suppress unrelated outbound traffic to the server.

impl Service

pub async fn execute_synapse<T>( &self, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Debug + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Sends a federation request with the long-timeout Synapse client.

Resolution, signing, response decoding, and peer-status recording match super::Service::execute; only the selected HTTP client differs.

impl Service

pub async fn execute_on<T>( &self, client: &Client, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Sends through a supplied client and records the peer outcome.

A successful response clears every stored failure row for the destination. Only errors classified as peer failures are recorded, and no backoff gate is consulted before sending.

impl Service

pub(super) async fn execute_on_allow_self<T>( &self, client: &Client, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Executes one Feds request while permitting only this server as a self-destination and preserving ordinary peer-status recording.

Other federation entry points retain the configured loopback gate.

impl Service

pub(super) async fn execute_uncounted<T>( &self, client: &Client, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Sends through a supplied client without changing peer status.

Callers that gate separately can honor existing backoff without adding success or failure records.

impl Service

pub(super) async fn execute_uncounted_allow_self<T>( &self, client: &Client, dest: &ServerName, request: T, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

Executes one Feds request while permitting only this server as a self-destination and leaving peer status untouched.

Other federation entry points retain the configured loopback gate.

impl Service

fn validate_request_destination(&self, dest: &ServerName) -> Result

impl Service

async fn perform<T>( &self, actual: &ActualDest, dest: &ServerName, request: Request, client: &Client, ) -> Result<T::IncomingResponse>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

impl Service

fn prepare<T>( &self, actual: &ActualDest, dest: &ServerName, request: T, ) -> Result<Request>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

impl Service

fn validate_url(&self, url: &Url) -> Result

impl Service

fn handle_error( &self, dest: &ServerName, actual: &ActualDest, method: &Method, url: &Url, e: Error, ) -> Result

impl Service

fn evict_misrouted(&self, dest: &ServerName, actual: &ActualDest, error: &Error)

impl Service

fn evict_route(&self, dest: &ServerName, actual: &ActualDest)

impl Service

fn to_http_request<T>( &self, actual: &ActualDest, dest: &ServerName, request: T, ) -> Result<Request<Vec<u8>>>

where T: OutgoingRequest + Send, T::Authentication: FedAuth, T::PathBuilder: FedPath,

impl Service

pub fn for_room<'a, F, R>( &'a self, room_id: &'a RoomId, make: F, opts: Opts, ) -> impl Stream<Item = Outcome<R::IncomingResponse>> + Send + 'a

where F: Fn(&ServerName) -> R + Send + 'a, R: OutgoingRequest + Send + 'a, R::IncomingResponse: Send, R::Authentication: FedAuth, R::PathBuilder: FedPath,

Surveys every server participating in a room.

The local server participates unless exclude_self removes it before the sweep. Cursor-backed server names become owned before concurrent polling.

impl Service

pub fn fanout_to<'a, D, F, R>( &'a self, dests: D, make: F, opts: Opts, ) -> impl Stream<Item = Outcome<R::IncomingResponse>> + Send + 'a

where D: Stream<Item = OwnedServerName> + Send + 'a, F: Fn(&ServerName) -> R + Send + 'a, R: OutgoingRequest + Send + 'a, R::IncomingResponse: Send, R::Authentication: FedAuth, R::PathBuilder: FedPath,

Builds one request for every destination and drives the resulting pairs.

Request construction remains sequential and lazy, while only the returned federation futures are polled concurrently.

impl Service

pub fn fanout<'a, S, R>( &'a self, pairs: S, opts: Opts, ) -> impl Stream<Item = Outcome<R::IncomingResponse>> + Send + 'a

where S: Stream<Item = (OwnedServerName, R)> + Send + 'a, R: OutgoingRequest + Send + 'a, R::IncomingResponse: Send, R::Authentication: FedAuth, R::PathBuilder: FedPath,

Drives arbitrary destination and federation request pairs.

Every consumed pair settles as one completion-ordered outcome unless the caller drops the stream and cancels remaining work. The selected recording posture applies independently to each request.

impl Service

pub async fn format_pdu_into( &self, pdu_json: CanonicalJsonObject, room_version: Option<&RoomVersionId>, ) -> Box<RawJsonValue>

Formats an event object for an outgoing federation response.

The supplied room version takes precedence; otherwise the room ID is used to look it up. When no version can be resolved, only event_id is removed. The returned raw JSON satisfies ruma’s response type and is not a full PDU.

impl Service

pub async fn record_success(&self, server: &ServerName)

Clears all recorded failures after a successful outbound request.

Removing the peer prefix makes the next attempt immediately eligible.

impl Service

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

Clears failure rows after a peer proves reachable through inbound activity.

The return value reports whether any rows were present, allowing the caller to flush only after a change. A healthy-peer miss writes no tombstone.

impl Service

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

Reports whether the reachability store holds a failure row for a peer.

Database errors are ignored and therefore behave like an empty prefix.

impl Service

pub fn record_failure( &self, server: &ServerName, classification: Classification, )

Records one classified failure in the peer’s current time bucket.

Repeated failures in the same bucket overwrite the same row. The value also stores the exact failure instant while remaining compatible with old rows.

impl Service

pub async fn should_attempt(&self, server: &ServerName) -> ShouldAttempt

Determines whether a federation request should currently target a peer.

A peer without readable failure rows is immediately eligible. Otherwise the verdict is derived from its newest failure and surviving bucket span.

impl Service

pub async fn peer_backoff(&self, server: &ServerName) -> Option<PeerBackoff>

Returns the current admin-facing backoff summary for one server.

The result is None when the peer has no readable failure rows.

impl Service

pub async fn peer_backoffs(&self) -> BTreeMap<OwnedServerName, PeerBackoff>

Returns admin-facing backoff summaries for all peers with failure rows.

The store is scanned once. Rows group by server on disk, so each contiguous run of buckets is folded in place; database errors are skipped.

impl Service

pub fn peer_snapshot( &self, ) -> impl Stream<Item = (&ServerName, SystemTime, Classification)> + Send + '_

Streams one tuple per readable peer-status bucket.

Items are ordered by (server, bucket_start) for the admin snapshot table. Borrowed server names are cursor-backed and remain valid only until the next poll. Database and key-decoding errors are skipped; malformed values decode as transient failures.

impl Service

fn current_bucket(&self) -> u64

impl Service

fn bucket_start(&self, bucket: u64) -> SystemTime

Wall-clock instant at the start of bucket.

impl Service

fn streak(&self, latest_bucket: u64, oldest_bucket: u64) -> u32

impl Service

async fn peer_streak(&self, server: &ServerName) -> Option<Streak>

Folds a server’s failure rows into its streak, None when it has none.

impl Service

fn backoff(&self, run: Streak) -> Backoff

Builds the pure backoff state from a server’s failure streak.

impl Service

fn peer_backoff_from(&self, streak: Streak) -> PeerBackoff

Projects a failure streak onto the admin-facing summary.

impl Service

pub async fn rank_candidates( &self, eligible: Candidates, when_all: WhenAllBackedOff, ) -> Candidates

Ranks eligible candidates by current peer reachability.

The method gathers each ShouldAttempt verdict, preserves caller order within each bucket, and applies when_all only when every peer is backed off.

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.