Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
net: *Conn.ReadMsgXXX documentation could be improved #30346
Unfortunately, this is documentation/API request more than a 'bug'. I started this needing to know what interface a UDP message was received on, and immediately ran into an interface limitation.
Summary: ReadMsgXXX is impossible to use without a priori knowledge of the underlying network API that Go uses. Furthermore, the documentation for said methods refers the user to another package, without explaining what to look for in said package.*
Either the documentation for UdpConn.ReadMsgUDP and/or the function's mere existence in it's current form are at best useless (I understand how frustrating this statement is, but unfortunately this is the case). Additionally, while this message is primarily regarding UdpConn.ReadMsgUDP, it is likely equally applicable to all the net/x ReadMsgXXX (and possibly the WriteMsgXXX) functions as well.
The fundamental problem, which I'm certain you are aware of, is that every different OS stack behaves differently and reports different pieces of information in different ways. However, as written, the documentation does not explain anything about what is the user needs to access the out-of-band data. It only says:
But not anything about how to do that.
The user has to already understand the underlying network stack enough to connect the 'out-of-band' comment in the documentation for UdpConn.ReadMsgUDP to 'control message' in the overview examples of x/net/ipv4:
Finally, after determining that these are related the user is still required to manually call Parse on the out-of-band data array to finally convert it to the ControlMessage that they require.
*I believe this redirection is referring to SetControlMessage in x/net/ipvX. However, there is no indication that this will do anything to configure the 'out-of-band' data.
I'm relieved to see the word "useless" instead of "considered harmful" because the package net is a sort of intersection between various operating system kernels, various network- and transport-layer protocols. The API surfaces and docs are able to propagate wrong information easily, to mislead API users into doing wrong things. I agree that the documentation update is necessary; see also #29978.
Requests for more better API surfaces should be addressed in #28900. The current API surfaces have a history, for example, @rsc vs. @mikioh :), wandering ipv4 and ipv6 packages and settlement of the x/net repository. #28900 is a new hope.
I think the documentation for
@antong As both a library developer and library user, there is a reason why I hold that the documentation is not ok and is in fact useless. If we look at the actual purpose of a library, we find that it exists to provide an abstraction of commonly repeated behaviors and simplify the job of the developer using the library. Examining the net package, the majority of the API revolves around interacting with network protocols and paradigms; not the underlying OS level API.
The net library exists for the explicit purpose of allowing a developer to work with network communications without understanding the intimate details of the network API of every platform. I understand now (after digging through the entirety of the net and x/net/ipv4 source) that the ReadMsgXXX methods are nothing more than a mapping layer on top of 'recvmsg', but there is no way to make that leap with only the documentation.
If ReadMsgXXX is a method that cannot be used without understanding the underlying network stack, fine! Tell me that in the documentation! Tell me what I will need to know to understand what to do! There are references to various RFCs scattered throughout the docs(!), but when we get to a function which is essentially a direct mapping onto the OS syscall, there's nothing; no mention of that, no direct pointer of what to look for in other documentation, no "Here be dragons", just some vague mention of "these other packages can be used to manipulate what is returned in oob".
@mikioh The API split between net and x/net makes a fair bit of sense, but I'll admit to not understanding the reasoning for placing SetControlMessage in x/net and not duplicated in net as well (a la ReadMsgXXX); I'm guessing there was a bit of a contentious debate on the subject.