Mercurial > crates > systemd-socket
annotate README.md @ 21:f6334887e3c8
Support `tokio` 1.0
Tokio 1.0 was already out for a while and this adds the missing support
for it. Deprecation of 0.2 and 0.3 is planned but they are staying for
now.
| author | Martin Habovstiak <martin.habovstiak@gmail.com> |
|---|---|
| date | Sat, 13 Jul 2024 15:09:13 +0200 |
| parents | f740dadd2948 |
| children | 0feab4f4c2ce |
| 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` | |
|
21
f6334887e3c8
Support `tokio` 1.0
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
13
diff
changeset
|
52 * `tokio` - adds `bind_tokio` method to `SocketAddr` |
|
4
66c0e10c89fc
Support resolving hostnames
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
3
diff
changeset
|
53 * `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
|
54 * `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
|
55 * `async_std` - adds `bind_async_std` method to `SocketAddr` |
| 0 | 56 |
|
3
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
57 ## MSRV |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
58 |
|
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
59 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
|
60 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
|
61 |
| 0 | 62 ## License |
| 63 | |
| 64 MITNFA |