Struct Service 

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

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 request to a federation server

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,

Client-initiated key lookup (/keys/query, /keys/claim) over federation: skips servers already in backoff and bounds the request by federation_keys_timeout so a waiting client is not held past its own send deadline. Honors peer-status but does not record into it; a slow key lookup must 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,

Like execute() but with a very large timeout

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,

impl Service

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,

Like [execute_on] but leaves peer-status untouched, for callers that must honor backoff without contributing to it.

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 async fn format_pdu_into( &self, pdu_json: CanonicalJsonObject, room_version: Option<&RoomVersionId>, ) -> Box<RawJsonValue>

This does not return a full Pdu it is only to satisfy ruma’s types.

impl Service

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

impl Service

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

Clears a peer’s failure rows after it has proven reachable via inbound activity, reporting whether any were present so the caller flushes only for a peer that was actually sad. The healthy-peer miss writes no tombstone.

impl Service

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

Whether the reachability store holds any failure rows for this peer.

impl Service

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

impl Service

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

impl Service

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

Admin-facing backoff summary for one server, None when it has no failure rows.

impl Service

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

Admin-facing backoff summary for every server with failure rows, in one pass over the reachability store. Rows group by server on disk, so a run of one server’s buckets folds in place.

impl Service

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

Yields one tuple per populated bucket, ordered by (server, bucket_start), backing the admin peer-status snapshot table.

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

Gather each candidate’s ShouldAttempt verdict and rank eligible, preserving the caller’s order within each verdict bucket.

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.