Crate tokio_listener

Source
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)
  • 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§