Graceful shutdown of the websocket connection.
markusthoemmes opened this issue · comments
It seems like to achieve a "normal" shutdown of a websocket connection, one needs to do a dance like:
- Send Close message
- Wait for receiving a Close message
- Actually close the connection
The Close method of today closes the connection immediately, without warning or graceful shutdown. Would it be desirable to have a Shutdown method like golang's http servers, which does the dance explained above for the user?
I think this is desirable to have, as well as in-built support for checking liveness using ping/pong and deadlines. Most applications need these features.
The current API mostly handles the wire format. The only thing the package does above the wire format is respond to ping and respond to close. This low-level API provides flexibility for the applications that need it (like the one I work on), but most don't need this flexibility.
This package can benefit from a high-level API that wraps up all these things that applications need: shutdown, checking liveness, concurrent sends, ...
@garyburd Can you please assign this issue to me. I would like to work on it.
@ankur0493 Please post a proposed API and overview of the implementation for discussion.
I tried to assign you to this issue, but Github will not let me do it. Please let me know what I need to do.
Thanks @garyburd. Will soon share the API details.
This feature is a helper method. It's possible for applications to implement the RFC today. If an application does not initiate the closing handshake, then the application probably implements the RFC without doing anything special.
Based on discussion in #487, here's my summary of the design:
To avoid concurrent reads on the connection, the following two cases must be handled differently:
- Shutdown is executed from the reading goroutine
- Shutdown in executed from some other goroutine.
The common code for both cases starts with:
err := c.WriteControlMessage(CloseMessage,FormatCloseMessage(code, msg))
if err != nil && err != ErrCloseSent {
// If close message could not be sent, then close without the handshake.
return c.Close()
}
The remaining code for the reading goroutine case is:
// To prevent ping, pong and close handlers from setting the read deadline, set these handlers to the default.
c.SetPingHandler(nil)
c.SetPongHandler(nil)
c.SetCloseHandler(nil)
c.SetReadDeadline(timeout)
for {
if _, _, err := c.NextReader(); err != nil {
break
}
}
return c.Close()
The remaining code for shutdown from another goroutine is:
select {
case <- c.readDone:
case <- time.After(timeout):
}
return c.Close()
where c.readDone is a channel that's closed when c.readErr is changed from nil to a non-nil value.
For someone who wants this now, I've implemented it in nhooyr.io/websocket@v1.7.0
See discussion in nhooyr/websocket#160
How to implement:
Add field to Upgrader and Dialer:
CloseTimeout time.Duration
Add field to Conn:
maxReadDeadline time.Time
When a close message is sent, CloseTimeout is not zero, and maxReadDeadline is zero, then set maxReadDeadline to time.Now().Add(CloseTimeout). Set read deadline on underlying connection to the same value.
Modify SetReadDeadline to honor maxReadDeadline.
Use a mutex to protect against data races in the code above.
Applications that set the upgrader/dialer field get graceful shutdown by sending a close message. The application’s read loop will either exit with the echoed close message or a timeout.
This proposal allows any goroutine to initiate the shutdown by using WriteControl to send a close message.