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