Crate trillium_http

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
// any other http client would work here too
let url = format!("http://localhost:{}/", port);
let client = trillium_client::Client::new(trillium_smol::ClientConfig::default());
let mut client_conn = client.get(&*url).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

Re-exports

• pub use received_body::ReceivedBodyState;
• pub use buffer::Buffer;

Modules

• transport
  Types to represent the bidirectional data stream over which the HTTP protocol is communicated

Structs

• Body
  The trillium representation of a http body. This can contain either &'static [u8] content, Vec<u8> content, or a boxed AsyncRead type.
• Conn
  A http connection
• HeaderName
  The name of a http header. This can be either a KnownHeaderName or a string representation of an unknown header.
• HeaderValue
  A HeaderValue represents the right hand side of a single name: value pair.
• HeaderValues
  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.
• Headers
  Trillium’s header map type
• HttpConfig
  Performance and security parameters for trillium-http.
• ReceivedBody
  A received http body
• StateSet
  Store and retrieve values by TypeId. This allows storing arbitrary data that implements Sync + Send + 'static.
• Stopper
  This struct provides a synchronized mechanism for canceling Futures and Streams.
• Synthetic
  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.
• Upgrade
  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

• ConnectionStatus
  This represents the next state after a response on a conn transport.
• Error
  Concrete errors that occur within trillium’s http implementation
• KnownHeaderName
  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.
• Method
  HTTP request methods.
• Status
  HTTP response status codes.
• Version
  The version of the HTTP protocol in use.

Constants

• SERVER
  Default Server header
• SERVICE_UNAVAILABLE
  A pre-rendered http response to send when the server is at capacity.

Functions

• copy
  copy from the reader to the writer, yielding back to the runtime every loops_per_yield

Type Aliases

• Result
  this crate’s result type