Struct trillium::Conn [−][src]
pub struct Conn { /* fields omitted */ }Expand description
A Trillium HTTP connection.
A Conn represents both the request and response of a http connection, as well as any application state that is associated with that connection.
with_{attribute} naming convention
A convention that is used throughout trillium is that any interface
that is named with_{attribute} will take ownership of the conn, set
the attribute and return the conn, enabling chained calls like:
struct MyState(&'static str);
async fn handler(mut conn: trillium::Conn) -> trillium::Conn {
conn.with_header("content-type", "text/plain")
.with_state(MyState("hello"))
.with_body("hey there")
.with_status(418)
}
use trillium_testing::prelude::*;
assert_response!(
get("/").on(&handler),
Status::ImATeapot,
"hey there",
"content-type" => "text/plain"
);If you need to set a property on the conn without moving it,
set_{attribute} associated functions will be your huckleberry, as is
conventional in other rust projects.
State
Every trillium Conn contains a state type which is a set that contains at most one element for each type. State is the primary way that handlers attach data to a conn as it passes through a tuple handler. In general, state access should generally be implemented by libraries using a private type and exposed with a ConnExt trait. See library patterns for more elaboration and examples.
In relation to trillium_http::Conn
trillium::Conn is currently implemented as an abstraction on top of a
trillium_http::Conn. In particular, trillium::Conn boxes the
transport using a BoxedTransport
so that application code can be written without transport
generics. See Transport for further
reading on this.
Implementations
Conn::ok is a convenience function for the common pattern of
setting a body and a 200 status in one call. It is exactly
identical to conn.with_status(200).with_body(body).halt()
use trillium::Conn;
use trillium_testing::prelude::*;
let mut conn = get("/").on(&|conn: Conn| async move { conn.ok("hello") });
assert_body!(&mut conn, "hello");
assert_status!(&conn, 200);
assert!(conn.is_halted());returns the response status for this conn, if it has been set.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert!(conn.status().is_none());
conn.set_status(200);
assert_eq!(conn.status().unwrap(), Status::Ok);assigns a status to this response. see Conn::status for example usage
sets the response status for this conn and returns it. note that this does not set the halted status.
use trillium_testing::prelude::*;
let conn = get("/").on(&|conn: Conn| async move {
conn.with_status(418)
});
let status = conn.status().unwrap();
assert_eq!(status, Status::ImATeapot);
assert_eq!(status, 418);
assert!(!conn.is_halted());Sets the response body from any impl Into<Body> and returns the
conn for fluent chaining. Note that this does not set the response
status or halted. See Conn::ok for a function that does both
of those.
use trillium_testing::prelude::*;
let conn = get("/").on(&|conn: Conn| async move {
conn.with_body("hello")
});
assert_eq!(conn.response_len(), Some(5));Sets the response body from any impl Into<Body>. Note that this does not set the response
status or halted.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
conn.set_body("hello");
assert_eq!(conn.response_len(), Some(5));Removes the response body from the conn
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
conn.set_body("hello");
let mut body = conn.take_response_body().unwrap();
assert_eq!(body.len(), Some(5));
assert_eq!(conn.response_len(), None);Attempts to retrieve a &T from the state set
use trillium_testing::prelude::*;
struct Hello;
let mut conn = get("/").on(&());
assert!(conn.state::<Hello>().is_none());
conn.set_state(Hello);
assert!(conn.state::<Hello>().is_some());Attempts to retrieve a &mut T from the state set
Puts a new type into the state set. see Conn::state
for an example. returns the previous instance of this type, if
any
Puts a new type into the state set and returns the conn. this is useful for fluent chaining
Removes a type from the state set and returns it, if present
Either returns the current &mut T from the state set, or inserts a new one with the provided default function and returns a mutable reference to it
returns a ReceivedBody that references this conn. the conn retains all data and holds the singular transport, but the ReceivedBody provides an interface to read body content
use trillium_testing::prelude::*;
let mut conn = get("/").with_request_body("request body").on(&());
let request_body = conn.request_body().await;
assert_eq!(request_body.content_length(), Some(12));
assert_eq!(request_body.read_string().await.unwrap(), "request body");Convenience function to read the content of a request body as a String.
use trillium_testing::prelude::*;
let mut conn = get("/").with_request_body("request body").on(&());
assert_eq!(conn.request_body_string().await.unwrap(), "request body");if there is a response body for this conn and it has a known fixed length, it is returned from this function
use trillium_testing::prelude::*;
let mut conn = get("/").on(&|conn: trillium::Conn| async move {
conn.with_body("hello")
});
assert_eq!(conn.response_len(), Some(5));returns the request method for this conn.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert_eq!(conn.method(), Method::Get);returns the request headers
stability note: this may become request_headers at some point
returns the mutable response headers
stability note: this may become response_headers at some point
pub fn with_header(
self,
header_name: impl Into<HeaderName<'static>>,
header_value: impl Into<HeaderValues>
) -> Self
pub fn with_header(
self,
header_name: impl Into<HeaderName<'static>>,
header_value: impl Into<HeaderValues>
) -> Self
insert a header name and value/values into the response headers
and return the conn. for a slight performance improvement, use a
KnownHeaderName as the first argument instead of a
str.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&|conn: trillium::Conn| async move {
conn.with_header("content-type", "application/html")
});returns the path for this request. note that this may not represent the entire http request path if running nested routers.
returns query part of the request path
use trillium_testing::prelude::*;
let conn = get("/a/b?c&d=e").on(&());
assert_eq!(conn.querystring(), "c&d=e");
let conn = get("/a/b").on(&());
assert_eq!(conn.querystring(), "");sets the halted attribute of this conn, preventing later
processing in a given tuple handler. returns
the conn for fluent chaining
use trillium_testing::prelude::*;
let mut conn = get("/").on(&|conn: trillium::Conn| async move {
conn.halt()
});
assert!(conn.is_halted());sets the halted attribute of this conn. see Conn::halt.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert!(!conn.is_halted());
conn.set_halted(true);
assert!(conn.is_halted());retrieves the halted state of this conn. see Conn::halt.
predicate function to indicate whether the connection is secure. note that this does not necessarily indicate that the transport itself is secure, as it may indicate that trillium_http is behind a trusted reverse proxy that has terminated tls and provided appropriate headers to indicate this.
returns an immutable reference to the inner
trillium_http::Conn. please open an issue if you need to do
this in application code.
stability note: hopefully this can go away at some point, but for now is an escape hatch in case trillium_http::Conn presents interface that cannot be reached otherwise.
returns a mutable reference to the inner
trillium_http::Conn. please open an issue if you need to
do this in application code.
stability note: hopefully this can go away at some point, but for now is an escape hatch in case trillium_http::Conn presents interface that cannot be reached otherwise.
transforms this trillium::Conn into a trillium_http::Conn
with the specified transport type. Please note that this will
panic if you attempt to downcast from trillium’s boxed
transport into the wrong transport type. Also note that this
is a lossy conversion, dropping the halted state and any
nested router path data.
for router implementations. pushes a route segment onto the path