ws

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 2, 2020 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// All control frames MUST have a payload length of 125 bytes or less and MUST NOT be fragmented.
	MaxControlFramePayloadSize = 125
)

Constants defined by specification.

View Source
const (
	MaxHeaderSize = 14
)

Header size length bounds in bytes.

Variables

View Source
var (
	ErrProtocolStatusCodeNotInUse         = ProtocolError("status code is not in use")
	ErrProtocolStatusCodeApplicationLevel = ProtocolError("status code is only application level")
	ErrProtocolStatusCodeNoMeaning        = ProtocolError("status code has no meaning yet")
	ErrProtocolStatusCodeUnknown          = ProtocolError("status code is not defined in spec")
	ErrProtocolInvalidUTF8                = ProtocolError("invalid utf8 sequence in close reason")
)

Errors used by the protocol checkers.

View Source
var (
	ErrHandshakeBadProtocol = RejectConnectionError(
		RejectionStatus(http.StatusHTTPVersionNotSupported),
		RejectionReason("handshake error: bad HTTP protocol version"),
	)
	ErrHandshakeBadMethod = RejectConnectionError(
		RejectionStatus(http.StatusMethodNotAllowed),
		RejectionReason("handshake error: bad HTTP request method"),
	)
	ErrHandshakeBadHost = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerHost)),
	)
	ErrHandshakeBadUpgrade = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerUpgrade)),
	)
	ErrHandshakeBadConnection = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerConnection)),
	)
	ErrHandshakeBadSecAccept = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerSecAccept)),
	)
	ErrHandshakeBadSecKey = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerSecKey)),
	)
	ErrHandshakeBadSecVersion = RejectConnectionError(
		RejectionStatus(http.StatusBadRequest),
		RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerSecVersion)),
	)
)

Errors used by both client and server when preparing WebSocket handshake.

View Source
var (
	StatusRangeNotInUse    = StatusCodeRange{0, 999}
	StatusRangeProtocol    = StatusCodeRange{1000, 2999}
	StatusRangeApplication = StatusCodeRange{3000, 3999}
	StatusRangePrivate     = StatusCodeRange{4000, 4999}
)

Status code ranges defined by specification. See https://tools.ietf.org/html/rfc6455#section-7.4.2

View Source
var ErrHandshakeUpgradeRequired = RejectConnectionError(
	RejectionStatus(http.StatusUpgradeRequired),
	RejectionHeader(HandshakeHeaderString(headerSecVersion+": 13\r\n")),
	RejectionReason(fmt.Sprintf("handshake error: bad %q header", headerSecVersion)),
)

ErrHandshakeUpgradeRequired is returned by Upgrader to indicate that connection is rejected because given WebSocket version is malformed.

According to RFC6455: If this version does not match a version understood by the server, the server MUST abort the WebSocket handshake described in this section and instead send an appropriate HTTP error code (such as 426 Upgrade Required) and a |Sec-WebSocket-Version| header field indicating the version(s) the server is capable of understanding.

View Source
var ErrMalformedRequest = RejectConnectionError(
	RejectionStatus(http.StatusBadRequest),
	RejectionReason("malformed HTTP request"),
)

ErrMalformedRequest is returned when HTTP request can not be parsed.

Functions

func Cipher

func Cipher(payload []byte, mask [4]byte, offset int)

Cipher applies XOR cipher to the payload using mask. Offset is used to cipher chunked data (e.g. in io.Reader implementations).

To convert masked data into unmasked data, or vice versa, the following algorithm is applied. The same algorithm applies regardless of the direction of the translation, e.g., the same steps are applied to mask the data as to unmask the data.

func RejectConnectionError

func RejectConnectionError(options ...RejectOption) error

RejectConnectionError constructs an error that could be used to control the way handshake is rejected by Upgrader.

Types

type Frame

type Frame struct {
	Header  Header
	Payload []byte
}

Frame represents websocket frame. See https://tools.ietf.org/html/rfc6455#section-5.2

func NewFrame

func NewFrame(op OpCode, fin bool, p []byte) *Frame

NewFrame creates frame with given operation code, flag of completeness and payload bytes.

type Handshake

type Handshake struct {
	// Protocol is the subprotocol selected during handshake.
	Protocol string

	// Extensions is the list of negotiated extensions.
	Extensions []httphead.Option
}

Handshake represents handshake result.

type HandshakeHeader

type HandshakeHeader interface {
	io.WriterTo
}

HandshakeHeader is the interface that writes both upgrade request or response headers into a given io.Writer.

type HandshakeHeaderBytes

type HandshakeHeaderBytes []byte

HandshakeHeaderBytes is an adapter to allow the use of headers represented by ordinary slice of bytes as HandshakeHeader.

func (HandshakeHeaderBytes) WriteTo

func (b HandshakeHeaderBytes) WriteTo(w io.Writer) (int64, error)

WriteTo implements HandshakeHeader (and io.WriterTo) interface.

type HandshakeHeaderFunc

type HandshakeHeaderFunc func(io.Writer) (int64, error)

HandshakeHeaderFunc is an adapter to allow the use of headers represented by ordinary function as HandshakeHeader.

func (HandshakeHeaderFunc) WriteTo

func (f HandshakeHeaderFunc) WriteTo(w io.Writer) (int64, error)

WriteTo implements HandshakeHeader (and io.WriterTo) interface.

type HandshakeHeaderHTTP

type HandshakeHeaderHTTP http.Header

HandshakeHeaderHTTP is an adapter to allow the use of http.Header as HandshakeHeader.

func (HandshakeHeaderHTTP) WriteTo

func (h HandshakeHeaderHTTP) WriteTo(w io.Writer) (int64, error)

WriteTo implements HandshakeHeader (and io.WriterTo) interface.

type HandshakeHeaderString

type HandshakeHeaderString string

HandshakeHeaderString is an adapter to allow the use of headers represented by ordinary string as HandshakeHeader.

func (HandshakeHeaderString) WriteTo

func (s HandshakeHeaderString) WriteTo(w io.Writer) (int64, error)

WriteTo implements HandshakeHeader (and io.WriterTo) interface.

type Header struct {
	Fin    bool
	Rsv    byte
	OpCode OpCode
	Masked bool
	Mask   [4]byte
	Length int64
}

Header represents websocket frame header. See https://tools.ietf.org/html/rfc6455#section-5.2

func (Header) Rsv1

func (h Header) Rsv1() bool

Rsv1 reports whether the header has first rsv bit set.

func (Header) Rsv2

func (h Header) Rsv2() bool

Rsv2 reports whether the header has second rsv bit set.

func (Header) Rsv3

func (h Header) Rsv3() bool

Rsv3 reports whether the header has third rsv bit set.

type MessageType

type MessageType int

MessageType represents the type of a WebSocket message. See https://tools.ietf.org/html/rfc6455#section-5.6

const (
	// MessageText Text
	MessageText MessageType = iota + 1
	// MessageBinary Binary
	MessageBinary
)

type OpCode

type OpCode byte

OpCode represents operation code.

const (
	OpContinuation OpCode = 0x0
	OpText         OpCode = 0x1
	OpBinary       OpCode = 0x2
	OpClose        OpCode = 0x8
	OpPing         OpCode = 0x9
	OpPong         OpCode = 0xa
)

Operation codes defined by specification. See https://tools.ietf.org/html/rfc6455#section-5.2

func (OpCode) IsControl

func (c OpCode) IsControl() bool

IsControl checks whether the c is control operation code. See https://tools.ietf.org/html/rfc6455#section-5.5

func (OpCode) IsData

func (c OpCode) IsData() bool

IsData checks whether the c is data operation code. See https://tools.ietf.org/html/rfc6455#section-5.6

func (OpCode) IsReserved

func (c OpCode) IsReserved() bool

IsReserved checks whether the c is reserved operation code. See https://tools.ietf.org/html/rfc6455#section-5.2

type ProtocolError

type ProtocolError string

ProtocolError describes error during checking/parsing websocket frames or headers.

func (ProtocolError) Error

func (p ProtocolError) Error() string

Error implements error interface.

type RejectOption

type RejectOption func(*rejectConnectionError)

RejectOption represents an option used to control the way connection is rejected.

func RejectionHeader

func RejectionHeader(h HandshakeHeader) RejectOption

RejectionHeader returns an option that makes connection to be rejected with given HTTP headers.

func RejectionReason

func RejectionReason(reason string) RejectOption

RejectionReason returns an option that makes connection to be rejected with given reason.

func RejectionStatus

func RejectionStatus(code int) RejectOption

RejectionStatus returns an option that makes connection to be rejected with given HTTP status code.

type StatusCode

type StatusCode uint16

StatusCode represents the encoded reason for closure of websocket connection.

There are few helper methods on StatusCode that helps to define a range in which given code is lay in. accordingly to ranges defined in specification.

See https://tools.ietf.org/html/rfc6455#section-7.4

const (
	StatusNormalClosure           StatusCode = 1000
	StatusGoingAway               StatusCode = 1001
	StatusProtocolError           StatusCode = 1002
	StatusUnsupportedData         StatusCode = 1003
	StatusNoMeaningYet            StatusCode = 1004
	StatusInvalidFramePayloadData StatusCode = 1007
	StatusPolicyViolation         StatusCode = 1008
	StatusMessageTooBig           StatusCode = 1009
	StatusMandatoryExt            StatusCode = 1010
	StatusInternalServerError     StatusCode = 1011
	StatusTLSHandshake            StatusCode = 1015

	// StatusAbnormalClosure is a special code designated for use in
	// applications.
	StatusAbnormalClosure StatusCode = 1006

	// StatusNoStatusRcvd is a special code designated for use in applications.
	StatusNoStatusRcvd StatusCode = 1005
)

Status codes defined by specification. See https://tools.ietf.org/html/rfc6455#section-7.4.1

func (StatusCode) Empty

func (s StatusCode) Empty() bool

Empty reports whether the code is empty. Empty code has no any meaning neither app level codes nor other. This method is useful just to check that code is golang default value 0.

func (StatusCode) In

In reports whether the code is defined in given range.

func (StatusCode) IsApplicationSpec

func (s StatusCode) IsApplicationSpec() bool

IsApplicationSpec reports whether the code should be defined by application, framework or libraries specification.

func (StatusCode) IsNotUsed

func (s StatusCode) IsNotUsed() bool

IsNotUsed reports whether the code is predefined in not used range.

func (StatusCode) IsPrivateSpec

func (s StatusCode) IsPrivateSpec() bool

IsPrivateSpec reports whether the code should be defined privately.

func (StatusCode) IsProtocolDefined

func (s StatusCode) IsProtocolDefined() bool

IsProtocolDefined reports whether the code is already defined by protocol specification.

func (StatusCode) IsProtocolReserved

func (s StatusCode) IsProtocolReserved() bool

IsProtocolReserved reports whether the code is defined by protocol specification to be reserved only for application usage purpose.

func (StatusCode) IsProtocolSpec

func (s StatusCode) IsProtocolSpec() bool

IsProtocolSpec reports whether the code should be defined by protocol specification.

type StatusCodeRange

type StatusCodeRange struct {
	Min, Max StatusCode
}

StatusCodeRange describes range of StatusCode values.

type Upgrader

type Upgrader struct {
	// Protocol is a select function that is used to select subprotocol
	// from list requested by client. If this field is set, then the first matched
	// protocol is sent to a client as negotiated.
	//
	// The argument is only valid until the callback returns.
	Protocol func([]byte) bool

	// ProtocolCustrom allow user to parse Sec-WebSocket-Protocol header manually.
	// Note that returned bytes must be valid until Upgrade returns.
	// If ProtocolCustom is set, it used instead of Protocol function.
	ProtocolCustom func([]byte) (string, bool)

	// Extension is a select function that is used to select extensions
	// from list requested by client. If this field is set, then the all matched
	// extensions are sent to a client as negotiated.
	//
	// The argument is only valid until the callback returns.
	//
	// According to the RFC6455 order of extensions passed by a client is
	// significant. That is, returning true from this function means that no
	// other extension with the same name should be checked because server
	// accepted the most preferable extension right now:
	// "Note that the order of extensions is significant.  Any interactions between
	// multiple extensions MAY be defined in the documents defining the extensions.
	// In the absence of such definitions, the interpretation is that the header
	// fields listed by the client in its request represent a preference of the
	// header fields it wishes to use, with the first options listed being most
	// preferable."
	Extension func(httphead.Option) bool

	// ExtensionCustorm allow user to parse Sec-WebSocket-Extensions header manually.
	// Note that returned options should be valid until Upgrade returns.
	// If ExtensionCustom is set, it used instead of Extension function.
	ExtensionCustom func([]byte, []httphead.Option) ([]httphead.Option, bool)

	// Header is an optional HandshakeHeader instance that could be used to
	// write additional headers to the handshake response.
	//
	// It used instead of any key-value mappings to avoid allocations in user
	// land.
	//
	// Note that if present, it will be written in any result of handshake.
	Header HandshakeHeader

	// OnRequest is a callback that will be called after request line
	// successful parsing.
	//
	// The arguments are only valid until the callback returns.
	//
	// If returned error is non-nil then connection is rejected and response is
	// sent with appropriate HTTP error code and body set to error message.
	//
	// RejectConnectionError could be used to get more control on response.
	OnRequest func(uri []byte) error

	// OnHost is a callback that will be called after "Host" header successful
	// parsing.
	//
	// It is separated from OnHeader callback because the Host header must be
	// present in each request since HTTP/1.1. Thus Host header is non-optional
	// and required for every WebSocket handshake.
	//
	// The arguments are only valid until the callback returns.
	//
	// If returned error is non-nil then connection is rejected and response is
	// sent with appropriate HTTP error code and body set to error message.
	//
	// RejectConnectionError could be used to get more control on response.
	OnHost func(host []byte) error

	// OnHeader is a callback that will be called after successful parsing of
	// header, that is not used during WebSocket handshake procedure. That is,
	// it will be called with non-websocket headers, which could be relevant
	// for application-level logic.
	//
	// The arguments are only valid until the callback returns.
	//
	// If returned error is non-nil then connection is rejected and response is
	// sent with appropriate HTTP error code and body set to error message.
	//
	// RejectConnectionError could be used to get more control on response.
	OnHeader func(key, value []byte) error

	// OnBeforeUpgrade is a callback that will be called before sending
	// successful upgrade response.
	//
	// Setting OnBeforeUpgrade allows user to make final application-level
	// checks and decide whether this connection is allowed to successfully
	// upgrade to WebSocket.
	//
	// It must return non-nil either HandshakeHeader or error and never both.
	//
	// If returned error is non-nil then connection is rejected and response is
	// sent with appropriate HTTP error code and body set to error message.
	//
	// RejectConnectionError could be used to get more control on response.
	OnBeforeUpgrade func() (header HandshakeHeader, err error)
}

Upgrader contains options for upgrading connection to websocket.

func (*Upgrader) Upgrade

func (u *Upgrader) Upgrade(in *ringbuffer.RingBuffer) (out []byte, hs Handshake, err error)

Upgrade zero-copy upgrades connection to WebSocket. It interprets given conn as connection with incoming HTTP Upgrade request.

It is a caller responsibility to manage i/o timeouts on conn.

Non-nil error means that request for the WebSocket upgrade is invalid or malformed and usually connection should be closed. Even when error is non-nil Upgrade will write appropriate response into connection in compliance with RFC.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL