Struct CallContext 

pub struct CallContext { /* private fields */ }

Everything one backend call needs: timeout, deadline, retry policy, cancel token, round-trip recorder and redactor. Cheap to clone.

Build one with CallContext::new and the with_* methods; run a call with call. See the module docs.

Implementations

impl CallContext

pub fn new() -> Self

A context with nothing set: a DEFAULT_CALL_TIMEOUT attempt timeout, one attempt, no cancel token, no deadline, no metering.

pub fn with_timeout(self, timeout: Duration) -> Self

Bound each attempt by timeout. An attempt that runs out fails with a retriable FaucetError::Timeout.

pub fn without_timeout(self) -> Self

Let each attempt run as long as it takes. For a call that legitimately outlives any fixed bound (a long poll, a streamed download); a deadline still applies.

pub fn with_deadline(self, deadline: Instant) -> Self

End the whole call — every attempt and every backoff — at deadline, with a FaucetError::Timeout.

pub fn with_retry(self, policy: RetryPolicy) -> Self

Retry failed attempts under policy: classified by RetryClass, backed off with jitter, and a FaucetError::RateLimited waits the time it states.

pub fn without_retry(self) -> Self

Make exactly one attempt, whatever a layered context says.

pub fn with_rate_limit_retries(self, n: u32) -> Self

Give rate limits their own budget: a FaucetError::RateLimited outcome waits its stated time and is retried up to n consecutive times without using one of the retry policy’s attempts (any other outcome resets the count). Without this, a rate limit is an ordinary retriable attempt.

pub fn with_cancel(self, cancel: CancellationToken) -> Self

Stop the call, and any backoff, as soon as cancel fires, with FaucetError::Cancelled.

pub fn with_recorder(self, recorder: Arc<RoundtripRecorder>) -> Self

Count each attempt as a round trip, and report throttling and retries, on recorder.

pub fn with_roundtrip_metering(self, on: bool) -> Self

Whether call counts each attempt as a round trip (default true). Throttling and retries are reported either way; turn this off for a call whose round trips the connector counts itself.

pub fn with_redactor(self, redactor: CallRedactor) -> Self

Scrub error text with redactor instead of the process-wide hook (crate::redact::redact).

pub fn inherit(&self, base: &CallContext) -> CallContext

This context with every field it leaves unset taken from base.

pub fn timeout(&self) -> Option<Duration>

The attempt timeout, None when attempts are unbounded.

pub fn deadline(&self) -> Option<Instant>

The overall deadline, when one is set.

pub fn retry(&self) -> Option<&RetryPolicy>

The retry policy, when one is set (None = a single attempt).

pub fn rate_limit_retries(&self) -> Option<u32>

The rate-limit budget set by with_rate_limit_retries.

pub fn cancel(&self) -> Option<&CancellationToken>

The cancel token, when one is set.

pub fn is_cancelled(&self) -> bool

Whether the cancel token has fired.

pub fn recorder(&self) -> Option<&Arc<RoundtripRecorder>>

The round-trip recorder, when one is set.

pub fn record(&self, op: &'static str)

Count one round trip the connector made outside call.

pub fn signal(&self, kind: &'static str, unit: &'static str, quantity: f64)

Report a backend-measured usage figure (see RoundtripRecorder::signal).

pub fn redact(&self, text: &str) -> String

Scrub text with this context’s redactor, or the process-wide one.

pub fn redact_error(&self, err: FaucetError) -> FaucetError

err with the text it carries scrubbed: the URL and body of an HTTP status error, and the URL of a transport error (credentials in it are removed too).

pub async fn wait(&self, duration: Duration) -> Result<(), FaucetError>

Wait duration the way a call waits: ended early with FaucetError::Cancelled when the token fires, and with FaucetError::Timeout when the deadline comes first. For a pause that is not a retry — a poll interval, a server-requested pacing delay.

pub async fn call<T, F, Fut>( &self, op: &'static str, f: F, ) -> Result<T, FaucetError>

where F: FnMut() -> Fut, Fut: Future<Output = Result<T, FaucetError>>,

Run f as one backend call named op (a closed, connector-defined label such as query, page, put).

Each invocation of f is one attempt. The call:

• fails fast with FaucetError::Cancelled when the token has fired, and stops an attempt or a backoff the moment it fires;
• bounds each attempt by the attempt timeout and the whole call by the deadline (FaucetError::Timeout, retriable while the deadline allows);
• retries under the retry policy: classified errors only, jittered backoff, a FaucetError::RateLimited waiting its stated time;
• counts every attempt as a round trip on the recorder (with its duration), and every throttle, throttle wait and retry;
• scrubs the final error (redact_error).

pub async fn call_once<T, Fut>( &self, op: &'static str, fut: Fut, ) -> Result<T, FaucetError>

where Fut: Future<Output = Result<T, FaucetError>>,

Run fut as one backend call named op, in a single attempt: the form for a call that cannot be rebuilt — a statement on a borrowed transaction, a step of a cursor or stream, a non-idempotent write. Timeout, deadline, cancel, metering and redaction apply as in call; any retry policy is ignored.

impl CallContext

pub fn reader<R>(&self, inner: R) -> CallReader<R>

inner read under this context (CallReader).

Trait Implementations

impl Clone for CallContext

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 CallContext

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

Formats the value using the given formatter.

impl Default for CallContext

fn default() -> Self

Returns the “default value” for a type.

impl RefUnwindSafe for CallContext

impl UnwindSafe for CallContext