albatross/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! # albatross
4//!
5//! A composable HTTP server for [`tower::Service`] built around pluggable connection acceptors.
6//!
7//! **albatross** provides a small, focused API for flexible connection
8//! handling through **pluggable acceptors**. Acceptors allow you to inspect,
9//! transform, or wrap incoming connections before they reach your application,
10//! without complicating the core server interface.
11//!
12//! This makes it easy to add functionality such as TLS termination, automatic
13//! certificate management, protocol detection, or integration with service
14//! managers, all in a modular and composable way.
15//!
16//! `albatross` works with any tower [`Service`](tower::Service) that matches the expected
17//! signature. While it is generally intended for use with [axum](https://docs.rs/axum),
18//! it can serve any compatible tower service.
19//!
20//! ## Pluggable Acceptors
21//!
22//! An **acceptor** sits between the listener and your service. Acceptors can:
23//!
24//! - Wrap connections (e.g., TLS termination)  
25//! - Inspect or modify connection metadata  
26//! - Conditionally redirect or upgrade protocols  
27//! - Integrate with external systems
28//!
29//! Multiple acceptors can be composed together to create the exact connection
30//! behavior your server needs.
31//!
32//! ## Built-in Acceptors
33//!
34//! The library provides several ready-to-use acceptors behind feature flags:
35//!
36//! - `systemd` — integrates with systemd notifications and watchdogs  
37//! - `tls` — terminates HTTPS connections  
38//! - `acme` — similar to `tls` but automatically obtains and renews certificates  
39//! - `https-upgrade` — detects plain HTTP connections and upgrades or redirects them to HTTPS
40//!
41//! ## Getting Started
42//!
43//! Add **albatross** to your project:
44//!
45//! ```sh
46//! cargo add albatross --features tls,https-upgrade
47//! ```
48//!
49//! Create a server by binding a socket address and serving a `tower::Service`.
50//! Additional connection behavior (such as TLS or redirects) can be added using acceptors.
51//!
52//! ```rust,no_run
53//! # use axum::{Router, routing::get};
54//! #[tokio::main]
55//! async fn main() {
56//!     let router = Router::new()
57//!       .route("/", get(|| async { "Hello, world!" }));
58//!
59//! # #[cfg(all(feature = "tls", feature = "https-upgrade"))]
60//!     albatross::server("0.0.0.0:443")
61//!         .with_acceptor(albatross::tls().with_certificate("cert.pem"))
62//!         .with_https_upgrade()
63//!         .serve(router.into_make_service())
64//!         .await
65//!         .unwrap();
66//!
67//! # #[cfg(not(all(feature = "tls", feature = "https-upgrade")))]
68//!     albatross::server("0.0.0.0:443")
69//!         .serve(router.into_make_service())
70//!         .await
71//!         .unwrap();
72//! }
73//! ```
74
75#[cfg(feature = "acme")]
76#[cfg_attr(docsrs, doc(cfg(feature = "acme")))]
77use crate::accept::acme::Acme;
78
79#[cfg(feature = "tls")]
80#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
81use crate::accept::tls::Tls;
82
83pub use crate::{
84    accept::{Accept, IntoAccept},
85    server::{Server, Shutdown},
86};
87
88pub mod accept;
89pub mod server;
90
91/// Creates a new [`Server`] bound to the given socket address.
92///
93/// This is a shorthand for [`Server::new`]. The returned server
94/// initially has no acceptor or shutdown handle configured; you can
95/// customize it using methods like [`map_acceptor`](Server::map_acceptor)
96/// or [`with_shutdown`](Server::with_shutdown).
97#[inline]
98pub const fn server<A>(socket_addr: A) -> Server<A> {
99    Server::new(socket_addr)
100}
101
102/// Creates a new TLS acceptor.
103///
104/// This is a convenience wrapper for [`Tls::new`](crate::accept::tls::Tls::new) and
105/// produces a TLS acceptor ready to be composed with a server.
106///
107/// The acceptor can be further configured before use.
108#[cfg(feature = "tls")]
109#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
110#[inline]
111pub const fn tls() -> Tls {
112    Tls::new()
113}
114
115/// Creates a new ACME acceptor using the specified ACME directory URL.
116///
117/// This is a convenience wrapper for [`Acme::new`](crate::accept::acme::Acme::new) and returns
118/// an acceptor that can automatically obtain and renew certificates via
119/// the ACME protocol (e.g., Let's Encrypt).
120///
121/// The `directory` parameter should be the ACME server URL, such as the
122/// production or staging endpoint provided by your ACME provider.
123#[cfg(feature = "acme")]
124#[cfg_attr(docsrs, doc(cfg(feature = "acme")))]
125#[inline]
126pub fn acme(directory: &str) -> Acme {
127    Acme::new(directory)
128}
albatross/lib.rs

albatross/
lib.rs
