websocket

README

websocket

go WebSocket library

Documentation

Index

• Constants
• Variables
• func IsWsRequest(r *http.Request) bool
• func VerifyURI(uri string) (err error)
• type CloseCode
  • func (c CloseCode) String() string
• type ConnectionCloseError
• type ConnectionState
• type Dialer
  • func (d *Dialer) Dial(url string) (ws WebSocket, err error)
  • func (d *Dialer) DialContext(ctx context.Context, url string) (ws WebSocket, err error)
• type Message
• type NetDialer
• type Opcode
  • func (op Opcode) String() (disp string)
• type ServerConfig
  • func (srv *ServerConfig) Upgrade(w http.ResponseWriter, r *http.Request) (ws WebSocket, err error)
• type WebSocket
  • func Dial(url string) (ws WebSocket, err error)
  • func Upgrade(w http.ResponseWriter, r *http.Request) (ws WebSocket, err error)

Constants

const WebSocketGUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

WebSocketGUID is a fixed GUID for websocket server to generate |Sec-WebSocket-Accept| header.

rfc 6455: section 4.1

Variables

var DefaultDialer = new(Dialer)

var DefaultServerConfig = new(ServerConfig)

var MaximumSegmentSize = 1024

var PortMap = map[string]string{
	"ws":  "80",
	"wss": "443",
}

Functions

func IsWsRequest

func IsWsRequest(r *http.Request) bool

IsWsRequest checks the incoming http request to determine whether it's a websocket request.

func VerifyURI

func VerifyURI(uri string) (err error)

VerifyURI verifies whether the provided uri is a valid websocket uri, returns nil if it's valid.

rfc 6455: section 3

Types

type CloseCode

type CloseCode uint16

CloseCode indicates the close status of a closed websocket connection, call CloseCode.String() to get the status text.

rfc 6455: section 7.4

const (
	NormalClosure           CloseCode = 1000
	GoingAway               CloseCode = 1001
	ProtocolError           CloseCode = 1002
	UnsupportedData         CloseCode = 1003
	NoStatusReceived        CloseCode = 1005
	AbnormalClosure         CloseCode = 1006
	InvalidFramePayloadData CloseCode = 1007
	PolicyViolation         CloseCode = 1008
	MessageTooBig           CloseCode = 1009
	MandatoryExtension      CloseCode = 1010
	InternalServerError     CloseCode = 1011
	TLSHandshake            CloseCode = 1015
)

func (CloseCode) String

func (c CloseCode) String() string

type ConnectionCloseError

type ConnectionCloseError interface {
	net.Error
	Code() CloseCode
	Msg() []byte
}

ConnectionCloseError contains all about an error caused by connection close.

type ConnectionState

type ConnectionState string

ConnectionState indicates the connection state of a websocket connection.

rfc 6455: section 4

const (
	Connecting ConnectionState = "CONNECTING"
	Open       ConnectionState = "OPEN"
	Closed     ConnectionState = "CLOSED"
)

type Dialer

type Dialer struct {
	// Origin should be contained for a web browser.
	Origin string
	// Protocol contains the sub-protocols to use.
	// server may choose one or none from them.
	Protocol []string
	// Extensions are websocket extensions to use.
	// server should support all of them.
	Extensions []string

	// Header contains original headers in the handshake request.
	Header http.Header

	// NetDialer is the net dialer for the connection,
	// defaults to tls.NetDialer for "wss" scheme and net.NetDialer for "ws".
	NetDialer NetDialer
}

Dialer contains the config to start a websocket connection.

func (*Dialer) Dial

func (d *Dialer) Dial(url string) (ws WebSocket, err error)

Dial connects to the url.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, url string) (ws WebSocket, err error)

DialContext connects to the url using the provided context. The provided context must be non-nil.

type Message

type Message struct {
	// Op is the Opcode of the message(the Opcode of the first frame).
	//
	// rfc 6455: section 5.2
	Op Opcode
	// Len indicates the content-length of the message(the total payload length of all frames).
	Len int64

	// Data is the message content(concatenate the payload of all frames).
	Data []byte
}

Message is a websocket message. To send a message, the Message.Len will be calculated from Message.Data and the original value will be discarded.

rfc 6455: section 1.2

type NetDialer

type NetDialer interface {
	Dial(network string, addr string) (net.Conn, error)
	DialContext(ctx context.Context, network string, addr string) (net.Conn, error)
}

NetDialer can hold net.Dialer or tls.Dialer.

type Opcode

type Opcode uint8

Opcode indicates the operation of a websocket frame.

rfc 6455: section 5.2

const (
	OpContinuationFrame Opcode = 0x0
	OpTextFrame         Opcode = 0x1
	OpBinaryFrame       Opcode = 0x2

	OpConnectionClose Opcode = 0x8
	OpPing            Opcode = 0x9
	OpPong            Opcode = 0xa
)

func (Opcode) String

func (op Opcode) String() (disp string)

type ServerConfig

type ServerConfig struct {
	// Protocol contains protocols the server support.
	// May choose one of them for each connect request.
	Protocol []string
	// Extensions contains extensions the server support.
	// for each connection request, server should support all the client extensions.
	Extensions []string
}

func (*ServerConfig) Upgrade

func (srv *ServerConfig) Upgrade(w http.ResponseWriter, r *http.Request) (ws WebSocket, err error)

Upgrade takes over an existing http context and returns a websocket connection

type WebSocket

type WebSocket interface {
	// State returns the state of the websocket connection.
	State() ConnectionState
	// Extensions returns extensions used by the websocket connection.
	Extensions() []string
	// Protocol returns the sub-protocol used by the websocket connection.
	Protocol() string

	// RecvCtx waits for a websocket message, and parses it into Message.
	// Frames with OpPing will be responded with a frame with OpPong.
	// When receiving a frame with OpConnectionClose, the close response
	// will be sent and returns ConnectionCloseError instead of Message.
	RecvCtx(ctx context.Context) (msg Message, err error)
	// Recv works like WebSocket.RecvCtx but discards the frame metadata.
	Recv() (data []byte, err error)

	// SendCtx sends a message to the connection.
	SendCtx(ctx context.Context, msg Message) (err error)
	// Send sends a message with OpBinaryFrame to the connection.
	Send(data []byte) (err error)
	// SendText sends a message with OpTextFrame to the connection.
	SendText(txt string) (err error)
	// Ping sends a frame with OpPing to the connection and waits for the next frame,
	// typically a frame with OpPong, parses it and returns its body.
	Ping() (resp []byte, err error)

	// CloseMsg sends CloseCode and msg by a frame with OpConnectionClose, waits for the response and closes the underlying
	// net.Conn. It does nothing if WebSocket is already closed or is closing.
	// The return value is nil(when it does nothing) or ConnectCloseError. Unwarp to get the error
	// occurred during closing(the close code must be AbnormalClosure in this case).
	CloseMsg(msg []byte, code CloseCode) (err error)
	// Close works like CloseMsg but with NormalClosure as CloseCode and NormalClosure.String() as msg.
	Close() (err error)
}

WebSocket is a websocket connection.

func Dial

func Dial(url string) (ws WebSocket, err error)

Dial connects to the url using DefaultDialer.

func Upgrade

func Upgrade(w http.ResponseWriter, r *http.Request) (ws WebSocket, err error)

Upgrade upgrades the existing http context using DefaultServerConfig.