Mercurial > crates > systemd-socket
annotate README.md @ 4:66c0e10c89fc
Support resolving hostnames
Until now the crate supported only IP addresses and systemd sockets.
This was troublesome because it prevented the popular `localhost:1234`
format. This commit changes the behavior so that if parsing of
`std::net::SocketAddr` fails it attempts to parse it as `hostname:port`.
`bind_*()` methods were also modified to be async because of this.
| author | Martin Habovstiak <martin.habovstiak@gmail.com> |
|---|---|
| date | Fri, 27 Nov 2020 15:05:19 +0100 |
| parents | 0edcde404b02 |
| children | a7893294e9b2 |
| rev | line source |
|---|---|
| 0 | 1 # systemd socket |
| 2 | |
| 3 A convenience crate for optionally supporting systemd socket activation. | |
| 4 | |
| 5 ## About | |
| 6 | |
| 7 The goal of this crate is to make socket activation with systemd in your project trivial. | |
| 8 It provides a replacement for `std::net::SocketAddr` that allows parsing the bind address from string just like the one from `std` | |
| 9 but on top of that also allows `systemd://socket_name` format that tells it to use systemd activation with given socket name. | |
| 10 Then it provides a method to bind the address which will return the socket from systemd if available. | |
| 11 | |
| 12 The provided type supports conversions from various types of strings and also `serde` and `parse_arg` via feature flag. | |
| 13 Thanks to this the change to your code should be minimal - parsing will continue to work, it'll just allow a new format. | |
| 14 You only need to change the code to use `SocketAddr::bind()` instead of `TcpListener::bind()` for binding. | |
| 15 | |
|
4
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
16 Further, the crate also provides methods for binding `tokio` 0.2, 0.3, and `async_std` sockets if the appropriate features are |
|
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
17 activated. |
| 0 | 18 |
| 19 ## Example | |
| 20 | |
| 21 ```rust | |
| 22 use systemd_socket::SocketAddr; | |
| 23 use std::convert::TryFrom; | |
| 24 use std::io::Write; | |
| 25 | |
| 26 let mut args = std::env::args_os(); | |
| 27 let program_name = args.next().expect("unknown program name"); | |
| 28 let socket_addr = args.next().expect("missing socket address"); | |
| 29 let socket_addr = SocketAddr::try_from(socket_addr).expect("failed to parse socket address"); | |
| 30 let socket = socket_addr.bind().expect("failed to bind socket"); | |
| 31 | |
| 32 loop { | |
| 33 let _ = socket | |
| 34 .accept() | |
| 35 .expect("failed to accept connection") | |
| 36 .0 | |
| 37 .write_all(b"Hello world!") | |
| 38 .map_err(|err| eprintln!("Failed to send {}", err)); | |
| 39 } | |
| 40 ``` | |
| 41 | |
| 42 ## Features | |
| 43 | |
| 44 * `serde` - implements `serde::Deserialize` for `SocketAddr` | |
| 45 * `parse_arg` - implements `parse_arg::ParseArg` for `SocketAddr` | |
|
4
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
46 * `tokio_0_2` - adds `bind_tokio_0_2` method to `SocketAddr` |
|
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
47 * `tokio_0_3` - adds `bind_tokio_0_3` method to `SocketAddr` |
|
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
48 * `async_std` - adds `bind_async_std` method to `SocketAddr` |
| 0 | 49 |
|
3
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
50 ## MSRV |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
51 |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
52 This crate must always compile with the latest Rust available in the latest Debian stable. |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
53 That is currently Rust 1.41.1. (Debian 10 - Buster) |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
54 |
| 0 | 55 ## License |
| 56 | |
| 57 MITNFA |