Document that the SocketAddr memory representation is not stable

[faern]

Intended to help out with #78802. Work has been put into finding and fixing code that assumes the memory layout of SocketAddrV4 and SocketAddrV6. But it turns out there are cases where new code continues to make the same assumption (example).

The memory layout of a type in std is never part of the public API. Unless explicitly stated I guess. But since that is invalidly relied upon by a considerable amount of code for these particular types, it might make sense to explicitly document this. This can be temporary. Once #78802 lands it does not make sense to rely on the layout any longer, and this documentation can also be removed.

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[faern]

r? @sfackler

Because you are the reviewer of #78802

[sfackler]

@bors r+ rollup

[bors]

📌 Commit 147316a has been approved by sfackler

[the8472]

I am slightly concerned about explicitly mentioning the absence of a guarantee. Does that now mean that every type that doesn't say this implicitly has such a guarantee? Of course it doesn't, but it would be nice if it could be phrased in a way that makes it clear that we just happen to spell out what already is and has been the default policy.

[faern]

@the8472 Is that properly documented somewhere? The fact that the memory layout is not part of a types stable API. If so, we could link to it maybe? The SocketAddr documentation does not feel like the correct place to state properties about the entire std IMHO.

[the8472]

https://doc.rust-lang.org/reference/type-layout.html#the-default-representation

The Default Representation

Nominal types without a repr attribute have the default representation. Informally, this representation is also called the rust representation.
There are no guarantees of data layout made by this representation.

The rustonomicon says roughly the same.

There are more details in the UCG, but they're not normative yet.

But there is a much simpler fact that establishes that the internals of SocketAddr are not public: The fields are not pub, and the absence of that means they're private, aka not part of the API.

[faern]

But there is a much simpler fact that establishes that the internals of SocketAddr are not public: The fields are not pub, and the absence of that means they're private, aka not part of the API.

I'm not disagreeing with you. But it's a fact that at least nine different crates have assumed they can rely on the memory layout of these types. So just as a temporary precaution while trying to make the change of implementation happen we can try to not continue making the same mistake.

[the8472]

But it's a fact that at least nine different crates have assumed they can rely on the memory layout of these types.

We'd have to ask the authors, but my guess it's due to a lack of conversion APIs between the std SocketAddr type to the libc types. You need them if you actually want to make syscalls and writing those conversions is a bit tedious if you want to unpack IPv4, IPv6, ports, scope IDs, ...
So people take the shortcut and ignore the distinction between implementation details and API surface to fill that gap.

Looking at the fixup PRs that's 100LoC replicated over several crates.

[faern]

People should bring in socket2 to get the conversion, if they don't want to implement it by themselves: https://docs.rs/socket2/0.4.0/socket2/struct.SockAddr.html#impl-From%3CSocketAddr%3E.

std should not offer conversion to and from libc types as std does not depend on libc (publicly). And since the entire point of this is to move the SocketAddr types to core, the types become even more foreign to libc.

[faern]

socket2 has provided conversion to and from the system representation since basically forever. A bunch of the fix PRs I have submitted to various libraries to patch this up could probably have used socket2 instead of duplicating a lot of conversion code indeed!

[the8472]

socket2 is owned by rust-lang, could we just link there?