x/net/websocket: The documentation should make it clear that the package is retired

[mortie]

What is the URL of the page with the issue?

https://pkg.go.dev/golang.org/x/net/websocket

What is your user agent?

N/A

Screenshot

What did you do?

I read the documentation

What did you expect to see?

I expected to see some wording about how the package is retired (which it is according to #2134) and should not be used

What did you see instead?

I saw completely normal looking documentation for a package with no warning or indication that the package is retired. There is the suggestion that the package "lacks some features" found in other libraries, but as my needs are very basic, that did not stand out to me as a problem.

Luckily, I tried reasoning about the API and couldn't understand how one would read frames whose length is a multiple of len(buf) and asked someone on IRC who pointed out that the aforementioned issue claims the package is retired.

Since the library is retired, and the API is problematic (for reasons discussed in the other issue), I believe the docs page should make it clear that new code should not be written using x/net/websocket. As it is part of the high-profile and official x/net, I'm probably not the first or last person to gravitate towards it.

[seankhliao]

Duplicate of #18152

[ruyi789]

这个包满足我的，因为很小，而且是官方维护。唯一不足的地方大多数人没法用它，因为不会Read。

var c *websocket.Conn
var buf bytes.Buffer
b := make([]byte, 1024)

for {
	n, err := c.Read(b)

	if n > 0 {
		buf.Write(b[:n])
	} else if err != nil {
		return
	}

	//处理帧数据，你可能有如下三种判断之一：

	if err == io.EOF { //表示帧结束? 但是你可能永远等不到io.EOF这个值
		//处理帧数据
		buf.Reset()
	}

	//或者
	if buf.Len() == c.Len() { //c.Len()? 这方法返回没有准确表达我需要的条件，不知道有什么作用:frame.Length?
		//处理帧数据
		buf.Reset()
	}

	//或者
	if buf.Len() == int(c.FrameDataLenth()) { //ok,非常棒。但是 websocket.Conn 没有这个方法：FrameDataLenth=frame.header.Length
		//处理帧数据
		buf.Reset()
	}

}