README.md (3696B)
1 # `tokio_dual_stack` 2 3 [<img alt="git" src="https://git.philomathiclife.com/badges/tokio_dual_stack.svg" height="20">](https://git.philomathiclife.com/tokio_dual_stack/log.html) 4 [<img alt="crates.io" src="https://img.shields.io/crates/v/tokio_dual_stack.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/tokio_dual_stack) 5 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-tokio_dual_stack-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/tokio_dual_stack/latest/tokio_dual_stack/) 6 7 `tokio_dual_stack` is a library that adds a "dual-stack" 8 [`TcpListener`](https://docs.rs/tokio/latest/tokio/net/struct.TcpListener.html). 9 10 ## Why is this useful? 11 12 Only certain platforms offer the ability for one socket to handle both IPv6 and IPv4 requests 13 (e.g., OpenBSD does not). For the platforms that do, it is often dependent on runtime configuration 14 (e.g., [`IPV6_V6ONLY`](https://www.man7.org/linux/man-pages/man7/ipv6.7.html)). Additionally those platforms 15 that support it often require the "wildcard" IPv6 address to be used (i.e., `::`) which has the unfortunate 16 consequence of preventing other services from using the same protocol port. 17 18 There are a few ways to work around this issue. One is to deploy the same service twice: one that uses 19 an IPv6 socket and the other that uses an IPv4 socket. This can complicate deployments (e.g., the application 20 may not have been written with the expectation that multiple deployments could be running at the same time) in 21 addition to using more resources. Another is for the application to manually handle each socket (e.g., 22 [`select`](https://docs.rs/tokio/latest/tokio/macro.select.html)/[`join`](https://docs.rs/tokio/latest/tokio/macro.join.html) 23 each `TcpListener::accept`). 24 25 `DualStackTcpListener` chooses an implementation similar to what the equivalent `select` would do while 26 also ensuring that one socket does not "starve" another by ensuring each socket is fairly given an opportunity 27 to `TcpListener::accept` a connection. This has the nice benefit of having a similar API to what a single 28 `TcpListener` would have as well as having similar performance to a socket that does handle both IPv6 and 29 IPv4 requests. 30 31 ## Minimum Supported Rust Version (MSRV) 32 33 This will frequently be updated to be the same as stable. Specifically, any time stable is updated and that 34 update has "useful" features or compilation no longer succeeds (e.g., due to new compiler lints), then MSRV 35 will be updated. 36 37 MSRV changes will correspond to a SemVer patch version bump pre-`1.0.0`; otherwise a minor version bump. 38 39 ## SemVer Policy 40 41 * All on-by-default features of this library are covered by SemVer 42 * MSRV is considered exempt from SemVer as noted above 43 44 ## License 45 46 Licensed under either of 47 48 * Apache License, Version 2.0 ([LICENSE-APACHE](https://www.apache.org/licenses/LICENSE-2.0)) 49 * MIT license ([LICENSE-MIT](https://opensource.org/licenses/MIT)) 50 51 at your option. 52 53 ## Contribution 54 55 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, 56 as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. 57 58 Before any PR is sent, `cargo clippy` and `cargo t` should be run. Additionally 59 `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features` should be run to ensure documentation can be built. 60 61 ### Status 62 63 This package is actively maintained and will conform to the latest version of 64 [`tokio`](https://crates.io/crates/tokio). 65 66 The crate is only tested on `x86_64-unknown-linux-gnu` and `x86_64-unknown-openbsd` targets, but it should work 67 on most platforms.