Documentation Request about Ping Pong

[Zamiell]

Hello nhooyr,

In gorilla/websocket, end-users must explicitly handle pings and pongs. From what I am reading on the issues forum, nhooyr/websocket handles this automatically. This is also implied by reading the source code from the chat example, which doesn't seem to have any ping pong code.

Can this please be documented front and center in the README? Right now, the README simply states that there is a "Ping pong API", but this doesn't communicate to the end user whether or not they should be writing pong pong code in their application or not.

Maybe the text of "Ping pong API" should be changed to "Automatic handling of pings and pongs, with an API exposing functionality for advanced users", or something along those lines. I would write a PR, but it's a one line change and you can probably word it the way you want yourself.

The reason that this seems important is that I expect typical writers of Go software will have used gorilla/websocket in the past, and are used to handling ping/pongs, so this will be a repeated point of confusion as more and more users use this library.

In closing, thanks for the library.

[nhooyr]

Hi @Zamiell

I've been a little busy but I did actually add a ping/pong example into the README dev branch but it hasn't been merged into master yet.

See https://github.com/nhooyr/websocket/blob/fdc407913d18e6fff8feacf9bc50f8545c234d9d/example_test.go#L138-L161

The library responds to pongs automatically as long as you have a goroutine in read but you must send pings yourself if you need them.

Also see https://pkg.go.dev/nhooyr.io/websocket#Conn.Ping and https://pkg.go.dev/nhooyr.io/websocket#Conn.CloseRead

[nhooyr]

Sorry, I meant I added the example to the dev branch.

[Zamiell]

Thanks for the quick response.

The library responds to pongs automatically as long as you have a goroutine in read

Forgive me, but I am new to this library. What does a "goroutine in read" mean? I opened up the chat example, and it doesn't seem to have any goroutines that are reading stuff.

you must send pings yourself if you need them.

Can you go into a bit more detail here? Apologies, I have not read the WebSocket RFC myself, but presumably a WebSocket server needs to send ping messages to the client after some interval. Which means that presumably everybody would need to send pings, right?

[nhooyr]

Forgive me, but I am new to this library. What does a "goroutine in read" mean? I opened up the chat example, and it doesn't seem to have any goroutines that are reading stuff.

A goroutine that is currently in a c.Reader call. i.e it's actively reading frames from the connection.

Can you go into a bit more detail here? Apologies, I have not read the WebSocket RFC myself, but presumably a WebSocket server needs to send ping messages to the client after some interval. Which means that presumably everybody would need to send pings, right?

There's no requirement to send ping messages to the client. Most of the time TCP keep alives are enough. If you need to send pings, you have to start a goroutine that calls c.Ping at some interval but also ensure there's some other goroutine actively calling c.Reader or c.Read.

If that doesn't make sense, I can update the chat example for you to see what it's like.

[nhooyr]

So yea to be clear, the chat example at the moment does not do a ping/pong because it doesn't need to. Go's HTTP server has TCP keep alives enabled by default.

As part of #227 I was thinking of adding a second example demonstrating ping/pongs and given this has popped up on the issue tracker multiple times now, it's definitely a good idea.

Also give #226 a read as well, I clarified the behaviour in that thread as well.

[Zamiell]

Thanks.
So it sounds like by default, WebSocket server applications should not be sending pings to clients.
I was not aware of that when opening this issue, so that kind of changes the premise of my original request.

This is all a little confusing because the gorilla/websocket chat example has code for doing pings, and it looks to be important for managing a proper read deadline, correct me if I am wrong.
Additionally, the melody WebSocket framework lists that one of its features is "automatic handling of ping/pong and session timeouts", which implies that gorilla/websocket does not have these features out of the box, and that these features are necessary for a good WebSocket connection.
(Does nhooyr/websocket have automatic session timeouts?)

Perhaps a short discussion of this in the README.md might be useful for those who are shopping around for Golang WebSocket frameworks.

@Zamiell The following features are the same between the current package and gorilla:

• Both packages automatically respond to ping with a pong.
• Both packages require the application to read the connection to process control messages.
• The decision to rely on TCP keep alive or to use ping and pong is the same.
• The application must explicitly send pings. The packages do not send pings automatically.

The difference is in the API for detecting the pong. In the current package, the Ping method sends a ping and returns on receipt of the corresponding pong or cancelation of the context. If the error returned from Ping is nil, then the pong was received.

The gorilla package has a lower-level API. The API to write a ping does not wait for the pong. Instead, the application registers a pong handler to receive pongs. The API in the current package can be written using the gorilla API, but not vice versa.

An application cannot use ping/pong to manage the read deadline in the current package because the package does not expose an API for setting the read deadline.

[nhooyr]

Everything @TaylorRex has said is correct except for this:

An application cannot use ping/pong to manage the read deadline in the current package because the package does not expose an API for setting the read deadline.

It doesn't directly but you can still do it! See #87
That's how the net.Conn adapter for example works and implements SetReadDeadline.

I documented it at some point but I guess I accidentally removed it when refactoring the docs.

@nhooyr I didn't mean to imply that the application cannot put a time bound on reading data.

Let me rephrase the last point: The gorilla examples use ping/pong and the read deadline on the underlying network connection to detect dead clients. That approach is not possible with the current package because the current package does not have an API for setting the read deadline on the underlying network connection.

Applications using the current package can use ping/pong to handle dead clients, but the code is different.

[Zamiell]

Thanks for the discussion.

Applications using the current package can use ping/pong to handle dead clients,

Presumably, when using nhooyr/websocket, dead clients will automatically be cleaned up and have the corresponding Close() method called when the TCP keepalive expires.

Can you elaborate on why application-authors would want to write extra code to handle ping pongs in order to handle dead clients? What application use-case would not be able to rely on a TCP keepalive?

Ping/pong more reliably detects dead peer applications when proxies are in play. Also, ping/pong helps with proxies that close inactive connections.

[Zamiell]

Both of those sound like general enough & common enough things such that every application would want to have ping pongs. Or is that not true?

Maybe some specialized application would want to omit ping/pong if they were optimizing for the minimum amount of network packets sent, or something?

[Zamiell]

Is the tradeoff here simply more reliable connections through proxies versus a little bit of extra network traffic? If so, it seems like a no brainer to take that tradeoff.

If it is indeed the case that the vast majority of non-specialized Golang applications would want to handle the relatively-common case of handling WebSocket users behind proxies, then why doesn't the nhooyr/websocket library just handle sending pings to clients for me? Ideally, I would not want to stick ping pong code in my app - those are the kind of low-level details that I would prefer a WebSocket library abstract away from me. Or is nhooyr/websocket meant to be only be a lower level library, mimicking the functionality of gorilla?

(Hopefully it doesn't sound like I am complaining, I am just legitimately curious. =p)