Crate tokio_listener

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)
• inetd — Enable inetd (stdin/stdout) mode
• unix — Enable UNIX socket mode
• unix_path_tools — Enable tools such as unlink/chmod/chown for UNIX path sockets in UserOptions
• sd_listen — Enable receiving pre-bound sockets from inherited file descriptor (e.g. from systemd). Disabling this should make the crate unsafe-free.
• socket_options — 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
• 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)

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

Modules

axum07

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.

ListenerAddressLFlag

Clap helper to provide optional listener address a named argument --listen-address or -l.

ListenerAddressPositional

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)

TcpKeepaliveParams

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

UnixChmodVariant

Value of --unix-listen-chmod option which allows changing DAC file access mode for UNIX path socket