Struct Conn

Source

pub struct Conn { /* private fields */ }

Expand description

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

Implementations§

Source §

impl Conn

Source

pub fn transport(&self) -> Option<&dyn Transport>

Borrows the transport for this conn

This should only be used to call your own custom methods on the transport that do not read or write any data. Calling any method that reads from or writes to the transport will disrupt the HTTP protocol.

Source

pub fn transport_mut(&mut self) -> Option<&mut dyn Transport>

Mutably borrow the transport for this conn

This should only be used to call your own custom methods on the transport that do not read or write any data. Calling any method that reads from or writes to the transport will disrupt the HTTP protocol.

Source

pub fn url(&self) -> &Url

Borrows the url for this conn.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::from(client_config());

let conn = client.get("http://localhost:9080");

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

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

Source

pub fn url_mut(&mut self) -> &mut Url

Mutably borrow the url for this conn.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::from(client_config());

let conn = client.get("http://localhost:9080");

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

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

Source

pub fn set_url(&mut self, url: Url) -> &mut Self

Sets the url for this conn., returning &mut Self for chaining

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::from(client_config());

let conn = client.get("http://localhost:9080");

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

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

Source

pub fn method(&self) -> Method

Returns a copy of the method for this conn.

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::from(client_config());
let conn = client.get("http://localhost:9080");

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

assert_eq!(method, Method::Get);

Source

pub fn set_method(&mut self, method: Method) -> &mut Self

Sets the method for this conn., returning &mut Self for chaining

use trillium_client::{Client, Method};
use trillium_testing::client_config;

let client = Client::from(client_config());
let conn = client.get("http://localhost:9080");

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

assert_eq!(method, Method::Get);

Source

pub fn request_headers(&self) -> &Headers

Borrows the request headers

Source

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

Mutably borrow the request headers

Source

pub fn response_headers(&self) -> &Headers

Borrows the response headers

Source

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

Returns a copy of the status code for this conn.

If the conn has not yet been sent, this will be None.

use trillium_client::{Client, Status};
use trillium_testing::{client_config, with_server};

async fn handler(conn: trillium::Conn) -> trillium::Conn {
conn.with_status(418)
}

with_server(handler, |url| async move {
let client = Client::new(client_config());
let conn = client.get(url).await?;
assert_eq!(Status::ImATeapot, conn.status().unwrap());
Ok(())
});

Source

pub fn request_body(&self) -> Option<&Body>

Borrows the request body

env_logger::init();
use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
let client = Client::from(client_config());
let mut conn = client
.post(url)
.with_body("body") //<-
.await?;

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

Source

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

Sets the request body, returning &mut Self for chaining

env_logger::init();
use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
let client = Client::from(client_config());
let mut conn = client
.post(url)
.with_body("body") //<-
.await?;

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

Source

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

Owned chainable setter for the request body, returning Self

env_logger::init();
use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
let client = Client::from(client_config());
let mut conn = client
.post(url)
.with_body("body") //<-
.await?;

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

Source

pub fn take_request_body(&mut self) -> Option<Body>

Takes the request body, leaving a None in its place

env_logger::init();
use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
let client = Client::from(client_config());
let mut conn = client
.post(url)
.with_body("body") //<-
.await?;

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

Source

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

Returns a copy of the timeout for this conn

this can also be set on the client with Client::set_timeout and Client::with_timeout

Source

pub fn timeout_mut(&mut self) -> Option<&mut Duration>

Mutably borrow the timeout for this conn

this can also be set on the client with Client::set_timeout and Client::with_timeout

Source

pub fn set_timeout(&mut self, timeout: Duration) -> &mut Self

Sets the timeout for this conn, returning &mut Self for chaining

this can also be set on the client with Client::set_timeout and Client::with_timeout

Source

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

Owned chainable setter for the timeout for this conn, returning Self

this can also be set on the client with Client::set_timeout and Client::with_timeout

Source

pub fn take_timeout(&mut self) -> Option<Duration>

Takes the timeout for this conn, leaving a None in its place

this can also be set on the client with Client::set_timeout and Client::with_timeout

Source

pub fn set_http_version(&mut self, http_version: Version) -> &mut Self

Sets the http version hint for this conn, returning &mut Self for chaining

Pre-execution this is the prior-knowledge hint, not the version that will necessarily be on the wire. None means “no hint, use auto-discovery” (Alt-Svc h3, ALPN/pooled h2); Some(version) names the protocol to try first. Post-execution this is Some(version) reflecting the version the request was actually sent over.

The public http_version accessor resolves None to Version::Http1_1. See the crate-level Protocol selection documentation.

Source

pub fn with_http_version(self, http_version: Version) -> Self

Owned chainable setter for the http version hint for this conn, returning Self

Pre-execution this is the prior-knowledge hint, not the version that will necessarily be on the wire. None means “no hint, use auto-discovery” (Alt-Svc h3, ALPN/pooled h2); Some(version) names the protocol to try first. Post-execution this is Some(version) reflecting the version the request was actually sent over.

The public http_version accessor resolves None to Version::Http1_1. See the crate-level Protocol selection documentation.

Source

pub fn strict_http_version(&self) -> bool

Returns a copy of Whether a request that cannot be carried by the protocol it was matched to fails rather than being retried on an earlier protocol.

Off by default: a websocket handshake that lands on an h2 or h3 connection whose peer doesn’t support extended CONNECT is retried as an HTTP/1.1 upgrade on a new connection. When on, that peer yields an error instead. A version hint sets the protocol to try first; this flag decides what happens when that protocol can’t carry the request.

This can also be set for every conn on the client with Client::set_strict_http_version.

Source

pub fn set_strict_http_version( &mut self, strict_http_version: bool, ) -> &mut Self

Sets Whether a request that cannot be carried by the protocol it was matched to fails, returning &mut Self for chaining rather than being retried on an earlier protocol.

Off by default: a websocket handshake that lands on an h2 or h3 connection whose peer doesn’t support extended CONNECT is retried as an HTTP/1.1 upgrade on a new connection. When on, that peer yields an error instead. A version hint sets the protocol to try first; this flag decides what happens when that protocol can’t carry the request.

This can also be set for every conn on the client with Client::set_strict_http_version.

Source

pub fn with_strict_http_version(self) -> Self

Owned chainable setter for Whether a request that cannot be carried by the protocol it was matched to fails, returning Self rather than being retried on an earlier protocol.

Off by default: a websocket handshake that lands on an h2 or h3 connection whose peer doesn’t support extended CONNECT is retried as an HTTP/1.1 upgrade on a new connection. When on, that peer yields an error instead. A version hint sets the protocol to try first; this flag decides what happens when that protocol can’t carry the request.

This can also be set for every conn on the client with Client::set_strict_http_version.

Source

pub fn without_strict_http_version(self) -> Self

Owned chainable setter for Whether a request that cannot be carried by the protocol it was matched to fails, returning Self rather than being retried on an earlier protocol.

Off by default: a websocket handshake that lands on an h2 or h3 connection whose peer doesn’t support extended CONNECT is retried as an HTTP/1.1 upgrade on a new connection. When on, that peer yields an error instead. A version hint sets the protocol to try first; this flag decides what happens when that protocol can’t carry the request.

This can also be set for every conn on the client with Client::set_strict_http_version.

Source

pub fn authority(&self) -> Option<&str>

Borrows the :authority pseudo-header, populated during h2 or h3 header finalization

Source

pub fn scheme(&self) -> Option<&str>

Borrows the :scheme pseudo-header, populated during h2 or h3 header finalization

Source

pub fn path(&self) -> Option<&str>

Borrows the :path pseudo-header, populated during h2 or h3 header finalization

Source

pub fn request_target(&self) -> Option<&str>

Borrows an explicit request target override, used only for OPTIONS * and CONNECT host:port

When set and the method is OPTIONS or CONNECT, this value is used as the HTTP request target instead of deriving it from the url. For all other methods, this field is ignored.

Source

pub fn set_request_target( &mut self, request_target: impl Into<Cow<'static, str>>, ) -> &mut Self

Sets an explicit request target override, used only for OPTIONS * and CONNECT host:port, returning &mut Self for chaining

When set and the method is OPTIONS or CONNECT, this value is used as the HTTP request target instead of deriving it from the url. For all other methods, this field is ignored.

Source

pub fn with_request_target( self, request_target: impl Into<Cow<'static, str>>, ) -> Self

Owned chainable setter for an explicit request target override, used only for OPTIONS * and CONNECT host:port, returning Self

When set and the method is OPTIONS or CONNECT, this value is used as the HTTP request target instead of deriving it from the url. For all other methods, this field is ignored.

Source

pub fn protocol(&self) -> Option<&str>

Borrows The protocol this request switches the connection to, if any: sent as the Upgrade header over HTTP/1.1 and as the :protocol pseudo-header of an extended CONNECT over HTTP/2 and HTTP/3. Either way the stream is left open as a bidirectional byte channel after the response head.

Source

pub fn request_trailers(&self) -> Option<&Headers>

Borrows trailers sent with the request body, populated after the body has been fully sent.

Only present when the request body was constructed with Body::new_with_trailers and the body has been fully sent.

Source

pub fn response_trailers(&self) -> Option<&Headers>

Borrows trailers received with the response body, populated after the response body has been fully read.

Source

pub fn client(&self) -> &Client

Borrows the Client that built this conn.

Source §

impl Conn

Source

pub fn http_version(&self) -> Version

the http version for this conn

Pre-execution this resolves the version hint — the default (no hint) reports Version::Http1_1, which means “use auto-discovery,” not “force HTTP/1.1.” An explicit version set via with_http_version is the protocol to try first. Post-execution this reflects the version the request was actually sent over.

See the crate-level Protocol selection documentation.

Source

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

chainable setter for inserting a request header

use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
    let client = Client::new(client_config());
    let mut conn = client
        .get(url)
        .with_request_header("some-request-header", "header-value") // <--
        .await?;
    assert_eq!(
        conn.response_body().read_string().await?,
        "some-request-header was header-value"
    );
    Ok(())
})

Source

pub fn with_request_headers<HN, HV, I>(self, headers: I) -> Self
where I: IntoIterator<Item = (HN, HV)> + Send, HN: Into<HeaderName<'static>>, HV: Into<HeaderValues>,

chainable setter for extending request headers

use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, move |url| async move {
    let client = Client::new(client_config());
    let mut conn = client
        .get(url)
        .with_request_headers([
            ("some-request-header", "header-value"),
            ("some-other-req-header", "other-header-value"),
        ])
        .await?;

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

Source

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

Chainable method to remove a request header if present

Source

pub fn with_json_body(self, body: &impl Serialize) -> Result<Self>

Available on crate feature sonic-rs only.

chainable setter for json body. this requires the sonic-rs crate feature to be enabled.

Source

pub fn response_body(&mut self) -> ResponseBody<'_>

returns a ResponseBody that borrows the connection inside this conn.

use trillium_client::Client;
use trillium_testing::{client_config, with_server};

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

with_server(handler, |url| async move {
    let client = Client::from(client_config());
    let mut conn = client.get(url).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(())
});

Source

pub async fn response_json<T>(&mut self) -> Result<T, ClientSerdeError>
where T: DeserializeOwned,

Available on crate feature sonic-rs only.

Attempt to deserialize the response body. Note that this consumes the body content.

Source

pub fn success(self) -> Result<Self, UnexpectedStatusError>

Returns the conn or an UnexpectedStatusError that contains the conn

use trillium_client::{Client, Status};
use trillium_testing::{client_config, with_server};

with_server(Status::NotFound, |url| async move {
    let client = Client::new(client_config());
    assert_eq!(
        client.get(url).await?.success().unwrap_err().to_string(),
        "expected a success (2xx) status code, but got 404 Not Found"
    );
    Ok(())
});

with_server(Status::Ok, |url| async move {
    let client = Client::new(client_config());
    assert!(client.get(url).await?.success().is_ok());
    Ok(())
});

Source

pub fn take_response_body(&mut self) -> Option<ResponseBody<'static>>

Detach the response body as an owned, 'static value.

Returns None if there is no body to take — neither an override has been installed nor a transport-backed body is available. Subsequent calls return None. Callers who want to wrap-and-replace the body (e.g. tee through a cache) compose this with ConnExt::set_response_body; the conn’s body slot is empty between the two calls.

For a transport-backed body, this moves the transport into the returned ResponseBody<'static>. Drop on that value drains-and-pools (keepalive) or closes (otherwise) the transport via a spawned task; ResponseBody::recycle is the await-able variant. For an override body, the inner Body is moved out and any leftover transport on the conn is recycled immediately.

Source

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.

Source

pub fn peer_addr(&self) -> Option<SocketAddr>

attempts to retrieve the connected peer address

Source

pub fn with_state<T: Send + Sync + 'static>(self, state: T) -> Self

add state to the client conn and return self

Source

pub fn insert_state<T: Send + Sync + 'static>(&mut self, state: T) -> Option<T>

add state to the client conn, returning any previously set state of this type

Source

pub fn state<T: Send + Sync + 'static>(&self) -> Option<&T>

borrow state

Source

pub fn state_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T>

borrow state mutably

Source

pub fn take_state<T: Send + Sync + 'static>(&mut self) -> Option<T>

take state

Source §

impl Conn

Source

pub async fn into_sse(self) -> Result<EventStream, SseError>

Available on crate feature sse only.

Execute this request and interpret the response body as a Server-Sent Events stream.

This is an execution method: it sends the request, setting Accept: text/event-stream unless the conn already carries an Accept other than the default */*, then validates that the response has a success status and a text/event-stream content-type before handing back an EventStream. Calling it on a conn that has already been awaited returns SseErrorKind::AlreadyExecuted — build the conn, then call this; don’t await it yourself first.

On any failure the returned SseError still carries the Conn, so the caller can inspect the response (status, headers, error body) or convert it back with From/Into.

Source §

impl Conn

Source

pub async fn into_websocket( self, ) -> Result<WebSocketConn, WebSocketUpgradeError>

Available on crate feature websockets only.

Attempt to transform this Conn into a WebSocketConn.

This is an execution method: calling it on a conn that has already been awaited returns ErrorKind::AlreadyExecuted. Build the conn, then call this — don’t await it yourself first.

The handshake is an Upgrade over HTTP/1.1 and an extended CONNECT over HTTP/2 and HTTP/3. Which one is sent follows the same protocol selection as any other request, with one addition: a peer that speaks h2 or h3 but does not support extended CONNECT is retried as an HTTP/1.1 upgrade, unless strict_http_version is on, in which case it yields ErrorKind::ExtendedConnectUnsupported. See the crate-level Protocol selection documentation.

Source

pub async fn into_websocket_with_config( self, config: WebSocketConfig, ) -> Result<WebSocketConn, WebSocketUpgradeError>

Available on crate feature websockets only.

Like Conn::into_websocket but with a caller-supplied WebSocketConfig.

Trait Implementations§

Source §

impl AsMut<TypeSet> for Conn

Source §

fn as_mut(&mut self) -> &mut TypeSet

Converts this type into a mutable reference of the (usually inferred) input type.

Source §

impl AsRef<TypeSet> for Conn

Source §

fn as_ref(&self) -> &TypeSet

Converts this type into a shared reference of the (usually inferred) input type.

Source §

impl ConnExt for Conn

Source §

fn set_followup(&mut self, conn: Conn) -> &mut Self

Queue a follow-up Conn to be executed after the current cycle’s after_response chain has fully unwound. Read more

Source §

fn followup(&self) -> Option<&Conn>

Borrow the queued follow-up Conn, if any, without consuming it. Read more

Source §

fn take_followup(&mut self) -> Option<Conn>

Detach the queued follow-up Conn, if any. Read more

Source §

fn error(&self) -> Option<&Error>

Borrow the transport-level error stashed on this conn, if any. Read more

Source §

fn set_error(&mut self, error: Error) -> &mut Self

Install a transport-level error on this conn. Read more

Source §

fn take_error(&mut self) -> Option<Error>

Take the transport-level error stashed on this conn, leaving None in its place. Read more

Source §

fn halt(&mut self) -> &mut Self

Mark this conn halted, skipping the network round-trip in the current cycle. Read more

Source §

fn set_halted(&mut self, halted: bool) -> &mut Self

Set the halt flag explicitly. Read more

Source §

fn is_halted(&self) -> bool

Whether this conn is halted within the current cycle. Read more

Source §

fn set_response_body(&mut self, body: impl Into<Body>) -> &mut Self

Install an override response body, replacing whatever transport-backed body would otherwise be read from the network. Read more

Source §

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

Owned chainable variant of ConnExt::set_response_body.

Source §

fn set_status(&mut self, status: Status) -> &mut Self

Set the response status — handler-author synthesis. Read more

Source §

fn with_status(self, status: Status) -> Self

Owned chainable variant of ConnExt::set_status.

Source §

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

Mutably borrow the response headers — handler-author synthesis. Read more

Source §

fn set_response_headers(&mut self, response_headers: Headers) -> &mut Self

Replace the response headers wholesale — handler-author synthesis.

Source §

fn response_trailers_mut(&mut self) -> Option<&mut Headers>

Mutably borrow the response trailers, if any — handler-author synthesis.

Source §

fn set_response_trailers(&mut self, response_trailers: Headers) -> &mut Self

Install response trailers — handler-author synthesis.

Source §

fn upgrade(self) -> Self

Mark this conn as eligible for an upgrade. Read more

Source §

fn is_upgrade(&self) -> bool

Whether this conn is armed for an upgrade. See ConnExt::upgrade.

Source §

impl Debug for Conn

Source §

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

Formats the value using the given formatter. Read more

Source §

impl Drop for Conn

Source §

fn drop(&mut self)

Executes the destructor for this type. Read more

Source §

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Source §

impl From<Conn> for Body

Source §

fn from(conn: Conn) -> Body

Converts to this type from the input type.

Source §

impl From<Conn> for Upgrade<Box<dyn Transport>>

Source §

fn from(conn: Conn) -> Self

Convert a client conn into a trillium_http::Upgrade after response headers arrive, handing off the open transport for direct AsyncRead / AsyncWrite exchange with per-protocol framing applied.