websocket package - golang.org/x/net/websocket - Go Packages (original) (raw)
Package websocket implements a client and server for the WebSocket protocol as specified in RFC 6455.
This package currently lacks some features found in an alternative and more actively maintained WebSocket packages:
func Origin(config *Config, req *http.Request) (*url.URL, error)
- func (ws *Conn) Close() error
- func (ws *Conn) Config() *Config
- func (ws *Conn) IsClientConn() bool
- func (ws *Conn) IsServerConn() bool
- func (ws *Conn) LocalAddr() net.Addr
- func (ws *Conn) Read(msg []byte) (n int, err error)
- func (ws *Conn) RemoteAddr() net.Addr
- func (ws *Conn) Request() *http.Request
- func (ws *Conn) SetDeadline(t time.Time) error
- func (ws *Conn) SetReadDeadline(t time.Time) error
- func (ws *Conn) SetWriteDeadline(t time.Time) error
- func (ws *Conn) Write(msg []byte) (n int, err error)
const ( ProtocolVersionHybi13 = 13 ProtocolVersionHybi = ProtocolVersionHybi13 SupportedProtocolVersion = "13"
ContinuationFrame = 0
TextFrame = 1
BinaryFrame = 2
CloseFrame = 8
PingFrame = 9
PongFrame = 10
UnknownFrame = 255
DefaultMaxPayloadBytes = 32 << 20 )
var ( ErrBadMaskingKey = &ProtocolError{"bad masking key"} ErrBadPongMessage = &ProtocolError{"bad pong message"} ErrBadClosingStatus = &ProtocolError{"bad closing status"} ErrUnsupportedExtensions = &ProtocolError{"unsupported extensions"} ErrNotImplemented = &ProtocolError{"not implemented"} )
var ( ErrBadProtocolVersion = &ProtocolError{"bad protocol version"} ErrBadScheme = &ProtocolError{"bad scheme"} ErrBadStatus = &ProtocolError{"bad status"} ErrBadUpgrade = &ProtocolError{"missing or bad upgrade"} ErrBadWebSocketOrigin = &ProtocolError{"missing or bad WebSocket-Origin"} ErrBadWebSocketLocation = &ProtocolError{"missing or bad WebSocket-Location"} ErrBadWebSocketProtocol = &ProtocolError{"missing or bad WebSocket-Protocol"} ErrBadWebSocketVersion = &ProtocolError{"missing or bad WebSocket Version"} ErrChallengeResponse = &ProtocolError{"mismatch challenge/response"} ErrBadFrame = &ProtocolError{"bad frame"} ErrBadFrameBoundary = &ProtocolError{"not on frame boundary"} ErrNotWebSocket = &ProtocolError{"not websocket protocol"} ErrBadRequestMethod = &ProtocolError{"bad method"} ErrNotSupported = &ProtocolError{"not supported"} )
ErrFrameTooLarge is returned by Codec's Receive method if payload size exceeds limit set by Conn.MaxPayloadBytes
JSON is a codec to send/receive JSON data in a frame from a WebSocket connection.
Trivial usage:
import "websocket"
type T struct { Msg string Count int }
// receive JSON type T var data T websocket.JSON.Receive(ws, &data)
// send JSON type T websocket.JSON.Send(ws, data)
Message is a codec to send/receive text/binary data in a frame on WebSocket connection. To send/receive text frame, use string type. To send/receive binary frame, use []byte type.
Trivial usage:
import "websocket"
// receive text frame var message string websocket.Message.Receive(ws, &message)
// send text frame message = "hello" websocket.Message.Send(ws, message)
// receive binary frame var data []byte websocket.Message.Receive(ws, &data)
// send binary frame data = []byte{0, 1, 2} websocket.Message.Send(ws, data)
Origin parses the Origin header in req. If the Origin header is not set, it returns nil and nil.
Addr is an implementation of net.Addr for WebSocket.
Network returns the network type for a WebSocket, "websocket".
type Codec struct { Marshal func(v interface{}) (data []byte, payloadType byte, err error) Unmarshal func(data []byte, payloadType byte, v interface{}) (err error) }
Codec represents a symmetric pair of functions that implement a codec.
func (cd Codec) Receive(ws *Conn, v interface{}) (err error)
Receive receives single frame from ws, unmarshaled by cd.Unmarshal and stores in v. The whole frame payload is read to an in-memory buffer; max size of payload is defined by ws.MaxPayloadBytes. If frame payload size exceeds limit, ErrFrameTooLarge is returned; in this case frame is not read off wire completely. The next call to Receive would read and discard leftover data of previous oversized frame before processing next frame.
func (cd Codec) Send(ws *Conn, v interface{}) (err error)
Send sends v marshaled by cd.Marshal as single frame to ws.
Config is a WebSocket configuration
func NewConfig(server, origin string) (config *Config, err error)
NewConfig creates a new WebSocket config for client connection.
DialContext opens a new client connection to a WebSocket, with context support for timeouts/cancellation.
type Conn struct { PayloadType byte
MaxPayloadBytes [int](/builtin#int)}
Conn represents a WebSocket connection.
Multiple goroutines may invoke methods on a Conn simultaneously.
func Dial(url_, protocol, origin string) (ws *Conn, err error)
Dial opens a new client connection to a WebSocket.
This example demonstrates a trivial client.
package main
import ( "fmt" "log"
"golang.org/x/net/websocket")
func main() { origin := "http://localhost/" url := "ws://localhost:12345/ws" ws, err := websocket.Dial(url, "", origin) if err != nil { log.Fatal(err) } if _, err := ws.Write([]byte("hello, world!\n")); err != nil { log.Fatal(err) } var msg = make([]byte, 512) var n int if n, err = ws.Read(msg); err != nil { log.Fatal(err) } fmt.Printf("Received: %s.\n", msg[:n]) }
Output:
func DialConfig(config *Config) (ws *Conn, err error)
DialConfig opens a new client connection to a WebSocket with a config.
NewClient creates a new WebSocket client connection over rwc.
Close implements the io.Closer interface.
func (ws *Conn) Config() *Config
Config returns the WebSocket config.
func (ws *Conn) IsClientConn() bool
IsClientConn reports whether ws is a client-side connection.
func (ws *Conn) IsServerConn() bool
IsServerConn reports whether ws is a server-side connection.
LocalAddr returns the WebSocket Origin for the connection for client, or the WebSocket location for server.
Read implements the io.Reader interface: it reads data of a frame from the WebSocket connection. if msg is not large enough for the frame data, it fills the msg and next Read will read the rest of the frame data. it reads Text frame or Binary frame.
RemoteAddr returns the WebSocket location for the connection for client, or the Websocket Origin for server.
Request returns the http request upgraded to the WebSocket. It is nil for client side.
SetDeadline sets the connection's network read & write deadlines.
SetReadDeadline sets the connection's network read deadline.
SetWriteDeadline sets the connection's network write deadline.
Write implements the io.Writer interface: it writes data as a frame to the WebSocket connection.
type DialError struct { *Config Err error }
DialError is an error that occurs while dialling a websocket server.
type Handler ¶
Handler is a simple interface to a WebSocket browser client. It checks if Origin header is valid URL by default. You might want to verify websocket.Conn.Config().Origin in the func. If you use Server instead of Handler, you could call websocket.Origin and check the origin in your Handshake func. So, if you want to accept non-browser clients, which do not send an Origin header, set a Server.Handshake that does not check the origin.
This example demonstrates a trivial echo server.
package main
import ( "io" "net/http"
"golang.org/x/net/websocket")
// Echo the data received on the WebSocket. func EchoServer(ws *websocket.Conn) { io.Copy(ws, ws) }
// This example demonstrates a trivial echo server. func main() { http.Handle("/echo", websocket.Handler(EchoServer)) err := http.ListenAndServe(":12345", nil) if err != nil { panic("ListenAndServe: " + err.Error()) } }
Output:
func (Handler) ServeHTTP ¶
ServeHTTP implements the http.Handler interface for a WebSocket
type ProtocolError struct { ErrorString string }
ProtocolError represents WebSocket protocol errors.
Server represents a server of a WebSocket.
ServeHTTP implements the http.Handler interface for a WebSocket