Struct RequestBuilder 

pub struct RequestBuilder<'a> { /* private fields */ }

One call, before it is sent.

Implementations

impl RequestBuilder<'_>

pub fn query(self, name: &str, value: impl Display) -> Self

A query parameter. Repeating a name sends it twice, which is how the API spells a list.

pub fn maybe_query(self, name: &str, value: Option<impl Display>) -> Self

A query parameter, if there is one to send.

pub fn header(self, name: &str, value: impl Into<String>) -> Self

A header. If-Match on the policy file is what this is for.

pub fn json(self, body: &impl Serialize) -> Self

A JSON body.

pub fn text(self, content_type: &str, body: impl Into<String>) -> Self

A body that is text rather than JSON, under a content type of its own.

The policy file is the reason: it is HuJSON — JSON with comments and trailing commas — and a caller who wrote one wants it sent as written, comments included. Sending it as a JSON string would send the document quoted and escaped, which is a different document.

pub fn budget(self, budget: Duration) -> Self

The whole of this call, retries and backoff included: past it the call ends as a timeout whatever it was doing.

The default is the client’s, which is the tool timeout; a tool that waits on something slower passes its own. One attempt is separately capped at the client’s budget, so raising this raises how long a call may spend across attempts rather than how long one may stall.

pub async fn send(self) -> Result<Value, ApiError>

Send it, and read the answer as JSON.

An empty body — which is what a successful DELETE sends — comes back as Value::Null rather than as a failure to parse nothing.

pub async fn send_as<T: DeserializeOwned>(self) -> Result<T, ApiError>

Send it, and read the answer as a particular shape.

pub async fn send_answer<T: DeserializeOwned>( self, ) -> Result<Answer<T>, ApiError>

Send it, and read the answer both ways at once.

ADR-0003 asks for “the parsed model together with the raw body and the headers that matter”, and this is why: a tool forwards the body it was given, unrenamed and with every field the control plane sent, while the server reads the typed value to decide what to do next. Parsing twice would be two chances to disagree, so the model is deserialised from the Value rather than from the bytes a second time.

An empty body reads as Value::Null, the same as send gives it, and T has to be a type that can read null — Value or () or an Option. A model cannot: every one of them carries a flattened map of unknown fields, which makes it a map to serde, and serde will not read a map from null. That is the right way round, because the endpoints that answer with nothing are the deletions, and a deletion has no model to answer with.

pub async fn send_text(self) -> Result<TextBody, ApiError>

Send it, and read the answer as text.

The policy file is HuJSON — comments and trailing commas — so it is not JSON to parse, and its ETag is what a later write has to quote.

Trait Implementations

impl<'a> Debug for RequestBuilder<'a>

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

Formats the value using the given formatter.