tokio_dual_stack

Dual-stack TcpListener.
git clone https://git.philomathiclife.com/repos/tokio_dual_stack
Log | Files | Refs | README

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.