[mhelkey]

Stabilization Report

Closes #150487

Implementation History

Unix domain socket support (UDS) on Windows was added in #150428.

API Summary

A summary of the API is included at the top of this tracking issue.

mod std::os::windows::net {
    pub struct SocketAddr; 
    pub struct UnixStream; 
    pub struct UnixListener; 

    impl SocketAddr { 
        pub fn from_pathname<P: AsRef<Path>>(path: P) -> io::Result<SocketAddr>; 
        pub fn as_pathname(&self) -> Option<&Path>; 
        pub fn is_unnamed(&self) -> bool; 
    }

    impl UnixStream { 
        pub fn connect<P: AsRef<Path>>(path: P) -> io::Result<UnixStream>; 
        pub fn connect_addr(socket_addr: &SocketAddr) -> io::Result<UnixStream>; 
        pub fn try_clone(&self) -> io::Result<UnixStream>; 
        pub fn local_addr(&self) -> io::Result<SocketAddr>; 
        pub fn peer_addr(&self) -> io::Result<SocketAddr>; 
        pub fn set_read_timeout(&self, dur: Option<Duration>) -> io::Result<()>; 
        pub fn set_write_timeout(&self, dur: Option<Duration>) -> io::Result<()>; 
        pub fn read_timeout(&self) -> io::Result<Option<Duration>>; 
        pub fn write_timeout(&self) -> io::Result<Option<Duration>>; 
        pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()>; 
        pub fn take_error(&self) -> io::Result<Option<io::Error>>; 
        pub fn shutdown(&self, how: Shutdown) -> io::Result<()>; 
    } 

    impl UnixListener { 
        pub fn bind<P: AsRef<Path>>(path: P) -> io::Result<UnixListener>; 
        pub fn bind_addr(socket_addr: &SocketAddr) -> io::Result<UnixListener>; 
        pub fn accept(&self) -> io::Result<(UnixStream, SocketAddr)>; 
        pub fn try_clone(&self) -> io::Result<UnixListener>; 
        pub fn local_addr(&self) -> io::Result<SocketAddr>; 
        pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()>; 
        pub fn take_error(&self) -> io::Result<Option<io::Error>>; 
        pub fn incoming(&self) -> Incoming<'_>; 
    } 
} 

Unix vs Windows diff

	Unix	Windows
Module	std::os::unix::net	std::os::windows::net
Types	UnixStream, UnixListener, SocketAddr, Incoming	same names
Inner fd access	AsFd / AsRawFd (OwnedFd, RawFd)	AsSocket / AsRawSocket (OwnedSocket, RawSocket)
UnixDatagram	yes	Not supported on the platform
SocketAddr from abstract namespace	yes	Not supported on the platform
Ancillary / SCM_RIGHTS fd passing	yes	Not supported on the platform
pair()	yes	Not supported on the platform

The core APIs for UDS (UnixStream, UnixListener, etc) are largely the same across Unix and Windows when using socket paths.

Windows does not support abstract paths in AF_UNIX, and as such UDS on Windows would not support creating a SocketAddr from an abstract path.

Due to this divergence, I recommend that we maintain the current structure with two separate implementations in OS specific locations (std::os::unix::net and std::os::windows::net).

Out of scope for this stabilization is presenting a unified interface if one exists.

Experience Report

The uds_windows crate which provides similar functionality has 55 million downloads, showing demand for this feature in std.

Additionally, uds_windows only provides a synchronous interface. Once std aligns on the interface, mio and tokio intend to mirror it to provide an async interface.

We'd like to use this at $work (currently using https://docs.rs/uds-windows). We've confirmed that moving from uds-windows to the std API doesn't run into any issues in our integration tests (or feature compatibility).

Mark-Simulacrum already reported our experience using this nightly API at $WORK.

To provide some additional detail, we have a shared crate that provides a shared interface across Windows and Unix via cfg gating on the OS. We verified that UDS created using a socket path works on both Unix and Windows.

#150487 (comment)

I think we have sufficient evidence that we can stabilize this feature as is.

I wrote the PR description entirely by hand, while copying format and some language from example stabilization reports (#88581 (comment), #163696) as this is my first stabilization report.

LLM usage disclosure: I used an LLM which pulled function headers for Unix and Windows variants of Unix Domain socket and generated the first draft of the diff chart.

[rustbot]

Thanks for the pull request, and welcome! The Rust Project has assigned @Mark-Simulacrum (or someone else) to review your changes, you should hear from them (or someone else) within the next two weeks.

Please see the contribution instructions and our LLM policy for more information.

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 37 candidates
• Random selection from ChrisDenton, JohnTitor, Mark-Simulacrum

[rust-bors]

☔ The latest upstream changes (presumably #165056) made this pull request unmergeable. Please resolve the merge conflicts by rebasing.

[ChrisDenton]

@rfcbot merge libs

[rust-rfcbot]

@ChrisDenton has proposed to merge this. The next step is review by the rest of the tagged team members:

• @ChrisDenton
• @Mark-Simulacrum
• @cuviper
• @dtolnay
• @joshtriplett
• @nia-e
• @the8472
• @thomcc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/libs-ping: FCP proposed for libs, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.