Struct Server 

pub struct Server<S> {
    pub max_body_size: usize,
    pub max_connections: usize,
    /* private fields */
}

Main server configuration and runner.

Wraps a CompiledRouter and provides multiple serve_* methods for different transport protocols. The server is cheaply cloneable via Arc internally.

Example

use tachyon_web::{Router, Server, get};
use tokio::net::TcpListener;

async fn hello() -> &'static str { "hello" }

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let app = Router::new().route("/", get(hello));
    let listener = TcpListener::bind("0.0.0.0:8080").await?;
    Server::new(app).serve_http(listener).await?;
    Ok(())
}

Fields

max_body_size: usize

Maximum permitted request body size in bytes (default: 2 MiB, matching Axum’s DefaultBodyLimit default).

max_connections: usize

Maximum number of concurrent active TCP connections per worker thread.

Tachyon runs one worker (with its own SO_REUSEPORT listener and connection semaphore) per CPU core, so the effective process-wide ceiling is max_connections × number of cores, not a single global cap. Size this accordingly if you’re relying on it for downstream resource planning (e.g. a connection-pooled database sized to the server’s max concurrency).

This per-core sharding applies to serve_http and serve_https (and anything built on them, like serve_all_acme). HTTP/3 (serve_h3) runs a single QUIC endpoint with its own connection semaphore, not sharded across the worker pool — for H3 traffic the effective ceiling is max_connections alone.

Default: 25,600 — matching actix-server’s own per-worker max_concurrent_connections.

Implementations

impl<S> Server<S>

where S: Clone + Send + Sync + 'static,

pub async fn serve_h3(self, quic_server: Server) -> Result<(), Error>

Serve HTTP/3 over QUIC using the given s2n-quic server.

Errors

Returns an error if FIPS compliance enforcement fails. The accept loop itself never surfaces per-connection errors as an Err; it just stops when quic_server.accept() returns None.

impl<S> Server<S>

where S: Clone + Send + Sync + 'static,

pub async fn serve_http(self, listener: TcpListener) -> Result<(), Error>

Serve HTTP/1.1 (and, with the http2 feature, HTTP/2 over cleartext — “h2c”, detected via the connection preface with no ALPN needed) over plaintext TCP on the given listener.

Without the http2 feature this uses hyper::server::conn::http1::Builder directly — no protocol sniffing, no auto dispatch overhead. With it, it uses hyper_util’s auto::Builder, which peeks at the first bytes of each connection to detect an HTTP/2 client connection preface and falls back to HTTP/1.1 otherwise. Either builder is constructed once and cloned per connection (cheap: only pointer-sized fields).

h2c has no browser support (browsers only ever negotiate HTTP/2 via TLS ALPN) but is exactly what most non-browser HTTP/2 clients (gRPC, curl --http2-prior-knowledge, many internal service meshes) expect when TLS is terminated upstream (e.g. behind a load balancer) or simply not wanted.

Errors

Returns an error if FIPS compliance enforcement fails. Per-connection I/O errors (accept failures, handshake failures, etc.) are logged and do not terminate the accept loop.

pub async fn serve_https( self, listener: TcpListener, acceptor: TlsAcceptor, ) -> Result<(), Error>

Serve HTTP/1.1 and HTTP/2 over TLS (HTTPS) on the given listener and acceptor.

Errors

Returns an error if FIPS compliance enforcement fails. Per-connection I/O errors (accept failures, handshake failures, etc.) are logged and do not terminate the accept loop.

pub async fn serve_https_config( self, listener: TcpListener, config: ServerConfig, ) -> Result<(), Error>

Serve HTTP/1.1 and HTTP/2 over TLS (HTTPS) on the given listener with a custom rustls::ServerConfig.

Errors

Returns an error if FIPS compliance enforcement fails. Per-connection I/O errors (accept failures, handshake failures, etc.) are logged and do not terminate the accept loop.

impl<S> Server<S>

where S: Clone + Send + Sync + 'static,

pub async fn serve_i2p( self, nickname: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes this router as an I2P eepsite and serves requests arriving over it, blocking indefinitely — the accept loop retries forever on error and has no graceful-stop mechanism today; abort the surrounding task (e.g. via JoinHandle::abort) to end it.

Starts a fresh I2pRouter and a persistent destination under ./.tachyon-i2p/<nickname>.keys — plaintext only, no other configuration. For a custom data directory, TLS, or an on_ready hook, use serve_i2p_config instead.

See the module docs for why this feature does not honor tachyon-web’s forbid(unsafe_code) guarantee.

Errors

Returns an error if the I2P router fails to start (most commonly: tachyon_i2p::I2pError::AlreadyRunning if another I2pRouter is already running in this process — only one may exist per process) or the destination fails to load/create.

pub async fn serve_i2p_config( self, config: I2pConfig, ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes this router as an I2P eepsite according to config, starting a fresh I2pRouter, and serves requests arriving over it, blocking indefinitely — the accept loop retries forever on error and has no graceful-stop mechanism today; abort the surrounding task (e.g. via JoinHandle::abort) to end it.

See the module docs for why this feature does not honor tachyon-web’s forbid(unsafe_code) guarantee.

Errors

Returns an error if the I2P router fails to start (most commonly: tachyon_i2p::I2pError::AlreadyRunning if another I2pRouter is already running in this process — only one may exist per process; use serve_i2p_config_with_router to reuse one instead), the destination fails to load/create, or (when TLS is enabled) the TLS configuration is invalid.

pub async fn serve_i2p_config_with_router( self, router: &I2pRouter, config: I2pConfig, ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes this router as an I2P eepsite according to config, using an already-started I2pRouter (only one may run per process — this is how a second eepsite, or a second destination used purely as an outbound client, shares the same router instead of hitting tachyon_i2p::I2pError::AlreadyRunning), and serves requests arriving over it, blocking indefinitely — the accept loop retries forever on error and has no graceful-stop mechanism today; abort the surrounding task (e.g. via JoinHandle::abort) to end it.

See the module docs for why this feature does not honor tachyon-web’s forbid(unsafe_code) guarantee.

The self-signed certificate (when I2pConfig::self_signed_tls is used) shares this server’s crypto/TLS policy — see Server::tls_policy.

Errors

Returns an error if nickname contains path separators or .. (it’s used verbatim to build the destination keys file path, as <data_dir>/<nickname>.keys), the destination fails to load/create, or (when TLS is enabled) the TLS configuration is invalid.

impl<S> Server<S>

where S: Clone + Send + Sync + 'static,

pub async fn serve_tor( self, nickname: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes this router as a Tor .onion hidden service and serves requests arriving over it, blocking until the service stops.

Bootstraps a fresh TorClient with TorClientConfig::default — this alone can take from several seconds up to a minute or more, since it involves connecting to and syncing with the live Tor network — then behaves like serve_tor_with_client. Reuse a TorClient across calls (via serve_tor_with_client) rather than bootstrapping one per service.

This is the plaintext-only entry point (virtual port 80 only, no HTTPS, no configuration) — available under the tor feature alone, no TLS stack required. For native onion HTTPS (needs the tls feature too), custom state/cache directories, or the other OnionConfig options, use serve_onion instead.

Errors

Returns an error if the Tor client fails to bootstrap, nickname is not a valid HsNickname, or the onion service fails to launch.

pub async fn serve_tor_with_client<R>( self, client: &TorClient<R>, nickname: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

where R: Runtime,

Publishes this router as a Tor .onion hidden service using an already-bootstrapped TorClient, and serves requests arriving over it, blocking until the service stops.

Only rendezvous requests targeting virtual port 80 are accepted (the port every .onion HTTP client expects); anything else has its circuit shut down immediately. Requests are dispatched through the same handling pipeline as serve_http — HTTP/1.1, plus h2c with the http2 feature — one Tokio task per stream.

Since client is already bootstrapped, arti has already constructed its internal relay/channel TLS provider from whatever rustls::crypto::CryptoProvider was installed process-wide before this call — install one yourself (e.g. server.effective_tls_policy(), or simply TlsPolicy::hardened().install_as_process_default(), both requiring this crate’s tls feature) before bootstrapping client if that matters to you; it’s too late to affect client by the time this function runs. serve_tor does this for you because it owns the bootstrap.

Errors

Returns an error if nickname is not a valid HsNickname, or the onion service fails to launch (for example, if onion services are disabled in client’s config).

pub async fn serve_onion( self, config: OnionConfig, ) -> Result<(), Box<dyn Error + Send + Sync>>

Publishes this router as a Tor .onion hidden service according to config (state/cache directories, vanguards) and serves requests arriving over it, blocking until the service stops. Bootstraps a fresh TorClient — see the bootstrap-time note on serve_tor; prefer serve_onion_with_client to reuse one across services.

Errors

Returns an error if the Tor client fails to bootstrap, config.nickname is not a valid HsNickname, or the onion service fails to launch.

pub async fn serve_onion_with_client<R>( self, client: &TorClient<R>, config: OnionConfig, ) -> Result<(), Box<dyn Error + Send + Sync>>

where R: Runtime,

Publishes this router as a Tor .onion hidden service according to config, using an already-bootstrapped TorClient, and serves requests arriving over it, blocking until the service stops.

Dispatch depends on config and on which features are compiled in: virtual port 80 serves plaintext HTTP unless redirect_http is enabled (in which case it issues a 308 to the https:// equivalent) — both only possible with the tls feature enabled; virtual port 443 terminates TLS — self-signed by default with cert-gen, or a caller-supplied config via tls_config with just tls — and is only listened on if the tls feature is enabled and no_tls wasn’t called. Without the tls feature at all, this behaves exactly like serve_tor_with_client: plaintext on virtual port 80 only. Anything else has its circuit shut down immediately.

Since client is already bootstrapped, install a CryptoProvider process-wide yourself before bootstrapping it if you want arti’s relay/channel TLS to share this server’s policy — see the equivalent note on serve_tor_with_client. The self-signed certificate on virtual port 443 always uses this server’s TlsPolicy (see Server::tls_policy), regardless of what’s installed process-wide.

Errors

Returns an error if config.nickname is not a valid HsNickname, the onion service fails to launch, or (when TLS is enabled) the TLS configuration is invalid.

impl Server<()>

pub fn new(router: Router<()>) -> Self

Creates a new Server with default settings and the given router.

Panics

Panics if router compilation fails (e.g. a duplicate route was registered).

impl<S> Server<S>

where S: Clone + Send + Sync + 'static,

pub const fn max_body_size(self, size: usize) -> Self

Overrides the maximum request body size (in bytes).

Requests whose body exceeds this limit are rejected with 413 Content Too Large before the body bytes are fully buffered. The default is 2 MiB, matching Axum’s DefaultBodyLimit default.

Example

let server = Server::new(router).max_body_size(64 * 1024 * 1024); // 64 MiB

pub const fn max_connections(self, limit: usize) -> Self

Overrides the maximum number of concurrent connections per worker thread (default: 25,600 — see Server::max_connections for why this isn’t a single process-wide cap).

pub const fn response_jitter(self, min: Duration, max: Duration) -> Self

Adds a random delay, uniformly sampled from [min, max), before every response this Server returns — on every transport it serves (clearnet, .onion, .i2p alike, since they all funnel through the same response path).

Off by default. This exists to blunt naive response-time correlation: if you run the same app on both clearnet and a .onion/.i2p mirror (e.g. via MultiServer), an observer positioned to time both could otherwise try to match requests between them by how long the handler took to respond. Jitter alone does not make correlation impossible — it raises the number of samples an observer needs, nothing more — so treat it as one layer among several (network-level timing is a much stronger signal than this addresses), not a complete mitigation.

min == max (or max <= min) always waits exactly min — use this for a fixed per-response delay instead of a random range.

pub fn crypto_provider(self, provider: Arc<CryptoProvider>) -> Self

Sets a custom rustls::crypto::CryptoProvider to be used for TLS operations.

This overrides the default provider (which uses aws-lc-rs with customized Kex and AEAD). Shorthand for .tls_policy(TlsPolicy::with_provider(provider)) — use tls_policy directly if you also want to restrict protocol versions (e.g. TLS 1.3-only) or install this provider process-wide for arti’s Tor relay connections.

pub fn tls_policy(self, policy: TlsPolicy) -> Self

Sets the crypto/TLS policy shared by every listener this Server runs: clearnet HTTPS (static cert or Let’s Encrypt), the onion .onion HTTPS termination, and the I2P eepsite’s optional TLS layer. All three derive their rustls::ServerConfig (including self-signed certs) from the same TlsPolicy instead of each reconstructing their own defaults.

Defaults to TlsPolicy::hardened if never called.

See TlsPolicy’s docs for how this interacts with Tor’s relay/channel TLS layer (a separate concern from HTTPS termination).

pub fn with_http(self, listener: TcpListener) -> MultiServer<S>

Begins publishing this app over multiple transports at once — see MultiServer and the module docs.

Adds a plaintext clearnet HTTP transport bound to listener; chain more .with_* calls (.with_https/.with_h3/.with_onion/.with_i2p) to add further transports, then finish with .serve().await.

pub fn with_https( self, listener: TcpListener, config: ServerConfig, ) -> MultiServer<S>

Begins publishing this app over multiple transports at once — see MultiServer and the module docs.

Adds a clearnet HTTPS transport bound to listener, terminated with config. Requires the tls feature.

pub fn with_h3(self, quic_server: Server) -> MultiServer<S>

Begins publishing this app over multiple transports at once — see MultiServer and the module docs.

Adds an HTTP/3-over-QUIC transport. Requires the http3 feature.

pub fn with_onion(self, config: OnionConfig) -> MultiServer<S>

Begins publishing this app over multiple transports at once — see MultiServer and the module docs.

Adds a Tor .onion hidden-service transport. Requires the tor feature.

pub fn with_i2p(self, config: I2pConfig) -> MultiServer<S>

Begins publishing this app over multiple transports at once — see MultiServer and the module docs.

Adds an I2P .b32.i2p eepsite transport. Requires the i2p feature (⚠️ breaks forbid(unsafe_code)).

pub async fn start_http_addr(self, addr: SocketAddr) -> Result<(), Error>

Starts a pure plaintext HTTP server on a parsed SocketAddr.

Errors

Returns an error if the server fails to run.

pub async fn start_http(self, http_addr: &str) -> Result<(), Error>

Starts a pure plaintext HTTP server.

Arguments

• http_addr: The address to bind (e.g., "0.0.0.0:80").

Errors

Returns an error if parsing the bind address fails or the server fails to run.

pub async fn start_https_with_config_addr( self, addr: SocketAddr, config: ServerConfig, ) -> Result<(), Error>

Starts a pure HTTPS server (HTTP/1.1 and HTTP/2 over TLS) using a custom rustls::ServerConfig.

This provides advanced control for users who want to configure TLS themselves, without relying on cert-gen or Let’s Encrypt automation.

Arguments

• tls_addr: The address to bind for TLS (e.g., "0.0.0.0:443").
• config: A configured rustls::ServerConfig.

Errors

Returns an error if parsing the bind address fails or the server fails to run.

pub async fn start_https_with_config( self, tls_addr: &str, config: ServerConfig, ) -> Result<(), Error>

Starts a pure HTTPS server (HTTP/1.1 and HTTP/2 over TLS) using a custom rustls::ServerConfig.

This provides advanced control for users who want to configure TLS themselves, without relying on cert-gen or Let’s Encrypt automation.

Arguments

• tls_addr: The address to bind for TLS (e.g., "0.0.0.0:443").
• config: A configured rustls::ServerConfig.

Errors

Returns an error if parsing the bind address fails or the server fails to run.

pub async fn start_https_and_h3_with_config( self, tls_addr: &str, config: ServerConfig, ) -> Result<(), Box<dyn Error + Send + Sync>>

Starts HTTPS (HTTP/1.1 + HTTP/2 over TLS) and HTTP/3 (QUIC) using a custom rustls::ServerConfig.

This provides advanced control for users who want to configure TLS themselves, without relying on cert-gen or Let’s Encrypt automation. Both listeners will bind to the provided tls_addr (TCP for HTTPS and UDP for HTTP/3).

Arguments

• tls_addr: The address to bind for TCP and UDP (e.g., "0.0.0.0:443").
• config: A configured rustls::ServerConfig.

Errors

Returns an error if FIPS compliance enforcement, binding, or server initialization fails.

pub async fn start_all( self, tls_addr: &str, cleartext_addr: Option<&str>, cert_pem: String, key_pem: String, ) -> Result<(), Box<dyn Error + Send + Sync>>

Starts the server across all enabled protocols simultaneously using pre-loaded PEM certificate and key strings.

This is a convenience wrapper that sets up:

• HTTP → HTTPS redirect on cleartext_addr (if provided), with ACME HTTP-01 challenge pass-through so Let’s Encrypt can validate the domain even while this server is running.
• HTTP/3 (QUIC) on tls_addr (if the http3 feature is enabled).
• HTTPS (HTTP/1.1 + HTTP/2 over TLS) on tls_addr, which blocks the current task.

Arguments

• tls_addr: The address to bind for TLS (e.g., "0.0.0.0:443").
• cleartext_addr: Optional plaintext HTTP address for the redirect listener (e.g., Some("0.0.0.0:80")). Pass None if you manage HTTP elsewhere.
• cert_pem: PEM-encoded certificate chain (leaf + intermediates).
• key_pem: PEM-encoded ECDSA or RSA private key.

Errors

Returns an error if address binding, TLS configuration, or certificate parsing fails.

pub async fn serve_all_acme( self, tls_addr: &str, cleartext_addr: &str, domains: Vec<String>, email: String, cache_dir: impl Into<PathBuf>, staging: bool, ) -> Result<(), Box<dyn Error + Send + Sync>>

Starts the server with automatic Let’s Encrypt certificate management.

This is the simplest way to deploy a production HTTPS server with Tachyon. It combines AcmeManager (certificate issuance and renewal) with start_all (multi-protocol serving) into a single call.

What this does

1. Creates an AcmeManager for the given domains and email.
2. Starts the ACME background renewal loop.
3. Binds an HTTP listener on cleartext_addr that:
   • Serves ACME HTTP-01 challenge responses (required for cert issuance).
   • Redirects all other requests to HTTPS with 308 Permanent Redirect.
4. Waits (up to 30s) for the first certificate to be cached or provisioned, then starts the TLS listener regardless of whether that wait timed out.
5. Optionally starts HTTP/3 QUIC listener (if the http3 feature is enabled).

Arguments

• tls_addr: Address to bind for HTTPS (e.g., "0.0.0.0:443").
• cleartext_addr: Address to bind for HTTP and ACME challenges (e.g., "0.0.0.0:80"). Port 80 must be publicly reachable for Let’s Encrypt HTTP-01 challenges to work.
• domains: Domain names to include in the certificate (must all resolve to this server).
• email: Contact email for Let’s Encrypt account registration and expiry notices.
• cache_dir: Directory to store credentials and the certificate on disk. Must be writable. Survives server restarts — this prevents hitting rate limits.
• staging: If true, uses the Let’s Encrypt staging environment. Recommended for testing; staging issues untrusted certs but has much higher rate limits.

Example

use tachyon_web::{Router, Server, get};

async fn hello() -> &'static str { "Hello, HTTPS World!" }

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    #[cfg(feature = "lets-encrypt")]
    {
        let app = Router::new().route("/", get(hello));

        Server::new(app)
            .serve_all_acme(
                "0.0.0.0:443",
                "0.0.0.0:80",
                vec!["example.com".to_string(), "www.example.com".to_string()],
                "admin@example.com".to_string(),
                "/var/cache/tachyon/certs",
                false,  // false = production Let's Encrypt
            )
            .await?;
    }
    Ok(())
}

Errors

Returns an error if:

• The HTTP or HTTPS addresses cannot be bound.
• The ACME account cannot be created or loaded.
• Certificate provisioning fails (after exhausting retries).

Trait Implementations

impl<S> Clone for Server<S>

where S: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug> Debug for Server<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.