Struct trillium_client::Conn

pub struct Conn<'config, C: Connector> { /* private fields */ }

a client connection, representing both an outbound http request and a http response

Implementations

impl<'config, C: Connector> Conn<'config, C>

pub fn set_config<'c2: 'config>(&mut self, config: &'c2 C::Config)

imperatively assign a given config reference to this Conn.

use trillium_smol::{TcpConnector, ClientConfig};
type Conn<'config> = trillium_client::Conn<'config, TcpConnector>;

let config = ClientConfig {
    ttl: Some(100),
    ..Default::default()
};

let mut conn = Conn::get("http://localhost:8080/");
conn.set_config(&config); // <-

pub fn with_config<'c2: 'config>(
    self,
    config: &'c2 C::Config
) -> Conn<'config, C>

set a config reference on this conn and return the conn, allowing chaining

use trillium_smol::{TcpConnector, ClientConfig};
type Conn<'config> = trillium_client::Conn<'config, TcpConnector>;

let config = ClientConfig {
    nodelay: Some(true),
    ..Default::default()
};

let conn = Conn::get("http://localhost:8080/")
    .with_config(&config); //<-

impl<C: Connector> Conn<'static, C>

pub async fn execute(self) -> Result<Self>

Performs the http request, consuming and returning the conn. This is suitable for chaining on conns with owned Config. For a borrowed equivalent of this, see Conn::send.

type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

trillium_testing::with_server("ok", |url| async move {
    let mut conn = Conn::get(url).execute().await?; //<-
    assert_eq!(conn.status().unwrap(), 200);
    assert_eq!(conn.response_body().read_string().await?, "ok");
    Ok(())
});

impl<C: Connector> Conn<'_, C>

pub fn new<M, U>(method: M, url: U) -> Self where
    M: TryInto<Method>,
    <M as TryInto<Method>>::Error: Debug,
    U: TryInto<Url>,
    <U as TryInto<Url>>::Error: Debug, 

builds a new client Conn with the provided method and url

type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;
use trillium_testing::prelude::*;

let conn = Conn::new("get", "http://trillium.rs"); //<-
assert_eq!(conn.method(), Method::Get);
assert_eq!(conn.url().to_string(), "http://trillium.rs/");

let url = url::Url::parse("http://trillium.rs").unwrap();
let conn = Conn::new(Method::Post, url); //<-
assert_eq!(conn.method(), Method::Post);
assert_eq!(conn.url().to_string(), "http://trillium.rs/");

pub fn get<U>(url: U) -> Self where
    <U as TryInto<Url>>::Error: Debug,
    U: TryInto<Url>, 

Builds a new client conn with the get http method and the provided url.

use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

let conn = Conn::get("http://localhost:8080/some/route");

assert_eq!(conn.method(), Method::Get);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn post<U>(url: U) -> Self where
    <U as TryInto<Url>>::Error: Debug,
    U: TryInto<Url>, 

Builds a new client conn with the post http method and the provided url.

use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

let conn = Conn::post("http://localhost:8080/some/route");

assert_eq!(conn.method(), Method::Post);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn put<U>(url: U) -> Self where
    <U as TryInto<Url>>::Error: Debug,
    U: TryInto<Url>, 

Builds a new client conn with the put http method and the provided url.

use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

let conn = Conn::put("http://localhost:8080/some/route");

assert_eq!(conn.method(), Method::Put);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn delete<U>(url: U) -> Self where
    <U as TryInto<Url>>::Error: Debug,
    U: TryInto<Url>, 

Builds a new client conn with the delete http method and the provided url.

use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

let conn = Conn::delete("http://localhost:8080/some/route");

assert_eq!(conn.method(), Method::Delete);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub fn patch<U>(url: U) -> Self where
    <U as TryInto<Url>>::Error: Debug,
    U: TryInto<Url>, 

Builds a new client conn with the patch http method and the provided url.

use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, trillium_smol::TcpConnector>;

let conn = Conn::patch("http://localhost:8080/some/route");

assert_eq!(conn.method(), Method::Patch);
assert_eq!(conn.url().to_string(), "http://localhost:8080/some/route");

pub async fn send(&mut self) -> Result<()>

Performs the http request on a mutable borrow of the conn. This is suitable for conns with borrowed Config. For an owned and chainable equivalent of this, see Conn::execute.

use trillium_smol::TcpConnector;
type Client = trillium_client::Client<TcpConnector>;
trillium_testing::with_server("ok", |url| async move {
    let client = Client::new();
    let mut conn = client.get(url);

    conn.send().await?; //<-

    assert_eq!(conn.status().unwrap(), 200);
    assert_eq!(conn.response_body().read_string().await?, "ok");
    Ok(())
})

pub async fn recycle(self)

Returns this conn to the connection pool if it is keepalive, and closes it otherwise. This will happen asynchronously as a spawned task when the conn is dropped, but calling it explicitly allows you to block on it and control where it happens.

pub fn request_headers(&mut self) -> &mut Headers

retrieves a mutable borrow of the request headers, suitable for appending a header

use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |conn: trillium::Conn| async move {
    let header = conn.headers().get_str("some-request-header").unwrap_or_default();
    let response = format!("some-request-header was {}", header);
    conn.ok(response)
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::get(url);

    conn.request_headers() //<-
        .insert("some-request-header", "header-value");

    conn.send().await?;
    assert_eq!(
        conn.response_body().read_string().await?,
        "some-request-header was header-value"
    );
    Ok(())
})

pub fn with_header(
    self,
    name: impl Into<HeaderName<'static>>,
    value: impl Into<HeaderValues>
) -> Self

chainable setter for inserting a request header

use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |conn: trillium::Conn| async move {
    let header = conn.headers().get_str("some-request-header").unwrap_or_default();
    let response = format!("some-request-header was {}", header);
    conn.ok(response)
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::get(url)
        .with_header("some-request-header", "header-value") // <--
        .execute()
        .await?;
    assert_eq!(
        conn.response_body().read_string().await?,
        "some-request-header was header-value"
    );
    Ok(())
})

pub fn response_headers(&self) -> &Headers

use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |conn: trillium::Conn| async move {
    conn.with_header("some-header", "some-value")
        .with_status(200)
};

trillium_testing::with_server(handler, |url| async move {
    let conn = Conn::get(url).execute().await?;

    let headers = conn.response_headers(); //<-

    assert_eq!(headers.get_str("some-header"), Some("some-value"));
    Ok(())
})

pub fn response_headers_mut(&mut self) -> &mut Headers

get a mutable borrow of the response headers

pub fn set_request_body(&mut self, body: impl Into<Body>)

env_logger::init();
use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |mut conn: trillium::Conn| async move {
    let body = conn.request_body_string().await.unwrap();
    conn.ok(format!("request body was: {}", body))
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::post(url);

    conn.set_request_body("body"); //<-

    conn.send().await?;

    assert_eq!(conn.response_body().read_string().await?, "request body was: body");
    Ok(())
});

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

👎 Deprecated:

renamed as with_body. will be removed at the next minor release

chainable setter to assign the request body. deprecated in preference to the renamed Conn::with_body since it wouldn’t make sense to set a response body on a client conn.

env_logger::init();
use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |mut conn: trillium::Conn| async move {
    let body = conn.request_body_string().await.unwrap();
    conn.ok(format!("request body was: {}", body))
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::post(url)
        .with_request_body("body") //<-
        .execute()
        .await?;

    assert_eq!(
        conn.response_body().read_string().await?,
        "request body was: body"
    );
    Ok(())
});

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

chainable setter for the request body

env_logger::init();
use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |mut conn: trillium::Conn| async move {
    let body = conn.request_body_string().await.unwrap();
    conn.ok(format!("request body was: {}", body))
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::post(url)
        .with_body("body") //<-
        .execute()
        .await?;

    assert_eq!(
        conn.response_body().read_string().await?,
        "request body was: body"
    );
    Ok(())
});

pub fn url(&self) -> &Url

retrieves the url for this conn.

use trillium_smol::TcpConnector;
use trillium_client::Conn;

let conn = Conn::<TcpConnector>::get("http://localhost:9080");

let url = conn.url(); //<-

assert_eq!(url.host_str().unwrap(), "localhost");

pub fn method(&self) -> Method

retrieves the url for this conn.

use trillium_smol::TcpConnector;
use trillium_client::Conn;
use trillium_testing::prelude::*;
let conn = Conn::<TcpConnector>::get("http://localhost:9080");

let method = conn.method(); //<-

assert_eq!(method, Method::Get);

pub fn response_body(&mut self) -> ReceivedBody<'_, C::Transport>

returns a ReceivedBody that borrows the connection inside this conn.

env_logger::init();
use trillium_smol::TcpConnector;
type Conn = trillium_client::Conn<'static, TcpConnector>;

let handler = |mut conn: trillium::Conn| async move {
    conn.ok("hello from trillium")
};

trillium_testing::with_server(handler, |url| async move {
    let mut conn = Conn::get(url).execute().await?;

    let response_body = conn.response_body(); //<-

    assert_eq!(19, response_body.content_length().unwrap());
    let string = response_body.read_string().await?;
    assert_eq!("hello from trillium", string);
    Ok(())
});

pub fn status(&self) -> Option<Status>

returns the status code for this conn. if the conn has not yet been sent, this will be None.

use trillium_smol::TcpConnector;
use trillium_testing::prelude::*;
type Conn = trillium_client::Conn<'static, TcpConnector>;
async fn handler(conn: trillium::Conn) -> trillium::Conn {
    conn.with_status(418)
}

trillium_testing::with_server(handler, |url| async move {
    let conn = Conn::get(url).execute().await?;
    assert_eq!(Status::ImATeapot, conn.status().unwrap());
    Ok(())
});

Trait Implementations

impl<C: Connector> AsRef<<C as Connector>::Transport> for Conn<'_, C>

fn as_ref(&self) -> &C::Transport

Performs the conversion.

impl<C: Connector> Debug for Conn<'_, C>

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

Formats the value using the given formatter.

impl<C: Connector> Drop for Conn<'_, C>

fn drop(&mut self)

Executes the destructor for this type.

impl<C: Connector> From<Conn<'_, C>> for Body

fn from(conn: Conn<'_, C>) -> Body

Performs the conversion.

impl<C: Connector> From<Conn<'_, C>> for ReceivedBody<'static, C::Transport>

fn from(conn: Conn<'_, C>) -> Self

Performs the conversion.

impl<C: Connector> From<Conn<'_, C>> for Upgrade<C::Transport>

fn from(conn: Conn<'_, C>) -> Self

Performs the conversion.