albatross 0.1.1

A composable HTTP server for Tower services built around pluggable connection acceptors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

#![cfg_attr(docsrs, feature(doc_cfg))]

//! # albatross
//!
//! A composable HTTP server for [`tower::Service`] built around pluggable connection acceptors.
//!
//! **albatross** provides a small, focused API for flexible connection
//! handling through **pluggable acceptors**. Acceptors allow you to inspect,
//! transform, or wrap incoming connections before they reach your application,
//! without complicating the core server interface.
//!
//! This makes it easy to add functionality such as TLS termination, automatic
//! certificate management, protocol detection, or integration with service
//! managers, all in a modular and composable way.
//!
//! `albatross` works with any tower [`Service`](tower::Service) that matches the expected
//! signature. While it is generally intended for use with [axum](https://docs.rs/axum),
//! it can serve any compatible tower service.
//!
//! ## Pluggable Acceptors
//!
//! An **acceptor** sits between the listener and your service. Acceptors can:
//!
//! - Wrap connections (e.g., TLS termination)  
//! - Inspect or modify connection metadata  
//! - Conditionally redirect or upgrade protocols  
//! - Integrate with external systems
//!
//! Multiple acceptors can be composed together to create the exact connection
//! behavior your server needs.
//!
//! ## Built-in Acceptors
//!
//! The library provides several ready-to-use acceptors behind feature flags:
//!
//! - `systemd` — integrates with systemd notifications and watchdogs  
//! - `tls` — terminates HTTPS connections  
//! - `acme` — similar to `tls` but automatically obtains and renews certificates  
//! - `https-upgrade` — detects plain HTTP connections and upgrades or redirects them to HTTPS
//!
//! ## Getting Started
//!
//! Add **albatross** to your project:
//!
//! ```sh
//! cargo add albatross --features tls,https-upgrade
//! ```
//!
//! Create a server by binding a socket address and serving a `tower::Service`.
//! Additional connection behavior (such as TLS or redirects) can be added using acceptors.
//!
//! ```rust,no_run
//! # use axum::{Router, routing::get};
//! #[tokio::main]
//! async fn main() {
//!     let router = Router::new()
//!       .route("/", get(|| async { "Hello, world!" }));
//!
//! # #[cfg(all(feature = "tls", feature = "https-upgrade"))]
//!     albatross::server("0.0.0.0:443")
//!         .with_acceptor(albatross::tls().with_certificate("cert.pem"))
//!         .with_https_upgrade()
//!         .serve(router.into_make_service())
//!         .await
//!         .unwrap();
//!
//! # #[cfg(not(all(feature = "tls", feature = "https-upgrade")))]
//!     albatross::server("0.0.0.0:443")
//!         .serve(router.into_make_service())
//!         .await
//!         .unwrap();
//! }
//! ```

#[cfg(feature = "acme")]
#[cfg_attr(docsrs, doc(cfg(feature = "acme")))]
use crate::accept::acme::Acme;

#[cfg(feature = "tls")]
#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
use crate::accept::tls::Tls;

pub use crate::{
    accept::{Accept, IntoAccept},
    server::{Server, Shutdown},
};

pub mod accept;
pub mod server;

/// Creates a new [`Server`] bound to the given socket address.
///
/// This is a shorthand for [`Server::new`]. The returned server
/// initially has no acceptor or shutdown handle configured; you can
/// customize it using methods like [`map_acceptor`](Server::map_acceptor)
/// or [`with_shutdown`](Server::with_shutdown).
#[inline]
pub const fn server<A>(socket_addr: A) -> Server<A> {
    Server::new(socket_addr)
}

/// Creates a new TLS acceptor.
///
/// This is a convenience wrapper for [`Tls::new`](crate::accept::tls::Tls::new) and
/// produces a TLS acceptor ready to be composed with a server.
///
/// The acceptor can be further configured before use.
#[cfg(feature = "tls")]
#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
#[inline]
pub const fn tls() -> Tls {
    Tls::new()
}

/// Creates a new ACME acceptor using the specified ACME directory URL.
///
/// This is a convenience wrapper for [`Acme::new`](crate::accept::acme::Acme::new) and returns
/// an acceptor that can automatically obtain and renew certificates via
/// the ACME protocol (e.g., Let's Encrypt).
///
/// The `directory` parameter should be the ACME server URL, such as the
/// production or staging endpoint provided by your ACME provider.
#[cfg(feature = "acme")]
#[cfg_attr(docsrs, doc(cfg(feature = "acme")))]
#[inline]
pub fn acme(directory: &str) -> Acme {
    Acme::new(directory)
}