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. 227 package websocket 228