Mercurial > crates > systemd-socket
annotate README.md @ 13:f740dadd2948
Added enable_systemd feature
This feature makes systemd support optional, on by default. While it may
seem strange that this feature exists, it makes sense for authors of
applications who want to make systemd optional. Thanks to this feature
the interface stays the same, it just fails to parse `systemd://`
addresses with a helpful error message.
| author | Martin Habovstiak <martin.habovstiak@gmail.com> |
|---|---|
| date | Thu, 03 Dec 2020 16:34:09 +0100 |
| parents | a7893294e9b2 |
| children | f6334887e3c8 |
| 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 | |
|
6
a7893294e9b2
Make the crate compilable on non-linux systems
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
4
diff
changeset
|
16 You also don't need to worry about conditional compilation to ensure OS compatibility. |
|
a7893294e9b2
Make the crate compilable on non-linux systems
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
4
diff
changeset
|
17 This crate handles that for you by disabling systemd on non-linux systems. |
|
a7893294e9b2
Make the crate compilable on non-linux systems
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
4
diff
changeset
|
18 |
|
4
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
19 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
|
20 activated. |
| 0 | 21 |
| 22 ## Example | |
| 23 | |
| 24 ```rust | |
| 25 use systemd_socket::SocketAddr; | |
| 26 use std::convert::TryFrom; | |
| 27 use std::io::Write; | |
| 28 | |
| 29 let mut args = std::env::args_os(); | |
| 30 let program_name = args.next().expect("unknown program name"); | |
| 31 let socket_addr = args.next().expect("missing socket address"); | |
| 32 let socket_addr = SocketAddr::try_from(socket_addr).expect("failed to parse socket address"); | |
| 33 let socket = socket_addr.bind().expect("failed to bind socket"); | |
| 34 | |
| 35 loop { | |
| 36 let _ = socket | |
| 37 .accept() | |
| 38 .expect("failed to accept connection") | |
| 39 .0 | |
| 40 .write_all(b"Hello world!") | |
| 41 .map_err(|err| eprintln!("Failed to send {}", err)); | |
| 42 } | |
| 43 ``` | |
| 44 | |
| 45 ## Features | |
| 46 | |
|
13
f740dadd2948
Added enable_systemd feature
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
6
diff
changeset
|
47 * `enable_systemd` - on by default, the existence of this feature can allow your users to turn |
|
f740dadd2948
Added enable_systemd feature
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
6
diff
changeset
|
48 off systemd support if they don't need it. Note that it's already disabled on non-linux |
|
f740dadd2948
Added enable_systemd feature
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
6
diff
changeset
|
49 systems, so you don't need to care about that. |
| 0 | 50 * `serde` - implements `serde::Deserialize` for `SocketAddr` |
| 51 * `parse_arg` - implements `parse_arg::ParseArg` for `SocketAddr` | |
|
4
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
52 * `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
|
53 * `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
|
54 * `async_std` - adds `bind_async_std` method to `SocketAddr` |
| 0 | 55 |
|
3
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
56 ## MSRV |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
57 |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
58 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
|
59 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
|
60 |
| 0 | 61 ## License |
| 62 | |
| 63 MITNFA |