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