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 uses
 10// the Upgrade function from an Upgrader object with a HTTP request handler
 11// to get a pointer to a Conn:
 12//
 13//  var upgrader = websocket.Upgrader{
 14//      ReadBufferSize:  1024,
 15//      WriteBufferSize: 1024,
 16//  }
 17//
 18//  func handler(w http.ResponseWriter, r *http.Request) {
 19//      conn, err := upgrader.Upgrade(w, r, nil)
 20//      if err != nil {
 21//          log.Println(err)
 22//          return
 23//      }
 24//      ... Use conn to send and receive messages.
 25//  }
 26//
 27// Call the connection's WriteMessage and ReadMessage methods to send and
 28// receive messages as a slice of bytes. This snippet of code shows how to echo
 29// messages using these methods:
 30//
 31//  for {
 32//      messageType, p, err := conn.ReadMessage()
 33//      if err != nil {
 34//          return
 35//      }
 36//      if err = conn.WriteMessage(messageType, p); err != nil {
 37//          return err
 38//      }
 39//  }
 40//
 41// In above snippet of code, p is a []byte and messageType is an int with value
 42// websocket.BinaryMessage or websocket.TextMessage.
 43//
 44// An application can also send and receive messages using the io.WriteCloser
 45// and io.Reader interfaces. To send a message, call the connection NextWriter
 46// method to get an io.WriteCloser, write the message to the writer and close
 47// the writer when done. To receive a message, call the connection NextReader
 48// method to get an io.Reader and read until io.EOF is returned. This snippet
 49// shows how to echo messages using the NextWriter and NextReader methods:
 50//
 51//  for {
 52//      messageType, r, err := conn.NextReader()
 53//      if err != nil {
 54//          return
 55//      }
 56//      w, err := conn.NextWriter(messageType)
 57//      if err != nil {
 58//          return err
 59//      }
 60//      if _, err := io.Copy(w, r); err != nil {
 61//          return err
 62//      }
 63//      if err := w.Close(); err != nil {
 64//          return err
 65//      }
 66//  }
 67//
 68// Data Messages
 69//
 70// The WebSocket protocol distinguishes between text and binary data messages.
 71// Text messages are interpreted as UTF-8 encoded text. The interpretation of
 72// binary messages is left to the application.
 73//
 74// This package uses the TextMessage and BinaryMessage integer constants to
 75// identify the two data message types. The ReadMessage and NextReader methods
 76// return the type of the received message. The messageType argument to the
 77// WriteMessage and NextWriter methods specifies the type of a sent message.
 78//
 79// It is the application's responsibility to ensure that text messages are
 80// valid UTF-8 encoded text.
 81//
 82// Control Messages
 83//
 84// The WebSocket protocol defines three types of control messages: close, ping
 85// and pong. Call the connection WriteControl, WriteMessage or NextWriter
 86// methods to send a control message to the peer.
 87//
 88// Connections handle received close messages by sending a close message to the
 89// peer and returning a *CloseError from the the NextReader, ReadMessage or the
 90// message Read method.
 91//
 92// Connections handle received ping and pong messages by invoking callback
 93// functions set with SetPingHandler and SetPongHandler methods. The callback
 94// functions are called from the NextReader, ReadMessage and the message Read
 95// methods.
 96//
 97// The default ping handler sends a pong to the peer. The application's reading
 98// goroutine can block for a short time while the handler writes the pong data
 99// to the connection.
100//
101// The application must read the connection to process ping, pong and close
102// messages sent from the peer. If the application is not otherwise interested
103// in messages from the peer, then the application should start a goroutine to
104// read and discard messages from the peer. A simple example is:
105//
106//  func readLoop(c *websocket.Conn) {
107//      for {
108//          if _, _, err := c.NextReader(); err != nil {
109//              c.Close()
110//              break
111//          }
112//      }
113//  }
114//
115// Concurrency
116//
117// Connections support one concurrent reader and one concurrent writer.
118//
119// Applications are responsible for ensuring that no more than one goroutine
120// calls the write methods (NextWriter, SetWriteDeadline, WriteMessage,
121// WriteJSON, EnableWriteCompression, SetCompressionLevel) concurrently and
122// that no more than one goroutine calls the read methods (NextReader,
123// SetReadDeadline, ReadMessage, ReadJSON, SetPongHandler, SetPingHandler)
124// concurrently.
125//
126// The Close and WriteControl methods can be called concurrently with all other
127// methods.
128//
129// Origin Considerations
130//
131// Web browsers allow Javascript applications to open a WebSocket connection to
132// any host. It's up to the server to enforce an origin policy using the Origin
133// request header sent by the browser.
134//
135// The Upgrader calls the function specified in the CheckOrigin field to check
136// the origin. If the CheckOrigin function returns false, then the Upgrade
137// method fails the WebSocket handshake with HTTP status 403.
138//
139// If the CheckOrigin field is nil, then the Upgrader uses a safe default: fail
140// the handshake if the Origin request header is present and not equal to the
141// Host request header.
142//
143// An application can allow connections from any origin by specifying a
144// function that always returns true:
145//
146//  var upgrader = websocket.Upgrader{
147//      CheckOrigin: func(r *http.Request) bool { return true },
148//  }
149//
150// The deprecated Upgrade function does not enforce an origin policy. It's the
151// application's responsibility to check the Origin header before calling
152// Upgrade.
153//
154// Compression EXPERIMENTAL
155//
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
159// support.
160//
161//  var upgrader = websocket.Upgrader{
162//      EnableCompression: true,
163//  }
164//
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.
168//
169// Per message compression of messages written to a connection can be enabled
170// or disabled by calling the corresponding Conn method:
171//
172//  conn.EnableWriteCompression(false)
173//
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.
178//
179// Use of compression is experimental and may result in decreased performance.
180package websocket