Documentation ¶
Overview ¶
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 package:
https://pkg.go.dev/nhooyr.io/websocket
Index ¶
- Constants
- Variables
- func ServeHTTP(w http.ResponseWriter, req *http.Request, ...) error
- type Codec
- type Config
- type Conn
- func (ws *Conn) Close() error
- func (ws *Conn) DiscardReader() error
- func (ws *Conn) LocalAddr() net.Addr
- func (ws *Conn) NextFrameReader() (*Header, io.Reader, error)
- func (ws *Conn) Read(msg []byte) (n int, err error)
- func (ws *Conn) RemoteAddr() net.Addr
- 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)
- func (ws *Conn) WriteClose(status int) (err error)
- func (ws *Conn) WriteMsg(msg []byte, payloadType opcode) (int, error)
- func (ws *Conn) WritePong(msg []byte) (n int, err error)
- type ErrorBufioReadWriter
- type Header
- type ProtocolError
- type Request
- type ServerHandshaker
Constants ¶
const (
DefaultMaxPayloadBytes = 32 << 20 // 32MB
)
const (
SupportedProtocolVersion = "13"
)
Variables ¶
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"} )
var (
ErrUnsupportedExtensions = &ProtocolError{"unsupported extensions"}
)
var JSON = Codec{jsonMarshal, jsonUnmarshal}
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)
var Message = Codec{marshal, unmarshal}
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)
Functions ¶
Types ¶
type Codec ¶
type Codec struct { Marshal func(v any) (data []byte, payloadType opcode, err error) Unmarshal func(data []byte, payloadType opcode, v any) (err error) }
Codec represents a symmetric pair of functions that implement a codec.
func (Codec) Receive ¶
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.
type Config ¶
type Config struct { Host string Path string // A Websocket client origin. OriginUrl string // eg: http://example.com/from/ws // WebSocket subprotocols. Protocol []string }
Config is a WebSocket configuration
type Conn ¶
type Conn struct { IsServer bool LastPayloadType opcode PayloadType opcode DefaultCloseStatus int Rw *struct { // contains filtered or unexported fields } Frame io.Reader RawConn net.Conn // contains filtered or unexported fields }
Conn represents a WebSocket connection.
Multiple goroutines may invoke methods on a Conn simultaneously.
func NewClient ¶
func NewClient(config *Config, SecWebSocketKey string, header http.Header, rwc net.Conn, handshake func(*http.Response) error) (ws *Conn, err error)
NewClient creates a new WebSocket client connection over rwc.
func NewServerConn ¶
func (*Conn) DiscardReader ¶
func (*Conn) Read ¶
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.
func (*Conn) RemoteAddr ¶
func (*Conn) Write ¶
Write implements the io.Writer interface: it writes data as a frame to the WebSocket connection.
func (*Conn) WriteClose ¶
type ErrorBufioReadWriter ¶
type ErrorBufioReadWriter struct {
// contains filtered or unexported fields
}
func (*ErrorBufioReadWriter) Flush ¶
func (b *ErrorBufioReadWriter) Flush() error
func (*ErrorBufioReadWriter) ReadByte ¶
func (b *ErrorBufioReadWriter) ReadByte() (byte, error)
func (*ErrorBufioReadWriter) WriteByte ¶
func (b *ErrorBufioReadWriter) WriteByte(byte) error
type Header ¶
type Header struct {
// contains filtered or unexported fields
}
Header represents a WebSocket frame Header. See https://tools.ietf.org/html/rfc6455#section-5.2.
type ProtocolError ¶
type ProtocolError struct {
ErrorString string
}
ProtocolError represents WebSocket protocol errors.
func (*ProtocolError) Error ¶
func (err *ProtocolError) Error() string
type ServerHandshaker ¶
type ServerHandshaker struct {
*Request
}
A HybiServerHandshaker performs a server handshake using hybi draft protocol.
func (*ServerHandshaker) AcceptHandshake ¶
func (c *ServerHandshaker) AcceptHandshake(w http.ResponseWriter) (err error)
func (*ServerHandshaker) ReadHandshake ¶
func (c *ServerHandshaker) ReadHandshake(req *http.Request) (code int, err error)