about

albatross is small library for serving web applications over http. It's core Server is built on-top of tower, which means web frameworks like axum will work out of the box. Whilst this library mainly focuses on serving with tls, there is also a non-encrypted, tcp server configuration, which can be useful for local-development.

tls is built upon the tls::Provider, which receives incoming connections and decides what tls::Certificate to provide. Under-the-hood rustls is used for handling connections, and is thinly-abstracted away for providers to interact with.

tls providers

Currently, this library offers a few different tls providers:

tls::Certificate

Simple static certificates automatically implement the tls::Provider trait for which, every incoming connection uses that certificate. This provides basically the same functionality as using the axum_server crate. Certificates can be read from a pem file, or can be generated with self-signed.

tls::sni

This tls::Provider holds server-name / tls::Certificate pairs and selects a suitable certificate based on whether the incoming server_name matches any of them. This is useful when you have different certificates for subdomains, and need to handle requests to any of said subdomains.

tls::acme

This tls::Provider is one of the major features of this crate. It will automatically issue and refresh certificates from any valid acme service such as LetsEncrypt, and cache the resulting certificates across server restarts.

getting started

To start using albatross, you'll first need to add our package to your Cargo.toml manifest:

cargo add avosetta

// Create our axum (tower compatible) router.
let router = axum::Router::new()
  .route("/", get(|| async move { "Hello, World!" }));

// Serve our application using a static `tls` certificate
albatross::server((Ipv4Addr::LOCALHOST, 80))
  .with_tls(albatross::tls::from_pem("../certificate.pem"))
  .serve(router.into_make_service())
  .await
  .unwrap();

features

albatross has a variety of features that can be enabled / disabled to aid in compilation times.

• http1: enables support for http/1.1.
• http2: enables support for http/2.0.
• tls: enables support for tls.
• tls-self-signed: enables support for generating self-signed certificates.
• tls-sni: enables the sni based tls provider.
• tls-acme: enables the acme base tls provider.
• tls-acme-file-cache: enables a file-backed acme cache.
• tracing: enables tracing support.