1// Copyright 2013 The Gorilla WebSocket Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package websocket implements the WebSocket protocol defined in RFC 6455. 6// 7// Overview 8// 9// The Conn type represents a WebSocket connection. A server application calls 10// the Upgrader.Upgrade method from an HTTP request handler to get a *Conn: 11// 12// var upgrader = websocket.Upgrader{ 13// ReadBufferSize: 1024, 14// WriteBufferSize: 1024, 15// } 16// 17// func handler(w http.ResponseWriter, r *http.Request) { 18// conn, err := upgrader.Upgrade(w, r, nil) 19// if err != nil { 20// log.Println(err) 21// return 22// } 23// ... Use conn to send and receive messages. 24// } 25// 26// Call the connection's WriteMessage and ReadMessage methods to send and 27// receive messages as a slice of bytes. This snippet of code shows how to echo 28// messages using these methods: 29// 30// for { 31// messageType, p, err := conn.ReadMessage() 32// if err != nil { 33// log.Println(err) 34// return 35// } 36// if err := conn.WriteMessage(messageType, p); err != nil { 37// log.Println(err) 38// return 39// } 40// } 41// 42// In above snippet of code, p is a []byte and messageType is an int with value 43// websocket.BinaryMessage or websocket.TextMessage. 44// 45// An application can also send and receive messages using the io.WriteCloser 46// and io.Reader interfaces. To send a message, call the connection NextWriter 47// method to get an io.WriteCloser, write the message to the writer and close 48// the writer when done. To receive a message, call the connection NextReader 49// method to get an io.Reader and read until io.EOF is returned. This snippet 50// shows how to echo messages using the NextWriter and NextReader methods: 51// 52// for { 53// messageType, r, err := conn.NextReader() 54// if err != nil { 55// return 56// } 57// w, err := conn.NextWriter(messageType) 58// if err != nil { 59// return err 60// } 61// if _, err := io.Copy(w, r); err != nil { 62// return err 63// } 64// if err := w.Close(); err != nil { 65// return err 66// } 67// } 68// 69// Data Messages 70// 71// The WebSocket protocol distinguishes between text and binary data messages. 72// Text messages are interpreted as UTF-8 encoded text. The interpretation of 73// binary messages is left to the application. 74// 75// This package uses the TextMessage and BinaryMessage integer constants to 76// identify the two data message types. The ReadMessage and NextReader methods 77// return the type of the received message. The messageType argument to the 78// WriteMessage and NextWriter methods specifies the type of a sent message. 79// 80// It is the application's responsibility to ensure that text messages are 81// valid UTF-8 encoded text. 82// 83// Control Messages 84// 85// The WebSocket protocol defines three types of control messages: close, ping 86// and pong. Call the connection WriteControl, WriteMessage or NextWriter 87// methods to send a control message to the peer. 88// 89// Connections handle received close messages by calling the handler function 90// set with the SetCloseHandler method and by returning a *CloseError from the 91// NextReader, ReadMessage or the message Read method. The default close 92// handler sends a close message to the peer. 93// 94// Connections handle received ping messages by calling the handler function 95// set with the SetPingHandler method. The default ping handler sends a pong 96// message to the peer. 97// 98// Connections handle received pong messages by calling the handler function 99// set with the SetPongHandler method. The default pong handler does nothing. 100// If an application sends ping messages, then the application should set a 101// pong handler to receive the corresponding pong. 102// 103// The control message handler functions are called from the NextReader, 104// ReadMessage and message reader Read methods. The default close and ping 105// handlers can block these methods for a short time when the handler writes to 106// the connection. 107// 108// The application must read the connection to process close, ping and pong 109// messages sent from the peer. If the application is not otherwise interested 110// in messages from the peer, then the application should start a goroutine to 111// read and discard messages from the peer. A simple example is: 112// 113// func readLoop(c *websocket.Conn) { 114// for { 115// if _, _, err := c.NextReader(); err != nil { 116// c.Close() 117// break 118// } 119// } 120// } 121// 122// Concurrency 123// 124// Connections support one concurrent reader and one concurrent writer. 125// 126// Applications are responsible for ensuring that no more than one goroutine 127// calls the write methods (NextWriter, SetWriteDeadline, WriteMessage, 128// WriteJSON, EnableWriteCompression, SetCompressionLevel) concurrently and 129// that no more than one goroutine calls the read methods (NextReader, 130// SetReadDeadline, ReadMessage, ReadJSON, SetPongHandler, SetPingHandler) 131// concurrently. 132// 133// The Close and WriteControl methods can be called concurrently with all other 134// methods. 135// 136// Origin Considerations 137// 138// Web browsers allow Javascript applications to open a WebSocket connection to 139// any host. It's up to the server to enforce an origin policy using the Origin 140// request header sent by the browser. 141// 142// The Upgrader calls the function specified in the CheckOrigin field to check 143// the origin. If the CheckOrigin function returns false, then the Upgrade 144// method fails the WebSocket handshake with HTTP status 403. 145// 146// If the CheckOrigin field is nil, then the Upgrader uses a safe default: fail 147// the handshake if the Origin request header is present and the Origin host is 148// not equal to the Host request header. 149// 150// The deprecated package-level Upgrade function does not perform origin 151// checking. The application is responsible for checking the Origin header 152// before calling the Upgrade function. 153// 154// Buffers 155// 156// Connections buffer network input and output to reduce the number 157// of system calls when reading or writing messages. 158// 159// Write buffers are also used for constructing WebSocket frames. See RFC 6455, 160// Section 5 for a discussion of message framing. A WebSocket frame header is 161// written to the network each time a write buffer is flushed to the network. 162// Decreasing the size of the write buffer can increase the amount of framing 163// overhead on the connection. 164// 165// The buffer sizes in bytes are specified by the ReadBufferSize and 166// WriteBufferSize fields in the Dialer and Upgrader. The Dialer uses a default 167// size of 4096 when a buffer size field is set to zero. The Upgrader reuses 168// buffers created by the HTTP server when a buffer size field is set to zero. 169// The HTTP server buffers have a size of 4096 at the time of this writing. 170// 171// The buffer sizes do not limit the size of a message that can be read or 172// written by a connection. 173// 174// Buffers are held for the lifetime of the connection by default. If the 175// Dialer or Upgrader WriteBufferPool field is set, then a connection holds the 176// write buffer only when writing a message. 177// 178// Applications should tune the buffer sizes to balance memory use and 179// performance. Increasing the buffer size uses more memory, but can reduce the 180// number of system calls to read or write the network. In the case of writing, 181// increasing the buffer size can reduce the number of frame headers written to 182// the network. 183// 184// Some guidelines for setting buffer parameters are: 185// 186// Limit the buffer sizes to the maximum expected message size. Buffers larger 187// than the largest message do not provide any benefit. 188// 189// Depending on the distribution of message sizes, setting the buffer size to 190// a value less than the maximum expected message size can greatly reduce memory 191// use with a small impact on performance. Here's an example: If 99% of the 192// messages are smaller than 256 bytes and the maximum message size is 512 193// bytes, then a buffer size of 256 bytes will result in 1.01 more system calls 194// than a buffer size of 512 bytes. The memory savings is 50%. 195// 196// A write buffer pool is useful when the application has a modest number 197// writes over a large number of connections. when buffers are pooled, a larger 198// buffer size has a reduced impact on total memory use and has the benefit of 199// reducing system calls and frame overhead. 200// 201// Compression EXPERIMENTAL 202// 203// Per message compression extensions (RFC 7692) are experimentally supported 204// by this package in a limited capacity. Setting the EnableCompression option 205// to true in Dialer or Upgrader will attempt to negotiate per message deflate 206// support. 207// 208// var upgrader = websocket.Upgrader{ 209// EnableCompression: true, 210// } 211// 212// If compression was successfully negotiated with the connection's peer, any 213// message received in compressed form will be automatically decompressed. 214// All Read methods will return uncompressed bytes. 215// 216// Per message compression of messages written to a connection can be enabled 217// or disabled by calling the corresponding Conn method: 218// 219// conn.EnableWriteCompression(false) 220// 221// Currently this package does not support compression with "context takeover". 222// This means that messages must be compressed and decompressed in isolation, 223// without retaining sliding window or dictionary state across messages. For 224// more details refer to RFC 7692. 225// 226// Use of compression is experimental and may result in decreased performance. 227package websocket 228