Crate trillium_http
source · [−]Expand description
This crate provides the http 1.x implementation for Trillium.
Stability
As this is primarily intended for internal use by the Trillium crate, the api is likely to be less stable than that of the higher level abstractions in Trillium.
Example
This is an elaborate example that demonstrates some of trillium_http
’s
capabilities. Please note that trillium itself provides a much more
usable interface on top of trillium_http
, at very little cost.
use async_net::{TcpListener, TcpStream};
use futures_lite::StreamExt;
use stopper::Stopper;
use trillium_http::{Conn, Result};
let stopper = Stopper::new();
let listener = TcpListener::bind(("localhost", 0)).await?;
let port = listener.local_addr()?.port();
let server_stopper = stopper.clone();
let server_handle = smol::spawn(async move {
let mut incoming = server_stopper.stop_stream(listener.incoming());
while let Some(Ok(stream)) = incoming.next().await {
let stopper = server_stopper.clone();
smol::spawn(Conn::map(stream, stopper, |mut conn: Conn<TcpStream>| async move {
conn.set_response_body("hello world");
conn.set_status(200);
conn
})).detach()
}
Result::Ok(())
});
// this example uses the trillium client
// please note that this api is still especially unstable.
// any other http client would work here too
let url = format!("http://localhost:{}/", port);
type ClientConn<'a> = trillium_client::Conn<'a, trillium_smol::TcpConnector>;
let mut client_conn = ClientConn::get(&*url).execute().await?;
assert_eq!(client_conn.status().unwrap(), 200);
assert_eq!(client_conn.response_headers().get_str("content-length"), Some("11"));
assert_eq!(
client_conn.response_body().read_string().await?,
"hello world"
);
stopper.stop(); // stop the server after one request
server_handle.await?; // wait for the server to shut down
Modules
Types to represent the bidirectional data stream over which the
HTTP protocol is communicated
Structs
The trillium representation of a http body. This can contain
either
&'static [u8]
content, Vec<u8>
content, or a boxed
AsyncRead
type.A http connection
The name of a http header. This can be either a
KnownHeaderName
or a string representation of an unknown
header.A
HeaderValue
represents the right hand side of a single name: value
pair.A header value is a collection of one or more
HeaderValue
. It
has been optimized for the “one HeaderValue
” case, but can
accomodate more than one value.Trillium’s header map type
A received http body
Store and retrieve values by
TypeId
. This
allows storing arbitrary data that implements Sync + Send + 'static
.This struct provides a synchronized mechanism for canceling
Futures and Streams.
Synthetic represents a simple transport that contains fixed
content. This is exclusively useful for testing or for server
implementations that are not read from an io connection, such as a
faas function, in which the entire body may be available immediately
on invocation.
This open (pub fields) struct represents a http upgrade. It contains
all of the data available on a Conn, as well as owning the underlying
transport.
Enums
This represents the next state after a response on a conn transport.
Concrete errors that occur within trillium’s http implementation
A short nonehaustive enum of headers that trillium can
represent as a u8. Use a
KnownHeaderName
variant instead
of a &’static str anywhere possible, as it allows trillium
to skip parsing the header entirely.HTTP request methods.
the current read state of this body
HTTP response status codes.
The version of the HTTP protocol in use.
Constants
A pre-rendered http response to send when the server is at capacity.
Type Definitions
this crate’s result type