websocket

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 ReadByte(r io.Reader) (byte, error)
• func ServeHTTP(w http.ResponseWriter, req *http.Request, ...) error
• type Codec
  • func (cd Codec) Receive(ws *Conn, v any) error
  • func (cd Codec) Send(ws *Conn, v any) (err error)
• type Config
  • func (config *Config) NewClient(SecWebSocketKey string, rwc net.Conn, request func(*http.Request) error, ...) (ws *Conn, err error)
• type Conn
  • func NewServerConn(w http.ResponseWriter, req *http.Request, handshake func(*Request) error) (conn *Conn, err error)
  • func (ws *Conn) Close() error
  • func (ws *Conn) LocalAddr() net.Addr
  • func (ws *Conn) NextFrameReader(handle func(*Header, io.ReadCloser) error) 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 Header
• type ProtocolError
  • func (err *ProtocolError) Error() string
• type Request
• type ServerHandshaker
  • func (c *ServerHandshaker) AcceptHandshake(w http.ResponseWriter) (err error)
  • func (c *ServerHandshaker) ReadHandshake(req *http.Request) (code int, err error)

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)

var PROTO = Codec{protoMarshal, protoUnmarshal}

var PROTOJSON = Codec{protoJsonMarshal, protoJsonUnmarshal}

Functions

func ReadByte

func ReadByte(r io.Reader) (byte, error)

func ServeHTTP

func ServeHTTP(w http.ResponseWriter, req *http.Request, Handler func(context.Context, *Conn) error) error

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

func (cd Codec) Receive(ws *Conn, v any) 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 (Codec) Send

func (cd Codec) Send(ws *Conn, v any) (err error)

Send sends v marshaled by cd.Marshal as single frame to ws.

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

func (*Config) NewClient

func (config *Config) NewClient(SecWebSocketKey string, rwc net.Conn, request func(*http.Request) error, handshake func(*http.Response) error) (ws *Conn, err error)

NewClient creates a new WebSocket client connection over rwc.

type Conn

type Conn struct {
	Frame io.ReadCloser

	RawConn net.Conn

	IsServer bool

	LastPayloadType opcode
	PayloadType     opcode
	// contains filtered or unexported fields
}

Conn represents a WebSocket connection.

Multiple goroutines may invoke methods on a Conn simultaneously.

func NewServerConn

func NewServerConn(w http.ResponseWriter, req *http.Request, handshake func(*Request) error) (conn *Conn, err error)

func (*Conn) Close

func (ws *Conn) Close() error

Close implements the io.Closer interface.

func (*Conn) LocalAddr

func (ws *Conn) LocalAddr() net.Addr

func (*Conn) NextFrameReader

func (ws *Conn) NextFrameReader(handle func(*Header, io.ReadCloser) error) error

func (*Conn) Read

func (ws *Conn) Read(msg []byte) (n int, err error)

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 (ws *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline

func (ws *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (ws *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (ws *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write

func (ws *Conn) Write(msg []byte) (n int, err error)

Write implements the io.Writer interface: it writes data as a frame to the WebSocket connection.

func (*Conn) WriteClose

func (ws *Conn) WriteClose(status int) (err error)

func (*Conn) WriteMsg

func (ws *Conn) WriteMsg(msg []byte, payloadType opcode) (int, error)

func (*Conn) WritePong

func (ws *Conn) WritePong(msg []byte) (n int, err 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 Request

type Request struct {
	Request         *http.Request
	Header          http.Header
	SecWebSocketKey string
	Protocol        []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)