websocket/README.md

65 lines
3.9 KiB
Markdown
Raw Permalink Normal View History

# Gorilla WebSocket
2013-10-16 20:41:47 +04:00
[![GoDoc](https://godoc.org/github.com/gorilla/websocket?status.svg)](https://godoc.org/github.com/gorilla/websocket)
[![CircleCI](https://circleci.com/gh/gorilla/websocket.svg?style=svg)](https://circleci.com/gh/gorilla/websocket)
2013-10-29 17:29:20 +04:00
Gorilla WebSocket is a [Go](http://golang.org/) implementation of the
2013-10-16 20:41:47 +04:00
[WebSocket](http://www.rfc-editor.org/rfc/rfc6455.txt) protocol.
2013-10-29 17:29:20 +04:00
### Documentation
2013-10-16 20:41:47 +04:00
2014-03-21 00:26:28 +04:00
* [API Reference](http://godoc.org/github.com/gorilla/websocket)
2013-10-16 20:41:47 +04:00
* [Chat example](https://github.com/gorilla/websocket/tree/master/examples/chat)
2015-10-18 23:32:14 +03:00
* [Command example](https://github.com/gorilla/websocket/tree/master/examples/command)
2015-09-24 01:23:26 +03:00
* [Client and server example](https://github.com/gorilla/websocket/tree/master/examples/echo)
2014-03-21 00:26:28 +04:00
* [File watch example](https://github.com/gorilla/websocket/tree/master/examples/filewatch)
2013-10-16 20:41:47 +04:00
2013-10-29 17:29:20 +04:00
### Status
2013-10-16 20:41:47 +04:00
2013-10-29 17:29:20 +04:00
The Gorilla WebSocket package provides a complete and tested implementation of
the [WebSocket](http://www.rfc-editor.org/rfc/rfc6455.txt) protocol. The
package API is stable.
2013-10-16 20:41:47 +04:00
2013-10-29 17:29:20 +04:00
### Installation
2013-10-16 20:41:47 +04:00
go get github.com/gorilla/websocket
2013-10-29 17:29:20 +04:00
### Protocol Compliance
The Gorilla WebSocket package passes the server tests in the [Autobahn Test
Suite](https://github.com/crossbario/autobahn-testsuite) using the application in the [examples/autobahn
2013-10-29 17:29:20 +04:00
subdirectory](https://github.com/gorilla/websocket/tree/master/examples/autobahn).
### Gorilla WebSocket compared with other packages
<table>
<tr>
<th></th>
<th><a href="http://godoc.org/github.com/gorilla/websocket">github.com/gorilla</a></th>
<th><a href="http://godoc.org/golang.org/x/net/websocket">golang.org/x/net</a></th>
2013-10-29 17:29:20 +04:00
</tr>
<tr>
<tr><td colspan="3"><a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a> Features</td></tr>
2019-04-27 07:03:06 +03:00
<tr><td>Passes <a href="https://github.com/crossbario/autobahn-testsuite">Autobahn Test Suite</a></td><td><a href="https://github.com/gorilla/websocket/tree/master/examples/autobahn">Yes</a></td><td>No</td></tr>
2014-06-06 00:56:06 +04:00
<tr><td>Receive <a href="https://tools.ietf.org/html/rfc6455#section-5.4">fragmented</a> message<td>Yes</td><td><a href="https://code.google.com/p/go/issues/detail?id=7632">No</a>, see note 1</td></tr>
<tr><td>Send <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close</a> message</td><td><a href="http://godoc.org/github.com/gorilla/websocket#hdr-Control_Messages">Yes</a></td><td><a href="https://code.google.com/p/go/issues/detail?id=4588">No</a></td></tr>
<tr><td>Send <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">pings</a> and receive <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pongs</a></td><td><a href="http://godoc.org/github.com/gorilla/websocket#hdr-Control_Messages">Yes</a></td><td>No</td></tr>
2014-04-21 08:48:25 +04:00
<tr><td>Get the <a href="https://tools.ietf.org/html/rfc6455#section-5.6">type</a> of a received data message</td><td>Yes</td><td>Yes, see note 2</td></tr>
<tr><td colspan="3">Other Features</tr></td>
2016-10-21 22:35:05 +03:00
<tr><td><a href="https://tools.ietf.org/html/rfc7692">Compression Extensions</a></td><td>Experimental</td><td>No</td></tr>
<tr><td>Read message using io.Reader</td><td><a href="http://godoc.org/github.com/gorilla/websocket#Conn.NextReader">Yes</a></td><td>No, see note 3</td></tr>
<tr><td>Write message using io.WriteCloser</td><td><a href="http://godoc.org/github.com/gorilla/websocket#Conn.NextWriter">Yes</a></td><td>No, see note 3</td></tr>
2013-10-29 17:29:20 +04:00
</table>
2018-03-04 22:58:07 +03:00
Notes:
2014-04-21 08:48:25 +04:00
2014-06-06 00:56:06 +04:00
1. Large messages are fragmented in [Chrome's new WebSocket implementation](http://www.ietf.org/mail-archive/web/hybi/current/msg10503.html).
2014-04-21 08:48:25 +04:00
2. The application can get the type of a received data message by implementing
a [Codec marshal](http://godoc.org/golang.org/x/net/websocket#Codec.Marshal)
2014-04-21 08:48:25 +04:00
function.
3. The go.net io.Reader and io.Writer operate across WebSocket frame boundaries.
Read returns when the input buffer is full or a frame boundary is
2014-11-03 18:02:20 +03:00
encountered. Each call to Write sends a single frame message. The Gorilla
io.Reader and io.WriteCloser operate on a single WebSocket message.