Mercurial > crates > systemd-socket
annotate README.md @ 26:0feab4f4c2ce
Relax version requirements and update MSRV
The MSRV was accidentally increased without documentation. Increase
itself is fine since it satisfies "latest stable Debian" condition but
given there are soundness issues this relaxes the version requirements
to work on 1.48 and also documents it.
| author | Martin Habovstiak <martin.habovstiak@gmail.com> |
|---|---|
| date | Fri, 28 Feb 2025 23:10:11 +0100 |
| parents | f6334887e3c8 |
| children |
| 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. |
|
26
0feab4f4c2ce
Relax version requirements and update MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
21
diff
changeset
|
60 That is currently Rust 1.48.1. (Debian 11 - Bullseye) |
|
3
0edcde404b02
Added information about MSRV
Martin Habovstiak <martin.habovstiak@gmail.com>
parents:
0
diff
changeset
|
61 |
| 0 | 62 ## License |
| 63 | |
| 64 MITNFA |