Skip to content

adding ToC and adding new section to readme #269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

adding ToC and adding new section to readme #269

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
06901ab
adding table of contents
Zamiell Dec 5, 2020
a059e1d
new section in readme
Zamiell Dec 5, 2020
abd7cc0
Update README.md
Zamiell Dec 5, 2020
1e9a8ec
Update README.md
Zamiell Dec 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,15 @@

websocket is a minimal and idiomatic WebSocket library for Go.

## Table of Contents

1. [Install](#install)
1. [Highlights](#highlights)
1. [Roadmap](#roadmap)
1. [Examples](#examples)
1. [Comparison With Other Packages](#comparison-with-other-packages)
1. [Ping/Pong](#pingpong)

## Install

```bash
Expand Down Expand Up @@ -82,7 +91,7 @@ if err != nil {
c.Close(websocket.StatusNormalClosure, "")
```

## Comparison
## Comparison With Other Packages

### gorilla/websocket

Expand Down Expand Up @@ -130,3 +139,15 @@ to nhooyr.io/websocket.
in an event driven style for performance. See the author's [blog post](https://medium.freecodecamp.org/million-websockets-and-go-cc58418460bb).

However when writing idiomatic Go, nhooyr.io/websocket will be faster and easier to use.

## Ping/Pong

Some WebSocket libraries and WebSocket applications implement pings and pongs. Is this necessary?

The WebSocket protocol (layer 7) is built on top of the HTTP protocol (layer 7), which is built on top of the TCP protocol (layer 4). TCP has a feature called [keepalive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html), which, as its name suggests, keeps long connections alive. keepalive is automatically enabled in the Golang standard standard library, so any HTTP server that you create with Golang should inherit it. By default, it [sends probes every 15 seconds and has a timeout of 3 minutes](https://golang.org/pkg/net/#Dialer).

WebSocket applications almost always need to detect when an end-user's internet has died, so that they can properly disconnect the user and clean up the relevant data structures. Using TCP keepalives for this purpose should be sufficient - meaning that we don't need to write any additional code.

Some Golang authors, such as the creators of the [melody WebSocket framework](https://github.com/olahol/melody), have implemented WebSocket-level ping/pong code inside the framework as an extra failsafe in case TCP keepalives aren't working. Additionally, [some people claim](https://github.com/nhooyr/websocket/issues/265#issuecomment-734095675) that TCP keepalives don't work well when going through proxy servers, which would seem to justify this extra code.

However, reliable data for TCP keepalives not working properly is scant. After [careful consideration](https://github.com/nhooyr/websocket/issues/1), this library does not include automatic ping/pong code like the melody WebSocket framework does. Until more evidence is gathered either way, the authors of this library do not recommend putting pong/pong code in your application. However, we always welcome [more discussion on the topic](https://github.com/nhooyr/websocket/issues/1).