Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/networkexception/tokio-unix-tcp

Wraps the `tokio` types for Unix and TCP https://crates.io/crates/tokio-unix-tcp
https://github.com/networkexception/tokio-unix-tcp

Last synced: about 2 months ago
JSON representation

Wraps the `tokio` types for Unix and TCP https://crates.io/crates/tokio-unix-tcp

Awesome Lists containing this project

README 

        
# tokio-unix-tcp



This crate wraps the `tokio` types for Unix and TCP Listeners, Socket Addresses and Streams in a generic

enum each, with helper functions existing on both variants passed through.



On non Unix systems, all Unix specific behavior is compiled to no ops.



## Types



### Listener



Either a `tokio::net::TcpListener` or `tokio::net::UnixListener`. This wrapper allows binding to either

a path or IP address and port.



Binding returns a `Listener` instance that can be used to await new incoming connections and accept them.



Accepting a connection returns a `Socket` instance with both a `local_addr` and `peer_addr`.

The `local_peer` will be the `SocketAddr` the `Listener` is bound to and `peer_addr` will be the

remote IP address and port for a TCP socket and an unnamed unix socket address

(`UnixSocketAddr::AbstractOrUnnamed`) for a Unix socket.



Use the `Listener::bind_and_prepare_unix` function to remove an existing file at the bind path when using

Unix sockets. This function also allows adjusting the mode of the socket (defaults to `0o222`).



### UnixSocketAddr



A more developer friendly version of `tokio::net::unix::SocketAddr` for the purposes of this crate. Tokio

current does not support abstract Unix sockets, the underlying `mio::net::SocketAddr` does however.



This leaves `tokio::net::unix::SocketAddr` in an awkward state where calling `is_unnamed` could return `false`

while `as_pathname` also returns `None`. The `UnixSocketAddr` solves this by having a unified variant for

unnamed or abstract sockets.



### SocketAddr



Either a `std::net::SocketAddr` or `UnixSocketAddr`. This type is used as the local or peer address of an

established stream.



Converting to a `NamedSocketAddr` using `to_named_socket_addr` may throw in case the unix socket is

`UnixSocketAddr::AbstractOrUnnamed`, which is not representable as `NamedSocketAddr`. See the documentation

below.



### NamedSocketAddr



Either a `std::net::SocketAddr` or `std::path::PathBuf`. This type is used for creating a socket (connecting) or

creating a listener (binding).



This type differs from `SocketAddr` in that it does not have an unnamed variant for the Unix socket. In case Tokio

starts to support abstract unix socket, the `NamedSocketAddr::Unix` variant will also have to support this instead

of just a `std::path::PathBuf`.



Converting to a `SocketAddr` using `to_socket_addr` always succeeds.



### Stream



Either a `tokio::net::TcpStream` or `tokio::net::UnixStream`. This wrapper allows opening a new connection to either

a path or IP address and port.



When connecting succeeds it returns a `Socket` instance with both a `local_addr` and `peer_addr`.

The `local_peer` will be the local IP address and port for a TCP socket and an unnamed unix socket

address (`UnixSocketAddr::AbstractOrUnnamed`) for a Unix socket and `peer_addr` will be the remote

`SocketAddr` (so IP address and port or path) of the server.



## Flags and Compile Targets



Enabling the `serde` flag adds serializer and deserializer helpers for `SocketAddr` and `NamedSocketAddr`.



Compiling on non `unix` systems will exclude all unix specific functionality and imports. TCP will still work

perfectly fine.



## Related work



- [`multisock`](https://crates.io/crates/multisock) for unifying `std::net` and `std::os::unix::net` types

- [`async-uninet`](https://crates.io/crates/async-uninet) for unifying async types from `async_std` and types from `std`



As far as I can tell both of these don't handle the nuances of abstract and unnamed unix sockets very well, which

this create also aims to fix.



## License



This crate is permissively licensed under either the [BSD 2-Clause "Simplified" License](https://spdx.org/licenses/BSD-2-Clause)

or [MIT License](https://spdx.org/licenses/MIT).