[go: up one dir, main page]

RequestBuilder

surf

Struct RequestBuilder 

Source 
pub struct RequestBuilder { /* private fields */ }
Expand description

Request Builder

Provides an ergonomic way to chain the creation of a request. This is generally accessed as the return value from surf::{method}(), however Request::builder is also provided.

§Examples

use surf::http::{Method, mime::HTML, Url};
let mut request = surf::post("https://httpbin.org/post")
    .body("<html>hi</html>")
    .header("custom-header", "value")
    .content_type(HTML)
    .build();

assert_eq!(request.take_body().into_string().await.unwrap(), "<html>hi</html>");
assert_eq!(request.method(), Method::Post);
assert_eq!(request.url(), &Url::parse("https://httpbin.org/post")?);
assert_eq!(request["custom-header"], "value");
assert_eq!(request["content-type"], "text/html;charset=utf-8");
use surf::http::{Method, Url};
let url = Url::parse("https://httpbin.org/post")?;
let request = surf::Request::builder(Method::Post, url).build();

Implementations§

Source§

impl RequestBuilder

Source

pub fn new(method: Method, url: Url) -> Self

Create a new instance.

This method is particularly useful when input URLs might be passed by third parties, and you don’t want to panic if they’re malformed. If URLs are statically encoded, it might be easier to use one of the shorthand methods instead.

§Examples
use surf::http::{Method, Url};

let url = Url::parse("https://httpbin.org/get")?;
let req = surf::RequestBuilder::new(Method::Get, url).build();
Source

pub fn header( self, key: impl Into<HeaderName>, value: impl ToHeaderValues, ) -> Self

Sets a header on the request.

§Examples
let req = surf::get("https://httpbin.org/get").header("header-name", "header-value").build();
assert_eq!(req["header-name"], "header-value");
Source

pub fn content_type(self, content_type: impl Into<Mime>) -> Self

Sets the Content-Type header on the request.

§Examples
let req = surf::post("https://httpbin.org/post").content_type(mime::HTML).build();
assert_eq!(req["content-type"], "text/html;charset=utf-8");
Source

pub fn body(self, body: impl Into<Body>) -> Self

Sets the body of the request from any type with implements Into<Body>, for example, any type with is AsyncRead.

§Mime

The encoding is set to application/octet-stream.

§Examples
use serde_json::json;
let mut req = surf::post("https://httpbin.org/post").body(json!({ "any": "Into<Body>"})).build();
assert_eq!(req.take_body().into_string().await.unwrap(), "{\"any\":\"Into<Body>\"}");
Source

pub fn body_json(self, json: &impl Serialize) -> Result<Self>

Pass JSON as the request body.

§Mime

The encoding is set to application/json.

§Errors

This method will return an error if the provided data could not be serialized to JSON.

§Examples
#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let uri = "https://httpbin.org/post";
let data = &Ip { ip: "129.0.0.1".into() };
let res = surf::post(uri).body_json(data)?.await?;
assert_eq!(res.status(), 200);
Source

pub fn body_string(self, string: String) -> Self

Pass a string as the request body.

§Mime

The encoding is set to text/plain; charset=utf-8.

§Examples
let uri = "https://httpbin.org/post";
let data = "hello world".to_string();
let res = surf::post(uri).body_string(data).await?;
assert_eq!(res.status(), 200);
Source

pub fn body_bytes(self, bytes: impl AsRef<[u8]>) -> Self

Pass bytes as the request body.

§Mime

The encoding is set to application/octet-stream.

§Examples
let uri = "https://httpbin.org/post";
let data = b"hello world".to_owned();
let res = surf::post(uri).body_bytes(data).await?;
assert_eq!(res.status(), 200);
Source

pub async fn body_file(self, path: impl AsRef<Path>) -> Result<Self>

Pass a file as the request body.

§Mime

The encoding is set based on the file extension using mime_guess if the operation was successful. If path has no extension, or its extension has no known MIME type mapping, then None is returned.

§Errors

This method will return an error if the file couldn’t be read.

§Examples
let uri = "https://httpbin.org/post";
let res = surf::post(uri).body_file("./archive.tgz").await?.await?;
assert_eq!(res.status(), 200);
Source

pub fn query(self, query: &impl Serialize) -> Result<Self, Error>

Set the URL querystring.

§Examples
#[derive(Serialize, Deserialize)]
struct Index {
    page: u32
}

let query = Index { page: 2 };
let mut req = surf::get("https://httpbin.org/get").query(&query)?.build();
assert_eq!(req.url().query(), Some("page=2"));
assert_eq!(req.url().as_str(), "https://httpbin.org/get?page=2");
Source

pub async fn recv_bytes(self) -> Result<Vec<u8>>

Submit the request and get the response body as bytes.

§Examples
let bytes = surf::get("https://httpbin.org/get").recv_bytes().await?;
assert!(bytes.len() > 0);
Source

pub async fn recv_string(self) -> Result<String>

Submit the request and get the response body as a string.

§Examples
let string = surf::get("https://httpbin.org/get").recv_string().await?;
assert!(string.len() > 0);
Source

pub async fn recv_json<T: DeserializeOwned>(self) -> Result<T>

Submit the request and decode the response body from json into a struct.

§Examples
#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let uri = "https://api.ipify.org?format=json";
let Ip { ip } = surf::get(uri).recv_json().await?;
assert!(ip.len() > 10);
Source

pub async fn recv_form<T: DeserializeOwned>(self) -> Result<T>

Submit the request and decode the response body from form encoding into a struct.

§Errors

Any I/O error encountered while reading the body is immediately returned as an Err.

If the body cannot be interpreted as valid json for the target type T, an Err is returned.

§Examples
#[derive(Deserialize, Serialize)]
struct Body {
    apples: u32
}

let url = "https://api.example.com/v1/response";
let Body { apples } = surf::get(url).recv_form().await?;
Source

pub fn middleware(self, middleware: impl Middleware) -> Self

Push middleware onto a per-request middleware stack.

Important: Setting per-request middleware incurs extra allocations. Creating a Client with middleware is recommended.

Client middleware is run before per-request middleware.

See the middleware submodule for more information on middleware.

§Examples
let res = surf::get("https://httpbin.org/get")
    .middleware(surf::middleware::Redirect::default())
    .await?;
Source

pub fn build(self) -> Request

Return the constructed Request.

Source

pub async fn send(self) -> Result<Response>

Create a Client and send the constructed Request from it.

Trait Implementations§

Source§

impl Debug for RequestBuilder

Source§

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

Formats the value using the given formatter. Read more
Source§

impl From<RequestBuilder> for Request

Source§

fn from(builder: RequestBuilder) -> Request

Converts a surf::RequestBuilder to a surf::Request.

Source§

impl Future for RequestBuilder

Source§

type Output = Result<Response, Error>

The type of value produced on completion.
Source§

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<F> FutureExt for F
where F: Future + ?Sized,

Source§

fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
where Self: Unpin,

A convenience for calling Future::poll() on !Unpin types.
Source§

fn or<F>(self, other: F) -> Or<Self, F>
where Self: Sized, F: Future<Output = Self::Output>,

Returns the result of self or other future, preferring self if both are ready. Read more
Source§

fn race<F>(self, other: F) -> Race<Self, F>
where Self: Sized, F: Future<Output = Self::Output>,

Returns the result of self or other future, with no preference if both are ready. Read more
Source§

fn catch_unwind(self) -> CatchUnwind<Self>
where Self: Sized + UnwindSafe,

Catches panics while polling the future. Read more
Source§

fn boxed<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a>>
where Self: Sized + Send + 'a,

Boxes the future and changes its type to dyn Future + Send + 'a. Read more
Source§

fn boxed_local<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + 'a>>
where Self: Sized + 'a,

Boxes the future and changes its type to dyn Future + 'a. Read more
Source§

impl<F> FutureExt for F
where F: Future + ?Sized,

Source§

fn poll(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
where Self: Unpin,

A convenience for calling Future::poll() on !Unpin types.
Source§

fn or<F>(self, other: F) -> Or<Self, F>
where Self: Sized, F: Future<Output = Self::Output>,

Returns the result of self or other future, preferring self if both are ready. Read more
Source§

fn race<F>(self, other: F) -> Race<Self, F>
where Self: Sized, F: Future<Output = Self::Output>,

Returns the result of self or other future, with no preference if both are ready. Read more
Source§

fn catch_unwind(self) -> CatchUnwind<Self>
where Self: Sized + UnwindSafe,

Catches panics while polling the future. Read more
Source§

fn boxed<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a>>
where Self: Sized + Send + 'a,

Boxes the future and changes its type to dyn Future + Send + 'a. Read more
Source§

fn boxed_local<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + 'a>>
where Self: Sized + 'a,

Boxes the future and changes its type to dyn Future + 'a. Read more
Source§

impl<T> FutureExt for T
where T: Future + ?Sized,

Source§

fn delay(self, dur: Duration) -> DelayFuture<Self>
where Self: Sized,

Returns a Future that delays execution for a specified time. Read more
Source§

fn flatten(self) -> FlattenFuture<Self, <Self::Output as IntoFuture>::Future>
where Self: Sized, Self::Output: IntoFuture,

Flatten out the execution of this future when the result itself can be converted into another future. Read more
Source§

fn race<F>(self, other: F) -> Race<Self, F>
where Self: Sized + Future, F: Future<Output = Self::Output>,

Waits for one of two similarly-typed futures to complete. Read more
Source§

fn try_race<F, T, E>(self, other: F) -> TryRace<Self, F>
where Self: Sized + Future<Output = Result<T, E>>, F: Future<Output = Self::Output>,

Waits for one of two similarly-typed fallible futures to complete. Read more
Source§

fn join<F>(self, other: F) -> Join<Self, F>
where Self: Sized + Future, F: Future,

Waits for two similarly-typed futures to complete. Read more
Source§

fn try_join<F, A, B, E>(self, other: F) -> TryJoin<Self, F>
where Self: Sized + Future<Output = Result<A, E>>, F: Future<Output = Result<B, E>>,

Waits for two similarly-typed fallible futures to complete. Read more
Source§

fn timeout(self, dur: Duration) -> TimeoutFuture<Self>
where Self: Sized,

Waits for both the future and a timeout, if the timeout completes before the future, it returns a TimeoutError. Read more
Source§

impl<T> FutureExt for T
where T: Future + ?Sized,

Source§

fn map<U, F>(self, f: F) -> Map<Self, F>
where F: FnOnce(Self::Output) -> U, Self: Sized,

Map this future’s output to a different type, returning a new future of the resulting type. Read more
Source§

fn map_into<U>(self) -> MapInto<Self, U>
where Self::Output: Into<U>, Self: Sized,

Map this future’s output to a different type, returning a new future of the resulting type. Read more
Source§

fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
where F: FnOnce(Self::Output) -> Fut, Fut: Future, Self: Sized,

Chain on a computation for when a future finished, passing the result of the future to the provided closure f. Read more
Source§

fn left_future<B>(self) -> Either<Self, B>
where B: Future<Output = Self::Output>, Self: Sized,

Wrap this future in an Either future, making it the left-hand variant of that Either. Read more
Source§

fn right_future<A>(self) -> Either<A, Self>
where A: Future<Output = Self::Output>, Self: Sized,

Wrap this future in an Either future, making it the right-hand variant of that Either. Read more
Source§

fn into_stream(self) -> IntoStream<Self>
where Self: Sized,

Convert this future into a single element stream. Read more
Source§

fn flatten(self) -> Flatten<Self>
where Self::Output: Future, Self: Sized,

Flatten the execution of this future when the output of this future is itself another future. Read more
Source§

fn flatten_stream(self) -> FlattenStream<Self>
where Self::Output: Stream, Self: Sized,

Flatten the execution of this future when the successful result of this future is a stream. Read more
Source§

fn fuse(self) -> Fuse<Self>
where Self: Sized,

Fuse a future such that poll will never again be called once it has completed. This method can be used to turn any Future into a FusedFuture. Read more
Source§

fn inspect<F>(self, f: F) -> Inspect<Self, F>
where F: FnOnce(&Self::Output), Self: Sized,

Do something with the output of a future before passing it on. Read more
Source§

fn catch_unwind(self) -> CatchUnwind<Self>
where Self: Sized + UnwindSafe,

Catches unwinding panics while polling the future. Read more
Source§

fn shared(self) -> Shared<Self>
where Self: Sized, Self::Output: Clone,

Create a cloneable handle to this future where all handles will resolve to the same result. Read more
Source§

fn boxed<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a>>
where Self: Sized + Send + 'a,

Wrap the future in a Box, pinning it. Read more
Source§

fn boxed_local<'a>(self) -> Pin<Box<dyn Future<Output = Self::Output> + 'a>>
where Self: Sized + 'a,

Wrap the future in a Box, pinning it. Read more
Source§

fn unit_error(self) -> UnitError<Self>
where Self: Sized,

Turns a Future<Output = T> into a TryFuture<Ok = T, Error = ()>.
Source§

fn never_error(self) -> NeverError<Self>
where Self: Sized,

Turns a Future<Output = T> into a TryFuture<Ok = T, Error = Never>.
Source§

fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
where Self: Unpin,

A convenience for calling Future::poll on Unpin future types.
Source§

fn now_or_never(self) -> Option<Self::Output>
where Self: Sized,

Evaluates and consumes the future, returning the resulting output if the future is ready after the first call to Future::poll. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<F> IntoFuture for F
where F: Future,

Source§

type Output = <F as Future>::Output

The output that the future will produce on completion.
Source§

type IntoFuture = F

Which kind of future are we turning this into?
Source§

fn into_future(self) -> <F as IntoFuture>::IntoFuture

Creates a future from a value. Read more
Source§

impl<T> IntoFuture for T
where T: Future,

Source§

type Output = <T as Future>::Output

The type of value produced on completion.
Source§

type Future = T

Which kind of future are we turning this into?
Source§

fn into_future(self) -> <T as IntoFuture>::Future

Create a future from a value
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<F, T, E> TryFuture for F
where F: Future<Output = Result<T, E>> + ?Sized,

Source§

type Ok = T

The type of successful values yielded by this future
Source§

type Error = E

The type of failures yielded by this future
Source§

fn try_poll( self: Pin<&mut F>, cx: &mut Context<'_>, ) -> Poll<<F as Future>::Output>

Poll this TryFuture as if it were a Future. Read more
Source§

impl<Fut> TryFutureExt for Fut
where Fut: TryFuture + ?Sized,

Source§

fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>
where F: FnOnce(Self::Ok) -> T, Self: Sized,

Maps this future’s success value to a different value. Read more
Source§

fn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E>
where F: FnOnce(Self::Ok) -> T, E: FnOnce(Self::Error) -> T, Self: Sized,

Maps this future’s success value to a different value, and permits for error handling resulting in the same type. Read more
Source§

fn map_err<E, F>(self, f: F) -> MapErr<Self, F>
where F: FnOnce(Self::Error) -> E, Self: Sized,

Maps this future’s error value to a different value. Read more
Source§

fn err_into<E>(self) -> ErrInto<Self, E>
where Self: Sized, Self::Error: Into<E>,

Maps this future’s Error to a new error type using the Into trait. Read more
Source§

fn ok_into<U>(self) -> OkInto<Self, U>
where Self: Sized, Self::Ok: Into<U>,

Maps this future’s Ok to a new type using the Into trait.
Source§

fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>
where F: FnOnce(Self::Ok) -> Fut, Fut: TryFuture<Error = Self::Error>, Self: Sized,

Executes another future after this one resolves successfully. The success value is passed to a closure to create this subsequent future. Read more
Source§

fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F>
where F: FnOnce(Self::Error) -> Fut, Fut: TryFuture<Ok = Self::Ok>, Self: Sized,

Executes another future if this one resolves to an error. The error value is passed to a closure to create this subsequent future. Read more
Source§

fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>
where F: FnOnce(&Self::Ok), Self: Sized,

Do something with the success value of a future before passing it on. Read more
Source§

fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>
where F: FnOnce(&Self::Error), Self: Sized,

Do something with the error value of a future before passing it on. Read more
Source§

fn try_flatten(self) -> TryFlatten<Self, Self::Ok>
where Self::Ok: TryFuture<Error = Self::Error>, Self: Sized,

Flatten the execution of this future when the successful result of this future is another future. Read more
Source§

fn try_flatten_stream(self) -> TryFlattenStream<Self>
where Self::Ok: TryStream<Error = Self::Error>, Self: Sized,

Flatten the execution of this future when the successful result of this future is a stream. Read more
Source§

fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F>
where Self: Sized, F: FnOnce(Self::Error) -> Self::Ok,

Unwraps this future’s output, producing a future with this future’s Ok type as its Output type. Read more
Source§

fn into_future(self) -> IntoFuture<Self>
where Self: Sized,

Wraps a TryFuture into a type that implements Future. Read more
Source§

fn try_poll_unpin( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<Self::Ok, Self::Error>>
where Self: Unpin,

A convenience method for calling TryFuture::try_poll on Unpin future types.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,