11 unstable releases (3 breaking)
0.4.3 | Jul 9, 2024 |
---|---|
0.4.2 | May 15, 2024 |
0.3.2 | Mar 16, 2024 |
0.3.1 | Feb 7, 2024 |
0.1.0 | Jul 30, 2023 |
#619 in Network programming
96 downloads per month
Used in 3 crates
110KB
2K
SLoC
Rationale
Web service projects created using Hyper or Axum Rust frameworks typically allow users to specify TCP port and host to bind to in order to listen for incoming connetions. While it is a solid default choice, sometimes more flexibility is desired, especially on Linux.
tokio-listener
allows to add this flexibility by offering special abstract types ListenerAddress
and Listener
instead of typical SocketAddr
and TcpListener
, allowing adding this flexibility to projects in easy way.
Features
Listening modes
- Listening UNIX socket instead of TCP socket. It is triggered by beginning the address with
.
or/
. - Listening abstract-namespaced UNIX socket on Linux. It is triggered by beginning the address with
@
. - Accepting connections from a pre-opened socket inherited from parent process (e.g. systemd). This is triggered by special address
sd-listen
. You can also request a specific named or all sockets. - Inetd mode - stdin/stdout can also be used for serving one connection.
Other
- Portability - tricky features are not compiled on platforms which do not support them
clap
integration - custom address can be added as a Clap field (due to FromStr impl). Other options can be included byclap(flatten)
, which also brings short documentation to the CLI help message. Alternatively, the whole set of primary address and additional options can be brought in usingListenerAddressPositional
orListenerAddressLFlag
helper types.serde
intergration - custom address type behaves like a string with respect to Serde. Other options can also be serialized or deserialized.- For UNIX path sockets, it supports unlinking, chowning and chmodding the file per user request.
axum 0.7
integration.- Multi-listener - easy was to bind to multiple ports simulteneously. Combined with systemd support, also allows to trigger multi-listen using special
sd-listen:*
address. Not enabled by default. - Fine-grained compile-time feature switches. Without features it should basically reduce to a thin wrapper around plain
TcpListener
.
Examples
- clap_axum - simplest, most straighforward example. Uses Clap as CLI framework and Axum as web framework. There are two versions of the example: one for Axum 0.6, the other for Axum 0.7.
- argh_hyper - demonstrages how to use non-clap CLI parser. Also uses
hyper
directly instead of Axum. - serde_echo - demonstrates that listening configuration can also be specified using e.g. toml file. Is not a web service, but an echo server.
See crate docs for API reference and some other examples.
Limitations
- There is no support of SEQPACKET or DGRAM sockets.
- It may be slower that just using TcpListener directly, as each send or recv needs to go though a wrapper. This slowdown should disappear if you disable UNIX and inetd modes at compilation time.
- Specifying non-UTF8-compatible paths for UNIX sockets is not supported.
Example session
Given this series of invocations:
target/debug/examples/clap_axum07 127.0.0.1:8080 $'Hello from usual mode\n'
target/debug/examples/clap_axum07 ./path_socket $'Hello from UNIX socket path mode\n'
target/debug/examples/clap_axum07 @abstract_socket $'Hello from UNIX socket abstract mode\n'
systemd-socket-activate -l 8081 target/debug/examples/clap_axum07 sd-listen $'Hello from pre-listened socket\n'
systemd-socket-activate --inetd -al 8082 target/debug/examples/clap_axum07 inetd $'Hello from inetd mode\n'
systemd-socket-activate -l 8083 -l 8084 --fdname=foo:bar -- target/debug/examples/clap_axum07 sd-listen:bar $'Hello from a named pre-listened socket\n'
systemd-socket-activate -l 8085 -l 8086 -- target/debug/examples/clap_axum07 sd-listen:* $'Hello from any of the two pre-listened sockets\n'
and this Caddyfile:
{
admin off
}
:4000
handle_path /tcp/* {
reverse_proxy 127.0.0.1:8080
}
handle_path /unix/* {
reverse_proxy unix/./path_socket
}
handle_path /abstract/* {
reverse_proxy unix/@abstract_socket
}
handle_path /sdlisten/* {
reverse_proxy 127.0.0.1:8081
}
handle_path /inetd/* {
reverse_proxy 127.0.0.1:8082
}
you can see that effectively the same service can be accessed in multiple ways:
$ curl http://127.0.0.1:4000/tcp/
Hello from usual mode
$ curl http://127.0.0.1:4000/unix/
Hello from UNIX socket path mode
$ curl http://127.0.0.1:4000/abstract/
Hello from UNIX socket abstract mode
$ curl http://127.0.0.1:4000/sdlisten/
Hello from a pre-listened socket
$ curl http://127.0.0.1:4000/inetd/
Hello from inetd
$ curl --unix ./path_socket http://q/
Hello from UNIX socket path mode
$ curl --abstract-unix abstract_socket http://q/
Hello from UNIX socket abstract mode
Help message of one of the examples
Demo application for tokio-listener
Usage: clap_axum [OPTIONS] <LISTEN_ADDRESS> <TEXT_TO_SERVE>
Arguments:
<LISTEN_ADDRESS>
Socket address to listen for incoming connections.
Various types of addresses are supported:
* TCP socket address and port, like 127.0.0.1:8080 or [::]:80
* UNIX socket path like /tmp/mysock or Linux abstract address like @abstract
* Special keyword "inetd" for serving one connection from stdin/stdout
* Special keyword "sd-listen" to accept connections from file descriptor 3 (e.g. systemd socket activation).
You can also specify a named descriptor after a colon or * to use all passed sockets (if this feature is enabled).
<TEXT_TO_SERVE>
Line of text to return as a body of incoming requests
Options:
--unix-listen-unlink
remove UNIX socket prior to binding to it
--unix-listen-chmod <UNIX_LISTEN_CHMOD>
change filesystem mode of the newly bound UNIX socket to `owner`, `group` or `everybody`
--unix-listen-uid <UNIX_LISTEN_UID>
change owner user of the newly bound UNIX socket to this numeric uid
--unix-listen-gid <UNIX_LISTEN_GID>
change owner group of the newly bound UNIX socket to this numeric uid
--sd-accept-ignore-environment
ignore environment variables like LISTEN_PID or LISTEN_FDS and unconditionally use file descritor `3` as a socket in sd-listen or sd-listen-unix modes
--tcp-keepalive <TCP_KEEPALIVE>
set SO_KEEPALIVE settings for each accepted TCP connection.
Value is a colon-separated triplet of time_ms:count:interval_ms, each of which is optional.
--tcp-reuse-port
Try to set SO_REUSEPORT, so that multiple processes can accept connections from the same port in a round-robin fashion
--recv-buffer-size <RECV_BUFFER_SIZE>
Set socket's SO_RCVBUF value
--send-buffer-size <SEND_BUFFER_SIZE>
Set socket's SO_SNDBUF value
--tcp-only-v6
Set socket's IPV6_V6ONLY to true, to avoid receiving IPv4 connections on IPv6 socket
--tcp-listen-backlog <TCP_LISTEN_BACKLOG>
Maximum number of pending unaccepted connections
-h, --help
Print help (see a summary with '-h')
All this can be brought in with just one #[clap(flatten)] addr: tokio_listener::ListenerAddressPositional
.
Dependencies
~3–14MB
~157K SLoC