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.
5 // Package websocket implements the WebSocket protocol defined in RFC 6455.
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:
12 // var upgrader = websocket.Upgrader{
13 // ReadBufferSize: 1024,
14 // WriteBufferSize: 1024,
17 // func handler(w http.ResponseWriter, r *http.Request) {
18 // conn, err := upgrader.Upgrade(w, r, nil)
23 // ... Use conn to send and receive messages.
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:
31 // messageType, p, err := conn.ReadMessage()
36 // if err := conn.WriteMessage(messageType, p); err != nil {
42 // In above snippet of code, p is a []byte and messageType is an int with value
43 // websocket.BinaryMessage or websocket.TextMessage.
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:
53 // messageType, r, err := conn.NextReader()
57 // w, err := conn.NextWriter(messageType)
61 // if _, err := io.Copy(w, r); err != nil {
64 // if err := w.Close(); err != nil {
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.
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.
80 // It is the application's responsibility to ensure that text messages are
81 // valid UTF-8 encoded text.
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.
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.
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.
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.
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
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:
113 // func readLoop(c *websocket.Conn) {
115 // if _, _, err := c.NextReader(); err != nil {
124 // Connections support one concurrent reader and one concurrent writer.
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)
133 // The Close and WriteControl methods can be called concurrently with all other
136 // Origin Considerations
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.
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.
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.
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.
154 // Compression EXPERIMENTAL
156 // Per message compression extensions (RFC 7692) are experimentally supported
157 // by this package in a limited capacity. Setting the EnableCompression option
158 // to true in Dialer or Upgrader will attempt to negotiate per message deflate
161 // var upgrader = websocket.Upgrader{
162 // EnableCompression: true,
165 // If compression was successfully negotiated with the connection's peer, any
166 // message received in compressed form will be automatically decompressed.
167 // All Read methods will return uncompressed bytes.
169 // Per message compression of messages written to a connection can be enabled
170 // or disabled by calling the corresponding Conn method:
172 // conn.EnableWriteCompression(false)
174 // Currently this package does not support compression with "context takeover".
175 // This means that messages must be compressed and decompressed in isolation,
176 // without retaining sliding window or dictionary state across messages. For
177 // more details refer to RFC 7692.
179 // Use of compression is experimental and may result in decreased performance.
OSDN Git Service
