websocket

Documentation

Overview

Package websocket implements a basic websocket server.

Index

• type Frame
• type Handler
• type Limits
• type Message
• type Opcode
• type StatusCode
• type WebSocket
  • func New(w http.ResponseWriter, r *http.Request, limits Limits) *WebSocket
  • func (s *WebSocket) Handshake() error
  • func (s *WebSocket) Serve(handler Handler)

Types

type Frame

type Frame struct {
	Fin     bool
	RSV1    bool
	RSV3    bool
	RSV2    bool
	Opcode  Opcode
	Payload []byte
}

Frame is a websocket protocol frame.

type Handler

type Handler func(ctx context.Context, msg *Message) (*Message, error)

Handler handles a single websocket message. If the returned message is non-nil, it will be sent to the client. If an error is returned, the connection will be closed.

var EchoHandler Handler = func(ctx context.Context, msg *Message) (*Message, error) {
	return msg, nil
}

EchoHandler is a Handler that echoes each incoming message back to the client.

type Limits

type Limits struct {
	MaxDuration     time.Duration
	MaxFragmentSize int
	MaxMessageSize  int
}

Limits define the limits imposed on a websocket connection.

type Message

type Message struct {
	Binary  bool
	Payload []byte
}

Message is an application-level message from the client, which may be constructed from one or more individual protocol frames.

type Opcode

type Opcode uint8

Opcode is a websocket OPCODE.

const (
	OpcodeContinuation Opcode = 0x0
	OpcodeText         Opcode = 0x1
	OpcodeBinary       Opcode = 0x2
	OpcodeClose        Opcode = 0x8
	OpcodePing         Opcode = 0x9
	OpcodePong         Opcode = 0xA
)

See the RFC for the set of defined opcodes: https://datatracker.ietf.org/doc/html/rfc6455#section-5.2

type StatusCode

type StatusCode uint16

StatusCode is a websocket status code.

const (
	StatusNormalClosure      StatusCode = 1000
	StatusGoingAway          StatusCode = 1001
	StatusProtocolError      StatusCode = 1002
	StatusUnsupported        StatusCode = 1003
	StatusNoStatusRcvd       StatusCode = 1005
	StatusAbnormalClose      StatusCode = 1006
	StatusUnsupportedPayload StatusCode = 1007
	StatusPolicyViolation    StatusCode = 1008
	StatusTooLarge           StatusCode = 1009
	StatusTlSHandshake       StatusCode = 1015
	StatusServerError        StatusCode = 1011
)

See the RFC for the set of defined status codes: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1

type WebSocket

type WebSocket struct {
	// contains filtered or unexported fields
}

WebSocket is a websocket connection.

func New

func New(w http.ResponseWriter, r *http.Request, limits Limits) *WebSocket

New creates a new websocket.

func (*WebSocket) Handshake

func (s *WebSocket) Handshake() error

Handshake validates the request and performs the WebSocket handshake. If Handshake returns nil, only websocket frames should be written to the response writer.

func (*WebSocket) Serve

func (s *WebSocket) Serve(handler Handler)

Serve handles a websocket connection after the handshake has been completed.