1 # Gorilla WebSocket

     2 

     3 Gorilla WebSocket is a [Go](http://golang.org/) implementation of the

     4 [WebSocket](http://www.rfc-editor.org/rfc/rfc6455.txt) protocol.

     5 

     6 [![Build Status](https://travis-ci.org/gorilla/websocket.svg?branch=master)](https://travis-ci.org/gorilla/websocket)

     7 [![GoDoc](https://godoc.org/github.com/gorilla/websocket?status.svg)](https://godoc.org/github.com/gorilla/websocket)

     8 

     9 ### Documentation

    10 

    11 * [API Reference](http://godoc.org/github.com/gorilla/websocket)

    12 * [Chat example](https://github.com/gorilla/websocket/tree/master/examples/chat)

    13 * [Command example](https://github.com/gorilla/websocket/tree/master/examples/command)

    14 * [Client and server example](https://github.com/gorilla/websocket/tree/master/examples/echo)

    15 * [File watch example](https://github.com/gorilla/websocket/tree/master/examples/filewatch)

    16 

    17 ### Status

    18 

    19 The Gorilla WebSocket package provides a complete and tested implementation of

    20 the [WebSocket](http://www.rfc-editor.org/rfc/rfc6455.txt) protocol. The

    21 package API is stable.

    22 

    23 ### Installation

    24 

    25     go get github.com/gorilla/websocket

    26 

    27 ### Protocol Compliance

    28 

    29 The Gorilla WebSocket package passes the server tests in the [Autobahn Test

    30 Suite](http://autobahn.ws/testsuite) using the application in the [examples/autobahn

    31 subdirectory](https://github.com/gorilla/websocket/tree/master/examples/autobahn).

    32 

    33 ### Gorilla WebSocket compared with other packages

    34 

    35 <table>

    36 <tr>

    37 <th></th>

    38 <th><a href="http://godoc.org/github.com/gorilla/websocket">github.com/gorilla</a></th>

    39 <th><a href="http://godoc.org/golang.org/x/net/websocket">golang.org/x/net</a></th>

    40 </tr>

    41 <tr>

    42 <tr><td colspan="3"><a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a> Features</td></tr>

    43 <tr><td>Passes <a href="http://autobahn.ws/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>

    44 <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>

    45 <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>

    46 <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>

    47 <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>

    48 <tr><td colspan="3">Other Features</tr></td>

    49 <tr><td><a href="https://tools.ietf.org/html/rfc7692">Compression Extensions</a></td><td>Experimental</td><td>No</td></tr>

    50 <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>

    51 <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>

    52 </table>

    53 

    54 Notes:

    55 

    56 1. Large messages are fragmented in [Chrome's new WebSocket implementation](http://www.ietf.org/mail-archive/web/hybi/current/msg10503.html).

    57 2. The application can get the type of a received data message by implementing

    58    a [Codec marshal](http://godoc.org/golang.org/x/net/websocket#Codec.Marshal)

    59    function.

    60 3. The go.net io.Reader and io.Writer operate across WebSocket frame boundaries.

    61   Read returns when the input buffer is full or a frame boundary is

    62   encountered. Each call to Write sends a single frame message. The Gorilla

    63   io.Reader and io.WriteCloser operate on a single WebSocket message.

    64