Struct Opts 

pub struct Opts {

    pub op: Op,
    pub room_id: Option<OwnedRoomId>,
    pub event_id: Option<OwnedEventId>,
    pub ts: Option<MilliSecondsSinceUnixEpoch>,
    pub dir: Option<Direction>,
    pub earliest_events: EventWindow,
    pub latest_events: EventWindow,
    pub hint: Option<OwnedServerName>,
    pub candidates: Candidates,
    pub room_version: Option<RoomVersionId>,
    pub attempt_limit: Option<NonZeroUsize>,
    pub backfill_limit: Option<NonZeroUsize>,
    pub fanout_growth: FanoutGrowth,
    pub fanout_max_width: Option<NonZeroUsize>,
    pub fanout_rounds: Option<NonZeroUsize>,
    pub check_event_id: bool,
    pub check_conforms: bool,
    pub check_hashes: bool,
    pub authoritative_redaction: bool,
    pub check_signature: bool,
}

Describes one caller’s federation fetch policy.

event_id addresses Event, AuthEvent, AuthChain, and StateIds requests and anchors Backfill; MissingEvents uses its event windows, while TimestampToEvent uses ts and dir. Candidate, retry, fanout, and validation settings also participate in single-flight identity.

Fields

op: Op

Federation endpoint this fetch targets.

room_id: Option<OwnedRoomId>

Room the fetch is scoped to, or None for an unscoped id-addressed fetch.

event_id: Option<OwnedEventId>

Target for Event, AuthEvent, AuthChain, and StateIds or Backfill anchor; unused by MissingEvents and TimestampToEvent.

ts: Option<MilliSecondsSinceUnixEpoch>

Timestamp the Op::TimestampToEvent search starts from; None for every other op.

dir: Option<Direction>

Direction the Op::TimestampToEvent search runs; None for every other op.

earliest_events: EventWindow

Boundary events the requester already holds; an Op::MissingEvents window stops its backward walk here. Empty for every other op.

latest_events: EventWindow

Frontier events an Op::MissingEvents window fills the predecessors of. Empty for every other op.

hint: Option<OwnedServerName>

Server to try ahead of the ranked candidates.

candidates: Candidates

Caller-supplied candidate pool tried in place of the room-derived ranking; empty defers to the room-derived candidates.

room_version: Option<RoomVersionId>

Room version for Event and AuthEvent validation; None assumes V11, and other operations do not consult it.

attempt_limit: Option<NonZeroUsize>

Cap on candidate servers tried; None tries every candidate.

backfill_limit: Option<NonZeroUsize>

Event count requested per Op::Backfill / Op::MissingEvents batch response; defaults to 10.

fanout_growth: FanoutGrowth

Per-round width curve for staged fan-out. Fixed(1) is sequential.

fanout_max_width: Option<NonZeroUsize>

Per-round concurrency ceiling. None lets the curve run free, clamped only by the candidate pool and attempt_limit; Some(n) caps each round at n.

fanout_rounds: Option<NonZeroUsize>

Optional per-call round cap; the global round cap still applies.

check_event_id: bool

For Event and AuthEvent, reject a response whose calculated event ID differs; other operations ignore this flag.

check_conforms: bool

Reject a response that is not well-formed JSON.

check_hashes: bool

Requests combined event verification for Event and AuthEvent responses.

Either this flag or check_signature runs the verifier. Its returned Verified status is currently ignored, so a content-hash mismatch with valid signatures is accepted; other operations ignore the flag.

authoritative_redaction: bool

Accepted but not yet consulted; redaction-aware hash verification is unimplemented.

check_signature: bool

For Event and AuthEvent, reject verifier errors when either verification flag is enabled; other operations ignore this flag.

Implementations

impl Opts

pub fn new(op: Op, room_id: OwnedRoomId) -> Self

Creates a fetch scoped to a room.

Validation gates start enabled, while the fixed width of one keeps attempts sequential unless the caller opts into staged fanout.

pub fn unscoped(op: Op) -> Self

Creates an unscoped fetch for an ID-addressed operation.

Room-derived candidate ranking is skipped, leaving the hint, caller-supplied pool, and event ID origin as candidate sources.

fn with_room_id(op: Op, room_id: Option<OwnedRoomId>) -> Self

All validation toggles default on; the caller relaxes them per request.

pub fn event_id(self, event_id: OwnedEventId) -> Self

Sets the target event or Backfill anchor.

Event, AuthEvent, AuthChain, Backfill, and StateIds require this value; MissingEvents and TimestampToEvent do not consult it.

pub fn ts(self, ts: MilliSecondsSinceUnixEpoch) -> Self

Sets the timestamp for a Op::TimestampToEvent search.

Other operations retain the value in coalescing identity but do not consult it during transport.

pub fn dir(self, dir: Direction) -> Self

Sets the direction for a Op::TimestampToEvent search.

Other operations retain the value in coalescing identity but do not consult it during transport.

pub fn earliest_events<I>(self, earliest_events: I) -> Self

where I: IntoIterator<Item = OwnedEventId>,

Sets the boundary where a Op::MissingEvents backward walk stops.

Only MissingEvents consults this window, whose order is normalized in the single-flight key.

pub fn latest_events<I>(self, latest_events: I) -> Self

where I: IntoIterator<Item = OwnedEventId>,

Sets the frontier a Op::MissingEvents request fills behind.

Only MissingEvents consults this window, whose order is normalized in the single-flight key.

pub fn hint(self, hint: OwnedServerName) -> Self

Adds a server ahead of the initial candidate order.

Reachability ranking may still drop or deprioritize it, and a failed attempt falls through to remaining candidates.

pub fn candidates<I>(self, candidates: I) -> Self

where I: IntoIterator<Item = OwnedServerName>,

Supplies a candidate pool in place of room-derived discovery.

The supplied servers remain subject to eligibility filtering, deduplication, and peer-reachability ranking.

pub fn room_version(self, room_version: RoomVersionId) -> Self

Sets the room version for Event and AuthEvent deep validation.

None keeps the V11 default, so callers from another room version must set it to avoid spurious rejection. Other operations retain the value in coalescing identity but do not consult it during validation.

pub fn attempt_limit(self, attempt_limit: NonZeroUsize) -> Self

Caps the number of candidate servers contacted.

None permits candidate exhaustion, and each round stays within the remaining budget.

pub fn backfill_limit(self, backfill_limit: NonZeroUsize) -> Self

Sets the event limit for Backfill and MissingEvents batches.

Other operations retain the value in coalescing identity but do not send it on the wire.

pub fn fanout(self, growth: FanoutGrowth) -> Self

Sets the per-round fanout width schedule.

The worker clamps each computed width to the candidate pool, optional ceiling, and remaining attempt budget.

pub fn fanout_max_width(self, max_width: NonZeroUsize) -> Self

Caps concurrent candidate attempts in each fanout round.

None lets the configured growth curve run until another budget binds.

pub fn fanout_rounds(self, rounds: NonZeroUsize) -> Self

Caps the number of fanout escalation rounds.

None leaves the per-call cap unset; the global round cap, candidate pool, or attempt budget can still stop escalation.

pub fn fanout_for_op(self) -> Self

Applies the operation’s recommended staged fanout profile.

Opts::new is sequential unless the caller opts in here. AuthEvent, AuthChain, StateIds, and MissingEvents receive profiles; Event, Backfill, and TimestampToEvent remain unchanged.

pub fn checks(self, enabled: bool) -> Self

Toggles the four implemented validation gates together.

Passing false accepts transport bytes without conformance or deep PDU checks. The unused authoritative_redaction option remains unchanged.

Trait Implementations

impl Clone for Opts

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Opts

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.