Crate tokio_listener

Expand description

Library for abstracting over TCP server sockets, UNIX server sockets, inetd-like mode.

ListenerAddress is like SocketAddr and Listener is like TcpListener, but with more flexibility.

let addr1 : ListenerAddress = "127.0.0.1:8087".parse().unwrap();
let addr2 : ListenerAddress = "/path/to/socket".parse().unwrap();
let addr3 : ListenerAddress = "@abstract_linux_address".parse().unwrap();

let system_options : SystemOptions = Default::default();
let user_options : UserOptions = Default::default();

let mut l = Listener::bind(&addr1, &system_options, &user_options).await.unwrap();
while let Ok((conn, addr)) = l.accept().await {
    // ...
}

There is special integration with clap:

use clap::Parser;

#[derive(Parser)]
/// Demo application for tokio-listener
struct Args {
    #[clap(flatten)]
    listener: tokio_listener::ListenerAddressPositional,
}

let args = Args::parse();

let listener = args.listener.bind().await.unwrap();

let app = axum06::Router::new().route("/", axum06::routing::get(|| async { "Hello, world\n" }));

axum06::Server::builder(listener).serve(app.into_make_service()).await;

See project README for details and more examples.

§Feature flags

clap — Enable derive(Parser) for UserOptions and other Clap helpers
user_facing_default (enabled by default) — Subset of default features that add features supposed to be accessed by end user
serde — Enable serde::Serialize and serde::Deserialize implementations for UserOptions and ListenerAddress and some other types.
hyper014 — Enable hyper(v0.14)::server::accept::Accept implementation for Listener
axum07 — Enable tokio-listener-adapted serve function from Axum 0.7 (and related types)
axum08 — Enable axum::Listener implementation for Axum 0.8
inetd (enabled by default) — Enable inetd (stdin/stdout) mode
unix (enabled by default) — Enable UNIX socket mode
unix_path_tools (enabled by default) — Enable tools such as unlink/chmod/chown for UNIX path sockets in UserOptions
sd_listen (enabled by default) — Enable receiving pre-bound sockets from inherited file descriptor (e.g. from systemd). Disabling this should make the crate unsafe-free.
socket_options (enabled by default) — Enable socket options such as receive or send buffer sizes or keepalives in UserOptions
tonic010 — Enable tonic(v0.10)::transport::server::Connected implementation for Connection
tonic011 — Enable tonic(v0.11)::transport::server::Connected implementation for Connection
tonic012 — Enable tonic(v0.12)::transport::server::Connected implementation for Connection
tonic013 — Enable tonic(v0.13)::transport::server::Connected implementation for Connection
tokio-util (enabled by default) — Enable tokio_util::net::Listener implementation for Listener.
multi-listener — Enable Listener::bind_multiple and sd-listen:* (if combined with sd_listen feature)
duplex_variant — Add tokio::io::DuplexStream variant to Connection for extra flexibility (cannot be triggered by end user, only by API).
dummy_variant — Add tokio::io::Empty variant to Connection for extra flexibility (cannot be triggered by end user, only by API).
boxed_variant — Add Pin<Box<dyn AsyncRead + AsyncWrite + Send>> variant to Connection for extra flexibility (cannot be triggered by end user, only by API). In particular this allows using tokio_test::io::Mock as a Connection. Also allows constructing customized Listeners.
mpsc_listener — Add ability to use tokio::sync::mpsc::Receiver as a custom Listener. Can be useful for tests, together with boxed_variant.
custom_socket_address — Add additional variant to [SomeSocketAddress] for storing arbitrary content.
vsock — Enable Vsock support on Linux and Mac

Disabling default features bring tokio-listener close to usual TcpListener.

Modules§

axum07axum07: Analogue of axum::serve module, but for tokio-listener.

Structs§

Connection: Accepted connection, which can be a TCP socket, AF_UNIX stream socket or a stdin/stdout pair.
Listener: Configured TCP. AF_UNIX or other stream socket acceptor.
ListenerAddressLFlagclap: Clap helper to provide optional listener address a named argument --listen-address or -l.
ListenerAddressPositionalclap: Clap helper to require listener address as a required positional argument listen_address, for clap(flatten)-ing into your primary options struct.
SystemOptions: Listener options that are supposed to be hard coded in the code (not configurable by user)
TcpKeepaliveParamssocket_options: Value of --tcp-keepalive option.
UserOptions: User options that supplement listening address.

Enums§

AcceptError: tokio-listener-specific accept errors, to be packed in std::io::Error::other.
BindError: tokio-listener-specific bind errors, to be packed in std::io::Error::other.
ListenerAddress: Abstraction over socket address that instructs in which way and at what address (if any) [Listener] should listen for incoming stream connections.
SomeSocketAddr: Some form of accepted connection’s address. Variant depends on variant used in [ListenerAddress].
SomeSocketAddrClonable: Other representation of SomeSocketAddr with Arc-wrapped Unix addresses to enable cloning
UnixChmodVariantunix_path_tools: Value of --unix-listen-chmod option which allows changing DAC file access mode for UNIX path socket

Traits§